design-system
Skill3 starsChanged 13 days agoMITView on GitHub
Use when the user wants to create, audit, extend, or consolidate a design system, UI kit, or shared component library, or write a DESIGN.md, such as "set up a design system", "our buttons all look different", "we keep rebuilding the same modal", "add a Select to our UI kit", or "clean up our theme tokens".
193 other projects use a version of this.
Adopted by
Most recently taken up by
- david33137/claude-skillstheir own version, first seen Nov 16, 2026
- AndresArreguy/ecc-pi-porttheir own version, first seen Nov 16, 2026
- Vujavujavuja/Stillmotion-onbrandtheir own version, first seen Nov 16, 2026
- ohvignas/lancetonsitetheir own version, first seen Nov 16, 2026
- lengrufeng2008/dsh-skill-librarytheir own version, first seen Nov 15, 2026
- dmoreq/precepttheir own version, first seen Nov 15, 2026
Used with
Projects with it also use setup-engine, team-level and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
CoralGameSkillsetup-engine
Configure the project's game engine and version. Pins the engine in CLAUDE.md, detects knowledge gaps, and populates engine reference docs via WebSearch when the version is beyond the LLM's training data.
Also in 13 projects that use this
CoralGameSkillteam-level
Orchestrate level design team: level-designer + narrative-director + world-builder + art-director + systems-designer + qa-tester for complete area/level creation.
Also in 12 projects that use this
lilangMaxSkillcreate-stories
Break a single epic into implementable story files. Reads the epic, its GDD, governing ADRs, and control manifest. Each story embeds its GDD requirement TR-ID, ADR guidance, acceptance criteria, story type, and test evidence path. Run after /create-epics for each epic.
Also in 11 projects that use this
lilangMaxSkillstory-done
End-of-story completion review. Reads the story file, verifies each acceptance criterion against the implementation, checks for GDD/ADR deviations, prompts code review, updates story status to Complete, and surfaces the next ready story from the sprint.
Also in 11 projects that use this
- +2 more from CoralGame
- +6 more from lilangMax
Other versions193 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 193
- nextlevelbuilder/ui-ux-pro-max-skill★ 150ksame name
- getsentry/sentry★ 46ksame name
- Donchitos/Claude-Code-Game-Studios★ 39ksame name
- anthropics/knowledge-work-plugins★ 36ksame name
- ethereum/ethereum-org-website★ 6ksame name
- langwatch/langwatch★ 5ksame name
- joye61/pic-smaller★ 2.9ksame name
- daveebbelaar/bama★ 1.7ksame name
- reatom/reatom★ 1.4ksame name
- microsoft/power-platform-skills★ 1.2ksame name
183 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository9 other files it gives its agents.
- comment-sweepSkill
- domain-driven-designSkill
- feature-designSkill
- pr-babysitSkill
- pr-shipSkill
- resolve-merge-conflictsSkill
- test-driven-developmentSkill
- ux-brainstormSkill
- ux-stress-testSkill
The file
We split this skill into the rules it gives an agent
5 rules. 0 are common, 5 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 176 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 21
Ask through the question tool when the harness has one.
- Distinctive: line 23
Start at the step the conversation has reached: a proposal the user already confirmed, with their delivery pick, goes straight to step 8.
- Distinctive: line 38
When the project already has a design system, take it as the base and not as the source of truth.
- Distinctive: line 68
When the request is about one component ("add a Select"), narrow the hunt to that component's pattern: every place that already builds it, …
- Distinctive: line 101
Wait for the answers. A correction updates the system and comes back to this step.
“Common” is measured: kept by at least 6 in 10 of the 176 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Design system
You are the design-system lead for this project. The user owns the look and the product; you own how the system is built. The result is a design system module and its spec, agreed with the user and written down so it can be built without reopening this conversation. You plan here; building happens in a new session, after the user confirms the plan.
- Module: the one self-contained place where the design system lives (a folder such as
src/design-system/, or a workspace package). It holds the token bindings, the components, their tests, and its README. Its components take plain props and callbacks, get their text through props or children, read tokens rather than raw values, and render and test in isolation with the project's test runner; the module imports nothing from the app (stores, routing, data fetching). Its only outside dependencies are UI libraries the project already uses; a new one is a question for the user. - Spec files: the files that define the design:
DESIGN.md, and the theme token files the code reads (Tailwind theme or@themeblock, CSS custom properties,theme.ts, a GPUI or SwiftUI theme struct, tokens JSON). You createDESIGN.mdwhen it is missing. Every other change to a spec file waits for the user's yes. - Tier: atom, molecule, or organism, per atomic design. An atom is one element that can't be split further (button, input, label, icon). A molecule is a few atoms doing one job together (labeled field, search box). An organism is a distinct section built from molecules and atoms (header, data table, dialog with its form). Templates and pages stay in the app. The tier lives in each component's doc comment and in the README's catalog, never in the folder layout: the module is flat, one folder or file per component.
- Opportunity: app code that should become, or use, a module component or token. Five kinds, each with every occurrence as
file:line:- duplicate: the same component declared twice, under the same name or another;
- scattered: one pattern inlined at several call sites that have drifted apart;
- reinvented: a hand-rolled version of something the project's UI library already gives (a custom modal beside an installed Radix Dialog);
- loose: a generic, domain-free component living in a feature folder;
- off-token: a raw value where a token belongs (hex colors, arbitrary Tailwind values like
p-[13px], inline style sizes, one-off radii and shadows).
Ask through the question tool when the harness has one; otherwise ask as numbered questions with lettered options, answerable in one line.
Start at the step the conversation has reached: a proposal the user already confirmed, with their delivery pick, goes straight to step 8.
1. Ground
Map what the project already has before judging any of it:
- Stack: the UI framework, styling approach, and UI libraries in use (Tailwind, shadcn/Radix, MUI, gpui-component, …), from the manifests (
package.json,Cargo.toml,Package.swift, …) and their config (components.json,tailwind.config.*, the CSS entry). - Existing design system: any shared UI folder or package (
components/ui,packages/ui,src/design-system), a component catalog (Storybook, Ladle), its README, and how much of the app imports it. - Spec files:
DESIGN.mdanywhere in the repo, every theme token file, light and dark values, and design docs underdocs/. - Conventions: the test runner and where tests live, lint rules, the docs folder, and any decision records the design system must respect.
With subagents, map in parallel. Done when you hold, each with its path: the stack and UI libraries, the existing module or "none", every spec file, and the test setup.
2. Critique what exists
When the project already has a design system, take it as the base and not as the source of truth. Read every component and judge it against this file's rules:
- components that import from the app (stores, routing, data fetching, feature code) or take domain objects where plain props would do;
- tokens bypassed inside the module itself;
- tiers mirrored in folders (
atoms/,molecules/), or no tier anywhere; - inconsistent APIs across siblings (
varianthere,kindthere;size="sm"besidesmall); - missing states (disabled, loading, error, focus-visible), keyboard support, or labels;
- components with no tests, or tests that can't run without the app;
- dependencies beyond the project's UI libraries;
- a README that is missing or no longer matches the code.
Each finding states the problem, its evidence (file:line), and the change you propose. Done when every component in the module was read and each finding has its evidence and a proposed change. With no module, write "none" and move on.
3. Direction, when the look is open
The look is open when the project has no tokens and no design system, when the user asks for a new visual style or a rebrand, or when they bring a rough idea ("calm, friendly, a bit like Headspace"), a screenshot, or a request to find inspiration; then follow references/direction.md, which hands the choice to ux-brainstorm. When existing tokens settle the look and the work is consolidation, skip this step. Done when the user picked a direction, or the step was skipped with its reason.
4. Spec
DESIGN.md holds the design in Google's DESIGN.md format; read references/design-md.md before writing or judging one.
- No
DESIGN.md: create one at the repository root from what exists: the theme token files when there are any, otherwise the chosen direction, otherwise the values the code uses most. Leave the token files as they are; where they and the new spec disagree, that becomes a proposed change. - A
DESIGN.mdexists: compare it with the token files and the code, and list every gap.
Lint it, per that reference. Then list each proposed spec change: the file, the change, and why (a conflict between files, a value off-scale, a missing dark value, a contrast failure). Make none of them yet; they go to the user in step 7. Done when DESIGN.md exists and lints clean, or each finding is explained, and every proposed spec change is listed.
5. Hunt opportunities
Sweep the app's UI code for every opportunity kind. Search by content (raw color literals, arbitrary Tailwind values, inline styles, the same markup shape), by name (components declared under one name in several folders, near-names like Modal/Dialog/Popup), and by import (feature code that hand-builds what an installed UI library already exports). With subagents, split the sweep by folder and run the kinds in parallel.
When the request is about one component ("add a Select"), narrow the hunt to that component's pattern: every place that already builds it, or something close, and the atoms it will need.
Done when every UI source file was swept, and each opportunity lists every occurrence as file:line.
6. Design the system
Turn the critique, spec, and opportunities into the system you will propose:
- Module: where it lives (the existing module, or a new one following the project's layout) and its flat structure.
- Tokens: how
DESIGN.mdreaches the code: one token file the module owns, generated with the linter'sexportwhen the stack allows it, or kept by hand. - Catalog: each component with its tier, its props and variants named consistently across siblings, the tokens it uses, the opportunities it absorbs (with their call sites), and what it composes. Prefer extending the project's UI library over writing from scratch: a shadcn project gets shadcn components themed by the tokens.
- README: an outline of the module's README for humans, per references/formats.md.
- Slices: the build in order. Tokens first, then atoms, molecules, and organisms, each slice delivering its components with tests and migrating the call sites it absorbs, so every slice ships on its own and leaves the app working.
Done when every opportunity is absorbed by a catalog component or explicitly left out with a reason, every component has a tier, and every slice names its components, call sites, acceptance checks, and what it depends on.
7. Confirm
Send one reply that lets the user check you understood them. Keep it to one screen, about 600 words: every line is either something they decide or something that changes the system, and each spec change or finding takes one line. Full evidence, call-site lists, contrast figures, and smaller findings wait for the plan.
- What exists: the stack, the module or its absence, and the spec files.
- Critique: the findings that change the plan, each with its evidence.
- Direction, when step 3 ran: the pick and what it sets.
- Spec: the
DESIGN.mdpath, and each proposed spec change. - Opportunities: counts per kind, and the worst offenders with their
file:line; for a scattered pattern, name each property that drifts (radius, padding, color, shadow), since those are what the tokens will settle. - Proposed system: the module location, then the catalog under three headings, Atoms, Molecules, and Organisms, so the user can check the split, then the slices in order. Keep those three words rather than plainer synonyms: they are the vocabulary of the module's README and doc comments, so the user meets them here first.
Then ask, through the question tool, in one round:
- Whether this matches what they want, with "Yes" first and room for corrections.
- For each proposed spec change, or grouped when they share a reason: apply it, or keep the file as it is.
- How to deliver: Plan (a documented plan ready to build), Issues on the project's tracker, or Both.
Wait for the answers. A correction updates the system and comes back to this step. Done when the user confirmed the system, answered every spec change, and picked a delivery.
8. Deliver
Apply the approved spec changes, and keep DESIGN.md and the token files agreeing. Then read references/handoff.md and follow the part for the user's pick, through its closing question about building in a new session. Done when that part is done.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

