docs: six schools behind a carousel, and a rule for when to stop widening

Three schools is not a neighbourhood in inner London, so the cap is six with
three visible and arrows for the rest.

Raising the cap exposes something the old cap hid. Tiers exist to reach a
usable set, and with six slots a naive loop would keep widening to fill them
— dragging in tier-3 schools ten miles away to sit beside three good matches
that had already earned the row. So tiers now stop relaxing once three are
found, and the remaining slots are filled only from the tiers already used.
Four tier-1 matches never open tier 2.

The carousel scrolls a list rather than swapping a view: all six cards are in
the initial HTML, so every link stays crawlable and the row still scrolls with
JavaScript off. The arrows' edge test carries an 8px tolerance because the
scroller's focus-ring padding is the first snap position — a row at rest
reports scrollLeft 2, and an exact test for 0 left the back arrow live and
pointing nowhere. Caught in the mockup.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/superpowers/specs/2026-09-21-similar-schools-nearby-design.md

@@ -11,9 +11,9 @@ after the results tables: *and what else is around here?*
 
 Today a school page links outward to its place pages through
 `components/school/NearbyPlaces.tsx` and nowhere else. It never links to another
-school. This section adds that edge — three nearby schools of the same phase and
-a comparable intake, each a crawlable link and each addable to the comparison
-basket in one click.
+school. This section adds that edge — up to six nearby schools of the same phase
+and a comparable intake, three at a time in a carousel, each a crawlable link and
+each addable to the comparison basket in one click.
 
 Mockup, with all three tier states live in both themes:
 <https://claude.ai/artifact/168KdUMcfkUeGWW2FGjuec>
@@ -77,8 +77,10 @@ school the frontend treats as special for benchmarking but the backend treats as
 mainstream for matching would be dropped from its own England comparison and
 then offered as a peer to a mainstream school on the next page along.
 
-**Three cards.** The target count is 3, which is what the grid is built for; 2
-is the minimum that renders at all.
+**Up to six cards, three visible.** Six is a cap, not a quota: the section shows
+every school that qualifies at the tiers it used, up to six. Three fit the row,
+and the rest are reached with the carousel arrows. Two is the minimum that
+renders at all.
 
 ### Soft preferences, relaxed in tiers
 
@@ -88,9 +90,27 @@ is the minimum that renders at all.
 | 2 | exact gender equality | 5 miles |
 | 3 | nothing beyond the hard filters | 10 miles |
 
-Candidates are taken from tier 1 first, ordered by distance; if fewer than three
-have been found the next tier tops up, and so on. A school already taken cannot
-be taken again by a later tier.
+**Tiers relax to reach a usable set, never to fill the last slots.**
+
+Work down the tiers until the schools found so far reach three. Call the tier
+that got there T. The section then shows up to six schools drawn from tiers 1
+to T, nearest first — and does not open tier T+1 merely because six slots are
+not yet full.
+
+Worked through:
+
+| Qualifying | T | Shown |
+|---|---|---|
+| 14 at tier 1 | 1 | the 6 nearest tier-1 schools |
+| 4 at tier 1 | 1 | all 4 — tier 2 is never opened |
+| 2 at tier 1, 7 more at tier 2 | 2 | the 6 nearest of those 9 |
+| 2 at tier 1, 1 at tier 2 | 2 | all 3 |
+| 2 across all three tiers | 3 | both, since 2 is the minimum |
+
+Without that stopping rule, a cap of six would reliably drag in tier-3 schools
+ten miles away to fill a row that three good matches had already earned. The old
+cap of three hid this; six exposes it, which is why the rule is stated rather
+than left to the loop.
 
 **Faith relaxes before gender.** A faith mismatch changes the character of a
 school; a gender mismatch can mean the school is not available to the reader's
@@ -105,12 +125,11 @@ the promise in the heading and a reader scanning the row reads the first card as
 the closest. A tier-2 school at 0.4 miles therefore appears above a tier-1
 school at 2.9 miles, and the chips explain the difference in match quality.
 
-**More than three qualifying schools are dropped, not paginated.** In a dense
-urban area dozens of schools clear tier 1, and the section shows the three
-nearest of them. There is no "show more" and no count of what was left out,
-because `NearbyPlaces` sits directly beneath and already answers "more schools
-near here" by linking to the place pages — which are the pages built for
-browsing a full list, and which the school page exists to feed.
+**Past the sixth school, the rest are dropped without a count.** In inner
+London dozens clear tier 1, and a parent there will notice three is not the
+neighbourhood — hence six. Beyond that the section does not try to be the list:
+`NearbyPlaces` sits directly beneath and already leads to the place pages, which
+are built for browsing a full set and which the school page exists to feed.
 
 **Fewer than two results renders nothing.** Not an empty state, not a single
 lonely card, not padding with schools that failed the hard filters. The section
@@ -157,7 +176,7 @@ lede may claim a similar intake, and whether a chip renders as a brand-tinted
 fill or a muted outline — and inferring it from chip count would couple those
 decisions to the copy.
 
-Three rows of roughly 130 bytes each. It rides in the existing detail payload
+Up to six rows of roughly 130 bytes each. It rides in the existing detail payload
 rather than a new endpoint because the page already makes exactly one server
 fetch for its data, and `/school/[slug]` regenerates at most weekly
 (`revalidate = 604800`), so the per-request cost is paid once per school per
@@ -180,14 +199,50 @@ the shared `Section` shell from `sectionShared.tsx`. It renders the heading,
 the lede, the card grid, the footer CTA and one caption line. Every
 card's title is an `<a>` to the school's canonical slug URL via `schoolUrl()`.
 
