@keboola/brand-audit

Portable CLI for the Keboola UI platform that scans a built bundle (JS, CSS, HTML, SVG) for hardcoded color literals — hex values, functional color notation (rgb, rgba, hsl, hsla), and common CSS color keywords (red, blue, etc.).

Use it after a production build to verify your app routes every color through CSS variables / design tokens — i.e. nothing in the shipped bundle bakes in a brand-specific hex that the @keboola/brand-registry swap mechanism can't override.

Who needs this

Most relevant for audience C (Keboola customers shipping data apps under their own brand) — @keboola/design Layer-0 primitives are brand-neutral by contract, but third-party CSS, inline SVG fills, or copy-pasted snippets can still smuggle in literal colors. brand-audit catches them at the bundle level.

Audiences A and B (internal + Keboola-branded external) get less value — mostly a regression net.

Pattern reference: fitness functions (Ford & Parsons, Building Evolutionary Architectures) — architectural constraints enforced by tooling rather than human review.

Install / run

Zero install:

npx @keboola/brand-audit --dir dist/

Or as a dev dependency:

npm install -D @keboola/brand-audit
# or
yarn add -D @keboola/brand-audit

# Scan dist/ (default), output Markdown to stdout
npx @keboola/brand-audit

# Scan a specific output directory
npx @keboola/brand-audit --dir packages/design/storybook-static/

# JSON output (machine-readable)
npx @keboola/brand-audit --dir dist/ --format json

# Use a custom allow-list
npx @keboola/brand-audit --dir dist/ --allow-list .brand-audit-allowlist

Exit codes:

• 0 — no violations (after allow-list filtering).
• 1 — one or more violations remain.
• 2 — bad arguments or I/O error.

Use in CI

Add a step after your build step:

- name: Brand audit
  run: npx @keboola/brand-audit --dir dist/ --format markdown

For machine-readable output (e.g., to post a PR comment):

- name: Brand audit (JSON)
  run: |
    npx @keboola/brand-audit --dir dist/ --format json > brand-audit.json || true
    cat brand-audit.json

The exit code is non-zero when violations are found, so CI will fail automatically unless you pipe through || true.

CLI options

| Option | Default | Description | | -- | -- | -- | | --dir <path> | dist/ | Directory to scan (relative to CWD or absolute) | | --allow-list <path> | .brand-audit-allowlist | Path to the allow-list file | | --format markdown\|json | markdown | Output format |

Authoring the allow-list file

Create .brand-audit-allowlist at the directory root you run from (or pass --allow-list <path>).

Format:

# Lines starting with "# " are comments (note the space after #).
# Hex colors like #FFFFFF are valid entries — they do NOT need a space.

# Allow these known-safe colors
#FFFFFF
#000000
transparent
currentColor

Rules:

• One entry per line.
• A comment line starts with # (hash + space) or is exactly #.
• Lines like #FFFFFF are treated as allow-list entries, not comments.
• Matching is exact — case-sensitive, full-string match. red does not suppress Red.
• Blank lines are ignored.

Example: Allow a specific legacy hex value in a third-party chunk you can't control:

# vendor/leaflet — cannot change this dependency's hardcoded fill
#3388ff

What is scanned

Files matching **/*.{js,css,html,svg} under --dir.

Detected patterns:

• Hex: #RGB, #RRGGBB, #RGBA, #RRGGBBAA
• Functional: rgb(...), rgba(...), hsl(...), hsla(...)
• Keywords: red, blue, green, yellow, orange, purple, pink, cyan, magenta, lime, teal, indigo, violet, brown, gray/grey, silver, gold, maroon, navy, olive, aqua, fuchsia, crimson, salmon, coral

Automatically skipped (not reported as violations):

• Content inside var(...) calls — design tokens are correct usage.
• Content inside data: URLs — baked-in SVG fills in icon data URIs are intentional.
• Content inside comments (/* */, //, <!-- -->).
• Entries matching the allow-list.

Running the tests

yarn workspace @keboola/brand-audit test

The test suite uses Node's built-in test runner — no extra dependencies.

Known limitations

• No auto-fix — the tool only reports; fixing is manual.
• No contextual understanding — it cannot tell whether #ff0000 in a button.css is "wrong" vs. a legitimate intentional override. Use the allow-list for known-acceptable values.
• Keyword false-positives — color keywords can appear in variable names, class names, or string content. Review matches before adding to the allow-list.
• Minified bundles — line:col numbers in minified output will point to large single-line files; the match values are still correct.
• No CSS-in-JS parsing — colors inside JS template literals that ultimately produce CSS are detected as JS violations, which is correct behaviour.

Related

• @keboola/brand-registry — the multi-brand token mechanism this audit protects.
• docs/branding.md — the broader brand-neutrality contract for @keboola/design.
• UT-3919 "UI as a Platform" — why this CLI exists.

License

MIT