UI Taste

Most UIs that look cheap have the same problem: too many one-off values. Six greys that should be one, eleven font sizes, padding of 13px next to 16px. Consolidating them into a few tokens fixes more than any new component library would.

1. Lint and save a baseline

python3 scripts/ui_lint.py src --json > /tmp/ui-before.json   # keep this for step 4
python3 scripts/ui_lint.py src                                # readable report with file:line examples
python3 scripts/ui_lint.py src --exclude 'src/legacy/*' --exclude '*theme.generated.css'

It reads .css/.scss/.less, <style> blocks, inline style attributes and objects, styled/css template literals, and Tailwind classes in class/className and cn()/clsx()/cva() calls in .html/.vue/.svelte/.astro/.jsx/.tsx (--include-js adds .js/.ts). It skips node_modules, dist, build, vendor, *.min.*, minified files and CSS with a /*! license banner. Exclude generated themes yourself: a 20,000-line UI kit stylesheet will swamp the score.

Each category scores weight x health (0 to 1); the exact formulas are in --help. A category with nothing to measure gets full marks and shows n/a. Exit codes: 0 ok · 1 score below --fail-below N · 2 nothing to scan.

Limits: it scans with regexes. It does not see the cascade, media queries, the Tailwind config or the rendered page. Contrast is only checked where it can resolve both colours (literals, var(), shadcn-style --x: 222 47% 11% tokens, Tailwind classes that map to a CSS variable). Light-theme tokens are measured and .dark overrides are skipped.

2. Look at the page

If a browser or screenshot tool is available, capture the main screens at desktop width and at 375px before you change anything. Then check what the lint can't see.

Each view should have one primary action. Two filled accent buttons side by side means neither of them is primary. Body text should be left-aligned inside one container width, with edges that line up from section to section. Paragraphs read best at 45 to 75 characters per line (max-width: 65ch or max-w-prose). The generic look also shows up in layout: a gradient hero over a centred stack of identical cards, emoji standing in for icons, glass blur on every panel.

3. Fix by consolidating into tokens

Start with the categories that lost the most points, and fix each one as a set instead of patching values one at a time.

1. Pick the scale from what is already there. The report lists every font size in use, so keep the common ones as steps (for example 12/14/16/18/20/24/30/36) and move the rare ones to the nearest step. Do the same for spacing in multiples of 4, radii (say 4, 8 and full) and shadows (sm, md, lg).
2. Write the tokens once, as custom properties on :root for plain CSS, @theme { --color-brand: ...; } in the CSS entry file for Tailwind v4, theme.extend in tailwind.config.js for Tailwind v3, or a _tokens.scss partial.
3. Replace the literals with the tokens. In each near-duplicate group keep the most used value, which the report lists first. Once brand is in the theme, text-[#3b82f6] becomes text-brand.
4. Take neutrals from one family (not gray and slate both), keep one accent, and use red, green and amber only for status. Fix contrast by darkening the text, not by changing the brand colour.
5. Swap z-index: 99999 for a short named set (dropdown, sticky, modal, toast). Remove an !important once the selector it was fighting is fixed.

4. Re-lint and compare

python3 scripts/ui_lint.py src --baseline /tmp/ui-before.json   # Score: 81/100 (was 46, +35), with per-category change
python3 scripts/ui_lint.py src --fail-below 70                   # CI gate once the team agrees on a floor

Take the same screenshots again and compare them side by side. The page should look calmer and the same overall. If the layout moved or a brand colour changed, revert that part.

Report

Before and after score per category, the tokens you added, the five biggest changes with file:line, before and after screenshots if you took them, and what you left alone and why (for example a 13px value that aligns an icon on purpose).

Rules

Don't change brand colours, fonts or the layout structure without asking; propose the change and show it. Don't add a UI library or CSS framework to get consistency. Don't chase the score: a one-off value that is right for the design stays, with a line in the report saying why. Leave vendored, generated and third-party styles alone and exclude them from the lint. For a full accessibility audit (keyboard, screen readers, ARIA) use a11y-fixer; this skill only checks colour contrast.