Product Design Systems

03

A design system is a product, not a folder

A design system is not a collection of beautiful components waiting to be admired. It is a product with its own users (designers and engineers), its own roadmap, its own quality bar and its own measure of success — whether the product stays consistent when nobody is looking.

• It is a product, not a folder — it has users, a roadmap, releases and maintenance; a static gallery belongs on a wall, not in a codebase.
• It answers a real cost — every re-decided button, rebuilt dialog and relitigated colour is the price of having no system.
• Consistency becomes the default — the easy path and the consistent path are the same path, so quality does not depend on discipline.
• The system has customers — designers and engineers vote with their hands; if they keep reaching for it, it is working.
• It pays for itself or it dies — a system that costs more to use than to bypass will be bypassed, quietly and forever.
• Leadership owns it — token governance, component reviews and migration priorities need an owner, or the system withers into a museum.

We build systems like products because that is the only way they survive contact with a team that is trying to ship.

04

Design tokens: the single source of visual truth

Tokens are the foundation: named decisions for colour, spacing, type, radius, shadow, motion and more, defined once and consumed everywhere. When the source of truth is a token, a brand change is an edit to one file — not a search-and-replace across fifty screens.

• Named decisions beat raw values — 'surface-2' is a decision; '#F4F6FA' is a recipe; tokens carry intent with the value.
• A scale, not a rainbow — colour is a small set of roles with deliberate shades, not a palette of one-off hex values.
• Spacing is a rhythm — the grid gives every gap a name and a reason, so space stops being an accident of the moment.
• Type is a scale — sizes, weights and line heights are tokens with hierarchy built in, not font-size roulette.
• Tokens cross the fence — the same tokens drive design files, web CSS, mobile styles and docs, so designed equals shipped.
• Tokens are data — stored as JSON, exported to every platform, and versioned like code.

On a money product the balance number, the fee row and the error text all inherit the same scale no matter which rail settled the payment — M-Pesa, a card, a wallet or a bank — which is why a user never meets two different looking money screens.

05

The colour system and contrast discipline

Colour is the fastest way to look consistent and the fastest way to look chaotic. Our palettes are built as a system of roles — primary, success, danger, warning, neutral — each with a job, so colour means something consistently and contrast stays provable.

• Colour has jobs, not moods — every token is a role with a behaviour; success is green everywhere because green means success.
• Contrast is checked in the system — tokens are validated against contrast ratios before they ship, not discovered failing after.
• States derive from one base — hovered, pressed, disabled and focused are computed from tokens, so no screen improvises a shade.
• Brand colours are controlled — a loud brand colour gets a set role; it does not get free rein to fight every component.
• Dark mode is a second deck — the dark palette is a full, deliberate set of tokens with its own contrast pass, not an inversion filter.
• Charts and data survive both themes — money, status and currency colours are chosen to remain legible in light and dark.

A user should never guess what a colour means from screen to screen; in our systems the colour already told them.

06

A type scale that scales

Typography is the interface's loudest voice. We define the scale, weights and rules once, with the display, heading, body and caption hierarchy the product actually needs — and the money numbers get their own discipline.

• One scale, five voices — display, heading, body, caption and small exist before any screen invents a 17.3px font.
• Hierarchy is the scale — size, weight and spacing carry the pecking order, so a screen communicates without shouting.
• Money gets tabular numerals — balances, fees and totals align in columns and never jiggle as they change.
• Legibility at arm's reach — minimum sizes are set for a phone held in a moving matatu, not a desk monitor.
• Line height is a token — paragraph spacing rules are consistent, so content never looks crammed or abandoned.
• Localisation holds the line — the scale survives languages that run longer, so the design does not break on translation.

Type is how a user recognises 'this is the amount, this is the fee, this is the truth' without reading a word; the scale makes that recognition effortless.

07

Spacing, rhythm and the grid

Spacing is where products look either engineered or allergic. A base unit and a grid give every gap a reason; rhythm makes screens feel calm, predictable and fast to scan.

