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/bundle-exploration.md

View on GitHub
# Bundle Exploration Strategy

## Core Principle

The Design Spec Bundle is a multi-file archive. NEVER attempt to load it entirely into memory. Read progressively: **index → overview → detail → deep-dive**.

## Phase 1: Main Agent Lightweight Scan (Index-Level Only)

> ⚠️ **DEPRECATED for `create-library` route (bundle-generator v1.3+)**: Phase 1 now reads ONLY `generated/bundle-manifest.jsonl` (see `workflows/create-library.md` § Phase 1). This section is retained for:
> - Bundles generated by older BundleGenerator versions (no manifest)
> - `expand-components` route when manifest is absent
> - Debug reference for understanding what the manifest replaces

Main agent reads ONLY these index files to build global awareness:

| File | What to Extract | Size | Read Params |
|------|----------------|------|-------------|
| `METADATA.md` | File count, coverage stats, navigation pointers | ≤4KB | — |
| `context/import-context.md` | Library name, source file, frame count | ≤2KB | — |
| `context/data-integrity.md` | Extraction/export counts, warnings | ≤3KB | — |
| `tokens/variables-index.md` | Variable type/set/mode overview | ≤4KB | — |
| `pages/index.md` | Page/frame table | ≤4KB (small) / up to 200KB (large) | **Always use `offset: 1, limit: 200`** |
| `assets/icons/index.md` | Exported SVG icon list, extraction stats | ≤2KB | — | *Sub-agent only (supplementary); Main Agent gets icon info from manifest `assetAvailability`* |

**Stop condition**: Main agent has enough to plan Phase 2 sub-tasks.

### Bundle Manifest Contract (REQUIRED)

At the end of Phase 1, Main Agent MUST produce an internal `bundleManifest` and pass the relevant parts to Phase 2 analysts. This manifest is distilled metadata only; it must not contain raw component trees.

```json
{
  "stats": {
    "categories": 25,
    "primitives": 479,
    "variants": 6981,
    "frames": 704,
    "variables": 318,
    "icons": 4430,
    "svgIconsExported": 0
  },
  "warnings": [
    "No frame selection — Bundle contains ALL data",
    "28 alias resolutions failed",
    "Icons detected but zero SVGs exported"
  ],
  "validComponentCategories": [
    { "slug": "buttons", "name": "Buttons", "variantCount": 2334 }
  ],
  "excludedCategories": [
    { "name": "Internal Only Canvas", "reason": "non-UI/internal canvas data" }
  ],
  "assetAvailability": {
    "iconsUsableAsSvg": false,
    "availableIcons": [],
    "imageBinariesExported": true,
    "fontsAvailable": true
  },
  "paginationHotspots": [
    { "path": "assets/icons/root.md", "parts": 21 }
  ]
}
```

Required behavior:
- `validComponentCategories` must exclude internal, structural, examples, utilities, style-only, and shape-only categories before component shortlisting
- `excludedCategories` must include the reason, so later agents do not re-add noisy categories
- `warnings` must be propagated into Phase 2 returns or final summary
- `assetAvailability.iconsUsableAsSvg = false` when `data-integrity.md` reports icons detected but zero SVGs exported
- `assetAvailability.availableIcons` = list of exported SVG filenames from `assets/icons/index.md` § "Exported SVG Files" (e.g., `["close", "search", "chevron-down"]`). Empty array if no SVGs exported.

> **Note (bundle-generator v1.3+)**: `assetAvailability` is now directly embedded in `bundle-manifest.jsonl` by the SDK.
> Main Agent reads it from manifest in Phase 1 — no additional file reads required.
> For older bundles without this field, § 2.3b uses directory detection as fallback (checks if `assets/icons/` dir exists).

## Information Density Assessment (Read Before Deep Dive)

Not all bundle files are equally valuable. Sub-agents MUST triage before reading:

| File Pattern | Expected Density | Reading Strategy |
|-------------|-----------------|-----------------|
| `tokens/colors-full*.md` | **HIGH** — all color variables by set/mode | Large file (80-120KB); SKIP in favor of `generated/design-tokens.jsonl` or `colors-summary.md`. Only read via offset/limit if summary sources lack needed detail. |
| `context/brand-clues.md` | **HIGH** — curated brand signals | Always read |
| `context/component-page-matrix.md` | **LOW** — repetitive state names | Read first 50 lines only (for category→page mapping); ignore detailed rows |
| `annotations/ui-copies*.md` | VARIABLE | Scan first 20 lines; if all entries are state labels (Enabled/Disabled/Hovered) → mark as "no brand signal", skip rest |
| `context/selected-frames-full.md` | LOW | Only read first 30 lines if focus scope needs confirmation |

