agentleFS
mastro993mastro993/fstack/skills/design-system/SKILL.md

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

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.
  • CoralGameSkill

    setup-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

  • CoralGameSkill

    team-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

  • lilangMaxSkill

    create-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

  • lilangMaxSkill

    story-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

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
  1. Distinctive:

    Ask through the question tool when the harness has one.

    line 21
  2. Distinctive:

    Start at the step the conversation has reached: a proposal the user already confirmed, with their delivery pick, goes straight to step 8.

    line 23
  3. Distinctive:

    When the project already has a design system, take it as the base and not as the source of truth.

    line 38
  4. Distinctive:

    When the request is about one component ("add a Select"), narrow the hunt to that component's pattern: every place that already builds it, …

    line 68
  5. Distinctive:

    Wait for the answers. A correction updates the system and comes back to this step.

    line 101

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 @theme block, CSS custom properties, theme.ts, a GPUI or SwiftUI theme struct, tokens JSON). You create DESIGN.md when 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.md anywhere in the repo, every theme token file, light and dark values, and design docs under docs/.
  • 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 (variant here, kind there; size="sm" beside small);
  • 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.md exists: 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.md reaches the code: one token file the module owns, generated with the linter's export when 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.md path, 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:

  1. Whether this matches what they want, with "Yes" first and room for corrections.
  2. For each proposed spec change, or grouped when they share a reason: apply it, or keep the file as it is.
  3. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.