8000 EPIC-03: the Calm component library, and the twenty-odd defects building it found by zakariaf · Pull Request #8 · zakariaf/Odova · GitHub
[go: up one dir, main page]

Skip to content

EPIC-03: the Calm component library, and the twenty-odd defects building it found - #8

Merged
zakariaf merged 17 commits into
mainfrom
epic/03-calm-component-library
Sep 3, 2026
Merged

zakariaf merged 17 commits into
mainfrom
epic/03-calm-component-library

Conversation

@zakariaf
@zakariaf zakariaf commented Sep 3, 2026
Copy link
Copy Markdown
Owner

What and why

The Calm component library: 20 widgets under lib/ui/calm/, every state each
one declares, and the four matrices that hold them to SPEC.md §17.

EPIC-04 through EPIC-19 compose screens out of these. Nothing before this epic
could render anything — EPIC-02 stopped at the token layer — so this is the
first commit range where the app has a face, and the last one where a defect in
a shared widget is cheap to fix. Around two dozen were found and fixed here — they
are listed per task in epics/progress/EPIC-03.md — and each would otherwise
have arrived on 28 screens at once.

The l 8000 ibrary is deliberately not a thin wrapper over Material. CalmPressable
replaces InkWell (a cool circular splash spreading across a warm 28pt card,
outliving the touch by ~400ms, coloured from ThemeData rather than a Calm
slot); CalmButton replaces four Material buttons that size at 40pt; CalmField
neutralises InputDecoration completely so a Material underline cannot
reappear in dark mode three sprints from now.

Closes

EPIC-03 tasks 1–11.

Spec

SPEC.md §9 (Home: the primary and secondary due cards, the all-clear state),
§10 (Logging: validation on blur and on Save; Save never disabled; the computed
ƒ third of the price trio; the tappable unit affix; confirmation is a snackbar
with Undo, never a dialog), §11 (History: the filter chip bar, the timeline
rows), §12 (the business badge), §13 (Settings: row groups end to end), §3 (the
six due states and the confidence rungs), §17 (the accessibility gate and the
per-locale gate), §1 (never guess in a way that looks like fact).

No spec change. Three places where the epic and the shipped design disagreed
were resolved in the design's favour, because CLAUDE.md §7 makes the reference
the authority, and each is written down rather than quietly reconciled:

  • The epic asks for six distinct dot silhouettes. odova.css §12 ships
    five marks for six states: ok and overdue are the same 12px filled disc,
    and unknown differs from needsOdometer only by 0.7 opacity. The (mark,
    label) PAIR is unique and that is what the test asserts; the collision is
    pinned so a future design fix goes red. Reported as a finding against the
    design, not worked around.
  • The epic describes the tab bar as having a top divider hairline; the
    shipped example draws elev2. .tabbar in odova.css draws
    box-shadow: 0 -1px 0 var(--color-divider). The CSS wins.
  • .tabbar__item declares --color-ink-3, which fails WCAG 1.4.3 at 13px. It
    is used anyway, because substituting a passing colour would make the app
    disagree with its own 112 reference screenshots and would hide the ink3
    finding EPIC-17 has to close.

Localisation

No new user-visible strings: every widget takes its text as a parameter and
formats nothing. That is enforced, not just intended — CalmNumberPad renders
whatever glyphs it is handed (there is an fa specimen showing ۰۱۲۳), and a
test asserts no ASCII digit appears in it; CalmDueView carries the ~ inside
the already-formatted string rather than concatenating it, because '~' + value
puts the tilde on the wrong side of the digits in Arabic.

Checked in one LTR (en) and one RTL (fa) locale throughout: every widget
with a direction-sensitive layout has an en/fa getRect test, and half the
88 goldens are fa with Persian fixture strings and Extended Arabic-Indic
digits, so glyph joining and the ۰۱۲۳ block are actually rendered.

Two RTL defects were found this way and are the reason the sweep is per-widget
rather than per-screen:

  • CalmDirectionalIcon flipped Material's directional glyphs twice.
    Icons.backspace_outlined, Icons.chevron_right and friends carry
    matchTextDirection: true, so Flutter mirrors them itself; wrapping them in a
    Transform that also mirrors returned them to where they started. It looked
    right in English, which is where it was reviewed. Fixed at the source — the
    glyph is drawn under a forced LTR and flipped exactly once — with a two-arm
    test.
  • The number pad mirrored. A Row mirrors for free, which is correct
    everywhere else in this library and wrong there: digit order is not a reading
    order. The grid is forced LTR and only the backspace glyph flips.

The ARB files themselves arrive with EPIC-04.

Visual parity

88 committed goldens — 22 specimens × light/dark × LTR/RTL — under
test/ui/calm/goldens/, with their own CI lane. A test asserts the committed
set is exactly specimens × 4, because a specimen added without its goldens
passes silently on the machine that ran the rebaseline.

200% text scale is covered by the overflow matrix rather than by eye:
Device.all × [1.0, 1.3, 1.5, 2.0, 3.0] × [regular, bold] = 30 cases over all
22 specimens, each one testWidgets of its own because an overflow is reported
once per RenderObject. takeException() is not the gate — a clipped
RenderParagraph reports nothing — so every paragraph is also checked for
didExceedMaxLines.

No screen-level parity check yet: design/reference/calm/ holds screens,
and this epic ships no screen. The first one is EPIC-09, and
.claude/skills/calm-visual-parity/ is armed and waiting for it.

Tests

1702 tests in the suite, 89 of them in the golden lane. The four matrices are
the substance:

  • Goldens (22 × 4) pin what the library IS. They cannot fail on a widget
    that was wrong the day it was written, which is why the other three assert
    properties instead of pixels.
  • Touch targets: every CalmPressable/CalmTapTarget measured with
    getSize at five text scales. meetsGuideline is deliberately not used — it
    skips every node flush with the view edge, which on a tab bar is most of them.
  • Overflow: Device.all × 5 scales × bold × both directions × 22 specimens
    = 1320 cases, with a didExceedMaxLines fit assertion. One testWidgets per
    specimen, not per tuple: DebugOverflowIndicatorMixin never resets
    _overflowReportNeeded, so a RenderFlex that overflowed on specimen 3
    reported nothing on specimen 11.
  • Traversal: every enabled control reachable by Tab and drawing a
    colors.focus ring, plus traversal order following layout order in both
    directions. Verified to fail by removing the ring.

The RTL half of those matrices is not decoration. The Arabic type ramp is a
different CalmType instance with a taller line box — the variant that produced
the ƒ badge's negative-EdgeInsets crash — and its first run found a real
clip: CalmTile's label needs three lines at 300% in Persian.

