Skip to content
acss-plugins

/utility-bridge

Regenerate token-bridge.css so the fpkit-style aliases (--color-error, --color-error-bg, --color-primary-light, …) resolve to your active acss-kit theme. Always emits both :root and [data-theme="dark"] blocks.

Syntax

Section titled “Syntax”
/utility-bridge [--theme=<file>]

Options

Section titled “Options”
OptionDefaultDescription
--theme=<file>Auto-detectedOverride the source theme file path

Examples

Section titled “Examples”

Regenerate against the auto-detected theme:

/utility-bridge

Regenerate against a specific theme file:

/utility-bridge --theme=src/styles/theme/light.css

Regenerate against a brand override:

/utility-bridge --theme=src/styles/theme/brand-forest.css

Theme detection

Section titled “Theme detection”

Without --theme, the command looks for your theme in this order:

  1. src/styles/theme/light.css and dark.css
  2. Any .css file in src/styles/theme/ containing --color-primary
  3. Built-in defaults from assets/utilities/token-bridge.css (warns the user)

What the bridge generates

Section titled “What the bridge generates”

The bridge maps fpkit-style utility names to acss-kit role names and synthesizes derived variants using color-mix():

:root {
  --color-error: var(--color-danger, #dc2626);
  --color-error-bg: color-mix(
    in oklch,
    var(--color-danger, #dc2626) 12%,
    var(--color-background, #ffffff)
  );
  --color-primary-light: color-mix(
    in oklch,
    var(--color-primary, #4f46e5) 80%,
    white
  );
}


[data-theme="dark"] {
  --color-error: var(--color-danger, #f87171);
  --color-error-bg: color-mix(
    in oklch,
    var(--color-danger, #f87171) 18%,
    var(--color-background, #0f172a)
  );
  --color-primary-light: color-mix(
    in oklch,
    var(--color-primary, #7dd3fc) 70%,
    black
  );
}

Dark-mode parity validation

Section titled “Dark-mode parity validation”

After generating the bridge, validate_utilities.py checks that every alias defined in :root also exists in [data-theme="dark"]. If parity fails, the command reports the missing aliases and does not write the file.

Automatic regeneration

Section titled “Automatic regeneration”

From acss-kit v1.0.0, every /theme-create and /theme-update run automatically regenerates token-bridge.css via generate_bridge.py. You only need to call /utility-bridge directly when you update the theme after the initial install and don’t want to re-copy the full utilities bundle.

When to run /utility-bridge

Section titled “When to run /utility-bridge”
  • After /theme-update (a role value changed)
  • After /theme-brand (brand overlay applied)
  • After manually editing a theme CSS file
  • After migrating from acss-utilities to acss-kit v1.0.0 (one-time refresh)

Output location

Section titled “Output location”

The regenerated bridge is written to the same location as the existing token-bridge.css, auto-detected from .acss-target.json or the detected styles directory.

Section titled “Related”