---
name: design-system-from-scratch
description: "Defines a new design system in one document: tokens, components, states, and the rules for using them so teams build the same way. Use when a team starting a product or a new platform needs one document that defines design tokens, components, states, and usage rules. Do not use for restyling a single screen or generating only a colour palette. Related topics: design, coding."
---

# Design System From Scratch

Defines a new design system in one document: tokens, components, states, and the rules for using them so teams build the same way.

## When to use

Use this skill when a team starting a product or a new platform needs one document that defines design tokens, components, states, and usage rules. Do not use it for restyling a single screen or generating only a colour palette.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Define foundation tokens for colour roles, type, spacing, radius, elevation, and motion.
3. Specify each chosen component with anatomy, variants, sizes, and all seven states.
4. Write usage rules for each component, including the most common misuse.
5. Set accessibility requirements and a lightweight process for proposing and versioning components.
6. List ten decisions the team must confirm before adoption.

## Inputs

- **Product and brand personality** (longer free text)
- **Platforms covered** (choose any: Web, iOS, Android, Flutter, Email)
- **Starting colours** (free text, e.g. "Brand hex values or none")
- **Team using it** (free text, e.g. "Designers and developers and how many")
- **Component set** (choose any: Buttons, Forms, Navigation, Cards, Modals, Tables, Alerts, Tabs)
- **Output format** (choose one: Markdown, Design tokens JSON plus Markdown)

## Output

One document with Foundations, Components, Usage Rules, Accessibility, and Governance sections, ending with a ten-item decision list, in the chosen format.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Design System From Scratch

Create the foundation document for a new design system.

- Product and brand personality: {{Product and brand personality}}
- Platforms covered: {{Platforms covered}}
- Starting colours: {{Starting colours}}
- Team using it: {{Team using it}}
- Component set: {{Component set}}
- Output format: {{Output format}}

Build the document in layers. Foundations: colour roles, type scale, spacing, radius, elevation, and motion timings, all as named tokens. Components: for each chosen component give anatomy, variants, sizes, and every state (default, hover, focus, active, disabled, loading, error). Usage rules: when to use each component, when not to, and the one most common misuse. Accessibility: contrast targets, focus rings, minimum touch size, and keyboard behaviour. Governance: how a new component is proposed, reviewed, and versioned. Keep each component entry to a short block that a developer could implement from. End with a list of the ten decisions the team must confirm before adoption.

## Pitfalls

- Documenting components without states, so developers invent the missing ones differently.
- Naming tokens by value, which breaks when the brand changes.
- Omitting the misuse examples, where most inconsistency is born.