scrum-skills 0.3.2 → 0.3.4

package/.agents/skills/diagram-design/references/type-architecture.md

@@ -0,0 +1,117 @@
+# Architecture
+
+**Best for:** system overviews, data-flow diagrams, integration maps, infra topology.
+
+## Layout conventions
+- Group components by tier or trust boundary (frontend → backend → data; public → private).
+- Primary flow runs left→right or top→down. Pick one and hold it.
+- Draw arrows before boxes so z-order puts connections behind components.
+- 1–2 coral focal nodes: the primary integration point, the primary data store, or the key decision node.
+- Dashed boundary rectangles mark regions (VPC, security group, trust zone); labels sit on a paper-colored mask over the boundary line.
+
+## Connector style
+
+**Rounded right-angle (orthogonal) connectors are MANDATORY** for all non-horizontal/vertical connections — diagonal `<line>` between off-axis nodes is a hard fail (see SKILL.md §6 Mandatory connector rules). Two-bend elbow path with `r=8`:
+
+```svg
+<!-- right+down: from (x1,y1) to (x2,y2), mid = (x1+x2)/2 -->
+<path d="M x1,y1 H mid-8 Q mid,y1 mid,y1+8 V y2-8 Q mid,y2 mid+8,y2 H x2"
+      fill="none" stroke="…" stroke-width="1.2" marker-end="url(#arrow)"/>
+```
+
+Flip the vertical signs for right+up. Use a plain `<line>` only when endpoints share the same x or y. Arrow labels sit on the vertical segment, centered horizontally on `mid` and vertically between the two corners.
+
+**Port selection for vertical connectors.** When the destination is noticeably above or below the source, enter the destination through its top or bottom edge. Use a single-bend L-path: leave the source through the side edge that faces the destination's column, run horizontally, turn once, and run vertically into the destination:
+
+```svg
+<!-- destination above source: leave the source's right edge at (x_right, y_port), enter the destination's bottom edge at x2 -->
+<path d="M x_right,y_port H x2-8 Q x2,y_port x2,y_port-8 V y_dst"
+      fill="none" stroke="…" stroke-width="1.2" marker-end="url(#arrow)"/>
+```
+
+Every segment leaves its box perpendicular to the edge it starts on. Never start a horizontal segment on a top or bottom edge: it runs along the border, hidden behind the node fill, and the arrow looks like it grows out of the corner. When two of these connectors leave the same side edge, fan their ports (primitives-core.md rule 4) and keep each port at least 8px from a corner so it never lands on the corner radius.
+
+Reserve left/right ports on the destination for connections that travel primarily horizontally. Entering a node from the side on a mainly-vertical path looks like the arrow punctures the node face rather than arriving from above or below.
+
+**Dashed paths — same routing rules.** Optional, return, async, and passive flows use `stroke-dasharray="4,3"` and a lighter stroke weight (`stroke-width="1"`). Apply the **same orthogonal routing, port-selection, and bridge/hop rules** as solid paths — the dash pattern only communicates semantic weight, not a different routing grammar. When a dashed path and a solid path must cross, bridge the dashed one (it is by definition the less important connection).
+
+**Zone label margin.** Leave ≥16px between the bottom of the zone eyebrow label and the top of the first enclosed node. Size the zone rect tall enough to contain this header gap (zone `y` = node_top − 32; label mask `y` = zone_y + 4).
+
+## Crossing arrows — bridge / hop
+
+When two orthogonal arrows must cross, add a small arc (hop/bridge) on the **less important** arrow at the crossing point. The more important arrow is drawn uninterrupted.
+
+```svg
+<!-- Horizontal hop over a vertical crossing at x=cx, on a line at y -->
+<path d="M x1,y H cx-8 a 8,8 0 0,1 16,0 H x2"
+      fill="none" stroke="…" stroke-width="1.2" marker-end="url(#arrow)"/>
+```
+
+`a 8,8 0 0,1 16,0` is an SVG arc: rx=ry=8, large-arc=0, sweep=1 (curves visually upward), advancing 16px right — creating an 8px-radius semicircular bump over the crossing. For a vertical hop over a horizontal, use `a 8,8 0 0,0 0,16` on the vertical path.
+
+Decide which arrow to bridge: bridge the one that is less semantically important (passive, secondary, write-back), or the one with lighter stroke weight (dashed, muted). Never bridge both.
+
+## Zone grouping
+
+Group 2+ nodes that serve the same tier or trust boundary with a zone rect — drawn **before** arrows and nodes (z-order: bg → zones → arrows → nodes):
+
+```svg
+<rect x="{x}" y="{y}" width="{w}" height="{h}" rx="8"
+      fill="{ink @ 0.02}" stroke="{ink @ 0.10}" stroke-width="0.8"/>
+<rect x="{label_x}" y="{y+4}" width="{label_w}" height="12" rx="2" fill="{paper}"/>
+<text x="{label_cx}" y="{y+13}" fill="{soft}" font-size="7"
+      font-family="{eyebrow}" text-anchor="middle" letter-spacing="0.14em">LAYER</text>
+```
+
+Rules:
+- Leave 12–16px above the first enclosed node — the eyebrow label sits in this margin.
+- Zone fill: `ink @ 0.02` (2% ink wash). Any stronger competes with node fills.
+- **Zone label: `soft`, never ink at an opacity.** A zone eyebrow is a boundary label, and `soft` is the boundary-label role in [`style-guide.md`](style-guide.md). An opacity such as `ink @ 0.40` composites differently on every `paper`; on a light warm paper it falls near 2.2:1, unreadable at 7px. The role carries its own contrast contract under any skin.
+- Max 3 **flat** zones per diagram. More and it reads like a swimlane (use that type instead). Nested administrative and traffic scopes under **Containment** below are not this cap — they nest, so the cap is sibling traffic scopes at one level.
+- Dark mode: the roles invert with the skin, so nothing is swapped by hand. Take `ink`, `soft`, and `paper` from the dark column in [`style-guide.md`](style-guide.md); opacities stay the same.
+
+## Containment
+
+Use this section when **the network hierarchy itself carries the meaning** — the reader must see what sits inside which scope, and a flattened zone label (`VNET · SNET-APP`) would lie about that hierarchy. Connectors stay Architecture; containment geometry comes from Nested (consistent insets, eyebrow per level, fills stepping up inward). This is a variant of Architecture, not a new type and not a provider-specific grammar.
+
+Two scope kinds, never interchangeable:
+
+| Kind | What it is | Shape | `data-scope-kind` |
+|---|---|---|---|
+| **Administrative** | Billing, permissions, lifecycle. Holds no traffic. | Horizontal **band** — a full-width containment rect with a 24px header | `admin` |
+| **Traffic** | A boundary packets do not cross without an explicit rule. | **Box** — the existing zone rect (`rx=8`) | `traffic` |
+
+Provider-neutral metadata (no vendor prefix):
+
+- `data-grammar="architecture-containment"` on the root `<svg>` — files without it are ordinary Architecture and this contract does not apply.
+- `data-scope-id` + `data-scope-kind` on every scope's bounds rect (`data-role="bounds"`). Bounds are always a `<rect>`, for scopes and nodes alike.
+- `data-parent` on every nested scope and every node, naming the innermost enclosing `data-scope-id`. Only the outermost scope, which no other scope encloses, may omit it.
+- Nodes: `data-node-id`, `data-kind` of `compute` (workloads inside a traffic scope), `endpoint` (private endpoint inside a traffic scope), or `managed` (PaaS that belongs to an administrative scope).
+- An `endpoint` carries `data-target` naming the `managed` node it reaches.
+- A peering path carries `data-peering`, `data-from`, and `data-to` naming the two traffic scopes it joins.
+
+**PaaS placement (normative).** A managed service is never inside a traffic scope. It sits in the administrative band that owns it. What lives in the subnet is its private endpoint. Drawing a database inside a subnet tells the reader it sits behind that subnet's security rules, which it does not. `scripts/verify-architecture-containment.py` fails a `managed` node whose bounds fall inside any `traffic` scope, and an `endpoint` that is not inside one.
+
+**Sibling axis.** Sibling traffic scopes at one level share one axis. Directly under an administrative band the parent's aspect chooses it: wider than tall (or square) → a row sharing one `y`; taller than wide → a column sharing one `x`. Nested children take the perpendicular axis: siblings inside a traffic scope that sits in a row form a column, and their own children form a row again. Do not mix axes at one level.
+
+**Budget** (tightens Architecture's flat 3-zone cap; see `layout-budget.md`): ≤2 administrative bands, ≤4 traffic scopes, ≤8 nodes, 2 accent elements. Split per subscription when a figure exceeds that.
+
+**Draw scopes in place.** Containment is read from each bounds rect's own `x`, `y`, `width`, and `height`. Do not position a scope or node with a `transform` attribute, a moving inline style (`transform`, `translate`, `x`, `y`, `position`, `margin`, and similar), a nested `<svg>`, a `<style>` rule, or an animation, on the element or any group around it. The checker fails each of those. It does not evaluate external stylesheets or script, so keep containment geometry out of both.
+
+`scripts/verify-architecture-containment.py` checks unique IDs, resolving innermost parents, geometric containment, `<rect>` bounds, the admin-band vs traffic-box shapes (with `stroke-dasharray` resolved as rendered, so `none` or all-zero dashes count as solid), PaaS placement, endpoint targets, sibling axes, declared peerings, and the moved-geometry rule above. Files without `data-grammar="architecture-containment"` are skipped.
+
+## Anti-patterns
+- Every box in coral ("this is important too") — hierarchy collapses.
+- Bidirectional arrow when one direction is obvious from context.
+- Legend floating inside the diagram area.
+- Flattening two containment levels into one zone eyebrow (`VNET · SNET-APP`) — the hierarchy is the claim.
+- A managed PaaS box drawn inside a subnet or VPC — only its private endpoint belongs there.
+- Colour as the only distinction between an administrative band and a traffic box — the shapes must differ, because greyscale still has to tell them apart.
+
+## Examples
+- `assets/example-architecture.html` — minimal light
+- `assets/example-architecture-dark.html` — minimal dark
+- `assets/example-architecture-full.html` — full editorial
+- `assets/example-architecture-containment.html` — nested admin/traffic scopes, light
+- `assets/example-architecture-containment-dark.html` — nested admin/traffic scopes, dark
+- `assets/example-architecture-containment-full.html` — nested admin/traffic scopes, full editorial

package/.agents/skills/diagram-design/references/type-axonometric-plan.md

@@ -0,0 +1,83 @@
+# Axonometric plan
+
+**Best for:** one floor or one site seen from above at an angle, with what stands on it. An office floor with its rooms and furniture, a campus with its buildings and roads, a warehouse with its zones, a store layout. Use it when the reader needs to see rooms or buildings in relation to each other and how they are used, in a single view.
+
+**Not this type:**
+
+- Parts of one object pulled apart along an axis → **exploded axonometric** (`type-exploded.md`). A plan has one plate and nothing explodes.
+- Containment without geography → **nested** (`type-nested.md`).
+- Where software runs → **deployment** (`type-deployment.md`).
+- A list of rooms and capacities → a table.
+
+## Projection
+
+The same 2:1 dimetric projection as the exploded axonometric, from one function:
+
+```python
+def iso(x, y, z, ox, oy):
+    """Model point to SVG point. (ox, oy) is where model (0, 0, 0) lands."""
+    return ox + x - y, oy + (x + y) / 2 - z
+```
+
+Every element is a rounded prism standing on the plate: `r = 0` for walls, furniture, and buildings, `r = w / 2` for a tree canopy. `type-exploded.md` § Projection covers the corner ellipse and the face matrices; `scripts/build-axonometric-plan-examples.py` in the repository builds every shipped example from the same helpers.
+
+## Layout conventions
+
+- **Plate:** One floor slab (6 units) or one site (8 units, small corner radius). Everything stands on it, and nothing extends past its edge.
+- **Walls:** 6 units thick and cut at desk height, about 22 units, so no wall hides a room. Doors are gaps in a wall. Walls meet without overlapping: run one wall through a junction and stop the other at its face.
+- **Furniture and buildings:** Boxes on the plate with the house face shading (`type-exploded.md` § Faces and lines). Heights are to scale with each other. Two footprints never overlap.
+- **Flat marks:** Roads, paths, and floor tints sit on the plate's top face as flat fills (`ink` at 0.07) with no thickness. A dashed centre line (`ink` at 0.25, `6,5`) may mark a road.
+- **Racks:** Tall shelving is a box of kind `rack` with the house shading, a shelf line every 14 units, and an upright every 30. Run rack rows along x so the reader sees the lit face and the aisles between rows.
+- **Trees:** A canopy cylinder 8 units up on a short trunk, canopy top in `rule-solid` light or `soft` dark. Trees are planting, so keep them small and off every footprint.
+- **Paint order:** The plate first, then flat marks, then every box back to front. Sort with a topological order: box A paints before box B when A lies entirely behind B (`A.x1 <= B.x0` or `A.y1 <= B.y0`) and their screen outlines overlap. A plain `x + y` sort fails on long walls.
+- **Frame:** The canvas is 1000 wide and the plate is centred. The viewBox height follows the plate and its tallest box plus a 48px top margin.
+
+### Tags
+
+- Rooms and buildings are named by a horizontal tag: the name in the `node-name` role, 600, 12px, above a sublabel in the `sublabel` role at 8px, on an opaque `paper` backing with a `rule` hairline, 32px tall, width rounded up to a multiple of 4.
+- A room's tag sits on open floor inside the room. A building's tag sits on its roof. Tags paint after every box so walls never cut them.
+- Tags never overlap each other. Move a tag to open floor before you shorten its name.
+- One or two words per name. No leader lines and no numbered key.
+
+### Focal element
+
+One room or one building wears the accent. A focal room gets an `accent` tint on its floor and an accent tag; a focal building gets the accent face ramp and an accent tag. Furniture inside a focal room stays neutral, so the accent marks one thing.
+
+## Optional motion
+
+A site that is built in phases can reveal its buildings phase by phase with the pinned controller from `assets/template-motion.html` in `reveal` mode. Each building and its tag form one `data-motion-item` whose `data-step` is its phase, at most two per step. Buildings drop 16px into place and fade in, inside the 24px limit in `animation.md`.
+
+A floor plan can reveal by zone the same way. Give each zone's furniture a `step`, and the builder paints each phase as one contiguous group of boxes (it contracts a phase to one node in the depth sort, so a phase that would have to paint on both sides of a static wall fails the build) plus one group of that phase's room tags after every box. That is two motion items per phase, inside the limit of two per step. Walls and unphased rooms stay static. The static, no-JavaScript, reduced-motion, print, and export states show the finished site.
+
+## Metadata contract
+
+`scripts/verify-axonometric-plan.py` reprojects each element from what it declares:
+
+- The figure: one `<g data-axo-plan data-origin="ox oy">`.
+- The plate: one `<g data-plate data-rect="x0 y0 x1 y1 r" data-z="0" data-t="t">`.
+- Each box: a `<g data-box>` with `data-rect`, `data-z` (the plate top, or 8 above it for a tree canopy), `data-h`, `data-kind` (`wall`, `furniture`, `building`, `tree`, `rack`), and for a building `data-name`. Its first path is `data-role="silhouette"`.
+- Each room: a `<g data-room data-name data-rect>`.
+- Each tag: a `<g data-role="tag" data-name data-at="x y z">` with a backing `<rect>` and a `<text data-role="name">`. Its complete text, including inline `<tspan>` descendants, must match the tag's `data-name`. The point sits inside the room it names at the plate top, or on the building's roof.
+- The focal room or building carries `data-focal`.
+
+The silhouette verifier accepts signed decimal and scientific-notation coordinates within the existing absolute M/L/A/Z path contract. Every operand must be finite; projected vertices, corner radii, and arc flags are still checked. This does not add relative path commands.
+
+## Anti-patterns
+
+- Full-height walls that hide the rooms behind them.
+- Boxes that overlap on the plate, or a box hanging past the plate edge.
+- Painting by `x + y` alone, which draws long walls over the furniture in front of them.
+- Tags tilted onto the floor plane, tags that overlap, or a numbered key under the figure.
+- Accent on the focal room and on its furniture as well.
+- Gradients, shadows, or glow on the plate or the boxes.
+
+## Examples
+
+- `assets/example-axonometric-plan.html`: office floor, minimal light
+- `assets/example-axonometric-plan-dark.html`: office floor, minimal dark
+- `assets/example-axonometric-plan-full.html`: office floor, full editorial
+- `assets/example-axonometric-plan-campus.html`, `-dark`, `-full`: campus site plan with roads, trees, and buildings tagged by phase
+- `assets/example-axonometric-plan-coffee-shop.html`, `-dark`, `-full`: a coffee shop with an entrance and queue posts, an espresso bar, round tables, a kitchen, and a restroom
+- `assets/example-axonometric-plan-warehouse.html`, `-dark`, `-full`: a fulfillment floor with dock doors, tall storage racks, a pick zone, packing stations, and shipping docks
+- `assets/example-axonometric-plan-campus-animated.html`: the campus built phase by phase
+- `assets/example-axonometric-plan-coffee-shop-animated.html`, `assets/example-axonometric-plan-warehouse-animated.html`: each floor revealed zone by zone in three phases

package/.agents/skills/diagram-design/references/type-bar.md

@@ -0,0 +1,108 @@
+# Bar / Column Chart
+
+**Best for:** comparing discrete quantities across categories or time intervals — sprint velocity, monthly revenue, feature adoption, cohort counts. Use when each category has a single numeric value and the comparison between bars is the primary message — or, in the dumbbell variant below, exactly two values whose difference is the message.
+
+## Layout conventions
+
+- **Orientation:** Vertical bars (columns) are default. Horizontal bars are appropriate when category labels are long or you have more than 8 categories.
+- **Plot area margins:** left 80px (y-axis labels), bottom 60px (x-axis labels), top 40px, right 40px — inside a `0 0 1000 500` viewBox.
+- **Bar count cap:** 4–8 bars. More than 8 → group into periods or split into two charts.
+- **Bar width:** ≥ 50% of the column pitch (the gap should never exceed the bar). Typical: pitch=110px, bar=72px.
+- **Y-axis gridlines:** 4–6 horizontal lines at regular intervals. Stroke `ink @ 0.08` (very faint), 0.8px. X-axis baseline at `ink @ 0.25`, 1px.
+- **Y-axis labels:** right-aligned `arrow-label` role 8px in `muted`, at x=72 (8px left of the plot area).
+- **X-axis labels:** centered below each bar, `node-name` role 11px 600 for category names.
+- **Value labels:** `arrow-label` role 8px above each bar. Focal bar label in `accent`; others in `muted`.
+- **Focal bar:** 1 bar max in accent fill/stroke. All others in `muted @ 0.15` fill + `muted` stroke.
+- **Y-axis line:** thin vertical `<line>` at x=80 from y=40 to y=420.
+
+### Bar element pattern
+
+```svg
+<!-- Opaque paper mask prevents bleed from background -->
+<rect x="X" y="Y" width="W" height="H" fill="{paper}"/>
+<!-- Bar body -->
+<rect x="X" y="Y" width="W" height="H" fill="{muted @ 0.15}" stroke="{muted}" stroke-width="1"/>
+<!-- Value label above bar -->
+<text x="X+W/2" y="Y-8" fill="{muted}" font-size="8" font-family="{arrow-label}" text-anchor="middle">VALUE</text>
+```
+
+Focal bar: replace fill with `accent @ 0.12`, stroke with `accent`, label fill with `accent`.
+
+## Anti-patterns
+
+- More than 8 bars without grouping (illegible at normal scale).
+- Truncated y-axis (not starting at 0) — distorts the magnitude comparison.
+- Accent on more than 1 bar ("everything is important" = nothing is).
+- 3-D bar extrusion — no shadows, no depth.
+- Category labels rotated more than 45°; prefer short labels or horizontal chart instead.
+
+## Variants
+
+- **Grouped bars:** two bars per category, side by side. Use `accent` for the primary series and `series-1` for the secondary. Max 2 groups.
+- **Stacked bars:** segments stacked to total. Use `accent` for the focal segment; muted tints for others. Document the total at the top of each stack.
+- **Dumbbell:** one row per category, two dots on a single shared horizontal scale joined by a hairline. Use it for a two-state comparison where the *distance* between the ends is the message — before/after, two cohorts, target vs actual. Two series only; a third dot makes the connector meaningless and the figure is a dot plot.
+
+### Dumbbell layout
+
+- **Orientation:** horizontal only. Rows stack downward and the value axis runs left → right; a vertical dumbbell forces rotated category labels.
+- **Plot area:** left margin 200px for row labels — this replaces the 80px margin above — so `x` 200→960, `y` 40→420 inside `0 0 1000 500`. Row labels right-aligned at x=188, `node-name` role 11px 600 `ink` (the category-label size this type already uses).
+- **Rows:** the 4–8 bar count cap applies. Pitch and origin are fixed per row count so the block stays inside the plot band — a 64px pitch from y=96 overflows y=420 at seven rows:
+
+  | rows | pitch | first row `y` | last row `y` |
+  | --- | --- | --- | --- |
+  | 4 | 88 | 96 | 360 |
+  | 5 | 64 | 96 | 352 |
+  | 6 | 64 | 76 | 396 |
+  | 7 | 52 | 72 | 384 |
+  | 8 | 48 | 68 | 404 |
+
+- **Gridlines:** vertical at each tick, `ink @ 0.08` 0.8px, spanning y 56→408. At the domain floor the axis line replaces the gridline rather than doubling it: `ink @ 0.25` 1px, y 40→420.
+- **Tick labels:** centered under each gridline at y=440, `arrow-label` role 8px `muted`.
+- **Axis title:** the value axis carries the family's axis label — `eyebrow` role 7px `muted`, `letter-spacing="0.14em"`, centered at x=580, y=456, below the tick labels and clear of the legend rule. A horizontal axis takes the un-rotated form the scatter x-axis uses, not the `rotate(-90 24 230)` form the column charts apply to their y-axis. The category axis needs no title: the row labels name themselves.
+- **Dots:** r=6, positioned by value. Style by *series*: the reference end hollow (paper fill, `muted` stroke 1.5px), the focal end solid `accent` with a 1px `ink` stroke. Both marks therefore have a boundary above 3:1 even though the accent fill is not — see below. Fill weight, not hue, carries the pairing.
+- **Accent marks the series, not a focal row.** The solid dot repeats on every row — the one place this variant departs from the one-accent rule above, because the two ends must be told apart in each pair. Do not additionally accent a "most changed" row; the sort order already carries rank.
+- **Connector:** `ink @ 0.55` 1px (`rgba(45,49,66,0.55)` under the default light skin, the value `scripts/verify-dumbbell.py` checks), declared before both dots so the dots cap it. It is not the axis hairline: the connector is what says *these two dots are one row*, so it has to clear 3:1 (0.55 gives 3.19:1; the 0.25 the axis uses gives 1.60:1).
+- **Endpoint positions round, they never snap.** `x = 200 + (v − floor) ÷ (ceil − floor) × 760`, with `floor` and `ceil` set by the axis rule below, rounded to the nearest integer pixel — at most 0.5px, below one rendered pixel. Data coordinates are exempt from the 4px grid; snapping them moves the data.
+- **Value labels sit outside the pair, placed by geometry rather than by series.** A focal value *below* its reference reverses the dots, so derive `x_left = min(x_ref, x_focal)` and `x_right = max(x_ref, x_focal)`: left label right-anchored at `x_left − 12`, right label left-anchored at `x_right + 12`, both baseline `y + 4`, `arrow-label` role 8px `muted`, each still carrying its own series' value. Keying the offsets to start/end instead puts both labels *inside* the pair on every decreasing row.
+- **Floor exception.** A value sitting on the domain floor lands its label at x=188, right-anchored on baseline `y + 4` — exactly the category label's anchor and baseline, so the two texts overlap. When `x_left − 12 < 200`, centre that label above its dot at baseline `y − 10` instead.
+- **Legend:** two keys on the legend row — hollow dot, then solid dot, each with its series name. Circular keys centre at `cy=493`, the centre of the bar legend's 10px key rect at y=488, so both sit on the 497 text baseline. The row order goes in the legend or the source line, right-aligned on the same row.
+
+**Why the dots differ by fill, not hue.** The focal bar pattern above (12% tint + accent stroke) does not transfer to a 6px dot: the 12% tint across a 6px-radius disc contributes roughly 14 square pixels of colour, so the mark reads as its stroke alone and the pair separates by hue only. A solid accent dot against a hollow one separates by shape, survives greyscale and colour-vision deficiency, and leaves hue as redundant encoding.
+
+**Non-text contrast: the boundary carries it, not the fill.** The default accent clears the 3:1 WCAG 1.4.11 asks of a graphical object (4.71:1 on light paper, 5.21:1 on dark), but an onboarded accent may not, and shape redundancy does not waive that floor, because the reader still has to see the mark's edge and the line joining the pair. So neither is left to the accent: the solid endpoint takes a 1px `ink` stroke (11.82:1 against paper) and the connector takes 55% ink on light, 40% on dark (3.19:1 and 3.24:1). The hollow end already cleared it via its `muted` stroke at 6.11:1 light and 7.07:1 dark. `scripts/verify-dumbbell.py` asserts all four, so a later tint change cannot quietly drop one under the line. The hollow/solid shape difference stays as redundant encoding for greyscale and colour-vision deficiency — do not collapse the two dots to a single fill.
+
+**Minimum drawn gap — never clamp it.** Both dots carry `r="6"`; the hollow one paints out to 6.75 because its 1.5px stroke straddles the path, so the marks touch at 12.75px of centre separation and below about 16px the pair reads as one blob — on a 0–100 domain across 760px, a data gap of 2.1 units. Do **not** widen the separation to clear it: moving a dot off its scaled position breaks the shared-scale rule below. Keep the true positions and shrink both marks (r=4 touches at 8.75px), or print the two values and mark the row as too close to resolve.
+
+### Dumbbell element pattern
+
+```svg
+<!-- One row. Connector first so the dots cap it; labels outside the pair. -->
+<line x1="458" y1="96" x2="740" y2="96" stroke="{ink @ 0.55}" stroke-width="1"/>
+<circle cx="458" cy="96" r="6" fill="{paper}" stroke="{muted}" stroke-width="1.5"/>
+<circle cx="740" cy="96" r="6" fill="{accent}" stroke="{ink}" stroke-width="1"/>
+<text x="446" y="100" fill="{muted}" font-size="8" font-family="{arrow-label}" text-anchor="end">34</text>
+<text x="752" y="100" fill="{muted}" font-size="8" font-family="{arrow-label}">71</text>
+<text x="188" y="100" fill="{ink}" font-size="11" font-weight="600" font-family="{node-name}" text-anchor="end">Platform</text>
+```
+
+Values 34 and 71 on a 0–100 domain compute to 458.4 and 739.6, rounded to 458 and 740. Had this row fallen instead, the accent dot would sit on the left; the two anchors stay tied to left and right, and each label carries its own series' value.
+
+**Dark theme.** Dots and labels keep their roles and take the dark column of [`style-guide.md`](style-guide.md): hollow `paper` fill with a `muted` stroke, solid `accent` with an `ink` stroke, labels `muted`. **The hairline opacities change too:** gridlines `ink @ 0.08`, axis `ink @ 0.20`, connector `ink @ 0.40` (`rgba(245,245,245,0.40)` under the default dark skin). The connector stays heavier than the axis, for the same 3:1 reason. Resolve `ink` against the dark column, never the light one: in the default skin light `ink` *is* dark `paper`, so a connector, gridline, or axis carried over from light composites to exactly 1.000:1 and the gap encoding and the scale both vanish.
+
+### Dumbbell honesty rules
+
+- **Never truncate the value axis.** `floor` and `ceil` follow the data's range, never its observed extremes — taking `min` and `max` as the bounds *is* the truncation. With `lo` and `hi` the smallest and largest values, the four cases are exhaustive: `lo >= 0` anchors `floor = 0` and rounds `ceil` up past `hi` (including fractional data smaller than a fixed absolute tolerance); `hi <= 0` anchors `ceil = 0` and rounds `floor` down past `lo`; `lo < 0 < hi` brackets both sides, and zero then falls inside the plot — give it a line at its scaled position in the axis-line weight, since it is what every gap is read against. The fourth case is the one a sign-based rule drops: **when every value is zero**, `lo == hi == 0` would make `ceil - floor` zero and the position formula divide by zero, so take a finite fallback span (`floor = 0`, `ceil = 1` in the data's unit) and let every dot sit on the floor, which is the truth. Data that merely *touches* zero is covered by the first two cases, not a special one. `scripts/verify-dumbbell.py` implements this and proves finite coordinates for all four. The plot width is fixed, so narrowing the domain raises px-per-unit and draws every gap wider: across the same 760px, an 8-point gap is 61px on a 0–100 axis and 152px on a 40–80 axis. Ratios *between* rows survive the zoom — what inflates is each gap's size against the frame, which is how a reader judges whether a gap is large. The gap is the entire claim, which makes this the most common way a dumbbell lies.
+- **Both dots share one scale and one unit.** Label both endpoints with their real values. Labelling only the focal end asks the reader to take the geometry on trust.
+- **The connector is a gap, not a trajectory.** It encodes the distance between two values and nothing about what lies between them — no intermediate points, no rate, no guarantee the change was monotonic. Do not narrate it as movement.
+- **State the row order** in the legend or source line: by one endpoint, by signed change, by absolute change, or by an order the subject supplies (chronological, geographic, ordinal). "By gap" alone is ambiguous — say signed or absolute. What is not allowed is an unstated order, which reads as arbitrary.
+- **A row missing an endpoint is disclosed, never imputed and never silently dropped.** Removing incomplete categories without saying so changes the population being compared. Either draw the known end and name the missing value, or drop the row *and* record which rows went and why — a lone dot is otherwise indistinguishable from two coincident dots, which is to say from a genuine zero gap.
+
+Two of these rules live in a formula rather than a drawing, so they are executable: `scripts/verify-dumbbell.py` resolves the domain over every sign case and asserts finite coordinates and 3:1 marks, and `scripts/test-verify-dumbbell.py` exercises both polarities — including all-zero and zero-touching data, and the sub-3:1 treatments this replaced. The checker reads the tokens out of this file, so prose and thresholds cannot drift apart. A shipped dumbbell example would additionally owe a check of drawn positions against the values printed at them.
+
+## Examples
+
+- `assets/example-bar.html` — minimal light
+- `assets/example-bar-dark.html` — minimal dark
+- `assets/example-bar-full.html` — full editorial
+
+Dumbbell domain resolution retains finite bounds for representable subnormal and extreme values. If the next nice ladder step would overflow, the finite extreme is used; opposite-sign extreme domains are scaled without overflowing their span.