# BrandSweets

> Generated by BrandSweets from the brandsweets BrandDoc (v1, schema 1). Do not edit by hand.

## Identity

**Tagline:** Your brand, sweetened for agents.

**Mission:** Make every brand legible to the agents that now build with it, without giving up the human who owns the taste.

**Sector:** brand infrastructure / developer tools

**Audience:** founders, brand designers, and the agents building alongside them

**Founded:** 2026

**Domain:** brandsweets.com

**Guidelines:** https://brandsweets.com/b/brandsweets


BrandSweets is the brand home for the agent era, and its own first customer — the site you are reading is rebuilt from this document. A brand used to live in a PDF no machine could read. Now agents design, extract, and ship on a brand's behalf, and they need something better: a structured, versioned source of truth they can read to stay on-brand and write to when a human asks. So we built the living brand book. Every brand becomes a brand doc that serializes losslessly to brand.md, tokens.json, brand.css, and a per-brand MCP endpoint. Agents propose; a person approves. Nothing leaves without clearing a taste floor. And because it is plain files, you can walk out the door with your brand any time you like.

### Values

- **Humans approve** — Agents propose; a person signs off. The human-in-the-loop is the product, not a safety net bolted on afterward.
- **A taste floor** — Every brand that leaves BrandSweets clears a validated minimum — contrast, hierarchy, fallbacks — before it ships. Taste is enforced, not hoped for.
- **No lock-in** — A brand serializes losslessly to brand.md, tokens.json, and brand.css. Leave whenever you like and take the whole thing with you.
- **Structure you can taste** — Strict grid, generous space, one sweet accent. The discipline is what makes the warmth read as premium rather than childish.

## Voice

**Tone:** confident, precise, warm, anti-hype

### Do

- Lead with the verb — say what the reader can do, not how they will feel
- Name the surface plainly: brand.md, tokens.json, brand.css, the MCP endpoint
- Keep the taste floor visible — every claim about quality should be checkable
- Write like a specimen caption: precise, set, and quietly assured
- Let hierarchy and whitespace carry emphasis; reach for a bigger idea before a bigger adjective
- Say 'humans approve' out loud — the human-in-the-loop is the point, not a footnote

### Don't

- Never 'unlock', 'supercharge', 'seamless', 'effortless', or 'revolutionary'
- No exclamation points — the confidence lives in the claim, not the punctuation
- Don't call agents 'magic'; they read a document, so say so
- No 'AI-powered' as a feature — the brand doc is the feature
- Avoid 'unleash', 'empower', 'game-changing', 'next-gen', 'leverage', 'synergy'
- Don't promise 'one-click' anything; describe the actual step

### Sample copy

- **auth — accounts-launch-soon notice** _(notification)_: "Accounts launch soon. For now your draft stays private to this session; claiming and saving arrive with sign-in." — `auth-accounts-soon`
- **auth — claim-your-brand explainer** _(body)_: "Claiming a brand ties it to your account and unlocks verification, versioning, and the MCP endpoint. Sign-in is a moment away." — `auth-claim`
- **closing call-to-action band** _(headline)_: "Ready to sweeten a brand?" — `closing-nudge`
- **create-intake holding state after a brief is captured** _(empty-state)_: "Brief captured. The agent-guided generation step is on the way; until then, nothing is faked — here is exactly what happens next with what you gave us." — `create-holding`
- **primary button — begin creation intake** _(cta)_: "Create a brand" — `cta-create`
- **primary button — begin extraction** _(cta)_: "Extract my brand" — `cta-extract`
- **secondary button — open a brand's page** _(cta)_: "Open the brand book" — `cta-view-brand`
- **empty state — no brands yet in a list** _(empty-state)_: "No brands here yet. Extract one from a domain, or start a new one from a brief." — `empty-brands`
- **404 / error page body** _(error)_: "This page isn't in the book. The link may be old, or the brand may be private. Head back to the shelf." — `error-page`
- **extraction failed error** _(error)_: "We couldn't reach that domain. Check the spelling and that the site is live, then try again." — `extraction-failure`
- **extraction in-progress status** _(notification)_: "Reading your site in a real browser — colors, type, logo, voice. This usually takes ten to thirty seconds." — `extraction-pending`
- **extraction complete confirmation** _(notification)_: "Draft ready. We pulled your palette, type, and logo into a brand doc — review it, then claim it." — `extraction-success`
- **site footer line** _(microcopy)_: "BrandSweets — the living brand book. Made to be read by people and agents alike." — `footer-line`
- **onboarding fork card — 'I have a brand'** _(body)_: "Type your domain. We run a real browser over it and read the colors, type, logo, and voice into a draft you can review." — `fork-have-brand`
- **onboarding fork card — 'I need a brand'** _(body)_: "Start from a brief — a name, a one-liner, an audience, a few vibe words. We shape it into a complete brand doc you can claim." — `fork-need-brand`
- **hero eyebrow / kicker above the headline** _(microcopy)_: "The living brand book, for the agent era" — `hero-eyebrow`
- **landing hero headline** _(headline)_: "Your brand, sweetened for agents." — `hero-headline`
- **landing hero subline beneath the headline** _(body)_: "Turn a brand into a structured system agents can read to stay on-brand everywhere, and write to while a human approves. Extract an existing brand from its domain, or start a new one from a brief." — `hero-subline`
- **three-surface explainer — tokens.json / brand.css (apply)** _(body)_: "tokens.json and brand.css carry role-based color, type, and spacing. One import and a prototype is on-brand by construction." — `surface-apply`
- **three-surface explainer — MCP endpoint (connect)** _(body)_: "The MCP endpoint gives an agent the right logo, the right tokens, the right copy — and a way to propose changes a human approves." — `surface-connect`
- **three-surface explainer — brand.md (read)** _(body)_: "brand.md is the narrative brief an agent grounds on before it writes a word — voice, story, dos and don'ts, in one readable file." — `surface-read`
- **section heading — the three machine surfaces** _(headline)_: "One document, three surfaces." — `surfaces-heading`

