# Portfolio AI design system proof

> A compact AI-readable interface contract for Portfolio AI: tokens, components, interaction rules, accessibility rules, and machine-readable docs.

## Canonical routes
- Visual page: https://www.minwookshin.com/design-system
- Markdown: https://www.minwookshin.com/design-system.md
- Tokens JSON: https://www.minwookshin.com/design-system/tokens.json
- Portfolio AI case study: https://www.minwookshin.com/work/portfolio-ai

## Source files
- app/globals.css
- lib/material/motion.ts
- components/HomePage.tsx
- components/detail/CaseStudy.tsx
- components/StudioVideoPlayer.tsx
- lib/aiPortfolio.ts

## Design tokens
### Color roles
- background.base: #FFFFFF (--bg-base) - page canvas
- background.surface: #FFFFFF (--bg-surface) - quiet panels and inputs
- background.element: #F4F4F5 (--bg-element) - resting underline, subtle UI fill, skeleton states
- border.light: #E2E4E9 (--border-light) - hairline structure only where needed
- text.primary: #000000 (--text-primary) - primary text and active links
- text.muted: #A1A1AA (--text-muted) - metadata, secondary copy, timestamps
- text.underlineMuted: #F4F4F5 (--text-underline-muted) - resting link underline
- dark.background: #08090A (--dark-bg-base) - embedded dark code/project surfaces
- dark.surface: #121314 (--dark-bg-surface) - embedded dark detail surfaces

### Typography
- sans: Switzer, Helvetica Neue, Arial, sans-serif (--font-sans)
- mono: Geist Mono, SF Mono, monospace (--font-mono)
- caption: 0.64rem (--type--2)
- small: 0.8rem (--type--1)
- body: 1rem (--type-0)
- bodyLarge: 1.125rem (--type-3)
- displaySmall: 1.25rem (--type-4)
- body line-height: 1.55 (--leading-body)
- heading line-height: 1.16 (--leading-heading)
- tight line-height: 1.22 (--leading-tight)
- measure: 65ch (--measure)

### Spacing
- 1: 0.5rem (--space-1)
- 2: 1rem (--space-2)
- 3: 1.5rem (--space-3)
- 4: 2rem (--space-4)
- 5: 2.5rem (--space-5)
- 6: 3rem (--space-6)
- 7: 3.5rem (--space-7)
- 8: 4rem (--space-8)

### Radius and elevation
- xs: 4px (--md-shape-xs)
- sm: 4px (--md-shape-sm)
- md: 4px (--md-shape-md)
- lg: 8px (--md-shape-lg)
- xl: 8px (--md-shape-xl)
- full: 999px (--md-shape-full)
- default: none - the product relies on spacing, type, and hairlines instead of decorative shadows
- cursor: small shadow only - custom cursor affordance, not layout surfaces

### Motion
- instant: 120ms (--motion-duration-instant)
- fast: 180ms (--motion-duration-fast)
- base: 250ms (--motion-duration-base)
- slow: 350ms (--motion-duration-slow)
- reveal: 800ms (--motion-duration-reveal)
- standard: cubic-bezier(0.22, 1, 0.36, 1) (--motion-ease-standard)
- inOut: cubic-bezier(0.45, 0, 0.55, 1) (--motion-ease-in-out)
- emphasized: cubic-bezier(0.34, 1.28, 0.5, 1) (--motion-ease-emphasized)
- spatialDefault: stiffness 240, damping 30, mass 1.5
- spatialFast: stiffness 320, damping 28, mass 1.3
- pressMorph: stiffness 380, damping 26, mass 1.4
- island: stiffness 190, damping 19, mass 1.3

## Component primitives
### navigation
- Purpose: Text-first work/studies routing, identity link, and contact links using the same lateral link motion.
- Primitives: identity link, section tabs, contact links, breadcrumb trail

### project preview
- Purpose: Row-based project selection with static media fallback, subtle hover movement, and reduced-motion support.
- Primitives: project row, preview frame, metadata line, case-study route

### case study section
- Purpose: Editorial detail blocks for hero, lead, split proof, stats, gallery, video, links, and outcome.
- Primitives: hero, lead, split, stats, gallery, video, links, outcome

### ai chat and recruiter intake
- Purpose: Streaming project-intake interface connected to deterministic project routing and public proof links.
- Primitives: chat input, answer stream, project action, question prompt

### buttons and links
- Purpose: Plain text links, focus-visible outlines, press affordance, and no decorative icon dependency unless useful.
- Primitives: micro link, lateral link, focus ring, pressable row

### cards and surfaces
- Purpose: Transparent or white surfaces with spacing-first hierarchy; borders appear only when structure needs them.
- Primitives: detail panel, media frame, code block, status block

### status and proof blocks
- Purpose: Build version, updated time, resume links, markdown routes, and public repository proof.
- Primitives: build meta, proof repository list, markdown route, tokens JSON

## Interaction rules
- Keep hover movement small: text and metadata can shift, but the layout should not reflow.
- Use 180ms to 300ms transitions for hover, focus, and press feedback; reserve longer reveal timing for page entry or scroll entry.
- Use blur only as a brief entry bridge, not as a permanent decorative layer.
- Provide static image or text fallbacks for media previews and reduced-motion users.
- Buttons, links, project rows, and video controls must be reachable by keyboard and expose visible focus states.
- Loading states should preserve space so rows, inputs, and proof blocks do not jump.

## Accessibility rules
- Use semantic routes, headings, links, buttons, lists, and landmarks before visual wrappers.
- Keep contrast intent simple: black primary text on white, muted gray only for secondary copy and metadata.
- Never hide essential navigation behind hover-only behavior.
- Focus-visible outlines are required for interactive text, rows, buttons, and controls.
- Respect prefers-reduced-motion with static or non-transform fallbacks.
- Write descriptive link labels; avoid bare arrows as the only action label.

## AI-readable contract
### Use
- Compose new UI from existing route, row, section, link, proof, and media primitives.
- Use token roles instead of raw color values unless documenting a token.
- Keep copy concise, evidence-based, and recruiter-readable.
- Prefer spacing, typography, and small motion over decorative surfaces.
- Expose important proof through both visible UI and machine-readable routes.

### Avoid
- Do not invent metrics, employers, awards, repository links, or project outcomes.
- Do not create a separate visual system, large landing page, or marketing-heavy hero for proof pages.
- Do not add new dependencies for primitives that already exist in the codebase.
- Do not use flashy gradients, decorative glass, or large motion that competes with the work.
- Do not remove reduced-motion, keyboard, or focus-visible behavior.