WinWin Shop — Design System

A reusable design system for WinWin Shop, an affiliate / UGC marketing platform that connects Israeli Shopify merchants ("businesses") with content creators. The platform is Hebrew-first (RTL), bilingual (he / en), and runs as both a web app at staging.winwinshop.online and a Capacitor-wrapped mobile app.

This document is the manifest. Everything else in this folder — tokens, UI kits, preview cards — is downstream of the decisions captured here.

---

Sources & Inputs

Source	What we used it for
Codebase — WinWin-Shop/ (local attach of the staging tree)	Ground-truth colors, fonts, layout, components, copy. The system was built by reading the actual PHP files, not guessing from screenshots.
CLAUDE.md (repo root)	Architecture, routes, role model (business / creator / admin), data model, flows.
winwin-design-handoff-spec.md (v2.0 "Serious Ecommerce Upgrade" doc)	Type scale, spacing grid, radii, shadow recipes, component anatomies, page-by-page specs.
GitHub — git@github.com:WinWin-App/WinWin-Shop.git (org WinWin-App)	Original repo. Browse it for the most up-to-date PHP / styles / icons. Explore it directly if you need fresher context than this folder.
Live staging — https://staging.winwinshop.online	Visual reference (auth-gated for dashboard).

Note on the v2.0 spec: the handoff doc proposes a green / gold palette. The product owner has asked to stay on the existing indigo + teal palette from the live staging site. We've adopted the v2.0 doc's structure (type scale, spacing, radii, shadows, component anatomy, layout rules) but kept the colors as they are live today.

---

File Index

.
├── README.md                  ← you are here
├── SKILL.md                   ← Agent-Skills entry point
├── colors_and_type.css        ← the single source of truth for tokens
├── assets/                    ← logos, OG cover, placeholder
├── fonts/                     ← Google Font links (Assistant / Heebo loaded via CDN)
├── preview/                   ← cards rendered in the Design System tab
│   ├── type-*.html
│   ├── color-*.html
│   ├── spacing-*.html
│   ├── component-*.html
│   └── brand-*.html
└── ui_kits/
    ├── public-site/           ← marketing homepage, login, register
    │   ├── README.md
    │   ├── index.html
    │   └── *.jsx
    ├── business/              ← business dashboard, sidebar, KPIs, graph, table
    │   ├── README.md
    │   ├── index.html
    │   └── *.jsx
    └── creator/               ← creator dashboard, my-links, earnings
        ├── README.md
        ├── index.html
        └── *.jsx

---

Product Context

WinWin Shop is a two-sided marketplace:

• Businesses sign in via Shopify OAuth, sync their product catalog, and either invite or approve creators to promote products. They pay commissions on tracked sales (via affiliate links + discount codes) and/or fixed prices for UGC deliverables.
• Creators sign up directly, fill out a profile + payout method, request collaborations with brands, generate affiliate links / discount codes, and withdraw earnings (PayPal / bank / Bit).
• Admins moderate users, review payouts, and run analytics.

The core domain object is active_collaborations — every relationship between a business and a creator (whether affiliate-style or UGC-style) lives there.

Stack: PHP 8.4 + MariaDB on a single EC2 box, vanilla JS frontend (no framework), Chart.js for graphs, Shopify GraphQL Admin API, PayPlus + PayPal Payouts, S3 for media uploads. PWA via manifest.json.

Two products inside one codebase:

1. Public marketing site — index.php, login.php, register.php, about.php, contact.php, terms.php, tutorial.php, plus the two role-specific landing pages landing-business.php / landing-creators.php. Audience: cold visitors. Tone: confident, modern, "production-grade."
2. Authenticated app — split into three role spaces:
   • business/ — dashboard, products (Shopify sync), creators (collab approval inbox), orders, payments, settings, UGC.
   • creator/ — dashboard, shop (browse products), my-links, ugc-deals, orders (commissions earned), profile, notifications.
   • admin/ — separate Vercel/Linear-inspired dark theme; out of scope for this design system (admin is intentionally minimalist and has no emojis/no color).

---

Content Fundamentals

Language