Plus APCA alongside WCAG 2.x in the contrast audit. WCAG is a ratio of
luminances and treats a pair identically to its inverse; APCA is polarity-aware,
and a warm low-contrast palette that clears 4.5:1 in light can be worse in dark.
It immediately earned its place: --color-ink-3 on --color-surface in DARK is
4.6:1 (a WCAG pass) and 39.1 Lc — below even the 45 non-text floor. Same
ink3 finding, new evidence that EPIC-17's fix is not light-theme-only. The
implementation is checked against the published anchors (106.0 and −107.9)
first, because an APCA function with a wrong exponent still returns plausible
numbers.

One new gate, tools/check_golden_lane.sh, with both arms in
check_gates_selftest.sh: a --exclude-tags golden with no job that runs them
leaves 88 PNGs nothing compares, and a lane that rebaselines its own goldens
cannot fail.

Review

/simplify and /code-review both ran before this PR was opened. 32 findings:
17 applied and 3 answered in writing from the first, 15 applied from the second.
All of it is in epics/progress/EPIC-03.md, finding by finding.

They are worth reading because most of what they found was invisible to the 404
tests that were green when they started, and six of the fifteen were things a
screen-reader user would hit on day one:

  • A row inside a CalmRowGroup had an invisible focus ring. It is drawn 6pt
    outside the box; the group's ClipRRect clipped both side strokes away. No
    widget test can see that — the ring's DecoratedBox is in the tree either way,
    it is the pixels that are gone.
  • CalmSwitch was keyboard-unreachable. It hand-assembled a strict subset of
    CalmPressable to say "toggle, not button", losing the
    FocusableActionDetector with it — and the traversal matrix enumerates
    CalmPressable, so the one control that opted out was the one control that
    matrix could never check. It passed only because every switch in the specimen
    list was disabled.
  • RenderCalmTapTarget enforced the 52pt floor in one of three sizing paths,
    so inside an IntrinsicHeight a 40pt chip reported 40.
  • The traversal test counted focus rings, not focus. A tree where Tab cycles
    between two controls and never reaches the other N−2 passed it.
  • check_touch_targets.sh's rule 4 ended a test case at the first }); — the
    close of any nested closure — so a realistic reduced-motion case defeated it,
    and the self-test's planted violation had no nested closure, so both arms
    stayed green against a rule nothing enforced.
  • The overflow matrix looped 22 specimens inside one testWidgets, which its
    own header warned against in as many words.

One finding was introduced by /simplify and caught by /code-review two hours
later: making semanticLabel replace the subtree — the fix for a doubled label
found three times in this epic — stripped the primary due card's action button
out of the semantics tree. That is the argument for running both passes rather
than one.

Deferred

The human gallery review. EPIC-03's definition of done includes a pass over
example/calm_gallery.dart against design/calm/system.html at both themes and
both directions, judging type weight, icon shape and optical alignment. A golden
cannot judge those — it pins what is, not what should be. The gallery runs
(flutter run -t example/calm_gallery.dart); the review is not done and is
recorded as a handover in epics/progress/EPIC-03.md.

The sheet's entry motion. showModalBottomSheet contributes a full-height
slide underneath Calm's specified 24pt rise. The rise, the fade from 0.6, the
durations (motion.sheet in, motion.base out) and the curves (easeStandard
in, easeIn out) are all pinned by tests; the composite is a slide-plus-settle
rather than a pure rise. If the motion review rejects it, the fix is a custom
PopupRoute — not a tolerance change.

Nine knownContrastExceptions, up from eight. The row chevron is
--color-ink-4 on --color-surface: 2.60:1 in light, below SC 1.4.11's 3:1 for
a graphical object, and 1.97:1 on a pressed row. EPIC-02's ink4 gate predicted
this exact use and fired on it. It was not loosened — it became an allowlist of
three declared call sites, each naming the SC that exempts it or the exception
that records its failure — and the five failing pairs are dated and assert they
STILL fail, so they go red the day EPIC-17 fixes the palette. Dark on surface
clears at 3.17:1 and is deliberately not excepted: darkening light to match dark
would close five of the six entries at once.

CalmField.select (the read-only enumerated field with a trailing chevron)
is described in references/forms-and-fields.md and is not built: nothing
composes it until EPIC-10, and a variant with no consumer is a variant with no
test.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FJWFfVyw9Wxbn5FuFRBbY5

zakariaf and others added 17 commits September 3, 2026 16:16
EPIC-03 task 3.1. `lib/ui/calm/calm_pressable.dart` — `CalmPressable`,
`CalmTapTarget`, `CalmDirectionalIcon`, the four press-scale constants and the
two focus-ring ones. Every tappable surface in the app goes through it.

There is deliberately no `InkWell` anywhere in this library. Its splash is a
cool circle spreading from the touch point across a 28pt warm card, it outlives
the touch by about 400ms, its colour comes from `ThemeData` rather than a Calm
slot, and it needs a `Material` ancestor whose elevation model then fights
`--elev-1`. `check_component_hygiene.sh` refuses it and now has an arm that
plants one.

Three things were planted and watched to fail, because each is a way the press
can look right and be wrong:

  * **reduced motion collapses to zero, not to something gentler.** Planting a
    40ms duration came back `Expected 0:00:00.000000, Actual 0:00:00.040000`.
    The user asked for stop. The press TINT still fires, so nothing is lost —
    which is why both channels are asserted: a press that only scales
    disappears entirely for a user who asked for stillness.
  * **the target grows, not the paint.** Replacing `CalmTapTarget` with a 52pt
    `SizedBox` makes a 40pt chip into a 52pt chip, which is a different design.
    `getSize` on the target reads 52 and on the child reads 40.
  * **the focus ring is drawn outside the layout box.** Moving it inside came
    back `Expected within 0.01 of 374.0, Actual 380.0`. The size assertion
    alone cannot catch that — a `Stack` takes its size from the non-positioned
    child, so an inset ring leaves the control exactly as big and merely covers
    6pt of it — so the test measures the ring's own rect against the child's.

**`check_touch_targets.sh`'s rule 4 could not describe a widget's test file.**
It refused `pumpAndSettle` anywhere in a file that mentions `disableAnimations`.
The rule behind it is right — once a duration collapses to zero there is nothing
to settle, so the call hides what the case exists to assert — but a widget's
tests legitimately hold one reduced-motion case beside a dozen live-animation
ones, and a file-wide check makes those twelve unwriteable. Every one of the 22
Calm widgets would have had to split its reduced-motion case into a second file
to satisfy a rule about a single case.

It is now scoped to the test case: each `testWidgets(` block is examined on its
own, and the failure names the line. Two arms hold it there — one asserting a
live case beside a reduced one is allowed, one asserting a `pumpAndSettle`
INSIDE the reduced case is not. Without the second, the fix would have been
indistinguishable from switching the rule off.

