@transcodes/design-tokens

A comprehensive design token system built with Style Dictionary. Features dark mode support, WCAG AA accessibility compliance, and responsive design values.


Features

- Dark Mode Support - Automatic system detection + manual override with data-theme (58 dark tokens)
- WCAG AA Compliant - All color combinations meet accessibility contrast requirements
- Utopia Fluid Tokens - Responsive typography and spacing using CSS clamp() (v0.3.6+)
- Size Tokens - Comprehensive sizing system for icons, spinners, borders (v0.3.6+)
- TypeScript Support - Full type definitions included
- CSS Auto-import - Zero-config CSS loading (v0.3.1+)
- Tree-shakable - Optimized for modern bundlers

Installation

``bash
npm install @transcodes/design-tokens


or


bun add @transcodes/design-tokens
`

Quick Start

$3

`typescript
// CSS automatically loaded (light + dark themes)
import '@transcodes/design-tokens';
`

That's it! CSS variables are now available globally.

`css
.card {
color: var(--ink-black);
background: var(--paper-white);
padding: var(--space-md);
border-radius: var(--radius-md);
box-shadow: var(--shadow-card);
}
`

$3

`typescript
import { tokens, cssVars } from '@transcodes/design-tokens';

// camelCase keys
console.log(tokens.accentPrimary); // "#6b4fd9"
console.log(tokens.spaceMd); // "clamp(0.875rem, 0.77rem + 0.54vw, 1.25rem)"

// CSS variable names as keys
console.log(cssVars['--accent-primary']); // "#6b4fd9"
console.log(cssVars['--space-md']); // "clamp(0.875rem, 0.77rem + 0.54vw, 1.25rem)"
`

$3

Automatic Detection (v0.3.1+)

Dark mode is automatically applied based on system preferences:

`css
/ Respects prefers-color-scheme: dark /
@media (prefers-color-scheme: dark) {
:root:not([data-theme="light"]) {
/ Dark theme variables /
}
}
`

Manual Override

Force a specific theme:

`html








`

`javascript
// Toggle theme with manual override
function toggleTheme() {
const current = document.documentElement.getAttribute('data-theme');
const next = current === 'dark' ? 'light' : 'dark';
document.documentElement.setAttribute('data-theme', next);
}

// Reset to system preference
function resetTheme() {
document.documentElement.removeAttribute('data-theme');
}
`

Available Tokens

$3

| Token | Light | Dark | Usage |
|-------|-------|------|-------|
| --ink-black | #1a1a1a | #ffffff | Primary text |
| --ink-dark | #2d2d2d | #e5e5e5 | Secondary text |
| --ink-medium | #5c5c5c | #a3a3a3 | Tertiary text |
| --ink-light | #8a8a8a | #737373 | Placeholder text |
| --paper-white | #faf9fc | #1a1a1a | Primary background |
| --paper-cream | #f5f4f8 | #2d2d2d | Secondary background |
| --paper-warm | #ebe9f0 | #404040 | Tertiary background |
| --accent-primary | #6b4fd9 | #8b7ae8 | Brand accent |
| --accent-success | #357a46 | #4ade80 | Success state |
| --error-base | #c0392b | #f87171 | Error state |

$3

| Token | Description |
|-------|-------------|
| --button-dark | Dark button background |
| --button-dark-hover | Dark button hover state |
| --button-light | Light button background |
| --button-light-hover | Light button hover state |
| --semantic-warning-bg | Warning callout background |
| --semantic-success-bg | Success callout background |
| --semantic-info-bg | Info callout background |

$3

Responsive values that scale with viewport width using Utopia-style fluid scaling.

| Token | Value Range | Description |
|-------|-------------|-------------|
| --space-xs | 4px → 5px | Extra small |
| --space-sm | 8px → 10px | Small |
| --space-md | 14px → 20px | Medium |
| --space-lg | 20px → 32px | Large |
| --space-xl | 24px → 44px | Extra large |
| --space-2xl | 32px → 72px | 2X large |

Fluid Pair Tokens (v0.3.6+)

Steeper scaling for more dramatic responsive changes:

| Token | Value Range | Use Case |
|-------|-------------|----------|
| --space-xs-sm | 4px → 10px | Progressive scaling for small elements |
| --space-sm-md | 8px → 20px | Container padding |
| --space-md-lg | 14px → 32px | Section spacing |
| --space-lg-xl | 20px → 44px | Major layout spacing |

$3

`css
/ Font families /
--font-body: 'DM Sans', system-ui, sans-serif;
--font-mono: 'JetBrains Mono', monospace;

