DesignTokens

The design tokens of Milpa, shipped so a surface can look like the house WITHOUT copying them. ── WHY THIS EXISTS, AND WHY HERE ──────────────────────────────────────────────────────────────── Until now the tokens only travelled by being copied into a package's own `assets/`. Three packages carried them — `milpa/admin`, `milpa/agent-workspace`, `milpa/desktop-app` — with identical copies that had already DRIFTED from the source: measured by hash, all three were missing `--space-32`, a token added upstream that never came down (greenhouse decisions/0243). The surface that made it visible was the passkey ceremony. `/webauthn/enroll` is served by `milpa/app-runtime`, which vendors nothing, so its page carried `system-ui` and hand-picked hex — not out of neglect, but because there was nowhere to get the house's own vocabulary from. And it could not simply depend on the panel: enrolling is the PRECONDITION of having a panel session, so a house with no panel still has to be able to let somebody in. They live here because this package already ships what a component needs to run in a browser and depends only on `milpa/core` and `milpa/live` — the same reach the tokens need, and no cycle. ── WHAT THIS IS NOT ───────────────────────────────────────────────────────────────────────────── Not the component stylesheet. The tokens are the house's VOCABULARY — its ramps, its type scale, its spacing; the bundle that styles `mui-*` classes is a different artifact with a different lifetime, and it stays where it is until something measured says otherwise. A separate class from {@see ClientRuntime} on purpose: that one's docblock says «two runtimes and one vendored library, ON PURPOSE», naming a decision. A stylesheet is not a runtime, and folding it in would blur a boundary somebody drew deliberately.

public static function path(string $name): ?string

The absolute path of a shipped file, or null when `$name` is not one of them. A name this package does not own answers `null` and never a path: a host serves whatever this returns, so anything looser would be a file read with extra steps.

Parameters

public static function urls(string $prefix = ''): array

THE URLS ONE HOST SERVES THESE AT, UNDER ITS OWN PREFIX — the canon, called instead of typed. 🚨 EACH HOST STILL SERVES THEM ITSELF. That is a decision, written where it is made ({@see iconLink()}: «each serves this file from its own asset route, with its own cache policy»), and this method does not touch it: a plugin whose pages work the moment it is installed cannot depend on another plugin's routes being mounted. What it replaces is the TYPING. Measured before writing it: nine sites across three packages spelled these names into route declarations and `<link>` tags by hand — five routes in `milpa/app-runtime`'s passkey plugin, three `<link>`s in the framework's welcome page, a wordmark `<img>` in the gate renderer — while `defaultUrls()`, which exists for exactly this, was called by nothing in any `src/`. Only its own test called it. The canon was written and never wired, which is how a fourth prefix (`/design/`) got invented in one afternoon without its author seeing the other three (greenhouse decisions/0308). The `fonts/` segment is the reason a shape authority is worth having at all: `milpa-fonts.css` names its faces RELATIVELY, so a host that flattens them serves a stylesheet whose every `src` is a 404 — a defect that shows up as missing type, not as an error.

Parameters

Returns

name => URL

public static function defaultUrls(): array

The same set at the root — {@see urls()} with no prefix. Kept because it is published API and two tests name it; it is now one call deep so the two can never disagree about the shape.

Returns

name => URL

public static function iconLink(string $href): string

The `<link>` a page declares its icon with — ONE tag, because five pages needed it. 🚨 THE POINT IS THAT THE PAGE DECLARES IT, not that a route exists. A browser only asks for `/favicon.ico` when the document says nothing, and that root belongs to no plugin — so five hosts writing five copies of this tag was the duplication, and five 404s was the symptom (greenhouse decisions/0286). `$href` is the host's: each serves this file from its own asset route, with its own cache policy.

Parameters

public static function contentType(string $name = self::TOKENS): string

The MIME type a host should serve `$name` with — by extension, not by default. Falling back to `text/css` for anything unrecognised is how an image gets served as a stylesheet: the `<img>` renders nothing, no error is raised, and the page looks styled while it is not. Same failure shape this class exists to end, one level down.

Parameters