Design Systems — Token & Component Architecture

• · DS1 — Tokens are three-layered (reference/system/component); components consume system/component tokens only.
• · DS2 — Every component ships with usage docs, prop reference, and accessibility notes — undocumented components don't count as published.
• · DS3 — Component APIs are designed for the anticipated range of use cases up front, not grown reactively prop-by-prop per feature request.
• · DS4 — Breaking changes to shared components go through a deprecation path (old + new coexist for a transition window), not an instant swap.
• · DS5 — A named owner/team governs additions and changes to the system; ad hoc unreviewed additions are not merged.

• · A raw hex/px value appearing in a feature codebase outside the design-system package → should have been a token.
• · A one-off component built inside a feature that resembles an existing system component → check if it should be a system component variant instead.
• · A component prop list growing past ~8-10 props → API design smell, consider compound-component restructuring.
• · Consumers copy-pasting a component and modifying it rather than using props/composition → the API doesn't support their use case; extend it deliberately.

• · Token pyramid bypass — feature code with raw hex/px values because "the token didn't exist yet," instead of adding it properly.
• · Undocumented components — a component exists in the codebase but no docs, so every consumer reads the source or asks in chat.
• · Prop accretion — a Button component with 20 props added reactively over two years, each solving one feature's need, none designed together.
• · Instant breaking changes — a shared component's API changed in one PR with no deprecation window, breaking every consumer simultaneously.
• · Unowned system — no one reviews additions; the "design system" package becomes a junk drawer of inconsistent one-offs.

• [ ] Feature code uses tokens, not raw values. (DG1)
• [ ] Base interactive components have full state/a11y coverage centrally. (DG3)
• [ ] Published components documented (usage, props, a11y). (DG2)
• [ ] Breaking changes have a deprecation path. (DG4)
• [ ] Shared additions reviewed by a named owner. (DG5)

• Design Systems Handbook

Este pack cita las siguientes fuentes registradas en el índice bibliográfico:

• webDesign SystemsAlla Kholmatova (Smashing Magazine, 2017)
• webDesign Systems HandbookDesignBetter / InVision
• webDesign Systems RepoJad Limcaco