How Onbrand works.From your code to everyone, start to finish.
This page walks through the whole thing in plain words: what you need, what you paste, what your agent does in your repository, what you get, and what happens every time you push after that.
What Onbrand is
Onbrand is a small tool that reads your brand out of your frontend code: the colors, type, spacing, icons, logo, components and motion. It turns all of that into one design-system page, and it runs again on every push, so the page never falls behind the code.
Nothing is added to your app. There's no package to install and no code that runs in your product. Everything Onbrand needs lives in one design-system folder and one workflow file.
Before you start
You need two things:
- A frontend repository on GitHub. Plain CSS, Tailwind 3 or 4, SCSS and the common CSS-in-JS themes (MUI, Chakra, styled-components, Emotion) are all read.
- An AI coding agent that can work in that repository, like Claude Code or Cursor. It does the setup for you.
Then pick where the page should live:
- GitHub Pages: free, in your own GitHub account. Anyone with the link can see it.
- Onbrand hosting at
sites.onbrand.tools/your-name: can keep the page behind a password or let in only people who sign in with Google on your company's domain, and comes with a dashboard for access, views and history. It's invite only for now.
1. Get your install prompt
There are two ways in:
- Copy install prompt on the home page. It includes the full setup guide, so it works even in tools that can't open links.
- Get started: sign in with Google and enter your access code. Your dashboard then gives you a prompt with your account key built in. That key links the repository to your account, so you can watch every step of the setup live. Keep it private, like a password.
Set up Onbrand in this repository: turn this frontend
into a live design system that updates on every push,
for my team and our AI tools.
Follow the setup guide below exactly. Before changing
anything, ask me where the page should live, who can
see it and which components to show.
--- the full setup guide follows (install.md)
2. Paste it into your agent
Open your repository in your agent and paste the prompt. Before it changes anything, the agent asks you three questions in one message:
- Where should the page live? GitHub Pages or Onbrand hosting. If you used the prompt from your dashboard, it's already Onbrand hosting and it skips this one.
- Who can see it? Anyone with the link, or, on Onbrand hosting, people with a password or people signing in with Google on your company's domain.
- Which components should be shown? It suggests what it found in your code, like buttons, inputs, cards or navigation, and you pick.
Set up Onbrand in this repository: turn this frontend into a live design system that updates on every push…
install.md · setup guideBefore I change anything, three quick questions.
3. What your agent does
Once you've answered, the agent follows the setup guide step by step:
- Looks at what Onbrand finds. It lists your colors in light and dark, the other tokens, fonts, icons, logo, components and animations, and compares that with your code. If it picked up too much (say, a vendored library) or too little, it narrows or widens the sources.
- Sets up the folder. It adds
design-system/with your settings, written guidance, one example file per component and an empty changelog, plus a GitHub workflow that rebuilds the page on every push to main. - Writes your component examples using your app's real class names and real copy from your product, showing the main states side by side.
- Writes short guidance: your principles, what each color group is for, and rules for type, spacing and motion, from what it sees in the code and what you tell it.
- Checks it locally at
localhost:4400, goes through every page and fixes anything that looks wrong. - Turns on publishing. On GitHub Pages you flip one setting yourself: Settings → Pages → Source: GitHub Actions. On Onbrand hosting it publishes once and saves a publish key as a secret in your repository.
- Commits and reports back with the address of your page, what it found, and anything it couldn't find.
Nothing in your app changes.
GitHub Pages, anyone with the link, and buttons, inputs and cards.
Working 7 steps
- 1Look at what Onbrand finds
onbrand scanCompleted - 2Set up the folder
onbrand initCompleted - 3Write 3 component examples
components/Completed - 4Write the guidance
guide.jsonCompleted - 5Check it locally
onbrand previewCompleted - 6Turn on publishing
workflowCompleted - 7Commit and report back
git commitCompleted
npx -y onbrand.tools/v/0.7.0/onbrand.tgz scan --json
Ranonbrand init --name "Yourco" --host pages
design-system/onbrand.json+14components/01-buttons.html+38
guide.json+41
The agent's report
Done. Onbrand is set up and committed.
- Your page:
yourco.github.io/web, live after your next push. - Found: 24 colors in light and dark, 2 fonts, 31 icons, your logo, 3 components and 6 animations.
- Not found: brand imagery. Add images to
design-system/imagery/any time.
One thing for you: turn on GitHub Pages once, in Settings → Pages → Source: GitHub Actions.
Lines in your commit messages that start with Brand: become notes in the changelog. To show another component, add a file to design-system/components/. And give design.md to your AI tools so they build on brand.
4. What you get
One page, always current, with a section for each part of your brand (more on the home page):
- Colors, light and dark, grouped by meaning. Click any color to copy its variable.
- Typography and layout: the font weights and sizes you actually use, your spacing scale and breakpoints.
- Icons and logo: every SVG, searchable and copyable.
- Components, rendered with your real CSS in light, dark, desktop and phone.
- Motion: every animation at its real speed and curve.
- Changelog: a dated record of every change, with before and after.
- Use it: how to bring the system into code and AI tools.
If you add images to design-system/imagery/, a Brand imagery page appears too.
- Overview
- Logo
- Colors
- Typography
- Layout
- Icons
- Components
- Motion
- Changelog
- Use it
--primaryforeground--fgbackground--bgborder--linesuccess--okdanger--danger5. Every push after that
Change a color, push to main, and the workflow rebuilds the page. A few minutes later it's current, and the changelog has a dated entry showing exactly what changed.
- Lines in your commit message that start with
Brand:become notes in the changelog. Your other commit messages and your app code stay private: only the brand is published. - To show another component later, add one file to
design-system/components/.
12 --radius: 12px; 13- --primary: #f2601a; 13+ --primary: #e8590c; 14 --primary-fg: #fff;
Brand: note.6. Using it every day
- In code: link
tokens.cssand every color, radius, shadow and font is there, in light and dark. - In AI tools: give Claude Projects, Cursor rules or your custom instructions your page's
design.md, the whole system in one file, so first drafts use your real tokens and components. The Use it page can also open a chat with the system already loaded. - With your team: anyone can download the full kit as a .zip, and the changelog shows what changed and when for design reviews.
- On Onbrand hosting, your dashboard lets you change who can see the page, see views and history, and get new keys.
Build a pricing card for our three plans.
design.mdUsing your Card and Button examples and the tokens in design.md: var(--primary), --radius: 12px and your type scale. No new colors.
design.md builds with your real tokens and components instead of guessing.What it costs
Today, Onbrand costs nothing. On your own hosting it runs in your repository and deploys to GitHub Pages. Onbrand hosting, with password or Google sign-in, is invite only for now and costs nothing during that time. Pricing may change later. More answers are in the questions on the home page, and what's new is in the changelog.