brand-ui-audit
Audit and refine UI built with brand-ui — visual quality, design consistency, accessibility, and token compliance. Use when the user asks to audit/review/polish a UI, check contrast or accessibility, find design issues, make an interface feel more finished, verify it works across themes, or before shipping a screen. Runs a deterministic static pass (token violations, spacing, sizing, anti-patterns) plus a rendered cross-theme visual + WCAG-contrast pass over Storybook or a running app, then produces a phased, token-referenced plan. Read-only by default — reports findings; every fix points at a @brand token, never raw hex.
- License 许可
- MIT
- 最近更新
- 2026-10-07
- Stars
- ★ 1
- Forks
- 1
01 前言 Front Matter
- name
- brand-ui-audit
- description
- Audit and refine UI built with brand-ui — visual quality, design consistency, accessibility, and token compliance. Use when the user asks to audit/review/polish a UI, check contrast or accessibility, find design issues, make an interface feel more finished, verify it works across themes, or before shipping a screen. Runs a deterministic static pass (token violations, spacing, sizing, anti-patterns) plus a rendered cross-theme visual + WCAG-contrast pass over Storybook or a running app, then produces a phased, token-referenced plan. Read-only by default — reports findings; every fix points at a @brand token, never raw hex.
- allowed-tools
- [ "Bash(npx @elabs-ai/components-cli *)", "Bash(pnpm brand-ui *)", "Bash(npx brand-ui *)" ]
- argument-hint
- [audit|contrast|review|polish] [target]
- user-invocable
- true
02 资源文件 3
- 参考文档reference/anti-patterns.md8.5 KB
- 参考文档reference/contrast-audit.md4.7 KB
- 参考文档reference/ux-evaluation.md11.2 KB
03 SKILL.md 正文
brand-ui-audit
A design-quality reviewer for brand-ui interfaces. It catches what static checks and unit tests miss — weak hierarchy, cramped spacing, low contrast, token violations, broken theming, anti-patterns — and reports them as a prioritized, implementation-ready plan. Read-only: it reports and (with approval) files issues; the fix is done separately.
Run the CLI with the project's runner. In this monorepo:
pnpm brand-ui <cmd>. In a consuming project, add it withpnpm add -D @elabs-ai/components-cli(a public npm package — no registry setup, no token), then runpnpm exec brand-ui <cmd>;npx -y @elabs-ai/components-cli <cmd>works with no install at all. Inside Claude Code with the plugin installed, prefer themcp__brand-ui__*tools (mcp__brand-ui__info,mcp__brand-ui__audit) — the plugin launches the same CLI for you, so you skip the per-project dev-dependency. Examples below saybrand-ui.
Setup
-
Run
brand-ui infoonce (viamcp__brand-ui__info, or the runner from the note above) to load the theme list and token set. Every recommendation must resolve to a token from this set — never propose raw hex. -
Identify the target: a file/dir (static pass), a Storybook story id, or a running app URL (rendered pass).
-
Read the active taste profile — don't ask for it. The same
brand-ui infocall carries atasteblock:register × density × motion × expressiveness(brand-ui ADR 0020). It resolves the shipped defaults against the optionalbrand-ui.config.jsontastekey nearest the code being judged (the audit target's own ancestors first, then the cwd, then the repo root). If it is absent (an old CLI, or a project with no config), fall back to the restrained default —product / comfortable / system / 0— and say so in the report, so nobody mistakes a default for a decision. Only ask the user when the surface in focus plainly contradicts the resolved register (a landing page in aproductrepo — judge by the surface in focus, not the whole repo) and say which one you used. The register flips the defaults you audit against:- product (the default for brand-ui) — app UI, dashboards, admin, tools. Bar is
earned familiarity: one type family, fixed rem scale, restrained color,
every component state present (default/hover/focus/active/disabled/loading/
empty/error), skeletons over spinners, quick 150–250ms state-only motion, no
modal-as-first-thought. Most
@elabs-ai/components-*surfaces are here. - brand —
@elabs-ai/components-marketingsurfaces, landing pages, campaigns. Bar is distinctiveness: committed color, required real imagery (not colored blocks), ambitious first-load motion, a POV. "Restraint without intent reads as mediocre."
The deterministic pass honours the register for you —
brand-ui auditsoftensover-round/side-stripe/bounce-easingto advisory in thebrandregister (override with--register=product|brandwhen you audit one surface against a different bar than the project's). It never softens a banned rule (raw color,gradient-text, tiny text) or content slop. - product (the default for brand-ui) — app UI, dashboards, admin, tools. Bar is
earned familiarity: one type family, fixed rem scale, restrained color,
every component state present (default/hover/focus/active/disabled/loading/
empty/error), skeletons over spinners, quick 150–250ms state-only motion, no
modal-as-first-thought. Most
Modes (route on the first argument)
| Mode | Does |
|---|---|
audit [path] |
Full pass: static lint + rendered cross-theme visual + contrast. Default. |
contrast [target] |
Just the WCAG pass (oklch-aware) across all themes. |
review [story|url] |
Visual/UX critique of a specific surface (hierarchy, spacing, states). |
polish [target] |
Re-audit after fixes; confirm findings are resolved, no regressions. |
Pass 1 — deterministic (no browser, no LLM)
Run brand-ui audit <path> --json (via mcp__brand-ui__audit, or the runner from
the note above). It flags, per file:line:
- raw-hex / rgb-literal / arbitrary-color — colors outside
themes.css(the one allowed place). Fix: a semantic token (bg-card,text-muted-foreground, …). - space-y-x —
space-x/space-y-*→ useflex/grid+gap-*. - wh-equal —
w-N h-Nwith equal values →size-N. - outline-none — focus ring possibly removed → keep
focus-visible:ring-2 ring-ring. - Visual anti-slop (WP-15) —
pure-black(use theforegroundtoken),neon-glow(tinted/inset shadow),gradient-text,side-stripe,over-round,custom-cursor,viewport-h-screen(min-h-dvh). Token-translated tells. - Composition —
ai/prefer-composer: a direct<PromptInput>render where<Composer>is the canonical chat input. Advisory, always — dropping to the primitive for a bespoke shell (a mention roster, say) is a documented escape hatch, so this never fails--strict. Quiet in a file that also renders<Composer>, in the file that defines it, in thePromptInputfamily's own modules/stories, and in any test. A file argues its own case with// brand-ui-audit-allow: ai/prefer-composer— which works on advisory rules only, never on a blocking one. - Content anti-slop — the "Jane Doe effect" (WP-15) —
slop-generic-name("John/Jane Doe"),slop-fake-number("99.99%"),slop-brand-name("Acme/Nexus"),marketing-buzzword(filler verbs). Advisory here (placeholders can be intentional); the audit reports them, and a reviewer decides.
These are cheap, exact, and CI-friendly. The register-gated/perceptual tells (anti-card, 3-equal-cards, motion intensity) and rendered contrast stay in Pass 2.
Pass 2 — rendered (cross-theme visual + contrast)
This is the high-signal pass and needs a browser. Use the agent-browser skill
to drive a running Storybook (default http://localhost:6007) or app:
- Enumerate the surfaces to check (Storybook
/index.json, or the app's routes). Pick a representative set: app shell, data table, chat, charts, flow, forms, overlays (opened), states (empty/loading/error), plus foundation (button, badge, alert). - For each theme (light, dark): navigate with a render
gate, screenshot, and read the pixels. Switch a Storybook story's theme via
&globals=theme:<light|dark>. Always wait for render before the screenshot (poll for content / fixed delay) — a screenshot fired during the loader is a capture bug, not a finding. - Measure contrast on the real pixels, oklch-aware. Computed colors here come
back as
oklch(), so anrgb()-only parser silently passes everything — convert oklch → sRGB → relative luminance, then ratio. Flag body text < 4.5:1, large text/UI < 3:1. (This is exactly how the brand green was caught at 3.61:1 white-on-green and 3.77:1 green-on-white.) - Check focus rings (tab through), hover/active/disabled, and that each theme
actually repaints (
document.documentElement.dataset.theme).
See reference/contrast-audit.md for the oklch contrast function and the capture-gate recipe, and reference/anti-patterns.md for the design smells.
Two ways to measure rendered contrast (the reference covers the first; the second is the more robust upgrade):
- Computed-color (default here): read each text element's computed
color+ effective background, convert oklch→sRGB→luminance, ratio. Accurate for the solid-token backgrounds brand-ui normally uses; blind to gradients/images behind text. - Screenshot-diff (upgrade, for gradient/image backgrounds): screenshot the
element, hide the glyph text (
color: transparent), screenshot again, pixel-diff to isolate glyph pixels, and take the p10 percentile contrast against the actually-rendered background. This is how a mature detector (impeccable'sscreenshot-contrast.mjs) avoids missing low contrast over a photo or gradient. Reach for it when text sits on imagery.
Evaluate (scored)
Run two independent passes then synthesize — form the design/heuristic read (Pass A) before the detector numbers (Pass B) enter judgment, so the deterministic output doesn't anchor the eye. Then score with the rubric in reference/ux-evaluation.md:
- /24 scorecard (accessibility · states & resilience · theming & tokens ·
consistency & hierarchy · visual anti-patterns · taste & anti-slop), optional
0–100 composite + a one-line "does this look AI-generated?" verdict that now
weighs content slop (the "Jane Doe effect"), not just visual tells. The taste
axis is register-gated — judge against the resolved taste profile from
Setup step 3 (
brand-ui info→taste) and state it in the report; product is restrained, brand is expressive. - 9-state inventory per component (default/hover/focus/active/disabled/loading/
empty/error/partial) — flag missing or ad-hoc states; check brand-ui's
EmptyState/Skeleton/ErrorState/LoadingStateare used, not bespoke markup. - WCAG 2.2 for designers (POUR + the 2.2 additions: 24px targets, focus not obscured, redundant entry, dragging alternative).
- Copy & microcopy (error = what+how, empty = what+how+why, verb+object buttons, destructive friction hierarchy), the content anti-slop check (the "Jane Doe effect"), and an ethics / dark-pattern scan.
- Taste pre-flight (ux-evaluation.md) — the final, register-gated QA gate (tokens-not-literals, real content, every state, motion honored-not-mandated, cross-theme contrast, hierarchy/layout) before a surface is "done".
Apply the reduction filter — if an element can be removed without losing meaning, recommend removing it; if a user would need to be told it exists, rework it.
Output — phased plan, then approval
Group findings by severity and present as a plan; do not edit components:
- P0 — broken / illegible / inaccessible (e.g. AA contrast failures).
- P1 — clearly hurts quality.
- P2 — polish.
Each finding: surface + theme, what's wrong, why it matters, and a concrete,
token-referenced fix (name the token or rule). Write the report to a dated
file (e.g. reports/visual-ux-<date>.md) with screenshot links.
Then report the findings to the user — for each: file:line (or
surface + theme), severity, and the concrete, token-referenced fix. This skill
reports, it does not fix: the user decides what to change. Don't edit
components as part of the audit.
Token discipline (what makes this on-brand, not generic)
Never recommend a raw color, a hardcoded radius, or an arbitrary value. Every fix
is a @brand token or a documented rule. If a needed visual concept has no token,
say so and route to brand-ui-theme to add it — don't invent a literal.
04 同仓库更多 Skills
brand-ui
Build UI with the brand-ui component system (@elabs-ai/components-* packages — ui, data, ai, flow, maps, charts, marketing, editor, viewer, terminal, tokens, icons). Use when working in a project that depends on @elabs-ai/components-ui or any @elabs-ai/components-* package, when adding/composing components, building dashboards, data tables, AI/chat surfaces, React Flow canvases, MapLibre maps, code editors, file/document viewers, app shells, forms, or marketing sections, when theming with the token system, or when the user mentions brand-ui, @brand, light/dark themes, or "our design system". Provides live project context, the real component API, composition patterns, and the rules that keep components token-driven, accessible, and theme-safe.
brand-ui-update-theme
Use when an existing brand-ui theme family should be improved from new material — updated brand guidelines, a new logo, product screenshots, a live site, feedback like "the green is off" or "match their new design system" — e.g. "update the qlik theme with these links", "refresh our theme from the new brand book", "/update-theme". For a brand with no theme yet, use brand-ui-create-theme.
brand-ui-theme
Create or retune a brand-ui theme (token work). Use when adding a new theme, re-branding the system to a customer's palette, adjusting global radius/spacing/surfaces, or fixing token-level contrast across themes. Use when the user says "new theme", "brand it for <customer>", "make corners less rounded", "dark theme", "adjust the tokens", or "our colors". Every change is a token in a theme stylesheet — never a hardcoded value in a component.
brand-ui-start
The front door for building UI with brand-ui — a router/concierge that asks what you want to do and hands you to the right flow. Use when someone is starting out and unsure where to begin ("help me with brand-ui", "where do I start", "I want to build something", "what can brand-ui do", "get me going"), or types /brand-ui-start. Routes to three flows — build a NEW app (brand-ui-new-app), improve/migrate an EXISTING app (brand-ui-migrate), or just help me USE brand-ui in an app that already has it (brand-ui). If the intent is already obvious (the person said "build me a dashboard" or "audit this screen"), skip the question and go straight to that flow.
brand-ui-registry
Curate the brand-ui shadcn-compatible registry (maintainer workflow). Use when deciding whether something belongs as an imported @elabs-ai/components-* primitive vs a copy-own registry block/template, when adding or editing a registry item, or when validating/building the registry for distribution. Use when the user says "add a registry item", "make this a block", "publish to the registry", or "package vs registry". For consuming registry items in an app, use the `brand-ui` skill (npx shadcn add).
brand-ui-new-app
Define-to-build — scaffold a new brand-ui app from a plain-language description (VP-02). Use when the user wants to START an app, page, or demo ("build me a sales dashboard", "I need an admin console for X", "new app", "scaffold a chat assistant", "create a landing page for a pitch") rather than add to an existing one. Runs a staged interview (quick 3-question mode or full 7-stage spec mode), writes an app-spec.md, then scaffolds from the matching template + playbook with every wiring point annotated and a starter CLAUDE.md so later agent sessions stay on-brand. For adding components to an existing app use `brand-ui`; for authoring library components use `brand-ui-component`.