• A base unit, doubled — the 4-point scale (or 8-point where content is denser) gives every gap a name.
• Gaps are tokens, not guesses — space-2, space-4 and space-8 mean the same on every screen, by definition.
• Density is a decision — each surface gets an explicit density level (comfortable, compact, tight) applied from tokens.
• Alignment is structural — the grid keeps vertical and horizontal edges honest, so nothing floats by chance.
• Rhythm supports scanning — consistent grouping lets a user read a screen's shape in one glance.
• Responsive collapse is tokenized — breakpoints and re-flow follow the system, so mobile is not a surprise layout.

The grid is boring on purpose — because a user should feel the calm rhythm of a screen without ever being told it is there.

08

Components: the library engineers actually consume

The heart of a design system is the component library — buttons, inputs, dialogs, chips, toggles, lists and tables rebuilt once with every state and behaviour, and consumed by every screen. The test of a component is not how good it looks in a gallery; it is how fast an engineer chooses it over building fresh.

• Components carry their states — default, pressed, disabled, loading, error and success live inside the component, not in each screen.
• Props are the language — a clear, documented API lets engineering compose screens without reading design PDFs.
• Accessibility is inside — focus, keyboard, labelling and screen-reader behaviour are the component's job, solved once.
• Theming is inside — the component adapts to light and dark from tokens, so screens never re-theme by hand.
• Behaviour is tested — component tests prove the dialog blocks scroll, the toggle maps to the right key and the form validates.
• Adoption is measured — teams dogfood the library; screens built without it are exceptions that need a reason.

A library that engineers default to is a library that works; ours is measured by being the easy path, every weekday, on every screen.

09

Component anatomy and API design

Every component is a contract: what it renders, what it accepts, which states it owns and what accessibility behaviour it promises. We design that contract before styling it, because the API is what dozens of screens will depend on.

• The contract comes first — props, states, slots and events are specified before the pixels, so the component is predictable.
• Composition over kitchen sinks — components nest and share primitives instead of growing a shape-shifting prop per team.
• Every state is a design decision — a component without its error, empty and busy states will be improvised per screen.
• Semantics are in the API — a button knows it is a button, a list knows it is a list, for assistive tech and for maintenance.
• Breaking changes are managed — APIs evolve through deprecation and codemods, not silent behaviour swaps.
• One canonical variant — a slight difference is a component's keyed variant, never a copy pasted and edited in a screen.

Designing a component API is like designing a tiny product for dozens of engineers; every good decision compounds across every screen it powers.

10

Documentation that stays alive

A design system nobody can understand is a museum. Documentation — why the tokens exist, how the components behave, when to use which state — is the system's user manual, and it must live beside the code so it cannot go stale.

• Docs are co-located — component code and its documentation evolve together, so one cannot rot behind the other.
• Usage rules beat opinions — 'use the danger dialog when money will move' is a rule a reviewer can enforce.
• Playgrounds show behaviour — interactive examples (click it, break it, flip the theme) teach faster than paragraphs.
• Token catalogs are searchable — a designer finds 'error' and lands on the right token with its contrast proof.
• Docs answer 'when not to use' — telling teams when a component is wrong is as valuable as showing when it is right.
• Living, not printed — a frozen PDF is a corpse; the docs update with the code or they are not documentation.

A new engineer should be productive on the system by day three; that is the standard our documentation is written to.

11

Theming: light, dark and branded, built once

A real product needs more than one theme — light for the office, dark for the evening, branded variants for partners or campaigns. Theming built into the token and component layer means all of them come free, and none of them breaks a screen.

• Themes are token sets — a theme is a named deck of tokens, not fifty screens of bespoke CSS.
• Components render any theme — because tokens flow through components, a new theme never revisits every screen.
• Brand theming is isolated — a client or partner theme changes accents and surfaces without forking components.
• Contrast is re-verified per theme — every themed deck passes the same contrast gate before it ships.
• System preference is respected — light and dark follow the device, with an in-app override that remembers.
• Theming is a feature, not a fight — the moment a client asks for a variant, the system answers in tokens, not in tears.

On KodiiPay, dark mode and an eye-resting balance screen were delivered as themes, not as a re-design — because the tokens had already done the work.

12

Accessibility baked into the components