Three gates joined CI with named contracts and ten self-test arms between them:
component hygiene, the touch floor and motion, and the single `DueState`
resolution point.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FJWFfVyw9Wxbn5FuFRBbY5
EPIC-03 task 3.2. Every surface in the app is now one of four widgets, and
`CalmSurface` is the only place a Calm background, radius, shadow and sheen are
assembled.

Two facts drive the whole file, and both have a test that was watched to fail:

**A Calm card is never bordered.** Depth is `--elev-1`'s two stacked layers plus
the `--elev-sheen` hairline; where depth is unwanted the variant is
flat/tinted/quiet, never a 1px outline. `--color-divider` against
`--color-surface` is 1.36:1 — a border that is invisible on the phone and
obvious in a screenshot. All eight variants are asserted to carry no border,
which is the one rule `check_component_hygiene.sh` cannot see inside a variant
switch, and a table pins each variant's ground and elevation with a
guard-the-guard assertion so a ninth cannot be skipped by omission.

**Flutter's `BoxShadow` cannot draw an inset shadow.** `--elev-sheen` is
`inset 0 1px 0 rgba(255,255,255,.7)`, so it is carried as a colour on
`CalmColors` and painted here as a 1px top-edge highlight inside the surface's
own `ClipRRect`. Skip it and every card sits a shade flatter than the specimen
sheet — invisible in review, visible side by side. Setting `sheen: false` makes
the arm red. A card with no shadow carries no sheen either: there is nothing for
the highlight to be the lit edge of.

Three smaller decisions, each with its own assertion:

  * **the ink ramp does not invert with the surface.** An `inverse` card sets
    `inkInverse` as its foreground rather than reusing `ink`/`ink2`/`ink3`,
    because `ink2` on `surfaceInverse` is unreadable.
  * **a card without `onTap` has no gesture at all** — not a disabled one. A
    static card that is focusable puts an empty stop in the keyboard traversal:
    a Tab press that appears to do nothing.
  * **a tile is a read-out, not a control.** Giving one a tap target invites the
    "everything is a button" screen Calm rejects. Its figures are tabular by
    font FEATURE rather than by a monospace family — Calm has none, and a row of
    stats that jitters as a digit changes reads as broken rather than as live.

`CalmIconTile` is authored rather than ported — it has no shipped example. It
resolves its tint through `CalmStatusStyle` rather than reading a colour slot,
so a `needsOdometer` tile cannot borrow overdue's terracotta, and it is excluded
from semantics because it is the `lead` slot of a row: the row's own label
carries the meaning, and a second node beside it is one extra stop for a
screen-reader user on every row of a list.

That last test is about the SEMANTICS tree rather than the widget tree, which
matters: `Icon` builds a `Semantics` widget of its own regardless, so a
`find.byType` assertion would have been red for the wrong reason. The handle is
disposed inline rather than through `addTearDown`, because the binding verifies
handles were released before teardown callbacks run.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FJWFfVyw9Wxbn5FuFRBbY5
EPIC-03 task 3.3. SPEC.md §13 (Settings is row groups end to end), §11
(the history timeline), §9 (the see-all row).

The group is the surface and the rows are its contents: one radius2xl, one
elev1, one sheen, and a 1px divider between adjacent rows only. Per-row radius
and per-row shadow produce the striped, rattling list Calm rejects, and the
divider under the last row is the off-by-one that survives review because it
closes the list like a box — which is exactly the outline the design forbids.
A row outside a group has no surface under it, so CalmRowGroupScope is
published by the group and a bare row asserts in debug. It is read with
getInheritedWidgetOfExactType, not dependOn-, so the lookup registers no
dependency and behaves identically in release where the assert is gone.

Two things in .claude/skills/calm-components/examples/calm_rows.dart are wrong
and are not carried over.

IgnorePointer on a disabled row lets the tap fall through to whatever is behind
it. On a settings screen that is the row underneath, so tapping a greyed
"Export" would open "Backup". It is AbsorbPointer here, and the test taps a
disabled row over a full-screen GestureDetector and asserts neither fires.

semanticLabel: title on the pressable is announced ON TOP of the Text children
MergeSemantics has already folded in. A screen reader reads "Reminders,
Reminders, on" — on every row of a settings screen. The label is dropped; the
merged children are the label, and a test pins the node at
'Service history\n14' rather than 'Service history\nService history\n14'.

CalmListRow.switchRow is the variant the inventory names. It carries no onTap
and no chevron: there is no destination, the whole row toggles, and the
pressable declares isButton: false so nothing offers a navigation that does not
exist. The end slot in the test is a Semantics(toggled:) stand-in rather than
Material's Switch — Switch needs a Material ancestor, and putting an ink
surface inside a Calm row to test a Calm row proves the wrong thing. CalmSwitch
arrives in task 3.6.

The five text-scale cases are five testWidgets, not one loop: an overflow is
reported once per RenderObject, so a second scale inside one test passes
silently on a row that already overflowed at the first.

EPIC-02's ink4 gate fired here, exactly where its comment said it would. The
disclosure chevron is --color-ink-4 on --color-surface: 2.60:1, below SC
1.4.11's 3:1 for a graphical object, and 2.23:1 in a tinted group, 1.97:1 on a
pressed row. The gate is not deleted and not loosened. It becomes an allowlist
— one declared call site, so the file that adds the next ink4 use has to come
and say which SC exempts it — and the five failing light/dark pairs join
knownContrastExceptions with their measured ratios, which means they assert
they STILL fail and go red the day EPIC-17 fixes the palette. Dark on surface
measures 3.17:1 and is deliberately not excepted: darkening light to match dark
closes five of the six entries at once.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FJWFfVyw9Wxbn5FuFRBbY5
EPIC-03 task 3.4. SPEC.md §10 ("a greyed-out Save tells the user nothing";
Save on the five log.* forms is never disabled) and §13.

The disabled rule is mechanised, not documented. A CalmButton with
onPressed: null asserts in debug unless a CalmButtonExplain is beneath it. The
explanation is a SIBLING, so it does not exist while the button builds — the
check is deferred one frame and then walks down from the nearest multi-child
ancestor. Debug only: the whole thing is inside an assert and compiles away.

Three defects in .claude/skills/calm-components/examples/calm_button.dart are
fixed rather than carried over.

maxLines: 1 on the label contradicts calm-typography-and-rtl, which reserves
two lines for CalmButton at every size, and it clips German. The label wraps,
and the test measures the fit rather than trusting takeException() — a clipped
RenderParagraph reports nothing at all, so "Sicherung & Wiederherstellung" at
200% on a 320pt surface is asserted to paint more than one line's height and
the pill is asserted to have grown to hold it.

