groundwork-method 0.0.1 → 0.11.0

package/src/docs/principles/delivery/platform.md

@@ -0,0 +1,101 @@
+---
+title: Platform
+description: Internal developer platforms, self-service tooling, and the treatment of the dev CLI as a product in its own right.
+status: active
+last_reviewed: 2026-06-19
+---
+# Platform
+
+## TL;DR
+
+The platform is the substrate every application team builds on: the local stack, the CI/CD pipeline, the observability collector, the secrets manager, the IDP that fronts all of it. We treat the platform as a product — it has users (us), a backlog, a quality bar, and explicit investment. A good platform makes the right thing the easy thing. But product thinking cuts both ways: a platform with no market is overhead, and self-service that exposes every knob just relocates the pain. Pave the common path, leave the escape hatch open, and measure what developers actually feel.
+
+## Why this matters
+
+Every team in a multi-service organisation eventually arrives at the same realisation: the biggest drag on productivity is not the code the team writes, but the accumulated friction of the common plumbing every project has to assemble. A platform that handles the plumbing well turns that friction into a paved road. A platform that does not becomes a tax every project pays repeatedly. The quality of the platform is a direct multiplier on the output of every engineer on top of it — which also means a *premature* or *over-built* platform multiplies overhead just as efficiently.
+
+## Our principles
+
+### 1. Platform is a product — and you can build it too early
+
+The people who build the platform have explicit users — the application engineers — and treat their work as a product: backlog, priorities, measurement, feedback. A platform maintained "when we have time" decays; a platform treated as product investment compounds.
+
+The contested zone is *when*. The most expensive platform mistake is not under-investment — it is investing before the pain is real. A platform team stood up for two services is a cost centre with no one to amortise it against. Product thinking demands a market: if the "market" of internal teams is two engineers, you do not have a platform, you have speculative generality. The rule of three applies here as it does to abstractions — pave a path once the same plumbing pain recurs across multiple teams, not in anticipation of it.
+
+Start with the **thinnest viable platform** (Skelton & Pais): the smallest set of tools, docs, and defaults that *measurably* accelerates the teams on top of it, and nothing more. Grow it from demonstrated friction, not from a roadmap of features no one has asked for.
+
+### 2. Self-service — encapsulate the decision, do not expose the knobs
+
+Every common task — spinning up a new service, requesting a secret, adding a dashboard, changing a feature flag — should be self-service. When an application team has to file a ticket and wait, the platform is the bottleneck. That much is settled.
+
+The subtlety is *what* you serve. Self-service that exposes every underlying knob does not remove cognitive load — it relocates it from a ticket queue onto the developer, who now must understand Kubernetes, Terraform, and IAM to ship a service. That is the platform labyrinth. The opposite failure is the golden cage: full orchestration that handles everything until the one case it does not, with no way out.
+
+The decision rule: self-service should **encapsulate the decision** — sane defaults, the 90% path one command away — *and* **provide an escape hatch** to the underlying tool for the cases the abstraction does not fit. Self-serve the common path; offer expert assist, not a ticket, for the rare and complex. The acid test is whether shipping the normal case requires understanding the substrate. It should not.
+
+### 3. Golden paths over policy — paved road, not paved cage
+
+We pave specific paths — how to create a service, how to deploy, how to observe — and we make those paths the easiest route. Policy documents without paved paths produce compliance in shape but drift in substance.
+
+A golden path is optional with a visible cost, never mandatory. A path that is *enforced* is just policy with better tooling, and it rots the moment a legitimate case does not fit it. Pave the common route, make it the obvious default, and leave the off-ramp open — teams that take it carry the maintenance cost themselves (see principle 5). Optimise the path for the 80%; give the 20% a documented way to extend or override a part of it without abandoning the whole.
+
+### 4. The dev CLI is the platform's front door
+
+For local workflows, the dev CLI is the abstraction over every underlying tool: Docker, language runtimes, database clients, migration tools. The platform team maintains it; application teams use it without needing to know what is under it. The CLI must *wrap*, not *hide* — `dev db ...` for the 90%, with raw `psql` still available when the abstraction is in the way. See [DevEx](devex.md).
+
+### 5. One paved-road CI pipeline
+
+One pipeline definition for every service of the same type. Teams that deviate earn the cost of maintaining their own pipeline. This is how we prevent snowflake CI configurations from accumulating.
+
+### 6. Observability is part of the platform
+
+Traces, metrics, and logs flow through the same collector, into the same backend, onto the same dashboards. Observability set up by each team independently ([Observability](../quality/observability.md)) is observability broken in five different ways.
+
+### 7. The platform gets the same scrutiny as the product
+
+Platform code is reviewed, tested, versioned, and deployed the same way product code is. A broken platform release can hurt every team at once, so the bar is actually higher. "It is just tooling, ship it" is how a platform becomes an obstacle.
+
+### 8. Measure what the users feel — and know what your metrics cannot tell you
+
+Platform success is measured by the application teams' outcomes, not by the platform team's own output metrics, which can look excellent while the users are miserable. But the standard yardsticks have known blind spots, and using them naively is its own failure.
+
+DORA's four keys measure **software-delivery performance**, not productivity and not platform value — Nicole Forsgren, who created them, says this directly. So pair delivery metrics with developer-experience signal: periodic perception surveys (the SPACE framework, or DX Core 4, which folds DORA, SPACE, and DevEx into counterbalanced dimensions), time-to-first-meaningful-PR for onboarding, and tickets filed against the platform as a friction proxy.
+
+Two traps to name explicitly. **Vanity adoption** — logins, registered services, command invocations — inflates the moment adoption is mandated and tells you nothing about value. **Gamed output** — diffs or PRs per engineer — rewards quantity over outcome. The honest signal is counterfactual: would teams choose this platform if it were optional? Build for that answer.
+
+### 9. Name the substrate; buy the platform when it pays
+
+Infrastructure-as-code is a deliberate choice, not a default:
+
+- **Terraform** — largest market share, deepest HCP/Terraform Cloud integration, AI-assisted tooling; ships under the BSL 1.1 source-available licence (not OSI-approved).
+- **OpenTofu** — MPL 2.0, OSI-approved, CNCF-hosted, and now *genuinely diverging*: native state encryption and provider-defined functions that Terraform lacks. It is no longer a silent drop-in — encrypted OpenTofu state is unreadable by Terraform, so adopting those features is a committed choice. Roughly a tenth of IaC practitioners as of 2026, and climbing.
+- **Pulumi** — real general-purpose languages instead of HCL.
+
+Pick on licence-risk tolerance and lock-in, not vibes.
+
+The platform itself is build-vs-buy, and a self-hosted developer portal is the sharpest case. "Free and open source" Backstage is not free: a production install means several dedicated engineers and ongoing operational cost to keep it alive and adopted. The crossover where building can pay off sits well into the low hundreds of engineers *and* requires genuinely unique needs the market does not serve. Below that, a managed portal (Port, Cortex, hosted Backstage, Spotify Portal) usually wins; buying trades customisation for lock-in to someone else's data model, which is a real cost when you outgrow it. Treat the decision as product strategy with an honest total cost of ownership, not a reflex.
+
+## How we apply this
+
+- [DevEx](devex.md) — the developer-facing experience the platform enables.
+- [Observability](../quality/observability.md) — the centralised telemetry substrate.
+- [Progressive Delivery](progressive-delivery.md) — the CI/CD pipeline as a platform service.
+
+## Anti-patterns we reject
+
+- **The premature platform.** A platform team and bespoke tooling stood up before there are enough teams to amortise them. Overhead wearing the costume of leverage.
+- **Platform-as-gatekeeper.** A platform that says "no" more than it says "self-serve" is a bottleneck, not a platform.
+- **The golden cage.** Full orchestration with no escape hatch — fluent until the first case it does not handle, then a wall the team cannot get past.
+- **The platform labyrinth.** "Self-service" that exposes every underlying knob, so shipping the normal case still requires understanding the whole substrate. Load moved, not removed.
+- **Five ways to do one thing.** Pipelines and tools nobody consolidated. The platform should converge them.
+- **Tooling that only the platform team can use.** If the API requires insider knowledge, the tool is incomplete.
+- **"Platform investment later."** The platform is either invested in or decaying; there is no steady state.
+- **Vanity metrics.** Measuring "tickets closed" or login counts without measuring application-team outcomes and developer experience misses the point — and mandated adoption makes the numbers lie.
+
+## Further reading
+
+- *Team Topologies*, Skelton & Pais — the canonical framing of platform teams, enabling teams, and the thinnest viable platform.
+- *Platform Engineering on Kubernetes*, Mauricio Salatino — the practical engineering view.
+- *The DevOps Handbook*, Kim et al. — the broader cultural context the platform sits inside.
+- *CNCF Platforms White Paper* (CNCF App Delivery TAG) — vendor-neutral definitions of platforms, capabilities, and maturity.
+- *DX Core 4* (Noda, Forsgren, Storey et al., getdx.com) — a multi-dimensional model for measuring developer productivity without the single-metric traps.
+- *Backstage documentation* ([backstage.io](https://backstage.io)) — the archetype of an internal developer portal.

package/src/docs/principles/delivery/progressive-delivery.md

@@ -0,0 +1,92 @@
+---
+title: Progressive Delivery
+description: Feature flags, canaries, trunk-based development, and deployment strategies that let us move fast without breaking things.
+status: active
+last_reviewed: 2026-06-19
+---
+# Progressive Delivery
+
+## TL;DR
+
+Progressive delivery is how we decouple the act of deploying code from the act of releasing a feature. We ship to production multiple times a day from a single branch, but users see changes only when we open a flag, route a canary, or promote a cohort. The production environment is stable; the user experience is controlled independently.
+
+## Why this matters
+
+The reason most teams avoid shipping often is that shipping carries risk — a bad deploy can break production for every user at once. Progressive delivery breaks the link. A deploy puts the code into production. A release makes the code reach users. With the two decoupled, deploys become small, frequent, and boring; releases become observable, controllable, and reversible. That asymmetry is how modern teams sustain a fast release cadence without a proportional rate of incidents — the throughput-without-instability result that DORA has reproduced year over year.
+
+## Our principles
+
+### 1. Trunk-based development with short-lived branches
+
+Every change lands on `main` as soon as it is ready. Branches measured in days, not weeks. Long-lived branches are how integration bugs accumulate quietly; trunk-based development surfaces them constantly, which makes them cheap to fix.
+
+Trunk-based is a claim about integration frequency, not about the absence of branches. Committing directly to trunk and merging a one-day PR branch are both trunk-based; the line is integration within a day. The thing it rules out is the multi-week feature branch that diverges from `main` until the merge is its own project. If a change is too big to integrate in a day, it ships dark behind a flag (principle 3) — the branch stays short even when the feature is long.
+
+### 2. Always deployable; deploy on every merge
+
+`main` is always deployable, and we deploy from it continuously. A merged PR reaches production within the deploy window — not hours or days later. This is enforced by automation.
+
+The non-negotiable is *continuous delivery*: `main` is always in a releasable state and the path to production is fully automated. *Continuous deployment* — an automatic production push on every merge — is the default we reach for, but it is not universal. The bottleneck worth killing is the human "release engineer" who manually assembles, blesses, and ships builds; that role is a cap on cadence and a single point of failure. A deliberate, push-button promotion gate is a different thing and is legitimate — for blast-radius control, regulatory sign-off, or business timing — provided the pipeline up to that gate is fully automated and the gate is a click, not a project. DORA's throughput result tracks small batches and end-to-end automation, not literally auto-deploying every commit.
+
+### 3. Feature flags separate deploy from release
+
+A new feature is deployed behind a flag, defaulted off. The flag state decides who sees the feature — nobody, internal users, a cohort, everyone. A bad feature is disabled without a redeploy; a controversial feature is rolled to 1% before 100%.
+
+Flags are a first-class capability, not an afterthought — but "build vs buy" is a real choice, and the honest split is between the two halves of a flag system. Flag *evaluation* must be a local, in-process primitive: it evaluates against locally cached rules, returns in microseconds, adds no network hop to the request path, and fails safe to an explicit known-good default when the control plane is unreachable. That part we own and never put behind a synchronous network call. The flag *management plane* — targeting UI, audit log, rule distribution — is fair game for a vendor (LaunchDarkly, Unleash, Flagsmith) or an in-house service; it is not on the hot path and its outage must not take down evaluation. OpenFeature (principle 9) is what lets both be true: a standard evaluation API in the code, a swappable provider behind it.
+
+### 4. Canary before promote
+
+Every release that could affect latency, reliability, or user experience goes through a canary — a small fraction of traffic for a bounded window — before promoting. Canary signals (error rate, p99 latency, user journey success) are automated comparisons, not eyeballs on a dashboard.
+
+Canary is not the universal rollout primitive, and treating it as one is a mistake. A canary needs enough traffic to produce a statistically meaningful comparison inside its window; a low-traffic service, a long-session or stateful workload, or a change whose blast radius is a single tenant cannot canary honestly — you promote on noise. Pick the mechanism by what you can actually observe and reverse:
+
+- **High-volume stateless service, gradual blast radius** → canary with automated analysis against SLOs.
+- **Low traffic, or you need instant whole-population rollback** → blue-green; cut over and cut back in one move.
+- **Per-user or per-cohort exposure, kill-switch granularity, experimentation** → feature flag.
+
+These compose rather than compete: deploy the binary via canary or blue-green, then gate the user-visible feature behind a flag. The deployment strategy controls which code runs; the flag controls who sees it.
+
+### 5. Release is reversible, cheaply
+
+Every release has a rollback path that can be executed in a few minutes by any on-call engineer. Flags can be flipped; canaries can be re-routed; blue-green can be cut back. "We can't roll that back" is a red flag on the release itself.
+
+The hard case is schema. A migration that drops or renames in place is a one-way door — the old code can no longer read the database the instant it lands, so the deploy and the rollback are coupled and neither is safe. We use expand/contract (parallel change): first expand — add the new column or table and write to both shapes while reading the old; deploy and bake; then migrate readers; only after the new shape is proven do we contract and remove the old. Each step is independently deployable and independently reversible, so a rollback is never blocked on a schema state that no running version understands.
+
+### 6. Flag hygiene is continuous
+
+Flags are an asset and a debt. A long-lived flag that nobody remembers the purpose of is a drag on every future change, and a stale flag with live targeting rules is a latent incident — dead code paths that can still be switched on. Every flag has an owner, a purpose, and an expiry date; release flags are removed in the normal course of work once fully rolled out. Distinguish the lifetimes: a *release* flag is born to die at 100%, while an *operational* kill-switch or a long-running *experiment/permission* flag is meant to persist — give it a different label and review cadence rather than letting it masquerade as temporary forever.
+
+### 7. Observability defines "healthy"
+
+A release is healthy when the relevant user-journey SLOs are within tolerance ([Reliability](../quality/reliability.md)). Not when CPU is low, not when memory is steady — when users' journeys are succeeding at the rate they did before. The canary is evaluated against SLO burn rates, with a window long enough to clear startup and warm-cache noise before the verdict.
+
+### 8. The release story is the same for every service
+
+One rollout model, one flag system, one canary pattern. Different services with different release mechanics multiply cognitive load and reduce the effectiveness of the on-call engineer. Consistency is a force multiplier — the rollout and rollback steps should be muscle memory regardless of which service paged.
+
+### 9. Standard flags, GitOps-driven rollout
+
+Feature flags use the vendor-neutral **OpenFeature** standard (a CNCF incubating project) so the management plane stays swappable behind a stable evaluation API. The progressive-delivery engine follows the GitOps tool and owns traffic weighting and automated canary analysis: **Argo Rollouts** in an ArgoCD shop, **Flagger** in a Flux shop. Both are CNCF projects and production-viable; the lean is Argo Rollouts when you want explicit, step-based control with approval gates between stages, and Flagger when you want hands-off, metric-driven promotion with minimal manifest change. Either way the rollout machinery is declarative and lives in the repository, not in a console someone clicks.
+
+## How we apply this
+
+- [DevEx](devex.md) — the inner loop that feeds into continuous delivery.
+- [Reliability](../quality/reliability.md) — the SLO surface that gates canary promotion.
+- [Observability](../quality/observability.md) — the signal layer for release health.
+
+## Anti-patterns we reject
+
+- **Release trains.** Batching up a month of changes and shipping them on Friday is how you get a huge, unreviewable deploy that breaks in ways nobody can localise.
+- **Flags without expiry.** A flag that has been "temporary" for a year is permanent — and a permanent decision hidden inside a runtime config.
+- **Canary-by-eyeball.** Promoting because the graph "looks fine" is a coin flip. Automate the comparison — and on a low-traffic service, don't pretend a canary means anything; use blue-green or a flag cohort instead.
+- **"We will test it in staging."** Staging has no users. A canary in production is the only test of production behaviour.
+- **Flag evaluation on the network hot path.** A flag check that makes a synchronous call to a vendor — and blocks or errors the request when that vendor blips — has turned a release tool into an availability dependency. Evaluate locally, fail safe to a default.
+- **Commit-and-hope.** No canary, no flag, deploy to 100%. You will find out in the morning.
+
+## Further reading
+
+- *Accelerate*, Forsgren, Humble, Kim — the data on trunk-based development and its outcomes.
+- *Continuous Delivery*, Humble & Farley — the canonical treatment of the release pipeline.
+- James Governor, *Progressive Delivery* (RedMonk, 2018) — the essay that named the practice.
+- *Release It!*, Second Edition, Michael Nygard — the stability-pattern view of rollout.
+- *DORA / State of DevOps* reports — the ongoing evidence base for delivery throughput and stability moving together.

package/src/docs/principles/design/ai-native-design.md

@@ -0,0 +1,73 @@
+---
+title: AI-Native Design
+description: Designing the outcome envelope of probabilistic and generative interfaces — latency, uncertainty, graceful failure, calibrated autonomy, and the human on the dial.
+status: active
+last_reviewed: 2026-06-20
+---
+# AI-Native Design
+
+## TL;DR
+
+A probabilistic feature is a distribution of outputs, not a single answer, and the interface has to be designed for that whole distribution — the wrong answer first, the uncertain answer honestly, the slow answer as a designed wait. Latency is a first-class design material. Confidence is communicated without false precision. Failure is the expected path, designed before the happy one. The human stays on the dial: action is previewed, scoped to reversibility and severity, and reversible. Chat is one tool among many, not the universal interface.
+
+## Why this matters
+
+The core failure of AI features is a probabilistic engine wrapped in a deterministic interface that presents a guess as truth. Models are systematically overconfident, hallucinate at non-trivial rates, and return different output for the same input — so an interface that renders a single confident answer, hides its uncertainty, and offers no cheap correction sets the user up to over-trust and then lose trust entirely on the first error. Designing for AI is the discipline of making the probabilistic nature legible and controllable: showing the range, the confidence, the sources, and the off switch, so the user can collaborate with an uncertain system instead of being surprised by it.
+
+## Our principles
+
+### 1. Design the outcome envelope, not one happy path
+
+A probabilistic feature is designed for the distribution of what it might produce, not a single mocked result, because the designer no longer controls the exact rendered output. We vary the treatment by likelihood of intent — more persuasion and framing where confidence is low, less friction where it is high — prefer ranges and windows over false-precise points, and plan explicit fallback states for degrading confidence. Because ideation is cheap with these systems, requesting and presenting multiple candidates is often the right default.
+
+### 2. Latency is a first-class design material
+
+We optimise time-to-first-token and stream output immediately, because streaming removes the wait-for-completion delay even though it does not speed the model, and perceived speed is the metric that matters. Anything beyond ~1s shows structured progress, users can act on partial output rather than waiting for the whole, and streaming content is parsed incrementally to avoid re-rendering the entire response on every chunk. An unindicated wait past roughly ten seconds collapses satisfaction.
+
+### 3. Communicate confidence without false precision
+
+We prefer calibrated categorical confidence (high / medium / low) and first-person hedging at the point of the claim, reserving numeric scores for high-stakes domains with genuinely comparable predictions, because a single definitive score drives over-reliance and then trust collapse while a spurious percentage implies precision the model does not have. We do not amplify the model's default overconfidence; where the system is uncertain, the interface says so plainly.
+
+### 4. Ground claims in sources, and surface the gaps
+
+Where a feature makes factual claims, citations are assembled during generation from the retrieval context, not grafted on afterwards, and they cite at the passage level rather than the document, because in-context citation is more reliable and document-level pointers do not let the user verify the claim. Sources are layered — preview, click-through, full list — and a missing or broken source is surfaced explicitly, because a citation creates a halo that lowers user vigilance, so a gap must be shown rather than hidden.
+
+### 5. Design the wrong answer first
+
+We treat incorrect output as the norm and design that flow before the happy path: unpredictable output is sandboxed to a designated region so it cannot break the deterministic parts of the UI, doubt is marked in context at the claim rather than buried in a global "AI can make mistakes" disclaimer that habituates into ignored noise, and correction is made cheap with the feedback routed back to improve the system. Unverified output is never fed straight into an irreversible downstream action.
+
+### 6. Keep the human on the dial: gate by reversibility and severity
+
+Autonomy is a slider the user controls, not a default of maximal automation. We gate on reversibility crossed with severity — irreversible, high-severity actions (send, charge, delete, deploy) require pre-approval; reversible, high-severity actions get human oversight with a rollback window; reversible, low-severity actions run autonomously — and the agent's reasoning is visible at the gate, because an action the user cannot preview feels like a surprise they did not consent to. Gating everything is its own failure: alert fatigue turns approval into rubber-stamping.
+
+### 7. Make regeneration and steering first-class, non-destructive
+
+We offer both a one-click retry and guided regeneration that nudges style or parameters before re-running, and we choose deliberately between overwriting (convergent chat) and branching (explicit comparison), because plain regeneration trades precision for variation while guided and branching flows recover control. Prior outputs are never silently destroyed, and where reproducibility matters the determinism lever (the seed) is exposed.
+
+### 8. Chat is one tool, not the universal interface
+
+Chat became the default because it was the easiest thing to ship, not because it is the right interface for most tasks: a bare text box has no affordances, hides the system's capabilities, and forces constant mode-switching between instructing and evaluating. Most AI features are better as embedded, affordance-rich tools — highlight-to-rephrase, context-menu actions, ambient background agents — with conversation reserved for genuinely open-ended dialogue and paired with a persistent, directly manipulable surface (a canvas) where the user edits in place rather than through the chat turn. We design for control and legibility — copilots, not captains — over "magic" full autonomy.
+
+## How we apply this
+
+- [AI-Native Product](../ai-native/ai-native-product.md) — the product framing: evals, the outcome envelope, and the cost layers this design sits within.
+- [Interaction & Motion](interaction-and-motion.md) — streaming, partial-result, and perceived-performance patterns for probabilistic output.
+- [Design Systems & Tokens](design-systems-and-tokens.md) — grounding generative UI in the system so the model builds on-system components.
+- [Usability & UX](usability-and-ux.md) — recognition over recall and progressive disclosure applied to AI affordances.
+
+## Anti-patterns we reject
+
+- **A guess presented as truth.** A single confident answer with no confidence signal, no sources, and no cheap correction.
+- **The blocking wait.** Holding the whole response until generation completes instead of streaming and showing progress.
+- **False precision.** Spurious percentage confidence implying accuracy the model does not have, amplifying its default overconfidence.
+- **Retrofitted citations.** Document-level references grafted on after generation, which the user cannot use to verify a claim.
+- **The global disclaimer.** One "AI can make mistakes" line standing in for in-context doubt and cheap correction.
+- **Approve-everything autonomy.** Either gating every action into rubber-stamping, or auto-running irreversible actions with no preview.
+- **Chat as the answer to everything.** Defaulting to a chat widget where an embedded, affordance-rich tool would serve the task better.
+
+## Further reading
+
+- Nielsen Norman Group, *AI Hallucinations* and the AI-UX article corpus.
+- Google PAIR, *People + AI Guidebook* — errors, failing gracefully, and explainability.
+- *Shape of AI* (shapeof.ai) — the emerging pattern language: citations, confidence, regeneration.
+- Maggie Appleton and Amelia Wattenberger — beyond the chatbox: ambient, embedded, and malleable AI interfaces.

package/src/docs/principles/design/design-foundations.md

@@ -0,0 +1,80 @@
+---
+title: Design Foundations
+description: Design as the discipline that owns usability and craft — intent translated into precise specification, implemented not decorated, held to the bar set by the best products of the day.
+status: active
+last_reviewed: 2026-06-20
+---
+# Design Foundations
+
+## TL;DR
+
+Design is the discipline that decides how a product looks, feels, and behaves for the person using it — and then proves the result, in running software, against the bar set by the best products of the day. We own the **usability** risk: whether a real user can understand and operate what we ship. Taste is an input; a precise, implemented specification is the output. A design that lives only in a comp, or renders but reads as generic, has not done its job.
+
+## Why this matters
+
+The dominant failure mode of engineering-led products is not ugliness — it is *plausibility*. The build renders, the tests pass on the business logic, and the result looks like every other framework-default app: an indigo gradient, Inter at one weight, a flat grey border, a single 0.3s ease-in-out. It satisfies the spec and reaches none of the craft. Meanwhile the design system that was carefully authored evaporates between the design phase and the screen, because no one looked at the running product and held it to the intention.
+
+Design closes that gap. It is the discipline that translates a felt intention ("calm, dense, fast") into values a machine can implement without guessing, and then judges the rendered result against both the stated intention and the market leaders the work drew inspiration from. The two halves are inseparable: precision without taste produces a tidy but lifeless interface; taste without precision produces a beautiful mock no one can build twice.
+
+## Our principles
+
+### 1. Design owns usability; it is the third risk
+
+Every bet must clear four risks: value and viability (product owns), feasibility (architecture and engineering own), and **usability** — whether the target user can actually understand and operate the thing. Usability is the design risk. It is killed the same way the others are: named early, tested against evidence, and proven before delivery rather than discovered after launch. A flow that works for the person who built it is not validated; it is unexamined.
+
+### 2. Taste is the input; specification is the output
+
+The user speaks in taste, instinct, and analogy — "warm and editorial," "fast like Linear," "it should feel trustworthy." That is the correct level of input. The designer's core contribution is the *translation*: `oklch(96% 0.008 60)` paired with a 450-weight serif at a 1.25 modular scale is a specification; "warm and editorial" is a brief. An interface description that echoes the user's words back with formatting has done no design work — the value is created entirely in the act of turning feeling into precise, implementable, defensible values.
+
+### 3. Design is implemented, not decorated
+
+A design system wired through to production — semantic tokens compiled into the styles the app actually serves — is implemented. A Figma library that engineers reproduce by eye is decorative, and it drifts the moment it ships. The test is mechanical: change one semantic token's value and watch the running product change. If it does not, the system is decoration and the design was never really delivered. We design *in the material* — the rendered, stateful, responsive software — because that is the only place the design exists for the user.
+
+### 4. Craft is everything above the spec
+
+A door that opens meets the spec; whether it swings true, latches with a satisfying weight, and aligns to the frame is craft. Software is the same. The functional requirement is the floor. Craft is the layered shadow that reads as real light instead of a fuzzy grey box, the spring that settles instead of a linear slide, the empty state that teaches instead of a blank panel, the perceptual colour ramp whose steps look evenly spaced. Craft is not decoration added at the end — it is the difference between a product that is tolerated and one that is trusted, and it is decided in the same breath as the function.
+
+### 5. Hold the work to the leaders, by name
+
+The best product teams of the day — Linear, Vercel, Stripe, Raycast, Apple, Family — set a public, observable bar. We name the references the work draws from during design, and we judge the delivered result against them: not to copy a signature, but to match the *level* of restraint, density, motion discipline, and typographic rigour. "Is this as considered as the thing we said we admired?" is a question with a defensible answer, and asking it is how a team escapes its own gravity.
+
+### 6. Distinguish durable craft from fashion
+
+Durable craft is invisible correctness — it matches physics (light, motion), human perception (colour, type), or epistemic reality (uncertainty). Perceptual colour, motion with purpose, spatial depth, typographic rigour: all are codified in specifications and platform guidelines and will not date. Fashion is a visible signature — neumorphism, whole-UI glassmorphism, the purple-gradient-and-three-cards "AI slop" look that models regress to from vague prompts. We invest in the correctness and let the signature emerge from it; we do not chase the look.
+
+### 7. The interface medium is decided, never assumed
+
+A screen, a terminal, an API, a voice surface, and an agent protocol are different design problems with different materials. Before any visual or interaction decision, the medium is explicit, because the whole vocabulary — what a "component" is, what "feedback" means, what can be perceived — hangs off it. A design conversation that produces an experience description without naming its medium has left the most consequential decision implicit.
+
+## The design discipline
+
+This page is the spine of a wider design corpus — the discipline of designing usable, crafted software, expanded into its working parts:
+
+- [Visual Design](visual-design.md) — perceptual colour, typographic rigour, spatial depth, and visual hierarchy: the craft of how a surface looks.
+- [Layout & Space](layout-and-space.md) — spatial systems, modern intrinsic layout, container-driven responsiveness, and density as an axis.
+- [Interaction & Motion](interaction-and-motion.md) — affordance and feedback, the full set of interface states, and motion that serves function.
+- [Usability & UX](usability-and-ux.md) — heuristics and UX laws applied at decision time, cognitive load, forms, and error recovery.
+- [Design Systems & Tokens](design-systems-and-tokens.md) — the token contract, components as contracts, and the system as the durable interface between design and engineering.
+- [AI-Native Design](ai-native-design.md) — designing the outcome envelope of probabilistic and generative interfaces.
+
+## How we apply this
+
+- [Accessibility](../quality/accessibility.md) — usability that excludes assistive-technology users is not usability; WCAG 2.2 AA is the floor design works within.
+- [Product Engineering](../foundations/product-engineering.md) — design owns the usability risk in the same four-risk frame product engineering sets up.
+- [Surface Architecture](../system-design/surface-architecture.md) — the design system is a contract across surfaces; the seam between core and surface is where design and architecture meet.
+
+## Anti-patterns we reject
+
+- **The echo spec.** An interface description that restates the user's adjectives with headings and never reaches a concrete value. The translation is the work; skipping it produces nothing.
+- **Decorative design system.** Tokens that live in a design tool and are reproduced by hand in code. They diverge on the first commit and the "system" becomes a museum piece.
+- **Happy-path-only design.** Designing the populated ideal and leaving empty, loading, partial, error, and success states to fall out of the implementation. Users live in those states; that is where the product is won or lost.
+- **Generic-by-default.** Shipping the framework defaults — one gradient, one font weight, one easing curve, one flat shadow — and calling it designed. Plausible is not the bar.
+- **Mimicry over craft.** Copying a leader's signature look instead of matching its underlying rigour. The signature dates; the rigour does not.
+- **Design as a final coat.** Treating design as a styling pass after the logic is built. By then the structure has foreclosed the good options.
+
+## Further reading
+
+- *The Design of Everyday Things*, Don Norman — affordances, signifiers, feedback, and mapping: the grammar of interaction.
+- *Refactoring UI*, Adam Wathan & Steve Schoger — the practical craft bridge between design intent and implemented interface.
+- Karri Saarinen, *Building Linear* and the craft essays — restraint, opinion, and quality as a top-down editorial act.
+- Jim Nielsen, *The Case for Design Engineers* — why design delivered as code, not handoff, is how craft survives.

package/src/docs/principles/design/design-systems-and-tokens.md

@@ -0,0 +1,72 @@
+---
+title: Design Systems & Tokens
+description: The token contract, components as contracts, and the design system as the durable, machine-readable interface between design and engineering.
+status: active
+last_reviewed: 2026-06-20
+---
+# Design Systems & Tokens
+
+## TL;DR
+
+A design system is the durable contract between design and engineering: semantic tokens as its wire format, components as its typed interfaces, usage rules as its documentation. Tokens are tiered — primitives feed semantics feed the occasional component override — and components bind only to the semantic layer. The system is the source of truth in code, wired to production so a single token change moves the running product, and it is run as a product, measured by adoption rather than by how many components were contributed.
+
+## Why this matters
+
+The design system is the mechanism by which design survives contact with the codebase. Without it, every screen re-decides colour, spacing, and component behaviour, and the carefully authored design drifts into a thousand local variations. With a *decorative* system — a design-tool library reproduced by hand in code — the drift is just slower. The systems that hold are the ones built as a contract: tokens as version-controlled data, components as published APIs, both wired to production and enforced in CI. That contract is now also what lets AI tooling generate on-system UI instead of inventing ad-hoc interfaces, which makes its machine-legibility a first-class concern.
+
+## Our principles
+
+### 1. Tokens are tiered, and primitives are never consumed directly
+
+A token system has three tiers. **Primitives** (options) are context-free raw values — full colour ramps, the spacing and radius scales, durations — carrying no usage intent. **Semantic** tokens (decisions) alias primitives by role — `color.background.default`, `color.text.primary`, `border.hairline` — and this is the layer components bind to and the layer themes remap. **Component** tokens are scoped overrides that reference the semantic tier, an escape hatch promoted only on genuine repeated need, not the norm. Components never read a primitive directly, because a component wired to `blue.500` makes theming a rewrite; indirection is capped at roughly two hops so the system stays traceable.
+
+### 2. Name by intent, not by value
+
+A token is named for what it means, never for what it currently is — `border.hairline`, not `neutral-80`; `color.feedback.error`, not `red-600` — because a value-named token used semantically lies the moment the value changes, and because intent names are what make the system legible to a human and usable by an AI agent reading it. Theme and mode are orthogonal axes, each an explicit modifier, never positions baked into one name.
+
+### 3. Theme at the semantic tier; model axes as orthogonal overrides
+
+Theming is a mapping swap at the semantic layer — the token name stays stable, the primitive it points to changes per mode — so components and primitives stay theme-agnostic and a dark theme is a remap, not a parallel set of components. Every theming dimension (light/dark, contrast, brand, density) is modelled as an independent override set resolved by order, because orthogonal axes *add* while names that encode a dimension *multiply* — and only the additive model survives a fifth axis. We never precompute the full permutation matrix, and high-contrast or colourblind themes are authored as thin diffs over the base, not full duplicate sets.
+
+### 4. Components are contracts
+
+A component's public surface — props, slots, states, accessibility semantics — is a contract designed like a typed signature and versioned like one: additions are minor, renames and removals are major with a deprecation window and a codemod. Variant, state, size, and slot are four orthogonal axes; each enumerable axis is a single enum rather than a pile of booleans, because an enum makes illegal states unrepresentable where boolean soup multiplies the test matrix and permits nonsense combinations. The same concept carries the same prop name across every component, because that consistency is what makes the system learnable.
+
+### 5. Compose over configure; separate behaviour from style
+
+We prefer composition to configuration — compound components that share state and let the consumer own structure — because configuration scales linearly into a swamp of props while composition expresses infinite arrangements from a small, stable API. Behaviour, accessibility, focus, and keyboard handling live in a headless core that conforms to the ARIA Authoring Practices Guide; visual decisions live in semantic tokens; product-specific assemblies live as recipes in the product, not the system. This separation is what lets a component be re-themed without touching product code and re-styled without reimplementing behaviour.
+
+### 6. The system is truth in code, wired to production
+
+Tokens are the source of truth as version-controlled data — diffable, reviewable, semver'd — compiled by a build step into the styles the application actually serves; the design tool consumes this, it does not originate it, and component behaviour is truth in the code closest to the user. The system is *implemented, not decorative*, and the test is mechanical: change one semantic token's value and the running product changes. If it does not, the system is a museum piece and the design was never delivered. Documentation is executable — prop tables generated from types, stories that double as test fixtures, accessibility checked in the same surface.
+
+### 7. Run it as a product: centralise the core, measure adoption
+
+A design system is run as a product with a roadmap and consumers, owned by a central core team — federated contribution is added gradually once the foundations are stable, never adopted as the starting model, because pure federation has no owner and decays. The success metric is **adoption** — the share of production UI built from the system — not the count of components contributed, because most components made across teams do not belong in the system and contribution volume measures effort, not value. The contract is enforced in CI: linting that forbids raw hex and off-scale values, deprecated-token detection, and visual regression, because a contract a machine cannot check is a contract that drifts.
+
+### 8. Make the system machine-legible
+
+The system is authored so an AI agent can build on it: semantic, intent-named tokens carrying usage descriptions and relationships, and components with discoverable, documented APIs. An agent grounded in the system reuses its components; an ungrounded agent invents ad-hoc UI, and an agent reading value-named, undescribed tokens grabs the wrong one. Machine-legibility is therefore an extension of naming-by-intent, not a separate feature — but tokens remain plumbing, and the craft and architecture above them are still where the value lives.
+
+## How we apply this
+
+- [Visual Design](visual-design.md) — the colour, type, and depth decisions that become the token values.
+- [Surface Architecture](../system-design/surface-architecture.md) — the design system as a contract spanning surfaces, and the core/surface seam.
+- [AI-Native Design](ai-native-design.md) — grounding generative UI in the system's tokens and component contracts.
+
+## Anti-patterns we reject
+
+- **Primitives in components.** `button { color: blue.500 }` — turning a theme change into a six-month refactor.
+- **Value-named semantics.** `neutral-80` used as if it meant something, lying the moment its value moves.
+- **Theming the primitive layer.** Remapping primitives instead of semantics, collapsing the indirection that makes theming possible.
+- **Dimension-in-the-name.** Encoding mode/brand/density into token names, multiplying the matrix until a fifth axis is unmanageable.
+- **The boolean trap.** `isPrimary`, `isLarge` booleans where one enum belongs, permitting illegal states and exploding the test matrix.
+- **The decorative system.** A design-tool library reproduced by eye in code, with a parallel hand-kept token set that drifts immediately.
+- **Adoption by contribution count.** Measuring how many components were added rather than how much of production is actually on the system; promoting every snowflake into the core.
+
+## Further reading
+
+- Nathan Curtis / EightShapes — *Naming Tokens*, *Tokens in Design Systems*, *The Fallacy of Federated Design Systems*.
+- Brad Frost — *Creating Themeable Design Systems* and *Components, Recipes, and Snowflakes*.
+- Martin Fowler / Adam Woznica — *Design Token-Based UI Architecture*.
+- W3C Design Tokens Community Group — the DTCG format as the vendor-neutral token contract.

package/src/docs/principles/design/interaction-and-motion.md

@@ -0,0 +1,69 @@
+---
+title: Interaction & Motion
+description: Affordance and feedback, the full set of interface states, motion that serves function, and perceived performance as a design material.
+status: active
+last_reviewed: 2026-06-20
+---
+# Interaction & Motion
+
+## TL;DR
+
+An interface communicates what it can do and what just happened. Every actionable element signals its affordance; every action gets immediate feedback. Every surface that fetches or mutates data is designed for its full set of states — empty, loading, partial, error, success, populated — not just the happy path. Motion serves a function or is cut, runs on physics, and respects the user's reduced-motion preference. Speed is designed: perceived performance is a material the designer shapes, not a number the backend hands over.
+
+## Why this matters
+
+The states a user actually lives in — the first-run empty screen, the slow load, the failed submit — are where products are won or lost, and they are exactly the states an engineering-led build leaves to fall out of the code. A blank panel on first use teaches nothing; a generic toast on failure with the form wiped loses trust irrecoverably. Motion compounds the effect either way: purposeful motion explains cause and continuity, while decorative motion on a hundred-times-a-day action becomes friction. And because users judge speed by feel, an interface that acts optimistically and streams partial results feels fast even when the network is not.
+
+## Our principles
+
+### 1. Affordance is signalled; feedback is immediate
+
+Every actionable element carries a perceptible signifier — shape, weight, underline, cursor, label — because an affordance the user cannot perceive does not exist for them, and a non-interactive element avoids signifiers that imply action. Every action produces a response within ~100ms, proportional to the action and located at its point, because users build a correct mental model only from feedback they can see. Control layout maps to effect: arrangement mirrors what it changes, and a toggle's state is unambiguous.
+
+### 2. Design every state, not the happy path
+
+Every surface that loads or changes data is designed for six states: **empty** (first-use teaches what goes here and offers one action; distinguish first-use from user-cleared from no-results), **loading** (skeleton matching the final layout for content, spinner for short waits, determinate progress past ~1s), **partial** (render what is here and stream the rest), **error** (in-context, specific, recoverable, with the user's input preserved), **success** (confirm clearly — this is the remembered "end"), and **populated** (the ideal, which must survive real data extremes — long strings, huge counts, missing fields). Designing only the populated state is the most common production failure.
+
+### 3. Motion serves a function or it is cut
+
+Every animation justifies itself against one of four jobs — feedback (confirm an action registered), continuity (move rather than teleport, preserving the user's spatial model), focus (direct the eye to what changed), or perceived performance (an ease-out entrance feels faster) — and motion that serves none is removed. High-frequency and keyboard-initiated actions get *no* animation, because an interface used hundreds of times a day feels fast precisely when it does not animate. Motion is salt: too much spoils the dish.
+
+### 4. Motion runs on physics and stays out of the way
+
+The default transition is `ease-out`, around 200ms, animating only `transform` and `opacity` — compositor-only properties that hold frame rate, where animating `width`/`margin`/`box-shadow` drops frames. `ease-in` is never used on interface elements (it starts slow and feels sluggish); `ease-in-out` is for on-screen movement, `ease-out` for entrances, `linear` only for progress. Springs — tuned by duration and a subtle bounce (≈0.1–0.3) — are preferred for anything grabbable, flingable, or interruptible, because a spring maintains velocity when interrupted while a fixed-duration tween restarts from zero. Elements enter from `scale(0.95)`, never `scale(0)`, because nothing in the real world shrinks to nothing.
+
+### 5. Choreography is restrained; transitions are declarative
+
+A sequence of related elements enters with a short stagger (≈20–50ms) that reads as one gesture with a single focal point, never as everything animating at once. We use the View Transitions API for shared-element and page transitions rather than hand-built FLIP, because it captures before/after snapshots and animates declaratively, is Baseline for same-document transitions, and degrades to a clean cut where unsupported. Each animated element carries its own `view-transition-name`, and heavy cross-fades over large subtrees are avoided.
+
+### 6. Speed is designed: perceived performance is a material
+
+We budget feedback to the perceptual thresholds — under ~100ms feels instantaneous, ~1s holds the flow of thought, ~10s is the limit of attention — and design to them: animate freely below 100ms, show an instant affordance (not a spinner) around 1s, show determinate progress past 10s. Low-risk, high-success mutations are optimistic by default — apply the effect immediately and reconcile in the background, reverting visibly on failure — because acting before the network confirms is what makes an interface feel fast. Spinners are reserved for risky or genuinely slow operations; skeletons are used only when content-shaped and longer than ~1s, and must match the final layout to avoid a flash and a shift.
+
+### 7. Reduced motion is the safe baseline
+
+We author the muted baseline and layer motion inside `prefers-reduced-motion: no-preference`, so the interface fails safe for users with vestibular conditions. Reduced motion means *reduce, not remove* — disable vestibular triggers (parallax, large translations, scale, spin, autoplay) and keep functional feedback (quick fades, focus changes, state transitions), replacing a slide with a cross-fade rather than nuking all motion. Meaning is never carried by motion alone: when motion is reduced, state must still read through colour, text, icon, and layout.
+
+## How we apply this
+
+- [Usability & UX](usability-and-ux.md) — the heuristics and UX laws that govern interaction decisions and form behaviour.
+- [Visual Design](visual-design.md) — depth and colour give motion its surfaces and its sense of physical light.
+- [Accessibility](../quality/accessibility.md) — reduced motion, focus visibility, and target size as hard constraints on interaction.
+- [AI-Native Design](ai-native-design.md) — latency, streaming, and partial-result design for probabilistic features.
+
+## Anti-patterns we reject
+
+- **Happy-path-only.** Shipping the populated state and leaving empty, loading, error, and success to chance — abandoning users exactly where they need the most help.
+- **Mystery-meat UI.** Text, links, and buttons made visually indistinguishable, so the user cannot tell what is actionable.
+- **`transition: all`.** Animating unintended (and layout-triggering) properties; the default `ease`/`ease-in` curve on interactive UI.
+- **Animation on everything.** Decorative motion on high-frequency or keyboard-driven actions, where speed beats polish.
+- **Optimism where it is unsafe.** Optimistic updates on irreversible or low-success actions like payments and deletes.
+- **Frame-display skeletons.** Skeletons that do not match the real layout, or flash on sub-300ms loads — reading as broken, causing a shift.
+- **Motion as the only signal.** State conveyed solely by movement, lost entirely when motion is reduced.
+
+## Further reading
+
+- Don Norman, *The Design of Everyday Things* — affordances, signifiers, feedback, and mapping.
+- Emil Kowalski, *Great Animations* — purposeful, interruptible, reduced-motion-aware UI motion.
+- Nielsen Norman Group, *Response Times: The 3 Important Limits* — the 0.1s / 1s / 10s perceptual thresholds.
+- *Material 3 Motion* — easing and duration tokens, and the spring-based expressive system.

package/src/docs/principles/design/layout-and-space.md

@@ -0,0 +1,72 @@
+---
+title: Layout & Space
+description: Spatial systems, modern intrinsic layout, container-driven responsiveness, fluid sizing, and density as a first-class axis.
+status: active
+last_reviewed: 2026-06-20
+---
+# Layout & Space
+
+## TL;DR
+
+Space is a designed material, governed by a consistent scale rather than ad-hoc numbers. Layout is intrinsic — sized from content and the space a component is given, not from device dimensions — which is why responsiveness now belongs to the container, not the viewport. Type and space flow fluidly between anchor points, density is an explicit axis, and the whole system is authored in logical, internationalisable properties.
+
+## Why this matters
+
+Inconsistent spacing is the most common reason an interface feels amateur even when its colour and type are fine: a 7px here and a 13px there break the rhythm the eye uses to group and separate. And the device-era model of responsiveness — viewport media queries snapping a layout between fixed breakpoints — produces components that cannot be reused, because the same card needs a different layout in a wide column and a narrow sidebar *at the same viewport width*. Modern CSS resolved both: a tokenised spatial scale gives rhythm, and container queries plus intrinsic sizing make components carry their own responsive logic.
+
+## Our principles
+
+### 1. Space comes from one tokenised scale
+
+Every margin, padding, and gap is a step on a single spacing scale, expressed in `rem` and generated from one base variable, so the whole system rescales and themes from one place and honours user font-size. We use a 4px base unit with 8px as the dominant cadence — 8 divides cleanly, stays whole at 2× and 3× density, and 4 supplies the half-steps dense UI genuinely needs — and a non-linear scale (4, 8, 12, 16, 24, 32, 48, 64, 96) so steps stay perceptually proportional instead of wasting tokens on imperceptible large-end jumps. Tokens name intent where it helps (`inset`, `stack`, `inline`), never a raw pixel value in a component.
+
+### 2. The grid is rhythm, and relatedness is spacing
+
+Spacing is how the interface communicates structure: related elements sit closer than unrelated ones, so internal spacing is always less than the spacing that separates groups. Equal spacing everywhere erases grouping and forces the user to work out relationships the layout should have shown. The grid is expressed in code as margins and padding in scale multiples, not as a snapped overlay to fight — a soft grid bends to content where a hard grid produces brittle layouts.
+
+### 3. Layout is intrinsic: Grid for structure, Flexbox for flow
+
+We let layout be intrinsic to content — sized from `minmax()`, `min()`, `fr`, `ch`, and `auto-fit`/`auto-fill` — rather than forcing content into fixed columns. Grid handles two-dimensional structure; Flexbox handles one-dimensional flow; matching the tool to the layout's dimensionality makes the alignment hacks disappear. Subgrid aligns content across sibling cards without fixed heights or JavaScript. The responsive-grid default is the RAM pattern with its overflow guard — `repeat(auto-fill, minmax(min(100%, 16rem), 1fr))` — because the bare `minmax(16rem, 1fr)` overflows its container below the floor.
+
+### 4. Responsiveness belongs to the container
+
+A reusable component does not know the viewport; it knows the space its slot gives it. We make every reusable component a container (`container-type: inline-size`) and write its internal breakpoints with `@container`, reserving `@media` for true page-level chrome like global navigation. This is what makes a component portable — the same card lays out correctly in a wide main column and a narrow sidebar with no knowledge of the page. Container queries are Baseline across evergreen browsers; a section that needed seven viewport breakpoints collapses to two container queries.
+
+### 5. Type and space scale fluidly between anchor points
+
+Rather than redefining sizes at each breakpoint, we ship generated fluid scales — type and space as `clamp()` custom properties interpolating between a small-viewport and large-viewport anchor — so the system scales smoothly and stays internally consistent from one declaration. Every fluid font-size includes a `rem` term in its preferred value, never pure `vw`, because pure-viewport text does not respond to zoom and fails WCAG resize-text. Container units (`cqi`) drive component-scaled type where the container, not the viewport, is the right reference.
+
+### 6. Density is a first-class axis
+
+The same viewport demands different compactness by user, input modality, and data load, so density is an explicit, named mode (default and compact) driven by tokenised deltas — 4px steps of element height plus tighter line-height — not by hand-shrinking components one at a time. A single switch keeps the whole UI consistent and reversible. Density is applied where it serves (dense data regions) and withheld where it harms (focused inputs and primary actions), and never compresses touch targets below the accessible minimum.
+
+### 7. Author in logical, internationalisable properties
+
+We write layout in flow-relative logical properties — `margin-inline`, `padding-block`, `inset-inline-end`, `text-align: start` — by default, because one stylesheet then internationalises to right-to-left and vertical writing modes for free, with no parallel `[dir="rtl"]` override sheet to maintain. Media reserves its space with `aspect-ratio` plus `object-fit: cover` (and intrinsic `width`/`height` on images) to prevent layout shift as content loads.
+
+### 8. Breakpoints follow content, and density is designed for both ends
+
+Where discrete breakpoints are still needed for macro column-count shifts, they are placed in `em` at the widths where *the content* breaks — a measure growing past comfort, cards becoming cramped — not at device dimensions that churn every hardware cycle. We author mobile-first but design an explicit desktop information-density target, because a single-column mobile layout naïvely stretched to a wide screen produces a low-density, high-scroll, low-trust desktop experience.
+
+## How we apply this
+
+- [Visual Design](visual-design.md) — the spatial scale carries the visual rhythm colour and type sit on.
+- [Interaction & Motion](interaction-and-motion.md) — layout transitions and the View Transitions API depend on a stable spatial model.
+- [Design Systems & Tokens](design-systems-and-tokens.md) — spacing, breakpoints, and density become tokens in the system contract.
+
+## Anti-patterns we reject
+
+- **Magic-number spacing.** `padding: 7px`, `top: 13px` — values off the scale that break the rhythm grouping depends on.
+- **Viewport media queries inside components.** `@media` in a reusable component couples it to the page and kills portability; the container is the right reference.
+- **Faking 2D with Flexbox.** Ragged pseudo-columns and magic margins where Grid (and subgrid) would align cleanly.
+- **The unguarded RAM pattern.** `minmax(16rem, 1fr)` without the `min(100%, …)` guard, overflowing its container on narrow screens.
+- **Pure-`vw` fluid type.** `font-size: 4vw` or a `clamp()` whose preferred value omits a `rem` term, breaking zoom.
+- **Physical properties.** `margin-left` and `text-align: left` that land on the wrong side in right-to-left languages.
+- **Stretched mobile layout.** A single-column phone layout shipped unchanged to desktop, low-density and untrustworthy on a wide screen.
+
+## Further reading
+
+- Jen Simmons, *Intrinsic Web Design* — sizing layout from content rather than device width.
+- Ahmad Shadeed, *A Guide to CSS Container Queries* — the shift from viewport to container responsiveness.
+- *Utopia* (utopia.fyi) — fluid type and space scales from two anchor points.
+- Nathan Curtis, *Space in Design Systems* — spacing scales and intent-named space tokens.