@mediaradar/design-tokens 2.0.0

package/README.md

@@ -0,0 +1,50 @@
+# Design Tokens — MediaRadar Design System
+
+Style Dictionary build for the MediaRadar Design System. This package 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 — deployed to a CDN consumed directly by URL, no npm package required.
+
+See the root `CLAUDE.md` for the full token pipeline architecture and consuming-app setup. This file covers only building this package locally.
+
+---
+
+## Building locally
+
+```bash
+cd packages/design-tokens
+npm ci
+npm run build   # runs scripts/build-tokens.js → writes dist/
+```
+
+`dist/` is gitignored and never committed — it's a pure CI build artifact, deployed straight to the CDN 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   ← NOT built here — published by the ux-design repo; do not create or edit
+  index.html, scss/utilities/  ← copied as-is from static/, unwired legacy leftovers
+```
+
+## Consuming this package
+
+Downstream projects don't install anything from this package — they `@import` the deployed CSS directly by URL:
+
+```css
+@import "https://lemon-cliff-091e8ef0f.7.azurestaticapps.net/css/tokens.css";
+@import "https://lemon-cliff-091e8ef0f.7.azurestaticapps.net/css/dark.css";
+```
+
+See root `CLAUDE.md`'s "Consuming in a React + Tailwind app" section for the full Tailwind v4 wiring, the CDN asset reference table, and MCP server tool list.
+
+## 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 automatically on merge.

package/dist/DESIGN.md

@@ -0,0 +1,370 @@
+# MediaRadar Design System
+
+> LLM context file for `@mediaradar/design-tokens`. Provides brand rules, semantic guides, and component patterns for AI-assisted UI development. Import via `@node_modules/@mediaradar/design-tokens/DESIGN.md` in Claude Code. The token reference section below is auto-generated — rebuild the package to update resolved values.
+>
+> This is the authoritative resolved-values reference — if any other doc
+> disagrees with it, this one wins. Two other places document the same
+> system from a different angle: `design-site`'s live `/stylesheet` route
+> (real components, real variants — the visual reference) and
+> `mr-clientapps-insights-studio`'s local `frontend/DESIGN.md` (app-specific
+> component usage).
+
+## Brand
+
+MediaRadar is a B2B media intelligence platform — enterprise software for advertising analytics, market research, and competitive intelligence. The UI is professional, information-dense, and analytical. It is never playful or decorative. Palette is warm-cream, not the cool-gray/blue look common to SaaS dashboards.
+
+**Two brand colors, strictly separated by role — do not conflate them:**
+- **Coral** — `sys.color.brand.primary` (`#f05323` light / `#ff7548` dark) — **identity only**: logo, AI-surface accents (sparkle icons, AI gradient endpoint), brand moments. Never a button fill, never a link, never used for "interactive" anything.
+- **Warm royal blue** — `sys.color.brand.primaryAction` (`#2747c4` light / `#5b73dd` dark) — **the only interactive color**: primary CTA fills, links, focus rings, active/selected nav states.
+- **Neutral "black":** `sys.color.text.primary` (`#1f1b16` light / `#f4f2ee` dark) — a warm near-black, not a cool blue-black. The whole neutral ramp (canvas/surface/subtle/borders) is warm-toned; never substitute cool grays.
+- **Typography:** Instrument Sans (UI/body) + Instrument Serif (display — used italic for editorial/greeting moments). Not Roboto Flex.
+
+## Token semantics
+
+**Rule:** Always consume `sys.*` tokens in component styles. `ref.*` tokens bypass dark mode and semantic intent — they are raw primitives, not design decisions.
+
+### Color roles
+
+| Tailwind key | Use for |
+|---|---|
+| `canvas` | Outermost page background |
+| `surface` | Cards, panels, dialogs, drawers |
+| `subtle` | Secondary areas, sidebars, striped table rows |
+| `text-primary` | Body copy, headings, form values |
+| `text-secondary` | Supporting text, metadata, timestamps |
+| `text-inverse` | Text/icons on dark or brand-colored backgrounds |
+| `text-warning` | Caution states |
+| `brand-primary` | Logo, AI-surface accents, brand identity moments ONLY — never buttons/links |
+| `brand-primaryAction` | CTAs, links, focus rings, active/selected nav — the actual interactive color |
+| `brand-onprimary` | Text/icons placed directly on brand-primary backgrounds |
+| `border-default` | Dividers, input outlines, card borders |
+| `border-focus` | Keyboard focus rings |
+| `status-success` | Positive values, confirmations |
+| `status-danger` | Errors, destructive actions |
+| `status-onstatus` | Text/icons on status-colored backgrounds |
+
+### Typography hierarchy
+
+Prefer `text-style-*` composite classes — they set size, weight, line-height, letter-spacing, and color in one class and support all Tailwind variants (`hover:`, `md:`, etc.).
+
+| Role | Class | Use for |
+|---|---|---|
+| Page title | `text-style-heading-1` | h1, page-level titles |
+| Section heading | `text-style-heading-2` | h2, major section headers |
+| Sub-heading | `text-style-heading-3` | h3, card titles, panel headers |
+| Large body | `text-style-body-lg` | Intro or featured paragraphs |
+| Body | `text-style-body` | Standard paragraphs, descriptions |
+| Small body | `text-style-body-sm` | Secondary content, sidebar text |
+| XS body | `text-style-body-xs` | Fine print, helper text |
+| Label | `text-style-label` | Form labels, key–value metadata |
+| Label strong | `text-style-label-strong` | Bold labels, selected state labels |
+| Label small | `text-style-label-sm` | Compact labels, tag text |
+| Label XS | `text-style-label-xs` | Dense table headers, badge text |
+| Caption | `text-style-caption` | Tooltips, image captions, timestamps |
+| Link | `text-style-link` | Anchor text |
+| Link strong | `text-style-link-strong` | Prominent / bold links |
+| Link XS | `text-style-link-xs` | Inline small links |
+
+## Component patterns
+
+### Card
+```tsx
+<div className="bg-surface rounded-card shadow-raised border border-border-default p-6">
+  <h2 className="text-style-heading-3">Title</h2>
+  <p className="text-style-body text-text-secondary mt-2">Description</p>
+</div>
+```
+
+### Form input
+```tsx
+<label className="text-style-label text-text-primary">
+  Field label
+  <input
+    className="mt-1 block w-full bg-surface rounded-control border border-border-default
+               px-3 py-2 text-style-body text-text-primary
+               focus:border-border-focus focus:outline-none"
+  />
+</label>
+```
+
+### Primary button
+```tsx
+<button className="inline-flex items-center gap-2 bg-brand-primaryAction text-brand-onprimary
+                   rounded-control px-4 py-2 text-style-label-strong
+                   hover:opacity-90 disabled:opacity-disabled">
+  Action
+</button>
+```
+Note: `bg-brand-primary` (coral) is reserved for identity/AI-accent moments — never a button fill.
+
+### Dialog / modal
+```tsx
+<div className="fixed inset-0 z-modal flex items-center justify-center">
+  <div className="bg-surface rounded-card shadow-overlay p-8 w-full max-w-lg">
+    <h2 className="text-style-heading-2">Dialog title</h2>
+    <p className="text-style-body text-text-secondary mt-3">Content goes here.</p>
+  </div>
+</div>
+```
+
+### Data table row
+```tsx
+<tr className="border-b border-border-default hover:bg-subtle
+               transition-colors duration-interactive ease-interactive">
+  <td className="px-4 py-3 text-style-body text-text-primary">{value}</td>
+  <td className="px-4 py-3 text-style-body-sm text-text-secondary">{meta}</td>
+</tr>
+```
+
+### Status badge
+```tsx
+<span className="inline-flex items-center gap-1 rounded-control px-2 py-1
+                 text-style-label-xs bg-status-success text-status-onstatus">
+  Active
+</span>
+```
+
+### Dropdown / tooltip overlay
+```tsx
+<div className="bg-surface rounded-card shadow-overlay border border-border-default
+               z-dropdown p-1">
+  {items}
+</div>
+```
+
+## Dark mode
+
+Set `data-theme="dark"` on any ancestor element. All `sys.*` tokens adapt automatically — no `dark:` Tailwind variants needed.
+
+```ts
+document.documentElement.setAttribute('data-theme', isDark ? 'dark' : 'light')
+```
+
+**Diagnostic:** If a color is not adapting to dark mode, verify you're using a `sys.color.*` token (e.g., `bg-canvas`) rather than a `ref.color.*` primitive (e.g., `--mr-ref-color-shadow-universal-2`). Only sys tokens have dark overrides.
+
+## Decision guide
+
+When building UI, follow this order:
+
+1. **Text:** Is there a `text-style-*` that matches the typographic role? Use it — do not manually compose font-size + weight + line-height.
+2. **Color:** Is there a `sys.color.*` semantic name describing the element's intent? Use it — `bg-{key}`, `text-{key}`, `border-{key}`, etc.
+3. **Spacing:** Is there a spacing scale value that fits? Use the discrete scale (`p-4`, `gap-3`, `mt-8`). Avoid arbitrary values. Use pixel values (`p-1px`) only for sub-pixel tuning.
+4. **Shape/elevation:** Use `rounded-control` for interactive elements, `rounded-card` for containers. Use `shadow-raised` for resting cards, `shadow-overlay` for floating surfaces.
+5. **Primitives:** Reach into `ref.*` only when no semantic token fits. If the pattern recurs, propose a new `sys.*` token.
+
+---
+
+## Token reference
+
+> Auto-generated from Style Dictionary. All values are resolved — no aliases. Rebuild to update.
+
+### Colors
+
+Key is the suffix for any Tailwind color utility: `bg-{key}`, `text-{key}`, `border-{key}`, `ring-{key}`, `fill-{key}`, etc. Dark values activate when `data-theme="dark"` is set on any ancestor.
+
+| Key | Light | Dark |
+| --- | --- | --- |
+| canvas | #f4f2ee | #1c1814 |
+| surface | #fbfaf7 | #26211b |
+| subtle | #ebe7e0 | #322c24 |
+| text-primary | #1f1b16 | #f4f2ee |
+| text-secondary | #6b6358 | #b5aea1 |
+| text-tertiary | #5f574b | #a39b8c |
+| text-inverse | #fbfaf7 | #1c1814 |
+| text-warning | #5c4118 | #e8c285 |
+| text-danger | #8b1018 | #ff7068 |
+| text-success | #1d4d2a | #7fc28f |
+| text-link | #2747c4 | #8aa0ff |
+| brand-primary | #f05323 | #ff7548 |
+| brand-primaryAction | #2747c4 | #5b73dd |
+| brand-onprimary | #ffffff | — |
+| brand-primarySoft | #ebe3d5 | #3a322a |
+| status-success | #1d7a3b | #3a9555 |
+| status-warning | #b8843a | #d9a655 |
+| status-danger | #c53030 | #e84a4a |
+| status-onstatus | #ffffff | — |
+| status-on-status | #ffffff | — |
+| border-default | #dcd6cb | #3a3329 |
+| border-interactive | #6b6358 | — |
+| border-focus | #2747c4 | #8aa0ff |
+| border-focusSoft | rgba(39, 71, 196, 0.28) | rgba(138, 160, 255, 0.35) |
+| ai-tint | #e4e2f5 | #2b2e48 |
+| ai-ontint | #2747c4 | #8aa0ff |
+| ai-gradient | linear-gradient(135deg, #2747c4 0%, #f05323 60%, #f99d20 100%) | linear-gradient(135deg, #5b73dd 0%, #ff7548 60%, #ffb878 100%) |
+
+### Typography
+
+**Font sizes** — Tailwind: `text-{key}`
+
+| Key | Value |
+| --- | --- |
+| xs | 0.75rem |
+| sm | 0.875rem |
+| base | 1rem |
+| md | 1.125rem |
+| lg | 1.25rem |
+| xl | 1.5rem |
+| h1 | 1.875rem |
+
+**Font weights** — Tailwind: `font-{key}`
+
+| Key | Value |
+| --- | --- |
+| regular | 400 |
+| medium | 500 |
+| semibold | 600 |
+| bold | 700 |
+
+**Line heights** — Tailwind: `leading-{key}`
+
+| Key | Value |
+| --- | --- |
+| tight | 1.2 |
+| base | 1.5 |
+| head | 1.5 |
+
+**Letter spacing** — Tailwind: `tracking-{key}`
+
+| Key | Value |
+| --- | --- |
+| normal | 0em |
+| tight | -0.01em |
+
+**Text styles** — Tailwind: `text-style-{name}`. One class sets font-size, font-weight, line-height, letter-spacing, and color. Supports all Tailwind variants.
+
+| Style | Size | Weight | Leading | Tracking | Color |
+| --- | --- | --- | --- | --- | --- |
+| text-style-heading-1 | 1.875rem | 600 | 1.5 | 0em | #363233 |
+| text-style-heading-2 | 1.25rem | 600 | 1.2 | 0em | #1f1b16 |
+| text-style-heading-3 | 0.875rem | 600 | 1.2 | 0em | #1f1b16 |
+| text-style-body-lg | 1.25rem | 700 | 1.2 | 0em | #1f1b16 |
+| text-style-body | 1.125rem | 400 | 1.5 | 0em | #1f1b16 |
+| text-style-body-sm | 0.875rem | 400 | 1.5 | 0em | #1f1b16 |
+| text-style-body-xs | 0.75rem | 400 | 1.5 | 0em | #1f1b16 |
+| text-style-label | 1rem | 400 | 1.2 | 0em | #1f1b16 |
+| text-style-label-strong | 1rem | 600 | 1.2 | 0em | #1f1b16 |
+| text-style-label-sm | 0.875rem | 700 | 1.2 | 0em | #6b6358 |
+| text-style-label-xs | 0.75rem | 600 | 1.2 | 0em | #6b6358 |
+| text-style-caption | 0.75rem | 400 | 1.5 | 0em | #6b6358 |
+| text-style-link | 0.875rem | 400 | 1.5 | 0em | #2747c4 |
+| text-style-link-strong | 0.875rem | 600 | 1.5 | 0em | #2747c4 |
+| text-style-link-xs | 0.75rem | 400 | 1.5 | 0em | #2747c4 |
+
+### Spacing
+
+Tailwind: `p-{key}`, `m-{key}`, `gap-{key}`, `w-{key}`, `h-{key}`, etc. Integer scale: 1 step = 0.25rem (4px) — so `p-4` = 1rem = 16px. Half-steps (e.g. `p-1_5`) and pixel values (e.g. `p-1px`) are available.
+
+**rem scale:**
+
+| Key | Value |
+| --- | --- |
+| 0 | 0rem |
+| 1 | 0.25rem |
+| 2 | 0.5rem |
+| 3 | 0.75rem |
+| 4 | 1rem |
+| 5 | 1.25rem |
+| 6 | 1.5rem |
+| 7 | 1.75rem |
+| 8 | 2rem |
+| 9 | 2.25rem |
+| 10 | 2.5rem |
+| 11 | 2.75rem |
+| 12 | 3rem |
+| 13 | 3.25rem |
+| 14 | 3.5rem |
+| 15 | 3.75rem |
+| 16 | 4rem |
+| 17 | 4.25rem |
+| 18 | 4.5rem |
+| 19 | 4.75rem |
+| 20 | 5rem |
+| 21 | 5.25rem |
+| 22 | 5.5rem |
+| 23 | 5.75rem |
+| 24 | 6rem |
+| 25 | 7rem |
+| 26 | 8rem |
+| 27 | 9rem |
+| 28 | 10rem |
+| 29 | 11rem |
+| 30 | 12rem |
+| 1_5 | 0.375rem |
+| 2_5 | 0.625rem |
+| 3_5 | 0.875rem |
+| 4_5 | 1.125rem |
+| 5_5 | 1.375rem |
+| 6_5 | 1.625rem |
+| 7_5 | 1.875rem |
+
+**pixel values:**
+
+| Key | Value |
+| --- | --- |
+| 0px | 0px |
+| 1px | 1px |
+| 2px | 2px |
+| 3px | 3px |
+| 5px | 5px |
+| 6px | 6px |
+| 7px | 7px |
+| 8px | 8px |
+| 9px | 9px |
+| 10px | 10px |
+
+**Semantic spacing** — no Tailwind utility; use `var(--mr-spacing-{key})` in CSS directly.
+
+| Token | Value |
+| --- | --- |
+| control-padding-x | 0.75rem |
+| control-padding-y | 0.5rem |
+| layout-xs | 0.5rem |
+| layout-sm | 0.75rem |
+| layout-md | 1rem |
+| layout-lg | 1.5rem |
+| layout-xl | 2rem |
+| card-padding | 1.25rem |
+| dialog-padding | 1.5rem |
+
+### Shape
+
+**Border radius** — Tailwind: `rounded-{key}`
+
+| Key | Value |
+| --- | --- |
+| control | 8px |
+| card | 12px |
+
+### Elevation
+
+**Box shadows** — Tailwind: `shadow-{key}`
+
+| Key | Value |
+| --- | --- |
+| raised | #000bec |
+| overlay | #000bec |
+
+### Motion
+
+| Type | Key | Tailwind | Value |
+| --- | --- | --- | --- |
+| duration | interactive | duration-interactive | 200ms |
+| easing | interactive | ease-interactive | cubic-bezier(0.2, 0, 0, 1) |
+
+### Opacity
+
+Tailwind: `opacity-{key}`
+
+| Key | Value |
+| --- | --- |
+| disabled | 0.4 |
+
+### Z-index
+
+Tailwind: `z-{key}`
+
+| Key | Value |
+| --- | --- |
+| dropdown | 1000 |
+| modal | 1100 |
+| tooltip | 1200 |

package/dist/css/component.css

@@ -0,0 +1,8 @@
+/**
+ * Do not edit directly, this file was auto-generated.
+ */
+
+:root {
+  --mr-button-border: #dcd6cb;
+  --mr-button-typography-fontfamily: 'Roboto Flex', sans-serif;
+}

package/dist/css/dark.css

@@ -0,0 +1,27 @@
+[data-theme="dark"] {
+  --mr-color-canvas: var(--mr-ref-color-brand-warm-canvas-dark);
+  --mr-color-surface: var(--mr-ref-color-brand-warm-surface-dark);
+  --mr-color-subtle: var(--mr-ref-color-brand-warm-subtle-dark);
+  --mr-color-text-primary: var(--mr-ref-color-brand-warm-text-primary-dark);
+  --mr-color-text-secondary: var(--mr-ref-color-brand-warm-text-secondary-dark);
+  --mr-color-text-tertiary: var(--mr-ref-color-brand-warm-text-tertiary-dark);
+  --mr-color-text-inverse: var(--mr-ref-color-brand-warm-text-inverse-dark);
+  --mr-color-text-warning: var(--mr-ref-color-brand-warm-text-warning-dark);
+  --mr-color-text-danger: var(--mr-ref-color-brand-warm-text-danger-dark);
+  --mr-color-text-success: var(--mr-ref-color-brand-warm-text-success-dark);
+  --mr-color-text-link: var(--mr-ref-color-brand-warm-text-link-dark);
+  --mr-color-brand-primary: var(--mr-ref-color-brand-warm-brand-primary-dark);
+  --mr-color-brand-primary-action: var(--mr-ref-color-brand-warm-brand-primary-action-dark);
+  --mr-color-brand-primary-soft: var(--mr-ref-color-brand-warm-brand-primary-soft-dark);
+  --mr-color-status-success: var(--mr-ref-color-brand-warm-status-success-dark);
+  --mr-color-status-warning: var(--mr-ref-color-brand-warm-status-warning-dark);
+  --mr-color-status-danger: var(--mr-ref-color-brand-warm-status-danger-dark);
+  --mr-color-border-default: var(--mr-ref-color-brand-warm-border-default-dark);
+  --mr-color-border-focus: var(--mr-ref-color-brand-warm-border-focus-dark);
+  --mr-color-border-focus-soft: var(--mr-ref-color-brand-warm-border-focus-soft-dark);
+  --mr-color-ai-tint: var(--mr-ref-color-brand-warm-ai-tint-dark);
+  --mr-color-ai-ontint: var(--mr-ref-color-brand-warm-ai-ontint-dark);
+  --mr-color-ai-gradient: var(--mr-ref-color-brand-warm-ai-gradient-dark);
+  --mr-text-style-heading-1-color: var(--mr-ref-color-secondary-light-10);
+  --mr-typography-line-height-head: var(--mr-ref-typography-line-height-sm);
+}