# Frontend Design Cookbook

This cookbook defines the visual system for the frontend so every new change extends the existing style instead of inventing a new one.

## Agent workflow

- For any frontend edit, consult this cookbook before implementing changes.
- If a change introduces or alters reusable UI patterns, wrappers, component variants, tokens, motion rules, or shared classes, update this cookbook in the same change.
- Keep updates concise and actionable so future edits remain consistent.

## Design intent

- Core tone: light editorial, calm and information-first.
- Product feel: premium personal logbook, not generic SaaS dashboard.
- Contrast model: neutral paper and ink do most of the work; accents are restrained.

## Non-negotiables

- Keep layouts readable first. Aesthetic details support hierarchy, not the other way around.
- Use one visual language across the app shell, cards, forms, tables, and actions.
- Prefer subtle depth (borders, layered paper, soft shadows) over loud gradients.
- Keep motion purposeful and short; always preserve `prefers-reduced-motion` behavior.

## Typography

- Display/headings: `Cormorant Infant`.
- Body/UI text: `Manrope`.
- Use display typography for page titles and section heads only.
- Keep paragraph text in body font for legibility.
- Keep Google font loading aligned with current usage:
  - `Cormorant Infant`: `600`, `700` (no italic)
  - `Manrope`: `400`, `500`, `600`, `700`

## Color system

Global neutrals are defined in `frontend/src/app.css` using CSS variables.

- `--background`, `--card`, `--foreground`, `--muted-foreground`, `--border`
- `--page-accent` drives route-level emphasis.
- `--page-accent-soft` is the low-contrast companion tint.

### Domain accents (muted and professional)

- Dashboard: `--accent-dashboard`
- Products: `--accent-products`
- Routines: `--accent-routines`
- Skin: `--accent-skin`
- Profile: `--accent-profile`
- Health labs: `--accent-health-labs`
- Health medications: `--accent-health-meds`

The app shell assigns a domain class per route and maps it to `--page-accent`.

## Where to use accent color

Use accent for:

- active navigation state
- important buttons and key badges
- focus ring tint and hover border tint
- section separators and small status markers

Do not use accent for:

- full-page backgrounds
- body text
- large surfaces that reduce readability

Guideline: accent should occupy roughly 10-15% of visual area per screen.

## Layout rules

- Use the app shell spacing rhythm from `app.css` (`.app-main`, editorial cards).
- Keep max content width constrained for readability.
- Prefer asymmetry in hero/summary areas, but keep forms and dense data grids regular.

### Shared page wrappers

Use these wrappers before introducing route-specific structure:

- `editorial-page`: standard constrained content width for route pages.
- `editorial-hero`: top summary strip for title, subtitle, and primary actions.
- `PageHeader.svelte`: preferred reusable wrapper for page-level hero sections; use it to keep title hierarchy, backlinks, meta rows, and action placement consistent.
- `editorial-panel`: primary surface for forms, tables, and ledgers.
- `editorial-toolbar`: compact action row under hero copy.
- `editorial-backlink`: standard top-left back navigation style.
- `editorial-alert`, `editorial-alert--error`, `editorial-alert--success`, `editorial-alert--warning`, `editorial-alert--info`: feedback banners.
- `page-header-meta`, `page-header-foot`, `hero-strip`: shared secondary rows inside page headers for compact metadata and summary stats.

### Collapsible panels

For secondary information (debug data, reasoning chains, metadata), use this pattern:

```svelte
<div class="border border-muted rounded-lg overflow-hidden">
  <button class="w-full flex items-center gap-2 px-4 py-3 bg-muted/30 hover:bg-muted/50 transition-colors">
    <Icon class="size-4 text-muted-foreground" />
    <span class="text-sm font-medium text-foreground">Panel Title</span>
    <ChevronIcon class="ml-auto size-4 text-muted-foreground" />
  </button>
  {#if expanded}
    <div class="p-4 bg-card border-t border-muted">
      <!-- Content -->
    </div>
  {/if}
</div>
```

