Tokens before anything else
Fix colours, spacing and type sizes as named tokens first, then let everything reference them. Changing a theme stops meaning changing components.
Variables carry semantics, components carry structure
Variables answer 'what changes in dark mode'. Components answer 'what does this look like here'. Mix the two and batch changes become impossible.
Write the docs next to the component
Put usage notes and do-not-use cases in the component description. It gets read far more often than a separate docs site.
Versioning and deprecation
A component library with no deprecation markers becomes something nobody dares delete from two years later.
Tools in this playbook
Based on a real rollout; product behaviour reflects the version at publication. Tell us if something has changed.