GADS Design System

GADS Design System (this repo: gads-design-system) is the GA Design System token package plus an upload/compare app for Figma exports. Single source of truth for colors, typography, and component definitions.

Exported from Figma via plugin. Published as the npm package @gabardiles/ga-ds so any downstream tool (Storybook, Governor, AI Builder, Figma Make, apps) can import from the same versioned baseline.

What’s in this repo

| Part | Purpose | |------|--------| | Package (src/, dist/) | Design tokens, primitives, typography, component catalogue → published to npm as @gabardiles/ga-ds | | Upload app (apps/upload/) | Web UI to upload Figma export, compare with current tokens, and apply updates to src/tokens/ |

Upload app (update tokens from Figma)

1. Export from Figma (plugin) → save e.g. components_v5.json.
2. In this repo: cd apps/upload && npm install && npm run dev → open http://localhost:5174.
3. On the page: click Load current from repo, then Choose file and select your export. Review the compare.
4. Click Apply to repo to write the new file into src/tokens/components_v5.json.
5. In the repo root: npm run build, npm run validate, then commit, push, and npm publish (see full steps on the upload page).

Install the package

npm install @gabardiles/ga-ds
# or
yarn add @gabardiles/ga-ds

Usage

Import everything

import {
  colorTokens,
  colorPrimitives,
  textStyles,
  toCSS,
  componentCatalogue,
  allowedComponents,
} from '@gabardiles/ga-ds'

Cherry-pick sub-modules

import { colorTokens }      from '@gabardiles/ga-ds/tokens'
import { colorPrimitives }  from '@gabardiles/ga-ds/primitives'
import { textStyles, toCSS } from '@gabardiles/ga-ds/typography'
import { componentCatalogue, allowedComponents } from '@gabardiles/ga-ds/components'

CSS custom properties (in your global stylesheet)

@import '@gabardiles/ga-ds/css';

/* Then use anywhere: */
.my-button {
  background: var(--surface-accent);
  color: var(--text-primary-inverse);
}

What's inside

| Export | Description | |---|---| | colorPrimitives | Raw hex values grouped by color scale (gray, blue, red…) | | overlayPrimitives | Dark/light overlay tokens with alpha values | | colorTokens | Semantic tokens resolved to hex (surface-, text-, border-, icon-) | | textStyles | 21 text style definitions (family, size, weight, lineHeight…) | | toCSS(style) | Convert a TextStyle to a CSS-in-JS object | | componentCatalogue | 123 component definitions grouped by section (29 groups) | | allowedComponents | Flat list of allowed component names – used by the Governor | | dist/tokens.css | All tokens as CSS custom properties |

Governor usage

The Governor can import this package to validate any design output:

import { allowedComponents, colorTokens } from '@gabardiles/ga-ds'

// Is this component allowed?
const isValid = allowedComponents.includes(componentName)

// Is this color token valid?
const tokenExists = componentName in colorTokens

Scripts (package root)

npm run validate   # Validates all token references & checks for issues
npm run build      # Builds dist/ (run after any JSON changes)

Updating (manual alternative to upload app)

1. Export fresh JSONs from the Figma plugin
2. Replace files in src/tokens/ (or use the upload app)
3. Run npm run validate – fix any warnings
4. npm run build
5. Bump version and publish

Known issues

• icon-surface-bold is unresolved in Figma (missing source token). Set to UNRESOLVED in the package until fixed in the DS file.
• 16 components have duplicate canonical names from Figma (validator warns but does not block). Fix by renaming in Figma.