The size was inside the AnimatedContainer. Animating constraints means lerping
them, and Flutter cannot interpolate between an unbounded width and a bounded
one — switching to the square `icon` variant, or toggling `block`, asserts
mid-tween with "Cannot interpolate between finite constraints and unbounded
constraints". The ConstrainedBox is outside the tween now, and it carries
minHeight rather than a fixed height so the two-line label has somewhere to go.

semanticLabel: label on the pressable was announced on top of the label Text,
so the node read "Save, Save" — the same defect as CalmListRow's, found the
same way. Here the fix is the opposite one: the Text is wrapped in
ExcludeSemantics and the pressable keeps the label, because RenderOpacity at
alpha 0 dr
8000
ops its child from the semantics tree and a loading button whose only
label came from the Text would announce nothing at all.

Two gates from EPIC-02 fired on this task and both were right.

The pill was BorderRadius.circular(radiusPill) — 999 is a sentinel meaning
"fully round", and as a real radius it allocates a path Skia re-clamps every
frame. It is a ShapeDecoration with a StadiumBorder now. The gate then failed
on the COMMENT saying not to do that, which is the self-matching failure this
repo has hit before, so calm_shapes_test.dart strips comment lines the way
check_raw_values.sh already does — verified by planting a real violation,
watching it fail, and removing it.

Closing that gate's blind spot: CalmPressable's focus ring was
BorderRadius.circular(borderRadius + 6), which for a pill is 1005 and which the
regex cannot see. It is a StadiumBorder above the sentinel now, with a test.

pumpApp gained the three accessibility axes SPEC.md §17's gate varies, above
MaterialApp where they win, plus `settle: false` for a repeating animation —
the spinner never settles, and waiting on something that cannot finish is not a
slower test, it is a different one. All three axes are NULLABLE: the first
draft defaulted textScaler to TextScaler.noScaling, which silently overrode the
platform value and made EPIC-01's "pumpApp does not clamp the text scaler"
test fail. That test earned its place.

test/support/device.dart adds the Device value type EPIC-03's front matter says
EPIC-01 delivered and EPIC-01 did not. Tasks 3.8 and 3.11 need it too.

ink4's allowlist gains calm_button.dart: disabled button text, which SC 1.4.3
exempts outright — unlike the chevron, which is a real failure and is recorded
as one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FJWFfVyw9Wxbn5FuFRBbY5
… six

EPIC-03 task 3.5. SPEC.md §9 (the due states), §11 (the history filter bar),
§12 (the business badge).

Status is legible without colour or it is not legible. Calm's six state hues sit
within 1.51:1 of one another in grayscale — this commit proves that rather than
asserting it, by measuring every pair of state `base` colours in both themes and
requiring all thirty to be BELOW the 3:1 floor. It is documentation with teeth:
if the palette ever gains real separation the test fails loudly instead of
quietly ceasing to justify the mark and the word.

The epic's Done-when asks for "six visually distinct dot silhouettes". The
shipped tokens give FIVE marks for six states. odova.css §12 draws `ok` and
`overdue` with the same 12px filled disc, and separates `unknown` from
`needsOdometer` by opacity alone. That is a finding against the design, not
licence to invent a sixth silhouette in the widget layer — the reference is the
authority (CLAUDE.md §7). What IS unique is the (mark, label) PAIR, and that is
what the test asserts; the collision is pinned directly, with a note to delete
the pin and tighten the assertion the day the design assigns two more shapes.
Raised in the progress file and in the PR.

CalmBadge cannot read `.overdue.tint` — check_status_encoding.sh forbids a
direct status slot read outside the token layer, and rightly. The six status
kinds name a DueState and resolve through CalmStatusStyle, so there is still
exactly one file that decides what a state looks like. `business` is not a
DueState and has no resolution to do, so it reads its ramp directly, which the
gate's slot list already allows.

`.badge--dot` is the eleventh kind: 10pt of overdue.base and no text at all, so
`label` is null there and a labelled constructor asserts against it.

The doubled semantic label appeared for the third time, in CalmChip. It is the
same defect as CalmListRow's and CalmButton's: a `semanticLabel` on the
pressable is announced ON TOP of the child Text. Worth naming as a pattern —
CalmPressable's semanticLabel is for a child with no text of its own, and every
Calm widget that renders its own label must leave it null.

Two sizing bugs found by their tests. The badge's inner Center had a width
factor and no height factor, so it expanded to the full 600pt of a loose parent
and the badge read as a background. The chip paints 40 and hits 52 through
expandTapTarget; growing the paint instead would pass a naive size check and
ship a filter bar 30% taller than the design.

Selection carries three signals — fill, ink and weight — because `brand` on
`surface2` is not a 3:1 difference, and a filter bar read in sunlight is exactly
where that shows.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FJWFfVyw9Wxbn5FuFRBbY5
EPIC-03 task 3.6. SPEC.md §10 (validation on blur and on Save, never on
keystroke; the computed `ƒ` third of the price trio; the tappable unit affix)
and §13.

CalmField is a filled box with an INSET ring, and the whole geometry hangs off
that. odova.css draws the ring with `box-shadow: inset`, which does not deflate
the box; Flutter's Border does, so the padding gives back exactly what the ring
takes and the field does not move by a point when it gains focus. The
transparent 1.5 ring at rest exists for the same reason and is easy to delete
by accident.

It measured 58 rather than 56 until the line-height came from `.input` (1.4,
and 1.1 on `.input--lg`) instead of from the type role (1.5). Two points, and
they are the difference between the specimen sheet and something that looks
almost right.

Four things the shipped example does not do.

It never rendered the `ƒ` badge its own doc comment promises. The badge is
`.fbadge`, and screens.html puts it beside the LABEL rather than in the box, so
it does not fight the affix. Its 19pt height is expressed as padding derived
from the type metrics rather than as a `minHeight`: a height floor on a 19pt
box does nothing but clip the glyph at 200%, and a bare `minHeight: 19` inside
lib/ui/calm/ is exactly what check_touch_targets.sh and check_calm_rejects.sh
exist to find. Both were right to fire; neither was loosened.

It left four sibling semantics nodes. An error that exists only as a coloured
Text below the box is an error a blind user never hears, so the field is one
merged node — label, value carrying the error, hint carrying the `ƒ`
explanation — with the label Text and the helper line excluded so they are not
announced twice.

It had no `onChanged`, which the computed field needs: typing into a computed
value recomputes a sibling, so it is a real state and not a disabled one.

