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

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

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)

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:

npm run bundle-dist

To publish a new version to NPM:

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