# Visual Style Guide

Status: T02 baseline complete  
Scope: Global design tokens + component baseline only (no full page redesign)

## 1) Design intent
A warm, appetizing visual language for a modern recipe app:
- **Warm brand hue:** orange/amber (food-forward, inviting)
- **Clean surfaces:** soft cream background + white cards
- **Readable typography:** high contrast body text, expressive heading serif
- **Low-friction interactions:** consistent focus ring, elevation, and control sizing

## 2) Token sources
- **TS token source:** `frontend/src/theme.ts`
- **Global CSS token source:** `frontend/src/styles/tokens.css`
- **Baseline component classes:** `frontend/src/index.css` (`@layer components`)

## 3) Core tokens

### Color palette
- Brand scale: `brand50` → `brand800`
- Semantic:
  - `primary` / `primaryDark` / `primaryLight`
  - `accent`
  - `success`, `warning`, `error` (+ light variants)
- Surfaces/text:
  - `bg`, `bgAlt`, `surface`, `surfaceMuted`, `border`
  - `text`, `textHeading`, `textDim`

### Typography scale
- Families:
  - Sans: `Inter, Manrope, system-ui...`
  - Heading: `Fraunces, Inter, Georgia, serif`
  - Mono: `ui-monospace...`
- Sizes: `xs`, `sm`, `base`, `lg`, `xl`, `2xl`, `3xl`, `4xl`
- Line heights: `tight`, `normal`, `relaxed`

### Layout primitives
- Spacing: `xxs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`
- Radius: `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `full`
- Elevation:
  - `subtle`
  - `card`
  - `hover`
- Focus:
  - `focus` token in TS
  - `--focus-ring` token in CSS

## 4) Component baseline classes
Defined in `frontend/src/index.css`:

- **Page container:** `.ui-page`
- **Section container:** `.ui-section`
- **Card container:** `.ui-card`
- **Buttons:**
  - base `.ui-btn`
  - variants `.ui-btn-primary`, `.ui-btn-secondary`
- **Inputs:** `.ui-input`, `.ui-textarea`, `.ui-select`
- **Chips/Badges:** `.ui-chip`, `.ui-badge`

All of these share tokenized radius, border, spacing, shadows, and focus behavior.

## 5) Adoption in current baseline
Initial integration applied to reduce disruption:
- `RecipeListPage` page/section/button/input/chip/badge usage
- `RecipeForm` input/textarea/button usage
- `TagSelector` chip/input/button usage
- `RecipeCard` card/chip usage

## 6) Usage pattern
Prefer semantic baseline classes + utility classes for layout only.

Example:
```tsx
<button className="ui-btn ui-btn-primary px-5">Save Recipe</button>
<input className="ui-input" />
<span className="ui-chip">Vegetarian</span>
```

## 7) Notes for next tasks (T04+)
- Reuse these primitives before introducing one-off visual patterns.
- Keep all new colors mapped to semantic tokens.
- Preserve AA contrast and focus visibility for every interactive control.

## 8) Imagery and icon direction update (Photo-First)
- Food storytelling should use real photography as the default medium.
- Legacy custom illustrations are fallback/decorative only.
- Prefer photographic aspect ratios:
  - list cards: 4:3
  - detail hero: 16:9 (or 3:2)
  - square thumbnails: 1:1
- Keep icons modern and restrained; standardize on `lucide-react` for action/navigation icons.
- Avoid emoji icons in production UI where a system icon exists.

See also: `docs/visual-audit/photo-first-assets.md` and `frontend/public/assets/photos/manifest.json`.