# Audit and Quality Gates

## Contents

1. Audit dimensions
2. Severity and confidence
3. Required evidence
4. Maturity assessment
5. Quality gates
6. Report format

## Audit dimensions

Review the system across:

- scope and ownership;
- token architecture;
- component contracts;
- accessibility;
- responsive behavior;
- localization and content;
- theming and multi-brand behavior;
- implementation adapters;
- documentation;
- automated and manual testing;
- package distribution;
- versioning and deprecation;
- migration and adoption;
- performance and bundle impact;
- security and third-party risk.

Do not score only the number of components or tokens.

## Severity

| Severity | Meaning |
| --- | --- |
| Critical | Blocks safe release, creates broad accessibility exclusion, corrupts public contracts, or can break many consumers without practical rollback |
| High | Causes recurring product inconsistency, inaccessible critical interaction, major migration risk, or unstable public API |
| Medium | Creates maintainability, adoption, content, responsive, theme, or testing risk with available workaround |
| Low | Local refinement, documentation gap, naming inconsistency, or future resilience issue |

## Confidence

| Confidence | Meaning |
| --- | --- |
| Confirmed | Reproduced or deterministically verified in source, build output, or runtime |
| High | Strong static or repository evidence with limited ambiguity |
| Medium | Likely issue requiring runtime, design, consumer, or ownership validation |
| Low | Heuristic signal or candidate for investigation |

Keep severity and confidence separate.

## Required finding format

For each finding provide:

| Field | Content |
| --- | --- |
| ID | Stable identifier |
| Title | Specific contract or user problem |
| Severity and confidence | Separate classifications |
| Scope | Tokens, components, packages, products, themes, platforms, or routes |
| Evidence | Files, lines, resolved values, screenshots, runtime behavior, consumer usage, or test results |
| Impact | User, consumer, release, accessibility, maintenance, or migration effect |
| Root cause | Architecture, naming, tooling, implementation, governance, documentation, or adoption |
| Conservative correction | Smallest durable fix compatible with current constraints |
| Compatibility risk | Public API, visual, DOM, CSS, framework, package, or consumer impact |
| Verification | Exact automated and manual checks |
| Owner | Suggested accountable role or team |

## Static inspection

Run:

```bash
python scripts/mcp-design-system-engineer/inspect_design_system.py /path/to/project --format markdown
```

The script can identify:

- DTCG-style token files and token metadata;
- CSS custom properties and naming prefixes;
- Sass and Less variables;
- repeated hard-coded colors and dimensions;
- theme selectors and dark-mode signals;
- Bootstrap variables and overrides;
- component stories, tests, docs, changelogs, and package metadata;
- potentially public CSS selectors;
- deprecated markers;
- icon-font and raw asset signals;
- missing common system infrastructure.

Static findings are evidence, not a complete assessment. Confirm runtime cascade, generated output, component behavior, visual quality, accessibility, and actual adoption separately.

## Maturity assessment

Rate each dimension independently from 0 to 5 and explain evidence.

Do not average dimensions into a single score unless an internal dashboard requires it. A mature token pipeline does not compensate for inaccessible components or absent governance.

Recommended dimensions:

1. scope and principles;
2. token architecture;
3. component contracts;
4. accessibility and content;
5. responsive and localization behavior;
6. themes and brands;
7. documentation;
8. testing;
9. implementation and distribution;
10. governance and versioning;
11. migration and adoption;
12. measurement and support.

## Quality gates

### Token release gate

- schema valid;
- types valid;
- no unresolved references or cycles;
- required themes complete;
- deprecated token usage reported;
- generated artifacts deterministic;
- semantic color pairs validated;
- output changes reviewed.

### Component release gate

- contract documented;
- API review complete;
- default and edge states implemented;
- keyboard and accessibility behavior verified;
- narrow container, zoom, text scaling, long content, RTL, and themes tested;
- interaction and visual regression tests pass;
- package exports and framework adapters pass;
- migration and release notes supplied.

### Major release gate

- breaking changes enumerated;
- migration guide and codemods where safe;
- prerelease tested by representative consumers;
- deprecated usage inventory reviewed;
- support and rollback plan approved;
- documentation versioned;
- accessibility regression review completed.

## Report format

Default audit report:

1. Scope, assumptions, products, platforms, and exclusions.
2. Executive summary.
3. Current architecture and source-of-truth map.
4. Maturity assessment by dimension.
5. Critical and high findings.
6. Token findings.
7. Component and accessibility findings.
8. Documentation, testing, distribution, and governance findings.
9. Legacy and adoption risks.
10. Target architecture.
11. Prioritized roadmap: immediate, next release, structural.
12. Validation matrix and success measures.
13. Limitations and unverified areas.

Prefer actionable findings and dependency-aware sequencing over a large undifferentiated backlog.