Design
docs/DESIGN.md · the same file GitHub renders ·Edit on GitHub ·Markdown
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.