Skip to content
acss-plugins

/utility-add

Copy the bundled utilities.css and token-bridge.css into your React project. Auto-detects your styles directory and reports the recommended import order.

Syntax

Section titled “Syntax”
/utility-add [--target=<dir>] [--families=<list>] [--no-bridge]

Options

Section titled “Options”
OptionDefaultDescription
--target=<dir>Auto-detectedOverride the destination directory
--families=<list>All familiesComma-separated list of family partials to include (e.g. color-bg,spacing,flex)
--no-bridgeBridge includedSkip copying token-bridge.css — use when the project ships its own theme without acss-kit

Examples

Section titled “Examples”

Full install (auto-detect directory):

/utility-add

Install to a custom directory:

/utility-add --target=app/styles/

Install only specific families:

/utility-add --families=color-bg,color-text,spacing,flex,display

Install without the token bridge (standalone use without acss-kit):

/utility-add --no-bridge

Workflow

Section titled “Workflow”

  1. Detect styles directory — runs detect_utility_target.py. Uses the utilitiesDir from .acss-target.json if present; falls back to src/styles/, src/css/, app/styles/, or styles/ in that order. Pass --target=<dir> to override.

  2. Detect build stack — runs detect_stack.py to classify framework and entrypoint. Result is merged into .acss-target.json under a stack key. If acss-kit is not installed, this step is skipped with a warning.

  3. Copy files — copies the prebuilt utilities.css verbatim (or a filtered bundle when --families= is set) and token-bridge.css (unless --no-bridge) to the detected directory.

  4. Print import order — reports the required import sequence:

    import "./styles/token-bridge.css"; // first — defines the aliases
    import "./styles/utilities.css"; // then — utility classes consume them

  5. Print summary — files written, total bundle size, families included.

  6. Verify integration — runs verify_integration.py against the recorded entry point (skipped when acss-kit is absent). Missing imports are surfaced as a numbered fix-up list; the command never auto-edits your entry file.

Partial family install

Section titled “Partial family install”

To install only the families you need (reduces bundle size):

/utility-add --families=color-bg,color-text,spacing,flex,display

This generates a filtered utilities.css containing only the specified families, concatenated in canonical order. You can add more families later by re-running the command — the file is always regenerated from scratch.

Re-running safely

Section titled “Re-running safely”

/utility-add always overwrites utilities.css and token-bridge.css. It is safe to re-run to pick up updated bundles after a plugin version update or after changing which families are included.

Section titled “Related”