@whatsaaaa/design-system 0.6.0 → 0.7.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.
@@ -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
@@ -32,8 +32,9 @@ Or take pieces. `tokens.css` and `fonts.css` first, then what you use:
32
32
  | `@whatsaaaa/design-system/css/theme.css` | `ws-theme-dark` and `ws-theme-light`, for an element of one theme only |
33
33
  | `@whatsaaaa/design-system/css/ghost.css` | Styles of `<ws-ghost>` |
34
34
  | `@whatsaaaa/design-system/css/icons.css` | The icons the callouts and prompts draw, and `--ws-icon-check`, the tick of a form. Needed with `callout.css` and `terminal.css`, and for the tick |
35
+ | `@whatsaaaa/design-system/css/nuxt-ui.css` | Nuxt UI's colors on the roles. Only in an app on Nuxt UI, after it: see With Tailwind CSS below |
35
36
 
36
- Everything is prefixed: classes with `ws-`, variables with `--ws-`.
37
+ Everything is prefixed: classes with `ws-`, variables with `--ws-`. Only `nuxt-ui.css` sets variables of another prefix, Nuxt UI's `--ui-*`.
37
38
 
38
39
  ### With Tailwind CSS
39
40
 
@@ -47,21 +48,19 @@ An app on Tailwind CSS v4, such as one on Nuxt UI, imports the Tailwind entry in
47
48
 
48
49
  Install `tailwindcss` 4.3.5 or a later 4.x next to the package. Only this entry needs it.
49
50
 
50
- The entry gives Nuxt UI the system's fonts, weights, radii and spacing, but not its colors. Nuxt UI takes its colors from its own `--ui-*` variables, which fall back to its green and slate, and without `--ui-bg` it paints the body in its own background. Pointing them at the roles is the app's job, in its stylesheet outside any layer. A variable takes the role's value where it is set, so set it on `:root`, which follows the system, and on every element that chooses a theme, with `data-theme` or the `dark` or `light` class:
51
+ The entry gives Nuxt UI the system's fonts, weights, radii and spacing, but not its colors. Nuxt UI takes its colors from its own `--ui-*` variables, which fall back to its green and slate, and without `--ui-bg` it paints the body in its own background. `css/nuxt-ui.css` points them at the roles. It is not in the entry, as it has to come after Nuxt UI, so an app on Nuxt UI imports it last:
51
52
 
52
53
  ```css
53
- :root,
54
- [data-theme],
55
- .dark,
56
- .light {
57
- --ui-primary: var(--ws-color-interactive);
58
- --ui-bg: var(--ws-color-bg);
59
- --ui-text: var(--ws-color-text);
60
- --ui-border: var(--ws-color-border);
61
- /* and the rest of Nuxt UI's colors, such as --ui-error and --ui-bg-elevated */
62
- }
54
+ @import '@whatsaaaa/design-system/tailwind.css';
55
+ @import '@nuxt/ui';
56
+ @import '@whatsaaaa/design-system/tailwind/variants.css';
57
+ @import '@whatsaaaa/design-system/css/nuxt-ui.css';
63
58
  ```
64
59
 
60
+ It sets them outside any layer, so they win over Nuxt UI's own, which it keeps in its theme layer and in a style it adds at runtime. A variable takes the role's value where it is set, so it sets them on `:root`, which follows the system, and again on every element that chooses a theme, with `data-theme` or the `dark` or `light` class, where Nuxt UI sets its own. The primary color is `--ws-color-interactive`, success, info, warning and error are tip, note, warning and danger, and `secondary` has no role, so it is left out. A step the system has no role for, such as `--ui-bg-accented` or a shade of a color other than 500, is mixed from the roles around it in oklab: a color's shades run from the page at 50 through the color at 500 to the text at 950, so a low shade is a faint tint in both themes. It also sets `--ui-radius` to `--ws-radius-sm`, and `--ui-header-height` to the height of the tab bar, 3rem where Nuxt UI's own is 4rem. Nuxt UI makes its headers that tall: the app's `UHeader`, a dashboard's navbar and the header of its sidebar, and at least the header of a modal, a slideover or a sidebar. It also leaves room for the app's header by it: `UMain` and `UError` are at least the height of the window less it, and `UPageAside`, `UContentToc` and a heading scrolled to stop below it.
61
+
62
+ To change one of them, set it after the import, outside any layer, on the same selectors: `:root, :host, [data-theme], .dark, .light`. On `:root` alone it holds only where no element around chooses a theme, as the stylesheet sets its own value again on each one that does.
63
+
65
64
  The entry brings Tailwind and everything `index.css` brings, in cascade layers, so a utility wins over a class of the system and the app's rules outside any layer win over both:
