Theme Tokens Overview

Understanding theme tokens in Stoop

What are Theme Tokens?

Theme tokens are design values (colors, spacing, typography, etc.) referenced in styles using the $ prefix. They resolve to CSS variables.

Usage

const Button = styled("button", {
  padding: "$medium",      // Theme token
  color: "$text",          // Theme token
  backgroundColor: "$primary", // Theme token
});
Copy

Shorthand vs Explicit Syntax

Stoop supports two token formats. Shorthand is recommended for cleaner, more maintainable code:

// Shorthand (RECOMMENDED - property-aware resolution)
padding: "$medium"  // → space.medium (automatically resolved)
color: "$text"      // → colors.text (automatically resolved)

// Explicit (use only when needed)
padding: "$space.medium"  // Explicitly specifies scale
color: "$colors.text"     // Explicitly specifies scale
Copy

When to Use Shorthand

Use shorthand in most cases - it's cleaner and leverages property-aware resolution:

const Button = styled("button", {
  backgroundColor: "$primary",  // ✓ Clean, automatically maps to colors
  color: "$text",               // ✓ Clean, automatically maps to colors
  padding: "$medium",           // ✓ Clean, automatically maps to space
  fontSize: "$large",           // ✓ Clean, automatically maps to fontSizes
});
Copy

When to Use Explicit Syntax

Use explicit syntax only when:

1. Token name exists in multiple scales and you need disambiguation:

   // If both colors.medium and space.medium exist:
   padding: "$space.medium"  // Explicitly choose space scale
   Copy

2. Property-aware resolution doesn't map correctly (rare):

   // For custom properties without default mapping
   customProperty: "$colors.primary"
   Copy

3. You want to be extra clear for code readability in complex scenarios

CSS Variables

Tokens resolve to CSS variables:

padding: "$medium"
// Becomes:
padding: var(--stoop-space-medium)

color: "$text"
// Becomes:
color: var(--stoop-colors-text)
Copy

Property-Aware Resolution

Stoop resolves tokens based on the CSS property name. Using a shorthand token (like $primary), Stoop checks the CSS property to determine which theme scale to search:

How it works:

1. Check if token is explicit path ($colors.primary) → convert directly
2. If shorthand ($primary), check the CSS property name
3. Map property to scale using DEFAULT_THEME_MAP or custom themeMap
4. Search theme in the mapped scale first
5. If not found, search all scales (with warning if ambiguous)
6. Convert to CSS variable: var(--stoop-colors-primary)

Property mappings:

• color, backgroundColor, borderColor → colors scale
• padding, margin, gap → space scale
• fontSize → fontSizes scale
• fontWeight → fontWeights scale
• borderRadius → radii scale
• boxShadow → shadows scale
• And more...

Example:

const Button = styled("button", {
  color: "$text",        // Property: color → maps to colors scale
  padding: "$medium",    // Property: padding → maps to space scale
  fontSize: "$large",    // Property: fontSize → maps to fontSizes scale
});
Copy

Shorthand tokens ($text, $medium) work without specifying the scale explicitly.