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

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)
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