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/quality-gates.md

View on GitHub
# Quality Gates

## Purpose

Main agent MUST execute this validation after ALL sub-agents complete (Phase 5). Files may be delivered incrementally through phase-level `generate_skill_files` actions, but the accumulated file set MUST pass all gates before `complete` is emitted.

## Capability-Aware Validation

Use the strongest available validation mode, but never claim browser validation if the runtime lacks browser/preview tools.

| Mode | When | Required Checks |
|------|------|-----------------|
| Full validation | Browser or preview tooling is explicitly requested and available | Run deterministic static checks first; optional browser checks are advisory unless requested |
| Static fallback | Default mode | Run deterministic file/CSS/JSON checks listed below |

## Script-First Static Validation

Main Agent MUST run the deterministic validator before emitting `complete`:

```bash
node {SKILL_DIR}/scripts/validate-design-library-output.mjs {output_dir}
```

(The validator auto-enables uikit-plan allowlist validation when `{output_dir}/uikit-plan.json` exists — auto-enabled findings are advisory warnings; pass `--require-uikit-plan` to enforce them as hard failures.)

Rules:
- Validator pass is REQUIRED for successful `complete`; if it exits non-zero, do not claim success.
- Treat only these validator counts as hard failures: undefined CSS variables > 0, preview link failures > 0, JSON failures > 0, UI Kit failures > 0, component slug mismatches > 0.
- If the validator passes, do NOT read full generated HTML/CSS/JSON files into LLM context; use the compact JSON summary as the Phase 5 static evidence.
- If the validator fails, only fix deterministic structure/CSS/JSON issues reported by the validator. Do not fix wording, visual style, screen count, implementation style, or other non-deterministic concerns.
- The validator is the mandatory static gate. Browser checks are optional and advisory unless the user explicitly asks for interactive validation.

## Hard Rule: Validator MUST Execute

If Main Agent emits a final response WITHOUT having run `validate-design-library-output.mjs`:
- The session is considered **FAILED** regardless of file state
- Main Agent MUST NOT claim "validation passed" or "validation partially failed" without having actually executed the script
- If the agent is about to stop (budget exhaustion, user cancellation, or error) → run validator FIRST

**Violation indicator**: If final response mentions "校验" / "validation" / "quality gate" but no RunCommand with `validate-design-library-output.mjs` appears in the call history → the agent hallucinated validation results.

Prompt-contract validation for skill changes only:

> Only run this when editing the `design-library-creator` skill itself. Never run it during normal Design Library generation. The checker lives outside the distributed skill in Prompt Base: `scripts/ci/design_library_creator_tests/validate-skill-contracts.mjs`.

```bash
node <repo>/scripts/ci/design_library_creator_tests/validate-skill-contracts.mjs {SKILL_DIR}
```

Trace-level regression indicators that block success:
- TodoWrite count > 4 in the full session.
- Any `Read` NotFound for `{bundle_path}/{bareComponentFile}` such as `bundle/input.md`.
- Phase 2b/2.4c token generation missing `colors_and_type.css` in output_dir, or token input gate failed.
- No Phase 4 docs dispatch before `complete` (UIKit dispatch NOT required for token-only bundles).
- No validator run before `complete`.

Static fallback MUST verify:
- Required file tree exists (including `css.json`)
- `preview/component-*.html` uses `<link rel="stylesheet" href="../colors_and_type.css">`
- `ui_kits/<type>/index.html` references `../../colors_and_type.css`
- No `var(--*)` reference points to an undefined variable in `colors_and_type.css`
- `components/index.json` matches `components/{slug}.json` files one-to-one
- `complete.stats` contains only `tokensExtracted`, `componentsAnalyzed`, and `filesGenerated`
- All generated files were delivered through phase-level `generate_skill_files` when that protocol action is available; otherwise files exist on disk and are listed in the final relative file summary

## Validation Read Budget

Phase 5 validation reads are a separate budget from Phase 1 bundle exploration reads.

Rules:
- Generated-output validation reads do NOT count toward the Main Agent bundle/intermediate read hard stop in `SKILL.md`
- MUST use `{SKILL_DIR}/scripts/validate-design-library-output.mjs` via `RunCommand` instead of reading full generated files into LLM context
- Read generated files only when the validator fails and the compact failure summary is insufficient for a targeted fix, or when the runtime lacks shell/static-check capability
- If reading is needed, use targeted ranges: first 120 lines for preview files, first 200 lines for `README.md`/`SKILL.md`, and script-based JSON parsing for `css.json`
- Never read raw bundle files during Phase 5 validation


## Token Input Gate (Create-Library)

