01

The system has no look of its own

Anyone adopting this brings their own visual identity, so the thing underneath cannot have one. Not a muted one, not a tasteful one — none.

Everything else follows. The anatomy carries no color because a skin must be able to set it. The contract is versioned because what is built on it references it by name. A skin is values rather than a stylesheet, because the person supplying it must not be able to reach a selector.

Building. if a decision would look wrong under a different palette, a different typeface or a different set of corners, it belongs to a skin and not to the system.

02

A name is a promise; a value is not

Names are fixed, versioned, and breaking to change. Values are free and change per site.

That split is the whole architecture. It is why an entire system can be repainted without touching a component, and why renaming one token is a major version while changing every color in it is not a version at all.

Building. spend time on the name. The value can be wrong and corrected in an afternoon; the name cannot.

03

The platform decides before we do

Behavior and vocabulary both. A native element plus the contract, unless the pattern genuinely needs a focus scope, collision detection, or a portal. And where the platform has a word — role="banner", aria-expanded, [readonly] — that is the word.

Platform behavior is tested by browser vendors against more assistive technology than we will ever own. A control we write is a control we maintain forever. A name we invent is a name someone has to translate on every reading.

Building. start from the native element and remove what you do not need. Invent a name only where the platform has none, then define it once and never vary it.

04

Accessibility is a floor, not a feature

Not a phase, not a checklist, not something a skin may trade away for a look. A component that cannot be operated by keyboard is not a component with a bug — it is not finished.

Conformance to a pattern spec is a behavior contract, and that is not the same as an accessibility claim. What has been tested, and against what, is stated rather than implied.

Building. the keyboard contract is part of the component, not a pass over it afterward. A shortfall that needs a design decision is recorded in the open with a reason, never quietly excluded from the check.

05

The system holds what is shared; the product holds what is not

A thing belongs here when more than one consumer needs it. A thing built well but used once is noise in the contract and maintenance forever.

The system solves the ordinary problem so a product can spend its effort on the problem only it has. It does not attempt the product's job, and it does not decide when a product adopts it.

Building. two questions before adding anything. Does more than one thing need this? And does something need it *now*, rather than could something need it later? A name added because it completes a pattern, with nothing asking for it, is the one to refuse.

06

The simple case stays simple

The common use is the one that must read cleanly. Flexibility is layered on top for the case that needs it, never spread across the case that does not.

A prop every caller must think about is a tax on every call site. A default that is right most of the time is worth more than an option that is right always.

Building. write the simplest call first and make it work. If the elaborate case forces a parameter into the simple one, that is two components wearing one name.

07

Consistent, not uniform

The same idea gets the same name everywhere. That is consistency, and it is not the same as forcing every part of the system into one shape.

A pattern with a genuine local need gets a local answer. What must never vary is the vocabulary — a word meaning one thing here and another thing there costs more than any amount of surface variation.

Building. before inventing a name, look for the existing one. Before forcing a component into a shared shape, ask whether the shape is carrying meaning or only symmetry.

08

A change must reach whatever adopted the old answer

Being wrong is ordinary. Leaving something stranded on the old answer is not.

A rename ships with a way to keep the old name working. A breaking change ships with the version that says so. Anything generated from this system records which version generated it, so it can be found later and brought forward.

Building. before changing a name, answer how you would find everything using the old one. If there is no answer, that is the work to do first.

09

Documentation that runs beats documentation that reads

A specimen that renders is worth more than a paragraph describing what would render. Anything demonstrating the system should be the system, executing, so it cannot quietly fall out of date.

Prose explains why. It is a poor way to say what something does, because nothing checks it.

Building. make the example real and make a gate assert it. A code sample nothing runs is a claim, and claims drift.

10

A rule nobody enforces is a preference

If it matters, a gate checks it before a commit lands. If a machine cannot check it, that is written down with the reason, so the next person knows it needs a reader rather than a script.

A green check means what it measures and nothing more. Reading it as broader approval is how a system drifts while every light stays on.

Building. when you write a rule, write the check with it. If you cannot, say plainly what is unchecked and who has to look.

11

Every rule says where it stops

A rule stated without its exception is one someone will apply where it breaks, and then distrust everywhere else. The exception is written at the moment it is made, including when it feels obvious.

Building. when a rule gains its first exception, that is not the rule failing. That is the rule becoming usable. Write it down beside the rule, not in a commit message.

12

What was rejected is recorded

A commit records what changed. Nothing records what was considered and abandoned, and that is precisely the thing re-proposed every six months.

Building. when you decide against something, write down what it was and why. Records of what happened are never rewritten to match a decision made later — they are true as of their date.