### Vocabulary

- **Preferred:** brand doc, surfaces, agents, claim, boards, tokens, the taste floor, on-brand by construction, extract, the living brand book, brand.md, brand.css, MCP endpoint, humans approve
- **Avoided:** unlock, supercharge, seamless, effortless, revolutionary, game-changing, AI-powered, synergy, next-gen, leverage, empower, unleash, disrupt, magic
- **BrandDoc:** One word, camel-cased. The versioned, structured document that is a brand's source of truth (the schema object).
- **BrandSweets:** One word, camel-cased with a capital B and S. Never 'Brand Sweets' or 'Brandsweets'.
- **MCP:** Always uppercase — Model Context Protocol. 'the MCP endpoint', never 'an mcp'.
- **agents:** Lowercase. The AI readers and writers of a brand doc — not 'bots', not 'the AI'.
- **brand doc:** Two words, lowercase, when speaking generically; 'BrandDoc' when naming the schema object.
- **brand.css:** Lowercase, .css, mono. The token layer exported as CSS custom properties.
- **brand.md:** Lowercase with the .md extension, set in mono. The narrative brief agents read to ground themselves.
- **tokens.json:** Lowercase, .json, mono. The token layer as structured data.

## Colors

| Role | Name | Hex | Dark | Usage |
| --- | --- | --- | --- | --- |
| `primary` | Caramel | `#a4501c` | `#e6a063` | The single brand accent. CTAs, links, the mark, and caramel emphasis on paper. Used sparingly against paper and ink. |
| `surface` | Sugar Paper | `#fbf7ef` | `#17120c` | The page. Warm off-white paper — the ground the whole specimen sits on. Never plain #ffffff. |
| `surfaceMuted` | Marzipan | `#f1e8d8` | `#221a11` | Panels, cards, and inset blocks that need to sit just off the paper ground. |
| `text` | Cocoa Ink | `#241c14` | `#f4eadb` | Headlines and body text on paper — a warm near-black, not pure black. |
| `textMuted` | Toffee Grey | `#6b5d4c` | `#a6937b` | Captions, eyebrows, metadata, and secondary text. Still AA on paper. |
| `border` | Wafer | `#e7dcc9` | `#362a1c` | Hairline rules, dividers, and card borders. Decorative — never load-bearing for contrast. |
| `success` | Pistachio | `#2f7d51` | `#4bbf7e` | Positive product states — a clean extraction, a saved brief. UI only, never decorative. |
| `danger` | Redcurrant | `#b23a2b` | `#ef6b5e` | Errors and destructive actions — a failed extraction, a validation block. UI only. |

### Scales

- **primary:** 50 `#fbf1e7`, 100 `#f6ddc4`, 200 `#ecbb8c`, 300 `#e09a5c`, 400 `#d07a34`, 500 `#b5601f`, 600 `#a4501c`, 700 `#863f18`, 800 `#653111`, 900 `#46220c`, 950 `#271205`
- **surface:** 50 `#fbf7ef`, 100 `#f5eddd`, 200 `#ece0c7`, 300 `#ddcca9`, 400 `#c7b083`, 500 `#ab9160`, 600 `#8a7249`, 700 `#675636`, 800 `#453a25`, 900 `#2a2317`, 950 `#17120c`
- **text:** 50 `#f4f2ee`, 100 `#e5e0d8`, 200 `#cbc2b3`, 300 `#a99c87`, 400 `#837462`, 500 `#635646`, 600 `#4b4034`, 700 `#392f26`, 800 `#2c2419`, 900 `#241c14`, 950 `#150f0a`

