recipe-manager/docs/visual-style-guide.md

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:

<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.