# Use with AI tools

Query typestyles documentation from LLM crawlers, coding agents, and chat assistants


TypeStyles documentation is built for humans **and** AI tools. Every page has a clean Markdown sibling, a machine-readable index, and a remote MCP server you can add to your editor.

## Quick links

| Resource            | URL                                                                 |
| ------------------- | ------------------------------------------------------------------- |
| Documentation index | [llms.txt](https://typestyles.dev/llms.txt)                         |
| Full doc bundle     | [llms-full.txt](https://typestyles.dev/llms-full.txt)               |
| JSON index          | [docs-index.json](https://typestyles.dev/docs-index.json)           |
| MCP server          | [https://typestyles.dev/mcp](https://typestyles.dev/mcp)            |
| MCP discovery       | [.well-known/mcp.json](https://typestyles.dev/.well-known/mcp.json) |

Any doc page is also available as Markdown: append `.md` to the HTML path — for example [getting-started.md](https://typestyles.dev/docs/getting-started.md).

## MCP server tools

The MCP server at `https://typestyles.dev/mcp` exposes read-only tools:

- **`search_docs`** — keyword search across all pages
- **`get_doc`** — full clean markdown for one page by slug
- **`list_docs`** — all pages grouped by sidebar category
- **`lookup_api`** — API reference sections by symbol (e.g. `styles.component`)
- **`get_examples`** — code blocks from the docs by topic
- **`get_changelog`** — package changelogs, optionally one version

Doc pages are also available as MCP resources at `typestyles://docs/<slug>`.

## Add to your editor

### Claude Code

```bash
claude mcp add --transport http typestyles https://typestyles.dev/mcp
```

### Cursor

Add to your MCP config (`.cursor/mcp.json` in your project or global Cursor settings):

```json
{
  "mcpServers": {
    "typestyles": {
      "url": "https://typestyles.dev/mcp"
    }
  }
}
```

### VS Code

Add to your user or workspace MCP settings:

```json
{
  "servers": {
    "typestyles": {
      "type": "http",
      "url": "https://typestyles.dev/mcp"
    }
  }
}
```

### ChatGPT

Use **Connectors** or custom GPT actions with the MCP endpoint `https://typestyles.dev/mcp` (Streamable HTTP transport).

## On-page actions

Every documentation page includes **Copy as Markdown**, **View as Markdown**, and **Open in AI** actions next to the title. Use them to paste a page into Claude or ChatGPT with one click.

## In your project

The `typestyles` npm package ships an [`llms.txt`](https://www.npmjs.com/package/typestyles) with API patterns and links to the full docs. Agents working inside consumer repos can read it from `node_modules/typestyles/llms.txt`.

The [typestyles monorepo](https://github.com/type-styles/typestyles) includes an `AGENTS.md` at the repo root with monorepo layout and build commands.

Source: https://typestyles.dev/docs/ai-tools

---

# Animation Patterns

Common animation patterns and techniques with typestyles


TypeStyles supports CSS animations through the `keyframes` API. This guide covers common animation patterns and best practices.

## Basic animations

### Fade in

```ts
import { keyframes, styles } from 'typestyles';

const fadeIn = keyframes.create('fadeIn', {
  from: { opacity: 0 },
  to: { opacity: 1 },
});

const card = styles.component('card', {
  base: {
    animation: `${fadeIn} 300ms ease`,
  },
});
```

### Slide in

```ts
const slideInRight = keyframes.create('slideInRight', {
  from: {
    opacity: 0,
    transform: 'translateX(20px)',
  },
  to: {
    opacity: 1,
    transform: 'translateX(0)',
  },
});

const slideInLeft = keyframes.create('slideInLeft', {
  from: {
    opacity: 0,
    transform: 'translateX(-20px)',
  },
  to: {
    opacity: 1,
    transform: 'translateX(0)',
  },
});

const slideInUp = keyframes.create('slideInUp', {
  from: {
    opacity: 0,
    transform: 'translateY(20px)',
  },
  to: {
    opacity: 1,
    transform: 'translateY(0)',
  },
});

const slideInDown = keyframes.create('slideInDown', {
  from: {
    opacity: 0,
    transform: 'translateY(-20px)',
  },
  to: {
    opacity: 1,
    transform: 'translateY(0)',
  },
});
```

### Scale animations

```ts
const scaleIn = keyframes.create('scaleIn', {
  from: {
    opacity: 0,
    transform: 'scale(0.9)',
  },
  to: {
    opacity: 1,
    transform: 'scale(1)',
  },
});

const scaleOut = keyframes.create('scaleOut', {
  from: {
    opacity: 1,
    transform: 'scale(1)',
  },
  to: {
    opacity: 0,
    transform: 'scale(0.9)',
  },
});

const popIn = keyframes.create('popIn', {
  '0%': { transform: 'scale(0)' },
  '70%': { transform: 'scale(1.1)' },
  '100%': { transform: 'scale(1)' },
});
```

## Common UI animations

### Loading spinner

```ts
const spin = keyframes.create('spin', {
  from: { transform: 'rotate(0deg)' },
  to: { transform: 'rotate(360deg)' },
});

const spinner = styles.component('spinner', {
  base: {
    display: 'inline-block',
    width: '24px',
    height: '24px',
    border: '3px solid #e5e7eb',
    borderTopColor: '#3b82f6',
    borderRadius: '50%',
    animation: `${spin} 800ms linear infinite`,
  },

  sm: {
    width: '16px',
    height: '16px',
    borderWidth: '2px',
  },

  lg: {
    width: '32px',
    height: '32px',
    borderWidth: '4px',
  },
});
```

### Pulse animation

```ts
const pulse = keyframes.create('pulse', {
  '0%, 100%': { opacity: 1 },
  '50%': { opacity: 0.5 },
});

const skeleton = styles.component('skeleton', {
  base: {
    backgroundColor: '#e5e7eb',
    borderRadius: '4px',
    animation: `${pulse} 2s ease-in-out infinite`,
  },
});
```

### Shake animation (error state)

```ts
const shake = keyframes.create('shake', {
  '0%, 100%': { transform: 'translateX(0)' },
  '10%, 30%, 50%, 70%, 90%': { transform: 'translateX(-4px)' },
  '20%, 40%, 60%, 80%': { transform: 'translateX(4px)' },
});

const input = styles.component('input', {
  base: { ... },
  error: {
    borderColor: '#ef4444',
    animation: `${shake} 500ms ease-in-out`,
  },
});
```

### Bounce animation

```ts
const bounce = keyframes.create('bounce', {
  '0%, 100%': {
    transform: 'translateY(0)',
    animationTimingFunction: 'cubic-bezier(0.8, 0, 1, 1)',
  },
  '50%': {
    transform: 'translateY(-25%)',
    animationTimingFunction: 'cubic-bezier(0, 0, 0.2, 1)',
  },
});

const notification = styles.component('notification', {
  badge: {
    animation: `${bounce} 1s infinite`,
  },
});
```

## Page transitions

### Page fade

```ts
const pageFadeIn = keyframes.create('pageFadeIn', {
  from: { opacity: 0 },
  to: { opacity: 1 },
});

const pageLayout = styles.component('page', {
  container: {
    animation: `${pageFadeIn} 300ms ease`,
  },
});
```

### Staggered list items

```ts
// Individual item animation
const listItemFadeIn = keyframes.create('listItemFadeIn', {
  from: {
    opacity: 0,
    transform: 'translateY(10px)',
  },
  to: {
    opacity: 1,
    transform: 'translateY(0)',
  },
});

// Delay classes for stagger effect
const list = styles.component('list', {
  item: {
    opacity: 0,
    animation: `${listItemFadeIn} 300ms ease forwards`,
  },

  itemDelay1: { animationDelay: '50ms' },
  itemDelay2: { animationDelay: '100ms' },
  itemDelay3: { animationDelay: '150ms' },
  itemDelay4: { animationDelay: '200ms' },
  itemDelay5: { animationDelay: '250ms' },
});

// React usage with index
function List({ items }) {
  return (
    <ul>
      {items.map((item, index) => (
        <li
          key={item.id}
          className={list(
            'item',
            index === 0 && 'itemDelay1',
            index === 1 && 'itemDelay2',
            index === 2 && 'itemDelay3',
            // ... or use a function to calculate delay
          )}
        >
          {item.name}
        </li>
      ))}
    </ul>
  );
}
```

## Micro-interactions

### Button press

```ts
const buttonPress = keyframes.create('buttonPress', {
  '0%': { transform: 'scale(1)' },
  '50%': { transform: 'scale(0.95)' },
  '100%': { transform: 'scale(1)' },
});

const button = styles.component('button', {
  base: {
    transition: 'transform 100ms ease',

    '&:active': {
      transform: 'scale(0.95)',
    },
  },

  // Or with keyframe for more control
  press: {
    animation: `${buttonPress} 150ms ease`,
  },
});
```

### Checkbox check

```ts
const checkmark = keyframes.create('checkmark', {
  '0%': {
    strokeDashoffset: 100,
  },
  '100%': {
    strokeDashoffset: 0,
  },
});

const checkbox = styles.component('checkbox', {
  base: { ... },

  checkmark: {
    strokeDasharray: 100,
    strokeDashoffset: 100,
  },

  checked: {
    '& .checkmark': {
      animation: `${checkmark} 200ms ease forwards`,
    },
  },
});
```

### Hover lift effect

```ts
const card = styles.component('card', {
  base: {
    transition: 'transform 200ms ease, box-shadow 200ms ease',
  },

  interactive: {
    cursor: 'pointer',

    '&:hover': {
      transform: 'translateY(-4px)',
      boxShadow: '0 12px 24px rgba(0, 0, 0, 0.15)',
    },
  },
});
```

## Complex animations

### Modal enter/exit

```ts
const modalBackdropFadeIn = keyframes.create('modalBackdropFadeIn', {
  from: { opacity: 0 },
  to: { opacity: 1 },
});

const modalBackdropFadeOut = keyframes.create('modalBackdropFadeOut', {
  from: { opacity: 1 },
  to: { opacity: 0 },
});

const modalContentSlideIn = keyframes.create('modalContentSlideIn', {
  from: {
    opacity: 0,
    transform: 'scale(0.95) translateY(10px)',
  },
  to: {
    opacity: 1,
    transform: 'scale(1) translateY(0)',
  },
});

const modalContentSlideOut = keyframes.create('modalContentSlideOut', {
  from: {
    opacity: 1,
    transform: 'scale(1) translateY(0)',
  },
  to: {
    opacity: 0,
    transform: 'scale(0.95) translateY(10px)',
  },
});

const modal = styles.component('modal', {
  backdrop: {
    position: 'fixed',
    inset: 0,
    backgroundColor: 'rgba(0, 0, 0, 0.5)',
  },

  backdropEnter: {
    animation: `${modalBackdropFadeIn} 200ms ease`,
  },

  backdropExit: {
    animation: `${modalBackdropFadeOut} 200ms ease forwards`,
  },

  content: {
    backgroundColor: 'white',
    borderRadius: '8px',
    padding: '24px',
  },

  contentEnter: {
    animation: `${modalContentSlideIn} 300ms ease`,
  },

  contentExit: {
    animation: `${modalContentSlideOut} 200ms ease forwards`,
  },
});
```

### Toast notifications

```ts
const toastSlideIn = keyframes.create('toastSlideIn', {
  from: {
    opacity: 0,
    transform: 'translateX(100%)',
  },
  to: {
    opacity: 1,
    transform: 'translateX(0)',
  },
});

const toastSlideOut = keyframes.create('toastSlideOut', {
  from: {
    opacity: 1,
    transform: 'translateX(0)',
  },
  to: {
    opacity: 0,
    transform: 'translateX(100%)',
  },
});

const toastProgress = keyframes.create('toastProgress', {
  from: { transform: 'scaleX(1)' },
  to: { transform: 'scaleX(0)' },
});

const toast = styles.component('toast', {
  base: {
    padding: '16px 20px',
    borderRadius: '8px',
    boxShadow: '0 4px 12px rgba(0, 0, 0, 0.15)',
  },

  enter: {
    animation: `${toastSlideIn} 300ms ease`,
  },

  exit: {
    animation: `${toastSlideOut} 300ms ease forwards`,
  },

  progressBar: {
    height: '3px',
    backgroundColor: 'rgba(255, 255, 255, 0.3)',
    marginTop: '12px',
    transformOrigin: 'left',
    animation: `${toastProgress} 5000ms linear forwards`,
  },

  success: {
    backgroundColor: '#10b981',
    color: 'white',
  },

  error: {
    backgroundColor: '#ef4444',
    color: 'white',
  },

  info: {
    backgroundColor: '#3b82f6',
    color: 'white',
  },
});
```

### Skeleton loading

```ts
const shimmer = keyframes.create('shimmer', {
  '0%': { backgroundPosition: '-200% 0' },
  '100%': { backgroundPosition: '200% 0' },
});

const skeleton = styles.component('skeleton', {
  base: {
    backgroundColor: '#e5e7eb',
    borderRadius: '4px',
  },

  animated: {
    background: 'linear-gradient(90deg, #e5e7eb 25%, #f3f4f6 50%, #e5e7eb 75%)',
    backgroundSize: '200% 100%',
    animation: `${shimmer} 1.5s infinite`,
  },

  text: {
    height: '1em',
    marginBottom: '0.5em',
  },

  textLarge: {
    height: '1.5em',
  },

  circle: {
    borderRadius: '50%',
  },

  avatar: {
    width: '40px',
    height: '40px',
  },

  card: {
    height: '200px',
  },
});
```

## Scroll animations

### Infinite scroll indicator

```ts
const scrollIndicator = keyframes.create('scrollIndicator', {
  '0%, 100%': {
    opacity: 1,
    transform: 'translateY(0)',
  },
  '50%': {
    opacity: 0.5,
    transform: 'translateY(6px)',
  },
});

const scrollCue = styles.component('scroll-cue', {
  base: {
    display: 'flex',
    flexDirection: 'column',
    alignItems: 'center',
    gap: '4px',
  },

  arrow: {
    animation: `${scrollIndicator} 1.5s ease-in-out infinite`,
  },

  arrowDelay1: { animationDelay: '0ms' },
  arrowDelay2: { animationDelay: '150ms' },
  arrowDelay3: { animationDelay: '300ms' },
});
```

## Best practices

### Performance

```ts
// ✅ Use transform and opacity for smooth animations
const goodAnimation = keyframes.create('goodAnimation', {
  from: {
    opacity: 0,
    transform: 'translateY(20px)', // GPU accelerated
  },
  to: {
    opacity: 1,
    transform: 'translateY(0)',
  },
});

// ❌ Avoid animating layout properties
const badAnimation = keyframes.create('badAnimation', {
  from: {
    height: 0, // Triggers layout
    marginTop: 0, // Triggers layout
  },
  to: {
    height: '100px',
    marginTop: '20px',
  },
});
```

### Accessibility

```ts
// Respect reduced motion preference
const animated = styles.component('animated', {
  base: {
    '@media (prefers-reduced-motion: reduce)': {
      animation: 'none',
      transition: 'none',
    },
  },
});
```

### Timing functions

```ts
// Standard curves
const ease = 'ease'; // Standard
const easeIn = 'ease-in'; // Accelerate
const easeOut = 'ease-out'; // Decelerate
const easeInOut = 'ease-in-out'; // Both

// Custom cubic-bezier for specific feels
const springy = 'cubic-bezier(0.68, -0.55, 0.265, 1.55)';
const smooth = 'cubic-bezier(0.4, 0, 0.2, 1)';
const enter = 'cubic-bezier(0, 0, 0.2, 1)';
const exit = 'cubic-bezier(0.4, 0, 1, 1)';

// Usage
const button = styles.component('button', {
  base: {
    transition: `transform 200ms ${springy}`,
  },
});
```

### Duration guidelines

| Animation Type    | Duration  | Use Case                    |
| ----------------- | --------- | --------------------------- |
| Micro-interaction | 100-200ms | Button press, hover states  |
| Standard          | 200-300ms | Modals, dropdowns, tooltips |
| Complex           | 300-500ms | Page transitions, reveals   |
| Ambient           | 1-10s     | Loading states, skeletons   |

### Naming conventions

```ts
// Use descriptive names
const fadeIn = keyframes.create('fadeIn', { ... });
const slideUp = keyframes.create('slideUp', { ... });
const modalEnter = keyframes.create('modalEnter', { ... });
const modalExit = keyframes.create('modalExit', { ... });

// Include direction when applicable
const slideInRight = keyframes.create('slideInRight', { ... });
const slideInLeft = keyframes.create('slideInLeft', { ... });
const slideOutUp = keyframes.create('slideOutUp', { ... });
```

## Animation utilities

### Animation delay helper

```ts
function createStaggeredAnimation(
  baseName: string,
  itemCount: number,
  baseDelay: number
): Record<string, string> {
  const delays: Record<string, string> = {};

  for (let i = 0; i < itemCount; i++) {
    delays[`delay${i + 1}`] = `${baseDelay * (i + 1)}ms`;
  }

  return delays;
}

// Usage in React
function StaggeredList({ items }) {
  const delayClass = (index: number) => {
    const delays = ['delay1', 'delay2', 'delay3', 'delay4', 'delay5'];
    return delays[index] || 'delay5';
  };

  return (
    <ul>
      {items.map((item, index) => (
        <li
          key={item.id}
          className={list('item', delayClass(index))}
        >
          {item.name}
        </li>
      ))}
    </ul>
  );
}
```

### Animation presets

```ts
// animations/presets.ts
export const presets = {
  fade: {
    in: 'fadeIn 300ms ease',
    out: 'fadeOut 200ms ease',
  },
  slide: {
    up: 'slideUp 300ms ease',
    down: 'slideDown 300ms ease',
    left: 'slideLeft 300ms ease',
    right: 'slideRight 300ms ease',
  },
  scale: {
    in: 'scaleIn 200ms ease',
    out: 'scaleOut 200ms ease',
  },
  bounce: 'bounce 500ms ease',
  pulse: 'pulse 2s ease-in-out infinite',
  spin: 'spin 1s linear infinite',
  shake: 'shake 500ms ease-in-out',
} as const;

// Usage
const modal = styles.component('modal', {
  enter: {
    animation: presets.fade.in,
  },
});
```

## Summary

1. **Use transform and opacity** - Best performance
2. **Respect reduced motion** - Accessibility first
3. **Keep animations purposeful** - Don't animate just because you can
4. **Use appropriate timing** - Match animation to importance
5. **Consider physics** - Natural motion feels better
6. **Test on real devices** - Performance varies
7. **Name descriptively** - Make intent clear
8. **Reuse animations** - Create a preset library
9. **Document timing** - Help other developers
10. **Test with users** - Get feedback on feel

Source: https://typestyles.dev/docs/animation-patterns

---

# API Reference

Complete API reference for typestyles


Auto-generated documentation for all typestyles APIs.

## Core Exports

### `styles`

Default style API (semantic class names, empty `scopeId`). Prefer `createStyles({ scopeId, mode, prefix })`
per package or micro-frontend for isolation.

**Methods:**

- `styles.component(namespace, config)`: Create multi-variant component styles (CVA-style)
- `styles.class(name, properties)`: Create a single class
- `styles.container(…)`: Build typed `@container` keys for nested styles (also exported as `container`). Object/two-arg forms infer a **literal** `@container …` string, so `[container({ minWidth: 400 })]: { … }` works next to longhands without casting; use `atRuleBlock` when the key is only known as a generic `string`.
- `styles.has(…)`, `styles.is(…)`, `styles.where(…)`: Build nested `&`-keys for `:has()`, `:is()`, and `:where()` (same as the `has` / `is` / `where` exports). Literal arguments narrow to a concrete `&:…` key so you can mix them with longhands as `[has('.x')]: { … }` without `as CSSProperties`. `:where()` keeps **zero specificity**; raw `'&:has(…)'` strings still work.
- `styles.atRuleBlock(key, nested)`: Spreadable `{ [@key]: nested }` so `@…` keys type-check (also exported as `atRuleBlock`)
- `styles.containerRef(label)`: Readable `{scopeId}-{label}` or `{prefix}-{label}` `container-name` (see `createContainerRef`)
- `styles.hashClass(properties, label?)`: Create a deterministic hashed class
- `styles.property(id, options?)`: Register a standalone CSS custom property (optional `@property` when `syntax` is set); returns `{ name, var, toString }`
- `styles.compose(...fns)`: Compose multiple style functions
- `styles.withUtils(utils)`: Create a utility-aware styles API (prefer `createStyles({ utils })` for a single instance)
- `styles.classNaming`: Read-only resolved naming config for the default `styles` instance

**Named exports (same behavior as `styles.*`):** `container`, `createContainerRef`, `atRuleBlock`, `has`, `is`, `where`.

**Related types:** `ContainerQueryKey`, `ContainerObjectKey`, `HasNestedKey`, `IsNestedKey`, `WhereNestedKey`, `IsPseudoArg`. See [Custom selectors & at-rules](/docs/custom-at-rules) and [TypeScript tips](/docs/typescript-tips).

### `createStyles(options?)`

Returns a new style API (same shape as `styles`) with its own class naming config. Pass `Partial<ClassNamingConfig>`: `mode` (`'semantic' | 'hashed' | 'compact' | 'atomic'`), `prefix`, `scopeId`. Optionally pass **`utils`** — a map of shorthand expanders — to get a utility-aware API in one step (same typing as `styles.withUtils(…)`; see [Styles](/docs/styles#utility-shortcuts)). Optionally pass **`layers`** (tuple or `{ order, prependFrameworkLayers? }`) to enable **`@layer`** output; then every **`class`**, **`hashClass`**, and **`component`** call must include a third argument **`{ layer: '…' }`** (see [Cascade layers](/docs/cascade-layers)).

The default `import { styles } from 'typestyles'` is `createStyles()` with default options.

### `tokens`

Default token API (unscoped custom properties). Prefer `createTokens({ scopeId })` when multiple
bundles share a page.

**Methods:**

- `tokens.create(namespace, values)`: Creates CSS custom properties; returns a branded `CreatedTokenRef`. Leaf values may use `{ value, syntax?, inherits? }` to register `@property` and return `{ name, var, toString }` refs instead of plain `var(...)` strings.
- `tokens.use(namespace | createdRef)`: References existing tokens; infers types from a `tokens.create()` return value or a `createTokens<Registry>()` generic
- `tokens.createTheme(name, config)`: Registers a theme class that overrides token custom properties
- `tokens.createDarkMode(name, darkOverrides)`: Shorthand theme with a single dark `@media` branch
- `tokens.when` / `tokens.colorMode`: Condition helpers for themes
- `tokens.scopeId`: The scope passed to `createTokens`, if any

### `createTokens(options?)`

Returns a token + theme API bound to an optional `scopeId`. When set, `tokens.create('color', …)` emits `--{scopeId}-color-*` variables and `tokens.createTheme('dark', …)` registers `.theme-{scopeId}-dark` (sanitized segments). With **`layers`**, **`tokenLayer`** is required and token/theme CSS is wrapped in that layer. Optional **`nameTemplate`** on the instance or per `tokens.create` call controls emitted `--*` names (see [Tokens](/docs/tokens#custom-css-variable-names-nametemplate)).

The default `import { tokens } from 'typestyles'` is `createTokens()` (no scope).

Exported types: **`TokenNameContext`**, **`TokenNameTemplate`**, **`FlatTokenPathEntry`**. Helper: **`flattenTokenPaths`** (segment-preserving flatten for custom templates).

### `keyframes`

Keyframe animation API.

**Methods:**

- `keyframes.create(name, stops)`: Creates @keyframes animation

### `color` (`typestyles/color`)

Type-safe CSS color function helpers, on a **separate subpath** so the main `typestyles` entry stays lean. Import `color` (namespace) or named functions from `typestyles/color`.

Each function returns a plain CSS color string — no runtime color math.
Composes naturally with token references.

**Functions:**

- `color.rgb(r, g, b, alpha?)`: RGB color
- `color.hsl(h, s, l, alpha?)`: HSL color
- `color.oklch(l, c, h, alpha?)`: OKLCH color
- `color.oklab(l, a, b, alpha?)`: OKLAB color
- `color.lab(l, a, b, alpha?)`: LAB color
- `color.lch(l, c, h, alpha?)`: LCH color
- `color.hwb(h, w, b, alpha?)`: HWB color
- `color.mix(c1, c2, p?, space?)`: Mix two colors
- `color.lightDark(light, dark)`: Light/dark mode color
- `color.alpha(color, opacity, space?)`: Adjust opacity

See [Color](/docs/color).

### `color-scale` (`typestyles/color-scale`)

OKLCH ramp generation and WCAG contrast math, on a **separate subpath** (zero impact on main bundle size).

**Functions:**

- `parseColor(hex)`: Hex → `{ l, c, h }` in OKLCH units (hex only in v1)
- `generateRamp({ hue, chroma, steps?, lightnessRange? })`: Perceptual OKLCH ramp (lightest → darkest)
- `contrastRatio(colorA, colorB)`: WCAG relative luminance ratio (hex or `oklch()` strings)

See [Theming Patterns — Generating a theme from one accent color](/docs/theming-patterns#generating-a-theme-from-one-accent-color).

### `token-scale` (`typestyles/token-scale`)

Generic numeric ramp generators for type/motion/radius ladders, on a **separate subpath** (zero impact on main bundle size). Pure numbers in, pure numbers out — naming steps is a design-system concern.

**Functions:**

- `generateGeometricScale({ base, ratio, steps, round? })`: `base * ratio ** offset` for each signed integer offset in `steps` (font-size-style ladders)
- `generateLinearScale({ base, multiplier, steps, round? })`: `base * step * multiplier` for each ordinal in `steps` (radius-style ladders)
- `expandDurationBand({ base, ratio, roundTo? })`: `{ min, base, max }` motion band (`min = base * ratio`, `max = base / ratio`, rounded to nearest 5 by default)

See [Theming Patterns — Generating type, motion, and radius scales](/docs/theming-patterns#generating-type-motion-and-radius-scales).

### `calc` and `clamp`

Helpers for CSS `calc()` and `clamp()` that always emit balanced outer parentheses:

- **`calc`** — tagged template: `` calc`100vh - ${token}` `` → `calc(100vh - …)`
- **`clamp(min, preferred, max)`** — three arguments → `clamp(min, preferred, max)`

See [TypeScript Tips — Complex CSS values](/docs/typescript-tips).

### `createTypeStyles(options)`

Returns **`{ styles, tokens, global }`** with one shared **`scopeId`** (and optional **`mode`**, **`prefix`**, **`layers`**, **`tokenLayer`**). When **`layers`** is omitted, behavior matches separate **`createStyles()`** + **`createTokens()`** (no `@layer` in output). When **`layers`** is set, **`tokenLayer`** is required and both APIs use the same cascade-layer stack. See [Cascade layers](/docs/cascade-layers).

**Default singleton:** `import { styles, tokens } from 'typestyles'` is the same as calling `createStyles()` and `createTokens()` with **no** `scopeId`. That is fine for throwaway demos, but **prefer `createTypeStyles({ scopeId })`** in real apps and libraries so tokens and themes stay namespaced. Add **`global`** from the same constructor when you register [cascade layers](/docs/cascade-layers) or shared `@layer` stacks.

### Cascade layers (types)

Exported types include **`CascadeLayersInput`**, **`CascadeLayersObjectInput`**, **`ResolvedCascadeLayers`**, and **`ThemeEmitLayerContext`** (theme emission with layers).

### `global`

Global CSS helpers (not scoped to a component class):

- `global.style(selector, styles)`: Insert rules for an arbitrary selector. Rules dedupe by an internal key (`scopeId` + selector + layer when layered). A second call with the **same** key and **different** CSS is skipped; in non-`production` builds, TypeStyles logs a **console warning** so overlapping selectors (for example reset `body` plus your own `body`) are not silent failures. Reuse one call, merge properties, or use a more specific selector (e.g. `html body`).
- `global.fontFace(family, props)`: Register `@font-face` (supports `src` as a string or array of fragments, variable font weight ranges, `font-display`, `unicode-range`, and metric overrides — see [Fonts](/docs/fonts))

### `cx(...parts)`

Joins class name parts into a single string, filtering out falsy values (`false`, `undefined`, `null`, `0`, `''`).

Use `cx` to combine TypeStyles classes with external class strings and conditional expressions.

```ts
import { cx, styles } from 'typestyles';

const card = styles.component('card', {
  base: { padding: '16px' },
  elevated: { boxShadow: '0 4px 12px rgba(0,0,0,0.1)' },
});

cx(card(), isElevated && card.elevated, externalClassName);
```

### CSS variables (dynamic styling)

- [`createVar(name?, fallback?)`](/docs/dynamic-styles), [`assignVars(vars)`](/docs/dynamic-styles): Typed custom property helpers for per-instance dynamic values. Pass a debug name (e.g. `createVar('cardBg')`) for readable DevTools property names.

### Sheet and testing utilities

- `getRegisteredCss()`: Returns all CSS registered so far (useful with SSR or diagnostics)
- `subscribeRegisteredCss(listener)`: Subscribe to CSS registration changes; returns an unsubscribe function. Compatible with React `useSyncExternalStore` (used by `@typestyles/next` `useTypestyles`)
- `reset()`, `flushSync()`, `ensureDocumentStylesAttached()`: Primarily for tests and advanced setup; see [Testing](/docs/testing)
- `insertRules(rules)`: Low-level rule insertion (mainly for library authors)

### SSR helpers (`typestyles/server`)

- `collectStyles(renderFn)`: Wrap a sync or async render; returns `{ html, css }`. Request-isolated on Node via `AsyncLocalStorage`. See [SSR](/docs/ssr).
- `TYPESTYLES_STYLE_ID`: Stable `"typestyles"` id for the managed `<style>` element (must match client hydration)
- `typestylesStyleHtml(css)`: Render `<style id="typestyles">…</style>` (empty string when `css` is empty)
- `injectStylesIntoHtml(html, css)`: Insert collected CSS before `</head>`
- `streamingDocumentShell(css)`: Open doctype + `<head>` + `<body>` for `renderToPipeableStream` (pair with `collectStyles` for the CSS pass)

### Class naming helpers

- `mergeClassNaming(partial?)`: Build a full `ClassNamingConfig` from partial options
- `defaultClassNamingConfig`: Default `mode`, `prefix`, and `scopeId`
- `scopedTokenNamespace(scopeId, logicalNamespace)`: CSS variable namespace segment for scoped token instances

See [Class naming](/docs/class-naming).

## Usage Examples

### Creating Styles

```ts
import { styles } from 'typestyles';

const button = styles.component('button', {
  base: { padding: '8px 16px' },
  variants: {
    intent: { primary: { backgroundColor: '#0066ff' } },
  },
  defaultVariants: { intent: 'primary' },
});

button(); // "button-base button-intent-primary"
button({ intent: 'primary' }); // same
const { base } = button; // destructure class strings
```

### Creating Tokens

```ts
import { tokens } from 'typestyles';

const color = tokens.create('color', {
  primary: '#0066ff',
  secondary: '#6b7280',
});

color.primary; // "var(--color-primary)"
```

### Scoped instances (libraries / micro-frontends)

```ts
import { createStyles, createTokens } from 'typestyles';

export const styles = createStyles({ scopeId: 'my-ds', mode: 'hashed', prefix: 'ds' });
export const tokens = createTokens({ scopeId: 'my-ds' });
```

### `:has()`, `:is()`, `:where()` (nested selectors)

Use the helpers as **computed keys** so you keep normal CSS semantics (including `:where`’s zero specificity) with the same “small builder” ergonomics as `container()`:

```ts
import { styles } from 'typestyles';

const nav = styles.class('nav', {
  display: 'flex',
  [styles.where('.nav')]: { gap: '8px' },
  [styles.has('.active')]: { borderBottom: '2px solid blue' },
  [styles.is(':hover', ':focus-visible')]: { outline: '2px solid blue' },
});
```

The named exports `has`, `is`, and `where` are identical to `styles.has` / `styles.is` / `styles.where`. The `IsPseudoArg` type documents common pseudos for `:is()` groups.

### Creating Animations

```ts
import { keyframes } from 'typestyles';

const fadeIn = keyframes.create('fadeIn', {
  from: { opacity: 0 },
  to: { opacity: 1 },
});

// Use in styles
animation: `${fadeIn} 300ms ease`;
```

---

_This API reference was auto-generated from source code._
_Last updated: 2026-04-06_

Source: https://typestyles.dev/docs/api-reference

---

# Atomic CSS Utilities

Type-safe atomic CSS utilities with @typestyles/props


The `@typestyles/props` package provides a type-safe way to generate atomic CSS utility classes, similar to Tailwind CSS but with full TypeScript inference and zero runtime overhead.

Runtime APIs such as `styles.class`, `styles.component`, and `styles.hashClass` use a separate naming system; to change those class strings (semantic vs hashed), see [Class naming](/docs/class-naming).

**Compare approaches:** this package (`defineProperties` + `createProps`) powers layout utilities on the docs site ([`docs/src/atoms.ts`](https://github.com/type-styles/typestyles/blob/main/docs/src/atoms.ts)). For hand-written `styles.class` utilities (Tailwind-style), see [examples/typewind](https://github.com/type-styles/typestyles/blob/main/examples/typewind/README.md).

## Installation

```bash
npm install @typestyles/props
```

## Quick Start

```ts
import { defineProperties, createProps } from '@typestyles/props';

// Define your atomic utilities
const atoms = createProps(
  'atom',
  defineProperties({
    properties: {
      display: ['flex', 'block', 'grid', 'none'],
      padding: { 0: '0', 1: '4px', 2: '8px', 3: '16px' },
      gap: { 0: '0', 1: '4px', 2: '8px', 3: '16px' },
    },
  }),
);

// Use them with full type safety
atoms({
  display: 'flex',
  padding: 2,
  gap: 1,
});
// Returns: "atom-display-flex atom-padding-2 atom-gap-1"
```

## Defining Properties

Use `defineProperties()` to define a collection of CSS properties with their allowed values:

### Array-Based Values

For enumerated values like display modes:

```ts
const utilities = defineProperties({
  properties: {
    display: ['flex', 'block', 'grid', 'none', 'inline-flex'],
    flexDirection: ['row', 'column', 'row-reverse', 'column-reverse'],
    alignItems: ['start', 'center', 'end', 'stretch', 'baseline'],
  },
});
```

### Object-Based Values

For scale-based values like spacing or font sizes:

```ts
const utilities = defineProperties({
  properties: {
    padding: {
      0: '0',
      1: '0.25rem',
      2: '0.5rem',
      3: '0.75rem',
      4: '1rem',
      8: '2rem',
    },
    fontSize: {
      xs: '0.75rem',
      sm: '0.875rem',
      base: '1rem',
      lg: '1.125rem',
      xl: '1.25rem',
    },
  },
});
```

## Responsive Conditions

Add breakpoints and other conditional styles:

```ts
const responsive = defineProperties({
  conditions: {
    mobile: { '@media': '(min-width: 640px)' },
    tablet: { '@media': '(min-width: 768px)' },
    desktop: { '@media': '(min-width: 1024px)' },
  },
  properties: {
    display: ['flex', 'block', 'grid'],
    flexDirection: ['row', 'column'],
  },
});

const atoms = createProps('atom', responsive);

// Apply responsive values
atoms({
  display: 'block', // Base value
  flexDirection: { mobile: 'column', desktop: 'row' }, // Responsive
});
// Returns: "atom-display-block atom-flexDirection-mobile-column atom-flexDirection-desktop-row"
```

### Condition Types

**Media Queries:**

```ts
{ mobile: { '@media': '(min-width: 768px)' } }
```

**Container Queries:**

```ts
{ wide: { '@container': '(min-width: 400px)' } }
```

**Feature Queries:**

```ts
{ supportsGrid: { '@supports': '(display: grid)' } }
```

**Custom Selectors:**

```ts
{
  hover: {
    selector: '&:hover';
  }
}
{
  dark: {
    selector: '[data-theme="dark"] &';
  }
}
```

## Shorthands

Define shorthands that expand to multiple properties:

```ts
const spacing = defineProperties({
  properties: {
    paddingTop: { 0: '0', 1: '4px', 2: '8px' },
    paddingRight: { 0: '0', 1: '4px', 2: '8px' },
    paddingBottom: { 0: '0', 1: '4px', 2: '8px' },
    paddingLeft: { 0: '0', 1: '4px', 2: '8px' },
  },
  shorthands: {
    padding: ['paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft'],
    paddingX: ['paddingLeft', 'paddingRight'],
    paddingY: ['paddingTop', 'paddingBottom'],
  },
});

const atoms = createProps('atom', spacing);

atoms({ padding: 2 });
// Expands to: paddingTop, paddingRight, paddingBottom, paddingLeft all set to 2
// Returns: "atom-paddingTop-2 atom-paddingRight-2 atom-paddingBottom-2 atom-paddingLeft-2"

atoms({ paddingX: 1, paddingY: 2 });
// Returns: "atom-paddingLeft-1 atom-paddingRight-1 atom-paddingTop-2 atom-paddingBottom-2"
```

## Combining Property Collections

Merge multiple property collections into one props function:

```ts
const layout = defineProperties({
  properties: {
    display: ['flex', 'block', 'grid'],
    position: ['relative', 'absolute', 'fixed', 'sticky'],
  },
});

const spacing = defineProperties({
  properties: {
    padding: { 0: '0', 1: '4px', 2: '8px' },
    margin: { 0: '0', 1: '4px', 2: '8px', auto: 'auto' },
  },
});

const colors = defineProperties({
  properties: {
    color: { primary: '#0066ff', secondary: '#6b7280' },
    backgroundColor: { white: '#ffffff', gray: '#f3f4f6' },
  },
});

// Combine all collections
const atoms = createProps('atom', layout, spacing, colors);

// Use properties from any collection
atoms({
  display: 'flex',
  padding: 2,
  color: 'primary',
});
```

## Default Conditions

Set a default condition for all property values:

```ts
const mobileFirst = defineProperties({
  conditions: {
    tablet: { '@media': '(min-width: 768px)' },
    desktop: { '@media': '(min-width: 1024px)' },
  },
  defaultCondition: false, // No condition by default (mobile-first)
  properties: {
    fontSize: { sm: '14px', base: '16px', lg: '18px' },
  },
});

const desktopFirst = defineProperties({
  conditions: {
    mobile: { '@media': '(max-width: 768px)' },
  },
  defaultCondition: 'mobile', // All values get mobile condition by default
  properties: {
    fontSize: { sm: '14px', base: '16px', lg: '18px' },
  },
});
```

## SSR Support

CSS is automatically injected and available for SSR:

```ts
import { getRegisteredCss } from 'typestyles';

// Define and create your atoms
const atoms = createProps(
  'atom',
  defineProperties({
    /* ... */
  }),
);

// CSS is automatically registered
const css = getRegisteredCss();
// Contains all atomic utility classes
```

## Composing with Component Styles

Combine atomic utilities with component-specific styles using `styles.compose()`:

```ts
import { styles } from 'typestyles';
import { createProps, defineProperties } from '@typestyles/props';

const atoms = createProps(
  'atom',
  defineProperties({
    properties: {
      display: ['flex', 'grid'],
      gap: { 0: '0', 1: '4px', 2: '8px' },
      padding: { 0: '0', 1: '4px', 2: '8px', 3: '16px' },
    },
  }),
);

const card = styles.component('card', {
  base: {
    borderRadius: '8px',
    border: '1px solid #e5e5e5',
    background: 'white',
  },
});

// Compose together
const flexCard = styles.compose(card, atoms({ display: 'flex', gap: 2, padding: 3 }));

flexCard();
// "card-base atom-display-flex atom-gap-2 atom-padding-3"
```

## Real-World Example

Building a complete design system:

```ts
import { defineProperties, createProps } from '@typestyles/props';

// Define responsive breakpoints and utilities
const atoms = createProps(
  'ds',
  defineProperties({
    conditions: {
      sm: { '@media': '(min-width: 640px)' },
      md: { '@media': '(min-width: 768px)' },
      lg: { '@media': '(min-width: 1024px)' },
      xl: { '@media': '(min-width: 1280px)' },
      dark: { selector: '[data-theme="dark"] &' },
      hover: { selector: '&:hover' },
    },
    properties: {
      // Layout
      display: ['none', 'flex', 'block', 'grid', 'inline-flex'],
      flexDirection: ['row', 'column'],
      alignItems: ['start', 'center', 'end', 'stretch'],
      justifyContent: ['start', 'center', 'end', 'between', 'around'],

      // Spacing
      gap: { 0: '0', 1: '0.25rem', 2: '0.5rem', 3: '0.75rem', 4: '1rem' },
      padding: { 0: '0', 1: '0.25rem', 2: '0.5rem', 4: '1rem', 8: '2rem' },
      margin: { 0: '0', auto: 'auto', 1: '0.25rem', 2: '0.5rem' },

      // Typography
      fontSize: { xs: '0.75rem', sm: '0.875rem', base: '1rem', lg: '1.125rem' },
      fontWeight: { normal: '400', medium: '500', semibold: '600', bold: '700' },

      // Colors
      color: { primary: '#3b82f6', secondary: '#64748b', muted: '#94a3b8' },
      backgroundColor: { white: '#fff', gray: '#f1f5f9', transparent: 'transparent' },
    },
    shorthands: {
      p: ['padding'],
      px: ['paddingLeft', 'paddingRight'],
      py: ['paddingTop', 'paddingBottom'],
      m: ['margin'],
    },
  })
);

// Use in components
export function Button() {
  return (
    <button
      className={atoms({
        display: 'inline-flex',
        alignItems: 'center',
        gap: 2,
        px: 4,
        py: 2,
        fontSize: { sm: 'sm', md: 'base' },
        fontWeight: 'semibold',
        color: 'white',
        backgroundColor: { _: 'primary', hover: 'secondary', dark: 'gray' },
      })}
    >
      Click me
    </button>
  );
}
```

## Class Naming

Classes follow a predictable pattern:

```
{namespace}-{property}-{value}
{namespace}-{property}-{condition}-{value}
```

Examples:

- `atom-display-flex`
- `atom-display-mobile-block`
- `atom-padding-2`
- `atom-padding-desktop-4`

## TypeScript

Full type inference and autocomplete for:

- Property names
- Property values
- Condition names
- Shorthand names

```ts
const atoms = createProps(
  'atom',
  defineProperties({
    properties: {
      display: ['flex', 'block'],
    },
  }),
);

atoms({ display: 'flex' }); // ✅
atoms({ display: 'grid' }); // ❌ Type error: 'grid' not in ['flex', 'block']
atoms({ fontSize: '16px' }); // ❌ Type error: 'fontSize' not defined
```

## Inspecting Properties

Check which properties are available:

```ts
const atoms = createProps(
  'atom',
  defineProperties({
    properties: { display: ['flex', 'block'] },
    shorthands: { d: ['display'] },
  }),
);

atoms.properties.has('display'); // true
atoms.properties.has('d'); // true (shorthand)
atoms.properties.has('fontSize'); // false
```

## Performance

- **Zero runtime overhead** - All CSS is pre-generated at module load time
- **Automatic deduplication** - Classes are only generated once
- **Small bundle size** - Only the props function and a lookup map are included
- **Fast runtime** - Just string concatenation, no CSS generation at runtime

Source: https://typestyles.dev/docs/atomic-css

---

# Benchmarks

Reproducible performance measurements for TypeStyles — CSS generation, file size, runtime injection, SSR collection, and cross-framework comparison


Measured numbers, reproducible methodology, and honest caveats. These benchmarks run in CI on every pull request — regressions beyond thresholds block the build.

## Reference app

Both TypeStyles and Vanilla Extract benchmarks use equivalent self-contained reference design systems:

- **50 components** — buttons, cards, inputs, modals, layout primitives, etc.
- **8 token namespaces** — color, space, radius, typography, shadow, duration, easing, z-index
- **3 themes** — dark, high-contrast, warm
- **2 keyframe animations**, **4 global styles**

This covers dimensioned variants, flat variants, compound variants, nested selectors, media queries, and pseudo-classes — a realistic production design system. The Vanilla Extract version uses `recipe()`, `style()`, `createThemeContract()`, and `createGlobalTheme()` — their closest equivalents to TypeStyles' APIs.

## TypeStyles results

### CSS generation time

Time to register all styles, tokens, themes, keyframes, and globals.

| Metric                                               | Median       | p95      |
| ---------------------------------------------------- | ------------ | -------- |
| Style registration (50 components + tokens + themes) | **~1.0 ms**  | ~1.5 ms  |
| Selector calls (~90 component function invocations)  | **~0.10 ms** | ~0.13 ms |

Style registration happens once at module load. Selector calls (e.g. `button({ intent: 'primary', size: 'lg' })`) happen on every render — they're string concatenation, not CSS generation.

### Extracted CSS file size

The same 50-component reference app extracted in each naming mode:

| Mode         | Raw     | Gzip   | Rules |
| ------------ | ------- | ------ | ----- |
| **Semantic** | 31.4 KB | 4.7 KB | 232   |
| **Hashed**   | 30.7 KB | 5.2 KB | 232   |
| **Compact**  | 29.0 KB | 4.9 KB | 232   |
| **Atomic**   | 19.0 KB | 4.7 KB | 296   |

Atomic mode produces the smallest raw CSS because identical declarations are deduplicated across components. Gzip sizes converge because compression already exploits repetition.

### Runtime injection

Full cycle: create all styles → serialize CSS → flush to sheet buffer.

| Metric                            | Median      | p95     |
| --------------------------------- | ----------- | ------- |
| Full cycle (registration + flush) | **~1.1 ms** | ~1.3 ms |

### SSR collection

Per-request `collectStyles()` overhead, including `AsyncLocalStorage` isolation.

| Metric                        | Median      | p95     |
| ----------------------------- | ----------- | ------- |
| `collectStyles()` per request | **~1.1 ms** | ~1.4 ms |
| Collected CSS size            | 31.4 KB     | —       |

## Cross-framework comparison: Vanilla Extract

The same 50-component design system implemented in Vanilla Extract's `recipe()` / `style()` / `createThemeContract()` APIs, measured under identical conditions (same machine, same Node version, same benchmark harness).

### Style registration

Time to define all styles, tokens, and themes. For Vanilla Extract this is the build-time `.css.ts` execution cost; for TypeStyles this is module-load time.

| Framework           | Median  | p95     |
| ------------------- | ------- | ------- |
| **TypeStyles**      | ~1.0 ms | ~1.5 ms |
| **Vanilla Extract** | ~0.7 ms | ~1.2 ms |

VE is slightly faster at registration because it collects style objects without serializing CSS inline — serialization happens in their bundler plugin.

### Selector calls

Time to invoke recipe/component functions and get class name strings back. Both frameworks do string concatenation at this stage.

| Framework           | Median   | p95      |
| ------------------- | -------- | -------- |
| **TypeStyles**      | ~0.10 ms | ~0.13 ms |
| **Vanilla Extract** | ~0.03 ms | ~0.07 ms |

VE's recipes are simpler string joins. TypeStyles does more work per call (variant resolution, compound variant matching), which trades a few microseconds for richer variant semantics.

### Extracted CSS file size

| Framework                 | Raw     | Gzip   | Rules |
| ------------------------- | ------- | ------ | ----- |
| **TypeStyles (semantic)** | 31.4 KB | 4.7 KB | 232   |
| **TypeStyles (atomic)**   | 19.0 KB | 4.7 KB | 296   |
| **Vanilla Extract**       | 30.5 KB | 4.6 KB | 196   |

CSS output sizes are nearly identical. TypeStyles' atomic mode produces 38% less raw CSS through cross-component declaration dedup, though gzip narrows the gap.

### What's not compared

- **Runtime injection** — VE doesn't do runtime injection (CSS is always a build artifact). TypeStyles' runtime path is an additional capability, not a comparable dimension.
- **SSR collection** — VE has no runtime CSS collection. Their CSS exists as static files at build time.
- **Build pipeline overhead** — VE's bundler plugin (Vite, webpack, esbuild) adds build-time cost beyond `.css.ts` execution. We only measure the style definition cost, not the full build pipeline.

## Methodology

Each timing benchmark:

1. Runs **5 warmup iterations** (discarded)
2. Runs **30–100 measured iterations**
3. Forces garbage collection between iterations (`--expose-gc`)
4. Reports **median, p95, min, max**

File size measurements are deterministic — they run once per mode and measure exact byte counts (raw and gzip).

The Vanilla Extract benchmark uses their `@vanilla-extract/css/adapter` and `@vanilla-extract/css/fileScope` APIs to run style definitions in Node without a bundler — the same mechanism VE's own test suite uses. CSS output is serialized from VE's structured format to measure comparable file sizes.

### Environment

Numbers above were measured on Apple Silicon (M-series). CI runs on `ubuntu-latest` (GitHub Actions, Node 22) and may differ. File sizes are platform-independent.

## Reproduce locally

From the monorepo root:

```bash
# Build the core package first
pnpm --filter typestyles build

# Run benchmarks (prints results)
pnpm --filter @typestyles/benchmarks bench

# Run with regression check against baseline
pnpm --filter @typestyles/benchmarks bench:ci

# Update baseline after intentional changes
pnpm --filter @typestyles/benchmarks bench:update
```

Results are written to `benchmarks/baseline.json`. The CI job compares each run against this baseline:

- **File size metrics**: fail if raw or gzip size grows > 5%
- **Timing metrics**: printed for visibility but not gated — timing varies too much across hardware (Apple Silicon vs CI VMs can differ 3x+) to use a checked-in baseline reliably

VE results are tracked for comparison but never gate CI (we don't control VE's performance).

## Caveats

- **Runtime injection is measured in Node**, not a real browser. The "full cycle" timing covers CSS serialization and sheet buffering, not actual CSSOM `insertRule` latency.
- **Single-machine numbers.** These are not a cross-platform benchmark suite. Your production performance depends on your users' devices.
- **VE comparison is honest but partial.** We measure what's directly comparable (style definition cost, CSS output size, selector call speed). We don't measure VE's full build pipeline, and we note where TypeStyles has capabilities VE doesn't (runtime injection, SSR collection) rather than treating those as advantages.
- **CI VMs are noisy.** File sizes are the most reliable regression signal.

## Related

- [Performance guide](/docs/performance) — best practices for keeping TypeStyles fast
- [Class naming](/docs/class-naming) — how semantic, hashed, compact, and atomic modes work
- [Zero-runtime extraction](/docs/zero-runtime) — eliminating runtime CSS injection entirely
- [Framework comparison](/docs/framework-comparison) — feature-level comparison across ecosystems

Source: https://typestyles.dev/docs/benchmarks

---

# Best Practices

Tips for organizing and maintaining typestyles in your project


These guidelines will help you write maintainable, scalable code with typestyles.

## Naming conventions

### Namespaces

Use kebab-case for namespaces. The namespace should describe the component or pattern:

```ts
// Good - descriptive and consistent
const button = styles.component('button', { ... });
const card = styles.component('card', { ... });
const navigationMenu = styles.component('navigation-menu', { ... });

// Avoid - generic or single-letter names
const b = styles.component('b', { ... });
const x = styles.component('x', { ... });
const component = styles.component('component', { ... });
```

### Variants

Use camelCase for variant dimension names. Be descriptive about the style purpose, not just the visual appearance:

```ts
const button = styles.component('button', {
  base: { ... },
  variants: {
    intent: {
      primary: { ... },     // The main action
      secondary: { ... },   // Alternative action
      danger: { ... },      // Destructive action
      ghost: { ... },       // Subtle action
    },
    size: {
      small: { ... },
      medium: { ... },
      large: { ... },
    },
  },
  defaultVariants: {
    intent: 'primary',
    size: 'medium',
  },
});

// Avoid - describes appearance only
// blue: { ... }, big: { ... }, rounded: { ... }
```

For flat configs, variant names should still be descriptive:

```ts
const card = styles.component('card', {
  base: { ... },
  elevated: { ... },
  interactive: { ... },
  disabled: { ... },
});
```

### Tokens

Group tokens by category. Use consistent naming within groups:

```ts
// Good - clear categories and consistent naming
export const color = tokens.create('color', {
  // Semantic colors
  primary: '#0066ff',
  secondary: '#6b7280',
  success: '#10b981',
  warning: '#f59e0b',
  danger: '#ef4444',

  // Neutral scale
  gray50: '#f9fafb',
  gray100: '#f3f4f6',
  gray200: '#e5e7eb',
  // ...etc

  // Text colors
  text: '#111827',
  textMuted: '#6b7280',
  textInverse: '#ffffff',

  // Surface colors
  surface: '#ffffff',
  surfaceRaised: '#f9fafb',
  surfaceSunken: '#f3f4f6',
});

export const space = tokens.create('space', {
  // Scale-based
  0: '0',
  1: '4px',
  2: '8px',
  3: '12px',
  4: '16px',
  5: '20px',
  6: '24px',
  8: '32px',
  10: '40px',
  12: '48px',
  16: '64px',
  20: '80px',
  24: '96px',

  // Semantic aliases (optional)
  xs: '4px',
  sm: '8px',
  md: '16px',
  lg: '24px',
  xl: '32px',
});
```

## File organization

### Monorepo/Package structure

```
src/
  tokens/
    index.ts          # Re-exports all tokens
    colors.ts         # Color definitions
    spacing.ts        # Spacing scale
    typography.ts     # Font sizes, line heights
    radii.ts          # Border radius
    shadows.ts        # Box shadows
  components/
    Button/
      index.ts      # Component export
      Button.tsx    # Component implementation
      Button.styles.ts  # Style definitions
    Card/
      index.ts
      Card.tsx
      Card.styles.ts
    ...
  layouts/
    Layout.styles.ts
    ...
  utils/
    styles.ts         # Shared utility styles
```

### Token files

Keep tokens in dedicated files, grouped by category:

```ts
// tokens/colors.ts
import { tokens } from 'typestyles';

export const color = tokens.create('color', {
  // Brand colors
  brand50: '#eff6ff',
  brand100: '#dbeafe',
  brand500: '#3b82f6',
  brand600: '#2563eb',
  brand700: '#1d4ed8',

  // Neutral scale
  gray50: '#f9fafb',
  gray100: '#f3f4f6',
  // ... etc
});

// tokens/index.ts
export { color } from './colors';
export { space } from './spacing';
export { font } from './typography';
```

### Component style files

Keep styles co-located with components or in a separate `.styles.ts` file:

**Option 1: Same file (for simple components)**

```tsx
// Button.tsx
import { styles } from 'typestyles';
import { color, space } from '../tokens';

const button = styles.component('button', {
  base: { ... },
  variants: {
    intent: { primary: { ... }, secondary: { ... } },
  },
  defaultVariants: { intent: 'primary' },
});

export function Button({ variant = 'primary', children }) {
  return <button className={button({ intent: variant })}>{children}</button>;
}
```

**Option 2: Separate file (for complex components)**

```ts
// Button.styles.ts
import { styles } from 'typestyles';
import { color, space } from '../tokens';

export const button = styles.component('button', {
  base: { ... },
  variants: {
    intent: { primary: { ... }, secondary: { ... } },
    size: { small: { ... }, medium: { ... }, large: { ... } },
  },
  defaultVariants: { intent: 'primary', size: 'medium' },
});

// Button.tsx
import { button } from './Button.styles';

export function Button({ variant = 'primary', size = 'medium', children }) {
  return (
    <button className={button({ intent: variant, size })}>
      {children}
    </button>
  );
}
```

## Token architecture

### Semantic vs. literal tokens

Use literal tokens for the design system foundation, semantic tokens for application use:

```ts
// tokens/primitives.ts
// Raw values from your design system
export const primitives = {
  colors: {
    blue500: '#0066ff',
    blue600: '#0052cc',
    gray500: '#6b7280',
    red500: '#ef4444',
  },
  space: {
    1: '4px',
    2: '8px',
    3: '16px',
    4: '24px',
  },
};

// tokens/semantic.ts
// Semantic meanings mapped to primitives
export const color = tokens.create('color', {
  primary: primitives.colors.blue500,
  primaryHover: primitives.colors.blue600,
  secondary: primitives.colors.gray500,
  danger: primitives.colors.red500,
  // ... etc
});

export const space = tokens.create('space', primitives.space);
```

### Component-specific tokens

For complex components, you can scope tokens to just that component:

```ts
// components/Calendar/Calendar.tokens.ts
import { tokens } from 'typestyles';

export const calendar = tokens.create('calendar', {
  daySize: '40px',
  headerHeight: '48px',
  gridGap: '4px',
});

// Usage in Calendar.styles.ts
import { calendar } from './Calendar.tokens';

const calendarStyles = styles.component('calendar', {
  base: {
    width: calendar.daySize,
    height: calendar.daySize,
  },
});
```

### Token composition

Reference other tokens when defining new ones:

```ts
const space = tokens.create('space', {
  1: '4px',
  2: '8px',
  3: '16px',
  4: '24px',
  5: '32px',
});

const size = tokens.create('size', {
  // Reference space tokens for consistency
  sm: space[1], // 4px
  md: space[2], // 8px
  lg: space[3], // 16px
  icon: space[4], // 24px
});
```

## Component patterns

### Compound components

For related components (like Form + Input + Label), use consistent namespacing:

```ts
const form = styles.component('form', {
  base: { ... },
});

const input = styles.component('input', {
  base: { ... },
  variants: {
    state: {
      error: { borderColor: '#ef4444' },
      success: { borderColor: '#10b981' },
    },
  },
});

const label = styles.component('label', {
  base: { ... },
  variants: {
    required: {
      true: { '&::after': { content: '"*"', color: '#ef4444' } },
    },
  },
});

// Usage
<form className={form()}>
  <div>
    <label className={label({ required: true })}>Name</label>
    <input className={input({ state: error ? 'error' : undefined })} />
  </div>
</form>
```

### Variant composition

Use dimensioned variants for structured component APIs:

```ts
const button = styles.component('button', {
  base: {
    display: 'inline-flex',
    alignItems: 'center',
    justifyContent: 'center',
    cursor: 'pointer',
    border: 'none',
    fontWeight: 500,
    transition: 'all 150ms ease',
  },
  variants: {
    intent: {
      primary: { backgroundColor: color.primary, color: '#fff' },
      secondary: { backgroundColor: color.secondary, color: '#fff' },
      ghost: { backgroundColor: 'transparent' },
    },
    size: {
      small: { padding: '4px 8px', fontSize: '12px' },
      medium: { padding: '8px 16px', fontSize: '14px' },
      large: { padding: '12px 24px', fontSize: '16px' },
    },
  },
  defaultVariants: {
    intent: 'primary',
    size: 'medium',
  },
});

// Usage
button(); // Primary medium button
button({ intent: 'ghost', size: 'small' }); // Small ghost button
```

### Layout components

Use layout components with flexible spacing:

```ts
const stack = styles.component('stack', {
  base: {
    display: 'flex',
    flexDirection: 'column',
  },
  variants: {
    gap: {
      1: { gap: space[1] },
      2: { gap: space[2] },
      3: { gap: space[3] },
      4: { gap: space[4] },
    },
  },
  defaultVariants: { gap: 2 },
});

const row = styles.component('row', {
  base: {
    display: 'flex',
    flexDirection: 'row',
    alignItems: 'center',
  },
  variants: {
    gap: {
      1: { gap: space[1] },
      2: { gap: space[2] },
    },
  },
});
```

## State management

### Boolean variants

For simple on/off states, use boolean variants or flat configs:

```ts
const card = styles.component('card', {
  base: { ... },
  elevated: {
    boxShadow: '0 4px 6px rgba(0,0,0,0.1)',
  },
  interactive: {
    cursor: 'pointer',
    '&:hover': {
      boxShadow: '0 8px 12px rgba(0,0,0,0.15)',
    },
  },
});

// Destructure and use cx() for conditional application:
import { cx } from 'typestyles';

const { base, elevated, interactive } = card;
cx(base, isElevated && elevated, isInteractive && interactive);
```

### Complex state

For more complex state combinations, use dimensioned variants:

```ts
const button = styles.component('button', {
  base: { ... },
  variants: {
    intent: { primary: { ... }, secondary: { ... }, ghost: { ... } },
    size: { small: { ... }, medium: { ... }, large: { ... } },
    disabled: { true: { opacity: 0.5, cursor: 'not-allowed' } },
    loading: { true: { cursor: 'wait' } },
  },
  defaultVariants: { intent: 'primary', size: 'medium' },
});

function getButtonClasses({ variant, size, isDisabled, isLoading }: ButtonProps) {
  return button({
    intent: variant,
    size,
    disabled: isDisabled || undefined,
    loading: isLoading || undefined,
  });
}
```

## Theming patterns

### Dark mode with createTheme

```ts
// tokens/index.ts
export const color = tokens.create('color', {
  text: '#111827',
  textMuted: '#6b7280',
  surface: '#ffffff',
  surfaceRaised: '#f9fafb',
});

export const darkTheme = tokens.createTheme('dark', {
  base: {
    color: {
      text: '#e0e0e0',
      textMuted: '#9ca3af',
      surface: '#1a1a2e',
      surfaceRaised: '#25253e',
    },
  },
});

// Apply theme to document body or specific container
document.body.classList.add(darkTheme.className);
```

### Multiple themes

```ts
const brandLight = tokens.createTheme('brand-light', {
  base: {
    /* … */
  },
});
const brandDark = tokens.createTheme('brand-dark', {
  base: {
    /* … */
  },
});
const highContrast = tokens.createTheme('high-contrast', {
  base: {
    /* … */
  },
});
```

## Code style

### Consistent formatting

```ts
// Good - consistent structure
const card = styles.component('card', {
  base: {
    padding: space[4],
    borderRadius: '8px',
    backgroundColor: color.surface,
  },
  elevated: {
    boxShadow: shadow.md,
  },
  interactive: {
    cursor: 'pointer',
    transition: 'box-shadow 200ms ease',
    '&:hover': {
      boxShadow: shadow.lg,
    },
  },
});

// Avoid - inconsistent formatting
const card = styles.component('card', {
  base: { padding: space[4], borderRadius: '8px', backgroundColor: color.surface },
  elevated: { boxShadow: shadow.md },
});
```

### Import organization

```ts
// 1. External imports
import React from 'react';
import { styles, tokens, cx } from 'typestyles';

// 2. Internal absolute imports
import { color, space } from '@/tokens';
import { Button } from '@/components';

// 3. Internal relative imports
import { card } from './Card.styles';
import { useCardState } from './useCardState';
```

## Performance tips

1. **Define styles at module level** - Never create styles inside components
2. **Reuse token references** - Define once, import many times
3. **Minimize variants** - Don't create a variant for every possible state
4. **Use [`createVar()` for dynamic values**](/docs/dynamic-styles) — Keep styles static; set per-instance values via CSS custom properties
5. **Lazy load component styles** - Use dynamic imports for code splitting

## Scope isolation

### Why scopeId matters

In semantic mode (the default), `styles.component('button', …)` produces class names like `button-base`. If two packages — or two files in the same app — both register a `'button'` namespace without a `scopeId`, their CSS rules silently overwrite each other. TypeStyles warns about this in development, but the fix is simple: always set a `scopeId`.

### For applications

Use `createTypeStyles` with a `scopeId` at the root of your styles:

```ts
// src/styles.ts
import { createTypeStyles } from 'typestyles';

export const { styles, tokens } = createTypeStyles({
  scopeId: 'my-app',
});
```

Class names become `my-app-button-base` — unique across your dependency tree.

### For published packages

Published packages **must** use a `scopeId` to avoid colliding with consumer code or other packages. Use the package name and `hashed` mode:

```ts
import { createTypeStyles } from 'typestyles';

export const { styles, tokens } = createTypeStyles({
  scopeId: '@acme/ui',
  mode: 'hashed',
});
```

See the full [Publishing Packages](/docs/publishing-packages) guide for ESLint enforcement, token scoping, and a complete library setup example.

### Per-file isolation (CSS Modules style)

For maximum isolation without choosing a global scope, use `fileScopeId`:

```ts
import { createStyles, fileScopeId } from 'typestyles';

const styles = createStyles({ scopeId: fileScopeId(import.meta) });
```

Each file gets a unique hash-based scope, similar to CSS Modules.

## Common mistakes to avoid

### Creating styles inside components

```tsx
// Bad - creates new styles on every render
function Button({ children }) {
  const button = styles.component('button', { base: { ... } }); // Don't do this
  return <button className={button()}>{children}</button>;
}

// Good - define at module level
const button = styles.component('button', { base: { ... } });

function Button({ children }) {
  return <button className={button()}>{children}</button>;
}
```

### Dynamic style values

```tsx
import { styles, createVar, assignVars } from 'typestyles';

// Bad - creates styles for every possible value
const button = styles.component('button', {
  base: { width: props.width }, // Don't do this
});

// Good - wire dynamic values through CSS custom properties
const widthVar = createVar('buttonWidth');

const button = styles.component('button', {
  base: { display: 'inline-block', width: widthVar },
});

function Button({ width, children }) {
  return (
    <button className={button()} style={assignVars({ [widthVar]: width })}>
      {children}
    </button>
  );
}
```

### Duplicate namespaces

```ts
// File A
const button = styles.component('button', { ... });

// File B
const button = styles.component('button', { ... }); // Collision!

// Fix 1 - use descriptive names
const iconButton = styles.component('icon-button', { ... });
const textButton = styles.component('text-button', { ... });

// Fix 2 (recommended) - use scopeId to isolate
const { styles } = createTypeStyles({ scopeId: 'my-app' });
const button = styles.component('button', { ... }); // "my-app-button-base"
```

## Summary

- Always set a `scopeId` via `createTypeStyles` or `createStyles` — especially in published packages
- Use descriptive, consistent naming for namespaces and variants
- Organize tokens by category in dedicated files
- Define styles at module level, never in components
- Use semantic tokens for application code
- Keep variants focused on style purpose, not appearance
- Use [`createVar()` + `assignVars()`](/docs/dynamic-styles) for per-instance dynamic values
- Use `cx()` from typestyles for conditional class joining
- Use a bundler plugin for [zero-runtime production builds](/docs/zero-runtime)

Source: https://typestyles.dev/docs/best-practices

---

# Cascade layers (@layer)

Opt-in CSS cascade layers for predictable specificity against global CSS


By default, TypeStyles emits **flat** rules (no `@layer`), matching legacy behavior and keeping the API surface small.

When you opt in with a **`layers`** tuple on `createStyles`, `createTokens`, or the unified **`createTypeStyles`** factory, TypeStyles:

1. Registers a single **`@layer a, b, c;`** preamble (once per distinct stack) so order is deterministic.
2. Wraps each emitted rule block in **`@layer <name> { … }`** for the `layer` you pass on each style call.
3. When **`createTokens({ layers, tokenLayer })`** is used, `:root` custom properties and **theme** rules go into `tokenLayer` so utilities and components can override tokens predictably.

## `createTypeStyles` (recommended for design systems)

One config object gives you matching **`scopeId`**, **`layers`**, and **`tokenLayer`** for both class CSS and token/theme CSS:

```ts
import { createTypeStyles } from 'typestyles';

const { styles, tokens } = createTypeStyles({
  scopeId: 'ds',
  mode: 'semantic',
  layers: ['reset', 'tokens', 'components', 'utilities'] as const,
  tokenLayer: 'tokens',
});

const reset = styles.class('reset', { margin: 0, padding: 0 }, { layer: 'reset' });

const button = styles.component(
  'button',
  {
    base: { padding: '8px 16px' },
    variants: {
      intent: { primary: { backgroundColor: '#0066ff' } },
    },
    defaultVariants: { intent: 'primary' },
  },
  { layer: 'components' },
);

tokens.create('color', { primary: '#0066ff' });
```

Conceptual output:

```css
@layer reset, tokens, components, utilities;
@layer tokens {
  :root {
    /* --ds-color-* */
  }
}
@layer reset {
  .reset {
    margin: 0;
    padding: 0;
  }
}
@layer components {
  .button-base {
    padding: 8px 16px;
  }
}
```

## `createStyles` only

Pass **`layers`** as a `const` tuple (or as `{ order, prependFrameworkLayers? }`). Every **`styles.class`**, **`styles.hashClass`**, and **`styles.component`** call must include **`{ layer: '…' }`**. Layer names must appear in the tuple (not in `prependFrameworkLayers`, which only affects ordering against external frameworks).

```ts
const styles = createStyles({
  layers: { order: ['components'], prependFrameworkLayers: ['bootstrap'] },
});

styles.class('card', { padding: '1rem' }, { layer: 'components' });
```

## `createTokens` with layers

When **`layers`** is set, **`tokenLayer`** is **required**. Token and theme CSS is wrapped in that layer.

```ts
const tokens = createTokens({
  scopeId: 'app',
  layers: ['tokens', 'components'] as const,
  tokenLayer: 'tokens',
});
```

## Default (no layers)

Omit **`layers`** everywhere: no `@layer` in output, and there is no `layer` option on style APIs.

## Notes

- **Multiple instances:** Each factory that passes **`layers`** owns its own stack; preamble keys include **`scopeId`** and full order so different design systems on one page stay distinct.
- **Build / SSR:** Preamble rules are inserted at the **front** of the virtual sheet so `getRegisteredCss()` and extraction see ordering before wrapped blocks.
- **jsdom:** Older parsers may log warnings for `@layer`; real browsers support cascade layers.

See also [Class naming](/docs/class-naming).

Source: https://typestyles.dev/docs/cascade-layers

---

# Class naming

Per-instance semantic, hashed, or atomic class names via createStyles; scoped tokens via createTokens


By default, typestyles emits **readable semantic** class names: `button-base`, `card-elevated`, `button-intent-primary`. You can switch to **hashed**, **compact** (hash-only whole-object), or **atomic** (one class per declaration) names for smaller strings, deduped CSS, or closer parity with CSS-in-JS tools that minify class names.

Naming applies to:

- [`styles.class`](/docs/styles)
- [`styles.component`](/docs/components) (single-part components and [multipart `slots`](/docs/components))

It does **not** change [`@typestyles/props`](/docs/atomic-css) utility naming; that package uses its own `createProps` namespace pattern.

## Quick start

**Class names** are configured per **`createStyles()`** instance (not with a global singleton). Create one instance per package, design system, or micro-frontend and import that everywhere in the package:

```ts
import { createStyles } from 'typestyles';

export const styles = createStyles({
  mode: 'hashed',
  prefix: 'ds',
  scopeId: '@acme/design-system',
});
```

Use `styles.component`, `styles.class`, and `styles.hashClass` from that object. For [utility shortcuts](/docs/styles#utility-shortcuts), pass **`utils`** into `createStyles` (or call `styles.withUtils(…)` on the default export). The default `import { styles } from 'typestyles'` is simply `createStyles()` with default options—fine for apps that own the whole page.

**Tokens and themes** use the same idea: **`createTokens({ scopeId })`** so custom properties and theme classes do not collide when multiple bundles share one document:

```ts
import { createTokens } from 'typestyles';

export const tokens = createTokens({ scopeId: '@acme/design-system' });
```

With `scopeId` set, `tokens.create('color', …)` emits variables like `--acme-design-system-color-primary` (sanitized), and `tokens.createTheme('dark', …)` registers a theme class whose segment includes the scope.

For **CSS cascade layers** (`@layer`) — optional, and off by default — see [Cascade layers](/docs/cascade-layers). Use **`createTypeStyles`** when both class rules and token/theme CSS should share one layer stack and one `scopeId`.

## API

### `createStyles(options?)`

Returns a style API with the same methods as the default `styles` export. Options are a partial **`ClassNamingConfig`** merged onto defaults:

| Option    | Type                                                        | Default      | Description                                                                                                                                                                                                                                                                |
| --------- | ----------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mode`    | `'semantic' \| 'hashed' \| 'compact' \| 'atomic'`           | `'semantic'` | How class strings are built (see below).                                                                                                                                                                                                                                   |
| `prefix`  | `string`                                                    | `'ts'`       | Leading segment for hashed/compact/atomic output and for `hashClass`.                                                                                                                                                                                                      |
| `scopeId` | `string`                                                    | `''`         | Optional id (package name, app name) so two packages can reuse the same logical namespace without sharing the same class string. In `semantic` mode the sanitized scope is prefixed onto class names; in `hashed`/`compact`/`atomic` mode it is mixed into the hash input. |
| `layers`  | `readonly string[]` or `{ order, prependFrameworkLayers? }` | _(omitted)_  | When set, enables `@layer` output and requires `{ layer }` on each `class` / `hashClass` / `component` call. See [Cascade layers](/docs/cascade-layers).                                                                                                                   |

The instance also exposes **`styles.classNaming`**: a read-only snapshot of the resolved config (useful for debugging).

### `mergeClassNaming(partial?)` and `defaultClassNamingConfig`

Use these when you need the resolved config object without creating a full API (for example tests or tooling).

### `scopedTokenNamespace(scopeId, logicalNamespace)`

Returns the CSS custom property namespace segment used for `tokens.create` when `scopeId` is set (sanitized). Advanced / library use.

## Modes

### `semantic` (default)

Human-readable, stable names derived from the namespace and variant segment:

- `styles.class('card', { … })` → `card`
- `styles.component('button', { … })` → `button-base`, `button-intent-primary`, etc.
- Components with `slots` → `{namespace}-{slot}`, `{namespace}-{slot}-{dimension}-{option}`, etc.

With **`scopeId`** set, the sanitized scope is prefixed onto every class name — the same way `tokens.create` scopes custom property names:

- `createStyles({ scopeId: 'my-ui' })` + `styles.component('button', { … })` → `my-ui-button-base`
- `createStyles({ scopeId: '@acme/ds' })` + `styles.class('card', { … })` → `acme-ds-card`

This keeps semantic names readable while making isolation real: two packages can both register `styles.component('button', …)` without their CSS rules overwriting each other. In development, typestyles also logs an error if two different definitions ever emit the same class string (cross-scope collisions, or hash collisions in `hashed`/`compact` mode).

### `hashed`

Deterministic names of the form **`{prefix}-{namespace-slug}-{hash}`**. The hash is computed from (when set) `scopeId`, the namespace, a variant segment (e.g. `base`, `intent-primary`, `root-compound-0`), and the serialized style object for that rule. Identical definitions produce identical class strings.

Use this when you want shorter, scoped names while still recognizing the namespace in DevTools.

### `compact`

**`{prefix}-{hash}`** only—no namespace slug in the string. Same hash inputs as `hashed`, so behavior is equally deterministic. Each component rule is still **one class per style chunk** (base, variant option, compound rule, etc.).

Use this when you want the shortest hash-only class strings without per-declaration splitting.

### `atomic`

**One class per CSS declaration.** Identical property values share a class across the codebase—CSS size plateaus as you add components instead of growing linearly with every rule chunk.

- `styles.class('card', { padding: '1rem', color: 'red' })` → two classes joined with a space
- `styles.component('button', { base: { color: 'red', padding: '8px' } })` → `button.base` is a space-separated list of atomic classes
- Nested selectors (`&:hover`, attribute selectors) and `@media` blocks decompose the same way; each inner declaration gets its own class

Hash inputs include (when set) `scopeId`, the declaration path (property + nested context), and the value. For Tailwind-style **utility prop APIs**, see [`@typestyles/props`](/docs/atomic-css).

#### Migrating from the old `atomic` name

Before P2.10, `atomic` meant hash-only **whole-object** classes (no namespace slug). That mode is now **`compact`**. If you were using `mode: 'atomic'` for short hash-only class strings, switch to **`mode: 'compact'`**. Use **`mode: 'atomic'`** when you want true per-declaration output and dedup.

## `styles.hashClass`

`hashClass` on a given instance uses that instance’s **`prefix`** and **`scopeId`**. If **`scopeId`** is empty, the hash input matches the historical behavior (properties only, plus label handling) for the same style shape.

## Monorepos and `scopeId`

Two packages might both use `styles.component('button', …)`. Give each package its own **`createStyles({ scopeId: '…' })`**: in **`semantic`** mode the scope is prefixed onto the class name (`pkg-a-button-base` vs `pkg-b-button-base`); in **`hashed`**, **`compact`**, or **`atomic`** mode the scope is mixed into the hash so identical style objects in different packages do not map to the same class string.

For tokens, use **`createTokens({ scopeId })`** per package so `--color-*` and `.theme-*` rules do not overwrite each other on `:root` or clash by name.

## SSR

Use the **same** `createStyles` / `createTokens` options (including `scopeId`) on the server and the client so class names, custom property names, and injected CSS match.

## Testing

Use a **dedicated** `createStyles({ … })` per test file or suite when you need hashed, compact, or atomic mode. There is no global naming state to reset—only call **`reset()`** (and related sheet helpers) to clear injected CSS between tests. Default **`import { styles } from 'typestyles'`** is still shared across tests, so prefer a local `createStyles()` when asserting on class strings under non-semantic modes.

```ts
import { createStyles, reset } from 'typestyles';

const styles = createStyles({ mode: 'hashed', prefix: 't', scopeId: 'test-a' });

beforeEach(() => {
  reset();
});
```

If you assert on class strings under **`hashed`**, **`compact`**, or **`atomic`**, prefer stable snapshots or assert on substrings (prefix, absence of semantic segments) rather than hard-coding full hashes unless you fix `scopeId` and styles.

See also [Testing](/docs/testing).

## Related

- [Styles](/docs/styles) — `styles.class`, `compose`, `withUtils`
- [Components](/docs/components) — `styles.component` and `slots`
- [Tokens](/docs/tokens) — `createTokens` and scoped custom properties
- [Atomic CSS Utilities](/docs/atomic-css) — `@typestyles/props` (separate naming scheme)
- [API Reference](/docs/api-reference) — export list

Source: https://typestyles.dev/docs/class-naming

---

# Color

Type-safe helpers for CSS color functions


The `color` API provides type-safe helpers for modern CSS color functions. These functions return plain CSS strings (no runtime color math), so they compose naturally with token references and other CSS values.

## Basic color functions

### rgb

Create `rgb()` colors with space-separated syntax:

```ts
import { color } from 'typestyles/color';

color.rgb(0, 102, 255); // "rgb(0 102 255)"
color.rgb(0, 102, 255, 0.5); // "rgb(0 102 255 / 0.5)"
```

### hsl

Create `hsl()` colors:

```ts
color.hsl(220, '100%', '50%'); // "hsl(220 100% 50%)"
color.hsl(220, '100%', '50%', 0.8); // "hsl(220 100% 50% / 0.8)"
```

### oklch

Create `oklch()` colors for perceptually uniform color spaces:

```ts
color.oklch(0.7, 0.15, 250); // "oklch(0.7 0.15 250)"
color.oklch(0.7, 0.15, 250, 0.5); // "oklch(0.7 0.15 250 / 0.5)"
```

### oklab

Create `oklab()` colors:

```ts
color.oklab(0.7, -0.1, -0.1); // "oklab(0.7 -0.1 -0.1)"
color.oklab(0.7, -0.1, -0.1, 0.5); // "oklab(0.7 -0.1 -0.1 / 0.5)"
```

### lab

Create `lab()` colors:

```ts
color.lab('50%', 40, -20); // "lab(50% 40 -20)"
```

### lch

Create `lch()` colors:

```ts
color.lch('50%', 80, 250); // "lch(50% 80 250)"
```

### hwb

Create `hwb()` colors:

```ts
color.hwb(220, '10%', '0%'); // "hwb(220 10% 0%)"
```

## Advanced color functions

### mix

Mix two colors using `color-mix()`:

```ts
// Mix red and blue equally (50/50)
color.mix('red', 'blue');
// "color-mix(in srgb, red, blue)"

// Mix 30% red with 70% blue
color.mix('red', 'blue', 30);
// "color-mix(in srgb, red 30%, blue)"

// Mix in a different color space
color.mix('red', 'blue', 50, 'oklch');
// "color-mix(in oklch, red 50%, blue)"
```

Works great with token references:

```ts
const theme = tokens.create('theme', {
  primary: '#0066ff',
});

// Create a lighter variant of your primary color
color.mix(theme.primary, 'white', 20);
// "color-mix(in srgb, var(--theme-primary) 20%, white)"
```

### alpha

Adjust the opacity of any color:

```ts
color.alpha('red', 0.5); // "color-mix(in srgb, red 50%, transparent)"
color.alpha(theme.primary, 0.2); // "color-mix(in srgb, var(--theme-primary) 20%, transparent)"
color.alpha('#0066ff', 0.8, 'oklch'); // "color-mix(in oklch, #0066ff 80%, transparent)"
```

This is a convenience wrapper around `color.mix()` that mixes any color with transparent.

### lightDark

Use the `light-dark()` CSS function for automatic light/dark mode switching:

```ts
color.lightDark('#111', '#eee');
// "light-dark(#111, #eee)"

// Works with tokens too
color.lightDark(theme.textLight, theme.textDark);
// "light-dark(var(--theme-textLight), var(--theme-textDark))"
```

Note: This requires the browser to support `light-dark()` and the element to have an appropriate `color-scheme` value.

## Using with tokens

All color functions accept token references since tokens are just CSS `var()` strings:

```ts
import { styles, tokens } from 'typestyles';
import { color as colorFn } from 'typestyles/color';

const themeColor = tokens.create('color', {
  primary: '#0066ff',
  secondary: '#6b7280',
});

const card = styles.component('card', {
  base: {
    backgroundColor: colorFn.mix(themeColor.primary, 'white', 10),
    borderColor: colorFn.alpha(themeColor.secondary, 0.3),
  },
});
```

## Color spaces for mixing

When using `mix()` or `alpha()`, you can specify different color spaces:

- `'srgb'` (default) - Standard RGB, most common
- `'srgb-linear'` - Linear RGB
- `'display-p3'` - Wide gamut RGB
- `'a98-rgb'` - Wide gamut RGB
- `'prophoto-rgb'` - Very wide gamut
- `'rec2020'` - Ultra HD color space
- `'lab'` - CIE Lab color space
- `'oklab'` - Better Lab, perceptually uniform
- `'xyz'`, `'xyz-d50'`, `'xyz-d65'` - CIE XYZ
- `'hsl'` - HSL color space
- `'hwb'` - HWB color space
- `'lch'` - CIE LCH
- `'oklch'` - Better LCH, perceptually uniform

```ts
// Mix in perceptually uniform space for smoother gradients
color.mix('red', 'blue', 50, 'oklch');
color.alpha(theme.primary, 0.5, 'oklab');
```

## Why no runtime color math?

Unlike some libraries that parse and manipulate colors in JavaScript, these helpers simply generate CSS strings. This means:

- Zero runtime overhead
- Colors are computed by the browser (which can use hardware acceleration)
- Works naturally with CSS custom properties and tokens
- Respects user's color scheme and accessibility preferences
- Smaller bundle size

If you need programmatic color manipulation (e.g., generating a palette programmatically), do that at build time and use the resulting values with these helpers.

Source: https://typestyles.dev/docs/color

---

# Component Library Setup

Building a reusable component library with typestyles


This guide shows you how to set up a reusable component library using typestyles, suitable for publishing to npm.

**Reference implementation:** [examples/react-design-system](https://github.com/type-styles/typestyles/blob/main/examples/react-design-system/README.md) (React Aria wrappers + shared tokens). Consumed by [examples/vite-app](https://github.com/type-styles/typestyles/blob/main/examples/vite-app/README.md) and [examples/next-app](https://github.com/type-styles/typestyles/blob/main/examples/next-app/README.md).

## Project structure

```
my-ui-library/
├── src/
│   ├── tokens/
│   │   ├── index.ts          # Token exports
│   │   ├── colors.ts         # Color definitions
│   │   ├── spacing.ts        # Spacing scale
│   │   └── typography.ts     # Font tokens
│   ├── components/
│   │   ├── Button/
│   │   │   ├── Button.tsx
│   │   │   ├── Button.styles.ts
│   │   │   └── index.ts
│   │   ├── Card/
│   │   │   ├── Card.tsx
│   │   │   ├── Card.styles.ts
│   │   │   └── index.ts
│   │   ├── Input/
│   │   │   └── ...
│   │   └── index.ts          # Component exports
│   ├── utils/
│   │   └── style-utils.ts    # Shared style utilities
│   ├── index.ts              # Main library export
│   └── styles.css            # Optional global CSS
├── package.json
├── tsconfig.json
├── vite.config.ts
└── README.md
```

## Package configuration

### package.json

```json
{
  "name": "@myorg/ui-library",
  "version": "1.0.0",
  "description": "A React component library built with typestyles",
  "type": "module",
  "main": "./dist/index.js",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./tokens": {
      "import": "./dist/tokens/index.js",
      "types": "./dist/tokens/index.d.ts"
    },
    "./styles.css": "./dist/styles.css"
  },
  "files": ["dist"],
  "scripts": {
    "build": "tsc && vite build",
    "dev": "vite",
    "test": "vitest",
    "typecheck": "tsc --noEmit"
  },
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0",
    "typestyles": "^1.0.0"
  },
  "devDependencies": {
    "@types/react": "^18.0.0",
    "typestyles": "^1.0.0",
    "typescript": "^5.0.0",
    "vite": "^5.0.0"
  }
}
```

Note: `typestyles` should be a peer dependency so consuming apps can control the version.

## Scope isolation

Published packages **must** use a `scopeId` to prevent class name collisions with consumer code or other libraries. Without one, `styles.component('button', …)` produces `button-base` in both your library and the consuming app — their CSS rules silently overwrite each other.

```ts
// src/styles.ts
import { createTypeStyles } from 'typestyles';

export const { styles, tokens } = createTypeStyles({
  scopeId: '@myorg/ui-library',
});
```

Now all class names are prefixed (`myorg-ui-library-button-base`) and all token custom properties are namespaced (`--myorg-ui-library-color-primary`). See [Best Practices — Scope isolation](/docs/best-practices#scope-isolation) for more options.

## Token system

### Colors

```ts
// src/tokens/colors.ts
import { tokens } from './styles'; // use the scoped instance

export const colors = tokens.create('color', {
  // Brand
  brand50: '#eff6ff',
  brand100: '#dbeafe',
  brand200: '#bfdbfe',
  brand300: '#93c5fd',
  brand400: '#60a5fa',
  brand500: '#3b82f6',
  brand600: '#2563eb',
  brand700: '#1d4ed8',
  brand800: '#1e40af',
  brand900: '#1e3a8a',

  // Gray scale
  gray50: '#f9fafb',
  gray100: '#f3f4f6',
  gray200: '#e5e7eb',
  gray300: '#d1d5db',
  gray400: '#9ca3af',
  gray500: '#6b7280',
  gray600: '#4b5563',
  gray700: '#374151',
  gray800: '#1f2937',
  gray900: '#111827',

  // Semantic
  success: '#10b981',
  warning: '#f59e0b',
  danger: '#ef4444',
  info: '#3b82f6',
});

// Semantic aliases
export const semanticColors = tokens.create('semantic-color', {
  primary: colors.brand500,
  primaryHover: colors.brand600,
  secondary: colors.gray500,
  secondaryHover: colors.gray600,
  text: colors.gray900,
  textMuted: colors.gray500,
  background: colors.gray50,
  surface: '#ffffff',
  surfaceRaised: colors.gray100,
  border: colors.gray200,
});
```

### Spacing

```ts
// src/tokens/spacing.ts
import { tokens } from 'typestyles';

export const spacing = tokens.create('space', {
  0: '0',
  1: '4px',
  2: '8px',
  3: '12px',
  4: '16px',
  5: '20px',
  6: '24px',
  8: '32px',
  10: '40px',
  12: '48px',
  16: '64px',
  20: '80px',
  24: '96px',

  // Semantic aliases
  xs: '4px',
  sm: '8px',
  md: '16px',
  lg: '24px',
  xl: '32px',
  '2xl': '48px',
  '3xl': '64px',
});
```

### Typography

```ts
// src/tokens/typography.ts
import { tokens } from 'typestyles';

export const fontSize = tokens.create('font-size', {
  xs: '0.75rem', // 12px
  sm: '0.875rem', // 14px
  base: '1rem', // 16px
  lg: '1.125rem', // 18px
  xl: '1.25rem', // 20px
  '2xl': '1.5rem', // 24px
  '3xl': '1.875rem', // 30px
  '4xl': '2.25rem', // 36px
});

export const fontWeight = tokens.create('font-weight', {
  normal: '400',
  medium: '500',
  semibold: '600',
  bold: '700',
});

export const lineHeight = tokens.create('line-height', {
  none: '1',
  tight: '1.25',
  snug: '1.375',
  normal: '1.5',
  relaxed: '1.625',
  loose: '2',
});
```

### Token exports

```ts
// src/tokens/index.ts
export { colors, semanticColors } from './colors';
export { spacing } from './spacing';
export { fontSize, fontWeight, lineHeight } from './typography';
```

## Component implementation

### Button component

```ts
// src/components/Button/Button.styles.ts
import { styles } from 'typestyles';
import { semanticColors, spacing, fontSize, fontWeight } from '../../tokens';

export const button = styles.component('button', {
  base: {
    display: 'inline-flex',
    alignItems: 'center',
    justifyContent: 'center',
    gap: spacing[2],
    borderRadius: '6px',
    lineHeight: '1.5',
    cursor: 'pointer',
    border: 'none',
    transition: 'all 150ms ease',

    '&:disabled': {
      opacity: 0.5,
      cursor: 'not-allowed',
    },

    '&:focus': {
      outline: 'none',
      boxShadow: `0 0 0 3px ${semanticColors.primary}33`,
    },
  },
  variants: {
    intent: {
      primary: {
        backgroundColor: semanticColors.primary,
        color: '#ffffff',
        '&:hover:not(:disabled)': {
          backgroundColor: semanticColors.primaryHover,
        },
      },
      secondary: {
        backgroundColor: semanticColors.secondary,
        color: '#ffffff',
        '&:hover:not(:disabled)': {
          backgroundColor: semanticColors.secondaryHover,
        },
      },
      outline: {
        backgroundColor: 'transparent',
        border: `1px solid ${semanticColors.border}`,
        color: semanticColors.text,
        '&:hover:not(:disabled)': {
          backgroundColor: semanticColors.surfaceRaised,
        },
      },
      ghost: {
        backgroundColor: 'transparent',
        color: semanticColors.text,
        '&:hover:not(:disabled)': {
          backgroundColor: semanticColors.surfaceRaised,
        },
      },
    },
    size: {
      sm: {
        padding: `${spacing[1]} ${spacing[3]}`,
        fontSize: fontSize.sm,
        fontWeight: fontWeight.medium,
      },
      md: {
        padding: `${spacing[2]} ${spacing[4]}`,
        fontSize: fontSize.base,
        fontWeight: fontWeight.medium,
      },
      lg: {
        padding: `${spacing[3]} ${spacing[6]}`,
        fontSize: fontSize.lg,
        fontWeight: fontWeight.medium,
      },
    },
    width: {
      auto: {},
      full: { width: '100%' },
    },
  },
  defaultVariants: {
    intent: 'primary',
    size: 'md',
    width: 'auto',
  },
});
```

```tsx
// src/components/Button/Button.tsx
import { cx } from 'typestyles';
import { forwardRef, type ButtonHTMLAttributes, type ReactNode } from 'react';
import { button } from './Button.styles';

export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  fullWidth?: boolean;
  children: ReactNode;
}

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ variant = 'primary', size = 'md', fullWidth = false, children, className, ...props }, ref) => {
    return (
      <button
        ref={ref}
        className={cx(
          button({
            intent: variant,
            size,
            width: fullWidth ? 'full' : 'auto',
          }),
          className,
        )}
        {...props}
      >
        {children}
      </button>
    );
  },
);

Button.displayName = 'Button';
```

```ts
// src/components/Button/index.ts
export { Button } from './Button';
export type { ButtonProps } from './Button';
```

## Theming support

### Dark theme

```ts
// src/tokens/themes.ts
import { tokens } from 'typestyles';

export const darkTheme = tokens.createTheme('dark', {
  base: {
    'semantic-color': {
      primary: '#60a5fa',
      primaryHover: '#3b82f6',
      text: '#f9fafb',
      textMuted: '#9ca3af',
      background: '#111827',
      surface: '#1f2937',
      surfaceRaised: '#374151',
      border: '#4b5563',
    },
  },
});

export const highContrastTheme = tokens.createTheme('high-contrast', {
  base: {
    'semantic-color': {
      text: '#000000',
      background: '#ffffff',
      primary: '#0000ff',
      border: '#000000',
    },
  },
});
```

### Theme provider

```tsx
// src/components/ThemeProvider/ThemeProvider.tsx
import { createContext, useContext, useState, type ReactNode } from 'react';
import { darkTheme } from '../../tokens/themes';

interface ThemeContextValue {
  theme: 'light' | 'dark';
  setTheme: (theme: 'light' | 'dark') => void;
}

const ThemeContext = createContext<ThemeContextValue>({
  theme: 'light',
  setTheme: () => {},
});

export function useTheme() {
  return useContext(ThemeContext);
}

interface ThemeProviderProps {
  children: ReactNode;
  defaultTheme?: 'light' | 'dark';
}

export function ThemeProvider({ children, defaultTheme = 'light' }: ThemeProviderProps) {
  const [theme, setTheme] = useState(defaultTheme);

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      <div className={theme === 'dark' ? darkTheme.className : ''}>{children}</div>
    </ThemeContext.Provider>
  );
}
```

## Build configuration

### Vite config

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import dts from 'vite-plugin-dts';
import path from 'path';

export default defineConfig({
  plugins: [
    react(),
    dts({
      insertTypesEntry: true,
    }),
  ],
  build: {
    lib: {
      entry: path.resolve(__dirname, 'src/index.ts'),
      name: 'MyUILibrary',
      formats: ['es', 'cjs'],
      fileName: (format) => `index.${format === 'es' ? 'js' : 'cjs'}`,
    },
    rollupOptions: {
      external: ['react', 'react-dom', 'typestyles'],
      output: {
        globals: {
          react: 'React',
          'react-dom': 'ReactDOM',
          typestyles: 'TypeStyles',
        },
      },
    },
  },
});
```

### TypeScript config

```json
// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "declaration": true,
    "declarationMap": true,
    "outDir": "dist"
  },
  "include": ["src"],
  "references": [{ "path": "./tsconfig.node.json" }]
}
```

## Main exports

```ts
// src/index.ts
// Components
export { Button } from './components/Button';
export type { ButtonProps } from './components/Button';

export { Card } from './components/Card';
export type { CardProps } from './components/Card';

export { Input } from './components/Input';
export type { InputProps } from './components/Input';

// Theme
export { ThemeProvider, useTheme } from './components/ThemeProvider';
export { darkTheme, highContrastTheme } from './tokens/themes';

// Tokens (for custom styling)
export { colors, semanticColors, spacing, fontSize, fontWeight, lineHeight } from './tokens';
```

## Usage examples

### Installation

```bash
npm install @myorg/ui-library typestyles react react-dom
```

### Basic usage

```tsx
import { Button, Card, Input } from '@myorg/ui-library';

function App() {
  return (
    <Card>
      <Card.Header>
        <h2>Login</h2>
      </Card.Header>
      <Card.Body>
        <Input label="Email" type="email" />
        <Input label="Password" type="password" />
      </Card.Body>
      <Card.Footer>
        <Button variant="primary" fullWidth>
          Sign In
        </Button>
      </Card.Footer>
    </Card>
  );
}
```

### With theming

```tsx
import { ThemeProvider, Button } from '@myorg/ui-library';

function App() {
  return (
    <ThemeProvider defaultTheme="dark">
      <Button variant="primary">I adapt to the theme!</Button>
    </ThemeProvider>
  );
}
```

### Using tokens for custom styling

```tsx
import { Button } from '@myorg/ui-library';
import { semanticColors, spacing } from '@myorg/ui-library/tokens';
import { styles } from 'typestyles';

const customCard = styles.component('custom-card', {
  base: {
    padding: spacing[6],
    border: `2px solid ${semanticColors.primary}`,
    borderRadius: '12px',
  },
});

function CustomComponent() {
  return (
    <div className={customCard()}>
      <Button variant="primary">Library Button</Button>
    </div>
  );
}
```

## Publishing

### Build the library

```bash
npm run build
```

### Publish to npm

```bash
npm login
npm publish --access public
```

## Versioning

Follow semantic versioning:

- **Patch (1.0.1)**: Bug fixes, token value changes
- **Minor (1.1.0)**: New components, new tokens (backward compatible)
- **Major (2.0.0)**: Breaking changes, removed components, renamed tokens

## Best practices

1. **Export prop types** - Let consumers extend your components
2. **Document breaking changes** - Keep a detailed changelog
3. **Test thoroughly** - Components should work in any React app
4. **Minimize dependencies** - Keep the library lightweight
5. **Provide examples** - Show how to customize and extend
6. **Support tree-shaking** - Use ES modules and avoid side effects
7. **Version tokens separately** - Consider a separate tokens package
8. **Test with multiple React versions** - Ensure compatibility

## Troubleshooting

### Styles not working in consumer app

Make sure `typestyles` is installed in the consumer app:

```bash
npm install typestyles
```

### TypeScript errors in consumer

Ensure the consumer has compatible TypeScript settings:

```json
{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "esModuleInterop": true
  }
}
```

### Duplicate typestyles instances

If you see duplicate style tags, ensure `typestyles` is a peer dependency, not a regular dependency.

Source: https://typestyles.dev/docs/component-library

---

# Components

Build typed variant APIs with styles.component


`styles.component()` is the first-class API for variant-driven component styling.

`styles.component()` is the unified API for all component styling. For flat configs (no dimensioned `variants`), see [Styles](/docs/styles).

Use the dimensioned config when you want a typed interface with:

- `base` styles
- `variants` dimensions
- `compoundVariants` for combinations
- `defaultVariants`

## Basic component

The live example defines a dimensioned `button` with `intent` and `size` variants, then shows how to call it. Class strings follow the global [class naming](/docs/class-naming) configuration (`semantic` by default).


> Interactive demo: https://typestyles.dev/docs/components

```ts
import { createStyles } from 'typestyles';

const styles = createStyles();

const button = styles.component('variant-button', {
  base: {
    display: 'inline-flex',
    alignItems: 'center',
    justifyContent: 'center',
    border: '1px solid transparent',
    borderRadius: '8px',
    fontWeight: 500,
  },
  variants: {
    intent: {
      primary: { backgroundColor: '#2563eb', color: 'white' },
      ghost: { backgroundColor: 'transparent', color: '#1f2937' },
    },
    size: {
      sm: { padding: '6px 10px', fontSize: '14px' },
      lg: { padding: '10px 16px', fontSize: '16px' },
    },
  },
  defaultVariants: { intent: 'primary', size: 'sm' },
});
```


## Compound variants

Use `compoundVariants` for styles that should apply only when multiple variant values match.

```ts
const badge = styles.component('badge', {
  variants: {
    tone: {
      success: { color: '#166534' },
      warning: { color: '#92400e' },
      danger: { color: '#991b1b' },
    },
    size: {
      sm: { fontSize: '12px' },
      lg: { fontSize: '14px' },
    },
  },
  compoundVariants: [
    {
      variants: { tone: ['success', 'warning'], size: 'lg' },
      style: { fontWeight: 700 },
    },
  ],
});

badge({ tone: 'success', size: 'lg' }); // includes "badge-compound-0"
badge({ tone: 'danger', size: 'lg' }); // does not include compound class
```

`compoundVariants` supports:

- single values: `{ size: 'lg' }`
- multi-value arrays: `{ tone: ['success', 'warning'] }`

## Boolean variants

Boolean variant dimensions are represented with `"true"` / `"false"` option keys.

```ts
const input = styles.component('input', {
  base: { border: '1px solid #d1d5db' },
  variants: {
    invalid: {
      true: { borderColor: '#ef4444' },
      false: { borderColor: '#d1d5db' },
    },
  },
  defaultVariants: {
    invalid: false,
  },
});

input(); // "input-base input-invalid-false"
input({ invalid: true }); // "input-base input-invalid-true"
```

## Multipart `slots`

Pass a `slots` array for components with multiple parts (for example root, trigger, and panel). `base`, `variants`, `compoundVariants`, and `defaultVariants` can each target specific slot keys.

TypeScript infers each slot name from the array literal, so the return value is typed with those keys (for example `tabs.root`, `tabs.trigger`) and unknown keys are errors. You do not need `as const` on `slots` when you pass an inline array inside `styles.component(...)`.

```ts
const tabs = styles.component('tabs', {
  slots: ['root', 'trigger', 'content'],
  base: {
    root: { display: 'grid' },
    trigger: { cursor: 'pointer' },
  },
  variants: {
    size: {
      sm: {
        trigger: { fontSize: '12px' },
        content: { padding: '8px' },
      },
      lg: {
        trigger: { fontSize: '16px' },
        content: { padding: '12px' },
      },
    },
  },
  defaultVariants: { size: 'sm' },
});

const c = tabs();
c.root; // class string for the root element
c.trigger;
c.content;
```

## Data and ARIA selectors

`styles.component` supports all CSS selectors:

```ts
const accordionTrigger = styles.component('accordion-trigger', {
  base: {
    '&[data-state="open"]': { fontWeight: 600 },
    '&[aria-expanded="true"]': { color: '#1d4ed8' },
  },
});
```

## Attribute-driven variants

Some design systems want variant state expressed as `data-*` attributes on the DOM (Radix/shadcn-style: one stable class, `data-variant`/`data-size` legible in the markup) rather than as discrete classes. Set `variantStrategy: 'attribute'` and each `variants` option compiles to a `&[data-{dimension}="{option}"]` selector scoped under the single `base` class, instead of its own class:

```ts
const button = styles.component('button', {
  base: { padding: '8px 16px', borderRadius: '6px' },
  variants: {
    variant: {
      primary: { backgroundColor: '#0066ff', color: '#fff' },
      secondary: { backgroundColor: '#6b7280', color: '#fff' },
    },
    size: {
      small: { fontSize: '14px' },
      large: { fontSize: '18px' },
    },
  },
  defaultVariants: { variant: 'primary', size: 'small' },
  variantStrategy: 'attribute',
});

const b = button({ variant: 'primary', size: 'small' });
b.className; // "button-base"
b.attrs; // { 'data-variant': 'primary', 'data-size': 'small' }
b.props; // { className: 'button-base', 'data-variant': 'primary', 'data-size': 'small' }

<button {...b.props}>...</button>;
// <button class="button-base" data-variant="primary" data-size="small">
```

`String(b)` / template-literal coercion and `cx(b, 'extra')` still return `"button-base"`, same as a plain class string.

Boolean dimensions (option keys exactly `{ true, false }`) are presence-based rather than value-matched: `true` compiles to `&[data-disabled]` and sets `data-disabled` with an empty value; `false` compiles to `&:not([data-disabled])` and omits the attribute entirely.

```ts
variants: {
  disabled: {
    true: { opacity: 0.5, cursor: 'not-allowed' },
    false: {},
  },
},
```

`compoundVariants` still work — each condition compiles to a single combined attribute selector (`.button-base[data-variant="primary"][data-size="large"]`) with no extra compound class and no runtime matching; an array of allowed values for one dimension (`{ tone: ['success', 'warning'], size: 'lg' }`) compiles to a `:is(...)` group ANDed with the rest of the condition.

Set `defaultVariantStrategy: 'attribute'` on `createStyles`/`createTypeStyles` to make this the default for every `styles.component` call from that instance, without repeating `variantStrategy` per component. A component can still opt back into class-based variants with `variantStrategy: 'class'`.

```ts
const { styles } = createTypeStyles({ defaultVariantStrategy: 'attribute', utils: {} });
```

**Trade-offs:**

- No per-option class hooks — `button['variant-primary']` doesn't exist in attribute mode, since there's no discrete class to expose. `button.base` still exposes the single base class.
- Only the plain dimensioned config (`base` / `variants` / `compoundVariants` / `defaultVariants`) supports `variantStrategy: 'attribute'` — not `slots` and not the flat (non-dimensioned) config shape.
- Attribute names are the dimension name verbatim (`data-{dimension}`), not kebab-cased. This matters only for multi-word camelCase dimension names (e.g. a dimension named `fontWeight` renders as `data-fontweight` in the DOM, since HTML lowercases attribute names on write) — it won't round-trip through `element.dataset.fontWeight`, which expects the kebab form `data-font-weight`. Single-word dimension names (`variant`, `size`, `tone`, `intent`) are unaffected.

## Migration quick-start

### From CVA

CVA config maps directly:

- `cva(base, { variants, compoundVariants, defaultVariants })`
- to `styles.component(name, { base, variants, compoundVariants, defaultVariants })`

The main difference is class generation/injection is handled by typestyles.

See the [Migration Guide](/docs/migration) for library-specific examples.

## Expose themeable properties as vars

If you expect a property to vary by theme region, expose it as a component-scoped CSS
custom property instead of hard-coding the value in `base` or variant styles. Token
and theme overrides then stay on [Tier 1](/docs/theming-patterns#tier-1--component-scoped-css-custom-properties-preferred)
and consumers rarely need plain class overrides or `@scope`.

```ts
const button = styles.component('button', (c) => {
  const v = c.vars({
    background: { value: '#fff', syntax: '<color>', inherits: false },
    foreground: { value: '#111', syntax: '<color>', inherits: false },
  });
  return {
    base: {
      backgroundColor: v.background.var,
      color: v.foreground.var,
    },
    variants: {
      intent: {
        primary: {
          [v.background.name]: '#0066ff',
          [v.foreground.name]: '#fff',
        },
      },
    },
  };
});
```

The [design-system example](/docs/design-system) uses this pattern throughout
(`examples/design-system/src/components/button.ts`).

## Responsive property values

Register breakpoints once on your styles instance, then use `{ base, md, lg }` shorthand on individual CSS properties instead of repeating full `@media` keys beside every property.

```ts
const { styles } = createTypeStyles({
  scopeId: 'app',
  breakpoints: {
    sm: '(min-width: 640px)',
    md: '(min-width: 768px)',
    lg: '(min-width: 1024px)',
    xl: '(min-width: 1280px)',
  },
});

const container = styles.component('container', {
  base: {
    width: '100%',
    paddingLeft: { base: '1rem', md: '1.5rem' },
    paddingRight: { base: '1rem', md: '1.5rem' },
    maxWidth: {
      base: '100%',
      sm: '640px',
      md: '768px',
      lg: '1024px',
      xl: '1280px',
    },
  },
});
```

This compiles to the same CSS you would write with explicit `'@media (min-width: …)'` object keys — one base declaration per property, plus nested `@media` blocks per breakpoint.

**Conventions:**

- `base` is the mobile-first default; `_` is an alias (Panda migration).
- Breakpoint values are media conditions **without** the `@media` wrapper — same strings as `@typestyles/props` `{ '@media': '(min-width: 640px)' }`.
- Values must be scalars (`string | number`); nested styles per breakpoint still use explicit `@media` keys.
- Responsive objects work in `styles.class`, `styles.component`, `styles.scope`, and `createTypeStyles({ breakpoints }).global.style` (or `createGlobal({ breakpoints }).style`). The root `global` export has no breakpoint registry — use a factory instance.

**Before (manual media keys):**

```ts
base: {
  padding: '1rem',
  '@media (min-width: 768px)': { padding: '1.5rem' },
  '@media (min-width: 1024px)': { padding: '2rem' },
}
```

**After:**

```ts
base: {
  padding: { base: '1rem', md: '1.5rem', lg: '2rem' },
}
```

For atomic utility props with responsive class names, use [`@typestyles/props`](/docs/atomic-css#responsive-conditions) — that system resolves to utility classes at runtime. Responsive property values are for declarative style objects that compile to plain CSS rules.

You can derive breakpoints from media tokens:

```ts
const { styles, tokens } = createTypeStyles({ scopeId: 'app' });
const media = tokens.create('media', {
  sm: '(min-width: 640px)',
  md: '(min-width: 768px)',
});

const stylesWithMedia = createStyles({
  scopeId: 'app',
  breakpoints: { fromTokens: media, lg: '(min-width: 1024px)' },
});
```

## Public class name stability

Semantic class names (`button-base`, `button-intent-primary`, …) are public API for
consumers theming your package. Do not rename namespaces or variant keys without a
major semver bump. Opt into snapshot + ESLint guardrails described in
[Publishing Packages — guard public class names](/docs/publishing-packages#guard-public-class-names).

## Related docs

- [Theming Patterns — component overrides](/docs/theming-patterns#component-overrides-two-tier-model)

- [Styles](/docs/styles)
- [Migration Guide](/docs/migration)
- [Custom Selectors & At-Rules](/docs/custom-at-rules)

Source: https://typestyles.dev/docs/components

---

# Style Composition

Combine multiple style functions and class strings with styles.compose


The `styles.compose()` function lets you merge multiple component style functions or class name strings into a single reusable function.

## Basic Usage

Combine multiple style groups into one:

```ts
import { styles } from 'typestyles';

const base = styles.component('base', {
  base: { padding: '8px', borderRadius: '4px' },
});

const primary = styles.component('primary', {
  base: { backgroundColor: '#0066ff', color: 'white' },
});

const button = styles.compose(base, primary);
```

## Composing with Static Classes

Mix component style functions with static class strings:

```ts
const card = styles.component('card', {
  base: { padding: '16px', borderRadius: '8px' },
});

const composed = styles.compose(card, 'shadow-lg', 'hover:scale-105');
```

## Conditional Composition

Use falsy values for conditional composition:

```ts
import { cx } from 'typestyles';

const base = styles.component('base', {
  base: { padding: '8px' },
});

const elevated = styles.component('elevated', {
  base: { boxShadow: '0 4px 8px rgba(0,0,0,0.1)' },
});

const isElevated = true;
const isDark = false;

const composed = styles.compose(base, isElevated && elevated, isDark && 'dark-mode');
```

You can also use `cx()` to conditionally join class strings from destructured components:

```ts
const card = styles.component('card', {
  base: { padding: '16px' },
  elevated: { boxShadow: '0 4px 8px rgba(0,0,0,0.1)' },
});
const { base, elevated } = card;

cx(base, isElevated && elevated);
```

## Overlapping Variants

When multiple style groups share the same base styles, all matching classes are applied:

```ts
const layout = styles.component('layout', {
  base: { display: 'flex' },
});

const spacing = styles.component('spacing', {
  base: { gap: '8px' },
});

const composed = styles.compose(layout, spacing);
```

This is useful for layering different concerns (layout, spacing, colors) while keeping styles semantic.

## Composition with Atomic Utilities

Combine component styles with atomic utilities from `@typestyles/props`:

```ts
import { styles } from 'typestyles';
import { createProps, defineProperties } from '@typestyles/props';

const atoms = createProps(
  'atom',
  defineProperties({
    properties: {
      display: ['flex', 'block', 'grid'],
      gap: { 0: '0', 1: '4px', 2: '8px', 3: '16px' },
    },
  }),
);

const card = styles.component('card', {
  base: { borderRadius: '8px', border: '1px solid #e5e5e5' },
});

// Compose component styles with atomic utilities
const flexCard = styles.compose(card, atoms({ display: 'flex', gap: 2 }));
```

## Use Cases

### Component Inheritance

Create base components and extend them:

```ts
const baseButton = styles.component('btn-base', {
  base: {
    padding: '8px 16px',
    borderRadius: '6px',
    fontSize: '14px',
    cursor: 'pointer',
    border: 'none',
  },
});

const primaryButton = styles.compose(
  baseButton,
  styles.component('btn-primary', {
    base: { backgroundColor: '#0066ff', color: 'white' },
  }),
);

const secondaryButton = styles.compose(
  baseButton,
  styles.component('btn-secondary', {
    base: { backgroundColor: '#e5e7eb', color: '#1f2937' },
  }),
);
```

### Utility-First Patterns

Build components with a mix of custom styles and utilities:

```ts
const customCard = styles.component('custom-card', {
  base: {
    background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
    color: 'white',
  },
});

const featureCard = styles.compose(customCard, atoms({ padding: 3, borderRadius: 2 }));
```

### Multi-Layer Composition

Compose multiple concerns separately:

```ts
const layout = styles.component('layout', { base: { maxWidth: '1200px' } });
const spacing = styles.component('spacing', { base: { padding: '0 16px' } });
const responsive = styles.component('responsive', {
  base: {
    '@media (max-width: 768px)': { padding: '0 8px' },
  },
});

const container = styles.compose(layout, spacing, responsive);
```

## Type Safety

`styles.compose()` infers a merged variant selection type from all composed component functions. TypeScript autocomplete and excess-property checks apply to the composed function's argument.

```ts
const size = styles.component('size', {
  variants: {
    size: { sm: { fontSize: '12px' }, lg: { fontSize: '18px' } },
  },
});

const intent = styles.component('intent', {
  variants: {
    intent: { primary: { color: 'blue' }, ghost: { color: 'gray' } },
  },
});

const button = styles.compose(size, intent);

// OK — both dimensions are known
button({ size: 'lg', intent: 'ghost' });

// TypeScript error — unknown variant key
button({ typo: true });
```

In development, `styles.compose()` also logs a `console.error` when a runtime selection object includes keys that none of the composed functions accept. Individual component functions still warn when a key is valid for one composed function but not another.

Source: https://typestyles.dev/docs/compose

---

# Custom Selectors & At-Rules

Using @container, @supports, and other CSS features


TypeStyles supports all CSS at-rules and advanced selectors through special key prefixes.

## Pseudo-classes and pseudo-elements

Use the `&` prefix for pseudo-classes:

```ts
const button = styles.component('button', {
  base: {
    padding: '8px 16px',
    backgroundColor: '#0066ff',
    color: 'white',

    // Hover state
    '&:hover': {
      backgroundColor: '#0052cc',
    },

    // Focus state
    '&:focus': {
      outline: '2px solid #0066ff',
      outlineOffset: '2px',
    },

    // Active/pressed state
    '&:active': {
      transform: 'scale(0.98)',
    },

    // Disabled state
    '&:disabled': {
      opacity: 0.5,
      cursor: 'not-allowed',
    },

    // Pseudo-elements
    '&::before': {
      content: '""',
      display: 'inline-block',
      width: '16px',
      height: '16px',
    },

    '&::after': {
      content: '" →"',
    },
  },
});
```

### Form-related pseudo-classes

```ts
const input = styles.component('input', {
  base: {
    border: '1px solid #e5e7eb',

    // Checked state (checkboxes, radios)
    '&:checked': {
      backgroundColor: '#0066ff',
    },

    // Placeholder text
    '&::placeholder': {
      color: '#9ca3af',
    },

    // Invalid state
    '&:invalid': {
      borderColor: '#ef4444',
    },

    // Valid state
    '&:valid': {
      borderColor: '#10b981',
    },

    // Required field
    '&:required': {
      borderColor: '#f59e0b',
    },
  },
});
```

### Structural pseudo-classes

```ts
const list = styles.component('list', {
  item: {
    padding: '8px 0',
    borderBottom: '1px solid #e5e7eb',

    // First child
    '&:first-child': {
      paddingTop: 0,
    },

    // Last child
    '&:last-child': {
      paddingBottom: 0,
      borderBottom: 'none',
    },

    // Every other item
    '&:nth-child(even)': {
      backgroundColor: '#f9fafb',
    },

    // First 3 items
    '&:nth-child(-n+3)': {
      fontWeight: 600,
    },

    // Only child
    '&:only-child': {
      border: 'none',
    },
  },
});
```

## Descendant and sibling selectors

### Child selectors

```ts
const card = styles.component('card', {
  base: {
    padding: '16px',
  },

  // Direct children
  '& > header': {
    marginBottom: '12px',
    fontWeight: 600,
  },

  // Any descendant
  '& .content': {
    lineHeight: 1.6,
  },

  // Descendant with specific element
  '& p': {
    marginBottom: '8px',
  },

  // Multiple selectors
  '& h1, & h2, & h3': {
    marginTop: 0,
  },
});
```

### Sibling selectors

```ts
const form = styles.component('form', {
  base: {
    display: 'flex',
    flexDirection: 'column',
    gap: '16px',
  },

  // Adjacent sibling
  '& > * + *': {
    // Adds margin between consecutive children (owl selector)
    marginTop: '16px',
  },

  // General sibling
  '& input ~ .error': {
    display: 'none',
  },

  '& input:invalid ~ .error': {
    display: 'block',
    color: '#ef4444',
  },
});
```

## Attribute selectors

```ts
const link = styles.component('link', {
  base: {
    color: '#0066ff',
    textDecoration: 'none',

    // External links
    '&[href^="http"]': {
      '&::after': {
        content: '" ↗"',
      },
    },

    // Download links
    '&[download]': {
      '&::after': {
        content: '" ↓"',
      },
    },

    // Links with specific target
    '&[target="_blank"]': {
      '&::after': {
        content: '" (opens in new tab)"',
      },
    },

    // Selector list support (both selectors scoped to .link-base)
    '[data-state="open"], [aria-expanded="true"]': {
      fontWeight: 600,
    },
  },
});
```

All CSS attribute selector operators are supported:

- exact match: `[attr="value"]`
- contains token: `[attr~="token"]`
- starts with / language: `[attr|="en"]`
- starts with: `[attr^="prefix"]`
- ends with: `[attr$="suffix"]`
- contains substring: `[attr*="part"]`

## `:has()`, `:is()`, and `:where()` helpers

Use **`styles.has`**, **`styles.is`**, and **`styles.where`** (or the named exports `has`, `is`, `where` from `typestyles`) to build `&`-nested keys the same way **`styles.container`** builds `@container` keys. Each helper returns a string suitable as an object key; multiple arguments become a comma-separated list inside the pseudo-class.

- **`:where()`** — wraps a selector list at **zero specificity**, so library defaults are easy for consumers to override.
- **`:is()`** — groups selectors; specificity is that of the most specific argument in the list.
- **`:has()`** — accepts a [relative selector list](https://drafts.csswg.org/selectors/#relative-real-selector-list) (parent / descendant-aware styling).

```ts
import { styles } from 'typestyles';

const nav = styles.class('nav', {
  display: 'flex',
  [styles.where('.nav')]: { gap: '8px' },
  [styles.has('.active')]: { borderBottom: '2px solid blue' },
  [styles.is(':hover', ':focus-visible')]: { outline: '2px solid blue' },
});
```

You can still author raw nested keys (e.g. `'&:has(.active)'`, `'&:is(:hover, :focus)'`). The **`IsPseudoArg`** type lists common pseudos for `:is()` groups. See [API Reference](/docs/api-reference) for exported types (`HasNestedKey`, `IsNestedKey`, `WhereNestedKey`).

**TypeScript:** literal arguments narrow to a concrete `` `&:…` `` template so computed keys mix cleanly with longhands; for dynamic selector strings, prefer plain `'&…'` keys or a small wrapper object you spread.

## Media queries

Use the `@` prefix for media queries:

```ts
const layout = styles.component('layout', {
  container: {
    display: 'grid',
    gridTemplateColumns: '1fr',
    gap: '16px',

    // Tablet
    '@media (min-width: 768px)': {
      gridTemplateColumns: 'repeat(2, 1fr)',
    },

    // Desktop
    '@media (min-width: 1024px)': {
      gridTemplateColumns: 'repeat(3, 1fr)',
    },

    // Wide screens
    '@media (min-width: 1440px)': {
      gridTemplateColumns: 'repeat(4, 1fr)',
      gap: '24px',
    },
  },
});
```

### Complex media queries

```ts
const hero = styles.component('hero', {
  base: {
    padding: '48px 16px',

    // High DPI screens
    '@media (min-resolution: 192dpi)': {
      backgroundImage: 'url(hero@2x.jpg)',
    },

    // Dark mode preference
    '@media (prefers-color-scheme: dark)': {
      backgroundColor: '#1a1a2e',
      color: '#e0e0e0',
    },

    // Reduced motion preference
    '@media (prefers-reduced-motion: reduce)': {
      animation: 'none',
      transition: 'none',
    },

    // Print styles
    '@media print': {
      background: 'none',
      color: 'black',
    },
  },
});
```

### Combining media queries with pseudo-classes

```ts
const button = styles.component('button', {
  base: {
    padding: '8px 16px',

    // Hover only on devices that support it
    '@media (hover: hover)': {
      '&:hover': {
        backgroundColor: '#0052cc',
      },
    },

    // Touch device adjustments
    '@media (pointer: coarse)': {
      padding: '12px 20px', // Larger touch target
    },
  },
});
```

## Container queries

Container queries respond to the size of a container, not the viewport. You can write plain `'@container …'` keys (they serialize like `@media`), or use **`styles.container()`** / **`container()`** for typed size features and named containers.

### Typed keys with `styles.container()`

```ts
import { styles } from 'typestyles';

const card = styles.class('card', {
  containerType: 'inline-size',
  padding: '16px',

  [styles.container({ minWidth: 400 })]: {
    padding: '24px',
    display: 'grid',
    gridTemplateColumns: '1fr 1fr',
  },
});
```

`container({ … })` accepts camelCase size features (`minWidth`, `maxInlineSize`, `orientation`, …). Numbers become `px` (except `aspectRatio`, where a number is emitted as-is—prefer a string like `'16 / 9'` when needed). Multiple features compile to one condition joined with `and`.

**TypeScript:** object and two-argument forms infer a **literal** `` `@container …` `` template, so **`[styles.container(…)]`** can sit next to longhands (`padding`, `display`, …) without `as CSSProperties`. When the `@container` text is only known as a generic **`string`** at compile time, spread **`styles.atRuleBlock(key, nested)`** (or the `atRuleBlock` export) instead. A **string literal** one-arg call also narrows, e.g. `[styles.container('(min-width: 1px)')]: { … }`.

### Named container queries

Set `containerName` on the element that establishes the container, then target it by name:

```ts
const sidebar = styles.class('sidebar', {
  containerType: 'inline-size',
  containerName: 'sidebar',
  width: '280px',
});

const sidebarItem = styles.class('sidebar-item', {
  // Either form:
  [styles.container('sidebar', { minWidth: 250 })]: {
    flexDirection: 'row',
  },
  // [styles.container({ name: 'sidebar', minWidth: 250 })]: { ... },
});
```

### Typed container names (`containerRef` / `createContainerRef`)

**`styles.containerRef(label)`** returns a **human-readable** `container-name` you can reuse in TypeScript instead of repeating string literals: **`{scopeId}-{label}`** when `scopeId` is set on the styles instance, otherwise **`{prefix}-{label}`** (same defaults as `createStyles`). Use that value for both `containerName` and the first argument to `styles.container(…)`.

```ts
const shell = styles.containerRef('product-shell');

const root = styles.class('shell-root', {
  containerType: 'inline-size',
  containerName: shell,
});

const body = styles.class('shell-body', {
  display: 'flex',
  flexDirection: 'column',
  ...styles.atRuleBlock(styles.container(shell, { minWidth: 480 }), {
    flexDirection: 'row',
  }),
});
```

Without a `styles` instance, call **`createContainerRef('product-shell', { scopeId: 'my-app' })`** — or with an empty scope, **`{ prefix: 'acme' }`** so names become `acme-product-shell`.

A full copy-paste example lives in the design-system package: [`namedContainerQuery.ts`](https://github.com/type-styles/typestyles/blob/main/examples/design-system/src/components/namedContainerQuery.ts).

### Raw string keys (style queries, `not`, scroll state)

For anything beyond the typed helper (e.g. `style()`, `not (…)`), pass a single string—the part of the rule after `@container`:

```ts
{
  [styles.container('style(--theme: dark)')]: { color: '#fff' },
}
```

### Manual keys (equivalent)

```ts
const card = styles.class('card', {
  containerType: 'inline-size',
  containerName: 'card',
  padding: '12px',

  '@container (min-width: 400px)': {
    padding: '24px',
    display: 'flex',
    gap: '16px',
  },

  '@container (min-width: 600px)': {
    padding: '32px',
  },
});
```

## Supports queries

Feature detection with `@supports`:

```ts
const backdrop = styles.component('backdrop', {
  base: {
    backgroundColor: 'rgba(0, 0, 0, 0.5)',

    // Use backdrop-filter if supported
    '@supports (backdrop-filter: blur(4px))': {
      backdropFilter: 'blur(4px)',
      backgroundColor: 'rgba(0, 0, 0, 0.3)',
    },
  },
});
```

### Complex supports queries

```ts
const grid = styles.component('grid', {
  base: {
    // Fallback layout
    display: 'flex',
    flexWrap: 'wrap',

    // Use grid if supported
    '@supports (display: grid)': {
      display: 'grid',
      gridTemplateColumns: 'repeat(auto-fit, minmax(250px, 1fr))',
    },

    // Use subgrid if supported
    '@supports (grid-template-columns: subgrid)': {
      gridTemplateColumns: 'subgrid',
    },
  },
});
```

## Layer (cascade layers)

CSS cascade layers for organizing styles:

```ts
const reset = styles.component('reset', {
  base: {
    // Apply to @layer reset
    '@layer reset': {
      margin: 0,
      padding: 0,
      boxSizing: 'border-box',
    },
  },
});

const components = styles.component('components', {
  button: {
    '@layer components': {
      padding: '8px 16px',
      backgroundColor: '#0066ff',
    },
  },
});
```

## Nesting depth

While typestyles supports deep nesting, it's best to keep it shallow:

```ts
// ✅ Good - 2-3 levels deep
const nav = styles.component('nav', {
  base: {
    display: 'flex',

    '& li': {
      position: 'relative',

      '&:hover > ul': {
        display: 'block', // 3 levels, acceptable
      },
    },
  },
});

// ❌ Avoid - too deep, hard to maintain
const deep = styles.component('deep', {
  base: {
    '& div': {
      '& span': {
        '& a': {
          '&:hover': {
            color: 'red', // 5 levels, problematic
          },
        },
      },
    },
  },
});
```

## Complex real-world example

```ts
const dataTable = styles.component('data-table', {
  container: {
    overflowX: 'auto',
    containerType: 'inline-size',
    containerName: 'data-table',
  },

  table: {
    width: '100%',
    borderCollapse: 'collapse',

    // Responsive adjustments
    '@container (max-width: 600px)': {
      fontSize: '14px',
    },

    // Sticky header
    '& thead': {
      position: 'sticky',
      top: 0,
      backgroundColor: '#f9fafb',

      '& th': {
        padding: '12px',
        textAlign: 'left',
        fontWeight: 600,

        '&:hover': {
          backgroundColor: '#e5e7eb',
          cursor: 'pointer',
        },
      },
    },

    // Body rows
    '& tbody tr': {
      borderBottom: '1px solid #e5e7eb',

      '&:last-child': {
        borderBottom: 'none',
      },

      '&:hover': {
        backgroundColor: '#f9fafb',
      },

      '& td': {
        padding: '12px',
      },

      // Selected row
      '&[data-selected="true"]': {
        backgroundColor: '#eff6ff',
      },
    },
  },

  // Print styles
  '@media print': {
    container: {
      overflow: 'visible',
    },

    table: {
      '& thead': {
        position: 'static',
      },
    },
  },
});
```

## Generated CSS

TypeStyles converts these nested objects to flat CSS:

**Input:**

```ts
const button = styles.component('button', {
  base: {
    padding: '8px',
    '&:hover': {
      backgroundColor: 'blue',
    },
    '@media (min-width: 768px)': {
      padding: '12px',
    },
  },
});
```

**Generated CSS:**

```css
.button-base {
  padding: 8px;
}

.button-base:hover {
  background-color: blue;
}

@media (min-width: 768px) {
  .button-base {
    padding: 12px;
  }
}
```

## Best practices

1. **Keep nesting shallow** - Max 3 levels deep
2. **Use container queries** - For component-level responsiveness
3. **Use media queries** - For viewport-level changes
4. **Combine selectors wisely** - Avoid overly complex selectors
5. **Test in real browsers** - Some selectors have varying support
6. **Consider progressive enhancement** - Use `@supports` for new features

Source: https://typestyles.dev/docs/custom-at-rules

---

# Design System with Tokens

Building a comprehensive design system using typestyles tokens


A design system is more than just components—it's a complete set of standards for design and code. This guide shows how to build a token-based design system with typestyles.

**Reference implementation:** [`@examples/design-system`](https://github.com/type-styles/typestyles/blob/main/examples/design-system/README.md) (tokens + recipes) and [`@examples/react-design-system`](https://github.com/type-styles/typestyles/blob/main/examples/react-design-system/README.md) (React components). The [docs site kitchen sink](/docs/design-system/kitchen-sink) renders the same recipes.

## Token architecture

### Three-layer token system

```
Layer 1: Primitives (raw values)
    ↓
Layer 2: Semantics (meaningful tokens)
    ↓
Layer 3: Components (component-specific)
```

### Layer 1: Primitives

Raw values from your brand guidelines:

```ts
// tokens/primitives/colors.ts
export const primitiveColors = {
  // Brand palette
  brand: {
    50: '#eff6ff',
    100: '#dbeafe',
    200: '#bfdbfe',
    300: '#93c5fd',
    400: '#60a5fa',
    500: '#3b82f6',
    600: '#2563eb',
    700: '#1d4ed8',
    800: '#1e40af',
    900: '#1e3a8a',
  },

  // Neutral palette
  gray: {
    50: '#f9fafb',
    100: '#f3f4f6',
    200: '#e5e7eb',
    300: '#d1d5db',
    400: '#9ca3af',
    500: '#6b7280',
    600: '#4b5563',
    700: '#374151',
    800: '#1f2937',
    900: '#111827',
    950: '#030712',
  },

  // Functional colors
  red: { 50: '#fef2f2', 500: '#ef4444', 900: '#7f1d1d' },
  orange: { 50: '#fff7ed', 500: '#f97316', 900: '#7c2d12' },
  yellow: { 50: '#fefce8', 500: '#eab308', 900: '#713f12' },
  green: { 50: '#f0fdf4', 500: '#22c55e', 900: '#14532d' },
  blue: { 50: '#eff6ff', 500: '#3b82f6', 900: '#1e3a8a' },
  purple: { 50: '#faf5ff', 500: '#a855f7', 900: '#581c87' },
} as const;
```

```ts
// tokens/primitives/spacing.ts
export const primitiveSpacing = {
  0: '0px',
  1: '4px',
  2: '8px',
  3: '12px',
  4: '16px',
  5: '20px',
  6: '24px',
  8: '32px',
  10: '40px',
  12: '48px',
  16: '64px',
  20: '80px',
  24: '96px',
  32: '128px',
  40: '160px',
  48: '192px',
  56: '224px',
  64: '256px',
} as const;
```

```ts
// tokens/primitives/typography.ts
export const primitiveTypography = {
  fontFamily: {
    sans: ['Space Grotesk', 'system-ui', 'sans-serif'],
    serif: ['Georgia', 'Cambria', 'serif'],
    mono: ['Menlo', 'Monaco', 'monospace'],
  },
  fontSize: {
    xs: '0.75rem', // 12px
    sm: '0.875rem', // 14px
    base: '1rem', // 16px
    lg: '1.125rem', // 18px
    xl: '1.25rem', // 20px
    '2xl': '1.5rem', // 24px
    '3xl': '1.875rem', // 30px
    '4xl': '2.25rem', // 36px
    '5xl': '3rem', // 48px
    '6xl': '3.75rem', // 60px
    '7xl': '4.5rem', // 72px
  },
  fontWeight: {
    thin: '100',
    light: '300',
    normal: '400',
    medium: '500',
    semibold: '600',
    bold: '700',
    extrabold: '800',
    black: '900',
  },
  lineHeight: {
    none: '1',
    tight: '1.25',
    snug: '1.375',
    normal: '1.5',
    relaxed: '1.625',
    loose: '2',
  },
  letterSpacing: {
    tighter: '-0.05em',
    tight: '-0.025em',
    normal: '0',
    wide: '0.025em',
    wider: '0.05em',
    widest: '0.1em',
  },
} as const;
```

### Layer 2: Semantic tokens

Meaningful tokens that reference primitives:

```ts
// tokens/semantic/colors.ts
import { tokens } from 'typestyles';
import { primitiveColors } from '../primitives/colors';

export const color = tokens.create('color', {
  // Brand
  brand: primitiveColors.brand[500],
  brandHover: primitiveColors.brand[600],
  brandActive: primitiveColors.brand[700],
  brandSubtle: primitiveColors.brand[100],
  brandMuted: primitiveColors.brand[200],

  // Text
  text: primitiveColors.gray[900],
  textMuted: primitiveColors.gray[500],
  textSubtle: primitiveColors.gray[400],
  textInverse: '#ffffff',
  textBrand: primitiveColors.brand[600],

  // Backgrounds
  background: primitiveColors.gray[50],
  surface: '#ffffff',
  surfaceRaised: primitiveColors.gray[100],
  surfaceSunken: primitiveColors.gray[50],
  surfaceOverlay: 'rgba(0, 0, 0, 0.5)',

  // Borders
  border: primitiveColors.gray[200],
  borderHover: primitiveColors.gray[300],
  borderActive: primitiveColors.brand[500],

  // Status
  success: primitiveColors.green[500],
  successSubtle: primitiveColors.green[50],
  warning: primitiveColors.orange[500],
  warningSubtle: primitiveColors.orange[50],
  danger: primitiveColors.red[500],
  dangerSubtle: primitiveColors.red[50],
  info: primitiveColors.blue[500],
  infoSubtle: primitiveColors.blue[50],
});
```

```ts
// tokens/semantic/spacing.ts
import { tokens } from 'typestyles';
import { primitiveSpacing } from '../primitives/spacing';

export const space = tokens.create('space', {
  // Base scale
  ...primitiveSpacing,

  // Semantic aliases
  gap: primitiveSpacing[4],
  gapSm: primitiveSpacing[2],
  gapLg: primitiveSpacing[6],

  section: primitiveSpacing[16],
  sectionSm: primitiveSpacing[12],
  sectionLg: primitiveSpacing[24],

  component: primitiveSpacing[4],
  componentSm: primitiveSpacing[3],
  componentLg: primitiveSpacing[6],
});
```

Split typography into **separate token namespaces** so scale names like `normal` and `tight` do not collide across weight, line height, and tracking (a single `tokens.create('font', …)` object cannot contain duplicate keys).

```ts
// tokens/semantic/typography.ts
import { tokens } from 'typestyles';
import { primitiveTypography } from '../primitives/typography';

export const font = tokens.create('font', {
  sans: primitiveTypography.fontFamily.sans.join(', '),
  serif: primitiveTypography.fontFamily.serif.join(', '),
  mono: primitiveTypography.fontFamily.mono.join(', '),

  xs: primitiveTypography.fontSize.xs,
  sm: primitiveTypography.fontSize.sm,
  base: primitiveTypography.fontSize.base,
  lg: primitiveTypography.fontSize.lg,
  xl: primitiveTypography.fontSize.xl,
  '2xl': primitiveTypography.fontSize['2xl'],
  '3xl': primitiveTypography.fontSize['3xl'],
  '4xl': primitiveTypography.fontSize['4xl'],

  body: primitiveTypography.fontSize.base,
  bodySm: primitiveTypography.fontSize.sm,
  bodyLg: primitiveTypography.fontSize.lg,
  headingSm: primitiveTypography.fontSize.xl,
  heading: primitiveTypography.fontSize['2xl'],
  headingLg: primitiveTypography.fontSize['3xl'],
  headingXl: primitiveTypography.fontSize['4xl'],
  display: primitiveTypography.fontSize['5xl'],
  displayLg: primitiveTypography.fontSize['6xl'],
});

export const fontWeight = tokens.create('font-weight', {
  normal: primitiveTypography.fontWeight.normal,
  medium: primitiveTypography.fontWeight.medium,
  semibold: primitiveTypography.fontWeight.semibold,
  bold: primitiveTypography.fontWeight.bold,
});

export const lineHeight = tokens.create('line-height', {
  none: primitiveTypography.lineHeight.none,
  tight: primitiveTypography.lineHeight.tight,
  snug: primitiveTypography.lineHeight.snug,
  normal: primitiveTypography.lineHeight.normal,
  relaxed: primitiveTypography.lineHeight.relaxed,
  loose: primitiveTypography.lineHeight.loose,
});

export const letterSpacing = tokens.create('letter-spacing', {
  tighter: primitiveTypography.letterSpacing.tighter,
  tight: primitiveTypography.letterSpacing.tight,
  normal: primitiveTypography.letterSpacing.normal,
  wide: primitiveTypography.letterSpacing.wide,
  wider: primitiveTypography.letterSpacing.wider,
  widest: primitiveTypography.letterSpacing.widest,
});
```

### Layer 3: Component tokens

Component-specific tokens:

```ts
// tokens/components/button.ts
import { tokens } from 'typestyles';
import { color, space, font, fontWeight } from '../semantic';

export const button = tokens.create('button', {
  // Size
  heightSm: '32px',
  heightMd: '40px',
  heightLg: '48px',

  // Padding
  paddingHorizontalSm: space[3],
  paddingHorizontalMd: space[4],
  paddingHorizontalLg: space[6],
  paddingVerticalSm: space[2],
  paddingVerticalMd: space[2],
  paddingVerticalLg: space[3],

  // Border radius
  borderRadius: '6px',
  borderRadiusSm: '4px',
  borderRadiusLg: '8px',

  // Font
  fontSizeSm: font.sm,
  fontSizeMd: font.base,
  fontSizeLg: font.lg,
  fontWeight: fontWeight.medium,

  // Primary variant
  primaryBackground: color.brand,
  primaryBackgroundHover: color.brandHover,
  primaryBackgroundActive: color.brandActive,
  primaryText: color.textInverse,

  // Secondary variant
  secondaryBackground: color.surface,
  secondaryBackgroundHover: color.surfaceRaised,
  secondaryBorder: color.border,
  secondaryText: color.text,

  // Focus ring
  focusRingColor: color.brand,
  focusRingWidth: '2px',
  focusRingOffset: '2px',
});
```

```ts
// tokens/components/card.ts
import { tokens } from 'typestyles';
import { color, space } from '../semantic';

export const card = tokens.create('card', {
  // Spacing
  padding: space[6],
  paddingSm: space[4],
  paddingLg: space[8],

  // Visual
  borderRadius: '8px',
  borderWidth: '1px',
  borderColor: color.border,
  background: color.surface,

  // Shadow
  shadow: '0 1px 3px rgba(0, 0, 0, 0.1)',
  shadowHover: '0 4px 6px rgba(0, 0, 0, 0.1)',

  // Header
  headerPadding: space[4],
  headerBorderColor: color.border,

  // Body
  bodyPadding: space[6],

  // Footer
  footerPadding: space[4],
  footerBackground: color.surfaceRaised,
  footerBorderColor: color.border,
});
```

## Token documentation

### Token reference table

Create documentation for your tokens:

```md
# Color Tokens

## Brand

| Token               | Value   | Usage                  |
| ------------------- | ------- | ---------------------- |
| `color.brand`       | #3b82f6 | Primary buttons, links |
| `color.brandHover`  | #2563eb | Hover states           |
| `color.brandSubtle` | #dbeafe | Light backgrounds      |

## Text

| Token               | Value   | Usage                    |
| ------------------- | ------- | ------------------------ |
| `color.text`        | #111827 | Primary text             |
| `color.textMuted`   | #6b7280 | Secondary text           |
| `color.textInverse` | #ffffff | Text on dark backgrounds |

## Status

| Token           | Value   | Usage          |
| --------------- | ------- | -------------- |
| `color.success` | #22c55e | Success states |
| `color.danger`  | #ef4444 | Error states   |
```

### Token usage examples

```ts
// Always use tokens, never hardcode values

// ❌ Bad
const button = styles.component('button', {
  base: {
    padding: '8px 16px', // Hardcoded
    backgroundColor: '#3b82f6', // Hardcoded
  },
});

// ✅ Good
const button = styles.component('button', {
  base: {
    padding: `${buttonToken.paddingHorizontalMd} ${buttonToken.paddingVerticalMd}`,
    backgroundColor: buttonToken.primaryBackground,
  },
});
```

## Theme variations

### Dark theme

```ts
// tokens/themes/dark.ts
import { tokens } from 'typestyles';
import { primitiveColors } from '../primitives/colors';

export const darkTheme = tokens.createTheme('dark', {
  base: {
    color: {
      brand: primitiveColors.brand[400],
      brandHover: primitiveColors.brand[300],
      brandActive: primitiveColors.brand[500],

      text: primitiveColors.gray[100],
      textMuted: primitiveColors.gray[400],
      textSubtle: primitiveColors.gray[500],
      textInverse: primitiveColors.gray[900],

      background: primitiveColors.gray[900],
      surface: primitiveColors.gray[800],
      surfaceRaised: primitiveColors.gray[700],
      surfaceSunken: primitiveColors.gray[950],

      border: primitiveColors.gray[700],
      borderHover: primitiveColors.gray[600],
    },
  },
});
```

### High contrast theme

```ts
// tokens/themes/high-contrast.ts
import { tokens } from 'typestyles';

export const highContrastTheme = tokens.createTheme('high-contrast', {
  base: {
    color: {
      text: '#000000',
      background: '#ffffff',
      border: '#000000',
      brand: '#0000ff',

      success: '#006600',
      warning: '#cc6600',
      danger: '#cc0000',
    },
  },
});
```

## Token naming conventions

### Consistent naming

```
Category + Property + Variant + State

Examples:
- color.text (category.property)
- color.textMuted (category.property.variant)
- color.textMutedHover (category.property.variant.state)
- button.primaryBackground (category.property)
- button.primaryBackgroundHover (category.property.state)
```

### Property modifiers

```
Base: color.brand
Subtle: color.brandSubtle
Muted: color.brandMuted
Hover: color.brandHover
Active: color.brandActive
Disabled: color.brandDisabled
Inverse: color.brandInverse
```

## Token validation

### Type checking

```ts
// Ensure all required tokens exist
interface RequiredTokens {
  brand: string;
  text: string;
  background: string;
  // ... etc
}

// TypeScript will catch missing tokens
const requiredTokens: RequiredTokens = {
  brand: color.brand,
  text: color.text,
  background: color.background,
};
```

### Contrast checking

```ts
// WCAG contrast ratio helper
function getContrastRatio(color1: string, color2: string): number {
  // Implementation
}

// Ensure accessible contrast
const contrastRatio = getContrastRatio(color.text, color.background);
if (contrastRatio < 4.5) {
  console.warn('Text contrast does not meet WCAG AA standards');
}
```

## Token distribution

### NPM package structure

```
@myorg/design-tokens/
├── package.json
├── tokens/
│   ├── primitives/
│   ├── semantic/
│   ├── components/
│   └── themes/
└── dist/
    ├── tokens.css      # CSS custom properties
    ├── tokens.json     # JSON format
    └── tokens.scss     # SCSS variables
```

### Multiple formats

TypeStyles **does not** ship a separate “token compiler” — your `tokens.create` calls emit **CSS custom properties** when the module runs (or when an extraction build evaluates your entry). For **additional** artifacts (JSON for Figma pipelines, SCSS for legacy apps), treat primitives as the source of truth in TypeScript and add your own small exporters.

**CSS (what TypeStyles already produces)**

- **Diagnostics / tests** — `getRegisteredCss()` from `typestyles` after importing your token modules.
- **SSR** — `collectStyles()` from `typestyles/server` around `renderToString`, then inject the returned CSS string.
- **Production bundle** — `@typestyles/vite`, `@typestyles/rollup`, or `@typestyles/next` with an [extraction entry](/docs/zero-runtime) so a static `.css` file includes `:root` and theme rules.

**JSON / SCSS**

- Export plain objects from `tokens/primitives/*.ts` and `JSON.stringify` them, or generate SCSS variables from those objects in a script. Keep TypeStyles as the runtime source of truth for `var(--…)` values that components actually use.

## Token governance

### Change process

1. **Request**: Designer/developer requests a new token
2. **Review**: Design system team reviews for necessity
3. **Naming**: Follow naming conventions
4. **Documentation**: Update token reference
5. **Communication**: Announce breaking changes
6. **Deprecation**: Mark old tokens as deprecated before removal

### Versioning

```json
{
  "name": "@myorg/design-tokens",
  "version": "2.1.0",
  "description": "Design tokens for the Acme design system"
}
```

Breaking changes (new major version):

- Removing tokens
- Renaming tokens
- Changing token values significantly

Non-breaking changes (new minor/patch):

- Adding new tokens
- Small value adjustments
- Adding new themes

## Best practices summary

1. **Never hardcode values** - Always use tokens
2. **Use semantic names** - `color.text` not `color.gray900`
3. **Layer your tokens** - Primitives → Semantics → Components
4. **Document everything** - Maintain token reference
5. **Test contrast** - Ensure accessibility compliance
6. **Version carefully** - Follow semantic versioning
7. **Support multiple themes** - Light, dark, high-contrast
8. **Generate multiple formats** - CSS, SCSS, JSON for different consumers
9. **Govern changes** - Have a process for token modifications
10. **Provide examples** - Show developers how to use tokens

Source: https://typestyles.dev/docs/design-system

---

# Dynamic styling

Per-instance values with createVar and assignVars — the TypeStyles way to handle dynamic CSS


Some style values change per instance: a progress bar's width, a chart segment's color, a user's chosen accent. TypeStyles styles are defined at module level and extracted at build time, so you cannot put runtime props directly into style objects. Instead, wire dynamic values through **CSS custom properties** with `createVar()` and `assignVars()`.

This keeps your extracted CSS static while still letting each element pick its own value at runtime — without abandoning your component's type-safe style definitions.

## Basic pattern

Define a var reference in your styles, then set its value on each instance:

```ts
import { styles, createVar, assignVars } from 'typestyles';

const progressFill = createVar('progressFill');

const progress = styles.component('progress', {
  base: {
    height: '8px',
    borderRadius: '4px',
    background: '#e5e7eb',
  },
  bar: {
    height: '100%',
    borderRadius: 'inherit',
    background: '#0066ff',
    width: progressFill,
  },
});

function ProgressBar({ value }: { value: number }) {
  return (
    <div className={progress('base')}>
      <div
        className={progress('bar')}
        style={assignVars({ [progressFill]: `${value}%` })}
      />
    </div>
  );
}
```

In DevTools you'll see `--ts-progressfill: 42%` on the element — readable, not an anonymous `--ts-1`.

## Debug names

Pass a name to `createVar()` for inspectable custom property names:

```ts
const cardBg = createVar('cardBg'); // → var(--ts-cardbg)
const cardBorder = createVar('cardBorder', 'transparent'); // → var(--ts-cardborder, transparent)
```

Names are sanitized to valid CSS identifiers (lowercase, hyphens). Calling `createVar('cardBg')` twice produces `--ts-cardbg` and `--ts-cardbg-2` so refs stay unique.

Omit the name when you don't need DevTools labels — anonymous vars use numeric ids (`--ts-1`, `--ts-2`, …).

## assignVars

`assignVars()` converts var refs into a plain object for inline `style` props:

```ts
assignVars({ [cardBg]: '#ff0099', [cardBorder]: '#ccc' });
// → { '--ts-cardbg': '#ff0099', '--ts-cardborder': '#ccc' }
```

It skips `null` and `undefined` values, so you can conditionally omit vars. The return type is `Record<string, string>` — safe to spread into React, Vue, Svelte, or plain DOM `element.style`.

Works with fallbacks too: `assignVars` extracts the property name from `var(--ts-cardbg, #fff)`.

## When to use this vs alternatives

| Approach                                 | Best for                                                                             |
| ---------------------------------------- | ------------------------------------------------------------------------------------ |
| **`createVar` + `assignVars`**           | Dynamic _values_ on otherwise static styles (widths, colors, transforms)             |
| **Variants**                             | Discrete, known-ahead-of-time options (`size: 'sm' \| 'lg'`)                         |
| **Tokens / themes**                      | Design-system values shared across the app                                           |
| **Component `ctx.var()` / `ctx.vars()`** | Internal vars scoped to one component namespace (see [Components](/docs/components)) |
| **Raw inline styles**                    | One-off properties with no shared style definition                                   |

Prefer `createVar` over raw inline styles when the property is part of a component's style definition. The CSS rule stays in your extracted stylesheet; only the variable value changes per instance.

## Multiple dynamic properties

```ts
const barColor = createVar('barColor');
const barWidth = createVar('barWidth');

const chartBar = styles.component('chart-bar', {
  base: {
    background: barColor,
    width: barWidth,
    height: '100%',
    borderRadius: '2px',
  },
});

function Bar({ color, width }: { color: string; width: string }) {
  return (
    <div
      className={chartBar('base')}
      style={assignVars({ [barColor]: color, [barWidth]: width })}
    />
  );
}
```

## Fallback values

Provide a CSS fallback as the second argument — useful when a var might not be set:

```ts
const accent = createVar('accent', '#0066ff');

const badge = styles.component('badge', {
  base: {
    color: accent,
    fontWeight: 600,
  },
});

// Without assignVars, the fallback '#0066ff' applies
<div className={badge('base')} />

// Per-instance override
<div
  className={badge('base')}
  style={assignVars({ [accent]: userColor })}
/>
```

## Zero-runtime extraction

Dynamic vars work in zero-runtime mode. The extracted CSS contains rules like `width: var(--ts-progressfill)` — only the custom property _values_ are set at runtime via inline styles. Your build output stays deterministic; unreachable styles are still caught by [verifyTypestylesBuild](/docs/zero-runtime#verify-extraction-in-ci).

## Related

- [Components](/docs/components) — scoped internal vars via `ctx.var()` and `ctx.vars()`
- [Tokens](/docs/tokens) — design-system custom properties
- [Performance](/docs/performance) — why module-level styles + vars beat dynamic style objects
- [Best practices](/docs/best-practices) — naming and organization patterns

Source: https://typestyles.dev/docs/dynamic-styles

---

# Fonts

Loading web fonts with global.fontFace, Vite, and Next.js


TypeStyles does not replace the platform font stack: you still choose **families** with normal CSS properties (`fontFamily`, `fontWeight`, tokens, and so on). For **loading** files or tuning fallbacks, use **`global.fontFace()`** from the same `createTypeStyles` / `createGlobal` instance as the rest of your app styles.

## `global.fontFace(family, props)`

Registers an `@font-face` rule. Calls are deduplicated by **family name + normalized `src`**.

- **`src`** — Either one CSS fragment (`"url('…') format('woff2')"` or `"local('My Font')"`…) or an **array** of fragments, which are joined with commas (same as a handwritten multi-value `src:`).
- **`fontWeight`** / **`fontStyle`** — Supports variable fonts with a range string, e.g. `'100 900'`.
- **`fontDisplay`**, **`fontStretch`**, **`unicodeRange`** — Passed through to CSS.
- **Metric overrides** (optional): **`sizeAdjust`**, **`ascentOverride`**, **`descentOverride`**, **`lineGapOverride`** — map to `size-adjust`, `ascent-override`, `descent-override`, and `line-gap-override` for fallback tuning.

The family name is emitted as a quoted `font-family` in `@font-face`. Use the same name first in your `font-family` stacks (as in design tokens) so the loaded face applies.

See also [API Reference — `global`](/docs/api-reference).

## Vite: local files

### `public/` (works with zero-runtime extraction)

Put files under **`public/fonts/`** and use a root-relative URL. This matches how [zero-runtime extraction](/docs/zero-runtime) collects CSS: extract entries are bundled with **esbuild**, which does **not** run Vite’s `?url` pipeline for font files. Any module in `extract.modules` should avoid `import './font.woff2?url'` unless you add a custom extract setup.

```ts
global.fontFace('Inter', {
  src: "url('/fonts/inter-latin-400-normal.woff2') format('woff2')",
  fontWeight: 400,
  fontStyle: 'normal',
  fontDisplay: 'swap',
});
```

The [Vite plugin](/docs/vite-plugin) invalidates `@font-face` rules on HMR when your module calls `global.fontFace('FamilyName', …)`.

### `?url` imports (runtime-only or non-extract graphs)

When styles run only through **Vite’s** transform (for example **no** `extract.modules`, or the font import lives outside the extract entry graph), you can use **`?url`** so production CSS points at a hashed asset:

```ts
import interWoff2 from './fonts/inter-latin-400-normal.woff2?url';

global.fontFace('Inter', {
  src: `url(${interWoff2}) format('woff2')`,
  fontDisplay: 'swap',
});
```

Add `/// <reference types="vite/client" />` in a `vite-env.d.ts` (or use Vite’s default template) so TypeScript understands `?url` imports.

## Next.js: local files

**`buildTypestylesForNext` / `collectStylesFromModules`** execute your style entry in **Node**. Avoid importing binary font URLs there unless your runner resolves them the same way as the browser bundle.

**Reliable pattern:** place fonts in **`public/fonts/…`** and reference them with a **root-relative** `url('/fonts/…')` in `global.fontFace`. Next serves `public/` at the site root, and extraction only needs the string.

**With `next/font/local`:** you can keep `next/font` for optimized loading and still use TypeStyles for components. Either apply the `next/font` `className` on the root layout or map the resolved CSS variables into your tokens—TypeStyles does not need to own `@font-face` in that setup.

## External stylesheets (Google Fonts, etc.)

You can still use `<link rel="stylesheet" href="…">` in your layout. That path is independent of `global.fontFace`; pick one strategy per family to avoid loading the same face twice.

## Types

`FontFaceProps` and **`FontFaceSrc`** are exported from `typestyles` for reuse in helpers or design-system wrappers.

Source: https://typestyles.dev/docs/fonts

---

# Framework comparison

How TypeStyles compares to StyleX, Panda CSS, vanilla-extract, Emotion, CSS Modules, and plain CSS—with a shared button example and a topic-by-topic comparison


This page is a **decision lens**: same button pattern across ecosystems, then a **topic-by-topic** comparison (easier to scan on a laptop than a wide grid of cards or a seven-column table). For API-by-API moves, use the [Migration guide](/docs/migration). For install and your first component, see [Getting started](/docs/getting-started).

## Compared at a glance

Each subsection below is one decision axis. Lists use normal body typography—**tool names** and `inline code` carry the emphasis.

### Build

- **TypeStyles** — Optional; runtime by default, [zero-runtime](/docs/zero-runtime) when you want.
- **StyleX** — **Required** compiler (Babel / SWC).
- **Panda CSS** — **Required** codegen + config.
- **vanilla-extract** — **Required** `.css.ts` + bundler.
- **Emotion / styled-components** — Bundler only; runtime in the loop.
- **CSS Modules** — Bundler maps your authored class names to **per-file scoped** output.
- **Plain CSS** — None for CSS itself.

### Typical DOM classes

- **TypeStyles** — Readable names (`button-intent-primary`); scoped `--scope-token-*`.
- **StyleX** — Atomic, hashed.
- **Panda CSS** — Utilities / recipes from your preset.
- **vanilla-extract** — Usually hashed / scoped.
- **Emotion / styled-components** — Hashed.
- **CSS Modules** — You choose readable names in CSS; the bundler emits **scoped** class strings in the DOM, **usually with a short content hash** so files cannot collide (for example `._primary_abc123`).
- **Plain CSS** — Whatever you author.

### Tokens

- **TypeStyles** — `tokens.create` → real CSS variables.
- **StyleX** — `defineVars` + compiler.
- **Panda CSS** — Config-first scales (`blue.600`, etc.).
- **vanilla-extract** — You wire CSS vars / contracts.
- **Emotion / styled-components** — Theme objects / your own vars.
- **CSS Modules** — Your globals / vars.
- **Plain CSS** — Your conventions.

### Good fit when…

- **TypeStyles** — TS variants **and** inspectable CSS **without** a compiler on day one.
- **StyleX** — Meta stack, static guarantees, atomic output.
- **Panda CSS** — You want Panda’s pipeline and strict token schema.
- **vanilla-extract** — **Zero runtime by default**, file-based CSS.
- **Emotion / styled-components** — Classic styled API; fine with runtime (or separate extraction).
- **CSS Modules** — Mostly hand-written CSS; variants via `clsx` / toggles.
- **Plain CSS** — Maximum portability; TS ergonomics are DIY.

**SSR / production CSS:** TypeStyles can [collect styles for SSR](/docs/ssr) and optionally [extract static CSS](/docs/zero-runtime). StyleX, Panda, and vanilla-extract generally emit CSS at build time. Emotion’s story depends on your bundler and extraction setup. CSS Modules and plain CSS ship as stylesheets like any static asset.

---

## Same button: primary vs ghost

Each snippet is a **typed** `intent` (`primary` = filled, `ghost` = outline). Real apps add focus, sizing, and tokens; lengths are trimmed.

### TypeStyles (recommended shape)

[`createTypeStyles`](/docs/api-reference#createtypestyles-options) keeps **styles** and **tokens** on one **`scopeId`** (see [Getting started](/docs/getting-started)).

```ts
import { createTypeStyles } from 'typestyles';

const { styles, tokens } = createTypeStyles({ scopeId: 'app' });
const color = tokens.create('color', { primary: '#2563eb', surface: '#ffffff' });

export const button = styles.component('button', {
  base: {
    padding: '8px 16px',
    borderRadius: '6px',
    fontWeight: 500,
    border: 'none',
    cursor: 'pointer',
  },
  variants: {
    intent: {
      primary: { backgroundColor: color.primary, color: color.surface },
      ghost: {
        backgroundColor: 'transparent',
        color: color.primary,
        border: `1px solid ${color.primary}`,
      },
    },
  },
  defaultVariants: { intent: 'primary' },
});
```

```tsx
<button type="button" className={button({ intent })}>
  {children}
</button>
```

### StyleX (compiler, atomic classes)

Author-time objects; **`stylex.props`** merges styles at compile time. Hashed atomic classes in the DOM.

```ts
import * as stylex from '@stylexjs/stylex';

const s = stylex.create({
  base: {
    padding: '8px 16px',
    borderRadius: '6px',
    fontWeight: 500,
    border: 'none',
    cursor: 'pointer',
  },
  primary: { backgroundColor: '#2563eb', color: '#fff' },
  ghost: {
    backgroundColor: 'transparent',
    color: '#2563eb',
    borderWidth: '1px',
    borderStyle: 'solid',
    borderColor: '#2563eb',
  },
});
```

```tsx
<button type="button" {...stylex.props(s.base, intent === 'ghost' ? s.ghost : s.primary)}>
  {children}
</button>
```

### Panda CSS (`cva` / recipes)

Codegen from **`panda.config`**; import paths vary (`../styled-system/css` here is illustrative). Token strings like `blue.600` are **your** scale.

```ts
import { cva } from '../styled-system/css';

export const button = cva({
  base: { px: '4', py: '2', rounded: 'md', fontWeight: 'medium', cursor: 'pointer' },
  variants: {
    intent: {
      primary: { bg: 'blue.600', color: 'white', borderWidth: '0' },
      ghost: { bg: 'transparent', color: 'blue.600', borderWidth: '1px', borderColor: 'blue.600' },
    },
  },
  defaultVariants: { intent: 'primary' },
});
```

```tsx
<button type="button" className={button({ intent })}>
  {children}
</button>
```

### vanilla-extract (`recipe`)

**`.css.ts`** files; bundler emits **static CSS**. Typed variants; class strings usually **hashed**.

```ts
import { recipe } from '@vanilla-extract/recipes';

export const button = recipe({
  base: {
    padding: '8px 16px',
    borderRadius: '6px',
    fontWeight: 500,
    border: 'none',
    cursor: 'pointer',
  },
  variants: {
    intent: {
      primary: { background: '#2563eb', color: '#fff' },
      ghost: { background: 'transparent', color: '#2563eb', border: '1px solid #2563eb' },
    },
  },
  defaultVariants: { intent: 'primary' },
});
```

```tsx
<button type="button" className={button({ intent })}>
  {children}
</button>
```

### Emotion / styled-components

**Styled component** or `css` prop; **hashed** classes; **tokens** are usually theme objects or vars you wire.

```tsx
import styled from '@emotion/styled';

export const Button = styled.button<{ intent?: 'primary' | 'ghost' }>`
  padding: 8px 16px;
  border-radius: 6px;
  font-weight: 500;
  cursor: pointer;
  border: none;
  ${(p) =>
    p.intent === 'ghost'
      ? `background: transparent; color: #2563eb; border: 1px solid #2563eb;`
      : `background: #2563eb; color: #fff;`}
`;
```

```tsx
<Button intent={intent}>{children}</Button>
```

### CSS Modules

**Plain CSS** in `.module.css`; bundler scopes names. Variants are **manual** (`clsx`, toggles, BEM).

```css
/* Button.module.css */
.base {
  padding: 8px 16px;
  border-radius: 6px;
  font-weight: 500;
  cursor: pointer;
  border: none;
}
.primary {
  background: #2563eb;
  color: #fff;
}
.ghost {
  background: transparent;
  color: #2563eb;
  border: 1px solid #2563eb;
}
```

```tsx
import styles from './Button.module.css';
import clsx from 'clsx';

<button
  type="button"
  className={clsx(styles.base, intent === 'ghost' ? styles.ghost : styles.primary)}
>
  {children}
</button>;
```

### Plain CSS

Global stylesheets, BEM modifiers, or attribute selectors—**no** TS variant layer unless you add one yourself. Maximum portability; colocation and typing are DIY.

---

## Theming architecture: TypeStyles vs. StyleX (and Astryx)

Theming is where compiler restrictions surface in practice. **Astryx**—Meta's design system for internal tools, built on **StyleX**—has a genuinely flexible theming story, but it gets there by working _around_ StyleX's constraints. TypeStyles never had those constraints, so the workaround layer doesn't exist. Three concrete differences:

### Token variables: plain custom properties vs. compiler-managed vars

- **TypeStyles** — [`tokens.create`](/docs/tokens) emits **plain CSS custom properties** with predictable names (`--app-color-primary` under `scopeId: 'app'`) from any ordinary TypeScript module. Themes are [`tokens.createTheme`](/docs/theming-patterns) surfaces: a stable `theme-{name}` class whose properties override token values for that subtree. Because the variables are just CSS, any stylesheet—yours, legacy, third-party—can read or set them directly.
- **StyleX** — `defineVars` also compiles to custom properties, but with **hashed names the compiler owns**, and variable definitions **must live in `.stylex.ts` / `.stylex.js` files** so imports can be resolved statically; theming (`createTheme`) flows through those same files. Astryx's theming flexibility is built by routing around these rules. With TypeStyles there is **no compiler restriction to route around**.

TypeStyles theme surfaces also carry a general condition engine—`tokens.when` (media queries, attributes, class names, `or` / `and` / `not` combinators) plus [`tokens.colorMode`](/docs/theming-patterns#light-dark-system-on-data) presets—so "dark when the OS prefers it, unless `data-color-mode="light"` wins" is a declaration, not bespoke infrastructure on top of fixed light/dark modes.

### Distribution: build-always vs. runtime injection with a warning

- **TypeStyles** — Token and theme CSS goes through the **same pipeline as every other style**: runtime injection in dev, static CSS via [zero-runtime extraction](/docs/zero-runtime) when you want it. There is no dedicated theme-build command, because none is needed—and therefore no "did you forget to build your theme" state to warn about.
- **Astryx** — Themes that weren't compiled ahead of time are **injected at runtime with a console warning**, and users are pushed toward a separate `astryx theme build` step to get static CSS.

### Component overrides: plain CSS vs. a config DSL

- **TypeStyles** — [`styles.component`](/docs/components) emits **semantic, deterministic class names** (`button-intent-primary`). A consumer restyling a component writes ordinary CSS targeting that class—any property, any selector, any stylesheet—and [cascade layers](/docs/cascade-layers) keep override order predictable.
- **StyleX / Astryx** — Hashed atomic classes can't be targeted from outside the compiler, so Astryx exposes overrides through an **`@scope` + data-attribute configuration DSL**: you can override what the DSL anticipates, in the shapes it anticipates.

The pattern across all three: a StyleX-based system must **generate an escape hatch** for each theming capability its compiler forecloses. TypeStyles ships the underlying primitives—real custom properties, readable class names, cascade layers—so the capability is the default, not the workaround.

---

## When TypeStyles is a strong default

- **Readable classes** and **scoped CSS variables** for DevTools, legacy CSS, and third-party markup.
- **Typed variants** (CVA-/recipe-like) **without** a compiler on day one.
- **Incremental adoption** and **`createTypeStyles` + `scopeId`** for libraries or micro-frontends.
- Comfortable with **runtime injection in dev**, with an **optional** [zero-runtime](/docs/zero-runtime) path when you need static CSS.

## When another tool might win

- **StyleX** — Standardized on Meta’s compiler; want static guarantees and atomic output.
- **Panda CSS** — Want codegen utilities and a strict config-first token pipeline.
- **vanilla-extract** — Want **zero runtime by default** and are fine with `.css.ts` contracts.
- **Emotion / styled-components** — Want the classic styled API and accept runtime (or a separate extraction story).
- **CSS Modules** — Mostly hand-written CSS; no first-class variant API in the styling layer.
- **Plain CSS** — Zero JS styling layer; maximum portability.

## Practical migration

Start with [Migration](/docs/migration): Panda- and CVA-like APIs map closely to **`styles.component`**; Emotion and CSS Modules map well to **`styles.class`** plus [`cx`](/docs/compose) from `'typestyles'`.

## Related docs

- [Getting started](/docs/getting-started)
- [Design system with tokens](/docs/design-system)
- [Theming patterns](/docs/theming-patterns)
- [Cascade layers](/docs/cascade-layers)
- [Zero-runtime extraction](/docs/zero-runtime)
- [Component library setup](/docs/component-library)

Source: https://typestyles.dev/docs/framework-comparison

---

# Getting Started

Install TypeStyles and ship your first typed component styles in a few minutes


TypeStyles is **CSS in TypeScript**: style objects (selectors, media queries, pseudos), **typed variants**, **tokens as CSS variables**, and ordinary `className` strings in React, Vue, Svelte, or HTML.

In production, TypeStyles extracts styles at build time into a **static CSS file** with zero runtime overhead — the same approach as StyleX and Vanilla Extract. During development, the runtime injects styles for instant feedback with HMR.

## Installation


```bash
pnpm add typestyles @typestyles/vite
# npm: npm install typestyles @typestyles/vite
# yarn: yarn add typestyles @typestyles/vite
```


The bundler plugin gives you **zero-runtime production builds** and **HMR in dev**. Plugins are also available for [Next.js](/docs/zero-runtime#nextjs), [Rollup](/docs/zero-runtime#rollup--rolldown), [esbuild](/docs/zero-runtime#esbuild), and [webpack](/docs/zero-runtime#webpack).

> **Prototyping without a plugin?** TypeStyles also works as a pure runtime library — just `npm install typestyles` and skip the plugin. You can add build extraction later without changing any application code. See [Zero-runtime extraction](/docs/zero-runtime#switching-between-modes) for the migration path.

## Set up the Vite plugin

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import typestyles from '@typestyles/vite';

export default defineConfig({
  plugins: [react(), typestyles()],
});
```

Create a **convention entry** that imports all your style registrations. The plugin discovers it automatically and extracts CSS on `vite build`:

```ts
// src/typestyles-entry.ts
import './tokens';
import './components/Button.styles';
import './components/Card.styles';
```

That's it. In dev you get runtime injection + HMR. In production, `typestyles.css` is emitted as a static asset with no runtime JS.

## Your first styles

Use [`createTypeStyles`](/docs/api-reference#createtypestyles-options) once so `styles` and `tokens` share one **`scopeId`** (namespaced CSS variables and predictable class names). Put the module in a file you import from your UI — the live example below includes the full source and a `className` usage snippet.


> Interactive demo: https://typestyles.dev/docs/getting-started

```ts
import { createTypeStyles } from 'typestyles';

export const { styles, tokens } = createTypeStyles({ scopeId: 'app' });

export const color = tokens.create('color', {
  primary: '#0066ff',
  surface: '#ffffff',
});

export const button = styles.component('button', {
  base: {
    display: 'inline-flex',
    alignItems: 'center',
    justifyContent: 'center',
    padding: '8px 16px',
    borderRadius: '6px',
    fontWeight: 500,
    border: 'none',
    cursor: 'pointer',
    color: color.surface,
    backgroundColor: color.primary,
  },
  variants: {
    intent: {
      primary: { backgroundColor: color.primary, color: color.surface },
      ghost: {
        backgroundColor: 'transparent',
        color: color.primary,
        border: `1px solid ${color.primary}`,
      },
    },
  },
  defaultVariants: { intent: 'primary' },
});
```


Toggle **Ghost** in the demo and check the **DOM** and **Emitted CSS** panels (or DevTools on the preview button). Scoped class names are prefixed with your `scopeId`, and token-backed values resolve to custom properties such as `--app-color-primary`.

**What just happened:** definitions register when the module loads. In dev, the runtime injects CSS rules into a managed `<style>` tag. In production with a bundler plugin, these same rules are extracted into a static `.css` file — no client-side injection at all. See [Zero-runtime extraction](/docs/zero-runtime) for the full story.

For React-specific patterns (refs, merging `className`, server components), see [React integration](/docs/react-integration). Vue and Svelte work the same way — see the runnable examples below.

## Runnable examples

Clone the [typestyles monorepo](https://github.com/type-styles/typestyles) and run from the repo root (`pnpm install` once):

| Example                                                | Command               | README                                                                                                   |
| ------------------------------------------------------ | --------------------- | -------------------------------------------------------------------------------------------------------- |
| Vite + React (recommended, zero-runtime in production) | `pnpm vite-app dev`   | [examples/vite-app](https://github.com/type-styles/typestyles/blob/main/examples/vite-app/README.md)     |
| Next.js App Router + extraction verify                 | `pnpm next-app dev`   | [examples/next-app](https://github.com/type-styles/typestyles/blob/main/examples/next-app/README.md)     |
| Vue 3                                                  | `pnpm vue-app dev`    | [examples/vue-app](https://github.com/type-styles/typestyles/blob/main/examples/vue-app/README.md)       |
| Svelte 5                                               | `pnpm svelte-app dev` | [examples/svelte-app](https://github.com/type-styles/typestyles/blob/main/examples/svelte-app/README.md) |
| Runtime only (no bundler plugin)                       | `pnpm parcel-app dev` | [examples/parcel-app](https://github.com/type-styles/typestyles/blob/main/examples/parcel-app/README.md) |

Full index: [examples/README.md](https://github.com/type-styles/typestyles/blob/main/examples/README.md) · maintainer map: [docs/README.md](https://github.com/type-styles/typestyles/blob/main/docs/README.md#doc-pages-and-runnable-examples)

## Next steps

| Topic                                              | What you will learn                                                               |
| -------------------------------------------------- | --------------------------------------------------------------------------------- |
| [Zero-runtime extraction](/docs/zero-runtime)      | Production static CSS with Vite, Next.js, Rollup, esbuild, webpack                |
| [Styles](/docs/styles)                             | Flat vs dimensioned `styles.component`, `styles.class`, composition, mental model |
| [Components](/docs/components)                     | Variants, compounds, multipart `slots`                                            |
| [Tokens](/docs/tokens)                             | Namespaces, themes, `tokens.use`                                                  |
| [Framework comparison](/docs/framework-comparison) | How TypeStyles compares to other tools                                            |
| [Migration](/docs/migration)                       | Mapping from Panda, CVA, StyleX, Emotion                                          |
| [Design system with tokens](/docs/design-system)   | Primitives → semantics → components                                               |
| [Class naming](/docs/class-naming)                 | Semantic vs hashed output                                                         |

Source: https://typestyles.dev/docs/getting-started

---

# Keyframes

Create CSS animations with type-safe keyframe definitions


The `keyframes` API lets you define CSS animations with type-safe keyframe stops. Like styles and tokens, keyframes generate readable names and integrate seamlessly with the rest of your typestyles.

## Creating animations

Use `keyframes.create(name, stops)` to define an animation:

```ts
import { keyframes } from 'typestyles';

const fadeIn = keyframes.create('fadeIn', {
  from: { opacity: 0 },
  to: { opacity: 1 },
});
```

The function returns the animation name as a string, which you can use directly in your styles:

```ts
import { styles } from 'typestyles';

const card = styles.component('card', {
  base: {
    animation: `${fadeIn} 300ms ease`,
  },
});

// className={card()}
```

## Keyframe stops

You can use percentage values, `from` (0%), or `to` (100%):

```ts
const bounce = keyframes.create('bounce', {
  '0%': { transform: 'translateY(0)' },
  '40%': { transform: 'translateY(-30px)' },
  '60%': { transform: 'translateY(-15px)' },
  '100%': { transform: 'translateY(0)' },
});
```

## Using with styles

Reference keyframes in your style definitions using template literals:

```ts
import { styles, keyframes } from 'typestyles';

const spin = keyframes.create('spin', {
  from: { transform: 'rotate(0deg)' },
  to: { transform: 'rotate(360deg)' },
});

const loader = styles.component('loader', {
  base: {
    width: '24px',
    height: '24px',
    border: '3px solid #e5e7eb',
    borderTopColor: '#0066ff',
    borderRadius: '50%',
    animation: `${spin} 800ms linear infinite`,
  },
});
```

## Multiple properties

Each keyframe stop can contain multiple CSS properties:

```ts
const slideIn = keyframes.create('slideIn', {
  from: {
    opacity: 0,
    transform: 'translateX(-20px)',
  },
  to: {
    opacity: 1,
    transform: 'translateX(0)',
  },
});
```

## TypeScript support

Keyframe stops are fully typed, giving you autocomplete and error checking:

```ts
// TypeScript will catch this typo
const badAnimation = keyframes.create('bad', {
  frrom: { opacity: 0 }, // Error: Object literal may only specify known properties
  to: { opacity: 1 },
});
```

## Generated CSS

Keyframes generate standard CSS `@keyframes` rules with the exact name you provide:

```css
@keyframes fadeIn {
  from {
    opacity: 0;
  }
  to {
    opacity: 1;
  }
}

@keyframes bounce {
  0% {
    transform: translateY(0);
  }
  40% {
    transform: translateY(-30px);
  }
  60% {
    transform: translateY(-15px);
  }
  100% {
    transform: translateY(0);
  }
}
```

This makes debugging easy—you'll see `fadeIn` in DevTools, not a hashed string.

## Performance note

Keyframe CSS is injected once when the animation is first used, just like styles. Multiple components using the same animation share the same CSS rule.

Source: https://typestyles.dev/docs/keyframes

---

# Migration Guide

Migrate to typestyles from other CSS-in-JS libraries


Switching to typestyles from other styling solutions is straightforward. This guide covers the most common migration paths.

If you are adopting the variant API, start with [Components](/docs/components).

## From Panda CSS

Panda and typestyles share many concepts (component variants, tokens, utilities), so migration is mostly API shape changes rather than a full styling rewrite.

### `css()` to `styles.class()` or `styles.component()`

**Before (Panda CSS):**

```tsx
import { css } from '../styled-system/css';

const className = css({
  display: 'flex',
  gap: '4',
  '&:hover': { opacity: 0.9 },
});
```

**After (typestyles):**

```tsx
import { styles } from 'typestyles';

const className = styles.class('card', {
  display: 'flex',
  gap: '16px',
  '&:hover': { opacity: 0.9 },
});
```

For reusable variant families, prefer `styles.component()` instead of a single class.

### `cva()` / `defineRecipe()` to `styles.component()`

**Before (Panda CSS):**

```ts
import { cva } from '../styled-system/css';

const button = cva({
  base: { fontWeight: 'medium' },
  variants: {
    intent: {
      solid: { bg: 'blue.500', color: 'white' },
      ghost: { bg: 'transparent' },
    },
  },
  defaultVariants: { intent: 'solid' },
});
```

**After (typestyles):**

```ts
import { styles } from 'typestyles';

const button = styles.component('button', {
  base: { fontWeight: 500 },
  variants: {
    intent: {
      solid: { backgroundColor: '#2563eb', color: 'white' },
      ghost: { backgroundColor: 'transparent' },
    },
  },
  defaultVariants: { intent: 'solid' },
});

// Call as function (base auto-applied):
button(); // base + solid
button({ intent: 'ghost' }); // base + ghost

// Or destructure:
const { base } = button;
```

### `theme.tokens` / semantic tokens to `tokens.create()` + `tokens.createTheme()`

**Before (Panda CSS):**

```ts
// panda.config.ts
theme: {
  tokens: {
    colors: {
      primary: { value: '#0FEE0F' }
    }
  },
  semanticTokens: {
    colors: {
      danger: { value: { base: '{colors.red.500}', _dark: '{colors.red.200}' } }
    }
  }
}
```

**After (typestyles):**

```ts
import { tokens } from 'typestyles';

export const color = tokens.create('color', {
  primary: '#0FEE0F',
  danger: '#ef4444',
});

export const darkTheme = tokens.createTheme('dark', {
  base: {
    color: {
      danger: '#fca5a5',
    },
  },
});
```

Apply `darkTheme.className` on a parent container to scope dark values.

### Panda utility props to `@typestyles/props`

```ts
import { defineProperties, createProps } from '@typestyles/props';

const atoms = createProps(
  'atom',
  defineProperties({
    conditions: {
      sm: { '@media': '(min-width: 640px)' },
      dark: { selector: '[data-theme="dark"] &' },
    },
    properties: {
      display: ['flex', 'grid', 'block'],
      gap: { 1: '4px', 2: '8px', 3: '12px' },
    },
  }),
);

atoms({
  display: 'flex',
  gap: { _: 2, sm: 3 },
});
```

### Slot components (Panda `sva`)

If you use Panda `sva` (multipart slot variants), use `styles.component` with a `slots` configuration so each part maps to a named slot. See [Components](/docs/components).

## From styled-components

### Component structure

**Before (styled-components):**

```tsx
import styled from 'styled-components';

const Button = styled.button`
  padding: 8px 16px;
  border-radius: 6px;
  background-color: ${(props) => (props.primary ? '#0066ff' : '#6b7280')};
  color: white;

  &:hover {
    opacity: 0.9;
  }

  &:disabled {
    opacity: 0.5;
    cursor: not-allowed;
  }
`;

<Button primary>Click me</Button>;
```

**After (typestyles):**

```tsx
import { styles, tokens } from 'typestyles';

const color = tokens.use('color');

const button = styles.component('button', {
  base: {
    padding: '8px 16px',
    borderRadius: '6px',
    color: 'white',
    '&:hover': { opacity: 0.9 },
    '&:disabled': { opacity: 0.5, cursor: 'not-allowed' },
  },
  variants: {
    intent: {
      primary: { backgroundColor: color.primary },
      secondary: { backgroundColor: color.secondary },
    },
  },
  defaultVariants: { intent: 'primary' },
});

function Button({ primary, children }) {
  return (
    <button className={button({ intent: primary ? 'primary' : 'secondary' })}>{children}</button>
  );
}
```

### Key differences

1. **No component wrapper** - typestyles returns class names, not React components
2. **Explicit props handling** - Logic moves from template literals to regular JavaScript
3. **Static styles** - Dynamic values become explicit variants or are passed via inline styles
4. **CSS nesting** - Use `&` prefix for pseudo-classes like `&:hover`

### Dynamic values

**Before:**

```tsx
const Box = styled.div`
  width: ${(props) => props.width}px;
  height: ${(props) => props.height}px;
`;
```

**After:**

```tsx
const box = styles.component('box', {
  base: {
    display: 'inline-block',
  },
});

function Box({ width, height, children }) {
  return (
    <div className={box()} style={{ width, height }}>
      {children}
    </div>
  );
}
```

Dynamic values that change frequently should use inline styles. Static styles should use typestyles variants.

## From Emotion

Emotion's API is similar to styled-components, so the migration path is nearly identical.

### css prop

**Before (Emotion):**

```tsx
/** @jsxImportSource @emotion/react */
import { css } from '@emotion/react';

function Button({ children }) {
  return (
    <button
      css={css`
        padding: 8px 16px;
        background-color: #0066ff;
        color: white;
        &:hover {
          background-color: #0052cc;
        }
      `}
    >
      {children}
    </button>
  );
}
```

**After (typestyles):**

```tsx
import { styles } from 'typestyles';

const button = styles.component('button', {
  base: {
    padding: '8px 16px',
    backgroundColor: '#0066ff',
    color: 'white',
    '&:hover': {
      backgroundColor: '#0052cc',
    },
  },
});

function Button({ children }) {
  return <button className={button()}>{children}</button>;
}
```

### cx utility

**Before:**

```tsx
import { css, cx } from '@emotion/css';

const base = css`padding: 8px;`;
const primary = css`background: blue;`;
const large = css`font-size: 18px;`;

className={cx(base, isPrimary && primary, isLarge && large)}
```

**After:**

When all classes come from one `styles.component` recipe, you can call it with variant overrides or combine pieces with `cx()`:

```tsx
import { styles, cx } from 'typestyles';

const button = styles.component('button', {
  base: { padding: '8px' },
  variants: {
    intent: {
      primary: { backgroundColor: 'blue' },
    },
    size: {
      large: { fontSize: '18px' },
    },
  },
});

// Option 1: Call with variant overrides
className={button({ intent: isPrimary ? 'primary' : undefined, size: isLarge ? 'large' : undefined })}

// Option 2: Destructure dimensioned variant classes and use cx()
const { base, 'intent-primary': intentPrimary, 'size-large': sizeLarge } = button;
className={cx(base, isPrimary && intentPrimary, isLarge && sizeLarge)}
```

When you need to combine classes from different sources (multiple style groups, external class strings, or conditional expressions), use the built-in `cx` utility:

```tsx
import { cx, styles } from 'typestyles';

const card = styles.class('card', { padding: '16px' });
const button = styles.component('button', {
  base: { padding: '8px' },
  primary: { backgroundColor: 'blue' },
});
const { primary } = button;

className={cx(card, button(), isPrimary && primary, isActive && 'active', externalClassName)}
```

## From CVA (Class Variance Authority)

`styles.component` maps closely to CVA's mental model:

- `variants`
- `compoundVariants`
- `defaultVariants`

### Basic mapping

**Before (CVA):**

```ts
import { cva } from 'class-variance-authority';

export const button = cva('inline-flex rounded font-medium', {
  variants: {
    intent: {
      primary: 'bg-blue-600 text-white',
      ghost: 'bg-transparent text-gray-900',
    },
    size: {
      sm: 'px-2 py-1 text-sm',
      lg: 'px-4 py-2 text-base',
    },
  },
  compoundVariants: [
    {
      intent: ['primary', 'ghost'],
      size: 'lg',
      class: 'uppercase',
    },
  ],
  defaultVariants: {
    intent: 'primary',
    size: 'sm',
  },
});
```

**After (typestyles):**

```ts
import { styles } from 'typestyles';

export const button = styles.component('button', {
  base: {
    display: 'inline-flex',
    borderRadius: '8px',
    fontWeight: 500,
  },
  variants: {
    intent: {
      primary: { backgroundColor: '#2563eb', color: 'white' },
      ghost: { backgroundColor: 'transparent', color: '#111827' },
    },
    size: {
      sm: { padding: '4px 8px', fontSize: '14px' },
      lg: { padding: '8px 16px', fontSize: '16px' },
    },
  },
  compoundVariants: [
    {
      variants: {
        intent: ['primary', 'ghost'],
        size: 'lg',
      },
      style: {
        textTransform: 'uppercase',
      },
    },
  ],
  defaultVariants: {
    intent: 'primary',
    size: 'sm',
  },
});

// Usage -- base is auto-applied, defaults kick in:
button(); // base + primary + sm
button({ intent: 'ghost' }); // base + ghost + sm
button({ size: 'lg' }); // base + primary + lg
```

### Key differences

1. CVA returns composed class strings from existing class tokens; typestyles generates and injects CSS from style objects.
2. CVA `class` in `compoundVariants` becomes typestyles `style`.
3. You can keep readable deterministic class output (`button-intent-primary`, etc.).
4. The return is both callable AND destructurable (CVA-style).

## From Stitches variants

### Variant migration

**Before (Stitches):**

```ts
import { styled } from '@stitches/react';

const Button = styled('button', {
  padding: '8px 12px',
  variants: {
    intent: {
      primary: { backgroundColor: 'dodgerblue', color: 'white' },
      ghost: { backgroundColor: 'transparent' },
    },
    outlined: {
      true: { border: '1px solid currentColor' },
    },
  },
  compoundVariants: [
    {
      intent: 'primary',
      outlined: true,
      css: { borderColor: 'blue' },
    },
  ],
  defaultVariants: {
    intent: 'primary',
  },
});
```

**After (typestyles):**

```ts
import { styles } from 'typestyles';

const button = styles.component('button', {
  base: {
    padding: '8px 12px',
  },
  variants: {
    intent: {
      primary: { backgroundColor: 'dodgerblue', color: 'white' },
      ghost: { backgroundColor: 'transparent' },
    },
    outlined: {
      true: { border: '1px solid currentColor' },
      false: { border: 'none' },
    },
  },
  compoundVariants: [
    {
      variants: {
        intent: 'primary',
        outlined: true,
      },
      style: {
        borderColor: 'blue',
      },
    },
  ],
  defaultVariants: {
    intent: 'primary',
    outlined: false,
  },
});
```

## From vanilla-extract recipes

### `recipe()` migration

**Before (vanilla-extract `recipe`):**

```ts
import { recipe } from '@vanilla-extract/recipes';

export const button = recipe({
  base: {
    borderRadius: 6,
  },
  variants: {
    tone: {
      neutral: { background: 'white' },
      brand: { background: 'blue', color: 'white' },
    },
  },
  defaultVariants: {
    tone: 'neutral',
  },
});
```

**After (typestyles):**

```ts
import { styles } from 'typestyles';

export const button = styles.component('button', {
  base: {
    borderRadius: '6px',
  },
  variants: {
    tone: {
      neutral: { backgroundColor: 'white' },
      brand: { backgroundColor: 'blue', color: 'white' },
    },
  },
  defaultVariants: {
    tone: 'neutral',
  },
});
```

Main trade-off:

- vanilla-extract is build-time only
- typestyles supports runtime + SSR today, with build-mode work in progress

## From Tailwind CSS

### Class-based to object-based

**Before (Tailwind):**

```tsx
function Button({ primary, children }) {
  return (
    <button
      className={`
        px-4 py-2 rounded
        font-medium transition-colors
        ${
          primary
            ? 'bg-blue-600 text-white hover:bg-blue-700'
            : 'bg-gray-200 text-gray-800 hover:bg-gray-300'
        }
      `}
    >
      {children}
    </button>
  );
}
```

**After (typestyles):**

```tsx
import { styles, tokens } from 'typestyles';

const color = tokens.create('color', {
  primary: '#0066ff',
  primaryHover: '#0052cc',
  secondary: '#6b7280',
  secondaryHover: '#4b5563',
});

const button = styles.component('button', {
  base: {
    padding: '8px 16px',
    borderRadius: '6px',
    fontWeight: 500,
    transition: 'background-color 150ms ease',
  },
  variants: {
    intent: {
      primary: {
        backgroundColor: color.primary,
        color: '#fff',
        '&:hover': { backgroundColor: color.primaryHover },
      },
      secondary: {
        backgroundColor: color.secondary,
        color: '#fff',
        '&:hover': { backgroundColor: color.secondaryHover },
      },
    },
  },
  defaultVariants: { intent: 'primary' },
});

function Button({ primary, children }) {
  return (
    <button className={button({ intent: primary ? 'primary' : 'secondary' })}>{children}</button>
  );
}
```

### Design tokens

Tailwind's configuration becomes typestyles tokens:

**Before (tailwind.config.js):**

```js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#0066ff',
        secondary: '#6b7280',
      },
      spacing: {
        4: '16px',
        6: '24px',
      },
    },
  },
};
```

**After (tokens.ts):**

```ts
import { tokens } from 'typestyles';

export const color = tokens.create('color', {
  primary: '#0066ff',
  secondary: '#6b7280',
});

export const space = tokens.create('space', {
  4: '16px',
  6: '24px',
});
```

### Gradual migration

You can use Tailwind and typestyles together during migration:

```tsx
import { styles, cx } from 'typestyles';

const card = styles.component('card', {
  base: {
    // New styles with typestyles
    boxShadow: '0 4px 6px rgba(0,0,0,0.1)',
  },
});

function Card({ children }) {
  return (
    <div className={cx(card(), 'p-4 bg-white rounded')}>
      {/*                       ^ Tailwind classes still work */}
      {children}
    </div>
  );
}
```

## From CSS Modules

### File organization

**Before (Button.module.css):**

```css
.button {
  padding: 8px 16px;
  border-radius: 6px;
}

.primary {
  background-color: #0066ff;
  color: white;
}

.secondary {
  background-color: #6b7280;
  color: white;
}
```

**Before (Button.tsx):**

```tsx
import styles from './Button.module.css';

function Button({ variant, children }) {
  return <button className={`${styles.button} ${styles[variant]}`}>{children}</button>;
}
```

**After (button.styles.ts):**

```ts
import { styles } from 'typestyles';

export const button = styles.component('button', {
  base: {
    padding: '8px 16px',
    borderRadius: '6px',
  },
  variants: {
    intent: {
      primary: { backgroundColor: '#0066ff', color: 'white' },
      secondary: { backgroundColor: '#6b7280', color: 'white' },
    },
  },
  defaultVariants: { intent: 'primary' },
});
```

**After (Button.tsx):**

```tsx
import { button } from './button.styles';

function Button({ variant, children }) {
  return <button className={button({ intent: variant })}>{children}</button>;
}
```

### Global styles

CSS Modules `:global` becomes typestyles without nesting:

**Before:**

```css
:global(.tooltip) {
  position: absolute;
}
```

**After:**

```ts
const tooltip = styles.component('tooltip', {
  base: {
    position: 'absolute',
  },
});

// Use: tooltip()
```

## From plain CSS

Migrating from plain CSS gives you type safety and better organization.

### Step-by-step

1. **Identify components** - Start with your most reused components (buttons, inputs, cards)

2. **Extract tokens** - Move hardcoded values to tokens:

   ```ts
   // Before: colors scattered in CSS files
   // After:
   export const color = tokens.create('color', {
     primary: '#0066ff',
     secondary: '#6b7280',
   });
   ```

3. **Create style definitions** - Convert CSS rules to typestyles:

   ```css
   /* Before */
   .btn {
     padding: 8px 16px;
     background: #0066ff;
   }
   .btn:hover {
     background: #0052cc;
   }
   ```

   ```ts
   // After
   const button = styles.component('button', {
     base: {
       padding: '8px 16px',
       backgroundColor: color.primary,
       '&:hover': {
         backgroundColor: color.primaryHover,
       },
     },
   });
   ```

4. **Update components** - Replace className strings with function calls

5. **Remove old CSS** - Once fully migrated, delete the CSS files

## From styles.create (previous typestyles API)

If you are migrating from the previous `styles.create()` API:

### Basic migration

**Before:**

```ts
const button = styles.create('button', {
  base: { padding: '8px 16px' },
  primary: { backgroundColor: '#0066ff' },
  large: { fontSize: '18px' },
});

// Usage:
button('base', 'primary', 'large');
button('base', isPrimary && 'primary');
```

**After (flat config):**

```ts
const button = styles.component('button', {
  base: { padding: '8px 16px' },
  primary: { backgroundColor: '#0066ff' },
  large: { fontSize: '18px' },
});

// Base is auto-applied. Destructure for direct access:
const { base, primary, large } = button;
cx(base, primary, large);

// Or use cx() with conditions:
cx(button(), isPrimary && primary);
```

**After (dimensioned config -- recommended for variants like intent/size):**

```ts
const button = styles.component('button', {
  base: { padding: '8px 16px' },
  variants: {
    intent: {
      primary: { backgroundColor: '#0066ff' },
    },
    size: {
      large: { fontSize: '18px' },
    },
  },
  defaultVariants: { intent: 'primary', size: 'large' },
});

// Base auto-applied, defaults kick in:
button();
button({ intent: 'primary', size: 'large' });
```

### Key changes

1. `styles.create()` is removed; use `styles.component()` instead.
2. Base styles are auto-applied when calling as a function -- no need to pass `'base'` explicitly.
3. The return is both callable AND destructurable.
4. Use `cx()` (exported from `'typestyles'`) for conditional class joining.
5. Varargs calling patterns like `button('base', 'primary')` are replaced by either the function call with variant object or destructuring.

## General migration tips

### 1. Start small

Don't migrate everything at once. Pick one component or one page and convert it. typestyles works alongside your existing styles during the transition.

### 2. Keep the same names

If you have `.button-primary` in CSS, create a `button` component with a `primary` variant. This makes the migration easier to follow.

### 3. Use tokens early

Define your design tokens before converting components. This ensures consistency and makes the component migration smoother.

### 4. Test class names

In your tests, you may need to update selectors:

**Before:**

```ts
expect(screen.getByRole('button')).toHaveClass('button-primary');
```

**After:**

```ts
expect(screen.getByRole('button')).toHaveClass('button-base', 'button-intent-primary');
```

### 5. DevTools familiarity

Your generated class names will be human-readable (`button-intent-primary`), so DevTools inspection stays familiar -- actually more readable than hashed class names from other CSS-in-JS libraries.

### 6. Bundle size check

After migration, your JavaScript bundle may be slightly smaller (no CSS parsing runtime) but you'll have a small runtime addition from typestyles itself. Overall size should be similar or smaller.

## Common patterns comparison

| Pattern            | styled-components            | Emotion                   | Tailwind            | typestyles                    |
| ------------------ | ---------------------------- | ------------------------- | ------------------- | ----------------------------- |
| **Basic styling**  | `styled.div`...`             | `css`...`                 | `className="p-4"`   | `styles.component()`          |
| **Variants**       | Props + template literals    | Props + template literals | Conditional strings | Variant object or destructure |
| **Pseudo-classes** | `&:hover` in template        | `&:hover` in template     | `hover:` prefix     | `&:hover` in object           |
| **Media queries**  | `@media` in template         | `@media` in template      | Responsive prefixes | `@media` in object            |
| **Theme values**   | `${props => props.theme...}` | `${theme...}`             | Config-based        | Token references              |
| **Dynamic values** | Template literals            | Template literals         | Arbitrary values    | Inline styles                 |
| **Class joining**  | `className` props            | `cx()` from emotion       | `clsx()`            | `cx()` from typestyles        |

## Migration CLI (MVP)

The `@typestyles/migrate` package includes an early CLI to help with static migrations from styled-components and Emotion.

### Scope in this first version

- Converts static tagged templates (`styled.*`, `styled(...)`, and `css\`...\``) into `styles.class(...)`or`styles.component(...)` when boolean prop variants are detected.
- Rewrites JSX usage for safely transformable styled components.
- Skips unsupported template interpolations (theme access, non-literal ternaries, etc.) and emits warnings instead of doing unsafe rewrites.
- Converts prop-based interpolations such as `` `${props => props.color}` `` to `createVar` + `assignVars`.
- Converts boolean prop ternaries such as `` `${props => props.primary ? '#0066ff' : '#6b7280'}` `` to `styles.component` variants.
- Supports destructured prop params (`` `${({ color }) => color}` ``) and `@media` blocks in static templates.

### Usage

```bash
pnpm --filter @typestyles/migrate typestyles-migrate src
```

By default the command is **dry-run** and prints patch output. Use `--write` to apply changes:

```bash
pnpm --filter @typestyles/migrate typestyles-migrate src --write
```

Useful options:

- `--include <glob>`: only process matching files (repeatable)
- `--exclude <glob>`: ignore matching files (repeatable)
- `--extensions .ts,.tsx`: customize scanned extensions
- `--report migration-report.json`: write a JSON summary and warning report

### Current limitations

- Theme access and other non-literal interpolations are not auto-migrated.
- Exported styled components are skipped to avoid accidental API-shape changes.
- Complex non-JSX references to styled component variables are skipped.

Prop-based interpolations (for example `` `${(props) => props.color}` `` or `` `${props => props.width}px` ``) are converted to `createVar` + `assignVars` at JSX call sites. Boolean prop ternaries become `styles.component` variants. Destructured prop params and `@media` blocks in static templates are supported.

## Troubleshooting migration issues

### Styles not applying

- Check that the namespace in `styles.component()` is unique
- Verify the component is being rendered (lazy injection means CSS only appears when used)
- Use DevTools to confirm class names are being applied

### Type errors

- Ensure you're importing from `'typestyles'`
- Check that TypeScript knows about the CSS property types (should work out of the box)
- For custom properties, use type assertions: `{ ['--custom' as string]: 'value' }`

### Performance concerns

- Don't create styles inside components (define them at module level)
- Use tokens instead of recreating values
- Static styles only -- dynamic values should use inline styles

If you hit any issues during migration, check the [troubleshooting guide](/docs/troubleshooting) or [open an issue](https://github.com/type-styles/typestyles/issues).

Source: https://typestyles.dev/docs/migration

---

# Open Props

Type-safe access to Open Props CSS custom properties


[Open Props](https://open-props.style/) is a collection of expertly crafted CSS design tokens. This package provides type-safe access to all Open Props tokens directly in TypeScript.

## Installation

```bash
npm install @typestyles/open-props
```

## Quick Start

```ts
import { styles } from 'typestyles';
import { sizes, radius, color, font } from '@typestyles/open-props';

const card = styles.component('card', {
  padding: sizes['4'],
  borderRadius: radius['3'],
  backgroundColor: color['gray-2'],
  fontFamily: font['sans'],
});
```

All tokens return `var(--token-name)` references that work seamlessly with typestyles.

## Available Tokens

### Sizes

Spacing and sizing tokens for layout:

```ts
sizes['0']; // var(--size-0)
sizes['1']; // var(--size-1)
sizes['2']; // var(--size-2)
sizes['3']; // var(--size-3)
sizes['4']; // var(--size-4)
// ... up to sizes['10']

// Fluid sizes
sizes['fluid-1']; // var(--size-fluid-1)
sizes['fluid-2']; // var(--size-fluid-2)
sizes['fluid-3']; // var(--size-fluid-3)

// Content sizes
sizes['content-1']; // 20ch
sizes['content-2']; // 45ch
sizes['content-3']; // 60ch
```

### Radius

Border radius tokens:

```ts
radius['0']; // var(--radius-0)
radius['1']; // var(--radius-1)
radius['2']; // var(--radius-2)
radius['3']; // var(--radius-3)
radius['4']; // var(--radius-4)
// ... up to radius['30']

// Special values
radius['round']; // 100%
radius['pill']; // 9999px
```

### Colors

19 color scales with 13 shades each (0-12):

```ts
// Access by color name and shade
color['gray-0']; // var(--color-gray-0)
color['gray-5']; // var(--color-gray-5)
color['gray-10']; // var(--color-gray-10)

color['indigo-0']; // var(--color-indigo-0)
color['blue-6']; // var(--color-blue-6)
color['red-4']; // var(--color-red-4)
```

Available color palettes:

- `gray`, `stone`, `red`, `pink`, `purple`, `violet`, `indigo`, `blue`
- `cyan`, `teal`, `green`, `lime`, `yellow`, `orange`
- `choco`, `brown`, `sand`, `camo`, `jungle`

### Typography

```ts
// Font sizes
fontSize['00']; // 0.5rem
fontSize['0']; // 0.75rem
fontSize['1']; // 1rem
fontSize['2']; // 1.1rem
// ... up to fontSize['8']

// Fluid font sizes
fontSize['fluid-0']; // clamp(0.75rem, 2vw, 1rem)
fontSize['fluid-1']; // clamp(1rem, 4vw, 1.5rem)
fontSize['fluid-2']; // clamp(1.5rem, 6vw, 2.5rem)
fontSize['fluid-3']; // clamp(2rem, 9vw, 3.5rem)

// Font weights
fontWeight['1']; // 100
fontWeight['4']; // 400
fontWeight['7']; // 700
fontWeight['9']; // 900

// Letter spacing
fontLetterspacing['0']; // -.05em
fontLetterspacing['4']; // .150em

// Line height
fontLineheight['00']; // .95
fontLineheight['1']; // 1.25
fontLineheight['3']; // 1.5

// Font families
font['sans']; // var(--font-sans)
font['serif']; // var(--font-serif)
font['mono']; // var(--font-mono)
font['system-ui']; // var(--font-system-ui)
font['humanist']; // var(--font-humanist)
// ... and more
```

### Shadows

```ts
shadow['1']; // var(--shadow-1)
shadow['2']; // var(--shadow-2)
shadow['3']; // var(--shadow-3)
shadow['4']; // var(--shadow-4)
shadow['5']; // var(--shadow-5)
shadow['6']; // var(--shadow-6)

// Inner shadows
shadow['inner-1']; // var(--shadow-inner-1)
shadow['inner-2']; // var(--shadow-inner-2)
shadow['inner-3']; // var(--shadow-inner-3)
shadow['inner-4']; // var(--shadow-inner-4)
shadow['inner-5']; // var(--shadow-inner-5)
```

### Gradients

30 handcrafted gradients:

```ts
gradient['1']; // var(--gradient-1)
gradient['10']; // var(--gradient-10)
gradient['20']; // var(--gradient-20)
gradient['30']; // var(--gradient-30)
```

### Easing

CSS easing functions:

```ts
easing['1']; // var(--ease-1)
easing['2']; // var(--ease-2)
easing['3']; // var(--ease-3)

// Directional
easing['in-1']; // var(--ease-in-1)
easing['out-1']; // var(--ease-out-1)
easing['in-out-1']; // var(--ease-in-out-1)

// Elastic
easing['elastic-out-1']; // var(--ease-elastic-out-1)
easing['elastic-in-1']; // var(--ease-elastic-in-1)

// Bounce
easing['bounce-1']; // var(--ease-bounce-1)
```

### Animations

Pre-defined animation names:

```ts
animation['fade-in']; // var(--animation-fade-in)
animation['slide-in-up']; // var(--animation-slide-in-up)
animation['scale-in']; // var(--animation-scale-in)
animation['spin']; // var(--animation-spin)
animation['pulse']; // var(--animation-pulse)
// ... and more
```

### Media Queries

Media query conditions for responsive design:

```ts
media['motion']; // var(--media-motion)
media['motionReduce']; // var(--media-motionReduce)
media['dark']; // var(--media-dark)
media['light']; // var(--media-light)
media['landscape']; // var(--media-landscape)
media['portrait']; // var(--media-portrait)

// Breakpoints
media['sm']; // var(--media-sm)  - 24rem
media['md']; // var(--media-md)  - 28rem
media['lg']; // var(--media-lg)  - 32rem
media['xl']; // var(--media-xl)  - 36rem
media['2xl']; // var(--media-2xl) - 42rem
// ... up to media['9xl']
```

### Other Tokens

```ts
// Aspect ratios
ratio['square']; // var(--ratio-square)
ratio['landscape']; // var(--ratio-landscape)
ratio['portrait']; // var(--ratio-portrait)
ratio['widescreen']; // var(--ratio-widescreen)
ratio['golden']; // var(--ratio-golden)

// Z-index layers
zIndex['1']; // var(--zindex-1)
zIndex['max']; // var(--zindex-max)

// Durations
duration['0']; // 0s
duration['1']; // 0.05s
duration['2']; // 0.1s
duration['3']; // 0.2s
duration['4']; // 0.4s
duration['5']; // 0.8s

// Border widths
borderSize['0']; // 0
borderSize['1']; // 1px
borderSize['2']; // 2px
// ... and more
```

### Brand Colors

Brand-specific colors for common services:

```ts
brand['facebook']; // var(--brand-facebook)
brand['twitter']; // var(--brand-twitter)
brand['instagram']; // var(--brand-instagram)
brand['youtube']; // var(--brand-youtube)
brand['spotify']; // var(--brand-spotify)
brand['discord']; // var(--brand-discord)
// ... and more
```

### Palette

Dynamic OKLCH palette for creating custom color schemes:

```ts
palette['1']; // var(--palette-1)
palette['8']; // var(--palette-8)
palette['16']; // var(--palette-16)
```

### Masks

SVG mask presets:

```ts
masksEdges['0']; // var(--masks-edge-0)
masksEdges['4']; // var(--masks-edge-4)

masksCornerCuts['1']; // var(--masks-corner-cuts-1)
masksCornerCuts['6']; // var(--masks-corner-cuts-6)
```

## Using with Styles

All tokens work seamlessly with typestyles:

```ts
import { styles } from 'typestyles';
import { sizes, radius, color, shadow, fontSize } from '@typestyles/open-props';

const button = styles.component('button', {
  display: 'inline-flex',
  alignItems: 'center',
  justifyContent: 'center',
  padding: `${sizes['2']} ${sizes['4']}`,
  borderRadius: radius['2'],
  fontSize: fontSize['2'],
  backgroundColor: color['blue-6'],
  color: color['blue-0'],
  boxShadow: shadow['2'],
  transition: 'all 200ms var(--ease-2)',

  '&:hover': {
    boxShadow: shadow['3'],
    backgroundColor: color['blue-5'],
  },
});
```

## Combining with Custom Tokens

You can mix Open Props with your own custom tokens:

```ts
import { tokens } from 'typestyles';
import { color, sizes } from '@typestyles/open-props';

// Your custom tokens
const brand = tokens.create('brand', {
  primary: '#ff6b6b',
  accent: '#4ecdc4',
});

// Use both together
const container = styles.component('container', {
  backgroundColor: brand.primary, // var(--brand-primary)
  padding: sizes['4'], // var(--size-4)
  borderColor: color['gray-3'], // var(--color-gray-3)
});
```

Source: https://typestyles.dev/docs/open-props

---

# Performance

Understanding and optimizing typestyles performance


TypeStyles is designed to be fast. This guide explains how it works under the hood and how to keep your apps running smoothly.

## How typestyles performs

### Runtime cost

TypeStyles operates at runtime with minimal overhead. The timings below are **rough orders of magnitude** and will vary by device and bundle.

| Operation                               | Cost (typical) | Frequency                 |
| --------------------------------------- | -------------- | ------------------------- |
| `styles.component()` / `styles.class()` | sub-ms         | Once per style definition |
| `button()` / `cx(...)`                  | very small     | Every render              |
| CSS injection                           | sub-ms         | Once per unique rule      |

**What this means:**

- Creating styles is fast and happens once at module load
- Applying styles (selector calls) is just string concatenation
- CSS is injected lazily and only once per unique style

### Memory usage

TypeStyles stores:

- **Style definitions**: One object per style namespace
- **CSS rules**: One string per variant
- **Token values**: One object per token namespace

Memory use scales with how many namespaces and rules you register; profile your own app if it becomes a concern.

## Bundle size

### Minified + gzipped sizes

Approximate sizes (measure your own bundle with your toolchain):

```
typestyles (core): on the order of a few KB gzipped
typestyles/server: additional small chunk for SSR helpers
@typestyles/vite: dev dependency only
```

### Comparison with alternatives

Other libraries’ numbers change frequently; compare using [bundlephobia](https://bundlephobia.com/) or your bundler’s analyzer. TypeStyles aims for a small runtime that injects plain CSS, versus larger runtimes that parse CSS in JS.

## Lazy injection

Styles aren't injected until they're used. This means:

```ts
// This is defined but no CSS is injected yet
const button = styles.component('button', {
  base: { padding: '8px' },
});

// CSS is only injected when the component renders
function App() {
  return <button className={button()}>Click</button>;
}
```

**Benefits:**

- Unused code paths don't add CSS weight
- Initial page load is faster
- Code-split styles work automatically

## Batched DOM updates

CSS rules are batched and inserted on the next frame:

```ts
// Multiple style definitions
const button = styles.component('button', { ... });
const card = styles.component('card', { ... });
const input = styles.component('input', { ... });

// All queued together, inserted in one operation
// Uses requestAnimationFrame or microtask for batching
```

**Benefits:**

- Fewer DOM manipulations
- Better performance during initial render
- Avoids forced synchronous layout

## Performance best practices

### 1. Define styles at module level

```ts
// ✅ Good - defined once
const button = styles.component('button', { ... });

function Button() {
  return <button className={button()} />;
}

// ❌ Bad - redefined on every render
function Button() {
  const button = styles.component('button', { ... }); // Don't do this!
  return <button className={button()} />;
}
```

Module-level definitions are evaluated once. Creating styles inside components causes unnecessary work on every render.

### 2. Avoid dynamic style values

```ts
import { styles, createVar, assignVars } from 'typestyles';

// ❌ Bad - creates styles for every possible value
const box = styles.component('box', {
  base: { width: props.width }, // Dynamic values in styles
});

// ✅ Good — use CSS custom properties for dynamic values (see Dynamic styling guide)
const widthVar = createVar('boxWidth');

const box = styles.component('box', {
  base: { display: 'block', width: widthVar },
});

function Box({ width }) {
  return (
    <div
      className={box()}
      style={assignVars({ [widthVar]: width })}
    />
  );
}
```

Dynamic values in style objects require JavaScript to run for every value change. Use [`createVar()` and `assignVars()`](/docs/dynamic-styles) to keep styles static and set values via CSS custom properties — or use raw inline styles for one-off properties.

### 3. Reuse token references

```ts
// ✅ Good - reference the token object
const color = tokens.create('color', {
  primary: '#0066ff',
});

const button = styles.component('button', {
  base: { color: color.primary },
});

const link = styles.component('link', {
  base: { color: color.primary }, // Same reference
});

// ❌ Bad - recreate values
const button = styles.component('button', {
  base: { color: '#0066ff' },
});

const link = styles.component('link', {
  base: { color: '#0066ff' }, // Duplicated value
});
```

Tokens ensure consistency and reduce memory usage.

### 4. Minimize variants

```ts
// ❌ Bad - too many variants for rarely used combinations
const button = styles.component('button', {
  base: { ... },
  primary: { ... },
  secondary: { ... },
  primarySmall: { ... },      // Redundant
  primaryLarge: { ... },      // Redundant
  secondarySmall: { ... },    // Redundant
  secondaryLarge: { ... },    // Redundant
});

// ✅ Good - compose smaller variants
const button = styles.component('button', {
  base: { ... },
  primary: { ... },
  secondary: { ... },
  small: { ... },
  large: { ... },
});

// Usage: button({ primary: true, small: true }) with flat keys, or cx(base, primary, small)
```

Composing variants reduces the number of CSS rules and makes your styles more flexible.

### 5. Code split your styles

```ts
// ✅ Good - load styles on demand
const HeavyComponent = lazy(() => import('./HeavyComponent'));

// HeavyComponent.styles.ts is only loaded when needed
```

Since styles are co-located with components, code splitting works automatically.

### 6. Avoid deeply nested selectors

```ts
// ❌ Bad - deep nesting increases selector complexity
const card = styles.component('card', {
  base: {
    '& .header': {
      '& .title': {
        '& span': { // Too deep!
          fontWeight: 'bold',
        },
      },
    },
  },
});

// ✅ Good - flatter structure, separate styles
const card = styles.component('card', {
  base: { ... },
});

const cardTitle = styles.component('card-title', {
  base: { fontWeight: 'bold' },
});
```

Deep nesting makes CSS harder to maintain and can impact selector matching performance.

## Benchmarks

For reproducible, CI-validated performance numbers — including CSS generation time, extracted file sizes across all naming modes, runtime injection latency, and SSR collection overhead — see the dedicated **[Benchmarks](/docs/benchmarks)** page.

The benchmark harness runs a 50-component reference design system and reports median/p95 timings. Regressions are caught automatically in CI.

## Measuring performance

### DevTools profiling

To measure typestyles performance in your app:

1. **Chrome DevTools Performance tab:**
   - Record a profile during initial render
   - Look for `insertRule` calls
   - Check total time spent in typestyles functions

2. **Lighthouse:**
   - Run performance audit
   - Check "Reduce unused CSS" (should be minimal with lazy injection)
   - Check "Minimize main-thread work"

3. **React DevTools Profiler:**
   - Profile component renders
   - Selector calls are fast and won't show up prominently

### Performance marks

Add marks to measure specific operations:

```ts
import { styles } from 'typestyles';

performance.mark('styles-component-start');
const button = styles.component('button', { ... });
performance.mark('styles-component-end');

performance.measure(
  'styles-component',
  'styles-component-start',
  'styles-component-end'
);

// Check in DevTools > Performance > Timings
```

## Memory leaks

### Potential issues

**1. Creating styles in event handlers:**

```ts
// ❌ Bad - creates styles on every click
function handleClick() {
  const button = styles.component('dynamic-button', { ... });
  // This accumulates in memory!
}
```

**2. Not cleaning up in long-lived apps:**

TypeStyles doesn't automatically clean up unused styles. In most apps this isn't a problem because:

- Style definitions are small
- CSS rules are reused
- Apps don't have infinite style variations

However, if you're dynamically creating thousands of styles:

```ts
// If you must create dynamic styles, consider cleanup
// (Not built into typestyles - implement at app level)
```

### Best practices to avoid leaks

1. Always define styles at module level
2. Don't create styles based on user input or dynamic data
3. Use [`createVar()` + `assignVars()`](/docs/dynamic-styles) for dynamic values on shared styles, or inline styles for one-offs
4. Limit the number of unique style variations

## Server-side rendering performance

### CSS extraction

SSR adds minimal overhead:

```ts
const { html, css } = collectStyles(() => renderToString(<App />));
```

The `collectStyles` call:

1. Captures all CSS to a string buffer (synchronous)
2. No DOM operations (server environment)
3. Returns CSS ready to embed in HTML

**Performance tips:**

- Cache SSR output when possible
- Use streaming SSR with care — see [Streaming SSR](/docs/ssr#streaming-ssr-express--node) (two renders for custom Node servers; Next.js App Router should use `TypestylesStylesheet` or build-time extraction instead)
- The collected CSS string is often modest, but measure it for your app

### CSS size

Reported CSS weight depends entirely on how many variants and utilities you register. In many apps it stays smaller than a hand-maintained global stylesheet because unused definitions are never hit.

These are usually smaller than equivalent CSS files because:

- Unused styles aren't included
- No vendor prefixes (handled by browser)
- Minimal whitespace in generated CSS

## Comparison with CSS files

### CSS files (traditional approach)

**Pros:**

- Zero runtime cost
- Cacheable separately
- Familiar tooling

**Cons:**

- No type safety
- Global namespace
- Harder to code split

### TypeStyles

**Pros:**

- Type safety
- Scoped styles (via class names)
- Automatic code splitting
- Easy theming
- Minimal runtime cost

**Cons:**

- Small runtime (see your bundle analyzer)
- Runtime CSS injection (one-time cost)
- Requires JavaScript

**When to use CSS files:**

- Static sites with no interactivity
- When you don't need type safety
- Design systems with stable CSS

**When to use typestyles:**

- Interactive applications
- When type safety matters
- Complex theming requirements
- Component libraries

## Optimizing for production

### Build-time considerations

TypeStyles works the same in development and production. There's no build step or optimization needed.

However, you can optimize your build:

1. **Tree shaking:** Unused typestyles code is removed by your bundler
2. **Minification:** CSS in strings is minified along with JS
3. **Code splitting:** Lazy-loaded components bring their styles automatically

### Production checklist

- [ ] No `styles.component()` / `styles.class()` definitions inside component bodies (define at module scope)
- [ ] No dynamic values in style objects
- [ ] Tokens reused across components
- [ ] Variants composed, not multiplied
- [ ] Test performance on low-end devices
- [ ] Monitor Core Web Vitals (CLS, LCP, INP)

## Monitoring real-world performance

### Web Vitals

Track these metrics in production:

- **LCP (Largest Contentful Paint):** Should be < 2.5s
  - TypeStyles doesn't block rendering (lazy injection)
- **INP (Interaction to Next Paint):** Should be < 200ms
  - Selector calls are very cheap (string concatenation)
- **CLS (Cumulative Layout Shift):** Should be < 0.1
  - Styles are available before paint (if using SSR)

### Real User Monitoring (RUM)

```ts
// Send metrics to analytics
import { getCLS, getFCP, getFID, getLCP, getTTFB } from 'web-vitals';

getCLS(console.log);
getFCP(console.log);
getFID(console.log);
getLCP(console.log);
getTTFB(console.log);
```

## Summary

TypeStyles performance characteristics:

- **Bundle size:** Small core; measure with your bundler
- **Runtime cost:** Minimal (string concatenation + batched DOM inserts)
- **Memory:** Scales with registered rules; usually modest
- **Rendering:** No blocking, lazy injection
- **SSR:** Style collection is synchronous around your render

To maintain good performance:

1. Define styles at module level
2. Use [`createVar()` + `assignVars()`](/docs/dynamic-styles) for dynamic values on shared styles
3. Compose variants instead of multiplying them
4. Let code splitting handle lazy loading
5. Profile if you have concerns

TypeStyles is designed to be fast enough for almost all applications while providing excellent developer experience.

Source: https://typestyles.dev/docs/performance

---

# Publishing a Package with TypeStyles

Safe defaults and collision-proof patterns for npm-published libraries using TypeStyles


If you publish a package that ships TypeStyles components, you need class-name
isolation out of the box. Two npm packages that both call
`styles.component('button', …)` without a `scopeId` will silently overwrite each
other's CSS in the consuming app.

This guide covers the setup that prevents that.

## The problem

The default `styles` and `tokens` exports use an empty `scopeId`. In semantic
mode (the default), `styles.component('button', …)` emits class names like
`button-base`. If a consumer installs two packages that both define a `'button'`
namespace, the later import wins — no error, no warning, just broken styles.

Even in `hashed` mode the hash is derived from the namespace and declarations.
Two packages with different styles but the same namespace will hash differently
and not collide — but two with identical declarations _will_.

`scopeId` solves this: it prefixes semantic names and mixes into hashes, making
collisions across packages structurally impossible.

## Recommended setup

Use `createTypeStyles` with your package name as `scopeId` and `hashed` mode:

```ts
// src/styles.ts
import { createTypeStyles } from 'typestyles';

export const { styles, tokens, global } = createTypeStyles({
  scopeId: '@acme/ui',
  mode: 'hashed',
});
```

Then import `styles` and `tokens` from this module throughout your package:

```ts
// src/components/Button.styles.ts
import { styles } from '../styles';

export const button = styles.component('button', {
  base: {
    display: 'inline-flex',
    alignItems: 'center',
    cursor: 'pointer',
  },
  variants: {
    intent: {
      primary: { backgroundColor: '#0066ff', color: '#fff' },
      secondary: { backgroundColor: '#e5e7eb', color: '#111' },
    },
  },
  defaultVariants: { intent: 'primary' },
});
```

Class names will look like `ts-button-1a2b3c` instead of `button-base` — unique
to your package by construction.

### Why `hashed` mode?

| Mode       | Output                                      | Collision risk                                                                                                |
| ---------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `semantic` | `acme-ui-button-base`                       | Low with `scopeId`, but still human-readable names that _could_ overlap if two packages choose the same scope |
| `hashed`   | `ts-button-1a2b3c`                          | Hash includes `scopeId` — collision requires identical scope, namespace, and declarations                     |
| `compact`  | `ts-1a2b3c`                                 | Same hash safety as `hashed`, shortest output                                                                 |
| `atomic`   | One class per declaration, deduped globally | Safe; declarations dedupe intentionally                                                                       |

For libraries, `hashed` is the sweet spot: hash-safe, but the namespace slug is
still visible in class names for debugging.

## Tokens

The same `createTypeStyles` call scopes your tokens too. Custom property names
include the scope:

```ts
const color = tokens.create('color', {
  primary: '#0066ff',
  surface: '#ffffff',
});
// --acme-ui-color-primary: #0066ff;
// --acme-ui-color-surface: #ffffff;
```

Consumers can theme your package by overriding these properties without any
risk of colliding with their own or other packages' tokens.

## ESLint enforcement

The `@typestyles/eslint-plugin` includes a `no-default-scope-in-package` rule
that flags direct use of the default `styles.class()` and `styles.component()`
exports — the ones without a `scopeId`. Enable it in your package's ESLint
config:

```js
// eslint.config.js
import typestyles from '@typestyles/eslint-plugin';

export default [
  typestyles.configs.package,
  // ... your other config
];
```

Or enable the rule individually:

```js
export default [
  typestyles.configs.recommended,
  {
    rules: {
      '@typestyles/no-default-scope-in-package': 'error',
    },
  },
];
```

The rule reports on `styles.class(…)` and `styles.component(…)` — the default
exports. Calls on custom bindings (e.g. `myStyles.class(…)` from
`createTypeStyles`) are fine, because the factory requires you to set a
`scopeId`.

## Checklist

Before publishing a package that uses TypeStyles:

1. **Create a scoped factory** — `createTypeStyles({ scopeId: pkg.name })` at
   the root of your styles
2. **Choose a non-semantic mode** — `hashed` (readable + safe) or `compact`
   (shortest output)
3. **Enable the ESLint rule** — `@typestyles/no-default-scope-in-package` to
   catch unscoped usage
4. **Export tokens explicitly** — so consumers can theme without reaching into
   internals
5. **Document your `scopeId`** — mention it in your README so consumers know
   which CSS custom properties to override

## Example

A complete library setup:

```ts
// src/styles.ts
import { createTypeStyles } from 'typestyles';

export const { styles, tokens, global } = createTypeStyles({
  scopeId: '@acme/ui',
  mode: 'hashed',
});
```

```ts
// src/tokens/color.ts
import { tokens } from '../styles';

export const color = tokens.create('color', {
  primary: '#0066ff',
  primaryHover: '#0052cc',
  surface: '#ffffff',
  text: '#111827',
});
```

```ts
// src/components/Button.styles.ts
import { styles } from '../styles';
import { color } from '../tokens/color';

export const button = styles.component('button', {
  base: {
    display: 'inline-flex',
    alignItems: 'center',
    justifyContent: 'center',
    border: 'none',
    cursor: 'pointer',
    fontWeight: 500,
  },
  variants: {
    intent: {
      primary: { backgroundColor: color.primary, color: '#fff' },
      secondary: { backgroundColor: 'transparent', border: '1px solid currentColor' },
    },
  },
  defaultVariants: { intent: 'primary' },
});
```

The consumer's app can install `@acme/ui` alongside any other TypeStyles package
with zero class-name or token collisions.

## Guard public class names

Publishable component libraries should treat semantic class names as semver surface
area. Opt in with:

1. Add `@typestyles/cli` as a dev dependency, then generate a snapshot:
   `typestyles snapshot --write` (writes
   `.typestyles-public-classnames.json` in the project root).
2. Enable `@typestyles/no-removed-public-classname` in ESLint (not part of the
   recommended preset):

```js
// eslint.config.js
import typestyles from '@typestyles/eslint-plugin';

export default [
  {
    plugins: { '@typestyles': typestyles },
    rules: {
      '@typestyles/no-removed-public-classname': [
        'error',
        { snapshotFile: '.typestyles-public-classnames.json' },
      ],
    },
  },
];
```

Adding new class names never fails the rule — only removals or renames do. After an
intentional breaking rename, bump semver and regenerate the snapshot with
`typestyles snapshot --write`.

The rule reports **once per ESLint run** (project-level), not at individual call
sites. Snapshot scanning is static and best-effort: string-literal namespaces only,
direct `styles.component()` / `styles.class()` calls, and a single inferred
`scopeId` when all `createStyles` configs match. See the
[`@typestyles/no-removed-public-classname` README](https://github.com/type-styles/typestyles/tree/main/packages/eslint-plugin#typestylesno-removed-public-classname-opt-in)
for full limits.

See [Theming Patterns — public semantic class names](/docs/theming-patterns#public-semantic-class-names)
and [Components — expose themeable properties as vars](/docs/components#expose-themeable-properties-as-vars).

Source: https://typestyles.dev/docs/publishing-packages

---

# React Integration

Using typestyles with React patterns and best practices


TypeStyles works seamlessly with React. This guide shows common patterns for integrating typestyles into React applications.

**Runnable examples:** [examples/vite-app](https://github.com/type-styles/typestyles/blob/main/examples/vite-app/README.md) (Vite + shared design system) and [examples/next-app](https://github.com/type-styles/typestyles/blob/main/examples/next-app/README.md) (App Router + build verification). Component library source: [examples/react-design-system](https://github.com/type-styles/typestyles/blob/main/examples/react-design-system/README.md).

## Basic component setup

### Simple button component

```tsx
// components/Button/Button.tsx
import { styles } from 'typestyles';
import { color, space } from '../../tokens';

const button = styles.component('button', {
  base: {
    display: 'inline-flex',
    alignItems: 'center',
    justifyContent: 'center',
    borderRadius: '6px',
    fontWeight: 500,
    cursor: 'pointer',
    border: 'none',
    transition: 'background-color 150ms ease',
  },
  variants: {
    intent: {
      primary: {
        backgroundColor: color.primary,
        color: '#fff',
        '&:hover': { backgroundColor: color.primaryHover },
      },
      secondary: {
        backgroundColor: color.secondary,
        color: '#fff',
        '&:hover': { backgroundColor: color.secondaryHover },
      },
    },
    size: {
      small: { padding: `${space.xs} ${space.sm}`, fontSize: '12px' },
      medium: { padding: `${space.sm} ${space.md}`, fontSize: '14px' },
      large: { padding: `${space.md} ${space.lg}`, fontSize: '16px' },
    },
    disabled: {
      on: { opacity: 0.5, cursor: 'not-allowed' },
      off: {},
    },
    loading: {
      on: { cursor: 'wait' },
      off: {},
    },
  },
  defaultVariants: {
    intent: 'primary',
    size: 'medium',
    disabled: 'off',
    loading: 'off',
  },
});

interface ButtonProps {
  variant?: 'primary' | 'secondary';
  size?: 'small' | 'medium' | 'large';
  disabled?: boolean;
  loading?: boolean;
  onClick?: () => void;
  children: React.ReactNode;
}

export function Button({
  variant = 'primary',
  size = 'medium',
  disabled = false,
  loading = false,
  onClick,
  children,
}: ButtonProps) {
  return (
    <button
      className={button({
        intent: variant,
        size,
        disabled: disabled ? 'on' : 'off',
        loading: loading ? 'on' : 'off',
      })}
      onClick={onClick}
      disabled={disabled || loading}
    >
      {loading ? 'Loading...' : children}
    </button>
  );
}
```

### Using the button

```tsx
// App.tsx
import { Button } from './components/Button';

function App() {
  return (
    <div>
      <Button variant="primary">Primary</Button>
      <Button variant="secondary">Secondary</Button>
      <Button size="large">Large</Button>
      <Button disabled>Disabled</Button>
      <Button loading>Loading</Button>
    </div>
  );
}
```

## Polymorphic components

### Creating a polymorphic Box component

```tsx
// components/Box/Box.tsx
import { cx, styles } from 'typestyles';
import { space } from '../../tokens';
import type { ElementType, ComponentPropsWithoutRef } from 'react';

const box = styles.component('box', {
  base: {},
  flex: { display: 'flex' },
  block: { display: 'block' },
  inline: { display: 'inline' },
  hidden: { display: 'none' },
  gap1: { gap: space[1] },
  gap2: { gap: space[2] },
  gap3: { gap: space[3] },
  gap4: { gap: space[4] },
  row: { flexDirection: 'row' },
  column: { flexDirection: 'column' },
  wrap: { flexWrap: 'wrap' },
  center: {
    justifyContent: 'center',
    alignItems: 'center',
  },
  p1: { padding: space[1] },
  p2: { padding: space[2] },
  p3: { padding: space[3] },
  p4: { padding: space[4] },
  m1: { margin: space[1] },
  m2: { margin: space[2] },
  m3: { margin: space[3] },
  m4: { margin: space[4] },
});

const {
  base,
  flex,
  block,
  inline,
  hidden,
  gap1,
  gap2,
  gap3,
  gap4,
  row,
  column,
  wrap: wrapClass,
  center: centerClass,
  p1,
  p2,
  p3,
  p4,
  m1,
  m2,
  m3,
  m4,
} = box;

type BoxProps<T extends ElementType = 'div'> = {
  as?: T;
  display?: 'flex' | 'block' | 'inline' | 'hidden';
  gap?: 1 | 2 | 3 | 4;
  direction?: 'row' | 'column';
  wrap?: boolean;
  center?: boolean;
  padding?: 1 | 2 | 3 | 4;
  margin?: 1 | 2 | 3 | 4;
} & Omit<ComponentPropsWithoutRef<T>, 'as'>;

export function Box<T extends ElementType = 'div'>({
  as,
  display,
  gap,
  direction,
  wrap,
  center,
  padding,
  margin,
  className,
  ...props
}: BoxProps<T>) {
  const Component = as || 'div';

  return (
    <Component
      className={cx(
        base,
        display === 'flex' && flex,
        display === 'block' && block,
        display === 'inline' && inline,
        display === 'hidden' && hidden,
        gap === 1 && gap1,
        gap === 2 && gap2,
        gap === 3 && gap3,
        gap === 4 && gap4,
        direction === 'row' && row,
        direction === 'column' && column,
        wrap && wrapClass,
        center && centerClass,
        padding === 1 && p1,
        padding === 2 && p2,
        padding === 3 && p3,
        padding === 4 && p4,
        margin === 1 && m1,
        margin === 2 && m2,
        margin === 3 && m3,
        margin === 4 && m4,
        className,
      )}
      {...props}
    />
  );
}
```

### Using Box as different elements

```tsx
// Using as a div (default)
<Box display="flex" gap={2} padding={3}>
  Content
</Box>

// Using as a button
<Box as="button" display="flex" center padding={2}>
  Click me
</Box>

// Using as a link
<Box as="a" href="/about" display="inline" padding={1}>
  About
</Box>

// Using with custom component
<Box as={CustomComponent} display="block" padding={4}>
  Content
</Box>
```

## Compound components

### Card component with multiple parts

```tsx
// components/Card/Card.tsx
import { cx, styles } from 'typestyles';
import { color, space } from '../../tokens';
import { createContext, useContext, type ReactNode } from 'react';

const card = styles.component('card', {
  base: {
    borderRadius: '8px',
    backgroundColor: color.surface,
    border: `1px solid ${color.border}`,
    overflow: 'hidden',
  },
  elevated: {
    boxShadow: '0 4px 6px rgba(0, 0, 0, 0.1)',
  },
  interactive: {
    cursor: 'pointer',
    transition: 'box-shadow 200ms ease',
    '&:hover': {
      boxShadow: '0 8px 12px rgba(0, 0, 0, 0.15)',
    },
  },
});

const { elevated, interactive } = card;

const cardHeader = styles.component('card-header', {
  base: {
    padding: `${space.md} ${space.lg}`,
    borderBottom: `1px solid ${color.border}`,
  },
});

const cardBody = styles.component('card-body', {
  base: {
    padding: space.lg,
  },
});

const cardFooter = styles.component('card-footer', {
  base: {
    padding: `${space.md} ${space.lg}`,
    borderTop: `1px solid ${color.border}`,
    backgroundColor: color.surfaceRaised,
  },
});

// Context for sharing state between compound components
interface CardContextValue {
  isInteractive: boolean;
}

const CardContext = createContext<CardContextValue>({ isInteractive: false });

// Main Card component
interface CardProps {
  elevated?: boolean;
  interactive?: boolean;
  onClick?: () => void;
  children: ReactNode;
}

export function Card({ elevated = false, interactive = false, onClick, children }: CardProps) {
  return (
    <CardContext.Provider value={{ isInteractive: interactive }}>
      <div
        className={cx(card(), elevated && elevated, interactive && interactive)}
        onClick={onClick}
        role={interactive ? 'button' : undefined}
        tabIndex={interactive ? 0 : undefined}
      >
        {children}
      </div>
    </CardContext.Provider>
  );
}

// Card.Header
Card.Header = function CardHeader({ children }: { children: ReactNode }) {
  return <div className={cardHeader()}>{children}</div>;
};

// Card.Body
Card.Body = function CardBody({ children }: { children: ReactNode }) {
  return <div className={cardBody()}>{children}</div>;
};

// Card.Footer
Card.Footer = function CardFooter({ children }: { children: ReactNode }) {
  return <div className={cardFooter()}>{children}</div>;
};
```

### Using compound components

```tsx
import { Card } from './components/Card';

function Example() {
  return (
    <Card elevated interactive onClick={() => console.log('Clicked!')}>
      <Card.Header>
        <h3>Card Title</h3>
      </Card.Header>
      <Card.Body>
        <p>Card content goes here...</p>
      </Card.Body>
      <Card.Footer>
        <button>Action</button>
      </Card.Footer>
    </Card>
  );
}
```

## Form components

### Input with validation states

```tsx
// components/Input/Input.tsx
import { cx, styles } from 'typestyles';
import { color, space } from '../../tokens';
import { forwardRef } from 'react';

const inputWrapper = styles.component('input-wrapper', {
  base: {
    display: 'flex',
    flexDirection: 'column',
    gap: space.sm,
  },
});

const inputLabel = styles.component('input-label', {
  base: {
    fontSize: '14px',
    fontWeight: 500,
    color: color.text,
  },
});

const inputHelper = styles.component('input-helper', {
  base: {
    fontSize: '12px',
    color: color.textMuted,
  },
  variants: {
    tone: {
      neutral: {},
      error: { color: color.danger },
      success: { color: color.success },
    },
  },
  defaultVariants: { tone: 'neutral' },
});

const input = styles.component('input', {
  base: {
    width: '100%',
    padding: `${space.sm} ${space.md}`,
    borderRadius: '6px',
    border: `1px solid ${color.border}`,
    fontSize: '14px',
    lineHeight: '1.5',
    backgroundColor: color.surface,
    color: color.text,
    transition: 'border-color 150ms ease, box-shadow 150ms ease',

    '&:focus': {
      outline: 'none',
      borderColor: color.primary,
      boxShadow: `0 0 0 3px ${color.alpha(color.primary, 0.1)}`,
    },

    '&::placeholder': {
      color: color.textMuted,
    },

    '&:disabled': {
      backgroundColor: color.surfaceSunken,
      cursor: 'not-allowed',
    },
  },
  variants: {
    validation: {
      none: {},
      error: {
        borderColor: color.danger,
        '&:focus': {
          borderColor: color.danger,
          boxShadow: `0 0 0 3px ${color.alpha(color.danger, 0.1)}`,
        },
      },
      success: {
        borderColor: color.success,
        '&:focus': {
          borderColor: color.success,
          boxShadow: `0 0 0 3px ${color.alpha(color.success, 0.1)}`,
        },
      },
    },
  },
  defaultVariants: { validation: 'none' },
});

interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
  error?: boolean;
  success?: boolean;
  label?: string;
  helperText?: string;
}

export const Input = forwardRef<HTMLInputElement, InputProps>(
  ({ error, success, label, helperText, className, ...props }, ref) => {
    const validation = error ? 'error' : success ? 'success' : 'none';
    const helperTone = error ? 'error' : success ? 'success' : 'neutral';

    return (
      <div className={inputWrapper()}>
        {label && <label className={inputLabel()}>{label}</label>}
        <input ref={ref} className={cx(input({ validation }), className)} {...props} />
        {helperText && <span className={inputHelper({ tone: helperTone })}>{helperText}</span>}
      </div>
    );
  },
);

Input.displayName = 'Input';
```

## Lists and grids

### Responsive grid component

```tsx
// components/Grid/Grid.tsx
import { styles } from 'typestyles';
import { space } from '../../tokens';
import type { ReactNode } from 'react';

const grid = styles.component('grid', {
  base: { display: 'grid' },
  variants: {
    columns: {
      1: { gridTemplateColumns: 'repeat(1, 1fr)' },
      2: { gridTemplateColumns: 'repeat(2, 1fr)' },
      3: { gridTemplateColumns: 'repeat(3, 1fr)' },
      4: { gridTemplateColumns: 'repeat(4, 1fr)' },
      6: { gridTemplateColumns: 'repeat(6, 1fr)' },
      12: { gridTemplateColumns: 'repeat(12, 1fr)' },
    },
    gap: {
      none: { gap: 0 },
      sm: { gap: space.sm },
      md: { gap: space.md },
      lg: { gap: space.lg },
    },
  },
  defaultVariants: { columns: 1, gap: 'md' },
});

interface GridProps {
  columns?: 1 | 2 | 3 | 4 | 6 | 12;
  gap?: 'none' | 'sm' | 'md' | 'lg';
  children: ReactNode;
}

export function Grid({ columns = 1, gap = 'md', children }: GridProps) {
  return <div className={grid({ columns, gap })}>{children}</div>;
}
```

## Context and theming

### Theme provider

```tsx
// components/ThemeProvider/ThemeProvider.tsx
import { createContext, useContext, useState, type ReactNode } from 'react';
import { darkTheme } from '../../tokens';

interface ThemeContextValue {
  isDark: boolean;
  toggle: () => void;
}

const ThemeContext = createContext<ThemeContextValue>({
  isDark: false,
  toggle: () => {},
});

export function useTheme() {
  return useContext(ThemeContext);
}

interface ThemeProviderProps {
  children: ReactNode;
}

export function ThemeProvider({ children }: ThemeProviderProps) {
  const [isDark, setIsDark] = useState(() => {
    if (typeof window === 'undefined') return false;
    return document.documentElement.classList.contains('theme-dark');
  });

  const toggle = () => {
    setIsDark(!isDark);
    if (!isDark) {
      document.documentElement.classList.add('theme-dark');
      localStorage.setItem('theme', 'dark');
    } else {
      document.documentElement.classList.remove('theme-dark');
      localStorage.setItem('theme', 'light');
    }
  };

  return (
    <ThemeContext.Provider value={{ isDark, toggle }}>
      <div className={isDark ? darkTheme : ''}>{children}</div>
    </ThemeContext.Provider>
  );
}
```

### Using the theme

```tsx
// components/ThemeToggle/ThemeToggle.tsx
import { useTheme } from '../ThemeProvider';
import { Button } from '../Button';

export function ThemeToggle() {
  const { isDark, toggle } = useTheme();

  return (
    <Button variant="secondary" onClick={toggle}>
      {isDark ? '🌞 Light mode' : '🌙 Dark mode'}
    </Button>
  );
}
```

## Performance optimization

### Memoized class names

For components that re-render frequently, you can memoize class name generation:

```tsx
import { useMemo } from 'react';
import { button } from './button.styles';

function OptimizedButton({
  variant,
  size,
  disabled,
}: {
  variant: 'primary' | 'secondary';
  size: 'small' | 'medium' | 'large';
  disabled: boolean;
}) {
  const className = useMemo(
    () =>
      button({
        intent: variant,
        size,
        disabled: disabled ? 'on' : 'off',
        loading: 'off',
      }),
    [variant, size, disabled],
  );

  return <button className={className}>Click</button>;
}
```

However, this is usually unnecessary since the selector function is already very fast.

### Code splitting

```tsx
// Lazy load heavy components with their styles
const HeavyChart = lazy(() => import('./components/HeavyChart'));

function App() {
  return (
    <Suspense fallback={<Loading />}>
      <HeavyChart />
    </Suspense>
  );
}
```

The styles in `HeavyChart` are only loaded when the component is imported.

## TypeScript best practices

### Export component prop types

```tsx
// components/Button/Button.tsx
export interface ButtonProps {
  variant?: 'primary' | 'secondary';
  size?: 'small' | 'medium' | 'large';
  // ...
}

export function Button(props: ButtonProps) {
  // ...
}
```

### Use strict prop types

```tsx
// Good - strict typing
type ButtonVariant = 'primary' | 'secondary' | 'ghost';

interface ButtonProps {
  variant?: ButtonVariant;
}

// Avoid - too permissive
interface ButtonProps {
  variant?: string; // Too broad
}
```

## Summary

Key patterns for React + typestyles:

1. **Define styles at module level** - Never in components
2. **Use TypeScript for prop types** - Get autocomplete and error checking
3. **Compose variants** - Build flexible component APIs
4. **Consider polymorphism** - `as` prop for versatile components
5. **Leverage context** - Share state between compound components
6. **Memoize if needed** - But profile first, selector functions are fast
7. **Code split naturally** - Styles follow component boundaries

Source: https://typestyles.dev/docs/react-integration

---

# Server-Side Rendering (SSR)

Render typestyles on the server for better performance and SEO


TypeStyles supports SSR out of the box. Instead of injecting styles into the DOM during rendering, you can collect all the CSS on the server and include it in the HTML response.

## Request-safe collection

Every `collectStyles()` call runs inside an **isolated sheet store**. On Node, that isolation uses `AsyncLocalStorage`, so concurrent SSR requests (multiple Express handlers, parallel Remix bots, overlapping `renderToString` passes) each get their own CSS buffer. CSS from request A never leaks into request B.

This matters for:

- **Concurrent HTTP handlers** — two users hitting your server at the same time
- **The two-pass streaming pattern** — a sync `renderToString` pass for CSS, then `renderToPipeableStream` for the response (see below)
- **Async renders** — `collectStyles(async () => …)` is supported; isolation holds for the full await

`collectStylesFromModules()` (build extraction) uses the same isolation. In the browser bundle, isolation is a no-op because there is only one document.

## Basic setup

Import `collectStyles` from `typestyles/server`:

```ts
import { collectStyles } from 'typestyles/server';
import { renderToString } from 'react-dom/server';

const { html, css } = collectStyles(() => renderToString(<App />));
```

The `collectStyles` function:

1. Starts collecting CSS instead of injecting it
2. Runs your render function
3. Returns the rendered HTML and collected CSS

## Full example

Here's a complete Express.js example:

```ts
import express from 'express';
import { collectStyles } from 'typestyles/server';
import { renderToString } from 'react-dom/server';
import { App } from './App';

const app = express();

app.get('/', (req, res) => {
  const { html, css } = collectStyles(() => renderToString(<App />));

  res.send(`
    <!DOCTYPE html>
    <html>
      <head>
        <meta charset="utf-8" />
        <title>My App</title>
        <style id="typestyles">${css}</style>
      </head>
      <body>
        <div id="root">${html}</div>
        <script src="/client.js"></script>
      </body>
    </html>
  `);
});

app.listen(3000);
```

## How it works

During SSR:

1. **Collection mode**: When `collectStyles()` wraps your render, TypeStyles switches to collection mode
2. **CSS capture**: All styles, tokens, themes, and keyframes are captured to a buffer instead of being injected into the DOM
3. **Single style tag**: The collected CSS is returned as a single string ready to embed in your HTML

On the client:

1. **Hydration detection**: TypeStyles looks for an existing `<style id="typestyles">` element
2. **Reuse**: If found, it reuses that element and avoids re-injecting the CSS
3. **Seamless transition**: No flicker or style recalculation during hydration

## React Server Components (Next.js App Router)

Next.js streams HTML by default. TypeStyles supports three patterns — pick based on whether you extract CSS at build time or collect at request time.

| Pattern                                              | When to use                                                                                                                                                        |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Build-time extraction**                            | Production apps — static `typestyles.css`, no runtime sheet. See [Zero-runtime extraction](/docs/zero-runtime).                                                    |
| **`getRegisteredCss()` in root layout**              | Runtime mode; styles are imported on the server before layout runs. Simplest request-time setup.                                                                   |
| **`TypestylesStylesheet` + `useServerInsertedHTML`** | Runtime mode; styles register during the **same streamed render** as `{children}`. Use when lazy boundaries or client-only imports would make Option B miss rules. |

### Build-time extraction (recommended for production)

Import the extracted stylesheet in your root layout. No `collectStyles()` per request — CSS is static:

```tsx
// app/layout.tsx
import './typestyles.css';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}
```

Configure extraction with `@typestyles/next/build` — see [Zero-runtime extraction](/docs/zero-runtime).

### Runtime: server layout + `getRegisteredCss`

When style modules load synchronously on the server, the registered sheet already contains everything the layout needs:

```tsx
// app/layout.tsx
import { getRegisteredCss } from '@typestyles/next';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  const css = getRegisteredCss();

  return (
    <html lang="en">
      <head>
        {css ? <style id="typestyles" dangerouslySetInnerHTML={{ __html: css }} /> : null}
      </head>
      <body>{children}</body>
    </html>
  );
}
```

This works in **Server Components** — no `'use client'` required. Request isolation from `AsyncLocalStorage` applies when you also call `collectStyles()` elsewhere in the same request (for example a streaming pre-pass).

### Runtime: streaming collection with `TypestylesStylesheet`

For styles that register during the streamed React tree (client boundaries, lazy imports, or `useServerInsertedHTML` timing), use the client component wrapper:

```tsx
// app/layout.tsx
import { TypestylesStylesheet } from '@typestyles/next/client';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <TypestylesStylesheet />
        {children}
      </body>
    </html>
  );
}
```

`TypestylesStylesheet` calls React's `useServerInsertedHTML` so CSS collected during the real SSR pass is injected into the streamed document — no separate `renderToString` pass and no CSS leakage between concurrent requests.

## Next.js

Install the official integration so App Router, `useServerInsertedHTML`, and server helpers stay aligned:

```bash
pnpm add @typestyles/next typestyles
```

See the [`@typestyles/next` package README](https://github.com/type-styles/typestyles/tree/main/packages/next) for build-time extraction (`withTypestylesExtract`) and Turbopack notes.

### App Router (runtime) — quick reference

The [RSC section above](#react-server-components-nextjs-app-router) has full examples and a decision table. The options below are the same patterns in brief:

```tsx
// app/layout.tsx
import { getRegisteredCss } from '@typestyles/next';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  const css = getRegisteredCss();

  return (
    <html lang="en">
      <head>
        {css ? <style id="typestyles" dangerouslySetInnerHTML={{ __html: css }} /> : null}
      </head>
      <body>{children}</body>
    </html>
  );
}
```

**Option B — `TypestylesStylesheet` (client):** uses Next’s `useServerInsertedHTML` so CSS collected during the real SSR pass is injected into the streamed document. Prefer this when you rely on the same render tree as `{children}` (for example lazy boundaries or patterns where Option A would miss rules).

```tsx
// app/layout.tsx
import { TypestylesStylesheet } from '@typestyles/next/client';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <TypestylesStylesheet />
        {children}
      </body>
    </html>
  );
}
```

**Subtree-only CSS (advanced):** `collectStylesFromComponent` / `getTypestylesMetadata` from `@typestyles/next/server` run `renderToString` on a specific element and return the CSS registered during that pass. Each call is request-isolated via `collectStyles()`.

### Pages Router

Wrap the page tree with `TypestylesStylesheet` so collection lines up with what Next renders:

```tsx
// pages/_app.tsx
import { TypestylesStylesheet } from '@typestyles/next';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <TypestylesStylesheet>
      <Component {...pageProps} />
    </TypestylesStylesheet>
  );
}
```

Custom `pages/_document.tsx` with `collectStyles(() => ctx.renderPage())` is fragile because `renderPage` can be asynchronous and does not return a React element. Prefer the `_app` pattern above unless you maintain a custom synchronous pipeline.

## Remix

`renderToString(<RemixServer />)` usually returns your `app/root.tsx` tree, which in the default template already includes `<head>…</head>`. Collect CSS from that same render, inject the tag before `</head>`, then prefix `<!DOCTYPE html>` if the string does not already include it:

```tsx
// app/entry.server.tsx
import type { EntryContext } from '@remix-run/node';
import { RemixServer } from '@remix-run/react';
import { renderToString } from 'react-dom/server';
import { collectStyles, injectStylesIntoHtml } from 'typestyles/server';

export default function handleRequest(
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
  remixContext: EntryContext,
) {
  const { html, css } = collectStyles(() =>
    renderToString(<RemixServer context={remixContext} url={request.url} />),
  );

  responseHeaders.set('Content-Type', 'text/html; charset=utf-8');

  if (!html.includes('</head>')) {
    throw new Error(
      'typestyles SSR: expected </head> in Remix output. Ensure app/root.tsx renders a <head> (default Remix template does).',
    );
  }

  let documentHtml = injectStylesIntoHtml(html, css);
  if (!documentHtml.trimStart().toLowerCase().startsWith('<!doctype')) {
    documentHtml = `<!DOCTYPE html>${documentHtml}`;
  }

  return new Response(documentHtml, { status: responseStatusCode, headers: responseHeaders });
}
```

**Streaming:** the stock Remix `entry.server.tsx` uses `renderToPipeableStream` and never builds a single HTML string, so the pattern above targets **synchronous** document responses (for example the bot path in Remix’s default entry, or a custom non-streaming entry). To keep streaming, you still need a strategy for CSS: a prior `collectStyles(() => renderToString(<RemixServer … />))` pass, build-time CSS extraction, or adapting the streaming pipeline—see [Remix streaming](https://remix.run/docs/en/main/guides/streaming) and [entry.server](https://remix.run/docs/en/main/file-conventions/entry.server).

## Streaming SSR (Express / Node)

React's `renderToPipeableStream` does not give you a complete HTML string up front, so TypeStyles cannot collect CSS from the stream itself. The supported pattern is **two renders**:

1. **CSS pass** — `collectStyles(() => renderToString(<App />))` inside the same request (isolated via `AsyncLocalStorage`)
2. **Stream pass** — `renderToPipeableStream(<App />)` for the response body

Open your HTML shell (including the style tag) **before** `pipe(res)`, then finish the document when React signals the stream is done. Exact callbacks depend on Suspense boundaries — see [React `renderToPipeableStream`](https://react.dev/reference/react-dom/server/renderToPipeableStream).

Helpers from `typestyles/server` reduce boilerplate:

- `typestylesStyleHtml(css)` — `<style id="typestyles">…</style>`
- `streamingDocumentShell(css)` — doctype + `<head>` with charset and styles + `<body>`
- `injectStylesIntoHtml(html, css)` — insert before `</head>` (Remix-style full documents)
- `TYPESTYLES_STYLE_ID` — the stable `"typestyles"` id (must match client hydration)

```tsx
import { renderToString, renderToPipeableStream } from 'react-dom/server';
import type { Response } from 'express';
import { collectStyles, streamingDocumentShell } from 'typestyles/server';

app.get('/', (req, res: Response) => {
  const { css } = collectStyles(() => renderToString(<App />));

  const { pipe } = renderToPipeableStream(<App />, {
    onShellReady() {
      res.statusCode = 200;
      res.setHeader('Content-Type', 'text/html; charset=utf-8');
      res.write(streamingDocumentShell(css));
      pipe(res);
    },
    onShellError(error) {
      res.statusCode = 500;
      console.error(error);
      res.end();
    },
  });
});
```

If your shell opens wrappers around `<App />`, add the matching closing tags in the appropriate callback (`onAllReady` when streaming deferred content, or follow the full pattern in the React docs) so you never write to `res` after it has ended.

**Next.js App Router** already streams — prefer `TypestylesStylesheet` or build-time extraction instead of manual two-pass rendering.

## Important considerations

### Style deduplication

TypeStyles automatically deduplicates CSS during collection. If multiple components use the same style variant, it's only included once in the output.

### Critical CSS

By default, `getRegisteredCss()` returns every rule registered in the process. For large apps, prefer **build-time per-route CSS** on Next.js: `buildTypestylesForNext` writes route-scoped stylesheets and a v2 manifest (see [zero-runtime — Next.js](/docs/zero-runtime#nextjs) and [per-route critical CSS](#per-route-critical-css-nextjs) below).

### Per-route critical CSS (Next.js)

`buildTypestylesForNext` traces each App Router `page` plus its layout chain, extracts CSS for modules that import `typestyles`, and writes self-contained files under `app/_typestyles/routes/` (default). The manifest maps route paths to those files:

```json
{
  "version": 2,
  "css": "app/typestyles.css",
  "routes": {
    "/": { "css": "app/_typestyles/routes/index.css" },
    "/about": { "css": "app/_typestyles/routes/about.css" }
  }
}
```

At request time, read the pre-built CSS for the current route instead of the full global sheet:

```tsx
// app/about/layout.tsx (Server Component)
import { getRouteCss } from '@typestyles/next/server';

export default function AboutLayout({ children }: { children: React.ReactNode }) {
  const css = getRouteCss('/about', { root: process.cwd() });
  return (
    <>
      <style id="typestyles-about" dangerouslySetInnerHTML={{ __html: css }} />
      {children}
    </>
  );
}
```

Keep your convention entry minimal (tokens, reset, fonts). Route-specific `styles.*` modules imported only from that page's tree stay out of other routes' CSS files. Pass `routeCss: false` to `buildTypestylesForNext` when you only want the monolithic `typestyles.css`.

### Client-side hydration

Always use the same `id="typestyles"` on both server and client. Import `TYPESTYLES_STYLE_ID` from `typestyles/server` or use `typestylesStyleHtml()` so the id stays consistent:

```html
<!-- Server -->
<style id="typestyles">
  ${css}
</style>

<!-- Client finds and reuses this element -->
```

If the IDs don't match, you'll get duplicate styles.

### Memory and cleanup

`collectStyles()` manages collection state automatically. After the render function completes and CSS is collected, the internal state is reset. You don't need to manually clean up.

## Troubleshooting

### Styles missing in SSR output

Make sure you're actually rendering components that use typestyles during the `collectStyles()` call. If styles are defined but the component isn't rendered, no CSS will be generated.

### Styles appearing twice

This happens when the client can't find the server-rendered style tag:

1. Check that the `id` is exactly `"typestyles"`
2. Make sure the style tag is present in the initial HTML
3. Verify no ad blockers or CSP are interfering

### Flash of unstyled content (FOUC)

If you see FOUC:

1. Ensure styles are in the `<head>`, not the body
2. Check that the CSS string isn't empty
3. Verify that `collectStyles()` wraps the actual component render, not just an empty render

Source: https://typestyles.dev/docs/ssr

---

# Style Dictionary & W3C tokens

Use TypeStyles alongside the W3C Design Tokens Community Group (DTCG) format and Style Dictionary for a design-tool-to-code pipeline


TypeStyles already stores your design tokens as **real CSS custom properties** from TypeScript. The **W3C Design Tokens Community Group** (DTCG) format and **[Style Dictionary](https://styledictionary.com/)** solve a different problem: **exchange**. They let designers, documentation sites, iOS / Android apps, and your TypeStyles app all agree on one canonical token set.

This guide shows how to combine them without losing the parts that make TypeStyles pleasant: typed access, scoped variables, and no required compiler.

## Who does what

- **W3C DTCG** — A **JSON file format**. Each token is an object with `$value`, `$type`, optional `$description`, and `$extensions`. Groups nest tokens; aliases reference other tokens with `"{color.brand.500}"`. This is the interchange layer consumed by Figma plugins, Tokens Studio, documentation tools, etc.
- **Style Dictionary** — A **build-time transformer**. It reads DTCG (or its own legacy format), resolves aliases, and emits CSS, SCSS, JS/TS, iOS, Android, and custom formats. It does **not** run at runtime.
- **TypeStyles** — The **runtime** that turns TypeScript objects into `var(--…)` custom properties, typed style APIs, themes, and SSR output. It does not read DTCG directly — it consumes plain TS values.

The natural split: **DTCG is your source of truth**, **Style Dictionary generates a TypeScript module**, and **TypeStyles consumes that module** through `tokens.create(…)`.

```
Figma / Tokens Studio → tokens.json (DTCG) → Style Dictionary → tokens/generated.ts → tokens.create(...)
                                                                                         │
                                                                                         ▼
                                                                             real CSS custom properties
```

## A minimal DTCG file

```json
// tokens/core.tokens.json
{
  "color": {
    "brand": {
      "500": { "$value": "#3b82f6", "$type": "color" },
      "600": { "$value": "#2563eb", "$type": "color" }
    },
    "text": {
      "default": { "$value": "{color.brand.600}", "$type": "color" }
    }
  },
  "space": {
    "sm": { "$value": "0.5rem", "$type": "dimension" },
    "md": { "$value": "1rem", "$type": "dimension" },
    "lg": { "$value": "1.5rem", "$type": "dimension" }
  }
}
```

The aliased value `{color.brand.600}` is resolved by Style Dictionary at build time — by the time your TS module runs, `color.text.default` is already `#2563eb`.

## Workflow A — DTCG → Style Dictionary → TypeStyles

### 1. Install and configure


```bash
pnpm add -D style-dictionary
# npm: npm install -D style-dictionary
# yarn: yarn add -D style-dictionary
```


Style Dictionary v4 parses the DTCG format natively. Create a config that emits **a flat TypeScript primitives module** — no CSS output, because TypeStyles owns CSS generation.

```js
// sd.config.mjs
import StyleDictionary from 'style-dictionary';

const sd = new StyleDictionary({
  source: ['tokens/**/*.tokens.json'],
  platforms: {
    ts: {
      transformGroup: 'js',
      buildPath: 'src/tokens/generated/',
      files: [{ destination: 'primitives.ts', format: 'typestyles/primitives' }],
    },
  },
});

StyleDictionary.registerFormat({
  name: 'typestyles/primitives',
  format: ({ dictionary }) => {
    const groups = {};
    for (const token of dictionary.allTokens) {
      const [group, ...rest] = token.path;
      const key = rest.join('-'); // e.g. "brand-500"
      (groups[group] ??= {})[key] = token.$value ?? token.value;
    }
    const body = Object.entries(groups)
      .map(([name, vals]) => `export const ${name} = ${JSON.stringify(vals, null, 2)} as const;`)
      .join('\n\n');
    return `// AUTO-GENERATED. Do not edit by hand.\n${body}\n`;
  },
});

await sd.buildAllPlatforms();
```

Run it whenever tokens change:

```bash
node sd.config.mjs
```

This produces `src/tokens/generated/primitives.ts`:

```ts
// AUTO-GENERATED. Do not edit by hand.
export const color = {
  'brand-500': '#3b82f6',
  'brand-600': '#2563eb',
  'text-default': '#2563eb',
} as const;

export const space = {
  sm: '0.5rem',
  md: '1rem',
  lg: '1.5rem',
} as const;
```

### 2. Feed primitives into `tokens.create`

Keep the DTCG-derived primitives **separate** from your semantic token layer, so the code stays readable and refactors at the semantic level do not touch design-tool output.

```ts
// src/tokens/index.ts
import { createTypeStyles } from 'typestyles';
import { color as corePrimitives, space as corePrimitivesSpace } from './generated/primitives';

export const { styles, tokens } = createTypeStyles({ scopeId: 'app' });

export const color = tokens.create('color', {
  brand: corePrimitives['brand-500'],
  brandHover: corePrimitives['brand-600'],
  text: corePrimitives['text-default'],
});

export const space = tokens.create('space', corePrimitivesSpace);
```

`color.brand` is now `var(--app-color-brand)`; the underlying hex came from DTCG.

### 3. Wire it into your build

Add a prebuild script so the generated file is fresh before type-checking:

```json
// package.json
{
  "scripts": {
    "tokens:build": "node sd.config.mjs",
    "dev": "pnpm tokens:build && vite",
    "build": "pnpm tokens:build && vite build"
  }
}
```

Commit `src/tokens/generated/*.ts` so tooling (editors, CI, TypeScript) always sees the resolved values.

## Workflow B — TypeStyles → DTCG (export to design tools)

Going the other direction — making your TS primitives discoverable to Figma plugins or Tokens Studio — takes a few lines of plain JavaScript. Export the **primitive objects** (not `tokens.create` outputs — those are `var(...)` strings) and walk them into DTCG shape:

```ts
// scripts/export-dtcg.ts
import { writeFile } from 'node:fs/promises';
import { primitiveColors } from '../src/tokens/primitives/colors';
import { primitiveSpacing } from '../src/tokens/primitives/spacing';

function toDtcg(values: Record<string, unknown>, $type: string): Record<string, unknown> {
  const out: Record<string, unknown> = {};
  for (const [key, value] of Object.entries(values)) {
    if (value && typeof value === 'object') {
      out[key] = toDtcg(value as Record<string, unknown>, $type);
    } else {
      out[key] = { $value: value, $type };
    }
  }
  return out;
}

const bundle = {
  color: toDtcg(primitiveColors, 'color'),
  space: toDtcg(primitiveSpacing, 'dimension'),
};

await writeFile('dist/tokens.json', JSON.stringify(bundle, null, 2));
```

This emits a valid DTCG file your design team can import. The **primitives** are the right export boundary — semantic tokens like `color.text` are often aliases whose meaning depends on theme and are better expressed as DTCG aliases rather than baked values.

## Themes and color modes across the boundary

DTCG does not yet standardise multi-mode tokens. Two pragmatic patterns work well with TypeStyles:

### Pattern 1 — one file per mode

```
tokens/
  core.tokens.json          # mode-agnostic (spacing, radii, typography)
  color.light.tokens.json   # color/* in light mode
  color.dark.tokens.json    # color/* in dark mode
```

Run Style Dictionary twice (one platform per mode) into separate primitive modules, then feed each into a `tokens.createTheme`:

```ts
import { color as lightColor } from './generated/light';
import { color as darkColor } from './generated/dark';

export const darkTheme = tokens.createTheme('dark', {
  base: { color: { brand: darkColor['brand-500'], text: darkColor['text-default'] } },
});
```

### Pattern 2 — DTCG `$extensions` for modes

Tokens Studio and many design tools carry mode variants under `$extensions`. Read them in a **custom Style Dictionary format** and emit one primitive module per mode. From TypeStyles' perspective it looks exactly like Pattern 1 — `tokens.createTheme` plus `tokens.colorMode.*` presets (see [Tokens](/docs/tokens) and [Theming patterns](/docs/theming-patterns)).

## Aliases: build-time vs runtime

You have two valid strategies for DTCG aliases like `{color.brand.500}`:

- **Resolve at build time** — the default Style Dictionary behavior. `color.text.default` lands in your TS module as a literal hex. **Pro:** simple, zero runtime cost. **Con:** the link between semantic and primitive is lost in code.
- **Preserve as `var(...)` at runtime** — emit the primitives with `tokens.create`, then reference them from a second `tokens.create` call. Aliases resolve via the CSS cascade. **Pro:** themes can swap primitives without rebuilding. **Con:** requires two token namespaces.

```ts
const primitive = tokens.create('primitive-color', { brand500: '#3b82f6' });
const semantic = tokens.create('color', {
  brand: primitive.brand500, // var(--app-primitive-color-brand500)
});
```

The second strategy is worth the extra layer when you ship **multiple brand themes** that share the same semantic contract.

## Matching external CSS names

When Style Dictionary (or another tool) already defines your canonical `--*` naming convention, mirror it with **`nameTemplate`** on `tokens.create` so TypeStyles refs point at the same names TypeStyles injects — without duplicating `:root` blocks from SD.

```ts
const tokens = createTokens({ scopeId: 'acme' });

// SD might emit --color-brand-500; match that pattern (drop scope from var names if globals are unscoped).
const color = tokens.create('color', generatedPalette, {
  nameTemplate: ({ segments }) => `--color-${segments.join('-')}`,
});

const semantic = tokens.create(
  'color-semantic',
  {
    text: { primary: color.brand[500] },
  },
  {
    nameTemplate: ({ path }) => `--ds-color-${path}`,
  },
);
```

**Defaults are still recommended** for new apps — custom names are for interop and migration, not aesthetics. **`scopeId`** on `createTokens` / `createStyles` still scopes theme **classes** even when var names match globals.

## Gotchas

- **Do not let Style Dictionary emit the CSS.** If both Style Dictionary and TypeStyles ship `:root { --color-brand: … }`, you get duplicate declarations and scoping conflicts. Keep TypeStyles as the single source of CSS.
- **Do not pass `tokens.create` output to DTCG exporters.** It contains `var(--…)` strings, not literal values. Export the underlying primitive objects instead.
- **Type your generated module.** Keep `as const` in the Style Dictionary format so TypeStyles' inference preserves literal key types. Missing keys become type errors at the `tokens.create` call site.
- **Version the JSON, generate the TS.** Treat `tokens/*.tokens.json` as the reviewed artefact and `src/tokens/generated/**` as derived output. Some teams commit both; some gitignore the generated TS and rebuild in CI. Either works — pick one and stick with it.
- **Scope still matters.** Style Dictionary does not know about TypeStyles' `scopeId`. When you change `scopeId`, only the TypeStyles side updates — the DTCG file is unchanged because it describes design intent, not emission naming.

## Related

- [Tokens](/docs/tokens) — the `tokens.create`, `createTokens`, and `createTheme` APIs.
- [Design system](/docs/design-system) — three-layer token architecture (primitives / semantic / component) that this pipeline slots into.
- [Theming patterns](/docs/theming-patterns) — multi-theme and color-mode strategies.
- [Open Props](/docs/open-props) — pre-built primitive tokens, an alternative starting point when you do not have a design-tool source of truth yet.

Source: https://typestyles.dev/docs/style-dictionary

---

# Styles

Create and compose style variants with styles.component


The `styles` API lets you define named style variants and compose them at the call site.

`styles.component()` is the unified API for creating component styles. It supports both **flat** configs (simple named variants) and **dimensioned** configs (typed `variants`, `compoundVariants`, `defaultVariants`). For the full dimensioned variant API, see [Components](/docs/components).

## How TypeStyles runs

1. **Registration** — When your module loads, definitions are registered. Nothing paints until a class is actually used.
2. **First use** — The first time a returned class name is applied, TypeStyles injects the rules into a managed `<style>` tag (lazy injection, batched for performance).
3. **Stable names** — Class strings are deterministic from your namespace and variant keys, which keeps SSR and tests predictable when [collection APIs](/docs/ssr) wrap your render.
4. **Production** — You can keep this model, or switch to extracted CSS and a no-op runtime via the [zero-runtime](/docs/zero-runtime) path when you are ready.

## Choosing an API

| You want to…                                                            | Use                                     | Why                                                                                         |
| ----------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------- |
| Style a component with base + flat toggles (`elevated`, `compact`)      | `styles.component` (flat config)        | Small surface area; base applies automatically when you call the function.                  |
| Build typed variant axes (`intent`, `size`) with defaults and compounds | `styles.component` (dimensioned config) | First-class variant model: `variants`, `compoundVariants`, `defaultVariants`.               |
| One reusable class from a single style object                           | `styles.class`                          | One class string, no variant machinery.                                                     |
| Merge several style groups                                              | `styles.compose`                        | Reuse groups without repeating objects.                                                     |
| Join class names conditionally                                          | `cx()` from `'typestyles'`              | Filters falsy values; pairs well with props from parents (not tied to a `styles` instance). |

**Practical default:** one [`createTypeStyles`](/docs/api-reference#createtypestyles-options) module per app or package; then use `styles.component` for UI components, `styles.class` for one-off utilities, and `import { cx } from 'typestyles'` when you merge external `className` strings.

## Creating styles (flat config)

Call `styles.component(namespace, definitions)` with a unique namespace and an object of variant names to style definitions:

```ts
import { styles } from 'typestyles';

const card = styles.component('card', {
  base: {
    padding: '16px',
    borderRadius: '8px',
    border: '1px solid #e5e5e5',
  },
  elevated: {
    boxShadow: '0 4px 12px rgba(0,0,0,0.1)',
  },
});
```

The returned object is both **callable** and **destructurable**:

```ts
// Call as a function -- base styles are always auto-applied:
card(); // "card-base" (flat variants are opt-in via the call or `defaultVariants`)

// Destructure for direct class access:
const { base, elevated } = card;
// base => "card-base"
// elevated => "card-elevated"
```

Class names are deterministic: `card-base`, `card-elevated`.

To use **hashed** or **hash-only** class strings instead (for example in a design system package), see [Class naming](/docs/class-naming).

## Creating styles (dimensioned config)

For typed variant dimensions, use the full variant config:

```ts
const button = styles.component('button', {
  base: { padding: '8px 16px', borderRadius: '6px' },
  variants: {
    intent: {
      primary: { backgroundColor: '#0066ff', color: '#fff' },
      secondary: { backgroundColor: '#6b7280', color: '#fff' },
    },
    size: {
      sm: { fontSize: '14px' },
      lg: { fontSize: '18px' },
    },
  },
  defaultVariants: { intent: 'primary', size: 'sm' },
});

// Base styles auto-applied; pass variant overrides:
button(); // base + primary + sm
button({ intent: 'secondary' }); // base + secondary + sm
button({ size: 'lg' }); // base + primary + lg
```

See [Components](/docs/components) for `compoundVariants`, boolean variants, and multipart `slots`.

## Selectors

Use the `&` prefix for pseudo-classes and nested selectors, just like in CSS:

```ts
const button = styles.component('button', {
  base: {
    padding: '8px 16px',
    '&:hover': { opacity: 0.9 },
    '&:disabled': { opacity: 0.5, cursor: 'not-allowed' },
  },
});
```

### Data and ARIA attribute selectors

Attribute selectors work with `&`-prefixed nested selectors, including all CSS attribute selector operators:

```ts
const trigger = styles.component('trigger', {
  base: {
    // exact match
    '&[data-state="open"]': { opacity: 1 },

    // starts with / ends with / contains
    '&[data-side^="top"]': { marginTop: '4px' },
    '&[data-size$="-lg"]': { padding: '12px' },
    '&[data-name*="admin"]': { fontWeight: 700 },

    // whitespace-separated token / language-style match
    '&[data-flags~="selected"]': { borderStyle: 'solid' },
    '&[lang|="en"]': { fontFamily: 'system-ui' },

    // accessibility state hooks
    '&[aria-expanded="true"]': { backgroundColor: '#1d4ed8' },
    '&[aria-selected="true"]': { color: 'white' },
  },
});
```

### `:has()`, `:is()`, and `:where()` helpers

For grouped or low-specificity pseudos, use **`styles.has`**, **`styles.is`**, and **`styles.where`** (or import `has`, `is`, `where` from `typestyles`). They mirror the ergonomics of **`styles.container()`** for container queries: small builders that return `&`-prefixed keys and infer **literal** templates from your arguments, so you can mix them with ordinary properties without `as CSSProperties`.

```ts
const nav = styles.class('nav', {
  display: 'flex',
  [styles.where('.nav')]: { gap: '8px' },
  [styles.has('.active')]: { borderBottom: '2px solid blue' },
  [styles.is(':hover', ':focus-visible')]: { outline: '2px solid dodgerblue' },
});
```

`:where()` is especially useful for design-system defaults (zero specificity). See [Custom selectors & at-rules](/docs/custom-at-rules) for TypeScript notes and more examples.

## Composing styles

Use `styles.compose()` to combine multiple component style functions or class strings:

```ts
const base = styles.component('base', {
  base: { padding: '8px', borderRadius: '4px' },
});

const primary = styles.component('primary', {
  base: { backgroundColor: '#0066ff', color: 'white' },
});

const button = styles.compose(base, primary);
```

See the [Style Composition](/docs/compose) guide for more details.

## Joining classes with cx()

Use the built-in `cx()` utility to conditionally join class strings:

```ts
import { styles, cx } from 'typestyles';

const card = styles.component('card', {
  base: { padding: '16px' },
  elevated: { boxShadow: '0 4px 8px rgba(0,0,0,0.1)' },
});

const { base, elevated } = card;

// Conditionally join classes:
cx(base, isElevated && elevated, customClassName);
```

## Utility shortcuts

Define reusable shorthand properties (similar to Stitches `utils`) on your **`createStyles`** instance so class names, scope, and layers stay on one API — no global registration.

```ts
import { createStyles } from 'typestyles';

const styles = createStyles({
  scopeId: 'my-app',
  utils: {
    marginX: (value: string | number) => ({
      marginLeft: value,
      marginRight: value,
    }),
    paddingY: (value: string | number) => ({
      paddingTop: value,
      paddingBottom: value,
    }),
    size: (value: string | number) => ({
      width: value,
      height: value,
    }),
  },
});

const avatar = styles.class('avatar', {
  size: 40,
  marginX: 8,
});

const button = styles.component('button', {
  base: { paddingY: 8 },
  compact: { paddingY: 4 },
});
```

The returned API is utility-aware (`class`, `hashClass`, `component` accept your utility keys). If you already use the default `import { styles } from 'typestyles'`, you can instead call **`styles.withUtils({ … })`** to get the same behavior from a second object — prefer **`createStyles({ utils })`** when you want a single exported styles instance.

Utility keys are fully typed from your utility definitions and can be mixed with normal CSS properties.

## Composing with tokens

Use token references (e.g. from `tokens.create()`) in your style values. They compile to `var(--name-key)` and work with themes.

If you are migrating from CVA, Stitches, or vanilla-extract recipes, see [Migration Guide](/docs/migration).

Source: https://typestyles.dev/docs/styles

---

# Testing

Testing strategies for typestyles components


Testing components styled with typestyles is straightforward. Since typestyles generates regular CSS class names, you can use standard testing tools without any special setup.

## Unit testing components

### Basic component testing

Since typestyles returns regular class names, test your components the same way you'd test any React/Vue/Svelte component:

```tsx
// Button.tsx
import type { ReactNode } from 'react';
import { styles } from 'typestyles';

const button = styles.component('button', {
  base: { padding: '8px 16px' },
  primary: { backgroundColor: '#0066ff' },
  large: { fontSize: '18px' },
});

export function Button({
  variant,
  size,
  children,
}: {
  variant?: 'primary';
  size?: 'large';
  children: ReactNode;
}) {
  return (
    <button
      className={button({
        primary: variant === 'primary',
        large: size === 'large',
      })}
    >
      {children}
    </button>
  );
}

// Button.test.tsx
import { render, screen } from '@testing-library/react';
import { Button } from './Button';

describe('Button', () => {
  it('renders with base class', () => {
    render(<Button>Click me</Button>);
    const button = screen.getByRole('button');

    expect(button).toHaveClass('button-base');
  });

  it('applies variant classes', () => {
    render(<Button variant="primary">Click me</Button>);
    const button = screen.getByRole('button');

    expect(button).toHaveClass('button-base');
    expect(button).toHaveClass('button-primary');
  });

  it('applies multiple variants', () => {
    render(
      <Button variant="primary" size="large">
        Click me
      </Button>,
    );
    const button = screen.getByRole('button');

    expect(button).toHaveClass('button-base');
    expect(button).toHaveClass('button-primary');
    expect(button).toHaveClass('button-large');
  });
});
```

### Testing conditional classes

When variants are applied conditionally, test both states:

```tsx
import { cx } from 'typestyles';

const btn = styles.component('button', {
  base: { padding: '8px 16px' },
  loading: { cursor: 'wait', opacity: 0.8 },
});
const { loading: loadingClass } = btn;

function Button({ isLoading, children }: { isLoading?: boolean; children: React.ReactNode }) {
  return (
    <button className={cx(btn(), isLoading && loadingClass)}>
      {isLoading ? 'Loading...' : children}
    </button>
  );
}

// Button.test.tsx
it('applies loading state', () => {
  render(<Button isLoading>Click me</Button>);
  const button = screen.getByRole('button');

  expect(button).toHaveClass('button-base');
  expect(button).toHaveClass('button-loading');
});

it('does not apply loading class when not loading', () => {
  render(<Button>Click me</Button>);
  const button = screen.getByRole('button');

  expect(button).toHaveClass('button-base');
  expect(button).not.toHaveClass('button-loading');
});
```

## Testing with React Testing Library

### Prefer semantic queries

Instead of testing for specific class names, test for accessible properties when possible:

```tsx
// ✅ Good - test user-visible behavior
it('disables button when loading', () => {
  render(<Button isLoading>Click me</Button>);
  const button = screen.getByRole('button');

  expect(button).toBeDisabled();
  expect(button).toHaveTextContent('Loading...');
});

// Alternative if you need to verify styles
it('has loading styles', () => {
  render(<Button isLoading>Click me</Button>);
  const button = screen.getByRole('button');

  // Verify the class is applied (CSS testing is separate)
  expect(button).toHaveClass('button-loading');
});
```

### Testing style snapshots

If you want to ensure class names don't change unexpectedly, use snapshots:

```tsx
it('matches snapshot', () => {
  const { container } = render(<Button variant="primary">Click me</Button>);
  expect(container.firstChild).toMatchSnapshot();
  // Snapshot: <button class="button-base button-primary">Click me</button>
});
```

### Class naming mode

If you use [hashed, compact, or atomic class naming](/docs/class-naming) in tests, prefer a dedicated **`createStyles({ mode, prefix, scopeId })`** instance in that file so naming options never leak. The default **`import { styles } from 'typestyles'`** is a single shared instance. Always call **`reset()`** (from `typestyles`) in `beforeEach` when tests inject CSS. Assertions that depend on exact class strings may need snapshots or prefix-based checks when `mode` is not `semantic`.

## CSS testing strategies

### Don't test CSS output directly

CSS output is an implementation detail. Test user-facing behavior instead:

```tsx
// ❌ Avoid - testing implementation details
it('has padding of 8px', () => {
  const { container } = render(<Button>Click</Button>);
  expect(container.firstChild).toHaveStyle({ padding: '8px 16px' });
});

// ✅ Better - test that the component renders correctly
it('renders as a button', () => {
  render(<Button>Click</Button>);
  expect(screen.getByRole('button')).toBeInTheDocument();
});

// ✅ Or use visual regression tests for styles
```

### Visual regression testing

For CSS testing, use visual regression tools like Chromatic, Percy, or Storybook's visual testing:

```tsx
// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  component: Button,
};

export default meta;

type Story = StoryObj<typeof Button>;

export const Primary: Story = {
  args: {
    variant: 'primary',
    children: 'Primary Button',
  },
};

export const Secondary: Story = {
  args: {
    variant: 'secondary',
    children: 'Secondary Button',
  },
};

export const Large: Story = {
  args: {
    variant: 'primary',
    size: 'large',
    children: 'Large Button',
  },
};
```

Run visual regression tests in CI to catch unintended style changes.

## Testing tokens

### Token value tests

Test that tokens generate the expected CSS:

```ts
// tokens.test.ts
import { tokens } from 'typestyles';

describe('tokens', () => {
  it('creates color token references', () => {
    const color = tokens.create('color', {
      primary: '#0066ff',
    });

    expect(color.primary).toBe('var(--color-primary)');
  });

  it('creates spacing token references', () => {
    const space = tokens.create('space', {
      sm: '8px',
      md: '16px',
    });

    expect(space.sm).toBe('var(--space-sm)');
    expect(space.md).toBe('var(--space-md)');
  });
});
```

Note: Testing the actual CSS output requires DOM access (see integration tests below).

## Integration testing

### Testing with actual styles

For integration tests, you might want to verify that styles are actually applied:

```tsx
// setupTests.ts or jest.setup.ts
// Ensure styles are injected in test environment
import 'typestyles';

// For JSDOM-based tests, you may need to mock or stub some CSS APIs
Object.defineProperty(window, 'CSS', { value: { supports: () => true } });
```

### Testing computed styles

```tsx
import { render } from '@testing-library/react';
import { Button } from './Button';

it('applies correct background color', () => {
  const { getByRole } = render(<Button variant="primary">Click</Button>);
  const button = getByRole('button');

  // Get computed styles
  const styles = window.getComputedStyle(button);

  // Note: This may not work in JSDOM as it doesn't fully compute CSS
  // Better to use visual regression or E2E tests for this
  expect(styles.backgroundColor).toBeDefined();
});
```

⚠️ **Note**: JSDOM doesn't fully support CSS custom properties or computed styles. For testing actual styles, use a real browser with Playwright or Cypress.

## E2E testing

### Playwright example

```ts
// button.spec.ts
import { test, expect } from '@playwright/test';

test('button has correct styles', async ({ page }) => {
  await page.goto('/button-demo');

  const button = page.locator('button').first();

  // Check computed styles
  await expect(button).toHaveCSS('padding', '8px 16px');
  await expect(button).toHaveCSS('background-color', 'rgb(0, 102, 255)');

  // Check class names
  await expect(button).toHaveClass(/button-base/);
  await expect(button).toHaveClass(/button-primary/);
});

test('button hover state', async ({ page }) => {
  await page.goto('/button-demo');

  const button = page.locator('button').first();

  // Hover and check styles
  await button.hover();
  await expect(button).toHaveCSS('background-color', 'rgb(0, 82, 204)');
});
```

### Cypress example

```ts
// button.cy.ts
describe('Button', () => {
  it('has correct classes', () => {
    cy.visit('/button-demo');

    cy.get('button')
      .first()
      .should('have.class', 'button-base')
      .and('have.class', 'button-primary');
  });

  it('has correct computed styles', () => {
    cy.visit('/button-demo');

    cy.get('button')
      .first()
      .should('have.css', 'padding', '8px 16px')
      .and('have.css', 'background-color', 'rgb(0, 102, 255)');
  });
});
```

## Testing SSR

When testing SSR-rendered components, ensure styles are collected:

```tsx
// ssr.test.ts
import { collectStyles } from 'typestyles/server';
import { renderToString } from 'react-dom/server';
import { App } from './App';

describe('SSR', () => {
  it('collects styles during render', () => {
    const { html, css } = collectStyles(() => renderToString(<App />));

    // HTML should contain class names
    expect(html).toContain('button-base');

    // CSS should contain the styles
    expect(css).toContain('.button-base');
    expect(css).toContain('padding');
  });

  it('includes CSS custom properties', () => {
    const { css } = collectStyles(() => renderToString(<App />));

    expect(css).toContain('--color-primary');
    expect(css).toContain('--space-md');
  });
});
```

## Snapshot testing class names

For library authors or design systems, you might want to snapshot the generated class names:

```ts
// styles.test.ts
import { styles } from 'typestyles';

describe('Button styles', () => {
  it('generates consistent class names', () => {
    const button = styles.component('button', {
      base: { padding: '8px' },
      primary: { color: 'blue' },
    });

    expect(button()).toMatchInlineSnapshot(`"button-base"`);
    expect(button({ primary: true })).toMatchInlineSnapshot(`"button-base button-primary"`);
  });
});
```

## Mocking typestyles (if needed)

In rare cases, you might want to mock typestyles:

```ts
// __mocks__/typestyles.ts
export const styles = {
  component: (namespace: string, definitions: Record<string, unknown>) => {
    const keys = Object.keys(definitions);
    return (options?: Record<string, boolean>) => {
      const parts = [`${namespace}-base`];
      if (options) {
        for (const [k, on] of Object.entries(options)) {
          if (on && k !== 'base') parts.push(`${namespace}-${k}`);
        }
      }
      return parts.join(' ');
    };
  },
};

export const tokens = {
  create: (namespace: string, values: Record<string, string>) => {
    return Object.fromEntries(
      Object.keys(values).map((key) => [key, `var(--${namespace}-${key})`]),
    );
  },
  use: (namespace: string) => {
    return new Proxy(
      {},
      {
        get: (_, key: string) => `var(--${namespace}-${key})`,
      },
    );
  },
  createTheme: (name: string) => `theme-${name}`,
};
```

However, mocking is usually unnecessary since typestyles has minimal side effects in tests.

## Best practices

1. **Test behavior, not classes** - Focus on what users see and interact with
2. **Use semantic queries** - `getByRole`, `getByText` over class name selectors
3. **Visual regression for styles** - Use Chromatic/Percy for CSS testing
4. **E2E for computed styles** - Use Playwright/Cypress to test actual rendering
5. **Snapshot sparingly** - Only snapshot class names if you're maintaining a library
6. **Don't test implementation** - CSS output is an implementation detail

## Example test suite

Here's a complete example test suite for a component:

```tsx
// Card.test.tsx
import { render, screen } from '@testing-library/react';
import { Card } from './Card';

describe('Card', () => {
  it('renders children', () => {
    render(<Card>Content</Card>);
    expect(screen.getByText('Content')).toBeInTheDocument();
  });

  it('has correct ARIA role', () => {
    render(<Card>Content</Card>);
    expect(screen.getByRole('article')).toBeInTheDocument();
  });

  it('applies elevated variant', () => {
    render(<Card elevated>Content</Card>);
    const card = screen.getByRole('article');

    expect(card).toHaveClass('card-base');
    expect(card).toHaveClass('card-elevated');
  });

  it('applies interactive variant', () => {
    render(<Card interactive>Content</Card>);
    const card = screen.getByRole('article');

    expect(card).toHaveClass('card-base');
    expect(card).toHaveClass('card-interactive');
  });

  it('can combine variants', () => {
    render(
      <Card elevated interactive>
        Content
      </Card>,
    );
    const card = screen.getByRole('article');

    expect(card).toHaveClass('card-base');
    expect(card).toHaveClass('card-elevated');
    expect(card).toHaveClass('card-interactive');
  });

  it('matches snapshot', () => {
    const { container } = render(
      <Card elevated>
        <h2>Title</h2>
        <p>Description</p>
      </Card>,
    );
    expect(container.firstChild).toMatchSnapshot();
  });
});
```

This approach tests:

- Component rendering
- Accessibility
- Variant application
- Combination of variants
- Snapshot for unexpected changes

All without worrying about the actual CSS values, which should be tested via visual regression or E2E tests.

Source: https://typestyles.dev/docs/testing

---

# Theming Patterns

Light/dark mode, multi-brand theming, and advanced theme strategies


TypeStyles uses CSS custom properties for theming, making it flexible and powerful. This guide covers common theming patterns.

## Theme surfaces

`tokens.createTheme(name, config)` registers a **theme surface**: a stable class name `theme-{name}` whose custom properties override token values for that subtree.

- **`config.base`** — Token overrides always applied on `.theme-{name}` (your usual light / brand default).
- **`config.modes`** — Manual list of `{ id, overrides, when }` layers (see `tokens.when.*`).
- **`config.colorMode`** — Preset mode layers from `tokens.colorMode.*` (media-only dark, attribute toggles, light/dark/system, etc.).

Provide **`modes` or `colorMode`, not both.** Overrides use the same nested shape as `tokens.create` (nested keys become hyphenated `--namespace-key` variables).

The return value is a **`ThemeSurface`**: `{ className, name }`, with `String(surface)` and template literals resolving to `className`. In React, pass **`surface.className`** (or `String(surface)`) to `className` props.

For **dark only when the OS prefers dark**, use `tokens.createDarkMode(name, overrides)` or `colorMode: tokens.colorMode.mediaOnly({ dark: … })`.

See [Tokens](/docs/tokens) for the core API. The `THEME.md` file at the repository root documents conditions, presets, and cascade ordering in full.

Try a minimal light/dark surface in the live example below — toggle **Dark** to see the theme class, token overrides, and emitted CSS change together.


> Interactive demo: https://typestyles.dev/docs/theming-patterns

```ts
export const color = tokens.create('color', {
  text: '#111827',
  surface: '#ffffff',
  primary: '#0066ff',
});

export const darkTheme = tokens.createTheme('dark', {
  base: {
    color: {
      text: '#e0e0e0',
      surface: '#1a1a2e',
      primary: '#66b3ff',
    },
  },
});

// Apply theme-dark on a wrapper:
<div className={darkTheme.className}>
  <div className={card.base}>Themed surface</div>
</div>
```


## Generating a theme from one accent color

The design-system example ships `createColorTheme` — a semantic mapper that turns a single
hex accent into light and dark `DesignColorValues` using the core `typestyles/color-scale`
math (OKLCH ramps + WCAG contrast checks).

```ts
import { createColorTheme } from '@examples/design-system';

const { light, dark } = createColorTheme({
  accent: '#0064E0',
  neutralStyle: 'neutral', // 'neutral' | 'cool' | 'warm'
  contrast: 'standard', // 'standard' | 'high'
});

// Plug into createDesignTheme / tokens.createTheme mode overrides:
export const brandTheme = createDesignTheme({
  name: 'brand',
  light: { color: light, syntax: defaultLightSyntaxValues },
  dark: { color: dark, syntax: defaultDarkSyntaxValues },
});
```

**Layering:** `typestyles/color-scale` is vocabulary-agnostic (`parseColor`, `generateRamp`,
`contrastRatio`). `createColorTheme` lives in `examples/design-system` and decides which ramp
step maps to `background.app`, `accent.default`, and so on. Derived tokens such as
`accent.subtle` and `text.disabled` still come from the existing `color-mix()` machinery in
`tokens/index.ts` — `createColorTheme` only fills the base semantic slots.

**Core API** (usable without the design-system vocabulary):

```ts
import { parseColor, generateRamp, contrastRatio } from 'typestyles/color-scale';

const accent = parseColor('#0064E0'); // { l, c, h } in OKLCH units
const ramp = generateRamp({ hue: accent.h, chroma: accent.c }); // 10-step OKLCH strings
contrastRatio('#000', '#fff'); // 21
```

Dev-mode contrast warnings (`console.warn`) fire when generated pairs fall below 4.5:1
(standard) or 7:1 (high); they never throw.

## Generating type, motion, and radius scales

The `typestyles/token-scale` subpath does for numeric ladders what `color-scale` does for
color: it turns 2-3 numbers into a whole scale, so a theme author writes `{ base, ratio }`
instead of hand-picking every step. Like `color-scale`, it is vocabulary-agnostic — the
generators return plain numbers and never see names like `fontSize`, `radius`, or `fast`;
zipping your own step names onto the output is your design system's concern.

Reach for each generator by shape:

- **`generateGeometricScale`** — multiplicative ladders where each step is a ratio of the
  last (font sizes, spacing that grows faster at the top). `steps` are signed integer
  offsets from the base: `value(offset) = base * ratio ** offset`.
- **`generateLinearScale`** — even, grid-based ladders (radius steps on a 4px grid).
  `steps` are ordinal multipliers: `value(step) = base * step * multiplier`.
- **`expandDurationBand`** — one motion anchor expanded into a `{ min, base, max }` band:
  `min = base * ratio`, `max = base / ratio`, rounded to the nearest 5ms by default so
  computed bands look hand-picked instead of visibly computed (no `93.75ms`).

```ts
import {
  generateGeometricScale,
  generateLinearScale,
  expandDurationBand,
} from 'typestyles/token-scale';

// Font-size ladder: major third anchored at 16 (offset 0 is always exactly base).
generateGeometricScale({ base: 16, ratio: 1.25, steps: [-2, -1, 0, 1, 2, 3, 4] });
// → [10, 13, 16, 20, 25, 31, 39]

// Radius ladder on a 4px grid.
generateLinearScale({ base: 4, multiplier: 1, steps: [1, 2, 3, 4, 6] });
// → [4, 8, 12, 16, 24]

// One duration anchor → a min/base/max band (call once per named anchor).
expandDurationBand({ base: 150, ratio: 0.625 });
// → { min: 95, base: 150, max: 240 }
```

Outputs are unitless — append `px`/`rem`/`ms` yourself when zipping the numbers into your
own `tokens.create()` calls. All three generators round to whole numbers by default; the
array generators accept a `round` override and `expandDurationBand` accepts a `roundTo`
granularity for callers that want different precision.

## Basic light/dark mode

### Creating a theme

```ts
// tokens.ts
import { tokens } from 'typestyles';

// Define your base tokens
export const color = tokens.create('color', {
  // Light mode defaults
  text: '#111827',
  textMuted: '#6b7280',
  surface: '#ffffff',
  surfaceRaised: '#f9fafb',
  surfaceSunken: '#f3f4f6',
  border: '#e5e7eb',
  primary: '#0066ff',
  primaryHover: '#0052cc',
});

// Create dark theme override (class theme-dark)
export const darkTheme = tokens.createTheme('dark', {
  base: {
    color: {
      text: '#e0e0e0',
      textMuted: '#9ca3af',
      surface: '#1a1a2e',
      surfaceRaised: '#25253e',
      surfaceSunken: '#16162a',
      border: '#3f3f5c',
      primary: '#66b3ff',
      primaryHover: '#3399ff',
    },
  },
});
```

### Applying the theme

```tsx
// App.tsx
import { darkTheme } from './tokens';

function App() {
  const [isDark, setIsDark] = useState(false);

  return (
    <div className={isDark ? darkTheme.className : ''}>
      <button onClick={() => setIsDark(!isDark)}>Toggle theme</button>
      <PageContent />
    </div>
  );
}
```

### Persisting theme preference

```tsx
// hooks/useTheme.ts
import { useState, useEffect } from 'react';
import { darkTheme } from '../tokens';

export function useTheme() {
  const [isDark, setIsDark] = useState(() => {
    // Check localStorage first
    if (typeof window !== 'undefined') {
      const stored = localStorage.getItem('theme');
      if (stored) return stored === 'dark';

      // Fall back to system preference
      return window.matchMedia('(prefers-color-scheme: dark)').matches;
    }
    return false;
  });

  useEffect(() => {
    localStorage.setItem('theme', isDark ? 'dark' : 'light');

    // Optional: Update meta theme-color
    const meta = document.querySelector('meta[name="theme-color"]');
    if (meta) {
      meta.setAttribute('content', isDark ? '#1a1a2e' : '#ffffff');
    }
  }, [isDark]);

  return {
    isDark,
    themeClass: isDark ? darkTheme.className : '',
    toggle: () => setIsDark(!isDark),
  };
}
```

## System preference detection

### CSS-only approach (no flash)

```ts
// tokens.ts
export const color = tokens.create('color', {
  text: '#111827',
  surface: '#ffffff',
  // ... other tokens
});

export const darkTheme = tokens.createTheme('dark', {
  base: {
    color: {
      text: '#e0e0e0',
      surface: '#1a1a2e',
    },
  },
});
```

```html
<!-- index.html -->
<!DOCTYPE html>
<html>
  <head>
    <script>
      // Prevent flash of wrong theme
      (function () {
        const theme =
          localStorage.getItem('theme') ||
          (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
        if (theme === 'dark') {
          document.documentElement.classList.add('theme-dark');
        }
      })();
    </script>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>
```

```tsx
// App.tsx
import { darkTheme } from './tokens';

function App() {
  const [isDark, setIsDark] = useState(() =>
    document.documentElement.classList.contains(darkTheme.className),
  );

  const toggleTheme = () => {
    const newTheme = !isDark;
    setIsDark(newTheme);

    if (newTheme) {
      document.documentElement.classList.add(darkTheme.className);
    } else {
      document.documentElement.classList.remove(darkTheme.className);
    }
  };

  return <div className={isDark ? darkTheme.className : ''}>{/* app content */}</div>;
}
```

### Dark from media query only

If you do not toggle a class yourself and only want dark tokens when `prefers-color-scheme: dark` matches:

```ts
import { tokens } from 'typestyles';

const light = { color: { text: '#111827', surface: '#ffffff' } };
const dark = { color: { text: '#e5e7eb', surface: '#0f172a' } };

export const appTheme = tokens.createTheme('app', {
  base: light,
  colorMode: tokens.colorMode.mediaOnly({ dark }),
});
```

Apply `appTheme.className` once on your root; dark overrides apply automatically via CSS.

## Multi-brand theming

### Different themes for different contexts

```ts
// themes.ts
import { tokens } from 'typestyles';

// Define base tokens structure
const baseTokens = {
  color: {
    primary: '',
    secondary: '',
    text: '',
    surface: '',
  },
  space: {
    sm: '8px',
    md: '16px',
    lg: '24px',
  },
};

// Brand A theme
export const brandA = tokens.createTheme('brand-a', {
  base: {
    color: {
      primary: '#0066ff',
      secondary: '#6b7280',
      text: '#111827',
      surface: '#ffffff',
    },
  },
});

// Brand B theme
export const brandB = tokens.createTheme('brand-b', {
  base: {
    color: {
      primary: '#10b981',
      secondary: '#f59e0b',
      text: '#1f2937',
      surface: '#fafafa',
    },
  },
});

// Brand C theme
export const brandC = tokens.createTheme('brand-c', {
  base: {
    color: {
      primary: '#ef4444',
      secondary: '#8b5cf6',
      text: '#0f172a',
      surface: '#f8fafc',
    },
  },
});
```

### Applying brand themes

```tsx
// App.tsx
import { brandA, brandB, brandC } from './themes';

const brands = {
  a: brandA,
  b: brandB,
  c: brandC,
};

function App({ brandId }) {
  const surface = brands[brandId] || brandA;

  return (
    <div className={surface.className}>
      <PageContent />
    </div>
  );
}
```

### Nested themes

Themes can be nested for scoped theming:

```tsx
import { brandA, brandB } from './themes';

function App() {
  return (
    <div className={brandA.className}>
      <Header /> {/* Uses brandA colors */}
      <main>
        <div className={brandB.className}>
          <Widget /> {/* Uses brandB colors */}
        </div>
      </main>
      <Footer /> {/* Uses brandA colors */}
    </div>
  );
}
```

CSS custom properties cascade naturally, so the inner theme overrides only affect its subtree.

## Component-specific themes

### Isolated component theming

```ts
// components/Chart/Chart.tokens.ts
import { tokens } from 'typestyles';

// Chart-specific tokens that don't affect the rest of the app
export const chartTheme = tokens.createTheme('chart', {
  base: {
    color: {
      primary: '#0066ff',
      secondary: '#10b981',
      tertiary: '#f59e0b',
      quaternary: '#ef4444',
      grid: '#e5e7eb',
      axis: '#6b7280',
    },
  },
});
```

```tsx
// components/Chart/Chart.tsx
import { chartTheme } from './Chart.tokens';

export function Chart({ data }) {
  return (
    <div className={chartTheme.className}>
      <svg className={chart('svg')}>{/* Chart uses chart-specific color tokens */}</svg>
    </div>
  );
}
```

## Seasonal/time-based themes

### Time-aware theming

```ts
// themes/seasonal.ts
import { tokens } from 'typestyles';

export const holidayTheme = tokens.createTheme('holiday', {
  base: {
    color: {
      primary: '#c41e3a', // Holiday red
      secondary: '#165b33', // Holiday green
      accent: '#ffd700', // Gold
    },
  },
});

export const springTheme = tokens.createTheme('spring', {
  base: {
    color: {
      primary: '#88c999',
      secondary: '#f4a460',
      accent: '#ffb6c1',
    },
  },
});
```

```tsx
// hooks/useSeasonalTheme.ts
import { holidayTheme, springTheme } from '../themes/seasonal';

export function useSeasonalTheme(): string | undefined {
  const now = new Date();
  const month = now.getMonth();

  // Holiday season: December
  if (month === 11) {
    return holidayTheme.className;
  }

  // Spring: March-May
  if (month >= 2 && month <= 4) {
    return springTheme.className;
  }

  return undefined; // Use default theme
}
```

## Advanced theme composition

### Partial themes

```ts
// themes/semantics.ts
import { tokens } from 'typestyles';

// Semantic color tokens
export const successTheme = tokens.createTheme('success', {
  base: {
    color: {
      primary: '#10b981',
      primaryHover: '#059669',
    },
  },
});

export const warningTheme = tokens.createTheme('warning', {
  base: {
    color: {
      primary: '#f59e0b',
      primaryHover: '#d97706',
    },
  },
});

export const dangerTheme = tokens.createTheme('danger', {
  base: {
    color: {
      primary: '#ef4444',
      primaryHover: '#dc2626',
    },
  },
});
```

```tsx
// components/Alert/Alert.tsx
import { successTheme, warningTheme, dangerTheme } from '../../themes/semantics';

const alertThemeClasses = {
  success: successTheme.className,
  warning: warningTheme.className,
  danger: dangerTheme.className,
};

export function Alert({ type, children }) {
  return <div className={alertThemeClasses[type]}>{children}</div>;
}
```

### Token layering

```ts
// tokens/layers.ts
import { tokens } from 'typestyles';

// Layer 1: Primitives
const primitives = tokens.create('primitives', {
  // Raw values
  blue500: '#0066ff',
  blue600: '#0052cc',
  gray500: '#6b7280',
});

// Layer 2: Semantic tokens
const color = tokens.create('color', {
  // Reference primitives
  primary: primitives.blue500,
  primaryHover: primitives.blue600,
  text: '#111827',
});

// Layer 3: Component tokens
const button = tokens.create('button', {
  // Reference semantic tokens
  backgroundColor: color.primary,
  backgroundColorHover: color.primaryHover,
  textColor: '#ffffff',
});
```

## Light / dark / system on `data-*`

When the user can pick light, dark, or system, and **light must win over system dark**, use `tokens.colorMode.systemWithLightDarkOverride`:

```ts
import { tokens } from 'typestyles';

const light = { color: { text: '#111827', surface: '#ffffff' } };
const dark = { color: { text: '#e5e7eb', surface: '#0f172a' } };

export const shell = tokens.createTheme('shell', {
  base: light,
  colorMode: tokens.colorMode.systemWithLightDarkOverride({
    attribute: 'data-color-mode',
    values: { light: 'light', dark: 'dark', system: 'system' },
    scope: 'ancestor',
    light,
    dark,
  }),
});
```

Set `data-color-mode` on `html` (or another ancestor); apply `shell.className` on your themed subtree.

## Condition scopes: `self`, `ancestor`, `descendant`

`tokens.when.attr(name, value, { scope })` and `tokens.when.className(name, { scope })` accept three `scope` values describing where the marker lives relative to the theme root:

- **`'self'`** — the marker is on the theme root itself: `.theme-app[data-mode="dark"]`.
- **`'ancestor'`** — the marker is on an ancestor of the theme root (e.g. `data-color-mode` on `html`): `[data-mode="dark"] .theme-app`.
- **`'descendant'`** — the marker is on a descendant of the theme root, somewhere inside the themed subtree: `.theme-app [data-mode="dark"]`.

### Fixed-tone surfaces with `scope: 'descendant'`

Sometimes a specific element should render with a **fixed** tone regardless of the page's ambient mode — a toast that is always dark even on a light page, a syntax-highlighted code block that stays dark in light mode. That is not "dark mode": it is a design decision fixed to one element. A descendant-scoped mode expresses exactly that — the marker attribute goes on the element itself, inside the themed subtree:

```ts
import { tokens } from 'typestyles';

const light = { color: { text: '#111827', surface: '#ffffff' } };
const dark = { color: { text: '#e5e7eb', surface: '#0f172a' } };

export const app = tokens.createTheme('app', {
  base: light,
  modes: [
    // Ambient light/dark switching, as usual:
    ...tokens.colorMode.systemWithLightDarkOverride({
      attribute: 'data-color-mode',
      values: { light: 'light', dark: 'dark' },
      scope: 'ancestor',
      light,
      dark,
    }),
    // Fixed-tone override for marked elements inside the themed subtree:
    {
      id: 'surface-dark',
      overrides: dark,
      when: tokens.when.attr('data-surface', 'dark', { scope: 'descendant' }),
    },
  ],
});
```

```html
<div class="theme-app">
  <p>Follows the ambient light/dark mode…</p>
  <div data-surface="dark">…but this toast is always dark.</div>
</div>
```

The descendant-scoped rule compiles to `.theme-app [data-surface="dark"]`, so any element carrying `data-surface="dark"` inside the theme gets the dark token values — no matter what `prefers-color-scheme` or `data-color-mode` currently say. Note that `colorMode.*` presets return plain mode arrays, so you can spread one into `modes` alongside hand-written entries (as above) instead of using the `colorMode` config field.

Two properties worth knowing:

- **No built-in "reset to ambient".** Once a descendant-scoped mode matches, it applies to that whole subtree; a nested child cannot fall back to the ambient mode automatically. Define an explicit mode (e.g. `data-surface="light"`) if you need a counter-tone.
- **`when.not()` is not supported on descendant-scoped conditions** — a descendant relationship cannot collapse into a single `:not()` compound selector. In development this logs a warning and emits no rule.

## Accessibility considerations

### High contrast mode

```ts
// themes/accessibility.ts
import { tokens } from 'typestyles';

export const highContrastTheme = tokens.createTheme('high-contrast', {
  base: {
    color: {
      text: '#000000',
      surface: '#ffffff',
      primary: '#0000ff',
      border: '#000000',
    },
  },
});
```

```tsx
// hooks/useAccessibility.ts
export function useHighContrast() {
  const [isHighContrast, setIsHighContrast] = useState(false);

  useEffect(() => {
    const mediaQuery = window.matchMedia('(prefers-contrast: high)');
    setIsHighContrast(mediaQuery.matches);

    const handler = (e) => setIsHighContrast(e.matches);
    mediaQuery.addEventListener('change', handler);

    return () => mediaQuery.removeEventListener('change', handler);
  }, []);

  return isHighContrast;
}
```

### Respect user preferences

```ts
// tokens.ts
import { tokens } from 'typestyles';

export const color = tokens.create('color', {
  text: '#111827',
  // ... other tokens
});

export const darkTheme = tokens.createTheme('dark', {
  base: {
    color: {
      text: '#e0e0e0',
      // ... other overrides
    },
  },
});

// Optional: separate surface for motion tokens, etc.
export const reducedMotionTheme = tokens.createTheme('reduced-motion', {
  base: {
    /* motion-related overrides */
  },
});
```

```tsx
// App.tsx
import { darkTheme } from './tokens';

function App() {
  const prefersDark = useMediaQuery('(prefers-color-scheme: dark)');
  const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');

  const themeClasses = [prefersDark && darkTheme.className, prefersReducedMotion && 'reduce-motion']
    .filter(Boolean)
    .join(' ');

  return (
    <div className={themeClasses}>
      <PageContent />
    </div>
  );
}
```

## Theme switching transitions

### Smooth theme transitions

```css
/* Add to your global CSS or a style element */
html,
body,
* {
  transition:
    background-color 0.3s ease,
    color 0.3s ease,
    border-color 0.3s ease;
}
```

Or with typestyles global CSS:

```ts
import { global } from 'typestyles';

global.style('html', {
  transition: 'background-color 0.3s ease, color 0.3s ease, border-color 0.3s ease',
});
```

Use a scoped `global` from `createTypeStyles({ layers, globalLayer })` when you emit globals into a cascade layer (see [Cascade layers](/docs/cascade-layers)).

### Prevent flash during theme switch

```tsx
import { useEffect, useState } from 'react';
import { darkTheme } from './tokens';

function ThemeProvider({ children }) {
  const [themeClass, setThemeClass] = useState('');
  const [isReady, setIsReady] = useState(false);

  useEffect(() => {
    // Read theme from localStorage or system preference
    const savedTheme = localStorage.getItem('theme');
    setThemeClass(savedTheme === 'dark' ? darkTheme.className : '');
    setIsReady(true);
  }, []);

  // Prevent rendering until theme is determined
  if (!isReady) {
    return null; // or a loading spinner
  }

  return <div className={themeClass}>{children}</div>;
}
```

## SSR with themes

### Server-side theme detection

```ts
// server.ts
import { collectStyles } from 'typestyles/server';
import { darkTheme } from './tokens';

app.get('/', (req, res) => {
  // Detect theme from cookie or user preference
  const themeCookie = req.cookies.theme;
  const isDark = themeCookie === 'dark';
  const htmlClass = isDark ? darkTheme.className : '';

  const { html, css } = collectStyles(() =>
    renderToString(
      <div className={htmlClass}>
        <App />
      </div>
    )
  );

  res.send(`
    <!DOCTYPE html>
    <html class="${htmlClass}">
      <head>
        <style id="typestyles">${css}</style>
      </head>
      <body>
        <div id="root">${html}</div>
      </body>
    </html>
  `);
});
```

## Component overrides (two-tier model)

When a theme needs to change how a component looks beyond token overrides, there are
two tiers — pick the lightest option that fits.

### Tier 1 — component-scoped CSS custom properties (preferred)

If a component author exposed a property as a CSS custom property (`ctx.vars` /
`c.vars`), consumers override it per theme with ordinary token or theme CSS. Custom
properties inherit down the DOM and reset at each `.theme-*` boundary, so nested
themes stay proximity-correct with no extra tooling.

See [Components — expose themeable properties as vars](/docs/components#expose-themeable-properties-as-vars).

### Tier 2 — plain CSS against semantic class names

For properties the author did not expose as vars, target the stable semantic class
names from `styles.component()` (for example `button-base`, `button-intent-primary`).
See [Class naming](/docs/class-naming) and the [public contract](#public-semantic-class-names).

**Non-nested themes:** a descendant selector in a later cascade layer is enough:

```ts
import { createStyles } from 'typestyles';

const styles = createStyles({
  layers: ['components', 'overrides'] as const,
});

const button = styles.component(
  'button',
  { base: { padding: '8px 16px' } },
  { layer: 'components' },
);

// In theme setup for `.theme-acme`:
styles.class('.theme-acme .button-base', { borderRadius: '999px' }, { layer: 'overrides' });
```

**Nested conflicting themes:** when two `.theme-*` regions nest and both override the
same component class, plain selectors tie on specificity and source order wins. Use
`styles.scope()` so the nearest scoping root wins:

```ts
styles.scope({ root: '.theme-beta', to: '.theme-acme', layer: 'overrides' }, 'button-base', {
  backgroundColor: 'rebeccapurple',
  '&:hover': { opacity: 0.9 },
});
```

`styles.scope()` reuses the same `serializeStyle` / `applyLayerToRules` / `insertRules`
pipeline as other TypeStyles APIs — pseudo-selectors and `@media` in `overrides` work
unchanged.

**Browser support:** `@scope` ships in Chrome 118+, Firefox 128+, Safari 17.4+. Treat
it as an opt-in escalation for nested conflicts; older browsers can keep Tier 2 plain
selectors and accept the documented load-order caveat.

## Public semantic class names

In **`semantic` naming mode** (the default), every class emitted by
`styles.component()` / `styles.class()` is a **public, semver-guarded surface**.
Consumers may target those names in plain CSS, `styles.scope()`, or any other CSS
tooling. Renaming a namespace or variant key is a **breaking change** — TypeScript will
not catch a renamed string literal, so publishable design systems should opt into the
[`@typestyles/no-removed-public-classname`](/docs/publishing-packages#guard-public-class-names)
rule and regenerate `.typestyles-public-classnames.json` deliberately when names change.

## Best practices

1. **Use semantic token names** - `primary`, `surface`, `text` instead of `blue`, `white`, `black`
2. **Define dark mode alongside light mode** - Keep them in sync
3. **Test both themes** - Use visual regression for both modes
4. **Respect system preferences** - Default to `prefers-color-scheme`
5. **Provide user override** - Let users choose independently of system
6. **Store preference** - Use localStorage to remember user choice
7. **Avoid theme flash** - Set theme class before first paint
8. **Use CSS custom properties** - They cascade naturally for nested themes

Source: https://typestyles.dev/docs/theming-patterns

---

# Tokens

Design tokens and theming with tokens.create, createTheme, and color modes


Tokens are design primitives (colors, spacing, etc.) exposed as CSS custom properties. They keep your styles consistent and make theming straightforward.

## Scoped token instances

The default `import { tokens } from 'typestyles'` is unscoped. For a **package or micro-frontend** that shares the page with other TypeStyles bundles, call **`createTokens({ scopeId })`** once and reuse that instance so custom properties and theme classes do not collide:

```ts
import { createTokens } from 'typestyles';

export const tokens = createTokens({ scopeId: 'acme-ui' });

const color = tokens.create('color', { primary: '#0066ff' });
// var(--acme-ui-color-primary)
```

See [Class naming](/docs/class-naming) for how this pairs with `createStyles({ scopeId })` for styles.

To share a **cascade layer** stack with styles, use **`createTypeStyles`** or pass **`layers`** and **`tokenLayer`** to `createTokens` (see [Cascade layers](/docs/cascade-layers)).

## Creating tokens

Use `tokens.create(prefix, object)` to define a set of tokens:

```ts
import { tokens } from 'typestyles';

const space = tokens.create('space', {
  xs: '4px',
  sm: '8px',
  md: '16px',
  lg: '24px',
});

const color = tokens.create('color', {
  primary: '#0066ff',
  text: '#111827',
  border: '#e5e7eb',
});
```

Each value becomes a CSS custom property: `--space-xs`, `--color-primary`. The create function returns an object of the same shape whose values are `var(--prefix-key)` so you can use them in styles:

```ts
padding: space.md,        // var(--space-md)
backgroundColor: color.primary,  // var(--color-primary)
```

When you use **`createTypeStyles({ scopeId: 'app' })`**, the same `tokens` instance emits scoped names (for example `--app-space-md`). Add new namespaces in any module that imports `tokens` from your shared `./typestyles` module:

```ts
import { tokens } from './typestyles';

export const space = tokens.create('space', {
  sm: '8px',
  md: '16px',
});

// With scopeId 'app': padding: space.md  →  var(--app-space-md)
```

## Custom CSS variable names (`nameTemplate`)

The default naming pattern (`--{scopeId}-{namespace}-{path}`) is recommended for greenfield TypeStyles apps. When migrating from an existing CSS variable system, matching Style Dictionary output, or aliasing across namespaces, pass an optional **`nameTemplate`** function to control emitted `--*` names while keeping typed `var(--…)` references and theme integration.

```ts
const tokens = createTokens({ scopeId: 'acme' });

const primitive = tokens.create('color', palette, {
  nameTemplate: ({ segments }) => `--color-${segments.join('-')}`,
});
// --color-brand-500 (no acme- prefix on these vars)

const semantic = tokens.create(
  'semantic-color',
  {
    text: { primary: primitive.brand[500] },
  },
  {
    nameTemplate: ({ path }) => `--ds-color-${path}`,
  },
);
// --ds-color-text-primary: var(--color-brand-500)
```

Set a default on the instance with `createTokens({ nameTemplate })`, or override per namespace in `tokens.create(…, { nameTemplate })`. Templates receive `scopeId`, `scope`, `namespace`, flattened `path`, and `segments` (object keys at each nesting level — use `segments` when your external spec uses a different joiner than `-`).

**Migration notes:**

- Omitting `scopeId` from a custom template restores cross-package collision risk — keep `scopeId` on **classes** even when vars match global names.
- Theme overrides use the same names registered at `tokens.create` time; renaming a template after shipping is a breaking change for plain CSS targeting `--*`.
- Do not let Style Dictionary emit `:root` CSS — TypeStyles remains the single injector. Mirror SD naming via `nameTemplate` instead.

See [Style Dictionary & W3C tokens](/docs/style-dictionary#matching-external-css-names) for pipeline examples.

## Referencing tokens defined elsewhere

When tokens are created in another module or package, use `tokens.use(namespace)` to get the same `var(--namespace-key)` references **without** emitting another `:root` rule. The namespace must already be registered (via `tokens.create`) before those variables exist in CSS.

### Type inference (cross-package)

`tokens.create()` returns a branded ref. Pass that ref to `tokens.use()` so consumers get the same typed shape without duplicating a manual generic:

```ts
// design-system/tokens.ts
export const space = tokens.create('space', { sm: '8px', md: '16px' });

// app/styles.ts
import { space as spaceTokens } from '@acme/design-system';
const space = tokens.use(spaceTokens);
space.md; // string — typed as var(--space-md)
```

For string-only lookups inside one package, declare a registry on `createTokens<Registry>()`:

```ts
type DesignTokens = {
  space: { sm: '8px'; md: '16px' };
  color: { primary: '#0066ff' };
};

const tokens = createTokens<DesignTokens>();
const space = tokens.use('space'); // typed from Registry
```

Export `InferTokenValues<typeof created>` when consumers must reference tokens by namespace string.

## Theming

Use `tokens.createTheme(name, config)` to register a **theme surface**: a class `theme-{name}` whose custom properties override token values for that subtree.

- **`base`** — Overrides always applied on the surface (typical light / default brand).
- **`modes`** — Extra layers with explicit `tokens.when.*` conditions.
- **`colorMode`** — Preset layers from `tokens.colorMode.*` (mutually exclusive with `modes`).

```ts
const dark = tokens.createTheme('dark', {
  base: {
    color: {
      primary: '#66b3ff',
      text: '#e0e0e0',
      surface: '#1a1a2e',
    },
  },
});
```

`createTheme` returns a **`ThemeSurface`** (`className`, `name`, string coercion). Pass **`dark.className`** to DOM or React `className` props, or use `String(dark)` / `` `${dark}` `` in templates.

```ts
document.body.classList.add(dark.className);
```

**Shorthand — dark under `prefers-color-scheme` only:**

```ts
const autoDark = tokens.createDarkMode('app', {
  color: { text: '#e5e7eb', surface: '#0f172a' },
});
```

**Preset — system + `data-color-mode` toggle:**

```ts
const light = { color: { text: '#111', surface: '#fff' } };
const dark = { color: { text: '#eee', surface: '#111' } };

const shell = tokens.createTheme('shell', {
  base: light,
  colorMode: tokens.colorMode.systemWithLightDarkOverride({
    attribute: 'data-color-mode',
    values: { light: 'light', dark: 'dark', system: 'system' },
    scope: 'ancestor',
    light,
    dark,
  }),
});
```

Other presets: `tokens.colorMode.mediaOnly`, `attributeOnly`, `mediaOrAttribute`. Condition primitives: `tokens.when.media`, `prefersDark`, `attr`, `className`, `selector`, `and`, `or`, `not`. `attr` and `className` take a `scope` of `'self'`, `'ancestor'`, or `'descendant'` describing where the marker lives relative to the theme root (see [Theming patterns](/docs/theming-patterns#condition-scopes-self-ancestor-descendant)).

See [Theming patterns](/docs/theming-patterns) for end-to-end examples.

## Interop with DTCG and Style Dictionary

If your tokens originate in Figma, Tokens Studio, or another design tool that emits the **W3C Design Tokens Community Group (DTCG)** JSON format, use **Style Dictionary** as a build step that emits a plain TypeScript primitives module — then feed that module into `tokens.create(…)` here. See [Style Dictionary & W3C tokens](/docs/style-dictionary) for the full pipeline in both directions.

Source: https://typestyles.dev/docs/tokens

---

# Troubleshooting

Common issues and how to fix them


Common issues you might encounter and their solutions.

## Styles not applying

### Check the class name

First, verify the class name is being applied:

```tsx
function Button() {
  return <button className={button()}>Click me</button>;
}
```

Open DevTools and check that the element has the expected class:

```html
<!-- Should see something like this -->
<button class="button-base">Click me</button>
```

**If no class is present:**

- Check that the component is actually rendering
- Verify the style definition is being imported
- Ensure no JavaScript errors are preventing execution

**If class is present but styles don't apply:**

- Check the computed styles in DevTools
- Verify no other CSS is overriding your styles
- Look for CSS specificity issues

### Check CSS injection

Styles are injected lazily. Open DevTools and look for a `<style>` tag with typestyles:

```html
<head>
  <style id="typestyles">
    .button-base {
      padding: 8px 16px;
    }
  </style>
</head>
```

**If the style tag is missing:**

- Ensure typestyles is actually being imported
- Check that components using the styles are rendering
- Verify no bundler issues (check console for errors)

**If styles are in the tag but not applied:**

- Check for CSS syntax errors
- Verify the class name in HTML matches the CSS selector
- Look for ad blockers that might be removing styles

## Duplicate namespace warnings

### What it means

```
Style namespace "button" is also used in /path/to/other/file.ts.
Duplicate namespaces cause class name collisions.
```

This means you've created two different styles with the same namespace:

```ts
// File A
const button = styles.component('button', { ... });

// File B
const button = styles.component('button', { ... }); // Same namespace!
```

### How to fix

Use unique, descriptive namespaces:

```ts
// ✅ Good - descriptive names
const iconButton = styles.component('icon-button', { ... });
const textButton = styles.component('text-button', { ... });
const submitButton = styles.component('submit-button', { ... });

// ❌ Bad - generic names that collide
const button = styles.component('button', { ... });
const button2 = styles.component('button', { ... }); // Collision!
```

## TypeScript errors

### "Property does not exist"

```
Property 'tertiary' does not exist on type '{ primary: string; secondary: string; }'
```

You're trying to access a token that doesn't exist:

```ts
const color = tokens.create('color', {
  primary: '#0066ff',
  secondary: '#6b7280',
});

color.tertiary; // Error! This token doesn't exist
```

**Fix:** Add the missing token or use an existing one.

### "No overload matches this call"

```
No overload matches this call.
  The last overload gave the following error.
    Argument of type 'string' is not assignable to parameter of type...
```

You're passing an invalid variant:

```ts
const button = styles.component('button', {
  base: { ... },
  primary: { ... },
});

button({ secondary: true }); // Error! 'secondary' is not a valid flat flag on this recipe
```

**Fix:** Pass only variant keys that exist on the recipe (for dimensioned components, use the correct dimension keys and option names).

### Cannot find module 'typestyles'

```
Cannot find module 'typestyles' or its corresponding type declarations.
```

**Fix:**

1. Make sure typestyles is installed:

   ```bash
   npm install typestyles
   ```

2. Check your import path:

   ```ts
   // ✅ Correct
   import { styles } from 'typestyles';

   // ❌ Incorrect
   import { styles } from './typestyles';
   ```

3. Restart TypeScript server in your editor

## SSR issues

### Styles not included in SSR output

**Symptom:** Page renders without styles, then styles appear after hydration (flash of unstyled content).

**Cause:** Not using `collectStyles()` during render.

**Fix:**

```ts
import { collectStyles } from 'typestyles/server';
import { renderToString } from 'react-dom/server';

// ❌ Wrong
const html = renderToString(<App />);

// ✅ Correct
const { html, css } = collectStyles(() => renderToString(<App />));
// Include css in your HTML response
```

For Next.js, follow the [SSR guide](/docs/ssr) and use `@typestyles/next` (`getRegisteredCss`, `TypestylesStylesheet`, or `@typestyles/next/server` helpers) so the document matches what App Router streams.

### Hydration mismatch

**Symptom:** React warning about hydration mismatch or styles appearing twice.

**Cause:** Mismatch between server and client CSS injection.

**Fix:**

1. Ensure the style tag ID matches:

   ```html
   <!-- Server -->
   <style id="typestyles">
     ${css}
   </style>

   <!-- Client looks for this ID -->
   ```

2. Don't manually create the style tag on client:

   ```tsx
   // ❌ Don't do this on client
   document.head.innerHTML += `<style id="typestyles">...</style>`;

   // ✅ TypeStyles handles this automatically
   ```

### Empty CSS in SSR

**Symptom:** `css` string is empty.

**Cause:** Styles aren't being created during the render pass.

**Fix:** Make sure components with typestyles are actually rendered inside `collectStyles()`:

```ts
// ❌ Wrong - App doesn't use typestyles components
const { css } = collectStyles(() => renderToString(<App />));
// css is empty because App doesn't use styles

// ✅ Correct - Components with styles are rendered
const { css } = collectStyles(() =>
  renderToString(
    <App>
      <Button /> {/* Button uses typestyles */}
    </App>
  )
);
```

## Build issues

### Bundler errors

**ESM/CJS issues:**

If you get errors about ES modules:

```json
// package.json
{
  "type": "module"
}
```

Or use `.mjs` extension for your files.

**Webpack issues:**

If using webpack, ensure it can handle ES modules:

```js
// webpack.config.js
module.exports = {
  resolve: {
    fullySpecified: false,
  },
};
```

### Missing dependencies

If you see errors about missing dependencies, ensure you've installed typestyles:

```bash
npm install typestyles

# If using Vite plugin
npm install -D @typestyles/vite
```

## Runtime errors

### "Cannot read property 'create' of undefined"

```
TypeError: Cannot read property 'create' of undefined
```

**Cause:** Importing incorrectly.

**Fix:**

```ts
// ✅ Correct
import { styles } from 'typestyles';

// ❌ Incorrect
import styles from 'typestyles'; // Wrong! Use named import
```

### "insertRule is not a function"

```
TypeError: sheet.insertRule is not a function
```

**Cause:** Running in an environment without a real DOM (like jsdom with some configurations).

**Fix:** Mock the CSSOM APIs in your test setup:

```ts
// test-setup.ts
Object.defineProperty(document, 'styleSheets', {
  value: [
    {
      insertRule: jest.fn(),
      cssRules: [],
    },
  ],
});
```

Or use a real browser for testing (Playwright, Cypress).

## Styling issues

### Specificity problems

Your styles are being overridden by other CSS:

```css
/* Your typestyles class */
.button-base {
  color: blue;
}

/* Other CSS overrides it */
button {
  color: red;
} /* Higher specificity or loaded later */
```

**Fixes:**

1. Use more specific selectors:

   ```ts
   const button = styles.component('button', {
     base: {
       color: 'blue',
       // Increase specificity
       '&.button-base': {
         color: 'blue',
       },
     },
   });
   ```

2. Load typestyles CSS after other CSS

3. Use `!important` (not recommended):
   ```ts
   base: {
     color: 'blue !important',
   }
   ```

### Cascade issues

Styles from parent components affecting children:

```ts
const parent = styles.component('parent', {
  base: {
    '& button': { color: 'red' }, // Affects ALL buttons inside
  },
});
```

**Fix:** Be more specific or avoid nesting:

```ts
const parent = styles.component('parent', {
  base: {
    // Don't use & button, style specific class instead
  },
});

const childButton = styles.component('child-button', {
  base: {
    color: 'red',
  },
});
```

### Media queries not working

```ts
const responsive = styles.component('responsive', {
  base: {
    '@media (max-width: 768px)': {
      display: 'none',
    },
  },
});
```

**Check:**

1. Viewport is actually below 768px
2. No syntax errors in the media query
3. Check DevTools to see if the media query CSS was generated

## Theme issues

### Theme not applying

```tsx
const darkTheme = tokens.createTheme('dark', {
  base: {
    color: {
      primary: '#66b3ff',
    },
  },
});

<div className={darkTheme.className}>Content</div>;
```

**Check:**

1. The theme class is applied (check DevTools)
2. Tokens are being used in styles (not hardcoded values)
3. The token namespace matches:

   ```ts
   // Creating
   const color = tokens.create('color', { ... });

   // Overriding
   tokens.createTheme('dark', {
     base: {
       color: { ... }, // Must match 'color' namespace
     },
   });
   ```

### Theme flashing on load

**Cause:** Theme is applied after initial render.

**Fix:** Apply theme class before first paint:

```html
<head>
  <script>
    // Set theme immediately
    const theme = localStorage.getItem('theme');
    if (theme === 'dark') {
      document.documentElement.classList.add('theme-dark');
    }
  </script>
</head>
```

## Vite plugin issues

### HMR not working

1. Check that the plugin is installed and configured:

   ```ts
   // vite.config.ts
   import typestyles from '@typestyles/vite';

   export default {
     plugins: [typestyles()],
   };
   ```

2. Ensure files import from `'typestyles'` (not relative paths)

3. Check browser console for HMR-related errors

### "typestyles is not defined"

**Cause:** Plugin isn't transforming the file.

**Fix:** Make sure files import from `'typestyles'`:

```ts
// ✅ This file will be transformed
import { styles } from 'typestyles';

// ❌ This file won't be transformed
import { styles } from '../path/to/typestyles';
```

## Performance issues

### Slow initial render

**Check for:**

1. Too many style definitions at once
2. Creating styles inside components
3. Very large CSS rules

**Fixes:**

1. Code split your styles
2. Move style definitions to module level
3. Simplify complex selectors

### Memory leaks

**Symptoms:** App gets slower over time, memory usage grows.

**Common causes:**

1. Creating styles in event handlers or components
2. Dynamic style values generating infinite variations

**Fix:**

```ts
// ❌ Never do this
function Component() {
  const styles = createStyles(); // Creates on every render
}

// ✅ Do this instead
const styles = createStyles(); // Create once at module level

function Component() {
  // Use existing styles
}
```

## Inspecting registered CSS

To verify what the runtime has registered (for example in a route handler or test), call `getRegisteredCss()` from `typestyles`. For SSR-specific collection, use `collectStyles()` from `typestyles/server` as described in the [SSR guide](/docs/ssr).

## Getting help

If you're still stuck:

1. **Check the documentation:** Review the relevant guide for your use case
2. **Search issues:** Look for similar problems in [GitHub issues](https://github.com/type-styles/typestyles/issues)
3. **Create a minimal reproduction:**
   - Create the smallest possible example that shows the issue
   - Share the code and expected vs actual behavior
4. **Open an issue:** Include:
   - TypeScript version
   - Bundler (Vite, webpack, etc.)
   - Browser
   - Minimal reproduction code

## Quick checklist

When something isn't working, check:

- [ ] Is typestyles installed?
- [ ] Are imports correct (named imports, not default)?
- [ ] Are styles defined at module level (not in components)?
- [ ] Are namespaces unique?
- [ ] Is the component actually rendering?
- [ ] Are there any JavaScript errors in console?
- [ ] Are the class names in HTML what you expect?
- [ ] Is the CSS present in the DOM (DevTools)?
- [ ] For SSR: Is `collectStyles()` being used?
- [ ] For themes: Are tokens being used (not hardcoded values)?

Source: https://typestyles.dev/docs/troubleshooting

---

# TypeScript Tips

TypeScript best practices and advanced types for typestyles


TypeStyles is built with TypeScript in mind. This guide covers tips for getting the most out of types.

## Basic types

### Style definitions

TypeStyles automatically infers types from your definitions:

```ts
import { styles } from 'typestyles';

// Types are inferred automatically
const button = styles.component('button', {
  base: {
    padding: '8px 16px',
    backgroundColor: '#0066ff',
  },
  primary: {
    color: 'white',
  },
});

// Calling the recipe returns a class string (base is always included)
const classes = button({ primary: true });
//     ^? string
```

### Token types

Token references are typed as strings:

```ts
import { tokens } from 'typestyles';

const color = tokens.create('color', {
  primary: '#0066ff',
  secondary: '#6b7280',
});

// color is typed with specific keys
color.primary; // string
color.secondary; // string
color.tertiary; // Error: Property 'tertiary' does not exist
```

## Strict mode compatibility

TypeStyles works great with TypeScript's strict mode. Ensure your `tsconfig.json` has:

```json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true
  }
}
```

## Extending types

### Custom CSS properties

If you need custom CSS properties that aren't in the standard types:

```ts
import { CSSProperties } from 'typestyles';

// Extend the base type
interface CustomProperties extends CSSProperties {
  '--custom-property'?: string;
  '--theme-color'?: string;
}

// Use in your style definitions
const customStyles: Record<string, CustomProperties> = {
  base: {
    '--custom-property': 'value',
    '--theme-color': '#0066ff',
  },
};
```

### Custom at-rules

For custom at-rules that TypeStyles doesn't know about:

```ts
interface CustomAtRules extends CSSProperties {
  '@layer'?: Record<string, CSSProperties>;
}

const styles: Record<string, CustomAtRules> = {
  base: {
    '@layer': {
      utilities: {
        padding: '8px',
      },
    },
  },
};
```

## Component prop types

### Typed variant props

Make your component props type-safe:

```ts
import { styles } from 'typestyles';

const button = styles.component('button', {
  base: { fontWeight: 500 },
  variants: {
    intent: {
      primary: { backgroundColor: '#2563eb', color: 'white' },
      secondary: { backgroundColor: '#e5e7eb', color: '#111' },
      ghost: { backgroundColor: 'transparent', color: '#111' },
    },
    size: {
      small: { fontSize: '12px', padding: '4px 8px' },
      medium: { fontSize: '14px', padding: '8px 12px' },
      large: { fontSize: '16px', padding: '10px 16px' },
    },
  },
  defaultVariants: { intent: 'primary', size: 'medium' },
});

// First argument: partial variant overrides (typed from your recipe)
type ButtonOptions = Parameters<typeof button>[0];
//   ^? { intent?: 'primary' | 'secondary' | 'ghost'; size?: 'small' | 'medium' | 'large' } | undefined

interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'ghost';
  size?: 'small' | 'medium' | 'large';
  children: React.ReactNode;
}

function Button({ variant = 'primary', size = 'medium', children }: ButtonProps) {
  return (
    <button className={button({ intent: variant, size })}>
      {children}
    </button>
  );
}
```

### Stricter object literals

You can add `as const` to **nested values** when you want literal types preserved (for example token-like maps). For `styles.component`, variant keys are inferred from the config object, and **multipart `slots` names are inferred from a `slots` array literal** (no `as const` needed when the array is written inline in the config). Use explicit component prop types when you need a narrower public API than the style keys alone.

## Utility types

### Extracting style types

```ts
import { styles } from 'typestyles';

const card = styles.component('card', {
  base: { ... },
  elevated: { ... },
});

// Optional argument is a partial of flat variant flags
type CardOptions = Parameters<typeof card>[0];
//   ^? { elevated?: boolean } | undefined

// Create a type for your component props
type CardProps = {
  elevated?: boolean;
};
```

### Token type extraction

```ts
import { tokens } from 'typestyles';

const themeTokens = {
  color: tokens.create('color', {
    primary: '#0066ff',
    secondary: '#6b7280',
  }),
  space: tokens.create('space', {
    sm: '8px',
    md: '16px',
  }),
};

// Extract specific token types
type ColorToken = keyof typeof themeTokens.color;
//   ^? 'primary' | 'secondary'

type SpaceToken = keyof typeof themeTokens.space;
//   ^? 'sm' | 'md'
```

## Type-safe themes

### Theme type definition

```ts
// types/theme.ts
export interface Theme {
  color: {
    primary: string;
    secondary: string;
    text: string;
    surface: string;
  };
  space: {
    sm: string;
    md: string;
    lg: string;
  };
}

// Ensure your tokens match the theme
export const color = tokens.create('color', {
  primary: '#0066ff',
  secondary: '#6b7280',
  text: '#111827',
  surface: '#ffffff',
});

// TypeScript will error if you miss a key
```

### Theme-aware components

```ts
import { tokens } from 'typestyles';

const themeTokens = {
  color: tokens.create('color', {
    primary: '#0066ff',
    secondary: '#6b7280',
  }),
  space: tokens.create('space', {
    sm: '8px',
    md: '16px',
  }),
};

interface ThemedComponentProps {
  color: keyof typeof themeTokens.color;
  space: keyof typeof themeTokens.space;
}

function ThemedComponent({ color, space }: ThemedComponentProps) {
  const inline = {
    color: themeTokens.color[color],
    padding: themeTokens.space[space],
  };

  return <div style={inline}>Content</div>;
}

// Usage with autocomplete:
// <ThemedComponent color="primary" space="md" />
```

## Generic components

### Generic style components

```ts
import { styles } from 'typestyles';

const box = styles.component('box', {
  base: { padding: '16px' },
  variants: {
    tone: {
      default: {},
      elevated: { boxShadow: '0 4px 6px rgba(0,0,0,0.1)' },
    },
  },
  defaultVariants: { tone: 'default' },
});

function StyledBox({
  tone = 'default',
  children,
}: {
  tone?: 'default' | 'elevated';
  children: React.ReactNode;
}) {
  return <div className={box({ tone })}>{children}</div>;
}

// Usage
<StyledBox tone="elevated">Content</StyledBox>;
```

## Conditional types

### Responsive style types

```ts
type Breakpoint = 'sm' | 'md' | 'lg' | 'xl';

type ResponsiveValue<T> = T | Partial<Record<Breakpoint, T>>;

interface ResponsiveProps {
  padding: ResponsiveValue<string>;
  display: ResponsiveValue<'block' | 'flex' | 'grid'>;
}

// Implementation would handle responsive logic
```

### Variant combinations

```ts
// Type for all possible button combinations
type ButtonVariant =
  | { variant: 'primary'; size: 'small' | 'medium' | 'large' }
  | { variant: 'secondary'; size: 'small' | 'medium' | 'large' }
  | { variant: 'ghost'; size: 'small' | 'medium' };

function Button(props: ButtonVariant & { children: React.ReactNode }) {
  const { variant, size, children } = props;
  // Implementation
}

// TypeScript enforces valid combinations:
Button({ variant: 'primary', size: 'large', children: 'Click' }); // ✓
Button({ variant: 'ghost', size: 'large', children: 'Click' }); // ✗ Error: 'large' not assignable
```

## Module augmentation

### Extending typestyles types

If you need to add custom types to typestyles:

```ts
// types/typestyles.d.ts
declare module 'typestyles' {
  export interface CSSProperties {
    // Add custom properties
    'anchor-name'?: string;
    'position-anchor'?: string;

    // Add custom values to existing properties
    display?: 'block' | 'flex' | 'grid' | 'custom-value';
  }
}
```

## Type guards

### Safe variant checking

```ts
import { styles } from 'typestyles';

const button = styles.component('button', {
  base: { padding: '8px 12px' },
  variants: {
    intent: {
      primary: { color: 'white', backgroundColor: '#2563eb' },
      secondary: { color: '#111', backgroundColor: '#e5e7eb' },
      ghost: { color: '#111', backgroundColor: 'transparent' },
    },
  },
  defaultVariants: { intent: 'primary' },
});

function isValidVariant(
  variant: string
): variant is 'primary' | 'secondary' | 'ghost' {
  return ['primary', 'secondary', 'ghost'].includes(variant);
}

function Button({ variant }: { variant?: string }) {
  const intent = variant && isValidVariant(variant) ? variant : 'primary';

  return <button className={button({ intent })}>Click</button>;
}
```

## Configuration types

### Strict style configuration

```ts
// styles/config.ts
import { type CSSProperties, styles } from 'typestyles';

interface StyleConfig {
  namespace: string;
  base: CSSProperties;
  variants: Record<string, CSSProperties>;
}

function createStrictStyles(config: StyleConfig) {
  const { namespace, base, variants } = config;
  return styles.component(namespace, { base, ...variants });
}

// Usage with full type safety
const button = createStrictStyles({
  namespace: 'button',
  base: { padding: '8px' },
  variants: {
    primary: { backgroundColor: 'blue' },
  },
});

button({ primary: true }); // ✓ base + primary classes
```

## Type narrowing

### Narrowing with type predicates

```ts
import { styles } from 'typestyles';

type ButtonVariant = 'primary' | 'secondary' | 'ghost';

function isButtonVariant(value: string): value is ButtonVariant {
  return ['primary', 'secondary', 'ghost'].includes(value);
}

const button = styles.component('button', {
  base: { padding: '8px 12px' },
  variants: {
    intent: {
      primary: { color: 'white', backgroundColor: '#2563eb' },
      secondary: { color: '#111', backgroundColor: '#e5e7eb' },
      ghost: { color: '#111', backgroundColor: 'transparent' },
    },
  },
  defaultVariants: { intent: 'primary' },
});

function Button({ variant: variantProp }: { variant?: string }) {
  const intent: ButtonVariant = isButtonVariant(variantProp ?? '')
    ? variantProp
    : 'primary';

  return <button className={button({ intent })}>Click</button>;
}
```

## Best practices

1. **Let types be inferred** when possible
2. **Define explicit interfaces** for component props
3. **Use `as const`** on nested maps when you need literal types
4. **Extract shared types** to avoid duplication
5. **Leverage `keyof`** for token-based props
6. **Use strict mode** for best type safety
7. **Export types** that consumers might need
8. **Document complex types** with JSDoc comments

## Complex CSS values (`calc`, `clamp`, and other parentheses)

Property values are typed as **strings** (or numbers where unit conversion applies). TypeScript cannot tell whether `calc(…)`, `clamp(…)`, `min(…)`, `max(…)`, `url(…)`, or similar is syntactically valid. A single missing or extra `)` often produces **invalid CSS**; depending on where it appears, the browser may ignore one declaration or mis-parse **many rules** after it.

### Built-in helpers: `calc` and `clamp`

TypeStyles exports **`calc`** (a tagged template) and **`clamp(min, preferred, max)`** so the outer `calc(…)` / `clamp(…)` parentheses are always emitted together:

```ts
import { calc, clamp, styles } from 'typestyles';

styles.class('sidebar', {
  height: calc`100vh - 2 * ${t.space[4]}`,
  fontSize: clamp('0.875rem', '2vw', '1.125rem'),
});
```

You still need valid syntax inside the template (for example balanced parentheses in nested `min()` / `max()`), but you won’t forget the closing `)` of `calc` itself.

### Other patterns

1. **Manual template literals** — keep `calc(` and `)` in one literal and interpolate only the middle if you prefer not to use the tag:

   ```ts
   height: `calc(100vh - 2 * ${t.space[4]})`,
   ```

2. **Custom helpers** when you repeat the same shape:

   ```ts
   function calcSubtract(minuend: string, subtrahend: string) {
     return `calc(${minuend} - ${subtrahend})`;
   }
   ```

3. **Name intermediate pieces** if a value gets long—easier to review than a single huge string.

4. **Validate in the browser** (devtools → computed / rules) when you touch tricky values; there is no full compile-time substitute today.

## Nested keys: `container()`, `has()`, `is()`, `where()`

Style objects allow nested keys that start with **`&`** (pseudos, descendants), **`[`** (attributes), or **`@`** (at-rules). When you use a **computed** key next to normal longhands (`color`, `padding`, …), TypeScript must keep that key as a **narrow template literal**. If it widens to plain `string`, the object no longer matches `CSSProperties` and you might be tempted to use `as CSSProperties`.

TypeStyles narrows keys when you use the builders with **literal** inputs:

- **`styles.container({ minWidth: 400 })`**, **`styles.container('sidebar', { minWidth: 300 })`**, and **`styles.container('(min-width: 1px)')`** infer a concrete `` `@container …` `` key.
- **`styles.has('.active')`**, **`styles.is(':hover', ':focus-visible')`**, **`styles.where('.nav')`** infer a concrete `` `&:…` `` key.

So this pattern type-checks without casting:

```ts
import { styles } from 'typestyles';

styles.class('card', {
  color: 'inherit',
  [styles.container({ minWidth: 400 })]: { display: 'grid' },
  [styles.has('.expanded')]: { borderColor: 'blue' },
});
```

When the query or selector is only known as a **`string`** variable at compile time, use **`…styles.atRuleBlock(containerKey, { … })`** (or spread a one-key object) instead of `[someString]: { … }`. See [Custom selectors & at-rules](/docs/custom-at-rules).

## Common type issues

### Issue: "Type instantiation is excessively deep"

This can happen with very complex nested styles. Solution: simplify nesting or add explicit type annotations.

```ts
// If you get deep type errors, add explicit return type
const complex = styles.component('complex', {
  base: {
    // very deep nesting
  },
} as const); // or use explicit type annotation
```

### Issue: "Property does not exist"

Make sure you're importing the correct types:

```ts
// ✅ Import from typestyles
import type { CSSProperties } from 'typestyles';

// ❌ Don't use React's CSSProperties for styles
import type { CSSProperties } from 'react'; // Wrong!
```

### Issue: "Excessively deep type instantiation"

Break complex styles into smaller pieces:

```ts
// ❌ Avoid very complex single definitions
const complex = styles.component('complex', {
  base: {
    // hundreds of lines
  },
});

// ✅ Break into logical groups
const header = styles.component('header', { ... });
const content = styles.component('content', { ... });
const footer = styles.component('footer', { ... });
```

## Summary

TypeStyles provides excellent TypeScript support out of the box. Key points:

- Types are inferred automatically
- Strict mode is fully supported
- You can extend types for custom use cases
- Use explicit interfaces for component props
- Leverage TypeScript's type system for variant safety

Source: https://typestyles.dev/docs/typescript-tips

---

# Vite Plugin

Enhance your Vite development experience with HMR and style validation


The optional `@typestyles/vite` plugin enhances your development experience with Hot Module Replacement (HMR) and helpful warnings.

**Runnable examples:** [examples/vite-app](https://github.com/type-styles/typestyles/blob/main/examples/vite-app/README.md) (React), [examples/vue-app](https://github.com/type-styles/typestyles/blob/main/examples/vue-app/README.md), [examples/svelte-app](https://github.com/type-styles/typestyles/blob/main/examples/svelte-app/README.md), and [examples/typewind](https://github.com/type-styles/typestyles/blob/main/examples/typewind/README.md). Each includes a convention entry and production extraction.

## Installation

```bash
npm install -D @typestyles/vite
# or
pnpm add -D @typestyles/vite
# or
yarn add -D @typestyles/vite
```

## Basic setup

Add the plugin to your `vite.config.ts`:

```ts
import { defineConfig } from 'vite';
import typestyles from '@typestyles/vite';

export default defineConfig({
  plugins: [typestyles()],
});
```

For **zero-runtime production** builds while keeping **runtime + HMR in development**, add a [convention style entry](/docs/zero-runtime#vite) (e.g. `src/typestyles-entry.ts`) or set `extract.modules` (see [Zero-runtime extraction](/docs/zero-runtime)). When at least one extraction module resolves, the plugin defaults to `mode: 'build'`: `vite dev` still injects styles at runtime, and `vite build` emits a static CSS file and strips client injection.

For loading self-hosted fonts with Vite’s asset pipeline, see [Fonts](/docs/fonts).

## Features

### Hot Module Replacement (HMR)

Without the plugin, editing a style file causes a full page reload. With the plugin:

- Style changes apply instantly
- Component state is preserved
- No flicker or re-render cascade

The plugin works by:

1. Detecting when a module uses typestyles
2. Injecting HMR accept handlers
3. Invalidating affected style registrations on file change
4. Triggering a targeted update instead of a full reload

### Duplicate namespace warnings

The plugin warns you when multiple files use the same namespace:

```
Style namespace "button" is also used in /path/to/other/file.ts.
Duplicate namespaces cause class name collisions.
```

This helps catch issues early, since duplicate namespaces can cause unexpected style overwrites.

## Configuration

### Runtime in dev, static CSS in production (recommended for SPAs)

This is the usual setup for Vite: **development** uses the typestyles runtime so edits hot-reload without running a separate extraction step; **production** emits a real `.css` asset the browser can cache and parse in parallel with JS.

Add a convention entry file that imports every registration side effect (see [Zero-runtime extraction](/docs/zero-runtime)), **or** set `extract.modules` explicitly. You do **not** need to pass `mode` — when modules resolve (discovered or explicit), it defaults to `build`, and the plugin only disables the runtime during `vite build`, not during `vite dev`.

**Using discovery (minimal `vite.config`):**

```ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import typestyles from '@typestyles/vite';

export default defineConfig({
  plugins: [
    react(),
    typestyles(), // discovers e.g. src/typestyles-entry.ts when present
  ],
});
```

**Explicit `extract` (multiple entries or custom paths):**

```ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import typestyles from '@typestyles/vite';

export default defineConfig({
  plugins: [
    react(),
    typestyles({
      extract: {
        modules: ['src/typestyles-entry.ts'],
        fileName: 'typestyles.css',
      },
    }),
  ],
});
```

Link the generated file from `index.html` (for example `<link rel="stylesheet" href="/typestyles.css" />`). In dev the file is not emitted yet; the link may 404 harmlessly while the runtime supplies the same rules. Production builds include the asset.

To force runtime-only everywhere (no extraction), set `mode: 'runtime'` even when `extract` is present. For dynamic values that cannot be extracted, see `mode: 'hybrid'` in [Zero-runtime extraction](/docs/zero-runtime).

### Disable duplicate warnings

If you have a legitimate use case for duplicate namespaces (uncommon), you can disable the warning:

```ts
import { defineConfig } from 'vite';
import typestyles from '@typestyles/vite';

export default defineConfig({
  plugins: [
    typestyles({
      warnDuplicates: false,
    }),
  ],
});
```

## How HMR works

When you save a file that imports from `typestyles`, the plugin:

1. **Extracts namespaces**: Parses your code to find all `styles.component()`, `tokens.create()`, `createTheme()`, and `keyframes.create()` calls

2. **Injects HMR code**: Adds Vite's `import.meta.hot` handlers to the module

3. **On file change**:
   - The HMR handler calls `invalidateKeys()` from `typestyles/hmr`
   - Affected styles are removed from the internal registry
   - The module re-executes with fresh style definitions
   - New CSS is injected, replacing the old rules

4. **State preserved**: React/Vue/Svelte components keep their state since only the module containing styles changed

## Example: seeing HMR in action

Create a simple Vite app with typestyles:

```ts
// src/tokens.ts
import { tokens } from 'typestyles';

export const color = tokens.create('color', {
  primary: '#0066ff',
});

// src/styles.ts
import { styles } from 'typestyles';
import { color } from './tokens';

export const button = styles.component('button', {
  base: {
    backgroundColor: color.primary,
    padding: '8px 16px',
  },
});

// src/main.ts
import { button } from './styles';

document.getElementById('app').innerHTML = `
  <button class="${button()}">Click me</button>
`;
```

Run the dev server:

```bash
npm run dev
```

Now edit `src/tokens.ts` and change the primary color. The button updates instantly without a page reload!

## Framework integration

The plugin works with any Vite-based framework:

### React

```bash
npm create vite@latest my-app -- --template react-ts
npm install typestyles @typestyles/vite
```

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import typestyles from '@typestyles/vite';

export default defineConfig({
  plugins: [react(), typestyles()],
});
```

### Vue

```bash
npm create vite@latest my-app -- --template vue-ts
npm install typestyles @typestyles/vite
```

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import typestyles from '@typestyles/vite';

export default defineConfig({
  plugins: [vue(), typestyles()],
});
```

### Svelte

```bash
npm create vite@latest my-app -- --template svelte-ts
npm install typestyles @typestyles/vite
```

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';
import typestyles from '@typestyles/vite';

export default defineConfig({
  plugins: [svelte(), typestyles()],
});
```

## SSR with Vite

HMR hooks are dev-only (`import.meta.hot`). For build-time extraction, production client bundles get `__TYPESTYLES_RUNTIME_DISABLED__` so the sheet does not inject `<style>` tags; pair that with the emitted CSS file or SSR helpers. For SSR without extraction, use `collectStyles()` from `typestyles/server` as described in the [SSR guide](/docs/ssr).

## Troubleshooting

### HMR not working

1. Check that the plugin is listed in `vite.config.ts`
2. Ensure your files import from `'typestyles'` (not a relative path to the package)
3. Verify `import.meta.hot` is available (dev mode, not production)

### Duplicate namespace warnings appearing incorrectly

The detection is regex-based and may have false positives if you:

- Have strings that look like typestyles calls in comments
- Use variable names like `styles` for other purposes

These are rare and don't affect functionality—just ignore the warning or disable it.

### Full reloads still happening

Some changes require a full reload:

- Adding/removing imports that affect the module graph
- Changes to non-typestyles code in the same file
- Type-only changes (TypeScript types don't affect runtime)

### Plugin performance

The plugin adds minimal overhead:

- Only transforms files that import from `'typestyles'`
- Transformation is a simple regex match, not a full AST parse
- HMR helpers are stripped from production bundles; extraction runs only during `vite build` when using `build` or `hybrid` mode

## Is the plugin required?

No. TypeStyles works perfectly without it. The plugin improves DX for:

- Faster iteration with HMR
- Early warning about duplicate namespaces
- Optional production CSS extraction via `extract` (see [Zero-runtime extraction](/docs/zero-runtime))

If you prefer full page reloads or use a different bundler, you don't need this plugin.

## Future features

Planned enhancements (not yet implemented):

- **Dead style detection**: Warn when styles are defined but never used
- **Source maps**: Map generated CSS back to your style definitions

Stay tuned to the [GitHub repository](https://github.com/type-styles/typestyles) for updates.

Source: https://typestyles.dev/docs/vite-plugin

---

# Zero-Runtime Build Extraction

How to eliminate the typestyles runtime in production and emit a static CSS file


Without a bundler integration, typestyles injects CSS at runtime when components render. With **`@typestyles/vite`**, you can make **production** zero-runtime by default: if the plugin finds a [convention entry file](#vite) under the project root, it resolves an extraction module and defaults to `mode: 'build'` (runtime + HMR in dev, static CSS + no client injection on `vite build`). Apps that prefer injection-only can set `mode: 'runtime'` or omit a convention entry and any `extract.modules` list.

Typestyles supports an optional **build extraction** mode through its bundler integrations. When enabled:

- All styles are extracted at build time and written to a static `.css` asset.
- The typestyles runtime is replaced with a no-op stub (`~0 bytes` when tree-shaken).
- No `<style>` injection happens in the browser — the CSS file is served directly.

The same `styles.component`, `tokens.create`, and `keyframes.create` APIs work identically in both modes.

**Runnable examples** (monorepo root, after `pnpm install`):

| Bundler / app     | Command                 | README                                                                                                     |
| ----------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------- |
| Vite + React      | `pnpm vite-app dev`     | [examples/vite-app](https://github.com/type-styles/typestyles/blob/main/examples/vite-app/README.md)       |
| Next.js + verify  | `pnpm next-app build`   | [examples/next-app](https://github.com/type-styles/typestyles/blob/main/examples/next-app/README.md)       |
| esbuild           | `pnpm esbuild-app test` | [examples/esbuild-app](https://github.com/type-styles/typestyles/blob/main/examples/esbuild-app/README.md) |
| Rollup / Rolldown | `pnpm rollup-app build` | [examples/rollup-app](https://github.com/type-styles/typestyles/blob/main/examples/rollup-app/README.md)   |

See also [examples/README.md](https://github.com/type-styles/typestyles/blob/main/examples/README.md) and the [doc ↔ example map](https://github.com/type-styles/typestyles/blob/main/docs/README.md#doc-pages-and-runnable-examples).

---

## Why runtime in dev and extraction in production?

**Development:** You want instant feedback. The typestyles runtime plus the Vite plugin’s HMR hooks let you change tokens or components without running a separate Node extraction step on every save.

**Production:** You want a plain `.css` file: normal browser caching, parallel download/parse with JS, and no style injection work on the main thread after load.

The Vite plugin implements this split when at least one extraction module is resolved (explicit `extract.modules`, or an auto-discovered convention entry): it defaults to `mode: 'build'`, which **only** disables the runtime and emits CSS during `vite build`. `vite dev` keeps injection enabled.

---

## How it works

1. The bundler plugin (Vite, Rollup, Rolldown) scans your source files for typestyles imports.
2. Those modules are bundled and executed in a Node.js subprocess.
3. `getRegisteredCss()` collects all CSS that was registered during that execution.
4. The collected CSS is written as a static asset (e.g. `typestyles.css`) and linked in the HTML.
5. The `__TYPESTYLES_RUNTIME_DISABLED__` flag is defined as `"true"` so the browser bundle uses a no-op sheet that never injects CSS.

---

## Theme extraction

Theme and token CSS needs no separate build step. Because extraction is execute-and-collect, everything a module registers when it runs — including the `:root { --… }` blocks from **`tokens.create`** and the `.theme-*` classes from **`createTheme`** — lands in the same static CSS asset as your component styles. Theme CSS is a byproduct of normal extraction across all six bundler integrations: **Vite**, **Rollup / Rolldown**, **esbuild**, **webpack**, **Next.js**, and **Astro**.

```ts
// src/typestyles-entry.ts
import { tokens, createTheme } from 'typestyles';

export const color = tokens.create('color', { primary: '#0066ff', surface: '#ffffff' });
createTheme('dark', { base: { color: { primary: '#66aaff', surface: '#111111' } } });
```

```css
/* typestyles.css (emitted at build time) */
:root {
  --color-primary: #0066ff;
  --color-surface: #ffffff;
}
.theme-dark {
  --color-primary: #66aaff;
  --color-surface: #111111;
}
```

This means TypeStyles never needs a "did you forget to build your theme" runtime warning. Some zero-runtime libraries treat themes as a separate compilation unit — Astryx, for example, falls back to runtime theme evaluation and warns when a theme wasn't pre-built with `astryx theme build`. In TypeStyles there is no unbuilt-theme state to fall back from: if your entry module reaches the theme, the theme is in the CSS file.

The one thing to get right is the same as for component styles: the modules calling `tokens.create` / `createTheme` must be reachable from your [convention entry](#vite) (or explicit `extract.modules`). To guard against a theme module dropping out of the entry graph, assert on a token variable or theme class with `verifyTypestylesBuild()` (see [Verify extraction in CI](#verify-extraction-in-ci)):

```ts
verifyTypestylesBuild({
  root: process.cwd(),
  cssFile: 'dist/typestyles.css',
  requiredCssSubstrings: [':root { --color-primary:', '.theme-dark'],
});
```

---

## Vite

Install the Vite plugin:

```bash
npm install --save-dev @typestyles/vite
```

In `vite.config.ts`, either **add a convention entry** so the plugin can discover it, or **set `extract.modules`** yourself. When at least one module resolves, **`mode` defaults to `'build'`** (runtime stays on during `vite dev`; extraction and zero-runtime apply on `vite build`).

**Convention entry (minimal config):** add a file at one of these paths (first match wins), re-exporting or importing every registration side effect — for example `src/typestyles-entry.ts` that imports your tokens and components. After the `src/…` entries, the same names are tried under a top-level `styles/` folder (common in Next.js apps without `src/`).

```text
src/typestyles-entry.ts
src/typestyles.ts
src/styles/index.ts
src/styles.ts
styles/typestyles-entry.ts
styles/typestyles.ts
```

```ts
import { defineConfig } from 'vite';
import typestyles from '@typestyles/vite';

export default defineConfig({
  plugins: [
    // Discovers src/typestyles-entry.ts (etc.); mode defaults to 'build'
    typestyles(),
  ],
});
```

**Explicit modules** (multiple entries or non-standard paths):

```ts
import { defineConfig } from 'vite';
import typestyles from '@typestyles/vite';

export default defineConfig({
  plugins: [
    typestyles({
      extract: {
        modules: ['src/styles/tokens.ts', 'src/styles/components.ts'],
        fileName: 'typestyles.css', // optional, default: "typestyles.css"
      },
    }),
  ],
});
```

Explicit modes are still available when you need them:

```ts
typestyles({
  mode: 'runtime', // force injection-only (even if extract is set)
  extract: { modules: ['src/styles/index.ts'] },
});
```

### Modes

| Mode        | Description                                                                                                                                           |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"runtime"` | Default when **no** extraction modules resolve (no `extract.modules`, no discovered convention file). Injection only; no emitted CSS file.            |
| `"build"`   | Default when at least one module resolves (explicit or discovered). CSS is extracted on `vite build`; runtime disabled **only** in production builds. |
| `"hybrid"`  | CSS is extracted AND the runtime is kept (useful for dynamic styles not known at build time).                                                         |

### Linking the CSS file

Add a `<link rel="stylesheet" href="/typestyles.css" />` (or your chosen `fileName`) to `index.html` so production serves the emitted asset. During `vite dev`, that URL may not exist yet; the runtime still applies the same rules.

---

## Rollup / Rolldown

Install the Rollup plugin:

```bash
npm install --save-dev @typestyles/rollup
```

Add a [convention entry file](#vite) (for example `src/typestyles-entry.ts`) or pass explicit `extract.modules`. When a convention entry resolves, `mode` defaults to `"build"`.

```js
// rollup.config.js
import typestylesRollupPlugin from '@typestyles/rollup';

export default {
  input: 'src/main.ts',
  plugins: [
    typestylesRollupPlugin(), // discovers src/typestyles-entry.ts (etc.)
  ],
};
```

Explicit extraction:

```js
typestylesRollupPlugin({
  mode: 'build',
  extract: {
    modules: ['src/styles/index.ts'],
  },
});
```

---

## esbuild

Install the esbuild plugin:

```bash
npm install --save-dev @typestyles/esbuild esbuild
```

```js
// build.mjs
import { build } from 'esbuild';
import typestylesEsbuildPlugin from '@typestyles/esbuild';

await build({
  entryPoints: ['src/main.ts'],
  bundle: true,
  outfile: 'dist/index.js',
  plugins: [typestylesEsbuildPlugin()],
});
```

Convention entry discovery matches Vite and Rollup. The plugin writes `typestyles.css` to esbuild’s `outdir` (default: `dist/typestyles.css`).

---

## webpack

Install the webpack plugin:

```bash
npm install --save-dev @typestyles/webpack webpack
```

```js
// webpack.config.mjs
import TypestylesWebpackPlugin from '@typestyles/webpack';

export default {
  entry: './src/index.ts',
  plugins: [new TypestylesWebpackPlugin()],
};
```

When a convention entry resolves, the plugin emits `typestyles.css` as a build asset and defines `__TYPESTYLES_RUNTIME_DISABLED__` for client bundles.

---

## Next.js

Install the Next.js integration:

```bash
npm install --save-dev @typestyles/next
```

Use **`withTypestyles`** so behavior matches **`@typestyles/vite`**: when `NODE_ENV === 'production'` and a **convention entry file** exists under the project root (same discovery order as Vite — see the list above), the client bundle disables `<style>` injection (`withTypestylesExtract` under the hood). In **development**, the config is left unchanged so the runtime stays on (no need to branch on `NODE_ENV` yourself).

```js
// next.config.mjs
import { withTypestyles } from '@typestyles/next/build';

export default withTypestyles({
  // your existing config, e.g. transpilePackages: ['typestyles', '@typestyles/next'],
});
```

Run extraction before `next build` (CI or a `prebuild` script). **Defaults** match the Vite story: `buildTypestylesForNext({ root })` discovers a convention entry, then writes **`app/typestyles.css`** and **`app/typestyles.manifest.json`** (override with `cssOutFile`, `manifestOutFile`, or `modules` when you need a custom layout).

When an **`app/`** directory exists, extraction also emits **per-route critical CSS** under **`app/_typestyles/routes/`** and upgrades the manifest to **version 2** with a `routes` map. Disable with `routeCss: false` or customize `routeCssOutDir`.

```ts
// scripts/typestyles-build.mts
import { buildTypestylesForNext } from '@typestyles/next/build';

await buildTypestylesForNext({ root: process.cwd() });
```

Import the emitted CSS from your App Router layout (`import './typestyles.css'`), or load route-scoped CSS at request time with **`getRouteCss`** (see [SSR — per-route CSS](/docs/ssr#per-route-critical-css-nextjs)).

For full manual control, **`withTypestylesExtract`** is still available (always merges production defines). **`discoverDefaultExtractModules`** and **`DEFAULT_EXTRACT_MODULE_CANDIDATES`** are re-exported from `@typestyles/next/build` (same as `@typestyles/build-runner` / `@typestyles/vite`).

### Verify extraction in CI

Zero-runtime extraction is execute-and-collect: styles that never run during the build step are **silently omitted** from the CSS file. There is no compile error when a component file is missing from your convention entry.

Use **`verifyTypestylesBuild()`** from `@typestyles/build-runner` (also re-exported from `@typestyles/next/build`) after your build step to fail fast when output is missing or incomplete:

```ts
// scripts/typestyles-verify.mts
import { verifyTypestylesBuild } from '@typestyles/build-runner';

verifyTypestylesBuild({
  root: process.cwd(),
  cssFile: 'app/typestyles.css',
  manifestFile: 'app/typestyles.manifest.json',
  minBytes: 500,
  // App-specific: class names / token vars you expect from the entry graph
  requiredCssSubstrings: ['.my-scope-button-base {', ':root { --my-scope-color-primary:'],
});
```

Checks performed:

- CSS file exists and meets `minBytes` (defaults to non-empty when omitted)
- Optional `requiredCssSubstrings` — catch missing imports from the entry barrel
- Optional manifest exists with `version: 1` or `version: 2` and `css` pointing at your stylesheet path
- For v2 manifests, optional `minRouteEntries` and per-route CSS file checks

Wire it into `package.json` before `next build` (see `@examples/next`):

```json
{
  "scripts": {
    "typestyles:build": "tsx ./scripts/typestyles-build.mts",
    "typestyles:verify": "tsx ./scripts/typestyles-verify.mts",
    "build": "pnpm typestyles:build && pnpm typestyles:verify && next build"
  }
}
```

For Vite/Rollup, pass the emitted asset path (e.g. `dist/typestyles.css`) and omit `manifestFile` unless you write one yourself.

Add `TypestylesStylesheet` to your root layout to handle streaming SSR (React 18 App Router):

```tsx
// app/layout.tsx
import { TypestylesStylesheet } from '@typestyles/next/client';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <TypestylesStylesheet />
        {children}
      </body>
    </html>
  );
}
```

---

## Entry module requirements

The `modules` array should list files that register styles either directly or by importing other style files. A common pattern is a single `styles/index.ts` barrel file:

```ts
// src/styles/index.ts
export * from './tokens'; // tokens.create(...)
export * from './button'; // styles.component(...)
export * from './card'; // styles.component(...)
export * from './typography'; // styles.component(...)
```

```ts
// vite.config.ts
typestyles({
  extract: { modules: ['src/styles/index.ts'] },
});
```

---

## Switching between modes

Typestyles is designed for incremental migration from runtime to build extraction:

1. **Start in runtime-only mode** — omit a convention entry and any `extract.modules` (or set `mode: 'runtime'`).
2. **Add a convention entry or `extract`** — default `build` mode gives dev runtime + prod extraction in Vite.
3. **Use `hybrid`** when you need a static baseline plus runtime for dynamic values.

---

## Checking runtime disabled state

You can check whether the runtime is disabled at any point:

```ts
// The RUNTIME_DISABLED variable is defined by the bundler plugin.
// This will tree-shake to `false` in runtime mode and `true` in build mode.
declare const __TYPESTYLES_RUNTIME_DISABLED__: string | undefined;

const isStaticCSS =
  typeof __TYPESTYLES_RUNTIME_DISABLED__ !== 'undefined' &&
  __TYPESTYLES_RUNTIME_DISABLED__ === 'true';
```

---

## Limitations

- **Dynamic styles** — styles that are created based on runtime data (e.g. user-provided values) cannot be extracted at build time. Use the `hybrid` mode or keep those styles in runtime mode.
- **Lazy routes** — styles imported via dynamic `import()` in route code-splitting may not be captured unless those modules are also listed in `extract.modules`.
- **Server Components (Next.js)** — `TypestylesStylesheet` handles streaming SSR for React Server Components. Ensure it is present in your root layout, or use build-time extraction. See [SSR — RSC patterns](/docs/ssr#react-server-components-nextjs-app-router).

Source: https://typestyles.dev/docs/zero-runtime