-`components/school/AddToCompareButton.tsx` — the only `'use client'` file this
-adds, and the only client JavaScript in the section. It calls `addSchool` from
+`components/school/AddToCompareButton.tsx` — calls `addSchool` from
 `ComparisonProvider` and reports the selection with a `from: 'similar_schools'`
 attribution, mirroring `addSchoolFromSearch` in `HomeView.tsx:442`.
 
+`components/school/SimilarSchoolsCarousel.tsx` — the scroller and its arrows. It
+takes the server-rendered cards as `children` and the server-rendered heading and
+lede as a `header` prop, so those stay server components while the client
+component owns only the ref, the scroll handler and the arrows' disabled state.
+
 The split matters: the links — the part with SEO value and the part that must
 work without JavaScript — are server-rendered into the initial HTML, and only
-the basket interaction is hydrated.
+the basket interaction and the arrows are hydrated.
+
+### The carousel
+
+**Every card is in the initial HTML.** The arrows scroll a list; they never swap
+a view. Six `<a>` elements are in the markup whether or not anything is
+hydrated, which is the whole reason the section exists — a paginated widget that
+mounts cards on click would put four of the six links beyond a crawler and
+beyond a reader with no JavaScript.
+
+So the scroller is a plain overflowing `<ul>` with `scroll-snap-type: x
+mandatory`, and the arrows call `scrollBy` on it. With no JavaScript it
+degrades to a horizontally scrollable row that still works by touch and by
+trackpad. Three cards are visible at desktop width, two below 820px, and one
+below 560px, where touch swiping makes the arrows redundant but harmless.
+
+**Arrows appear only when there is somewhere to go** — that is, only when more
+than three schools were found. Each disables itself at its own end of the
+travel.
+
+**The edge test needs a tolerance, and this is not fussiness.** The scroller
+carries 2px of padding so focus rings are not clipped, and scroll-snap treats
+that padding as the first card's snap position: a scroller sitting at its start
+reports `scrollLeft` of 2, not 0. Sub-pixel rounding moves it again at other
+zoom levels. Testing `scrollLeft === 0` therefore leaves the back arrow live and
+pointing nowhere on first paint — confirmed in the mockup before it was fixed.
+Both ends compare against an 8px tolerance.
+
+**Selecting a school must not move the row.** Adding to the basket re-renders
+the footer; the scroll offset lives in the DOM rather than in React state, so
+the carousel must not remount or reset on that render. A reader who ticks the
+fifth school and is thrown back to the first has been punished for using the
+feature.
 
 ### Placement and navigation
 
@@ -215,9 +270,11 @@ shows.
 
 ## Copy, and what the section is allowed to claim
 
-**The lede tracks the tier.** At tiers 1–2 it reads "Other primary schools near
-X, with a similar intake." At tier 3 it drops "with a similar intake", because
-at tier 3 that is not what was matched.
+**The lede tracks the deepest tier shown.** At tiers 1–2 it reads "Other primary
+schools near X, with a similar intake." Where any card came from tier 3 it drops
+"with a similar intake", because for at least one of the cards that is not what
+was matched. Six cards make this more likely to fire than three did, which is
+correct: a wider net is exactly when the claim needs dropping.
 
 **Chips state only what is shared.** A tier-2 card carries fewer chips rather
 than a chip it has not earned; a tier-3 card falls back to the plain phase name,
@@ -270,6 +327,8 @@ synthetic frame rather than live marts:
 - a Boys school never returns a Girls school; Mixed matches both
 - closed schools and schools without coordinates are never returned
 - tier relaxation fills in order, and a school taken at tier 1 is not repeated
+- tiers stop relaxing once three are found: four tier-1 matches never open tier 2
+- more than six qualifying schools returns the six nearest
 - an all-through school is offered on both phase sides
 - fewer than two qualifying schools returns `[]`
 - distances match a hand-computed haversine for a known pair
@@ -280,11 +339,21 @@ synthetic frame rather than live marts:
 - the lede drops "with a similar intake" when any card is tier 3
 - a null metric renders "Not published"
 - the nav item appears only alongside the section
+- every card is in the DOM, including the ones scrolled out of view
+- arrows render only when more than three schools were found
+
+jsdom has no layout, so `scrollWidth` and `clientWidth` are both 0 there and the
+arrows' disabled state cannot be meaningfully asserted in Jest. That behaviour is
+covered in the journey instead, against a real engine, rather than by a unit test
+that would pass on a measurement that does not exist.
 
 **E2E**, added to the existing journeys in `e2e/tests` in the same PR, per the
 repository's rule on user-facing behaviour:
 
 - the section renders on a known staging URN, with resolving links
+- where arrows are present, the back arrow starts disabled and the forward arrow
+  moves the row
+- selecting a school does not reset the scroll position
 - add-to-compare reaches `/compare` with the expected `urns`
 
 The E2E gate runs after merge on this project, so these journeys are not
@@ -294,6 +363,9 @@ journeys are confirmed on the post-merge staging run.
 ## Out of scope
 
 - A map of the nearby schools. The section is a list; the page already has a map.
+- Autoplay, dots, or an infinite loop on the carousel. It is a short list a
+  reader scans deliberately, not a banner competing for attention, and a row
+  that moves on its own is a row that moves while someone is reading it.
 - Statistical neighbours on deprivation, size or cohort profile. If the tiers
   prove too coarse, that is the trigger to move this computation into a dbt mart
   — `_similar_schools_payload` is a deliberate seam for exactly that swap.