@auriel/peppertino 0.5.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.
Files changed (134) hide show
  1. package/CHANGELOG.txt +249 -224
  2. package/LICENSE +21 -21
  3. package/MIGRATION.md +52 -52
  4. package/README.md +811 -764
  5. package/agents/peppertino/SKILL.md +84 -0
  6. package/agents/peppertino/accordion.md +134 -0
  7. package/agents/peppertino/alert.md +116 -0
  8. package/agents/peppertino/badge.md +74 -0
  9. package/agents/peppertino/base.md +252 -0
  10. package/agents/peppertino/button.md +65 -0
  11. package/agents/peppertino/card.md +82 -0
  12. package/agents/peppertino/carousel.md +147 -0
  13. package/agents/peppertino/catalog.md +83 -0
  14. package/agents/peppertino/components-ai-search.md +10 -0
  15. package/agents/peppertino/components-display.md +19 -0
  16. package/agents/peppertino/components-inputs.md +15 -0
  17. package/agents/peppertino/components-navigation.md +12 -0
  18. package/agents/peppertino/dark-mode.md +152 -0
  19. package/agents/peppertino/footer.md +109 -0
  20. package/agents/peppertino/forms-fieldset.md +85 -0
  21. package/agents/peppertino/forms-form-instructions.md +94 -0
  22. package/agents/peppertino/forms-label.md +110 -0
  23. package/agents/peppertino/forms-text-field.md +134 -0
  24. package/agents/peppertino/forms-validation.md +153 -0
  25. package/agents/peppertino/gradient.md +41 -0
  26. package/agents/peppertino/header.md +105 -0
  27. package/agents/peppertino/modal.md +123 -0
  28. package/agents/peppertino/section.md +56 -0
  29. package/agents/peppertino/select.md +110 -0
  30. package/agents/peppertino/switch.md +72 -0
  31. package/agents/peppertino/table.md +69 -0
  32. package/agents/peppertino/tabs.md +115 -0
  33. package/agents/peppertino/toast.md +96 -0
  34. package/agents/peppertino/tooltip.md +111 -0
  35. package/agents/peppertino/typography.md +118 -0
  36. package/agents/peppertino/utilities.md +194 -0
  37. package/agents/skill.md +65 -0
  38. package/build.js +53 -53
  39. package/dist/accordion.js +1 -1
  40. package/dist/accordion.js.map +2 -2
  41. package/dist/alert.js.map +1 -1
  42. package/dist/carousel.js.map +1 -1
  43. package/dist/header.js.map +1 -1
  44. package/dist/main.css +2566 -1008
  45. package/dist/main.css.map +1 -1
  46. package/dist/main.min.css +1 -0
  47. package/dist/modal.js.map +1 -1
  48. package/dist/peppertino.js +1 -1
  49. package/dist/peppertino.js.map +2 -2
  50. package/dist/select.js.map +1 -1
  51. package/dist/switch.js.map +1 -1
  52. package/dist/tabs.js.map +1 -1
  53. package/dist/theme.js.map +1 -1
  54. package/dist/toast.js.map +1 -1
  55. package/dist/validation.js.map +1 -1
  56. package/icon.svg +4 -0
  57. package/index.html +2177 -2098
  58. package/package.json +28 -28
  59. package/scripts/hex-to-hsl.mjs +75 -75
  60. package/scripts/lint-bem.mjs +53 -53
  61. package/scripts/lint-colors.mjs +87 -87
  62. package/site.webmanifest +18 -0
  63. package/src/js/accordion.js +105 -103
  64. package/src/js/alert.js +28 -28
  65. package/src/js/carousel.js +153 -153
  66. package/src/js/header.js +85 -85
  67. package/src/js/modal.js +138 -138
  68. package/src/js/peppertino.js +15 -15
  69. package/src/js/select.js +101 -101
  70. package/src/js/switch.js +28 -28
  71. package/src/js/tabs.js +104 -104
  72. package/src/js/theme.js +47 -47
  73. package/src/js/toast.js +79 -79
  74. package/src/js/validation.js +132 -132
  75. package/src/scss/accordion.scss +190 -156
  76. package/src/scss/activity.scss +17 -0
  77. package/src/scss/alert.scss +203 -203
  78. package/src/scss/badge.scss +90 -90
  79. package/src/scss/base.scss +511 -506
  80. package/src/scss/button.scss +119 -119
  81. package/src/scss/card.scss +121 -121
  82. package/src/scss/carousel.scss +303 -303
  83. package/src/scss/code-block.scss +22 -0
  84. package/src/scss/counter.scss +5 -0
  85. package/src/scss/dark-mode.scss +514 -514
  86. package/src/scss/duration.scss +26 -0
  87. package/src/scss/folder.scss +27 -0
  88. package/src/scss/footer.scss +224 -224
  89. package/src/scss/forms/fieldset.scss +127 -127
  90. package/src/scss/forms/form-instructions.scss +133 -133
  91. package/src/scss/forms/label.scss +115 -115
  92. package/src/scss/forms/text-field.scss +240 -240
  93. package/src/scss/forms/validation.scss +215 -215
  94. package/src/scss/forms.scss +8 -8
  95. package/src/scss/gradient.scss +11 -11
  96. package/src/scss/gravity-letters.scss +7 -0
  97. package/src/scss/header.scss +257 -238
  98. package/src/scss/helpers/color.scss +9 -0
  99. package/src/scss/helpers/flex.scss +14 -0
  100. package/src/scss/helpers/index.scss +6 -0
  101. package/src/scss/helpers/layout.scss +14 -0
  102. package/src/scss/helpers/spacing.scss +14 -0
  103. package/src/scss/helpers/typography.scss +11 -0
  104. package/src/scss/helpers/visibility.scss +9 -0
  105. package/src/scss/main.scss +49 -24
  106. package/src/scss/modal.scss +188 -188
  107. package/src/scss/model-picker.scss +5 -0
  108. package/src/scss/notification.scss +5 -0
  109. package/src/scss/orb.scss +7 -0
  110. package/src/scss/otp.scss +5 -0
  111. package/src/scss/pill-nav.scss +10 -0
  112. package/src/scss/prompt.scss +28 -0
  113. package/src/scss/rail.scss +7 -0
  114. package/src/scss/reactions.scss +5 -0
  115. package/src/scss/reset.scss +84 -84
  116. package/src/scss/response.scss +11 -0
  117. package/src/scss/reveal.scss +5 -0
  118. package/src/scss/scroll-progress.scss +4 -0
  119. package/src/scss/search-results.scss +13 -0
  120. package/src/scss/section.scss +87 -79
  121. package/src/scss/select.scss +210 -210
  122. package/src/scss/sidebar.scss +8 -0
  123. package/src/scss/status.scss +5 -0
  124. package/src/scss/step-list.scss +13 -0
  125. package/src/scss/switch.scss +121 -121
  126. package/src/scss/table.scss +89 -89
  127. package/src/scss/tabs.scss +156 -156
  128. package/src/scss/task-list.scss +18 -0
  129. package/src/scss/theme-picker.scss +5 -0
  130. package/src/scss/toast.scss +170 -170
  131. package/src/scss/tooltip.scss +126 -126
  132. package/src/scss/typography.scss +58 -58
  133. package/src/scss/utilities.scss +243 -243
  134. package/src/scss/voice-note.scss +5 -0
