| name | speckit-design-injection |
| description | Inject a design system (Stitch DESIGN.md / Figma export / Claude Design output / hand-written DESIGN.md) into an existing GitHub Spec-Kit project WITHOUT re-running the whole spec/plan/tasks pipeline. Use this whenever the user has already completed Spec-Kit's specify/clarify/plan/tasks for one or more features AND now wants to add UI design guidance (DESIGN.md, Stitch zip, Figma exports, Claude Design output, HTML prototypes, design tokens) so that the frontend implementation matches a specific visual standard. Triggers include phrases like "我已经跑完 spec-kit 又拿到了设计", "DESIGN.md 怎么融入已有 spec", "Stitch 设计接入 spec-kit", "Figma 设计融入已有的 spec/plan", "Claude Design 怎么用到我已有的项目里", "想把视觉规范注入到 constitution", "不想推倒重跑 spec-kit 但要加入设计", "前端 UI 怎么和我已有的 spec 文档对接". Use this skill even if the user does not explicitly mention "Spec-Kit" — as long as they have spec.md / plan.md / tasks.md files and a separate design artifact, this skill applies. Do NOT use this skill for fresh projects that haven't run Spec-Kit yet (use Spec-Kit directly with DESIGN.md in repo root from the start). |
Spec-Kit Design Injection
A reusable workflow for merging a design system into a project that has already completed Spec-Kit's specify/clarify/plan/tasks pipeline — without throwing away the existing work.
Why this skill exists
The natural Spec-Kit flow puts DESIGN.md in the project from day one, before /speckit.plan runs. But real projects often go the other way around:
- You run Spec-Kit first (specify → clarify → plan → tasks) for several Must-have features
- Then you produce a design system (via Google Stitch, Figma, Claude Design, or hand-writing DESIGN.md)
- Now the existing plan/tasks don't reflect the new visual standard
Naive solutions are wrong:
- ❌ Throw away spec/clarify/plan/tasks and re-run everything → wastes hours of work, loses architecture decisions
- ❌ Manually edit every plan.md to mention DESIGN.md → error-prone, inconsistent across features
- ❌ Just tell the implement agent "also look at DESIGN.md" → no enforcement, AI drifts
The right answer is Constitution Injection + Selective Re-run, which this skill walks through.
When NOT to use this skill
- Fresh project, no Spec-Kit run yet → put DESIGN.md in the repo root from the start, use Spec-Kit normally
- No design artifact in hand → this skill is about injection, not creation
- Backend-only project (no UI) → no design system to inject; not applicable
- Design changes are tiny (1-2 color tweaks) → just edit DESIGN.md, no constitution update needed
Prerequisites (verify before starting)
Stop and ask the user if any of these are missing:
| Required | What to check |
|---|
| Spec-Kit already initialized | .specify/ directory exists at project root |
| At least one feature has plan + tasks | specs/00X-*/plan.md and tasks.md exist for ≥ 1 feature |
| Design artifact in hand | One of: DESIGN.md file / Stitch download zip / Figma export / Claude Design output / HTML prototypes |
| User can identify the project root | A concrete absolute path |
If anything is missing, ask the user to provide it before continuing. Do not guess.
The 4-step workflow
Step 1 · Material placement (put artifacts where Spec-Kit can find them)
Step 2 · Constitution injection (abstract design rules → .specify/memory/constitution.md)
Step 3 · Impact identification (scan specs/ → mark which features touch UI)
Step 4 · Selective re-run (only re-run plan + tasks for UI-touching features)
Critical: spec.md and clarify-updated spec.md are never touched. Business requirements don't change just because we added a design system.
Step 1 · Material placement
Goal: get the design artifacts into a predictable place in the project so subsequent steps can reliably reference them.
Target structure (regardless of where the design came from):
<project-root>/
├── DESIGN.md ← the design system "constitution"
├── design-reference/
│ └── <source>-export/ ← e.g. stitch-export/, figma-export/, claude-design-export/
│ ├── <page-1>/
│ │ ├── code.html (or .png, .jsx, etc.)
│ │ └── screen.png
│ └── ...
└── .specify/
└── memory/
└── constitution.md ← will be updated in Step 2
Source adapter logic — the actual move differs by source. Read references/design-source-adapters.md for the exact mapping rules for each source type (Stitch / Figma / Claude Design / hand-written / other).
Naming rule for pages in design-reference/: rename to semantic names that match the feature naming in specs/. Example: Stitch's _7 → watchlist-zh (matches specs/002-watchlist/). This makes Step 4's "which page goes with which feature" mapping mechanical.
Pre-flight check before placement:
- If
DESIGN.md already exists in project root → ask user before overwriting
- If
design-reference/ already exists → ask user before merging
- If
prd.md is duplicated in the design artifact → don't copy it (project already has its own); flag any content mismatches
Always use cp -r, never mv. Keep the original artifact intact as backup.
Step 2 · Constitution injection
Goal: encode the design system as abstract, unchanging rules in .specify/memory/constitution.md, so every future /speckit.plan and /speckit.tasks run automatically inherits them.
The cardinal rule: constitution holds direction, DESIGN.md holds values.
✅ Constitution writes: "Visual specs come exclusively from root DESIGN.md.
All colors/fonts/spacing must use its tokens."
❌ Constitution does NOT write: "Primary color is #adc6ff" or "Use ashare-up token for gains"
Why? Because constitution is supposed to be persistent across design iterations. Hex values and token names will change when designs evolve. If you bake them into constitution, the constitution becomes a snapshot rather than a contract.
Trigger prompt template (give this to the user to run, OR run it yourself if you have /speckit.constitution access):
/speckit.constitution
Materials in this project that you must read first:
- DESIGN.md at project root
- specs/prd.md (business context)
- design-reference/<source>-export/ — pick 2-3 representative pages to understand visual style
Your job: append a "Frontend Design System" section to .specify/memory/constitution.md.
Each principle in this section must be ABSTRACT direction, never concrete values.
Write each principle as:
Principle name → Why it's non-negotiable → Which file is the source of truth
Required principle directions (extract specific content from the materials above):
1. Single source of truth for visual specs (which file says what is final)
2. How to reference visual prototype samples (when to read design-reference/)
3. Target market / user conventions that cannot be compromised
(extract from prd.md; do NOT assume — if prd.md doesn't say, leave a Open Question)
4. Component library baseline (infer from DESIGN.md; if unclear, Open Question)
5. Information density / design philosophy (from DESIGN.md design principles)
6. Multi-language strategy (only if design-reference shows multiple languages)
7. Theme mode (dark/light) — write what DESIGN.md says, no more
Hard constraints:
- Do NOT copy hex values, token names, component names, or font names into constitution
- Do NOT make decisions for me — if a direction is unclear from the materials,
list it under an "Open Questions" subsection at the end and wait for my answer
- After writing, tell me: (a) which file(s) you changed, (b) which paragraphs of
the materials each principle traces back to
Common failure mode: the AI dumps DESIGN.md's tokens into constitution. If you see hex values or token names in the proposed constitution text, reject it and ask the AI to rewrite at the abstract level.
Step 3 · Impact identification
Goal: figure out which existing features need their plan/tasks updated (those that touch UI), versus which are pure backend (don't touch).
Don't re-run everything blindly. Re-running pure backend features wastes time and risks regressing already-good plans.
Trigger prompt template:
Scan all feature directories under specs/. For each feature, classify whether its
plan.md or tasks.md involves frontend UI (React/Vue components, pages, forms,
tables, charts, etc.) versus pure backend/algorithm work.
Output table:
| Feature dir | Has FE? | Needs re-run? | Best matching page in design-reference/ |
Re-run criteria:
- Has FE = true → needs re-run of /plan + /tasks
- Has FE = false → no action
Then WAIT for me to confirm the re-run list. Do not start re-running yet.
Page-to-feature matching: if design-reference/ was named semantically in Step 1, the matching is usually 1:1. If a feature has no matching page in design-reference/, surface that as a gap — the user may need to generate that page or accept that the AI will design it from scratch.
Step 4 · Selective re-run
Goal: re-run /speckit.plan and /speckit.tasks for UI-touching features only. Skip /specify and /clarify — business requirements are unchanged.
Trigger prompt template (one feature at a time; loop for each):
For specs/<NNN>-<feature-name>/, re-run plan + tasks ONLY.
Do NOT touch spec.md or any clarify outputs — business requirements are unchanged.
/speckit.plan
- Read root DESIGN.md and design-reference/<source>-export/<matched-page>/ first
- In plan.md, add a "Frontend section" listing:
(a) Which components are used (refer to DESIGN.md §Components)
(b) Which DESIGN.md section each component maps to
(c) The visual reference sample path
- Preserve ALL existing backend / data flow / integration / dependency content unchanged
/speckit.tasks
- Tag each task: [FE] / [BE] / [INT]
- [FE] tasks must cite:
(a) The DESIGN.md section being implemented
(b) The reference HTML/sample path
(c) The shadcn (or equivalent) component being used
- [BE] tasks: preserve original
- Re-evaluate parallel groups — usually [FE] and [BE] of the same feature can run in parallel
After completing this feature, STOP and let me review before moving to the next.
Iteration pacing rule: one feature at a time. Re-running 5 features in a single shot makes review impossible and bugs cascade.
Anti-patterns to avoid
| Anti-pattern | Why it's wrong | Right approach |
|---|
| Copy hex values into constitution | Constitution becomes a snapshot, not a contract | Constitution references DESIGN.md as source of truth |
| Re-run /specify after adding design | Wastes work, business hasn't changed | Only re-run /plan + /tasks |
| Re-run all features including backend-only | Wastes time, risks regression | Identify UI-touching features first |
| Let AI guess at unclear directions | Replaces user judgment, creates drift | Surface as Open Questions, wait for user |
| Inject DESIGN.md content directly into each plan.md | Inconsistent across features | Use constitution as single enforcement point |
| Skip Step 2, jump straight to re-run | Each plan.md remembers DESIGN.md differently | Constitution ensures uniform reference |
What success looks like
After running this skill:
DESIGN.md lives at project root, referenced by all future Spec-Kit runsdesign-reference/<source>-export/ has semantically-named pages.specify/memory/constitution.md has a Frontend Design System section with abstract principles (no hex values)- UI-touching features have updated plan.md (with frontend section referencing DESIGN.md) and tasks.md (with [FE]/[BE]/[INT] tags)
- Backend-only features are untouched
/speckit.implement (the next phase) can produce code that visually matches the design system
Reference files
references/design-source-adapters.md — how to map Stitch / Figma / Claude Design / hand-written outputs into the standard project structure (Step 1 details)references/prompts.md — full ready-to-copy prompts for all 4 steps in both English and Chinesereferences/examples.md — a complete walkthrough using a real Stitch-generated A-share trading dashboard project as the case study
Read these when you need source-specific guidance or want to show the user a worked example.
A note on user communication
This skill is used by people who have already invested significant effort in Spec-Kit. Their fear when bringing in a new design is "do I have to redo everything?" Your first message to them should immediately address that fear:
"No, you don't need to redo your spec/clarify work. We only update the frontend-touching plan/tasks, and we use Spec-Kit's constitution mechanism to enforce the design system project-wide. Total effort: usually 30-60 minutes regardless of how many features you have."
Then proceed through the 4 steps interactively, pausing at each step for confirmation.
