@whatsaaaa/design-system 0.1.0 → 0.1.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.
@@ -1,36 +1,22 @@
1
1
  /**
2
2
  * Keyboard shortcuts that cannot lie, and that a visitor can switch off.
3
3
  *
4
- * A shortcut is declared on the control it presses:
5
- *
6
- * <button type="button" data-ws-key="t"><kbd class="ws-kbd">t</kbd>theme</button>
7
- *
8
- * Pressing t clicks that button, so the hint and the action are one element. The styles
9
- * keep key hints hidden until `enableShortcuts()` has run, so a page never shows a hint
10
- * 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.
12
- *
13
- * The number keys go to the tabs of a tab bar, which numbers them.
14
- *
15
- * The keys are single characters that act on the whole page, so the page carries a switch
16
- * for them, declared the same way:
17
- *
18
- * <button type="button" class="ws-status-line__switch" role="switch"
19
- * aria-label="Shortcut keys" data-ws-keys-switch>
20
- * keys
21
- * <span class="ws-status-line__on" aria-hidden="true">on</span>
22
- * <span class="ws-status-line__off" aria-hidden="true">off</span>
23
- * </button>
24
- *
25
- * Pressing it turns every key off or on again, and the browser remembers the choice. With
26
- * the keys off the controls stay and work by hand. Only what names a key goes: the key caps
27
- * and the numbers of the tabs. The state of the switch, `aria-checked`, is set here: the
28
- * styles keep the switch hidden until it has one, so it never shows a state that is not the
29
- * real one. A key acts only on a page that has that switch: a page without it has no
30
- * shortcuts.
4
+ * A shortcut is declared on the control it presses, with `data-ws-key`, so pressing the key
5
+ * clicks that control and the hint and the action are one element. The number keys go to the
6
+ * tabs of a tab bar, which numbers them. The switch, declared with `data-ws-keys-switch`,
7
+ * turns every key off or on again, and the choice is kept in localStorage.
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.
31
15
  *
32
16
  * A held key acts once. The repeats a keyboard sends while a key is down do nothing, so a
33
17
  * finger that rests on t does not flash the page between its themes.
18
+ *
19
+ * The markup and the rules for a page that uses this module are in docs/usage.md, section 7.
34
20
  */
35
21
  export interface ShortcutOptions {
36
22
  /** A selector for the tabs the number keys go to, in their order. */
@@ -1,36 +1,22 @@
1
1
  /**
2
2
  * Keyboard shortcuts that cannot lie, and that a visitor can switch off.
3
3
  *
4
- * A shortcut is declared on the control it presses:
4
+ * A shortcut is declared on the control it presses, with `data-ws-key`, so pressing the key
5
+ * clicks that control and the hint and the action are one element. The number keys go to the
6
+ * tabs of a tab bar, which numbers them. The switch, declared with `data-ws-keys-switch`,
7
+ * turns every key off or on again, and the choice is kept in localStorage.
5
8
  *
6
- * <button type="button" data-ws-key="t"><kbd class="ws-kbd">t</kbd>theme</button>
7
- *
8
- * Pressing t clicks that button, so the hint and the action are one element. The styles
9
- * keep key hints hidden until `enableShortcuts()` has run, so a page never shows a hint
10
- * 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.
12
- *
13
- * The number keys go to the tabs of a tab bar, which numbers them.
14
- *
15
- * The keys are single characters that act on the whole page, so the page carries a switch
16
- * for them, declared the same way:
17
- *
18
- * <button type="button" class="ws-status-line__switch" role="switch"
19
- * aria-label="Shortcut keys" data-ws-keys-switch>
20
- * keys
21
- * <span class="ws-status-line__on" aria-hidden="true">on</span>
22
- * <span class="ws-status-line__off" aria-hidden="true">off</span>
23
- * </button>
24
- *
25
- * Pressing it turns every key off or on again, and the browser remembers the choice. With
26
- * the keys off the controls stay and work by hand. Only what names a key goes: the key caps
27
- * and the numbers of the tabs. The state of the switch, `aria-checked`, is set here: the
28
- * styles keep the switch hidden until it has one, so it never shows a state that is not the
29
- * real one. A key acts only on a page that has that switch: a page without it has no
30
- * shortcuts.
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.
31
15
  *
32
16
  * A held key acts once. The repeats a keyboard sends while a key is down do nothing, so a
33
17
  * finger that rests on t does not flash the page between its themes.
18
+ *
19
+ * The markup and the rules for a page that uses this module are in docs/usage.md, section 7.
34
20
  */
35
21
  /** Where the choice is kept in localStorage. Nothing is stored while the keys are on. */
36
22
  export const KEYS_STORAGE_KEY = 'ws-keys';
package/docs/usage.md CHANGED
@@ -142,12 +142,12 @@ import { enableShortcuts } from '@whatsaaaa/design-system/shortcuts'
142
142
  enableShortcuts()
143
143
  ```
144
144
 
145
- 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. A held key acts once: the repeats a keyboard sends while the key is down do nothing.
145
+ 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.
146
146
 
147
- 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.
147
+ 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.
148
148
 
149
149
  - It reads "keys on" or "keys off". Pressing it turns every key off or on again, and the browser remembers the choice.
150
- - Put it in the status line, outside `ws-status-line__keys`: it shows at every width, the hints do not.
150
+ - Put it in the status line, outside `ws-status-line__keys`: unlike the hints it shows at every width, because the number of a tab is a key at every width.
151
151
  - 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.
152
152
  - 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']`.
153
153
  - A key acts only on a page that has the switch. A page without the switch has no shortcuts.
@@ -203,7 +203,7 @@ export default defineConfigWithTheme<ThemeConfig>({
203
203
 
204
204
  Keep the site's nav, sidebar and search config as they are. Do not restyle the theme with `--vp-*` variables: change a token here instead.
205
205
 
206
- From 60rem up the brand has a box as wide as the sidebar, and the first tab starts on the sidebar's border, on pages without a sidebar too. With a logo there is room for about 23 characters in the site title, without one about 28. A longer title is cut with an ellipsis, and a short one leaves a gap before the tabs. The labels of the tabs have no such limit. Below 60rem there is no sidebar and the tabs follow the brand, and on a phone they take a row of their own under it.
206
+ From 60rem up the brand has a box as wide as the sidebar, 17rem with the sidebar's padding, and the first tab starts on the sidebar's border, on pages without a sidebar too. With a logo there is room for about 23 characters in the site title, without one about 28. A longer title is cut with an ellipsis: shorten it with `themeConfig.siteTitle`. A short one leaves a gap before the tabs. The labels of the tabs have no such limit: a long one moves the tabs after it. Below 60rem there is no sidebar and the tabs follow the brand, and on a phone they take a row of their own under it.
207
207
 
208
208
  ## 11. Data
209
209
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@whatsaaaa/design-system",
3
- "version": "0.1.0",
3
+ "version": "0.1.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",