Tailwind CSS v4 design tokens: map external semantic roles to @theme

An external token export, a runtime custom property, a Tailwind theme mapping, a generated utility, and a consuming component form a connected chain. They aren't interchangeable sources of truth. When a button looks wrong, changing the last declaration visible in DevTools may hide the mismatch while leaving the ownership error intact.

Tailwind v4 uses CSS-first configuration. Theme-variable namespaces connect declarations to utility families. A color variable in the appropriate namespace can supply background, text, border, and related color utilities. Tailwind also exposes theme variables as CSS custom properties, depending on how they are declared and emitted.

When a Tailwind theme variable points to an external custom property, Tailwind documents the inline option for resolving that reference in the generated utility. The generated rule then refers directly to the external property. That property remains a runtime dependency, so it must be present in served CSS wherever the utility can apply.

@import "tailwindcss";

:root {
  --source-action-background: oklch(0.62 0.17 252);
}

@theme inline {
  --color-action: var(--source-action-background);
}

<button class="bg-action">Save changes</button>

For this fixture, expect a generated declaration equivalent to .bg-action { background-color: var(--source-action-background); }. The raw color stays in one external property. The Tailwind mapping supplies the vocabulary, while the generated rule preserves the runtime dependency.

@theme static {
  --radius-control: 0.5rem;
}

The phrase "Tailwind supports this" can mean four different things. Keep the official framework contract, your project expectation, an environment-specific observation, and the acceptance decision in separate fields. A failure in one toolchain isn't a universal framework rule, and a clean build doesn't prove that the application served the intended CSS.

Treat the Clearly Design report as diagnostic evidence tied to a specific approach, date, and environment: its build appeared healthy while the served output lacked the expected token CSS. Tailwind's official release material separately documents built-in import support. Neither fact determines what your framework served. Inspect the exact artifact used by your application.

Let the required change scope determine placement. If an action background must change across buttons, selected navigation, and other action surfaces together, keep the meaning semantic. If only one promotional card may differ, record a card-level exception instead of redefining the global action role.

Create one record for every disputed or release-critical mapping. The record below includes the fields needed to trace both build output and runtime resolution. Its identifiers, values, consumers, and owners are illustrative project fixtures.

record_id: action-background-001
source_version: demo-kit@2026-09-09
semantic_role: action background
mode_values:
  light:
    upstream_identifier: --source-action-background
    expected_value: oklch(0.62 0.17 252)
  dark:
    upstream_identifier: --source-action-background
    expected_value: oklch(0.74 0.13 252)
tailwind_namespace: --color-*
theme_mapping: --color-action -> var(--source-action-background)
mapping_directive: "@theme inline"
mapping_owner: frontend platform
runtime_dependency: --source-action-background
runtime_scope_expectation:
  light: ':root and [data-theme="light"]'
  dark: '[data-theme="dark"]'
expected_utility: bg-action
expected_generated_declaration: 'background-color: var(--source-action-background)'
utility_evidence:
  expected_present: true
  observed_present: pending inspection
named_consumers:
  - primary save button
  - selected navigation item
consumer_observations:
  light:
    expected: recorded light value
    observed: pending
  dark:
    expected: recorded dark value
    observed: pending
evidence_status: pending inspection
protected_surfaces:
  destructive_button:
    light: { expected: recorded baseline, observed: pending }
    dark: { expected: recorded baseline, observed: pending }
  informational_badge:
    light: { expected: recorded baseline, observed: pending }
    dark: { expected: recorded baseline, observed: pending }
declared_exceptions: []
correction_owner: design systems engineer
final_disposition: pending

Use expected, observed, contradicted, unresolved, or accepted for evidence status. "The build passed" isn't a mapping status. It doesn't identify the source version, prove the generated rule exists, establish that the runtime dependency loaded, or show what a consumer computed.

The consuming application owns its mode selectors. In this bounded fixture, a data attribute changes the value behind one stable external identifier. Tailwind maps that identifier once, so components keep using bg-action in either mode.

:root,
[data-theme="light"] {
  --source-action-background: oklch(0.62 0.17 252);
}

[data-theme="dark"] {
  --source-action-background: oklch(0.74 0.13 252);
}

@theme inline {
  --color-action: var(--source-action-background);
}

<button class="bg-action">Save changes</button>

First, inspect the generated bg-action rule. It should contain the recorded reference to --source-action-background. Next, activate the explicit light selector and record the button's computed background-color. Repeat under the explicit dark selector. Compare both observations with the worksheet instead of deciding that the colors merely look plausible.

The public Ambient Sage page establishes a real upstream artifact with semantic light and dark roles and a Tailwind CSS v4 export. It doesn't establish your application's selector strategy, file order, aliases, consumers, overrides, or observed results. Record those in the consuming project's worksheet.

Responsive values don't have one universal home. The unresolved Tailwind discussion about responsive design tokens captures the tension: repeated breakpoint classes burden consumers, while a global responsive property can hide context and change more surfaces than intended. Before choosing syntax, classify the decision by meaning, scope, consumers, and owner.