Before dispatching the Figma token sub-agent:
- `{tmp_dir}/design-tokens.jsonl` MUST exist.
- It MUST NOT contain old schema fields: `brandSignals`, `unresolvedReferences`, `rawSpecAnnotations`, or `variables[].values`.
- Main Agent MUST run `node {SKILL_DIR}/scripts/validate-token-input.mjs {tmp_dir}/design-tokens.jsonl --legacy-css {bundle_path}/generated/colors_and_type.css --json`.
- If validator returns `mode="llm"`, dispatch the token sub-agent and pass warnings into the task prompt.
- If validator returns `mode="bundle"`, copy legacy `generated/colors_and_type.css` and skip the token sub-agent.
- If validator returns `mode="fail"`, stop only for unreadable/old-schema token input. Missing semantic roles or `themeSignals.quality.status=fail` are degraded-token warnings, not a reason to stop create-library.
- Token sub-agent reads the file in one pass if possible. If the Read tool returns a size-exceeded error, use offset/limit chunked reads (see figma-token-gen.md R2).

## Gate 1: Structure Completeness

| Required Path | Check |
|---------------|-------|
| `SKILL.md` | Exists |
| `README.md` | Exists |
| `colors_and_type.css` | Exists, contains `:root` and `.dark` blocks (see Exception below) |
| `css.json` | Exists, valid JSON, contains top-level keys: `color`, `font`, `shadow`, `radius`, `spacing`, `size` |
| `ui_kits/<type>/index.html` | Exists, links `../../colors_and_type.css` (**SKIP if components/ dir absent — token-only**) |
| `preview/component-*.html` | All pages listed in `outputPlan.previewPages` (from Phase 1 shortlist) exist (N = actual shortlist count from Phase 1, per `decision-rules.md` Component Count Formula) |
| `components/index.json` | Exists, valid JSON, `components[]` array has N entries matching shortlist slugs (**SKIP if components/ dir absent — token-only**) |
| `components/{slug}.json` × N | Each file exists, valid JSON, contains matching slug (**SKIP if components/ dir absent — token-only**) |

Exception: `.dark {}` block is NOT required when CSS contains `/* @light-only */` or `/* @dark-only */` comment markers (structured-spec route single-mode output).

## Gate 2: CSS Reference Integrity

- ALL `preview/component-*.html` files MUST contain `<link rel="stylesheet" href="../colors_and_type.css">`
- NONE may inline token CSS definitions
- `colors_and_type.css` MUST contain both `:root { }` and `.dark { }` blocks

  Exception: `.dark {}` block is NOT required when CSS contains `/* @light-only */` or `/* @dark-only */` comment markers (structured-spec route single-mode output).
- Font `@import` must be at the top of the CSS file
- `css.json` MUST be valid parseable JSON (no comments, no trailing commas)
- `css.json` color values MUST use `{ "hex": "#xxxxxx", "opacity": "N" }` format — never rgba() strings
- `css.json` token names MUST be consistent with `colors_and_type.css` variable names (minus `--` prefix)
- Component preview pages MUST only use CSS variables that are defined in `colors_and_type.css`

## Gate 3: JSON Structure Integrity

- `css.json` MUST be valid parseable JSON (no comments, no trailing commas)
- `components/index.json` MUST be valid parseable JSON
- Every component listed in `components/index.json` MUST have `components/{slug}.json`
- Every `components/{slug}.json` MUST parse and contain the same `slug`

## Gate 4: Non-Goals

- Do NOT block completion on documentation wording, line counts, section names, or banned prose patterns
- Do NOT block completion on UI Kit screen counts, navigation regexes, React marker strings, inline styles, icon strategy, or visual implementation style
- Do NOT dispatch SearchReplace loops for non-deterministic content/style concerns

## Gate 5: Optional UI Kit Functionality

- If the user explicitly requests browser validation, `index.html` may be opened to check runtime errors and navigation
- Browser validation findings are reported separately from deterministic static gate results
- Do not convert optional browser findings into automatic rewrite loops

## Gate 6: Protocol Compliance

Apply this gate only when the runtime explicitly exposes these protocol actions/tools.

- If available, all files were delivered via `generate_skill_files` actions
- If available, `update_tokens` was emitted after token system assembly when the route creates or changes tokens
- If available, `update_components` was emitted after component data export when the route creates or changes component coverage
- If available, `complete` is the final action with valid stats

No-action fallback:
- If protocol actions are not present in the available tools/actions, Main Agent MUST NOT fabricate or claim action emission.
- Completion evidence is: files exist on disk, deterministic validator exits 0, and final response lists compact relative file summary.
- In no-action fallback, do not fail solely because `generate_skill_files`, `update_tokens`, `update_components`, or `complete` were not emitted.

## Failure Handling

If any gate fails:
1. Identify the specific failing items from validator compact JSON output
2. For `create-library`: Fix only deterministic structure issues (CSS link path, JSON parse). Maximum 1 fix round. If still failing after 1 retry, emit failed completion.
3. For `create-from-scratch`: Do NOT fix. Report failed summary immediately. Zero fix rounds.
   - Rationale: from-scratch quality is guaranteed by sub-agent prompts. If the validator fails, the sub-agent template needs improvement — not a runtime patch. Quality is built in, not inspected in.
4. Emit targeted `generate_skill_files` updates for affected files only (create-library only)
5. Re-validate only the affected gates (create-library only)
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