@auriel/peppertino 0.5.0 → 0.6.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.
Files changed (130) hide show
  1. package/CHANGELOG.txt +242 -224
  2. package/LICENSE +21 -21
  3. package/MIGRATION.md +52 -52
  4. package/README.md +773 -764
  5. package/agents/peppertino/SKILL.md +76 -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 +81 -0
  14. package/agents/peppertino/dark-mode.md +152 -0
  15. package/agents/peppertino/footer.md +109 -0
  16. package/agents/peppertino/forms-fieldset.md +85 -0
  17. package/agents/peppertino/forms-form-instructions.md +94 -0
  18. package/agents/peppertino/forms-label.md +110 -0
  19. package/agents/peppertino/forms-text-field.md +134 -0
  20. package/agents/peppertino/forms-validation.md +153 -0
  21. package/agents/peppertino/gradient.md +41 -0
  22. package/agents/peppertino/header.md +105 -0
  23. package/agents/peppertino/modal.md +123 -0
  24. package/agents/peppertino/section.md +56 -0
  25. package/agents/peppertino/select.md +110 -0
  26. package/agents/peppertino/switch.md +72 -0
  27. package/agents/peppertino/table.md +69 -0
  28. package/agents/peppertino/tabs.md +115 -0
  29. package/agents/peppertino/toast.md +96 -0
  30. package/agents/peppertino/tooltip.md +111 -0
  31. package/agents/peppertino/typography.md +118 -0
  32. package/agents/peppertino/utilities.md +194 -0
  33. package/agents/skill.md +65 -0
  34. package/build.js +53 -53
  35. package/dist/accordion.js +1 -1
  36. package/dist/accordion.js.map +2 -2
  37. package/dist/alert.js.map +1 -1
  38. package/dist/carousel.js.map +1 -1
  39. package/dist/header.js.map +1 -1
  40. package/dist/main.css +2566 -1008
  41. package/dist/main.css.map +1 -1
  42. package/dist/main.min.css +1 -0
  43. package/dist/modal.js.map +1 -1
  44. package/dist/peppertino.js +1 -1
  45. package/dist/peppertino.js.map +2 -2
  46. package/dist/select.js.map +1 -1
  47. package/dist/switch.js.map +1 -1
  48. package/dist/tabs.js.map +1 -1
  49. package/dist/theme.js.map +1 -1
  50. package/dist/toast.js.map +1 -1
  51. package/dist/validation.js.map +1 -1
  52. package/icon.svg +4 -0
  53. package/index.html +2172 -2098
  54. package/package.json +28 -28
  55. package/scripts/hex-to-hsl.mjs +75 -75
  56. package/scripts/lint-bem.mjs +53 -53
  57. package/scripts/lint-colors.mjs +87 -87
  58. package/site.webmanifest +18 -0
  59. package/src/js/accordion.js +105 -103
  60. package/src/js/alert.js +28 -28
  61. package/src/js/carousel.js +153 -153
  62. package/src/js/header.js +85 -85
  63. package/src/js/modal.js +138 -138
  64. package/src/js/peppertino.js +15 -15
  65. package/src/js/select.js +101 -101
  66. package/src/js/switch.js +28 -28
  67. package/src/js/tabs.js +104 -104
  68. package/src/js/theme.js +47 -47
  69. package/src/js/toast.js +79 -79
  70. package/src/js/validation.js +132 -132
  71. package/src/scss/accordion.scss +190 -156
  72. package/src/scss/activity.scss +17 -0
  73. package/src/scss/alert.scss +203 -203
  74. package/src/scss/badge.scss +90 -90
  75. package/src/scss/base.scss +511 -506
  76. package/src/scss/button.scss +119 -119
  77. package/src/scss/card.scss +121 -121
  78. package/src/scss/carousel.scss +303 -303
  79. package/src/scss/code-block.scss +22 -0
  80. package/src/scss/counter.scss +5 -0
  81. package/src/scss/dark-mode.scss +514 -514
  82. package/src/scss/duration.scss +26 -0
  83. package/src/scss/folder.scss +27 -0
  84. package/src/scss/footer.scss +224 -224
  85. package/src/scss/forms/fieldset.scss +127 -127
  86. package/src/scss/forms/form-instructions.scss +133 -133
  87. package/src/scss/forms/label.scss +115 -115
  88. package/src/scss/forms/text-field.scss +240 -240
  89. package/src/scss/forms/validation.scss +215 -215
  90. package/src/scss/forms.scss +8 -8
  91. package/src/scss/gradient.scss +11 -11
  92. package/src/scss/gravity-letters.scss +7 -0
  93. package/src/scss/header.scss +257 -238
  94. package/src/scss/helpers/color.scss +9 -0
  95. package/src/scss/helpers/flex.scss +14 -0
  96. package/src/scss/helpers/index.scss +6 -0
  97. package/src/scss/helpers/layout.scss +14 -0
  98. package/src/scss/helpers/spacing.scss +14 -0
  99. package/src/scss/helpers/typography.scss +11 -0
  100. package/src/scss/helpers/visibility.scss +9 -0
  101. package/src/scss/main.scss +49 -24
  102. package/src/scss/modal.scss +188 -188
  103. package/src/scss/model-picker.scss +5 -0
  104. package/src/scss/notification.scss +5 -0
  105. package/src/scss/orb.scss +7 -0
  106. package/src/scss/otp.scss +5 -0
  107. package/src/scss/pill-nav.scss +10 -0
  108. package/src/scss/prompt.scss +28 -0
  109. package/src/scss/rail.scss +7 -0
  110. package/src/scss/reactions.scss +5 -0
  111. package/src/scss/reset.scss +84 -84
  112. package/src/scss/response.scss +11 -0
  113. package/src/scss/reveal.scss +5 -0
  114. package/src/scss/scroll-progress.scss +4 -0
  115. package/src/scss/search-results.scss +13 -0
  116. package/src/scss/section.scss +87 -79
  117. package/src/scss/select.scss +210 -210
  118. package/src/scss/sidebar.scss +8 -0
  119. package/src/scss/status.scss +5 -0
  120. package/src/scss/step-list.scss +13 -0
  121. package/src/scss/switch.scss +121 -121
  122. package/src/scss/table.scss +89 -89
  123. package/src/scss/tabs.scss +156 -156
  124. package/src/scss/task-list.scss +18 -0
  125. package/src/scss/theme-picker.scss +5 -0
  126. package/src/scss/toast.scss +170 -170
  127. package/src/scss/tooltip.scss +126 -126
  128. package/src/scss/typography.scss +58 -58
  129. package/src/scss/utilities.scss +243 -243
  130. package/src/scss/voice-note.scss +5 -0
