Start from an empty stylesheet. The first line pulls in Tailwind; everything you add sits below it. Define the raw, literal values first. These are named by what they are, not where they are used. Numbered scales are fine here because this layer is plumbing, not API.

@import "tailwindcss";
 
:root {
  /* RAW LAYER: literal values, named by what they are. */
  --color-ink-950: #0b0b0c;
  --color-ink-900: #131214;
  --color-ink-850: #1a181b;
 
  --color-neutral-50: #fafaf9;
  --color-neutral-400: #a8a29e;
  --color-neutral-950: #0c0a09;
 
  --color-red-500: #f5302c;
  --color-red-600: #e30613; /* the signature accent */
}

Nothing in a component will reference these directly. They exist so the semantic layer has something concrete to point at, and so a value lives in exactly one location. If you change --color-red-600, every role that points at it updates for free.

Now the layer that components actually consume. Each variable is named for its role in the interface, and its value is a var() reference into the raw scale. Read the right side as "this role is currently this raw value."

:root {
  /* ...raw layer above... */
 
  /* SEMANTIC LAYER: roles, pointing at the raw scale. */
  --background: var(--color-ink-950);  /* the page itself */
  --surface: var(--color-ink-900);     /* cards, panels, asides */
  --foreground: var(--color-neutral-50); /* primary text */
  --muted: var(--color-neutral-400);   /* secondary text */
  --accent: var(--color-red-600);      /* the one affordance color */
  --accent-foreground: #ffffff;        /* text that sits ON the accent */
}

These five (six with the accent's own foreground) cover most of an interface: the page, the raised surfaces on it, the primary and secondary text, and the single accent that marks where to act. Resist adding more roles than you can name without thinking. A token you cannot describe in four words is not yet a role.

Right now these are plain CSS variables. You could write style={{ background: "var(--background)" }} everywhere, but you want bg-background to exist as a utility. In Tailwind v4 you register variables as theme values with the @theme directive, and a color registered as --color-background generates the full family: bg-background, text-background, border-background, and so on.

Use @theme inline. The inline keyword tells Tailwind to emit the utility as a reference to your variable rather than copying the value in at build time. That distinction matters: with inline, bg-background resolves to var(--background) at runtime, so when you reassign --background later (for dark mode, say) the utility tracks the new value live. Without inline, Tailwind would bake in whatever the variable held at build time and your re-theming would not take.

/* Map semantic roles onto Tailwind's color namespace.
   A --color-* entry here generates bg-*, text-*, border-*, etc. */
@theme inline {
  --color-background: var(--background);
  --color-surface: var(--surface);
  --color-foreground: var(--foreground);
  --color-muted: var(--muted);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
}

The naming looks redundant (--color-background: var(--background)) but it is doing real work. The --color- prefix is the namespace Tailwind scans to build color utilities; the right side is your own semantic variable. You are bridging your role names into Tailwind's expected shape.

Wire the tokens into the page itself, then use them from a component. The body reads the semantic variables directly (it is global, not a utility site); components use the generated utilities.

@layer base {
  body {
    background: var(--background);
    color: var(--foreground);
    -webkit-font-smoothing: antialiased;
  }
}

Now a component references the palette through utilities and never names a color. Here is the difference that makes.

// Literal hex in the markup. Unenforceable, and impossible to re-theme.
export function Notice() {
  return (
    <div style={{ background: "#131214", color: "#a8a29e" }}>
      <strong style={{ color: "#fafaf9" }}>Heads up</strong>
      <a style={{ color: "#e30613" }}>Take action</a>
    </div>
  );
}

// Semantic utilities. Re-themes itself when the tokens change.
export function Notice() {
  return (
    <div className="bg-surface text-muted">
      <strong className="text-foreground">Heads up</strong>
      <a className="text-accent">Take action</a>
    </div>
  );
}

The Bad version hardcodes four hex values into one component. Multiply that by a real app and there is no palette, only forty private opinions about what gray means. The Good version says what each element is: a surface, secondary text, primary text, an affordance. Change a token and this component restyles without being touched.

This is the payoff. Because components reference roles and roles reference the raw scale, you can repoint a role and the whole interface moves. Reassign the semantic layer under a [data-theme="light"] selector. Notice that the components above do not change at all.

/* Flip the roles to point at light values. Components are untouched. */
:root[data-theme="light"] {
  --background: #ffffff;
  --surface: var(--color-neutral-50);
  --foreground: var(--color-neutral-950);
  --muted: var(--color-neutral-400);
  /* --accent stays the same: the brand red works on both. */
}

Toggle data-theme="light" on the <html> element and bg-background now resolves to white, text-foreground to near-black, all without recompiling a single component. That only works because of three choices made earlier: components consume semantic roles, roles are reassignable, and @theme inline keeps the utilities pointing at the live variable instead of a baked-in value.