# IYU Labs design reference Start at /design. Search its pattern index by component, behavior or source file. /design/catalog.json maps the finished site patterns to their chapter fragments and implementation sources. The approved logo master is /brand/mark.svg. Never change its paths or aspect ratio (547:831). Minimum normal height: 24px. Clear space: at least 11.3% of mark height. ## Source of truth - src/design/tokens.json: semantic colors, type sizes, spacing, motion. - src/design/catalog.json: the pattern inventory used by the overview and machine-readable export. - scripts/sync-design.mjs generates src/app/tokens.css, public/design/tokens.{css,json} and public/design/catalog.json. - src/app/globals.css maps semantic roles to Tailwind and defines shared control styles. src/app/facelift.css defines the current chapter, media, orbit and navigation compositions. - src/components/ui/: Button, ButtonLink, Field, TextLink, Disclosure. - src/components/brand/: Mark and Logo, generated geometry from the approved SVG. - src/design/orbit.ts: shared ring entrance, speed, arc, stroke, color and direction defaults with strict JSON validation. - src/design/motion.ts: arrival frames and validated experimental settings. - src/design/showcase.ts: the product stage’s bounded geometry/speed/color settings and strict JSON parser. - src/components/home/Showcase.tsx: shared product stage used by the homepage and /design/motion. - src/content/showcase.ts: actual project imagery and captions derived from the project registry. ## Themes Dark is the first-visit default. A pre-paint script reads iyu-theme-v1. ThemeToggle remembers a manual choice. In isolated specimens use data-theme=dark or data-theme=light. Use text or muted on page, surface or tint. Pair accent with on-accent. Use accent-ink for links and focus. line is decorative grouping; field identifies controls. ## Type and space Manrope for headings, body and navigation. Default heading weight is 550. Bricolage Grotesque and Instrument Sans load only in the font comparison. Font licenses live in /fonts/. Social images load local TrueType assets from src/app/_og-fonts; keep those assets in the project image route’s output-file trace. pnpm build runs scripts/check-og-trace.mjs to verify the packaged fonts. Use --type-display, --type-h1, --type-h2, --type-h3, --type-body, --type-small. Body measure: 64ch. Spacing follows the 4px scale. Use token steps before inventing values. ## Interaction Use a link for navigation and a button for actions. Controls have at least 44px targets. Keep visible focus. Disclosures expose aria-expanded, keep normal document flow, and make collapsed content inert. Escape closes the mobile navigation and returns focus to its trigger. ## Motion Use --motion-quick for feedback, --motion-disclosure for disclosures and --motion-entrance for finite arrivals. Honor reduced motion. Experimental settings stay in local component state and never write site tokens. /design/motion has validated JSON import/export. ## Documentation specimens Use src/components/design/DemoPanel.tsx for shared Preview/Code tabs with local theme control. CopyButton.tsx provides value-specific confirmation and selectable failure text. Do not install a parallel demo library. The motion playground has responsive comparison, side-by-side and isolated views. Looping in the arrival specimen is opt-in. Zero speed pauses only the experiment. Hidden/offscreen effects pause; completed finite effects stay complete. All settings are local, with strict JSON export/import. The product stage has named project controls with aria-pressed. Its geometry playground offers Flat, Deep and Website presets, theme-correct original comparison, pause and JSON transfer. Zero transition speed changes the view immediately. There is no automatic carousel. Hidden/offscreen transitions pause, including transitions triggered while the preview is paused. ## Page and comparison navigation Use src/components/layout/SiteLink.tsx for internal route links. It preserves ordinary anchors and uses next-view-transitions for page changes. Keep reduced-motion and unsupported-browser paths. Forward page links reset to the top; hash links and history retain their normal behavior. src/components/work/BeforeAfter.tsx is shared by the Tyken feature, detail and motion reference. Both captures have identical dimensions. The range reveals without scaling either image; endpoints and keyboard controls remain available. One cancellable intro runs per tab, and replay never starts a loop. Do not replace the original capture with an invented or recropped responsive site. src/components/brand/BrandOrbit.tsx keeps complete rings inside a fixed SVG view box and the approved Mark stationary at its center. The idle rotation runs continuously underneath an additive entrance offset, so its velocity never drops to zero at the handoff. There are no orbit play/pause buttons. Zero speed in the isolated tool holds the current frame. Offscreen and hidden animations pause; viewport reentry restarts the entrance. Reduced motion removes movement. The shared ring playground offers isolated settings, presets, replay, same-frame original comparison and strict JSON transfer. Grids are not part of the background treatment. Product screenshots stay opaque throughout selection. Use matching viewport captures at their natural aspect ratio, one border and one soft shadow. Do not add padding, fades, offset fake edges or independently stretched image dimensions. Keep the chapter rail fixed to the bottom at every width after discovery. Use native fragment links. The recorded next-view-transitions patch skips same-path popstate transitions so anchors never create page snapshots. ## Where to find each pattern - /design/brand: artwork, spacing, lockup, actual social-image crop study, icon downloads and the shared stationary-mark/orbit composition. - /design/color: semantic themes, contrast tests, persistence and the retained brass utility aliases that now resolve to cobalt. - /design/type: editable hierarchy, font comparison/licenses, spacing tokens and responsive page composition. - /design/components: actions/links, disclosure states, field validation, project statuses, actual ProjectList and ProjectGallery/ProjectPlate previews, live header/footer, embedded homepage chapter navigation, page composition/recovery and documentation helpers. - /design/motion: actual Tyken comparison, route/fragment behavior, arrival lab, product-stage lab and orbit lab, with copyable shared-component examples and lifecycle guidance. ProjectList and ProjectRow build Work collections from src/content/projects.ts. ProjectMedia displays verified captures; ProjectGallery preserves complete images and captions. ProjectPlate is the explicit fallback for projects without screenshots. Do not fabricate an interface for a missing image. DemoPanel themes and every playground stay isolated. The chapter navigator specimen is a lazy-loaded same-origin homepage iframe with its own scrolling viewport, not a second navigation implementation. Its links and controls operate the real site within that frame. ## Copy and claims No em dashes. Describe real behavior. No invented metrics, clients, outcomes, prices or legal claims. Project facts live in src/content/projects.ts. Private launch inputs live in docs/LAUNCH_RUNBOOK.md and must stay off customer pages. ## Checks Run node scripts/sync-design.mjs --check, node scripts/sync-brand.mjs --check, pnpm lint, pnpm typecheck, pnpm test, pnpm build and pnpm test:e2e against a production server. See docs/LAUNCH_RUNBOOK.md for environment and deployment gates.