## Phase 2: Brand Analyst Reading

The single brand-analyst sub-agent reads ONLY its assigned bundle partition:

### brand-analyst reads:
**Primary source** (structured, read FIRST):
1. `generated/brand-input.jsonl` — Pre-computed brand data (libraryName, categories, uiCopySamples, colors, typography, designSystemType)

**Supplementary sources** (only if brand-input.jsonl lacks sufficient signal):
2. `context/brand-clues.md` — Brand personality inference (curated narrative)
3. `annotations/ui-copies*.md` — Scan first 20 lines; skip if all state labels

> **Note**: `token-analyst` and `component-analyst` have been eliminated. Token data is generated deterministically by BundleGenerator (`generated/colors_and_type.css`). Component structural data is generated as `generated/components/{slug}.jsonl`. Both are copied from the bundle in Phase 2b without LLM involvement.


## Pagination Rules

- Most files are ≤16KB
- When paginated: base file (e.g., `ui-copies.md`) contains an index listing all parts
- Parts use suffix: `ui-copies-part1.md`, `ui-copies-part2.md`
- Read the base file first, then specific parts as needed
- Context files may occasionally be larger — use offset/limit if a read fails
- Part files MUST be read in the order listed by the base index file. If no explicit list exists, sort by numeric suffix (`part1`, `part2`, ..., `part10`), never by raw lexicographic order.
- Do NOT use a glob result order as semantic order. `part10` before `part2` is a data corruption risk.

## Directory Budgets

Each analyst has a strict default budget. Increase only if the current output schema cannot be completed.

| Domain | Default Budget | Expansion Rule |
|--------|----------------|----------------|
| Tokens | Read colors-full, typography, spacing, shadows first | Read paginated parts only when needed |
| Components | Read only `generated/components/{slug}.jsonl` evidence files for shortlisted slugs | Read additional evidence files only when needed |
| Brand | Read curated brand/context files and scan UI copies | Stop when copies are state labels or repeated variant names |
| Assets | Read icons index, images catalog, fonts | If SVG export count is 0, do not read large icon root part files unless explicitly needed for naming examples |

## No Focus Hint Rule

If `context/data-integrity.md` reports no frame selection and the bundle has more than 50 frames:
- Treat the bundle as noisy all-data export
- Prefer filtered `validComponentCategories` over raw top-variant categories
- Pass the warning to `brand-analyst`
- Do not let internal canvas, examples, utilities, styles, or shape-only categories enter the initial shortlist
- Ask the user for scope only if the filtered shortlist is still ambiguous or product type confidence is below medium

## Data Integrity Rules

- If `data-integrity.md` reports extraction warnings → acknowledge gaps in output
- NEVER fabricate data to fill gaps (no generic M3 defaults, no lorem ipsum)
- When variables count = 0 → rely on component renderings and page analysis
- `selectedFrameNames` are focus HINTS, not destructive filters — bundle contains full data

## Stop Conditions for Sub-Agents

A sub-agent should stop reading when:
- It has extracted all values needed for its output schema
- Remaining files are clearly outside its domain
- File pagination shows diminishing new information

---

## Large File Handling (> 64KB)

Some bundle files (especially paginated `*-part*.md` concatenations or full token exports) may exceed the 64KB read limit.

### Pre-emptive Strategy (avoid failures)

| File Pattern | Typical Size | Strategy |
|-------------|-------------|----------|
| `tokens/colors-full*.md` | 80-120KB | SKIP entirely — use `generated/design-tokens.jsonl` or `colors-summary.md` for color data instead |
| `assets/icons/root*.md` | 100-200KB | Read index only; do NOT deep-read root parts |

### Recovery Strategy (if read fails with size error)

1. NEVER retry the same Read without offset/limit
2. Use `offset: 1, limit: 600` (approximately first 36-60KB depending on line length)
3. If still too large, use `offset: 1, limit: 400` (approximately first 25KB)
4. Log a warning: "File {path} exceeds 64KB limit; reading first {N} lines only"

### Sub-Agent Instruction Template

Include this in all Phase 2 analyst Task queries:

```
⚠️ FILE SIZE RULE: If any Read fails with "exceeds the limit" error:
  1. Do NOT retry without offset/limit
  2. Re-read with offset=1, limit=600 (first ~40KB)
  3. Record a warning about partial read
  4. Continue with available data — do NOT fabricate missing values
```
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