## Typography

### Families

#### Fraunces `fraunces`
- **Source:** google
- **Foundry:** Undercase Type
- **Weights:** 400 Regular, 400 Regular Italic, 500 Medium, 600 Semibold, 900 Black
- **Fallback stack:** `Fraunces, Georgia, "Times New Roman", serif`
- **Licensing:** SIL Open Font License via Google Fonts — free to serve. Loaded, never re-sold or claimed as bespoke.
- **License:** https://fonts.google.com/specimen/Fraunces
- **Usage:** Display and big statements only, plus pull quotes in the italic. Never set running body copy in it.
- **Feature settings:** `'ss01' on`
- **Variable axes:** SOFT 0–100 (def 40), WONK 0–1 (def 0), opsz 9–144 (def 144), wght 100–900 (def 400)

#### Hanken Grotesk `hanken-grotesk`
- **Source:** google
- **Foundry:** Hanken Design Co.
- **Weights:** 400 Regular, 500 Medium, 600 Semibold, 700 Bold
- **Fallback stack:** `"Hanken Grotesk", system-ui, -apple-system, "Segoe UI", sans-serif`
- **Licensing:** SIL Open Font License via Google Fonts — free to serve.
- **License:** https://fonts.google.com/specimen/Hanken+Grotesk
- **Usage:** Headings, eyebrows, labels, and body text — the grid's working voice.
- **Feature settings:** `'ss01' on, 'cv11' on`
- **Variable axes:** wght 100–900 (def 400)

#### Space Mono `space-mono`
- **Source:** google
- **Foundry:** Colophon Foundry
- **Weights:** 400 Regular, 700 Bold
- **Fallback stack:** `"Space Mono", SFMono-Regular, ui-monospace, Menlo, monospace`
- **Licensing:** SIL Open Font License via Google Fonts — free to serve.
- **License:** https://fonts.google.com/specimen/Space+Mono
- **Usage:** Machine surfaces only: file-name tags, hex values, and brand.md / tokens.json code snippets.

### Role assignments

- **display:** Fraunces (`fraunces`) — weights 400, 500, 600, 900 — Fraunces at the large optical size for the hero statement and cover; Black for the biggest lines only.
- **heading:** Hanken Grotesk (`hanken-grotesk`) — weights 500, 600, 700
- **body:** Hanken Grotesk (`hanken-grotesk`) — weights 400, 500
- **mono:** Space Mono (`space-mono`) — weights 400, 700 — Every file name, hex, and code snippet.
- **quote:** Fraunces (`fraunces`) — weights 400 — Pull quotes are set in the Fraunces Regular Italic.

### Scale

| Step | Size (rem) | Line height | Tracking (em) |
| --- | --- | --- | --- |
| micro | 0.75 | 1.5 | 0.14 |
| caption | 0.8125 | 1.5 | — |
| body | 1.0625 | 1.65 | — |
| lede | 1.375 | 1.45 | — |
| heading | 2 | 1.2 | -0.01 |
| title | 3 | 1.1 | -0.02 |
| display | 4.75 | 1.02 | -0.025 |

## Gradients

- **caramel-wash:** `linear-gradient(135deg, #fbf7ef 0%, #f6ddc4 55%, #e09a5c 100%)` — Hero and section washes over paper — a warm caramel glow behind content. Atmosphere only, never an object.

## Logos

### primary
- **Formats:**
  - `svg` (560×128): brandsweets/logo/primary-lockup.svg
  - `png` (1120×256): brandsweets/logo/primary-lockup@2x.png
- **Clearspace:** 1× cap-height — One cap-height of paper on every side. The book never crowds its own name.
- **Min size:** 132px w (screen)
- **Allowed backgrounds:** light, muted
- **Disallowed backgrounds:** photo, brand
- **Colors:** primary, text
- **Notes:** The Swatch mark to the left of the Fraunces wordmark.

### mark
- **Symbol name:** The Swatch
- **Formats:**
  - `svg` (128×128): brandsweets/logo/mark-swatch.svg
