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

workflows/refine-library.md

View on GitHub
# Refine Existing Library

> Incremental workflow: Adjust an existing Design Library based on user feedback.
> Read when: User references an existing Library and requests changes (adjust tokens, fix docs, improve components).

## When to Use

- User says "adjust the colors", "fix the button docs", "update the typography"
- User provides feedback on generated Library and wants iteration
- User asks to "optimize" or "improve" the Library
- User points out errors in generated output

### TodoWrite Policy (per SKILL.md invariant #12)

HARD CAP = 2. Allowed positions: ① after the change manifest is built, ② before final validation. Never standalone — always batch with the next action.

## Flow

### Step 1 — Assess Current State (Main Agent)

1. Read the existing Library's key files to understand current state:
   - `README.md` — brand narrative, file index
   - `SKILL.md` — gateway rules
   - `css.json` — current token understanding source
   - `colors_and_type.css` — runtime CSS link source
2. If kit-related change: also read `ui_kits/*/index.html` (kit-level README files are not part of the standard output)
3. If component-related: resolve ComponentContractFile first. Use `components/_evidence/index.json` + relevant `components/_evidence/{slug}.json` when evidence exists; otherwise use `components/index.json` + relevant `components/{slug}.json`.
4. **Redo Quality Check**: If multiple core files are missing/empty/malformed (e.g., `css.json` has wrong structure, `SKILL.md` < 5 lines, `README.md` is boilerplate), the previous generation FAILED. In this case:
   - Do NOT attempt to patch/refine — the base is too broken
   - Inform user: "上次生成质量不足,建议重新生成而非修补。"
   - Re-route to the ORIGINAL creation workflow (see SKILL.md Redo Handling)
5. Classify the change scope:

| Scope | Signal | Affected Files |
|-------|--------|---------------|
| Token change | "change primary color", "adjust spacing" | CSS, all preview HTML, UI Kit, components/{slug}.json |
| Component fix | "fix Button docs", "add Input component", "change Button radius/hover/preview" | `components/{slug}.json` + `components/index.json` + `preview/*.html` + `components.css` + `README.md` component pattern entry |
| Kit improvement | "add a screen", "fix navigation" | `ui_kits/<type>/index.html` |
| Doc update | "update README", "fix brand description" | `SKILL.md` and/or `README.md` |
| Content fix | "fix typos", "change copy language" | Various |
| Graphic asset change | "change icon color", `<design_library type="graphic">` in user message | `.design_library/{lib}/assets/icons/{name}.svg` (or `icons/{name}.svg`) — edit in place |

### Graphic Asset Changes (Main Agent direct edit)

Graphic asset (icon/SVG) modification is an EXCEPTION to the sub-agent dispatch flow:

- Main Agent edits the ORIGINAL SVG file in place under `.design_library/{lib}/` (look for `assets/icons/{name}.svg` or `icons/{name}.svg`; if the user message carries a `file-path` attribute on the `<design_library>` tag, edit that exact file). No sub-agent dispatch, no CSS/README cascade.
- Changes under `.design_library/` are automatically uploaded as a new library version when the turn ends — do NOT call any protocol action for this.
- NEVER create a standalone copy outside the library directory as the deliverable.
- If the library directory does not exist in the workspace (not installed), tell the user the original asset file cannot be located — do NOT create an orphan file and claim the library was updated.

### Step 2 — Plan Minimal Changes (Main Agent)

- **Prefer minimal changes over full regeneration.**
- Map the change to affected files:
  - Token rename → list ALL files referencing that token name (preview HTML, components/{slug}.json, UI Kit CSS variables, `css.json`)
  - Token value change (colors, spacing, radius, etc.) → update CSS, then run `css-to-json.mjs` to regenerate `css.json` + update all preview pages referencing affected tokens
  - Component add → generate that component's preview page + update component data + regenerate `components.css` + update README Component Patterns. For Figma-derived libraries, write `components/_evidence/{slug}.json` + debug/traceability `components/{slug}.json` and update both indexes; normal generation reads evidence. For non-Figma libraries, write compact schema v2 `components/{slug}.json` and update `components/index.json`.
  - Component preview/style modification → update `preview/component-{slug}.html`, then regenerate `components.css`; if the change affects anatomy, states, variants, usage guidance, or key visual facts, update the README Component Patterns row for that slug.
- Create a change manifest:
  ```
  Changed: colors_and_type.css (updated --brand-primary from #ff6b35 to #e65100)
  Cascade: css.json, preview/component-buttons.html, ui_kits/app/index.html
  Unchanged: all other files
  ```
