Design Systems for SaaS: From Wireframes to Production

A SaaS design system is not a Figma library. It is the contract between design and engineering that says this button, in this state, on this surface, looks and behaves like this. The Figma library is one expression of that contract. The component code is another. The documentation is the third. Skip any one and the system drifts.

Tokens before components

Every system I have shipped starts with tokens. Color, spacing, radius, shadow, type scale, motion. Tokens are the smallest unit of design decisions. Components are compositions of tokens. When a tenant wants their brand green instead of your default gold, you swap a token. You do not repaint 40 components.

:root {
  --color-accent: #c9a961;
  --color-surface: #0e0e10;
  --space-4: 1rem;
  --radius-md: 6px;
  --shadow-card: 0 1px 0 rgba(255,255,255,0.04) inset;
}

[data-tenant="acme"] {
  --color-accent: #2e7d32;
}

Component states are the spec

A button is not a shape with a label. It is idle, hover, focus, active, disabled, loading, and error. Each state has a visual and a behavioral contract. If your Figma component only shows idle, your engineers will guess at the rest, and they will guess differently per module. Document every state, even the ugly ones.

• idle: default appearance, no interaction.
• hover: clear affordance, not a 1% brightness shift.
• focus: visible to keyboard users, not just mouse users.
• loading: disables input, shows progress, does not layout-shift.
• error: explains what went wrong, not just that something did.

Tenant customization without forking

In multi-tenant SaaS, tenants want to feel like the product is theirs. The temptation is to fork the component library per tenant. The correct path is to keep one component, expose tokens, and let tenants override tokens. Forking multiplies your maintenance cost by your tenant count. Token overrides keep it constant.

A design system that cannot be customized without forking is not a system. It is a screenshot you have to maintain.

Documentation that engineers actually read

The best system docs I have written are short, visual, and live next to the code. A one-line description, a visual of every state, the props table, and a copy-paste example. Anything longer goes unread. Anything that lives only in Figma goes unread by engineers. Treat the docs like a product, because they are.