Plan the reference cards, task by task

[bjlittle]

The implementation plan for the reference quadrant's card landing page, specified in #327 (narrative spec §3.9, amendment of 2026-09-15). Plan only — the build follows as its own pull request, as #320 preceded #322.

The six tasks

#	Task	Holds it
1	The gate reads cards: CARD_SECTIONS, card_targets, and the API page derived from conf.py	five new unit tests, and a mutation proving the .. refusal
2	Rename the card classes to teph-card / teph-card-icon	the root page's text-column widths measured before and after
3	Draw the seven icons, derive the dark twins, correct the Tutorials halo	mechanical colour checks, XML parses, and a rendered sheet read by eye
4	The reference page	the gate, four mutations, a missing-icon build, renders in both themes, and a hover check with a positive control
5	The style guide's Landing Pages rule, and the signpost test's docstring	lint, the citation gate, the signpost test
6	Verify the branch, open the pull request, add the fragment	pixi run tests, lint, docs

A gate hole the plan closes

Planning the gate turned up that test_every_row_links_to_a_page_in_its_own_quadrant resolves ..: (DOCS / "reference" / "../howtos/units.rst").is_file() is True today, so an entry reaching into another section passes as a page of its own. Task 1 refuses .. and proves it by mutation.

How the plan's code was checked

Plans are verified by nothing once merged, so this one was run before it was proposed. Task 1's seven code blocks and Task 4's page were extracted from the plan file itself and applied to a throwaway worktree of main, then:

• Task 1 Step 2's red state — 5 failed exactly as stated: three NameErrors for card_targets, one for generated_pages, and ['cli', 'generated/api/index'] == ['cli'].
• Task 4 Step 2's red state — exactly the three [reference] failures stated.
• Green — 61 passed across the gate, tests/test_docs_whatsnew.py, and the signpost test.
• Mutations — Task 1's .. mutation and Task 4's (a)–(d) each failed the check the plan names.

It found two defects in the plan, both corrected before this commit. A line of Task 1's code was 92 characters, which ruff check rejects and ruff format rewrites — so an executor would have met a failing hook on the first commit. And mutation (b) was predicted to fail two checks; it fails three. After the corrections, ruff format changes nothing in the applied code and ruff check passes.

Not dry-run: Task 2's layout measurement, Task 3's drawings and render, and Task 4's build, renders and hover — each needs a docs build or a browser, and each is written with its own expected output and a control where the check could pass vacuously.

🤖 Generated with Claude Code

https://claude.ai/code/session_01C79QePZ862i61EJodupwVT

[read-the-docs-community]

Documentation build overview

📚 tephpy | 🛠️ Build #34569350 | 📁 Comparing b0e8de7 against latest (c985b14)

  🔍 Preview build  

10 files changed · ± 10 modified

± Modified

• sg_execution_times.html
• gallery/plot_hodograph.html
• gallery/plot_parcel_analysis.html
• gallery/plot_sounding.html
• gallery/plot_sounding_comparison.html
• gallery/plot_tephigram.html
• gallery/sg_execution_times.html
• reference/changelog.html
• reference/whatsnew/index.html
• reference/whatsnew/latest.html