/design-system

name: design-system
description: Create, update, or refresh a visual design system or art style guide. Use when the user wants to define a visual style, create a design system, build a style guide, or when they mention "design system", "art style", "style guide", "visual identity", or "color palette".

Design System Generator

Create complete visual design systems from scratch through guided discovery, documentation, and AI-generated asset production.

Workflow Overview

Execute these phases in strict order. Output Location must be asked first. Phase 0 is optional (skip if user has no references). Never skip Phases 1-5. Each phase builds on the previous.

| Phase | Name | Action | Output | |-------|------|--------|--------| | — | Output Location | Ask where to save the design system | `output_location` = "local" or "user" | | 0 | Reference Input | Collect + analyze user reference images | Visual analysis + smart defaults for discovery | | 1 | Discovery | Interactive questionnaire | User preferences across 10 dimensions | | 2 | Synthesis | Analyze + name the style | Style name, core principles, full spec | | 3 | Documentation | Generate style guide | `{style-name}-design-system.md` | | 4 | Asset Generation | Generate images via creator-stack:nanobanana | 8 PNG style board elements | | 5 | Assembly | Organize + present | Complete design system directory |

---

Output Location

Before anything else, ask the user where they want the design system saved. Use the AskUserQuestion tool:

**Question:** "Where should this design system be saved?"

| Option | Description | |--------|-------------| | Local project (current directory) | Saves to `./design-system/` in the current working directory. Best when this design system is specific to one project. | | User level (system-wide) | Saves to `~/.claude/.context/design-systems/{style-name-slug}/`. Available across all projects and conversations. Best for brand-wide design systems you'll reuse everywhere (e.g., your YouTube brand, your newsletter brand). |

Store the choice as `output_location`.

**Path resolution** (happens after Phase 2 when the style name is finalized):

• **Local:** `{output_dir}` = `./design-system/`
• **User level:** `{output_dir}` = `~/.claude/.context/design-systems/{style-name-slug}/`

Where `{style-name-slug}` is the style name lowercased with spaces and special characters replaced by hyphens (e.g., "Ink & Ember" → `ink-and-ember`, "Neon Chalk" → `neon-chalk`).

**User-level design systems** are organized so each style gets its own directory:

~/.claude/.context/design-systems/
├── ink-and-ember/          ← YouTube brand
│   ├── ink-and-ember-design-system.md
│   ├── 01-hero-character.png
│   └── ...
├── paper-and-sage/         ← Newsletter brand
│   ├── paper-and-sage-design-system.md
│   ├── 01-hero-character.png
│   └── ...

---

Phase 0: Reference Input (Optional)

Before starting discovery, ask the user if they have existing visual references to anchor the design system. References dramatically improve consistency by grounding the system in concrete examples rather than abstract descriptions alone.

**Opening prompt:** "Before we start defining your design system, do you have any existing visual references? These could be brand assets you already use, inspiration images, or examples of styles you like. This is optional — we can build entirely from scratch too."

**Supported input modes:**

| Mode | How to Provide | What Happens | |------|---------------|--------------| | Folder path | User provides a path like `~/brand-assets/` or `./images/` | Read all image files in the folder (PNG, JPG, SVG, WebP). Limit to 10 most relevant if more are provided. | | Individual files | User provides one or more file paths | Read each image directly. | | Website URL | User provides a URL like `https://mybrand.com` | Use WebFetch to capture the page, then analyze the visual design (colors, typography, layout, imagery style). | | Direct paste | User pastes or drags images into the conversation | Analyze the images as provided. | | Skip | User says they have no references | Proceed directly to Phase 1 with no smart defaults. |

**Analysis protocol:**

For each reference image or website, extract and document:

1. **Dominant colors** — Identify the 3-5 most prominent colors with approximate hex codes. Note which appear to be background, primary, and accent. 2. **Line work / rendering style** — Is it illustrated or photographic? If illustrated: line weight (thick/thin), edge quality (clean/sketchy), fill approach (flat/gradient/outline-only). 3. **Composition patterns** — Spacing density, focal point placement, symmetry, use of whitespace. 4. **Medium / aesthetic** — Flat vector, hand-drawn, 3D, photographic, collage, abstract, etc. 5. **Mood / emotional tone** — What feeling does it convey? Warm, corporate, playful, dark, etc. 6. **Character style** (if characters present) — Proportions, facial detail level, body style, identifying features. 7. **What's NOT present** — Notable absences that may indicate intentional anti-patterns (no gradients, no photography, no text, etc.).

**After analysis, present a summary:** > "Here's what I'm seeing across your references: **[2-3 sentence synthesis of the dominant visual patterns — colors, style, mood, composition]**. I'll use this to suggest defaults during the discovery questionnaire, but you can override any suggestion."

**Smart defaults:**

• Store the analysis results as `reference_analysis`
• During Phase 1, for each dimension where the reference analysis provides a clear signal, pre-select the closest matching option and note: *"Based on your references, I'd suggest: **[option]** — [brief reason from analysis]. Does this match your intent?"*
• If the references are ambiguous for a dimension (e.g., mixed styles across images), present all options without a default and note the ambiguity: *"Your references show a mix of [X] and [Y] — which direction do you want to lean