Naming and System Hygiene

Set naming conventions, versioning, and cleanup cadence for the design system.

---

Learning Goal

• Naming for components/tokens (kebab/camel, prefixes).
• Versioning (semver-like) and changelog rule.
• Deprecation: mark, deadline, replacement.
• Monthly hygiene checklist.
• Apply across all Playbook assets.

---

Why This Matters

• Without hygiene the system rots.
• Newcomers ramp faster.
• Deprecation prevents cruft.

---

Explanation

• Naming: component.button.primary, token color.brand.primary.
• Versioning: semver-ish, release note required.
• Deprecation: flag + replacement link + timeline.

---

Examples

Bad: “New Button Final FINAL”.

Good: button/primary/v1.2 + changelog + deprecated button/legacy/primary.

---

Guided Exercise

1. Create naming table (component, token, file).
2. Write a changelog template.
3. Define deprecation process.

Independent Exercise

Run a hygiene audit on one component family; mark deprecated items.

---

Self-Check

• Naming exists.
• Changelog template ready.
• Deprecation documented.

---

Optional Deepening

• Semver: https://semver.org
• Design system maintenance: https://uxdesign.cc/maintaining-design-systems-7d3c34c3f0c3