Design System and Documentation in Figma
Tokens, components, and developer handoff.
Step 1: Audit and Scope
Inventory existing colors, type styles, buttons, and inputs across your app screens. Cluster duplicates — three similar blues should become one primary token.
Define scope: MVP system covers color, typography, spacing, and core components. Document principles in a cover page: who maintains the file, naming rules, and when to propose new components.
Step 2: Color and Typography Tokens
Create Figma variables or styles for color roles: primary, surface, border, text primary, text secondary, success, and error. Name semantically — color/action/primary — not color/blue-500.
Publish text styles for headings H1–H3, body, and caption with fixed size, weight, and line height. Align sizes to your 4 or 8 pt grid.
Step 3: Component Architecture
Build atoms first: icon button, text button, input field, checkbox. Compose molecules: search bar, form row, card header. Use variants for size and state instead of separate components per combination.
Document anatomy on a component page: padding, min height, icon slot, and label slot. Include do and do-not examples — correct primary button usage vs too many primaries on one screen.
Step 4: Spacing and Layout Rules
Document spacing scale: 4, 8, 12, 16, 24, 32, 48. Show how Auto Layout gap and padding map to tokens so designers and developers share the same numbers.
Add layout templates for page shells — mobile with bottom nav, desktop with sidebar. Templates speed new feature design and keep alignment consistent.
Step 5: Documentation Page for Handoff
Create a Documentation page with sections: Getting Started, Tokens, Components, Patterns, and Changelog. Each component frame lists props: variant options, text overrides, and interaction notes.
Link to Storybook or code repo if it exists. For dev-only teams, export specs via Inspect and attach redlines for motion duration and easing on interactive components.
Step 6: Governance and Iteration
Assign an owner for approvals — new components need a reason and a reuse plan. Version the library file and note breaking changes in Changelog.
Schedule quarterly audits: remove unused variants, merge duplicates, and validate contrast after brand updates. A living system beats a one-time PDF that goes stale in a month.
FAQ
Variables or styles in Figma?
Use variables for tokens that change by theme or mode — light and dark primary surfaces. Styles remain fine for typography and effects during transition. Many teams use both with variables driving color roles.
How many variants is too many?
If a component has more than a dozen meaningful combinations, split it or use nested instances. Variants should reflect real product states, not every theoretical edge case.
What belongs in written documentation?
Usage rules, accessibility notes, content guidelines, and when not to use a component. Specs alone — width and height — are insufficient for consistent product UI.