@domandigital/craft 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# @domandigital/craft
+
+## 0.1.0
+
+### Minor Changes
+
+- 000eb90: Initial release: OKLCh colour, contrast, motion tokens and the base stylesheet.
+
+  Colour ramps snap to anchors byte-identically, so an existing site adopts craft
+  without a visual diff. Semantic tokens are derived with measured WCAG 2.x _and_
+  APCA-W3 contrast, and `accentFork` returns the step nearest the brand accent that
+  clears both bars, emitting the measured ratios as a CSS comment.
+
+  Motion ships one vocabulary for CSS and JS (`EASE` / `EASE_TUPLE` hold identical
+  control points), replacing three ease curves that were wrong in the shared layer:
+  two byte-identical curves under different names, and an `ease-in` exit.
+
+  `craft.css` collapses reduced-motion durations rather than using `animation:
+none`, which strands forwards-filled entrances at `opacity: 0`.
+
+- 0b6d77e: Type, space, density, restraint, Tailwind adapters and STANDARD.md.
+
+  Fluid type and space scales after Utopia, always with a `rem` term so browser
+  text-size settings still apply (a bare-`vw` size fails WCAG 1.4.4 at 200% zoom).
+  Both accept pinned literals, so a live site adopts the scale without its type or
+  spacing moving.
+
+  Section rhythm ships three sizes rather than the five that shipped previously
+  with zero consumers. Density is three steps on a 4px grid, set once on a shell
+  via `[data-density]`.
+
+  `checkRestraint` is pure over strings — no filesystem, no parser, no
+  dependencies — so a guard, a CI check and an editor all run it on the same input
+  and agree. It catches accumulation, which a differentiation guard structurally
+  cannot see: a guard passes anything that differs from its siblings, however ugly.
+
+  STANDARD.md's canonical numbers are asserted against `HOUSE_BUDGET`, `EASE` and
+  `DURATION_MS` on every run, so the document cannot become a second source of
+  truth that reads as authoritative while being stale.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Doman Digital Ltd
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/PRINCIPLES.md

@@ -0,0 +1,93 @@
+# Why this package exists
+
+Not to make things consistent. Consistency was already achievable, and largely
+achieved, by hand. This package exists because the numbers that govern how a
+Doman Digital surface looks were written down in three places that never agreed,
+and because several of them were wrong in ways nobody could see by reading them.
+
+## The defect
+
+**Three token vocabularies, zero shared numbers.** `packages/ui/tokens/` in the
+monorepo, a `:root` block in a client site with no Tailwind at all, and a
+Tailwind v3 config in another. Each was internally coherent. None of them shared
+a single value with the others, so "the house easing curve" meant three different
+curves depending on which repo you were standing in.
+
+**`--ease-emphasized` was byte-identical to `--ease-standard`.** Both
+`cubic-bezier(0.2, 0, 0, 1)`. Every component reaching for emphasis got the
+standard curve and no emphasis. This is invisible on inspection — the names
+differ, the values are 26 characters apart, and nothing fails.
+
+**`--ease-exit` was `cubic-bezier(0.4, 0, 1, 1)` — an ease-*in* curve.** It
+starts slow and accelerates out of view. It is the one curve never to use for
+UI: a dismissal on an ease-in reads as the interface dragging the thing away from
+you rather than getting out of your way.
+
+**A site was stranded at `opacity: 0`.** A reduced-motion block used
+`animation: none`. That removes the animation *and* its `forwards` fill, so a
+forwards-filled entrance keyframe never applies its end state and the element
+keeps the `opacity: 0` from its own base rule. The content was permanently
+invisible, for exactly the users who had asked for less motion. Collapsing the
+duration to `0.01ms` runs the animation to completion inside a frame instead:
+the end state applies, and nothing moves.
+
+**141 classes painting nothing.** `bg-bg3` (48 uses) and `border-border` (93) in
+the portal reference Tailwind theme keys that do not exist under v4. They resolve
+to nothing and fall through to whatever the base rule said. Adding the missing
+keys would not be a fix — it would suddenly paint 48 surfaces nobody designed.
+
+**Two guesses at one accessible accent.** Two client repos each hand-picked a
+"legible variant" of the brand accent and wrote the contrast ratio into a
+comment. Both were plausible. Neither was re-checked when the accent moved, and
+a comment is not a measurement.
+
+## What follows from that
+
+**Anchors are sacred.** Any hex a consuming repo supplies comes back out of a
+ramp as the same string, byte for byte. That is the only reason an existing site
+can adopt this without a visual diff. Values that already shipped stay literal;
+only the steps nobody had picked get computed. The tests assert string identity,
+not colour equality, because re-serialising `#7050f5` through a colour space and
+back is exactly the kind of "no visible change" that turns out to be visible.
+
+**Derived values carry their measurement.** `accentFork` does not pick a nice
+lighter violet. It walks the ramp from the brand end and returns the first step
+that actually clears both 4.5:1 and Lc 60 against every background it will sit
+on, with the measured ratios emitted as a CSS comment beside the token. When
+nothing clears the bar it says so loudly rather than returning the least-bad in
+silence.
+
+**Both contrast models, because they disagree and the disagreement matters.**
+The portal's shipped `--violet-400` (`#a78bfa`) scores 7.21:1 against the
+marketing canvas — comfortably AA — and Lc −49.1, which is under the house bar
+for body text. WCAG 2.x is what an audit asks for; APCA is what tracks
+readability on dark backgrounds. The house bar is the pair.
+
+**Search from the brand end, not the legible end.** On a dark background every
+step lighter than the accent eventually passes a contrast check, so a naive
+search returns near-white. The answer that is useful is the *darkest* step that
+passes: maximum brand, minimum sufficient contrast.
+
+**Motion is a decision before it is a curve.** The commonest motion defect is
+not a wrong easing, it is animating something that should have been instant.
+`shouldAnimate` refuses keyboard-triggered motion outright, refuses anything a
+user hits a hundred times a day, and always gives a reason — so a "no" is
+arguable rather than mysterious.
+
+**Plain custom properties, nothing else.** The consumers do not agree on a
+styling engine and are not going to. Custom properties are the only output all
+of them can read without a build step. What this package deliberately does not
+decide: the styling engine, the motion library, or where the tokens live.
+
+## The tension the ramp has to resolve
+
+An anchor's real lightness and the ramp's lightness curve contradict each other.
+`#7050f5` sits at OKLCh L=0.564; `LIGHTNESS_CURVE[500]` is 0.658. Pin the anchor
+at 500, generate 600 from the raw curve at 0.586, and step 600 comes out
+*lighter* than step 500 — a ramp that reverses direction halfway down.
+
+Both properties are required, so neither can be dropped. The curve is warped
+instead: a piecewise-linear map pinned at 0 and 1 that passes through
+(curve value, actual value) for the anchor. Monotonic by construction, and every
+other step keeps its relative position. The anchors define the ramp; the curve
+only sets the spacing between them.