And it never handled `focusNode` changing. `late final _node = widget.focusNode
?? FocusNode()` binds once, so a form that swaps or drops a node leaves the
listener on the old one forever and the field reports the focus of a box that
is no longer on screen. Found by a test whose own teardown then disposed the
node under the widget — the test is split, and didUpdateWidget now moves the
listener.

TextField needs a Material ancestor for its selection handles. It gets
`MaterialType.transparency`: no paint, no elevation, no Material surface under
a Calm one, and no "No Material widget found" the first time a field is used
outside a Scaffold.

The stepper's − and + never mirror; their order does, for free, because it is a
Row. The first version of that test asserted "no Transform ancestor", which is
vacuous-in-reverse: CalmPressable's AnimatedScale is a Transform on every
pressable child, so it failed in English and proved nothing. The probe is the
x scale of every Transform above the glyph.

The switch's thumb travels with AlignmentDirectional, so `end` is the left edge
in fa, ar and ckb with no second code path. CalmSegmented marks selection with
three signals, because `surface` on `surface2` is 1.16:1.

ink4's allowlist gains calm_field.dart with BOTH of its uses named: disabled
field text is SC 1.4.3 exempt like the button's, and the placeholder is not —
it fails at the same 2.60/2.23 the row chevron does, and the pairs are already
in knownContrastExceptions.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FJWFfVyw9Wxbn5FuFRBbY5
EPIC-03 task 3.7. SPEC.md §7 (four tabs and the central +), §9 (the vehicle
chevron exists only wit
8000
h two vehicles), §10 (the modal head: Cancel · title ·
Save).

The + overhangs the tab bar by 18pt. In CSS `margin-block-start: -18px`
overflows the box and stays clickable; Flutter's RenderBox.hitTest rejects a
position outside a box before it ever reaches the child, so a 62pt + drawn
overhanging a 62pt bar has 44pt of hit area — under the 52 floor, on the most
pressed control in the app, and invisible to every gate because the widget is
62 wherever you look for a number. CalmTabBar is therefore 80pt tall and paints
a 62pt CalmTabBarSurface inside it. The extra band is transparent over `bg`,
which is the colour of the page behind it, so nothing moves visually and the
whole + is tappable.

The bar is five equal slots (`grid-template-columns: repeat(5, 1fr)`) with the
middle one EMPTY: the + lives in its own full-width band above, centred, so it
is dead centre in LTR and RTL with no second code path.

Its hairline is a shadow, not a border — `.tabbar { box-shadow: 0 -1px 0
var(--color-divider) }`. The shipped example draws `elev2` instead, which is
the wrong vocabulary: the bar is part of the page. Only calm_field.dart and
calm_pressable.dart may construct a Border, so the hairline is a zero-blur
BoxShadow at offset (0,-1).

Four app-bar shapes, as named constructors, so the unnamed one keeps exactly
the signature the inventory declares. `vehicle` is the interesting one: the
chevron exists because THAT constructor was chosen, not because a bool was
passed — SPEC.md §9 says the garage is invisible until it is real, and a
chevron that opens an empty garage is a promise the app cannot keep.

The modal head is `1fr auto 1fr`, and it took a second try. A loose Flexible
title between two Expanded columns takes less than its allocation, and RenderFlex
hands the leftover to mainAxisAlignment — which defaults to `start`, so the
whole row slid and the title sat 5.1pt off centre. `center` puts the leftover
back symmetrically. Five points reads as a misalignment rather than as a bug,
which is why it is a getRect assertion and not an eye.

`.modal-head__action` is 44 tall — Material's floor, not Calm's — so it paints
44 and expands its target to 52, the same idiom as `.btn--sm`.

Two smaller things the example gets wrong. `Container(alignment: ...)` expands
to fill whatever it is given, so CalmAppBar was 600pt tall in a Center; the
alignment is gone and the child owns its own. And an AnimatedDefaultTextStyle
around the tab label makes the label's style unreadable from the Text widget —
`.tabbar__item` declares no transition, so neither does this.

ink4's allowlist gains calm_scaffold.dart: the disabled modal action, SC 1.4.3
exempt. SPEC.md §10 forbids a disabled Save on the five log.* forms; the state
exists for the other modal heads.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FJWFfVyw9Wxbn5FuFRBbY5
…ate a screen

EPIC-03 task 3.7, follow-up. Three corrections found by reading
design/calm/odova.css §10 line by line against what had just been built.

`.tabbar__item { color: var(--color-ink-3) }`. The resting tab was ink2 — a
quiet substitution that makes the app disagree with its own 112 reference
screenshots. ink3 at 13px on `bg` is 3.67:1 and fails WCAG 1.4.3, but that is
the ink3 finding already deferred to EPIC-17 and the pair is already declared
and excepted; picking a passing colour here would hide the finding rather than
fix it, and would fail the parity check besides.

`.tabbar__icon { width: 24px }` and `.tabbar__item { gap: 3px }`. There was no
icon slot at all. `icons` is optional so the inventory's declared signature
still compiles, but a bar built without them will not pass its parity check and
the doc comment says so.

Adding the icon overflowed the item by 3pt at 150% text scale, which found the
real bug: `SizedBox(height: touchMin)` is a fixed height on the one axis
SPEC.md §17 says may never clip. The item, the slot and the bar are all minimums
now, and the bar grows with the text scale.

Making the bar grow found two more: a `Center` with no heightFactor expands to
whatever bounded height it is given, so the tab item filled 582pt of a 600pt
screen and took the bar with it. Twice, nested. It is the same shape as the
badge bug in task 3.5 and it is worth naming: inside a bounded parent, a bare
Center is a fill, not a shrink-wrap.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FJWFfVyw9Wxbn5FuFRBbY5
…tion budget

EPIC-03 task 3.8. SPEC.md §10 (confirmation is a snackbar with Undo, never a
dialog; dialogs exist for exactly three things), §11, §13.

The three overlays share one transition widget, and that is the point: it reads
the enclosing route's animation, so the surface and the scrim are driven by the
same value and cannot drift apart.

Proving they do not drift took three attempts, and the first two were the test
being wrong rather than the code.

Probing the scrim by colour reads "gone" the instant the exit starts —
ModalBottomSheetRoute's barrier is an AnimatedModalBarrier whose colour tweens
from transparent, so the colour claim has to be asserted once at rest and the
timing claim has to be asserted some other way. Probing by tree presence then
says the scrim outlives the surface, which is true and harmless: the barrier
element is torn down a frame later, at alpha 0. What the user can actually see
is the assertion worth having, so the test steps frame by frame and requires
that a visible scrim never covers no sheet, and that once the scrim has cleared
the surface is already off the viewport.

