@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.
@@ -6,12 +6,12 @@
6
6
  * tabs of a tab bar, which numbers them. The switch, declared with `data-ws-keys-switch`,
7
7
  * turns every key off or on again, and the choice is kept in localStorage.
8
8
  *
9
- * The styles keep key hints hidden until `enableShortcuts()` has run, so a page never shows a
10
- * hint for a key that does nothing. For the same reason `aria-keyshortcuts` is set here, while
11
- * the key works, and not written in the markup. The state of the switch, `aria-checked`, is
12
- * set here too: the styles keep the switch hidden until it has one, so it never shows a state
13
- * that is not the real one. A key acts only on a page that has that switch: a page without it
14
- * has no shortcuts.
9
+ * The styles keep key hints and the numbers of the tabs hidden until `enableShortcuts()` has
10
+ * run, so a page never shows a hint for a key that does nothing. For the same reason
11
+ * `aria-keyshortcuts` is set here, while the key works, and not written in the markup. The
12
+ * state of the switch, `aria-checked`, is set here too: the styles keep the switch hidden
13
+ * until it has one, so it never shows a state that is not the real one. A key acts only on a
14
+ * page that has that switch: a page without it has no shortcuts.
15
15
  *
16
16
  * A held key acts once. The repeats a keyboard sends while a key is down do nothing, so a
17
17
  * finger that rests on t does not flash the page between its themes.
@@ -39,9 +39,11 @@ export declare function shortcutsOn(): boolean;
39
39
  */
40
40
  export declare function enableShortcuts({ tabs }?: ShortcutOptions): () => void;
41
41
  /**
42
- * A script for the <head> that marks the page before the first paint when the keys are
43
- * remembered as off. The styles then leave out what names a key, the numbers of the tabs
44
- * among it, from the start instead of taking it away once `enableShortcuts()` runs.
42
+ * A script for the <head> that marks the page before the first paint: `off` when the keys
43
+ * are remembered as off, and `pending` otherwise, until `enableShortcuts()` says on or off.
44
+ * With off the styles leave out what names a key, the numbers of the tabs among it, from the
45
+ * start instead of taking it away. With pending the numbers keep their place unseen, so the
46
+ * labels of the tabs do not move when the module shows them.
45
47
  *
46
48
  * <script>{keysInitScript}</script>
47
49
  */
@@ -6,12 +6,12 @@
6
6
  * tabs of a tab bar, which numbers them. The switch, declared with `data-ws-keys-switch`,
7
7
  * turns every key off or on again, and the choice is kept in localStorage.
8
8
  *
9
- * The styles keep key hints hidden until `enableShortcuts()` has run, so a page never shows a
10
- * hint for a key that does nothing. For the same reason `aria-keyshortcuts` is set here, while
11
- * the key works, and not written in the markup. The state of the switch, `aria-checked`, is
12
- * set here too: the styles keep the switch hidden until it has one, so it never shows a state
13
- * that is not the real one. A key acts only on a page that has that switch: a page without it
14
- * has no shortcuts.
9
+ * The styles keep key hints and the numbers of the tabs hidden until `enableShortcuts()` has
10
+ * run, so a page never shows a hint for a key that does nothing. For the same reason
11
+ * `aria-keyshortcuts` is set here, while the key works, and not written in the markup. The
12
+ * state of the switch, `aria-checked`, is set here too: the styles keep the switch hidden
13
+ * until it has one, so it never shows a state that is not the real one. A key acts only on a
14
+ * page that has that switch: a page without it has no shortcuts.
15
15
  *
16
16
  * A held key acts once. The repeats a keyboard sends while a key is down do nothing, so a
17
17
  * finger that rests on t does not flash the page between its themes.
@@ -146,10 +146,12 @@ export function enableShortcuts({ tabs = '.ws-tabs a' } = {}) {
146
146
  };
147
147
  }
148
148
  /**
149
- * A script for the <head> that marks the page before the first paint when the keys are
150
- * remembered as off. The styles then leave out what names a key, the numbers of the tabs
151
- * among it, from the start instead of taking it away once `enableShortcuts()` runs.
149
+ * A script for the <head> that marks the page before the first paint: `off` when the keys
150
+ * are remembered as off, and `pending` otherwise, until `enableShortcuts()` says on or off.
151
+ * With off the styles leave out what names a key, the numbers of the tabs among it, from the
152
+ * start instead of taking it away. With pending the numbers keep their place unseen, so the
153
+ * labels of the tabs do not move when the module shows them.
152
154
  *
153
155
  * <script>{keysInitScript}</script>
154
156
  */
