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/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
```
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 |