🧭 Roadmap: backlog triage, modernization, card syntax redesign & new components

[chrisjsewell]

Context

This is a tracking issue consolidating a full triage of the open backlog (56 issues, 14 PRs as of 2026-07), a code-level review of the extension, and a forward plan — to agree direction before implementation starts.

Groundwork already landed: v0.7.0 (Python 3.11–3.14, Sphinx 7–9) via #250/#255/#256, AGENTS.md (#251, #254), Sass @import→@use migration (#259), tab-set crash fix (#258).

Implementation briefs: each work item below has a detailed, self-contained brief (one PR each, with file:line references, steps, tests, and acceptance criteria) on the claude/sphinx-design-modernize-orr9g0 branch under briefs/, including an execution plan with parallelization tracks and a file-conflict matrix.

---

1. Open PR triage

PR	Verdict	Notes
#205	✅ merged via #266 (81dbab8)	Verified: OCTICON_CSS in icons.py was dead code. Original fork branch couldn't re-trigger required checks (2024 runs too old to re-run), so re-created with authorship preserved
#262	✅ merged (03ccc10)	pre-commit autoupdate (ruff 0.15, mypy 2.1); [dependency-groups] pins synced in #267
#264	✅ merged via #270 (834eebe)	Button i18n fix, carried with authorship credit + crash hardening and i18n test coverage. Closed #96, #44, #263
#230	🔨 being carried	Focus rings (a11y) — being ported onto the post-@use SCSS with author credit, as part of the a11y pass (brief 10, in progress)
#158	🔍 review & land	Button docs clarification; needs rebase
#241	✅ closed	Superseded by the merged #276 (static-asset rework), which includes its HTML-only gating; credited in-thread
#237	✅ closed	.readthedocs.yml on main already has sphinx.configuration
#220	✅ closed	pyproject already allows myst-parser>=4,<6
#203	✅ closed	Superseded by the merged #272 (codecov-action v5 + fixing the dead upload condition)
#175	✅ closed	Superseded by #264/#270
#221 #225 #226 #227	✅ closed	Superseded by the merged #267 (pins refreshed + dependabot groups)

2. Open issue triage (by cluster)

i18n — ✅ buttons fixed

#44, #96, #263 closed by #270. Remaining: #234 (table content inside tabs missing from .pot) — separate extraction bug to investigate. Known gap documented in #270: button-ref text is absent from .pot extraction (std-domain xref resolution flattens explicit-title content before the gettext builder extracts); translation itself works.

Static files / builder lifecycle — ✅ fixed

#200, #235 closed by #276: static assets are now served via Sphinx's standard html_static_path mechanism (HTML-format builders only), nothing is written into outdir outside Sphinx's own copying, and the Sphinx floor moved to ≥7.2.

LaTeX output

#107 (dropdown → \subsubsection*), #218 (same for tabs), #179 (grids with images), #242 (fontawesome5 package clash — fix in progress via the FontAwesome modernization). The extension has essentially no LaTeX visitors; everything degrades via sphinxuseclass. Plan: a dedicated LaTeX pass — dropdown/tab-item → boxed environments (e.g. sphinxShadowBox-style), grids → sequential blocks, and conditional fontawesome5 loading.

Tabs

• Support sticky tab selection #103: ✨ NEW: sync tabs by URL query parameters #196 added persistence, but via sessionStorage (despite the JS header comment claiming localStorage) — so selection does not survive a new browsing session. Fix in progress: switch to localStorage + a configurable storage-key prefix
• Open tab when its :name: is used in URL #239 open tab when its anchor is in the URL fragment (in progress, same JS pass)
• Include radio/label ID as part of tab-content div #30 ARIA gap — aria-controls wiring in progress, folded into the a11y pass with Restore focus rings #230
• Click+drag on tab causes synced tabs to go out of sync #46 (click+drag desync — root cause: sync hangs off label.onclick instead of the radio's change event; fix in progress), Scope of tabs is visually unclear #173 (tab scope CSS), Vertically-oriented tabs #219 (vertical orientation option), Tab-item is modifying .html files #238 (raw HTML inside tab-item)