• Hebrew is primary (dir="rtl"). English is a secondary toggle. Every page sets <html dir="<?= $dir ?>"> from a session-stored lang ∈ {he, en}. Labels live in includes/lang.php.
• Personal address: 2nd person plural ("אתם" / "we serve you") in marketing, neutral imperative in the app ("הזן כתובת אימייל", "אשר שיתוף פעולה"). English copy uses "you" (2nd person singular).
• Hebrew sentences should not be flipped manually — let CSS logical properties (margin-inline-start, border-inline-start) handle direction. Don't write margin-right directly.

Tone

• Confident and matter-of-fact. Not "fun startup," not "enterprise stiff." Examples lifted from index.php:
  • Hero H1 (Hebrew): "המקום שבו מותגים ויוצרים עושים עסקים." → "Where brands and creators do business."
  • Hero sub: "פלטפורמת אפיליאט ו-UGC ישראלית. שיתופי פעולה אמיתיים, עם נתונים ועמלות בזמן אמת."
• Numbers are the proof. Trust strips show "500+ יוצרי תוכן", "₪2M+ עמלות ששולמו", "98% שביעות רצון". Never decorative — always cite a metric when you can.
• Hebrew is direct, English is concise. Avoid jingles, slogans, em-dashes in Hebrew copy. Avoid the word "פשוט" (just / simply) — it's overused everywhere else.
• Status copy is operational, not chatty. "ממתין לתשלום", "הוחזר", "פעיל" — no "Oops!" or "Yay!".

Casing & punctuation