66
65
 
67
66
  | Layer | What it has, the later winning |
@@ -114,15 +113,17 @@ Use the role tokens. Never write a hex value, and never use a `--ws-palette-*` c
114
113
  | Text | `--ws-color-text` |
115
114
  | Secondary text | `--ws-color-text-secondary` |
116
115
  | Disabled text, idle marks | `--ws-color-text-faint` |
117
- | Brand accent | `--ws-color-brand` |
116
+ | Brand accent, where you are | `--ws-color-brand`, with `--ws-color-on-brand` on `--ws-color-brand-fill` for small text |
118
117
  | Links, focus ring, primary button | `--ws-color-interactive`, with `--ws-color-on-interactive` for text on it |
119
118
  | Primary button, hovered or pressed | `--ws-color-interactive-hover`, `--ws-color-interactive-active` |
120
119
  | Tags | `--ws-color-tag-text` on `--ws-color-tag-bg` |
121
120
  | Status | `--ws-color-tip`, `-note`, `-warning`, `-danger`: each with `-text` for its label and `-tint` for its background |
121
+ | An error | `--ws-color-danger` for the border and icon, `--ws-color-danger-text` for the message |
122
122
 
123
123
  Rules:
124
124
 
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`.
125
+ - **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`.
126
+ - **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
127
  - **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
128
  - **Faint is never body text.** `--ws-color-text-faint` is 3:1.
128
129
  - **Status text uses the `-text` token**, not the status color. On the light theme the two differ.
@@ -145,6 +146,33 @@ setTheme('system') // follows the system again
145
146
 
146
147
  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
148
 
149
+ 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:
150
+
151
+ ```ts
152
+ // vite.config.ts
153
+ import { defineConfig, type Plugin } from 'vite'
154
+ import { keysInitScript } from '@whatsaaaa/design-system/shortcuts'
155
+ import { themeInitScript } from '@whatsaaaa/design-system/theme'
156
+
157
+ function designSystemHead(): Plugin {
158
+ return {
159
+ name: 'design-system-head',
160
+ transformIndexHtml: {
161
+ // before Vite adds the stylesheet and the app's script to the <head>
162
+ order: 'pre',
163
+ handler: () => [
164
+ { tag: 'script', children: themeInitScript, injectTo: 'head' },
165
+ { tag: 'script', children: keysInitScript, injectTo: 'head' },
166
+ ],
167
+ },
168
+ }
169
+ }
170
+
171
+ export default defineConfig({
172
+ plugins: [designSystemHead()],
173
+ })
174
+ ```
175
+
148
176
  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
177
 
150
178
  ```html
@@ -209,11 +237,12 @@ Do not load other fonts, and do not load these from a CDN. Set `font-variant-lig
209
237
  - 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
238
  - 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
239
  - 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"`.
240
+ - 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.
241
+ - 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
242
  - 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
243
  - Forms: `ws-segmented` and `ws-pairs`. See [forms](#forms).
215
244
 
216
- The markup of each piece is in the comment at the top of its stylesheet, and in the style guide.
245
+ 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
246
 
218
247
  ### Status line
219
248
 
@@ -330,7 +359,7 @@ import { enableShortcuts } from '@whatsaaaa/design-system/shortcuts'
330
359
  enableShortcuts()
331
360
  ```
332
361
 
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.
362
+ 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
363
 
335
364
  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
365
 
@@ -339,7 +368,7 @@ The switch is not optional. The keys are single characters that act on the whole
339
368
  - 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
369
  - 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
370
  - 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.
371
+ - 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
372
 
344
373
  ## 8. The ghost
345
374
 
@@ -415,5 +444,5 @@ The sources are in `tokens/`, in the Design Tokens Community Group format.
415
444
 
416
445
  - No hex values, no `--ws-palette-*` in interface code, no fonts from elsewhere.
417
446
  - It reads in both themes. Check with `data-theme="light"` on `<html>`.
418
- - Nothing overflows sideways at 390 px.
447
+ - 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
448
  - 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.7.0",
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,