# SukoWise Design System

SukoWise is a **B2C agentic nutrition platform**. A user hands over their real health picture — conditions, medication, bloods, budget, schedule, tastes — and an AI nutritionist ("Suko") writes a bespoke diet plan around it, then keeps rewriting it as the week actually unfolds. The product is conversation-first and data-backed: a chat agent with a plan, a calorie/macro model and a memory of what you logged, not a static PDF meal plan.

This repo is the design system: brand foundations, token CSS, a React component library, and click-through UI kits for the two surfaces (mobile app, marketing site).

## Sources used

| Source | What was in it |
|---|---|
| `https://github.com/Isra-Tabassum/SukoWise` (branch `main`) | **README only.** The v2 rebuild repo: new Supabase project, agent flow moving Flowise → n8n, "designs coming from Figma". No UI code, styles, component library or assets existed at import time. |
| `uploads/logo.svg` (supplied by the user) | The SukoWise wordmark — brush stroke with knocked-out letters. Cleaned copy at `assets/logo-wordmark.svg`. |
| Figma: `figma.com/design/EnXDRkv8yFpB9JH1D9T8Rb/SukoWise-Design-System` | **Not yet read** — no Figma connection is available in this project, so nothing from this file has informed the system. |
| Brand brief (chat) | Name, primary palette `#FF8969 / #053B06 / #0DAB8E`, feedback colour `#FFD269`, product description, and the direction: *fluid, organic, gradient-forward*. |

Explore that repository further as it fills out — once the Figma-derived v2 code lands there, the UI kits here should be rebuilt from real source rather than interpretation. `github.md` records the sync state.

### What was NOT supplied (and therefore substituted)

- **Logo** — supplied (`assets/logo-wordmark.svg`). An apricot brush stroke with knocked-out letterforms, so the ground behind becomes the letter colour: use it on sand/white or forest, **never on apricot**. Favicon, stacked lockup and a mono variant are still outstanding.
- **Fonts** — no font files. Substituted from Google Fonts: **Gabarito** (display) + **Hanken Grotesk** (body) + **DM Mono** (figures). **Please confirm or send the real brand fonts.**
- **Icons** — no icon set. Substituted **Lucide** (2px stroke, round caps) via `unpkg.com/lucide-static`, masked to `currentColor`.
- **Photography / illustration** — none. Marketing layouts use labelled dashed placeholders.
- **Success / info / error colours** — derived here (see below); only `#FFD269` (warning) was given.

---

## Content fundamentals

The voice is a **good clinician who happens to be warm**: specific, calm, never preachy, never cheerleading. It talks about *your week*, not *your journey*.

- **Person.** "You" for the user; "I" for Suko when the agent is speaking in chat or a nudge ("I moved dinner to 20:30"); "we" only for the company on marketing pages ("We're not a substitute for medical advice"). Never "we" for the agent — it's one assistant, not a team.
- **Casing.** Sentence case everywhere — headlines, buttons, labels, dialog titles. The only uppercase is the 11px eyebrow/label style (`letter-spacing: .1em`).
- **Punctuation.** Em-dashes and full stops in body copy; no exclamation marks; no ellipsis except in a placeholder ("Ask Suko anything…") or a live "Thinking…" state.
- **Numbers.** Always concrete and unit-suffixed: `610 kcal`, `P 44g · C 52g · F 22g`, `72.4 kg`, `15 minutes`. Mid-dot separates macro runs. Never "approx" hedging — if it's an estimate, say what it's based on.
- **Length.** Headline ≤ 8 words. Agent messages 1–2 sentences, then offer an action. Body paragraphs ≤ 3 lines.
- **Agent copy always says *why*.** "Your last iron panel came back low and you've skipped red meat all month" — the reason precedes the suggestion. Never a bare instruction.
- **No shame, no streak-guilt.** Missed days are described neutrally: "Log yesterday so the plan stays accurate", never "You broke your streak".
- **No emoji.** Not in UI, not in copy, not in notifications. Status is carried by colour, badges and Lucide glyphs.
- **Buttons are verbs the user would say:** "Build my plan", "Swap it", "Tell me more", "Not now". Never "Submit", "OK", "Learn more".

Examples, verbatim from the kits:

> **Eat for the body you have today** — hero headline
> "Suko reads your health profile — conditions, bloods, tastes, schedule — then writes a week of meals around it. And rewrites it the moment your week changes."
> "You're low on iron this week. I've put lentils in Thursday's dinner. Want me to explain why?"
> "Most plans ignore the thing you're managing."
> "Made for people, not macros."

