Skip to main content

max / makeover-geometry

Strip historical narrative from documentation Remove what a doc used to say, when it changed, the incidents that justified a rule, finished migration narration, and counts and versions that rot. State the rules in the present tense instead. Keep every instruction, prohibition and threshold, and keep the measurements that make a rule actionable. Public-facing docs keep their explanatory voice.
Co-Authored-By
Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session
https://claude.ai/code/session_01MptwXZ8k65v19rFmdGAyki
Author: Max Johnson <me@maxj.phd> · 2026-08-31 01:51 UTC
Signed with PGP, not checked
Commit: cc5de30f290faace874c341bb3b7453e6b48b7bd
Parent: 6f75e9b
1 file changed, +26 insertions, -42 deletions
M src/lib.rs +26 -42
@@ -93,23 +93,22 @@
93 93 //! | pane | 24 | 24 | a shell is not a target |
94 94 //! | page | 32 | 32 | a shell is not a target |
95 95 //!
96 - //! The previous Touch preset was thrown out on 2026-07-29 because it also
97 - //! *tightened* `Pane` and `Page`, on the argument that outer margin is screen
98 - //! you do not get. **That is a claim about screen budget, not about the input
99 - //! device**, and smuggling it into this axis is what broke: opening `Section`
100 - //! to 16 while tightening `Pane` below it made any Pointer `Pane` at or under
101 - //! 16 an inversion, so a derived preset silently set a floor under the one
102 - //! quoted from the HIG. A phone is small *and* touch; a tablet and a
103 - //! touchscreen laptop are big and touch. Screen budget is a separate axis and
104 - //! does not belong here.
96 + //! A Touch preset must never *tighten* `Pane` or `Page` on the argument that
97 + //! outer margin is screen you do not get. **That is a claim about screen
98 + //! budget, not about the input device.** Opening `Section` to 16 while
99 + //! tightening `Pane` below it makes any Pointer `Pane` at or under 16 an
100 + //! inversion, so a derived preset silently sets a floor under the one quoted
101 + //! from the HIG. A phone is small *and* touch; a tablet and a touchscreen
102 + //! laptop are big and touch. Screen budget is a separate axis and does not
103 + //! belong here.
105 104 //!
106 105 //! ## The one cross-density rule
107 106 //!
108 107 //! **Touch never resolves tighter than Pointer**, at any gap. Stated as a
109 108 //! deliberate claim rather than inherited, and chosen for its direction: it
110 109 //! constrains the *derived* preset by the *quoted* one, never the reverse. A
111 - //! Pointer retune downward moves freely and cannot be blocked by Touch, which
112 - //! is the exact failure this replaces. Only a Pointer move upward can push
110 + //! Pointer retune downward moves freely and cannot be blocked by Touch. Only a
111 + //! Pointer move upward can push
113 112 //! Touch, and that is the correct direction of authority.
114 113 //!
115 114 //! # Size class: the axis Density kept being asked to carry
@@ -119,10 +118,9 @@
119 118 //! a touchscreen laptop are big and touch; a half-width desktop window is small
120 119 //! and pointer. Four real combinations, and one axis cannot name them.
121 120 //!
122 - //! This is the home for the claim the old Touch preset was thrown out for
123 - //! making: *outer margin is screen you do not get*. That claim was never wrong,
124 - //! it was on the wrong axis, and putting it on the input device is what let a
125 - //! derived preset set a floor under a quoted one.
121 + //! This is the home for the claim *outer margin is screen you do not get*. On
122 + //! the input device it lets a derived preset set a floor under a quoted one;
123 + //! here it is correct.
126 124 //!
127 125 //! Boundaries are **quoted** (Material 3 window size classes: 600 and 840)
128 126 //! rather than derived, for the same reason the [`Gap`] values are. This crate
@@ -131,9 +129,8 @@
131 129 //!
132 130 //! Size class feeds [`Gap::step_at_size`], and only the two shells listen to
133 131 //! it: `pane` and `page` come down one step on a compact window. That is where
134 - //! "outer margin is screen you don't get" belongs. It sat in the Pointer
135 - //! preset's pending retune until 2026-08-09, which would have been the same
136 - //! mistake the old Touch preset made, one axis over.
132 + //! "outer margin is screen you don't get" belongs. It does not belong in the
133 + //! Pointer preset, which would be the same mistake one axis over.
137 134 //!
138 135 //! # Surfaces, and why a TUI is not a third density
139 136 //!
@@ -350,8 +347,7 @@
350 347 /// `@media`.
351 348 ///
352 349 /// A capability question rather than a width or a device, which is the
353 - /// policy this crate already settled for [`density_css`] and which three
354 - /// consumers previously answered three ways.
350 + /// policy this crate settles for [`density_css`].
355 351 ///
356 352 /// The two are **not** each other's textual negation, and that is the
357 353 /// reason they live in one place. Touch is comma-joined, so it is an OR,
@@ -391,9 +387,8 @@
391 387 /// This enum carries the **boundaries only**. What appears, disappears or
392 388 /// reflows at each is a product decision and belongs to `makeover-touch`, not
393 389 /// here, with one exception: shells tighten on a compact window, through
394 - /// [`Gap::step_at_size`]. That was a look call of exactly the kind that
395 - /// produced the 2026-07-29 demolition, so it waited for an eyeball rather than
396 - /// being derived a second time, and got one on 2026-08-09.
390 + /// [`Gap::step_at_size`]. That is a look call, so it is eyeballed rather than
391 + /// derived.
397 392 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Default)]
398 393 pub enum SizeClass {
399 394 /// Under 600px. Phones in either orientation, and any window narrowed to
@@ -605,19 +600,11 @@
605 600 /// controls do not, because how much room a window has says nothing about
606 601 /// how far apart two tap targets should be.
607 602 ///
608 - /// **Which axis owns this** (Max, 2026-08-09). The Pointer preset was
609 - /// carrying a retune to `pane 14 / page 16` on the strength of a specimen
610 - /// that wanted a tighter window edge. A tighter window edge is a claim
611 - /// about screen budget, and the 0.3.0 Touch re-derivation had already
612 - /// ruled that smuggling screen budget into the density axis was the whole
613 - /// bug the old Touch preset embodied — it just had nowhere else to put it,
614 - /// because [`SizeClass`] did not exist yet. It does now, so the claim goes
615 - /// where it belongs and the quoted Pointer values hold.
616 - ///
617 - /// Two things fall out. There is no need for a `Step` at 7/8 = 14, which
618 - /// is off the eighths scale and would have wanted a public name; both
619 - /// compact values are already on it. And no consumer migrates, because no
620 - /// quoted value changed.
603 + /// **Which axis owns this** (Max). A tighter window edge is a claim about
604 + /// screen budget, and smuggling screen budget into the density axis is the
605 + /// bug [`SizeClass`] exists to prevent. So the claim goes here and the
606 + /// quoted Pointer values hold. Both compact values sit on the eighths
607 + /// scale, so no `Step` at 7/8 = 14 is needed.
621 608 #[must_use]
622 609 pub const fn step_at_size(self, density: Density, size: SizeClass) -> Step {
623 610 match self {
@@ -1081,13 +1068,10 @@
1081 1068 /// someone who simply wants roomier targets are both real, and neither is
1082 1069 /// visible to a media query.
1083 1070 ///
1084 - /// Settles a policy three consumers previously answered three ways. GoingsOn
1085 - /// sniffed the user agent behind a mode class, Balanced Breakfast used
1086 - /// `(hover: none)` alone, and audiofiles had no switch at all; the first of
1087 - /// those asked what device this is as a proxy for a capability already
1088 - /// reported.
1071 + /// Never sniff the user agent for this: that asks what device this is as a
1072 + /// proxy for a capability the browser already reports.
1089 1073 ///
1090 - /// Emitted inside [`CSS_LAYER`] since 0.6.0. Custom properties follow the
1074 + /// Emitted inside [`CSS_LAYER`]. Custom properties follow the
1091 1075 /// ordinary cascade, so unlayered ones outrank layered ones: an app that puts
1092 1076 /// its own `:root` overrides in a named layer while this file stayed unlayered
1093 1077 /// would find the generated tokens beating the overrides meant to replace them.