# KADOM: A design system, from Figma kit to shipped package.

Case study by Debiprasad Sena ("Debi"), product designer. Plain-text copy of https://debiprasadsena.com/work/kadom, with the same words as the page.
Images are described by their captions.

KADOM is the design system behind Kairo. I started it as a Figma kit before the first release. After launch, as a designer who directs the code rather than typing it, I rebuilt it in Figma and in code — Claude as the execution layer, me on architecture and verification: audited, renamed, themed, documented and packaged.

- **Role:** Design-system owner, design and code
- **Timeline:** 7 weeks, from audit to version 1.0.0
- **Built with:** Figma, Figma Console MCP, Claude Code, React, Storybook
- **Scope:** 50+ components, 650+ tokens
- **Live:** Storybook docs (https://kadom.surge.sh/) · Live test app (https://kadom-testing.vercel.app/)

## 01 · Product first, system second

Basics: A design system is the shared set of decisions behind a product: foundations like colour, type and spacing, the components built from them, and the patterns those components form.

I didn’t start with components. I started with the product: what Kairo was for, and explorations of its screens, like My Journey and Browse. Only once I knew what those screens needed did I build a Figma kit: colour, typography, spacing and a few components.

Two decisions shaped that first kit. Kairo is content-heavy, so it went dark first, and its tokens were dark only. And because the product personalises around the goal a person chooses, I added six goal themes. The kit worked well for design, and I shared it with the marketing team so their work stayed on brand too.

[Image: The first Figma kit: dark only, a colour ramp for each of the six goals, the type scale, and early components like Option Tile.]

## 02 · Why it had to live in code

Basics: Tokens are named design decisions, like a colour or a spacing step, stored once and used by both the design file and the code, so the two can’t drift apart.

We needed to build fast to be ready for funding, so development started and the first release shipped. But in code, every component and every style lived in one repository. Even a small visual change meant a lot of developer work.

After launch, I took the initiative to build a real design system, not only in Figma but in code. I can read code and follow how it’s structured, but I can’t write it by hand. So I researched how others were doing it, and found a way to work with AI through MCP. That gave me the confidence to start.

- **Figma Console MCP** — Lets Claude read and change the Figma file directly: its variables, components and documentation.
- **Claude Code** — Builds, tests and checks the code, working from the same Figma file.
- **My product knowledge** — What shipped in the first release, and what the product really needs next.

> My idea, my verification. Claude was the execution layer.

## 03 · Measure before you fix

Basics: A healthy system is named consistently, documented, accessible, and built from real variants rather than one-off copies.

This time I wanted real structure, so I audited before building anything: the tokens, the components, and how the product actually used them. I ran the audit with Claude against common design-system criteria, and reviewed what it found.

- 79/100 — overall health of the first kit
- 5% — of components had a description
- 30% — of colour pairs met the contrast minimum

Source: From an audit Claude ran over the Figma file, which I reviewed.

The numbers set the priorities. Documentation and accessibility were the weakest areas, so they became the two things the new system had to do visibly better. The tokens were inconsistent, and many were simply missing.

One screen summed it up. The phone-number country selector in sign-up was hand-built: a search field and roughly 200 separately drawn buttons, one per country, with no shared component behind any of them. Its hand-off note described a trigger that opens a list and closes on selection. That is exactly what KADOM’s Phone Field does now: a country code that opens a searchable list, built from the same Input and Menu Item as the rest of the system.

> It was never a component gap. It was a pattern hiding behind 200 duplicates.

[Image: The country selector, before and after. The same job, now built from two components the whole system shares.]

## 04 · Naming and theming

Basics: Primitive tokens hold raw values, like a hex or a pixel size. Semantic tokens say what a value is for, like a surface or a border, and point to a primitive. Components only ever use semantic tokens.

Comparing every token family against every other surfaced seven real inconsistencies. Instead of fixing them one by one, I turned them into a written convention that every future token is judged against.

- **[tier]/[category]/[property]/[variant]** — General to specific, left to right. One path structure for every token.
- **One scale style per family** — Numeric or t-shirt sizes, never both inside one family.
- **subtle → default → strong → emphasis** — One emphasis vocabulary across surface, border, icon and text. “Base” is retired.
- **Mode name = token name** — Where a Figma mode is also a token (goal, theme, breakpoint), the two names match exactly.

| Concept | Before | After |
| --- | --- | --- |
| Default goal | start-a-business | new-biz |
| Growth goal | grow-business | grow-biz |
| Promotion goal | get-promotion | get-promo |
| Border tier | border/base | border/default |

Every rename was confirmed one by one against the live variables before it was applied.

This time the system needed two kinds of theme. A system theme, light and dark: dark stays the default, and light was added without changing a single dark value. And a custom theme: the goal a person picks, which colours every progress item. Each theme is a mode, a set of values the same tokens switch between, so a component never needs to know which theme it’s in.

[Image: The same screen in both system themes: drag to compare. The green of the progress items is the goal theme.]

[Image: The goal theme: the same Progress Bar, learning path and Checkbox Item in all six goal modes. No new components, just a different mode.]

**See the foundations live, in Storybook**
- [Theme](https://kadom.surge.sh/?path=/docs/getting-started-theme--docs) — Light and dark, six goal themes, motion and layout, switched at runtime.
- [Colours](https://kadom.surge.sh/?path=/docs/foundations-colors--docs) — The primitive palette and the semantic colours, read live from the tokens.
- [Typography](https://kadom.surge.sh/?path=/docs/foundations-typography--docs) — The shared type scale every component uses.
- [Icons](https://kadom.surge.sh/?path=/docs/foundations-icons--docs) — The icon set used across every component.
- [Spacing and sizing](https://kadom.surge.sh/?path=/docs/foundations-spacing-sizing--docs) — The spacing, sizing and radius tokens.
- [Elevation and blur](https://kadom.surge.sh/?path=/docs/foundations-elevation-blur--docs) — Shadows and blur, as tokens.
- [Motion](https://kadom.surge.sh/?path=/docs/foundations-motion--docs) — Durations and easing, with a reduced-motion mode.
- [Layout grid](https://kadom.surge.sh/?path=/docs/foundations-layout-grid--docs) — The responsive grid, breakpoint by breakpoint.

## 05 · Seven decisions that shaped it

Basics: A component is a single building block with real states, like a button. A pattern is several components composed for one recurring job, like a sidebar.

### Decision 01: Not a redesign.

Context: The first kit’s look already worked for the product. What didn’t work was underneath it.

Decision: Keep the same product and the same visual language, and give it a real token architecture.

Why: The problem was structure, not style. A redesign would have cost weeks and fixed nothing that was actually broken.

### Decision 02: Patterns are earned, not predicted.

Context: A pattern is expensive to keep in a shared system. Built too early, it fits one screen and forces the rest.

Decision: A pattern joins the system only once three or more real screens need the identical shape. Header, Sidebar and Bottom Nav were promoted only after six real screens confirmed them.

Why: Until real screens ask for a pattern, it stays out. That’s what makes it a rule, not a guess.

### Decision 03: Two cards, not one.

Context: The live product had a family of cards that looked alike. The obvious move was one card with options.

Decision: Measured, not just named, they did two different jobs: the content card helps you discover, the course card tracks your progress and expands into lessons. So Content Card became a component on its own, and the course card is planned as a pattern built from it and a Lesson Item.

Why: Two things can look the same and do different jobs. The job decides the component, not the resemblance.

[Image: Content Card only previews. The course card tracks progress: in the test app, Lesson Items make a course card, and course cards make the learning path.]

### Decision 04: Option Tile gave way to Checkbox and Radio.

Context: The first kit had Option Tile: one component with 120 variants, and props that were hard to tell apart, like selectionMode, selectionStyle and isSelected. It handled very different choices: age ranges and content preferences in the old, longer sign-up, and the milestone checklist in My Journey. It’s still in the live product until KADOM is adopted.

Decision: KADOM leaves it out. Instead, two small building blocks, Checkbox and Radio, and two components built on them, Checkbox Item and Radio Item, which add a visible label and a line for a description or an error. In KADOM, the milestone checklist is a list of Checkbox Items.

Why: One tile trying to be every kind of choice needed 120 variants. Two small building blocks cover the same ground and can go anywhere a choice is needed, like sign-in or a question Kairo asks, and each Item has a few plain props: size, fill, state, label and description.

[Image: Option Tile’s selectionMode made one tile a button, a radio or a checkbox. KADOM gives each job its own component.]

### Decision 05: Modal absorbs Bottom Sheet, but not Popover.

Context: Bottom sheets and modals behaved the same way; only their position differed.

Decision: Bottom Sheet became a position of Modal. Popover stayed separate: it’s anchored to something and doesn’t block the page, which is a different job.

Why: Merging is good until it hides a real difference. Knowing where a merge stops matters as much as the merge.

### Decision 06: The brand colour stays rare.

Context: The lime accent is reserved for Premium, around 1–2% of the interface.

Decision: I got this wrong early, using lime on send buttons and focused inputs, then corrected every component built up to that point. Everyday interaction now uses neutral tokens.

Why: A colour that means Premium stops meaning anything once it’s everywhere.

### Decision 07: Hover is a layer, not a new colour.

Context: Hover and pressed states were separate solid colours, and they disagreed: one darkened on hover while another lightened.

Decision: I replaced them with one translucent layer over the unchanged colour: white on dark surfaces, black on light ones.

Why: One rule that works on every surface and in both themes, instead of a colour to maintain for each.

## 06 · Building it in code, with Claude

Basics: In a design system, Figma and code must describe the same thing. The work is keeping them identical, not just similar.

Every component went through the same loop, from its spec in Figma to a real browser.

- **Every component:** Read the spec in Figma → Check it against the live file → Build → Test → Check in a real browser

When the written spec and the live file disagreed, the live file won. That caught dozens of small mistakes the written docs had carried.

The choices that shape a system stayed mine. When the build reached a real fork, like whether a dropdown should manage its own opening and closing, or which library to trust for floating menus, Claude laid out the options and I decided.

**What Claude did**
- Ran the audit at a scale no one would do by hand.
- Checked every component’s documentation against its live values.
- Wrote, tested and packaged the code.
- Rebuilt 65 documentation sections onto one template.

**What stayed mine**
- The idea, and the decision to build it at all.
- Every rename, confirmed line by line.
- Every call on scope, patterns and product shape.
- Verifying the result, in Figma and in the browser.

[Image: One login screen, twice. Left: the Figma frame, with its spacing tokens showing. Right: the same screen in the test app, built from KADOM. The two small differences, a longer email placeholder and a show-password icon, are props I tried out in the test app.]

**Open it**
- [From Figma to Code](https://kadom.surge.sh/?path=/docs/getting-started-from-figma-to-code--docs) — In the Storybook: a real screen from the Figma file, rebuilt from KADOM, token by token.
- [Kairo’s chat, live](https://kadom-testing.vercel.app/kairo) — In the test app: Kairo’s chat, composed only from KADOM components.

> When the documentation and the live data disagree, trust the live data.

## 07 · Shipping it as a product

Basics: A package is the system bundled for other teams to install. Its version number tells them what changed, and whether it’s safe to update.

This was the part I knew least about, and enjoyed most. I learned how packages are built, prepared and shared, and how real versioning works in code. KADOM ships as two packages, the tokens and the React components, at version 1.0.0.

- **Two packages** — Tokens and components, installed like any other library.
- **Real versioning** — Fixes, new components and breaking changes each move a different part of the version number, so teams update on their own schedule.
- **Ready for native apps** — Every Figma variable also carries its iOS and Android name, ready for a shared token pipeline.
- **Ready for any AI** — Skills, rules and machine-readable component details live in the repository, so anyone can work on it with an AI assistant.

Documentation was treated as part of the product: one master template for every component in Figma, 65 sections, written as a current reference rather than a history of changes. Storybook is the front door for developers.

Our engineering lead agreed to take KADOM on, and a frontend developer is testing it now. To prove the package works outside its own repository, I built a test app that installs it the way any team would. Every screen in it uses only KADOM components and KADOM’s own tokens.

Building the test app was the real test. As the package’s first consumer, I ran into what a system only shows in use: layouts that broke at other widths, a video player that fought with touch, props the components were missing, and tokens the package didn’t export yet. I logged twelve fixes for the next version, each with the reason and the fix.

[Image: Browse on the test app: search, content types, Kairo’s guide and the course lists. All of it is KADOM, installed as a package. It follows this site’s theme: switch light and dark to see both.]

**Try it**
- [The test app](https://kadom-testing.vercel.app/) — The installed package, running real Kairo screens in light and dark.
- [Storybook](https://kadom.surge.sh/) — Every component, pattern and foundation, documented.

## 08 · What it takes to last

Basics: Governance is how a system decides what gets in, who owns it, and how it stays alive.

Building it was the part I could do myself. Keeping it alive isn’t. So I made the case to leadership for what a design system needs to become infrastructure: an owner with protected time, a first product that fully adopts it, a clear way for teams to request changes, and a few numbers everyone can see.

> A design system with no dedicated time is a hobby, not infrastructure.

I spent about a year exploring design systems before this, and KADOM is the first one I took all the way from zero to a shipped package. I’m still learning from it. The build itself took seven weeks. What I learned is that the components were never the hard part. Measuring first, naming well, saying no to patterns that aren’t ready, and making it installable by someone else were.

Every time I opened version 1.0.0, I found something to improve. Core text already meets WCAG AA in both themes; the quieter greys are next. But each change means the full journey: add it, pack it, distribute it, and let teams consume it.

> A design system is never polished work. It always evolves.

## KADOM, in plain words

- **Design system:** The shared decisions behind a product: foundations, the components built from them, and the patterns they form.
- **Token:** A named design decision, like a colour or a spacing step, stored once and used by both Figma and code.
- **Primitive token:** A raw value with no meaning attached: a hex, a pixel size, a duration.
- **Semantic token:** A token that says what a value is for, like a surface or a border. It points to a primitive.
- **Mode:** A set of values the same tokens can switch between, like light and dark.
- **System theme:** Light or dark. Dark is the default; light is opt-in.
- **Goal theme:** The accent colour of the goal a user picked, applied to every progress item.
- **Component:** A reusable building block with real states, like a button or a checkbox.
- **Variant:** One version of a component, like a small, disabled or danger button.
- **Pattern:** Several components composed for one recurring job, like a sidebar.
- **MCP:** A way for an AI assistant to work inside another tool, here the Figma file itself.
- **Package:** The system bundled so other teams can install it, with a version number.
- **Storybook:** The live website where developers browse and try every component.
