Why this project exists, written as a case study rather than a spec. The technical record is ARCHITECTURE-V2.md; the operating manual is ../CLAUDE.md. This document answers a question neither of those does: why did anyone start this.

Provenance. Reconstructed 2026-08-03 from evidence, because no goal statement existed in this repo. Sources: the portfolio repo (~/Windsurf Projects/portfolio — README.md, docs/decisions/adr-platform-portfolio-split.md 2026-07-26, docs/archive/portfolio-platform-market-research.md 2026-07-18), this repo's own commit history (b97c14c first commit, fcb48f6 the pivot), and the session transcripts of 2026-06-27 → 2026-08-02. Inferences are marked as such at the end — they are not presented as record.

Background

The product is a portfolio platform — a multi-tenant service where creatives publish their work. Its market is crowded: purpose-built portfolio tools (Format, Pixpa, Cargo, Carrd) and general builders (Squarespace, Webflow, Framer), against a baseline where the user's question is never "which portfolio tool" but "why pay anything at all when Behance is free." [S: market research, 2026-07-18]

Tenant #1 is the owner's own portfolio — a private, password-gated site with a lightweight built-in CMS, Astro rendering server-side on Vercel, content and projects stored as YAML. It is simultaneously a real product and the platform's proving ground: features are built and hardened there before anyone else sees them. [S: portfolio README.md]

Platform and portfolio are currently one deployment sharing one credential. A decision record dated 2026-07-26 sets out separating them in four phases, with one hard constraint: finish before tenant #2 exists. Stores are already partly tenant-scoped (plan, projects, uploads) and partly still global. [S: adr-platform-portfolio-split.md]

The interface was built in-house. Status pills, stat cards, timelines, tags, kanban boards, day accordions — written against a hand-maintained token set, under a standing rule: any pattern used three or more times is promoted to a single ratified implementation and refactored everywhere it appears. [S: session record, 2026-06-30]

That rule surfaced the first problem. Patterns kept crossing the three-use line and sitting unratified — copied into a new file, adjusted slightly, drifting from the version beside it. A contemporaneous review names it directly: components "currently sitting unratified, which is exactly the drift the UI registry exists to prevent." [S: session record, 2026-06-27]

So a registry was created to hold the canonical implementation and make it installable rather than re-copied. This repo's first commit is exactly that — registry.json plus one component, described in its own README as "a personal shadcn registry… no server, no build step," installed with npx shadcn@latest add davoranic/registry/status-pill. The component it shipped, status-pill, was one of the drifting ones. [S: commit b97c14c, 2026-08-01]

Problem

Then tenant #2 came into view.

In this market, look is the product. A portfolio platform whose tenants all resemble each other has nothing to sell. So the platform needed themes — and the conventional route is to author one design system and give it several skins.

A different bet was taken: don't author a design system, inherit them. Treat an existing published design system as a theme, so the theme catalogue grows by adding a repository rather than by designing another system.

That turns a design problem into a research question, and it is the question this entire project exists to answer:

Can any UI repository on GitHub be consumed as a theme?

The pivot is visible two commits into this repo, where the README was rewritten around "a design system's character expressed as values for the contract plus a capabilities declaration" — already noting that theme-salt unlocks density and fixes corners sharp while theme-shadcn has a free radius knob and no density. [S: commit fcb48f6, 2026-08-01]

Why these three systems

They were chosen for distance from each other, not convenience — to test the approach at the extremes of maturity and complexity.

Material 3 was added specifically because it disagrees about what a colour is. Salt and shadcn treat colour as a value — a role points at a hex; read it and you have it. Material 3 treats colour as a computed position on a tonal ramp: surface-container-high does not name a colour, it names neutral at tone 17, generated from a source colour under a scheme. The clone's own generated header names the context — audience 3P, platform Web, scheme Dynamic — and the ramps carry non-round stops (neutral12, neutral17, neutral22) that are the signature of computation rather than hand-picking. [S: material-web/tokens/versions/v0_192/_md-ref-palette.scss, _md-sys-color.scss]

Two systems where colour is stated; one where colour is derived. A contract that holds both has been tested against the widest available gap. If it only ever had to reconcile Salt and shadcn, it would be a much easier and far less interesting claim.