- **Clearspace:** 0.5× mark-width — Half a mark-width of clear paper on every side.
- **Min size:** 20px w (screen)
- **Allowed backgrounds:** any
- **Colors:** primary
- **Notes:** A generously-rounded square specimen chip — a paint-swatch, a caramel square, and a page — with the top-right corner turned down like a dog-eared brand-book page and a peeled sweet-wrapper corner in one. The face is Caramel (primary); the revealed underside of the fold is the paler sugar tint (primary@200). Used as favicon, app splash, and social avatar.

### wordmark
- **Formats:**
  - `svg` (480×88): brandsweets/logo/wordmark.svg
  - `pdf`: brandsweets/logo/wordmark-print.pdf
- **Clearspace:** 1× cap-height
- **Min size:** 160px w (screen)
- **Allowed backgrounds:** light, muted
- **Disallowed backgrounds:** photo
- **Colors:** text
- **Notes:** BrandSweets set in Fraunces, camel-cased — never all-caps, never re-spaced.

### mono
- **Formats:**
  - `svg` (560×128): brandsweets/logo/mono-caramel.svg
  - `eps`: brandsweets/logo/mono-caramel-foil.eps
- **Clearspace:** 1× cap-height
- **Min size:** 132px w (screen)
- **Allowed backgrounds:** light, muted
- **Colors:** primary
- **Notes:** One-color caramel lockup for foil stamping and single-ink print. The EPS is the foil master.

### inverse
- **Formats:**
  - `svg` (560×128): brandsweets/logo/inverse.svg
- **Clearspace:** 1× cap-height
- **Min size:** 132px w (screen)
- **Allowed backgrounds:** dark, brand, photo
- **Colors:** surface, primary
- **Notes:** Sugar-Paper wordmark with the caramel Swatch, for the deep-charcoal dark surface and photography.

### favicon
- **Formats:**
  - `svg` (32×32): brandsweets/logo/favicon.svg
  - `png` (32×32): brandsweets/logo/favicon-32.png
  - `ico` (32×32): brandsweets/logo/favicon.ico
- **Allowed backgrounds:** any
- **Colors:** primary
- **Notes:** The Swatch mark alone, cropped to the tile. The folded corner stays legible at 16px.

## Usage Rules

- **[SHOULD] Ship the warm dark counterpart** (accessibility) — Every surface has a full dark counterpart on the deep-toffee ground — warm, not blue-black. The light/dark pair is a demo of the schema's dark dimension, so keep both honest. `dark-mode-parity`
- **[MUST] Say humans approve out loud** (voice) — Wherever copy describes an agent writing to a brand, name the approval step. Agents propose; a person signs off. Never imply autonomous changes ship unreviewed. `humans-approve`
- **[MUST] Honor the one-cap-height clearspace** (logo) — The primary lockup needs one cap-height of clear paper on every side. Nothing — rule, image, or type — enters that margin. `logo-clearspace`
- **[MUST NOT] Caramel is the one sweet note** (color) — Caramel is an accent on paper and ink, not a field. Never flood a page or a full section with it; the warmth reads as premium precisely because it is rationed. One sweet note, not a bag of candy. `one-sweet-note`
  - Don't: A hero section filled edge-to-edge with saturated caramel.
- **[MUST] Grounds are warm paper, never sterile white** (color) — Every light surface sits on Sugar Paper (#fbf7ef) or Marzipan, never pure #ffffff. The warmth of the ground is half the brand; plain white breaks it. `paper-not-white`
- **[SHOULD] Fraunces sets statements, not paragraphs** (typography) — Fraunces carries the hero line, cover, and pull quotes. Running body and UI copy are set in Hanken Grotesk; never set a paragraph in the display serif. `serif-for-statements`
- **[MUST NOT] Cut the hype lexicon** (voice) — No 'unlock', 'supercharge', 'seamless', 'effortless', 'revolutionary', 'AI-powered', or exclamation points. State the capability plainly; the confidence lives in the claim. `voice-no-hype`

## Boards

- **Cover** — `cover` (`board-cover`)
- **The Swatch & the Wordmark** — `logo-suite` (`board-logos`)
- **Paper, Ink & Caramel** — `color-system` (`board-colors`)
- **Set in Fraunces & Hanken** — `type-specimen` (`board-type`)
- **How BrandSweets Speaks** — `voice` (`board-voice`)
- **The Product, On-Brand** — `ui-preview` (`board-ui`)
- **Welcome to the Living Brand Book** — `custom-html` (`board-welcome`)

## Resources

- Tokens (JSON): /b/brandsweets/tokens.json
- Tokens (CSS): /b/brandsweets/brand.css
- This document: /b/brandsweets/brand.md
- MCP endpoint (public read): mcp.brandsweets.com/brandsweets/mcp
- Agent integration guide: /agents.md