Cascade Tokens is a methodology for organizing CSS variables directly in the browser, without JSON, without a build step, and without unnecessary JavaScript.

1. A token stabilizes a decision, not an isolated value

Not every value deserves a shared name: a token is worth creating when the value must be shared, adapted, documented or overridden. Global tokens name stabilized primitives, such as a palette or scale entry, while semantic tokens name a usage decision. A purely local layout detail can remain a raw value in its rule.

A semantic token that nobody consumes is a warning sign. An unused palette entry, on the other hand, can be legitimate: the base also publishes what variants or future themes will need.

2. Three levels, one dependency direction

Each token belongs to one of these three levels, and the level is visible in the name, with dependencies flowing only one way: component → semantic → global.

• Global

  The system's raw palette: colors, spacing, radii.

  • --blue-600
  • --space-4

• Semantic

  The usage intention, independent from the raw value.

  • --color-accent
  • --color-danger

• Component

  What a specific component agrees to expose for customization.

  • --button-bg
  • --field-border

For colors and visual intentions, a component goes through a semantic token: --button-bg can be fed by --color-danger, never by --blue-600. Neutral primitives such as spacing, radius, font size or duration can still be consumed directly when they do not hide a usage intention.

The anti-pattern to recognize fits on one line: .button { background: var(--blue-600); }. Nothing is wrong as long as there is only one theme, until the day a second one arrives and forces every component open to correct a color, when a single semantic token would have been enough.

3. The cascade does the work, not you

A CSS variable inherits, is redefined on an element and propagates to its descendants without rewriting any rule. Changing a theme, a zone or a state means redefining a few tokens as close as possible to the need, not duplicating rendering properties.

.danger-zone {
  --button-bg: var(--color-danger);
}

Even in an override, --button-bg remains fed by a semantic token, never by a raw value or by a global color token consumed directly.

4. Explicit layers for arbitration

@layer layers reduce specificity wars and the need for !important. A base publishes default values in a weak layer, then a theme or application overrides them in a stronger layer, without making selectors heavier.

@layer reset, base, theme, components;

@layer base {
  :root {
    /* Global: the whole palette, including colors not used yet */
    --blue-600: #155eef;
    --green-600: #0e7c66;
    --color-accent: var(--blue-600);
  }
}

@layer theme {
  [data-theme="calm"] { --color-accent: var(--green-600); }
}

The base publishes the whole available palette, including colors reserved for alternate themes. The theme only reconnects the semantic token to an existing entry; it never declares a new color itself.

The reset layer is for external dependencies. A library imported without a layer remains outside the layers, and an unlayered rule beats every layer: the project would lose arbitration against its own dependency. Placing it explicitly is enough to reverse that balance of power.

@import "a-library.css" layer(reset);

The limit to keep in mind: this only works for CSS whose import you control. A library that injects its stylesheet at runtime, as many Web Components do, arrives outside the layers and therefore beats everything you have organized. In that case, the only winning move is to take the override out of the layers too.

5. A local fallback before a global dependency

A reusable component declares its tokens with a fallback in var(). It remains usable if nothing is provided, and a variant only overrides what actually changes.

.badge {
  --badge-bg: var(--color-surface-raised, Canvas);

  background: var(--badge-bg);
}

The fallback chain reads from left to right: the project's semantic token if it exists, otherwise the system color Canvas, which already follows the browser theme. The component never breaks, even when dropped into a page that knows none of its tokens.

6. @property for cases that require it, not by default

When a token must be validated, isolated from inheritance or animated, @property lets you give it an explicit syntax, initial value and inheritance behavior. For an animation, it gives the browser enough information to interpolate the value; a regular custom property remains opaque. For everything else (colors, spacing, static values), a classic CSS variable is enough.

@property --notice-border-width {
  syntax: "<length>";
  inherits: false;
  initial-value: 1px;
}

One caveat before mixing it with principle 4: @property is not subject to layers. Placing it inside an @layer neither weakens nor strengthens it, and a second declaration with the same name overwrites the first regardless of the declared order. Better to keep it outside layers, in one place.

1. The scripts

• Suggest

  Finds recurring values and derives a palette, semantic intentions and component tokens.

  • suggest_tokens.py

• Audit

  Hard-coded colors, unlayered imports, semantic tokens without a dark pair, misplaced @property.

  • audit_tokens.py

• Measure

  Resolves var() and light-dark(), then checks contrast in both themes, against two thresholds.

  • check_contrast.py

A fourth script, check_build_layers.py, works on the built CSS rather than the source: @import rules are flattened there, and that is the file that decides production behavior. It catches a library left outside the layers, or an override placed in a layer where it will lose.

The fifth file, cast_lib.py, is never called directly, but it runs every time: the other four import it. It holds what they all need, a small CSS scanner, colour conversion, and the resolution of var() and light-dark(). Without it each script would carry its own parser, four of them, drifting apart, and a bug fixed in one would survive in the other three.

It is also importable from outside, so a one-off check is worth writing on top of it rather than rebuilding a parser.

2. Installation

Copy the skills/cascade-tokens folder from the repository to the location expected by your tool.

# Claude Code
mkdir -p ~/.claude/skills
cp -R skills/cascade-tokens ~/.claude/skills/cascade-tokens

# Codex
mkdir -p ~/.codex/skills
cp -R skills/cascade-tokens ~/.codex/skills/cascade-tokens

It is the same folder in both cases; no adaptation of the skill itself is required.

3. Triggering it

Two ways. Explicitly, by naming it according to the tool's convention: this is the safest path when you already know what you want.

# Claude Code
/cascade-tokens audit src/styles/ before the refactor

# Codex
$cascade-tokens audit src/styles/ before the refactor

Or without invoking anything: the skill describes the situations it applies to, and the assistant picks it up when the request matches. "My colors are hard-coded everywhere", "dark mode is unreadable", "I want to organize my CSS variables" are enough to bring it into play.

The scripts can also be used on their own, without going through an assistant.

python3 skills/cascade-tokens/scripts/suggest_tokens.py src/styles/ --only-new
python3 skills/cascade-tokens/scripts/audit_tokens.py src/styles/
python3 skills/cascade-tokens/scripts/check_contrast.py src/styles/ --min 4.5 --min-ui 3

The skill repository is available on GitHub: Effeilo/cascade-tokens.git.

What it does not do: choose your visual identity, or rewrite CSS in one silent pass. It measures, suggests with the declarations that justify each deduction, and leaves the decision to you. A report that cannot be challenged is not a diagnosis.