Skip to main content
skill CX Codex

craft-system — Claude Code skill for design systems

craft-system — a skill for Claude Code builds and updates design systems, then checks guides and screens for inconsistencies. It activates for work on tokens, components, or UI audits.

MIT ★ 393 updated 2026-11-15

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add diego3g/craft
/plugin install craft@craft
Open on GitHub

What craft-system does

The skill builds a design system in stages. It starts with colour roles, type, spacing, and interaction rules, then adds components one at a time with their variants and states. It pauses for approval between stages.

When a shared component changes, the skill lists the screens and code locations affected before propagating the update. For an audit, it reports findings by severity, location, reason, and proposed fix. It leaves files untouched until fixes are selected. It reads DESIGN.md at the project root if present and picks an adapter from references/adapters/; HTML is the fallback when no design tool is available.

What it helps with

  • set up design tokens and interaction rules
  • add a component while tracking affected screens
  • audit a guide, screens, and code for inconsistencies

Example prompts for the agent

  • Create a design system for this project and show me the foundations before adding components.
  • Add a button variant and list every affected screen and code location.
  • Audit the design system and report findings without editing files.

How to install craft-system

1Plugin marketplace

/plugin marketplace add diego3g/craft
/plugin install craft@craft

This installs the whole craft plugin with all its skills

2Skills CLI (Vercel)

npx skills add diego3g/craft --skill craft-system -a claude-code

3Manually: put the files in place

~/.claude/skills/craft-system/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/craft-system/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about craft-system

How do I install craft-system in Claude Code?

Add the marketplace with /plugin marketplace add diego3g/craft, then install the skill with /plugin install craft@craft.

What does craft-system do?

It helps create design systems, update shared components and tokens, and audit guides, screens, and code. It shows affected locations and pauses for approval before applying shared changes.

Does craft-system edit files during an audit?

No. It produces a report with proposed fixes and changes no file until fixes are chosen.

Source text

SKILL.md · MIT
---
name: craft-system
description: Use when starting a design system, style guide or token set, adding or changing a component or token, standardizing screens that drifted apart, or auditing a guide for loose colours, one-off pieces, missing states or screens that don't match it.
---

# Design system

## Overview

A design system is the place where a decision is made once and then reused everywhere. Every colour is a token, every interactive piece shows all its states, and every change reaches every screen that uses the piece. **Build it in layers, foundations first, and stop for approval at each layer. An audit reports and never fixes on its own.**

## When to use

- "Start a style guide / design system / tokens for …"
- Adding a component, variant or token, or changing an existing one.
- "Make these screens consistent", "standardize", "audit the guide", or loose hex values and one-off pieces in the screens.

## When NOT to use

- A question about one value ("what's our primary colour?"): answer it.
- A small edit the person described exactly (one value, one label, one size), even on a shared piece: change it once where it's defined and say which screens it affects. No states matrix, no stop.

## Before you start

0. Read `DESIGN.md` at the project root if it exists: it is the project's design brief.
1. Find what exists: tokens, the guide, the components, the screens and the code. **An existing guide wins on look.** Follow its rules even where they differ from the defaults below, and mention the difference once.
2. Pick your tool's adapter in `references/adapters/` (`paper.md`, `figma.md`, `html.md`). If no adapter matches your tool, do the same verbs in your tool and say which you mapped by hand. With no design tool at all, build in HTML (`html.md`). If an image is all you have, say that values read from it are estimates.
3. Decide the mode: **create**, **add or change**, or **audit**.

## Steps · create

1. **Foundations draft:**
   - colour roles ([token roles](references/token-roles.md));
   - type scale;
   - spacing;
   - radius;
   - shadows (two at most);
   - layout widths;
   - motion durations;
   - a short "how we write" section.

   Name tokens by role (`text-muted`, `border-hover`, `danger-bg`), never only by value (`gray-500`).
2. **Interaction rules, once:** for bordered pieces, borderless pieces and the primary action, write how hover, pressed, focus (keyboard only), disabled, loading and selected look. Components follow these rules instead of each inventing its own.
3. **Stop and show the person the foundations and the interaction rules.** Don't build components yet.
4. **Components one at a time, in the order the first screens need them.** Each gets a guide section with the [component anatomy](references/component-anatomy.md): a legend with the rule and why, examples, and a **states matrix** of variants × states. Add each one to the **component index**.

## Steps · add or change a piece

1. Check whether an existing component plus a variant covers it. Prefer reuse to a one-off.
2. Draw it with the anatomy, including the full states matrix. A new colour, size or icon becomes a token or an icon-set entry now, not later.
3. **List every screen and code location that uses the piece.**
4. **Stop and show the person the change and that list.**
5. On approval, propagate:
   - update every screen on the list;
   - update the code, if any. When `DESIGN.md` says the design system's source is code, do it with **REQUIRED SUB-SKILL:** `craft-sync` (export), so the code change is a reviewed diff. If that diff holds only the change just approved and no conflicts, the approval carries over: say so and apply, without a second stop;
   - update the component index;
   - report what changed where.