Cards / grids

• comments inside a grid generate confusing warnings #86 ✅ closed by 🐛 Ignore comments/targets in component child validation #271 (+ anchor follow-up 🐛 Keep target anchors rendered in tab-set and tab-set-code #275)
• Multi-line content in dropdown has extra spacing on first line #40 ✅ fixed in 🐛 Stamp sd-card-text on direct paragraphs only, never replace classes #278: the dropdown transform no longer wipes user paragraph classes (inverted conditional), and sd-card-text is stamped on direct child paragraphs only (a CSS-child-selector alternative is noted as a follow-up for the card redesign)
• Bugs: Adding padding to a grid-card-item adds it to the sd-col div and not to sd-card div #26 (verified: grid-item-card applies :padding: to the outer sd-col div, and the plain card directive has no padding option at all), docutils hyperlink targets don't work for clickable cards #164 (docutils hyperlink targets as card links). Also: the card :link: option shares :ref: does not resolve autosectionlabel #110's whitespace-stripping bug (directives.uri in the option spec) — targeted follow-up in progress
• Enhancements worth accepting: Option to open clickable cards in new tab #170 (:link-newtab:), [Feature request] Add class-link option for cards #261 (:class-link:), CSS Class for Thumbnails/Images with fixed Height #152 (fixed-height image class), Add img-left and img-right to grid-item-card #211 (img-left/right), After screen resize or on mobile card-carousel looks bad #133/Card Carousel with Controls/Indicators #181 (carousel options/controls), ENH: Add download as clickable ref type for Cards #56, Changing colors on cards #157

Icons

• toctree skips an entry if its title begins with an inline icon directive #99/icons not shown correctly in rst toctree #117 ✅ fixed/documented in 🐛 Stop icon roles leaking SVG into toc labels and search #279: icon roles no longer leak SVG into toctree labels or the search index (new sd_icon node with empty astext()); icons not shown correctly in rst toctree #117 documented as a core-Sphinx limitation (toctree entry titles are plain text). Bonus: article-info icons regained their silently-dropped sd-pr-2 spacing class
• Remaining: Material icons are padded slightly below by default #100 (material icon baseline), FontAwesome import interfering with Pro License #174 (bundled FontAwesome conflicts with FA Pro → config in progress), Option for fontawesome icons instead of octicon for dropdowns #233 (FA icons for dropdown markers)

Refs / links

• :ref: does not resolve autosectionlabel #110, Nested parse broken for button-ref but not button-link #228 ✅ fixed in 🐛 Fix button-ref target whitespace and nested content #281: button-ref no longer strips whitespace from targets (multi-word autosectionlabel labels resolve; ref-type: ref lowercases for :ref: parity), and rich/nested button content survives resolution instead of being flattened. (Card :link: follow-up for the same root cause in progress — see cards cluster)
• Remaining: Can't use anything for a button-link URL other than a string? #222 (URL from substitution)

Docs-only quick wins — ✅ done

#172, #122, #184, #247 closed by #273. Remaining: #52 (indent MyST examples).

Close / answer — ✅ done

#6, #77, #80, #177, #165, #182 all closed with explanations; #260 ✅ done in #277 (public sphinx_design.testing module).

3. Modernization plan

