---
title: Spec
description: Document your design system in Bamboo.
---

A spec is a readable JSON representation of the theme structure in your bamboo config. They're designed to be used for
**documentation purposes** in your own docs websites and Storybook. Some common use cases:

- Document tokens in your theme (colors, spacing, fonts, etc.)
- Showcase the recipes and slot recipes (include their variants and default variants)
- Document the typography styles and layer styles

## Spec Command

To create the spec files, run the following command in your terminal:

```bash
pnpm bamboo spec
```

Learn more about the spec CLI flags [here](/docs/references/cli#spec)

## Spec Output

The spec command generates a set of JSON files that represent your entire design system. Here's an example of the output
structure:

```sh
styled-system/
└── specs/                        # Generated documentation-ready spec files
    ├── color-palette.json        # List of palette names (blue, teal, etc.) — conditional
    ├── conditions.json           # Condition selectors (_hover, _focus, ...)
    ├── keyframes.json            # Keyframe definitions (spin, ping, ...)
    ├── patterns.json             # Pattern definitions + their properties
    ├── recipes.json              # Component recipes + variants + defaults
    ├── semantic-tokens.json      # Semantic tokens with conditions (base, dark, etc.)
    ├── mixins.json               # Named style bundles (body, heading.h1, offShadow, ...)
    ├── themes.json               # Per-theme tokens and semantic tokens — conditional
    └── tokens.json               # Raw design tokens grouped by category
```

`color-palette.json` and `themes.json` are only written when there is something to write: the first when the theme
defines at least one color palette and `theme.colorPalette.enabled` is not `false`, the second when `themes` is
non-empty. The other nine are always emitted, with an empty `data` array if nothing is configured.

Below is a breakdown of what each file contains and how it can be used.

### `tokens.json`

#### Structure

This file contains an array of raw design tokens grouped by category

```json
{
  "type": "tokens",
  "data": [
    {
      "type": "colors",
      "values": [
        {
          "name": "purple.800",
          "value": "#6b21a8",
          "cssVar": "var(--colors-purple-800)"
        }
      ],
      "tokenFunctionExamples": ["token('colors.purple.800')", "token.value('colors.purple.800')"],
      "functionExamples": ["css({ color: 'purple.800' })"]
    }
  ]
}
```

Each token in the `values` array includes:

- **name**: token key (e.g., 2xs, md, primary)
- **value**: resolved CSS value (e.g., "1rem", "#F6E458")
- **cssVar**: the generated CSS custom property
- **tokenFunctionExamples**: examples of how to use the token in the `token` function
- **functionExamples**: examples of how to use the token in the `css` function

#### Usage

Here's an example of how to document color tokens:

```tsx
import { grid } from 'styled-system/patterns'
import tokens from 'styled-system/specs/tokens.json'

const Demo = () => {
  const colors = tokens.data.find((token) => token.type === 'colors')
  return (
    <div className={grid({ padding: '40px', columns: 3, gap: '4' })}>
      {colors?.values.map((color) => (
        <div key={color.name}>
          <p>{color.name}</p>
          <p>{color.value}</p>
          <div
            style={{
              width: '100px',
              height: '100px',
              background: color.value,
              border: '1px solid lightgray',
            }}
          />
        </div>
      ))}
    </div>
  )
}
```

Your color token documentation should look similar to this:

![Token Spec Documentation](/token-spec.png)

### `semantic-tokens.json`

#### Structure

This file contains an array of semantic token definitions grouped by category, with conditional values for different
modes (e.g., light/dark).

```json
{
  "type": "semantic-tokens",
  "data": [
    {
      "type": "colors",
      "values": [
        {
          "name": "bg",
          "values": [
            { "value": "token(colors.white)", "condition": "base" },
            { "value": "token(colors.dark)", "condition": "dark" }
          ],
          "cssVar": "var(--colors-bg)"
        }
      ],
      "tokenFunctionExamples": ["token('colors.bg')", "token.value('colors.bg')"],
      "functionExamples": ["css({ color: 'bg' })"]
    }
  ]
}
```

Each semantic token in the `values` array includes:

- **name**: the semantic token key (e.g., `bg`, `fg.muted`, `accent`)
- **values**: an array of conditional mappings, each with:
  - **value**: the resolved token reference (e.g., `token(colors.white)`)
  - **condition**: the condition name (e.g., `base`, `dark`)
- **cssVar**: the generated CSS custom property
- **tokenFunctionExamples**: examples of how to use the token in the `token` function
- **functionExamples**: examples of how to use the token in the `css` function

### `recipes.json`

#### Structure

This file contains an array of recipe definitions for styling components with variant support.

```json
{
  "type": "recipes",
  "data": [
    {
      "name": "button",
      "description": "A button style",
      "variants": {
        "shape": ["square", "circle"],
        "color": ["main", "black", "white"],
        "size": ["sm", "md", "lg"]
      },
      "defaultVariants": {
        "shape": "square",
        "color": "main",
        "size": "md"
      },
      "functionExamples": ["button({ shape: 'square' })", "button({ color: 'main' })", "button({ size: 'sm' })"]
    }
  ]
}
```

Each recipe in the `data` array includes:

- **name**: the recipe name (e.g., `button`, `card`)
- **description**: optional description of what the recipe does
- **variants**: an object where each key is a variant name and each value is an array of allowed options
- **defaultVariants**: an object defining the default option for each variant
- **functionExamples**: examples of how to use the recipe function

#### Usage

Here's an example of how to document a button recipe within a table:

```tsx
import recipes from 'styled-system/specs/recipes.json'

const Demo = () => {
  const buttonRecipe = recipes.data.find((recipe) => recipe.name === 'button')
  const defaultVariants = buttonRecipe?.defaultVariants || {}

  return (
    <div>
      <h2>{buttonRecipe?.name}</h2>
      {buttonRecipe?.description && <p>{buttonRecipe.description}</p>}
      <table>
        <thead>
          <tr>
            <th>Variant</th>
            <th>Options</th>
            <th>Default</th>
          </tr>
        </thead>
        <tbody>
          {Object.entries(buttonRecipe?.variants || {}).map(([key, options]) => (
            <tr key={key}>
              <td>{key}</td>
              <td>
                {(options as string[]).map((option) => (
                  <span key={option}>{option}</span>
                ))}
              </td>
              <td>{defaultVariants[key as keyof typeof defaultVariants] || 'none'}</td>
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  )
}
```

Your button recipe documentation should look similar to this:

![Recipe Spec Documentation](/recipe-spec.png)

### `color-palette.json`

Contains a list of all color names defined in your palette.

- `values` – an array of color keys (e.g., `"blue"`, `"teal"`, `"pink"` and more).
- Does not contain the color scales (e.g., 500, 600); it only lists the available palette names.
- `functionExamples` – examples of how to use `colorPalette` in the `css` function

This file is only written when the theme has at least one color palette and `theme.colorPalette.enabled` is not `false`.

### `mixins.json`

#### Structure

This file contains an array of the named style bundles the theme declares.

```json
{
  "type": "mixins",
  "data": [
    {
      "name": "offShadow",
      "functionExamples": ["css({ mixin: 'offShadow' })"]
    }
  ]
}
```

Each mixin in the `data` array includes:

- **name**: the mixin name, dotted for a nested one (e.g., `body`, `heading.h1`, `offShadow`)
- **description**: optional description of the bundle
- **functionExamples**: examples of how to apply it in the `css` function

The declarations themselves are not part of the spec. If no mixins are configured in your `bamboo.config.ts` file, this
file will contain an empty data array.

### `keyframes.json`

#### Structure

This file contains an array of keyframe definitions for CSS animations.

```json
{
  "type": "keyframes",
  "data": [
    {
      "name": "spin",
      "functionExamples": ["css({ animationName: 'spin' })", "css({ animation: 'spin 1s ease-in-out infinite' })"]
    }
  ]
}
```

Each keyframe in the `data` array includes:

- **name**: the keyframe name (e.g., `spin`, `ping`, `pulse`, `bounce`, `fade-in`)
- **functionExamples**: examples of how to use the keyframe in the `css` function

### `patterns.json`

#### Structure

This file contains an array of pattern definitions for layout utilities.

```json
{
  "type": "patterns",
  "data": [
    {
      "name": "flex",
      "properties": [
        { "name": "align", "type": "SystemProperties[\"alignItems\"]" },
        { "name": "justify", "type": "SystemProperties[\"justifyContent\"]" },
        { "name": "direction", "type": "SystemProperties[\"flexDirection\"]" }
      ],
      "functionExamples": ["flex({ align: 'center' })", "flex({ justify: 'space-between' })"]
    }
  ]
}
```

The `properties` array above is abridged — `flex` has seven.

Each pattern in the `data` array includes:

- **name**: the pattern function name (e.g., `flex`, `grid`, `center`, `container`)
- **properties**: an array of pattern-specific props, each with:
  - **name**: the prop name (e.g., `align`, `justify`, `gap`)
  - **type**: the TypeScript type for the prop
  - **defaultValue**: optional default value for the prop
- **functionExamples**: examples of how to use the pattern function

#### Usage

Here's an example of how to document patterns with their properties:

```tsx
import patterns from 'styled-system/specs/patterns.json'

const Demo = () => {
  return (
    <div>
      {patterns.data.map((pattern) => (
        <div key={pattern.name}>
          <h3>{pattern.name}</h3>
          {pattern.properties.length > 0 && (
            <table>
              <thead>
                <tr>
                  <th>Prop</th>
                  <th>Type</th>
                  <th>Default</th>
                </tr>
              </thead>
              <tbody>
                {pattern.properties.map((prop) => (
                  <tr key={prop.name}>
                    <td>{prop.name}</td>
                    <td>{prop.type}</td>
                    <td>{prop.defaultValue || '—'}</td>
                  </tr>
                ))}
              </tbody>
            </table>
          )}
        </div>
      ))}
    </div>
  )
}
```

### `conditions.json`

Contains an array of condition entries. Each entry includes:

- `name` – the condition key used in style objects (e.g.,`_hover`, `_focus`, `_focusWithin`)
- `value` – the CSS selector or media query that the condition maps to
- `functionExamples` – examples of how to use the condition in the `css` function

### `themes.json`

Contains one entry per theme declared in `themes`. Each entry includes:

- `name` – the theme key
- `tokens` – the token groups the theme overrides, in the same shape as `tokens.json`
- `semanticTokens` – the semantic token groups the theme overrides, in the same shape as `semantic-tokens.json`

## FAQs

### Can I edit the spec files directly?

**No.** The spec files are **generated** files–you should **not** edit your design tokens, recipes, or theme directly in
these files. All configuration changes must be made in your `bamboo.config.ts` file. The spec files exist purely for
documentation and visualization purposes.
