Design Systems

A design system tells the AI what your UI is actually made of — your colors and spacing, your components and their props, your usage rules, and the import paths that make them real code. With one attached, generated UI looks like your product instead of generic markup you throw away.

Every app already has one. If you never touch this, you get cdbx's default and everything just works.

Rolling out. Design Systems is being enabled gradually — if you don't see a Design System tab in an app's settings, it isn't switched on for your account yet.

Where you see it

An app's Settings → Design System names the one it's using. Everything you own, plus cdbx's catalog, is on Account settings → Design systems.

Picking one when you create something

• New app — the "New app" dialog has a Design system row. Pick one, or leave it on your default.
• Quick Plan — the planning flow shows the same chips above the final "Start Building" step.
• Plain vibe prompt — click + → Design system to pick one from a menu, or just name it in what you type ("using my Acme design system") and cdbx matches it for you. Do neither and it uses your account default.

Anything you don't pick falls back to your account default, so there's never a wrong answer here.

Changing it later

There are three places, and each decides one thing.

Which design system this app uses — open Settings → Design System on the app. It's one row: a dropdown, grouped into From cdbx, Yours, and one section per team you're in (named after the team, e.g. Acme (team)) so a shared team system never looks like a private one, with a one-line description under each entry. Pick one and the next message you send generates against it, no reload needed. Pick None and the AI stops following or checking against any system.

What you own, and your default — Account settings → Design systems. There's a Manage design systems button next to the dropdown that takes you straight there. Two sections:

Your design systems — only what you actually brought: an MCP server, a Figma file, a tokens file, an npm package, one you wrote, a combination, or a remix. Here you can:

• See what each one holds — a row of its colours, and counts like "342 tokens · 12 components · 2 guidelines". A system that arrived empty says so, instead of looking identical to a working one.
• See how many apps use it, so you know what a change affects.
• Rename, refresh, or delete it. Deleting detaches the apps using it rather than breaking them: they keep the colours they already have and simply stop following a design system.

cdbx design systems — the shared catalog. You can't rename, edit or delete these; they're not yours. What you can do is star one as your account default, or Remix it (below).

What every account can build with — that's the catalog, and only an admin changes it.

Remixing

You can't edit cdbx's design systems, because everyone uses them. Remix gives you your own editable copy: it appears under Your design systems with a token editor already open, and it's yours to rename and change.

A remix is a snapshot. If cdbx later changes the system you remixed, your copy doesn't move — which is the point. It has no Refresh for the same reason: there's no upstream to re-read.

Two defaults

New apps need a design system before you've picked one, so there are two levels:

1. Your account default — the star on your Design systems page. Every app you create starts with it.
2. cdbx's default — what a brand-new account gets before it has chosen anything.

Yours always wins. If cdbx changes its default, accounts that have chosen are never touched. And adding a design system doesn't silently make it your default — only the star does.

Finding apps by design system

The Apps, Projects and Experiments lists can filter and sort by design system. The filter only lists systems something in that list actually uses, so it stays out of the way until it's useful. Sorting by design system groups everything using the same one together, with anything unattached at the end.

No styling, and no design system

Two entries in the picker mean different things, and the description under each says which:

• None — nothing steers the AI, so it styles to its own taste. Your app keeps whatever look it already has; nothing is removed.
• Unstyled — the AI deliberately writes no styling. Attaching it replaces your stylesheet with a bare reset (box-sizing, no margins, a system font) and empties the token file, so the app really is unstyled rather than just unthemed.

Switching away from Unstyled puts the template's stylesheet back, so the app themes normally again — but only if you haven't written CSS of your own since. If you have, that's yours and switching won't touch it.

Bringing your own

There are five ways to get your real design system in, all under Add your own on the Account settings → Design systems page. Each is read once and cached, so chat stays fast — hit Refresh when the real thing changes.

A design-system MCP server

