xinetzone/SpecWeave / .agents/skills/design-library-creator
design-library-creator
FlaggedCreate, expand, and refine professional Design Libraries / Design Systems with structured token architecture. ONLY invoke when user EXPLICITLY mentions design-system terminology: 'Design Library', 'Design System', '设计系统', '设计库', 'token system', 'design tokens', '组件库规范', or provides a parsed design-spec bundle (ZIP/Figma export). Also covers creating a new theme / color theme as a design-system deliverable (创建主题/新建暖色主题/深色主题等 — tokens + palette + component styling). Do NOT route here for: '素材库', '全套素材', '素材合集', '物料库', '生成素材', '做一套设计', '做几张图', '设计一套页面', '帮我出图', page/poster/landing-page creation, or any visual-asset generation intent where the user does not demonstrate knowledge of design-system concepts. Those belong to solo-design.
operation-policies/decision-rules.md
View on GitHub# Decision Rules
## Route Table
> **SSOT**: The primary Route Table lives in `SKILL.md`. This table extends it with trigger signal classification for ambiguous routing.
| User Intent | Workflow | Trigger Signals |
|-------------|----------|-----------------|
| Create new Design Library from parsed Bundle | `workflows/create-library.md` | User provides design-spec ZIP or bundle directory |
| Create Design Library without Bundle data | `workflows/create-from-scratch.md` | User describes desired style but provides no bundle/ZIP/figma data |
| Create Design Library from structured token spec | `workflows/create-from-structured-spec.md` | User provides token document (.md/.json/.css) with complete color/font/spacing definitions; tokens already named and valued; NOT a vague description |
| Expand component coverage in existing Library | `workflows/expand-components.md` | User references existing Library and asks to add more components |
| Refine/adjust existing Design Library | `workflows/refine-library.md` | User references existing Library and asks for changes (token values, docs, bug fixes) |
| Add additional kit type to existing Library | `workflows/generate-additional-kit.md` | User asks for new kit type (e.g., "add a website kit") |
| Extract design style from existing .design project into a Library | `workflows/create-from-structured-spec.md` | User references an existing `.design` project (or its output directory) and asks to "extract/distill/save/沉淀 the design style as a design library"; evidence: presence of `{name}.design` file + `colors_and_type.css` in the same directory |
## Component Count Formula
**First-batch cap = 6** (Figma import path). The first run generates intent/preview for up to 6 core components from the fixed-slots-first shortlist. Dispatch topology uses batches of 3 sub-agents per round (≤2 turns). Full evidence remains available via `supportEvidenceComponents` and `components/_evidence` for UIKit fallback; remaining components are available via expand-components workflow (triggered by user "继续解析" action).
> **Indexing**: Shortlist uses **1-based indexing**. The selected indices map directly to `preview/component-{slug}.html` and `components/{slug}.json`.
The same shortlist produces preview pages and structured component data:
- `preview/component-{slug}.html` — one per shortlisted category
- `components/index.json` + `components/{slug}.json` — structured component analysis (copied from bundle, deterministically generated by BundleGenerator)
Users can request additional components via `workflows/expand-components.md` if their bundle is re-imported with new content.
## Token-Only Bundle Detection
When BundleGenerator produces a bundle where no component categories were identified (e.g., the .fig file contains only a design token specification page with colors, typography, spacing, border-radius, and shadows):
**Detection rule** (SSOT for Recovery triggers = `workflows/create-library.md` § 1.2 Trigger conditions; check Recovery FIRST, Token-Only second):
| Priority | Condition | Action |
|----------|-----------|--------|
| 1 | Any § 1.2 trigger condition met: `manifest.splitHint?.needed === true`; OR `shortlist` empty AND `componentFilesBySlug` has exactly 1 entry; OR `shortlist.length <= 1` AND `stats.totalPrimitives > 6`; OR `stats.componentCategories <= 2` AND `stats.totalPrimitives > 6`; OR the single category slug matches internal/canvas/deprecated patterns | Trigger § 1.2 Shortlist Recovery |
| 2 | `shortlist.length === 0` AND `stats.totalPrimitives ≤ 6` AND component evidence exists | Use generated component evidence as shortlist directly |
| 3 | `shortlist.length === 0` AND no recovery trigger applies (or recovery returned `recoveryFailed` with no usable evidence) | Token-Only mode |
| 4 | Otherwise (`shortlist.length > 1` and no trigger) | Normal path |
**Token-Only mode skips**: Phase 3 (components), Phase 4 UIKit. Only produces: tokens + docs (SKILL.md + README.md).
## Shortlist Recovery (Single-Category Fallback)
When BundleGenerator produces an over-coarse shortlist (typically because all components reside on a single Figma Page), the manifest `shortlist` is often empty or has ≤1 entry (the single category name often matches exclusion patterns like "internal"/"canvas"). Trigger conditions are owned by `workflows/create-library.md` § 1.2 (see Detection rule table above — do not redefine them here).
**Splitting strategy**:
- Primary: group primitives by `structures[].name` prefix (the part before the first comma in variant strings like "Type=TextOnly, State=Default, Size=32px" → "Type=TextOnly" → category "Button")
- Secondary: group by shared `variantDimensions` axis combinations
- Target: each category MUST have ≥3 variants; merge any group below this threshold into its nearest neighbor
- Naming: infer English component name from the grouping key (e.g., "TextOnly"→"Button", "Select"→"Tab", "Check"→"Checkbox")
## Component Selection Priority
All creation workflows that generate components follow this priority order:
1. **User explicit list** (highest): If user names specific components → use those
2. **User quantity limit**: If user says "只要 3 个" / "just 3 components" → take top-N from preset or bundle
3. **.design page evidence**: If input is a .design project and ≥4 component types identified from pages → use them
4. **Bundle shortlist**: (create-library only) Use manifest.shortlist
5. **Product-type preset** (default): From preset table (create-from-scratch / structured-spec)
Cap: **No hard cap.** All valid bundle shortlist categories are generated. When user explicitly specifies components, all specified components are generated. Users can add more later via `expand-components`.
If user specifies components by name but name is not in preset:
- Infer structure from component name + product type
- Write minimal `components/{slug}.json` with inferred variants
## Forbidden Questions (Never Ask)
These have fixed answers defined by the skill:
| Question | Fixed Answer |
|----------|-------------|
| "Should I generate a README?" | YES, always |
| "Should I generate components?" | **Conditional**: Generate unless `components` in skipSet (per SKILL.md § Skip Set) |
| "Should I generate preview pages?" | **Conditional**: Generate unless `previews` in skipSet |
| "Should I generate a UI Kit?" | **Conditional**: Generate unless `uikit` in skipSet OR Token-Only Bundle |
| "Should I include dark mode?" | YES, always |
| "Which components should I document?" | Main agent selects top-N from shortlist by variant count (see Component Count Formula above); structured data exported as JSON |
| "What format should the CSS be in?" | Single `colors_and_type.css` |
| "Should I rename tokens to M3 naming?" | NO — preserve source tokens in the definition layer, but add portable aliases for the unified consumption layer when components/previews/UIKit are generated |
| "Is the bundle/file too large?" / "Token count exceeds threshold" / "Figma 包过大" | Proceed with Phase 2 using bundle data as-is. Size/token assessment and downgrade decisions are automated by BundleGenerator — never ask the user about size limits or import strategies. |
## Allowed Questions (May Ask When Needed)
| Question Type | When to Ask |
|---------------|-------------|
| Bundle path/attachment confirmation | Phase 0, if no ZIP or directory is evident |
| Target library name | Phase 0, if not inferable from bundle metadata |
| Selected frames scope | Phase 0, if bundle has >50 frames and user hasn't indicated focus |
| Kit type preference | Phase 2 (§ 2.4), only if evidence is ambiguous (confidence < medium) |
## Pre-routing: .design Project → Structured Spec
When user's intent is to extract a Design Library from an existing `.design` project:
1. **Locate the project**: Find the `.design` entry file and confirm sibling `colors_and_type.css` exists
2. **Primary input**: Use the project's `colors_and_type.css` as the structured token spec — it contains the complete CSS variable system
3. **Secondary input (optional)**: Scan up to 3 HTML pages from `pages/` to identify recurring component patterns (Button, Card, Nav, etc.) — informs component selection
4. **Device context**: Read `.design` JSON → `config.deviceType` to determine kit type:
- `'mobile'` → kitType `"app"`
- `'desktop'` → kitType `"website"` or `"dashboard"`
- `'tablet'` → kitType `"app"`
5. **Library name**: Derive from `.design` project directory name (e.g., `my-portfolio/` → `"my-portfolio"`)
6. **Route to**: `create-from-structured-spec` with `source: "design-project"`
## Information Priority
When multiple sources conflict:
1. User's explicit instructions (highest)
2. Bundle data (ground truth for values)
3. Agent inference (for narrative, personality, guidelines)
## Call Budget by Route (Two-Layer Semantics)
Budgets have exactly two layers — do not mix them up:
1. **Soft guidance (this table)**: observational typical ranges, NOT hard limits. Do NOT compress Tasks or reduce quality to stay within these ranges.
2. **Graceful-degradation protocols (per-workflow)**: each workflow MAY define its own hard checkpoint table (e.g., `create-from-scratch.md` STOP at ≥50, `create-from-structured-spec.md` STOP at ≥40). Those checkpoints are authoritative for their route and are NOT overridden by this table — they exist to guarantee css.json + validator run before stopping, not to compress quality.
| Route | Typical Range (soft) | Hard degradation protocol |
|-------|--------------|-------|
| create-from-structured-spec | 15–45 | Owned by `workflows/create-from-structured-spec.md` (STOP ≥40) |
| create-from-scratch | 20–55 | Owned by `workflows/create-from-scratch.md` (STOP ≥50) |
| create-library | 30–70 | None (Budget Exhaustion Protocol below is the only stop) |
| refine-library | 5–25 | None |
**Anti-compression rule**: The Main Agent must NOT batch multiple components into fewer Tasks, skip sub-agent dispatches, or invent sub-agent call limits beyond what a dispatch template itself declares (templates may declare their own caps, e.g., `phase-3-4-component.md` MAX CALLS: 5). Quality > speed.
**Exhaustion handling** (retained):
If session reaches a natural quality-complete state, run final validation. If somehow stuck in an infinite loop (>80 calls with no progress), execute Budget Exhaustion Protocol:
1. Ensure `{output_dir}/css.json` exists → if not, run `css-to-json.mjs`
2. Run `validate-design-library-output.mjs`
3. STOP with validator result as final output
These deterministic derivation steps apply to both `TOKEN_GEN_MODE=llm` and `TOKEN_GEN_MODE=bundle`. Bundle mode skips only the LLM token-generation Task, never `css-to-json.mjs`.
Rationale: deterministic scripts cost 0 LLM tokens and <2s wall time. They are never budget-competing.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |