Typing a CSS-in-JS Theme

The plain-language idea

CSS-in-JS libraries (styled-components, Emotion, vanilla-extract, and friends) usually let you define a single "theme" object holding your design tokens — colors, spacing, font sizes — and reference it from every styled component. Without types, that reference is just a string lookup: theme.colors.pirmary (typo, missing the second r) fails silently at runtime, rendering with undefined and no visual feedback beyond "this looks wrong."

Typing the theme turns every token reference into something the compiler checks. The trick isn't writing an interface by hand and hoping it stays in sync — it's deriving the type from the actual theme object, so the type can never drift from the real values, and autocomplete lists exactly the tokens that exist.

See it in a real thing: a theme derived from its own values

// theme.ts
export const theme = {
  colors: {
    primary: "#3b82f6",
    danger: "#ef4444",
    text: "#111827",
  },
  spacing: {
    sm: "0.5rem",
    md: "1rem",
    lg: "1.5rem",
  },
} as const;

// The type IS the theme's shape — no hand-written interface to fall out of sync.
export type Theme = typeof theme;

// Button.ts — a hypothetical styled-components-style helper
function styled<T>(fn: (props: { theme: Theme }) => T) {
  return fn;
}

const buttonStyles = styled(({ theme }) => ({
  backgroundColor: theme.colors.primary,   // ✅ autocompletes: primary | danger | text
  padding: theme.spacing.md,               // ✅ autocompletes: sm | md | lg
  color: theme.colors.pirmary,             // ❌ Property 'pirmary' does not exist
}));

as const is what makes this work: without it, theme.colors.primary would widen to plain string, and Theme would just say "colors has some string properties" — real, but not useful, because every string would satisfy it. as const locks each value to its literal type and makes every key a fixed, known member, which is what lets theme.colors.pirmary fail as a genuine "property does not exist" error rather than type-checking as an unfortunately-misspelled but still-valid string.

What people usually miss

Watch out

• as const is doing the real work here, not the Theme type alone. typeof theme without as const on the object produces a much looser type — properties widen to string, and you lose both the literal values and the "only these exact keys" guarantee that makes typo-catching possible.
• This is compile-time only — it says nothing about runtime theme switching. If your app swaps themes at runtime (dark mode, white-labeling), every theme variant needs to satisfy the same Theme shape, or the type stops being trustworthy the moment you switch.
• Nested objects need as const too, not just the outer one. as const is recursive on object literals by default in modern TypeScript, but if you build the theme by spreading in values from a non-const source, those spread-in parts won't get the same literal narrowing — check the inferred type, don't assume.

The genealogy: typeof in type space meets template literals

Deriving Theme from typeof theme is the same "read a type back off a real value" move from the keyof/typeof operators lesson, just applied to a whole design-tokens object instead of a single variable. If you also want to validate that arbitrary CSS custom-property strings (like var(--color-primary)) reference real tokens, that's the territory of template literal types — a natural next step once the theme itself is properly typed.