@imj_media/orbit-tokens
v1.2.0
Published
Design tokens for the Orbit Design System — colors, spacing, typography, radius, shadows, strokes, sizes, z-index. Single source of truth exported as CSS variables, JSON, and Tailwind preset.
Downloads
392
Readme
@imj_media/orbit-tokens
Design tokens for the Orbit design system: CSS custom properties, optional theme layers, and a Tailwind CSS preset so every consumer shares the same theme.extend mapping to var(--ui-*).
Single source of truth
| Layer | Role |
|--------|------|
| src/css/tokens.css (published as @imj_media/orbit-tokens/css/tokens.css) | Defines --ui-* variables. Do not duplicate these values in app :root or in other packages. |
| src/tailwind/buildThemeExtend.ts + preset.ts | Tailwind theme.extend mirrors those variables. Do not redefine the same keys in consumer tailwind.config unless you have a documented, temporary exception. |
When Figma or the token pipeline changes: update CSS first, then align the Tailwind theme modules, bump this package (semver), and align @imj_media/ui / apps to the new version.
Installation
npm install @imj_media/orbit-tokensCSS
Import tokens once at the root of your stylesheet entry (order: tokens before app overrides):
@import "@imj_media/orbit-tokens/css/tokens.css";Optional light/dark theme shells (see package exports). Import tokens first, then themes; activa modo oscuro con data-theme="dark" (o clase .theme-dark) en un ancestro del contenido (p. ej. <html> o <body>):
@import "@imj_media/orbit-tokens/css/tokens.css";
@import "@imj_media/orbit-tokens/themes/light.css";
@import "@imj_media/orbit-tokens/themes/dark.css";Tailwind
Use the preset so colors, spacing, typography scales, etc. resolve to Orbit variables. Do not set prefix inside the preset; each app sets its own (ui-, obp-, …).
ESM (type: "module")
import orbitPreset from "@imj_media/orbit-tokens/tailwind/preset";
/** @type {import('tailwindcss').Config} */
export default {
presets: [orbitPreset],
content: ["./src/**/*.{js,ts,jsx,tsx}"],
prefix: "ui-", // example; omit if you do not want a prefix
};CommonJS
/** @type {import('tailwindcss').Config} */
module.exports = {
presets: [require("@imj_media/orbit-tokens/tailwind/preset")],
content: ["./src/**/*.{js,ts,jsx,tsx}"],
};Programmatic import
import { tailwindPreset } from "@imj_media/orbit-tokens";Consuming from @imj_media/ui
The UI library uses this preset in its own tailwind.config.js and imports tokens.css in shared styles. For details and local-only exceptions, see packages/ui/README.md and packages/ui/DEVELOPMENT_GUIDE.md (section Orbit — Tailwind preset).
Versioning
- Additive theme keys or new variables with backward-compatible defaults → minor.
- Removing or renaming theme keys or variables that consumers rely on → major (document in
CHANGELOG.md).
Cursor agents
Repository rule .cursor/rules/imj-orbit-tokens-no-ad-hoc.mdc: do not add ad hoc design tokens without explicit user confirmation and a short risk summary.
