generate-design-system

name

generate-design-system

description

Research, design, implement, document, and validate a complete production-ready design system tailored to a specific product, repository, organization, interface, or brand. Use when Codex is asked to create, redesign, extract, migrate, formalize, or deliver a Design System; generate DESIGN.md, DTCG design tokens, CSS variables, Tailwind v4 themes, component/state specifications, interactive HTML explorers, product demos, framework adapters, accessibility evidence, typography/color/spacing/motion rules, compact and extended variants, or reconcile an existing visual language with production code.

Generate Design System

Core Principle

Design the system around the product, users, workflows, implementation stack, and evidence. Do not impose a favorite palette, font, component library, visual trend, or previous project's identity. Treat every prior deliverable as evidence of possible scope, never as a template to copy blindly.

Produce a system that is truthful, locally appropriate, professionally complete, and usable by both humans and agents. A polished specimen without reliable tokens and implementation contracts is incomplete. A token file without visual proof and component behavior is also incomplete.

Workflow

1. Read the project before designing

• Inspect the repository, product docs, user request, existing UI, brand assets, CSS, tokens, components, screenshots, target platforms, locales, accessibility requirements, build tooling, and delivery conventions.
• Run scripts/scan_design_context.py <project-or-artifact-path> as an inventory seed when a filesystem project exists.
• Separate supplied facts, repository evidence, measured findings, design hypotheses, and external handoffs. Never present a hypothesis as research or a mockup as production evidence.
• Identify the actual audience and dominant workflows. Operational tools, consumer apps, editorial products, games, public services, and marketing sites require different density, hierarchy, motion, and component behavior.
• Preserve established conventions that are working. Replace them only when evidence or the user's explicit direction justifies the cost.

2. Declare the delivery contract

• Read references/delivery-contract.md completely before selecting deliverables.
• Inventory each deliverable as required, optional, not applicable, or external handoff. Never collapse completeness into vague labels such as “full package.”
• Explain why any normally expected deliverable is not applicable.
• Adapt filenames and adapters to the target stack, but preserve equivalent information and behavior.
• Default to a usable interactive Design System Explorer and a representative product Demo for UI-bearing systems. Do not substitute a landing page for the actual product experience.

3. Build an evidence-backed design thesis

• Read references/design-method.md completely before making visual-system decisions.
• Translate product meaning and usage into principles, not decorative metaphors.
• Define the system's voice, density, hierarchy, shape grammar, color behavior, typography roles, imagery rules, motion logic, and explicit negative constraints.
• If deriving colors from imagery, measure and cluster the source, then assign semantic roles using perceptual color and contrast rules. Do not eyedrop arbitrary colors directly into UI roles.
• Choose fonts for language coverage, legibility, licensing, loading cost, and role separation. Bundle redistributable assets and licenses when local delivery is required.

4. Author one canonical token source

• Use DTCG-compatible JSON as the canonical source unless the project already has a stronger established source of truth.
• Separate primitives, semantic aliases, component tokens, modes/themes, typography, spacing, geometry, elevation, motion, and data-visualization tokens as applicable.
• Model interaction states explicitly: default, hover, pressed, focus-visible, disabled, loading, selected, invalid, warning, success, read-only, empty, and skeleton where relevant.
• Generate or synchronize CSS Variables, Tailwind v4 theme variables, framework themes, and documentation from the canonical source. Do not maintain silently divergent copies.
• Use public token names that survive framework changes. Keep brand poetry in descriptions, not in every implementation key.

5. Design behavior, not only appearance

• Specify component anatomy, variants, sizes, states, content rules, keyboard behavior, focus behavior, responsive behavior, loading and error behavior, and accessibility names.
• Use color plus a second channel for status. Validate text, icon, boundary, focus, disabled, hover, and selected-state contrast independently.
• Define localization and mixed-script behavior, including CJK fallback stacks when applicable.
• Prefer container-aware component behavior for embeddable surfaces. Document minimum and maximum dimensions for fixed-format UI.
• Reserve cards for discrete objects or framed tools. Do not turn every page section into a card.

6. Produce the visual proof