A responsive spacing role applied identically to every page section may belong upstream or in layout policy. A card that changes composition inside a narrow container may own that behavior. A one-off marketing arrangement may be clearest as explicit breakpoint utilities. Recording the scope makes the decision reviewable; the category name alone doesn't settle the architecture.

Freeze expectations before inspecting anything. Use content that exposes ordinary and edge behavior: a primary save button, the same action with a long label, a selected navigation item, a destructive action, and an informational badge. Inspect both explicit modes in the same immutable built artifact.

1. 1

   Freeze the source and mapping

   Record the exact upstream version, mode values, external identifiers, runtime selector scopes, @theme declarations, expected generated rules, expected utilities, consumers, owners, and exceptions.

2. 2

   Inspect the built and served artifact

   Confirm that the intended source version, required runtime properties, expected generated declarations, and required static variables are present in the asset the application actually serves.

3. 3

   Record utility evidence

   For each required utility, record whether the expected declaration is present and whether it references the expected runtime dependency.

4. 4

   Inspect representative consumers

   In each mode, record the computed value for the primary save button and selected navigation item. Compare each observation with its recorded expectation.

5. 5

   Inspect protected surfaces

   Record expected and observed values for the destructive button and informational badge in both modes. Treat an unexplained difference as a failure.

6. 6

   Route every mismatch

   Send a wrong source value upstream, a missing runtime property to application loading, a missing generated rule to the Tailwind mapping, and a local conflict to the component or exception owner.

7. 7

   Choose the disposition

   Accept only when all required evidence matches. Revise a bounded mismatch with a known correction owner. Block when a required artifact, mode, observation, exception, or owner remains unresolved.

acceptance_id: tailwind-token-handoff-001
execution_context:
  tailwind_version: record exact installed v4 version
  application_build: record immutable build identifier
  source_version: record exact upstream artifact version
built_artifact:
  location: record inspected served CSS asset
  runtime_dependency: --source-action-background
  runtime_dependency_presence:
    light_scope: { expected: present, observed: pending }
    dark_scope: { expected: present, observed: pending }
utility_evidence:
  bg-action:
    expected_present: true
    observed_present: pending
    expected_declaration: 'background-color: var(--source-action-background)'
    observed_declaration: pending
mode_matrix:
  light:
    selector: '[data-theme="light"]'
    primary_save_button:
      expected: recorded light action value
      observed: pending computed background-color
    selected_navigation_item:
      expected: recorded light action value
      observed: pending computed background-color
  dark:
    selector: '[data-theme="dark"]'
    primary_save_button:
      expected: recorded dark action value
      observed: pending computed background-color
    selected_navigation_item:
      expected: recorded dark action value
      observed: pending computed background-color
protected_surfaces:
  destructive_button:
    light: { expected: recorded light baseline, observed: pending }
    dark: { expected: recorded dark baseline, observed: pending }
  informational_badge:
    light: { expected: recorded light baseline, observed: pending }
    dark: { expected: recorded dark baseline, observed: pending }
representative_content:
  - Save changes
  - A deliberately long primary-action label
declared_exceptions:
  - record selector, reason, scope, owner, and removal condition
unresolved_behavior:
  - record responsive classification or selector-precedence questions
correction_owners:
  upstream_value: design system owner
  application_loading: frontend platform owner
  tailwind_mapping: frontend platform owner
  component_override: component owner
failure_conditions:
  - wrong or unknown source version
  - runtime dependency absent from a required selector scope
  - expected utility or generated declaration absent
  - generated declaration references the wrong dependency
  - either mode resolves to the wrong recorded value
  - a protected surface differs from its expected baseline without an approved exception
  - an exception or unresolved mismatch has no owner
disposition: block until every required observation is recorded

Let the record determine the final decision. Accept when the exact source version reaches the served artifact, every runtime dependency exists in its required scope, the expected utilities and declarations are present, both modes produce the recorded consumer values, and protected surfaces match their baselines. Revise a mismatch when its layer and owner are known. Block when the evidence or responsibility remains unclear.

• Tailwind CSS v4.0 - Tailwind CSS: Tailwind CSS v4 introduced CSS-first configuration, built-in import support, and native CSS-variable exposure for design tokens.
• Theme variables - Core concepts - Tailwind CSS: Tailwind documents theme-variable namespaces, utility generation, runtime variables, inline reference behavior, and static emission.
• Adding custom styles - Core concepts - Tailwind CSS: Tailwind documents custom CSS as a project-specific surface when ordinary theme variables and utilities do not fit a requirement.
• Wiring design tokens through Tailwind v4 (Nuxt and Next): This implementation account reports an import failure in particular Nuxt and Next.js setups and demonstrates inspecting served CSS instead of relying on build completion.
• How to make design tokens responsive in Tailwind 4?: The discussion records an unresolved question about repeating responsive variation at consumers versus representing it through a shared token mechanism.
• Ambient Sage Design Kit: The public Ambient Sage kit provides semantic light and dark roles and a Tailwind CSS v4 export as an upstream implementation artifact.