design-system

Design System

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.

Phases at a glance:

1. Philosophy & Constraints -- Brand, principles, accessibility, responsive strategy, constraints. Every subsequent decision traces here.
2. Design Tokens -- Color, typography, spacing, radii, elevation, motion, breakpoints, opacity. Each token cites a philosophy principle.
3. Atoms -- Indivisible elements (buttons, inputs, labels, icons). Each documents states and references only tokens.
4. Molecules -- Functional units composed of atoms (form fields, search bars). Documents composition and interaction.
5. Organisms -- Distinct UI sections composed of molecules and atoms (headers, forms, data tables). Documents layout behavior.
6. Templates -- Page layouts arranging organisms. Defines structure, content slots, and breakpoint behavior.
7. 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.

1. Do not assume visual preferences -- ask
2. Do not skip ahead when the user gives a partial answer -- probe deeper
3. If event model wireframes exist in docs/event_model/, use them to identify required components, but still confirm with the user
4. 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.

Missing a dependency? Install with:

npx skills add jwilger/agent-skills --skill event-modeling