npm package: @gadsai/tokens
Description: GADS Design System — design tokens, primitives, typography and component definitions
Latest version: 3.2.1

# GADS Token — Design System Package

The official NPM package and Figma plugin for the **GADS Design System**.  
Exports design tokens, typography, primitives, and full component definitions directly from Figma — structured for AI tooling, code generation, and Storybook.

**Schema version: 3.1** · **87 components · 710 variants**

---

## Installation

```bash
npm install @gadsai/tokens
```

---

## Package contents

The package ships six JSON artifacts in `dist/`. Import only what you need:

| Import path | File | What it contains |
|---|---|---|
| `@gadsai/tokens/primitives` | `primitives.json` | Raw design primitives: spacing scale, color values, radius values |
| `@gadsai/tokens/color-tokens` | `color-tokens.json` | Semantic color tokens with per-mode resolved hex values and alias chains |
| `@gadsai/tokens/typography` | `typography.json` | Text styles: fontFamily, fontWeight, fontSize, lineHeight, CSS-mapped enums |
| `@gadsai/tokens/components-contract` | `components.contract.json` | Component identity, props schema, variant axes, slots, token references |
| `@gadsai/tokens/components-visuals` | `components.visuals.json` | Per-variant rendering data: fills, strokes, effects, radii, children tree |
| `@gadsai/tokens/components-full` | `components.full.json` | Contract + visuals combined in a single file |

---

## Usage

### ES modules / bundlers

```js
import contract   from '@gadsai/tokens/components-contract'
import visuals    from '@gadsai/tokens/components-visuals'
import tokens     from '@gadsai/tokens/color-tokens'
import typo       from '@gadsai/tokens/typography'
import primitives from '@gadsai/tokens/primitives'
```

### Node.js (CommonJS)

```js
const contract = require('@gadsai/tokens/components-contract')
const visuals  = require('@gadsai/tokens/components-visuals')
```

### For AI tools / LLM prompts

Pass the contract file for component API lookups (lightweight, fits in context).  
Pass a single component's visuals slice for rendering/styling tasks.

---

## The two component files — how they work together

### `components.contract.json` — the schema layer

Answers: *"What is this component? What are its props and variants?"*

Contains per component:
- `canonicalName` — stable path-based identifier (e.g. `Buttons/Button::Button`)
- `variantAxes` — all variant dimensions and their values (e.g. `Style: [Primary, Secondary, Ghost]`)
- `propsSchema` — full Figma component property definitions
- `slots` — exposed child slots
- `tokenRefs` — which design tokens are bound, with token names and resolved values
- `textStyleRefs` — which typography styles are applied
- `layout` — component-set-level auto layout summary
- `dependencies` — which other components are used internally

Use this for: Storybook `argTypes`, prop type generation, AI component lookups, documentation.

### `components.visuals.json` — the rendering layer

Answers: *"How does each variant of this component actually look?"*

Contains per variant (all 710 across 87 components):
- `fills` — background paints: SOLID colors, gradients (linear/radial/angular/diamond), images
- `strokes` — border paints with weight, align, dash pattern
- `cornerRadius` — uniform or per-corner (topLeft / topRight / bottomLeft / bottomRight)
- `effects` — drop shadows, inner shadows, layer blurs (color, offset, radius, spread)
- `opacity`, `blendMode`, `visible`
- `size` — explicit width/height
- `layout` — per-variant auto layout (direction, padding, spacing, alignment, sizing modes)
- `tokenRefs` — token bindings with `variableName` and `resolvedValue` inline
- `children` — recursive node tree to **depth 5** with full visual data on every node

Use this for: CSS-in-JS generation, Storybook visual stories, style dictionaries, AI rendering prompts.

### Together they cover 100% of what's needed to render a component

```
contract  →  knows Button has Style=Primary|Secondary|Ghost, Label prop, Size=Default|Small
visuals   →  knows Primary/Default has fill #5692cd, cornerRadius 10, padding 16px, white label text
```

---

## Color tokens

`color-tokens.json` contains semantic tokens with:
- Token name and alias chain
- `resolvedByMode` — hex value resolved per light/dark mode
- Collection name and variable ID for cross-referencing

`primitives.json` contains the raw base values the tokens alias into (spacing scale, radius values, raw color palette).

---

## Typography

`typography.json` contains all text styles normalized to CSS:
- `fontFamily`, `fontWeight` (numeric: 400, 700 etc.), `fontStyle` (`normal` / `italic`)
- `fontSize`, `lineHeight`, `letterSpacing`
- `textTransform`, `textDecoration` (CSS-mapped values)
- `fills` — text color paints

---

## Schema version

All artifacts carry `meta.schemaVersion: "3.1"` and `meta.exportLevel`.

| `exportLevel` | Files produced |
|---|---|
| `contract` | `components.contract.json` |
| `visual` | `components.visuals.json` |
| `full` | Both + `components.full.json` |

---

## Figma Plugin

The plugin is part of this repo (`code.js` + `ui.html`). It syncs all artifacts directly to GitHub via a middle-layer API and allows per-artifact downloads.

**Network access:** `https://gads-sync.vercel.app`

To rebuild the `dist/` folder after a fresh export:

```bash
npm run bundle-dist
```

To publish a new version to NPM:

```bash
npm version patch   # or minor / major
npm publish
```

`prepublishOnly` runs `bundle-dist` automatically before every publish.

---

## Changelog

### 3.1.1
- Skip `fontFamily` and `fontStyle` from tokenRefs (not design tokens)
- New validation warning: `primitiveColourBindings` — flags components bound directly to primitive colour tokens instead of semantic tokens

### 3.1.0
- Split component export into `components.contract.json` + `components.visuals.json`
- `components.full.json` replaces the legacy combined file
- Recursive child node traversal to depth 5 in visuals
- Per-variant auto layout, effects, gradient/image paints, per-corner radii
- `tokenRefs` now include `variableName`, `collectionName`, `resolvedValue`
- Color tokens: per-mode resolved hex values
- Typography: CSS-normalized font weight, text-transform, text-decoration
- Export levels: `contract` | `visual` | `full`

### 3.0.0
- Initial component contract export with variant visual data
- Design token primitives and semantic color tokens
- Typography text styles