sphinx-design

sphinx-design is a Sphinx extension that adds a set of screen-size-responsive web components — cards, grids, tabs, dropdowns, badges, and buttons — as reStructuredText directives and MyST Markdown syntax, so documentation authors can build modern, visually rich layouts without writing raw HTML or CSS.

Maintained by the Executable Books project (the team behind Jupyter Book and MyST-Parser), it is designed to work with any Sphinx theme, ships its own themeable CSS variables for light/dark mode, and includes a Font Awesome-backed icon role, making it a common building block for documentation sites that want a more polished visual layout than plain Sphinx provides.

What You Get

• Card, grid, and container directives for building responsive multi-column documentation layouts
• Tabbed content and collapsible dropdown directives for progressive disclosure of information
• Badge and button directives with themeable colors for calls-to-action or status labels
• Font Awesome icon role for inline icons anywhere in the documentation text
• Works in both classic reStructuredText and MyST Markdown syntax
• CSS variables for consistent theming and automatic light/dark mode support

Common Use Cases

• Building card-grid landing pages or feature overviews inside a Sphinx-based documentation site
• Adding tabbed code examples (e.g., per-language install instructions) to project docs
• Creating collapsible FAQ or advanced-option sections with the dropdown directive
• Adding icons, badges, and call-to-action buttons to otherwise plain reStructuredText/MyST pages

Under The Hood

Architecture - the extension registers a family of docutils directives/roles (grids.py, cards.py, tabs.py, dropdown.py, badges_buttons.py, icons.py, article_info.py) with Sphinx via extension.py’s setup() entry point; each directive parses its reStructuredText/MyST arguments and emits docutils nodes wrapped in HTML div/span elements with component-specific CSS classes, while config.py centralizes user-configurable options and shared.py holds cross-directive helpers for consistent option parsing. Tech Stack - Python for the Sphinx-extension logic, paired with a hand-authored CSS design system under style/ (compiled/bundled into sphinx_design/static/ and sphinx_design/compiled/) driven by a design.toml token file and a tools/generate_css.py build script that keeps CSS variables consistent across components; packaged via pyproject.toml with tox for cross-version testing. Code Quality - the tests/ directory has focused suites per component (test_tabs_js.py, test_card_link.py, test_badge_tooltips.py, test_icons.py, test_css.py, accessibility-focused test_tabs_a11y.py) plus a tools/check_css_equivalence.py script guarding against CSS/token drift, and the package ships py.typed and a testing.py module exposing pytest fixtures for downstream Sphinx-extension testing. API Design - the entire public surface is markup-facing (reStructuredText directives and MyST syntax) rather than a Python API to import, which is the natural interface for a Sphinx extension; configuration is centralized in conf.py options rather than scattered per-directive arguments, keeping site-wide theming consistent.