Design System Component Audit

Template Overview

As design systems scale across multidisciplinary product teams, UI debt, inconsistent token overrides, and undocumented component variants accumulate rapidly. The Design System Component Audit template establishes a rigorous evaluation matrix for design leads and frontend engineers. It tracks component health across code and design libraries, covering WCAG 2.2 accessibility states, responsive behavior, token adherence, and technical debt deprecations.

Markdown Template Structure

Copy the block below or click Download .md File to add this template directly to your personal vault:

---
title: "Component Audit: [Component Name / Category]"
date: [YYYY-MM-DD]
design_lead: "[[Design Systems Lead]]"
engineering_lead: "[[Frontend Architect]]"
library_package: "@org/ui-kit [vX.Y.Z]"
wcag_conformance: "WCAG 2.2 Level AA"
tags: [design-system, components, tokens, accessibility, ui-audit]
---

# Design System Component Audit — [Component Name]

## 1. Audit Scope & Inventory
- **Target Component:** `[e.g., Button / Modal / Combobox / DatePicker]`
- **Design Source (Figma):** `[Figma Library File / Component Link]`
- **Code Implementation:** `packages/ui/src/components/[ComponentName].tsx`
- **Current Production Usages:** [XX] instances across [YY] application views.

## 2. State & Interaction Matrix
| State | Figma Token Parity | Code Parity | Keyboard Focus Ring | Color Contrast Ratio | Notes & Deficiencies |
|---|---|---|---|---|---|
| Default / Rest | Complete | Complete | N/A | 4.8:1 (Pass) | Standard surface token applied |
| Hover | Complete | Incomplete | N/A | 5.2:1 (Pass) | CSS transition duration differs by 50ms |
| Active / Pressed | Complete | Complete | N/A | 4.6:1 (Pass) | Satisfies tactile response expectation |
| Focus Visible | Incomplete | Incomplete | Incomplete | 3.1:1 (Fail) | Focus ring clipped by parent overflow container |
| Disabled | Complete | Complete | N/A | 2.8:1 (Exempt) | Missing `aria-disabled="true"` attribute in DOM |
| Loading / Busy | Incomplete | Missing | Incomplete | N/A | Spinner component hardcoded instead of sub-component |

## 3. Token & Theming Adherence
- **Color Tokens:** Adheres to semantic palette tokens `var(--color-interactive-primary)` with zero raw hex color values.
- **Typography Tokens:** Line height properly mapped to typography scale `--font-body-md`.
- **Spacing & Radius Tokens:** Padding uses `--space-3` (12px); border radius aligns with global curve `--radius-md`.

## 4. Accessibility & Assistive Tech Evaluation
- **Screen Reader Announcement:** Tested with VoiceOver / NVDA. Announcing correct ARIA roles and expanded states.
- **Touch Target Sizing:** Minimum clickable dimensions measure 44x44px across responsive touch viewports.
- **Reduced Motion Support:** Respects `prefers-reduced-motion` media query by eliminating layout shift animations.

## 5. Remediation Plan & Jira Backlog
- [ ] Patch focus-visible ring styles in CSS module to prevent container clipping.
- [ ] Add `aria-busy` and semantic spinner component to loading state variant.
- [ ] Deprecate legacy hardcoded variants across checkout and customer portal screens.

Filled Real-World Example

Here is a realistic example demonstrating how this template captures actual deliberations:

---
title: "Component Audit: Modal Dialog Component"
date: 2026-10-09
design_lead: "[[Marcus Vance]]"
engineering_lead: "[[Sofia Kowalski]]"
library_package: "@acme/core-ui v3.8.0"
wcag_conformance: "WCAG 2.2 Level AA"
tags: [design-system, components, tokens, accessibility, ui-audit]
---

# Design System Component Audit — Modal Dialog

## 1. Audit Scope & Inventory
- **Target Component:** `ModalDialog` / `ConfirmDialog`
- **Design Source (Figma):** `Foundations v3 > Overlays > Dialog`
- **Code Implementation:** `packages/core-ui/src/overlays/ModalDialog.tsx`
- **Current Production Usages:** 47 instances across workspace settings, billing checkout, and auth screens.

## 2. State & Interaction Matrix
| State | Figma Token Parity | Code Parity | Keyboard Focus Ring | Color Contrast Ratio | Notes & Deficiencies |
|---|---|---|---|---|---|
| Backdrop Render | Complete | Complete | N/A | 6.5:1 (Pass) | Uses `--surface-backdrop-scrim` 60% opacity |
| Header / Title | Complete | Complete | N/A | 9.2:1 (Pass) | Strict h2 heading tag enforcement |
| Close Button Rest | Complete | Complete | Complete | 5.8:1 (Pass) | Proper 44px tap target preserved |
| Close Button Focus | Complete | Complete | Complete | 7.1:1 (Pass) | Dual 2px contrast ring renders cleanly |
| Scroll Container | Incomplete | Incomplete | Incomplete | N/A | Inner body scrolls without keyboard scroll focus |
| Escape Key Dismiss | Complete | Complete | N/A | N/A | Restores initial focus back to trigger button |

## 3. Token & Theming Adherence
- **Color Tokens:** Modal header and surface use `--color-surface-elevated` ensuring correct dynamic dark-mode contrast.
- **Elevation Tokens:** Box shadow maps directly to `--elevation-dialog-3` (0 20px 25px -5px rgba(0,0,0,0.3)).
- **Radius Tokens:** 8px rounded corners match `--radius-container-lg`.

## 4. Accessibility & Assistive Tech Evaluation
- **Focus Trapping:** Built-in focus trap successfully loops keyboard navigation between first and last focusable elements.
- **ARIA Attributes:** Enforces `role="dialog"`, `aria-modal="true"`, and `aria-labelledby="dialog-title-id"`.

## 5. Remediation Plan & Jira Backlog
- [ ] Add `tabIndex={0}` to overflowing scroll container with keyboard-scrollable instructions.
- [ ] Sync Figma token variables for max-width constraints (currently 560px vs Figma 600px).
- [ ] Update documentation site with mobile responsive viewport usage guidelines.

When to Use and When to Avoid

When to Use

• Use prior to major design token migrations or design system version upgrades.
• Use during quarterly accessibility compliance audits to verify WCAG 2.2 interactive states.
• Use when reconciling design differences between Figma assets and production code.

When to Avoid

• Avoid using for broad user research sentiment collection (use UX teardown or interview logs).
• Avoid using for full application performance benchmarks (use frontend profiler tools).

On-Device AI Integration

Summarize your recording in Oyma with this local instruction:

Review the component audit findings:
1. Flag critical accessibility failures that violate WCAG 2.2 Level AA.
2. Cross-reference token naming deviations against standard design token naming conventions.
3. Produce a prioritized sprint backlog of component bug fixes with estimated engineering points.
Output in structured Markdown.

Your data remains securely on your Mac with zero cloud exposure.