What is the design-system-architecture skill?
The design-system-architecture skill is a guide an AI coding agent follows when creating or evolving a component library. It covers a three-tier token model of primitive, semantic and component tokens, React and TypeScript component API patterns, atomic design categories, documentation structure and versioning rules.
The design-system-architecture skill opens with a diagram of three stacked boxes: component tokens on top, semantic tokens in the middle and primitive tokens at the base. That layered model is the spine of the whole guide.
It lives in the skills folder of the Cortex repository and has triggers such as design system, component library, design tokens, theme architecture and ui kit.
The token model it teaches
- Primitive tokens hold raw values, for example a blue at the 500 step, a spacing step of 1rem and a medium radius of 8px.
- Semantic tokens give purpose, such as an action color and a primary text color, and point back to primitives with CSS variables.
- Component tokens bind semantics to parts, for instance a button background, button horizontal padding and a card radius.
- Light and dark themes are objects that remap semantic names, so components never hardcode a color.
What changes in your agent's output
- Components expose typed props with defaults, such as variant, size, loading and disabled states, plus an optional leading icon.
- Complex widgets use the compound pattern, so Tabs offers List, Tab and Panel parts instead of one giant prop list.
- Layout primitives can render as other elements through a polymorphic as prop.
- Each component gets docs with usage, a props table, examples and an accessibility section.
Who the design-system-architecture skill is for
Best for
- Starting a design system or evolving an existing component library with a clear token structure.
- Teams that want one agreed component API style, with a good place to compare notes in design-token.
- Library authors who want release rules in writing: semantic versioning, deprecation warnings before removal and migration guides.
Not for
- Getting ready-made components. The skill is guidance and ships none. For a copy-in component source, see shadcn.
- Stacks outside React and TypeScript without adaptation, since the prop and polymorphic examples use both.
- Choosing a visual style or a color palette. It structures tokens and does not pick brand values.
Use it with UiChemy
A token system is the contract between design and code. If your design lives in Figma, UiChemy Figma to WordPress converts it into an editable WordPress page, and Composer adjusts it afterward. Click Get Started on uichemy.com. For building the library itself in Figma, see figma-generate-library.
How to install Design System Architecture Skill: Tokens and Component APIs
git clone https://github.com/NickCrew/Claude-Cortex.gitFetch the repository
Run
git clone https://github.com/NickCrew/Claude-Cortex.git. Cortex bundles many skills, and this one is at skills/design-system-architecture.Pick out the folder
Lift skills/design-system-architecture out of the clone and put it where your agent looks for skills. The Cortex README says its installer links bundled skills into
~/.claude/for Claude Code.Name the job
Tell the agent whether you are creating a design system, evolving a component library, defining tokens or setting up documentation.
Use a trigger word
Phrases from the skill's trigger list, such as design system, component library, design tokens, theme architecture or ui kit, point the agent to it.
Check that it loaded
Ask for a token structure for a small button and card set. The reply should separate primitive, semantic and component tokens and offer a light and a dark theme mapping.
Key features
- Three-tier token systemPrimitive, semantic and component tokens are shown as a stack, with examples such as blue-500, color-action-primary and button-primary-bg to make the naming difference clear.
- CSS custom property examplesToken categories are written as CSS variables, with semantic variables referencing primitives through var(), and component variables referencing semantic ones.
- Theme supportLight and dark themes are TypeScript objects that map semantic names such as background, text and border to different primitive values.
- Typed prop API designA button example uses variant, size, isLoading, isDisabled and leftIcon props with default values, so the component works out of the box and TypeScript guides usage.
- Compound componentsTabs is split into List, Tab and Panel parts, which keeps the API small for complex interfaces and lets the consumer arrange the pieces.
- Polymorphic componentsA Box component takes an as prop, so the same primitive can render as a section or a button while still accepting that element's native props.
- Atomic design categoriesAtoms cover buttons, inputs, labels and layout primitives. Molecules cover form fields and cards. Organisms cover headers, data tables and modals.
- Documentation templateA markdown template lists usage code, a props table with type, default and description, example groups and accessibility notes such as using the button element by default.
- Design principlesFive rules guide the agent: composition over configuration, sensible defaults, accessible by default, type-safe APIs and a minimal API surface.
- Maintenance rulesSemantic versioning for breaking changes, deprecation warnings before removal, migration guides for major versions and automated visual regression testing.
Frequently asked questions
What is the design-system-architecture skill?
It is a guide inside the Cortex repository for building scalable design systems. It covers token architecture, component API patterns, atomic design categories, documentation strategy and maintenance rules, so an AI coding agent can create or evolve a component library with a consistent structure.
How do I install the design-system-architecture skill?
Clone the Cortex repository and copy skills/design-system-architecture into your agent's skills directory. The README's Homebrew and pip routes install the full framework instead. After copying, ask the agent about design tokens, a component library or theme architecture to bring the skill in.
What are the three token tiers?
Primitive tokens hold raw values such as a blue shade, a spacing step or a radius. Semantic tokens name a purpose, like a primary action color or text color. Component tokens attach those meanings to specific parts, such as a button background or card radius.
Does it work with frameworks other than React?
The token and documentation advice is general, but the prop interfaces, compound components and polymorphic Box examples are written in React and TypeScript. For another framework, keep the structure and ask the agent to translate the patterns. The repository does not claim support beyond that.
Which AI coding agents can use the design-system-architecture skill?
The Cortex README says it coordinates Claude Code, Codex and Gemini, and its installer links skills into ~/.claude/. The skill is a plain SKILL.md with keywords and triggers. The repo does not confirm this one skill on every agent, so try it in yours.
Does the skill generate my component library?
It gives rules, examples and templates, not a finished library. Your agent writes the components from those patterns. For ready component source to start from, compare options such as shadcn, then apply this skill's token layering on top.
Where do themes fit in?
Themes remap semantic tokens. The skill shows light and dark theme objects that assign values to names like background, text and border, so components keep using the same names across themes. To generate palettes and fonts as a set, see theme-factory.
What license does the design-system-architecture skill use?
The Cortex repository is MIT licensed, and the README points to its LICENSE file. The skill is bundled in that repository, so the same license applies. Check the file before you reuse the folder inside a product you distribute.