@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,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](../loading-and-feedback.md#toasts) 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,116 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Motion
|
|
3
|
+
description: The sidebar slide 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 fade in and out. Ghosts, the grey shapes shown
|
|
8
|
+
while data loads, fade in, and so does the content that replaces
|
|
9
|
+
them. godmin's stylesheet animates nothing else. It sets no
|
|
10
|
+
transitions, so its own hover and focus looks change at once.
|
|
11
|
+
|
|
12
|
+
Parts that WordPress packages draw keep the motion those packages
|
|
13
|
+
give them. These include the dialogs, the drawer on a small screen
|
|
14
|
+
and the bars inside a ghost.
|
|
15
|
+
|
|
16
|
+
## The tokens
|
|
17
|
+
|
|
18
|
+
A design token is a value the WordPress Design System names, written
|
|
19
|
+
as a CSS custom property. A custom property is a CSS variable. A
|
|
20
|
+
duration is how long an animation takes. An easing is the curve its
|
|
21
|
+
speed follows from start to end. godmin times its fades with three
|
|
22
|
+
design tokens:
|
|
23
|
+
|
|
24
|
+
| Token | Value | What it times |
|
|
25
|
+
| --- | --- | --- |
|
|
26
|
+
| `--wpds-motion-duration-md` | 200ms | A toast, a ghost or new content fading in |
|
|
27
|
+
| `--wpds-motion-duration-sm` | 100ms | A toast fading out |
|
|
28
|
+
| `--wpds-motion-easing-balanced` | `cubic-bezier(0.4, 0, 0.2, 1)` | Every fade |
|
|
29
|
+
|
|
30
|
+
Two lengths have no token: the sidebar slide and the wait before a
|
|
31
|
+
ghost shows. The sections below cover both.
|
|
32
|
+
|
|
33
|
+
## The sidebar slide
|
|
34
|
+
|
|
35
|
+
The sidebar menu shows one screen at a time. The root screen holds
|
|
36
|
+
the main rows, and each sub menu has a screen of its own. A
|
|
37
|
+
drilldown row is a row with a chevron that opens a sub menu. Back is
|
|
38
|
+
the link in the title row of a sub menu. When a drilldown row or Back
|
|
39
|
+
changes the screen, the new screen slides in:
|
|
40
|
+
|
|
41
|
+
- It starts `--godmin-navigation-slide-distance` (50px) to one side
|
|
42
|
+
and moves into place. As it moves, it fades from transparent to
|
|
43
|
+
fully visible.
|
|
44
|
+
- It takes `--godmin-navigation-slide-duration` (140ms). Its speed
|
|
45
|
+
follows the CSS `ease-in-out` curve, which starts slow and ends
|
|
46
|
+
slow. It plays once, with no delay.
|
|
47
|
+
- A sub menu comes in from the side the text ends on. That is the
|
|
48
|
+
right in a left-to-right language and the left in a right-to-left
|
|
49
|
+
one. Back brings the screen in from the other side.
|
|
50
|
+
[Right-to-left languages](./layout.md#right-to-left-languages) says
|
|
51
|
+
where godmin reads the direction from.
|
|
52
|
+
|
|
53
|
+
These are the numbers the WordPress Site Editor uses for its own
|
|
54
|
+
sidebar slide.
|
|
55
|
+
|
|
56
|
+
The slide plays only after a drilldown row or Back. It does not play
|
|
57
|
+
on the first load, after a row that keeps the same screen, after a
|
|
58
|
+
link elsewhere on the page, or after the browser's Back button. A
|
|
59
|
+
sub menu whose code loads late slides in once that code has arrived.
|
|
60
|
+
|
|
61
|
+
Only the screen moves. The sidebar footer stays still under it, and
|
|
62
|
+
the sidebar hides anything that slides past its sides.
|
|
63
|
+
[Where focus goes](./accessibility.md#where-focus-goes) says where
|
|
64
|
+
the focus lands after the slide.
|
|
65
|
+
|
|
66
|
+
You may change the slide through its two custom properties.
|
|
67
|
+
[Where each one is set](./custom-properties.md#where-each-one-is-set)
|
|
68
|
+
shows how.
|
|
69
|
+
|
|
70
|
+
## Toasts
|
|
71
|
+
|
|
72
|
+
A toast fades in when it arrives. When it leaves, it fades out and
|
|
73
|
+
stays hidden at the end. A leaving toast stays on the page until its
|
|
74
|
+
fade ends. Nobody can press it in that time. If the browser cuts the
|
|
75
|
+
fade short, the toast still goes.
|
|
76
|
+
[How a toast behaves](../loading-and-feedback.md#how-a-toast-behaves)
|
|
77
|
+
says how long a toast stays before it leaves.
|
|
78
|
+
|
|
79
|
+
## Loading
|
|
80
|
+
|
|
81
|
+
`LoadingScreen` and `LoadingRows` draw the ghosts, as
|
|
82
|
+
[the ghosts](../loading-and-feedback.md#the-ghosts) shows.
|
|
83
|
+
|
|
84
|
+
A ghost starts transparent. It waits a short delay, then fades in and
|
|
85
|
+
stays visible. A load that ends within the delay shows no ghost at
|
|
86
|
+
all.
|
|
87
|
+
[Why a ghost does not appear immediately](../loading-and-feedback.md#why-a-ghost-does-not-appear-immediately)
|
|
88
|
+
gives the delay and the reason for it. The bars inside a ghost are
|
|
89
|
+
the `Skeleton` of `@wordpress/ui`, and they pulse the way that
|
|
90
|
+
package pulses them.
|
|
91
|
+
|
|
92
|
+
Content with the `godmin-arrival` class fades in the same way, with
|
|
93
|
+
no delay.
|
|
94
|
+
[Fading the content in](../loading-and-feedback.md#fading-the-content-in)
|
|
95
|
+
shows where to put the class.
|
|
96
|
+
|
|
97
|
+
## Reduced motion
|
|
98
|
+
|
|
99
|
+
A reader can ask their system for less motion. The browser then
|
|
100
|
+
reports `prefers-reduced-motion: reduce` to CSS, and godmin changes
|
|
101
|
+
two things:
|
|
102
|
+
|
|
103
|
+
- The fades of toasts, ghosts and new content last 1ms. They still
|
|
104
|
+
run and still end. So a leaving toast still goes, and a ghost
|
|
105
|
+
still waits its delay and then stays visible.
|
|
106
|
+
- The sidebar slide lasts 0s, as in the WordPress Site Editor, even
|
|
107
|
+
when you set your own slide duration. It does not play, and the new
|
|
108
|
+
screen shows at once in its place.
|
|
109
|
+
|
|
110
|
+
These rules change only how long each animation lasts. They keep
|
|
111
|
+
the delay, the animation itself, and the setting that holds a ghost
|
|
112
|
+
visible after its fade. Turning the animation off would leave a
|
|
113
|
+
ghost transparent for good.
|
|
114
|
+
|
|
115
|
+
The bars inside a ghost stop their pulse too. Their WordPress
|
|
116
|
+
package does that on its own.
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Design System
|
|
3
|
+
description: The rules for how an admin built on godmin looks, where its colors come from, and how to read a design token name.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
The Design System is the set of rules for how an admin built on
|
|
7
|
+
godmin looks. It says where each part of the screen sits, how big
|
|
8
|
+
things are, how they move and which colors they take. A new product
|
|
9
|
+
can follow these pages without reading any godmin code.
|
|
10
|
+
|
|
11
|
+
These pages hold the values the whole admin shares. A value that
|
|
12
|
+
belongs to one part, such as the size of a
|
|
13
|
+
[toast](../loading-and-feedback.md#toasts), sits on the page that
|
|
14
|
+
shows how to use that part.
|
|
15
|
+
|
|
16
|
+
godmin builds on the WordPress Design System, WPDS for short. For
|
|
17
|
+
layout, sizes and motion it follows WordPress's new admin and the
|
|
18
|
+
Site Editor. Colors work another way. They come from three seeds. A
|
|
19
|
+
seed is one color you hand the design system, and the design system
|
|
20
|
+
works out every shade it needs from it:
|
|
21
|
+
|
|
22
|
+
- The chrome seed paints the chrome, the part of the
|
|
23
|
+
[frame](./layout.md#the-frame) around your screens. That is the
|
|
24
|
+
sidebar, or the top bar and its drawer on a small screen.
|
|
25
|
+
- The canvas seed paints the canvas, the panel that shows the current
|
|
26
|
+
screen.
|
|
27
|
+
- The accent is the color of primary buttons, selected rows and
|
|
28
|
+
focus rings.
|
|
29
|
+
|
|
30
|
+
Each seed has a prop of its own. A product changes colors only
|
|
31
|
+
through these three props. It never sets a design token itself.
|
|
32
|
+
[The three seeds](./color.md#the-three-seeds) names each prop and its
|
|
33
|
+
default.
|
|
34
|
+
|
|
35
|
+
## Reading a token name
|
|
36
|
+
|
|
37
|
+
A design token is a named value, such as a color or a size. WPDS
|
|
38
|
+
ships each token as a CSS custom property, a variable your CSS reads
|
|
39
|
+
with `var()`. The name is made of parts, read from left to right.
|
|
40
|
+
Take `--wpds-dimension-gap-md`:
|
|
41
|
+
|
|
42
|
+
- `--wpds-` marks a token of the design system.
|
|
43
|
+
- `dimension` is the kind of value, here a length. The other kinds
|
|
44
|
+
are `color`, `border`, `typography`, `motion` and `cursor`.
|
|
45
|
+
- `gap` is what it sets, the space between items.
|
|
46
|
+
- `md` is its step on the size scale, medium. Steps such as `sm` and
|
|
47
|
+
`lg` sit below and above it. [Spacing](./layout.md#spacing) gives
|
|
48
|
+
the value of each step.
|
|
49
|
+
|
|
50
|
+
Color names have more parts. `--wpds-color-foreground-content-neutral`
|
|
51
|
+
is the text color of the page. `foreground` means text and icons.
|
|
52
|
+
`content` means something you read rather than click. `neutral` means
|
|
53
|
+
the color carries no meaning such as success or error. Add `weak` or
|
|
54
|
+
`strong` and the color gets fainter or stronger.
|
|
55
|
+
`--wpds-color-foreground-content-neutral-weak` is the muted text
|
|
56
|
+
color.
|
|
57
|
+
|
|
58
|
+
godmin's own custom properties start with `--godmin-` instead.
|
|
59
|
+
[Custom properties](./custom-properties.md) lists them and says which
|
|
60
|
+
ones you may read or change.
|
|
61
|
+
|
|
62
|
+
## Writing your own styles
|
|
63
|
+
|
|
64
|
+
Write the token, not the value it holds today. The value can change.
|
|
65
|
+
Color tokens follow the seeds, and radius tokens follow
|
|
66
|
+
[the corner radius setting](./radius-and-elevation.md#the-corner-radius-setting)
|
|
67
|
+
of `AdminRoot`. The same color token holds one value in the sidebar
|
|
68
|
+
and another in the canvas, because each region has its own seed.
|
|
69
|
+
|
|
70
|
+
The design system ships rules for stylelint, a checker for CSS files.
|
|
71
|
+
They catch a token name that does not exist, and a token you set
|
|
72
|
+
yourself. [Lint your
|
|
73
|
+
stylesheets](../build-and-versioning.md#lint-your-stylesheets)
|
|
74
|
+
shows how to turn them on.
|
|
75
|
+
|
|
76
|
+
Most of godmin's rules sit in a cascade layer. A cascade layer is a
|
|
77
|
+
named group of CSS rules with its own place in the order that
|
|
78
|
+
decides which rule wins. A rule of yours outside any layer wins over
|
|
79
|
+
every godmin rule inside one.
|
|
80
|
+
[Changing the page appearance](../overview.md#changing-the-page-appearance)
|
|
81
|
+
explains this, and names the few godmin rules that sit outside the
|
|
82
|
+
layer.
|
|
83
|
+
|
|
84
|
+
## The pages
|
|
85
|
+
|
|
86
|
+
- [Color](./color.md): the three seeds, the token that paints each
|
|
87
|
+
part, the contrast minimums, and the raw colors painted on purpose.
|
|
88
|
+
- [Layout](./layout.md): the areas of the frame and their sizes, the
|
|
89
|
+
canvas margin and gutters, the breakpoints, the screen widths where
|
|
90
|
+
the layout changes, the spacing tokens, and right-to-left languages.
|
|
91
|
+
- [Radius and elevation](./radius-and-elevation.md): how round each
|
|
92
|
+
surface's corners are, and which surfaces cast a shadow to look
|
|
93
|
+
raised.
|
|
94
|
+
- [Typography](./typography.md): the font, the text sizes and
|
|
95
|
+
weights, and the heading outline.
|
|
96
|
+
- [Motion](./motion.md): the motion tokens, the sidebar slide, and
|
|
97
|
+
what changes for a reader who asks for less motion.
|
|
98
|
+
- [Accessibility](./accessibility.md): focus rings, where focus goes,
|
|
99
|
+
landmarks, what a screen reader hears, and text length.
|
|
100
|
+
- [Custom properties](./custom-properties.md): every godmin custom
|
|
101
|
+
property, where it is set and what it changes.
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Radius and elevation
|
|
3
|
+
description: Which corner radius each surface of a godmin admin takes, what the cornerRadius setting changes, and the shadows godmin draws.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Radius is how round a corner is. Elevation is how high a surface
|
|
7
|
+
seems to sit above the page. A shadow is what shows it. WordPress
|
|
8
|
+
uses both words, and so does this page.
|
|
9
|
+
|
|
10
|
+
godmin takes most of its corners from the design tokens, the named
|
|
11
|
+
values `@wordpress/theme` ships. The tokens hold no shadows, so godmin
|
|
12
|
+
writes each shadow out in full.
|
|
13
|
+
|
|
14
|
+
## Corners from the tokens
|
|
15
|
+
|
|
16
|
+
The tokens have five radius steps. Each step is meant for one kind of
|
|
17
|
+
surface, and godmin rounds its surfaces to match. The pixel values are
|
|
18
|
+
those of the default preset, `subtle`.
|
|
19
|
+
[The corner radius setting](#the-corner-radius-setting) explains
|
|
20
|
+
presets.
|
|
21
|
+
|
|
22
|
+
| Token | Meant for | What godmin rounds with it |
|
|
23
|
+
| --- | --- | --- |
|
|
24
|
+
| `--wpds-border-radius-xl` (12px) | Page and app shell surfaces | The canvas, the panel that shows the active screen |
|
|
25
|
+
| `--wpds-border-radius-lg` (8px) | Cards, dialogs, notices and other larger containers | A `LogList`, the box of items shown one under the other |
|
|
26
|
+
| `--wpds-border-radius-md` (4px) | Menus, popovers and other small overlays | A toast, the short message near the bottom of the screen |
|
|
27
|
+
| `--wpds-border-radius-sm` (2px) | Buttons, inputs and compact controls | A sidebar row, the Back button of a sidebar screen, the grey bars of a loading ghost, and the focus rings of a page tab and of a toast action |
|
|
28
|
+
| `--wpds-border-radius-xs` (1px) | Elements nested inside controls | Nothing of godmin's own |
|
|
29
|
+
|
|
30
|
+
A surface inside another takes a smaller step than the one around
|
|
31
|
+
it, as WordPress asks. A log list on the canvas takes `lg` inside the
|
|
32
|
+
`xl` of the canvas.
|
|
33
|
+
|
|
34
|
+
Below `EDGE_BREAKPOINT` the canvas meets the screen edges and its
|
|
35
|
+
corners are square. [Breakpoints](./layout.md#breakpoints) gives that
|
|
36
|
+
width. A bleed canvas, the mode with no padding, keeps the same
|
|
37
|
+
corners as a padded one. [The canvas](./layout.md#the-canvas) explains
|
|
38
|
+
both modes.
|
|
39
|
+
|
|
40
|
+
## Corners that never change
|
|
41
|
+
|
|
42
|
+
These shapes are fixed in the stylesheet. They stay the same at every
|
|
43
|
+
preset.
|
|
44
|
+
|
|
45
|
+
| Surface | Corner |
|
|
46
|
+
| --- | --- |
|
|
47
|
+
| An `InitialsAvatar`, and the picture inside it | A circle, `50%` |
|
|
48
|
+
| The DataViews media box around an avatar | A circle, `50%` |
|
|
49
|
+
| A `MenuCount` | Half its height. That makes the count a pill, a box with fully round ends |
|
|
50
|
+
| The navigation drawer | Square, `0` |
|
|
51
|
+
| The thumb of the sidebar scrollbar, the part you drag | 8px |
|
|
52
|
+
|
|
53
|
+
The drawer is the panel that holds the sidebar on a small screen.
|
|
54
|
+
DataViews is the WordPress list component.
|
|
55
|
+
|
|
56
|
+
## The corner radius setting
|
|
57
|
+
|
|
58
|
+
`AdminRoot` takes a `cornerRadius` prop and hands it to the design
|
|
59
|
+
system theme provider. Its value is a preset, a named amount of
|
|
60
|
+
roundness. One preset sets all five radius steps:
|
|
61
|
+
|
|
62
|
+
| Preset | `--wpds-border-radius-xs` | `--wpds-border-radius-sm` | `--wpds-border-radius-md` | `--wpds-border-radius-lg` | `--wpds-border-radius-xl` |
|
|
63
|
+
| --- | --- | --- | --- | --- | --- |
|
|
64
|
+
| `none` | 0px | 0px | 0px | 0px | 0px |
|
|
65
|
+
| `subtle` | 1px | 2px | 4px | 8px | 12px |
|
|
66
|
+
| `moderate` | 6px | 8px | 12px | 16px | 20px |
|
|
67
|
+
| `pronounced` | 18px | 20px | 22px | 24px | 26px |
|
|
68
|
+
|
|
69
|
+
Without the prop the preset is `subtle`.
|
|
70
|
+
|
|
71
|
+
```tsx
|
|
72
|
+
<AdminRoot cornerRadius="moderate">
|
|
73
|
+
<YourApp />
|
|
74
|
+
</AdminRoot>
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
`AdminRoot` renders the root theme provider, the one that also themes
|
|
78
|
+
the whole document. So the preset also reaches the dialogs, menus and
|
|
79
|
+
popovers that the design system draws outside the `AdminRoot`
|
|
80
|
+
element. The theme providers of `Frame.Root` and `Frame.Canvas` set
|
|
81
|
+
only colors, so the sidebar and the canvas take the preset from
|
|
82
|
+
`AdminRoot`.
|
|
83
|
+
|
|
84
|
+
The band of notices at the top of a bleed canvas always takes `none`.
|
|
85
|
+
Its notices run edge to edge as square strips. On a padded canvas the
|
|
86
|
+
notices take the same preset as the canvas around them.
|
|
87
|
+
[Notices for the whole
|
|
88
|
+
application](../framing-an-application.md#notices-for-the-whole-application)
|
|
89
|
+
shows how to pass them.
|
|
90
|
+
|
|
91
|
+
`renderAdmin` from `@gopherium/godmin/testing` takes the same
|
|
92
|
+
`cornerRadius`, so a test can draw a screen under any preset.
|
|
93
|
+
|
|
94
|
+
## Elevation
|
|
95
|
+
|
|
96
|
+
WordPress names four levels of elevation: extra small, small, medium
|
|
97
|
+
and large. The higher the level, the more a surface asks for
|
|
98
|
+
attention. A dialog sits at the top. godmin draws three shadows that
|
|
99
|
+
show depth:
|
|
100
|
+
|
|
101
|
+
| Surface | Shadow |
|
|
102
|
+
| --- | --- |
|
|
103
|
+
| The canvas | `0 1px 2px rgb(0 0 0 / 0.08)`. None below `EDGE_BREAKPOINT` |
|
|
104
|
+
| A toast | The WordPress small elevation, the one the snackbar uses. The snackbar is WordPress's own toast. Four layers: `0 1px 2px rgb(0 0 0 / 0.05)`, `0 2px 3px rgb(0 0 0 / 0.04)`, `0 6px 6px rgb(0 0 0 / 0.03)`, `0 8px 8px rgb(0 0 0 / 0.02)` |
|
|
105
|
+
| The navigation drawer | `2px 0 8px rgba(0, 0, 0, 0.2)`, the shadow of the phone sidebar in WordPress's new admin |
|
|
106
|
+
|
|
107
|
+
A bleed canvas keeps the canvas shadow. The sidebar has no shadow.
|
|
108
|
+
Dialogs, menus and popovers keep the shadow their design system
|
|
109
|
+
package draws, because godmin sets none for them.
|
|
110
|
+
|
|
111
|
+
Two more shadows draw a line, not depth:
|
|
112
|
+
|
|
113
|
+
- Below `DENSE_BREAKPOINT` the actions column of a `godmin-table`
|
|
114
|
+
inside a `godmin-table-scroll` box stays pinned while the other
|
|
115
|
+
cells scroll. Its edge is an inset shadow, one drawn inside the
|
|
116
|
+
box: `--wpds-border-width-xs` (1px) of
|
|
117
|
+
`--wpds-color-stroke-surface-neutral`. It sits on the side that
|
|
118
|
+
faces the other cells, in a right-to-left page too. The table
|
|
119
|
+
merges the borders of its cells, and a merged border paints badly
|
|
120
|
+
on a pinned cell. [Stylesheet helpers](../screens.md#stylesheet-helpers)
|
|
121
|
+
shows the table markup.
|
|
122
|
+
- A focused toast with no action draws its focus ring as a shadow.
|
|
123
|
+
[The focus ring](./accessibility.md#the-focus-ring) covers the
|
|
124
|
+
other focus rings.
|
|
125
|
+
|
|
126
|
+
godmin also takes one shadow away. It drops the dark ring DataViews
|
|
127
|
+
draws around its media box when the box holds an avatar.
|
|
128
|
+
[Avatars](../lists.md#avatars) explains why godmin rounds that box and
|
|
129
|
+
drops its ring.
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Typography
|
|
3
|
+
description: The font, the type scale godmin sets its titles and body text in, and the heading outline of a screen.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
godmin sets its text with the design system's typography tokens. A
|
|
7
|
+
token is a named value that the design system ships as a CSS custom
|
|
8
|
+
property, such as `--wpds-typography-font-size-md`. CSS reads it with
|
|
9
|
+
`var()`. This page names each token and gives its value in brackets.
|
|
10
|
+
[Which token paints each part](./color.md#which-token-paints-each-part)
|
|
11
|
+
gives the color of each text.
|
|
12
|
+
|
|
13
|
+
## The font
|
|
14
|
+
|
|
15
|
+
The `body` rule in `base.css` sets the whole page in
|
|
16
|
+
`--wpds-typography-font-family-body`. The design system draws its
|
|
17
|
+
headings in `--wpds-typography-font-family-heading`. Both tokens hold
|
|
18
|
+
the same system font stack. That is a list of fonts the browser tries
|
|
19
|
+
in order, starting with the font the device uses for its own menus
|
|
20
|
+
and windows. Every rule in `base.css` that names a font names the
|
|
21
|
+
body font.
|
|
22
|
+
|
|
23
|
+
## The type scale
|
|
24
|
+
|
|
25
|
+
Each text has a size, a line height and a weight. The line height is
|
|
26
|
+
the height of one line of text. godmin's titles and body text follow
|
|
27
|
+
five styles.
|
|
28
|
+
|
|
29
|
+
| Style | Size | Line height | Weight |
|
|
30
|
+
| --- | --- | --- | --- |
|
|
31
|
+
| Sidebar screen title | `--wpds-typography-font-size-xl` (20px) | `--wpds-typography-line-height-xl` (32px) | Emphasis |
|
|
32
|
+
| `heading-lg`, for a page, section or empty list title | `--wpds-typography-font-size-lg` (15px) | `--wpds-typography-line-height-sm` (20px) | Emphasis |
|
|
33
|
+
| `heading-md`, for a section title inside a section | `--wpds-typography-font-size-md` (13px) | `--wpds-typography-line-height-sm` (20px) | Emphasis |
|
|
34
|
+
| `body-md`, for body text | `--wpds-typography-font-size-md` (13px) | `--wpds-typography-line-height-sm` (20px) | Default |
|
|
35
|
+
| `body-sm`, for small text such as the time of a log item | `--wpds-typography-font-size-sm` (12px) | `--wpds-typography-line-height-xs` (16px) | Default |
|
|
36
|
+
|
|
37
|
+
`heading-lg`, `heading-md`, `body-md` and `body-sm` are variants of
|
|
38
|
+
`Text`, the design system's text component. A variant sets the size,
|
|
39
|
+
the line height and the weight together. `Text` takes `body-md` when
|
|
40
|
+
it is given none. `base.css` sets the sidebar screen title itself.
|
|
41
|
+
|
|
42
|
+
The design system has two weights.
|
|
43
|
+
`--wpds-typography-font-weight-default` (400) is for body text.
|
|
44
|
+
`--wpds-typography-font-weight-emphasis` (600) is for titles and for
|
|
45
|
+
what stands out, such as the sidebar row of the page on screen. The
|
|
46
|
+
table calls them default and emphasis.
|
|
47
|
+
|
|
48
|
+
The smallest size, `--wpds-typography-font-size-xs` (11px), is for
|
|
49
|
+
small labels such as the count beside a sidebar row.
|
|
50
|
+
|
|
51
|
+
Some parts give the size of their text on their own page:
|
|
52
|
+
[the page subtitle](../screens.md#page),
|
|
53
|
+
[the page tabs](../screens.md#pagetabs),
|
|
54
|
+
[the title and description of a list row](../lists.md#the-title-field),
|
|
55
|
+
[a table that stays custom](../lists.md#lists-that-stay-custom),
|
|
56
|
+
[a toast](../loading-and-feedback.md#toasts) and
|
|
57
|
+
[the letter of an avatar](../lists.md#avatars).
|
|
58
|
+
|
|
59
|
+
## The heading outline
|
|
60
|
+
|
|
61
|
+
The heading outline is the list of headings a screen reader offers to
|
|
62
|
+
jump between, from `h1` down. A `NavigationScreen` draws its title as
|
|
63
|
+
the `h1`, as in the WordPress Site Editor. So the sidebar menu decides
|
|
64
|
+
which title is the `h1`. Below, with a sidebar means the sidebar shows
|
|
65
|
+
a `NavigationScreen`.
|
|
66
|
+
|
|
67
|
+
| Title | Without a sidebar | With a sidebar |
|
|
68
|
+
| --- | --- | --- |
|
|
69
|
+
| Sidebar screen title | None | `h1` |
|
|
70
|
+
| Page title | `h1` | `h2` |
|
|
71
|
+
| Section title | `h2` | `h3` |
|
|
72
|
+
| Section title inside a section | `h3` | `h4` |
|
|
73
|
+
| Empty list title | `h2` | `h3` |
|
|
74
|
+
|
|
75
|
+
With a sidebar, pass `headingLevel={2}` to each `Page`. Every title
|
|
76
|
+
inside it then moves one level down. Only the element changes. Each
|
|
77
|
+
title keeps its size, so a section looks the same on both kinds of
|
|
78
|
+
screen. [Heading levels](../screens.md#heading-levels) shows the code.
|
|
79
|
+
|
|
80
|
+
On a small screen the sidebar sits in the drawer, and its title is
|
|
81
|
+
the `h1` while the drawer is open. The brand in the top bar is not a
|
|
82
|
+
heading. So while the drawer is shut, the screen has no `h1`.
|
|
83
|
+
WordPress's new admin works the same way.
|