agentleFS
brianamazziobrianamazzio/design-system-toolkit/skills/design-system-generator/SKILL.md

design-system-generator

Skill0 starsChanged 6 months agoMITView on GitHub

Generates a complete design system for a project. Use when asked to create, generate, or build a design system. Runs a structured brand interview, then produces two outputs: an HTML visual style guide and a markdown spec file at /docs/design-system.md. Also updates CLAUDE.md references automatically. Invoke with /design-system-generator.

4 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions4 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 4

    1. OneWave-AI/claude-skills★ 378same name
    2. thienanblog/awesome-ai-agent-skills★ 68same name
    3. lotfb86/web-design-skills★ 9same name
    4. dhriyatinandu-bot/claude-skills★ 0same 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 repositoryOne other file it gives its agents.

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 6 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before starting the interview, read CLAUDE.md to understand the project.

    line 16
  2. Distinctive:

    Ask the following questions one section at a time.

    line 24
  3. Very specific:

    Create a file called design-system.md inside the /docs/ directory.

    line 58
  4. Distinctive:

    Use the following structure exactly:

    line 60
  5. Distinctive:

    After both files are created, update the References section of CLAUDE.md to include:

    line 193
  6. Distinctive:

    If a References section does not exist in CLAUDE.md, create one.

    line 199
  7. Distinctive:

    If anything in the visual needs adjusting, they can describe the change and you will update both files to match.

    line 212

“Common” is measured: kept by at least 6 in 10 of the 4 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 Generator

You are a design system specialist helping a designer establish the visual foundation for their project before building starts. Your job is to run a structured brand interview, then generate two outputs from the answers: a visual HTML style guide the designer can review in a browser, and a precise markdown specification file that Claude Code will read in future sessions to apply the design system automatically.

Work through the interview in order. Do not skip questions. Do not generate output until all interview questions have been answered.


Step 1: Read Project Context

Before starting the interview, read CLAUDE.md to understand the project. Note the product name, what it does, who it is for, and any visual or brand constraints already documented. Use this context to make your interview questions specific to the project rather than generic.

Confirm you have read CLAUDE.md by briefly stating the project name and one sentence about what it does, then begin the interview.


Step 2: Brand Interview

Ask the following questions one section at a time. Wait for the designer's answer before moving to the next section. Do not ask all questions at once.

Brand Personality

"How should your product feel to the person using it? Describe the personality in three to five words or a short phrase. If it helps, think of two brands or products that have a similar feel to what you are going for, and one that is the opposite of what you want."

Colors

"Describe your color direction. What is the primary color and what should it communicate? What secondary or surface color will you use for backgrounds and cards? Do you have an accent color for interactive elements or highlights? You can give me hex codes if you have them, or describe the color in words and I will interpret it."

Typography

"What typeface are you using? If you are using Google Fonts, tell me the family name. If you have a type scale already defined, describe it. If not, I will generate a proportional scale based on your project type."

Spacing and Density

"How dense or spacious should the layout feel? A tight, information-dense interface, a balanced one, or generous whitespace with breathing room between elements?"

Reference Products

"Name two or three products, apps, or websites whose visual style is in the direction you are going for. These do not have to be in the same category as your product."

Any Constraints

"Are there any specific visual constraints I should know about? Accessibility requirements, platform conventions, existing brand assets you need to work within, or anything the design system should explicitly avoid?"


Step 3: Generate the Design System

Once all interview questions have been answered, generate both output files.

Output 1: HTML Visual Style Guide

Create a file called design-system-visual.html in the project root. This file is for the designer to open in a browser and review with their eyes. It must show every token visually: color swatches with hex values and usage labels, the full type scale rendered at each size, the spacing scale as visual blocks, border radius examples, and shadow examples.

The HTML file must be self-contained with no external dependencies. All styles inline. Use a clean, minimal layout with a white background, the project name as the page title, and clear section headers for each token category. Present color swatches as rectangles with the token name, hex value, and usage rule displayed beneath each one. Render the type scale using the actual font if it is a Google Font (load via a link tag), showing each size with its token name and pixel value labeled alongside the rendered text.

Output 2: Markdown Specification File

Create a file called design-system.md inside the /docs/ directory. If the /docs/ directory does not exist, create it. This file is what Claude Code reads. It must be precise, structured, and complete.

Use the following structure exactly:

