generate-design-system

Evidence in. System out.

Turn product context, user intent, implementation constraints, and existing visual evidence into a complete, production-ready Design System that humans and agents can actually ship.

English · 简体中文 · 日本語

---

Why this exists

Most “design system” requests end in one of two incomplete places:

• a beautiful specimen with no reliable tokens, state contracts, adapters, or tests;
• a JSON token dump with no product proof, interaction behavior, or visual judgment.

This skill makes an agent work like a design-system team. It reads the product first, declares the real delivery contract, creates one canonical token source, designs component behavior, produces an interactive Explorer and representative Demo, integrates the target stack, and validates what it actually shipped.

It does not carry a house palette, favorite font, default SaaS layout, or previous project's identity into the next job. Every system must fit its own users, workflows, platform, language, and implementation reality.

What it can deliver

The exact inventory is selected per project. A typical portable web delivery includes:

Layer	Deliverables
System rationale	DESIGN.md, evidence boundaries, principles, voice, negative constraints
Color evidence	COLOR-SCIENCE.md, perceptual derivation, semantic roles, contrast evidence
Source of truth	DTCG-compatible design-tokens.json
Web consumers	variables.css, Tailwind v4 @theme, typed theme objects
Product proof	Interactive design-system.html and representative demo.html
Agent contracts	Real Compact and Extended variants
Ecosystem adapters	Astryx, React, SwiftUI, Android, Flutter, native resources, as applicable
Assets	Fonts, licenses, images, generated source data
Quality evidence	JSON, token, accessibility, browser, responsive, font, and adapter checks

Completeness is contextual. Every item is marked required, optional, not applicable, or external handoff; omissions need reasons.

How the workflow closes the loop

flowchart LR
    A[Project evidence<br/>and user intent] --> B[Delivery contract]
    B --> C[Design thesis<br/>and foundations]
    C --> D[Canonical tokens]
    D --> E[Components<br/>states and behavior]
    E --> F[Explorer and<br/>product Demo]
    F --> G[Framework<br/>integration]
    G --> H[Browser, code<br/>and accessibility QA]
    H -->|findings| C
    H --> I[Honest handoff]

Loading

Install

Codex

git clone https://github.com/Nebutra/generate-design-system.git ~/.codex/skills/generate-design-system

Claude Code

git clone https://github.com/Nebutra/generate-design-system.git ~/.claude/skills/generate-design-system

Shared cross-agent source

git clone https://github.com/Nebutra/generate-design-system.git ~/workspace/share/skills/generate-design-system
ln -s ~/workspace/share/skills/generate-design-system ~/.agents/skills/generate-design-system

60-second start

Inside an agent session:

Use $generate-design-system to study this repository and deliver a complete,
production-ready Design System tailored to the product and its users.

For redesign or extraction work:

Use $generate-design-system to audit the current UI, preserve what works,
replace what does not, and migrate the implementation without token drift.

For a portable delivery folder:

Use $generate-design-system to create DESIGN.md, DTCG tokens, CSS Variables,
Tailwind v4 theme, Compact/Extended sources, an interactive Explorer, and a
representative product Demo. Mark any non-applicable item explicitly.

Built-in tools

Scan an unfamiliar project

python3 scripts/scan_design_context.py /path/to/project

The scanner inventories design files, assets, manifests, frameworks, token evidence, themes, and accessibility signals. It is an evidence seed, not a substitute for reading the product.

Validate a portable delivery

python3 scripts/validate_delivery.py ./design-system \
  --require-tailwind \
  --require-demo \
  --require-compact-extended \
  --require-adapter astryx

The validator checks required materials, JSON, DTCG token leaves, local HTML references, Compact/Extended parity, copy/download/focus signals, placeholder content, and font licenses.

Repository map

SKILL.md                         Agent workflow and guardrails
agents/openai.yaml               Codex UI metadata
references/delivery-contract.md  Material inventory and applicability rules
references/design-method.md      Evidence-led design decision system
references/validation.md         Production QA and honest handoff gates
scripts/scan_design_context.py   Project design-context scanner
scripts/validate_delivery.py     Portable delivery validator
tests/test_tools.py              Deterministic tool tests

Quality bar

The skill explicitly rejects:

• copying palettes, fonts, metaphors, or layouts from an unrelated project;
• generic purple-blue gradients, glassmorphism, decorative orbs, and card-heavy SaaS defaults;
• token files that silently disagree with CSS, Tailwind, adapters, or docs;
• Latin-only assumptions in multilingual products;
• fake research, invented compliance, unverified adapters, and “should work” claims;
• TODOs, dead downloads, fake interactions, missing licenses, stale assets, and incomplete states;
• stopping at a plan when the user asked for actual deliverable files.

Proof

The screenshot above is a real Carina Design System delivery used to validate this skill's contract. Its portable folder passed the bundled validator with:

• root, Compact, and Extended token sources;
• interactive Explorer and product Demo;
• CSS Variables, Tailwind v4, and Astryx adapter;
• local font assets and matching licenses;
• valid JSON and resolvable local HTML references.

The point is not to make every project look like Carina. The point is to make every project leave behind equally complete, inspectable, and usable evidence.

License

MIT. See LICENSE.