155
- export const keysInitScript = `(function(){try{if(localStorage.getItem(${JSON.stringify(KEYS_STORAGE_KEY)})==='off')document.documentElement.dataset.wsKeys='off'}catch(e){}})()`;
157
+ export const keysInitScript = `(function(){var keys='pending';try{if(localStorage.getItem(${JSON.stringify(KEYS_STORAGE_KEY)})==='off')keys='off'}catch(e){}document.documentElement.dataset.wsKeys=keys})()`;
@@ -1,2 +1,2 @@
1
- // Marks the page before the first paint when the keys are remembered as off. Generated from src/shortcuts/index.ts.
2
- (function(){try{if(localStorage.getItem("ws-keys")==='off')document.documentElement.dataset.wsKeys='off'}catch(e){}})()
1
+ // Marks the keys before the first paint: off when they are remembered as off, and pending until the shortcuts module runs. Generated from src/shortcuts/index.ts.
2
+ (function(){var keys='pending';try{if(localStorage.getItem("ws-keys")==='off')keys='off'}catch(e){}document.documentElement.dataset.wsKeys=keys})()
@@ -23,7 +23,8 @@ export function whatsaaaaConfig() {
23
23
  ['script', { id: 'ws-theme' }, themeScript],
24
24
  // the browser's own bars take the background of the theme shown, as VitePress switches it
25
25
  ['script', { id: 'ws-theme-color' }, themeColorScript],
26
- // keys that are remembered as off are off from the first paint: no tab shows its number
26
+ // from the first paint the keys are pending, so the numbers of the tabs keep their place
27
+ // unseen until the module runs, or off where they are remembered so, with no numbers
27
28
  ['script', { id: 'ws-keys' }, keysInitScript],
28
29
  ],
