Motir

Repo: motir-core. One PR. The three-file design asset for the public developer-documentation surface — the one user-facing surface in an otherwise headless story, and the reason this story carries a design card at all.

Produce the standard THREE-file set under a new design/api-docs/ area: design-notes.md + api-docs.mock.html (built from the real design system, not a sketch) + a same-basename api-docs.png export. Compose the shipped primitives (components/ui/*) and the swap-layer tokens — colour through --el-*, shape through the element-semantic shape tokens, never Tier-0 --color-* and never raw rounded-md / p-2. Invent no colour.

The three pages to draw

1. The API reference — the operation catalogue. A navigable list of operations grouped by resource (work items, projects, sprints, backlog, ready set, workspaces, me), and the operation detail: method + path, the required scope, parameters, request body, the response envelope, the error statuses, and a copy-pasteable authenticated example (a curl with a Authorization: Bearer motir_pat_… placeholder). Draw how a reader gets from the list to one operation and back.
2. The getting-started guide — a linear read: mint a token → the first authenticated call → paginate → read an error → read the rate-limit headers. Draw the page's rhythm (prose, code block, callout) rather than writing the words; the words are 11.4.8's.
3. The stability & deprecation policy — a short prose page: what v1 guarantees, what "additive" means, the deprecation path.

Draw the three as ONE surface with shared chrome — a docs shell with in-page navigation — not three unrelated pages.

The ACCESS PATH — draw BOTH doors, in their own surfaces

A design that draws only the destination gets its entrance improvised at build time. There are two entrances and they are different in kind:

• The public door. The reference is reachable by a developer who is NOT logged in. Ground this in the shipped public chrome — app/(public)/_components/PublicTopBar.tsx and app/(public)/explore/_components/ExploreFooter.tsx are what an unauthenticated visitor already sees — and in the shell/nav convention in design/shell/. Verify how the shipped public group actually navigates before drawing the entry; do not invent a new nav pattern for one page. Show the affordance in its parent surface: where it sits, what it is labelled.
• The in-app door. A user who has just minted a PAT is the reader with the sharpest need. Draw the entry affordance on the shipped API-tokens settings page (app/(authed)/settings/account/api-tokens/page.tsx, designed in design/settings/token-scopes.mock.html) — a link to the reference and to getting-started. This design owns ONLY that affordance on that page; it does NOT redraw the token manager, which design/settings/ owns. Say so in design-notes.md on both counts, so neither design redraws the other's elements.

States, scale and reading conditions

Plan the real-product shape, not the happy path: the reference renders ~25 operations today and must stay navigable as the API grows; the operation list needs an in-page find; the page must be readable on a phone (a curl line is wide — say how it wraps or scrolls, and the wide block scrolls inside its own container, never the page); and the surface has a failure state — the spec could not be loaded — that says what a reader should do. Draw the light and dark treatments the token layer implies.

Scope BOUNDARY

Ends at the design asset. It writes no page, no route and no copy — 11.4.7 builds the reference and both doors, 11.4.8 writes the guide and the policy. It does not redesign the settings token manager, the public explore pages, or the public top bar itself — it places one affordance in each and cites the design that owns them. It does not decide the renderer or the routes: 11.4.1 pins those, and this asset draws to that answer.

Acceptance criteria

• design/api-docs/ holds the complete three-file set — design-notes.md, api-docs.mock.html, api-docs.png (same basename) — with the mock built from the real design system and the PNG exported from it.
• The mock draws all three pages plus the shared docs chrome, including the operation-detail view with a copy-pasteable authenticated example.
• Both access paths are VISUALIZED in their parent surfaces — the public entry as it appears in the shipped public chrome, and the settings entry as it appears on the API-tokens page — each labelled and placed, not described in prose alone.
• design-notes.md names every composing primitive and the --el-* / shape tokens used, cites design/settings/ and design/shell/ as the owners of the surfaces this one only places an affordance in, and states explicitly which elements this design does NOT own.
• The nav treatment of the public entry is grounded in how the shipped public group already navigates, with that convention cited — not invented for this page.
• The wide-content behaviour (code blocks), the small-viewport layout, the light/dark treatments and the spec-unavailable state are all drawn.
• No invented colour: every colour resolves to a palette token.

Context refs

• design/settings/token-scopes.mock.html · design/settings/design-notes.md — the shipped PAT surface this one places a door in and must not redraw.
• design/shell/ — the nav convention a new top-level view's entrance is grounded in.
• app/(public)/_components/PublicTopBar.tsx · app/(public)/explore/_components/ExploreFooter.tsx · app/(public)/explore/layout.tsx — the shipped public chrome the public door lives in.
• app/(authed)/settings/account/api-tokens/page.tsx — the in-app door's parent surface.
• components/ui/* — the primitives to compose; app/globals.css — the --el-* and shape-token layers.
• docs/decisions/public-api-conventions.md §§3–8 — the scopes, errors, pagination and stability facts the reference presents.
• Blocker: 11.4.1. The card whose content this surface holds: 11.4.8. Parent story: 11.4.