This also produced a rule now applied everywhere: the Material 3 edition is pinned to v0.192. When values are computed rather than authored, they move between editions, so "Material 3 says X" is meaningless without naming the edition that computed it.

What the three actually revealed

They are not three skins over one anatomy. They disagree about which knobs exist. Salt has a density axis shadcn has never heard of; shadcn has a size axis Salt does not have; Material 3 splits one of our components across five token files. You cannot theme across them by swapping values, because the values do not mean the same things — and anything that tries becomes one system wearing the other two as paint.

That failure has a name here, and a history: five rebuilds died of it before the current architecture. One system — usually shadcn, being easiest to read — quietly became the chassis, and the other two were draped over it. The result looks plausible and is wrong at the root, because it can never express a part the chassis system does not have.

Outcome

A contract, not a stylesheet. Every attribute of a component becomes a row; every system answers every row in its own terms — including "we don't have this," which is recorded with evidence rather than left blank. Every value traces back to the source file it came from.

Current state, measured from the working tree rather than asserted:

That middle figure is the actual result. If all three produced the same markup, the theme would be cosmetic and the premise false — so it is measured by a gate (scripts/check-anatomy.mjs) that exists for no other purpose.

The working answer to the research question is: yes, at a price. Each design system costs a column of cited values, and the differences that must be absorbed are structural rather than decorative. Once that is paid, drift stops — there is one implementation — and a fourth design system is a column, not a rewrite.

What is not yet true

• 288 of 584 value slots carry no citation. They were read from source, but the pointer back was never written down, so they cannot currently be re-verified. Concentrated in select, input, badge, card.
• Four of the ten build steps have no automated check, only judgement.
• 10 of 17 components have a behaviour test; calendar was generated but never visually validated.
• The claim is proven at 17 components, not at 79. Nothing here says it holds at scale — only that it has not broken yet.

Marked inferences

Two links above are reconstruction, not record, and should not harden into fact:

1. "Tenant #2 needs a different look, therefore the registry." The record shows multi-tenant theming explicitly trigger-gated on tenant #2, and shows this repo starting immediately afterward. No one wrote that causal sentence at the time.
2. Maturity-and-complexity spread as the selection criterion for the three systems. Confirmed by the owner in conversation (2026-08-03), not documented at the time of choosing.

Source. Condensed from ARCHITECTURE-V2.md (754 lines), written 2026-08-01. Quotations are from that document. The use case that motivates all of it is USE-CASE.md; the process it produced is in ../CLAUDE.md.

1 · The diagnosis

The starting point was a failure, not a blank page. The previous registry had a semantic tier only — and its own rulebook forbade component-scoped tokens outright ("slots don't belong to components"). Per-component decisions had nowhere legal to live, so they were hand-written into stylesheets instead.

The focus-ring alpha is the tell: hardcoded in 43 places at 60%, while shadcn's actual value is 50%. Nobody could have caught it, because per-slot provenance existed only as prose strings that build-themes.py stripped at compile time. Fidelity to the source was "undocumented, unqueryable, unchecked."

Everything in the current method — the citations, the [S]/[R] marks, the re-resolution gate — exists to make that one sentence false.

2 · How the method was found

Ten research passes were run. These five changed the design.

2.1 Survey what the industry actually does

Every mature multi-system token architecture converges on the same shape: three value tiers, with tier-skipping forbidden.

Salt writes it as one CSS pattern on every styleable property:

height: var(--saltButton-height, var(--salt-size-base));
/*          ^ override switch (empty)   ^ semantic default */

The override slot is deliberately never filled by Salt itself — it exists so someone plugging in can flip that one switch without forking the component. In production at JPMorgan.

Taken into the method: the three-tier shape, and the idea that a design system plugs in by filling switches rather than by being rewritten.

2.2 Read the clones — and find they are not peers

The audit changed the mental model. The five source systems occupy different layers of what a design system even is.

Taken into the method: motion becomes a first-class token category, and every joining system declares its layer — so we "stop translating apples into orchestras."

2.3 Find that our failure already has a name

The literature names the exact anti-pattern we had hit: "semantic tokens that are one brand's decisions in disguise." With a published defence attached:

• prove the contract against two or more visually divergent systems before freezing it;
• promote a decision from component tier to semantic tier only when three or more components demonstrably share it.

