# Install Onbrand: turn this frontend into a live design system

You are an AI coding agent working in the user's repository. Onbrand is a small command-line tool that reads the brand out of the code (colors, type, spacing, icons, logo, components, motion), builds a design-system page from it, and keeps that page current on every push with a dated changelog. Your job is to set it up, then do the parts that need judgement: picking components and writing the guidelines.

The tool runs with npx and adds no dependencies to the project:

```bash
npx -y https://onbrand.tools/v/0.7.0/onbrand.tgz <command>
```

Below, `onbrand` means that command.

**If the user gave you an Onbrand account key** (it starts with `oba_`), run `onbrand connect <key>` before anything else. It links this repo to their account, and their dashboard at https://onbrand.tools/app shows every step you take live. Then use Onbrand hosting: no invite code is needed. Never print the key again, write it into a file or commit it.

## 0. Ask first, then work

Before changing anything, ask the user these three questions in one message and wait for the answers:

1. **Where should the page live?**
   - **GitHub Pages** (free, in their own GitHub account, needs one setting turned on), or
   - **Onbrand hosting** at `https://sites.onbrand.tools/<name>/`: free with an Onbrand account (sign in at https://onbrand.tools/app and copy the prompt there), and it comes with a dashboard for access, stats and history. If you already ran `onbrand connect`, skip this question: it's Onbrand hosting.
2. **Who can see it?** Anyone with the link, a password, or (Onbrand hosting only) people signing in with Google on their company's domain.
3. **Which components should be shown?** Offer a short list of what you found in the code (buttons, inputs, cards, tables, toasts, navigation…) and let them pick.

## 1. Look at what Onbrand finds

```bash
onbrand scan --json
```

This lists the colors (light and dark), other tokens, fonts, icons, logo files, components and animations it found, plus warnings. Read it and compare with the code:

- **Too much?** (for example a vendored library or a second app in the repo) Narrow the sources in step 2 with `css` globs, or drop tokens with `tokens.exclude` patterns.
- **Too little?** Tailwind v3 needs `npm install` first so its config can load.
- **CSS-in-JS themes** (MUI `createTheme`, Chakra `extendTheme` / `createSystem`, the object passed to a styled-components or Emotion `<ThemeProvider>`) are read automatically when the theme is a plain object, even split across files. Values computed by functions (`alpha(...)`, `darken(...)`) are skipped. If colors are missing, write them as CSS custom properties in `design-system/theme.css` and add that file to `css`.
- **Icons and logo** are found by folder and file names. If the icons come from a package (lucide, heroicons), leave `icons` empty and say so to the user.

## 2. Set it up

```bash
onbrand init --name "<Brand name>" --host pages        # or --host onbrand --slug <name>
```

This adds:

```
design-system/
  onbrand.json      settings: name, sources, icons, logo, access
  guide.json         written guidance (principles, what each color group means, type/spacing/motion rules)
  components/        one HTML example per component (empty for now)
  changelog.json     starts as []
.github/workflows/design-system.yml   rebuilds on every push to main
```

With `--host onbrand`, `init` also sets up **Review**, where invited people comment on the live app:

- the review snippet, `<script src="https://onbrand.tools/s/<name>.js" defer></script>`, in the app's HTML entry (`index.html`, `app/layout.tsx`, `pages/_document.tsx`, `src/app.html` or the Astro base layout). Visitors never see anything.
- the source plugin, in `vite.config.*` (`onbrand/vite`) or the Babel config (`onbrand/babel`). It tags every element with the file and line it comes from, in dev and on preview deploys only.

It prints what it changed. When it isn't sure, it changes nothing and prints the line to add: put it in by hand where it belongs. If it added a plugin, install the package as a dev dependency: `npm i -D https://onbrand.tools/v/0.7.0/onbrand.tgz`. A Next.js app without a Babel config builds with SWC: don't add a Babel config just for this. Comments still work without the plugin. For a repo that's already set up, `onbrand init --review` adds only these. Use `--no-review` to skip them.

Then edit `design-system/onbrand.json` where the scan was wrong:

- `css`: globs of stylesheets to read, e.g. `["src/styles/**/*.css"]`. Empty means "find them".
- `icons`: the folder with the SVG icons, e.g. `"src/assets/icons"`.
- `logo`: `{ "lockup": "public/logo.svg", "mark": "public/mark.svg" }`.
- `componentsCss`: built CSS the component previews should load (Tailwind and CSS-modules projects: the compiled file, e.g. `["dist/assets/*.css"]`). Empty means the source CSS (and the Tailwind browser build when Tailwind is detected).
- `tokens.exclude`: regex patterns of token names to leave out.
- `groups`: `{ "brand": ["^--brand-"] }` to group colors yourself.
- `access`: `{ "mode": "link" }`, `{ "mode": "password" }` or `{ "mode": "google", "domains": ["theirdomain.com"] }`.

## 3. Add the components the user picked

One file per component in `design-system/components/`, numbered for order (`01-buttons.html`, `02-inputs.html`…). Use the app's real class names and realistic copy from the product, not lorem ipsum. Show the main states side by side (primary/secondary, empty/filled, error, disabled).

```html
<!--
name: Buttons
group: Actions
about: One primary action per view; secondary for the rest.
-->
<div class="sp-stack">
  <div><div class="sp-label">Primary and secondary</div>
  <div class="sp-row"><button class="btn btn-primary">Save changes</button><button class="btn">Cancel</button></div></div>
</div>
```

`sp-row`, `sp-stack` and `sp-label` are layout helpers that exist only on the preview page. For React/Vue components, write the HTML they render (open the running app and copy the markup if that is easier).

## 4. Write the guidance

Fill `design-system/guide.json` from what you see in the code and what the user tells you. Keep it short and specific:

```json
{
  "tagline": "One sentence about the brand system.",
  "principles": [["Short title", "One or two sentences."]],
  "colors": { "<group>": ["Heading", "What this color group is for and when to use it."] },
  "type": ["Rules for type, one per line."],
  "layout": ["Spacing and layout rules."],
  "motion": ["Motion rules."],
  "logo": ["How to use the logo."],
  "easings": { "cubic-bezier(.2,.8,.2,1)": "What this easing is for" },
  "breakpoints": { "max 768px": "What changes at this width" }
}
```

## 5. Check it locally

```bash
onbrand preview
```

Open http://localhost:4400 and check every page: Colors (light and dark), Typography, Layout, Icons, Components (each one renders with the real CSS, in light and dark, desktop and phone), Motion, Changelog, Use it. Fix what looks wrong in `onbrand.json` or the component files and run it again.

## 6. Turn on publishing

- **GitHub Pages:** the workflow builds and deploys on every push to main, and commits `design-system/changelog.json` and `design-system/brand.lock.json` back. Tell the user to turn it on once: repo **Settings → Pages → Source: GitHub Actions**. GitHub Pages can't do passwords or Google sign-in; for those, suggest Onbrand hosting, or Cloudflare Access in front of the page.
- **Onbrand hosting:** run `onbrand publish` once. With a connected account it claims the address for that account (older setups: `onbrand publish --invite <code>`). It saves a publish key to `~/.config/onbrand/<name>.key`. Add it as the `ONBRAND_KEY` repository secret (`gh secret set ONBRAND_KEY < ~/.config/onbrand/<name>.key`). For password access, the user sets the `ONBRAND_PASSWORD` secret themselves. Never print, log or commit the key or the password.

## Design feedback (any time later)

When the user asks you to fix design feedback (for example "Fix the design feedback at fpy.sh/…"), read it from the repo:

```bash
onbrand feedback                                   # the open items as Markdown: page, element, file:line, off-system values, thread
onbrand feedback reply ob-13 "Uses --brand-500 now" --done     # after fixing it
onbrand feedback reply ob-14 "Keep 14px or use --radius-md (12px)?" --ask   # when it's the reviewer's call
```

Fix each open item at the file and line given, using the tokens it names. Ask with `--ask` instead of guessing when it's a judgement call. Put `ob-<num>` in the commit message: the next publish marks it done and links the commit. It uses `ONBRAND_KEY` or the connected account. Never print the key.

## 7. Finish

Commit the `design-system/` folder and the workflow. Then tell the user:

- the URL (after the first push, or right away for Onbrand hosting),
- what was found (counts of colors, tokens, icons, components, animations) and anything that wasn't,
- that commit-message lines starting with `Brand:` become notes in the changelog,
- how to add a component later (a new file in `design-system/components/`),
- to give `design.md` (the page URL + `design.md`) to their AI tools (Claude Projects, Cursor rules, custom instructions) so every agent builds on brand.

---

Onbrand · https://onbrand.tools