• Hebrew: no title case (Hebrew doesn't have it). Sentence-style.
• English: Sentence case for headings, Title Case only for the brand mark "WinWin" itself.
• Hebrew uses Hebrew quote marks (״...״) only in legal copy; UI strings just use straight quotes.
• Numbers: (48230).toLocaleString('he-IL') → 48,230. Currency: ₪48,230 (prefix). Dates: DD/MM/YYYY.

Emoji & icons in copy

• Public marketing pages and dashboards: emoji are used sparingly as inline accents for sharing copy ("היי 😊") and in some legacy alert cards. New work should prefer SVG icons (the codebase has consistent feather-style 20×20 inline SVGs).
• Admin panel: zero emoji, per the operating rules in CLAUDE.md.
• The wordmark uses the gradient ramp brand → accent applied to "WinWin" as text fill (-webkit-background-clip: text).

Voice example — landing hero (he)

המקום שבו מותגים ויוצרים עושים עסקים. פלטפורמת אפיליאט ו-UGC ישראלית. שיתופי פעולה אמיתיים, עם נתונים ועמלות בזמן אמת. [התחילו עכשיו] [איך זה עובד?]

Voice example — dashboard greeting (he, from business/dashboard.php)

שלום, {שם העסק} סיכום הביצועים שלך

---

Visual Foundations

Color

The palette is indigo + teal on near-white, with slate-grey neutrals. Sourced verbatim from the live index.php / login.php.

Role	Token	Hex	Use
Brand	--ww-brand	#4F5DEC	Primary CTAs, links, focus rings, chart line 1, sidebar active state
Brand-dark	--ww-brand-dark	#3A48C5	Button hover, pressed states
Brand-deep	--ww-brand-deep	#2A3499	Dark hero panels, footer
Brand-tint	--ww-brand-tint	#EEF0FE	Tag bg, active nav highlight
Accent (teal)	--ww-accent	#0D9488	Secondary highlights, gradient pair, chart line 2
Ink	--ww-ink	#0F172A	Body text, headings
Ink-soft	--ww-ink-soft	#334155	Subheadings
Ink-muted	--ww-ink-muted	#64748B	Captions, placeholders
Line	--ww-line	#E2E8F0	All borders
Bg-alt	--ww-bg-alt	#F8FAFC	Page background, table stripes

Brand gradient (used sparingly): linear-gradient(120deg, #4F5DEC 0%, #0D9488 100%) — only on:

1. The "WinWin" wordmark text fill.
2. The hero highlight word (e.g. "מותגים ויוצרים").
3. The logo bag glyph itself.

Never use this gradient on buttons, cards, large fills, or as a page background. The look reads as cheap if applied broadly.

Semantic colors (--ww-success/warning/error/info) keep separate *-bg and *-border tints so status badges read clearly without leaning on color alone.

Typography

• Family: Assistant is the primary; Heebo is the documented fallback in the v2.0 spec and is loaded as the second family. Both cover Hebrew + Latin. Loaded via Google Fonts CDN — no .ttf files in this folder.
• Weights actually used: 400 body · 600 subheadings · 700 nav/buttons · 800 hero / KPI numbers.
• Scale: see colors_and_type.css. Range 11 → 60 px, on a (roughly) 1.2 / 1.25 ramp.
• Letter-spacing: -0.02em on hero / H1, +0.05em on nav labels, +0.14em on uppercase eyebrows.
• Line height: 1.15 on display, 1.6 on body, 1.75 on long-form legal copy.

⚠️ Font substitution flag: Assistant + Heebo are loaded from Google Fonts CDN, not bundled. If you ship this design system to an offline context, download the .woff2 files from Google Fonts and drop them in fonts/. We did not ship local copies because the live site doesn't.

Spacing & rhythm

4 px base grid. Tokens --ww-s-1 … --ww-s-24 (4 → 96 px). Section vertical padding on the public site is --ww-s-20 (80 px) desktop / --ww-s-12 mobile. Card padding is --ww-s-6 (24 px). KPI cards --ww-s-5 (20 px).

Border radius

4 / 8 / 12 / 16 / 20 / 24 / 9999 — the live site is consistent about 16px for cards / panels, 12px for buttons, 8px for inputs, and 9999px for pills.

Shadows

• Cards: --ww-shadow-md (0 4px 16px rgba(15,23,42,.06)) at rest, --ww-shadow-lg on hover.
• Primary CTA gets a brand-tinted shadow (--ww-shadow-brand, rgba(79,93,236,.28)) — the signature visual cue that this is the action.
• Focus ring is a 3 px translucent brand outline (--ww-shadow-focus), not a hard ring.
• Heavy / dramatic shadows (>20 px blur) are avoided everywhere except the optional hero panel.

Backgrounds

• Default: flat near-white (--ww-bg-alt #F8FAFC). Cards sit on it in pure white.
• Hero / auth pages: very subtle dual-radial wash — a brand-tinted ellipse from the top and an accent-tinted ellipse from the bottom-corner, both at ≤8% alpha. See body::before in login.php.
• Dashboard: soft diagonal gradient linear-gradient(135deg, #f5f7fa, #e8eef5) behind the sidebar + main column.
• No full-bleed photography, no illustrations, no repeating patterns, no grain. The brand is restrained — the imagery is the user's products (Shopify product thumbnails), not WinWin's own art.

Animation & motion

• Transitions are short and unflashy: 150–250 ms ease. No bounces, no spring physics.
• Cards lift translateY(-2px) + heavier shadow on hover.
• Primary buttons lift translateY(-2px) and grow their brand shadow.
• The hero badge dot has a slow pulse (2 s, opacity + scale). Logo on load fades + slides up fadeUp 0.7s ease forwards.
• Charts fade in over ~400 ms via Chart.js defaults. We don't add custom enter animations to data.

Hover, press, focus

• Hover (links / text): brand-dark color.
• Hover (buttons): background → brand-dark, translateY(-2px), stronger brand shadow.
• Hover (cards): shadow grows, slight lift.
• Press (buttons): translateY(0), shadow returns to rest.
• Focus-visible (everything): outline: none; box-shadow: 0 0 0 3px rgba(79,93,236,.18); — never use the native outline, but always provide a visible alternative.

Borders

• 1 px solid --ww-line everywhere by default.
• Form inputs use 1.5 px for crispness at small sizes.
• Active sidebar items use a 3 px border-inline-start accent in --ww-brand (logical property, RTL-aware).

Transparency & blur

• Used only on the floating language toggle and a couple of legacy "glass" KPI cards on the business dashboard: background: rgba(255,255,255,.6); backdrop-filter: saturate(180%) blur(8px);. Treat as an exception, not a pattern. New cards should be solid white.

Layout rules

• Public site: max content width 1200 px, centered. Section padding 80 px / 16 px desktop, 48 px / 24 px mobile.
• App: fixed sidebar (240 px desktop, 200 px on the legacy creator/business CSS) + fluid main column. Mobile collapses sidebar to a fixed bottom nav (60px tall, position: fixed).
• Top bar 68 px tall, white, --ww-shadow-xs on scroll.

Card anatomy

White surface, --ww-r-xl (16 px) radius, 1 px --ww-line border, --ww-s-6 padding, --ww-shadow-md at rest. Interactive cards lift on hover. KPI cards typically drop the border and lean on the shadow + a colored icon square in the corner. Premium / highlighted KPI cards use the dark brand-deep panel with white text.

Imagery

The product itself ships almost no first-party imagery beyond the logo. Photography would be:

• Warm-cool neutral, not heavily filtered.
• Shopify product photography is the actual content — show it on white with 4:3 or 1:1 framing inside cards.
• The OG cover (assets/og-cover.png) is the one stylized brand image; it uses the brand gradient.

---

Iconography

WinWin uses inline feather-style SVGs (1.8–2 px stroke, 24×24 viewBox, rounded caps/joins, stroke: currentColor). They are hand-rolled into PHP templates rather than loaded from an icon font — there is no codebase-bundled icon library and no Font Awesome / Material Icons dependency.

Recommendation for new work: use Lucide as the CDN icon set. Lucide is the open-source continuation of Feather and matches the existing inline SVGs almost exactly (same 24×24 grid, 2 px stroke, rounded ends). Load via:

<script src="https://unpkg.com/lucide@latest"></script>
<script>lucide.createIcons();</script>

Then write <i data-lucide="shopping-bag"></i>. This is the flagged substitution — the codebase doesn't pull from a CDN, but every SVG in the codebase is one-for-one with a Lucide icon.

Common icons in use (Hebrew label → Lucide name):

In app	Lucide
דשבורד	layout-dashboard
מוצרים	package
יוצרים / משתמשים	users
הזמנות	shopping-bag
תשלומים	credit-card
הגדרות	settings
דוחות / אנליטיקה	bar-chart-3
שיתופי פעולה	handshake
הלינקים שלי	link-2
התראות	bell
Shopify Sync	refresh-cw
התנתק	log-out
חיפוש	search
לסגור	x

Stroke / fill rules:

• Stroke = currentColor, so the icon inherits text color.
• Stroke width 1.8–2 px. Never below 1.6.
• 24×24 viewBox at 20×20 rendered size in nav, 18×18 in inline text.
• Solid / filled icons are reserved for brand glyphs (the logo shopping bag) and emoji-replacement in toasts. Never mix outline and filled icons in the same UI.

Emoji: used sparingly in marketing copy and toast feedback, never in the admin panel. Avoid emoji in serious dashboard surfaces.

Logos (in assets/):

File	When to use
logo-mark.png	Square mark only. Use at 32–64 px. The blue "W" inside a shopping bag.
logo-lyrics.png	Mark + wordmark, the canonical full lockup.
logo-app.png	PWA / app icon.
logo-favicon.png	Favicon, apple-touch-icon, OG fallback.
og-cover.png	Open Graph / Twitter card image.

---

How to use this system

1. Drop colors_and_type.css into your page (or copy the :root block).
2. Load the fonts: <link href="https://fonts.googleapis.com/css2?family=Assistant:wght@300;400;500;600;700;800&display=swap" rel="stylesheet">.
3. Pull icons from Lucide.
4. Wrap RTL content in <html dir="rtl"> and use logical properties for spacing (margin-inline-*, padding-inline-*, border-inline-start).
5. Cross-reference component anatomy in preview/ and full screens in ui_kits/.

For deeper context — flows, the data model, role gates — read WinWin-Shop/CLAUDE.md directly. It's the most authoritative architecture document.

---

Caveats

• Live admin panel UI is intentionally a different design system (Vercel/Linear dark theme) per CLAUDE.md §1. Not included here — design admin work against that file directly.
• PayPlus / PayPal screens are mostly redirects and not part of WinWin's visual surface.
• Mobile app is a Capacitor wrapper around the same web URLs — no separate native styling needed.
• Fonts are CDN, not bundled (see Typography note above). "# design"