Semantic tokens are earned by reuse, never designed speculatively from one system.

Taken into the method: the two-system proof requirement, and the rule that nothing enters shared vocabulary because one system wants it.

2.4 Notice which of Salt's own rules survived

Salt violates its own written rules — 61 components reference the palette layer directly, against their own documentation. But the rules they encode as build-failing lint (cross-theme token parity) hold perfectly.

Rules in prose decay. Rules in CI hold.

Taken into the method: the vocabulary is a JSON schema that fails the build, not a convention in a document. Every rule that matters got a gate.

2.5 Stress-test against three systems we don't ship

Before committing, the model was tested against Material 3, Apple's HIG, and Microsoft Fluent 2 — deliberately including one that is not a token system on purpose.

The four-layer model held against all three. M3 maps almost one-to-one (ref/sys/comp ↔ L1/L2/L3); Fluent's global/alias tiers are L1/L2; Apple's semantic colour API is an intent-named L2 — "Apple essentially invented that idiom." Nothing required a redesign.

But it caught one structural flaw, and eleven additive schema extensions.

3 · The flaw the stress test caught

Our own anti-retrofit gate — "no semantic slot without proof across two or more systems" — would have recreated the retrofit disease one layer up.

Material 3 has 51 semantic colour roles: a five-step surface-container ladder, fixed roles, inverse roles. No second system has most of them. The gate would have barred them from the shared tier forever, and their values would have had nowhere to live except per-component switches — destroying sparse overrides for every container-shaped component.

Same failure, new address.

The fix: adapter-private semantic namespaces. A design system may declare its own semantic slots (x-m3-surface-container-high) that live one level above its component switches and resolve only inside its own fallback chains. The shared contract stays lean and proven; a rich system keeps its full vocabulary without leaking it into components. Promotion to the shared contract still requires the two-system proof.

This is the clearest evidence the stress test earned its cost: the flaw was in our own rule, it looked like a safeguard, and it would only have surfaced after building against a system rich enough to trip it.

4 · What each system taught us

Material 3 — the easiest and most dangerous adapter. Three of its most characterful subsystems are functions, not values: colour is derived (seed → HCT → tonal palettes → scheme). You cannot copy a Material 3 colour and claim fidelity; you have to record which computation produced it. Hence the edition pin to v0.192.

Apple — the boundary test, not a token system on purpose. "Declared absence" must exist beside "declared gap." A contract has to distinguish this system chose not to have this from we haven't looked yet. Fallback chains also had to become capability-conditional.

Fluent 2 — the friendliest adapter, 8 of 12 findings fitting as-is. No component-token tier exists at all; 467 alias tokens flow straight into components. High contrast is a first-class third mode, not a dark variant. And density models are genuinely plural — Salt rescales global foundations, others do not — so density cannot be one shared axis.

5 · Setting up the process

The research produced a shape; the process turns it into work. Three phases, in order, no skipping ahead.

Phase 2 is where nearly all the work lives, and it is the only layer that repeats — the ten-step build loop, run once per component, each step existing because skipping it produced a real bug.

One honest note on the phases. They are not as clean as the ordering implies. Three foundations pages were later found wrong by a component re-reading the source, so phase 1 is not "finished" before phase 2 begins. Foundations are evidence, not scripture.

The artifact every other document points at. Thirteen component matrices, the schema that validates them, and every template and column refer back to what is defined here. The operating version lives in ../CLAUDE.md § THE ANATOMY, written for whoever builds next; this page is written to be understood first.

How we got to the matrix

The six segments were not designed up front. They arrived in three moves, each forced by something that failed.

1 · The old anatomy files recorded the wrong thing. They listed which slots a part consumed, and never what for:

"root": [action, radius-control]

That cannot answer the only question anyone actually asks — what is this part's background? It names ingredients without saying which dish.

2 · So they became an attribute inventory — per part, per attribute, per state, with the system's own token beside each one:

"root": {
  "background":       { "token": "button-background",         "semantic": "action" },
  "height":           { "token": "button-height",             "semantic": "control-height-md" },
  "opacity@disabled": { "token": "button-disabled-opacity",   "semantic": "opacity-disabled" }
}

The consequence is larger than it looks. Once the CSS is generated from that file, inventory-first stops being a preference and becomes the only possible order. You cannot write the stylesheet first, because the stylesheet is an output.

