npm package: @gabardiles/ga-ds
Description: GA Design System – tokens, primitives, typography and component catalogue
Latest version: 1.1.0

# 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

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

---

## Usage

### Import everything
```ts
import {
  colorTokens,
  colorPrimitives,
  textStyles,
  toCSS,
  componentCatalogue,
  allowedComponents,
} from '@gabardiles/ga-ds'
```

### Cherry-pick sub-modules
```ts
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)
```css
@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:

```ts
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)

```bash
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.