This matches the warm editorial aesthetic and maintains visual consistency with Card components.

## Component rules

- Reuse UI primitives under `frontend/src/lib/components/ui/*`.
- Keep primitive APIs stable when changing visual treatment.
- Style via tokens and shared classes, not one-off hardcoded colors.
- New variants must be documented in this file.

### Existing shared utility patterns

These classes are already in use and should be reused:

- Lists and ledgers: `routine-ledger-row`, `editorial-mobile-card`, `health-entry-row`
- Group headers: `editorial-section-title`
- Table shell: `editorial-table-shell`
- Compact metadata rows: `editorial-meta-strip`
- Tabs shell: `products-tabs`, `editorial-tabs`
- App shell/navigation: `app-mobile-header`, `app-drawer`, `app-nav-list`, `app-nav-link`, `app-sidebar-footer`
- Reusable locale control: `LanguageSwitcher.svelte` with `language-switcher*` classes
- Dashboard summary patterns: `dashboard-stat-strip`, `dashboard-stat-card`, `dashboard-attention-list`, `dashboard-attention-item`
- Health semantic pills: `health-kind-pill*`, `health-flag-pill*`
- Lab results utilities:
  - metadata chips: `lab-results-meta-strip`, `lab-results-meta-pill`
  - filter/paging surfaces: `editorial-filter-row`, `lab-results-filter-banner`, `lab-results-pager`
  - row/link rhythm: `lab-results-row`, `lab-results-code-link`, `lab-results-value-cell`
  - mobile density: `lab-results-mobile-grid`, `lab-results-mobile-card`, `lab-results-mobile-value`

## Forms and data views

- Inputs should remain high-contrast and calm.
- Validation/error states should be explicit and never color-only.
- Tables and dense lists should prioritize scanning: spacing, row separators, concise metadata.
- Filter toolbars for data-heavy routes should use `GET` forms with URL params so state is shareable and pagination links preserve active filters.
- Use the products filter pattern as the shared baseline: compact search input, chip-style toggle rows (`editorial-filter-row` + small `Button` variants), and apply/reset actions aligned at the end of the toolbar.
- For high-volume medical data lists, default the primary view to condensed/latest mode and offer full-history as an explicit secondary option.
- For profile/settings forms, reuse shared primitives (`FormSectionCard`, `LabeledInputField`, `SimpleSelect`) before creating route-specific field wrappers.
- In condensed/latest mode, group rows by collection date using lightweight section headers (`products-section-title`) to preserve report context without introducing heavy card nesting.
- Change/highlight pills in dense tables should stay compact (`text-[10px]`), semantic (new/flag change/abnormal), and avoid overwhelming color blocks.
- For lab results, keep ordering fixed to newest collection date (`collected_at DESC`) and remove non-essential controls (no lab filter and no manual sort selector).
- For lab results, keep code links visibly interactive (`lab-results-code-link`) because they are a primary in-context drill-down interaction.
- For lab results, use compact metadata chips in hero sections (`lab-results-meta-pill`) for active view/filter context instead of introducing a second heavy summary card; keep this strip terse (one context chip + one stats chip, with optional alert chip).
- In dense row-based lists, prefer `ghost` action controls; use icon-only buttons on desktop tables and short text+icon `ghost` actions on mobile cards to keep row actions subordinate to data.
- For editable data tables, open a dedicated inline edit panel above the list (instead of per-row expanded forms) and prefill it from row actions; keep users on the same filtered/paginated context after save.
- When a list is narrowed to a single entity key (for example `test_code`), display an explicit "filtered by" banner with a one-click clear action and avoid extra grouping wrappers that add no context.
- For dashboard-style summaries, prefer compact stat strips and attention rows over large decorative cards; each item should pair one strong value with one short explanatory line.

### DRY form primitives

- Use shared form components for repeated native select markup:
  - `frontend/src/lib/components/forms/SimpleSelect.svelte`
  - `frontend/src/lib/components/forms/GroupedSelect.svelte`
