@gopherium/godmin 0.26.0 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,107 @@
1
+ ---
2
+ title: Design System
3
+ description: The rules for how an admin built on godmin looks, where its colors come from, and how to read a design token name.
4
+ ---
5
+
6
+ The Design System is the set of rules for how an admin built on
7
+ godmin looks. It says where each part of the screen sits, how big
8
+ things are, how they move and which colors they take. A new product
9
+ can follow these pages without reading any godmin code.
10
+
11
+ These pages hold the values the whole admin shares. A part with a
12
+ page of its own, such as [toasts](./toasts.md), keeps its values
13
+ there. Every other part keeps its values on the page that shows how
14
+ to use it.
15
+
16
+ godmin builds on the WordPress Design System, WPDS for short. For
17
+ layout, sizes and motion it follows WordPress's new admin and the
18
+ Site Editor. Colors work another way. They come from three seeds. A
19
+ seed is one color you hand the design system, and the design system
20
+ works out every shade it needs from it:
21
+
22
+ - The chrome seed paints the chrome, the part of the
23
+ [frame](./layout.md#the-frame) around your screens. That is the
24
+ sidebar, or the top bar and its drawer on a small screen.
25
+ - The canvas seed paints the canvas, the panel that shows the current
26
+ screen.
27
+ - The accent is the color of primary buttons, selected rows and
28
+ focus rings.
29
+
30
+ Each seed has a prop of its own. A product changes colors only
31
+ through these three props. It never sets a design token itself.
32
+ [The three seeds](./color.md#the-three-seeds) names each prop and its
33
+ default.
34
+
35
+ ## Reading a token name
36
+
37
+ A design token is a named value, such as a color or a size. WPDS
38
+ ships each token as a CSS custom property, a variable your CSS reads
39
+ with `var()`. The name is made of parts, read from left to right.
40
+ Take `--wpds-dimension-gap-md`:
41
+
42
+ - `--wpds-` marks a token of the design system.
43
+ - `dimension` is the kind of value, here a length. The other kinds
44
+ are `color`, `border`, `typography`, `motion` and `cursor`.
45
+ - `gap` is what it sets, the space between items.
46
+ - `md` is its step on the size scale, medium. Steps such as `sm` and
47
+ `lg` sit below and above it. [Spacing](./layout.md#spacing) gives
48
+ the value of each step.
49
+
50
+ Color names have more parts. `--wpds-color-foreground-content-neutral`
51
+ is the text color of the page. `foreground` means text and icons.
52
+ `content` means something you read rather than click. `neutral` means
53
+ the color carries no meaning such as success or error. Add `weak` or
54
+ `strong` and the color gets fainter or stronger.
55
+ `--wpds-color-foreground-content-neutral-weak` is the muted text
56
+ color.
57
+
58
+ godmin's own custom properties start with `--godmin-` instead.
59
+ [Custom properties](./custom-properties.md) lists them and says which
60
+ ones you may read or change.
61
+
62
+ ## Writing your own styles
63
+
64
+ Write the token, not the value it holds today. The value can change.
65
+ Color tokens follow the seeds, and radius tokens follow
66
+ [the corner radius setting](./radius-and-elevation.md#the-corner-radius-setting)
67
+ of `AdminRoot`. The same color token holds one value in the sidebar
68
+ and another in the canvas, because each region has its own seed.
69
+
70
+ The design system ships rules for stylelint, a checker for CSS files.
71
+ They catch a token name that does not exist, and a token you set
72
+ yourself. [Lint your
73
+ stylesheets](../build-and-versioning.md#lint-your-stylesheets)
74
+ shows how to turn them on.
75
+
76
+ Most of godmin's rules sit in a cascade layer. A cascade layer is a
77
+ named group of CSS rules with its own place in the order that
78
+ decides which rule wins. A rule of yours outside any layer wins over
79
+ every godmin rule inside one.
80
+ [Changing the page appearance](../overview.md#changing-the-page-appearance)
81
+ explains this, and names the few godmin rules that sit outside the
82
+ layer.
83
+
84
+ ## The pages
85
+
86
+ - [Color](./color.md): the three seeds, the token that paints each
87
+ part, the contrast minimums, and the raw colors painted on purpose.
88
+ - [Layout](./layout.md): the areas of the frame and their sizes, the
89
+ canvas margin and gutters, the breakpoints, the screen widths where
90
+ the layout changes, the spacing tokens, and right-to-left languages.
91
+ - [Radius and elevation](./radius-and-elevation.md): how round each
92
+ surface's corners are, and which surfaces cast a shadow to look
93
+ raised.
94
+ - [Typography](./typography.md): the font, the text sizes and
95
+ weights, and the heading outline.
96
+ - [Motion](./motion.md): the motion tokens, the sidebar slide, and
97
+ what changes for a reader who asks for less motion.
98
+ - [Accessibility](./accessibility.md): focus rings, where focus goes,
99
+ landmarks, what a screen reader hears, and text length.
100
+ - [Custom properties](./custom-properties.md): every godmin custom
101
+ property, where it is set and what it changes.
102
+
103
+ One more page covers a single part, how it looks and how it behaves:
104
+
105
+ - [Toasts](./toasts.md): where a toast sits, how it looks, how long it
106
+ stays, how a reader clears it, and what a keyboard or a screen reader
107
+ meets.
@@ -0,0 +1,135 @@
1
+ ---
2
+ title: Radius and elevation
3
+ description: Which corner radius each surface of a godmin admin takes, what the cornerRadius setting changes, and the shadows godmin draws.
4
+ ---
5
+
6
+ Radius is how round a corner is. Elevation is how high a surface
7
+ seems to sit above the page. A shadow is what shows it. WordPress
8
+ uses both words, and so does this page.
9
+
10
+ godmin takes most of its corners from the design tokens, the named
11
+ values `@wordpress/theme` ships. The tokens hold no shadows, so godmin
12
+ writes each shadow out in full.
13
+
14
+ ## Corners from the tokens
15
+
16
+ The tokens have five radius steps. Each step is meant for one kind of
17
+ surface, and godmin rounds its surfaces to match. The pixel values are
18
+ those of the default preset, `subtle`.
19
+ [The corner radius setting](#the-corner-radius-setting) explains
20
+ presets.
21
+
22
+ | Token | Meant for | What godmin rounds with it |
23
+ | --- | --- | --- |
24
+ | `--wpds-border-radius-xl` (12px) | Page and app shell surfaces | The canvas, the panel that shows the active screen |
25
+ | `--wpds-border-radius-lg` (8px) | Cards, dialogs, notices and other larger containers | A `LogList`, the box of items shown one under the other |
26
+ | `--wpds-border-radius-md` (4px) | Menus, popovers and other small overlays | A toast, which keeps its corners at every preset, as [toasts](./toasts.md#colors-corners-and-shadow) shows |
27
+ | `--wpds-border-radius-sm` (2px) | Buttons, inputs and compact controls | A sidebar row, the Back button of a sidebar screen, the grey bars of a loading ghost, the focus ring of a page tab, and the focus ring of a toast action, which keeps its corners at every preset |
28
+ | `--wpds-border-radius-xs` (1px) | Elements nested inside controls | Nothing of godmin's own |
29
+
30
+ A surface inside another takes a smaller step than the one around
31
+ it, as WordPress asks. A log list on the canvas takes `lg` inside the
32
+ `xl` of the canvas.
33
+
34
+ Below `EDGE_BREAKPOINT` the canvas meets the screen edges and its
35
+ corners are square. [Breakpoints](./layout.md#breakpoints) gives that
36
+ width. A bleed canvas, the mode with no padding, keeps the same
37
+ corners as a padded one. [The canvas](./layout.md#the-canvas) explains
38
+ both modes.
39
+
40
+ ## Corners that never change
41
+
42
+ These shapes are fixed in the stylesheet. They stay the same at every
43
+ preset.
44
+
45
+ | Surface | Corner |
46
+ | --- | --- |
47
+ | An `InitialsAvatar`, and the picture inside it | A circle, `50%` |
48
+ | The DataViews media box around an avatar | A circle, `50%` |
49
+ | A `MenuCount` | Half its height. That makes the count a pill, a box with fully round ends |
50
+ | The navigation drawer | Square, `0` |
51
+ | The thumb of the sidebar scrollbar, the part you drag | 8px |
52
+
53
+ The drawer is the panel that holds the sidebar on a small screen.
54
+ DataViews is the WordPress list component.
55
+
56
+ ## The corner radius setting
57
+
58
+ `AdminRoot` takes a `cornerRadius` prop and hands it to the design
59
+ system theme provider. Its value is a preset, a named amount of
60
+ roundness. One preset sets all five radius steps:
61
+
62
+ | Preset | `--wpds-border-radius-xs` | `--wpds-border-radius-sm` | `--wpds-border-radius-md` | `--wpds-border-radius-lg` | `--wpds-border-radius-xl` |
63
+ | --- | --- | --- | --- | --- | --- |
64
+ | `none` | 0px | 0px | 0px | 0px | 0px |
65
+ | `subtle` | 1px | 2px | 4px | 8px | 12px |
66
+ | `moderate` | 6px | 8px | 12px | 16px | 20px |
67
+ | `pronounced` | 18px | 20px | 22px | 24px | 26px |
68
+
69
+ Without the prop the preset is `subtle`.
70
+
71
+ ```tsx
72
+ <AdminRoot cornerRadius="moderate">
73
+ <YourApp />
74
+ </AdminRoot>
75
+ ```
76
+
77
+ `AdminRoot` renders the root theme provider, the one that also themes
78
+ the whole document. So the preset also reaches the dialogs, menus and
79
+ popovers that the design system draws outside the `AdminRoot`
80
+ element. The theme providers of `Frame.Root` and `Frame.Canvas` set
81
+ only colors, so the sidebar and the canvas take the preset from
82
+ `AdminRoot`.
83
+
84
+ The band of notices at the top of a bleed canvas always takes `none`.
85
+ Its notices run edge to edge as square strips. On a padded canvas the
86
+ notices take the same preset as the canvas around them.
87
+ [Notices for the whole
88
+ application](../framing-an-application.md#notices-for-the-whole-application)
89
+ shows how to pass them.
90
+
91
+ The toast region keeps the corners of the WordPress snackbar at every
92
+ preset `AdminRoot` sets.
93
+ [Colors, corners and shadow](./toasts.md#colors-corners-and-shadow)
94
+ gives them.
95
+
96
+ `renderAdmin` from `@gopherium/godmin/testing` takes the same
97
+ `cornerRadius`, so a test can draw a screen under any preset.
98
+
99
+ ## Elevation
100
+
101
+ WordPress names four levels of elevation: extra small, small, medium
102
+ and large. The higher the level, the more a surface asks for
103
+ attention. A dialog sits at the top. godmin draws three shadows that
104
+ show depth:
105
+
106
+ | Surface | Shadow |
107
+ | --- | --- |
108
+ | The canvas | `0 1px 2px rgb(0 0 0 / 0.08)`. None below `EDGE_BREAKPOINT` |
109
+ | A toast | The WordPress small elevation, the one the snackbar uses. [Colors, corners and shadow](./toasts.md#colors-corners-and-shadow) writes out its four layers |
110
+ | The navigation drawer | `2px 0 8px rgba(0, 0, 0, 0.2)`, the shadow of the phone sidebar in WordPress's new admin |
111
+
112
+ A bleed canvas keeps the canvas shadow. The sidebar has no shadow.
113
+ Dialogs, menus and popovers keep the shadow their design system
114
+ package draws, because godmin sets none for them.
115
+
116
+ Two more shadows draw a line, not depth:
117
+
118
+ - Below `DENSE_BREAKPOINT` the actions column of a `godmin-table`
119
+ inside a `godmin-table-scroll` box stays pinned while the other
120
+ cells scroll. Its edge is an inset shadow, one drawn inside the
121
+ box: `--wpds-border-width-xs` (1px) of
122
+ `--wpds-color-stroke-surface-neutral`. It sits on the side that
123
+ faces the other cells, in a right-to-left page too. The table
124
+ merges the borders of its cells, and a merged border paints badly
125
+ on a pinned cell. [Stylesheet helpers](../screens.md#stylesheet-helpers)
126
+ shows the table markup.
127
+ - A focused toast with no action draws its focus ring as a shadow, as
128
+ [keyboard](./toasts.md#keyboard) on the toasts page shows.
129
+ [The focus ring](./accessibility.md#the-focus-ring) covers the
130
+ other focus rings.
131
+
132
+ godmin also takes one shadow away. It drops the dark ring DataViews
133
+ draws around its media box when the box holds an avatar.
134
+ [Avatars](../lists.md#avatars) explains why godmin rounds that box and
135
+ drops its ring.
@@ -0,0 +1,187 @@
1
+ ---
2
+ title: Toasts
3
+ description: Where a toast sits, how it looks, how long it stays, how a reader clears it, and what a keyboard or a screen reader meets.
4
+ ---
5
+
6
+ A toast is a short message near the bottom of the window. It says how
7
+ something went, then goes away on its own. godmin draws it as
8
+ WordPress's new admin draws its snackbar.
9
+ [Toasts](../loading-and-feedback.md#toasts) shows how to raise one and
10
+ what to write in it. This page gives every value of how a toast looks
11
+ and behaves.
12
+
13
+ ## Where a toast sits
14
+
15
+ Toasts stack in one column fixed to the window. The column spans the
16
+ whole width of the window, the sidebar included, and centers each
17
+ toast in it. So a toast sits at the center of the window, as in
18
+ WordPress's new admin. The sidebar and the drawer never move it.
19
+
20
+ - The column sits `--wpds-dimension-size-md` (32px) above the bottom
21
+ edge of the window.
22
+ - It keeps 16px free on each side, so a toast never touches the edge.
23
+ - Two toasts sit `--wpds-dimension-gap-sm` (8px) apart, the newest at
24
+ the bottom. The gap sits above each toast, inside the space that
25
+ grows and closes with the toast, as in the snackbar. So an arriving
26
+ toast starts one gap below the bottom of the column, then rises by
27
+ the gap and its own height.
28
+ - A click on the column between toasts reaches the page under it.
29
+
30
+ A toast paints above the canvas and the sidebar. On a list page it
31
+ floats over the list footer, as it does in WordPress. Two things paint
32
+ above a toast:
33
+
34
+ - The drawer on a small screen.
35
+ - An open dialog. On a wide screen a toast shows dimmed under the dark
36
+ layer around the dialog. On a phone it sits behind the sheet. Screen
37
+ readers still hear it, because every message is also spoken. Most
38
+ dialogs close as their write starts or ends, so their toast shows in
39
+ full. A [form dialog](../lists.md#a-form-dialog) stays open after a
40
+ failure, so its toast shows under it, as in WordPress.
41
+
42
+ ## Size
43
+
44
+ - A toast is as wide as its message, up to
45
+ `--wpds-dimension-surface-width-lg` (560px), its padding included.
46
+ - Below `SHEET_BREAKPOINT` (600px) it spans the column, so it keeps
47
+ 16px from each side of the window. It still stops at 560px.
48
+ - It keeps `--wpds-dimension-padding-md` (12px) above and below its
49
+ text and `--wpds-dimension-padding-xl` (20px) on each side. A toast
50
+ of one line is 42px tall, with or without an action.
51
+ - A long message wraps, even inside a long word. godmin never cuts a
52
+ message or a name in it.
53
+
54
+ ## Colors, corners and shadow
55
+
56
+ These are the colors of the WordPress snackbar. They stay the same
57
+ whatever seeds you pick.
58
+
59
+ - The box is `rgb(0 0 0 / 0.85)`, a black that lets the page show
60
+ through. The page behind it is blurred 16px and saturated to 180%.
61
+ - The text and the action are `#fff`, and so is the ring around a
62
+ focused action.
63
+ - A focused toast with no action has a `#fff` line
64
+ `--wpds-border-width-xs` (1px) wide inside its edge. Outside it sits
65
+ the usual focus ring, `--wpds-border-width-focus` (2px) of
66
+ `--wpds-color-stroke-focus`.
67
+ - The corners take `--wpds-border-radius-md` under the `subtle`
68
+ preset, so they are 4px. The toast region keeps `subtle` whatever
69
+ [corner radius setting](./radius-and-elevation.md#the-corner-radius-setting)
70
+ your app picks, as WordPress keeps the corners of its snackbar.
71
+ - The shadow is the WordPress small elevation, in four layers:
72
+ `0 1px 2px rgb(0 0 0 / 0.05)`, `0 2px 3px rgb(0 0 0 / 0.04)`,
73
+ `0 6px 6px rgb(0 0 0 / 0.03)` and `0 8px 8px rgb(0 0 0 / 0.02)`.
74
+
75
+ ## Text
76
+
77
+ - The message takes `--wpds-typography-font-family-body` at
78
+ `--wpds-typography-font-size-md` (13px), on a line 1.4 times its
79
+ size.
80
+ - The action is a link in the same text, underlined 0.2em below the
81
+ letters at the thickness the font sets. It loses its underline under
82
+ the pointer.
83
+ - The action sits on the first line of the message, at least
84
+ `--wpds-dimension-gap-2xl` (32px) after it. On a phone, where the
85
+ toast spans the column, the spare room goes between the message and
86
+ the action, as in the snackbar.
87
+
88
+ ## How long a toast stays
89
+
90
+ - A toast with no action stays 6 seconds. `dismissAfter` changes it.
91
+ - A toast with an action stays 10 seconds, time to read the message
92
+ and then act. `actionDismissAfter` changes it.
93
+ - WordPress's own snackbar in `@wordpress/components` 42.0.0 still
94
+ stays 6 seconds, with or without an action. Its next release keeps
95
+ one with an action 10 seconds, as godmin does.
96
+ - Each toast keeps its own timer. So a toast a screen raises as it
97
+ mounts leaves on time even under React strict mode, which mounts the
98
+ screen twice in development.
99
+ - At most three toasts show at once. When a fourth arrives, the oldest
100
+ leaves. `limit` changes the three. A toast pushed out in the same
101
+ moment it is raised never shows, as WordPress shows only its newest
102
+ three.
103
+ - Every toast leaves on its own. WordPress also has a snackbar that
104
+ waits for the reader, with no timer and a close button. godmin
105
+ raises none.
106
+
107
+ ## Motion
108
+
109
+ A toast moves as the WordPress snackbar does. Each toast takes a space
110
+ of its own in the column. The space grows as the toast arrives and
111
+ closes after it leaves, so the toasts above slide instead of jumping.
112
+
113
+ - An arriving toast grows its space from no height over
114
+ `--wpds-motion-duration-lg` (300ms) on `cubic-bezier(0, 0, 0.2, 1)`.
115
+ The toast rises into place as its space grows, and the toasts above
116
+ slide up. When a toast leaves, its space closes over 450ms on
117
+ `cubic-bezier(0.4, 0, 0.1, 1)`, so the toasts above slide down. The
118
+ closing waits `--wpds-motion-duration-sm` (100ms) for the toast to
119
+ fade out first. A space that is still growing closes from the height
120
+ it has reached.
121
+ - The toast fades in over 250ms on `cubic-bezier(0, 0, 0.2, 1)`, after
122
+ a wait of `--wpds-motion-duration-xs` (50ms). So the fade ends with
123
+ the growth. A leaving toast fades out over
124
+ `--wpds-motion-duration-sm` on the same curve and stays hidden at the
125
+ end. A toast that is still fading in fades out from where it got to.
126
+ - A leaving toast stays on the page until its space has closed, and
127
+ nobody can press it in that time. If the browser cuts the motion
128
+ short, the toast still goes.
129
+ - [Reduced motion](./motion.md#reduced-motion) says what changes for a
130
+ reader who asks for less motion. Then a toast shows and goes at
131
+ once, and nothing grows, slides or fades, as in WordPress.
132
+
133
+ ## Clearing a toast
134
+
135
+ - A click anywhere on a toast clears it, with or without an action.
136
+ The pointer turns to `--wpds-cursor-control` over every toast.
137
+ - A click on the action runs it and clears the toast.
138
+ - A click on a toast moves focus to the toast region, as WordPress
139
+ moves it to its snackbar list. The region draws no ring.
140
+ - A toast has no close button. WordPress draws its cross only on a
141
+ snackbar with no timer, and godmin raises none.
142
+
143
+ ## Keyboard
144
+
145
+ - A toast with no action is one button. Tab reaches it, and Enter or
146
+ Space clears it. Its focus ring is a white line
147
+ `--wpds-border-width-xs` wide inside the toast and a ring of
148
+ `--wpds-color-stroke-focus` `--wpds-border-width-focus` wide around
149
+ it, both drawn as a shadow. The browser's own ring shows too.
150
+ - In a toast with an action, only the action takes focus. The rest of
151
+ the toast is no tab stop and no button. A keyboard reader runs the
152
+ action, or lets the toast leave on its own when its time is up. So
153
+ offer the same action somewhere else on the screen too, as
154
+ [Toasts](../loading-and-feedback.md#toasts) says.
155
+ - The focus ring of the action is the design system ring in white: a
156
+ solid `#fff` outline `--wpds-border-width-focus` wide, set
157
+ `--wpds-border-width-focus` away from the text, with
158
+ `--wpds-border-radius-sm` corners. They are 2px, because the toast
159
+ region keeps the `subtle` preset, as on the snackbar. The underline
160
+ goes while the ring shows.
161
+ - When a toast that holds focus leaves, focus moves to the toast
162
+ region instead of falling back to the top of the page. The region
163
+ draws no ring, and Tab never stops on it. The region comes after the
164
+ rest of the page, so the next Tab reaches any other toast still on
165
+ screen and then leaves the page for the browser's own controls.
166
+ Shift+Tab goes back to the last control before the region.
167
+
168
+ WordPress makes its whole snackbar a button the keyboard reaches, with
169
+ the action button inside it. godmin never puts a button inside another
170
+ button. So it keeps the click on the whole toast, and leaves the
171
+ keyboard with the action.
172
+
173
+ ## What a screen reader hears
174
+
175
+ - Each message once, politely, through `speak` from `@wordpress/a11y`.
176
+ Polite means the screen reader first finishes what it is saying.
177
+ The region itself is not a live region, so nothing is read twice.
178
+ - Never the action. A reader who moves into the toast finds the action
179
+ by its label.
180
+ - A toast with no action is a button named by its message. After the
181
+ name the screen reader reads the hint `dismissLabel`, which says
182
+ "Dismiss this notice" unless your app passes its own words. No
183
+ tooltip shows when the pointer rests on it.
184
+
185
+ WordPress names its whole snackbar "Dismiss this notice", so a screen
186
+ reader hears those words in place of the message. godmin keeps the
187
+ message as the name of a plain toast and reads the words after it.
@@ -0,0 +1,83 @@
1
+ ---
2
+ title: Typography
3
+ description: The font, the type scale godmin sets its titles and body text in, and the heading outline of a screen.
4
+ ---
5
+
6
+ godmin sets its text with the design system's typography tokens. A
7
+ token is a named value that the design system ships as a CSS custom
8
+ property, such as `--wpds-typography-font-size-md`. CSS reads it with
9
+ `var()`. This page names each token and gives its value in brackets.
10
+ [Which token paints each part](./color.md#which-token-paints-each-part)
11
+ gives the color of each text.
12
+
13
+ ## The font
14
+
15
+ The `body` rule in `base.css` sets the whole page in
16
+ `--wpds-typography-font-family-body`. The design system draws its
17
+ headings in `--wpds-typography-font-family-heading`. Both tokens hold
18
+ the same system font stack. That is a list of fonts the browser tries
19
+ in order, starting with the font the device uses for its own menus
20
+ and windows. Every rule in `base.css` that names a font names the
21
+ body font.
22
+
23
+ ## The type scale
24
+
25
+ Each text has a size, a line height and a weight. The line height is
26
+ the height of one line of text. godmin's titles and body text follow
27
+ five styles.
28
+
29
+ | Style | Size | Line height | Weight |
30
+ | --- | --- | --- | --- |
31
+ | Sidebar screen title | `--wpds-typography-font-size-xl` (20px) | `--wpds-typography-line-height-xl` (32px) | Emphasis |
32
+ | `heading-lg`, for a page, section or empty list title | `--wpds-typography-font-size-lg` (15px) | `--wpds-typography-line-height-sm` (20px) | Emphasis |
33
+ | `heading-md`, for a section title inside a section | `--wpds-typography-font-size-md` (13px) | `--wpds-typography-line-height-sm` (20px) | Emphasis |
34
+ | `body-md`, for body text | `--wpds-typography-font-size-md` (13px) | `--wpds-typography-line-height-sm` (20px) | Default |
35
+ | `body-sm`, for small text such as the time of a log item | `--wpds-typography-font-size-sm` (12px) | `--wpds-typography-line-height-xs` (16px) | Default |
36
+
37
+ `heading-lg`, `heading-md`, `body-md` and `body-sm` are variants of
38
+ `Text`, the design system's text component. A variant sets the size,
39
+ the line height and the weight together. `Text` takes `body-md` when
40
+ it is given none. `base.css` sets the sidebar screen title itself.
41
+
42
+ The design system has two weights.
43
+ `--wpds-typography-font-weight-default` (400) is for body text.
44
+ `--wpds-typography-font-weight-emphasis` (600) is for titles and for
45
+ what stands out, such as the sidebar row of the page on screen. The
46
+ table calls them default and emphasis.
47
+
48
+ The smallest size, `--wpds-typography-font-size-xs` (11px), is for
49
+ small labels such as the count beside a sidebar row.
50
+
51
+ Some parts give the size of their text on their own page:
52
+ [the page subtitle](../screens.md#page),
53
+ [the page tabs](../screens.md#pagetabs),
54
+ [the title and description of a list row](../lists.md#the-title-field),
55
+ [a table that stays custom](../lists.md#lists-that-stay-custom),
56
+ [a toast](./toasts.md#text) and
57
+ [the letter of an avatar](../lists.md#avatars).
58
+
59
+ ## The heading outline
60
+
61
+ The heading outline is the list of headings a screen reader offers to
62
+ jump between, from `h1` down. A `NavigationScreen` draws its title as
63
+ the `h1`, as in the WordPress Site Editor. So the sidebar menu decides
64
+ which title is the `h1`. Below, with a sidebar means the sidebar shows
65
+ a `NavigationScreen`.
66
+
67
+ | Title | Without a sidebar | With a sidebar |
68
+ | --- | --- | --- |
69
+ | Sidebar screen title | None | `h1` |
70
+ | Page title | `h1` | `h2` |
71
+ | Section title | `h2` | `h3` |
72
+ | Section title inside a section | `h3` | `h4` |
73
+ | Empty list title | `h2` | `h3` |
74
+
75
+ With a sidebar, pass `headingLevel={2}` to each `Page`. Every title
76
+ inside it then moves one level down. Only the element changes. Each
77
+ title keeps its size, so a section looks the same on both kinds of
78
+ screen. [Heading levels](../screens.md#heading-levels) shows the code.
79
+
80
+ On a small screen the sidebar sits in the drawer, and its title is
81
+ the `h1` while the drawer is open. The brand in the top bar is not a
82
+ heading. So while the drawer is shut, the screen has no `h1`.
83
+ WordPress's new admin works the same way.