sphinx-design

Supported Browsers

sphinx-design targets Baseline Widely Available web features. This includes evergreen browsers (Chrome, Edge, Firefox, and Safari) that have been interoperable for at least 30 months. Internet Explorer is not supported.

Theme Support

sphinx-design is compatible with several popular Sphinx themes, including:

• alabaster
• sphinx-book-theme
• pydata-sphinx-theme
• sphinx-rtd-theme
• furo

You can customize how individual items behave within a grid:

• Override Column Width: Use the columns option on a grid-item to specify how many of the 12 columns it occupies. You can use a single number (fixed) or four numbers (responsive). Use auto to size based on content.
• Reverse Order: Use the reverse option on the grid directive to reverse the order of items. This is useful for changing visual priority between mobile (stacked) and desktop (side-by-side) views.

::::{grid} 2
:::{grid-item-card}
:columns: auto

A
:::{grid-item-card}
:columns: 12 6 6 6

B
::::

The sphinx_design.testing module is a semi-public API intended for downstream extensions writing doctree regression tests.

• Signatures: The function signatures are covered by the standard deprecation policy.
• Output Stability: The exact output of normalize_doctree_xml is not guaranteed to be stable across docutils versions. Its purpose is specifically to smooth over changes in how docutils serializes data for regression testing.
• Dependencies: The module has no dependency on pytest or any test extras; it can be used with only sphinx_design installed.

Dropdowns are highly composable and can be nested inside other sphinx-design components, such as:

• Admonitions: Place a dropdown inside an admonition block.
• Parent Dropdowns: Nest a dropdown inside another dropdown.
• Grids: Place dropdowns within grid-item elements inside a grid.

::::{admonition} Admonition Title

:::{dropdown} Nested Dropdown
Content
:::

::::

Grids can be nested inside grid-item directives to create complex, adaptive layouts. This allows for fine-grained control over sub-layouts within a larger grid structure.

:::::{grid} 1 1 2 2
:gutter: 1

:::::{grid-item}

::::{grid} 1 1 1 1
:gutter: 1
:::{grid-item-card} Item 1.1
Content
:::{grid-item-card} Item 1.2
Content
::::

:::::
:::::{grid-item}

::::{grid} 1 1 1 1
:gutter: 1
:::{grid-item-card} Item 2.1
Content
:::{grid-item-card} Item 2.2
Content
:::{grid-item-card} Item 2.3
Content
::::

:::::
::::::

The sphinx-design stylesheet is built using a two-tier plain CSS approach to avoid Node.js dependencies and enable runtime theme customization.

1. Hand-authored component CSS: Located in style/*.css, these files contain expanded selectors for specific component areas.
2. Generated utility CSS: These are emitted from declarative tokens defined in style/design.toml (such as color palettes, spacing scales, breakpoints, and column counts) using the tools/generate_css.py generator.

The generator assembles these tiers in a specific ASSEMBLY order to control the CSS cascade. The final output is a single minified file: sphinx_design/static/sphinx-design.min.css.

Styles in sphinx-design target Baseline Widely Available web features.

For modern features like color-mix(), the library uses a graceful degradation pattern. For example, hover shades are declared with a static fallback first, followed by a color-mix(in srgb, black 15%, var(--sd-color-*)) declaration. This ensures that if a user overrides a theme color via --sd-color-*, the hover shade is re-derived at runtime in supporting browsers, while older browsers fall back to the static value.

The card-carousel directive creates a single row of fixed-width, scrollable cards. The directive argument must be an integer between 1 and 12, representing the number of cards to display at once. The carousel supports scroll snapping to the nearest card.

::::{card-carousel} 2

:::{card} card 1
content
:::
:::{card} card 2
Longer content
:::
::::

You can use the :animate: option to add reveal animations to the hidden content. The available animation types are:

• fade-in
• fade-in-slide-down

:::{dropdown} Animated Dropdown
:animate: fade-in-slide-down

Content to reveal.
:::