---

## Visual foundations

**The idea:** a warm bowl of food and a clinical chart, reconciled. The wordmark sets the register — a hand-drawn brush stroke, casual and unclinical — so the system stays soft-edged and slightly imperfect everywhere: blob masks, drifting mesh, no hard rules. Everything is soft-edged, warm-neutral and gradient-lit; every number is precise and mono-set. Nothing is square, nothing is pure grey, nothing is pure black.

### Colour

| Role | Token | Value |
|---|---|---|
| Apricot (warmth, appetite, primary CTA) | `--apricot-400` | `#FF8969` |
| Forest (ink, inverse surfaces, trust) | `--forest-800` | `#053B06` |
| Jade (the agent, progress, focus) | `--jade-500` | `#0DAB8E` |
| Warning (given) | `--color-warning` | `#FFD269` |
| Success (derived) | `--color-success` | `#2FA35A` |
| Info (derived) | `--color-info` | `#2E8FA8` |
| Error (derived) | `--color-error` | `#E0512F` |

Derivation logic for the three new feedback colours: each was pulled toward the brand's warmth and desaturated slightly so it sits beside `#FFD269` without shouting — success is a leafy green kept clearly distinct from jade (jade means *the agent did something*, success means *you did something*), info is a muted lagoon rather than a corporate blue, error is a warm ember that reads as a sibling of apricot rather than an alarm red. Each ships with an `-ink` variant for text (4.5:1+ on its `-surface` tint) since the mid tones are too light for body copy.

Neutrals are **warm sand**, never grey — `--sand-50 #FCFAF6` is the canvas, `--sand-800` is body ink. Semantic aliases (`--surface-card`, `--text-muted`, `--border-subtle`, `--focus-ring`) are what product code should reference; the numbered ramps are the raw material.

Macro data has a fixed mapping (`--macro-protein/carb/fat/fibre`) so charts are comparable across screens.

### Gradients

Gradients are structural, not decorative garnish. Rules:

1. **Always warm → cool** (apricot → jade), 120–150°. Never cool → warm, never vertical, never a rainbow.
2. `--gradient-bloom` is the signature (apricot → apricot-light → jade). It appears at most once per screen at large scale, plus small-scale in exactly three places: the Switch on-track, the underline tab indicator, the ProgressRing arc.
3. `--gradient-sunrise` (honey → apricot) is the primary button fill. `--gradient-verdant` (jade → forest) is the inverse-panel fill.
4. `--gradient-mesh` is two-to-three blurred radial blobs (`blur(56–72px)`) behind heroes and agent surfaces, drifting slowly (`suko-drift`, 9–14s, alternate). It never sits behind body text without a glass card between.
5. `--gradient-scrim` (transparent → forest 82%) is the protection gradient over imagery. Text on photography always sits on a scrim, not on raw image.
6. `--gradient-hairline` is a 2px top-edge accent on cards — the system's one "line" flourish.

### Type

Display **Gabarito** 700–800, tracking `-.028em` at display sizes, line-height 1.04. Body **Hanken Grotesk** 400–600 at 1.5. Figures **DM Mono** — every number a user compares (kcal, grams, weight, times, durations) is mono; sentences never are. Micro-labels: 11px / 700 / `.1em` uppercase, jade-700 for contextual eyebrows, sand-500 for structural ones. Floor for readable text is 13px.

### Space, shape, elevation

4px base scale with a 6px half-step inside pills. App gutter 20px, web gutter 32px, card padding 24px, stacked rows 12px, section rhythm 32/48/80. Tap targets ≥ 48px.

Radii: `xs 8 · sm 12 · md 18 · lg 26 · xl 34 · 2xl 44 · pill`. The **pill is the default control shape** (buttons, inputs, tags, selects). Cards are 26px. Bottom sheets are 44px on the top corners only. The checkbox at 8px is the squarest thing in the system. **Organic blob radii** (`--radius-blob-1/2`, `--radius-leaf`) mask avatars, meal thumbnails, icon containers and the agent orb — a plain square image crop is off-brand.

Cards: white surface, `1px --border-subtle` hairline, `--shadow-sm`, 26px radius, optional gradient hairline. No card ever has a coloured left border. Shadows are **forest-tinted** (`rgba(5,59,6,…)`), soft and wide — `xs → xl` plus coloured `--shadow-brand` / `--shadow-accent` glows under gradient buttons. `--shadow-inset` is the only inner shadow (switch track, orb core).

