AD Tokens

Token Transformer + versioning layer for the AD Design System. It ingests unversioned exports from ad-tokens-raw (Token Studio data storage), converts them into typed, Tamagui-ready themes/token maps, and produces versioned releases.

Not a primary entrypoint. Most developers should not depend on this package directly. In apps, use the ad library and its useTokens() hook for dynamic, theme-aware tokens.

Role in the system (at a glance)

• Source of truth: ad-tokens-raw (Token Studio raw data, unversioned)
• Transform + version: ad-tokens (this repo)
• Consumption: ad (main DS library; useTokens() provides dynamic, typed tokens)

What this repo does

• Pulls raw JSON from ad-tokens-raw
• Generates foundation + semantic token maps
• Compiles themes (e.g. light, dark, light-chrome, dark-chrome)
• Emits typed token references and Tamagui-compatible theme objects
• Builds ESM + CJS bundles with .d.ts types

Note on dynamics: imports from this repo are static (compile-time). If you need runtime theme switching (SSR-friendly, media-query aware), use useTokens() from ad.

Installation

Currently not on NPM registry. Use .tgz file in root for now.

Once released:

npm install @l.hawkins/ad-tokens

Exports (API surface)

From ad-tokens you get:

import { staticTamaguiTokens, tokens } from "@l.hawkins/ad-tokens";
// and types:
import type {
  ColorTokensType,
  SpacingTokensType,
  FoundationTokensType,
  TypographyTokensType,
} from "@l.hawkins/ad-tokens";

Inside staticTamaguiTokens:

{
  Foundation: Tokens,       // foundation token set (Tamagui format)
  Semantic: Tokens,         // semantic token set (Tamagui format)
  Themes: TamaguiThemes     // { light, dark, light-chrome, dark-chrome }
}

Inside tokens:

{
  color: ColorTokensType,
  spacing: SpacingTokensType,
  typography: TypographyTokensType,
  foundation: FoundationTokensType,
}

Good for docs, SSR precompiles, or DS tooling. For apps, prefer ad → useTokens() for dynamic, theme-aware values.

Versioning strategy

• ad-tokens-raw: unversioned dump of Token Studio exports
• ad-tokens (this repo): versioned releases that match the Figma Styles Library
  • Major.Minor ≈ Figma Styles Library version
  • Patch = transformer/build fixes that don't change design intent.

Update flow (maintainers)

1. Update local raw package reference

npm run raw:update

Refreshes the ad-tokens-raw dev dependency.

2. Sync raw JSON into this repo

npm run raw:sync

Clones ad-tokens-raw into src/_raw.

3. Prebuild (transform)

npm run pre:build

Transforms raw tokens into Tamagui-ready structures:

• Auto-splits into themes
• Applies uniform scaling rules (spacing scaling, typography scaling)
• Generates typed maps + writes internal static artifacts to src/_static

4. Build

npm run build

Emits ESM/CJS bundles and bundled .d.ts.

Commit rules

• Do not hand-edit src/_static/* or src/_raw/*, they are generated/synced.
• Token changes must originate in Token Studio → ad-tokens-raw → then flow through this pipeline.

Future plans

• Current status: MVP focused on AD POC (web/Tamagui).
• Planned additional outputs:
  • Legacy web: TBD for best format.
  • iOS: generated Swift package (typed APIs + asset catalogs).
  • Android: generated Kotlin/Compose artifacts and/or XML resources.
• Context-aware behavior: currently solved on web via ad (useTokens() with SSR-friendly theming). The approach for iOS/Android/legacy web is TBD, options include lightweight runtime adapters or compile-time variant expansion. Open questions: theme switching, density/size scaling, and brand overrides on non-web targets.
• Note: scope and formats are subject to change as requirements land.

Npm Migration

Node version - v24.11.0 Npm version - 11.6.1

1. remove node_modules
2. npm install