# The Laws of Design

The patterns that govern beautiful thought and beautiful nature must also govern design: reduction, recursion, hierarchy, proportion, rhythm, relationship, and proof.

## Decision mandate

- Does it aid clarity or orientation?
- Does it provide a material benefit?
- Does it relieve a material detriment?
- If every answer is no, remove it.

## purpose

D01. **Existence test.** Every recurring word, heading, link, widget, control, badge, and mark must aid clarity, provide a material benefit, or relieve a material detriment. Otherwise remove it.

D02. **Reduction before addition.** Repair incoherence by removing, grouping, deferring, or collapsing competition before adding form. Perfection is reductive.

## nature

D03. **Nature is the precedent.** Branching trees, nautilus spirals, and golden-angle phyllotaxis are the precedent. Recurrence, hierarchy, proportion, and fractal self-similarity are structural constraints—not decorative references.

D04. **One recursive grammar.** Apply the same law to the site, page, section, component, paragraph, image, interval, graph, admin surface, and source module.

## system

D05. **One visual system.** Exactly three type roles—display, reading, machine voice—one restrained accent, one spacing scale, one radius, and one contrast law across public, governance, graph, and admin surfaces. Which typeface fills a role and which hex fills the accent is not law; those are values of the active runtime profile.

D06. **Principles are immutable; values are profile.** A principle (one accent, three type roles, tokens-only, reduction, one contrast law) is immutable and lives in this law. A value (a hex code, a typeface name, a pixel size, a radius) is mutable state held by the active runtime profile — defaulted in functions/_lib/design/tokens/core.js, overridden through /api/design, disclosed live at /design. The law never names a hex or a face as an obligation; a profile never violates a principle. Any document that describes a concrete value describes a profile, must say which profile, and must never present it as law.

D07. **Deliberate proportion.** Type scale, spacing intervals, and measures are one explicit, deliberate ladder held in the profile tokens — every step chosen, no step invented per-surface. Quantified reading bands bound every profile: body text 15–25px, line spacing 120–145% of size, measure 45–90 characters.

D21. **Restraint is enough.** One accent color, total. Neutrals — a ground, layered surfaces, an ink ramp, a hairline — carry the hierarchy; contrast, weight, proportion, and interval carry the meaning. The accent's hue is a profile value; the count of one is the law. (Amends the rescinded monochrome clause: the owner rejected pure black-and-white; restraint, not absence of color, is the obligation.)

D22. **Source is a REST object.** Organize source modules like a JSON object: identity, content, instructions, relationships, invocation, authority, conformance, representations, version, provenance.

## orientation

D08. **Location before options.** Expose the reader's current location, parent category, sibling family, and clear return path before presenting onward choices.

D09. **Hierarchy before volume.** Fold complexity into the smallest useful categories and subcategories. Expand one relationship family at a time.

D10. **Sticky highest-level navigation.** Keep a stable sticky header with only the highest-level human categories; place ontologies and subcategories inside intentional expanding hubs.

## reading

D11. **Editorial cadence.** Repeat idea → development → image, visual, comparison, or proof → subheading. Never allow more than two prose beats without a designed change in reading mode.

D12. **Invite reading.** Set display in a literary serif, hold measures near sixty-six characters, and tune line spacing, heading scale, paragraph length, and contrast until reading feels inevitable rather than laborious.

D13. **Lists disclose logic.** A list must become a category, sequence, comparison, map, or compact logic object. Never render walls of bullets, links, or raw pipe tables.

## complexity

D14. **Collapse every optional layer.** On every widget, default model commentary, provenance, machine procedures, raw fields, graph detail, controls, and secondary actions to a named collapsed disclosure.

D15. **Human surface first.** Raw JSON and API resources must be explicitly labeled machine data and must never appear as ordinary primary navigation or accidental reader destinations.

## interaction

D16. **Interaction must clarify.** Search, filters, maps, AI interaction, and expandable ontologies must reduce uncertainty or reveal relationships. Interaction without comprehension is removed.

D17. **Relationship before click.** Show why a link exists and what family it belongs to before asking a person to click it.

## quality

D18. **Content and design are inseparable.** Unreadable design makes content unclear. Rendering must reject or repair malformed tables, link walls, contrast failures, and source structures before they reach readers.

D19. **Queryable and discoverable.** Every reader surface requires categories, search or traversal, semantic headings, canonical metadata, structured data, valid internal links, and responsive behavior.

## source

D20. **The inside is beautiful.** Organize source as law → primitive → composition → surface → proof. Use shared names, one-directional dependencies, and no scattered local design inventions.

## knowledge

D23. **Page and skill and directory row are one.** A page explains to humans. Its skill directs models. Its directory row executes. They share one identity, version, and provenance but speak in the right language for each audience.

D24. **Widgets are content.** Evidence, capabilities, and directory widgets are not decoration. They are the page's meaning made visible and interactive.

D25. **Sources wear their platform.** An embedded source renders in its platform's own identity — a tweet looks exactly like a tweet, Reddit exactly like Reddit, a WSJ story wears the WSJ masthead, an organization speaking in its own name gets a letterhead and never someone else's masthead. Card interiors are the one sanctioned exemption from the profile tokens, because the mimicry is the meaning; everything around the card stays on tokens. Cards are centered, carry their ledger hash, and are disclosed as first-class specimens on /design.

D26. **Article and Skill are one.** An article explains a concept to a human. Its Skill directs model behavior. They share one identity, meaning, version, and provenance while using distinct language for distinct audiences.

D27. **Maximal interoperability.** Article, Markdown, JSON, directory row, Skill, OIP contract, REST resource, graph node, conformance target, version, and receipt lineage are typed expressions of one identity. Shared identity does not require shared wording.

D28. **Failures become knowledge.** Repeated model failures become negative-knowledge facets that can generate an article amendment, Skill instruction, conformance test, code repair, directory clarification, and regression proof.

## Representations

- **article:** /a/design-law — explain meaning (human reader)
- **markdown:** /api/articles/design-law?format=markdown — portable explanation (human or model reader)
- **json:** /api/articles/design-law — transport the complete typed object (software)
- **directory:** /api/directory/DESIGN_LAW — discover identity and contract (router or operator)
- **skill:** /api/articles/design-law/skill — teach behavior (LLM)
- **oip_contract:** /api/dispatch?key=DESIGN_LAW — discover authority and invocation (agent or protocol client)
- **invoke:** /api/dispatch?invoke=DESIGN_LAW — execute behavior and return proof (authorized agent or protocol client)
- **graph:** /api/articles/design-law/voxels — traverse relationships (graph client)
- **versions:** /api/articles/design-law/versions — inspect amendment lineage (auditor)
- **conformance:** /api/articles/design-law/conformance — falsify claims and prescribe repair (test runner or critic)