Skip to content

Commit c0f2db5

Browse files
trallardsmeragoel
trallard
and
smeragoel
authored
DOC - Add design system documentation (#2046)
Since we have done a lot of work on the design and accessibility side, we decided to add comprehensive docs to PST. The docs were authored by @smeragoel (I only helped get the PR in and added some minor edits). --------- Co-authored-by: Smera Goel <[email protected]>
1 parent 30cdb3f commit c0f2db5

File tree

7 files changed

+205
-4
lines changed

7 files changed

+205
-4
lines changed

‎docs/community/design-system.md

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# PyData Sphinx Theme Design System
2+
3+
The Pydata Sphinx Theme is committed to maintaining a theme that supports industry standards;
4+
the design system must be included.
5+
Whether choosing how to configure your theme or making changes to the design system itself,
6+
consider the most recent version of the Web Content Accessibility Guidelines
7+
(WCAG) to make sure the community continues to support documentation access for everyone.
8+
9+
## Guiding Principles
10+
11+
### Accessibility
12+
13+
Accessibility is at the core of the PyData Sphinx theme.
14+
All design decisions are made with [WCAG 2.1](https://www.w3.org/TR/WCAG21/) conformance in mind,
15+
ensuring that the theme is usable by people of all abilities.
16+
Accessibility is a priority to make the theme inclusive for all users.
17+
18+
### Open Source Collaboration
19+
20+
As an open-source project, collaboration and transparency are key principles:
21+
22+
1. **Clear Guidelines:** All components, color palettes, and typography rules must be documented.
23+
2. **Open Feedback:** Designers, developers, users and maintainers are encouraged
24+
to give feedback on the theme, helping to improve its functionality and usability over time.
25+
If you’d like to provide feedback, please open an issue on the
26+
[PyData Sphinx Theme GitHub repository.](https://github.com/pydata/pydata-sphinx-theme)
27+
3. **Community Driven:** The theme grows and evolves based on the needs and
28+
suggestions of the open-source community.
29+
30+
## Typography
31+
32+
### Typeface
33+
34+
PyData Sphinx uses default system fonts.
35+
36+
### Type Scale
37+
38+
A type scale refers to the multiple by which font sizes increase.
39+
You can find more about typographic scales at [Typographic Scale](https://designcode.io/typographic-scales).
40+
For content-heavy websites, a medium contrast scale, which provides balanced
41+
contrast between heading sizes without overly large jumps, is ideal,
42+
typically ranging from `1.2x` to `1.33x`.
43+
44+
The PST type scale was updated (August 2024) to improve the accessibility of the
45+
overall type system and increase visual contrast between the headings.
46+
The PST type scale uses the Minor Third scale (`1.2x`) with values rounded to the
47+
nearest even whole number.
48+
Except for the H4 to H3 transition, all headings have a minimum of a `1.2x` increase,
49+
which is an improvement over the previous scale.
50+
51+
### Styles
52+
53+
#### Headings
54+
55+
Headings create structure and hierarchy within the content.
56+
They range from `H1` to `H6`, with each level decreasing in size and importance.
57+
58+
| Style | Size (`px`) | Size (`rem`) | Weight | Use / Notes |
59+
| :-------- | :---------- | :----------- | :----- | :------------------------------- |
60+
| Heading 1 | 42 | 2.625 | 600 | Main page titles (use only once) |
61+
| Heading 2 | 34 | 2.125 | 600 | Section titles |
62+
| Heading 3 | 28 | 1.750 | 600 | Subsections within H2 |
63+
| Heading 4 | 24 | 1.500 | 600 | Tertiary level headings |
64+
| Heading 5 | 20 | 1.250 | 600 | Less prominent headings |
65+
| Heading 6 | 16 | 1.000 | 600 | Lowest level headings |
66+
67+
Always use headings in logical order (`H1`, `H2`, `H3`, etc.) without skipping levels,
68+
to help assistive tech such as screen readers interpret the structure of the page.
69+
Each page should have a single, unique `H1` to effectively define the page's purpose,
70+
improving search engine optimization (SEO) and accessibility for users who rely
71+
on assistive tech such as screen readers.
72+
73+
#### Body
74+
75+
Body text serves as the standard style for detailed content.
76+
It is primarily used for longer, detailed content such as paragraphs, articles,
77+
and descriptions, but may also apply to other areas such as modals, admonitions
78+
or sections where longer content needs to be displayed clearly.
79+
80+
| Style | Size (`px`) | Size (`rem`) | Weight | Use / Notes |
81+
| :---- | :---------- | :----------- | :----- | :--------------------------------- |
82+
| Body | 16 | 1.000 | 400 | Standard text size for readability |
83+
84+
While there is no absolute minimum text size, for optimum readability,
85+
body text should be at least `16px`.
86+
87+
#### Links
88+
89+
Links must be styled in a way that makes them visually distinct from regular text.
90+
All links should be underlined in addition to being color-coded,
91+
as [color alone should not be used to convey meaning](https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html).
92+
93+
| Style | Size (`px`) | Size (`rem`) | Weight | Use / Notes |
94+
| :---- | :---------- | :----------- | :----- | :-------------------------------- |
95+
| Links | 16 | 1.000 | 400 | Always underlined and color-coded |
96+
97+
Links also have a hover and focus interactive state.
98+
Hover and focus states should always show a change in color and visual design
99+
to provide clear feedback for interactive elements.
100+
101+
Links are used to navigate between different pages or sections and to redirect
102+
readers to external sources.
103+
They are visually distinct from buttons, which are used to perform actions within
104+
the current page or context and should not trigger actions like submitting forms
105+
or toggling components.
106+
107+
#### Code Text
108+
109+
Code text is used to display inline code snippets or larger blocks of code.
110+
It uses a monospaced font. The theme also includes interactive states for code
111+
text including links.
112+
113+
### Type Color
114+
115+
Text color plays a crucial role in ensuring that content is legible and accessible.
116+
In the PyData Sphinx theme, we use a predefined set of colors to ensure readability,
117+
visual hierarchy, and consistency across different elements.
118+
Each text color is designed to meet accessibility guidelines, ensuring sufficient
119+
contrast between text and background.
120+
121+
When using colors in text, ensure that it meets the minimum
122+
[WCAG color contrast accessibility criterion](https://www.w3.org/WAI/WCAG22/quickref/?versions=2.1#contrast-minimum).
123+
Color alone should not be used to indicate meaning.
124+
For example, text that is a link should not be indicated solely by color
125+
but also with an underline.
126+
This helps ensure that users who have difficulty distinguishing colors can still identify links.
127+
Semantic colors (such as for success, warning, or error messages) can be used to
128+
convey meaning, but color should not be the only indicator.
129+
Pair these colors with icons or text labels to ensure clarity.
130+
131+
### Relevant Links
132+
133+
For further reference, you can access the following resources related to the
134+
typography in the PyData Sphinx theme:
135+
136+
1. **GitHub Repository:** The source code for the PyData Sphinx theme is available on GitHub.
137+
You can find the specific file that defines the typography settings,
138+
including font stacks, sizes, and weights in the
139+
[`fonts.scss` file](https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/assets/styles/variables/_fonts.scss).
140+
2. **Figma Design File:** The Figma file contains the visual design and specifications
141+
for the typography styles, including font sizes, line heights,
142+
and spacing used throughout the theme.
143+
You can access it [through this link to the Figma file](https://www.figma.com/design/BHkBFxg1Qg0h5RApUw1ZrR/PyData-Design-System---Ongoing?node-id=2-7).
144+
145+
### References
146+
147+
1. [https://carbondesignsystem.com/elements/typography/overview/](https://carbondesignsystem.com/elements/typography/overview/)
148+
2. [https://canvas.workday.com/styles/tokens/type](https://canvas.workday.com/styles/tokens/type)
149+
3. [https://atlassian.design/foundations/typography-beta](https://atlassian.design/foundations/typography-beta)
150+
151+
---
152+
153+
## Color
154+
155+
The PyData Sphinx theme uses a well-defined color palette to ensure consistency,
156+
readability, and accessibility across the entire design system.
157+
This color palette is available for both light and dark themes.
158+
This document explains how to use the theme's color system
159+
160+
### Base Colors
161+
162+
Base colors form the foundation of the theme and are used across primary UI elements
163+
like buttons, backgrounds, and text. They maintain consistency throughout the interface.
164+
165+
- **Primary**: The main color for major actions and interactive elements.
166+
- **Secondary**: A supporting color for secondary actions and highlights.
167+
- **Accent**: An emphasis color used sparingly for highlighting content.
168+
- **Gray (Neutral)**: Used for typography, borders, and backgrounds.
169+
- **Foundation Colors**: Black and white base colors used for backgrounds and
170+
surfaces (for example, cards, containers, modals) in light and dark modes.
171+
172+
Color variables are also documented in the [](../user_guide/styling.rst) section
173+
of the User Guide.
174+
175+
### Semantic Colors
176+
177+
Semantic colors, colors named for what they represent and how they are used,
178+
are provided for success, errors, warnings, and information.
179+
Using these colors as named ensures users can easily understand system feedback
180+
through visual cues.
181+
182+
### Relevant Links
183+
184+
For further reference, you can access the following resources related to colors
185+
in the PyData Sphinx theme:
186+
187+
1. **GitHub Repository:** You find all the PyData Sphinx theme colors in the
188+
[`color.scss` file](https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/assets/styles/variables/_color.scss)
189+
2. **Figma Design File:** For specific color codes and detailed use cases,
190+
refer to the [Figma Design File](https://www.figma.com/design/BHkBFxg1Qg0h5RApUw1ZrR/PyData-Design-System---Ongoing?node-id=2-160).

‎docs/community/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,4 +29,5 @@ practices/*
2929
3030
contributors
3131
inspiration
32+
design-system
3233
```

‎docs/community/topics/accessibility.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Accessibility checks and manual auditing
22

33
As part of our commitment to making this theme accessible, we run automated
4-
checks against all of the pages under [](../../examples/kitchen-sink/index.rst).
4+
checks against all the pages under [](../../examples/kitchen-sink/index.rst).
55

66
The accessibility check is run every time that a pull request is created on
77
GitHub. We forbid merging a pull request into the codebase if it breaks this

‎docs/user_guide/accessibility.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,9 @@ page that lacks metadata, please open a pull request to add it!
3939
buttons and dropdowns to ensure that they meet WCAG 2 AA or AAA contrast
4040
requirements.
4141

42+
To learn more about the PyData Sphinx Theme colors, check the [](../community/design-system.md)
43+
section.
44+
4245
### Keyboard Navigation Support
4346

4447
For all buttons, dropdowns, tabbed panels, hamburger menus, modals, overlays,

‎docs/user_guide/extending.rst

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,9 @@ The title is specified on the same line as the ``.. admonition::`` directive:
8787
Styling with semantic color names
8888
---------------------------------
8989

90-
You can re-style any admonition to match any of the built-in admonition types using any of the :ref:`theme's semantic color names <color-variables>` as a class (this is most useful for custom-titled admonitions):
90+
You can re-style any admonition to match any of the built-in admonition types
91+
using any of the :ref:`theme's semantic color names <color-variables>` as a
92+
class (this is most useful for custom-titled admonitions):
9193

9294
.. begin-example-semantic
9395
.. admonition:: Custom title with "warning" style

‎docs/user_guide/fonts.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ icon font (the ``.fa-solid, .fa-regular, .fa-brands`` styles, which are used for
77
This is the only *vendored* font, and otherwise, the theme by default relies on
88
available system fonts for normal body text and headers.
99

10+
For more details on the PyData Sphinx Theme typography and text styles, see the
11+
:doc:`../community/design-system` section.
12+
1013
The default body and header fonts can be changed as follows:
1114

1215
- Using :ref:`custom-css`, you can specify which fonts to use for the body, header,

‎docs/user_guide/light-dark.rst

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@
44
Light and dark themes
55
=====================
66

7-
You can change the major background/foreground colors of this theme using built-in "dark" and "light" modes.
7+
You can change the major background/foreground colors of this theme using
8+
built-in "dark" and "light" modes.
89
These are controlled by a button in the navigation header, with the following options:
910

1011
- A ``light`` theme with a bright background and dark text / UI elements
@@ -16,7 +17,8 @@ Configure default theme mode
1617
----------------------------
1718

1819
By default, visitors to your documentation will use the theme mode ``auto``.
19-
This will choose a theme based on the user's system settings, and default to ``light`` if no system setting is found.
20+
This will choose a theme based on the user's system settings, and default to
21+
``light`` if no system setting is found.
2022

2123
If you wish to use a different default theme mode, set the ``default_mode`` configuration to one of ``auto``, ``dark``, ``light``.
2224
For example:

0 commit comments

Comments
 (0)