@gopherium/godmin 0.25.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.
Files changed (40) hide show
  1. package/README.md +9 -15
  2. package/dist/base.css +3 -2
  3. package/dist/close-while-open.d.ts +6 -0
  4. package/dist/close-while-open.js +21 -0
  5. package/dist/drilldown-item.d.ts +5 -3
  6. package/dist/drilldown-item.js +6 -6
  7. package/dist/focus-back.d.ts +25 -0
  8. package/dist/focus-back.js +125 -0
  9. package/dist/index.d.ts +9 -1
  10. package/dist/index.js +5 -1
  11. package/dist/list-run.d.ts +7 -2
  12. package/dist/list-run.js +64 -2
  13. package/dist/list-view.d.ts +1 -7
  14. package/dist/list-view.js +1 -16
  15. package/dist/menu-item.d.ts +7 -0
  16. package/dist/navigation-item.d.ts +8 -0
  17. package/dist/navigation-item.js +9 -1
  18. package/dist/navigation-list.js +12 -2
  19. package/dist/open-on-tap.d.ts +14 -0
  20. package/dist/open-on-tap.js +17 -0
  21. package/dist/run-confirm.d.ts +1 -1
  22. package/dist/run-confirm.js +4 -2
  23. package/dist/unsaved-text.d.ts +14 -0
  24. package/dist/unsaved-text.js +25 -0
  25. package/docs/build-and-versioning.md +190 -0
  26. package/docs/design-system/accessibility.md +206 -0
  27. package/docs/design-system/color.md +74 -0
  28. package/docs/design-system/custom-properties.md +63 -0
  29. package/docs/design-system/layout.md +157 -0
  30. package/docs/design-system/motion.md +116 -0
  31. package/docs/design-system/overview.md +101 -0
  32. package/docs/design-system/radius-and-elevation.md +129 -0
  33. package/docs/design-system/typography.md +83 -0
  34. package/docs/framing-an-application.md +386 -0
  35. package/docs/lists.md +1511 -0
  36. package/docs/loading-and-feedback.md +207 -0
  37. package/docs/overview.md +159 -0
  38. package/docs/screens.md +419 -0
  39. package/docs/testing.md +193 -0
  40. 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.