@@ -0,0 +1,69 @@
1
+ # Table
2
+
3
+ **Source:** `src/scss/table.scss` · No JS required.
4
+
5
+ Apple-style comparison tables with clean borders, alternating row shading, and equal-width columns defined by a modifier class. Designed for feature comparison and spec sheets — not for large data sets.
6
+
7
+ ## Usage
8
+
9
+ ```html
10
+ <table class="pp-table pp-table--cols-3">
11
+ <thead>
12
+ <tr>
13
+ <th scope="col">Feature</th>
14
+ <th scope="col">Standard</th>
15
+ <th scope="col">Pro</th>
16
+ </tr>
17
+ </thead>
18
+ <tbody>
19
+ <tr>
20
+ <td>Storage</td>
21
+ <td>256 GB</td>
22
+ <td>512 GB</td>
23
+ </tr>
24
+ <tr>
25
+ <td>Memory</td>
26
+ <td>8 GB</td>
27
+ <td>16 GB</td>
28
+ </tr>
29
+ </tbody>
30
+ </table>
31
+ ```
32
+
33
+ ## Column helpers
34
+
35
+ The column modifier sets `grid-template-columns` (or equivalent) so all columns share equal width. **One modifier is required** — without it the table renders with browser-default column sizing.
36
+
37
+ | Class | Columns |
38
+ |---|---|
39
+ | `.pp-table--cols-1` | 1 equal column |
40
+ | `.pp-table--cols-2` | 2 equal columns |
41
+ | `.pp-table--cols-3` | 3 equal columns |
42
+ | `.pp-table--cols-4` | 4 equal columns |
43
+
44
+ ## Row label pattern
45
+
46
+ The first column is conventionally used as a row label (the "feature" column in a comparison table). No special class is needed — the alternating row shading and border styling applies uniformly.
47
+
48
+ ```html
49
+ <tr>
50
+ <td>Chip</td> <!-- row label -->
51
+ <td>Apple M4</td>
52
+ <td>Apple M4 Pro</td>
53
+ </tr>
54
+ ```
55
+
56
+ ## ARIA & accessibility
57
+
58
+ - Use `<th>` for all header cells, never `<td>` — this is required for screen readers to announce column/row context.
59
+ - Add `scope="col"` to column headers and `scope="row"` to row headers.
60
+ - For tables with both row and column headers, use `scope="rowgroup"` / `scope="colgroup"` as appropriate.
61
+ - Provide a `<caption>` if the table's purpose is not clear from surrounding text — this is the table's accessible name.
62
+ - Do not use tables for layout — only for genuinely tabular data.
63
+ - On mobile, consider whether the table needs horizontal scrolling. Wrap in a `<div style="overflow-x:auto;">` if it may overflow narrow viewports.
64
+
65
+ ## Common mistakes
66
+
67
+ - Omitting the column modifier class produces unstyled column widths — always add `.pp-table--cols-N`.
68
+ - Using `<td>` for header cells breaks screen reader announcements of column/row context.
69
+ - Do not put interactive elements (buttons, selects) inside cells unless the table is genuinely an interactive data grid — in that case, full `role="grid"` semantics are required.
@@ -0,0 +1,115 @@
1
+ # Tabs
2
+
3
+ **Source:** `src/scss/tabs.scss` · `src/js/tabs.js`
4
+
5
+ Pill-style tab bar. Each tab can optionally control a panel via `data-tab-target` / `data-tab-panel`. JS wires ARIA and handles keyboard navigation — CSS provides the full visual baseline without JS.
6
+
7
+ ## With panels
8
+
9
+ ```html
10
+ <div class="pp-tabs" role="tablist" aria-label="Account settings">
11
+ <button class="pp-tabs__item is-active" role="tab"
12
+ aria-selected="true" tabindex="0"
13
+ data-tab-target="general">
14
+ <i data-lucide="settings" aria-hidden="true"></i>
15
+ General
16
+ </button>
17
+ <button class="pp-tabs__item" role="tab"
18
+ aria-selected="false" tabindex="-1"
19
+ data-tab-target="privacy">
20
+ <i data-lucide="shield" aria-hidden="true"></i>
21
+ Privacy
22
+ </button>
23
+ <button class="pp-tabs__item" role="tab"
24
+ aria-selected="false" tabindex="-1"
25
+ data-tab-target="notifications">
26
+ <i data-lucide="bell" aria-hidden="true"></i>
27
+ Notifications
28
+ </button>
29
+ </div>
30
+
31
+ <div data-tab-panel="general" role="tabpanel">
32
+ <p>General settings content.</p>
33
+ </div>
34
+ <div data-tab-panel="privacy" role="tabpanel" hidden aria-hidden="true">
35
+ <p>Privacy settings content.</p>
36
+ </div>
37
+ <div data-tab-panel="notifications" role="tabpanel" hidden aria-hidden="true">
38
+ <p>Notification settings content.</p>
39
+ </div>
40
+
41
+ <script src="dist/tabs.js" defer></script>
42
+ ```
43
+
44
+ JS automatically sets `aria-controls` on tabs and `aria-labelledby` on panels from the `data-tab-target` / `data-tab-panel` values.
45
+
46
+ ## Without panels (display-only tabs)
47
+
48
+ ```html
49
+ <div class="pp-tabs" role="tablist" aria-label="View mode">
50
+ <button class="pp-tabs__item is-active" role="tab" aria-selected="true" tabindex="0">Grid</button>
51
+ <button class="pp-tabs__item" role="tab" aria-selected="false" tabindex="-1">List</button>
52
+ </div>
53
+ ```
54
+
55
+ Omit `data-tab-target` and panels entirely — JS still wires ARIA states.
56
+
57
+ ## Variants
58
+
59
+ | Class on `.pp-tabs` | Active tab style |
60
+ |---|---|
61
+ | (none) | Filled primary red pill |
62
+ | `.pp-tabs--outline` | Outline pill, primary border |
63
+ | `.pp-tabs--gradient` | Gradient fill (gold→red) |
64
+ | `.pp-tabs--gradient-outline` | Gradient outline |
65
+
66
+ ## Sizes
67
+
68
+ | Class on `.pp-tabs` | Description |
69
+ |---|---|
70
+ | `.pp-tabs--sm` | Compact padding, sm font |
71
+ | (none) | Default |
72
+ | `.pp-tabs--lg` | Larger padding, lg font |
73
+
74
+ ## Active state
75
+
76
+ The active tab has both `.is-active` class and `aria-selected="true"`. CSS uses both selectors — remove either and the visual state breaks.
77
+
78
+ Inactive tabs have `tabindex="-1"`. The active tab has `tabindex="0"`. This implements the **roving tabindex** pattern — only one tab is in the tab order at a time; arrow keys move between tabs.
79
+
80
+ ## ARIA requirements
81
+
82
+ | Element | Required |
83
+ |---|---|
84
+ | `.pp-tabs` | `role="tablist"` + `aria-label` describing the tab group |
85
+ | `.pp-tabs__item` | `role="tab"` + `aria-selected="true/false"` + `tabindex="0/-1"` |
86
+ | Active tab | `aria-selected="true"` + `tabindex="0"` |
87
+ | Inactive tabs | `aria-selected="false"` + `tabindex="-1"` |
88
+ | Panel | `role="tabpanel"` + `aria-labelledby` (tab id) + `hidden` when inactive |
89
+
90
+ ## Keyboard navigation
91
+
92
+ | Key | Action |
93
+ |---|---|
94
+ | `←` | Activate and focus previous tab |
95
+ | `→` | Activate and focus next tab |
96
+ | `Home` | Activate and focus first tab |
97
+ | `End` | Activate and focus last tab |
98
+ | `Tab` | Move focus out of the tablist to the active panel |
99
+
100
+ ## Custom events
101
+
102
+ ```js
103
+ document.querySelector('.pp-tabs').addEventListener('pp-tabs:change', (e) => {
104
+ console.log(e.detail.value); // data-tab-target value
105
+ console.log(e.detail.label); // visible tab text
106
+ });
107
+ ```
108
+
109
+ ## Common mistakes
110
+
111
+ - Omitting `aria-label` on the tablist — AT cannot identify what the tabs control without it.
112
+ - Setting all tabs to `tabindex="0"` — only the active tab should be in the tab order; arrow keys handle the rest.
113
+ - Forgetting `hidden` on inactive panels — they remain visible without it.
114
+ - Using `display:none` on panels instead of `hidden` — both work visually, but `hidden` is semantically cleaner and matches what JS sets.
115
+ - Placing tabs inside a `<ul>` — tabs use `<div role="tablist">` with `<button role="tab">` children; the list element is not needed and adds implicit list semantics.
@@ -0,0 +1,96 @@
1
+ # Toast
2
+
3
+ **Source:** `src/scss/toast.scss` · `src/js/toast.js`
4
+
5
+ Auto-dismissing notification toasts. `ppToast.show()` creates a container on demand, injects the toast with an SVG icon and optional progress bar, and removes it after the configured duration. No HTML scaffolding needed in advance.
6
+
7
+ ## JS API
8
+
9
+ ```js
10
+ // Minimal
11
+ ppToast.show({ message: 'File saved.' });
12
+
13
+ // Full options
14
+ ppToast.show({
15
+ message: 'Payment failed. Check card details.', // required
16
+ title: 'Error', // optional heading
17
+ variant: 'error', // 'neutral'|'info'|'success'|'warning'|'error'
18
+ duration: 6000, // ms; 0 = persistent (no auto-dismiss)
19
+ position: 'top-right', // see positions table below
20
+ });
21
+ ```
22
+
23
+ ## Positions
24
+
25
+ | Value | Screen location |
26
+ |---|---|
27
+ | `top-right` (default) | Top-right corner |
28
+ | `top-left` | Top-left corner |
29
+ | `top-center` | Top-center, horizontally centered |
30
+ | `bottom-right` | Bottom-right corner |
31
+ | `bottom-left` | Bottom-left corner |
32
+ | `bottom-center` | Bottom-center, horizontally centered |
33
+
34
+ Each position maps to a `.pp-toast-container--{position}` container created on demand. Multiple containers can coexist for different positions.
35
+
36
+ ## Color variants
37
+
38
+ | Variant | Background | Border | Icon |
39
+ |---|---|---|---|
40
+ | `neutral` (default) | `neutral-800` | `neutral-700` | info circle |
41
+ | `info` | info / 12% | info / 30% | info circle |
42
+ | `success` | success / 12% | success / 30% | circle-check |
43
+ | `warning` | warning / 12% | warning / 35% | triangle-alert |
44
+ | `error` | error / 12% | error / 30% | circle-x |
45
+
46
+ ## Manual dismiss button
47
+
48
+ Add `data-toast-dismiss` to any button inside a toast for auto-wired dismiss (event delegation, no extra JS):
49
+
50
+ ```html
51
+ <!-- You don't need to write this manually — ppToast.show() injects it automatically.
52
+ Use data-toast-dismiss if building a static toast in HTML. -->
53
+ <div class="pp-toast pp-toast--info" role="status">
54
+ <div class="pp-toast__body">
55
+ <p class="pp-toast__message">Update available.</p>
56
+ </div>
57
+ <button class="pp-toast__dismiss" data-toast-dismiss aria-label="Dismiss">✕</button>
58
+ </div>
59
+ ```
60
+
61
+ ## Events
62
+
63
+ Both events bubble and are dispatched on the individual `.pp-toast` element:
64
+
65
+ | Event | When |
66
+ |---|---|
67
+ | `pp:toast:show` | Immediately after the toast is injected into the DOM |
68
+ | `pp:toast:dismiss` | Immediately before the toast is removed (after `.is-dismissing` is added) |
69
+
70
+ ```js
71
+ document.addEventListener('pp:toast:show', (e) => {
72
+ console.log('Toast shown:', e.target);
73
+ });
74
+ ```
75
+
76
+ ## Progress bar
77
+
78
+ When `duration > 0` (not persistent), a `.pp-toast__progress` bar animates from full width to zero over the duration. The animation pauses if the user hovers the toast container (via CSS `animation-play-state`).
79
+
80
+ ## Persistent toasts
81
+
82
+ Pass `duration: 0` to prevent auto-dismiss. The toast stays until the user clicks the dismiss button.
83
+
84
+ ```js
85
+ ppToast.show({ message: 'Action required.', variant: 'warning', duration: 0 });
86
+ ```
87
+
88
+ ## Dark mode
89
+
90
+ Background and border colors adapt under `.dark` via CSS custom property tokens. No extra classes needed.
91
+
92
+ ## Common mistakes
93
+
94
+ - Calling `ppToast.show()` before `DOMContentLoaded` — `toast.js` initialises on `DOMContentLoaded`; showing a toast before init will fail silently. Use `defer` on the script tag.
95
+ - Expecting `ppToast` to be available in module scope without a script tag — `toast.js` sets `window.ppToast`; it must be loaded globally.
96
+ - Using `duration: 0` without a dismiss button — the toast will never disappear; ensure the injected markup includes a `data-toast-dismiss` element (it always does when using `ppToast.show()`).
@@ -0,0 +1,111 @@
1
+ # Tooltip
2
+
3
+ **Source:** `src/scss/tooltip.scss`
4
+
5
+ CSS-only tooltip. Shows on `:hover` and `:focus-within` — no JavaScript required. Four placement variants. Content is visually hidden until triggered; `role="tooltip"` ensures screen readers announce it when the trigger receives focus.
6
+
7
+ ## Full structure
8
+
9
+ ```html
10
+ <span class="pp-tooltip">
11
+ <!-- The trigger — any inline or block element -->
12
+ <button type="button">Hover me</button>
13
+
14
+ <!-- The tooltip content -->
15
+ <span class="pp-tooltip__content" role="tooltip">
16
+ Helpful hint text
17
+ </span>
18
+ </span>
19
+ ```
20
+
21
+ ## Placement variants
22
+
23
+ Default placement is top-center. Override with a modifier on `.pp-tooltip__content`:
24
+
25
+ | Class | Placement |
26
+ |---|---|
27
+ | (none) | Top — centered above trigger |
28
+ | `.pp-tooltip__content--bottom` | Bottom — centered below trigger |
29
+ | `.pp-tooltip__content--left` | Left — vertically centered, left of trigger |
30
+ | `.pp-tooltip__content--right` | Right — vertically centered, right of trigger |
31
+
32
+ ```html
33
+ <!-- Bottom -->
34
+ <span class="pp-tooltip">
35
+ <button type="button">Trigger</button>
36
+ <span class="pp-tooltip__content pp-tooltip__content--bottom" role="tooltip">Below</span>
37
+ </span>
38
+
39
+ <!-- Left -->
40
+ <span class="pp-tooltip">
41
+ <button type="button">Trigger</button>
42
+ <span class="pp-tooltip__content pp-tooltip__content--left" role="tooltip">Left side</span>
43
+ </span>
44
+ ```
45
+
46
+ ## Force-show
47
+
48
+ Add `data-show` to `.pp-tooltip__content` to keep the tooltip visible at all times — useful during development and testing:
49
+
50
+ ```html
51
+ <span class="pp-tooltip">
52
+ <button type="button">Trigger</button>
53
+ <span class="pp-tooltip__content pp-tooltip__content--bottom" role="tooltip" data-show>
54
+ Always visible
55
+ </span>
56
+ </span>
57
+ ```
58
+
59
+ ## On icon buttons
60
+
61
+ Wrap the button with `.pp-tooltip` and place the content after the button:
62
+
63
+ ```html
64
+ <span class="pp-tooltip">
65
+ <button class="pp-button--ghost" style="padding:0.5rem;" type="button" aria-label="Delete">
66
+ <i data-lucide="trash-2" aria-hidden="true"></i>
67
+ </button>
68
+ <span class="pp-tooltip__content pp-tooltip__content--bottom" role="tooltip">Delete</span>
69
+ </span>
70
+ ```
71
+
72
+ Do not use `title=""` as a tooltip substitute — it is not keyboard accessible and is not announced consistently across screen readers.
73
+
74
+ ## ARIA
75
+
76
+ | Attribute | Required | Value |
77
+ |---|---|---|
78
+ | `role="tooltip"` | Yes | On `.pp-tooltip__content` |
79
+ | `aria-describedby` | Recommended | Associate trigger with tooltip `id` for programmatic access |
80
+
81
+ Full accessible pattern with `aria-describedby`:
82
+
83
+ ```html
84
+ <span class="pp-tooltip">
85
+ <button type="button" aria-describedby="tip-del">Delete</button>
86
+ <span class="pp-tooltip__content pp-tooltip__content--bottom" role="tooltip" id="tip-del">
87
+ Permanently removes the item
88
+ </span>
89
+ </span>
90
+ ```
91
+
92
+ ## Styling the content
93
+
94
+ The tooltip content box uses `--pp-neutral-900` background and white text by default. Override inline for one-offs:
95
+
96
+ ```html
97
+ <span class="pp-tooltip__content" role="tooltip" style="background: var(--pp-error);">
98
+ Dangerous action
99
+ </span>
100
+ ```
101
+
102
+ ## Dark mode
103
+
104
+ Tooltip background (`--pp-neutral-900`) becomes near-black under `.dark` via the inverted neutral scale. No extra classes needed.
105
+
106
+ ## Common mistakes
107
+
108
+ - Missing `role="tooltip"` — the content is not announced as a tooltip by screen readers on focus.
109
+ - Triggering on a non-focusable element (e.g., a `<span>` with no `tabindex`) — keyboard users cannot reach the tooltip. Use a `<button>` or add `tabindex="0"`.
110
+ - Placing interactive content inside `.pp-tooltip__content` — tooltip content is not keyboard-accessible once shown; buttons or links inside a tooltip are unreachable.
111
+ - Relying on hover only for critical information — tooltip content is purely supplemental. Never gate required information behind a hover state.
@@ -0,0 +1,118 @@
1
+ # Typography
2
+
3
+ **Source:** `src/scss/typography.scss` · No JS required.
4
+
5
+ Utility classes for font family, size, weight, line height, tracking, alignment, transform, decoration, and overflow. Classes compose freely — stack as many as needed on one element.
6
+
7
+ Base element styles (h1–h6, body, code, pre) are set in `base.scss` not here.
8
+
9
+ ## Font family
10
+
11
+ ```html
12
+ <p class="font-sans">Inter, system-ui, -apple-system…</p>
13
+ <p class="font-mono">Kode Mono, ui-monospace…</p>
14
+ ```
15
+
16
+ Both fonts load from Google Fonts via `base.scss`. `font-sans` is the default body font.
17
+
18
+ ## Font weight
19
+
20
+ `.font-100` through `.font-900` in steps of 100.
21
+
22
+ ```html
23
+ <p class="font-sans font-300">Light</p>
24
+ <p class="font-sans font-400">Regular</p>
25
+ <p class="font-sans font-500">Medium</p>
26
+ <p class="font-sans font-600">SemiBold</p>
27
+ <p class="font-sans font-700">Bold</p>
28
+ <p class="font-sans font-900">Black</p>
29
+ ```
30
+
31
+ Inter supports 300, 400, 500, 600, 700, 900. Weights 100, 200, 800 will be synthesised by the browser (may look different).
32
+
33
+ ## Font size
34
+
35
+ | Class | rem | px equiv |
36
+ |---|---|---|
37
+ | `.text-xs` | 0.75rem | 12px |
38
+ | `.text-sm` | 0.875rem | 14px |
39
+ | `.text-base` | 1rem | 16px |
40
+ | `.text-lg` | 1.125rem | 18px |
41
+ | `.text-xl` | 1.25rem | 20px |
42
+ | `.text-2xl` | 1.5rem | 24px |
43
+ | `.text-3xl` | 1.875rem | 30px |
44
+ | `.text-4xl` | 2.25rem | 36px |
45
+ | `.text-5xl` | 3rem | 48px |
46
+
47
+ ## Line height
48
+
49
+ | Class | Value | Best for |
50
+ |---|---|---|
51
+ | `.leading-none` | 1 | Display, icon labels |
52
+ | `.leading-tight` | 1.25 | Headings |
53
+ | `.leading-snug` | 1.375 | Sub-headings |
54
+ | `.leading-normal` | 1.5 | UI text |
55
+ | `.leading-relaxed` | 1.625 | Body copy |
56
+ | `.leading-loose` | 2 | Spaced lists |
57
+
58
+ ## Letter spacing
59
+
60
+ | Class | Value | Best for |
61
+ |---|---|---|
62
+ | `.tracking-tighter` | -0.05em | Large display headings |
63
+ | `.tracking-tight` | -0.025em | Headings, Apple-style |
64
+ | `.tracking-normal` | 0 | Body text |
65
+ | `.tracking-wide` | 0.025em | — |
66
+ | `.tracking-wider` | 0.05em | Small caps |
67
+ | `.tracking-widest` | 0.1em | Uppercase labels, eyebrows |
68
+
69
+ ## Text alignment
70
+
71
+ `.text-left` · `.text-center` · `.text-right`
72
+
73
+ ## Text transform
74
+
75
+ `.uppercase` · `.lowercase` · `.capitalize`
76
+
77
+ ## Text decoration
78
+
79
+ `.underline` · `.no-underline` · `.line-through`
80
+
81
+ ## Overflow
82
+
83
+ | Class | Behaviour |
84
+ |---|---|
85
+ | `.truncate` | `overflow: hidden; text-overflow: ellipsis; white-space: nowrap` — clips to one line |
86
+ | `.wrap-balance` | `text-wrap: balance` — balances line lengths in headings |
87
+
88
+ ## Composing classes
89
+
90
+ ```html
91
+ <!-- Apple-style section heading -->
92
+ <h2 class="font-sans font-700 tracking-tight text-4xl">
93
+ A powerful new approach.
94
+ </h2>
95
+
96
+ <!-- Uppercase label / eyebrow -->
97
+ <p class="font-sans font-600 text-xs uppercase tracking-widest" style="color:#71717a;">
98
+ New feature
99
+ </p>
100
+
101
+ <!-- Body copy -->
102
+ <p class="font-sans font-400 text-base leading-relaxed">
103
+ Supporting text that explains the heading above.
104
+ </p>
105
+ ```
106
+
107
+ ## ARIA & accessibility
108
+
109
+ - Never use typographic styling alone to convey meaning — an element that looks like a heading must use `<h1>`–`<h6>`, not a `<p class="text-4xl font-700">`.
110
+ - `.truncate` hides content visually — if the full text is meaningful, provide it via `title` attribute or `aria-label` so AT users can access it.
111
+ - `.wrap-balance` is a progressive enhancement — it has no effect in browsers that don't support `text-wrap: balance`; do not rely on it for layout.
112
+ - Avoid setting font sizes below `text-xs` (0.75rem / 12px) — text smaller than 12px fails WCAG 1.4.4 and is difficult to read.
113
+
114
+ ## Common mistakes
115
+
116
+ - Using `<p class="font-700 text-4xl">` for headings instead of `<h2>` — semantic heading elements are required for document structure and AT navigation.
117
+ - Combining `.text-*` classes with inline `font-size` — the inline style wins; use one or the other.
118
+ - Using `.uppercase` on user-generated content or names — transforms applied in CSS are not reflected in clipboard copy; spell out uppercase text in HTML if exact casing matters.