@gopherium/godmin 0.26.0 → 0.27.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 -14
- 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/unsaved-text.d.ts +14 -0
- package/dist/unsaved-text.js +25 -0
- package/docs/build-and-versioning.md +190 -0
- package/docs/design-system/accessibility.md +206 -0
- package/docs/design-system/color.md +74 -0
- package/docs/design-system/custom-properties.md +63 -0
- package/docs/design-system/layout.md +157 -0
- package/docs/design-system/motion.md +116 -0
- package/docs/design-system/overview.md +101 -0
- package/docs/design-system/radius-and-elevation.md +129 -0
- package/docs/design-system/typography.md +83 -0
- package/docs/framing-an-application.md +386 -0
- package/docs/lists.md +1511 -0
- package/docs/loading-and-feedback.md +207 -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,190 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Build configuration and versioning
|
|
3
|
+
description: The Vite config godmin needs and the design system versions it supports.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Most of what godmin needs from your build is this config:
|
|
7
|
+
|
|
8
|
+
```ts
|
|
9
|
+
import { godminDedupe, godminSingleCopy, godminStylesheetFirst } from '@gopherium/godmin/vite'
|
|
10
|
+
|
|
11
|
+
export default defineConfig({
|
|
12
|
+
resolve: { dedupe: godminDedupe },
|
|
13
|
+
plugins: [godminSingleCopy(), godminStylesheetFirst()],
|
|
14
|
+
})
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
This page explains what each part does, then covers stylesheet
|
|
18
|
+
linting and versioning.
|
|
19
|
+
|
|
20
|
+
## One copy of each shared package
|
|
21
|
+
|
|
22
|
+
Your bundle must contain exactly one copy of React and of each
|
|
23
|
+
package `godminDedupe` lists. Two copies of React crash on the first
|
|
24
|
+
hook. Two copies of these fail with no error:
|
|
25
|
+
|
|
26
|
+
- `@wordpress/theme` renders components unthemed.
|
|
27
|
+
- `@wordpress/i18n` renders English. [One copy of the
|
|
28
|
+
runtime](https://docs.gopherium.org/translations/health/#one-copy-of-the-runtime) explains why.
|
|
29
|
+
- `@wordpress/date` leaves the DataViews date filters in English, on
|
|
30
|
+
the wrong clock. The [list dates](./lists.md#dates-in-a-list)
|
|
31
|
+
set up one copy, and the filters read the other.
|
|
32
|
+
- `@gopherium/react-auth` keeps a
|
|
33
|
+
[configured transport](https://docs.gopherium.org/authentication/react-integration/#one-setting-for-the-whole-module)
|
|
34
|
+
that half the app cannot see.
|
|
35
|
+
|
|
36
|
+
The config handles this twice:
|
|
37
|
+
|
|
38
|
+
- `godminDedupe` makes Vite resolve each listed package once.
|
|
39
|
+
- `godminSingleCopy()` fails the build, naming the package and both
|
|
40
|
+
paths, if a duplicate got through anyway.
|
|
41
|
+
|
|
42
|
+
## Paint sooner
|
|
43
|
+
|
|
44
|
+
Nothing renders until your stylesheet arrives, and bundlers request
|
|
45
|
+
it after the JavaScript. `godminStylesheetFirst()` moves it first.
|
|
46
|
+
|
|
47
|
+
How much that helps depends on how much JavaScript competes with it.
|
|
48
|
+
In one app with eight preloads it cut the blank page from 1.9s to
|
|
49
|
+
1.3s. In another with two preloads it changed nothing, because
|
|
50
|
+
nothing was queueing. It costs nothing at runtime, so leave it on
|
|
51
|
+
and let it matter as your bundle grows.
|
|
52
|
+
|
|
53
|
+
On a bundler that is not Vite or Rollup, the underlying functions
|
|
54
|
+
`duplicateCopies` and `hoistStylesheet` are exported so you can wire
|
|
55
|
+
both checks into whatever hooks it offers.
|
|
56
|
+
|
|
57
|
+
## Lint your stylesheets
|
|
58
|
+
|
|
59
|
+
`@wordpress/theme` ships three stylelint rules. This turns them on:
|
|
60
|
+
|
|
61
|
+
```js
|
|
62
|
+
export default { extends: ['@gopherium/godmin/stylelint'] }
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
They catch design tokens that do not exist (a typo renders nothing,
|
|
66
|
+
with no error), redefined `--wpds-` properties, and hand-typed
|
|
67
|
+
fallback values.
|
|
68
|
+
|
|
69
|
+
## Design system versions
|
|
70
|
+
|
|
71
|
+
Each godmin release supports one design system window, written out
|
|
72
|
+
in full in its peer ranges as the first version it accepts and the
|
|
73
|
+
first one it refuses, such as `>=0.24.0 <0.25.0`. The window moves
|
|
74
|
+
forward with the design system and never widens, so no release
|
|
75
|
+
accepts two incompatible generations at once.
|
|
76
|
+
|
|
77
|
+
The window is exported for your tests:
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
import { SUPPORTED_WPDS } from '@gopherium/godmin'
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
`SUPPORTED_WPDS` names the `@wordpress/ui` and `@wordpress/theme`
|
|
84
|
+
windows only. The other design system peers, `@wordpress/icons`,
|
|
85
|
+
`@wordpress/a11y` and `@wordpress/style-runtime`, have their windows
|
|
86
|
+
in the peer ranges of godmin's `package.json`.
|
|
87
|
+
|
|
88
|
+
`@wordpress/i18n` is a required peer, because the main entry
|
|
89
|
+
translates godmin's own words. `@wordpress/date` is an optional peer,
|
|
90
|
+
needed only by `@gopherium/godmin/dates`. `@wordpress/components` is
|
|
91
|
+
an optional peer too, needed only by `@gopherium/godmin/dialogs`, in
|
|
92
|
+
the window `>=42.0.0 <43.0.0`. Install each one next to godmin when
|
|
93
|
+
you use its entry. Load the components stylesheet once in your
|
|
94
|
+
application, `@wordpress/components/build-style/style.css`, as
|
|
95
|
+
DataViews already asks. godmin never imports it. Their windows are in
|
|
96
|
+
the same peer ranges.
|
|
97
|
+
|
|
98
|
+
`@wordpress/dataviews` is an optional peer as well, in the window
|
|
99
|
+
`>=20.0.0 <21.0.0`. No godmin entry imports it, but `offeredView`
|
|
100
|
+
follows the filter rules of that DataViews release. A list built on
|
|
101
|
+
another release gets a peer warning when it installs godmin.
|
|
102
|
+
|
|
103
|
+
## Upgrading from godmin 0.24.0
|
|
104
|
+
|
|
105
|
+
godmin 0.25.0 gives the sidebar parts the names WordPress gives them.
|
|
106
|
+
TypeScript points at each old name, and
|
|
107
|
+
[the changelog](https://github.com/gopherium/godmin/blob/main/CHANGELOG.md)
|
|
108
|
+
lists every new one. Change your code in these places too:
|
|
109
|
+
|
|
110
|
+
- Install `@wordpress/i18n` next to godmin, and take
|
|
111
|
+
`@tanstack/react-router` 1.170.44 or a newer 1.x release.
|
|
112
|
+
- `NavigationScreen` draws its title as an `h1` and no longer moves
|
|
113
|
+
the focus to it. Pass `headingLevel={2}` to every `Page` beside it,
|
|
114
|
+
as [heading levels](./screens.md#heading-levels) explains.
|
|
115
|
+
- The sidebar and the drawer have no padding of their own. A sidebar
|
|
116
|
+
screen pads its rows.
|
|
117
|
+
- A stylesheet that reads the sidebar width reads
|
|
118
|
+
`--godmin-nav-sidebar-width`.
|
|
119
|
+
- A stylesheet that styles the sidebar slot or a sidebar screen reads
|
|
120
|
+
`.godmin-layout__sidebar` and the `.godmin-navigation-screen`
|
|
121
|
+
classes.
|
|
122
|
+
- The phone menu button is named "Open navigation panel" by default.
|
|
123
|
+
A test that finds it by its old name, "Open navigation", finds it by
|
|
124
|
+
the new one.
|
|
125
|
+
- `PageTabs` draws its tabs as a `ul` list, one `li` per tab, and its
|
|
126
|
+
`.godmin-page-tabs` class sits on that list. A stylesheet that
|
|
127
|
+
styles the tabs by the `nav` reads the list.
|
|
128
|
+
- `useUnsavedText` and `markLatest` came in 0.24.1 and come back in
|
|
129
|
+
0.27.0. 0.25.0 and 0.26.0 do not have them, so an app that uses them
|
|
130
|
+
on 0.24.1 moves straight to 0.27.0 or later.
|
|
131
|
+
|
|
132
|
+
## Upgrading from godmin 0.22.0
|
|
133
|
+
|
|
134
|
+
godmin 0.23.0 shows every failed write in a toast, never inside a
|
|
135
|
+
dialog or above the list, as WordPress does. Take 0.23.1 or later,
|
|
136
|
+
which lets a dialog take a write's promise whether the write
|
|
137
|
+
succeeds or fails. Change your code in these places:
|
|
138
|
+
|
|
139
|
+
- `ConfirmDialog`'s `onConfirm` no longer answers a failure to show.
|
|
140
|
+
To close the dialog at once, make it a plain function that returns
|
|
141
|
+
nothing, and drop the `async` your old handler needed. An `async`
|
|
142
|
+
function always returns a promise. Return the write's promise to
|
|
143
|
+
keep the dialog busy until the write ends. Escape, a click outside
|
|
144
|
+
it and its close button now close it even while it works.
|
|
145
|
+
- `ConfirmBody` and `RenameBody` no longer take `failure`, and
|
|
146
|
+
`RenameBody` no longer takes `busy`. Close a rename when the reader
|
|
147
|
+
presses Save, then write. `RenameBody` also sends a name left as it
|
|
148
|
+
was, and stops only a blank one.
|
|
149
|
+
- `useListRun` no longer answers `failure`, so drop the notice you
|
|
150
|
+
showed above the list. The function that `run.onStart()` answers
|
|
151
|
+
now takes only whether a row moved.
|
|
152
|
+
- `useBulkRun` toasts your `failed` words when a row failed, in place
|
|
153
|
+
of the `done` words.
|
|
154
|
+
|
|
155
|
+
TypeScript points at each prop and field that went away, at an
|
|
156
|
+
`onConfirm` that answers a failure and at a run settled with a
|
|
157
|
+
failure. The rest changes only what the reader sees. In each case,
|
|
158
|
+
show the failure in a toast, as
|
|
159
|
+
[a failure from a dialog](./lists.md#a-failure-from-a-dialog)
|
|
160
|
+
shows.
|
|
161
|
+
|
|
162
|
+
## Upgrading from godmin 0.19.0
|
|
163
|
+
|
|
164
|
+
`startListDates` and `listDate` left the main entry. Import them from
|
|
165
|
+
`@gopherium/godmin/dates`:
|
|
166
|
+
|
|
167
|
+
```ts
|
|
168
|
+
import { listDate, startListDates } from '@gopherium/godmin/dates'
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Keep `@wordpress/date` and `@wordpress/i18n` installed next to godmin
|
|
172
|
+
while you use them.
|
|
173
|
+
|
|
174
|
+
## Upgrading from godmin 0.7.0
|
|
175
|
+
|
|
176
|
+
godmin 0.7.0 and older asked you to copy a patch for
|
|
177
|
+
`@wordpress/element`. Newer releases support design system versions
|
|
178
|
+
that bring `@wordpress/element` 8.7.0 or newer, which needs no patch.
|
|
179
|
+
|
|
180
|
+
Delete the patch file, its `patchedDependencies` entry and any build
|
|
181
|
+
step that copies it. If your `package.json` lists
|
|
182
|
+
`@wordpress/element`, move it to 8.7.0 too. A leftover entry makes
|
|
183
|
+
`pnpm install` stop with `ERR_PNPM_UNUSED_PATCH`.
|
|
184
|
+
|
|
185
|
+
## License
|
|
186
|
+
|
|
187
|
+
godmin is Apache-2.0. The design system packages are
|
|
188
|
+
GPL-2.0-or-later and are peer dependencies: your application
|
|
189
|
+
installs them, godmin never redistributes them. Your built bundle
|
|
190
|
+
combines both and is conveyed under the WordPress packages' terms.
|
|
@@ -0,0 +1,206 @@
|
|
|
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 [toasts](../loading-and-feedback.md#toasts) lists. A plain toast and its close button keep 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, because only code ever
|
|
52
|
+
focuses it. Draw a ring of your own with the same line, on
|
|
53
|
+
`:focus-visible`, so it matches.
|
|
54
|
+
|
|
55
|
+
## Where focus goes
|
|
56
|
+
|
|
57
|
+
In the sidebar menu, a drilldown row is a row that opens a sub menu.
|
|
58
|
+
The drawer is the panel that holds the sidebar on a small screen. The
|
|
59
|
+
sidebar moves focus in these cases only:
|
|
60
|
+
|
|
61
|
+
| The reader | Focus goes to |
|
|
62
|
+
| --- | --- |
|
|
63
|
+
| 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 |
|
|
64
|
+
| 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 |
|
|
65
|
+
| Opens a page with any other link | Nowhere. The sidebar moves no focus |
|
|
66
|
+
| Closes the drawer with Escape or its close button | The menu button |
|
|
67
|
+
|
|
68
|
+
The title of a sidebar screen never takes focus.
|
|
69
|
+
|
|
70
|
+
Some parts go away while they hold focus. godmin then moves focus to
|
|
71
|
+
a part that stays, so the keyboard reader keeps their place:
|
|
72
|
+
|
|
73
|
+
- A toast that leaves, as
|
|
74
|
+
[how a toast behaves](../loading-and-feedback.md#how-a-toast-behaves)
|
|
75
|
+
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 or a cross, 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 cross on a toast is named by `dismissLabel`, never read as a
|
|
117
|
+
cross.
|
|
118
|
+
- The initials avatar is hidden, because the name beside it already
|
|
119
|
+
says who it is.
|
|
120
|
+
|
|
121
|
+
The current page carries `aria-current="page"`. A sidebar row draws
|
|
122
|
+
its highlight from that mark, so what the eye sees and what a screen
|
|
123
|
+
reader hears always match. A page tab draws its underline from its
|
|
124
|
+
`current` prop, which sets the same mark. A router link can set the
|
|
125
|
+
mark on its own too, so [PageTabs](../screens.md#pagetabs) says how
|
|
126
|
+
to keep the underline and the mark in step.
|
|
127
|
+
|
|
128
|
+
Some screen readers stop treating a list with no bullets as a list.
|
|
129
|
+
So the sidebar rows, the page tabs and a log list keep
|
|
130
|
+
`role="list"`.
|
|
131
|
+
|
|
132
|
+
## What a screen reader hears
|
|
133
|
+
|
|
134
|
+
godmin gives a sentence for the ear wherever the eye gets a shape, a
|
|
135
|
+
glyph or a bare number. Visually hidden text is text on the page that
|
|
136
|
+
only a screen reader meets. Some things appear without the reader
|
|
137
|
+
moving to them, such as a toast or a loading ghost. A screen reader
|
|
138
|
+
learns of those through a live region, a part of the page it reads
|
|
139
|
+
aloud when it changes.
|
|
140
|
+
|
|
141
|
+
| Part | What a screen reader hears | Set up in |
|
|
142
|
+
| --- | --- | --- |
|
|
143
|
+
| A toast | Its message, politely. Never its buttons | [How a toast behaves](../loading-and-feedback.md#how-a-toast-behaves) |
|
|
144
|
+
| A loading ghost | The `label` sentence, from a visually hidden status. The grey shapes are hidden | [The ghosts](../loading-and-feedback.md#the-ghosts) |
|
|
145
|
+
| 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) |
|
|
146
|
+
| An `ErrorNotice` | Its message, at once, as an alert | [ErrorNotice](../screens.md#errornotice) |
|
|
147
|
+
|
|
148
|
+
Polite means the screen reader first finishes what it is saying. An
|
|
149
|
+
alert breaks in at once. Keep `ErrorNotice` for a failure that has to
|
|
150
|
+
stay on screen until the reader acts, as
|
|
151
|
+
[what goes in a toast](../loading-and-feedback.md#what-goes-in-a-toast)
|
|
152
|
+
explains. [Announcements](../testing.md#announcements) shows how a
|
|
153
|
+
test reads what was spoken.
|
|
154
|
+
|
|
155
|
+
## Headings
|
|
156
|
+
|
|
157
|
+
A heading is a title marked up as one, from `h1` down. A screen reader
|
|
158
|
+
can list a screen by its headings and jump between them, so every
|
|
159
|
+
title godmin draws is a real heading, `h1` to `h4`.
|
|
160
|
+
[The heading outline](./typography.md#the-heading-outline) gives the
|
|
161
|
+
level each title takes. A title keeps its size when its level
|
|
162
|
+
changes.
|
|
163
|
+
|
|
164
|
+
## Reduced motion
|
|
165
|
+
|
|
166
|
+
A reader can ask the system for less motion. Every animation in the
|
|
167
|
+
godmin stylesheet then gets shorter or stops.
|
|
168
|
+
[Reduced motion](./motion.md#reduced-motion) says what each one does.
|
|
169
|
+
|
|
170
|
+
## Text length and language
|
|
171
|
+
|
|
172
|
+
godmin draws a few words of its own, such as Back and Navigation, and
|
|
173
|
+
translates them.
|
|
174
|
+
[godmin's own words](../framing-an-application.md#godmins-own-words)
|
|
175
|
+
lists them and the languages they ship in. The props `label`,
|
|
176
|
+
`menuLabel` and `backLabel` put your own words in their place. One
|
|
177
|
+
default stays in English: the close button of a toast is named
|
|
178
|
+
Dismiss until you pass `dismissLabel`, as
|
|
179
|
+
[how a toast behaves](../loading-and-feedback.md#how-a-toast-behaves)
|
|
180
|
+
says. Every other word comes from your app, such as the `label` of a
|
|
181
|
+
loading ghost or a count. Pass each one through your translations.
|
|
182
|
+
|
|
183
|
+
A translated label may be longer than the English one, so godmin
|
|
184
|
+
gives no label a fixed width:
|
|
185
|
+
|
|
186
|
+
- A sidebar row label takes the room its icon, count and chevron
|
|
187
|
+
leave. A longer label wraps, and the row grows, since the row sets
|
|
188
|
+
only a smallest height.
|
|
189
|
+
- A long title on a sidebar screen breaks onto the next line.
|
|
190
|
+
- A toast grows with its message up to its widest, then wraps, even
|
|
191
|
+
inside a long word. The aside of a page and a log list break a long
|
|
192
|
+
word the same way.
|
|
193
|
+
- The actions of a page header move under the title once they no
|
|
194
|
+
longer fit beside it. A form row and the header line of a log list
|
|
195
|
+
wrap the same way.
|
|
196
|
+
- The page tabs keep each label on one line. A tab row too long for
|
|
197
|
+
its page scrolls and fades the edge it cuts.
|
|
198
|
+
- Where a toast cuts a name, it counts the characters a reader sees,
|
|
199
|
+
so an emoji is never split.
|
|
200
|
+
[Naming an item in a toast](../lists.md#naming-an-item-in-a-toast)
|
|
201
|
+
shows it.
|
|
202
|
+
|
|
203
|
+
In a right-to-left language the chevrons, the sub menu slide and the
|
|
204
|
+
fade of the tab row turn around, as
|
|
205
|
+
[right-to-left languages](./layout.md#right-to-left-languages)
|
|
206
|
+
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
|
+
- The toast box is `rgb(0 0 0 / 0.85)`, a black that lets a blur of the page show through. Its text and its focus lines are `#fff`. These are the colors of the WordPress snackbar. [Toasts](../loading-and-feedback.md#toasts) describes the rest of the toast.
|
|
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,63 @@
|
|
|
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. So the
|
|
34
|
+
toast region reads the sidebar width and the canvas margin too. When
|
|
35
|
+
the sidebar is on screen, the region starts after it and ends where
|
|
36
|
+
the canvas ends, so the toasts stay centered on the canvas.
|
|
37
|
+
|
|
38
|
+
To change one of the four on `:root`, write a plain rule in your own
|
|
39
|
+
stylesheet. For example, a wider sidebar:
|
|
40
|
+
|
|
41
|
+
```css
|
|
42
|
+
:root { --godmin-nav-sidebar-width: 320px }
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Your rule wins over godmin's, as
|
|
46
|
+
[changing the page appearance](../overview.md#changing-the-page-appearance)
|
|
47
|
+
explains. The sidebar, the drawer and the toast region all follow it.
|
|
48
|
+
|
|
49
|
+
The canvas sets its two gutters on itself. So a gutter set on `:root`
|
|
50
|
+
changes nothing inside the canvas. Read them inside the canvas, for
|
|
51
|
+
anything that has to line up with the canvas edge.
|
|
52
|
+
|
|
53
|
+
## Internal custom properties
|
|
54
|
+
|
|
55
|
+
These serve godmin's own rules. They can change in any release, so
|
|
56
|
+
do not read or set them in your app.
|
|
57
|
+
|
|
58
|
+
- `--godmin-menu-count-size` sizes the count `MenuCount` draws. It is
|
|
59
|
+
set on the count itself.
|
|
60
|
+
- `--godmin-page-tabs-start`, `--godmin-page-tabs-end`,
|
|
61
|
+
`--godmin-page-tabs-fade-width`, `--godmin-page-tabs-fade` and
|
|
62
|
+
`--godmin-page-tabs-fade-both` fade an end of a `PageTabs` row where
|
|
63
|
+
more tabs sit out of view. They are set on the row itself.
|