# Design Farmer > Automated design system construction from repository analysis to production-ready implementation. Analyzes codebases, extracts design patterns, builds token hierarchies with OKLCH color management, implements accessible components with tests, and verifies through multi-reviewer panels. Use when: "build design system", "design tokens", "component library", "design-farmer" - Skill: `hakilee/design-farmer` (Agent Skill, multi-file: 27 files) - Install (CLI): `npx skillmds@latest add hakilee/design-farmer` - Raw SKILL.md: https://api.skillmd.com/api/skills/hakilee/design-farmer/raw - Safety review: pending (external: skill-scanner WARNING, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Design & Media - Author: hakilee (https://skillmd.com/u/hakilee) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/hakilee/design-farmer --- # Design Farmer > From seed to system — cultivate a production-ready design system from any codebase. Design Farmer analyzes your repository, extracts existing design patterns, and grows them into a structured, accessible, OKLCH-native design system with tokens, components, tests, and documentation. --- ## Version Check Before doing anything else, run the version check silently: ```bash _DF_UPDATE=$(bash ~/.claude/skills/design-farmer/bin/version-check 2>/dev/null || true) ``` If `_DF_UPDATE` starts with `UPGRADE_AVAILABLE`: 1. Parse the output: `UPGRADE_AVAILABLE ` 2. Ask the user via AskUserQuestion: ``` Design Farmer **v{latest}** is available (you're on v{current}). Options: - A) Update now — run the installer, then restart - B) Continue with current version - C) Skip — don't ask again this session ``` - If **A**: output the install command below and stop. The user must re-invoke after updating. ```bash curl -fsSL https://raw.githubusercontent.com/ohprettyhak/design-farmer/main/install.sh | bash ``` - If **B** or **C**: continue to the next section. If the script is missing, fails, or times out, continue silently — never block on a version check failure. --- ## Bundle Integrity Gate This skill is distributed as a **bundle**: the router `SKILL.md`, phase files under `phases/`, and companion docs under `docs/` must all be present. Before starting work, Read `phases/operational-notes.md` to verify the bundle is accessible. Before each phase, Read the corresponding phase file using the **Read** tool with its full path (e.g., `Read("~/.claude/skills/design-farmer/phases/phase-0-preflight.md")`). If the Read call fails (file not found), the bundle is incomplete — STOP immediately and report: ``` Status: BLOCKED Reason: Incomplete Design Farmer bundle — required file missing: {path} AskUserQuestion: "The installed Design Farmer skill bundle is incomplete (`{path}` is missing). Please reinstall or provide the missing file before I continue." ``` **Important**: Do NOT use Glob or Search tools with patterns like `phases/*.md` to verify phase files — these patterns may return zero results due to tool-specific path resolution behavior. Always use Read with the exact file path. Do NOT guess missing phase behavior from memory. --- ## Phase Architecture This skill is decomposed into specialized phase files under `phases/`. Load only the file for the current phase plus any explicitly referenced companion file. | Phase | File | Purpose | |-------|------|---------| | 0 | `phases/phase-0-preflight.md` | Detect project topology, frameworks, package manager, and existing design artifacts | | 1 | `phases/phase-1-discovery.md` | Run the one-question-at-a-time discovery interview and build `DesignFarmerConfig` | | 2 | `phases/phase-2-repo-analysis.md` | Assess design maturity, inventory components, and extract repository patterns | | 3 | `phases/phase-3-pattern-extraction.md` | Normalize color/typography/spacing patterns into token-ready design primitives | | 3.5 | `phases/phase-3.5-visual-preview.md` | Generate and review a design preview before implementation begins | | 4 | `phases/phase-4-architecture.md` | Define token hierarchy, directory structure, build pipeline, and CSS layering | | 4b | `phases/phase-4b-theming.md` | Define theme system, provider implementation, dark mode, and styling approach | | 4.5 | `phases/phase-4.5-design-source-of-truth.md` | Generate and maintain `DESIGN.md` as the persistent design reference | | 5 | `phases/phase-5-tokens.md` | Implement primitive/semantic/component tokens and token tests | | 6 | `phases/phase-6-components.md` | Implement components in dependency order | | 7 | `phases/phase-7-storybook.md` | Set up Storybook and visual documentation when the user wants it | | 8 | `phases/phase-8-review.md` | Run multi-reviewer verification and aggregate risk | | 8.5 | `phases/phase-8.5-design-review.md` | Run rendered visual QA with browser tooling or manual fallback | | 9 | `phases/phase-9-documentation.md` | Generate docs, final verification output, and completion report | | 10 | `phases/phase-10-integration.md` | Integrate the design system into the application when requested | | 11 | `phases/phase-11-readiness-handoff.md` | Produce release-readiness verification and handoff output | ### Reference Files | File | Purpose | |------|---------| | `phases/operational-notes.md` | Delegation strategy, escalation rules, OKLCH reference, forbidden patterns | | `docs/PHASE-INDEX.md` | Concise phase responsibilities and handoff map | | `docs/QUALITY-GATES.md` | Structural and behavioral quality gates for maintainers | | `docs/MAINTENANCE.md` | Update workflow, anti-drift checks, and contribution checklist | | `docs/EXAMPLES-GALLERY.md` | Example outcomes and reference scenarios | | `examples/DESIGN.md` | Fully filled-in DESIGN.md example (Nova UI) for greenfield reference | --- ## AskUserQuestion Tool Usage — MANDATORY **CRITICAL: When a phase file says "Via AskUserQuestion, ask:" or "ask via AskUserQuestion:", you MUST call the `AskUserQuestion` tool. Do NOT output the question as regular text or markdown. The blockquoted text following the instruction is the CONTENT for the tool call, not text to display.** Every `AskUserQuestion` call must: 1. Use the `AskUserQuestion` tool with structured `questions`, `header`, and `options` parameters. 2. Wait for the tool to return the user's response before taking any further action. 3. Never proceed past a `→ STOP` marker until the user's response has been received from the tool. If you output question text without calling the tool, the user cannot respond and the pipeline breaks. --- ## Voice & Tone - Speak like a senior design engineer pairing with the user — direct, specific, opinionated with reasoning. - Name the file, the token, the component. Never speak in abstractions when a concrete path exists. - One decision per question. Never batch multiple choices into a single prompt. - Recommend the complete option. With AI assistance, thoroughness costs seconds more than shortcuts. - When uncertain about the user's intent, ask. When certain, act and explain. --- ## Completion Status Protocol Every phase concludes with one of: - **DONE** — Phase complete with evidence (files created, tests passing, screenshots captured). - **DONE_WITH_CONCERNS** — Phase complete but issues flagged for user awareness. - **BLOCKED** — Cannot proceed. State what is missing and what would unblock. - **NEEDS_CONTEXT** — Missing information that only the user can provide. Ask one question. --- ## Fallback & Degradation Protocol Every phase that delegates to an Agent or uses an external tool MUST define a fallback path. The pipeline NEVER silently fails. Compatibility note: some runtimes represent delegation explicitly as `Agent(prompt="...")`. ### Degradation Pattern ``` Try primary path: If success → continue to next phase If failure (timeout, token limit, tool unavailable): Log: "[DEGRADATION] Phase {N}: {primary} failed ({reason}). Using {fallback}." Execute fallback path If fallback succeeds → continue with DONE_WITH_CONCERNS If fallback also fails: Escalate to user with BLOCKED status AskUserQuestion: "Both primary and fallback failed for {phase}. Error: {error}. How to proceed?" ``` ### Fallback Registry | Phase | Primary Path | Fallback Path | |-------|-------------|---------------| | Phase 2 (Analysis) | Structured repository analysis pass (specialized delegation preferred) | Direct Grep/Glob scanning with reduced depth | | Phase 3 (Extraction) | Specialized analysis pass | Manual OKLCH extraction via inline math | | Phase 3.5 (Visual Preview) | Generated preview HTML | Text-only preview summary and user approval gate | | Phase 4.5 (DESIGN.md) | Structured design-document drafting | Write `DESIGN.md` directly with the documented template | | Phase 5 (Tokens) | Specialized implementation pass | Implement tokens directly with Edit/Write | | Phase 6 (Components) | Specialized implementation pass | Implement components directly with Edit/Write, one at a time | | Phase 7 (Storybook) | `storybook init` via the detected package manager | Manual `.storybook` config + story file generation | | Phase 8 (Review) | 5 specialized reviewer passes (parallel when supported) | Sequential review with combined criteria | | Phase 8.5 (Visual QA) | Headless browser screenshots | Manual verification prompt with user-provided screenshots | | Phase 9 (Docs) | Structured documentation drafting | Write docs directly with Write tool | | Phase 10 (Integration) | Structured application changes | Guided step-by-step instructions for manual execution | | Phase 11 (Readiness) | Automated verification + readiness handoff | Manual readiness report with explicit failed-gate summary | --- ## Execution Flow Execute phases sequentially. Before starting each phase: 1. Read `phases/operational-notes.md` once per run if you have not already loaded it. 2. Read the corresponding phase file. 3. Follow the instructions in that file exactly. 4. Conclude the phase with a completion status. 5. Proceed only when that phase’s gates allow it. ### Phase Sequence ``` Phase 0: Pre-flight | Phase 1: Discovery Interview | Phase 2: Repository Analysis | Phase 3: Design Pattern Extraction & OKLCH Conversion | Phase 3.5: Visual Preview | Phase 4: Architecture Design | Phase 4b: Theme & Styling | Phase 4.5: Design Source of Truth (DESIGN.md) | Phase 5: Token Implementation | Phase 6: Component Implementation | Phase 7: Storybook Integration (optional — user chooses) | Phase 8: Multi-Reviewer Verification | Phase 8.5: Design Review (Live Visual QA) (if browser tooling or screenshots are available) | Phase 9: Documentation & Completion | Phase 10: App Integration (optional — user chooses) | Phase 11: Release Readiness & Handoff ``` ### Cross-Phase Contracts - **DesignFarmerConfig** (from Phase 1) is passed to all subsequent phases. Persisted to `{systemPath}/.design-farmer/config.json` for context-window resilience. - **Pipeline state tracking**: Completed and degraded phases append their IDs to `completedPhases` in config.json. User-optional skipped phases record dedicated skip state instead and do not append. `createdAt` is set once in Phase 1. Phase 8 writes `lastReviewScore` (0–10) and `lastReviewDate`. Phase 0 displays this state during re-entry. - **Design Maturity** (from Phase 2) is written to `DesignFarmerConfig.designMaturity` and determines the implementation path in Phases 3, 3.5, 5, and 6. Phase 0 re-entry may set a preliminary `designMaturity` from user input; Phase 2's formal assessment overrides this value. - **Existing DESIGN.md** detected in Phase 0 triggers a re-entry prompt — importing it as context continues to Phase 1 with pre-filled defaults. Critical discovery gates (scope/headless/theme decisions) must still be explicitly confirmed. - **DESIGN.md source classification**: Phase 0 distinguishes `internal-canonical` vs `external-context`. Readable third-party docs are context (not corruption); only unreadable files are treated as corrupted. - **Early DESIGN.md draft** (from Phase 3) captures extraction results to bridge the Phase 3→4.5 context gap. Phase 4.5 merges this draft into the final version. - **Phase 3.5 is a hard gate** before Phase 4. Preview HTML (`{systemPath}/.design-farmer/design-preview.html`) is mandatory for GREENFIELD, opt-in for EMERGING/MATURE. When skipped, the opt-in gate (3.5.0) handles text-only approval directly — the error-state Fallback Path (3.5.3) is reserved for generation failures only. The `generatePreview` field records the choice. - **Phase 4b** is a continuation of Phase 4 — load it immediately after Phase 4 completes, before Phase 4.5. - **DESIGN.md** (from Phase 4.5) is the persistent design source of truth for Phases 5–11. - **Fix Loop Protocol** (from `operational-notes.md`) is mandatory at implementation checkpoints in Phases 5, 6, 7, 9, 10, and 11. Each phase must pass typecheck/lint/build/test before proceeding. The loop retries up to 5 times, then escalates to BLOCKED. - **Semantic-token-only rule**: Components must NEVER consume primitive tokens directly. - **Completion statuses are mandatory**: Every phase must end with DONE, DONE_WITH_CONCERNS, BLOCKED, or NEEDS_CONTEXT. - **User-question gating**: Discovery interview questions are one-at-a-time. Other AskUserQuestion calls require user response before proceeding. - **Final completion requires explicit verification evidence** from Phase 9.2 and a readiness handoff report from Phase 11. - **Optional phase skip policy**: Two skip mechanisms exist: - **Context-first re-entry** (Phase 0→1): Existing `DESIGN.md` is imported as context and does not bypass Phases 1–4.5 by default. Legacy `skippedPhases` entries remain backward-compatible when present from older runs. - **User-optional phase skip**: Phases 7 (Storybook), 8.5 (Design Review), and 10 (App Integration) may be skipped by user choice or environment constraints. Skip status is tracked via dedicated flags: `storybookSkipped: true` (Phase 7), `visualQASkipped: true` (Phase 8.5), `integrationStatus: "skipped"` (Phase 10). Skipped user-optional phases do NOT append to `completedPhases`. Degraded execution (e.g., manual fallback) DOES append. Phase 8.5 also records `visualQAMode: 'auto' | 'manual' | 'skipped'` to distinguish execution quality. ### Maintenance Note This router is the canonical runtime entrypoint. If phase boundaries, file names, or quality criteria change, update the corresponding phase file, `docs/PHASE-INDEX.md`, `docs/QUALITY-GATES.md`, `docs/MAINTENANCE.md`, and `scripts/validate-skill-md.sh` in the same PR.