3 · Then the calendar pilot failed in a way that added two segments. The style layer validated cleanly — colours, sizes, spacing all correct. And the component still failed the native-speaker test: it did not read as a Salt calendar to someone who knows Salt, because the differences were in structure and content formatting, neither of which the style layer could express.

That failure produced two rules that outrank convenience:

• No inherited chassis. The renderer is generated from the union of every system's parts. "Theme-invariant structure" is only what remains after every per-system structural difference has been made a row.
• A coverage report that counts only style cells is lying. Structure and content rows must be counted too, and a switched-on row the implementation cannot express fails the build.

Which is why there are six segments rather than one. Character does not live only in colour.

What a matrix is

A table.

• Rows are attributes — one row is one addressable characteristic of one part, optionally in one state.
• Columns are design systems — salt, shadcn, m3.
• A cell is one system's answer for one attribute.

The vocabulary is deliberately narrow. Say row and cell. Never say "token" for a row — a token is a resolved value. Never say bare "attribute" for a DOM data-* hook — that is a data attribute.

Row names

Grammar: <piece>.<part>[.<subpart>].<property>[@state], validated by contract/template.schema.json against ^[a-z]+\.[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*(@[a-z][a-z0-9-]*)?$

Narrowest part last. The @suffix narrows to exactly one state or one non-default axis value.

The six segments

Each has a test. If you cannot answer the test, the row is in the wrong segment.

Character lives in structure and slot as much as in style. Salt clamping a badge count to 999+ while shadcn prints 1000 is a slot difference, and it is the entire personality of the component.

Answering a row

Policy — who may switch it off

Cell kinds

Evidence marks

[S] means grepped from the clone. [R] means inferred from a spec page, an APG convention, or published docs — and the reason must be given.

All Material 3 structure and behaviour is [R], because material-web ships tokens with no component to read. This is not a formality: three of the twenty-one [R] cells in the calendar were wrong. [R] is a debt, not a citation.

One row, all three systems

style.root.opacity@disabled — the ordinary disabled state.

Three systems, three answers, and the third is not even the same kind of answer — Material 3 dims the container and the text by different amounts, so "disabled" is a different mechanism rather than a different number. A contract that stored one opacity per component could not hold this row without lying.

The seven ways this drifts

All seven have been observed in this repo, not imagined.

1. A retrofit — building on one system's component and draping the others over it. check-anatomy.mjs is the tripwire.
2. A dead axis — prop declares values that no style row discriminates, so three of four tones render identically and the generator still reports OK.
3. A structure row with no size — the part renders with no dimensions, and an <svg width="100%"> inside it silently inherits 300px.
4. Cascade inversion — a state row emitted before the axis row it overrides, so it loses at equal specificity and never applies.
5. A documented-but-unimplemented behaviour — info rows have no gate.
6. An unshared derivation — when a system tokenises in a different kind than we emit (M3 gives dp, we need a shadow string), the conversion is ours. Publish it in foundations/ the first time or it drifts once per component.
7. An unstated denominator — a check reporting what it examined as though it were everything. This has bitten three separate times and is the most dangerous, because the output looks clean.

Where the matrices live

Every docs/<NAME>-MATRIX.md carries a generated Resolved values block — every row against every system, read from the column files by scripts/sync-matrix-values.py. The prose above that block is hand-written. If the two ever disagree, the block is the data and the prose is the claim.

Gates, last run

Run locally at 2026-08-06T10:28Z. CI cannot re-run these — they need the design-system clones, which are not in this repo — so this is the last real result, not a fresh one.

Coverage against the map

Every canonical component, by section. The denominator is the whole map, not the built set.

What each component owes

The open debts, stated plainly

• 288 of 584 value slots carry no citation. They were read from source, but the pointer back was never written down — so they cannot currently be re-verified.
• 7 of 17 components have no behaviour gate — alert, button, calendar, input, select, spinner, tooltip.
• 1 component generated but never visually checked — calendar.
• 61 canonical components remain unbuilt. The claim is proven at 18, not at 79.

One table per component: attributes down, design systems across. Segments collapse. Read from contract/templates/*.json and themes/columns/*.json at build time — nothing hand-written, so it cannot drift from the data.

All components