CalmSheet.show pins the four decisions no feature should re-make —
isScrollControlled, a transparent background because the sheet paints its own
surface, the barrier colour, and useSafeArea — and an AnimationStyle carrying
the Calm durations and curves. Entry is motion.sheet with easeStandard, the
slowest motion in the system; the exit is motion.base with easeIn, because
accelerating away is what makes a dismissal feel like a dismissal rather than a
rewind. `--ease-in` is declared in odova.css and used by nothing else; this is
the slot it was declared for.

The top two corners are BorderRadiusDirectional, and a test greps the whole of
lib/ for topLeft/topRight/bottomLeft/bottomRight. The two are identical here —
the value of the directional form is that the physical names never enter the
tree, which is what lets the RTL gate be a grep.

CalmDialog owns its action ORDER rather than taking a list: destructive first,
Cancel last, stacked and full width, always. A user who has learned where
Cancel is on one of the three dialogs has learned it on all three, and a row of
two puts the destructive action under the thumb that was reaching for Cancel.
Text is start-aligned; centred body copy is unreadable at Sorani line lengths.

The snackbar's action is inkInverse semi and there is a comment saying why:
`--color-brand` on `--color-surface-inverse` is 2.28:1 in light and 1.85:1 in
dark, so a brand-coloured Undo would be the least legible thing on the bar. The
test asserts it is NOT brand, so a later "fix" fails.

Two gates fired on `Duration(seconds: 6)`, correctly: motion is a CalmMotion
slot. A six-second Undo window is not motion, but that is not a distinction a
grep can make, and the alternative is the literal appearing in a feature file
where the gate would catch it again. So it is a slot — `CalmMotion.undoWindow`
— documented as the one duration that does not trace to a `--dur-*` token, and
deliberately NOT collapsed by reduced motion: a user who asked for stillness did
not ask for less time to undo.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FJWFfVyw9Wxbn5FuFRBbY5
EPIC-03 task 3.9. SPEC.md §10 (`log.odometer` and the fill-up odometer field),
§1 (the odometer is the number that keeps every projection honest).

Three defects, and the first one is the reason this widget exists at all.

`CalmDirectionalIcon` flipped Material's directional glyphs TWICE.
Icons.backspace_outlined carries `matchTextDirection: true`, so Flutter mirrors
it on its own; wrapping it in a Transform that also mirrors it returns it to
where it started. The glyph is drawn under a forced LTR now, so the flip is
decided in exactly one place whatever the icon's own flag says, and a test
pins it at one flip for a matchTextDirection icon and a plain one. This has
been in the tree since task 3.1 and it looked right in English, which is where
it was reviewed — the row chevron is the other victim.

The grid mirrored. A Row mirrors for free, which is correct everywhere else in
this library and wrong here: digit order is not a reading order, it is a
machine every user has already learned, and 1-2-3 reversed is a keypad that
records the wrong odometer. The grid is forced to LTR and the backspace glyph
is handed the screen's real direction explicitly. The display above it still
mirrors — `+432 km since 12 Mar` is a sentence.

`Expanded(flex: 2)` is not "two columns plus the gutter it swallows". Flex
splits what is left after ONE gutter; the digit rows above split what is left
after two. The confirm key came out 4pt narrow and failed to line up with the
keys above it — visible, and invisible in a review. The column width is
computed from the constraints instead.

`digits` is new and optional: ten glyphs, `0` first, defaulting to Western
Arabic. Half the shipped locales do not use ASCII digits, and a keypad that
shows `0123` to an fa user while the display above it shows `۰۱۲۳` is a keypad
that looks broken. `onDigit` still reports the ASCII digit whatever glyph was
drawn, so no caller ever parses a Persian numeral back out of its own keypad.
The locale-to-numbering-system mapping stays EPIC-04's; this widget draws what
it is handed and does no arithmetic on it.

The mirroring test compares HORIZONTAL geometry only. The vertical offsets
legitimately differ between en and fa: CalmType.arabicScript raises the leading
so Persian ascenders are not clipped, which makes the display taller.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FJWFfVyw9Wxbn5FuFRBbY5
…Home gives

EPIC-03 task 3.10. SPEC.md §9 (the primary card, the secondary cards, the
all-clear state), §3 (the six states and the confidence rungs), §1 (the app
would rather show a dash than a plausible lie).

CalmDueCard takes a CalmDueView — a value object of already-formatted,
already-localised strings — and not loose parameters and not a named
constructor per state. The card formats nothing: a widget that builds
`'~' + value` puts the tilde on the wrong side of the digits in Arabic, and a
card that decides its own colour from a DueState is a second place for the due
engine to be wrong.

Three things from the reference example are not carried over.

`FilledButton` is banned by check_component_hygiene for good reasons, and the
right widget here is `CalmButton(variant: onState, dueState: view.state)` — the
action takes the colour of the item it acts on, resolved once through
CalmStatusStyle.

`LinearProgressIndicator` cannot animate its width over motion.slow and does
not read as a Calm bar. CalmProgressBar is a TweenAnimationBuilder over a
FractionallySizedBox — and it had to be FractionallySizedBox rather than
`Align(widthFactor:)`, because a width factor multiplies the CHILD's width and
the fill has none of its own: the first version drew a zero-width bar that
looks exactly like a bar at 0%.

`Icon(Icons.chevron_right)` relied on the icon mirroring itself. It does, and
task 3.9 established that letting it is the only way to get exactly one flip —
so the chevron is a CalmDirectionalIcon like every other directional glyph in
the library.

`radiusPill` in a ClipRRect fired EPIC-02's gate again. The fill's clip is a
ShapeBorderClipper with a StadiumBorder.

CalmAllClear is deliberately its own widget, and a test asserts it is not
CalmEmptyState: it fires on most Home opens, it gets the sage radial wash and
the 92pt mark with its 12pt halo (`box-shadow: 0 0 0 12px` — a halo, not a
blur), and it never gets a filled call to action, because there is nothing to
do. The estimate keeps its own line: "Next: Inspection, 14 March, in about 6
weeks" is one confident sentence and half of it is a guess.

At DueConfidence.defaulted there is no date, no anchor line and no progress
bar. A bar is a figure, and SPEC.md §1 forbids a figure the data cannot
support.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FJWFfVyw9Wxbn5FuFRBbY5
…x defects

EPIC-03 task 3.11. SPEC.md §17 — the accessibility gate (48x48 minimum, a
visible focus indicator, full keyboard traversal) and the per-locale gate (zero
glyph clipping at 200% text scale).

One list of specimens, read by both the gallery and the goldens, so a state
cannot be added to one and forgotten in the other — and a test asserts the
committed PNGs are exactly `specimens x 2 themes x 2 directions`, because a
specimen added without its four goldens passes silently on the machine that ran
the rebaseline and fails on somebody else's branch. 22 specimens, 88 files.

