Collaborative design system creation using Atomic Design methodology with a structured seven-phase process (Philosophy, Tokens, Atoms, Molecules, Organisms, Templates, Assembly). Produces a specification artifact with philosophy traceability, named design tokens, and full component hierarchy. Use when creating a design system, defining a visual language, specifying UI tokens (colors, typography, spacing), building a component catalog, or planning component architecture before implementation. Triggers on: "create a design system", "define design tokens", "component library spec", "visual language", "atoms and molecules", "style guide", "UI philosophy", "component hierarchy". NOT for: implementing components in code (use atomic-design), choosing frameworks (use architecture-decisions).
Value: Communication -- a documented design system creates shared
vocabulary for every visual decision. When philosophy is explicit and
tokens are named, contributors extend the system consistently without
guessing at intent.
Purpose
Facilitates collaborative creation of a design system specification.
Produces an artifact at docs/design-system.pen (if Pencil MCP is
available) or docs/design-system.html (single-file fallback) that
documents philosophy, tokens, and the full component hierarchy from
atoms through templates.
Practices
Detect Artifact Format
Check whether the mcp__pencil__get_editor_state tool is available.
Present: Use .pen format. Follow references/pencil-workflow.md.
Absent: Use HTML format. Follow references/html-artifact.md.
Decide the format before starting any design work. Do not switch formats
mid-process.
Follow the Seven-Phase Collaborative Process
You MUST follow references/design-phases.md for the full methodology.
Each phase completes before the next begins.
Artifact Assembly -- Compile into the chosen format with
philosophy as the first section.
Facilitate, Do Not Assume
You are a facilitator, not a stenographer. Ask probing questions at each
phase. Challenge choices that conflict with stated philosophy. Use
references/facilitation-questions.md for question banks.
Do not assume visual preferences -- ask
Do not skip ahead when the user gives a partial answer -- probe deeper
If event model wireframes exist in docs/event_model/, use them to
identify required components, but still confirm with the user
Present token proposals informed by the philosophy and ask for
adjustments
Enforce Philosophy Traceability
Every design decision traces back to the philosophy.
Tokens cite which philosophy principle they serve (e.g., P1)
Atoms reference which tokens they use
Molecules document which atoms they compose
Organisms document which molecules and atoms they compose
Templates document which organisms they arrange
If a token cannot cite a principle, either the token is unnecessary or
the philosophy is incomplete. Resolve before proceeding.
Do:
Define philosophy before any visual decisions
Use only token references in components -- never raw values
Complete each phase before starting the next
Verify traceability at every level
Refer to references/token-categories.md for comprehensive token guidance
Do not:
Make technology decisions (CSS framework, component library) -- those
belong in architecture-decisions
Skip the philosophy phase or treat it as optional
Use raw color codes, pixel values, or font names in components
Design multiple phases simultaneously
Proceed with gaps -- if something is undefined, ask
Enforcement Note
Advisory in all modes. Phase gates are self-enforced: the agent must
complete each phase's outputs and get user confirmation before proceeding.
Token traceability is self-enforced: the agent must verify every component
references tokens, not raw values.
Hard constraints:
Phase ordering (complete each phase before starting the next): [RP]
Constraints
"No raw values in components": This means no literal color codes, pixel
values, font sizes, or spacing values anywhere in component definitions.
"I defined a token for it" is not sufficient if the component file contains
the raw value instead of the token reference. Defining many single-use
tokens to technically satisfy this rule while defeating reusability is also
a violation.
Philosophy phase: Philosophy means named principles with enough
specificity to guide decisions. "Modern and clean" is not a philosophy --
it constrains nothing. Each principle should be testable: given a design
decision, the principle should help you choose between options. If it
doesn't eliminate any option, it's not specific enough.
Verification
After completing work guided by this skill, verify:
Philosophy documented with named principles before any components
Tokens defined for all visual categories (color, typography,
spacing, radii, elevation, motion, breakpoints, opacity)
Every token cites a philosophy principle
Atoms reference only tokens (no raw values)
Molecules compose only atoms from the catalog
Organisms compose only molecules and atoms from the catalog
Templates arrange only organisms from the catalog
All component states documented (default, hover, focus, disabled,
error as applicable)
Wireframe fields mapped to components if event model exists
Artifact exists at docs/design-system.pen or
docs/design-system.html
Philosophy is the first section in the artifact
If any criterion is not met, revisit the relevant phase before proceeding.
Dependencies
This skill works standalone. For enhanced workflows, it integrates with:
event-modeling: Wireframes from event modeling sessions identify
which components the design system must include. Run event-modeling
first for best results.
architecture-decisions: The design system specification informs
technology decisions for UI implementation (CSS framework, component
library, build tooling). Run design-system before architecture-decisions.
atomic-design: The design system specification provides the token
definitions, component catalog, and hierarchy that atomic-design
implements in code.
tdd: Token values and component specifications become testable
contracts -- visual regression tests verify token compliance.
1---2name: design-system3description: >-4 Collaborative design system creation using Atomic Design methodology with5 a structured seven-phase process (Philosophy, Tokens, Atoms, Molecules,6 Organisms, Templates, Assembly). Produces a specification artifact with7 philosophy traceability, named design tokens, and full component hierarchy.8 Use when creating a design system, defining a visual language, specifying9 UI tokens (colors, typography, spacing), building a component catalog, or10 planning component architecture before implementation. Triggers on: "create11 a design system", "define design tokens", "component library spec", "visual12 language", "atoms and molecules", "style guide", "UI philosophy", "component13 hierarchy". NOT for: implementing components in code (use atomic-design),14 choosing frameworks (use architecture-decisions).15license: CC0-1.016compatibility: Designed for any coding agent (Claude Code, Codex, Cursor, OpenCode, etc.)17metadata:18 source: https://skillmd.com/skills/jwilger/design-system19 author: jwilger20 version: "1.2.1"21 requires: []22 context: [event-model]23 phase: decide24 standalone: true25effort: high26---2728# Design System2930**Value:** Communication -- a documented design system creates shared31vocabulary for every visual decision. When philosophy is explicit and32tokens are named, contributors extend the system consistently without33guessing at intent.3435## Purpose3637Facilitates collaborative creation of a design system specification.38Produces an artifact at `docs/design-system.pen` (if Pencil MCP is39available) or `docs/design-system.html` (single-file fallback) that40documents philosophy, tokens, and the full component hierarchy from41atoms through templates.4243## Practices4445### Detect Artifact Format4647Check whether the `mcp__pencil__get_editor_state` tool is available.4849- **Present:** Use `.pen` format. Follow `references/pencil-workflow.md`.50- **Absent:** Use HTML format. Follow `references/html-artifact.md`.5152Decide the format before starting any design work. Do not switch formats53mid-process.5455### Follow the Seven-Phase Collaborative Process5657You MUST follow `references/design-phases.md` for the full methodology.58Each phase completes before the next begins.5960**Phases at a glance:**61621. **Philosophy & Constraints** -- Brand, principles, accessibility,63 responsive strategy, constraints. Every subsequent decision traces here.642. **Design Tokens** -- Color, typography, spacing, radii, elevation,65 motion, breakpoints, opacity. Each token cites a philosophy principle.663. **Atoms** -- Indivisible elements (buttons, inputs, labels, icons).67 Each documents states and references only tokens.684. **Molecules** -- Functional units composed of atoms (form fields,69 search bars). Documents composition and interaction.705. **Organisms** -- Distinct UI sections composed of molecules and atoms71 (headers, forms, data tables). Documents layout behavior.726. **Templates** -- Page layouts arranging organisms. Defines structure,73 content slots, and breakpoint behavior.747. **Artifact Assembly** -- Compile into the chosen format with75 philosophy as the first section.7677### Facilitate, Do Not Assume7879You are a facilitator, not a stenographer. Ask probing questions at each80phase. Challenge choices that conflict with stated philosophy. Use81`references/facilitation-questions.md` for question banks.82831. Do not assume visual preferences -- ask842. Do not skip ahead when the user gives a partial answer -- probe deeper853. If event model wireframes exist in `docs/event_model/`, use them to86 identify required components, but still confirm with the user874. Present token proposals informed by the philosophy and ask for88 adjustments8990### Enforce Philosophy Traceability9192Every design decision traces back to the philosophy.9394- Tokens cite which philosophy principle they serve (e.g., `P1`)95- Atoms reference which tokens they use96- Molecules document which atoms they compose97- Organisms document which molecules and atoms they compose98- Templates document which organisms they arrange99100If a token cannot cite a principle, either the token is unnecessary or101the philosophy is incomplete. Resolve before proceeding.102103**Do:**104- Define philosophy before any visual decisions105- Use only token references in components -- never raw values106- Complete each phase before starting the next107- Verify traceability at every level108- Refer to `references/token-categories.md` for comprehensive token guidance109110**Do not:**111- Make technology decisions (CSS framework, component library) -- those112 belong in architecture-decisions113- Skip the philosophy phase or treat it as optional114- Use raw color codes, pixel values, or font names in components115- Design multiple phases simultaneously116- Proceed with gaps -- if something is undefined, ask117118## Enforcement Note119120Advisory in all modes. Phase gates are self-enforced: the agent must121complete each phase's outputs and get user confirmation before proceeding.122Token traceability is self-enforced: the agent must verify every component123references tokens, not raw values.124125**Hard constraints:**126- Phase ordering (complete each phase before starting the next): `[RP]`127128## Constraints129130- **"No raw values in components"**: This means no literal color codes, pixel131 values, font sizes, or spacing values anywhere in component definitions.132 "I defined a token for it" is not sufficient if the component file contains133 the raw value instead of the token reference. Defining many single-use134 tokens to technically satisfy this rule while defeating reusability is also135 a violation.136- **Philosophy phase**: Philosophy means named principles with enough137 specificity to guide decisions. "Modern and clean" is not a philosophy --138 it constrains nothing. Each principle should be testable: given a design139 decision, the principle should help you choose between options. If it140 doesn't eliminate any option, it's not specific enough.141142## Verification143144After completing work guided by this skill, verify:145146- [ ] Philosophy documented with named principles before any components147- [ ] Tokens defined for all visual categories (color, typography,148 spacing, radii, elevation, motion, breakpoints, opacity)149- [ ] Every token cites a philosophy principle150- [ ] Atoms reference only tokens (no raw values)151- [ ] Molecules compose only atoms from the catalog152- [ ] Organisms compose only molecules and atoms from the catalog153- [ ] Templates arrange only organisms from the catalog154- [ ] All component states documented (default, hover, focus, disabled,155 error as applicable)156- [ ] Wireframe fields mapped to components if event model exists157- [ ] Artifact exists at `docs/design-system.pen` or158 `docs/design-system.html`159- [ ] Philosophy is the first section in the artifact160161If any criterion is not met, revisit the relevant phase before proceeding.162163## Dependencies164165This skill works standalone. For enhanced workflows, it integrates with:166167- **event-modeling:** Wireframes from event modeling sessions identify168 which components the design system must include. Run event-modeling169 first for best results.170- **architecture-decisions:** The design system specification informs171 technology decisions for UI implementation (CSS framework, component172 library, build tooling). Run design-system before architecture-decisions.173- **atomic-design:** The design system specification provides the token174 definitions, component catalog, and hierarchy that atomic-design175 implements in code.176- **tdd:** Token values and component specifications become testable177 contracts -- visual regression tests verify token compliance.178179Missing a dependency? Install with:180```181npx skills add jwilger/agent-skills --skill event-modeling182```
Run npx get-skill add jwilger/design-system in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Collaborative design system creation using Atomic Design methodology with a structured seven-phase process (Philosophy, Tokens, Atoms, Molecules, Organisms, Templates, Assembly). Produces a specification artifact with philosophy traceability, named design tokens, and full component hierarchy. Use when creating a design system, defining a visual language, specifying UI tokens (colors, typography, spacing), building a component catalog, or planning component architecture before implementation. Triggers on: "create a design system", "define design tokens", "component library spec", "visual language", "atoms and molecules", "style guide", "UI philosophy", "component hierarchy". NOT for: implementing components in code (use atomic-design), choosing frameworks (use architecture-decisions). It is listed under Design & Media on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free. This skill is licensed under CC0-1.
jwilger (@jwilger) published this skill. Their other Agent Skills are listed on their SkillMD profile.