package/README.md

@@ -0,0 +1,105 @@
+# @domandigital/craft
+
+The Doman Digital house craft standard, as numbers.
+
+OKLCh colour ramps that snap to colours you already ship, semantic tokens derived
+with measured WCAG **and** APCA contrast, one motion vocabulary shared by CSS and
+JS, and a base stylesheet. Zero runtime dependencies.
+
+Read [PRINCIPLES.md](./PRINCIPLES.md) for why each rule is a rule.
+
+## Install
+
+```bash
+pnpm add @domandigital/craft
+```
+
+## Use
+
+```ts
+import { craftTokens } from "@domandigital/craft";
+
+const { css, report, ramps } = craftTokens({
+  // Steps you already ship come back byte-identical.
+  accent: { 400: "#a78bfa", 500: "#7050f5", 600: "#6e4ce8" },
+  bgCanvas: "#04060e",
+  bgSurface: "#0b1120",
+  bgElevated: "#151c2e",
+  textPrimary: "#ecf2ff",
+  textSecondary: "#b7c3d9",
+  textMuted: "#8e9cb5",
+  borderSubtle: "rgba(184, 198, 219, 0.16)",
+  borderStrong: "rgba(184, 198, 219, 0.28)",
+  success: "#3fb98a",
+  warning: "#d6a14a",
+  danger: "#e26d6d",
+  info: "#5aa7e8",
+});
+
+if (report.failures.length > 0) {
+  // Fails the house bar (4.5:1 AND |Lc| 60). Surface it; do not ship past it.
+  console.warn(report.failures.map((f) => f.note).join("\n"));
+}
+```
+
+Write `css` to a committed file and import it. Then, once, in your global
+stylesheet:
+
+```css
+@import "@domandigital/craft/craft.css";
+```
+
+`craft.css` needs no build step and works with or without Tailwind.
+
+On Tailwind v4, also import the theme bridge:
+
+```css
+@import "@domandigital/craft/craft.tailwind.css";
+```
+
+On Tailwind v3, add the preset:
+
+```js
+const { tailwindV3Preset } = require("@domandigital/craft");
+module.exports = { presets: [tailwindV3Preset()] };
+```
+
+## The standard itself
+
+[STANDARD.md](./STANDARD.md) is the eleven-section house standard, every numeric
+rule cited, including a section on what is deliberately *not* a rule. Its
+canonical numbers are compared against the code on every test run, so the
+document cannot drift from what ships.
+
+## The anchor guarantee
+
+Every hex you pass in comes back out unchanged — the same string, byte for byte.
+That is what lets a live site adopt this without a single pixel moving. Only the
+steps you never picked by hand are generated.
+
+## What it will tell you that you did not ask
+
+`report.failures` lists every text-on-surface pair that clears WCAG AA but misses
+the house APCA bar, which is the failure mode a WCAG-only check cannot see. The
+accent fork emits its measured ratios as a CSS comment, so the choice is
+checkable rather than asserted.
+
+## API
+
+| Area | Exports |
+| --- | --- |
+| Colour space | `hexToOklch`, `oklchToHex`, `toGamut`, `inSrgbGamut`, `inP3Gamut`, `deltaEOk`, `deltaEOkHex` |
+| Ramps | `ramp`, `rampFromAnchors`, `RAMP_STEPS`, `LIGHTNESS_CURVE` |
+| Contrast | `wcagContrast`, `apcaContrast`, `checkPair` |
+| Semantic | `semantic`, `accentFork` |
+| Motion | `EASE`, `EASE_TUPLE`, `DURATION_MS`, `DURATION_S`, `SPRING`, `SCALE`, `exitDuration`, `shouldAnimate` |
+| Type | `fluidType`, `fluidClamp`, `typeFeatureTokens`, `HOUSE_TYPE`, `TYPE_STEPS` |
+| Space | `fluidSpace`, `sectionRhythm`, `SPACE_STEPS` |
+| Density | `densityCss`, `densityTokens`, `DENSITIES` |
+| Restraint | `checkRestraint`, `HOUSE_BUDGET` |
+| Tailwind | `tailwindV3Preset` (v3), `tailwindV4Theme` / `craft.tailwind.css` (v4) |
+| Emit | `craftTokens`, `emitCss`, `motionTokens` |
+
+## Licence
+
+Apache-2.0