- **Protected directories**: `specs/` is user-maintained context — NEVER delete its contents during refinement. Modification is allowed ONLY when the user explicitly requests changes to specs content.

### Step 3 — Execute Changes (Sub-Agent dispatch)

- Dispatch only the necessary sub-tasks using the closest matching phase template/spec:
  - Token/CSS changes → targeted CSS-refine Task using `file-specs/css-tokens.md`; after CSS is updated, Main Agent runs `css-to-json.mjs` to regenerate css.json deterministically
  - Preview page changes → `examples/templates/incremental.md` § Preview-Only
  - Component data changes → for Figma-derived libraries, update `components/_evidence/{slug}.json` first and keep `components/{slug}.json` in sync or mark debug data stale. For non-Figma libraries, update compact schema v2 `components/{slug}.json` directly. CSS/HTML/MD content still goes through sub-agents.
  - UI Kit changes → `examples/templates/phase-4-ui-kit.md`
  - **Cascade rule**: Any change to `colors_and_type.css` MUST trigger a paired css.json regeneration via:
    ```bash
    node {SKILL_DIR}/scripts/css-to-json.mjs {output_dir}/colors_and_type.css --output {output_dir}/css.json
    ```
    - **Component CSS cascade rule**: Any change that creates, deletes, or modifies `preview/component-{slug}.html`, or changes component-level CSS/anatomy inside preview markers, MUST trigger:
      ```bash
      node {SKILL_DIR}/scripts/extract-components-css.mjs {output_dir}
      ```
      The regenerated `components.css` is part of the same change and must be listed in the final `writtenFiles`.
    - **README component-info cascade rule**: Any component add or meaningful component change MUST update `README.md` → Component Patterns with the slug, preview path, contract path, components.css coverage, variant/state/pattern facts, and one concise key insight.
- Include relevant snippets, file paths, and the change manifest for continuity
- Sub-agent constraints: use the closest template from `examples/templates/`; if that template says constraints are inline, do not add `file-specs/*.md` reads
- Each sub-agent receives:
  - The user's change request
  - Relevant snippets from current files (for reference)
  - Relevant token/component data (from README or CSS)

### Snippet Budget

Avoid pasting large generated files into the Task query.

| File Type | Default Context | Full Content Allowed When |
|-----------|-----------------|---------------------------|
| `README.md`, `SKILL.md`, `components/_evidence/index.json`, `components/index.json` | Relevant section + file index only | File is short and the entire file is directly affected |
| `colors_and_type.css` | Affected variable blocks + surrounding comments | Token rename/value change affects most of the file |
| `preview/*.html` | `<head>` CSS link + affected component/demo section | File is small and the requested change is page-wide |
| `ui_kits/<type>/index.html` | Route/screen/component snippets + import/link section | Never by default; only if the target file is demonstrably small |

Default snippet limit: 200-400 lines per sub-task. For larger context, pass the file path and exact symbols/sections to inspect; let the sub-agent read only the necessary ranges.

### Documentation and Markdown Changes

README, SKILL, CSS, HTML, and JSX content must still be generated by sub-agents. Main Agent may directly update structured component JSON (`components/_evidence/index.json`, `components/_evidence/{slug}.json`, `components/index.json`, and `components/{slug}.json`) when the change is limited to component metadata. Main Agent only:
- Builds the change manifest
- Selects affected files
- Dispatches targeted Task calls
- Collects `writtenFiles` paths from `{tmp_dir}/agent-reports/*.json`
- Emits `generate_skill_files`

### Step 4 — Cross-Reference Validation (Main Agent)

- If tokens changed: verify all preview HTML still references valid CSS variables
- If component added or preview/style changed: verify `components.css` contains the affected component section and `README.md` Component Patterns includes the affected slug with key facts
- If kit changed: verify kit still loads correctly
- Run relevant gates from `operation-policies/quality-gates.md` (not all — only affected ones)

### Step 5 — Finalize Changes

> Sub-agents Write updated files to disk, then write `{tmp_dir}/agent-reports/{refine-task-id}.json`; Main Agent references paths in reported `writtenFiles`. CSS sub-agent also writes `writtenFiles` + `stats` + `availableVariablesFile` to its report. Final sub-agent responses are short status sentences only.

## Constraints

- Do NOT regenerate unchanged files
- Preserve existing brand narrative and personality unless explicitly asked to change
- If user's request would break a Critical Invariant (see SKILL.md), warn before proceeding
- Maximum cascade depth: if a token rename affects >10 files, confirm with user before proceeding
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