Broom

Broom Design

Broom Design removes AI slop from interfaces: the generic, machine-made look of default UI. It keeps your UI work at the level of a good design studio, on any stack, and it respects the product's own design system.

Every path below is relative to this skill's folder, the folder that holds this SKILL.md. The scripts do the deterministic part: reading the code, the numbers, the validators, the files. You do the judging and the writing: reading documents and screenshots, reviewing screens, writing copy.

Always, whenever you write or change UI

1. Their system comes first. Before writing UI, find what the product already declares: its tokens (CSS custom properties, a Tailwind theme, a tokens file, a theme in Dart, Swift or Kotlin), its shared components, its radii, spacing scale, fonts and blurs, and how its surfaces separate (a fill, a stroke, or both). Build with those. Slop is drift from their system toward generic defaults, not distance from anyone's taste.
2. What their system does on purpose is theirs. A declared blur, gradients, pill-shaped controls, surfaces separated by a stroke: keep them. Accessibility floors hold whatever the system says: contrast, focus, names, keyboard paths.
3. Read before you write. Always references/studio-hand.md, then the files the table below names for the task.
4. Check before you finish. Run detect.mjs --changed (below). Fix every must, use their own token or component for every drift, weigh each taste line, then walk references/checklist.md for the screens you touched. UI work is not done while a must is left.
5. No system yet? If the product has none and the task is more than a small change, offer design first.

Commands

In Claude Code type /broom audit; in other agents ask for "broom audit" in the same words. When a request or its arguments name one of these, read the command file and follow it step by step.

• audit: find the slop and write SLOP_REPORT.md, changing no code. Read commands/audit.md and follow it.
• fix: fix SLOP_REPORT.md, one finding per edit. Read commands/fix.md and follow it.
• check: a quick pass over the files you changed. Read commands/check.md and follow it.
• design: a design system from scratch, from a short brief. Read commands/design.md and follow it.
• redesign: a new look for a product that already exists. Read commands/redesign.md and follow it.
• handoff: a finished Figma file becomes rules for the coding agent. Read commands/handoff.md and follow it.

Scripts

Both sit in this skill's own folder, under scripts/. Take their full path from the folder this SKILL.md was loaded from. If you do not know that folder, look for broom in .claude/skills/, .agents/skills/ or .windsurf/skills/ of the repository, then in the same places under your home folder (~/.claude/skills/, ~/.codex/skills/, ~/.cursor/skills/ and so on). Run them from the repository root.

detect.mjs, the checker

It needs Node 18 or later and nothing else, and it makes no network calls.

Copy code
node <skill-dir>/scripts/detect.mjs              # the whole repository
node <skill-dir>/scripts/detect.mjs src/app      # one folder
node <skill-dir>/scripts/detect.mjs --changed    # files changed against git HEAD, plus untracked ones
node <skill-dir>/scripts/detect.mjs --json       # the same, as data

Without git, pass the folder you changed instead of --changed.

It reads the product's own system first (tokens, radii, spacing, fonts, blurs, how surfaces separate), then prints one line per finding, path:line message [detector-id], in three groups:

• must: universal defects. Fix them.
• drift: off their own system. Use their token or component instead.
• taste: patterns that read as machine-made. Fix them in code you write; elsewhere only when asked.

A "Kept as theirs:" block lists what their system does on purpose, with the reason. Never change those. The last line is N findings in M files · score S (band): clean under 3, light 3–10, noticeable 10–20, heavy 20 and over.

Fix the code, not the check: a value moved into a variable or a comment is still the same value. A finding that is wrong for this code, because the code is right as it stands, is left alone and named in your summary.

design.mjs, the system

It does the deterministic half of design, redesign and handoff; the command files say when to run each part.

Copy code
node <skill-dir>/scripts/design.mjs example                                     # a brief.json template: every field, its values, its default
node <skill-dir>/scripts/design.mjs plan brief.json                             # what to write into fill.json: instructions, schema, parameters
node <skill-dir>/scripts/design.mjs render brief.json [fill.json] --out <dir>   # the whole pack, after the validators
node <skill-dir>/scripts/design.mjs handoff <file.fig>                          # what to write into fill.json for a Figma file, and its findings
node <skill-dir>/scripts/design.mjs handoff <file.fig> [fill.json] --out <dir>  # the pack of a Figma file, and its findings

It needs Node 18 or later; handoff needs 22.15 or later, because Figma files are zstd-compressed. It makes no network calls, writes only inside --out and never deletes, so render into an empty folder. Warnings (an unknown key, a stack from another product type, an id not in a catalogue) go to stderr: read them. A refusal goes to stderr with exit code 1.

Where the rules are

A reference such as §6a.32 means: open the file for §6a and read item 32. Each file starts with its section's heading.

Limits

The scripts read code and files; they render nothing. Hierarchy, density and contrast on the real screen are seen only if you can open it in a browser. When you cannot, say that those were checked by reading.