1. Rework static-asset handling ✅ done in ♻️ Serve static assets via html_static_path #276 — update_css_js/update_css_links replaced by a single builder-inited hook registering sphinx_design/static/ on html_static_path + add_css_file/add_js_file (HTML-format builders only, served filenames unchanged); Sphinx floor bumped to ≥7.2 (native ?v= checksums), md5 branch and test-suite compat shims deleted.
2. CI coverage is silently dead ✅ fixed in 🧪 Fix dead codecov upload, modernize CI actions #272 (condition, codecov-action v5, action bumps, concurrency group). Follow-up idea from Phase 1 friction: run the no-myst tox env in CI and widen tox -e mypy to cover tests/, so all checker environments agree (several Phase 1 failures were only visible in envs CI doesn't run). Phase 2 addendum: the ~=7.0 CI rail resolves to 7.4.x, so the declared 7.2 floor is never CI-tested — three floor-only bugs were caught in local pinned-version runs; consider adding a sphinx==7.2.* matrix entry.
3. PyPI Trusted Publishing (OIDC) — replace the long-lived PYPI_KEY secret + flit publish with pypa/gh-action-pypi-publish under a pypi environment; attestations for free. Deferred for now — needs a one-time publisher registration on PyPI; revisit before the next release.
4. Drop the _compat.findall shim ✅ done in ♻️ Serve static assets via html_static_path #276 — all call sites now use node.findall(...) directly (note for downstream: the private helper is gone).
5. Packaging polish: bump Development Status :: 4 - Beta → 5 - Production/Stable; adopt PEP 639 license = "MIT"; refresh theme extras pins (done in ⬆️ Refresh dev/docs pins, group dependabot updates #267); plan a 1.0 once i18n + static-asset fixes land.
6. Frontend hygiene: bump the sass pin (package.json/pre-commit still pin 1.35.2 from 2021); a11y pass (in progress: Restore focus rings #230 + Include radio/label ID as part of tab-content div #30); FA import opt-out (in progress: FontAwesome import interfering with Pro License #174).
7. LaTeX degradation pass (see cluster above) — largest coherent pain cluster after i18n.
8. Testing gaps: no i18n/gettext tests (✅ added in 🐛 Keep buttons intact under gettext translation #270); JS behaviour (tab sync) still entirely untested — doctree regressions can't catch Click+drag on tab causes synced tabs to go out of sync #46/Tab-item is modifying .html files #238-class bugs, and the 🐛 Ignore comments/targets in component child validation #271 anchor bugs (fixed in 🐛 Keep target anchors rendered in tab-set and tab-set-code #275) were likewise invisible to doctree assertions. Add a minimal Playwright smoke test.
9. Declarative configuration ✅ landed in ♻️ Central declarative SdConfig dataclass #274: all sd_* options on a typed dataclass (modelled on myst-parser's MdParserConfig + validators), every field TOML-representable. New options (tabs storage prefix, FontAwesome source/LaTeX) are being added as fields.

4. Card directive: replace bespoke header/footer syntax with a pure parse

Today card (and grid-item-card via CardDirective.create_card) pre-processes its raw source lines: split_content regex-scans for the first ^{3,} line (header separator) and the last \+{3,} line (footer separator), slices the StringList into three chunks, and nested-parses each separately.

Problems with this:

• False positives in nested content — a +++ or ^^^ line inside a nested code-block/literal block (e.g. Jupytext cell markers, rST section underlines in examples) is treated as a separator. The "last occurrence" heuristic for footers mitigates but doesn't solve.
• Approximate source mapping — there's a literal TODO set proper lines in _create_component; error locations inside cards are off.
• Invisible to tooling — the separators aren't part of any parse; formatters, MyST linters/LSPs, and other renderers (including any future non-Python MyST implementation) can't understand card structure.
• add_card_child_classes then stamps sd-card-text onto all descendant paragraphs (✅ fixed in 🐛 Stamp sd-card-text on direct paragraphs only, never replace classes #278 — now direct children only).

Proposal: card-header / card-footer sub-directives + doctree hoisting

Adopt the same structural pattern as tab-set/tab-item:

• Register card-header and card-footer directives. Content of card is parsed with one ordinary nested_parse (pure rST/MyST — no raw-text surgery).
• After parsing, the card directive hoists any card-header/card-footer component children into their slots and wraps the remaining siblings in card-body. Pure doctree manipulation, correct line attribution for free.
• card-header/card-footer used outside a card warn, mirroring tab-item.

.. card:: Card title

   .. card-header::

      Header content

   Body content

   .. card-footer::

      Footer content

Ergonomics notes:

• Slightly more verbose than ^^^/+++, but explicit, unambiguous, and identical in rST and MyST (MyST users already nest fences for tab-set/tab-item).
• Optionally also add :header:/:footer: options accepting inline markup for the very common one-liner case — to decide.

Alternative considered (rejected): transition-based splitting

Parse the content and split on nodes.transition (the old sphinx-panels approach). Rejected because the two parsers disagree: ^^^^ (4+) parses as a transition in rST but +++ does not, while MyST tokenizes +++ as a block-break — so no single separator has consistent semantics across parsers, and transitions inside genuine card body content would be misinterpreted.

Deprecation pathway (not back-breaking)

1. vNext (0.8): both syntaxes work; docs/examples switch to the new sub-directives; ^^^/+++ remain the default-on legacy path.
2. Add config sd_card_legacy_separators (default True) and emit a once-per-document deprecation notice (subtype design.card_legacy, suppressible) when separators are used.
3. Publish a short migration guide (precedent: the sphinx-panels migration docs); the rewrite is mechanical enough for a python -m sphinx_design.migrate helper if wanted.
4. 1.0/2.0: flip the default off; remove one major later.

5. New components & directive improvements

New directives that fit the repo's CSS-first / minimal-JS philosophy:

• accordion — a group of dropdowns where opening one closes the others. Dropdowns already render as <details>/<summary>, and native HTML <details name="..."> gives exclusive-open behaviour with zero JS (Baseline 2024). Implementation is essentially a container directive assigning a shared name + CSS. Bootstrap-parity component that gets asked for regularly.
• steps / step — numbered procedure steps (install guides, tutorials), CSS counters only. One of the most-copied custom CSS snippets across Sphinx sites.
• aside (Aside boxes #97) — floated call-out box with text wrap-around; CSS-only, long-standing request.
• tooltip — either a role or a :tooltip: option on badges/buttons (Add tooltip for badges #81) in progress: ; tooltip suffix syntax on badge roles.

Improvements to existing components (no new directives): vertical tab orientation (#219), carousel controls via CSS scroll-snap (#181, #133), card img-left/right (#211), dropdown FA icon option (#233).

Considered and decided out of scope: menu-style dropdowns / nav widgets (#165, closed) — interactive navigation rather than content components; better served by themes.

6. Suggested sequencing

• Phase 0 — PR hygiene ✅ complete ([pre-commit.ci] pre-commit autoupdate #262, ♻️ Remove unused constants #266, ⬆️ Refresh dev/docs pins, group dependabot updates #267 merged; 8 PRs closed; issue sweep done)
• Phase 1 — bugs & infra ✅ complete (6 landed; trusted publishing consciously deferred):
  • declarative config foundation (♻️ Central declarative SdConfig dataclass #274, 70cf79b)
  • button i18n: make button text translatable #264 carried by 🐛 Keep buttons intact under gettext translation #270 (834eebe) — closed internationalization is not working for buttons #96, i18n: translating button-ref label results in loss of CSS classes #44, Buttons cannot be rendered correctly if the content is translated by Gettext #263
  • CI codecov fix + action modernization (🧪 Fix dead codecov upload, modernize CI actions #272, 5f41b8e)
  • quick win comments inside a grid generate confusing warnings #86 (🐛 Ignore comments/targets in component child validation #271, aa59d89) + anchor follow-up (🐛 Keep target anchors rendered in tab-set and tab-set-code #275, 9f62c7d — a retrospective review caught two rendered-anchor bugs in 🐛 Ignore comments/targets in component child validation #271)
  • docs quick wins Documentation for the sizing CSS classes is incorrect #172/better way to set img src file for an avatar? #122/Documentation and examples #184/Document how to include query arguments when linking to tabs #247 (📚 Fix sizing classes, grid rows, tab links, MyST prereqs #273, ce1e0a9)
  • static-asset rework (♻️ Serve static assets via html_static_path #276, 1bfd79d) — closed _sphinx_design_static directory in _build/latex #200/Missing build directory leads to builder-inited error #235, superseded Limit copying _sphinx_design_static to HTML based builders #241; Sphinx floor now ≥7.2
  • PyPI trusted publishing (brief 06) — deferred: needs a one-time publisher registration on PyPI; revisit before the next release
• Phase 2 — a11y & frontend (in progress):
  • public testing module (✨ Add public sphinx_design.testing helpers #277) — closed Provide normalize_doctree_xml via sphinx_design.testing #260
  • card/dropdown sd-card-text fixes (🐛 Stamp sd-card-text on direct paragraphs only, never replace classes #278) — closed Multi-line content in dropdown has extra spacing on first line #40
  • icon toc/search leak fix (🐛 Stop icon roles leaking SVG into toc labels and search #279) — closed toctree skips an entry if its title begins with an inline icon directive #99, icons not shown correctly in rst toctree #117
  • button-ref target + rich-content fixes (🐛 Fix button-ref target whitespace and nested content #281) — closed :ref: does not resolve autosectionlabel #110, Nested parse broken for button-ref but not button-link #228
  • in progress: a11y pass (carries Restore focus rings #230, wires Include radio/label ID as part of tab-content div #30), tabs JS (Click+drag on tab causes synced tabs to go out of sync #46/Open tab when its :name: is used in URL #239/Support sticky tab selection #103), FontAwesome modernization (FontAwesome import interfering with Pro License #174/Latex build broken in Sphinx 8 #242), badge tooltips (Add tooltip for badges #81), card :link: whitespace follow-up
  • remaining: rebase/land Clarify the meaning of button in the docs #158; sass pin bump
• Phase 3 — card redesign & new components: §4 pure-parse cards with deprecation path; accordion; steps; aside; card options (Option to open clickable cards in new tab #170/[Feature request] Add class-link option for cards #261/CSS Class for Thumbnails/Images with fixed Height #152/Adding padding to a grid-card-item adds it to the sd-col div and not to sd-card div #26)
• Phase 4 — LaTeX pass & JS testing: make latex translates the dropdown title into a \subsubsection* #107/Tabs items shouldn't be rendered as they are in LaTeX output #218/Sphinx Grids with Image not compiling to Latex properly #179; Playwright harness
• Phase 5 — 1.0: Dev Status stable, PEP 639, backlog re-sweep

Feedback welcome on any of the verdicts above — in particular §4 (card syntax) and which of §5 to green-light.

[chrisjsewell]

Phase 0 progress (checklist in the description updated):

• Merged: [pre-commit.ci] pre-commit autoupdate #262 (pre-commit autoupdate)
• Closed as obsolete/superseded, each with an explanatory comment: ⬆️ Bump codecov/codecov-action from 3 to 4 #203, ⬆️ Update myst-parser requirement from <4,>=2 to >=2,<5 #220, ⬆️ Update furo requirement from ~=2024.7.18 to >=2024.7.18,<2024.9.0 #221, ⬆️ Update pydata-sphinx-theme requirement from ~=0.15.2 to >=0.15.2,<0.17.0 #225, ⬆️ Update pre-commit requirement from <4,>=3 to >=3,<5 #226, ⬆️ Update sphinx-rtd-theme requirement from ~=2.0 to >=2,<4 #227 (dependabot), Fix missing required RTD configuration key #237, 🐛 FIX: i18n of buttons #175 (with thanks to the authors)
• refactor: Remove unused constants #205: the fork branch couldn't re-trigger the now-required status checks (2024 runs are too old to re-run), so the change is carried by ♻️ Remove unused constants #266 with @ftnext's commit authorship preserved — merging once CI is green

Remaining in Phase 0: the dev-pins refresh PR (+ dependabot groups, + syncing the [dependency-groups] mypy/ruff pins) and the issue close/answer sweep.

---

Generated by Claude Code