Change Log

0.8.0 - 2026-11-10

New components (accordion, aside, steps, vertical tab sets, and explicit card header and footer directives), links that open in a new tab, badge tooltips, a plain-CSS build with no Sass, tab selections that persist across pages and visits, accessibility fixes, FontAwesome v6 support, and Octicons v19.42.0. Sphinx 7.2 or later is now required.

Upgrade notes

  • Sphinx >=7.2 is required (Sphinx 7.0 and 7.1 are no longer supported); Python stays at >=3.11 (PR #276).

  • The ^^^ and +++ card separators are deprecated and warn by default. They still render as before, but the first card in a document that uses them emits one design.card_legacy warning, so a build run with -W fails until you do one of two things:

    • move the header and footer into the new card-header and card-footer directives (or the one-line :header: and :footer: options), which need sphinx-design 0.8.0 or later; or

    • add "design.card_legacy" to suppress_warnings in your conf.py.

    Once every card is migrated, set sd_card_legacy_separators = False to stop scanning for the separators. The plan is to turn the separators off by default in 1.0 and remove them in 2.0; the cards page has a migration table (PR #294).

  • Tab selections persist in localStorage instead of sessionStorage, so a chosen tab is remembered across browsing sessions as well as across pages. The storage key prefix is set by the new sd_tabs_storage_prefix option; set it to an empty string to disable persistence (PR #284, #103).

  • Static assets are served through Sphinx’s html_static_path, only for HTML-format builders. A _sphinx_design_static directory left in an existing build directory by an earlier version is unused and can be deleted (PR #276).

  • The stylesheet is plain CSS, generated without Sass. The --sd-color-*-highlight hover and focus shades are now derived at runtime with color-mix() (behind the old value as a static fallback), so overriding a --sd-color-* variable now also changes its hover shade (PR #290).

  • The private sphinx_design._compat.findall helper is removed; call node.findall(...) directly (PR #276). The private CardDirective._create_component method is renamed _create_slot; the old name stays as an alias for one release (PR #294).

  • sd-card-text is added only to the direct child paragraphs of a card or dropdown body, and is added to a paragraph’s classes instead of replacing them; paragraphs nested deeper (in admonitions, lists, nested tab sets) no longer get it (PR #278).

New

  • ✨ accordion directive: groups dropdowns so that opening one closes the others, using the browser’s native <details name> behaviour with no JavaScript; :flush: renders it edge to edge by @chrisjsewell in PR #291

  • ✨ aside directive: a call-out box floated beside the body text (:align:, :width:), rendered as a semantic <aside> in HTML and a plain titled container elsewhere by @chrisjsewell in PR #292 (#97)

  • ✨ steps and step directives for numbered procedures, with CSS-only number markers on an ordered list, :start: and :color: options by @chrisjsewell in PR #293

  • ✨ card-header and card-footer directives, and :header: and :footer: options, for card and grid-item-card headers and footers: the card body is parsed once as ordinary content, and errors in a header or footer report their own line (see the upgrade notes for the legacy separators) by @chrisjsewell in PR #294

  • ✨ Vertical tab sets: tab-set and tab-set-code take :orientation: vertical, which stacks the labels in a rail beside the selected panel from the md breakpoint up by @kdeldycke in PR #304 (#219)

  • ✨ Open links in a new tab: the link-new-tab flag on card and grid-item-card, and new-tab on button-link and button-ref, for URLs and internal references alike by @dipinknair in PR #298 (#170)

  • ✨ Badge tooltips: badge roles accept a trailing ; tooltip suffix, rendered as a native HTML title; for link and ref badges it applies after the explicit text <target> form, and \; escapes a literal semicolon by @chrisjsewell in PR #286 (#81)

  • ✨ Every badge role (plain, line, link and ref, in every colour) accepts a tooltip role option, so a reStructuredText custom role (.. role:: bdg-stable(bdg-success) with :tooltip:) or an extension can preset a tooltip; a ; tooltip suffix still takes precedence by @chrisjsewell in PR #316

  • ✨ A line block in button-link or button-ref text renders as separate lines (<br /> in HTML, \newline{} in LaTeX), each line its own gettext message by @Cherith1222 in PR #308 and @chrisjsewell in PR #315 (#156)

  • ✨ A URL fragment that targets a tab (e.g. page.html#tab-name), or an element inside a tab panel, opens that tab, on load and on hashchange by @chrisjsewell in PR #284 (#239)

  • ✨ FontAwesome v6 roles (fa-solid, fa-brands, fa-regular), and CSS loading via the new sd_fontawesome_source and sd_fontawesome_cdn_url options (the supported path for FontAwesome Pro kits) by @chrisjsewell in PR #285 (#174)

  • ✨ sd_fontawesome_version makes icon role names version-agnostic: any spelling (fas, fa-solid, …) can emit the FontAwesome "4", "5" or "6" class scheme, so upgrading FontAwesome is a one-line conf.py change; the default "as-named" keeps emitting the role name as before by @chrisjsewell in PR #288 (#174)

  • ✨ sphinx_design.testing module with the normalize_doctree_xml helper, for downstream extensions’ doctree regression tests by @chrisjsewell in PR #277 (#260)

Improve

  • 👌 Keyboard focus rings restored on tab labels, dropdown summaries, buttons and stretched-link cards (with :focus-visible, so they do not show on mouse click) by @gabalafou in PR #230, carried in PR #283

  • 👌 Each tab label carries an aria-controls attribute naming its panel (this is not the full WAI-ARIA tabs pattern) by @chrisjsewell in PR #283 (#30)

  • 👌 The tab hover colour is the active colour at 80% opacity, so a hovered tab no longer looks selected by @dchaudhari7177 in PR #303 (#301)

  • 👌 sd_fontawesome_latex also accepts "fontawesome5" (loading fontawesome5.sty and emitting \faIcon{...}), resolving package clashes with themes that load it; True and False work as before by @chrisjsewell in PR #285 (#242)

  • 👌 All sd_* settings are declared in one typed configuration, and an invalid value warns (design.config) and falls back to the default by @chrisjsewell in PR #274

  • 👌 Plain-CSS stylesheet generated by a dependency-free Python tool (no Sass or Node), with the dead vendor-prefixed declarations removed by @chrisjsewell in PR #290

Fix

  • 🐛 Synced tabs stay in sync when activated by keyboard or click-and-drag by @chrisjsewell in PR #284 (#46)

  • 🐛 A tab-set with children other than tab-item warns for each one and renders the valid tabs, instead of crashing with a ValueError by @chrisjsewell in PR #258 (#243)

  • 🐛 Comments, hyperlink targets and system messages inside grid, card-carousel, tab-set and tab-set-code no longer warn as invalid children, and targets are kept so references to them resolve, including anchors to targets inside tabs by @chrisjsewell in PR #271 and PR #275 (#86)

  • 🐛 Buttons survive gettext translation: translated button-link and button-ref keep their styling and links by @sneakers-the-rat in PR #264, carried in PR #270 (#96, #44, #263)

  • 🐛 button-ref keeps whitespace in reference targets (so multi-word labels, such as those from autosectionlabel, resolve; ref targets are lowercased like the :ref: role), and renders nested inline content like button-link by @chrisjsewell in PR #281 (#110, #228)

  • 🐛 The card and grid-item-card :link: option keeps whitespace in reference targets, and lowercases ref targets like the :ref: role by @chrisjsewell in PR #282 (#110)

  • 🐛 Messages and gettext locations for button text name its first content line in reStructuredText (they named a later line, or the including page for a button in an included file) by @chrisjsewell in PR #315

  • 🐛 Icon roles no longer leak SVG markup into toctree labels and the search index, and article-info icons regain their sd-pr-2 spacing by @chrisjsewell in PR #279 (#99, #117)

  • 🐛 Dropdowns no longer overwrite user classes on their paragraphs with sd-card-text by @chrisjsewell in PR #278 (#40)

  • 🐛 Non-HTML builds no longer gain a spurious _sphinx_design_static directory by @chrisjsewell in PR #276 (#200, #235)

  • 🐛 The sd_fontawesome_latex row of the global options table no longer splits into an extra cell by @yvonnefroehlich in PR #297

Dependencies

  • ⬆️ Sphinx >=7.2,<10 by @chrisjsewell in PR #276

  • ⬆️ Octicons v19.8.0 to v19.42.0: 81 new icons (such as agent, library, release and sparkle), 12 redrawn icons and 37 extra sizes; no icon is removed (commit stays available) by @kdeldycke in PR #309

  • ⬆️ Theme extras refreshed to current releases by @chrisjsewell in PR #267, and the theme-pydata extra allows pydata-sphinx-theme<0.25 (PR #313)

  • ⬆️ The build backend allows flit_core>=3.4,<5 by @chrisjsewell in PR #312

Docs

  • 📚 Buttons are documented as links styled as buttons, with an accessibility note by @gabalafou in PR #158, carried in PR #287

  • 📚 Sizing classes, multiple grid rows, links to synchronised tabs, and the MyST extensions the examples need by @chrisjsewell in PR #273 (#172, #122, #184, #247)

  • 📚 A browser support policy (Baseline Widely Available) and a “Design: the CSS pipeline” page by @chrisjsewell in PR #290

  • 📚 Fix a typo in the get started page by @stefmolin in PR #229

Internal

  • 🔧 Releases are published to PyPI with trusted publishing, and every pull request builds and checks the distributions by @chrisjsewell in PR #311

  • 🔧 CI compiles the documentation PDF by @chrisjsewell in PR #289

  • ♻️ Remove the unused OCTICON_VERSION and OCTICON_CSS constants by @ftnext in PR #205, carried in PR #266

0.7.0 - 2026-01-19

Dependencies

Docs

0.6.1 - 2024-08-02

0.6.0 - 2024-05-23

Dependencies

New

✨ Create custom directives

You can use the sd_custom_directives configuration option in your conf.py to add custom directives, with default option values:

sd_custom_directives = {
    "dropdown-syntax": {
        "inherit": "dropdown",
        "argument": "Syntax",
        "options": {
            "color": "primary",
            "icon": "code",
        },
    }
}

The key is the new directive name to add, and the value is a dictionary with the following keys:

  • inherit: The directive to inherit from (e.g. dropdown)

  • argument: The default argument (optional, only for directives that take a single argument)

  • options: A dictionary of default options for the directive (optional)

by @chrisjsewell in PR #194

✨ sync tabs by URL query parameters

Synchronised tabs can now be selected by adding a query parameter to the URL, for that sync-group, such as ?code=python for

.. tab-set-code::

    .. literalinclude:: snippet.py
        :language: python

    .. literalinclude:: snippet.js
        :language: javascript

The last selected tab key, per group, is also persisted to SessionStorage

by @mikemckiernan and @chrisjsewell in PR #196

Improve

👌 Improve dropdown title bar

There are three visible changes:

  1. The “default” behaviour of the right chevron is to go from right-facing (closed) to down-facing (open), instead of down-facing (closed) to up-facing (open). There is also a rotate transition on opening/closing. The old default behaviour can be retained by using the new :chevron: down-up directive option.

  2. The prefix icon (optional), title text, and chevron state icon are now all better aligned

  3. The top/bottom padding is now 0.5em instead of 1em

The PR also introduces three new CSS variables to control font sizes of the dropdown:

--sd-fontsize-tabs-label: 1rem;
--sd-fontsize-dropdown-title: 1rem;
--sd-fontweight-dropdown-title: 700;

Internally, the HTML / CSS is changed, such that the title is now an inline-flex box, with three columns arranged with justify-content: space-between:

icon (optional)

text (flex-grow: 1)

state chevron

Also, the state chevron was previously two distinct SVGs (with one hidden), but now is one that get rotated on open/close.

by @chrisjsewell in PR #192

Fix

Internal

Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.5.0…v0.6.0

0.5.0 - 2023-07-27

Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.4.1…v0.5.0

v0.4.0 - 2023-04-13

Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.3.0…v0.4.0

Enhancements made

Version upgrades

Contributors to this release

The following people contributed discussions, new ideas, code and documentation contributions, and review. See our definition of contributors.

(GitHub contributors page for this release)

v0.3.0 - 2022-08-22

  • ⬆️ Update Materials Design Icons to v4.0.0-46-gc9e5528, thanks to @2bndy5 (PR #69)

  • 🐛 FIX: dropdown/tab-item :name: options (PR #91)

  • 🐛 FIX: Docs build against non-html formats (PR #88)

  • 👌 IMPROVE: Add card options class-img-top/class-img-bottom (PR #92)

  • 👌 IMPROVE: Add link-alt to fix card link accessibility (PR #89)

    • adds the link-alt option to card (and grid-item-card) directives, in order to assign a discernable name to the link (for screen readers).

  • 👌 IMPROVE: Make tab ids deterministic (PR #93)

    • Use increasing indices, rather than UUIDs

  • 🔧 MAINTAIN: Fix docutils PendingDeprecationWarning (PR #94)

  • 📚 DOCS: Update font awesome icons (PR #64)

Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.2.0…v0.3.0

v0.2.0 - 2022-06-14

  • ⬆️ Support Sphinx v5, drop v3

  • ⬆️ Add Python 3.10 support

Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.1.0…v0.2.0

v0.1.0 - 2022-04-21

Full Changelog: https://github.com/executablebooks/sphinx-design/compare/v0.0.13…v0.1.0

v0.0.13 - 2021-10-27

✨ NEW: add icon far role (PR #35), thanks to @OriolAbril

👌 IMPROVE: Styling for tabs (PR #21), thanks to @pradyunsg

👌 IMPROVE: Properly remove the border on dropdown card body (PR #23), thanks to @pradyunsg

🐛 FIX: sd-outline-* classes color (PR #25)

v0.0.11 - 2021-09-08

✨ NEW: Add ref-type option to button-ref directive

v0.0.10 - 2021-08-08

✨ NEW: Add grid-item directive child-direction and child-align options

✨ NEW: Add card directive img-background option

v0.0.9 - 2021-06-08

♻️ REFACTOR: test_sd_hide_root_title to sd_hide_title front-matter

👌 IMPROVE: dropdown chevrons

v0.0.8 - 2021-06-08

✨ NEW: Add test_sd_hide_root_title config option to hide the root title.

👌 IMPROVE: sd-card-hover:hover add scale 101%

📚 DOCS: Update landing page

v0.0.7 - 2021-05-08

✨ NEW: Add reverse option for grid directive

✨ NEW: Add animations

v0.0.6 - 2021-04-08

✨ NEW: Add card-carousel directive

v0.0.5 - 2021-28-07

👌 IMPROVE: Make octicon’s size variable

v0.0.4 - 2021-28-07

👌 IMPROVE: Allow auto for grid columns

v0.0.3 - 2021-26-07

👌 IMPROVE: Add more CSS classes and add documentation 📚

v0.0.2 - 2021-23-07

Improve documentation 📚

v0.0.1 - 2021-22-07

Initial release 🎉