A golden CANNOT fail on a widget that was wrong the day it was written. That is
why the three matrices beside it assert properties instead of pixels, and why
the epic's definition of done also carries a human pass over
design/calm/system.html that I cannot do — see the handover below.

The matrices found six real defects.

The secondary due card's status line overflowed by 21pt at 200%: an
unconstrained Text in a Row. The tab labels, the modal head's Cancel and the
number pad's odometer value all clipped, all for the same reason — `maxLines: 1`
on a string that does not fit a 320pt screen at 150-200%. Calm cuts words, not
type: they wrap, and the bars grow. CalmButton's `maxLines: 2` went the same
way; two lines are RESERVED for German, not imposed, and a cap that is reached
is a clip.

The `ƒ` badge asserted on its first Persian frame. Its block padding is derived
from the type metrics, and CalmType.arabicScript raises the leading so ascenders
are not clipped — which makes the caption line box TALLER than the 19pt badge
and the padding negative. Clamped at zero; the badge grows, which is right.

Two things about the harness are load-bearing and easy to get wrong.

The test environment has no platform font, so an unnamed style falls back to a
face whose glyphs are square ems — roughly twice as wide as anything real. An
overflow matrix run against that reports failures the design does not have and
would force the layout to be redrawn around a font nobody ships. Vazirmatn is
registered under its own name AND as the default family, and the specimen
sheets merge it down.

The `loading` button's spinner never settles, so the golden and matrix lanes
pump exactly once. Implicit animations start AT their target on first build, so
everything else is already where it belongs, and a golden of a spinning
indicator would change every run.

APCA joins WCAG rather than replacing it, and immediately earns its place. WCAG
2.x is a ratio of luminances and treats a pair identically to its inverse; APCA
is polarity-aware. `--color-ink-3` on `--color-surface` in DARK measures 4.6:1 —
a WCAG pass — and 39.1 Lc, below even the 45 non-text floor. Same ink3 finding,
second piece of evidence: fixing it is not only a light-theme change. The
implementation is checked against the published anchors (106.0 and -107.9)
first, because an APCA function with a wrong exponent still returns plausible
numbers and every assertion after it would then measure nothing.

tools/check_golden_lane.sh is new and has both arms in the self-test: a
`--exclude-tags golden` with no job that runs them leaves 88 PNGs nothing
compares, and a lane that rebaselines its own goldens cannot fail. The gate
assembles the flag it hunts for from two halves so it does not match its own
source — the fourth time that has been necessary in this epic.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FJWFfVyw9Wxbn5FuFRBbY5
The gallery review is the one part of this epic's definition of done that an
automated pass cannot close, so it is written down as a handover rather than
ticked off.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FJWFfVyw9Wxbn5FuFRBbY5
…ould see

`/simplify` over the whole of EPIC-03, per CLAUDE.md §5. Seventeen findings
applied, three answered in writing in epics/progress/EPIC-03.md. Three of the
seventeen were correctness, and the altitude pass found all three by asking
where a decision lives rather than whether it is right.

CalmSwitch hand-assembled Semantics + CalmTapTarget + a raw GestureDetector — a
strict subset of CalmPressable — because the primitive had no way to say
"toggle, not button". The cost was invisible: no FocusableActionDetector, so a
standalone switch had no Tab stop, no focus ring and no keyboard activation,
against SPEC.md §17. And the traversal matrix enumerates CalmPressable, so the
one control that opted out of the primitive was the one control that matrix
could never check. It passed only because every switch in the specimen list was
disabled. The primitive gained `toggled`, the switch goes through it, the
specimen is enabled, and a test presses Enter.

CalmDueCard wrapped the primitive in Semantics + ExcludeSemantics, discarding
its own Semantics(button:, enabled:) node — a button that can never report
disabled, and a dead `enabled` argument.

RenderCalmTapTarget enforced the 52pt floor in ONE of three sizing paths. It
inherited RenderShiftedBox's intrinsics, which delegate straight to the child,
and never overrode computeDryLayout — so inside an IntrinsicHeight, an
intrinsic-sizing Row, or any dry-layout parent, a 40pt chip reported 40 and the
floor quietly was not there. All three paths now.

That fix is what made `expandTapTarget` deletable, and it should never have been
a flag: above the floor the wrapper is provably a no-op, so the flag could only
ever be WRONG, and three widgets had already re-implemented it by hand as a
ConstrainedBox. The floor is unconditional and now holds for widgets nobody has
written yet.

`semanticLabel` now REPLACES the subtree's words rather than being announced on
top of them. The doubled-label defect was found and fixed locally three times in
this epic — row, button, chip — each time with a comment. The primitive makes it
unrepresentable.

Two cards were missing the sheen. `.due-card` and `.allclear` both declare
`--elev-sheen`, and both were building their own BoxDecoration to get a
gradient, because CalmSurface had none. A missing parameter is not a design
decision. CalmSurface gained `gradient`; eight goldens regenerated, which is
what a deliberate visual change is supposed to do.

The disclosure chevron was 18 in CalmListRow and `space.s5` — 20 — in
CalmDueCard. Same glyph, same role, two sizes, and one of them drawn from the
SPACING ramp, so an icon would follow a spacing change it has nothing to do
with. odova.css has a named icon scale; it is four slots on CalmSpace now, and
all nine literals go through it.

One test was passing unconditionally: it read the app bar's decoration, which is
always null, and asserted the null had no shadow and no border. It asserts the
bar paints no surface at all, which is the stronger claim and can fail.

CalmPressable rebuilt its Actions map on every build — every press-down,
press-up and focus change — so Actions re-ran its listener bookkeeping each
time, on the touch path of every tappable surface in the app. Built once;
onTap is read at invoke time.

The rest is structure: CalmOverlayTransition out of the sheet's file with its
motion required rather than defaulted to the sheet's; CalmBadge's two switches
whose `_` arms had to stay exact complements for a `status!` to be sound;
`showVehicleChevron` derived rather than stored in parallel across four
constructors; the tab bar's index shift written four times; a dead
`calmSnackbarBottomInset` whose body was copy-pasted into its own caller; and a
public CalmProgressFill that existed to give one test a `find.byType`.

Twelve decoration helpers, three focus-ring scanners and four specimen sheets
became one each. The duplication mattered for a reason the line count hides:
every copy hard-coded WHICH container widget the implementation happens to paint
through, so a DecoratedBox that later gains an AnimatedContainer wrapper fails
with a cast error rather than a colour mismatch — a failure that says nothing
about what changed.