@@ -0,0 +1,105 @@
1
+ # Header
2
+
3
+ For long desktop dropdowns, add `.pp-header__dropdown--columns` to the dropdown list. It uses two columns at widths of at least 768 CSS pixels and keeps items in reading and keyboard order. On smaller screens it remains a single-column mobile drawer. The menu scrolls when its content exceeds the available height.
4
+
5
+ **Source:** `src/scss/header.scss` · `src/js/header.js`
6
+
7
+ Sticky glassmorphism navigation bar, 56px tall, `z-index: 100` (overlay). The brand sits on the left; nav links on the right; a hamburger toggle appears below 768px. JS handles mobile drawer open/close, dropdown keyboard navigation, and ARIA state toggling.
8
+
9
+ ## Full structure
10
+
11
+ ```html
12
+ <header class="pp-header">
13
+
14
+ <a href="#hero" class="pp-header__brand">BrandName</a>
15
+
16
+ <nav aria-label="Main navigation">
17
+ <ul class="pp-header__nav" role="menubar">
18
+
19
+ <!-- Simple nav link -->
20
+ <li class="pp-header__nav-item" role="none">
21
+ <a href="#about" class="pp-header__nav-link" role="menuitem"
22
+ aria-current="page">About</a>
23
+ </li>
24
+
25
+ <!-- Nav link with dropdown -->
26
+ <li class="pp-header__nav-item" role="none">
27
+ <a href="#products" class="pp-header__nav-link" role="menuitem"
28
+ aria-haspopup="true" aria-expanded="false" id="products-trigger">Products</a>
29
+ <ul class="pp-header__dropdown" role="menu"
30
+ aria-label="Products" aria-labelledby="products-trigger">
31
+ <li role="none">
32
+ <a href="#features" class="pp-header__dropdown-link" role="menuitem">Features</a>
33
+ </li>
34
+ <li role="none">
35
+ <a href="#pricing" class="pp-header__dropdown-link" role="menuitem">Pricing</a>
36
+ </li>
37
+ </ul>
38
+ </li>
39
+
40
+ </ul>
41
+ </nav>
42
+
43
+ <!-- Mobile hamburger — hidden above 768px -->
44
+ <button class="pp-header__toggle" type="button"
45
+ aria-expanded="false" aria-label="Toggle navigation"
46
+ aria-controls="main-nav">
47
+ <span></span>
48
+ <span></span>
49
+ <span></span>
50
+ </button>
51
+
52
+ </header>
53
+ <script src="dist/header.js" defer></script>
54
+ ```
55
+
56
+ ## Parts
57
+
58
+ | Class | Element | Description |
59
+ |---|---|---|
60
+ | `.pp-header` | `<header>` | Sticky bar, `height: 56px`, glassmorphism blur |
61
+ | `.pp-header__brand` | `<a>` | Logo/brand link — semibold, hover → primary |
62
+ | `.pp-header__nav` | `<ul>` | Horizontal nav list — `role="menubar"` |
63
+ | `.pp-header__nav-item` | `<li>` | Nav item wrapper — `role="none"` |
64
+ | `.pp-header__nav-link` | `<a>` | Nav link — `role="menuitem"`, active via `aria-current="page"` or `.is-active` |
65
+ | `.pp-header__dropdown` | `<ul>` | Dropdown panel — `role="menu"`, shown on hover/focus-within |
66
+ | `.pp-header__dropdown-link` | `<a>` | Dropdown item — `role="menuitem"` |
67
+ | `.pp-header__toggle` | `<button>` | Hamburger — visible only below 768px |
68
+
69
+ ## Dropdown behaviour
70
+
71
+ - **Desktop:** dropdown appears on `:hover` and `:focus-within` via CSS — no JS required for the basic open state.
72
+ - **Mobile:** dropdown is inlined (static position, no animation) inside the drawer.
73
+ - JS adds `.is-open` to `.pp-header__nav-item` for programmatic control and updates `aria-expanded` on the trigger.
74
+ - The three `<span>` children of `.pp-header__toggle` animate into a × when `aria-expanded="true"` is set.
75
+
76
+ ## Active link
77
+
78
+ ```html
79
+ <a href="#current-page" class="pp-header__nav-link" role="menuitem" aria-current="page">
80
+ Current Page
81
+ </a>
82
+ ```
83
+
84
+ CSS styles `[aria-current="page"]` and `.is-active` identically — use `aria-current` for semantic correctness.
85
+
86
+ ## ARIA requirements
87
+
88
+ | Element | Required ARIA |
89
+ |---|---|
90
+ | `<nav>` | `aria-label="Main navigation"` (or your label) |
91
+ | `<ul class="pp-header__nav">` | `role="menubar"` |
92
+ | `<li class="pp-header__nav-item">` | `role="none"` |
93
+ | `<a class="pp-header__nav-link">` | `role="menuitem"` |
94
+ | Dropdown trigger `<a>` | `aria-haspopup="true"` + `aria-expanded="false/true"` |
95
+ | `<ul class="pp-header__dropdown">` | `role="menu"` + `aria-label` |
96
+ | `<li>` inside dropdown | `role="none"` |
97
+ | `<a class="pp-header__dropdown-link">` | `role="menuitem"` |
98
+ | `.pp-header__toggle` | `aria-expanded`, `aria-label`, `aria-controls` pointing to nav id |
99
+
100
+ ## Common mistakes
101
+
102
+ - Omitting `role="none"` on `<li>` wrappers — the default `listitem` role conflicts with `menuitem` children under a `menubar`/`menu`.
103
+ - Using `aria-haspopup="menu"` instead of `aria-haspopup="true"` — both are valid but `"true"` is more broadly supported.
104
+ - Adding `role="navigation"` to `<nav>` — redundant; `<nav>` already carries that role implicitly.
105
+ - Forgetting `aria-controls` on the mobile toggle — screen readers need to know which element the button controls.
@@ -0,0 +1,123 @@
1
+ # Modal
2
+
3
+ **Source:** `src/scss/modal.scss` · `src/js/modal.js`
4
+
5
+ Glassmorphic action sheet pattern. The backdrop blurs the page behind the modal. The modal container uses frosted glass (rgba white + backdrop-filter). A gradient accent strip appears at the top of the modal. JS provides focus trap, Escape-to-close, and focus restoration.
6
+
7
+ ## Full structure
8
+
9
+ ```html
10
+ <!-- Trigger -->
11
+ <button class="button" data-modal-open="confirm-modal">Delete item</button>
12
+
13
+ <!-- Modal — placed anywhere in <body>, outside normal flow -->
14
+ <div id="confirm-modal"
15
+ class="pp-modal-backdrop"
16
+ role="dialog"
17
+ aria-modal="true"
18
+ aria-labelledby="confirm-modal-title"
19
+ aria-describedby="confirm-modal-desc"
20
+ aria-hidden="true">
21
+
22
+ <div class="pp-modal">
23
+ <button class="pp-modal__close"
24
+ data-modal-close="confirm-modal"
25
+ aria-label="Close dialog">✕</button>
26
+
27
+ <p class="pp-modal__title" id="confirm-modal-title">Delete item</p>
28
+ <p class="pp-modal__description" id="confirm-modal-desc">
29
+ This action cannot be undone. The item will be permanently removed.
30
+ </p>
31
+
32
+ <ul class="pp-modal__actions">
33
+ <li>
34
+ <button class="pp-modal__action pp-modal__action--destructive">
35
+ Delete permanently
36
+ </button>
37
+ </li>
38
+ <li>
39
+ <button class="pp-modal__action pp-modal__action--cancel"
40
+ data-modal-close="confirm-modal">
41
+ Cancel
42
+ </button>
43
+ </li>
44
+ </ul>
45
+ </div>
46
+
47
+ </div>
48
+ <script src="dist/modal.js" defer></script>
49
+ ```
50
+
51
+ ## Native `<dialog>` variant
52
+
53
+ ```html
54
+ <dialog id="my-dialog" class="pp-modal-backdrop">
55
+ <div class="pp-modal">...</div>
56
+ </dialog>
57
+ ```
58
+
59
+ Use `ppModal.open('my-dialog')` — the shim calls `dialog.showModal()` automatically. Native `<dialog>` gets browser-managed focus trap and Escape handling in addition to the JS shim.
60
+
61
+ ## Parts
62
+
63
+ | Class | Element | Description |
64
+ |---|---|---|
65
+ | `.pp-modal-backdrop` | `<div>` or `<dialog>` | Fixed overlay, `backdrop-filter: blur(8px) saturate(120%)` |
66
+ | `.pp-modal` | `<div>` | Container, `max-width: 420px`, frosted glass, `border-radius: 20px` |
67
+ | `.pp-modal__title` | `<p>` | Bold lg, white — must have `id` matching `aria-labelledby` |
68
+ | `.pp-modal__description` | `<p>` | sm, white 70% — must have `id` matching `aria-describedby` |
69
+ | `.pp-modal__actions` | `<ul>` | Pill button list, flex-column |
70
+ | `.pp-modal__action` | `<button>` | Full-width pill, white glass style |
71
+ | `.pp-modal__action--destructive` | modifier | Red tint, for irreversible actions |
72
+ | `.pp-modal__action--cancel` | modifier | Muted, for dismiss/cancel |
73
+ | `.pp-modal__close` | `<button>` | 28px circle in top-right corner |
74
+
75
+ ## Open states
76
+
77
+ The backdrop is hidden by default. It becomes visible when **any one** of these is true:
78
+
79
+ | State | How to set |
80
+ |---|---|
81
+ | `[open]` attribute | Native `<dialog>` via `showModal()` |
82
+ | `.is-open` class | Added by JS or manually |
83
+ | `aria-hidden="false"` | Set by JS or manually |
84
+
85
+ ## JS API
86
+
87
+ ```js
88
+ // Programmatic control
89
+ ppModal.open('confirm-modal')
90
+ ppModal.close('confirm-modal')
91
+ ppModal.closeAll()
92
+
93
+ // Data attribute triggers (no JS calls needed in markup)
94
+ <button data-modal-open="confirm-modal">Open</button>
95
+ <button data-modal-close="confirm-modal">Close</button>
96
+ ```
97
+
98
+ JS automatically:
99
+ - Sets `aria-hidden="false"` on open, `"true"` on close
100
+ - Traps focus (Tab/Shift+Tab stays inside modal)
101
+ - Closes on Escape key
102
+ - Closes on backdrop click (outside `.pp-modal`)
103
+ - Restores focus to the element that opened the modal
104
+
105
+ ## ARIA requirements
106
+
107
+ | Attribute | Where | Value |
108
+ |---|---|---|
109
+ | `role="dialog"` | `.pp-modal-backdrop` | Required (implicit on `<dialog>`) |
110
+ | `aria-modal="true"` | `.pp-modal-backdrop` | Tells AT to ignore content behind the modal |
111
+ | `aria-labelledby` | `.pp-modal-backdrop` | ID of `.pp-modal__title` |
112
+ | `aria-describedby` | `.pp-modal-backdrop` | ID of `.pp-modal__description` |
113
+ | `aria-hidden` | `.pp-modal-backdrop` | `"true"` when closed, `"false"` when open |
114
+ | `aria-label="Close dialog"` | `.pp-modal__close` | Button has no text content |
115
+ | `id` | `.pp-modal__title` + `.pp-modal__description` | Must match `aria-labelledby`/`aria-describedby` |
116
+
117
+ ## Common mistakes
118
+
119
+ - Omitting `aria-modal="true"` — without it, screen readers may read the page content behind the modal.
120
+ - Not setting `aria-hidden="true"` on the closed modal — AT will still find and read hidden modal content.
121
+ - Forgetting unique `id` values for title and description — if multiple modals are on the page, each title/description pair needs unique ids.
122
+ - Placing modals inside other interactive containers (forms, sections with `overflow: hidden`) — modals must be direct children of `<body>` or sit at the top of the stacking context.
123
+ - Using `display: none` to hide a modal that should use `aria-hidden` — the JS shim manages visibility via class and attribute, not inline style.
@@ -0,0 +1,56 @@
1
+ # Section
2
+
3
+ **Source:** `src/scss/section.scss` · No JS required.
4
+
5
+ Sections are full-viewport content blocks. Each section occupies `100dvh` minimum, centers its content, and has `scroll-margin-top: 56px` to account for the sticky 56px header when navigating via anchor links.
6
+
7
+ ## Usage
8
+
9
+ ```html
10
+ <section id="hero" class="pp-section pp-section--gradient">
11
+ <div class="pp-section__inner">
12
+ <h1 class="font-sans font-700 tracking-tight">Heading</h1>
13
+ <p class="font-sans font-400 text-lg leading-relaxed">Supporting copy.</p>
14
+ <button class="button">Call to action</button>
15
+ </div>
16
+ </section>
17
+ ```
18
+
19
+ ## Parts
20
+
21
+ | Class | Description |
22
+ |---|---|
23
+ | `.pp-section` | Full-viewport block — `min-height: 100dvh`, flex-column, centered, `padding: 4rem 2rem` |
24
+ | `.pp-section__inner` | Content wrapper — `max-width: 960px`, flex-column, `gap: 1.5rem`, `text-align: center` |
25
+
26
+ To left-align inner content, add `style="align-items:flex-start;"` or a utility class to `.pp-section__inner`.
27
+
28
+ ## Variants
29
+
30
+ | Class | Background | Text color | Typical use |
31
+ |---|---|---|---|
32
+ | (none) | `$color-surface` (white) | `$color-on-surface` | Default content sections |
33
+ | `.pp-section--primary` | `$color-primary` (#e90111) | white | Promotional / CTA sections |
34
+ | `.pp-section--dark` | `$color-neutral-900` | `$color-neutral-50` | Feature highlights, testimonials |
35
+ | `.pp-section--muted` | `$color-neutral-100` | inherited | Alternating zebra rows |
36
+ | `.pp-section--gradient` | gold→red 135° | white | Hero sections |
37
+
38
+ ## Custom scrollbar
39
+
40
+ `section.scss` defines the global page scrollbar:
41
+ - **Track:** transparent
42
+ - **Thumb:** gold→red gradient, no border-radius
43
+ - **Width:** 16px (webkit), `auto` for Firefox with `$gradient-end` color
44
+
45
+ ## ARIA & accessibility
46
+
47
+ - Use semantic sectioning elements — `<section>`, `<main>`, `<article>`, `<aside>` — not `<div class="pp-section">`.
48
+ - Every `<section>` should have an accessible name: either a heading (`<h2>`) inside it, or `aria-labelledby` pointing to a heading, or `aria-label` if there is no visible heading.
49
+ - `id` attributes on sections enable anchor navigation — always include them for linkable sections.
50
+ - On `--primary` and `--gradient` variants, child text inherits white — ensure any inline colored text still meets 4.5:1 contrast against the section background.
51
+
52
+ ## Common mistakes
53
+
54
+ - Do not nest `.pp-section` inside `.pp-section` — sections are top-level page blocks.
55
+ - `.pp-section__inner` centers by default. For left-aligned forms or tables, override `align-items` and `text-align` inline or with utilities.
56
+ - `scroll-margin-top: 56px` only works when navigating via anchor links (`href="#id"`). If using smooth-scroll JS, ensure it accounts for the header height too.
@@ -0,0 +1,110 @@
1
+ # Select
2
+
3
+ **Source:** `src/scss/select.scss` · `src/js/select.js`
4
+
5
+ Two patterns: a CSS-restyled native `<select>` (simplest, most accessible), and a fully custom `.pp-select` dropdown (richer UI, more ARIA required). Use the native `<select>` unless you need custom option rendering.
6
+
7
+ ## Native `<select>`
8
+
9
+ Automatically styled — no class required.
10
+
11
+ ```html
12
+ <label for="framework">Framework</label>
13
+ <select id="framework" name="framework">
14
+ <option value="">Choose…</option>
15
+ <option value="peppertino">PeppertinoCSS</option>
16
+ <option value="tailwind">Tailwind</option>
17
+ </select>
18
+ ```
19
+
20
+ Always pair with a `<label>` — never rely on placeholder text alone for labelling.
21
+
22
+ ## Custom `.pp-select`
23
+
24
+ ```html
25
+ <div class="pp-select">
26
+
27
+ <button class="pp-select__trigger" type="button"
28
+ aria-label="Choose a color"
29
+ aria-haspopup="listbox"
30
+ aria-expanded="false"
31
+ aria-controls="color-panel">
32
+ <span class="pp-select__value">Choose a color</span>
33
+ <span class="pp-select__chevron" aria-hidden="true"></span>
34
+ </button>
35
+
36
+ <ul class="pp-select__panel" id="color-panel" role="listbox" aria-label="Colors">
37
+
38
+ <li role="option" aria-selected="false">
39
+ <button class="pp-select__option" data-value="red">Primary Red</button>
40
+ </li>
41
+ <li role="option" aria-selected="true">
42
+ <button class="pp-select__option is-selected" data-value="gold">Gradient Gold</button>
43
+ </li>
44
+
45
+ <!-- Divider between groups -->
46
+ <li role="separator" class="pp-select__divider"></li>
47
+
48
+ <!-- Option group -->
49
+ <li role="group" aria-label="Neutrals" style="list-style:none;">
50
+ <span class="pp-select__group-label">Neutrals</span>
51
+ <ul role="group" style="list-style:none;padding:0;margin:0;">
52
+ <li role="option" aria-selected="false">
53
+ <button class="pp-select__option" data-value="light">Light</button>
54
+ </li>
55
+ </ul>
56
+ </li>
57
+
58
+ </ul>
59
+ </div>
60
+ <script src="dist/select.js" defer></script>
61
+ ```
62
+
63
+ ## Parts
64
+
65
+ | Class | Element | Description |
66
+ |---|---|---|
67
+ | `.pp-select` | `<div>` | Wrapper — `position: relative` |
68
+ | `.pp-select__trigger` | `<button>` | Opens the panel — styled as an input |
69
+ | `.pp-select__value` | `<span>` | Displays current selection |
70
+ | `.pp-select__chevron` | `<span>` | Animated down arrow — rotates 180° when open |
71
+ | `.pp-select__panel` | `<ul>` | Dropdown list — `role="listbox"` |
72
+ | `.pp-select__option` | `<button>` | Option button inside `<li role="option">` |
73
+ | `.pp-select__divider` | `<li>` | `role="separator"` horizontal rule |
74
+ | `.pp-select__group-label` | `<span>` | Uppercase xs group heading |
75
+
76
+ ## Sizes
77
+
78
+ | Class on `.pp-select` | Padding | Font |
79
+ |---|---|---|
80
+ | `.pp-select--sm` | compact | sm |
81
+ | (none) | default | base |
82
+ | `.pp-select--lg` | large | lg |
83
+
84
+ ## Open states
85
+
86
+ The panel opens when any one of these is true:
87
+
88
+ - `.pp-select` has `.is-open`
89
+ - The trigger has `aria-expanded="true"`
90
+ - Focus is within `.pp-select` (CSS `:focus-within` fallback)
91
+
92
+ ## ARIA requirements — critical details
93
+
94
+ | Element | Role | Additional required attributes |
95
+ |---|---|---|
96
+ | `.pp-select__trigger` | button (implicit) | `aria-haspopup="listbox"`, `aria-expanded`, `aria-controls` → panel id, `aria-label` |
97
+ | `.pp-select__panel` | `role="listbox"` | `aria-label` describing what is being selected |
98
+ | `<li>` wrapping each option | `role="option"` | `aria-selected="true/false"` — **on the `<li>`, not the inner `<button>`** |
99
+ | Divider `<li>` | `role="separator"` | — |
100
+ | Group `<li>` | `role="group"` | `aria-label` for group name |
101
+
102
+ **Critical:** `role="option"` must go on the `<li>` directly under `role="listbox"`. Placing it on the nested `<button>` breaks the required listbox → option ownership and triggers ARIA validation errors.
103
+
104
+ ## Common mistakes
105
+
106
+ - Putting `role="option"` on the `<button>` instead of the `<li>` — breaks listbox ownership model.
107
+ - Omitting `aria-label` on the trigger — `<span class="pp-select__value">` text is not an accessible button name.
108
+ - Forgetting `aria-selected` on `<li role="option">` — AT cannot announce current selection without it.
109
+ - Using a bare `<span>` group label without wrapping in `<li role="group">` — leaves `<li>` elements outside valid parent context.
110
+ - Not updating `aria-expanded` on the trigger when the panel opens/closes — the JS shim handles this, but custom implementations must too.
@@ -0,0 +1,72 @@
1
+ # Switch
2
+
3
+ **Source:** `src/scss/switch.scss` · `src/js/switch.js`
4
+
5
+ iOS-style toggle switch. CSS provides the full visual baseline — the thumb slides via `translateX` driven by `aria-checked`. JS wires the toggle on click and Space key, and dispatches a CustomEvent.
6
+
7
+ ## Full structure
8
+
9
+ ```html
10
+ <!-- Off -->
11
+ <button class="pp-switch" role="switch" aria-checked="false" aria-label="Enable notifications"></button>
12
+
13
+ <!-- On -->
14
+ <button class="pp-switch" role="switch" aria-checked="true" aria-label="Dark mode"></button>
15
+
16
+ <!-- In a settings row -->
17
+ <label style="display:flex; justify-content:space-between; align-items:center; padding:0.875rem 1rem;">
18
+ <span>Push notifications</span>
19
+ <button class="pp-switch" role="switch" aria-checked="false" aria-label="Push notifications"></button>
20
+ </label>
21
+ ```
22
+
23
+ ## Required ARIA
24
+
25
+ | Attribute | Required | Value |
26
+ |---|---|---|
27
+ | `role="switch"` | Yes | Always |
28
+ | `aria-checked` | Yes | `"true"` or `"false"` |
29
+ | `aria-label` or `aria-labelledby` | Yes | Describes what the switch controls |
30
+
31
+ `aria-checked` is the source of truth for visual state — the thumb position and track color are both driven by this attribute. Without it, the switch has no visual state and no accessibility semantics.
32
+
33
+ ## Size modifiers
34
+
35
+ | Class | Width | Height | Thumb | Thumb translate |
36
+ |---|---|---|---|---|
37
+ | `.pp-switch--sm` | 32px | 20px | 14×14px | 12px |
38
+ | (default) | 44px | 26px | 20×20px | 18px |
39
+ | `.pp-switch--lg` | 56px | 32px | 26×26px | 24px |
40
+
41
+ ## JS API
42
+
43
+ `switch.js` auto-initialises all `[role="switch"]` and `.pp-switch` elements on `DOMContentLoaded`. No manual init needed.
44
+
45
+ **Event:**
46
+
47
+ ```js
48
+ switchEl.addEventListener('pp:switch:change', (e) => {
49
+ console.log(e.detail.checked); // boolean
50
+ });
51
+ ```
52
+
53
+ The event bubbles — listen at any ancestor.
54
+
55
+ **Manual toggle (if needed):**
56
+
57
+ ```js
58
+ const sw = document.querySelector('.pp-switch');
59
+ sw.setAttribute('aria-checked', 'true');
60
+ // switch.js listens for direct aria-checked changes too
61
+ ```
62
+
63
+ ## Dark mode
64
+
65
+ Track background uses `--pp-neutral-300` (off) and `--pp-primary` (on) — both adapt automatically under `.dark`. No extra classes needed.
66
+
67
+ ## Common mistakes
68
+
69
+ - Missing `aria-checked` — the switch has no visual state; both track color and thumb position depend on this attribute.
70
+ - Setting `type="checkbox"` instead of `role="switch"` on a `<button>` — use `<input type="checkbox">` with a custom styled label, or use `<button role="switch">` (never both at once).
71
+ - Omitting `aria-label` when the switch has no adjacent visible label — screen readers will announce "switch" with no description of what it controls.
72
+ - Using a `<div>` instead of `<button>` — `<button>` is keyboard focusable by default; `<div>` requires `tabindex="0"` and explicit keyboard handling.
@@ -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.