# Design System Audit Inventories what an interface is actually built from, and reports the distance between that and the system it is documented to use. ## Deliverable One Markdown document, `design-system-audit.md`, in the structure set out under **Output** below. It is read beside **Accessibility Audit** and is the input to any consolidation work that follows. ## Required inputs - **Access to what the interface is built from** — stylesheets, component source or the design files the build is made from. Something a value can be read out of. - **The documented system, or a statement that none exists** — drift is reported against a baseline, and a baseline nobody stated is not one. - **The boundary of the audit** — which product, which surfaces and which branch are in scope. If access is absent, stop and report it. An inventory assembled from screenshots or from memory records impressions, not values. ## Optional inputs - Token, variable or theme definitions, wherever they are declared - Usage data showing which components are rendered and how often - Build output or a dependency graph showing what imports what - The themes, platforms and densities the system must cover - Earlier audits and the decisions they produced - The people who maintain the system, and what they already know is wrong Absent optional inputs narrow what the audit may claim, not how it reports. A component whose usage cannot be counted is recorded `usage unknown`, never as unused. ## Execution **1 — Fix and record the boundary.** List the files, directories and design files that were read, and those that were in scope but could not be reached. Everything after this step is a claim about that list and nothing wider. **2 — Inventory the values.** Collect every colour, type, spacing and radius value that appears, each with the file it was found in. Count the distinct values on each axis. The count is the finding: an axis with one value and an axis with many are different problems. **3 — Separate tokens from one-offs.** For each value: defined centrally and referenced, hard-coded where it matches a defined token, or hard-coded where it matches nothing. The second is drift; the third is an undocumented addition. Record every place each one is used. **4 — Inventory the components.** Name, where it is defined, everywhere it is used, and how many usages there are. A component with no usages is dead. A component with one is a candidate for absorption, recorded as such rather than condemned. **5 — Find the duplicates.** Components doing the same job under different names. For each pair or group: what they share, what differs, and what a merge would have to keep from each. A difference nobody can explain is itself a finding. **6 — Compare the built system with the documented one.** Three lists: documented but not built, built but not documented, and present in both but divergent. Where they diverge, the built value is the one users receive and is labelled so. **7 — Order the consolidation candidates.** Rank them by how many call sites a change touches, taken from the counts in steps 3 and 4, and state for each what it would break. Do not recommend a merge whose blast radius could not be counted. ## Output `design-system-audit.md`, in this order: - **1. Scope and date** — what was read, what was in scope but unreachable, and when - **2. Value inventory** — per axis: the values found, how many are distinct, and the file each came from - **3. Tokens and one-offs** — per value: `token`, `hard-coded match` or `undocumented`, with every place it is used - **4. Component inventory** — name, where defined, usage count or `usage unknown`, and `in use`, `single-use` or `dead` - **5. Duplicates** — the components doing one job, what differs, what a merge must keep - **6. Drift** — documented but not built, built but not documented, present in both but divergent - **7. Consolidation candidates** — ordered by call sites touched, each with what it would break - **8. Missing information** — what could not be counted or located, and who can supply it ## Validation The audit is ready when all of these hold: - Every finding cites the file it was found in - Every value in section 2 is classified in section 3 - Every component in section 4 carries a usage count or `usage unknown` - A value or component with no usages is reported as dead, not as a violation - Section 6 names the baseline it compared against, or records that none was supplied - Section 1 lists what was out of reach as plainly as what was read Fail the run if a finding appears with no file behind it, or if a count appears that reading the supplied material did not produce. ## Failure handling - **No access to the source** — stop. Report that there is nothing to inventory, and that an audit of screenshots is a review of appearances. - **No documented system** — produce sections 1 to 5 and 7, and mark section 6 `no baseline supplied`. Report the built system as the baseline in fact, and name who would have to adopt it. - **Design files and build disagree** — record both values, name both sources, and raise the divergence in section 8. Label the built value as the one users receive; do not average them. - **Usage cannot be counted** — mark the component `usage unknown` and leave it out of section 7. An uncounted component is never reported as dead. - **Partial access** — audit what was reachable, mark the rest `NOT AUDITED — `, and state that an unaudited surface is not a clean one.