# @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 ```bash npm install @imj_media/orbit-tokens ``` ## CSS Import tokens once at the root of your stylesheet entry (order: tokens before app overrides): ```css @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. `` o ``): ```css @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"`) ```js 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 ```js /** @type {import('tailwindcss').Config} */ module.exports = { presets: [require("@imj_media/orbit-tokens/tailwind/preset")], content: ["./src/**/*.{js,ts,jsx,tsx}"], }; ``` ### Programmatic import ```ts 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.