Add a Token

Steps

1. Determine the layer

Layer	When to use	Example
Primitive	New color palette value, spacing step, or font property	`color.purple.400`
Semantic	New functional alias that maps to a primitive	`color.status-info`
Component	Token scoped to a specific component	`badge.bg`

2. Add to source JSON

Edit the appropriate file in packages/tokens/src/:

src/
├── primitives/
│   ├── color.json      ← palette colors
│   ├── spacing.json    ← spacing scale
│   ├── radius.json     ← border radius
│   └── ...
├── semantic/
│   ├── color.json      ← functional color aliases
│   ├── elevation.json  ← box shadows
│   └── typography.json ← composite type styles
└── component/
    ├── button.json
    ├── card.json
    └── input.json

For color tokens, provide both oklch and hex values:

{
  "purple": {
    "400": {
      "$type": "color",
      "$value": {
        "oklch": "0.68 0.17 300",
        "hex": "#A77BDB"
      }
    }
  }
}

3. Build and verify

pnpm build
pnpm test:parity   # verify oklch ↔ hex parity

4. Check outputs

CSS: dist/css/tokens.css
Dart: dist/dart/verdanta_tokens.dart
Figma: dist/figma/variables.verdanta.json

5. Brand overrides (if needed)

If GetPlants needs a different value for this token (semantic or component only):

Add the override in src/brands/getplants.json
Rebuild: pnpm build
Verify: dist/css/getplants.css and dist/figma/variables.getplants.json

6. Update docs

node packages/tokens/scripts/docs.mjs

This regenerates the Token Reference page.

7. Push to Figma (optional)

pnpm figma:sync:dry   # preview changes
pnpm figma:sync        # push to Figma