# BrandSweets — agent integration guide

> The brand memory and iteration layer for AI agents. Extract a brand from a domain or shape one on a canvas, then serve it as structured, agent-readable data — brand.md, tokens.json, brand.css, and a per-brand MCP endpoint every future session already knows.

This file tells a coding agent (Claude Code, Cursor, or any MCP-capable client)
how to integrate BrandSweets: connect the MCP endpoint, install the skills, read
a brand as brand.md / tokens.json / brand.css, and keep every output on-brand.

## What BrandSweets is

BrandSweets is an agent-native brand platform. A brand is stored as a validated
BrandDoc — identity, voice, role-based design tokens (color, typography, spacing,
radius, gradients), a logo/asset inventory, and usage rules — and served as the
formats agents actually consume. There is no bespoke SDK: you read plain files
and/or call MCP tools.

## Read a brand (no auth, public brands)

Every public brand at `/b/<slug>` exposes three stable, machine-readable URLs:

- `https://brandsweets.com/b/<slug>/brand.md` — narrative brief to GROUND on before writing (text/markdown)
- `https://brandsweets.com/b/<slug>/tokens.json` — role-based W3C DTCG design tokens (application/json)
- `https://brandsweets.com/b/<slug>/brand.css` — CSS custom properties; `@import` and a prototype is on-brand (text/css)

Fetch `brand.md` first for voice, story, dos & don'ts and usage rules. Use
`tokens.json` / `brand.css` to map real colors and type onto your UI — never
invent a hex or a font.

## Connect over MCP

Two Streamable-HTTP endpoints:

| Endpoint | Access | Auth |
| --- | --- | --- |
| `https://mcp.brandsweets.com/{slug}/mcp` | One brand, read-only | none |
| `https://mcp.brandsweets.com/w/{workspace}/mcp` | Whole workspace, read + write | `Authorization: Bearer <workspace-api-key>` |

Public read (one brand), `.mcp.json`:

    {
      "mcpServers": {
        "brandsweets": { "type": "http", "url": "https://mcp.brandsweets.com/{slug}/mcp" }
      }
    }

Workspace loop (read + write — reads brands, creates brands, designs logos, runs
the creation loop; a write key auto-approves edits):

    {
      "mcpServers": {
        "brandsweets": {
          "type": "http",
          "url": "https://mcp.brandsweets.com/w/{workspace}/mcp",
          "headers": { "Authorization": "Bearer <workspace-api-token>" }
        }
      }
    }

Or, in Claude Code:

    claude mcp add --transport http brandsweets https://mcp.brandsweets.com/{slug}/mcp

Create a workspace API key in the app under **Settings → Workspace API keys**. A
`bsk_r_…` read key grounds read-only; a `bsk_w_…` write key additionally unlocks
brand edits, the creation and logo loops, and (Pro) imagery. Your workspace slug
is the `<workspace>` segment of the URL.

## Install the skills plugin

    claude plugin marketplace add ethanplusai/brandsweets
    claude plugin install brandsweets-skills

Then enter your workspace slug and API token when prompted. The bundle wires the
workspace MCP server plus five design skills:

- `brandsweets-on-brand` — fetch the brand system first, map tokens onto Tailwind/shadcn/CSS, use the real contrast pairs, screenshot-review against the brand.
- `brandsweets-brand-design` — run the creation loop; with a write key, create a brand from nothing and build it up.
- `brandsweets-logo-design` — start a logo round, submit original vector marks, run the render → QA → critique loop.
- `brandsweets-imagery` — on-brand image generation (Pro + your own provider key).
- `design-taste` — framework-agnostic frontend craft; works even before a brand exists.

## Use the open font library

~1,900 free, open-licensed (OFL/Apache/UFL) typefaces, self-hosted with WOFF2 + license files, hand-vetted pairings and mood tags. Connect the public fonts MCP (read-only, no key) to search the catalog and get pairings:

    claude mcp add --transport http brandsweets-fonts https://mcp.brandsweets.com/fonts/mcp

- `list_fonts` — filter by category / mood / superfamily / weight / language / license.
- `suggest_fonts` — ranked pairings with rationale (give a `pairWith` family + `role`).
- `find_alternatives` — free, open-licensed alternatives to a commercial font (`commercialFont: "gotham"`), ranked by a published deterministic score with per-axis reasons; `list_commercial_fonts` lists the references. Humans: `https://brandsweets.com/fonts/alternatives`.

