@mediaradar/design-tokens

Style Dictionary build for the MediaRadar Design System. Reads the token source files in packages/tokens/ (one level up) and transforms them into CSS custom properties, Tailwind v4 integration files, and JS/TS token values.

Output is distributed two ways:

• npm package (this package) — how apps consume tokens. Take all four files (css/tokens.css, css/dark.css, tailwind/theme.css, tailwind/typography.css) from here, so they always come from the same version.
• CDN (https://tokens.mediaradar.com, Cloudflare Pages) — serves the same dist/ plus DESIGN.md, patterns.json, tokens.json and changelog.json for the MCP server. Useful for previewing an unreleased token change, not as an app's main source.

Installing (as a consumer)

npm install @mediaradar/design-tokens

@import "@mediaradar/design-tokens/css/tokens.css";
@import "@mediaradar/design-tokens/css/dark.css";
@import "tailwindcss";
@import "@mediaradar/design-tokens/tailwind/theme.css";
@import "@mediaradar/design-tokens/tailwind/typography.css";

Don't load tokens.css/dark.css from the CDN alongside a pinned theme.css: theme.css only aliases names, the values live in those two files, and loading them live lets the two halves drift apart (a CDN token rename breaks an app's classes with no version change on its side). And never load tailwind/*.css from the CDN at all — Tailwind can't resolve @theme from a remote @import.

This package is version-pinned like any other npm dependency — a token change reaches a consumer when it bumps the version (Dependabot opens that PR daily in insights-studio-prototype, and merges it automatically for non-major versions). See the root CLAUDE.md's "Consuming in a React + Tailwind app" section for the full wiring and the CDN asset reference table.

Building locally

cd packages/design-tokens
npm ci
npm run build   # runs scripts/build-tokens.js → writes dist/

dist/ is gitignored and never committed to this repo — it's a build artifact, both deployed to the CDN and packed into the npm tarball by .github/workflows/tokens.yml on push to main. Do not edit anything under dist/ by hand; it's regenerated from packages/tokens/*.json on every build and any local edit is silently overwritten.

Build config

Style Dictionary config lives in sd.config.mjs. The custom name/prefix-mr-strip-layer transform strips the leading layer segment (ref/sys/component) from each token path and adds an mr- prefix — see root CLAUDE.md's "Name transform" section for the full mapping rules.

Output

dist/
  css/            ← tokens.css (entry point), ref.css, sys.css, spacing.css, typography.css, component.css, dark.css
  tailwind/       ← theme.css (@theme block), typography.css (@utility text-style-* classes)
  js/             ← tokens.js, tokens.d.ts
  DESIGN.md       ← LLM-optimized design spec, auto-generated
  patterns.json   ← component catalog, built by tokens.yml from packages/design-components — do not create or edit
  index.html, staticwebapp.config.json, scss/utilities/  ← copied as-is from
    static/; CDN-hosting artifacts (routing/cache config, a landing page,
    unwired legacy SCSS) with no relevance to an npm consumer, so index.html
    and staticwebapp.config.json are excluded from what actually publishes
    (see package.json's "files")

Publishing

.github/workflows/tokens.yml bumps the version automatically when token values change (major for a breaking change, minor for an addition, patch otherwise) and publishes on merge to main. A change to generated output alone — sd.config.mjs, this package's own config — changes no token value, so bump version in package.json by hand in that PR; otherwise nothing publishes (the publish no-ops when the version is already on npm).

Contributing

1. Edit token source files under packages/tokens/*.json — never dist/.
2. npm run build locally to verify output.
3. Open a PR against main. Changes deploy (CDN) and publish (npm) automatically on merge.