Appearance
Design edits are hierarchy corrections: diagnose → intent → move
Context. During the occasions/person-card prototyping (PR #952) the maintainer twice had to pull the session back. First: "close" feedback was answered with brand-new directions instead of refinement. Second, and more fundamental: the refinements offered were mechanical (move the icons, delete a line, shuffle zones) rather than intentional. The steer that actually worked — "make the icon section a different colour and smaller, like it's bolted on the bottom" — wasn't a random one-variable tweak. It was a hierarchy correction by de-emphasis: a diagnosis (the tracked-icons zone carried more visual weight than its informational importance; the double hairlines were only the symptom) executed by moving every prominence-carrying property in the same direction (surface → tinted, scale → smaller, placement → footer). One intent selected the properties; the properties didn't wander on their own.
The loop. Every design change — generating variants or polishing one — runs the same four steps, and states them (in the variant's comment, the story name, the commit body):
- Diagnose in perception terms. What does the eye do wrong? The audit: rank each element's informational importance, rank its current visual weight — any mismatch IS the problem. ("Three equal bands; a tertiary zone competes with the primary content.")
- State ONE intent, as a hierarchy correction. "Demote the tracked zone to tertiary." "Promote the countdown to secondary." If you can't phrase the change as promote/demote/align, you don't have an intent yet — stop.
- Move only the weight-carrying properties, all in the intent's direction: contrast/colour, size, weight, position, containment (rule vs tint vs whitespace). Structure changes only if the intent demands them.
- Squint-verify. Does perceived weight now match importance? (The
docs/design.mdcraft self-tests are the checklist.)
Divergent mode = several hypotheses, never several arbitrary layouts: either competing diagnoses of the same complaint, or one diagnosis × different mechanisms (tint it / shrink it / detach it). Name each variant for its hypothesis, not its cosmetics.
Convergent mode (after the maintainer marks a variant "close") = the diagnosis is settled; each round is one intent, executed fully, on the frozen base. New diagnoses reopen only on explicit request ("give me N directions").
Vocabulary shortcuts the maintainer can use: "polish, not pivot" (stay convergent) · element + property + direction ("the footer — smaller, tinted, bolted on") fully specifies a convergent round · "give me N directions" reopens divergence.
The specific move that won, for reuse: separate zones inside a card with a surface tint, not another rule — two hairlines close together read as clutter; one hairline plus one tinted band reads as structure (Refactoring UI's "use fewer borders", applied as de-emphasis).