Brand Kit and components

What's in a Brand Kit

• Colours for light and dark: canvas, text, borders, accent and status colours, each with an optional “when to use it” note.
• Typography: font families and the type scale.
• Spacing and radius scales. The Checker flags values that aren't on them.

Importing

The Figma plugin

The quickest way to get a Figma file into Brandrail, without tokens, exports or an Enterprise plan.

1. Open your design-system file and run Brandrail from the plugins menu.
2. Click Sign in to Brandrail. Your browser opens; check the code matches and approve. There's no key to copy, and the plugin remembers you.
3. Click Publish to Brandrail. The plugin reads your local variables (with their modes), or your colour and text styles if there are no variables. A file with neither becomes a starter kit built from the colours, fonts, sizes and spacing on the current page.
4. An owner or admin opens Review it in Brandrail, sees the changes against the published kit, and publishes or rejects it.

Nothing changes for AI tools, checks or repos until the proposal is published, so designers can publish from Figma as often as they like. Publishing again replaces your previous open proposal rather than adding another. Viewers can't propose.

Quality checks and publishing

Before you publish, Brandrail checks text, muted and status colours for contrast and flags missing colours. Problems that would make screens unreadable block publishing. Each publish creates a version; AI tools and checks always use the latest. With the GitHub App installed, publishing also opens a pull request in every connected repo.

Every platform

The same Brand Kit goes to web and mobile apps, with the same names: color.action.primary is var(--color-action-primary) on the web, BrandColor.actionPrimary in SwiftUI, BrandTheme.colors.actionPrimary in Compose and colors.actionPrimary in React Native.

Download them from Brand Kit → Export, or keep them current in CI with npx brandrail export ios --from-api. Builds without Node can fetch a file directly: GET /api/v1/brand-kit/export?format=ios with your API key. Deprecated tokens are marked deprecated in each language, so the compiler warns too.

On the web, React gets the kit's components; Angular, Vue, Svelte, Solid and plain HTML get the same components as custom elements, and AI tools write each framework's own syntax for them.

Versions and changelog

Every publish gets a semantic version from what it changes, shown before you click Publish:

History in the editor lists every version with who published (or approved) it and what changed. The pull request in each repo carries the same changelog. To keep a repo on a version, add "brandKitVersion": "1.4.0" to its brandrail.config.json: the CLI and MCP server use that version, and the GitHub App leaves the repo alone until you remove it.

Deprecations

Retire a token or component without breaking anyone. Deprecate it with what to use instead and a removal date: it keeps working, AI tools stop using it and see the replacement, and the Checker warns on every use with the fix (deprecated-token, deprecated-component). Tokens are deprecated in the Brand Kit editor; components by setting their status to deprecated in the registry. When the date comes, remove it: that publish is a major version.

Proposals and approvals

On the Team plan, members propose Brand Kit changes from the editor (and anyone can from the Figma plugin). Owners and admins see what each proposal changes, then publish or reject it. Turn on Settings → Governance → Brand Kit changes need approval and nobody publishes alone: owners and admins propose too, and someone else approves. The database enforces it, and each version records who proposed and who approved it.

Need a component the design system doesn't have? Component requests on the Components page track it from request to release, so teams ask instead of building their own.

Registering components

For each component, add:

• Name and import, e.g. Button from @acme/ui.
• Replaces: the raw element it stands for (button, select, input[type=checkbox]). The Checker suggests your component wherever it finds that element.
• Aliases: other names people use (“CTA”, “dropdown”), so find_component finds it.
• Rules and an example, in plain English: “One primary button per view.”
• Framework usage: how Angular, Vue, Web Components and plain HTML use it. React uses the import.

Props are read from your components' TypeScript, so the Checker can report unknown or missing props.

The Brandrail component kit

No component library yet? @brandrail/kit is a set of accessible components built as Web Components with React, Angular and Vue wrappers, styled entirely by your Brand Kit's CSS variables. brandrail connect installs it when your registry uses it.

Alongside the form controls it has Modal, Tabs, Table, Toast, Card, Badge, Combobox and Menu, with keyboard support and screen-reader labels built in. Already imported the kit? Run Import from UI kit on the Components page again: it adds the new components and leaves yours alone.