Design system architecture

Skill jacob-balslev/skills/skills/frontend-engineering/design-system-architecture

Public Agent Skills library exported from skill-graph. Install: npx skills add jacob-balslev/skills

Install

npx -y skills add jacob-balslev/skills --skill design-system-architecture

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when designing or auditing a design system's architecture: token taxonomy, semantic tokens, component APIs, theming, accessibility contracts, documentation, governance, and migration strategy. Do NOT use for information hierarchy and navigation (use `information-architecture`), page-specific layout (use `layout-composition`), visual craft direction (use `visual-design-foundations`), sentence-level UI copy (use `microcopy`), or accessibility-only audits (use `a11y`).

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

12.7 KB, as published. Nobody here has run it

Design System Architecture

Concept of the skill

A design system architecture is the discipline of turning recurring UI decisions into a governed, layered vocabulary so that building a screen becomes composition from durable parts rather than a fresh round of local choices. It has three layers and a rule layer. Raw tokens hold the literal brand values — a palette, a spacing ramp, a type scale. Semantic tokens name product meaning (surface, danger, primary-action, text-muted) and point at raw tokens, so the meaning of a token is stable while the value behind it can change per theme. Component contracts define each reusable piece — its purpose, props and slots, states, accessibility behavior, and composition rules — and consume only semantic tokens, never raw values. Over all three sits governance: forbidden local overrides, deprecation and migration paths, documentation that shows expected use and anti-use, and drift detection between code and design intent. The architecture's job is to encode decisions once and make them reusable and enforceable, so that color, spacing, state, theming, and accessibility are answered by the system instead of re-decided on every screen — and a theme change or token rename propagates through the semantic layer without rewriting components.

Coverage

Design and audit reusable UI systems. Covers token taxonomy, semantic vs raw tokens, component APIs, variants, slots, theming, accessibility contracts, responsive behavior, documentation, governance, migration, and drift detection between code and design intent.

Philosophy of the skill

A design system is a product architecture layer, not a style pile. Tokens and components should encode durable decisions so product work becomes faster and more consistent. If every screen still makes local choices for color, spacing, state, and behavior, the design system is only decorative.

Optimize for clear constraints. A system with too many escape hatches is not flexible; it is ungoverned.

Method

Inventory tokens, components, variants, and usage hotspots.
Separate raw tokens from semantic tokens.
Define component contracts: purpose, props/slots, states, accessibility, and composition rules.
Establish theming and density rules before multiplying variants.
Mark forbidden local overrides and migration paths.
Add docs examples that show expected use and anti-use.
Verify real screens can be built without one-off styling.

Verification

Semantic tokens cover product meaning without leaking palette names
Components have clear ownership and API boundaries
Variants map to real use cases, not visual guesses
Accessibility behavior is part of the component contract
Theming does not require component-level rewrites
Deprecated tokens or components have migration paths
Real product screens can use the system without local escape hatches

Do NOT Use When

Use instead	When
`information-architecture`	You need page hierarchy, navigation, sitemap, or wayfinding.
`microcopy`	You need UI wording, labels, empty states, or error copy.
`a11y`	You need focused accessibility compliance verification.
`layout-composition`	You need page-specific responsive structure, section order, or breakpoints.
`visual-design-foundations`	You need color, typography, spacing, density, or visual craft direction.
`interaction-patterns`	You need to choose a control or interaction pattern before systemizing it.
`refactor`	You are only restructuring existing code without changing design-system contracts.