design-systems-architecture
Design system architecture: W3C design tokens, Style Dictionary pipelines, component library structure, theming, multi-brand token tiers, governance, versioning, and maturity models. Use when starting or scaling a design system, generating tokens, or setting up design-to-code distribution.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- design-systems-architecture
- description
- Design system architecture: W3C design tokens, Style Dictionary pipelines, component library structure, theming, multi-brand token tiers, governance, versioning, and maturity models. Use when starting or scaling a design system, generating tokens, or setting up design-to-code distribution.
- allowed-tools
- Read, Grep, Glob
02 资源文件 6
- 参考文档references/component-library-theming.md4.0 KB
- 参考文档references/design-token-architecture.md10.0 KB
- 参考文档references/design-token-implementation.md30.1 KB
- 参考文档references/governance-scaling.md37.6 KB
- 参考文档references/maturity-model-multi-brand.md26.1 KB
- 参考文档references/token-specification-guide.md35.1 KB
03 SKILL.md 正文
Design Systems Architecture
"A design system is not a project. It is a product serving products." — Nathan Curtis
The system is the single source of truth for how a product family looks, behaves, and communicates: opinionated enough for coherence, flexible enough for diverse products.
Core Principles
- Systematic over stylistic — define rules and relationships, not just visual recipes
- Tokens are the foundation — design decisions encoded as data, not hardcoded values
- Composition over inheritance — build complex components from simple, composable primitives
- Document the why — every decision needs rationale to prevent future erosion
- Adopt, then adapt — products adopt the system by default, request exceptions with justification
Token Architecture
Three tiers; each tier references only the tier below:
| Tier | Purpose | Example |
|---|---|---|
| 1 Global / primitive | The full value palette | color.blue.500 = #3b82f6 |
| 2 Semantic / alias | Design intent | color.action.primary = {color.blue.500} |
| 3 Component | Where a value is used | button.primary.bg = {color.action.primary} |
Follow the W3C DTCG format: $value, $type (color, dimension, fontFamily, fontWeight, duration, cubicBezier, shadow), $description, {} references, .tokens.json files. Categories: color, spacing, typography, radius, elevation, duration, easing, sizing, opacity, z-index.
Components
- Anatomy: props/API, variants, states (default, hover, active, focused, disabled, loading, error), slots, token bindings, accessibility, documentation.
- Maturity: Defined → Implemented → Tested → Documented → Governed.
- API rules: consistent prop names, enums over booleans, composition over configuration, sensible defaults, full TypeScript types, forwarded refs, polymorphic
as.
Theming
CSS custom properties are the runtime mechanism: swap values at the root, honor prefers-color-scheme, allow a persisted manual override. Component tokens reference semantic tokens, which resolve per theme. Multi-brand: shared behavior and accessibility, per-brand token sets, a component override layer only when tokens are not enough, and a Brand x Mode theme matrix.
Governance
Hybrid contribution is the default: the core team owns primitives (Button, Input, Card) and governance; domain teams contribute domain components (DataGrid, FileUploader) under core review. Changes go RFC → design, code, and accessibility review → build with tests → document → release. Version with SemVer (MAJOR = breaking API or visual change); keep deprecations for 2 major versions with warnings and migration guidance.
Design-to-Code
Figma component names match code names exactly, and variants map to props. Tokens flow Figma → tokens.json → code through CI (Style Dictionary) into CSS variables, Swift, Android XML, React Native, and TypeScript types. Run visual regression against the Figma source.
Routing
| Question | Read |
|---|---|
| Three-tier model with JSON examples, DTCG naming, token categories, the 2025 spec update | references/design-token-architecture.md |
DTCG spec detail, full $type reference, Style Dictionary config, Token Studio, token CI/CD, the October 2025 stable release |
references/token-specification-guide.md |
| Aliasing, multi-theme tokens, transformation pipeline, platform outputs, token docs, versioning, testing | references/design-token-implementation.md |
| Component anatomy, maturity levels, API principles, theme JSON, multi-brand layering, Figma-to-code sync | references/component-library-theming.md |
| Team models, contribution workflow, RFC and proposal templates, lifecycle, versioning, docs, adoption metrics | references/governance-scaling.md |
Five-level maturity model, assessment rubric, multi-brand tokens, white-label, migration, ROI, $extensions |
references/maturity-model-multi-brand.md |
Cross-Referencing
- Visual design principles:
visual-design-mastery - Accessibility component requirements:
accessibility-inclusive-design - Motion tokens and animation:
interaction-motion-design - Mobile component adaptations:
mobile-ux-design - Figma MCP design-to-code flywheel:
figma-design-tool-workflows - CSS
@layercascade for token architecture:component-patterns-code
Key Sources
- Curtis, N. "Design Systems" and Modular Web Design
- W3C Design Tokens Community Group specification
- Figma design systems documentation
- Material Design component guidelines
- Brad Frost "Atomic Design" methodology
04 同仓库更多 Skills
no-description
暂无简介
good-skill
Fixture skill that satisfies every rule.
broken-link
Links to a reference file that does not exist.
Bad_Name
Name violates the kebab-case rule and does not match the directory.
skill-authoring
Write, review, and validate portable agent skills in SKILL.md format. Use when creating a new skill, editing an existing one, or asked whether a skill follows the Agent Skills spec.
weigh-bags
Record scale readings for each bag — empty (tare), outbound, current, final — and reconcile them against the itemised inventory to find unaccounted weight. Use when the user gives a bag weight, says how heavy something is, weighs their luggage, or asks how close to the limit they are. Appends to bags.yaml and runs scripts/reconcile.py.