@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,200 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Accessibility
|
|
3
|
+
description: The rules godmin keeps for people who use a keyboard or a screen reader, from the focus ring and landmarks to what is spoken and how text may grow.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Some people never touch a mouse. They move through a page with the
|
|
7
|
+
keyboard, or listen to it with a screen reader. A screen reader is
|
|
8
|
+
software that reads the page aloud and lets its user jump between
|
|
9
|
+
headings, landmarks and controls. This page lists the rules godmin's
|
|
10
|
+
parts keep for those readers. A screen of your own keeps the same
|
|
11
|
+
rules when it draws with those parts and the design tokens.
|
|
12
|
+
|
|
13
|
+
## Contrast
|
|
14
|
+
|
|
15
|
+
Text has to stand out from what sits behind it. The stylesheet paints
|
|
16
|
+
text with design tokens, such as
|
|
17
|
+
`--wpds-color-foreground-content-neutral`. The theme works out those
|
|
18
|
+
tokens from the seed colors a product passes in. Only two parts keep
|
|
19
|
+
fixed colors for their text, the toast and the initials avatar.
|
|
20
|
+
[Contrast](./color.md#contrast) explains the contrast ratio, the
|
|
21
|
+
minimums godmin's tests hold and the parts they check.
|
|
22
|
+
[Avatars](../lists.md#avatars) gives the contrast of the avatar
|
|
23
|
+
letters.
|
|
24
|
+
|
|
25
|
+
## The focus ring
|
|
26
|
+
|
|
27
|
+
Focus marks the control the keyboard acts on. The reader moves it
|
|
28
|
+
with Tab, and Enter presses the control that holds it. godmin rings
|
|
29
|
+
the focused control only when the reader uses the keyboard, the state
|
|
30
|
+
CSS calls `:focus-visible`. A mouse click draws no ring.
|
|
31
|
+
|
|
32
|
+
Except on a toast, every ring godmin draws is the same line,
|
|
33
|
+
`outline: var(--wpds-border-width-focus) solid var(--wpds-color-stroke-focus)`.
|
|
34
|
+
|
|
35
|
+
- `--wpds-border-width-focus` (2px) sets the width. On a high density
|
|
36
|
+
screen, one that packs two or more device pixels into each CSS
|
|
37
|
+
pixel, it is 1.5px.
|
|
38
|
+
- `--wpds-color-stroke-focus` sets the color. The theme works it out
|
|
39
|
+
from the accent seed.
|
|
40
|
+
|
|
41
|
+
| Part | Where the ring sits |
|
|
42
|
+
| --- | --- |
|
|
43
|
+
| A sidebar row, and Back on a sidebar screen | Outside the part, as far out as the ring is wide. A row's ring paints over the row below it |
|
|
44
|
+
| The menu button of the top bar | Inside the button |
|
|
45
|
+
| The title link of a `godmin-table`, a `godmin-table-scroll` box and a row of `RepeatRows` | 2px outside the part |
|
|
46
|
+
| A page tab | Around its label, not around the whole height of the tab |
|
|
47
|
+
| A toast | Its own rings, as [keyboard](./toasts.md#keyboard) on the toasts page shows. A plain toast keeps the browser's ring too |
|
|
48
|
+
|
|
49
|
+
godmin turns the browser's own ring off in three places only. A page
|
|
50
|
+
tab draws its own ring around the label instead. Back draws none on a
|
|
51
|
+
mouse focus. The toast region draws none. Tab never stops on it, and
|
|
52
|
+
only a toast that leaves or a click on a toast focuses it. Draw a
|
|
53
|
+
ring of your own with the same line, on `:focus-visible`, so it
|
|
54
|
+
matches.
|
|
55
|
+
|
|
56
|
+
## Where focus goes
|
|
57
|
+
|
|
58
|
+
In the sidebar menu, a drilldown row is a row that opens a sub menu.
|
|
59
|
+
The drawer is the panel that holds the sidebar on a small screen. The
|
|
60
|
+
sidebar moves focus in these cases only:
|
|
61
|
+
|
|
62
|
+
| The reader | Focus goes to |
|
|
63
|
+
| --- | --- |
|
|
64
|
+
| Opens a sub menu with a drilldown row | Back. On a screen with no Back, the first control the Tab key reaches. On a screen with no control, the screen itself, so focus stays in the sidebar |
|
|
65
|
+
| Presses Back | The drilldown row that opened the sub menu, even after the reader opened pages inside it. When that row is gone, or the sub menu opened another way, the first control of the screen Back lands on |
|
|
66
|
+
| Opens a page with any other link | Nowhere. The sidebar moves no focus |
|
|
67
|
+
| Closes the drawer with Escape or its close button | The menu button |
|
|
68
|
+
|
|
69
|
+
The title of a sidebar screen never takes focus.
|
|
70
|
+
|
|
71
|
+
Some parts go away while they hold focus. godmin then moves focus to
|
|
72
|
+
a part that stays, so the keyboard reader keeps their place:
|
|
73
|
+
|
|
74
|
+
- A toast that leaves, as [keyboard](./toasts.md#keyboard) on the
|
|
75
|
+
toasts page says.
|
|
76
|
+
- A list row that a run moved, as
|
|
77
|
+
[running an action over the picked rows](../lists.md#running-an-action-over-the-picked-rows)
|
|
78
|
+
says.
|
|
79
|
+
- A row of `RepeatRows` that the reader removed, as
|
|
80
|
+
[RepeatRows](../screens.md#repeatrows) says.
|
|
81
|
+
|
|
82
|
+
Dialogs move focus as they open and close, as
|
|
83
|
+
[a confirm outside a list](../lists.md#a-confirm-outside-a-list) and
|
|
84
|
+
[a form dialog](../lists.md#a-form-dialog) explain. When the list
|
|
85
|
+
drew the row a dialog opened from anew while the dialog was open,
|
|
86
|
+
`useFocusBack` puts the focus back on that row, or on the list once
|
|
87
|
+
the row left it, as
|
|
88
|
+
[putting the focus back on a row](../lists.md#putting-the-focus-back-on-a-row)
|
|
89
|
+
explains.
|
|
90
|
+
|
|
91
|
+
## Landmarks and names
|
|
92
|
+
|
|
93
|
+
A landmark is a part of the page with a role, such as `main`, and
|
|
94
|
+
often a name. A screen reader lists the landmarks, so its user can
|
|
95
|
+
jump straight to one.
|
|
96
|
+
|
|
97
|
+
| Part | Role | Name |
|
|
98
|
+
| --- | --- | --- |
|
|
99
|
+
| The canvas | `main` | None |
|
|
100
|
+
| The sidebar on a wide screen, menu and footer together | `region` | "Navigation", or the `label` of `Frame.Sidebar` |
|
|
101
|
+
| The drawer on a small screen | `dialog` | "Navigation", whatever `label` says |
|
|
102
|
+
| The tabs of a page | `navigation` | The `label` of [`PageTabs`](../screens.md#pagetabs) |
|
|
103
|
+
| The list of a list page | `region` | The `listLabel` of [`Page`](../screens.md#page), when given |
|
|
104
|
+
|
|
105
|
+
The sidebar menu draws no landmark of its own, and the drawer holds
|
|
106
|
+
no region. So a screen reader meets the sidebar under one name only.
|
|
107
|
+
[The sidebar](../framing-an-application.md#the-sidebar) shows how to
|
|
108
|
+
pass `label`.
|
|
109
|
+
|
|
110
|
+
Every control godmin draws is named in words. A glyph, a small
|
|
111
|
+
picture such as an icon, is never the name:
|
|
112
|
+
|
|
113
|
+
- Every icon godmin draws itself, such as a row icon, a chevron, the
|
|
114
|
+
Back glyph or the menu glyph, is hidden from screen readers. The
|
|
115
|
+
control around it carries the name.
|
|
116
|
+
- The initials avatar is hidden, because the name beside it already
|
|
117
|
+
says who it is.
|
|
118
|
+
|
|
119
|
+
The current page carries `aria-current="page"`. A sidebar row draws
|
|
120
|
+
its highlight from that mark, so what the eye sees and what a screen
|
|
121
|
+
reader hears always match. A page tab draws its underline from its
|
|
122
|
+
`current` prop, which sets the same mark. A router link can set the
|
|
123
|
+
mark on its own too, so [PageTabs](../screens.md#pagetabs) says how
|
|
124
|
+
to keep the underline and the mark in step.
|
|
125
|
+
|
|
126
|
+
Some screen readers stop treating a list with no bullets as a list.
|
|
127
|
+
So the sidebar rows, the page tabs and a log list keep
|
|
128
|
+
`role="list"`.
|
|
129
|
+
|
|
130
|
+
## What a screen reader hears
|
|
131
|
+
|
|
132
|
+
godmin gives a sentence for the ear wherever the eye gets a shape, a
|
|
133
|
+
glyph or a bare number. Visually hidden text is text on the page that
|
|
134
|
+
only a screen reader meets. Some things appear without the reader
|
|
135
|
+
moving to them, such as a toast or a loading ghost. A screen reader
|
|
136
|
+
learns of those through a live region, a part of the page it reads
|
|
137
|
+
aloud when it changes.
|
|
138
|
+
|
|
139
|
+
| Part | What a screen reader hears | Set up in |
|
|
140
|
+
| --- | --- | --- |
|
|
141
|
+
| A toast | Its message, politely. Never its action | [What a screen reader hears](./toasts.md#what-a-screen-reader-hears) |
|
|
142
|
+
| A loading ghost | The `label` sentence, from a visually hidden status. The grey shapes are hidden | [The ghosts](../loading-and-feedback.md#the-ghosts) |
|
|
143
|
+
| A count beside a row | The `label` sentence, in place of the bare number | [A count beside a row](../framing-an-application.md#a-count-beside-a-row) |
|
|
144
|
+
| An `ErrorNotice` | Its message, at once, as an alert | [ErrorNotice](../screens.md#errornotice) |
|
|
145
|
+
|
|
146
|
+
Polite means the screen reader first finishes what it is saying. An
|
|
147
|
+
alert breaks in at once. Keep `ErrorNotice` for a failure that has to
|
|
148
|
+
stay on screen until the reader acts, as
|
|
149
|
+
[what goes in a toast](../loading-and-feedback.md#what-goes-in-a-toast)
|
|
150
|
+
explains. [Announcements](../testing.md#announcements) shows how a
|
|
151
|
+
test reads what was spoken.
|
|
152
|
+
|
|
153
|
+
## Headings
|
|
154
|
+
|
|
155
|
+
A heading is a title marked up as one, from `h1` down. A screen reader
|
|
156
|
+
can list a screen by its headings and jump between them, so every
|
|
157
|
+
title godmin draws is a real heading, `h1` to `h4`.
|
|
158
|
+
[The heading outline](./typography.md#the-heading-outline) gives the
|
|
159
|
+
level each title takes. A title keeps its size when its level
|
|
160
|
+
changes.
|
|
161
|
+
|
|
162
|
+
## Reduced motion
|
|
163
|
+
|
|
164
|
+
A reader can ask the system for less motion. Every animation in the
|
|
165
|
+
godmin stylesheet then gets shorter or stops.
|
|
166
|
+
[Reduced motion](./motion.md#reduced-motion) says what each one does.
|
|
167
|
+
|
|
168
|
+
## Text length and language
|
|
169
|
+
|
|
170
|
+
godmin draws a few words of its own, such as Back and Navigation, and
|
|
171
|
+
translates them.
|
|
172
|
+
[godmin's own words](../framing-an-application.md#godmins-own-words)
|
|
173
|
+
lists them and the languages they ship in. The props `label`,
|
|
174
|
+
`menuLabel` and `backLabel` put your own words in their place. One
|
|
175
|
+
default stays in English: the hint a toast with no action gives a
|
|
176
|
+
screen reader, until you pass `dismissLabel`, as
|
|
177
|
+
[what a screen reader hears](./toasts.md#what-a-screen-reader-hears)
|
|
178
|
+
says. Every other word comes from your app, such as the `label` of a
|
|
179
|
+
loading ghost or a count. Pass each one through your translations.
|
|
180
|
+
|
|
181
|
+
A translated label may be longer than the English one, so godmin
|
|
182
|
+
gives no label a fixed width:
|
|
183
|
+
|
|
184
|
+
- A sidebar row label takes the room its icon, count and chevron
|
|
185
|
+
leave. A longer label wraps, and the row grows, since the row sets
|
|
186
|
+
only a smallest height.
|
|
187
|
+
- A long title on a sidebar screen breaks onto the next line.
|
|
188
|
+
- A toast grows with its message, then wraps, as
|
|
189
|
+
[size](./toasts.md#size) on the toasts page shows. The aside of a
|
|
190
|
+
page and a log list break a long word the same way.
|
|
191
|
+
- The actions of a page header move under the title once they no
|
|
192
|
+
longer fit beside it. A form row and the header line of a log list
|
|
193
|
+
wrap the same way.
|
|
194
|
+
- The page tabs keep each label on one line. A tab row too long for
|
|
195
|
+
its page scrolls and fades the edge it cuts.
|
|
196
|
+
|
|
197
|
+
In a right-to-left language the chevrons, the sub menu slide and the
|
|
198
|
+
fade of the tab row turn around, as
|
|
199
|
+
[right-to-left languages](./layout.md#right-to-left-languages)
|
|
200
|
+
explains.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Color
|
|
3
|
+
description: The three seed colors behind every godmin screen, the design token that paints each part, and the contrast the tests hold.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
godmin does not pick a color for each part of the screen. It picks three seed colors and hands them to the theme provider. The theme provider is the `ThemeProvider` component of `@wordpress/theme`. A seed is a color you choose. The theme provider works out the other colors from the seeds, such as the grey of a line or of muted text. Each part of the screen then paints with a design token. A design token is a named value, such as `--wpds-color-background-surface-neutral-weak`, that the theme provider fills in. A few parts use a [raw color on purpose](#raw-colors-on-purpose).
|
|
7
|
+
|
|
8
|
+
## The three seeds
|
|
9
|
+
|
|
10
|
+
| Seed | Prop | Default |
|
|
11
|
+
| --- | --- | --- |
|
|
12
|
+
| Chrome | `chromeColor` on `Frame.Root` | `{ background: '#26292b' }` |
|
|
13
|
+
| Canvas | `canvasColor` on `Frame.Root` | `{ background: '#fcfcfc' }` |
|
|
14
|
+
| Accent | `color` on `AdminRoot` | `{ primary: '#3858e9' }` |
|
|
15
|
+
|
|
16
|
+
- The chrome is the part of the frame around the canvas: the sidebar, or on a small screen the top bar and the drawer its menu button opens. Its dark seed is godmin's own.
|
|
17
|
+
- The canvas is the panel that shows the current screen. Its seed is the design system's default background.
|
|
18
|
+
- The accent is the design system's own blue. It paints the brand tokens, such as `--wpds-color-foreground-interactive-brand`. It also paints the focus ring, `--wpds-color-stroke-focus`. The focus ring is the outline that shows which control has keyboard focus.
|
|
19
|
+
|
|
20
|
+
Each prop takes the color object of the theme provider, with a `background`, a `primary` or both. A seed must be fully opaque, such as a hex value. The theme provider throws an error on a see-through one.
|
|
21
|
+
|
|
22
|
+
A theme that names only one seed takes the other from the theme around it. With no theme around it, it takes the design system's default. So the chrome and the canvas keep the accent of `AdminRoot`. A `chromeColor` alone leaves the canvas on its default seed.
|
|
23
|
+
|
|
24
|
+
The status colors, such as the red of an error, come from the design system's own seeds. No prop changes them.
|
|
25
|
+
|
|
26
|
+
A product changes colors through these three props only. [Coloring the regions](../framing-an-application.md#coloring-the-regions) gives the greys the default seeds draw. It also says which theme dialogs and menus take.
|
|
27
|
+
|
|
28
|
+
## Which token paints each part
|
|
29
|
+
|
|
30
|
+
The [frame](./layout.md#the-frame) sets two themes. A theme is the set of token values that its seeds give. The chrome theme covers the whole frame. The canvas theme covers the canvas inside it. So one token can be dark in the sidebar and light on the canvas. The drawer opens inside the frame, so it keeps the chrome theme. The page body under the frame reads the theme of `AdminRoot`.
|
|
31
|
+
|
|
32
|
+
| Part | Token |
|
|
33
|
+
| --- | --- |
|
|
34
|
+
| Page body | `--wpds-color-background-surface-neutral` |
|
|
35
|
+
| Sidebar, top bar and drawer | `--wpds-color-background-surface-neutral-weak` |
|
|
36
|
+
| Canvas | `--wpds-color-background-surface-neutral-strong` |
|
|
37
|
+
| Text | `--wpds-color-foreground-content-neutral` |
|
|
38
|
+
| Muted text, such as the `footerNote` line of the sidebar | `--wpds-color-foreground-content-neutral-weak` |
|
|
39
|
+
| Line between parts, such as above the sidebar footer | `--wpds-color-stroke-surface-neutral` |
|
|
40
|
+
| Lighter line, such as under the page tabs or between the rows of a `godmin-table` | `--wpds-color-stroke-surface-neutral-weak` |
|
|
41
|
+
| Sidebar row | `--wpds-color-foreground-interactive-neutral-weak`, and `--wpds-color-foreground-interactive-neutral-weak-active` under the pointer or with focus |
|
|
42
|
+
| Current sidebar row | `--wpds-color-foreground-interactive-neutral-weak-active` on `--wpds-color-background-interactive-neutral-weak-active` |
|
|
43
|
+
| Menu button of the top bar | `--wpds-color-foreground-content-neutral`, and `--wpds-color-foreground-interactive-brand` on `--wpds-color-background-interactive-neutral-weak-active` under the pointer or with keyboard focus |
|
|
44
|
+
| Focus ring | `--wpds-color-stroke-focus` |
|
|
45
|
+
| Count pill | a `--wpds-color-foreground-interactive-neutral-strong` digit on `--wpds-color-background-thumb-brand` |
|
|
46
|
+
|
|
47
|
+
The count pill is the small number beside a sidebar row, as [a count beside a row](../framing-an-application.md#a-count-beside-a-row) shows. Page tabs and the `godmin-table` paint with design tokens too. [PageTabs](../screens.md#pagetabs) and [Stylesheet helpers](../screens.md#stylesheet-helpers) describe how they look.
|
|
48
|
+
|
|
49
|
+
The canvas also hands its surface to DataViews, the WordPress list component. `AdminRoot` hands the accent to DataViews and `@wordpress/components`. [The canvas colour](../lists.md#the-canvas-colour) and [the accent colour](../lists.md#the-accent-colour) explain both.
|
|
50
|
+
|
|
51
|
+
## Contrast
|
|
52
|
+
|
|
53
|
+
A contrast ratio says how far apart two colors are in lightness. The lowest is 1 to 1, a color on itself. The highest is 21 to 1, black on white. godmin's tests measure it the way WCAG does. WCAG is the Web Content Accessibility Guidelines, the common standard for accessible web pages. The tests hold two minimums:
|
|
54
|
+
|
|
55
|
+
- Text reaches 4.5 to 1 against what is behind it. The tests check the digit of the count pill in the sidebar and on the canvas, on the default seeds.
|
|
56
|
+
- A shape a reader must see reaches 3 to 1 against the surface around it. The tests check the count pill on the sidebar, the drawer, the current sidebar row and the canvas, on the default seeds.
|
|
57
|
+
|
|
58
|
+
The theme provider also checks contrast when it works out colors from a seed. It may make a seed lighter or darker to reach its targets.
|
|
59
|
+
|
|
60
|
+
## Raw colors on purpose
|
|
61
|
+
|
|
62
|
+
A raw color is a value written out, such as `#fff`, in place of a token. It stays the same whatever the seeds. `base.css` writes a few on purpose:
|
|
63
|
+
|
|
64
|
+
- A toast paints raw colors too: a see-through black box, white text and a white focus line, the colors of the WordPress snackbar. [Colors, corners and shadow](./toasts.md#colors-corners-and-shadow) gives each value.
|
|
65
|
+
- The backdrop is the dark layer behind the open drawer. It is `#000` at 0.5 opacity, as in the new WordPress admin. godmin sets the opacity through `--backdrop-opacity`. The `@wordpress/ui` drawer fades its black backdrop to that value, so the fade in and out still run.
|
|
66
|
+
- Shadows are black at a low opacity. [Elevation](./radius-and-elevation.md#elevation) lists them.
|
|
67
|
+
- The `#000` in `--godmin-page-tabs-fade` and `--godmin-page-tabs-fade-both` is a mask. The mask fades the ends of a long row of tabs. It paints nothing.
|
|
68
|
+
|
|
69
|
+
The initials avatar paints from a palette of its own, a circle color and a letter color for each entry. [Avatars](../lists.md#avatars) gives the palette and its contrast.
|
|
70
|
+
|
|
71
|
+
## No dark mode, no overrides
|
|
72
|
+
|
|
73
|
+
- godmin has no dark mode. The theme provider has no light or dark switch. The seeds decide the look. A dark chrome seed gives a dark chrome. A light canvas seed gives a light canvas.
|
|
74
|
+
- Never set a design token in your own stylesheet. The theme provider owns those values. Pass another seed instead. A stylelint rule catches a stylesheet that sets one, as [Lint your stylesheets](../build-and-versioning.md#lint-your-stylesheets) shows.
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Custom properties
|
|
3
|
+
description: godmin's own custom properties in base.css, where each one is set, and which ones an app may read or change.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
A CSS custom property is a named value, such as
|
|
7
|
+
`--godmin-canvas-margin`, that one rule sets and other rules read
|
|
8
|
+
with `var()`. Some people call it a CSS variable.
|
|
9
|
+
|
|
10
|
+
`base.css` sets a few of its own. The public ones are yours to read.
|
|
11
|
+
The ones set on `:root`, the top element of the page, are also yours
|
|
12
|
+
to change. The internal ones are not yours to read or change.
|
|
13
|
+
|
|
14
|
+
## Public custom properties
|
|
15
|
+
|
|
16
|
+
The canvas is the panel that shows the current screen.
|
|
17
|
+
[The frame](./layout.md#the-frame) and [the canvas](./layout.md#the-canvas)
|
|
18
|
+
give the four sizes below, and
|
|
19
|
+
[the sidebar slide](./motion.md#the-sidebar-slide) gives the two slide
|
|
20
|
+
values. This table says where each one is set and what it changes.
|
|
21
|
+
|
|
22
|
+
| Name | Set on | What it changes |
|
|
23
|
+
| --- | --- | --- |
|
|
24
|
+
| `--godmin-nav-sidebar-width` | `:root` | The width of the sidebar, and of the drawer that takes its place on a small screen |
|
|
25
|
+
| `--godmin-canvas-margin` | `:root` | The space around the canvas |
|
|
26
|
+
| `--godmin-canvas-gutter` | the canvas | The canvas padding left and right. A `Page` with `list` and no `aside` reaches out by it to the canvas edges |
|
|
27
|
+
| `--godmin-canvas-gutter-block` | the canvas | The canvas padding above and below. The band of notices above the screen keeps this space under it. A `Page` with `list` and no `aside` reaches down by it to the canvas bottom |
|
|
28
|
+
| `--godmin-navigation-slide-distance` | `:root` | How far a sidebar screen moves as it slides in |
|
|
29
|
+
| `--godmin-navigation-slide-duration` | `:root` | How long that slide takes |
|
|
30
|
+
|
|
31
|
+
## Where each one is set
|
|
32
|
+
|
|
33
|
+
A value set on `:root` reaches every element on the page.
|
|
34
|
+
|
|
35
|
+
To change one of the four on `:root`, write a plain rule in your own
|
|
36
|
+
stylesheet. For example, a wider sidebar:
|
|
37
|
+
|
|
38
|
+
```css
|
|
39
|
+
:root { --godmin-nav-sidebar-width: 320px }
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Your rule wins over godmin's, as
|
|
43
|
+
[changing the page appearance](../overview.md#changing-the-page-appearance)
|
|
44
|
+
explains. The sidebar and the drawer both follow it.
|
|
45
|
+
|
|
46
|
+
The canvas sets its two gutters on itself. So a gutter set on `:root`
|
|
47
|
+
changes nothing inside the canvas. Read them inside the canvas, for
|
|
48
|
+
anything that has to line up with the canvas edge.
|
|
49
|
+
|
|
50
|
+
## Internal custom properties
|
|
51
|
+
|
|
52
|
+
These serve godmin's own rules. They can change in any release, so
|
|
53
|
+
do not read or set them in your app.
|
|
54
|
+
|
|
55
|
+
- `--godmin-menu-count-size` sizes the count `MenuCount` draws. It is
|
|
56
|
+
set on the count itself.
|
|
57
|
+
- `--godmin-page-tabs-start`, `--godmin-page-tabs-end`,
|
|
58
|
+
`--godmin-page-tabs-fade-width`, `--godmin-page-tabs-fade` and
|
|
59
|
+
`--godmin-page-tabs-fade-both` fade an end of a `PageTabs` row where
|
|
60
|
+
more tabs sit out of view. They are set on the row itself.
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Layout
|
|
3
|
+
description: The areas of the frame and their sizes, the widths where they change, the spacing tokens, and how the layout reads in right-to-left languages.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
The frame is the outer layout of a godmin admin. `Frame` draws it, as
|
|
7
|
+
[Framing an application](../framing-an-application.md) shows. This
|
|
8
|
+
page gives the sizes of its areas, the widths where they change, the
|
|
9
|
+
spacing they take from the design system, and how they turn around in
|
|
10
|
+
a right-to-left language.
|
|
11
|
+
|
|
12
|
+
## The frame
|
|
13
|
+
|
|
14
|
+
The frame is as tall as the window. On a wide screen it sets two
|
|
15
|
+
areas side by side, with the names the WordPress Site Editor gives
|
|
16
|
+
them:
|
|
17
|
+
|
|
18
|
+
- The sidebar holds the menu. It is `--godmin-nav-sidebar-width`
|
|
19
|
+
(300px) wide and never shrinks. Its menu scrolls on its own, above a
|
|
20
|
+
footer that stays put.
|
|
21
|
+
- The canvas shows the screen and takes the rest of the width.
|
|
22
|
+
[The canvas](#the-canvas) gives its sizes.
|
|
23
|
+
|
|
24
|
+
Render `Frame.Sidebar` and then `Frame.Canvas` straight inside
|
|
25
|
+
`Frame.Root`, with no element of your own around them. The frame lays
|
|
26
|
+
its areas out in a row from the start edge, which is the left in
|
|
27
|
+
English, so the sidebar sits at the start.
|
|
28
|
+
|
|
29
|
+
Below `SIDEBAR_BREAKPOINT` (1024px) the frame turns into a column. A
|
|
30
|
+
top bar takes the place of the sidebar, above the canvas:
|
|
31
|
+
|
|
32
|
+
- The top bar is 46px tall. Its menu button sits at its start, in a box
|
|
33
|
+
52px wide and 46px tall. The `brand` you give `Frame.Sidebar` comes
|
|
34
|
+
8px after the button. The bar keeps 16px free at its end.
|
|
35
|
+
- The menu button opens the drawer, a panel that slides in over the
|
|
36
|
+
page. It holds the same menu and footer as the sidebar. It runs the
|
|
37
|
+
full height of the window, as wide as the sidebar but never more
|
|
38
|
+
than 85% of the window width. A dark backdrop dims the page under
|
|
39
|
+
it. [Raw colors on purpose](./color.md#raw-colors-on-purpose) gives
|
|
40
|
+
its color.
|
|
41
|
+
|
|
42
|
+
## The canvas
|
|
43
|
+
|
|
44
|
+
The canvas is a panel. Its margin is the space around it. Its gutter
|
|
45
|
+
is the padding between its edge and the screen inside it.
|
|
46
|
+
|
|
47
|
+
- The margin is `--godmin-canvas-margin` (16px). Beside the sidebar
|
|
48
|
+
the canvas has no margin on that side, because the sidebar menu
|
|
49
|
+
keeps its own space at that edge. With no sidebar on screen, as
|
|
50
|
+
under the top bar, the margin runs on all four sides.
|
|
51
|
+
- The gutter at each side is `--godmin-canvas-gutter`, 24px, or 16px
|
|
52
|
+
below `DENSE_BREAKPOINT` (640px).
|
|
53
|
+
- The gutter above and below is `--godmin-canvas-gutter-block`, set to
|
|
54
|
+
`--wpds-dimension-padding-lg` (16px).
|
|
55
|
+
- Below `EDGE_BREAKPOINT` (782px) the canvas meets the screen edges.
|
|
56
|
+
It drops its margin, its rounded corners and its shadow.
|
|
57
|
+
[Corners from the tokens](./radius-and-elevation.md#corners-from-the-tokens)
|
|
58
|
+
and [Elevation](./radius-and-elevation.md#elevation) give the
|
|
59
|
+
corners and the shadow.
|
|
60
|
+
|
|
61
|
+
The canvas scrolls its screen inside itself. A bleed canvas, which
|
|
62
|
+
`canvas="bleed"` asks for, has no gutter at any width and hides what
|
|
63
|
+
overflows it, so the screen scrolls its own parts. The default,
|
|
64
|
+
`padded`, keeps the gutters.
|
|
65
|
+
[Two canvas modes](../framing-an-application.md#two-canvas-modes)
|
|
66
|
+
says when to pick each one.
|
|
67
|
+
|
|
68
|
+
The canvas sets both gutters on itself, so read them from inside it. A
|
|
69
|
+
part that must reach the canvas edge pulls itself out by the gutter,
|
|
70
|
+
as a list page does, with
|
|
71
|
+
`margin-inline: calc(-1 * var(--godmin-canvas-gutter, 0px))`.
|
|
72
|
+
|
|
73
|
+
## Breakpoints
|
|
74
|
+
|
|
75
|
+
A breakpoint is a window width where the layout changes. godmin
|
|
76
|
+
exports each one, so your own rules can change at the same widths as
|
|
77
|
+
the frame and as WordPress. Each value is the first width that counts
|
|
78
|
+
as wide. A rule for the screens below it asks for one pixel less, as
|
|
79
|
+
`SMALL_VIEWPORT` does.
|
|
80
|
+
|
|
81
|
+
| Export | Value | What changes below it |
|
|
82
|
+
| --- | --- | --- |
|
|
83
|
+
| `HUGE_BREAKPOINT` | `1440` | Nothing in the frame. It is the WordPress huge breakpoint, for rules of your own |
|
|
84
|
+
| `SIDEBAR_BREAKPOINT` | `1024` | The sidebar becomes the top bar and the drawer |
|
|
85
|
+
| `EDGE_BREAKPOINT` | `782` | The canvas meets the screen edges. It is the WordPress medium breakpoint |
|
|
86
|
+
| `DENSE_BREAKPOINT` | `640` | The canvas side gutter narrows to 16px. A list from `useListView` takes its phone layout, as [the view in the address](../lists.md#the-view-in-the-address) shows. A table inside `godmin-table-scroll` scrolls sideways, as [stylesheet helpers](../screens.md#stylesheet-helpers) shows |
|
|
87
|
+
| `SHEET_BREAKPOINT` | `600` | Dialogs rise as sheets along the bottom of the screen and toasts widen to the screen, as [a form dialog](../lists.md#a-form-dialog) and [toasts](./toasts.md#size) show. It is the WordPress small breakpoint |
|
|
88
|
+
| `TITLE_BREAKPOINT` | `404` | Nothing in the frame. The WordPress editor drops the document title from its header here, for an editor header of your own |
|
|
89
|
+
| `SMALL_VIEWPORT` | `(max-width: 1023px)` | The media query the frame folds its sidebar at |
|
|
90
|
+
|
|
91
|
+
[What happens on a small screen](../framing-an-application.md#what-happens-on-a-small-screen)
|
|
92
|
+
shows `useMediaQuery`, which checks a media query from your own
|
|
93
|
+
components.
|
|
94
|
+
|
|
95
|
+
## Spacing
|
|
96
|
+
|
|
97
|
+
Most of godmin's spacing comes from the design system's dimension
|
|
98
|
+
tokens, its named sizes. A gap token is the space between two parts.
|
|
99
|
+
A padding token is the space between the edge of a box and what it
|
|
100
|
+
holds. godmin picks a token by the kind of space, not by its size, so
|
|
101
|
+
a margin between two parts takes a gap token too. The two scales
|
|
102
|
+
match up to `lg` and part ways from `xl` up:
|
|
103
|
+
|
|
104
|
+
| Step | Gap token | Padding token |
|
|
105
|
+
| --- | --- | --- |
|
|
106
|
+
| `xs` | `--wpds-dimension-gap-xs` (4px) | `--wpds-dimension-padding-xs` (4px) |
|
|
107
|
+
| `sm` | `--wpds-dimension-gap-sm` (8px) | `--wpds-dimension-padding-sm` (8px) |
|
|
108
|
+
| `md` | `--wpds-dimension-gap-md` (12px) | `--wpds-dimension-padding-md` (12px) |
|
|
109
|
+
| `lg` | `--wpds-dimension-gap-lg` (16px) | `--wpds-dimension-padding-lg` (16px) |
|
|
110
|
+
| `xl` | `--wpds-dimension-gap-xl` (24px) | `--wpds-dimension-padding-xl` (20px) |
|
|
111
|
+
| `2xl` | `--wpds-dimension-gap-2xl` (32px) | `--wpds-dimension-padding-2xl` (24px) |
|
|
112
|
+
| `3xl` | `--wpds-dimension-gap-3xl` (40px) | `--wpds-dimension-padding-3xl` (32px) |
|
|
113
|
+
|
|
114
|
+
A sidebar row keeps `--wpds-dimension-gap-sm` (8px) between its icon
|
|
115
|
+
and its label. When no token of the right kind holds a size, godmin
|
|
116
|
+
adds or subtracts two of them, such as
|
|
117
|
+
`calc(var(--wpds-dimension-gap-lg) + var(--wpds-dimension-gap-xs))`
|
|
118
|
+
for a 20px gap.
|
|
119
|
+
|
|
120
|
+
The frame's own sizes are plain pixels, not tokens. They are the
|
|
121
|
+
sidebar width, the canvas margin, the side gutter and the top bar.
|
|
122
|
+
The sidebar menu sets most of its spacing in plain pixels too. The
|
|
123
|
+
first three sizes have custom properties of their own, which
|
|
124
|
+
[public custom properties](./custom-properties.md#public-custom-properties)
|
|
125
|
+
lists.
|
|
126
|
+
|
|
127
|
+
## Right-to-left languages
|
|
128
|
+
|
|
129
|
+
In a right-to-left language, such as Arabic or Hebrew, text starts at
|
|
130
|
+
the right. The sidebar then sits at the right edge, and the canvas
|
|
131
|
+
drops its margin on that side. In the top bar, the menu button sits
|
|
132
|
+
at the right end.
|
|
133
|
+
|
|
134
|
+
Where a margin, a padding or a position differs between the two sides,
|
|
135
|
+
godmin's stylesheet sets it with a logical property. A logical
|
|
136
|
+
property names a side by the reading direction, start or end, in place
|
|
137
|
+
of left or right. `margin-inline-start` is the left margin in English
|
|
138
|
+
and the right margin in Arabic. Such a rule turns around with the text
|
|
139
|
+
and needs nothing more.
|
|
140
|
+
|
|
141
|
+
CSS has no logical form of a sideways slide, a gradient direction or a
|
|
142
|
+
sideways shadow. Where godmin draws one that must turn around, a
|
|
143
|
+
second rule under `:dir(rtl)`, the CSS selector for right-to-left
|
|
144
|
+
text, turns it. That covers
|
|
145
|
+
[the sidebar slide](./motion.md#the-sidebar-slide), the fade on the
|
|
146
|
+
page tabs where a tab is cut off, and the edge line of a pinned
|
|
147
|
+
actions column in a `godmin-table`.
|
|
148
|
+
|
|
149
|
+
Chevrons turn around too. A row that opens a sub menu ends in a
|
|
150
|
+
chevron that points to the end, right in English and left in a
|
|
151
|
+
right-to-left language. Back points the other way. godmin picks each
|
|
152
|
+
chevron with `isRTL()` from `@wordpress/i18n`, as WordPress does.
|
|
153
|
+
|
|
154
|
+
The stylesheet and the chevrons read the direction from two places.
|
|
155
|
+
The stylesheet follows the `dir="rtl"` your app sets on the page, such
|
|
156
|
+
as on the `html` element. The chevrons follow the translation your app
|
|
157
|
+
loads. Set both.
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Motion
|
|
3
|
+
description: The sidebar slide, the toast motion and the fades of a godmin admin, the design tokens that time them, and what changes when a reader asks for less motion.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
godmin's own motion is short and small. The sidebar slides a new
|
|
7
|
+
menu screen in. Toasts grow in and fade, and the toasts around them
|
|
8
|
+
slide along. Ghosts, the grey shapes shown
|
|
9
|
+
while data loads, fade in, and so does the content that replaces
|
|
10
|
+
them. godmin's stylesheet animates nothing else. It sets no
|
|
11
|
+
transitions, so its own hover and focus looks change at once.
|
|
12
|
+
|
|
13
|
+
Parts that WordPress packages draw keep the motion those packages
|
|
14
|
+
give them. These include the dialogs, the drawer on a small screen
|
|
15
|
+
and the bars inside a ghost.
|
|
16
|
+
|
|
17
|
+
## The tokens
|
|
18
|
+
|
|
19
|
+
A design token is a value the WordPress Design System names, written
|
|
20
|
+
as a CSS custom property. A custom property is a CSS variable. A
|
|
21
|
+
duration is how long an animation takes. An easing is the curve its
|
|
22
|
+
speed follows from start to end. godmin times its motion with five
|
|
23
|
+
design tokens:
|
|
24
|
+
|
|
25
|
+
| Token | Value | What it times |
|
|
26
|
+
| --- | --- | --- |
|
|
27
|
+
| `--wpds-motion-duration-lg` | 300ms | Toast motion, see [Motion](./toasts.md#motion) |
|
|
28
|
+
| `--wpds-motion-duration-md` | 200ms | A ghost or new content fading in |
|
|
29
|
+
| `--wpds-motion-duration-sm` | 100ms | Toast motion, see [Motion](./toasts.md#motion) |
|
|
30
|
+
| `--wpds-motion-duration-xs` | 50ms | Toast motion, see [Motion](./toasts.md#motion) |
|
|
31
|
+
| `--wpds-motion-easing-balanced` | `cubic-bezier(0.4, 0, 0.2, 1)` | The fades of ghosts and new content |
|
|
32
|
+
|
|
33
|
+
Some values have no token: the sidebar slide, the wait before a ghost
|
|
34
|
+
shows, and the rest of the toast motion. The sections below cover
|
|
35
|
+
them.
|
|
36
|
+
|
|
37
|
+
## The sidebar slide
|
|
38
|
+
|
|
39
|
+
The sidebar menu shows one screen at a time. The root screen holds
|
|
40
|
+
the main rows, and each sub menu has a screen of its own. A
|
|
41
|
+
drilldown row is a row with a chevron that opens a sub menu. Back is
|
|
42
|
+
the link in the title row of a sub menu. When a drilldown row or Back
|
|
43
|
+
changes the screen, the new screen slides in:
|
|
44
|
+
|
|
45
|
+
- It starts `--godmin-navigation-slide-distance` (50px) to one side
|
|
46
|
+
and moves into place. As it moves, it fades from transparent to
|
|
47
|
+
fully visible.
|
|
48
|
+
- It takes `--godmin-navigation-slide-duration` (140ms). Its speed
|
|
49
|
+
follows the CSS `ease-in-out` curve, which starts slow and ends
|
|
50
|
+
slow. It plays once, with no delay.
|
|
51
|
+
- A sub menu comes in from the side the text ends on. That is the
|
|
52
|
+
right in a left-to-right language and the left in a right-to-left
|
|
53
|
+
one. Back brings the screen in from the other side.
|
|
54
|
+
[Right-to-left languages](./layout.md#right-to-left-languages) says
|
|
55
|
+
where godmin reads the direction from.
|
|
56
|
+
|
|
57
|
+
These are the numbers the WordPress Site Editor uses for its own
|
|
58
|
+
sidebar slide.
|
|
59
|
+
|
|
60
|
+
The slide plays only after a drilldown row or Back. It does not play
|
|
61
|
+
on the first load, after a row that keeps the same screen, after a
|
|
62
|
+
link elsewhere on the page, or after the browser's Back button. A
|
|
63
|
+
sub menu whose code loads late slides in once that code has arrived.
|
|
64
|
+
|
|
65
|
+
Only the screen moves. The sidebar footer stays still under it, and
|
|
66
|
+
the sidebar hides anything that slides past its sides.
|
|
67
|
+
[Where focus goes](./accessibility.md#where-focus-goes) says where
|
|
68
|
+
the focus lands after the slide.
|
|
69
|
+
|
|
70
|
+
You may change the slide through its two custom properties.
|
|
71
|
+
[Where each one is set](./custom-properties.md#where-each-one-is-set)
|
|
72
|
+
shows how.
|
|
73
|
+
|
|
74
|
+
## Toasts
|
|
75
|
+
|
|
76
|
+
Toasts move as the WordPress snackbar does. An arriving toast grows
|
|
77
|
+
its space in the column and fades in. A leaving toast fades out, then
|
|
78
|
+
its space closes. So the other toasts slide instead of jumping.
|
|
79
|
+
[Motion](./toasts.md#motion) on the toasts page gives every duration
|
|
80
|
+
and curve, and says what a leaving toast does.
|
|
81
|
+
|
|
82
|
+
## Loading
|
|
83
|
+
|
|
84
|
+
`LoadingScreen` and `LoadingRows` draw the ghosts, as
|
|
85
|
+
[the ghosts](../loading-and-feedback.md#the-ghosts) shows.
|
|
86
|
+
|
|
87
|
+
A ghost starts transparent. It waits a short delay, then fades in and
|
|
88
|
+
stays visible. A load that ends within the delay shows no ghost at
|
|
89
|
+
all.
|
|
90
|
+
[Why a ghost does not appear immediately](../loading-and-feedback.md#why-a-ghost-does-not-appear-immediately)
|
|
91
|
+
gives the delay and the reason for it. The bars inside a ghost are
|
|
92
|
+
the `Skeleton` of `@wordpress/ui`, and they pulse the way that
|
|
93
|
+
package pulses them.
|
|
94
|
+
|
|
95
|
+
Content with the `godmin-arrival` class fades in the same way, with
|
|
96
|
+
no delay.
|
|
97
|
+
[Fading the content in](../loading-and-feedback.md#fading-the-content-in)
|
|
98
|
+
shows where to put the class.
|
|
99
|
+
|
|
100
|
+
## Reduced motion
|
|
101
|
+
|
|
102
|
+
A reader can ask their system for less motion. The browser then
|
|
103
|
+
reports `prefers-reduced-motion: reduce` to CSS, and godmin changes
|
|
104
|
+
two things:
|
|
105
|
+
|
|
106
|
+
- The fades of ghosts and new content last 1ms. They still run and
|
|
107
|
+
still end. So a ghost still waits its delay and then stays visible.
|
|
108
|
+
- Every toast animation lasts 1ms and starts at once, with no wait.
|
|
109
|
+
It still runs and still ends, so a leaving toast still goes. A toast
|
|
110
|
+
shows in its place at once and goes at once, and the toasts above
|
|
111
|
+
move in one step, as in WordPress.
|
|
112
|
+
- The sidebar slide lasts 0s, as in the WordPress Site Editor, even
|
|
113
|
+
when you set your own slide duration. It does not play, and the new
|
|
114
|
+
screen shows at once in its place.
|
|
115
|
+
|
|
116
|
+
These rules keep each animation itself and the setting that holds a
|
|
117
|
+
ghost visible after its fade. They keep the delay of a ghost too.
|
|
118
|
+
Turning an animation off would leave a ghost transparent for good.
|
|
119
|
+
|
|
120
|
+
The bars inside a ghost stop their pulse too. Their WordPress
|
|
121
|
+
package does that on its own.
|