Auditing the current project

An audit is the foundation of any design system. Until you know what already exists in the product, you cannot decide what to standardize, what to remove, and where to start the library.

The goal is not to “find someone to blame,” but to gather facts: which UI elements live in code and mocks, where styles diverge, which patterns repeat, and which accessibility and maintenance risks have already piled up.

What the audit covers

1. Component inventory — a catalog of all UI elements and their variations.
2. Style analysis — colors, fonts, sizes, spacing, radii, shadows.
3. Pattern detection — recurring layouts and interaction scenarios.
4. Problem identification — inconsistency, duplication, a11y, docs gaps.
5. Opportunity mapping — quick wins, mid-term, and long-term improvements.

Step 1. Component inventory

How to collect:

• manually walk key screens;
• search the codebase (Button, Modal, classes like .btn);
• screenshots and side-by-side comparison;
• if available — export from Figma/Sketch.

What to record:

• Buttons (primary/secondary/ghost/icon/disabled);
• Inputs and form fields;
• Cards, modals, navigation;
• Typography patterns;
• Loading / empty / error states;
• Icons and illustrations.

Minimal note format:

## Buttons
- Primary: blue, large, rounded — used on Checkout and Settings
- Secondary: gray, medium — 3 visually different variants
- Ghost: transparent + hover — only in the mobile header

An inventory is useful when every variation has context: where it is used and how it differs.

Step 2. Style analysis

Collect actual values, not “how it should be.”

const colors = {
  primary: ['#3B82F6', '#2563EB', '#1D4ED8'],
  gray: ['#F3F4F6', '#E5E7EB', '#9CA3AF', '#1F2937'],
  error: ['#EF4444', '#DC2626']
};

const fonts = {
  sans: ['Inter', 'Roboto', 'system-ui'],
  mono: ['Fira Code', 'monospace']
};

const spacing = ['4px', '8px', '10px', '12px', '16px', '20px', '24px'];

Watch for “breaking” values: 10px in a scale that is otherwise multiples of 4; four nearly identical blues; two different sans-serifs without roles.

Step 3. Patterns and problems

Layout patterns: grids, container width, header/footer, navigation. Interaction patterns: form submit, opening modals, dropdown, loading, errors.

Typical findings:

• inconsistency — 5 “primary” buttons, 3 shades of brand color;
• duplication — the same Input in three folders;
• accessibility — weak contrast, no focus/keyboard, missing ARIA;
• performance — duplicated styles and heavy icons;
• documentation — props and usage examples undocumented.

Step 4. Deliverable: what to ship from the audit

A good audit result is a set of artifacts, not a feeling that “things are messy”:

1. component-inventory.md — catalog of components and variations.
2. style-analysis.md — collected colors, fonts, spacing, radii, shadows.
3. problems-found.md — problems by category.
4. Priority matrix — Impact × Effort.

| Problem | Impact | Effort | Priority |
|----------|--------|--------|----------|
| 5 primary button styles | High | Low | High |
| No props documentation | Medium | Medium | Medium |
| Text contrast < 4.5:1 | High | Low | High |

Then the opportunity map:

• Quick wins (1–2 weeks): unify buttons, spacing on a 4px base, basic a11y fixes.
• Medium (1–2 months): core library, tokens, Storybook.
• Long (3–6 months): full DS, docs site, team processes.

How to run an audit in reasonable time

1. Pick 5–10 key screens, not the whole product at once.
2. Walk inventory → styles → problems.
3. Compare code and design: Figma vs production gaps are a separate debt category.
4. Align on a top-10 problem list with the team.
5. Only then plan the first tokens and components.

Criteria for a “good enough” audit

• components are categorized;
• styles are collected at least for color, typography, and spacing;
• key inconsistency/duplication is named;
• there is a priority matrix and “where to start” recommendations.

That package becomes the input for the tokens and components modules.