The design system audit we run before every rebuild

Everything visual should trace back to a small set of named tokens: colors, type scale, spacing units, radii, shadows, and motion durations. The first thing we do is dump every literal value actually used in the codebase and compare it against the token list. A healthy system has a handful of grays; a rotting one has forty near-identical hex codes because everyone eyedropped their own.

Count the divergence, because it is the single best proxy for design-system health. If you find 30 distinct spacing values instead of a clean scale like 4, 8, 12, 16, 24, 32, you have found the reason your UI looks subtly inconsistent and your engineers argue about pixels in code review. The fix is to collapse the values to the nearest token and lint against raw literals going forward.

Next, catalog every component and look for duplicates wearing different names. It is astonishingly common to find ButtonPrimary, PrimaryBtn, and CTAButton coexisting, each with subtly different padding and hover states, none of them the canonical one. Every duplicate is a place where a fix has to be applied three times and will be applied to two.

For each component, check the ratio of props to variants. A component with 25 boolean props is not a component, it is a configuration language that no one understands, and it is a sign the abstraction is wrong. The remedy is usually to split it into a few focused components or to move to composition, and to delete the variants that no live screen actually uses.

Spacing inconsistency is the tell that separates a designed product from an assembled one. Screenshot your key screens and overlay the grid; you will quickly see where margins drift by a few pixels between cards that should match. The human eye reads this as “cheap” long before it can name why.

We check that layout uses a consistent system, whether that is an 8-point grid, a spacing scale, or a layout primitive like a Stack component, rather than ad hoc margins sprinkled per screen. Standardizing on layout primitives that only accept token values makes the whole class of drift impossible, because there is no way to type an off-scale number.

Accessibility problems are design-system problems in disguise, and they are cheapest to fix at the token and component level. Check color contrast against WCAG AA, which wants 4.5 to 1 for body text; a surprising amount of on-brand light-gray-on-white text fails, and fixing the token fixes it everywhere at once. Verify that interactive targets meet the 44 by 44 point minimum and that focus states actually exist.

Then test with a real screen reader and keyboard, not just an automated linter. Automated tools like axe catch missing labels and roles, but they cannot tell you that your tab order is nonsensical or that a custom dropdown is a keyboard trap. Building these checks into the shared components means every team inherits accessibility instead of re-litigating it per screen.

Do not try to fix everything at once, and do not start with the visible screens. Start at the bottom of the stack, with tokens, because a correct token layer makes every component above it easier to fix and prevents new drift. Then consolidate components, then relayout screens, in that order, because the reverse wastes work you will redo.

Add guardrails as you go so the debt cannot silently return: lint rules against raw hex and off-scale spacing, a Storybook or component gallery as the source of truth, and visual regression tests with a tool like Chromatic so an accidental change to a shared button shows up as a red diff, not a support ticket three weeks later.