@whatsaaaa/design-system 0.6.0 → 0.6.1

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 CHANGED
@@ -62,10 +62,10 @@ A pull request that changes what the package ships adds a changeset with `pnpm c
62
62
  CI runs on every pull request:
63
63
 
64
64
  - formatting, lint and types,
65
- - the unit tests, with the contrast of every role pair in both themes,
65
+ - the unit tests, with the contrast of every role pair in both themes, and the comments of the stylesheets in the built ones,
66
66
  - that `assets/` is what the sources produce,
67
67
  - that the package and the style guide build,
68
- - the browser tests: no page overflows sideways at phone, tablet and desktop width in either theme, no page logs an error when it loads, the easter egg works with the mouse, the keyboard and reduced motion, the keys of the status line work and their switch turns them off, the path of the status line gives way at every width from 320 px and the theme button switches the theme, a `dark` or `light` class chooses the theme as `data-theme` does, an element for one theme shows only in it, the browser's theme-color follows the theme, a control that takes the focus is not left under the status line and no bar or corner of the window cuts off its focus ring, the first tab starts on the border of the sidebar, the pieces of a form fit every width from 320 px (a segmented control works with the keyboard, stands out at 3:1 and takes the selection colors in forced colors, amounts line up at the right in figures of one width, a number field has no spin buttons and its arrow keys step it, wrapped code hangs and stays inside its block, a long email breaks after its @, and the check icon and the ghost files draw), both fonts draw Serbian Latin, an app built on the Tailwind entry takes its utilities, layers and `dark:` and `light:` from the tokens and their theme, and the pages of the style guide look like their stored screenshots.
68
+ - the browser tests: no page overflows sideways at phone, tablet and desktop width in either theme, and no terminal window or bar of one cuts off its content, no page logs an error when it loads, the easter egg works with the mouse, the keyboard and reduced motion, the keys of the status line work and their switch turns them off, the numbers of the tabs show only while their keys work and keep their place while the keys load, the path of the status line gives way at every width from 320 px and the theme button switches the theme, a `dark` or `light` class chooses the theme as `data-theme` does, an element for one theme shows only in it, the browser's theme-color follows the theme, a control that takes the focus is not left under the status line and no bar or corner of the window cuts off its focus ring, a radius of the page's own wins over the focus ring's and a button without one takes its small corners, with index.css and with tailwind.css, a state lines up with the text beside it, a prompt that wraps keeps its chevron on its first line at every width from 320 px, assistive technology reads the parts of the path above a page title as words of their own, the first tab starts on the border of the sidebar, the pieces of a form fit every width from 320 px (a segmented control works with the keyboard, stands out at 3:1 and takes the selection colors in forced colors, amounts line up at the right in figures of one width, a number field has no spin buttons and its arrow keys step it, wrapped code hangs and stays inside its block, a long email breaks after its @, and the check icon and the ghost files draw), both fonts draw Serbian Latin, an app built on the Tailwind entry takes its utilities, layers and `dark:` and `light:` from the tokens and their theme, and the pages of the style guide look like their stored screenshots.
69
69
 
70
70
  The screenshots are in `tests/browser/__screenshots__/` and are taken on Linux, in the Playwright container, so they are the same on every machine. After a change that is meant to be seen, update them:
71
71
 
package/dist/css/base.css CHANGED
@@ -1,3 +1,8 @@
1
+ /*
2
+ * Page defaults for a site that is all this system: box sizing, the page colors, the body
3
+ * face, links, number fields, focus and selection. It resets margins and list markers, so
4
+ * content that should read as a document goes in a .ws-prose container.
5
+ */
1
6
  *, :before, :after {
2
7
  box-sizing: border-box;
3
8
  }
@@ -33,11 +38,16 @@ a {
33
38
  text-decoration-thickness: 1px;
34
39
  }
35
40
 
41
+ /* A mono face with ligatures turns => and != into single shapes, which code should not do. */
36
42
  code, kbd, samp, pre {
37
43
  font-family: var(--ws-font-family-mono);
38
44
  font-variant-ligatures: none;
39
45
  }
40
46
 
47
+ /*
48
+ * A number field is typed, and stepped with the arrow keys. The system draws no spin buttons,
49
+ * and the browser's own have no look of its, so they go.
50
+ */
41
51
  input[type="number"] {
42
52
  appearance: textfield;
43
53
  }
@@ -53,11 +63,21 @@ input[type="number"]::-webkit-outer-spin-button {
53
63
  }
54
64
 
55
65
  :focus-visible {
56
- border-radius: var(--ws-radius-sm);
57
66
  outline: var(--ws-border-width-medium) solid var(--ws-color-interactive);
58
67
  outline-offset: 3px;
59
68
  }
60
69
 
70
+ /*
71
+ * A ring follows the corners of what it rings. What has no corners of its own, such as a
72
+ * link, takes small ones while it is focused. The rule weighs no more than an element, so a
73
+ * class of the page's own, such as a round radio button's, always wins, wherever it is
74
+ * written. A form control weighs as an element here, to win over Tailwind's preflight, which
75
+ * squares its corners at that weight before base.css in the same layer.
76
+ */
77
+ :where(:focus-visible), :is(button, input, select, optgroup, textarea):where(:focus-visible) {
78
+ border-radius: var(--ws-radius-sm);
79
+ }
80
+
61
81
  ::selection {
62
82
  background: var(--ws-color-selection);
63
83
  color: var(--ws-color-text);
@@ -1,3 +1,13 @@
1
+ /*
2
+ * A callout: a bar in the status color, a label with an icon, then text.
3
+ * The status is never carried by color alone. On the light theme the label and icon take the
4
+ * text color, because the status hues miss AA as text there, and the hue stays on the bar.
5
+ *
6
+ * <aside class="ws-callout ws-callout--warning">
7
+ * <p class="ws-callout__title">Warning</p>
8
+ * <p>...</p>
9
+ * </aside>
10
+ */
1
11
  .ws-callout {
2
12
  --ws-callout-tone: var(--ws-color-note);
3
13
  --ws-callout-label: var(--ws-color-note-text);
package/dist/css/code.css CHANGED
@@ -1,3 +1,25 @@
1
+ /*
2
+ * A code block with a caption: the file name on the left, the language on the right.
3
+ *
4
+ * <figure class="ws-code">
5
+ * <figcaption><span>conditions.ts</span><span>ts</span></figcaption>
6
+ * <pre><code>...</code></pre>
7
+ * </figure>
8
+ *
9
+ * Code blocks stay on the dark palette in both themes: on dawn no syntax color except
10
+ * pine reaches AA on the surface.
11
+ *
12
+ * A block scrolls sideways. ws-code--wrap wraps its lines instead, for text a person typed,
13
+ * such as a long value, which a phone would cut off. When each line is a .line with
14
+ * --ws-code-hang, its indent in characters plus two, as the hangingIndent transformer of
15
+ * @whatsaaaa/design-system/shiki gives it, the rest of a wrapped line hangs one level in from
16
+ * the line's own text, so the shape of the code still reads.
17
+ *
18
+ * <figure class="ws-code ws-code--wrap">
19
+ * <figcaption><span>order.json</span><span>json</span></figcaption>
20
+ * <pre><code><span class="line" style="--ws-code-hang: 4"> "note": "..."</span></code></pre>
21
+ * </figure>
22
+ */
1
23
  .ws-code {
2
24
  margin: var(--ws-space-16) 0 0;
3
25
  border: var(--ws-border-width-thin) solid var(--ws-code-border);
@@ -44,6 +66,7 @@
44
66
  overflow-x: visible;
45
67
  }
46
68
 
69
+ /* A line is a box of its own, so its rest can hang. The line break after it stays text. */
47
70
  .ws-code--wrap .line {
48
71
  box-sizing: border-box;
49
72
  width: 100%;
@@ -61,6 +84,7 @@
61
84
  color: var(--ws-code-text);
62
85
  }
63
86
 
87
+ /* The scrollbar of a code block belongs to the dark block, whatever the page theme is. */
64
88
  .ws-code > pre, .ws-prose pre {
65
89
  --lightningcss-light: ;
66
90
  --lightningcss-dark: initial;
@@ -1,3 +1,14 @@
1
+ /*
2
+ * The ghost as an element: <ws-ghost>. See the ghost module for its markup and behavior.
3
+ * The body takes the text color and the tongue the brand color, so the free ghost follows
4
+ * the theme.
5
+ */
6
+
7
+ /*
8
+ * The one breakpoint of the system. Below it there is one column, the tab bar wraps and
9
+ * headings take their compact sizes. Custom properties cannot be used in media queries,
10
+ * so in another project write the query out: @media (width < 64rem).
11
+ */
1
12
  ws-ghost {
2
13
  color: var(--ws-color-text);
3
14
  vertical-align: middle;
@@ -22,6 +33,13 @@ ws-ghost {
22
33
  display: block;
23
34
  }
24
35
 
36
+ /*
37
+ * A ghost that is large on a wide screen, such as the one next to the display name, takes a
38
+ * smaller size on a phone with compact-px: the size of one sprite pixel below 64rem, a whole
39
+ * number from 1 to 5. The ghost is 10 by 12 sprite pixels.
40
+ *
41
+ * <ws-ghost px="6" compact-px="4"></ws-ghost>
42
+ */
25
43
  @media (width < 64rem) {
26
44
  ws-ghost[compact-px="1"] .ws-ghost__sprite {
27
45
  width: 10px;
@@ -57,6 +75,10 @@ ws-ghost {
57
75
  fill: var(--ws-color-brand);
58
76
  }
59
77
 
78
+ /*
79
+ * The speech bubble. It is a popover, so it shows above everything and no container clips
80
+ * it. The script places it next to the ghost and keeps it inside the window.
81
+ */
60
82
  .ws-ghost__bubble {
61
83
  z-index: 1000;
62
84
  pointer-events: none;
@@ -87,6 +109,7 @@ ws-ghost {
87
109
  fill: var(--ws-color-bg);
88
110
  }
89
111
 
112
+ /* The bubble pops in four frames, like a sprite. With reduced motion it is just there. */
90
113
  @media (prefers-reduced-motion: no-preference) {
91
114
  .ws-ghost__bubble svg {
92
115
  transform-origin: 0 100%;
@@ -105,6 +128,7 @@ ws-ghost {
105
128
  }
106
129
  }
107
130
 
131
+ /* The shout for screen readers. */
108
132
  .ws-ghost__live {
109
133
  clip-path: inset(50%);
110
134
  white-space: nowrap;
@@ -1,3 +1,15 @@
1
+ /*
2
+ * The few icons the styles draw themselves, as masks, so they take the color of their text
3
+ * and need no markup. All are 16 x 16 strokes of 1.5.
4
+ *
5
+ * .done::before {
6
+ * width: 1rem;
7
+ * height: 1rem;
8
+ * background: currentcolor;
9
+ * content: '';
10
+ * mask: var(--ws-icon-check) center / contain no-repeat;
11
+ * }
12
+ */
1
13
  :root {
2
14
  --ws-icon-note: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='none' stroke='%23000' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='8' cy='8' r='6.2'/%3E%3Cpath d='M8 7.4v3.4M8 5.1v.2'/%3E%3C/svg%3E");
3
15
  --ws-icon-tip: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16' fill='none' stroke='%23000' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M8 1.8a4.3 4.3 0 0 0-2.3 7.9v1.5h4.6V9.7A4.3 4.3 0 0 0 8 1.8ZM6.4 13.6h3.2'/%3E%3C/svg%3E");
@@ -1,3 +1,25 @@
1
+ /*
2
+ * Terms and their values, a row each: the answers of a form on its review step, or what an
3
+ * order costs. A term is in the voice of a label, its value in the face of a field, and the
4
+ * two share a baseline. The terms share a column as wide as the longest of them, at most two
5
+ * fifths of the row, so the values line up and have the rest of it. A long email or URL takes
6
+ * a <wbr /> after its @ or a /, so it breaks there and not in a word.
7
+ *
8
+ * <dl class="ws-pairs">
9
+ * <div><dt>Name</dt><dd>Ana Petrović</dd></div>
10
+ * <div><dt>Email</dt><dd>ana@<wbr />example.com</dd></div>
11
+ * </dl>
12
+ *
13
+ * Amounts take ws-pairs--amounts: each value at the right edge, in figures of one width, so
14
+ * the digits of the rows line up, and the terms take the rest of the row. The total is the
15
+ * last row, ws-pairs__total.
16
+ *
17
+ * <dl class="ws-pairs ws-pairs--amounts">
18
+ * <div><dt>Subtotal</dt><dd>€48.00</dd></div>
19
+ * <div><dt>Shipping</dt><dd>€4.00</dd></div>
20
+ * <div class="ws-pairs__total"><dt>Total</dt><dd>€52.00</dd></div>
21
+ * </dl>
22
+ */
1
23
  .ws-pairs {
2
24
  column-gap: var(--ws-space-16);
3
25
  border-bottom: var(--ws-border-width-thin) dashed var(--ws-color-border);
@@ -6,6 +28,9 @@
6
28
  display: grid;
7
29
  }
8
30
 
31
+ /* Each row takes the columns and the gap of the list, so a browser without subgrid (Chrome
32
+ before 117) still sets a term beside its value; only the terms of different rows may differ
33
+ in width. */
9
34
  .ws-pairs > div {
10
35
  grid-column: 1 / -1;
11
36
  grid-template-columns: inherit;
@@ -47,6 +72,7 @@
47
72
  white-space: nowrap;
48
73
  }
49
74
 
75
+ /* The total: set off by a solid rule, and both of its parts in the text color, semibold. */
50
76
  .ws-pairs > .ws-pairs__total {
51
77
  border-top-style: solid;
52
78
  }
@@ -1,3 +1,14 @@
1
+ /*
2
+ * Long-form text: headings, paragraphs, links, lists, inline code, tables and the small
3
+ * things around them. Put rendered Markdown in a .ws-prose container.
4
+ * The same rules style VitePress pages, whose content container is .vp-doc.
5
+ */
6
+
7
+ /*
8
+ * The one breakpoint of the system. Below it there is one column, the tab bar wraps and
9
+ * headings take their compact sizes. Custom properties cannot be used in media queries,
10
+ * so in another project write the query out: @media (width < 64rem).
11
+ */
1
12
  .ws-prose, .vp-doc {
2
13
  color: var(--ws-color-text);
3
14
  font: var(--ws-text-body);
@@ -285,6 +296,7 @@
285
296
  }
286
297
  }
287
298
 
299
+ /* A plain code block in prose. Dark in both themes, like every code block. */
288
300
  .ws-prose pre {
289
301
  margin: var(--ws-space-16) 0 0;
290
302
  padding: var(--ws-space-16);
@@ -302,6 +314,13 @@
302
314
  font: inherit;
303
315
  }
304
316
 
317
+ /*
318
+ * The path above a page title. The slashes between its parts are drawn. Assistive technology
319
+ * reads a comma in their place, so the parts come out as words of their own.
320
+ *
321
+ * <p class="ws-crumb"><span>writing</span><span>form-builder</span><span>conditions</span></p>
322
+ * <h1>Conditions</h1>
323
+ */
305
324
  .ws-crumb {
306
325
  color: var(--ws-color-text-secondary);
307
326
  font: var(--ws-text-caption);
@@ -312,7 +331,7 @@
312
331
  margin-inline: var(--ws-space-4);
313
332
  color: var(--ws-color-text-faint);
314
333
  content: "/";
315
- content: "/" / "";
334
+ content: "/" / ", ";
316
335
  }
317
336
 
318
337
  .ws-crumb + h1 {
@@ -1,3 +1,16 @@
1
+ /*
2
+ * A segmented control: buttons in a row that share their edges, one of them pressed, such as
3
+ * the switch between the languages of a page.
4
+ *
5
+ * <div class="ws-segmented" role="group" aria-label="Language">
6
+ * <button type="button" aria-pressed="true">en</button>
7
+ * <button type="button" aria-pressed="false">sr</button>
8
+ * </div>
9
+ *
10
+ * The pressed segment is raised, in the text color, with an edge of the interactive color
11
+ * that is twice as thick as the others, at least 3:1 on the page and on the raised fill. It is
12
+ * not filled: next to a primary button a filled segment would be as loud as the button.
13
+ */
1
14
  .ws-segmented {
2
15
  max-width: 100%;
3
16
  display: inline-flex;
@@ -27,6 +40,7 @@
27
40
  border-end-end-radius: var(--ws-radius-md);
28
41
  }
29
42
 
43
+ /* The edge two segments share is one line: the hovered or pressed one draws it, over the other. */
30
44
  .ws-segmented > button + button {
31
45
  margin-inline-start: calc(-1 * var(--ws-border-width-thin));
32
46
  }
@@ -59,6 +73,12 @@
59
73
  background: none;
60
74
  }
61
75
 
76
+ /*
77
+ * In forced colors the browser paints every fill in the page's color, so the pressed segment
78
+ * takes the system's colors of a selection. It keeps them as they are, as the browser would
79
+ * otherwise put a plate of the page's color behind its text. Kept colors keep the shadow too,
80
+ * so it drops the shadow itself: the fill already shows the segment is pressed.
81
+ */
62
82
  @media (forced-colors: active) {
63
83
  .ws-segmented > button[aria-pressed="true"] {
64
84
  box-shadow: none;
@@ -1,3 +1,34 @@
1
+ /*
2
+ * The terminal frame: a tab bar on top, prompts as headings, a status line at the bottom.
3
+ * Each piece stands alone, so an app can take the bars without the frame.
4
+ */
5
+
6
+ /*
7
+ * The one breakpoint of the system. Below it there is one column, the tab bar wraps and
8
+ * headings take their compact sizes. Custom properties cannot be used in media queries,
9
+ * so in another project write the query out: @media (width < 64rem).
10
+ */
11
+
12
+ /*
13
+ * An element for one theme only, such as one cut of a mark or the name of the theme.
14
+ *
15
+ * <img class="ws-theme-dark" src="mark-on-dark.svg" alt="whatsaaaa" />
16
+ * <img class="ws-theme-light" src="mark-on-light.svg" alt="whatsaaaa" />
17
+ *
18
+ * Both are in the page and the styles show the one of the theme in effect where it stands:
19
+ * the nearest choice, data-theme or a dark or light class, on <html> or on an element around
20
+ * it, or the system's preference when there is none. So the right one shows before any script
21
+ * runs.
22
+ *
23
+ * It hides with !important because it has to win over whatever else gives the element a
24
+ * display, such as a flex item of the status line. The status line's --dark and --light
25
+ * items are older names of the same two classes.
26
+ */
27
+
28
+ /*
29
+ * The rules are written by the token build, from the same selectors as the theme blocks of the
30
+ * tokens: scripts/lib/theme-selectors.ts.
31
+ */
1
32
  :is(.ws-theme-dark, .ws-status-line__item--dark):where(:is([data-theme="light"], .light:where(:not([data-theme], .dark))), :is([data-theme="light"], .light:where(:not([data-theme], .dark))) *):not(:is([data-theme="light"], .light:where(:not([data-theme], .dark))) :is([data-theme="dark"], .dark:where(:not([data-theme], .light))), :is([data-theme="light"], .light:where(:not([data-theme], .dark))) :is([data-theme="dark"], .dark:where(:not([data-theme], .light))) *), :is(.ws-theme-dark, .ws-status-line__item--dark):where(:is([data-theme="light"], .light:where(:not([data-theme], .dark))) :is([data-theme="dark"], .dark:where(:not([data-theme], .light))) :is([data-theme="light"], .light:where(:not([data-theme], .dark))), :is([data-theme="light"], .light:where(:not([data-theme], .dark))) :is([data-theme="dark"], .dark:where(:not([data-theme], .light))) :is([data-theme="light"], .light:where(:not([data-theme], .dark))) *):not(:is([data-theme="light"], .light:where(:not([data-theme], .dark))) :is([data-theme="dark"], .dark:where(:not([data-theme], .light))) :is([data-theme="light"], .light:where(:not([data-theme], .dark))) :is([data-theme="dark"], .dark:where(:not([data-theme], .light))), :is([data-theme="light"], .light:where(:not([data-theme], .dark))) :is([data-theme="dark"], .dark:where(:not([data-theme], .light))) :is([data-theme="light"], .light:where(:not([data-theme], .dark))) :is([data-theme="dark"], .dark:where(:not([data-theme], .light))) *), :is(.ws-theme-light, .ws-status-line__item--light):where(:is([data-theme="dark"], .dark:where(:not([data-theme], .light))), :is([data-theme="dark"], .dark:where(:not([data-theme], .light))) *):not(:is([data-theme="dark"], .dark:where(:not([data-theme], .light))) :is([data-theme="light"], .light:where(:not([data-theme], .dark))), :is([data-theme="dark"], .dark:where(:not([data-theme], .light))) :is([data-theme="light"], .light:where(:not([data-theme], .dark))) *), :is(.ws-theme-light, .ws-status-line__item--light):where(:is([data-theme="dark"], .dark:where(:not([data-theme], .light))) :is([data-theme="light"], .light:where(:not([data-theme], .dark))) :is([data-theme="dark"], .dark:where(:not([data-theme], .light))), :is([data-theme="dark"], .dark:where(:not([data-theme], .light))) :is([data-theme="light"], .light:where(:not([data-theme], .dark))) :is([data-theme="dark"], .dark:where(:not([data-theme], .light))) *):not(:is([data-theme="dark"], .dark:where(:not([data-theme], .light))) :is([data-theme="light"], .light:where(:not([data-theme], .dark))) :is([data-theme="dark"], .dark:where(:not([data-theme], .light))) :is([data-theme="light"], .light:where(:not([data-theme], .dark))), :is([data-theme="dark"], .dark:where(:not([data-theme], .light))) :is([data-theme="light"], .light:where(:not([data-theme], .dark))) :is([data-theme="dark"], .dark:where(:not([data-theme], .light))) :is([data-theme="light"], .light:where(:not([data-theme], .dark))) *) {
2
33
  display: none !important;
3
34
  }
@@ -14,6 +45,7 @@
14
45
  }
15
46
  }
16
47
 
48
+ /* The window: bar, content, bar. Give it a height to make the content scroll inside it. */
17
49
  .ws-term {
18
50
  border: var(--ws-border-width-thin) solid var(--ws-color-border);
19
51
  border-radius: var(--ws-radius-xl);
@@ -25,6 +57,23 @@
25
57
  overflow: hidden;
26
58
  }
27
59
 
60
+ /*
61
+ * Tab bar.
62
+ *
63
+ * <header class="ws-tab-bar">
64
+ * <a class="ws-tab-bar__brand" href="/">...mark... name</a>
65
+ * <nav class="ws-tabs" aria-label="Main">
66
+ * <ul>
67
+ * <li><a href="/" aria-current="page">home</a></li>
68
+ * <li><a href="/projects/">projects</a></li>
69
+ * </ul>
70
+ * </nav>
71
+ * <div class="ws-tab-bar__end">...</div>
72
+ * </header>
73
+ *
74
+ * The tabs are optional. A site of one page has nothing to tab to: its bar is the brand and
75
+ * the end.
76
+ */
28
77
  .ws-tab-bar {
29
78
  align-items: stretch;
30
79
  gap: var(--ws-space-32);
@@ -51,6 +100,7 @@
51
100
  display: flex;
52
101
  }
53
102
 
103
+ /* A brand that is a link fills the bar's height, where the window clips: its ring goes inside. */
54
104
  .ws-tab-bar__brand:focus-visible {
55
105
  outline-offset: calc(-1 * var(--ws-border-width-medium));
56
106
  }
@@ -88,21 +138,28 @@
88
138
  display: flex;
89
139
  }
90
140
 
91
- .ws-tabs a:before {
141
+ /*
142
+ * Tabs are numbered like the windows of a terminal multiplexer. The number names the key that
143
+ * goes to the tab, so it is drawn only while the keys are on: not without the shortcuts
144
+ * module, and not with the keys switched off. While the head script waits for the module,
145
+ * the number keeps its place unseen, so the labels do not move when it shows.
146
+ */
147
+ :is([data-ws-keys="on"], [data-ws-keys="pending"]) .ws-tabs a:before {
92
148
  color: var(--ws-color-text-faint);
93
149
  font-weight: var(--ws-font-weight-bold);
94
150
  content: counter(ws-tab);
95
151
  content: counter(ws-tab) / "";
96
152
  }
97
153
 
98
- [data-ws-keys="off"] .ws-tabs a:before {
99
- content: none;
154
+ [data-ws-keys="pending"] .ws-tabs a:before {
155
+ visibility: hidden;
100
156
  }
101
157
 
102
158
  .ws-tabs a:hover {
103
159
  color: var(--ws-color-text);
104
160
  }
105
161
 
162
+ /* A tab fills the bar from edge to edge, and the window clips there: its ring goes inside it. */
106
163
  .ws-tabs a:focus-visible {
107
164
  outline-offset: calc(-1 * var(--ws-border-width-medium));
108
165
  }
@@ -137,6 +194,7 @@
137
194
  color: var(--ws-color-text);
138
195
  }
139
196
 
197
+ /* An arrow after a link that leaves the site. */
140
198
  .ws-arrow:after {
141
199
  content: "";
142
200
  width: .75em;
@@ -148,8 +206,16 @@
148
206
  display: inline-block;
149
207
  }
150
208
 
209
+ /*
210
+ * A prompt: the chevron, then a command. As a heading it names a section by the command
211
+ * whose output the section is.
212
+ *
213
+ * <h2 class="ws-prompt">ls ~/projects</h2>
214
+ *
215
+ * The chevron is centered on the first line, so a command that wraps keeps it there.
216
+ */
151
217
  .ws-prompt {
152
- align-items: center;
218
+ align-items: flex-start;
153
219
  gap: var(--ws-space-10);
154
220
  color: var(--ws-color-text);
155
221
  font: var(--ws-text-label);
@@ -159,13 +225,15 @@
159
225
  }
160
226
 
161
227
  .ws-prompt:before {
162
- background: var(--ws-color-brand);
163
- content: "";
164
228
  width: .625em;
165
229
  height: .875em;
230
+ margin-top: calc((var(--ws-text-label-line-height) * 1em - .875em) / 2);
231
+ background: var(--ws-color-brand);
232
+ content: "";
166
233
  -webkit-mask: var(--ws-icon-chevron) center / contain no-repeat;
167
234
  mask: var(--ws-icon-chevron) center / contain no-repeat;
168
235
  flex: none;
236
+ margin-top: calc(.5lh - .4375em);
169
237
  }
170
238
 
171
239
  .ws-prompt a {
@@ -176,6 +244,7 @@
176
244
  color: var(--ws-color-text-secondary);
177
245
  }
178
246
 
247
+ /* What a command printed: text set off by a rule on the left. */
179
248
  .ws-output {
180
249
  margin: var(--ws-space-24) 0 0;
181
250
  padding-left: var(--ws-space-16);
@@ -194,6 +263,7 @@
194
263
  font-weight: var(--ws-font-weight-semibold);
195
264
  }
196
265
 
266
+ /* The block cursor after the handle. It does not blink. */
197
267
  .ws-cursor {
198
268
  background: var(--ws-color-brand);
199
269
  border-radius: 2px;
@@ -203,6 +273,7 @@
203
273
  display: inline-block;
204
274
  }
205
275
 
276
+ /* A key cap. */
206
277
  .ws-kbd {
207
278
  min-width: 1.125rem;
208
279
  height: 1.125rem;
@@ -218,6 +289,7 @@
218
289
  display: inline-grid;
219
290
  }
220
291
 
292
+ /* A tag on a tint of the interactive color, or outlined for a plain list such as a stack. */
221
293
  .ws-tag {
222
294
  padding: var(--ws-space-2) var(--ws-space-8);
223
295
  border-radius: var(--ws-radius-sm);
@@ -236,8 +308,14 @@
236
308
  background: none;
237
309
  }
238
310
 
311
+ /*
312
+ * A state as a dot with its word. The word carries the meaning, the dot only repeats it.
313
+ * The word gives the baseline, so a state lines up with the text beside it.
314
+ *
315
+ * <span class="ws-state ws-state--active">active</span>
316
+ */
239
317
  .ws-state {
240
- align-items: center;
318
+ align-items: baseline;
241
319
  gap: var(--ws-space-8);
242
320
  color: var(--ws-color-text-secondary);
243
321
  font: var(--ws-text-caption);
@@ -250,6 +328,7 @@
250
328
  background: var(--ws-color-text-faint);
251
329
  content: "";
252
330
  flex: none;
331
+ align-self: center;
253
332
  width: .4375rem;
254
333
  height: .4375rem;
255
334
  }
@@ -262,6 +341,39 @@
262
341
  background: var(--ws-color-warning);
263
342
  }
264
343
 
344
+ /*
345
+ * Status line.
346
+ *
347
+ * <footer class="ws-status-line">
348
+ * <span class="ws-status-line__mode">NORMAL</span>
349
+ * <span class="ws-status-line__path">
350
+ * <span class="ws-status-line__file"><span>guide/conditions.md</span></span>
351
+ * </span>
352
+ * <span class="ws-status-line__item ws-status-line__item--wide">main</span>
353
+ * <span class="ws-status-line__keys">
354
+ * <button type="button" data-ws-key="t"><kbd class="ws-kbd">t</kbd>theme</button>
355
+ * </span>
356
+ * <button type="button" class="ws-status-line__switch" role="switch"
357
+ * aria-label="Shortcut keys" data-ws-keys-switch>
358
+ * keys
359
+ * <span class="ws-status-line__on" aria-hidden="true">on</span>
360
+ * <span class="ws-status-line__off" aria-hidden="true">off</span>
361
+ * </button>
362
+ * <button type="button" class="ws-status-line__theme">
363
+ * <span class="ws-visually-hidden">Switch theme, now</span>
364
+ * <span class="ws-theme-dark">rose-pine</span>
365
+ * <span class="ws-theme-light">rose-pine-dawn</span>
366
+ * </button>
367
+ * </footer>
368
+ *
369
+ * The mode says whether the key hints work: NORMAL, or INSERT while the focus is in a field.
370
+ * The path takes the room the other items leave, so they always fit.
371
+ * A key hint is the control itself: pressing the key clicks it (see the shortcuts module).
372
+ * Hints stay hidden until that module runs, so a hint is never shown for a key that does nothing.
373
+ * The switch turns the keys off and on again. A status line with key hints carries it.
374
+ * With the keys off the controls stay, without their key caps.
375
+ * The theme button names the theme shown and switches it, at every width.
376
+ */
265
377
  .ws-status-line {
266
378
  min-height: var(--ws-size-status-line);
267
379
  border-top: var(--ws-border-width-thin) solid var(--ws-color-border);
@@ -289,6 +401,12 @@
289
401
  letter-spacing: .04em;
290
402
  }
291
403
 
404
+ /*
405
+ * The room the other items leave, which the path takes: the items after it go to the right
406
+ * edge, as after a spacer. The path gives way to them inside it. It shrinks to its first
407
+ * character and the ellipsis, then goes as a whole, padding and all, so a part of a
408
+ * character never shows.
409
+ */
292
410
  .ws-status-line__path {
293
411
  flex: 1;
294
412
  min-width: 0;
@@ -308,6 +426,11 @@
308
426
  overflow: hidden;
309
427
  }
310
428
 
429
+ /*
430
+ * No room for "~…" between the padding of the path, --ws-space-14 on each side. The padding
431
+ * is written out, as a container query takes no var(). The browser test of the path,
432
+ * tests/browser/status-line.spec.ts, holds the two together.
433
+ */
311
434
  @container ws-status-line-path (width < calc(2ch + 1.75rem)) {
312
435
  .ws-status-line__file {
313
436
  display: none;
@@ -327,14 +450,17 @@
327
450
  display: none;
328
451
  }
329
452
 
330
- [data-ws-keys] .ws-status-line__keys {
453
+ /* The module says on or off once it runs. The head script's pending is not yet a yes. */
454
+ :is([data-ws-keys="on"], [data-ws-keys="off"]) .ws-status-line__keys {
331
455
  display: flex;
332
456
  }
333
457
 
458
+ /* With the keys switched off a control stays and its key cap goes: nothing names a key then. */
334
459
  [data-ws-keys="off"] .ws-status-line__keys .ws-kbd {
335
460
  display: none;
336
461
  }
337
462
 
463
+ /* Without a path and without key hints the items after them still go to the right edge. */
338
464
  .ws-status-line__spacer {
339
465
  flex: 1;
340
466
  }
@@ -345,6 +471,12 @@
345
471
  display: flex;
346
472
  }
347
473
 
474
+ /*
475
+ * A control fills the height of the line, also in a group of hints. Its focus ring is drawn
476
+ * inside it, in padding taken back from the gap between hints with a negative margin, so a
477
+ * hint does not move. The gap in a group has no room for two rings: there a control after
478
+ * another takes nothing back at its start, so it moves over and the two only meet.
479
+ */
348
480
  .ws-status-line__keys :is(button, a) {
349
481
  align-self: stretch;
350
482
  align-items: center;
@@ -364,6 +496,14 @@
364
496
  margin-left: 0;
365
497
  }
366
498
 
499
+ /*
500
+ * The keys switch and the theme button. The switch reads "keys on" or "keys off" from its own
501
+ * state, which the shortcuts module sets, and stays hidden until it has one. Unlike the hints
502
+ * both show at every width: the numbers of the tabs are keys everywhere, and with the keys
503
+ * off the switch is the way to turn them on again. The theme button is the theme switch on
504
+ * a narrow screen, where the hints are hidden. It holds the names of both themes and shows
505
+ * the one of the theme shown, so it keeps the focus when it switches.
506
+ */
367
507
  .ws-status-line__switch, .ws-status-line__theme {
368
508
  align-items: center;
369
509
  gap: var(--ws-space-6);
@@ -391,14 +531,20 @@
391
531
  display: none;
392
532
  }
393
533
 
534
+ /* The status line clips what crosses its edges, so a ring is drawn inside its control. */
394
535
  .ws-status-line__keys :is(button, a):focus-visible, .ws-status-line__switch:focus-visible, .ws-status-line__theme:focus-visible {
395
536
  outline-offset: calc(-1 * var(--ws-border-width-medium));
396
537
  }
397
538
 
539
+ /*
540
+ * The window cuts off its corners, so a ring in one follows the window's curve: that of the
541
+ * last control of the status line, and on a narrow screen that of the brand.
542
+ */
398
543
  .ws-term .ws-status-line > :last-child:focus-visible {
399
544
  border-bottom-right-radius: calc(var(--ws-radius-xl) - var(--ws-border-width-thin));
400
545
  }
401
546
 
547
+ /* Text for assistive technology only, such as the start of the theme button's name. */
402
548
  .ws-visually-hidden {
403
549
  clip-path: inset(50%);
404
550
  white-space: nowrap;
@@ -432,6 +578,7 @@
432
578
  padding-right: var(--ws-space-16);
433
579
  }
434
580
 
581
+ /* The tabs take a row of their own and share it evenly. */
435
582
  .ws-tabs {
436
583
  border-top: var(--ws-border-width-thin) solid var(--ws-color-border);
437
584
  flex-basis: 100%;
@@ -451,6 +598,7 @@
451
598
  justify-content: center;
452
599
  }
453
600
 
601
+ /* The row runs from edge to edge, so the current tab has no border at an end of it. */
454
602
  .ws-tabs li:first-child a[aria-current] {
455
603
  border-left-color: #0000;
456
604
  }
@@ -459,7 +607,8 @@
459
607
  border-right-color: #0000;
460
608
  }
461
609
 
462
- [data-ws-keys] .ws-status-line__keys, .ws-status-line__item--wide {
610
+ /* The key hints and the wide items do not fit. A key whose hint is hidden does nothing. */
611
+ :is([data-ws-keys="on"], [data-ws-keys="off"]) .ws-status-line__keys, .ws-status-line__item--wide {
463
612
  display: none;
464
613
  }
465
614
  }