/ Font sizes (fluid) /
--font-size-sm / 13px - 14px /
--font-size-base / 14px - 16px /
--font-size-lg / 16px - 18px /
--font-size-xl / 20px - 24px /
--font-size-2xl / 24px - 32px /

/ Line heights /
--line-height-tight: 1.25;
--line-height-normal: 1.5;
--line-height-relaxed: 1.75;
`

$3

`css
/ Border radius /
--radius-sm: 4px;
--radius-md: 8px;
--radius-lg: 12px;
--radius-full: 9999px;

/ Z-index scale /
--z-index-dropdown: 1000;
--z-index-sticky: 1020;
--z-index-modal: 1050;
--z-index-tooltip: 1070;
`

$3

`css
--transition-fast: 150ms ease;
--transition-smooth: 300ms cubic-bezier(0.4, 0, 0.2, 1);
--transition-bounce: 400ms cubic-bezier(0.34, 1.56, 0.64, 1);
`

$3

Comprehensive sizing system for consistent UI elements.

`css
/ Icon sizes /
--size-icon-xs: 0.75rem; / 12px /
--size-icon-sm: 1rem; / 16px /
--size-icon-md: 1.5rem; / 24px /
--size-icon-lg: 2rem; / 32px /
--size-icon-action: 1.25rem; / 20px - for arrows, callout icons /

/ Spinner sizes /
--size-spinner-sm: 1rem; / 16px /
--size-spinner-md: 2rem; / 32px /
--size-spinner-lg: 4rem; / 64px /
--size-spinner-button: 1.125rem; / 18px - inside buttons /

/ Border widths /
--size-border-width-thin: 0.0625rem; / 1px /
--size-border-width-base: 0.09375rem; / 1.5px /
--size-border-width-thick: 0.125rem; / 2px /
`

Exports

| Path | Description |
|------|-------------|
| @transcodes/design-tokens | Recommended - Auto-loads CSS + exports JS objects |
| @transcodes/design-tokens/css | CSS variables only (light theme) |
| @transcodes/design-tokens/tokens-dark.css | Dark theme CSS only |
| @transcodes/design-tokens/components.css | Component utility classes |
| @transcodes/design-tokens/components | Component styles as JS |
| @transcodes/design-tokens/types | TypeScript type definitions |
| @transcodes/design-tokens/json | Raw token values as JSON |

$3

`typescript
// v0.3.0 (manual CSS imports)
import '@transcodes/design-tokens/css';
import '@transcodes/design-tokens/tokens-dark.css';

// v0.3.1+ (automatic)
import '@transcodes/design-tokens';
`

Accessibility

All primary color combinations meet WCAG AA standards (4.5:1 minimum contrast ratio):

| Combination | Ratio | Level |
|-------------|-------|-------|
| ink-black on paper-white | 15.8:1 | AAA |
| ink-dark on paper-white | 12.5:1 | AAA |
| ink-medium on paper-white | 6.0:1 | AA |
| accent-primary on paper-white | 4.5:1 | AA |

Browser Support

Supports all modern browsers with CSS custom properties and clamp()`:

- Chrome 79+
- Firefox 75+
- Safari 13.1+
- Edge 79+

Related Packages

- @transcodes/ui-components - Lit 3.x component library using these tokens

Changelog

See CHANGELOG.md for release history.

License

MIT