What a design system is, and what it is not
A design system is a shared set of decisions that a team reuses instead of remaking. It has four parts.
- Tokens: named values for colour, type, spacing, radius, shadow and motion, such as a surface colour or a space-4 gap. They are the single source for how the interface looks.
- Components: the buttons, inputs, dialogs, tables and navigation, built once in Figma and once in code, with every state defined.
- Documentation: when to use each component, how it behaves and what it must never do, with live examples.
- Governance: who owns the system, how changes are proposed and reviewed, and how a new version reaches every product.
It is not a UI kit, which is a file of shapes that shows how things look. It is not a PDF brand guide, and it is not a project that ends at handoff. A system is a product whose users are your designers and engineers, and it needs an owner. The short definition is in our design system glossary entry.
When a design system pays off, and when it is too early
A system pays off when many people build the same interface. The signs:
- Several designers, engineers or contractors build screens for the same product.
- The product runs on the web and on mobile and should feel like one product.
- Engineers keep asking the same questions about spacing, states and focus.
- You ship in English and Arabic, so every component has to work in both directions.
Signs it is too early
Before a product has found its users, a full system is a poor use of time. If the team is one designer and a couple of engineers and the screens change every week, build a starter set: colour, type and spacing tokens plus the ten or so components every screen needs, such as button, input, dialog, table and navigation. Grow it when the second team or platform arrives. The logic matches an MVP: build what the next release needs, but build it so it can grow.
How to build a design system, step by step
1. Audit what already exists
Capture every screen and sort the interface into buttons, inputs, cards and so on. It is common to find many near-identical buttons that differ by a few pixels. The audit shows what to merge and what to keep.
2. Define the tokens
Start with primitives: the palette, the type scale and the spacing scale. Add semantic tokens that name a purpose, such as text-primary or border-error, and let components use only those. That turns a dark theme, a second brand or a right-to-left variant into a change of tokens rather than a rewrite. A tool such as Style Dictionary can turn one token file into CSS, Swift, Kotlin and Flutter values.
3. Build the library in Figma and in code
Build the same components in Figma and in code, React and TypeScript for the web, Flutter or native code for mobile, with the same names, properties and states: default, hover, focus, disabled, loading and error.
4. Document it in Storybook
Storybook gives each coded component a live page with its variants, states and usage notes. Add a direction switch and a theme switch to the toolbar so every story can be reviewed in English and Arabic, light and dark. Accessibility checks can then run on every story.
5. Version and release
Use semantic versioning, so a breaking change is a major version, keep a changelog, and give removed components a deprecation period in which the old one still works and warns. Teams upgrade on their own schedule and nothing changes silently.
6. Set the contribution rules
Write down how a component gets in: a proposal with the problem and two real screens that need it, then design review, accessibility check, right-to-left check, documentation and code review. A short rule set keeps the system open without letting it fill with one-off variants.
Accessibility and right-to-left belong in the tokens
Adding these later costs more than building them in, because they touch every component.
- Tested colour pairs. Define text and background pairs that meet the WCAG contrast ratios, 4.5:1 for body text and 3:1 for large text and controls, so nobody picks a failing combination by accident.
- A focus ring token and a minimum target size, so keyboard and touch users get the same quality in every component.
- Logical spacing. Define padding and margins as inline-start and inline-end, never left and right.
- Type per script. Keep separate font stacks and line heights for Latin and Arabic, because Arabic needs a taller line box and no letter spacing.
- Icon direction. Mark each icon as mirrored or fixed, so arrows flip and logos do not.
- Direction as a mode. Treat left-to-right and right-to-left like light and dark: a mode every component and story can switch into.
The detail of Arabic type and layout is in our page on Arabic and right-to-left design.
Build your own or adopt an open-source library?
| Option | Good fit | Watch out for |
|---|---|---|
| Adopt a full library, such as Material UI or Ant Design | Internal tools and fast first versions | The look is theirs and deep restyling is expensive. Test right-to-left and accessibility on the components you use. |
| Headless primitives, such as Radix or React Aria, with your own tokens and styling | Brand-led products that need accessible behaviour without rebuilding it | You still build and document the visual layer. |
| Build from scratch | Large multi-platform products with a strict brand | The highest cost to build and maintain. Rarely justified at the start. |
Rule of thumb: adopt behaviour, own the tokens. Wrap library components in your own so you can swap them later, and test each one in Arabic before you commit.
Common failure modes
- Built in isolation. A library nobody asked for, which engineers route around.
- Design and code drift. Figma says one thing and the code another. Share the tokens and review both together.
- No owner. Without someone accountable, the system decays within a few releases.
- Tokens named by value. A token called blue-500 used everywhere tells you nothing. Name tokens by purpose.
- Right-to-left added at the end. Mirroring a finished system means touching everything. Make direction a mode from the first token.
How we run a design system project
A design system with reusable components is one of the deliverables of our UI/UX design service. Our method follows the steps above, scaled to the product.
- We audit your existing screens, or the clickable prototype from a discovery sprint, before drawing anything new.
- We define tokens first, including contrast pairs, type per script and direction, then build the Figma library and the coded components in step.
- Accessibility and right-to-left checks are part of the definition of done for each component.
- You see components in use on real screens at the weekly demo.
- We write down the contribution and versioning rules and hand the system over to your team.