# Design

Mockingbird looks like a field notebook kept on a northern mockingbird, Mimus polyglottos.
The bird learns another bird's song and sings it back. The product does the same with an
API: a familiar call, answered in kind. The site, this file, the GitHub README, llms.txt,
and every package published to npm use the same sentence and the same mark.

## The sentence

**Familiar calls. Faithful echoes.**

The longer note, under the title on the site and in the README, is: "Like its namesake,
Mockingbird learns a familiar call and answers in kind. Real API shapes, stateful behavior,
right inside your tests."

Both strings live in `sites/docs/src/lib/content.ts` as `IDENTITY`. Change them there.
`bun run readme:sync` and `bun run llms:sync` rewrite the generated files. Do not paraphrase
the sentence in a package README or on a page.

## The mark

`sites/docs/public/identity/mockingbird.png` is the mark: a northern mockingbird in profile,
long tail, two white wing bars, inside a circular paper plate. That path is
`MARK_REPO_PATH` in `sites/docs/src/lib/content.ts`. The docs site serves the same file
for the favicon and the header. The README image is `IDENTITY.mark`, that file on `main`.
`bun run check:readme` fails when the file is missing from the repo.

`sites/docs/public/identity/mockingbird-field.webp` is Plate I, the hero specimen. It stays
on paper in both themes. Do not recolor it, crop the wing bars out of it, or replace the
mark with an emoji.

On the docs site, `/identity` shows the mark, the plate, and the live tokens. This file is
the rules. `/docs/design` renders this file.

## Color

Drawn from the bird and the plate.

| Token | Light | Role |
| --- | --- | --- |
| `--bg` | `#f3eee4` | Notebook paper |
| `--fg` | `#1e2823` | Ink. Text, and the wing bars |
| `--accent` | `#243f34` | Live oak. A filled action |
| `--clay` | `#8d4a32` | The song. Species labels, the second half of the title, the current page |
| `--sage` | `#7d8a80` | Plumage. A strong border |
| `--eye` | `#c6a15a` | The eye-ring. One highlight, never a fill |

Dark theme inverts paper and ink. Oak becomes the pale wing-bar flash (`#d5e0cc`) so a filled
button still reads. Clay lightens to `#e2b094`. Error and HTTP-method colors stay semantic
and are not part of the identity.

The header theme control offers system, light, and dark. System is the default and follows
the operating system. An explicit choice is stored as `mb:theme`.

The README license shield uses oak (`243f34`).

## Type

Headings are a serif: Iowan Old Style, then Palatino, then Georgia. Interface text is Avenir
Next, then the system sans. Code is the system mono. No webfont is loaded. The second phrase
of the title is italic and clay. Species names are italic.

## Baseline

Every HTML surface starts from `packages/ui`. A full document includes `CSS_RESET`. A widget
mounted inside another page uses `scopeReset(root)`, which keeps the same baseline inside
that root. The surface's own type, color, and spacing come after the reset.

## Motifs

- **Wing bars.** Two rules, a thicker one and a thinner one, with a gap. They are the
  mockingbird's field mark. The footer is closed by a full-width pair. A prose heading
  carries a short pair. The header is a single rule.
- **Specimen.** A rectangular paper frame, a 1px ink border, almost no corner radius, no
  lift on hover. The hero plate and the service cards are specimens. Hover draws a clay bar
  on the leading edge.
- **Annotation.** Clay is for notes: eyebrows, the current nav item, the song in the title.
  It is not a second fill for buttons or page backgrounds.

Corners are `--radius` (3px) or `--radius-sm` (2px). A coverage meter may stay a thin bar.

The page scrollbar stays visible, so moving between a short page and a long one does not
shift the layout. Its track is the page background (`--bg`) and its thumb is sage.

## What to refuse

- Gradient text, purple, and glow.
- An emoji as the mascot. The mark is the bird.
- Traffic-light dots on a code window. A code sample is a field note: a filename and a wing bar.
- Pill buttons, pill badges, and pill filters.
- A different sentence on npm than on the site.

## Where each surface gets it

| Surface | What it must show |
| --- | --- |
| Docs site | Tokens in `sites/docs/src/styles/global.css`. Specimens at `/identity`. This file at `/docs/design`. |
| GitHub README | Generated by `scripts/readme.ts` from `IDENTITY` and this guide. The mark, the sentence, and the note are in the header. |
| `llms.txt` | Generated by `scripts/llms-txt.ts`. The opening blockquote starts with the sentence. |
| npm | Every public package README starts with `# <package>`, a blank line, then the `EPIGRAPH` from `content.ts`. `pack:check` fails when that line is missing or rewritten. The rest of the README stays the integration guide. |
| Package pages on the site | Render that same README, so the sentence appears there too. |

The sentence is the only marketing line a package README carries. Do not add a second banner,
a logo image, or a palette to a service README. Agents read those files to call the API.

## Adding a page

Use the tokens. Use `BirdMark` for the bird, not a new drawing. Use `.eyebrow` for a
species-style label. Use `.btn`, `.badge`, and `.prose`. If a new component needs a radius,
a color, or a shadow that is not a token, add the token and the reason to this file in the
same change.