@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.
- package/README.md +8 -19
- package/dist/base.css +49 -30
- package/dist/close-while-open.d.ts +6 -0
- package/dist/close-while-open.js +21 -0
- package/dist/focus-back.d.ts +25 -0
- package/dist/focus-back.js +125 -0
- package/dist/index.d.ts +9 -1
- package/dist/index.js +5 -1
- package/dist/list-run.d.ts +7 -2
- package/dist/list-run.js +64 -2
- package/dist/list-view.d.ts +1 -7
- package/dist/list-view.js +1 -16
- package/dist/open-on-tap.d.ts +14 -0
- package/dist/open-on-tap.js +17 -0
- package/dist/run-confirm.d.ts +1 -1
- package/dist/run-confirm.js +4 -2
- package/dist/toaster.d.ts +7 -9
- package/dist/toaster.js +41 -53
- package/dist/unsaved-text.d.ts +14 -0
- package/dist/unsaved-text.js +25 -0
- package/docs/build-and-versioning.md +219 -0
- package/docs/design-system/accessibility.md +200 -0
- package/docs/design-system/color.md +74 -0
- package/docs/design-system/custom-properties.md +60 -0
- package/docs/design-system/layout.md +157 -0
- package/docs/design-system/motion.md +121 -0
- package/docs/design-system/overview.md +107 -0
- package/docs/design-system/radius-and-elevation.md +135 -0
- package/docs/design-system/toasts.md +187 -0
- package/docs/design-system/typography.md +83 -0
- package/docs/framing-an-application.md +386 -0
- package/docs/lists.md +1495 -0
- package/docs/loading-and-feedback.md +165 -0
- package/docs/overview.md +159 -0
- package/docs/screens.md +419 -0
- package/docs/testing.md +193 -0
- package/package.json +6 -1
|
@@ -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.
|