Accessibility is the discipline with the worst retrofit economics: adding it after the screens exist means touching every screen. Solved once inside the components, it comes free with every future screen — which is why we solve it there, and only there.

• Focus is a component promise — visible focus, logical order and sane keyboard behaviour ship inside the component.
• Labels are structural — accessible names, roles and descriptions are part of the component's contract.
• Colour never carries meaning alone — icons, text and patterns accompany colour, so no user relies on hue.
• Motion has an off switch — every animation respects reduced-motion at the system level.
• Live regions announce changes — toast, spinner and status updates are spoken to assistive tech, not just painted.
• Automated checks run with builds — axe runs over the component library itself, catching regressions the day they land.

New screens inherit accessibility instead of renegotiating it — which is the only way a growing product stays inclusive.

13

Versioning: the system evolves with the product

A design system that freezes dies; a design system that churns annoys. We version the system like a dependency — releases, changelogs, deprecation and migration paths — so it evolves with the product without breaking the screens that trust it.

• Releases, not fires — tokens and components ship in released versions with changelogs, not as silent edits.
• Semver discipline — breaking changes get a major release and a migration path; patches ship without drama.
• Deprecation is slated — a component's replacement is announced, documented and codemodded before the old one dies.
• Teams upgrade on a clock — a known cadence keeps the library current without a painful big-bang migration.
• The changelog is the history — decisions, reasons and examples live in the log, so future teams know why.
• Versioning tech is borrowed, not invented — the system uses the same release machinery as the codebase it lives in.

The product and the system ship on the same heartbeat; when the product changes, the system changes with it — never around it.

14

Contribution and governance, not a bottleneck

A design system with one gatekeeper becomes a bottleneck; a system with no governance becomes a fork. We run a lightweight, fast contribution model — a clear path from 'I need this component' to 'it is in the library' — so the system grows with the real product instead of in a vacuum.

• A clear contribution path — request, propose, build with the system team, review, release; the route is known.
• Fast reviews keep the queue warm — the governance team reviews in days, not quarters, or teams route around it.
• Patterns over pixels — the review judges behaviour and accessibility first, taste in service of the product second.
• The system team is funded — a library nobody is paid to maintain is a library that rots in place.
• Usage data decides — the components teams actually use get the investment; the museum pieces get retired.
• Contributors are credited — engineers who build library components are named and celebrated, so contribution is prestige, not chore.

A design system that serves the roadmap but never chokes it is the balance we aim for on every engagement.

15

Adopted because it is faster, not mandated

The moment a design system is slower than the shortcut, it starts dying — silently, through every screen built without it. We build the library around what saves time, which is why adoption happens because it is the easy path and lasts because it keeps paying.

• The easy path is the system path — a component an engineer can grab and trust beats rebuilding one by a wide margin.
• Time-to-screen is the metric — if a fresh screen takes an hour instead of a day, the system has already won.
• Mandates only buy compliance — rules make teams use the library resentfully; savings make them choose it eagerly.
• Dogfooding keeps it honest — the system team ships real screens through the library, so the components are proven, not theoretical.
• Intricacy is the killer — a component that requires a degree to configure gets bypassed; simplicity is a feature.
• Adoption is measured and fed back — coverage stats and build times are reported so the team sees the payoff.

We do not force teams into the system; we make them faster inside it, and the library wins on the merits.

16

Design systems fail when treated as a gallery

Most design systems do not fail from bad tokens or bad components. They fail because a team built a beautiful gallery nobody was paid to maintain or adopt — and then real product work bypassed it, quietly and permanently. We name the failure mode openly because avoiding it is half the craft.

• A gallery is not a system — components nobody is funded to maintain and teams are not helped to adopt are artefacts, not infrastructure.
• Beauty without ergonomics dies — a gorgeous component that is awkward to configure will be re-built per screen.
• Unfunded systems rot — governance, contributions and migration need a standing owner; goodwill is not a budget.
• Dogfooding or disconnect — a system team that never ships product screens drifts into a library that misses the real problems.
• Perfection is the enemy — waiting for the perfect component means shipping none; ship stable, version it, improve it.
• The real test is the second year — adoption at launch is enthusiasm; adoption after twelve sprints is proof.

