Documentation

Design Tokens

Design tokens are named values for colors, spacing, radii, shadows, typography, and more. They enable a consistent, scalable, and themeable design system across your app. Designers provides a comprehensive, type-safe set of tokens out of the box.

Why Use Design Tokens?

  • Centralize your design decisions (colors, spacing, etc.)
  • Enable easy theming (light/dark/custom themes)
  • Ensure consistency and scalability in large codebases
  • Type-safe and autocompleted in your editor
Tip: You can extend or override tokens in your designers.config.json file for full customization.

Token Types & Examples

  • Colors: ds.colors.blue[600], ds.colors.gray[50]
  • Spacing: ds.spacing[4] (e.g. 1rem)
  • Radius: ds.radius.lg (e.g. 0.75rem)
  • Shadows: ds.shadows.md
  • Typography: ds.typography.fontSize.lg, ds.typography.fontWeight.bold

Usage Example

import { ds } from 'designers';

const styles = {
  color: ds.colors.blue[600],
  background: ds.colors.gray[50],
  padding: ds.spacing[4],
  borderRadius: ds.radius.lg,
  boxShadow: ds.shadows.md,
};

Real-World Component Example

import { ds } from 'designers';

export function Card() {
  return (
    <div
      style={{
        background: ds.colors.gray[50],
        color: ds.colors.gray[900],
        padding: ds.spacing[6],
        borderRadius: ds.radius.xl,
        boxShadow: ds.shadows.lg,
        fontSize: ds.typography.fontSize.lg,
        fontWeight: ds.typography.fontWeight.bold,
      }}
    >
      <h2>Design Tokens in Action</h2>
      <p>Consistent, themeable, and type-safe UI!</p>
    </div>
  );
}

Available Tokens

  • ds.colors: All color tokens, e.g. ds.colors.blue[600]
  • ds.spacing: Spacing scale, e.g. ds.spacing[4]
  • ds.radius: Border radius scale, e.g. ds.radius.lg
  • ds.shadows: Shadow presets, e.g. ds.shadows.md
  • ds.typography: Font sizes, weights, and more
Pro Tip: All tokens are theme-aware and update automatically when the theme changes.

Customizing & Extending Tokens

You can override or add tokens in designers.config.json at the root of your project. Example:

// designers.config.json
{
  "colors": {
    "brand": {
      "primary": "#1e40af",
      "secondary": "#f59e42"
    }
  },
  "spacing": {
    "xxl": "4rem"
  }
}
After editing, restart your dev server. Your new tokens will be available as ds.colors.brand.primary and ds.spacing.xxl.

Best Practices

  • Use tokens everywhere for consistency—avoid hardcoded values.
  • Organize custom tokens by brand, theme, or component as needed.
  • Leverage TypeScript for autocomplete and type safety.
  • Document your token usage for your team.

What's Next?

Quick StartConfigurationTheming