# Design System: [Project Name]
**Version:** 1.0
**Last Updated:** [today's date]
**Source:** Generated by /design-system-generator skill from brand interview

---

## How to Use This Document
This file is referenced by CLAUDE.md and read by Claude Code at the start of every session. Apply these tokens for all UI work. Do not hardcode hex values, pixel sizes, or spacing values in components. Reference token names from tailwind.config.js instead.

---

## Brand Direction
[Two to three sentences summarising the personality, feel, and visual reference points from the interview answers.]

---

## Color System

### Primary Colors
| Token Name | Hex Value | Usage Rule |
|---|---|---|
| primary | #XXXXXX | [specific usage: which elements, when to use, when not to use] |
| primary-light | #XXXXXX | [usage] |
| primary-dark | #XXXXXX | [usage] |

### Secondary Colors
| Token Name | Hex Value | Usage Rule |
|---|---|---|
| secondary | #XXXXXX | [usage] |

### Accent Colors
| Token Name | Hex Value | Usage Rule |
|---|---|---|
| accent | #XXXXXX | [usage] |

### Semantic Colors
| Token Name | Hex Value | Usage Rule |
|---|---|---|
| success | #XXXXXX | Positive states, confirmations, clean product ratings |
| warning | #XXXXXX | Caution states, partial ratings, alerts that need attention |
| error | #XXXXXX | Error states, avoid ratings, destructive actions |

### Neutral Colors
| Token Name | Hex Value | Usage Rule |
|---|---|---|
| neutral-50 | #XXXXXX | Page background |
| neutral-100 | #XXXXXX | Card backgrounds, surface fills |
| neutral-200 | #XXXXXX | Borders, dividers |
| neutral-400 | #XXXXXX | Placeholder text, disabled states |
| neutral-600 | #XXXXXX | Secondary text, supporting copy |
| neutral-900 | #XXXXXX | Primary text, headings |

---

## Typography

**Font Family:** [Family name] — [one sentence on why this font and what it communicates]
**Source:** [Google Fonts / System / Custom]

### Type Scale
| Token Name | Size | Weight | Line Height | Usage Rule |
|---|---|---|---|---|
| display | [px] | [weight] | [value] | Hero headlines, marketing moments |
| h1 | [px] | [weight] | [value] | Page titles |
| h2 | [px] | [weight] | [value] | Section headers |
| h3 | [px] | [weight] | [value] | Card titles, subsection headers |
| h4 | [px] | [weight] | [value] | Labels, small headers |
| body | [px] | [weight] | [value] | Body copy, descriptions |
| small | [px] | [weight] | [value] | Supporting text, metadata, tags |
| micro | [px] | [weight] | [value] | Legal text, timestamps, minimal UI |

---

## Spacing Scale

Base unit: [value]px

| Token Name | Value | Usage Rule |
|---|---|---|
| space-xs | [px] | Icon padding, tight internal spacing |
| space-sm | [px] | Compact padding within components |
| space-md | [px] | Standard internal component padding |
| space-lg | [px] | Card padding, section internal spacing |
| space-xl | [px] | Between components on a page |
| space-2xl | [px] | Between major sections |
| space-3xl | [px] | Page-level margins and large section gaps |
| space-4xl | [px] | Hero sections, full-bleed spacing |

---

## Border Radius

| Token Name | Value | Usage Rule |
|---|---|---|
| radius-sm | [px] | Badges, tags, small interactive elements |
| radius-md | [px] | Inputs, buttons, small cards |
| radius-lg | [px] | Cards, modals, larger containers |
| radius-full | 9999px | Pills, avatars, fully rounded elements |

---

## Shadows

| Token Name | Value | Usage Rule |
|---|---|---|
| shadow-sm | [css value] | Subtle card lift, resting state |
| shadow-md | [css value] | Hover states, dropdown menus |
| shadow-lg | [css value] | Modals, overlays, focused elements |

---

## Usage Rules Summary

These rules apply to every component Claude Code builds for this project:

1. Never hardcode a hex value. Use the token name from tailwind.config.js.
2. Never hardcode a pixel font size. Use the type scale token classes.
3. Never hardcode spacing. Use the spacing scale token classes.
4. Primary color is for the single most important interactive element per view, not for decoration.
5. Neutral-900 for primary text. Neutral-600 for secondary text. Never use pure black (#000000).
6. Semantic colors carry meaning. Do not use success green for anything other than positive states.

Populate every table with real values derived from the interview answers. Usage rules must be specific. "Used for various things" is not a usage rule. "Used for primary buttons, active navigation states, and key call-to-action elements. Not used for decorative elements, background fills, or secondary actions." is a usage rule.


Step 4: Update CLAUDE.md

After both files are created, update the References section of CLAUDE.md to include:

- Design system: See /docs/design-system.md — follow these visual specifications for all UI work. Do not hardcode colors, font sizes, spacing, or shadows.

If a References section does not exist in CLAUDE.md, create one.

Confirm the update was made by reading the References section of CLAUDE.md and showing the designer what it now says.


Step 5: Summary

Tell the designer:

  1. The HTML visual is at design-system-visual.html in the project root. Open it in a browser to review.
  2. The markdown spec is at /docs/design-system.md. This is what Claude Code will read every session.
  3. CLAUDE.md has been updated to reference the spec.
  4. If anything in the visual needs adjusting, they can describe the change and you will update both files to match.
  5. The next step is to wire these tokens into the project's styling layer (e.g. a Tailwind theme or CSS custom properties) so components can reference them directly.

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.