Browse or link humans to `https://brandsweets.com/fonts`; each font has a specimen, embed CSS, and a machine-readable `/fonts/<slug>/font.md`.

## Use the color tools

A deterministic color engine (no AI): analysis, WCAG contrast with fix suggestions, patterned palette generation with per-swatch locks, ~1,700 named colors (incl. real brand colors), ~60 curated palettes with rationale. Public MCP, read-only, no key:

    claude mcp add --transport http brandsweets-colors https://mcp.brandsweets.com/colors/mcp

- `analyze_color` / `check_contrast` — values, harmonies, moods; AA/AAA verdicts plus the nearest fix.
- `generate_palette` — propose 3–6 candidates (deterministic per seed) with a rationale and a shareable URL each; `suggest_palette` — curated-first by mood/industry.
- **The loop with a human:** each candidate URL looks like `https://brandsweets.com/palettes/new/3b82f6-1e293b-f59e0b-fef3c7-0f172a?lock=0,2`. Hand it to the human; they press Space to regenerate and lock what they like in the tool; the link they send back carries `?lock=` indices — those are their decisions. Regenerate around them (pass `hexes` + `locks`), then `systematize` into role tokens with contrast pairs, and (with a write key) apply via the workspace `generate_palette`.

## Use the gradient engine

A deterministic gradient engine (no AI): perceptual interpolation (OKLab / OKLCH — no grey midpoint), eased stops, anti-banding grain, mesh / conic / duotone / glass, and a report on every gradient. Public MCP, read-only, no key:

    claude mcp add --transport http brandsweets-gradients https://mcp.brandsweets.com/gradients/mcp

- `make_gradient` — 2–5 colours (+ kind, angle, interpolation, hue arc, easing, grain, seed) → CSS with the interpolation space, Tailwind v4 classes, SVG with correct geometry, a PNG URL, a DTCG token, the resolved stops, AND the report: worst-case WCAG contrast for white and black ink along the line, banding risk at 1440px (with a grain suggestion), gamut warnings. Tell the user when a gradient fails contrast without being asked.
- `brand_gradients` — a public brand slug or a raw palette → the canonical brand gradient, a hero background with an ink that passes AA at the worst point, a button surface with hover/active, and tonal / analogous / complementary / triadic variants — every export + report on each. The same values are served as `--brand-gradient*` in the brand's brand.css.
- Resource `gradients://corpus` — ~550 named gradients (uiGradients + WebGradients, MIT) with OKLCH family and mood tags.
- **URL as state:** every result carries a maker link like `https://brandsweets.com/gradients/new/v1.635bff-00d4ff?a=135&in=oklch`. Hand it to the human; they refine in the maker (side-by-side spaces, contrast strip with a one-click fix, easing, grain); the link they send back IS the gradient they chose — decode it (`v1.<stops>?k=&a=&in=&hue=&e=&g=&seed=`) and continue from there.
- Browse for humans: `https://brandsweets.com/gradients` (by colour, by mood, colour-to-colour, techniques, brand gradients); every collection has a `gradients.md` twin.

## Keep output on-brand

1. GROUND before you generate: fetch `brand.md` (or call the MCP `brand://<slug>/system` resource) at the start of the session.
2. Use ONLY the brand's tokens — colors by role, the declared type families and weights, the real logo asset URLs. No invented values.
3. Respect usage rules (MUST / MUST NOT / SHOULD). Honor logo clearspace, min sizes and allowed backgrounds.
4. Match the voice — tone attributes, preferred/avoided vocabulary, sample copy register.
5. Review the render against the brand and correct drift before shipping.

## Discovery

- Machine-discoverable manifest: `https://brandsweets.com/.well-known/mcp.json`
- Orientation file: `https://brandsweets.com/llms.txt` (concise) and `https://brandsweets.com/llms-full.txt` (everything in one fetch)
- Human setup guide: `https://brandsweets.com/docs/agents`
- Brand directory: `https://brandsweets.com/b`

---

_BrandSweets · https://brandsweets.com · this guide is also served as HTML at /docs/agents._