PyData Sphinx 主题设计系统#

PyData Sphinx 主题致力于维护符合行业标准的主题；设计系统是其中不可或缺的一部分。无论是选择如何配置您的主题，还是对设计系统本身进行更改，请参考最新版本的《网页内容可访问性指南》（WCAG），以确保社区继续支持为所有人提供文档访问的目标。

指导原则#

可访问性#

可访问性是 PyData Sphinx 主题的核心。所有的设计决策都以符合 WCAG 2.1 标准为考量，确保主题能够被所有能力水平的用户使用。可访问性是我们优先考虑的事项，以使主题对所有用户都具有包容性。

开源协作#

作为开源项目，协作与透明是关键原则：

  1. 清晰的指南： 所有组件、配色方案和排版规则都必须有详细的文档说明。

  2. 开放的反馈 ：鼓励设计师、开发者、用户和维护者对主题提出反馈，以帮助其功能和可用性不断改进。如果您希望提供反馈，请在 PyData Sphinx 主题 GitHub 仓库 中提交问题。

  3. 社区驱动 ：主题根据开源社区的需求和建议不断发展和演变。

排版#

字体#

PyData Sphinx 使用默认的系统字体。

字体比例#

字体比例指的是字体大小增加的倍数。您可以在 字体比例 了解更多关于排版比例的信息。对于内容丰富的网站，中等对比度的比例是最理想的，它能在标题大小之间提供平衡的对比，而不会出现过大的跳跃，通常范围在 1.2x 到 1.33x 之间。

PST 字体比例已于 2024 年 8 月更新，以提升整体字体系统的可访问性，并增加标题之间的视觉对比度。PST 字体比例采用小三分之一比例（1.2x），并将数值四舍五入至最接近的偶数。除了 H4 到 H3 的过渡外，所有标题的最小增加比例为 1.2x，这较之前的比例有所改进。

风格#

标题#

标题为内容创建结构和层次。标题范围从 H1 到 H6，每一级的字体大小和重要性依次递减。

Style

Size (px)

Size (rem)

Weight

Use / Notes

Heading 1

42

2.625

600

Main page titles (use only once)

Heading 2

34

2.125

600

Section titles

Heading 3

28

1.750

600

Subsections within H2

Heading 4

24

1.500

600

Tertiary level headings

Heading 5

20

1.250

600

Less prominent headings

Heading 6

16

1.000

600

Lowest level headings

Always use headings in logical order (H1, H2, H3, etc.) without skipping levels, to help assistive tech such as screen readers interpret the structure of the page. Each page should have a single, unique H1 to effectively define the page's purpose, improving search engine optimization (SEO) and accessibility for users who rely on assistive tech such as screen readers.

Body#

Body text serves as the standard style for detailed content. It is primarily used for longer, detailed content such as paragraphs, articles, and descriptions, but may also apply to other areas such as modals, admonitions or sections where longer content needs to be displayed clearly.

Style

Size (px)

Size (rem)

Weight

Use / Notes

Body

16

1.000

400

Standard text size for readability

While there is no absolute minimum text size, for optimum readability, body text should be at least 16px.

Code Text#

Code text is used to display inline code snippets or larger blocks of code. It uses a monospaced font. The theme also includes interactive states for code text including links.

Type Color#

Text color plays a crucial role in ensuring that content is legible and accessible. In the PyData Sphinx theme, we use a predefined set of colors to ensure readability, visual hierarchy, and consistency across different elements. Each text color is designed to meet accessibility guidelines, ensuring sufficient contrast between text and background.

When using colors in text, ensure that it meets the minimum WCAG color contrast accessibility criterion. Color alone should not be used to indicate meaning. For example, text that is a link should not be indicated solely by color but also with an underline. This helps ensure that users who have difficulty distinguishing colors can still identify links. Semantic colors (such as for success, warning, or error messages) can be used to convey meaning, but color should not be the only indicator. Pair these colors with icons or text labels to ensure clarity.

Color#

The PyData Sphinx theme uses a well-defined color palette to ensure consistency, readability, and accessibility across the entire design system. This color palette is available for both light and dark themes. This document explains how to use the theme's color system

Base Colors#

Base colors form the foundation of the theme and are used across primary UI elements like buttons, backgrounds, and text. They maintain consistency throughout the interface.

  • Primary: The main color for major actions and interactive elements.

  • Secondary: A supporting color for secondary actions and highlights.

  • Accent: An emphasis color used sparingly for highlighting content.

  • Gray (Neutral): Used for typography, borders, and backgrounds.

  • Foundation Colors: Black and white base colors used for backgrounds and surfaces (for example, cards, containers, modals) in light and dark modes.

Color variables are also documented in the 主题变量和 CSS section of the User Guide.

Semantic Colors#

Semantic colors, colors named for what they represent and how they are used, are provided for success, errors, warnings, and information. Using these colors as named ensures users can easily understand system feedback through visual cues.