Brand

---
name: brand
description: >-
  Give this project its own readable brand, so every chat card and report renders in its palette,
  logo and font. Detects the identity from the repo or interviews the user, then writes a
  committable .readable/ layer. Triggers: "brand readable", «کارت‌ها رنگ خودمون».
---

# brand: a per-project skin for cards and reports

Output = a small committable `.readable/` dir at the project root (ONLY at a project root, never `~/.claude` or `$HOME`: config dirs are not projects). From then on `/report` reskins automatically, and chat cards do too (the session hook announces the dir at session start; an app restart lets other sessions pick up a brand created mid-session). Since 4.13.1 the card server never guesses a brand across open projects: a call without an announced `brand` renders stock, so parallel branded projects cannot leak into each other.

## 1. Detect before asking

Search the repo for an existing identity, in this order; quote what you find to the user before generating:

1. Design tokens: `**/tokens.css`, `**/design-system/**`, CSS custom props in the main stylesheet, `tailwind.config.*` color scales.
2. `DESIGN.md` / `BRAND.md` / brand guidelines docs.
3. Logos: `media/brand/`, `public/*.svg`, favicon SVGs. Prefer a mark that uses `currentColor` (theme-flips for free).
4. Fonts: `@font-face` files in the repo, or the families the site loads.

If ≥ a primary/accent color and a light-or-dark character are found, generate directly. Otherwise interview with AskUserQuestion, ONE batch: accent color (offer 3 sensible hues + custom hex), light surface character (pure white / warm cream / cool gray), dark base (ink navy / graphite / near-black), wordmark text + optional logo path, one tone word (serious/friendly/technical — store it, it guides future doc copy). Never ask what detection already answered.

## 2. Generate `.readable/`

**`brand.css`** — variable overrides only, in EXACTLY this vocabulary (card template + report shell both consume it). Author card-first: a `:root{}` light block and a bare `[data-theme="dark"]{}` dark block (consumers normalize selectors themselves). Vars: `--text-primary --text-secondary --text-accent --surface-1 --surface-2 --border --border-strong --bg-success --bg-accent --bg-warning --bg-danger --font-mono` (report-only extra: `--page-bg`). Chart hues go on `.rc{--ca:… --cb:… --cc:… --cd:…}` (dark tweaks via `[data-theme="dark"] .rc{…}`).

Rules of taste: derive the full ramp from the 1-2 given colors — tinted, not gray, surfaces; `--bg-accent` = a soft wash of the accent; keep `--text-accent` ≥ 4.5:1 contrast on `--surface-1` in BOTH themes (compute it, don't eyeball); dark theme is a designed palette, not inverted light. A Google-Fonts family may be declared via `brand.json`; never `@import` other hosts (cards strip them).

**`brand.json`** (optional but recommended):

```json
{ "name": "پایا", "wordmark": "پایا", "kind": "سند داخلی تیم",
  "logo": "logo.svg", "tone": "صنعتی، ساده",
  "font": { "family": "Vazirmatn", "google": "Vazirmatn:wght@400;500;700",
            "files": { "400": "fonts/X-Regular.woff2", "700": "fonts/X-Bold.woff2" } } }
```

`wordmark`/`kind`/`logo` feed the letterhead: the report header, and since 4.14.0 a matching `.brand` row mounted above chat cards too (logo + wordmark + kind, fetched by the bridge through `read_brand_head`). `font.files` are inlined into reports; `font.google` is the only font path that also reaches chat cards.

`"signature": false` (5.2.0) drops readable's own one-line credit from this project's cards and reports. It is ON by default everywhere, including branded projects. Offer it when the project's reports go to CLIENTS: a branded report is the client's document, and a toolmaker's mark under someone else's letterhead reads as a subcontractor watermark. Internal or public-facing projects should keep it. One flag covers both paths (the card server and `build.py` read the same key), and it is committable, so the whole team gets the same answer.

**`logo.svg`** — copy the project mark VERBATIM (no redesign), ≤ 8KB, `currentColor` preferred.

## 3. Prove it, then hand over

1. Build a sample report through the report skill's `build.py` with a 5-block fragment; verify in a browser: both themes, palette applied, header shows, accent contrast holds.
2. Render one chat card passing `brand: "<abs>/.readable"`, then keep passing it on EVERY card for the rest of this session (the hook only announces at session start, so a just-created brand is otherwise invisible until restart). A pre-4.13 card server ignores the param harmlessly; tell the user other sessions start branding after an app restart.
3. Tell the user to commit `.readable/` (it is team-shared config, not local state).