@molano/tokens

Design tokens for the Molano Design System. JSON source files compiled to CSS custom properties, brand theme overrides, and W3C DTCG format.

Overview

JSON source files  →  build.mjs  →  tokens.css (359 vars)
                                 →  tokens-brand-energy.css
                                 →  tokens-brand-forest.css
                                 →  tokens-brand-royal.css
                                 →  tokens.dtcg.json (W3C format)

Installation

npm install @molano/tokens

// Base tokens (required)
import "@molano/tokens"

// Optional: brand override
import "@molano/tokens/tokens-brand-energy.css"

Token Categories

Primitive Tokens (8 JSON files)

| File | Variables | Examples | |------|-----------|---------| | colors.json | 60 | --ds-color-primary-500, --ds-color-neutral-200 | | typography.json | 16 | --ds-text-base, --ds-font-weight-bold, --ds-leading-normal | | spacing.json | 10 | --ds-spacing-xs (0.25rem) → --ds-spacing-4xl (6rem) | | effects.json | 12 | --ds-radius-lg, --ds-shadow-md | | borders.json | 4 | --ds-border-width-thin, --ds-border-style-solid | | breakpoints.json | 5 | --ds-breakpoint-sm (640px) → --ds-breakpoint-2xl (1536px) | | containers.json | 4 | --ds-container-content-max (1280px) | | layout.json | 8 | --ds-z-modal (50), --ds-duration-normal (200ms) |

Semantic Tokens (semantic.json)

Map primitives to meaning. Different values for light and dark mode:

| Token | Light | Dark | |-------|-------|------| | --ds-surface-page | neutral-50 | neutral-900 | | --ds-surface-card | white | neutral-800 | | --ds-text-primary | neutral-900 | neutral-50 | | --ds-text-link | primary-600 | primary-400 | | --ds-action-primary | primary-600 | primary-400 | | --ds-action-danger | error-600 | error-600 | | --ds-border-default | neutral-200 | neutral-700 | | --ds-status-success | success-600 | success-600 | | --ds-status-error | error-500 | error-600 |

Color Palettes

6 palettes × 10 steps (50–900):

• Primary — Brand color (blue by default)
• Neutral — Grays for text, backgrounds, borders
• Success — Green for positive states
• Warning — Amber for caution states
• Error — Red for error states
• Info — Blue for informational states

Multi-Brand Theming

How It Works

Brand themes override only color.primary values. Semantic tokens reference primaries via var(), so everything cascades automatically.

:root                     →  --ds-color-primary-500: #3b82f6 (blue)
.theme-brand-energy       →  --ds-color-primary-500: #f97316 (orange)
.theme-brand-forest       →  --ds-color-primary-500: #22c55e (green)
.theme-brand-royal        →  --ds-color-primary-500: #8b5cf6 (purple)

Theme Files

themes/
├── default.json          # Base theme (no overrides)
├── brand-energy.json     # Orange primary palette
├── brand-forest.json     # Green primary palette
└── brand-royal.json      # Purple primary palette

Each theme JSON extends default and only overrides what changes:

{
  "name": "Energy",
  "extends": "default",
  "overrides": {
    "color": {
      "primary-50": "#fff7ed",
      "primary-500": "#f97316",
      "primary-900": "#7c2d12"
    }
  }
}

Create a New Theme

1. Add themes/brand-{name}.json
2. Run node build.mjs → generates tokens-brand-{name}.css
3. Validate: node validate-themes.mjs
4. Add the export to package.json

Scripts

| Command | Description | |---------|-------------| | node build.mjs | Generate tokens.css + brand CSS + DTCG | | node validate.mjs | Validate JSON integrity + naming + CSS output | | node validate-themes.mjs | Validate all theme files (4/4) | | node check-contrast.mjs | WCAG AA contrast check (42 color pairs) | | node figma-export.mjs | Export tokens in Figma format |

Package Exports

{
  ".": "./tokens.css",
  "./css": "./tokens.css",
  "./*.json": "./*.json",
  "./tokens-brand-energy.css": "./tokens-brand-energy.css",
  "./tokens-brand-forest.css": "./tokens-brand-forest.css",
  "./tokens-brand-royal.css": "./tokens-brand-royal.css",
  "./themes/*": "./tokens-*.css",
  "./dtcg": "./tokens.dtcg.json"
}

CSS Variable Naming Convention

All variables follow --ds-{category}-{name}:

--ds-color-primary-500
--ds-text-base
--ds-spacing-md
--ds-radius-lg
--ds-shadow-md
--ds-z-modal
--ds-duration-normal
--ds-breakpoint-lg
--ds-container-content-max
--ds-border-width-thin
--ds-surface-page         /* semantic */
--ds-action-primary       /* semantic */
--ds-status-success       /* semantic */

File Structure

packages/tokens/
├── colors.json            # 6 palettes × 10 steps
├── typography.json         # Families, sizes, weights, line-heights
├── spacing.json            # xs → 4xl
├── effects.json            # Radius, shadows
├── borders.json            # Widths, styles
├── breakpoints.json        # sm → 2xl
├── containers.json         # Max-widths
├── layout.json             # Z-index, duration, easing
├── semantic.json           # Light/dark semantic mappings
├── themes/                 # Brand theme overrides
├── build.mjs               # ← Builder
├── validate.mjs            # ← Validator
├── validate-themes.mjs     # ← Theme validator
├── check-contrast.mjs      # ← Contrast checker
├── figma-export.mjs        # ← Figma exporter
├── tokens.css              # ← Generated output
├── tokens-brand-*.css      # ← Generated brand overrides
└── tokens.dtcg.json        # ← Generated W3C DTCG format