design-system-builder
Skill2 starsChanged 11 days agoMITView on GitHub
Use whenever shared design decisions are being created, cleaned up or extended, in any language and at any length - "create a design system", "our tokens are a mess", "the same button looks different on every page", "add dark mode or a second brand", "design and code have drifted", "should this join the system", "naming for colors and spacing". Covers design tokens, type, spacing, color roles, radii, elevation, motion and layout values, themes, components and their states, documentation, change rules, in CSS, JSON or specs. Not for styling one page (the focused skills), drawing a brand (brand-identity), or auditing a product without building (design-critique).
8 other projects use a version of this.
Adopted by
Most recently taken up by
- yesith0106/Skillstheir own version, first seen Nov 1, 2026
- zebbern/claude-code-guidetheir own version, first seen Oct 30, 2026
- mattiazi/skillstheir own version, first seen Oct 20, 2026
- signerlabs/design-system-builder-skillstheir own version, first seen Oct 20, 2026
- Geruyang/skillstheir own version, first seen Oct 15, 2026
- gnegreiros-ux/agentica-design-systemtheir own version, first seen Oct 13, 2026
Other versions8 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 8
- zebbern/claude-code-guide★ 4.7ksame name
- signerlabs/design-system-builder-skills★ 8same name
- Uwayxt/agent-skills★ 4same name
- Geruyang/skills★ 2same name
- gnegreiros-ux/agentica-design-system★ 2same name
- yesith0106/Skills★ 2same name
- mattiazi/skills★ 1same name
- novatic-cu/nova-skills★ 1same name
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 repository25 other files it gives its agents.
- agent-interface-designSkill
- brand-identitySkill
- chart-designSkill
- color-paletteSkill
- data-tablesSkill
- design-critiqueSkill
- form-designSkill
- generated-ui-restyleSkill
- interface-behaviorSkill
- journey-and-service-mappingSkill
- layout-structureSkill
- practice-and-assessmentSkill
- presentation-designSkill
- pricing-and-packagingSkill
- responsive-layoutSkill
- sales-conversationsSkill
- showing-workSkill
- spacing-and-groupingSkill
- teaching-interfacesSkill
- typeface-selectionSkill
- typesettingSkill
- ui-motionSkill
- ui-polish-passSkill
- user-research-basicsSkill
- visual-hierarchySkill
The file
We split this skill into the rules it gives an agent
1 rule. 0 are common, 1 is distinctive, and 0 are very specific to this project.
0
Common
Most of the 7 edited versions we read keep these.
1
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 55
Every value in use maps to a token, or is a marked exception.
“Common” is measured: kept by at least 6 in 10 of the 7 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 builder
A system is a small set of decisions made once and reused: values, names, components, rules for change. Unguided, it dumps every value from a mockup into tokens (dozens of near-identical grays, spacing in one-pixel steps), names tokens by color or page, gives every property its own token, builds dark mode by inverting, documents only the default state, names components after where they first appeared, and lets design files and code drift apart.
When to use
- Starting a system, extracting one from existing screens, or adding tokens, a component, a theme, a density or a brand to one.
- Cleaning a token file or component set, deciding whether a pattern joins the system, naming things, writing the guide or the change process.
- A short request ("what should our spacing tokens be?") gets the same rules at sketch size.
When not to use
- One page or screen: use the focused skills (typesetting, color-palette, spacing-and-grouping, layout-structure) if installed and do not build a system around it. A weekend flyer needs a page, not tokens.
- An established system already exists (an open-source kit, the company's own): theme and extend it; add a token or component only for a real gap and say how overrides are governed. Rebuilding needs a stated reason.
- Creating the brand itself: brand-identity if installed. Auditing without building: design-critique if installed. Build tooling beyond token formats: out of scope.
Rules that change the output
- Inventory before inventing. List what exists with counts (colors, sizes, spacings, radii, component variants) grouped by purpose. Near-duplicates are the first finding: three grays one step apart are an unresolved conflict, not a palette. Count content types and templates, not pages. With nothing to inventory, start from the product's real screens or ask for them; do not make up an inventory.
- Short scales, chosen by constraint. Fix each scale in advance (spacing, type, radius, shadow, border, opacity, duration); neighbors at least about a quarter apart, closer at the small end, wider at the large end. A new value replaces or merges with one; it is not added. Choose by comparing with each neighbor, not by calculating. Typical sizes: type 4 to 6 roles, spacing 8 to 10 steps, radii 2 to 4, elevations 2 to 4, motion three or four durations, three easings. These are the same thresholds the focused skills use; take the craft from them.
- Three tiers, no more by default. Raw values (ramps, scales) feed semantic roles (
text-secondary,surface-raised,border-subtle,accent,danger,space-inset-md); components read semantic roles. Add a component-level token only when that component needs an independent knob; one-off values stay local and marked as exceptions. Mechanics in token architecture. - Name by role and structure.
color.text.secondary, notgray-600in components and neverhomepage-hero-blue. Components are named for what they are (media-card), not where they live or what they show. Two things that look alike but behave differently (a navigation disclosure and a command menu) are two components; two that behave alike share one. - Themes remap semantics. Light, dark, high contrast and brands swap what each role points to; raw values are never inverted. Dark surfaces get lighter as they rise, accents are re-tuned for the ground, and every text and component pair is checked in every theme. Honor the system color-scheme setting, allow an override, and test forced-colors.
- Promote on second real use. A pattern enters the system when a second team or screen needs it; generalize its interface by structure, document it, and check it is not a copy of an existing component's behavior. No speculative components because "systems have a carousel". Admission to a shared catalog, merging copies, contribution and measures: extraction, naming and adoption.
- Components are built from tokens and finished. Variants follow behavior. Design every state that can occur (default, hover, focus, pressed, selected, disabled, loading, error, empty), plus names, keyboard, focus, target size, and edge content (long labels, translation, empty values). A spec with only a default state is half a spec. Template in components and governance.
- Expressive outside, calm inside. A brand's personality lives in neutrals, type and a few accents; transactional screens keep conventional, predictable patterns. Separate content from design the same way for charts: palette, text sizes and grid weight are tokens, the data mapping is not.
- One source. Tokens and components are defined once and consumed by design files and code (a token file exported to both). Any divergence is a defect with an owner, not a note.
- Govern in proportion. Four change types (add, modify, deprecate, remove), named owners, a changelog, deprecation announced before removal with a migration, someone allowed to say no. A guide states principles with reasons and shows misuse; it enables more than it polices. A one-squad system needs a page, not a committee.
Missing facts
If the product, platform, brand colors, existing tokens or team size are not given, assume a web product with one brand and a small team, say so in one line, and deliver. Ask once, with a default, only when interactive and the answer changes the structure (an existing system, native platforms, many brands). Never invent the user's current tokens, usage counts, adoption figures, owners or components; when a count is needed, mark it [count from your repo] and continue. Hex values you propose are proposals; say they are checked for contrast only if you checked them.
Do not produce
- A palette of one-step-apart grays or a spacing scale in 1px steps; twelve type sizes.
- Components referencing raw ramps (
blue-500) or tokens named by page, color or mood. - A token for every property of every component; a speculative component library.
- Dark mode as inverted values, or a theme that was never contrast-checked.
- A button, input or card documented only in its default state.
- A rebuild of an established system the team already uses.
- Invented inventories, metrics ("saves 40% of design time"), adoption numbers, owners or review dates.
Output discipline
Deliver the requested artifact first: the token set, the naming table, the spec, the verdict, the cleanup plan, with no history of design systems and no preamble. When a count or set is asked for, deliver exactly that (three durations, four roles) and verify it. Honor any word cap by dropping the lowest-value point, and count rather than assert. A cleanup names the merge map (old value to new token) and the migration order. After the work, at most two one-line notes (an assumption, the one trade-off), unless more is asked.
Quick checks
- Every value in use maps to a token, or is a marked exception.
- Scale counts are within the ranges above and no two neighbors are close enough to confuse.
- Components read semantic roles; names say what and why, not where or what color.
- Each theme remaps roles; text pairs pass in each.
- Each component lists its states and edge content.
- One source, an owner, and a way to deprecate are named.
- Copies or forks of system parts are listed with a way to reconnect them, and a part invented for a screen stays a named local component.
References
- references/token-architecture.md: load when writing or cleaning a token set; tiers, naming grammar, CSS and JSON formats, theme mechanics, a cleanup method.
- references/components-and-governance.md: load when specifying a component, writing the guide, or setting up change rules and rollout.
- references/extraction-naming-and-adoption.md: load when growing a system from existing screens, merging copies of a part, naming tokens or parts, deciding admission or who contributes, or choosing measures and how to present it.
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.

