# Tokens To Components

> Generate a full design component library from DTCG design tokens. Use this skill when the user has design tokens (from the painting-to-m3 or painting-to-theme skills, from Tokens Studio, from any DTCG JSON file, or from a CSS variables file) and wants to generate UI components, a component library, or a design system implementation from them. Triggers on phrases like "build components from these…

- **Type:** Skill
- **Install:** `agentstack add skill-peiqingzhang-art-inspired-design-system-for-ai-tokens-to-components`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [peiqingzhang](https://agentstack.voostack.com/s/peiqingzhang)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [peiqingzhang](https://github.com/peiqingzhang)
- **Source:** https://github.com/peiqingzhang/art_inspired_design_system_for_AI/tree/main/skills/tokens-to-components

## Install

```sh
agentstack add skill-peiqingzhang-art-inspired-design-system-for-ai-tokens-to-components
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Tokens to Components

Generate a complete, production-ready component library from DTCG design tokens. The output is a set of React components styled entirely by the token system.

## Why this matters

Design tokens alone don't ship products — components do. This skill bridges the gap between a token JSON file and actual usable UI. Every color, font, radius, and spacing value in the output traces back to a named token, so changing a token cascades everywhere. No magic numbers, no hardcoded hex values.

## Prerequisites

This skill expects design tokens in one of these formats:
1. **DTCG JSON** (`.tokens.json` files) — preferred, output by the `painting-to-m3` or `painting-to-theme` skills
2. **CSS custom properties** (`theme.css` file with `--color-*` variables)
3. **Raw JSON** with at minimum: primary/secondary/tertiary colors, font names, spacing scale

If the user doesn't have tokens yet, suggest the `painting-to-m3` skill (strict M3) or `painting-to-theme` skill (expressive/painting-faithful) first.

## Step 0: Check for Design Brief

Before parsing tokens, check if a `design-brief.md` file exists in the token directory or its sibling review directory:

```bash
ls /tokens/design-brief.md   # before review files are moved
ls /review/design-brief.md   # after review files are moved
```

If found, read it. Extract:
- **Theme name** — use in preview HTML title, README heading, and component output directory name
- **Mood** — reference in preview page subtitle and README description
- **Design intent** — use as the README's introductory sentence
- **Intended use case** — helps decide which component preset to recommend in Step 2

The design brief is the handoff contract from the `painting-to-m3` or `painting-to-theme` skill. It carries the reasoning behind the token choices that is not visible in raw JSON. Using it makes your component output more coherent with the design intent.

Also check for a **Painting Color Proportions** section in the brief. When proportions are present, the token system has already tinted surface/neutral palettes to match the dominant painting color's atmospheric presence. The preview HTML will automatically render a proportion bar showing the painting's color balance alongside the components, helping users see the visual connection between their source painting and the generated UI.

## Workflow Overview

```
Tokens → Parse → Generate Component CSS → Build React Components → Present to User
```

## Step 1: Parse the Tokens

Read the token files and resolve all aliases to concrete values. Build an internal lookup:

```
resolved = {
  "color.sys.light.primary": "#5c5ea1",
  "color.sys.light.on-primary": "#ffffff",
  ...
  "typography.sys.body-large.fontFamily": "Source Serif 4",
  "typography.sys.body-large.fontSize": "16px",
  ...
  "shape.corner.medium": "12px",
  "spacing.4": "16px",
  ...
}
```

Use the parsing script at `scripts/parse_tokens.py` to do this:

```bash
python scripts/parse_tokens.py --token-dir ./themes/{painting-name}/{variant}/tokens/ --output ./themes/{painting-name}/{variant}/tokens/resolved.json
```

Optionally, pass `--css` to also output CSS custom properties directly.

## Step 2: Ask the Human What They Need

Before generating 25 components the user doesn't need, ask:

1. **What kind of project?** This determines which components to prioritize.
   - Web app / dashboard → buttons, cards, inputs, tables, navigation, dialogs
   - Marketing site → hero sections, CTAs, testimonial cards, feature grids
   - Mobile-first → bottom sheets, FABs, compact cards, swipe actions
   
2. **Which component set?** Offer these presets:
   - **Core** (always recommended): Button, Card, Input, Chip, Badge, Avatar, Divider
   - **Navigation**: AppBar, Tabs, Sidebar, Breadcrumb, Bottom Navigation
   - **Data**: Table, List, DataCard, Stat
   - **Feedback**: Dialog, Snackbar, Tooltip, Progress, Skeleton
   - **Layout**: Container, Grid, Stack, Surface
   - **All** — generates everything

3. **TypeScript or JavaScript?**
   - **TypeScript** (default for new projects) — generates `.tsx` files with `Props` interfaces, typed sub-components, and `index.ts`
   - **JavaScript** — generates `.jsx` files with `index.js`

4. **Storybook?**
   - Yes — generates `[Component].stories.tsx` alongside each component, with named exports per variant
   - No (default) — skip story files

5. **Framework target?**
   - React + Tailwind (default — generates .tsx/.jsx with CSS variables mapped to tokens)
   - React + CSS Modules (generates component + .module.css)
   - Plain HTML + CSS (generates .html + .css)

## Step 3: Generate the Component Library

For each component, follow this pattern:

### Component Generation Rules

1. **Token-first styling**: Every visual property MUST reference a token. Never hardcode:
   - Colors → `var(--color-*)` from color tokens
   - Font → `var(--font-brand)` / `var(--font-plain)` from typography tokens
   - Radius → `var(--radius-*)` from shape tokens
   - Spacing → `var(--spacing-*)` from spacing tokens

2. **M3 component anatomy**: Follow Material Design 3 component specs:
   - Button: container + label + optional icon, uses primary/onPrimary roles
   - Card: surface container + content area, uses surface-container roles  
   - Input: container + label + supporting text, uses outline/surface-variant roles
   - etc.

3. **Variants per component**: Generate at minimum:
   - **Filled** variant (uses primary container color)
   - **Outlined** variant (uses outline color with transparent fill)
   - **Text/Tonal** variant (uses primary-container with on-primary-container text)

4. **State layers**: All interactive components include M3 state layers via `.m3-interactive` + `.state-layer` CSS classes defined in `theme.css`. Do not use `filter: brightness()` as a substitute. The state layer is a `` inside a `position: relative` container:
   - Hover: 8% opacity
   - Focus-visible: 12% opacity
   - Pressed (active): 12% opacity
   - Disabled: no overlay (component uses 38% opacity on content instead)

5. **Accessibility**: All interactive components MUST meet WCAG 2.1 AA keyboard accessibility:
   - Focusable via Tab (`tabIndex={0}` on non-native-interactive elements)
   - Activatable via Enter/Space (`onKeyDown` handler)
   - Correct ARIA roles (`role="option"` for chips, `role="article"` for cards, etc.)
   - Proper label associations (`htmlFor`/`id` pairing for inputs)
   - `aria-invalid`, `aria-describedby` for form elements
   - `aria-label` on icon-only elements (badges, avatars)

### Component Templates

Read the component templates in `references/component-specs.md` for detailed specifications of each M3 component's anatomy, variants, and token mappings.

## Step 4: Generate the Output Files

### For React + Tailwind (default)

Run the script:

```bash
python scripts/generate_components.py \
  --resolved-tokens ./themes/{painting-name}/{variant}/tokens/resolved.json \
  --output-dir ./themes/{painting-name}/{variant}/components \
  --review-dir ./themes/{painting-name}/{variant}/review \
  --theme-name "Van Gogh — Green Wheat Fields" \
  --sets all \
  [--no-typescript]              # default is TypeScript on
  [--storybook]                  # off by default
```

**CLI parameters:**
- `--resolved-tokens` (required): Path to resolved.json from parse_tokens.py
- `--output-dir`: Component output directory (default: `./components`)
- `--review-dir`: Directory for preview.html and README.md (defaults to `--output-dir`)
- `--theme-name`: Theme name used in README and preview title
- `--sets`: Comma-separated set names (`core`, `navigation`, `data`, `feedback`, `layout`) or `all` (default: `core`)
- `--components`: Optional comma-separated individual component names, merged with `--sets`
- `--no-typescript`: Generate plain .jsx files instead of TypeScript
- `--storybook`: Generate .stories.tsx files for each component

The script automatically generates all output: component files, theme.css, index.ts, preview.html, and README.md. Review files (preview.html, README.md) go to `--review-dir` when specified.

If the script is unavailable, generate the preview HTML manually following the template in `references/preview-template.html`.

## Step 5: Present and Iterate

Show the user:
1. The preview HTML (render it or share the file)
2. A summary: "Generated X components with Y variants using your [theme name] tokens"
3. The component files ready for download, including `README.md`
4. If Storybook was generated, note which story files were created

Ask:
- Do the components feel right with these colors and typography?
- Any components you want to add or modify?
- Should I adjust any token mappings (e.g., make cards use a different surface level)?
- Do you want Storybook stories generated for any components?

## Reference Files

- `references/component-specs.md` — Detailed M3 component anatomy and token mappings
- `scripts/parse_tokens.py` — Token parser and alias resolver
- `references/preview-template.html` — Fallback template for preview.html if the script is unavailable
- `scripts/generate_components.py` — Component code generator (also generates preview.html and README.md)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [peiqingzhang](https://github.com/peiqingzhang)
- **Source:** [peiqingzhang/art_inspired_design_system_for_AI](https://github.com/peiqingzhang/art_inspired_design_system_for_AI)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-peiqingzhang-art-inspired-design-system-for-ai-tokens-to-components
- Seller: https://agentstack.voostack.com/s/peiqingzhang
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.