Transparency + blur appear in exactly two patterns: **glass** (`--gradient-glass` + `blur(18px)`) for the sticky site header, mobile tab bar, chat composer and any card floating over mesh; and **overlay** (forest 44% + `blur(6px)`) behind modals. Blur is never used for aesthetics alone.

### Motion, hover, press

- Easing: `--ease-organic` (default, 240ms), `--ease-out-soft` (entrances, 420ms), `--ease-spring` (press/toggles, 160ms). Layout never bounces; only presses, toggles and the orb do.
- **Hover:** lift `-1px` (buttons) or `-2px` (cards) plus a deeper shadow; gradient fills brighten (`brightness(1.04) saturate(1.04)`) rather than darkening. Ghost/plain controls tint to `--sand-100`.
- **Press:** `scale(.97)` — no colour change.
- **Focus:** jade border + a 4px `rgba(13,171,142,.16)` glow on fields; 2px `--focus-ring` outline with 2px offset elsewhere. Never a hard black ring.
- Named keyframes: `suko-drift` (mesh), `suko-morph` (blob shapes), `suko-pulse` (thinking dots, orb core), `suko-sheen`. Progress arcs and bars animate their length over 420ms; they never spin.

### Imagery

Warm, natural daylight; real food and real kitchens; shallow depth of field; no grain, no filters, no cool blue-grey. Crops are blob-masked or 34px-rounded. Text over imagery requires `--gradient-scrim`.

### Iconography

**Lucide**, at its default 2px stroke with round caps and joins — the closest widely-available match to the brand's soft geometry (a substitution; flagged above). Consumed via `components/core/Icon.jsx`, which masks the glyph so it always inherits `currentColor`; sizes 12 / 14–15 (in badges/tags) / 16–20 (UI) / 22–24 (feature blobs). Icons are always paired with a label except inside `IconButton`, which requires `aria-label`. Feature icons sit inside a blob-radius container filled with `--gradient-sunrise`. **No emoji, ever.** No unicode symbols as icons — with two exceptions used as *text*: the mid-dot `·` as a metadata separator and the en/em dash. Brand illustration: none supplied; the `AgentOrb` gradient blob is the one brand-owned graphic element.

---

## Index

| Path | What it is |
|---|---|
| `styles.css` | The single entry point consumers link. `@import`s only. |
| `tokens/` | `colors · gradients · typography · spacing · radius · elevation · motion · fonts · base` |
| `guidelines/` | 20 foundation specimen cards (Colors, Type, Spacing, Brand groups) |
| `components/` | React primitives, grouped by concern (below) |
| `ui_kits/app/` | Mobile app click-through — onboarding, Today, Plan, Suko chat, profile |
| `ui_kits/marketing/` | Landing page — hero, how it works, conditions, pricing, footer |
| `assets/` | Asset provenance + substitution notes (no binaries supplied) |
| `thumbnail.html` | Homepage tile |
| `SKILL.md` | Agent Skills entry point |
| `github.md` | Upstream repo association + sync state |

### Components

**`components/core/`** — `Button`, `IconButton`, `Icon`, `Card`, `Badge`, `Tag`
**`components/forms/`** — `Input`, `Select`, `Checkbox`, `Radio`, `Switch`, `StepperField`
**`components/feedback/`** — `Toast`, `Tooltip`, `Dialog`
**`components/navigation/`** — `Tabs`, `TabBar`
**`components/nutrition/`** — `ProgressRing`, `MacroBar`, `MealCard`, `AgentOrb`, `ChatBubble`

Each has a sibling `.d.ts` (props contract) and `.prompt.md` (what/when + usage), and each directory has one `@dsCard` HTML showing its states.

#### Intentional additions

No component inventory existed upstream, so the standard primitive set was authored. These go beyond it, each because a core product surface requires it:

- `StepperField` — thumb-friendly numeric entry for profile/plan setup.
- `TabBar` — the app's bottom navigation.
- `ProgressRing`, `MacroBar` — the product is calorie/macro-led; these are its canonical data forms.
- `MealCard` — one meal row shared by day, week and swap views.
- `AgentOrb` — a non-anthropomorphic presence for the agent (no face, never a perfect circle).
- `ChatBubble` — the product is conversation-first.
- `Icon` — wrapper over the substituted Lucide set so a future swap is one file.