We would rather ship a small, used, maintained system than a beautiful, unused museum — and we tell clients so before we start.

17

Testing the system itself

The design system is code, and it gets tests like any critical code. Component behaviour, accessibility, theming and regressions are verified automatically, so the library's promises are provable rather than embodied.

• Behaviour tests on components — interactions, states, forms and focus are unit-tested inside the library.
• Accessibility checks run in CI — axe runs across every component and every theme with every build.
• Visual regression catches drift — component screenshots are compared across releases so styling cannot quietly change.
• Theming is a test case — every component is rendered in light and dark and asserted intact.
• Keyboard flows are scripted — tab order and shortcuts are exercised like user journeys.
• Consumption is tested — representative screens built from the library are regression-tested so real usage stays green.

When a component ships with its tests, 'trust the library' is an evidence-based instruction, not a leap of faith.

18

Design-tool and code integration

The seam between design files and code is where systems leak. We close it with tokens that flow both ways, components mirrored in the design tool, and handoff that hands over actual artefacts instead of screenshots.

• Tokens flow into code — design tokens export as code artefacts on release, so styles cannot drift between tool and build.
• Components live in the tools — the design tool hosts the same component set, so designers build with the real atoms.
• Handoff hands over data — measurements, tokens, states and copy travel with the design, not as a screenshot and a prayer.
• Bidirectional change works — a token rename updates the design file, the codebase and the docs together.
• Platform parity — tokens export to web and mobile so one decision renders the same in both.
• Tooling does not own the system — the source of truth is the shipped code; design tooling mirrors it, never competes.

The prototype, the design file and the built product share one vocabulary, which is why what the user finally sees is what was agreed.

19

Migration: paying down inconsistency without a big bang

Existing products rarely get the luxury of a clean redesign window. We migrate into the design system incrementally — screens converted as they are touched, high-traffic paths converted first, behaviour preserved throughout — so inconsistency is paid down without ever halting the business.

• Start with tokens — introducing the scale, palette and spacing first improves every screen without touching layout.
• High-traffic first — the most-seen screens get the components first, so the visible payoff comes early.
• Convert by touch — screens migrate when they are being changed anyway, so no parallel mountain of work.
• Behaviour before beauty — each conversion preserves behaviour exactly; cosmetics change, outcomes do not.
• Legacy patterns are tracked — an inventory of not-yet-migrated patterns keeps the debt visible and accountable.
• Measure the green — the share of screens on library primitives is reported as a number, so progress is provable.

A competent migration finishes the job; a heroic big-bang redesign usually gets cancelled by the second sprint — which is why we route around heroics.

20

Owning the system past launch

A design system's first release is the beginning, not the finish. Ownership after launch — reviews, releases, contribution, sunsetting, the second-system effect — is what separates a living library from a monument, and we stay for it.

• The second release counts — a v1 that never ships a v2 was a project, not a system; we plan the roadmap past day one.
• Sunsetting is scheduled — retired components get an announced end with a migration, so the library does not hoard skeletons.
• The second-system effect is resisted — the urge to rebuild the whole library in the new hot framework is a risk we manage.
• Usage keeps being measured — adoption, coverage and build-time savings are reviewed on a clock, not at launch.
• Docs stay true — documentation is updated in the same release as the code it describes, forever.
• Ownership is someone's job — the system has a named owner with time, budget and authority, not an enthusiast.

We hand over a living system with a roadmap and an owner — not a handover deck and a best-wishes email.

The toolchain

The design systems toolchain

The machinery that turns one designer's taste into a consistency engine an entire product inherits — from tokens to tested, versioned components.

Lifecycle

The design system lifecycle — from audit to living standard

Building a design system is a product program, not a design task. The lifecycle we run starts with the product's real pain and ends with a system the product keeps paying for.

Closing

More than development

A design system is how software stays consistent when it grows — the reason fifty screens still feel like one product a year after launch. Our system work covers:

A design system is not the components. It is the discipline around them: tokens that flow, code that is tested, docs that stay true and a team that is paid to keep it alive.

We build design systems that get adopted because they are faster, survive because they are maintained, and make the product look owned — not decorated.