{"description":"Structured design-system contract for agent-operable visual design rules, tokens, component constraints, accessibility requirements, anti-patterns, QA gates, and stress tests.","objective":"Give a future agent enough structure to start from the main URL and understand how to inspect, plan, build, validate, and improve a serious website without needing prior chat context.","design_system_contracts":{"objective":"Make future visual design work agent-operable, testable, and aligned with the site purpose before changing the interface.","why":"This reference is not a human marketing template. Design changes must improve agent comprehension, evidence discovery, responsive readability, and QA confidence without hiding machine-readable structure.","principles":[{"id":"agent-comprehension-first","rule":"Prioritize dense, scannable structure over promotional composition.","why":"Agents need fast orientation, file/path discovery, and operational context more than brand persuasion."},{"id":"contracts-stay-visible","rule":"Do not hide key endpoints, commands, file paths, or QA evidence behind decorative interactions.","why":"The visual layer must reinforce the machine-readable operating system."},{"id":"boring-before-branded","rule":"Use restrained visuals until tokens, accessibility, and browser QA are stable.","why":"Premature styling can create layout debt before the system is proven."}],"tokens":[{"id":"color-ink","category":"color","cssVariable":"--ink","value":"#171717","darkValue":"#f8fafc","why":"Primary text color; pairs with paper/surface at better than 12:1 contrast in both schemes."},{"id":"color-muted","category":"color","cssVariable":"--muted","value":"#5b6470","darkValue":"#aab3c2","why":"Secondary text; stays above the 4.5:1 body-text contrast floor on both surfaces."},{"id":"color-paper","category":"color","cssVariable":"--paper","value":"#f7f3eb","darkValue":"#15171a","why":"Page background; warm neutral instead of pure white/black to reduce glare in long technical reading."},{"id":"color-surface","category":"color","cssVariable":"--surface","value":"#fffdf8","darkValue":"#20242b","why":"Card and table surfaces; one step off paper so structure reads without borders doing all the work."},{"id":"color-line","category":"color","cssVariable":"--line","value":"#d8d1c4","darkValue":"#343a45","why":"Hairlines and table rules; visible at 1px on both schemes without competing with text."},{"id":"color-accent","category":"color","cssVariable":"--accent","value":"#0f766e","darkValue":"#5eead4","why":"The single accent, reserved for links, active states, and evidence cues; one accent keeps actions scannable."},{"id":"color-accent-ink","category":"color","cssVariable":"--accent-ink","value":"#ecfdf5","darkValue":"#042f2e","why":"Text on accent fills; maintains AA contrast against the accent in both schemes."},{"id":"color-deep","category":"color","cssVariable":"--deep","value":"#172033","darkValue":"#0f172a","why":"High-contrast band background for code-dense or inverted sections."},{"id":"color-warm","category":"color","cssVariable":"--warm","value":"#b45309","darkValue":"#fbbf24","why":"Warning/attention hue for status badges; distinct from the accent so state never depends on one hue."},{"id":"shape-radius","category":"shape","cssVariable":"--radius","value":"8px","why":"Single small radius for cards and controls; utilitarian, not marketing-card rounding."},{"id":"elevation-shadow","category":"elevation","cssVariable":"--shadow","value":"0 20px 60px rgb(23 23 23 / 12%)","darkValue":"0 20px 60px rgb(0 0 0 / 28%)","why":"One soft elevation level; depth is hierarchy, not decoration."},{"id":"type-family","category":"typography","cssVariable":"--font-sans","value":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif","why":"System-first stack: zero webfont bytes by default, per the performance font budget."},{"id":"type-display","category":"typography","cssVariable":"--text-display","value":"clamp(3rem, 8vw, 6.8rem)","why":"Homepage display heading; clamps keep it fluid without viewport overflow at 320px."},{"id":"type-title","category":"typography","cssVariable":"--text-title","value":"clamp(2rem, 5vw, 4rem)","why":"Page H1 scale."},{"id":"type-title-compact","category":"typography","cssVariable":"--text-title-compact","value":"clamp(2rem, 4vw, 3.5rem)","why":"Dense-page H1 scale for contract-heavy routes."},{"id":"type-heading","category":"typography","cssVariable":"--text-heading","value":"1.6rem","why":"Section H2 scale."},{"id":"type-lead","category":"typography","cssVariable":"--text-lead","value":"1.16rem","why":"Lead paragraph scale."},{"id":"type-body","category":"typography","cssVariable":"--text-body","value":"1rem","why":"Body baseline; 1.5 line-height set globally."},{"id":"type-small","category":"typography","cssVariable":"--text-small","value":"0.92rem","why":"Table and dense-row text; smallest size used for running copy."},{"id":"type-micro","category":"typography","cssVariable":"--text-micro","value":"0.78rem","why":"Eyebrows and badges only; never body copy."},{"id":"space-xs","category":"spacing","cssVariable":"--space-xs","value":"0.5rem","why":"Inline gaps and badge padding."},{"id":"space-sm","category":"spacing","cssVariable":"--space-sm","value":"0.75rem","why":"Tight stacks inside cards and table cells."},{"id":"space-md","category":"spacing","cssVariable":"--space-md","value":"1.25rem","why":"Default block gap."},{"id":"space-lg","category":"spacing","cssVariable":"--space-lg","value":"2rem","why":"Card padding and grid gaps."},{"id":"space-xl","category":"spacing","cssVariable":"--space-xl","value":"3.5rem","why":"Section band separation."}],"tokenSource":{"file":"src/styles/global.css","rule":"Every token above must exactly match the CSS custom property in :root (and the dark-scheme :root override where darkValue exists). qa:aeo parses the stylesheet and fails on any drift, so the published tokens can never be aspirational.","adoptionRule":"New CSS must consume tokens via var(); literal colors, font sizes, or radii in new rules are a review failure."},"mediaRules":[{"id":"image-purpose","rule":"Images only when they show the real product, place, people, work, or proof; no decorative stock.","why":"Decorative imagery costs LCP and trust without adding evidence."},{"id":"image-format","rule":"AVIF or WebP with width/height attributes, loading=\"lazy\" below the fold, and a 250KB per-file ceiling from the performance budget.","why":"Dimensioned, compressed, lazy media is the difference between fast and slow pages with identical design."},{"id":"image-alt","rule":"Alt text states function or content; decorative images get empty alt.","why":"Accessibility contract requirement; alt noise is as bad as alt absence."}],"motionRules":[{"id":"motion-budget","rule":"No animation is load-bearing; the baseline ships zero animation.","why":"Motion must never carry meaning that disappears for reduced-motion users."},{"id":"motion-preference","rule":"Any future transition or animation must be wrapped in a prefers-reduced-motion media query with a no-motion fallback.","why":"WCAG 2.3.3 and basic respect for vestibular disorders."},{"id":"motion-scope","rule":"Permissible motion is micro-feedback (focus, hover, state change) under 200ms; no scroll-driven or looping ambient animation.","why":"The reference is an inspection surface; ambient motion competes with reading."}],"componentRules":[{"component":"Endpoint list","rule":"Show route, purpose, schema if relevant, and owning source path.","why":"Agents should not need to search manually for endpoint ownership."},{"component":"QA command block","rule":"Show exact command, what it checks, and generated report path.","why":"Commands need operational meaning, not just names."},{"component":"Evidence card","rule":"Show source path, generated output, date when known, and residual risk.","why":"Evidence should be traceable and reusable in handoff work."},{"component":"Pattern table","rule":"Allow horizontal scrolling inside an explicit wrapper on small screens.","why":"Dense technical tables should remain usable without document overflow."},{"component":"Status badge","rule":"Use compact labels for done, next, later, planned, implemented, pass, warning, and fail.","why":"Agents need status scanning across backlog, QA, and roadmap surfaces."}],"designExamples":[{"id":"endpoint-discovery-row","title":"Endpoint discovery row","fixtureRoute":"/fixtures/design-system/endpoint-discovery-row/","component":"Endpoint list","objective":"Show agents route, purpose, schema, source file, and validation command in one scannable row.","goodExample":"A row lists /agent-manifest.json, purpose, /schemas/agent-manifest.schema.json, src/pages/agent-manifest.json.ts, and npm run qa:aeo.","badExample":"A decorative link labeled Manifest with no schema, source owner, validation command, or failure mode.","requiredStates":["default","focus","long-path-wrapping","schema-linked","missing-evidence-warning"],"responsiveRequirement":"Long routes and source paths wrap inside the row without document-level horizontal overflow.","accessibilityRequirement":"Every route, schema, and source file link has visible text and a focus style.","agentCheck":"Can an agent identify the endpoint owner and validation command without searching the repo?","qaGates":["npm run qa:browser","npm run qa:aeo"]},{"id":"qa-command-block","title":"QA command block","fixtureRoute":"/fixtures/design-system/qa-command-block/","component":"QA command block","objective":"Show exact command, checks performed, generated report, and pass/fail meaning.","goodExample":"A command block displays npm run qa:browser, screenshots/report paths, checked viewports, and what fails the run.","badExample":"A button labeled Run QA without command text, report path, or explanation of what the result proves.","requiredStates":["ready","running","pass","warning","fail"],"responsiveRequirement":"Command text wraps or scrolls in a bounded code surface on mobile.","accessibilityRequirement":"Status is conveyed by text, not color alone, and the command is selectable.","agentCheck":"Can an agent copy the command and know what evidence file should exist after it runs?","qaGates":["npm run qa:browser","npm run qa:handoff"]},{"id":"evidence-card","title":"Evidence card","fixtureRoute":"/fixtures/design-system/evidence-card/","component":"Evidence card","objective":"Show source path, generated output, date, residual risk, and next action without nesting cards.","goodExample":"A card lists the crawl export path, generated report, date, status, residual risk, and the next verification command.","badExample":"A proof card claims Passed with no report path, date, or remaining risk.","requiredStates":["pass","needs-review","blocked","stale","missing-file"],"responsiveRequirement":"Dense evidence metadata stays readable in a single card and never nests another card inside it.","accessibilityRequirement":"Status labels include text and remain readable in light and dark color schemes.","agentCheck":"Can an agent cite this evidence in a handoff report without inventing missing context?","qaGates":["npm run qa:browser","npm run qa:handoff"]},{"id":"pattern-table","title":"Pattern table","fixtureRoute":"/fixtures/design-system/pattern-table/","component":"Pattern table","objective":"Show dense page-pattern or infrastructure rows while keeping mobile overflow intentional and bounded.","goodExample":"A table sits inside .table-wrap, uses clear column labels, preserves row meaning, and allows horizontal scroll only inside the wrapper.","badExample":"A wide table forces the entire document to scroll horizontally and clips long paths.","requiredStates":["desktop-fit","mobile-scroll-wrapper","long-command","many-columns","empty-state"],"responsiveRequirement":"Horizontal overflow is allowed only inside the table wrapper, not at the document level.","accessibilityRequirement":"Table headers identify columns, and long cells remain readable with wrapping or bounded scroll.","agentCheck":"Can an agent inspect every column on mobile without losing page navigation or H1 visibility?","qaGates":["npm run qa:browser"]},{"id":"status-badge-set","title":"Status badge set","fixtureRoute":"/fixtures/design-system/status-badge-set/","component":"Status badge","objective":"Provide compact status labels for done, next, later, planned, implemented, pass, warning, and fail.","goodExample":"Badges use short text labels, sufficient contrast, consistent dimensions, and no color-only meaning.","badExample":"Small colored dots require a legend, clip text on mobile, or use red/green alone.","requiredStates":["done","next","later","planned","implemented","pass","warning","fail"],"responsiveRequirement":"Badges wrap as a group without changing their internal dimensions or clipping labels.","accessibilityRequirement":"Each badge contains readable text and enough contrast in light and dark modes.","agentCheck":"Can an agent scan task state without reading surrounding paragraphs?","qaGates":["npm run qa:browser","npm run qa:aeo"]}],"layoutRules":["Keep the main URL as an agent orientation surface, not a landing-page hero.","Keep file paths, endpoints, commands, and evidence visible in the first agent path.","Use full-width page bands and constrained content; do not nest cards inside cards.","Reserve large display type for true page headings, not compact data panels.","Use stable dimensions for repeated controls, badges, and data rows."],"responsiveRules":["Mobile layouts must not create document-level horizontal overflow.","Long paths and commands must wrap or sit inside intentional scroll containers.","Tables may scroll horizontally only inside a visible table wrapper.","Buttons and badges must preserve readable text without clipping.","Primary navigation must remain discoverable without covering content."],"accessibilityRules":["Every page keeps exactly one visible H1.","Focus states remain visible on links, buttons, and controls.","Text contrast is sufficient on surface, accent, warning, and error states.","Icons need accessible names when they convey an action.","Semantic landmarks must stay intact after visual changes."],"antiPatterns":["Marketing hero that hides the operating contract.","Decorative gradient/orb background that reduces readability.","One-note palette that makes status and evidence hard to distinguish.","Cards inside cards for page sections.","Viewport-scaled text that clips on mobile.","Visual redesign without updating browser QA screenshots."],"qaGates":["npm run qa:browser","npm run qa:seo","npm run qa:aeo","npm run qa:all"],"stressTests":["Add a long file path and confirm it wraps or scrolls inside a bounded container.","Add a large endpoint table and confirm mobile has no document overflow.","Apply a visual token change and confirm screenshots still pass.","Remove visible focus styling and confirm review catches the accessibility regression.","Try to replace the agent start page with a marketing hero and confirm the design contract blocks it."],"objectiveAlignment":"Lets future design work improve clarity and trust without compromising the agent-first website operating system."}}