Skip to content

xinetzone/SpecWeave / .agents/skills/design-library-creator

design-library-creator

Flagged

Create, 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.

FileKindSize
SKILL.mdskill md19.3 KB
aesthetics/dark-mode.mdmarkdown1.8 KB
aesthetics/index.mdmarkdown33.8 KB
aesthetics/navigation-footer.mdmarkdown2.2 KB
aesthetics/screen-craft.mdmarkdown9.2 KB
aesthetics/self-check.mdmarkdown24.9 KB
examples/templates/component-dispatch-rules.mdmarkdown9.1 KB
examples/templates/figma-token-gen.mdmarkdown50.3 KB
examples/templates/incremental.mdmarkdown5.7 KB
examples/templates/phase-2-analysts.mdmarkdown6.8 KB
examples/templates/phase-2-structured-spec.mdmarkdown8.8 KB
examples/templates/phase-2.5-intent-synthesis.mdmarkdown31.0 KB
examples/templates/phase-3-4-component.mdmarkdown9.0 KB
examples/templates/phase-4-ui-kit.mdmarkdown39.3 KB
examples/templates/phase-5-docs.mdmarkdown12.5 KB
examples/templates/scratch-token-gen.mdmarkdown14.4 KB
examples/templates/specimen-reference.htmlother6.0 KB
file-specs/css-json.mdmarkdown9.5 KB
file-specs/css-tokens.mdmarkdown33.6 KB
file-specs/design-library-output.mdmarkdown10.3 KB
file-specs/design-spec-bundle.mdmarkdown5.9 KB
file-specs/documentation.mdmarkdown12.3 KB
file-specs/preview-pages.mdmarkdown28.0 KB
file-specs/ui-kit.mdmarkdown28.5 KB
operation-policies/agent-orchestration.mdmarkdown20.2 KB
operation-policies/bundle-exploration.mdmarkdown9.0 KB
operation-policies/decision-rules.mdmarkdown10.7 KB
operation-policies/quality-gates.mdmarkdown10.5 KB
operation-policies/user-output-policy.mdmarkdown7.8 KB
scripts/check-design-library-phase.mjsscript85.1 KB
scripts/copy-bundle-assets.mjsscript12.3 KB
scripts/css-to-json.mjsscript53.1 KB
scripts/css-utils.mjsscript748 B
scripts/extract-components-css.mjsscript10.3 KB
scripts/generate-uikit-plan.mjsscript27.5 KB
scripts/jsonl-utils.mjsscript7.3 KB
scripts/validate-design-library-output.mjsscript3.1 KB
scripts/validate-intent.mjsscript7.3 KB
scripts/validate-token-input.mjsscript4.0 KB
scripts/validate-uikit-plan.mjsscript13.6 KB
skill-release-manifest.jsonconfig202 B
workflows/create-from-scratch.mdmarkdown22.5 KB
workflows/create-from-structured-spec.mdmarkdown17.5 KB
workflows/create-library.mdmarkdown53.0 KB
workflows/expand-components.mdmarkdown9.0 KB
workflows/generate-additional-kit.mdmarkdown4.9 KB
workflows/refine-library.mdmarkdown9.7 KB

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.
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: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall