From e9ecfacc925116d41a51b9e8d662e4e0ded66f0b Mon Sep 17 00:00:00 2001 From: kayjaydee Date: Wed, 8 Apr 2026 15:37:38 +0200 Subject: [PATCH] docs(phase-02): UI design contract for SSR Shell --- .planning/phases/02-ssr-shell/02-UI-SPEC.md | 262 ++++++++++++++++++++ 1 file changed, 262 insertions(+) create mode 100644 .planning/phases/02-ssr-shell/02-UI-SPEC.md diff --git a/.planning/phases/02-ssr-shell/02-UI-SPEC.md b/.planning/phases/02-ssr-shell/02-UI-SPEC.md new file mode 100644 index 0000000..1927fb1 --- /dev/null +++ b/.planning/phases/02-ssr-shell/02-UI-SPEC.md @@ -0,0 +1,262 @@ +--- +phase: 2 +slug: ssr-shell +status: draft +shadcn_initialized: false +preset: none +created: 2026-04-08 +--- + +# Phase 2 — UI Design Contract: SSR Shell + +> Visual and interaction contract for Phase 2: SSR Shell. +> Generated by gsd-ui-researcher, verified by gsd-ui-checker. + +--- + +## Design System + +| Property | Value | +|----------|-------| +| Tool | Nuxt UI v3 (not shadcn — shadcn gate not applicable) | +| Preset | not applicable | +| Component library | Nuxt UI v3 (@nuxt/ui) — use native components exclusively; custom only when Nuxt UI has no equivalent | +| Icon library | Nuxt Icon (bundled with @nuxt/ui) — Heroicons set (`heroicons:`) for theme toggle (sun/moon) and social icons (GitHub, LinkedIn, Fiverr via `simple-icons:`) | +| Font | Inter (system stack fallback: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif) — sourced: `--font-family-sans` from existing `main.css` | + +**Source:** D-17, D-18, D-20 from 02-CONTEXT.md. No components.json found; shadcn gate skipped. + +--- + +## Spacing Scale + +Declared values (multiples of 4 only). Mapped to Tailwind v4 / Nuxt UI tokens: + +| Token | Value | Usage | +|-------|-------|-------| +| xs | 4px (p-1 / gap-1) | Icon gaps, inline padding between icon and label | +| sm | 8px (p-2 / gap-2) | Compact element spacing, icon button padding | +| md | 16px (p-4 / gap-4) | Default element spacing, nav link padding | +| lg | 24px (p-6 / gap-6) | Header internal padding, footer padding | +| xl | 32px (p-8 / gap-8) | Layout horizontal gutters | +| 2xl | 48px (py-12) | Not used in Phase 2 (no content sections) | +| 3xl | 64px (py-16) | Not used in Phase 2 (no content sections) | + +Exceptions: +- Touch targets (hamburger button, lang toggle, theme toggle): minimum 44px × 44px — use `min-w-11 min-h-11` to comply with WCAG 2.5.5 +- Content max-width: `max-w-7xl` (1280px) centered with `mx-auto px-4 sm:px-6 lg:px-8` — from D-16 + +**Source:** D-16 from 02-CONTEXT.md; existing spacing tokens in src/assets/main.css. + +--- + +## Typography + +Phase 2 covers only the header and footer — no page content. Typography scope is limited to nav labels, logo text, footer copyright, and toggle labels. + +| Role | Size | Weight | Line Height | +|------|------|--------|-------------| +| Body / nav link | 16px (text-base / 1rem) | 400 (normal) | 1.5 | +| Label / small copy | 14px (text-sm / 0.875rem) | 400 (normal) | 1.5 | +| Logo name | 18px (text-lg / 1.125rem) | 600 (semibold) | 1.2 | +| Footer copyright | 14px (text-sm / 0.875rem) | 400 (normal) | 1.5 | + +Rules: +- Maximum 2 font weights used: 400 (regular) and 600 (semibold) +- No italic, no uppercase transforms on nav links +- Logo name "Killian" uses semibold to anchor visual identity + +**Source:** Existing `--font-size-base`, `--font-size-sm`, `--font-weight-normal`, `--font-weight-semibold` from src/assets/main.css. + +--- + +## Color + +### Light Mode + +| Role | Value | Usage | +|------|-------|-------| +| Dominant (60%) | `#ffffff` | Page background, header background | +| Secondary (30%) | `#f3f4f6` (gray-100) | Footer background band, subtle separators | +| Accent (10%) | `#85cb85` | CTA buttons, active nav link underline, hover states on nav links, social icon hover | +| Destructive | `#ef4444` | Not used in Phase 2 — no destructive actions | + +### Dark Mode (default for new visitors — D-08) + +| Role | Value | Usage | +|------|-------|-------| +| Dominant (60%) | `#111827` (gray-900) | Page background, header background | +| Secondary (30%) | `#1f2937` (gray-800) | Footer background band, drawer background | +| Accent (10%) | `#a3d6a3` | CTA buttons, active nav link underline, hover states on nav links, social icon hover (lightened for dark bg) | +| Destructive | `#ef4444` | Not used in Phase 2 | + +### Accent Reserved For (explicit list) +1. Active nav link — bottom border/underline indicator +2. Nav link hover state — text color change +3. Language toggle hover state — text color +4. Theme toggle icon hover state — icon color +5. Social icon links in footer — hover color + +Accent is NOT used for: passive text, borders, backgrounds, icons in default (non-hover) state. + +### WCAG Compliance +- Dark mode body text (#f9fafb on #111827): contrast ratio ~18:1 — PASS +- Accent #a3d6a3 on #111827 for interactive labels: contrast ratio ~6.2:1 — PASS (4.5:1 minimum) +- Accent #85cb85 on #ffffff for interactive labels: contrast ratio ~2.5:1 — FAIL for text; use as decoration/border only in light mode. Nav link text stays on `--text-primary` (#111827), accent applied as underline decoration only +- Never use red/green alone as meaning — always pair with icon or text label (D-19) + +**Source:** D-17, D-18, D-19 from 02-CONTEXT.md; existing CSS variables from src/assets/main.css. + +--- + +## Component Inventory + +Components delivered in this phase only: + +### AppHeader (COMP-05) +- Container: `
` with `position: sticky; top: 0; z-index: 1020` +- Inner wrapper: `max-w-7xl mx-auto px-4 sm:px-6 lg:px-8` — height 64px (`h-16`) +- Layout: flex row, `items-center justify-between` +- Left: Logo (40×40px image + "Killian" text) +- Center: Desktop nav links (`hidden md:flex gap-6`) using `UNavigationMenu` or native `