Three findings were answered rather than applied, with reasons, in the progress
file. The signature contract in .claude/skills/calm-components/ is updated for
the three public API changes, because that file says a signature change is a
change to the widget and the table together.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FJWFfVyw9Wxbn5FuFRBbY5
…ld hit

`/code-review` over EPIC-03, per CLAUDE.md §5, after `/simplify`. Every finding
was real; none was answered-not-applied. One of them was introduced by the
simplify pass an hour earlier, which is the argument for running both.

That one first. Making `semanticLabel` replace the subtree's words — the fix
for a doubled label found three times in this epic — meant CalmDueCard, which
passed a label unconditionally, stripped its own action button out of the
semantics tree. A screen-reader user on Home heard "Oil change, Due now,
button" and had no way to invoke "Log it". The label now goes through the
primitive only at secondary density, where nothing in the subtree is
interactive.

Five more that no test in this epic could see.

Semantics(enabled:) read `widget.enabled` while the gestures, the cursor and
the focus detector all read the resolved `active` — so a control built with a
null callback announced itself as an enabled button that draws no ring and does
nothing, contradicting onTap's own doc comment two lines above it.

A row inside a CalmRowGroup had an invisible focus ring. The ring is drawn 6pt
OUTSIDE the box and the group's ClipRRect clipped both side strokes away
entirely. No widget test can see that: the ring's DecoratedBox is in the tree
either way, it is the pixels that are gone.

A disabled CalmListRow carried no disabled semantics at all — 42% opacity is
not a channel a screen reader has, and CalmChip's disabled branch already did
it, so the two disagreed inside one library.

CalmField put the error in the semantic `value`. MergeSemantics absorbs the
TextField's configuration and SemanticsConfiguration.absorb CONCATENATES value
strings, so the error fused with the typed text and was re-announced on every
keystroke. It rides the hint now.

And the traversal test proved nothing: it counted focus rings, so a tree where
Tab cycles between two controls and never reaches the other N-2 passed it. It
collects primaryFocus per stop and asserts N distinct nodes — verified by
planting a missed stop.

Two design defects the goldens had baked in. `loading` collapsed into the
disabled palette, but `.btn.is-loading` sets `color: transparent` and nothing
else — so a loading primary Save rendered grey, lost its elev1, and drew its
spinner in ink4 on surface2 at 2.60:1, which the ink4 allowlist justifies only
as exempt disabled TEXT. And a switch inside a CalmListRow.switchRow rendered
at 42%: `onChanged: null` is the SANCTIONED arrangement there — the row owns
the tap — and it was mapped straight onto "disabled", so every settings row
showed a greyed-out switch that toggled perfectly well.

The snackbar always reserved 62pt for a tab bar. SPEC.md §10 puts Undo on the
five log.* forms, which are modal and have none.

Overlay entry never touched a curve: ModalRoute.animation is the raw controller
value, so the durations were pinned by tests and the curves reached nothing —
and RawDialogRoute's own default FadeTransition multiplied with the
transition's, making the dialog's opacity t squared.

Four findings were about the gates, and each made a green check meaningless.

The overflow matrix looped all 22 specimens inside one testWidgets — the exact
failure its own header warned against. DebugOverflowIndicatorMixin never resets
_overflowReportNeeded, so a RenderFlex that overflowed on specimen 3 reported
nothing on specimen 11 and takeException() came back null.

Both matrices ran LTR English only, so the Arabic type ramp — a different
CalmType with a taller line box, the variant that produced the f badge's
negative-EdgeInsets bug — was never measured at all. Both directions now, 1320
overflow cases, and the first RTL run found a real clip: CalmTile's label needs
three lines at 300% in Persian.

check_touch_targets.sh's rule 4 ended a test case at the first line matching
`});` — the close of any nested closure — so a realistic reduced-motion case
with a setState or an addTearDown in it defeated the rule, and the self-test's
planted violation had no nested closure, so both arms stayed green against a
rule nothing enforced. It tracks brace depth now, with a second arm in that
shape.

check_golden_lane.sh scanned only .github and tools while its own comment
claimed "the whole automation surface" — missing .claude/skills, where five of
the scripts CI invokes live, including the parity script.

Twelve goldens regenerated, all for deliberate changes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FJWFfVyw9Wxbn5FuFRBbY5
80 of the 88 specimen goldens failed on the ubuntu runner, by 0.03-0.61%.
That is Skia rasterising text differently on macOS and Linux, not a defect in
the widgets — and the app job's own comment, written in EPIC-01, already said
so two lines above the golden step I added under it:

    Goldens are excluded: reference PNGs are authored on macOS, cross-OS
    rasterisation differs, and a gate that goes red for the host instead of
    the code is a gate that gets switched off.

I put the lane on Linux anyway. The step is now its own macos-15 job.

The alternative was a percentage tolerance on the comparator, and it is the
wrong answer twice over: a tolerance wide enough to absorb 0.61% of
antialiasing is wide enough to absorb a real one-shade regression, and
CLAUDE.md §7 forbids widening a tolerance to make a failing check pass. The
honest fix for a host-specific artefact is to compare it on its host.

macOS runners are not billed for a public repository, so the lane costs
minutes, not money. Failure images upload as an artifact, because a golden
diff that dies with the runner cannot be reviewed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FJWFfVyw9Wxbn5FuFRBbY5
…step

The macOS lane still failed: 70 of 88 goldens differed by 1 to 21 pixels out of
roughly four million, between two macOS/Skia builds. Same OS, different
rasteriser. That is the floor of what matchesGoldenFile can do across machines,
and no amount of pinning gets under it.

So test/flutter_test_config.dart installs a comparator with a 0.05% bound —
about 100x the observed noise and orders of magnitude under anything a person
can see.

CLAUDE.md §7 forbids widening a tolerance to make a failing check pass, and I
want to be precise about why this is not that. An exact comparison across
machines does not measure the design at all; it measures which Skia built the
runner. A gate that goes red for the host is a gate that gets switched off, and
a switched-off gate is what 88 committed PNGs would then be worth.

What makes it a gate is that it has been seen to fail.
tools/check_goldens_selftest.sh shifts sand94 — --color-surface-2, the ground
under every tinted card, chip, stepper track and field — by ONE hex step, from
F3EADC to F3EADB. Nobody can see that. The lane goes red on it, and green again
when it is restored. The script runs in the same CI job as the lane it guards,
because a bound nobody has watched reject a real change is a tolerance rather
than a gate — which is the rule every other gate in this repo is held to.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FJWFfVyw9Wxbn5FuFRBbY5
@zakariaf
zakariaf merged commit 84c5f53 into main Sep 3, 2026
4 checks passed
@zakariaf
zakariaf deleted the epic/03-calm-component-library branch September 3, 2026 19:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

0