@integritymarketing/ic-tokens

Palette primitives and CSS custom properties. Zero runtime dependencies.

pnpm add @integritymarketing/ic-tokens

import { cssVariables } from '@integritymarketing/ic-tokens/tokens';
import { navyPalette } from '@integritymarketing/ic-tokens/palette';

@import '@integritymarketing/ic-tokens/tokens.css'; /* :root { --navy: …; } */

The one rule

src/palette.ts is the only file in this entire monorepo where a hex literal may appear. Everywhere else a hex is a lint error.

palette.ts      raw values, grouped by hue          #052A63
     ↓
tokens.ts       semantic CSS custom properties      --navy, --divider, --alert-error-bg
     ↓
components      var(--token), never a value

Components consume the semantic name. That is what lets a colour change once and land everywhere, and it is why --divider exists rather than fifteen components each picking their own grey.

If you need a colour the palette does not have: ask. Adding one is a design system decision, not a local one.

What ships

| Export | Contents | | --------------- | ------------------------------------------------------------------ | | . | barrel — palette + tokens | | ./palette | the raw hue groups and shadow definitions | | ./tokens | cssVariables — 180 CSS custom properties — and CssVariableName | | ./tokens.css | generated :root { … } for plain-CSS consumers | | ./tokens.json | generated map, for Figma variables import and tooling |

The last two are emitted by scripts/emit-css.ts during pnpm build, from the same cssVariables object the components use — so they cannot drift. Never hand-edit dist/.

Why this is separate from theme

@integritymarketing/ic-theme declares MUI as a peer, so installing it pulls in React's whole ecosystem. This package has no dependencies at all, so anything that only needs colour values — the email generator, the Figma Make kit, a Figma variables import — installs this instead.

Coverage

| Category | Count | | -------------------------------------------------- | ------- | | Colour (brand, semantic, alerts, component, chart) | 97 | | Spacing (ladder + layout + shell + touch target) | 26 | | Motion (durations + easings) | 12 | | Typography | 9 | | Elevation / shadow | 8 | | Breakpoints | 5 | | Radius | 2 | | Total | 159 |

All five categories named in the platform proposal exist, plus breakpoints.

One counting trap, because it has caused a miscount already: the --text-* prefix spans two categories. --text-h1 … --text-label are six type sizes and count as typography, while --text-primary, --text-secondary and --text-disabled are colours. Read the value, not the name.

Three worth knowing about:

• Spacing uses design's own token names and values, read off the padding & gap/* group on the Page Template (v2-Organisms, node 8208:220653): none · x-sm (4) · sm (8) · sm-plus (12) · md (16) · lg (24), plus xl (32) and 2xl (40) of ours. The awkward sm+ is deliberate — an earlier conventional ladder put --space-sm at 12px while design's sm is 8px, one step out of phase. In a component prefer MUI's sx={{ p: 2 }}; the tokens are for consumers that cannot call theme.spacing.

• Breakpoints come from the min/max constraints on the same Page Template artboards — 0 / 320 / 768 / 1200 / 1521. breakpoints carries the full range plus the width each size is drawn at; mediaQueries gives ready-made up and only query strings; theme.breakpoints is built from the same constants. Do not use the Atomic Library's breakpoints token group (444/600/900/1200/1536): those are MUI's defaults, named Default-*, and xs: 444 sat above design's own 376px Small artboard — breaking every sx={{ xs: … }} on real phones.

• Motion is documented in docs/foundations/motion.md. The duration scale mirrors MUI's and theme.ts assigns the same constants back to theme.transitions so the two cannot drift. Reduced motion is handled once here — see reducedMotionOverrides.

Publishing

On any token or palette change. A bump here cascades to theme, ui-core, ui-connect, ui-pro, email and make-kit — which is correct, because a token change really does alter all of their output.