If your team runs one, connect it as a custom connector in Settings → Connectors first. Then, on the Design systems page, choose that connector and click Connect. This gives the richest result: real tokens, components, prop APIs, examples, and guidelines.

A Figma file

Connect the Figma connector and give cdbx a file key (the ID in figma.com/design/{fileKey}/…). cdbx reads your published color, text, and effect styles as real values — actual hex codes, not style names — plus your component names.

Two things to know: only published styles and components are visible to Figma's API, and Figma Variables are a different thing from Styles. If your tokens are Variables, export them to a tokens file and use the option below.

A design tokens file

Paste, upload, or link a tokens JSON. Both the W3C format and Tokens Studio are understood, {alias} references are resolved to their real values, and composite tokens (typography, shadows, borders) become usable CSS values.

This is also how you use Figma Variables — export them to a tokens file and ingest that. No particular Figma plan needed.

An npm component library

Name a package and cdbx reads its TypeScript types — real component names and real prop APIs, so the AI imports from your actual package and uses props that exist.

Nothing needs to be installed anywhere. cdbx fetches the package's type declarations from the jsDelivr CDN and parses them; it never installs or runs a package, because a package's install scripts would execute on our servers.

Start typing and cdbx searches npm, so what you pick is a package that exists.

Pick the version your app uses. With just a name, cdbx reads the latest version. Add @version to read a specific one — @heroui/[email protected] — which matters when a library has changed shape between major versions. Refreshing the design system re-reads the same version.

What can't be read. cdbx reads types as written. Libraries whose props are built from other types rather than declared (HeroUI 3 derives most props from react-aria-components and style variants) show their components and import paths, but no prop list; when asked, the AI says it can't see the props rather than guessing them. Older, explicitly typed versions (HeroUI 2) read in full. A private package isn't on the CDN — open "It's a private package" and pick a project that already installed it with your registry token, and cdbx reads it from that container instead.

Private packages work: cdbx writes an .npmrc into your app so it can install from your private registry. Your registry token lives in the app's environment variables and is never written into the file.

cdbx never installs or runs your package on its servers — it reads the files your app already installed.

Setting up a private registry (step by step)

Only for a private package — a public one needs none of this, just its name.

For a package in a private registry — e.g. a company design system published to GitHub Packages:

1. Add your registry token in the app's Environment Variables, e.g. NPM_TOKEN. For GitHub Packages that's a token with the read:packages scope.
2. On the Design systems page, under an npm package, open "It's a private package" and give:
   • Package — e.g. @acme/ui
   • Scope — e.g. @acme
   • Registry URL — e.g. https://npm.pkg.github.com (must be https)
   • Token variable — the env var name from step 1 (NPM_TOKEN)
3. cdbx writes an .npmrc pointing your scope at the registry and referencing ${NPM_TOKEN} — npm expands it from the container at install time, so the token itself never lands in the file (safe to export, zip, or commit).
4. Your app installs the package as normal, and cdbx reads its real component prop APIs into the design system.

Write your own

No package, no Figma file, no server. Give it a name, and it appears on the Design systems page with a token editor open under it.

Each row is one token: a name, a value, and what kind of thing it is. A token named accent with the value #006fee becomes --accent in your app's design-tokens.css, and the AI styles with var(--accent). Tokens in the radius group are what corner-radius checking compares against, so put 8px or 0.5rem there rather than in other.

Save, and the next thing you generate uses the new values.

Tokens only, deliberately — tokens are what actually reach your app as CSS. Component and pattern descriptions are prose the AI reads, and are better authored somewhere real and imported than typed into a settings page.

Hand-authored systems are the only kind you can edit afterwards; there's no Refresh, because there's no upstream to re-read. Systems from a package, a Figma file, or a server stay read-only, since an edit would be overwritten the next time they refreshed.

Which to use

Each source carries different things. An npm package has prop APIs but no design tokens; a Figma file or tokens export has tokens but no prop APIs. Use Combining sources below to take components from one and tokens from the other.

