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.
file-specs/css-json.md
View on GitHub# CSS JSON Token File Specification
## File
Single file: **`css.json`**
A structured JSON representation of all design tokens. This is the canonical format consumed by the frontend `ThemeTokenData` interface.
## Generation Sources
All routes generate `css.json` deterministically via `scripts/css-to-json.mjs` from `colors_and_type.css`. LLM-written `css.json` is FORBIDDEN (see SKILL.md Critical Invariants #14, #26, #31).
- **`create-library` (Figma bundle)**: Derived by `scripts/css-to-json.mjs` from the final `colors_and_type.css` (Phase 2.4c).
- **`create-from-scratch` (text description)**: Token sub-agent writes `colors_and_type.css`; Main Agent derives `css.json` via `scripts/css-to-json.mjs`.
- **`create-from-structured-spec` (user-provided token doc)**: Parse-and-transform sub-agent writes `colors_and_type.css`; Main Agent derives `css.json` via `scripts/css-to-json.mjs`.
- **`refine-library` (token changes)**: Regenerated by `css-to-json.mjs` after CSS is updated.
## Top-Level Structure (6 keys)
```jsonc
{
"color": { /* Record<string, ColorGroup> */ },
"font": { /* FontTokens */ },
"shadow": { /* Record<string, ShadowTokenValue> */ },
"radius": { /* Record<string, string> */ },
"spacing": { /* Record<string, string> */ },
"size": { /* Record<string, string> */ }
}
```
All 6 top-level keys MUST be present. Each value MUST be a JSON object (not null, not array, not string).
---
## `color` — Color Groups (flat, sibling-level)
Structure: `Record<string, ColorGroup>` where `ColorGroup = Record<string, ColorTokenValue>`.
Color groups are placed as **flat sibling keys** under `color`. Group names are fully dynamic — determined by the source design data's color naming (e.g., `primary`, `brand`, `cyan`, `ocean`, `success`). There are no required or fixed group names.
> **CSS ↔ JSON naming**: group names are taken verbatim from the CSS section comments —
> `css-to-json.mjs` does NOT rename groups. `/* surface */` in CSS produces a `"surface"` JSON key.
> Downstream consumers must read groups by the actual comment names present in `colors_and_type.css`.
### ColorTokenValue Format
ALL color values MUST use this structure:
```json
{ "hex": "#1664ff", "opacity": "1" }
```
- `hex`: Always 6-digit lowercase hex with `#` prefix. Never shorthand (`#fff` → `#ffffff`).
- `opacity`: String representation of a number between `"0"` and `"1"`.
- `isPrimary` (optional): Boolean `true` when this token is the representative/key color of its group. Added automatically by `css-to-json.mjs` when the CSS declaration has a `/* @primary */` inline annotation. At most one token per group should be marked.
### Example
```json
{
"color": {
"primary": {
"primary-1": { "hex": "#e8f3ff", "opacity": "1" },
"primary-2": { "hex": "#bedaff", "opacity": "1" },
"primary-3": { "hex": "#94bfff", "opacity": "1" },
"primary-6": { "hex": "#1664ff", "opacity": "1", "isPrimary": true },
"primary-7": { "hex": "#0e4bd6", "opacity": "1" }
},
"danger": {
"danger-1": { "hex": "#ffece8", "opacity": "1" },
"danger-6": { "hex": "#f53f3f", "opacity": "1" }
},
"semantic": {
"bg": { "hex": "#ffffff", "opacity": "1" },
"fg": { "hex": "#1d2129", "opacity": "1" },
"accent": { "hex": "#1664ff", "opacity": "1" }
},
"surface": {
"surface": { "hex": "#ffffff", "opacity": "1" },
"surface-dim": { "hex": "#f7f8fa", "opacity": "1" }
},
"interactive": {
"interactive-hover": { "hex": "#1664ff", "opacity": "0.08" },
"interactive-focus": { "hex": "#1664ff", "opacity": "0.12" }
},
"error": {
"error": { "hex": "#f53f3f", "opacity": "1" }
},
"chart": {
"chart-1": { "hex": "#1664ff", "opacity": "1" },
"chart-2": { "hex": "#0fc6c2", "opacity": "1" }
},
"dark": {
"primary-1": { "hex": "#1a2a4a", "opacity": "1" },
"bg": { "hex": "#131416", "opacity": "1" }
}
}
}
```
**Notes**:
- Group names and token names vary by scenario — the spec only constrains the structure, not specific naming.
- The `dark` group is a flat collection of dark-mode override values.
---
## `font` — Font Tokens (4 dimensions + optional `assets`)
Structure: `FontTokens` with 4 required sub-keys and 1 optional sub-key:
```json
{
"font": {
"family": { "<token-name>": "<value>" },
"size": { "<token-name>": "<px-value>" },
"weight": { "<token-name>": "<value>" },
"lineHeight": { "<token-name>": "<unitless-ratio>" }
}
}
```
### Example
```json
{
"font": {
"family": {
"font-sans": "Inter, ui-sans-serif, sans-serif, system-ui",
"font-serif": "Playfair Display, serif",
"font-mono": "JetBrains Mono, monospace"
},
"size": {
"font-size-h1": "36px",
"font-size-h2": "30px",
"font-size-body": "16px",
"font-size-caption": "12px"
},
"weight": {
"font-weight-h1": "700",
"font-weight-h2": "600",
"font-weight-body": "400"
},
"lineHeight": {
"line-height-h1": "1.2222",
"line-height-h2": "1.2667",
"line-height-body": "1.5"
}
}
}
```
### `font.assets` — Font Resource Metadata (optional, managed by frontend GUI)
`font.assets` records metadata about font files uploaded by the user or referenced from CDN. This field is **managed exclusively by the frontend GUI** — Agent MUST NOT create, modify, or delete entries.
**Agent MUST merge-preserve existing `font.assets` when regenerating css.json.**
Structure:
- key: font identifier (typically equals family name, e.g. "Inter-Bold")
- value: `{ family, source, uri?, zipPath?, url?, weight?, style?, format? }`
Rules:
- `source: 'custom'` → user-uploaded font, file lives at `assets/fonts/`, referenced by `zipPath`
- `source: 'builtin'` → CDN font, referenced by `url`
- Same family may have multiple weight/style variants (different keys)
- **[FORBIDDEN]** Agent adding new `font.assets` entries (font upload is done by frontend GUI)
- **[FORBIDDEN]** Agent deleting `font.assets` entries
- **[FORBIDDEN]** Agent modifying existing `font.assets` entries
---
## `shadow` — Shadow Tokens (structured objects)
Structure: `Record<string, ShadowTokenValue | MultiLayerShadow>`
Single-layer shadow (flat object):
```json
{
"shadow": {
"<token-name>": {
"xOffset": "<value>",
"yOffset": "<value>",
"blur": "<value>",
"spread": "<value>",
"color": { "hex": "#000000", "opacity": "0.12" }
}
}
}
```
Multi-layer shadow (when CSS defines comma-separated layers):
```json
{
"shadow": {
"<token-name>": {
"layers": [
{ "xOffset": "0px", "yOffset": "2px", "blur": "4px", "spread": "0px", "color": { "hex": "#000000", "opacity": "0.08" } },
{ "xOffset": "0px", "yOffset": "1px", "blur": "2px", "spread": "0px", "color": { "hex": "#000000", "opacity": "0.04" } }
]
}
}
}
```
### Example
```json
{
"shadow": {
"shadow-1·Card": { "xOffset": "0px", "yOffset": "1px", "blur": "2px", "spread": "0px", "color": { "hex": "#000000", "opacity": "0.05" } },
"shadow-2·Card Hover": { "xOffset": "0px", "yOffset": "2px", "blur": "4px", "spread": "0px", "color": { "hex": "#000000", "opacity": "0.08" } },
"shadow-3·Float": { "layers": [{ "xOffset": "0px", "yOffset": "4px", "blur": "8px", "spread": "0px", "color": { "hex": "#000000", "opacity": "0.1" } }, { "xOffset": "0px", "yOffset": "2px", "blur": "4px", "spread": "0px", "color": { "hex": "#000000", "opacity": "0.04" } }] },
"shadow-4·Modal": { "xOffset": "0px", "yOffset": "8px", "blur": "16px", "spread": "0px", "color": { "hex": "#000000", "opacity": "0.12" } }
}
}
```
**Shadow key naming**: When CSS shadow variables have inline comments describing usage (e.g., `--shadow-2: ...; /* Card Hover */`), `css-to-json.mjs` constructs the JSON key as `{varName}·{annotation}`. If no annotation is present, the key is just the CSS variable name (e.g., `shadow-2`).
---
## `radius` — Border Radius Tokens
Structure: `Record<string, string>` — values in px units.
### Example
```json
{
"radius": {
"radius-none": "0px",
"radius-small": "4px",
"radius-medium": "8px",
"radius-large": "12px",
"radius-circle": "99px",
"radius-base": "4px"
}
}
```
---
## `spacing` — Spacing Tokens (independent)
Structure: `Record<string, string>` — values in px units. Contains only spacing scale tokens (`space-*`).
### Example
```json
{
"spacing": {
"space-0": "0px",
"space-1": "4px",
"space-2": "8px",
"space-3": "12px",
"space-4": "16px",
"space-5": "20px",
"space-6": "24px",
"space-7": "28px",
"space-8": "32px",
"space-9": "36px",
"space-10": "40px"
}
}
```
---
## `size` — Component Size / Layout Tokens
Structure: `Record<string, string>` — values in px units. Contains component dimension tokens (`size-*`) and layout constraints. Does NOT contain spacing tokens (those belong in `spacing`).
### Example
```json
{
"size": {
"size-button-height": "40px",
"size-input-height": "40px",
"size-icon-sm": "16px",
"size-icon-md": "24px"
}
}
```
---
## Requirements Checklist
- [ ] Valid JSON (parseable, no comments in output)
- [ ] Contains all 6 top-level keys: `color`, `font`, `shadow`, `radius`, `spacing`, `size`
- [ ] Each top-level value is a JSON object (not null/string/array)
- [ ] ALL color values use `{ "hex": "...", "opacity": "..." }` format
- [ ] Hex values are 6-digit lowercase with `#` prefix
- [ ] Opacity values are strings
- [ ] All values in `spacing`, `size`, `radius`, `font.size` MUST have px suffix (including zero: `"0px"` not `"0"`)
- [ ] No placeholder values ("TODO", empty strings, null)
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 |