Design System Cleanup Checklist + Playbook (Execution-Ready)

1. Purpose

A step-by-step playbook to audit, clean, and stabilize the component library so designers stop creating duplicates, developers ship consistent UI, and performance stays healthy.

2. Scope

• Applies to all project-specific and shared libraries.
• Covers tokens, components, variants, naming, usage, and performance.
• Used during scheduled hygiene (weekly/quarterly) and before major releases.

3. Success Criteria (define before you start)

4. When to Run

• Weekly: light sweep (30–45 min).
• Pre-Release: full cleanup.
• Trigger: team size change, big brand update, performance complaints, or code-library drift.

5. Roles (RACI)

A = Accountable, R = Responsible, C = Consulted, I = Informed

6. Pre-Flight (do this before touching anything)

• Duplicate the library file: LibraryName_backup_YYYYMMDD.
• Export current component list (names, IDs, instance count).
• Capture baseline metrics (success criteria table above).
• Announce read-only window to the team.

7. Cleanup Workflow (overview)

1. Inventory → 2) Token Normalize → 3) Merge & De-dup → 4) Variants & States Complete → 5) Naming & Structure Fix → 6) Usage & Orphans Sweep → 7) Accessibility Pass → 8) Performance Trim → 9) Publish + Changelog → 10) Migration & Follow-up

8. Detailed Checklist (use end-to-end)

8A) Token Hygiene

• All fills, borders, shadows use approved tokens (no raw hex).
• Typography styles applied (no manual overrides).
• Spacing uses 8px scale (no 5/7/13px fragments).
• Radius and shadows mapped to named tokens only.
• Failure fix: Batch-apply tokens; create missing tokens if patterns repeat.

8B) Component Hygiene

• Each component lives in its category page (Buttons, Inputs, Cards, Modals, Navigation, Alerts, Icons).
• Auto-layout and constraints set; responsive behavior verified.
• Properties exposed for size/icon/variant where applicable.
• No detached instances in published library.
• Failure fix: Rebuild as variants; reattach instances via “swap instance”.

8C) Variants & State Coverage

• Mandatory states present: Default, Hover, Active, Disabled, Error, Success.
• Data-driven: Empty, Loading, Permission where relevant.
• Focus/keyboard states represented for interactive components.
• Failure fix: Add missing states; document behaviors in component notes.

8D) Naming & Structure

• Naming scheme: Component/Variant/Size/State (e.g., Button/Primary/Medium/Hover).
• No visual names (no BlueButton).
• Frames/layers named: Label, Background, Icon_Left, Helper_Text, Error_Message.
• Version tags on major updates (v1.1, v1.2).
• Failure fix: Batch-rename; align pages to 01 Foundations / 02 Components / 03 Screens / 04 Archive.

8E) Usage & Orphans

• Components with 0 instances moved to Archive or deleted.
• Duplicates merged; most-used instance becomes the source of truth.
• Instance links in product files point to current published components.
• Failure fix: “Swap instance” in consumer files; leave deprecation markers for one sprint.

8F) Accessibility

• Text contrast ≥ AA; interactive elements ≥ 44px on mobile.
• Error messaging visible + descriptive (not color-only).
• Focus states visible and consistent.
• Failure fix: Adjust tokens and states; add helper text patterns.

8G) Performance

• Remove unused local styles and dead components.
• Consolidate icons into a single set (SVG, consistent stroke).
• Reduce nested autolayout depth where not needed.
• Failure fix: Flatten deep nests; replace raster with SVG where possible.

9. Duplicate Resolution — Decision Tree

1. Are two components visually and functionally identical?
2. → Yes: Keep the one with higher instance count; merge tokens/props; mark the other “Deprecated – do not use” for one sprint; then delete.
3. → No: If difference is intentional, convert into a Variant. If difference is accidental, normalize to a single source.

10. Deprecation & Migration

• Tag old components: Deprecated_DO-NOT-USE_until_YYYY-MM-DD.
• Communicate replacements with a table (old → new).
• Provide 1-sprint grace period; then remove deprecated ones.
• Run a “consumer projects” pass to swap all instances.
• Record all changes in the changelog.

Migration Table (example)

11. Exit Criteria (don’t publish until all hold true)

• 0 non-token styles.
• 0 missing mandatory states.
• 0 orphan components in published library.
• Duplicates resolved or formally deprecated.
• Changelog prepared.
• Dev team ack on impact.

12. Changelog (publish with the library)

13. Audit Log Template (keep per cleanup)

Severity: H = blocks release; M = fix before publish; L = backlog.

14. Practical “How-To” (fast actions)

• Find raw hex: search styles for # and replace with tokens.
• Find orphans: filter components by instance count = 0.
• Batch rename: apply pattern Button/* to Button/{Variant}/{Size}/{State}.
• Swap instances at scale: open consumer file → “Select all with same instance” → swap to new component.
• Measure performance: time-to-open the shared library before/after cleanup.

15. Weekly vs Quarterly Runbook

Weekly (30–45 min):

• Token drift check, missing states scan, new duplicates, orphans.
• Publish micro version (e.g., v1.4.1).

Quarterly (2–3 hrs):

• Full duplicate merge, icon set consolidation, archive sweep, accessibility pass, performance trims.
• Publish minor/major version (e.g., v1.5 / v2.0) with migration note.

Usage Notes

• Treat this as an operational ritual, not a one-off task.
• Keep the checklist, audit log, and changelog in the same folder as the library.
• Do not publish without meeting exit criteria.