@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.
@@ -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.