## Steps · audit

1. Run the [audit checklist](references/audit-checklist.md) over the guide, the screens and the code if any.
2. Write the report: findings ranked by severity, each with where it is, why it matters and the proposed fix.
3. **Stop and show the person the report. Change no file until they say which fixes to make.** Saving copies of the originals doesn't make editing them acceptable.

## Rules

**Firm (any project):**

| Rule | Why |
|---|---|
| Every colour is a token; no loose hex values in screens or code | Loose values drift into near-duplicates that nobody can change at once |
| One icon set | Mixed sets look like mixed products |
| Design and code change together, design first | Otherwise the guide stops being the truth within a week. When the system's source is code, "design first" means: draw the change in the tool, then land it in code through an approved export |
| Every interactive piece has a states matrix | States drawn ad hoc on screens never agree |
| A change to a shared piece is listed with the screens it affects before it propagates | Otherwise one "small" change silently redesigns twenty screens |

**Defaults (an existing guide overrides them):**

| Default | Why |
|---|---|
| On hover, bordered pieces only darken the border | A changing background on cards and fields feels heavy |
| Hover is subtler than selected | When hover looks like selected, people think two things are chosen |
| Selecting never changes font weight | A weight change shifts the text's width |
| Placeholders are lighter than muted text | Otherwise a placeholder reads as entered text |
| Items in stacked lists and menus have a small gap, never touching | Touching highlights merge into one block |
| The focus ring only appears from the keyboard | A ring after a mouse click looks like a bug |
| Loading keeps the element's exact size | Layout shift |
| Shadows only on floating things (menus, popovers, dialogs, toasts), at two strengths | Shadows everywhere flatten the hierarchy they were meant to create |
| At most one primary action per screen | Two primaries means the screen didn't decide |

## Done when

- **Create:** foundations and interaction rules approved; each component has its anatomy, states matrix and an index row.
- **Change:** every listed screen and code location updated, and the index updated.
- **Audit:** a ranked report delivered and no file changed.

## Common mistakes

| Thought | Reality |
|---|---|
| "I'll build the whole guide in one go: tokens and ten components" | Ten components on unapproved foundations means ten reworks. Foundations, stop, then components. |
| "The audit found problems, I'll just fix them" | The person may disagree with half of the fixes. Report, stop, fix only what they pick. |
| "I kept the originals in a backup folder, so fixing is safe" | A backup doesn't make the person agree with the fixes. Report first. |
| "Buttons have hover and disabled, good enough" | A states matrix has every state × every variant: normal, hover, pressed, focus, disabled, loading, selected. |
| "`--teal-600` is a token" | It's a value. Components need roles (`--color-primary`) so the value can change in one place. |
| "This screen needs a slightly different card" | Make it a variant of the card, or use the card. A one-off is the start of drift. |

© Diego Fernandes · MIT · diego3g/craft

Similar skills

All skills for Design →

From the same set9

using-craft The using-craft Claude Code skill routes interface design work to the right Craft skill. For a new page, it checks whether the project root contains DESIGN.md. CX Codex +1 ★ 393repo stars craft-explore The craft-explore Claude Code skill creates alternative designs for a screen, flow, or interface element. It activates when someone asks for options or rejects the current design. CX Codex +1 ★ 393repo stars craft-states The craft-states Claude Code skill maps the states a screen, flow, or component needs. It runs during design or redesign and before a screen is handed to development. CX Codex +1 ★ 393repo stars craft-critique The craft-critique Claude Code skill reviews a rendered screen and can apply focused design fixes. It activates for critique or polish requests, before a screen is shown, or before a design goes to code. CX Codex +1 ★ 393repo stars craft-setup craft-setup — a skill for Claude Code that gathers product design decisions and records them in DESIGN.md. It starts before a design task when the project root has no brief yet. CX Codex +1 ★ 393repo stars craft The craft Claude Code skill designs and revises pages, screens, flows, and UI elements. It checks project context, maps states, and reviews each board before presenting it. CX Codex +1 ★ 393repo stars craft-sync The craft-sync Claude Code skill moves design tokens and selected components between a codebase and a design tool. It activates before a design task or when asked to import a system or sync guide changes back to code. CX Codex +1 ★ 393repo stars craft This Claude Code plugin routes interface design requests to skills for screen states, design exploration and review. Ask for a new or revised UI, and craft selects a workflow. ★ 393repo stars

Project sponsors

Companies that keep this analytics open