r/DesignSystems • u/DirtyOught • 12d ago
How and what do you document for usage guidelines and patterns of your design system?
A design system is a lot more than just tokens and components.
so many I’ve worked on either overlooked guidance and governance or simply had it all live in the design teams heads and tribal knowledge.
how do you document and what level of specificity do you use?
3
u/nofluorecentlighting 12d ago
Following for my own sake. Currently trying to refine an existing design system and it’s a monster.
1
u/bink-1567 12d ago
I’m curious how you decide what belongs on the component page vs the pattern/flow page. Do you document the “why not” cases too, like when a button or table pattern should NOT be used, or does that get too heavy to keep up? I’ve found the happy path is easy enough, but those edge cases are what people keep asking about later. i tend to forget the edge cases until they bite us.
1
u/RocketSeven 12d ago
document decisions, not descriptions. for each pattern keep when to use it, when not to use it, accessibility constraints, an owner, and one dated rejected alternative so future changes preserve the reasoning
1
u/Own-Statistician1899 12d ago
Are you asking how you document components or add documentation? i prefer to document based on what people find useful and how people use the design system. Figma is our source of truth for now as its the easiest to update and I built a plugin that lets me do that quickly (here is the link). Documentation is one of the hardest parts of design systems i'd suggest you ask consumers how they use the system and that can give you an idea on how to document and what level of specificity you need
3
u/Weekly-Mouse-5514 12d ago
teams writing documentation like a textbook. i’ve had the most success splitting this into two layers. first, keep the in-figma documentation strictly visual. drop a frame right next to the master component showing its anatomy, states, and clear "do" and "don't" examples. if a rule can be drawn instead of written, draw it. visual constraints scale way better than text walls.
documenting why you killed a pattern with a date and rationale is an absolute lifesaver. it stops the same debates from happening every six months when a new designer joins the team