@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 +2 -2
- package/dist/css/base.css +21 -1
- package/dist/css/callout.css +10 -0
- package/dist/css/code.css +24 -0
- package/dist/css/ghost.css +24 -0
- package/dist/css/icons.css +12 -0
- package/dist/css/pairs.css +26 -0
- package/dist/css/prose.css +20 -1
- package/dist/css/segmented.css +20 -0
- package/dist/css/terminal.css +158 -9
- package/dist/css/theme.css +20 -0
- package/dist/index.css +304 -11
- package/dist/shortcuts/index.d.ts +11 -9
- package/dist/shortcuts/index.js +12 -10
- package/dist/shortcuts/init.js +2 -2
- package/dist/vitepress-config/index.js +2 -1
- package/docs/usage.md +37 -7
- package/package.json +1 -1
- package/src/vitepress/styles/nav.css +13 -6
|
@@ -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
|
|
10
|
-
* hint for a key that does nothing. For the same reason
|
|
11
|
-
* the key works, and not written in the markup. The
|
|
12
|
-
* set here too: the styles keep the switch hidden
|
|
13
|
-
* that is not the real one. A key acts only on a
|
|
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
|
|
43
|
-
* remembered as off
|
|
44
|
-
*
|
|
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
|
*/
|
package/dist/shortcuts/index.js
CHANGED
|
@@ -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
|
|
10
|
-
* hint for a key that does nothing. For the same reason
|
|
11
|
-
* the key works, and not written in the markup. The
|
|
12
|
-
* set here too: the styles keep the switch hidden
|
|
13
|
-
* that is not the real one. A key acts only on a
|
|
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
|
|
150
|
-
* remembered as off
|
|
151
|
-
*
|
|
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')
|
|
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})()`;
|
package/dist/shortcuts/init.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
// Marks the
|
|
2
|
-
(function(){try{if(localStorage.getItem("ws-keys")==='off')
|
|
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
|
-
//
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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
|
-
|
|
88
|
-
|
|
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
|
-
|
|
96
|
-
[data-ws-keys='
|
|
97
|
-
|
|
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,
|