July 15, 20266 min read

Give your AI a design system: the Belin Kit.

AI assistants are very good at building UI and very bad at building your UI. Ask Claude or Cursor for a settings page and you get competent markup in whatever style the model felt like — hex colors invented on the spot, text-xl font-bold stacks, a gray button that ignores the design system sitting right there in the repo. The Belin Kit exists to fix that: one zip that carries your theme, your components, and the instructions an AI actually follows.

A design system vibe-coding tools can work with.

A design system is a set of decisions: this blue, this type scale, these spacing steps, imported from here, never hardcoded there. Humans learn those decisions from docs, reviews, and being told twice. An AI session starts from zero every time. If the decisions aren't in its context — findable, readable, and phrased as rules — it improvises. Improvised UI is exactly what a design system exists to prevent.

Most shadcn theme tools stop at the theme: a CSS file, maybe an AI prompt to paste. That's a swatch, not a system. The parts the AI keeps getting wrong — which components exist, which text styles to use, which tokens are allowed — still live in your head.

What's in the zip.

You design your theme in the Belin customiser — colors with live WCAG contrast checks, a type scale, text styles, spacing, per-component variants, light and dark. Then one button, "Download UI kit," produces a single archive:

text

belin-kit-my-theme.zip
├─ theme/                 your theme, as static CSS + re-importable JSON
├─ belin/                 tokens + 50-plus wrapped components
├─ components/ui/         the shadcn (Base UI) source underneath
├─ lib/  hooks/  config/  helpers + ready-made Tailwind config
├─ ai-instructions/       a readable copy of the AI docs, for you
└─ .claude/skills/belin/  the same docs where Claude Code auto-discovers them
   ├─ SKILL.md            setup + usage instructions
   └─ reference/          components, tokens, text styles — generated from code

The .claude folder is the interesting part. Claude Code automatically discovers skills there, so the moment the kit lands in a repo, the AI gains two abilities with zero configuration: set up Belin (install the 16 dependencies from the manifest, fix the Tailwind version, wire the CSS load order) and build with Belin(every future "make me a page" follows the system's rules).

The reference docs are generated from the code.

The reference docs the AI reads are not written by hand — they are generated from the same source files that run the customiser. The component inventory comes from the component catalog, the text styles from the text-style definitions, the token list from the token CSS, the dependency list from scanning the actual imports. A guard test fails any commit where the docs drift from the code.

That setup caught a real error in its first week: the hand-written docs claimed seventeen dependencies, and measuring the imports found sixteen. Hand-written lists drift; generated ones can't.

Every kit is tested on a fresh AI session.

The whole idea has an honest failure mode: docs that look complete but leave the AI stumbling. So the acceptance test is the real thing. A script creates a brand-new Next.js project, drops in a real downloaded kit with a deliberately unusual purple theme, and hands it to a fresh AI session — no coaching, one prompt:

Set up Belin in this project, then build a settings page with a profile form, notification toggles, and a save button.

A grading script then judges the artifact, never the chatter: imports only from @/belin/components, zero hex colors, zero Tailwind palette classes, text styles used, TypeScript clean, build green, and the served page rendering with the custom purple actually live on the primary button. The kit passed on its first full run — the fresh session performed the Tailwind downgrade from the skill's instructions, installed everything from the manifest, and built a compliant page. The only bug found was in the grading script itself.

Design once; every AI session follows it.

You make the design decisions once, visually, in a browser — and they hold in every future AI session, in every project the kit lands in. Even a request like "make this button #ff6600" gets routed through the system: the skill's guardrails tell the AI to adjust the right token instead of hardcoding a value. The rules live in the project itself, where the AI reads them, instead of in a document nobody opens.

Try it: theme the components in the customiser on this site, download the kit, unzip it into a project, and ask Claude to set up Belin. The full story of how Belin itself was built — including the audit that nearly failed it — is in the case study.