Combining sources

Your components and your tokens often don't live in the same place. An npm component package has real prop APIs but no design tokens; a Figma file or a tokens JSON has real token values but no prop APIs. Neither one alone is a whole design system.

On the Design systems page, click Combine sources and say where each part comes from:

• Tokens — colors, spacing, type
• Components — component names and prop APIs
• Patterns — composed layouts and page recipes
• Guidelines — written rules the AI should follow

Pick at least one; leave the rest on None. Give it a name, hit Create and use, and it's attached straight away.

Each part comes entirely from one system. Nothing is merged and nothing overrides anything, so there's never a conflict to sort out — if two of your systems both define a Button, only the one you picked for Components is ever asked. The settings panel shows exactly which system supplies each part.

Refresh re-assembles a combined system from whatever its sources hold now. Refresh the sources first if they're stale — refreshing the combination deliberately doesn't reach out over the network on their behalf.

A combined system can't be built from another combined system, so those don't appear in the pickers.

Your tokens are real CSS in your app

Attaching a design system writes its tokens into your app as CSS custom properties, in a generated file called design-tokens.css. It's a normal file in your file tree, loaded straight after your stylesheet, and the AI styles everything with var(--primary) and friends rather than pasting colour values around.

The file is generated, so don't edit it — it's rewritten whenever you switch design systems, or when the system it came from changes. Change the value in the design system instead.

Two things follow from this:

• Dark mode is automatic. A design system that defines a dark palette switches with your system setting, with no extra work. One that defines a single palette keeps it in both modes, and the file says so.
• You can take it off again. Choosing None in the app's design-system dropdown stops the AI following or checking against it. Your CSS and token file are left exactly as they are, so the app keeps its look. (Unstyled is the one entry that does rewrite them — see above.) Your design-tokens.css and your CSS are left exactly as they are, so the app keeps the look it has — removing the file would break every var(--…) already in it.
• Your existing apps aren't touched until you ask. An app built before you had a design system keeps its own styling. Ask the AI to apply your design system to it and it wires the tokens in and converts what's there.

Apps with no stylesheet at all — an Express, FastAPI, or Go service — get no token file, and the AI is told not to reference variables that don't exist.

How the AI uses it

Component names, one-line summaries, import paths, and your tokens are always in the AI's context. The heavy detail — a component's full prop API, its examples, a guideline's body — is fetched only when the AI actually reaches for that component. That's why a large library costs almost nothing until it's used, and why the AI stops guessing prop names.

Checking the AI actually used it

After each AI turn in an app with a design system attached, cdbx checks the files that changed and flags three things:

• a color or corner radius hardcoded when one of your tokens already holds that exact value
• a component that isn't in your design system
• an import from a different UI library
• one of your design-system tokens redefined in your own CSS, which silently overrides the system for everything below it

Colours are compared by value, not by how they're written — hsl(222.2 47.4% 11.2%) and #0f172a are the same colour and both get caught. Converting between notations loses a unit or two per channel, so near-identical colours count as a match; the tolerance is small enough that a colour merely resembling a token still isn't flagged. Radii are compared the same way, so a 0.5rem token still matches a hardcoded 8px.

It then gives the AI one chance to fix them and tells you what happened — fixed, partly fixed, or found-but-not-fixed. It never blocks your work.

The check is a direct comparison, not an opinion: a hardcoded value is only flagged when a token holds that same value, so every finding is something you can verify and act on. Values no token covers are left alone, as are colors in comments, non-UI imports, and plain HTML elements. On a clean turn you'll see nothing at all.

One consequence worth knowing: a turn with findings runs a second, smaller AI call to fix them, so it costs a few more credits than a clean turn.

Decks

Slide decks use design systems too — a deck takes its colors, font, and radius from your tokens, and re-themes when you switch systems. See Slides.