A design system that keeps web and mobile in sync

I ran into each of these problems on a real project before I started building CDS.

1. Web and mobile drift apart

On a meeting platform, five people spent eight months building, each in their own direction, and no shared component layer ever emerged. The codebase ended up with three UI frameworks and four dropdown libraries. On a marketplace, the dashboards and the mobile app did share a library, but the public site went its own way.

The usual tools make divergence free. Platform.select puts a branch wherever it is convenient, and conditional imports let any file diverge. Neither leaves a trace, and nothing fails when they multiply.

What CDS does: it moves the platform split one layer below the call site, so the code that uses a component never has to check the platform. createTheme() turns a token into a string that resolves per platform, so ${theme.color.fg.default} behaves the same everywhere. Shared style recipes sit above that layer and both platforms apply them; they differ only in the trigger, :hover on the web and pressed on native. There is one definition of each color, so colors cannot drift apart.

The login screen shows the result: its component call is byte-identical in all three apps.

b768aa14a346  apps/web/app/LoginScreen.tsx        Next.js 16, RSC
b768aa14a346  apps/spa/src/routes/LoginRoute.tsx  Vite SPA
b768aa14a346  apps/mobile/App.tsx                 React Native 0.87

LoginForm.tsx is a single file of 135 lines with no native twin. It is assembled from Box, Button, Card, Input and Text, and the platform split happens inside those primitives.

The wrapper around it differs: on the web a Box centers the form, on the phone a SafeAreaView holds it, and the API URL is different. Those differences come from the platform and the product, and the design system adds none of its own.

2. Figma and the code are two sources of truth

I have run into this everywhere. On a white-label product with thirty brands, a plugin exported the tokens from Figma. That was automated, but it worked in one direction only, and the tokens easily fell behind the design. On most projects, the only link between Figma and the code is a person copying hex values.

Design changes on its own schedule and code on another, and without a mechanism between them the two are correct at the same moment only by accident.

What CDS does: design tokens arrive from Figma automatically over an MCP server, with a manual path as a fallback. The token layer is a package: core depends on tokens, and ui depends on core, so a change enters in one place and nobody has to search and replace it across the code.

3. Conventions written in a README stop being followed

On a marketplace with nineteen repositories, the same queue helper had been copied into seven of them, and nothing in the setup prevented it.

Nothing enforces a convention that is only written down, so it lasts until the first week nobody has time for a careful review.

What CDS does: every invariant has a check, and the build fails as soon as one is broken.

That is ~2,450 lines of verification, plus an ESLint plugin with four rules.

The rule that holds the architecture together is that a pattern must not have a .native variant. It is checked by pattern-native in verify-conventions.ts, which fails CI across 11 subjects. That rule is why the login screen stayed shared, and it will keep the screen shared after I stop paying attention.

CI runs the same chain instead of reimplementing it: pnpm verify plus three real builds, for Next, Vite and Metro. The real builds are there because next build is the only place where the 'use client' rule is actually verified, and a check that runs only in a script could pass while the real build fails.

4. Every new product starts its component layer from zero

I hit this while building three products of my own. Without a shared library, each of them would grow its own buttons, forms and modal, and the three products would end up with three sets of bugs.

What CDS does: it is a package that my financial platform already uses, and this site is built on it too.

It is a full component set: primitives (Box, Text, Button, Input, Switch, Slider), forms (Form, Field, Select, RadioGroup, OTPInput, PasswordField), overlays (Modal, Popover, Menu, Drawer, Tooltip, Toast), navigation (Link, Tabs, AppBar, TabBar, Breadcrumbs) and data (Table, Pagination, Accordion).

I measured what sideEffects: false does: an entry that imports only Box went from 253,075 B to 241,309 B. The trap is documented next to that setting. @cds/tokens must not be marked false, because then reset.css is dropped and the layout collapses without a single error. Nothing in the toolchain reports that failure, so the note sits where the next person will look.

5. Naive multi-brand theming multiplies the variants

One construction product is sold under more than thirty brands. Built naively, with a separate version of every component for each brand, its hundred components would become three thousand variants to keep up to date.

What CDS does: components refer to colors only through token names. A brand is added by supplying a new set of token values, and no component changes. The approach was proven on that construction product, and in CDS it has been part of the architecture since the first commit.

38 of 74 components have a native twin, which sounds as if half the system had diverged. In fact, the twins sit almost entirely in one layer:

33 of the 38 twins import no other component. They are leaves that translate a single platform element, div to View or input to TextInput, and do nothing more. The split sits at the bottom of the tree, which is why nothing above it needs to know about it.

A twin is allowed for only three reasons, and two of them have nothing to do with elements.

A different element. This covers 33 of the 38 twins. The change is mechanical and contained, and the components above never see it.

A different event. Tooltip.native exists because there is no hover on a touch screen, so the trigger is a long press, deliberately without a delay. On the web, delayShow prevents flicker while the cursor crosses a row of icons. A long press already signals intent, so a delay would only make the tooltip feel broken.

A different window. NativeSelect.native exists because a system picker must sit above the keyboard, and the only way to a separate native window is an RN Modal. The shared Portal hands the tree to the host, which would leave the list underneath the keyboard. That failure shows only on a device, and only inside a form.

The remaining three twins import exactly one component each and do not change the picture.

No pattern has a twin at all, and that is enforced: pattern-native in the verification layer fails CI across 11 subjects as soon as one appears. Modal shows that a hard case can stay shared, with its portal, focus management and measurement, and LoginForm shows that a whole screen can.

When a pattern needed a split, I left the pattern shared, extracted the primitive whose only difference was the element and gave that primitive the twin. It happened four times under pressure, which is why I treat it as a principle. The extracted primitives include PositionedLayer, DialogActionsRow and MenuSeparator.

I reviewed all 75 components the system had at the time and found 188 issues. They came down to three root causes, and the toolchain catches none of them: the typecheck, ESLint and the build all pass.

A label on an element with no role. accessibilityLabel on a node with no role is announced by neither platform. On the web, aria-label on a bare div does nothing, because the ARIA specification does not let a generic role take an author-supplied name. On native, accessibilityLabel without accessible is never read at all. Nine components had this bug, and the correct pattern already existed in the same package, where Icon always pairs its label with role="img".

An inherited prop that never reaches the element. Omit<BoxProps, …> leaves id, a11yRole, accessibilityLabel and pointerEvents in the contract, but a branch that does not destructure them passes them into ...box, and from there into a style helper that returns only $ props. Nothing complains, because an omitted prop is simply undefined, which is valid. Four sibling components wired three different subsets of these props: one wired all four, two wired two each, and one wired none.

A comment describing an earlier version of the system. A note describes a limitation, the limitation is later removed, and the note stays. This is the most insidious class, because a reader trusts the comment and never tries what has been possible for months. A worse variant is a JSDoc block shifted by one prop, so one prop carries two descriptions and its neighbor carries none. That text is generated into the catalog, where it becomes the public documentation.

Knowing why the three tools stayed silent matters more than the count of 188, because it decides whether the next bug of the same kind gets caught. Two of the three causes are now covered by verification rules, so catching them no longer depends on a review.

If I did it again, I would run that review when the system had 30 components, long before it reached 75. The same three causes were already present then, and correcting them would have cost an order of magnitude less. All 188 issues are fixed; coverage for aria-label and tabindex is still open.