29
30
  markdown: {
package/docs/usage.md CHANGED
@@ -114,15 +114,17 @@ Use the role tokens. Never write a hex value, and never use a `--ws-palette-*` c
114
114
  | Text | `--ws-color-text` |
115
115
  | Secondary text | `--ws-color-text-secondary` |
116
116
  | Disabled text, idle marks | `--ws-color-text-faint` |
117
- | Brand accent | `--ws-color-brand` |
117
+ | Brand accent, where you are | `--ws-color-brand`, with `--ws-color-on-brand` on `--ws-color-brand-fill` for small text |
118
118
  | Links, focus ring, primary button | `--ws-color-interactive`, with `--ws-color-on-interactive` for text on it |
119
119
  | Primary button, hovered or pressed | `--ws-color-interactive-hover`, `--ws-color-interactive-active` |
120
120
  | Tags | `--ws-color-tag-text` on `--ws-color-tag-bg` |
121
121
  | Status | `--ws-color-tip`, `-note`, `-warning`, `-danger`: each with `-text` for its label and `-tint` for its background |
122
+ | An error | `--ws-color-danger` for the border and icon, `--ws-color-danger-text` for the message |
122
123
 
123
124
  Rules:
124
125
 
125
- - **Brand is not for controls.** `--ws-color-brand` is the accent and the color of an error. Buttons, links, focus and checked controls use `--ws-color-interactive`.
126
+ - **Brand is not for controls.** What you press, and its hover, focus and checked states, uses `--ws-color-interactive`: buttons, links, the focus ring, checked boxes. `--ws-color-brand` is the accent: the mark, the cursor, a prompt's chevron, and the marks of where you are, such as the bar and number of the current tab and the mode of the status line. A mark of where you are may sit on a control, as on the current tab, because it says where you are, not what to press. So the current step of a form takes brand too: its number in `--ws-color-on-brand` on `--ws-color-brand-fill`.
127
+ - **An error uses the danger tokens, not brand.** A field in error takes `--ws-color-danger` for its border and its icon, and its message `--ws-color-danger-text`. On the dark theme they have the value of brand, but they are other roles: on the light theme brand is too light for small text, and the message takes the text color.
126
128
  - **Brand is for graphics and large type.** For small text on the brand color use `--ws-color-on-brand` on `--ws-color-brand-fill`.
127
129
  - **Faint is never body text.** `--ws-color-text-faint` is 3:1.
128
130
  - **Status text uses the `-text` token**, not the status color. On the light theme the two differ.
@@ -145,6 +147,33 @@ setTheme('system') // follows the system again
145
147
 
146
148
  Run the head script before the stylesheet, so a remembered choice applies before the first paint. Inline `themeInitScript` in a `<script>`, or load it as a file: `<script src=".../theme/init.js"></script>`. It is a plain script, not a module.
147
149
 
150
+ A bundler does not copy a plain script out of `node_modules`, so in an app built with Vite inline both head scripts, this one and the one of the keys in section 7, with a plugin. They come from the installed package, so they stay in step with it:
151
+
152
+ ```ts
153
+ // vite.config.ts
154
+ import { defineConfig, type Plugin } from 'vite'
155
+ import { keysInitScript } from '@whatsaaaa/design-system/shortcuts'
156
+ import { themeInitScript } from '@whatsaaaa/design-system/theme'
157
+
158
+ function designSystemHead(): Plugin {
159
+ return {
160
+ name: 'design-system-head',
161
+ transformIndexHtml: {
162
+ // before Vite adds the stylesheet and the app's script to the <head>
163
+ order: 'pre',
164
+ handler: () => [
165
+ { tag: 'script', children: themeInitScript, injectTo: 'head' },
166
+ { tag: 'script', children: keysInitScript, injectTo: 'head' },
167
+ ],
168
+ },
169
+ }
170
+ }
171
+
172
+ export default defineConfig({
173
+ plugins: [designSystemHead()],
174
+ })
175
+ ```
176
+
148
177
  The browser's own bars, such as a phone's address bar, take the background of the theme shown, `--ws-color-bg`. The head script keeps `<meta name="theme-color">` at it from the first paint on, when the theme is chosen by hand, with `setTheme`, `toggleTheme` or anything else that sets `data-theme` or the class of `<html>`, and when the system's theme changes. A page that has no theme-color tag gets one, so the head needs no tag of its own and no color in it:
149
178
 
150
179
  ```html
@@ -209,11 +238,12 @@ Do not load other fonts, and do not load these from a CDN. Set `font-variant-lig
209
238
  - Long-form text: put rendered Markdown in `<article class="ws-prose">`. Wrap a table in `<div class="ws-table">` so it scrolls inside itself, and give a cell of running text `class="ws-table__text"` so a narrow frame scrolls instead of squeezing it. A first cell stays on one line unless it has that class. The docs theme does both.
210
239
  - Code block with a caption: `<figure class="ws-code"><figcaption><span>file.ts</span><span>ts</span></figcaption><pre><code>...</code></pre></figure>`. For highlighting, use Shiki with `codeTheme` from `@whatsaaaa/design-system/shiki`. See [code blocks](#code-blocks).
211
240
  - Callout: `<aside class="ws-callout ws-callout--warning"><p class="ws-callout__title">Warning</p><p>...</p></aside>`. Modifiers: `--tip`, `--warning`, `--danger`. None is a note.
212
- - Terminal frame: `ws-term` (the window), `ws-tab-bar` with `ws-tab-bar__brand`, `ws-tabs` and `ws-tab-bar__end`, `ws-prompt` for headings, `ws-output`, `ws-status-line`. Mark the current tab with `aria-current="page"`.
241
+ - Terminal frame: `ws-term` (the window), `ws-tab-bar` with `ws-tab-bar__brand`, `ws-tabs` and `ws-tab-bar__end`, `ws-prompt` for headings, `ws-output`, `ws-status-line`. Mark the current tab with `aria-current="page"`. The tabs are optional: a site of one page has nothing to tab to, and a tab that only reloads the page would lose what was typed in it. Its bar is the brand and the end.
242
+ - The path above a page title: `<p class="ws-crumb"><span>writing</span><span>form-builder</span><span>conditions</span></p>`, right before the `<h1>`. The slashes between the parts are drawn, and assistive technology reads a comma in their place, so the parts come out as words of their own. It comes with `prose.css`.
213
243
  - Small pieces: `ws-kbd`, `ws-tag`, `ws-tag--outline`, `ws-state` with `--active` or `--experimental`, `ws-arrow`, `ws-cursor`, and `ws-visually-hidden` for text that only assistive technology reads.
214
244
  - Forms: `ws-segmented` and `ws-pairs`. See [forms](#forms).
215
245
 
216
- The markup of each piece is in the comment at the top of its stylesheet, and in the style guide.
246
+ The markup of each piece is in the comment above its rules, in its stylesheet in `dist/css/` and in `dist/index.css`, and in the style guide.
217
247
 
218
248
  ### Status line
219
249
 
@@ -330,7 +360,7 @@ import { enableShortcuts } from '@whatsaaaa/design-system/shortcuts'
330
360
  enableShortcuts()
331
361
  ```
332
362
 
333
- Hints are hidden until `enableShortcuts()` runs, and below 64rem. A key works only while its hint shows. Do not show a hint any other way. Number keys go to the tabs of a `ws-tabs` bar. Keys typed into a field, and keys pressed with Ctrl, Alt or Cmd, are left alone. A held key acts once: the repeats a keyboard sends while the key is down do nothing.
363
+ Hints are hidden until `enableShortcuts()` runs, and below 64rem. A key works only while its hint shows. Do not show a hint any other way. Number keys go to the tabs of a `ws-tabs` bar, and the number of a tab is drawn only while the keys are on, so a page without the module, or without JavaScript, shows none. Keys typed into a field, and keys pressed with Ctrl, Alt or Cmd, are left alone. A held key acts once: the repeats a keyboard sends while the key is down do nothing.
334
364
 
335
365
  The switch is not optional. The keys are single characters that act on the whole page, so a visitor has to be able to turn them off (WCAG 2.1.4): it matters most with speech input, where a dictated word presses them, and for someone who presses keys without meaning to.
336
366
 
@@ -339,7 +369,7 @@ The switch is not optional. The keys are single characters that act on the whole
339
369
  - Do not write `aria-checked` on the switch or `aria-keyshortcuts` on a control. The module sets both while they are true, and the switch stays hidden until it has its state.
340
370
  - With the keys off the controls stay and work by hand. What names a key goes: the key caps and the numbers of the tabs. Hide a control that is nothing but a key cap with `[data-ws-keys='off']`.
341
371
  - A key acts only on a page that has the switch. A page without the switch has no shortcuts.
342
- - Load `shortcuts/init.js` in the head, next to `theme/init.js`, or inline `keysInitScript`. It marks the page before the first paint when the keys are remembered as off, so the tab numbers are not drawn first and then taken away.
372
+ - Load `shortcuts/init.js` in the head, next to `theme/init.js`, or inline `keysInitScript` (with Vite, see section 3). It marks the page before the first paint: `data-ws-keys="off"` when the keys are remembered as off, and `pending` until the module says `on`. So the numbers of the tabs keep their place unseen while the module loads, and the labels do not move when they show. Do not write `data-ws-keys` yourself: the head script and the module own it.
343
373
 
344
374
  ## 8. The ghost
345
375
 
@@ -415,5 +445,5 @@ The sources are in `tokens/`, in the Design Tokens Community Group format.
415
445
 
416
446
  - No hex values, no `--ws-palette-*` in interface code, no fonts from elsewhere.
417
447
  - It reads in both themes. Check with `data-theme="light"` on `<html>`.
418
- - Nothing overflows sideways at 390 px.
448
+ - Nothing overflows sideways at 390 px, and nothing is cut off. The window hides what overflows it, so a page can fit while the window clips its content: measure the window too, and its bars, not only the page. Each `scrollWidth` of `document.documentElement`, `.ws-term`, `.ws-tab-bar` and `.ws-status-line` is at most its `clientWidth`.
419
449
  - Every key hint works, every status has a word, every control can be reached and seen with the keyboard.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@whatsaaaa/design-system",
3
- "version": "0.6.0",
3
+ "version": "0.6.1",
4
4
  "description": "Whatsaaaa's design system: brand identity, design tokens, typography, docs theme and asset kit",
5
5
  "homepage": "https://github.com/whatsaaaa/design-system#readme",
6
6
  "bugs": "https://github.com/whatsaaaa/design-system/issues",
@@ -84,18 +84,25 @@
84
84
  line-height: inherit;
85
85
  }
86
86
 
87
- .VPNav .VPNavBarMenu .VPNavBarMenuLink::before,
88
- .VPNav .VPNavBarMenu .VPNavBarMenuGroup .button::before {
87
+ /*
88
+ * the number names the key that goes to the tab, so it is drawn only while the keys are on.
89
+ * While the head script waits for the shortcuts module it keeps its place unseen.
90
+ */
91
+ :is([data-ws-keys='on'], [data-ws-keys='pending']) .VPNav .VPNavBarMenu .VPNavBarMenuLink::before,
92
+ :is([data-ws-keys='on'], [data-ws-keys='pending'])
93
+ .VPNav
94
+ .VPNavBarMenu
95
+ .VPNavBarMenuGroup
96
+ .button::before {
89
97
  color: var(--ws-color-text-faint);
90
98
  font-weight: var(--ws-font-weight-bold);
91
99
  content: counter(ws-tab);
92
100
  content: counter(ws-tab) / '';
93
101
  }
94
102
 
95
- /* the number names the key that goes to the tab. With the keys switched off it is left out. */
96
- [data-ws-keys='off'] .VPNav .VPNavBarMenu .VPNavBarMenuLink::before,
97
- [data-ws-keys='off'] .VPNav .VPNavBarMenu .VPNavBarMenuGroup .button::before {
98
- content: none;
103
+ [data-ws-keys='pending'] .VPNav .VPNavBarMenu .VPNavBarMenuLink::before,
104
+ [data-ws-keys='pending'] .VPNav .VPNavBarMenu .VPNavBarMenuGroup .button::before {
105
+ visibility: hidden;
99
106
  }
100
107
 
101
108
  .VPNav .VPNavBarMenu .VPNavBarMenuLink:hover,