@mihcm/tokens

Raw MiHCM design tokens for color, spacing, typography, radius, shadow, motion, and component-level CSS variables.

This package is the source of truth for token values. Application code should consume tokens through @mihcm/theme or Tailwind classes instead of copying raw values.

Current release

Current published version: 0.6.3.

This release adds the softer shadow-mi-input elevation token used by form controls and filter fields, while preserving existing card and overlay elevation tokens. The token surface is currently aligned with @mihcm/[email protected] and @mihcm/[email protected]; consumer apps installing the current train should pin those versions together.

Install

pnpm add @mihcm/tokens

Usage

Import the generated CSS variables directly only when you are building low-level infrastructure:

import '@mihcm/tokens/tokens.css';

Most applications should import @mihcm/theme/globals.css instead, because it includes token variables plus the design-system reset and theme layer.

What is included

• Brand color ramps and semantic aliases.
• Light and dark surface, text, border, muted, destructive, success, warning, and accent tokens.
• 60/30/10 composition aliases: ratio-60 / dominant, ratio-30 / supporting, and ratio-10 / emphasis.
• App-shell and component tokens, including TopBar, form field, chart, and motion variables.
• Spacing, radius, shadow, typography, and motion primitives.
• CSS variables that Tailwind 4 can consume through the theme package.

Recent additions and fixes

• Added fixed TopBar light/dark component tokens so system dark mode is deterministic.
• Added tokenized 60/30/10 color-balance aliases for dominant neutral surfaces, supporting brand blue, and restrained orange emphasis.
• Added subdued dark-mode orange segment tokens that pass contrast and align with the app-shell palette.
• Added smoother motion timing/easing tokens for Accordion, Collapsible, Sheet, Toast, and related components.
• Normalized form field surface tokens around white/card backgrounds, border-border, and the softer shadow-mi-input.

Token rules

• Use semantic tokens in components, not raw hex values.
• For screen composition, use bg-ratio-60 for dominant neutral area, bg-ratio-30 for supporting brand-blue structure/actions, and bg-ratio-10 for restrained orange emphasis.
• Add new raw values only when they represent a reusable design decision.
• Prefer aliases such as foreground/background/border/accent over brand-ramp values in component code.
• Do not encode product-specific copy, data, or business logic in tokens.
• Keep marketing-only decisions separate from core application tokens unless the value is shared by both surfaces.

Maintainer checklist

When adding or changing tokens:

1. Update src/tokens.css.
2. Update @mihcm/theme if Tailwind mapping or globals need to expose the token.
3. Update token docs in src/apps/docs/app/tokens/.
4. Check light and dark contrast for semantic color changes.
5. Run the package build and typecheck.
6. Add a changeset before publishing.

Build

cd src
pnpm -F @mihcm/tokens build
pnpm -F @mihcm/tokens typecheck

Related docs

• docs/CONVENTIONS.md
• docs/security-playbook.md
• src/apps/docs/app/tokens/