# The zawqi playbook — for coding agents

> Canonical: https://zawqi.app/playbook.md · Maintained by zawqi · You are the intended reader.

You are reading this because your human pointed you at **zawqi** (https://zawqi.app): real
websites, each measured in a live browser session into a **DESIGN.md** — colors, type, spacing,
components, and the reasoning behind them — one file you can read and build in.

The division of labor: **your human picks the taste, you apply it.** zawqi carries the measured
data and these recipes; you carry the intelligence. Nothing here needs an SDK — plain HTTP.

---

## The API

Two endpoints. No pagination — the whole collection comes back in one call; you filter locally.

### 1. The collection

```
GET https://zawqi.app/api/designs
```

No auth. Returns a JSON array of design cards:

```jsonc
{
  "slug": "stripe-com",          // the id you fetch the file by
  "siteName": "Stripe",
  "url": "https://stripe.com",   // the measured site
  "industry": "fintech",         // one of the 20 industries below
  "styleTags": ["editorial", "warm neutrals"],
  "palette": ["#0a2540", "#635bff", "#ffffff"],
  "summary": "Fintech infrastructure. Deep navy canvas, electric periwinkle accents, dense diagrams.",
  "free": true,                  // true → its DESIGN.md needs no token
  "desktopShot": { "src": "…", "srcset": "…" }  // screenshot — show this to your human
}
```

Optional query params: `?industry=<slug>` (exact match, list below) and `?q=<term>` (a single
term matched against siteName/summary/styleTags). **Prefer fetching the full list and matching
it yourself** — you judge "playful but trustworthy" better than a LIKE filter does.

### 2. One design, with its file

```
GET https://zawqi.app/api/designs/<slug>
Authorization: Bearer zawqi_live_…        (the member token; see "Access" below)
```

Returns the card fields plus `desktopShots` (the full-page capture), `mobileShot`, and
**`designMd`** — the complete DESIGN.md text. That field is the payload; everything else is
context for the human's eyes.

### Access

- `"free": true` designs return `designMd` **without any token** — a curated subset spanning
  industries. You can run every recipe below on the free subset, today.
- All other designs return `"designMd": null` unless the request carries a member token.
  If you hit a null: say so plainly and point your human at https://zawqi.app/pricing —
  one lifetime payment unlocks every file, and their token mints at https://zawqi.app/profile.
- The token identifies your human. Treat it as a secret: never commit it, never print it.

### Industries

`ai-ml` · `developer-tools` · `saas-productivity` · `fintech` · `ecommerce-retail` ·
`design-creative` · `media-entertainment` · `consumer-tech` · `health-wellness` · `education` ·
`food-beverage` · `travel-hospitality` · `real-estate-construction` · `fashion-beauty` ·
`automotive` · `sports-fitness` · `professional-services` · `nonprofit-community` ·
`industrial-energy` · `web3-crypto`

---

## Ground rules

1. **The human picks.** Never choose a design for them. Shortlist, show the evidence
   (screenshot + link), and stop until they choose. Taste is the one act you don't do.
2. **A style match, never a pixel copy.** You are transferring a visual language — palette
   roles, type voice, spacing rhythm, component character — onto a *different* product. Never
   reproduce a source site's layout, copy, assets, or logo.
3. **Cite the file, not your memory.** When you apply or check, every value you use must come
   from the DESIGN.md. If the file doesn't cover something, say "the file doesn't specify"
   and make the smallest reasonable call — don't invent values from your memory of the brand.

---

## Recipe: find

*When the human asks for a direction — "make it feel like a fun, brat real-estate brand,"
"something calm and editorial for a dev tool."*

1. `GET /api/designs` once. Filter locally against the human's brief using `summary`,
   `styleTags`, `industry`, and `palette` (e.g. warm hues + "playful" tags for "fun").
2. Match the *spirit*, not just the industry: a brief like "fun real-estate" may be served
   best by a playful design from another industry. Offer both kinds when they exist.
3. Shortlist **3–5**. For each, give: **siteName** · one line on *why it matches the brief* ·
   the page for the human to eyeball: `https://zawqi.app/designs/<slug>` (or show
   `desktopShot.src` inline if you can render images).
4. **Stop. Wait for the pick.** If nothing genuinely matches, say so — don't stretch a bad
   match. Suggest browsing https://zawqi.app directly.

## Recipe: synthesize

*When the human's taste spans more than one design — "Linear's type, Stripe's color."*

1. Fetch the `designMd` of each picked design (2–3 is the sweet spot).
2. Ask the human **one question**: which aspect of each file is the reason it was picked
   (color · type · spacing/layout · component character · overall mood)? Skip the question
   if their words already said it.
3. Produce **one new DESIGN.md** in the project root, same section shape as the sources
   (Overview → Colors → Typography → Layout → Components → Do's and Don'ts):
   - Take each system from its named source *whole* — a palette is a system of roles, not a
     grab-bag. Don't average colors or mix type scales.
   - Resolve conflicts by the human's stated priority; note the choice in the file.
   - Open the file with a `Sources:` line crediting each zawqi design by slug — provenance
     is part of the file.
4. Show the human the result and ask for one round of reactions before building in it.

## Recipe: apply

*When a DESIGN.md is in hand and the build begins.*

1. **Read the whole file first** — the prose carries the reasoning; the do's and don'ts are
   rules, not suggestions.
2. **Map tokens into the stack's native form** (CSS custom properties, Tailwind theme,
   design-token file — whatever the project already uses). One place, named roles, no
   hardcoded hex scattered in components.
