# 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 it is editorial art, does one story-specific idea remain readable with no text, table, UI collage, or generic AI imagery?
- If every answer is no, remove it.

## purpose

D01. **Existence test.** Every recurring word, heading, link, widget, control, badge and mark stays ONLY IF it aids clarity, gives a material benefit, or removes a material detriment. IF none THEN remove it.

D02. **Reduce before adding.** IF a surface is incoherent THEN remove, group, defer or collapse the competing elements. NEVER add form before reduction is exhausted.

## nature

D03. **Nature is the precedent.** ALWAYS treat recurrence, hierarchy, proportion and self-similarity as structural constraints. NEVER as decorative reference.

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

## system

D05. **One visual system.** ALWAYS use exactly three type roles: display, reading, machine voice. ALWAYS one accent, one spacing scale, one radius, one contrast law across every surface. The typeface and the accent value are profile state, NEVER law.

D06. **Principles are law, values are profile.** A principle is immutable and lives in this law. A hex, a typeface, a pixel size or a radius is profile state, defaulted in the token module and overridden through /api/design. This law NEVER names a value as an obligation. A document naming a value ALWAYS names its profile.

D07. **Deliberate proportion.** Type scale, spacing and measure ALWAYS come from one explicit ladder in the profile tokens. NEVER invent a step per surface. Body text is ALWAYS 15-25px, line spacing 120-145% of size, measure 45-90 characters.

D21. **One accent, total.** ALWAYS use exactly one accent colour. Neutrals ALWAYS carry the hierarchy; contrast, weight, proportion and interval ALWAYS carry the meaning. The hue is profile state; the count of one is law.

D22. **Source is a REST object.** A source module ALWAYS carries identity, content, instructions, relationships, invocation, authority, conformance, representations, version and provenance.

D36. **Every widget is on the index.** /widgets ALWAYS renders one live specimen of every widget type with its key, its fields and its governing clauses. IF a widget type is added THEN its specimen is added in the same change.

## orientation

D08. **Location before options.** ALWAYS show current location, parent category, sibling family and return path before any onward choice.

D09. **Hierarchy before volume.** ALWAYS fold complexity into the smallest useful categories. ALWAYS expand one relationship family at a time.

D10. **Sticky top-level navigation only.** The sticky header ALWAYS carries ONLY the highest-level human categories. Ontologies and subcategories ALWAYS live inside expanding hubs.

## reading

D11. **Editorial cadence.** ALWAYS repeat: idea, development, visual proof, subheading. NEVER run more than two prose beats without a change in reading mode.

D12. **Invite reading.** ALWAYS set display in a literary serif and hold measure near 66 characters. NEVER ship line spacing, heading scale, paragraph length or contrast that makes reading laborious.

D13. **Lists disclose logic.** A list ALWAYS becomes a category, sequence, comparison, map or compact logic object. NEVER a wall of bullets, links or raw pipe tables.

## complexity

D14. **Collapse optional layers.** ALWAYS 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 are ALWAYS labelled machine data. NEVER place them in primary navigation and NEVER let a reader arrive at one by accident.

## interaction

D16. **Interaction must clarify.** Search, filters, maps, AI interaction and expandable ontologies stay ONLY IF they reduce uncertainty or reveal a relationship. IF not THEN remove them.

D17. **Relationship before click.** ALWAYS show why a link exists and what family it belongs to before asking for the click.

## quality

D18. **Rendering repairs or refuses.** ALWAYS reject or repair a malformed table, a link wall, a contrast failure or a broken source structure before it reaches a reader.

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

D31. **Widget ink derives from the widget surface.** A widget stylesheet NEVER contains a prefers-color-scheme block, for any property. IF a widget needs a dark presentation THEN its surface and its ink change together in the same rule, keyed to the widget.

D32. **Contrast floors are computed.** Payload text ALWAYS clears 7:1 against its resolved surface. Secondary text ALWAYS clears 4.5:1. The surface is ALWAYS the nearest ancestor declaring a background, defaulting to the card. IF the ink is already at the light end THEN darken the surface, NEVER lighten the ink.

D33. **One token, one fallback.** Every reference to a token ALWAYS carries the same fallback, and that fallback ALWAYS clears the contrast floor on every surface the token is used on.

D34. **The quote is the payload.** A source's own words are NEVER styled lighter, smaller or lower-contrast than the label, masthead, hostname or timestamp around them.

D35. **Widget ink is a literal.** A widget's ink is ALWAYS a literal colour or a token the widget's own stylesheet declares. NEVER a token set elsewhere. Design tokens govern the page around the card, NEVER the card.

## source

D20. **The inside is beautiful.** ALWAYS organise source as law, primitive, composition, surface, proof. ALWAYS use shared names and one-directional dependencies. NEVER scatter local design inventions.

## knowledge

D23. **Page, skill and directory row are one.** A page, its skill and its directory row ALWAYS share one identity, version and provenance. Each ALWAYS speaks in the language of its own audience.

D24. **Widgets are content.** A widget is ALWAYS the page's meaning made visible. NEVER decoration.

D25. **Sources wear their platform.** An embedded source ALWAYS renders in its own platform identity. An organisation speaking in its own name ALWAYS gets a letterhead and NEVER another masthead. Card interiors are the ONLY exemption from profile tokens. A card ALWAYS carries its ledger hash and ALWAYS appears on /design.

D26. **Article and skill are one.** An article and its skill ALWAYS share one identity, meaning, version and provenance, in 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 ALWAYS express one identity. Shared identity NEVER requires shared wording.

D28. **Failures become knowledge.** IF a model failure repeats THEN produce the article amendment, skill instruction, conformance test, code repair, directory clarification and regression proof.

## editorial

D29. **One image, one literal idea.** An editorial image ALWAYS shows the story's literal subject in one instantly readable scene. NEVER analogy, rendered text, tables, dashboards, terminals, UI collage, generic robot or circuit art, keyword scenes, or stock people. The prompt is ALWAYS a plain description of the subject. NEVER set a standing palette, medium, era, lighting, material, mood or draughtsmanship across articles.

D30. **Preflight, inspect, keep auditing.** ALWAYS record the article subject, hero subject, visible action and why the image belongs to the story, then pass the editorial preflight. NEVER generate a batch before one brief and one render pass. ALWAYS open the rendered asset and record what is visibly present before publishing. A prompt is NEVER visual 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)