From design-farmer
Automates design system construction from repository analysis: extracts patterns, builds OKLCH token hierarchies, implements accessible components with tests, verifies via multi-reviewer panels.
npx claudepluginhub hakilee/design-farmer --plugin design-farmerThis skill is limited to using the following tools:
> From seed to system — cultivate a production-ready design system from any codebase.
bin/version-checkdocs/EXAMPLES-GALLERY.mddocs/MAINTENANCE.mddocs/PHASE-INDEX.mddocs/QUALITY-GATES.mdexamples/DESIGN.mdphases/operational-notes.mdphases/phase-0-preflight.mdphases/phase-1-discovery.mdphases/phase-10-integration.mdphases/phase-11-readiness-handoff.mdphases/phase-2-repo-analysis.mdphases/phase-3-pattern-extraction.mdphases/phase-3.5-visual-preview.mdphases/phase-4-architecture.mdphases/phase-4.5-design-source-of-truth.mdphases/phase-4b-theming.mdphases/phase-5-tokens.mdphases/phase-6-components.mdphases/phase-7-storybook.mdBuilds Figma design systems from codebases: creates variables/tokens, components, light/dark modes, foundations docs, reconciles code-Figma gaps via phased workflows.
Guides building design systems with tokens (typography, colors, spacing, shadows), components, documentation, governance, and best practices. Use for UI consistency across teams.
Automates Figma design review: extracts tokens, maps components to React/Vue/Svelte codebases, detects drift, generates implementation plans and tasks. For design handoffs.
Share bugs, ideas, or general feedback.
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.
Before doing anything else, run the version check silently:
_DF_UPDATE=$(bash ~/.claude/skills/design-farmer/bin/version-check 2>/dev/null || true)
If _DF_UPDATE starts with UPGRADE_AVAILABLE:
UPGRADE_AVAILABLE <current> <latest>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
curl -fsSL https://raw.githubusercontent.com/ohprettyhak/design-farmer/main/install.sh | bash
If the script is missing, fails, or times out, continue silently — never block on a version check failure.
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.
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 |
| 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 |
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:
AskUserQuestion tool with structured questions, header, and options parameters.→ 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.
Every phase concludes with one of:
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="...").
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?"
| 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 |
Execute phases sequentially. Before starting each phase:
phases/operational-notes.md once per run if you have not already loaded it.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
{systemPath}/.design-farmer/config.json for context-window resilience.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.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.internal-canonical vs external-context. Readable third-party docs are context (not corruption); only unreadable files are treated as corrupted.{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.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.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.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.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.