• Build design-system.html or the project's equivalent as a real visual explorer, not a screenshot.
• Show color roles, contrast evidence, typography, fonts, spacing, shape, surfaces, elevation, motion, state matrices, component recipes, guidelines, and implementation sources selected by the delivery contract.
• Include Compact/Extended source switching when both variants are delivered. Copy and download controls must return the exact checked-in file contents.
• Add hover/focus copy affordances for token samples and keyboard-operable controls.
• Embed or link a representative interactive demo.html that proves the system in an actual product workflow.
• Keep the explorer responsive and locally runnable when the requested delivery is a portable folder.

7. Integrate with the implementation ecosystem

• Follow the target repository's existing framework and component conventions before introducing adapters.
• Deliver Tailwind v4 @theme variables only when Tailwind v4 is relevant.
• Deliver framework adapters such as Astryx, React theme objects, SwiftUI tokens, Android resources, Flutter ThemeData, or native platform assets only when they match the target.
• Compile adapters in a minimal consumer when possible. A plausible-looking source file that has never compiled is not verified integration.
• Update product code, docs, generated outputs, and asset references when the request includes migration or adoption.

8. Validate before handoff

• Read references/validation.md completely and run all applicable gates.
• Run scripts/validate_delivery.py <delivery-directory> for portable-folder deliveries, adding requirement flags that match the declared contract.
• Validate JSON, token references, CSS/HTML paths, fonts, licenses, contrast, keyboard navigation, responsive layouts, copy/download behavior, and generated-source parity.
• Render and inspect the Explorer and Demo in real browsers at desktop and mobile widths. Do not claim visual verification from source inspection alone.
• Report skipped checks and residual risks explicitly.

Default Output Shape

Use this as a starting inventory, not a rigid folder template:

design-system/
├── DESIGN.md
├── COLOR-SCIENCE.md                 # when color derivation needs evidence
├── design-tokens.json               # canonical DTCG-compatible source
├── variables.css
├── tailwind-v4.css                  # when applicable
├── design-system.html               # interactive explorer
├── demo.html                        # representative product workflow
├── assets/                          # fonts, licenses, images, generated data
├── compact/                         # concise public/agent contract
├── extended/                        # full rationale and implementation
└── <framework-adapter>/             # Astryx, React, native, etc.

For non-web systems, replace HTML/CSS artifacts with equivalent native specimens and theme outputs while preserving the same evidence, contracts, and validation depth.

Resources

• references/delivery-contract.md: complete material inventory, output variants, and applicability rules.
• references/design-method.md: evidence, product-fit decisions, foundations, semantics, typography, color, components, and anti-patterns.
• references/validation.md: production QA gates and honest handoff requirements.
• scripts/scan_design_context.py: scan a project or artifact directory for design-system inputs and consumption surfaces.
• scripts/validate_delivery.py: validate common portable Design System deliverables and detect incomplete or placeholder output.

Guardrails

• Do not copy the visual identity, palette, typography, layout, mascot, or metaphors from a previous project unless the user explicitly requests that relationship.
• Do not default to purple-blue gradients, glassmorphism, decorative orbs, generic grotesk fonts, oversized marketing heroes, or card-heavy SaaS layouts.
• Do not invent user research, brand positioning, legal clearance, font licensing, accessibility compliance, browser testing, or framework compatibility.
• Do not claim WCAG compliance from four showcase color pairs; test every meaningful foreground/background and component state pairing.
• Do not ship Latin-only font assumptions into multilingual products without an explicit fallback and mixed-script strategy.
• Do not use 550 or other uncommon public font weights without checking variable-font and downstream-tool support.
• Do not hand-maintain duplicate token values across JSON, CSS, Tailwind, adapters, and explorer data without drift checks.
• Do not omit empty, error, loading, disabled, focus-visible, reduced-motion, forced-colors, and responsive states when the product can encounter them.
• Do not leave TODOs, Lorem Ipsum, dead downloads, fake interactions, missing licenses, stale assets, or rejected explorations in the final delivery.
• Do not stop after writing a plan when the user requested deliverable files. Implement, render, test, and hand off the actual system.