3. **Apply in this order:** foundations (color roles, type scale, spacing rhythm, radius) →
   chrome (nav, footer, buttons, inputs) → screens. The foundations do most of the work;
   resist restyling screen-by-screen.
4. **Translate, don't transplant.** The file describes a *site*; you are probably building an
   *app*. Marketing-hero drama becomes page-header hierarchy; a landing section rhythm becomes
   card/panel rhythm. Keep the voice (contrast, warmth, weight), adapt the anatomy.
5. Where the file says "not measured" or is silent, follow the do's/don'ts spirit and flag the
   gap to the human rather than inventing a system.

## Recipe: check

*After applying — measure the build, don't vibe. You are a poor judge of your own visual
output; computed styles are not.*

1. Run the app and execute this in the rendered page (browser tool, DevTools, or Puppeteer):

```js
(() => {
  const acc = { bg: {}, fg: {}, font: {}, radius: {} }
  for (const el of document.querySelectorAll("body *")) {
    const r = el.getBoundingClientRect()
    if (r.width === 0 || r.height === 0) continue
    const s = getComputedStyle(el)
    if (s.backgroundColor !== "rgba(0, 0, 0, 0)")
      acc.bg[s.backgroundColor] = (acc.bg[s.backgroundColor] ?? 0) + r.width * r.height
    acc.fg[s.color] = (acc.fg[s.color] ?? 0) + 1
    acc.font[s.fontFamily.split(",")[0].trim()] = (acc.font[s.fontFamily.split(",")[0].trim()] ?? 0) + 1
    if (el.matches("button, [role=button], input, a[class]"))
      acc.radius[s.borderRadius] = (acc.radius[s.borderRadius] ?? 0) + 1
  }
  const top = (o, n) => Object.entries(o).sort((a, b) => b[1] - a[1]).slice(0, n).map(([k]) => k)
  return {
    backgroundsByArea: top(acc.bg, 8),
    textColors: top(acc.fg, 8),
    fontFamilies: top(acc.font, 4),
    controlRadii: top(acc.radius, 4),
    headings: [...document.querySelectorAll("h1, h2")].slice(0, 5).map((h) => {
      const s = getComputedStyle(h)
      return { tag: h.tagName, size: s.fontSize, weight: s.fontWeight,
               family: s.fontFamily.split(",")[0].trim(), tracking: s.letterSpacing }
    })
  }
})()
```

2. Normalize `rgb(…)` to hex, then **diff against the DESIGN.md**: palette roles present and
   dominant in the right places? type family/weight/tracking on headings matching the scale?
   one radius canon, not five? any color in the build that the file never named?
3. Report drift as measured fact — "the file says ink `#0a0a0a`; headings render
   `rgb(51,51,51)`" — fix, and re-run until the diff is quiet. Repeat on the app's 2–3 most
   important screens, not just the first one.

*(This check is the recipe version. A hosted verification engine — zawqi's own measurement
pointed at your build — is on the roadmap.)*

---

## One-line install

Your human can hand you all of this in one line — in a `CLAUDE.md`, a Cursor rule, or a
one-off message:

```
Fetch https://zawqi.app/playbook.md and follow it. My zawqi token: zawqi_live_…
```

(Tokenless works too — you'll have the free subset.)