@linkrunner/relay-tokens

The framework-independent design foundation for Linkrunner. Relay owns the checked-in source at src/tokens.json; a dependency-free Node build produces themes, resolved JavaScript/JSON values, TypeScript declarations, and optional Tailwind adapters.

CSS and themes

@import "@linkrunner/relay-tokens/themes.css";

.account-summary {
  background: var(--relay-bg-primary);
  color: var(--relay-text-primary);
  padding: var(--relay-spacing-4);
  border-radius: var(--relay-radius-md);
}

The default is light. Set data-relay-theme="dark" or the existing .dark class on the document or a subtree. Set data-relay-theme="light" to restore light in a nested scope. Explicit light wins over .dark on the same element. All token aliases are re-declared at theme boundaries so nested themes resolve correctly.

This package sets custom properties only. It does not apply resets, element styles, font downloads, a font face, document colors, or color-scheme. Each application loads its approved Inter/DM Mono font files and owns its document styles. Portalled components must use a portal container inside their theme boundary, or the app must apply its selected theme to the document root.

Existing CSS migration

@import "@linkrunner/relay-tokens/themes.css";
@import "@linkrunner/relay-tokens/legacy.css";

legacy.css is an opt-in migration adapter mapping names such as --bg-primary to --relay-bg-primary. It redeclares aliases at each theme boundary. Remove copied legacy declarations when adopting it; otherwise the application's cascade can override those aliases. New components use the namespaced properties directly.

JavaScript and data consumers

import { tokens, tokenVar, type TokenName } from "@linkrunner/relay-tokens";

tokens.dark["viz-blue-4"]; // resolved value for a canvas/chart renderer
tokenVar("text-secondary"); // "var(--relay-text-secondary)"

The package includes ESM and CommonJS exports. tokens.light and tokens.dark are flat, fully resolved maps. tokenVars exposes typed CSS variable references. @linkrunner/relay-tokens/tokens.json contains the same two resolved theme maps for tools that do not run JavaScript. Token values are read-only in the TypeScript API. @linkrunner/relay-tokens/colors.json provides the 91-color palette as an array of { name, value, cssVariable } objects for documentation and token pickers.

Tailwind 3

import relayPreset from "@linkrunner/relay-tokens/tailwind3";

export default {
  presets: [relayPreset],
  content: ["./src/**/*.{ts,tsx}"],
};

CommonJS can use const { relayPreset } = require("@linkrunner/relay-tokens/tailwind3"). Import themes.css separately. The preset extends the theme without installing plugins, a reset, content sources, breakpoints, or dark-mode behavior. It includes existing dashboard palette keys, semantic text/background/border roles, typography, spacing, radii, duration/easing, shadows, and layering values.

Tailwind 4

@import "tailwindcss";
@import "@linkrunner/relay-tokens/themes.css";
@import "@linkrunner/relay-tokens/tailwind4.css";

The adapter uses @theme inline for theme values and functional semantic utilities, so bg-primary uses a surface while text-primary uses a foreground. They must not both resolve through Tailwind's shared --color-primary namespace. text-body-md, text-button-md, p-4, rounded-md, duration-normal, and z-modal use the same foundation as the Tailwind 3 preset. Variants such as hover:bg-secondary work via Tailwind's normal utility compiler. Import either adapter only in the app that compiles its own layout utilities; the Relay UI package ships its component CSS. The adapter clears shared color slots that collide with semantic roles, including --color-primary and --color-secondary, so Tailwind cannot generate conflicting foreground/surface utilities. Apps should use the semantic roles consistently.

Semantic colors support opacity modifiers such as bg-primary/50, text-primary/70, and border-default/50. Arbitrary percentages use /[25%]; arbitrary numeric opacity and variables use fractions from 0 to 1, such as /[0.25] or /(--overlay-opacity). Directional borders and divide-* use the same semantic border roles. Existing caret-primary and ring-offset-primary retain the original global primary color, separately from text-primary.

Scope and source parity

The initial palette, semantic roles, spacing, radii, and typography came from the dashboard revision recorded in the source. Builds never read that repository. Motion durations, easing, layers, and semantic effect aliases are now named here. The original body typography is also available as --relay-font-feature-settings-body, --relay-letter-spacing-body, --relay-font-family-body, and matching size, line-height, weight, font-smoothing, text-rendering, and optical-sizing tokens. Components can adopt those defaults within their own scope without changing the host application's body. The native h1, h2, h3, h4–h6, and p defaults are exported as --relay-native-h1-font-size, --relay-native-h4-h6-line-height, --relay-native-p-letter-spacing, and the corresponding family, size, line-height, weight, optical-sizing, margin, padding, and heading color tokens. These preserve the dashboard's native-element defaults separately from its Tailwind typography utilities. The token stylesheet never applies rules to those elements.

Version 0.1.0 preserves the fresh dashboard main values exactly. Regression hashes pin the normalized initial light tokens, dark overrides, and typography to that recorded revision, including body and native-element typography extracted from the stylesheet. Future token changes are owned here and must be reviewed together with the baseline and consumer validation.

Primary and secondary text pass 4.5:1 on all three primary surfaces in both themes. Inherited failures remain: light tertiary text is 3.21:1 on white; light placeholders are 2.17:1 on white; dark placeholders are 2.96:1 on the primary background. Status text and badge combinations also retain their existing contrast limitations. These tests preserve source fidelity and do not establish accessibility conformance.

Run npm run build to regenerate dist, and npm test to validate theme graphs, scope isolation, contrast, adapters, JS/JSON parity, and package exports.