package/STANDARD.md

@@ -0,0 +1,166 @@
+# The Doman Digital craft standard
+
+Eleven sections. Every numeric rule is cited, and section 10 says what is
+deliberately *not* a rule.
+
+This document and the package are bound together by a test: the machine-readable
+block in section 11 is compared against `HOUSE_BUDGET`, `EASE` and
+`DURATION_MS` on every run, so the standard cannot drift from what ships.
+
+---
+
+## 1. Colour is derived, not picked
+
+Anchors — colours a surface already ships — are sacred and come back byte-identical.
+Everything else is generated in OKLCh from those anchors.
+
+- Ramps have **11 steps** (50–950).
+- Gamut mapping reduces **chroma only**, preserving hue and lightness
+  (CSS Color 4 §13.2). RGB clipping is rejected: it walks a saturated violet
+  toward magenta.
+- Derived values standing in for a hand-picked one must be within
+  **ΔE_OK ≤ 0.02** — the just-noticeable difference — or be declared an
+  intentional change.
+
+*Source: Ottosson, "A perceptual color space for image processing" (2020); CSS Color 4 §13.2.*
+
+## 2. Contrast is measured against both models
+
+- Body text clears **4.5:1** (WCAG 2.x AA) **and** **|Lc| 60** (APCA-W3 0.1.9).
+- Large text and non-text UI clear **3:1**.
+- The two disagree, and the disagreement is the point: `#a78bfa` on `#060b19`
+  scores 7.21:1 and Lc −49.1. WCAG is what an audit asks for; APCA is what tracks
+  readability on dark backgrounds.
+- An accent fork searches **from the brand end**, returning the darkest passing
+  step, and emits its measured ratio as a comment. Searching from the light end
+  returns near-white, which passes everything and is no longer the brand colour.
+
+*Source: WCAG 2.2 SC 1.4.3; APCA-W3 0.1.9.*
+
+## 3. Type is fluid, and always has a rem term
+
+- Steps **−2 to 5**, `clamp()` interpolated between a small and a large viewport.
+- The interpolation term is **`rem + vw`, never bare `vw`** — a bare-`vw` size
+  ignores the browser text-size setting and fails WCAG 1.4.4 at 200% zoom.
+- Existing sizes are **pinned**, not regenerated, so adopting the scale moves
+  nothing.
+
+*Source: Utopia (utopia.fyi); WCAG 2.2 SC 1.4.4.*
+
+## 4. Typographic detail is not optional
+
+- Display tracking **−0.01em**; button **0.12em**; eyebrow **0.24em**.
+- Leading: display **1.05**, heading **1.1**, body **1.6**.
+- Measure **45–75ch**; body **65ch**.
+- Headings `text-wrap: balance`; body copy `text-wrap: pretty`.
+- Numeric columns get `tabular-nums` and align to the end. Proportional figures
+  in a column do not line up.
+- Clipped display text gets a **descender mask** (`padding-bottom: .16em;
+  margin-bottom: -.16em`), or it loses the tails of g, j, p, q, y.
+
+*Source: house habit — the −0.01em display tracking and the ch measure were arrived at independently in two client repos.*
+
+## 5. Space is fluid and proportional to type
+
+- Steps **3xs–3xl** as multiples of a base (0.25× to 6×), plus **one-up pairs**.
+- Section rhythm has **three** sizes, not five. Five shipped with zero consumers,
+  which is the signature of a scale invented ahead of a need.
+
+*Source: Utopia; measured — `--space-section-xs..xl` had no consumers in the monorepo.*
+
+## 6. Density is a property of the surface
+
+Three densities on a **4px grid**: rows **32 / 40 / 48px**. A table an operator
+scans for six hours and the same component on a client dashboard have different
+needs. Set once on a shell via `[data-density]`, inherited below.
+
+*Source: Linear and Stripe both converge on 4px with a 32/40/48 row ladder.*
+
+## 7. Motion is a decision before it is a curve
+
+- **The LCP element never animates.** Animating it delays the metric by exactly
+  the animation's duration.
+- **Transform and opacity only.** Everything else cannot be composited.
+- **Exits run at 0.75× their entrance.** Arriving content is asking to be read;
+  leaving content lingering reads as lag.
+- **No ease-in for UI, ever.** It accelerates away from the user.
+- **UI durations ≤ 300ms.** Drawers and one gated reveal may exceed it.
+- **Don't animate what fires 100×/day**, and never animate a keyboard-triggered
+  interaction — the user is moving faster than the animation.
+- **One signature moment per page**, gated, never the LCP element.
+
+*Source: Emil Kowalski, "Animations on the Web"; Core Web Vitals (LCP).*
+
+## 8. Reduced motion collapses, never disables
+
+`@media (prefers-reduced-motion: reduce)` sets `animation-duration` and
+`transition-duration` to **0.01ms** and `animation-iteration-count` to 1.
+
+**Never `animation: none`.** That drops the `forwards` fill along with the
+animation, so a forwards-filled entrance never applies its end state and the
+element keeps `opacity: 0` from its base rule — permanently invisible, for
+exactly the users who asked for less motion. This shipped.
+
+Images: AVIF and WebP, in that order.
+
+*Source: WCAG 2.2 SC 2.3.3; measured — a live site was stranded at opacity 0 by this exact defect.*
+
+## 9. Restraint is the budget
+
+Per surface: **≤10 font sizes, ≤3 weights, ≤2 families** (plus mono),
+**≤4 radii, ≤4 shadows**, accent hues clustered within **15° OKLCh**.
+
+Differentiation guards pass anything that differs from its siblings, however
+ugly. What they cannot see is accumulation — eighteen font sizes, six shadows,
+four competing accents, each added reasonably, together reading as noise.
+
+*Source: measured against the estate; the budget is the observed ceiling of the surfaces that read as designed.*
+
+## 10. What is deliberately not a rule
+
+The package emits **plain CSS custom properties** precisely so these stay free:
+
+- **The styling engine.** Tailwind v3, v4, or none. Adapters exist for the first
+  two; the third needs nothing.
+- **The motion library.** `EASE_TUPLE` carries the same control points as `EASE`,
+  so Framer Motion, GSAP and CSS agree without the package choosing one.
+- **Where tokens live.** A `:root` block, a generated file, a Tailwind theme —
+  the package does not care.
+- **Layout, grid and component structure.** Out of scope.
+- **Brand voice, copy, and photography grading.** Separate standards.
+
+A rule here has to be one that is wrong to break. Everything else is a default.
+
+## 11. The numbers
+
+<!-- craft:canonical -->
+```json
+{
+  "budget": {
+    "maxFontSizes": 10,
+    "maxFontWeights": 3,
+    "maxFontFamilies": 2,
+    "maxRadii": 4,
+    "maxShadows": 4,
+    "accentHueClusterDeg": 15,
+    "maxUiDurationMs": 300
+  },
+  "ease": {
+    "out": "cubic-bezier(0.23, 1, 0.32, 1)",
+    "inOut": "cubic-bezier(0.77, 0, 0.175, 1)",
+    "drawer": "cubic-bezier(0.32, 0.72, 0, 1)",
+    "reveal": "cubic-bezier(0.22, 0.61, 0.36, 1)"
+  },
+  "durationMs": {
+    "press": 120,
+    "tooltip": 150,
+    "dropdown": 200,
+    "modal": 300,
+    "drawer": 400,
+    "reveal": 500,
+    "stagger": 60
+  },
+  "exitRatio": 0.75,
+  "contrast": { "minWcag": 4.5, "minLc": 60, "deltaEOk": 0.02 }
+}
+```