Token format

Windcraft uses the W3C Design Tokens Community Group format. Every token is an object with $value and $type; groups are nested objects.

Categories

Eight built-in $types in V1:

color | dimension | fontFamily | fontWeight | fontSize | shadow | lineHeight | letterSpacing

Example

{
  "$schema": "https://design-tokens.github.io/community-group/format/",
  "color": {
    "primary": { "$value": "#007AFF", "$type": "color" },
    "neutral": {
      "50":  { "$value": "#FAFAFA", "$type": "color" },
      "900": { "$value": "#1C1C1E", "$type": "color" }
    }
  },
  "spacing": {
    "1": { "$value": "4px",  "$type": "dimension" },
    "2": { "$value": "8px",  "$type": "dimension" },
    "4": { "$value": "16px", "$type": "dimension" }
  },
  "fontFamily": {
    "sans": { "$value": ["SF Pro Text", "Inter", "system-ui"], "$type": "fontFamily" }
  },
  "radius": {
    "card":   { "$value": "12px", "$type": "dimension" },
    "button": { "$value": "8px",  "$type": "dimension" }
  }
}

Aliases

Tokens can reference other tokens. The sync engine resolves them recursively before generation, so downstream files only see concrete values.

{
  "color": {
    "brand": { "primary": { "$type": "color", "$value": "#5b21b6" } },
    "button": {
      "background": { "$type": "color", "$value": "{color.brand.primary}" }
    }
  }
}

What gets generated

From the same source, windcraft sync writes:

• tailwind.config.ts — extends theme with token names that resolve to CSS variables
• app/globals.css — :root { … } block with the actual values
• theme.ts — RN-flavored object with numeric dimensions
• windcraft.types.d.ts — TypeScript token name unions
• .claude/skills/windcraft.md — Claude Code skill summary

Versioning

Every PUT or PATCH to /projects/:id/tokens creates a new immutable row. Restore an older version from the editor sidebar. Diff any two versions (added / removed / changed) from the version history button.

Editing

In the dashboard token editor:

• Color: native picker plus HEX / RGB / HSL tabs per token
• Spacing / radius / fontSize / lineHeight / letterSpacing: drag-to-reorder
• Shadow: structured offset / blur / spread / color, with string fallback for multi-stop shadows
• JSON export: download tokens-vN.json directly