- Use shared checkbox helper for repeated label+hint toggles:
  - `frontend/src/lib/components/forms/HintCheckbox.svelte`
- Use shared input field helper for repeated label+input rows:
  - `frontend/src/lib/components/forms/LabeledInputField.svelte`
- Use shared section card helper for repeated titled form panels:
  - `frontend/src/lib/components/forms/FormSectionCard.svelte`
- Use shared class tokens from:
  - `frontend/src/lib/components/forms/form-classes.ts`
- Prefer passing option labels from route files via `m.*` to keep i18n explicit.

### Select policy (performance + maintainability)

- Default to native `<select>` for enum-style fields and simple pickers.
- Use `SimpleSelect` / `GroupedSelect` for consistency and to reduce duplication.
- Avoid `ui/select` primitives unless search, custom keyboard behavior, or richer popup UX is truly needed.
- For grouped option sets (e.g. products by category), use `<optgroup>` via `GroupedSelect`.

### Chunk hygiene

- Large forms should be split into focused section components.
- Lazy-load heavyweight modal and optional sections where practical.
- After structural UI refactors, run `pnpm build` and inspect output for large chunks.
- Track and prevent regressions in known hotspots (form-heavy pages and shared interaction primitives).

## Motion

- Entry animations: short upward reveal with slight stagger.
- Hover interactions: subtle translation or tint only.
- Never stack multiple strong animations in the same viewport.

## Accessibility baseline

- Keyboard navigation for all interactive elements.
- Visible focus states on controls and links.
- Respect reduced motion.
- Maintain readable contrast for text, borders, and controls.

## i18n rules

- Do not add hardcoded UI labels in route components when a message key already exists.
- Prefer existing `m.*` keys from paraglide for headings, labels, empty states, and helper text.
- If a new label is required, add a new translation key instead of shipping English literals.
- Keep fallback display values localized (`m.common_unknown()` over hardcoded `n/a`).
- Avoid language-specific toggle text in reusable components unless fully localized.

## Implementation checklist for new UI work

1. Pick the route domain and rely on `--page-accent`.
2. Use existing typography pair and spacing rhythm.
3. Build with primitives first; add route-level wrappers only if needed.
4. Validate mobile and desktop layout.
5. Run:
   - `pnpm check`
   - `pnpm lint`
   - `pnpm build` (for significant component architecture changes)

## File touchpoints

- Core tokens and global look: `frontend/src/app.css`
- App shell and route domain mapping: `frontend/src/routes/+layout.svelte`
- Shared page header: `frontend/src/lib/components/PageHeader.svelte`
- Route examples using the pattern:
  - `frontend/src/routes/+page.svelte`
  - `frontend/src/routes/products/+page.svelte`
  - `frontend/src/routes/routines/+page.svelte`
  - `frontend/src/routes/profile/+page.svelte`
  - `frontend/src/routes/health/lab-results/+page.svelte`
  - `frontend/src/routes/skin/+page.svelte`
- Primitive visuals:
  - `frontend/src/lib/components/ui/button/button.svelte`
  - `frontend/src/lib/components/ui/card/card.svelte`
  - `frontend/src/lib/components/ui/input/input.svelte`
  - `frontend/src/lib/components/ui/badge/badge.svelte`

- Shared form DRY helpers:
  - `frontend/src/lib/components/forms/SimpleSelect.svelte`
  - `frontend/src/lib/components/forms/GroupedSelect.svelte`
  - `frontend/src/lib/components/forms/HintCheckbox.svelte`
  - `frontend/src/lib/components/forms/LabeledInputField.svelte`
  - `frontend/src/lib/components/forms/FormSectionCard.svelte`
  - `frontend/src/lib/components/forms/form-classes.ts`

- i18n message source:
  - `frontend/src/lib/paraglide/messages/*`

When introducing new visual patterns, update this cookbook in the same change.