@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
package/README.md CHANGED
@@ -1,764 +1,811 @@
1
- # PeppertinoCSS — An Apple-inspired CSS framework with a little spice.
2
-
3
- PeppertinoCSS is an Apple-inspired CSS framework built with SCSS, featuring the clean geometry and restrained elegance of Cupertino design — but with a spicy red accent instead of blue, because we're not Apple and we're not pretending to be.
4
-
5
- ---
6
-
7
- ## Getting started
8
-
9
- ```bash
10
- bun add @auriel/peppertino
11
- ```
12
-
13
- CDN — stylesheet only:
14
-
15
- ```html
16
- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@auriel/peppertino@latest/dist/main.min.css" />
17
- ```
18
-
19
- CDN — with JS components:
20
-
21
- ```html
22
- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@auriel/peppertino@latest/dist/main.min.css" />
23
- <script src="https://cdn.jsdelivr.net/npm/@auriel/peppertino@latest/dist/peppertino.js" defer></script>
24
- ```
25
-
26
- SCSS import into your own build:
27
-
28
- ```scss
29
- @use '@auriel/peppertino/src/scss/main';
30
- ```
31
-
32
- Clone and build locally:
33
-
34
- ```bash
35
- git clone https://codeberg.org/debaditya/Peppertino
36
- cd Peppertino
37
- bun install
38
- bun run dev
39
- ```
40
-
41
- Then open `http://localhost:3000` in your browser.
42
-
43
- ---
44
-
45
- ## Build scripts
46
-
47
- | Command | Description |
48
- |---|---|
49
- | `bun run build` | Compile SCSS + JS to `dist/`, then run both linters |
50
- | `bun run build:css` | SCSS only, expanded with sourcemap |
51
- | `bun run build:css:min` | SCSS minified, no sourcemap |
52
- | `bun run build:js` | Bundle all `src/js/` components via esbuild |
53
- | `bun run lint:colors` | Fail if any component SCSS uses literal hex/SCSS color vars |
54
- | `bun run lint:bem` | Fail if any `.pp-*` class in `dist/main.css` violates BEM |
55
- | `bun run watch:css` | Watch and recompile SCSS on save |
56
- | `bun run watch:js` | Watch and rebundle JS on save |
57
- | `bun run serve` | Serve project on `http://localhost:3000` |
58
- | `bun run dev` | Build + watch CSS/JS + serve, all in parallel |
59
-
60
- ---
61
-
62
- ## Claude Code skill
63
-
64
- The `agents/` directory ships a Claude Code skill that gives AI agents per-component reference documentation covering classes, variants, ARIA requirements, and JS APIs.
65
-
66
- ### Install (project-level)
67
-
68
- Copy the skill into your project's Claude skills directory:
69
-
70
- ```bash
71
- cp -r agents/peppertino .claude/skills/peppertino
72
- ```
73
-
74
- Then invoke it in Claude Code:
75
-
76
- ```
77
- /peppertino
78
- ```
79
-
80
- ### Install (user-level — available in all projects)
81
-
82
- ```bash
83
- cp -r agents/peppertino ~/.claude/skills/peppertino
84
- ```
85
-
86
- ### What the skill contains
87
-
88
- | File | Covers |
89
- |---|---|
90
- | `skill.md` | Index, ARIA/WCAG requirements, conventions |
91
- | `base.md` | Design tokens, spacing, breakpoints, mixins |
92
- | `badge.md` | Badge variants, sizes, dot indicator |
93
- | `button.md` | All button variants |
94
- | `card.md` | Card parts, variants, grid |
95
- | `carousel.md` | Carousel markup, API, keyboard |
96
- | `footer.md` | Footer columns, social links |
97
- | `forms-fieldset.md` | Fieldset & legend |
98
- | `forms-form-instructions.md` | Pre-form instructions, hints |
99
- | `forms-label.md` | Label tiers, scale, icon row |
100
- | `forms-text-field.md` | Field wrapper, input, hint, validation |
101
- | `forms-validation.md` | Summary, confirmation checkbox, `ppValidation` API |
102
- | `gradient.md` | Gradient text |
103
- | `header.md` | Header, nav, dropdown, mobile drawer |
104
- | `modal.md` | Modal, actions, `ppModal` API |
105
- | `section.md` | Section variants, scrollbar |
106
- | `select.md` | Native select, custom dropdown |
107
- | `switch.md` | Toggle switch, sizes, `ppSwitch` events |
108
- | `table.md` | Table, column helpers |
109
- | `tabs.md` | Tabs, variants, keyboard nav |
110
- | `toast.md` | Toast positions, variants, `ppToast` API |
111
- | `tooltip.md` | Tooltip placements, CSS-only usage |
112
- | `typography.md` | All typography utility classes |
113
-
114
- The skill's `skill.md` enforces ARIA and WCAG AA compliance rules and instructs the agent to fetch authoritative specs from w3.org when uncertain.
115
-
116
- ---
117
-
118
- ## What's inside
119
-
120
- ### SCSS modules (`src/scss/`)
121
-
122
- | File | Purpose |
123
- |---|---|
124
- | `reset.scss` | Opinionated modern reset |
125
- | `base.scss` | Design tokens, CSS custom properties, helper functions, base element styles |
126
- | `accordion.scss` | `.pp-accordion` — collapsible panels; variants: `--flush`, `--dark`, `--primary` |
127
- | `alert.scss` | `.pp-alert` — inline feedback; variants: `--info/success/warning/error/primary/neutral`, `--filled` |
128
- | `badge.scss` | `.pp-badge` — pill badges; variants: `--primary/success/warning/error/info`, `--filled`, sizes `--sm/lg`, `--dot` |
129
- | `button.scss` | `.pp-button`, `.pp-button--outline`, semantic variants |
130
- | `card.scss` | `.pp-card` and variants |
131
- | `carousel.scss` | `.pp-carousel` — CSS scroll-snap carousel |
132
- | `dark-mode.scss` | `.dark` overrides for all `--pp-*` tokens — applied last |
133
- | `footer.scss` | `.pp-footer` — multi-column footer |
134
- | `forms.scss` | Aggregator for all form partials |
135
- | `forms/fieldset.scss` | `.pp-fieldset` + `.pp-legend` |
136
- | `forms/form-instructions.scss` | `.pp-form-instructions`, `.pp-form-hint` |
137
- | `forms/label.scss` | `.pp-label` — Apple HIG four-tier label system |
138
- | `forms/text-field.scss` | `.pp-field` — labelled input/textarea with validation states |
139
- | `forms/validation.scss` | `.pp-validation-summary`, `.pp-confirm`, `.pp-field--validate` |
140
- | `gradient.scss` | `.pp-gradient-text` |
141
- | `header.scss` | `.pp-header` — glassmorphism sticky header |
142
- | `modal.scss` | `.pp-modal-backdrop` + `.pp-modal` — glassmorphic modals |
143
- | `section.scss` | `.pp-section` — full-viewport sections + custom scrollbar |
144
- | `select.scss` | Native `<select>` restyling + `.pp-select` custom dropdown |
145
- | `switch.scss` | `.pp-switch` — iOS-style toggle; sizes `--sm/lg` |
146
- | `table.scss` | `.pp-table` — clean Apple-style data tables |
147
- | `tabs.scss` | `.pp-tabs` — pill-style tabs with icon + label |
148
- | `toast.scss` | `.pp-toast-container` + `.pp-toast` — auto-dismiss notifications |
149
- | `tooltip.scss` | `.pp-tooltip` — CSS-only tooltip; placements `--top/bottom/left/right` |
150
- | `typography.scss` | Utility classes for font, size, weight, spacing |
151
- | `utilities.scss` | Single-purpose layout/spacing/display/visibility classes |
152
-
153
- ### JS components (`src/js/`)
154
-
155
- Each file is a self-contained IIFE. Import only what you need, or include `peppertino.js` for everything.
156
-
157
- | File | Purpose |
158
- |---|---|
159
- | `accordion.js` | `aria-expanded`/`aria-hidden`, keyboard nav (↑ ↓ Home End), `data-allow-multiple`; `ppAccordion.get(ref)` API |
160
- | `alert.js` | `data-alert-dismiss` wiring; `window.ppAlert.dismiss(idOrEl)` |
161
- | `carousel.js` | ARIA wiring, IntersectionObserver sync, `ppCarousel` API |
162
- | `header.js` | Mobile drawer, dropdown ARIA wiring for `.pp-header` |
163
- | `modal.js` | Open/close, focus trap, focus restore, ARIA for `.pp-modal` |
164
- | `select.js` | Keyboard nav, ARIA listbox/option for `.pp-select` |
165
- | `switch.js` | `aria-checked` toggle, Space key, `pp:switch:change` event |
166
- | `tabs.js` | Click + arrow key activation, ARIA tablist; `ppTabs.get(ref).activate(index)` |
167
- | `theme.js` | `window.ppTheme.set/get/toggle`; persists to `localStorage`; `data-theme-toggle` wiring |
168
- | `toast.js` | `window.ppToast.show({ message, title, variant, duration, position })`; auto-dismiss |
169
- | `validation.js` | `aria-invalid` wiring, summary focus, `ppValidation` API |
170
- | `peppertino.js` | Aggregator — imports all of the above |
171
-
172
- All JS follows progressive enhancement — CSS provides the full visual baseline without JS. JS adds keyboard navigation, focus management, and ARIA state.
173
-
174
- ---
175
-
176
- ## Design tokens (`base.scss`)
177
-
178
- ### Colors — HSL channel system
179
-
180
- All color tokens are decomposed into H/S/L channel properties so any component can form alpha tints without `rgba()`:
181
-
182
- ```css
183
- /* Each token ships three channel vars + a composite shorthand */
184
- --pp-primary-h: 356;
185
- --pp-primary-s: 99.2%;
186
- --pp-primary-l: 46.3%;
187
- --pp-primary: hsl(var(--pp-primary-h) var(--pp-primary-s) var(--pp-primary-l));
188
-
189
- /* Alpha tints use the channels directly — no SCSS needed */
190
- background: hsl(var(--pp-primary-h) var(--pp-primary-s) var(--pp-primary-l) / 0.15);
191
- ```
192
-
193
- Available token families: `--pp-primary`, `--pp-gradient-start`, `--pp-gradient-end`, neutral scale (`--pp-neutral-50` → `--pp-neutral-900`), semantic scales `--pp-success-*`, `--pp-warning-*`, `--pp-error-*`, `--pp-info-*` (each with 50/100/200/300/400/500/600/700/800/900 levels).
194
-
195
- Dark mode overrides channel properties (`-l`, `-s`) rather than full hex values — single-token changes cascade everywhere.
196
-
197
- ### Typography
198
-
199
- ```scss
200
- $font-sans: 'Inter', system-ui, ...
201
- $font-mono: 'Kode Mono', ui-monospace, ...
202
- ```
203
-
204
- Both fonts are loaded from Google Fonts automatically via `base.scss`.
205
-
206
- ### Spacing, radius, shadows, breakpoints
207
-
208
- All defined as SCSS maps in `base.scss` and accessible via helper functions:
209
-
210
- ```scss
211
- spacing(4) // → 1rem
212
- font-size('2xl') // → 1.5rem
213
- radius('lg') // → 0.5rem
214
- z('modal') // → 200
215
- ```
216
-
217
- ### Responsive mixins
218
-
219
- ```scss
220
- @include respond-to('md') { /* min-width: 768px */ }
221
- @include respond-below('md') { /* max-width: 767px */ }
222
- @include respond-between('sm','lg') { /* 640px – 1023px */ }
223
- ```
224
-
225
- Tailwind breakpoints: `sm` 640px · `md` 768px · `lg` 1024px · `xl` 1280px · `2xl` 1536px
226
-
227
- Apple device breakpoints: `iphone-se` · `iphone` · `iphone-plus` · `iphone-pro-max` · `ipad-mini` · `ipad-air` · `ipad-pro-11` · `ipad-pro-13` · `macbook-air-13` · `macbook-pro-14` · `macbook-pro-16` · `imac`
228
-
229
- ---
230
-
231
- ## Typography utilities
232
-
233
- ```html
234
- <p class="font-sans font-700 text-2xl tracking-tight">Hello</p>
235
- <p class="font-mono font-400 text-sm leading-relaxed">code prose</p>
236
- ```
237
-
238
- | Category | Classes |
239
- |---|---|
240
- | Family | `.font-sans` `.font-mono` |
241
- | Weight | `.font-100` → `.font-900` |
242
- | Size | `.text-xs` `.text-sm` `.text-base` `.text-lg` `.text-xl` `.text-2xl` `.text-3xl` `.text-4xl` `.text-5xl` |
243
- | Line height | `.leading-none` `.leading-tight` `.leading-snug` `.leading-normal` `.leading-relaxed` `.leading-loose` |
244
- | Tracking | `.tracking-tighter` `.tracking-tight` `.tracking-normal` `.tracking-wide` `.tracking-wider` `.tracking-widest` |
245
- | Alignment | `.text-left` `.text-center` `.text-right` |
246
- | Transform | `.uppercase` `.lowercase` `.capitalize` |
247
- | Decoration | `.underline` `.no-underline` `.line-through` |
248
- | Overflow | `.truncate` `.wrap-balance` |
249
-
250
- ---
251
-
252
- ## Components
253
-
254
- ### Accordion
255
-
256
- ```html
257
- <div class="pp-accordion" data-allow-multiple>
258
- <div class="pp-accordion__item">
259
- <button class="pp-accordion__trigger" aria-expanded="false" aria-controls="acc-1">
260
- Question
261
- <svg class="pp-accordion__icon" viewBox="0 0 24 24" aria-hidden="true"><polyline points="6 9 12 15 18 9"/></svg>
262
- </button>
263
- <div class="pp-accordion__panel" id="acc-1" aria-hidden="true">
264
- <p class="pp-accordion__content">Answer text.</p>
265
- </div>
266
- </div>
267
- </div>
268
- <script src="dist/accordion.js" defer></script>
269
- ```
270
-
271
- Variants: `--flush` · `--dark` · `--primary`
272
- Attribute: `data-allow-multiple` — allow multiple panels open at once
273
- Keyboard: `↑` / `↓` arrows, `Home`, `End`
274
-
275
- ### Alert
276
-
277
- ```html
278
- <div class="pp-alert pp-alert--info" role="note">
279
- <span class="pp-alert__icon"><i data-lucide="info" aria-hidden="true"></i></span>
280
- <div class="pp-alert__body">
281
- <p class="pp-alert__title">Heads up</p>
282
- <p class="pp-alert__message">Your session expires in 10 minutes.</p>
283
- </div>
284
- </div>
285
-
286
- <!-- Dismissible -->
287
- <div class="pp-alert pp-alert--success is-dismissible" role="status" id="a1">
288
- <span class="pp-alert__icon"><i data-lucide="circle-check" aria-hidden="true"></i></span>
289
- <div class="pp-alert__body"><p class="pp-alert__message">Saved.</p></div>
290
- <button class="pp-alert__dismiss" aria-label="Dismiss"
291
- onclick="const e=document.getElementById('a1');e.classList.add('is-dismissing');setTimeout(()=>e.remove(),200);">
292
- <i data-lucide="x" aria-hidden="true"></i>
293
- </button>
294
- </div>
295
- ```
296
-
297
- Variants: `--info` · `--success` · `--warning` · `--error` · `--primary` · `--neutral`
298
- Modifier: `--filled` (solid background instead of tint)
299
- States: `.is-dismissible` · `.is-dismissing` (slide-out before removal)
300
-
301
- JS API: `window.ppAlert.dismiss(idOrEl)` — accepts an element or its `id` string.
302
- Event: `pp:alert:dismiss` dispatched on the alert element before removal.
303
-
304
- ### Badge
305
-
306
- ```html
307
- <!-- Tint variants (default) -->
308
- <span class="pp-badge pp-badge--info">New</span>
309
- <span class="pp-badge pp-badge--success">Active</span>
310
- <span class="pp-badge pp-badge--warning">Review</span>
311
- <span class="pp-badge pp-badge--error">Error</span>
312
- <span class="pp-badge pp-badge--primary">Beta</span>
313
-
314
- <!-- Filled (solid background) -->
315
- <span class="pp-badge pp-badge--success pp-badge--filled">Active</span>
316
-
317
- <!-- Sizes -->
318
- <span class="pp-badge pp-badge--info pp-badge--sm">Small</span>
319
- <span class="pp-badge pp-badge--info pp-badge--lg">Large</span>
320
-
321
- <!-- Dot indicator (no text — pair with sr-only label) -->
322
- <span class="pp-badge pp-badge--error pp-badge--dot" aria-label="3 unread"></span>
323
- ```
324
-
325
- Variants: `--primary` · `--success` · `--warning` · `--error` · `--info`
326
- Modifiers: `--filled` · `--sm` · `--lg` · `--dot`
327
-
328
- ### Button
329
-
330
- ```html
331
- <button class="pp-button">Primary</button>
332
- <button class="pp-button--success">Success</button>
333
- <button class="pp-button--warning">Warning</button>
334
- <button class="pp-button--error">Error</button>
335
- <button class="pp-button--dark">Dark</button>
336
- <button class="pp-button--gradient">Gradient</button>
337
- <button class="pp-button--ghost">Ghost</button>
338
-
339
- <button class="pp-button--outline">Primary</button>
340
- <button class="pp-button--outline pp-button--success">Success</button>
341
- <button class="pp-button--outline pp-button--warning">Warning</button>
342
- <button class="pp-button--outline pp-button--error">Error</button>
343
- <button class="pp-button--outline pp-button--dark">Dark</button>
344
- ```
345
-
346
- ### Card
347
-
348
- ```html
349
- <div class="pp-card">...</div>
350
- <div class="pp-card pp-card--dark">...</div>
351
- <div class="pp-card pp-card--gradient">...</div>
352
- <div class="pp-card pp-card--primary">...</div>
353
- <div class="pp-card pp-card--ghost">...</div>
354
- ```
355
-
356
- Grid helpers: `.pp-card-grid--2` · `.pp-card-grid--3` · `.pp-card-grid--4`
357
-
358
- ### Carousel
359
-
360
- ```html
361
- <div class="pp-carousel" id="my-carousel" data-label="Featured">
362
- <div class="pp-carousel__track">
363
- <div class="pp-carousel__slide" id="my-carousel-slide-0">...</div>
364
- <div class="pp-carousel__slide" id="my-carousel-slide-1">...</div>
365
- </div>
366
- <button class="pp-carousel__prev" type="button" aria-label="Previous slide">
367
- <svg viewBox="0 0 24 24" aria-hidden="true"><polyline points="15 18 9 12 15 6"/></svg>
368
- </button>
369
- <button class="pp-carousel__next" type="button" aria-label="Next slide">
370
- <svg viewBox="0 0 24 24" aria-hidden="true"><polyline points="9 6 15 12 9 18"/></svg>
371
- </button>
372
- <div class="pp-carousel__dots" aria-label="Slide navigation">
373
- <button class="pp-carousel__dot" type="button" aria-label="Go to slide 1" aria-controls="my-carousel-slide-0"></button>
374
- <button class="pp-carousel__dot" type="button" aria-label="Go to slide 2" aria-controls="my-carousel-slide-1"></button>
375
- </div>
376
- <div class="pp-carousel__announcer" aria-live="polite" aria-atomic="true"></div>
377
- </div>
378
- <script src="dist/carousel.js" defer></script>
379
- ```
380
-
381
- Variants: `--peek-2` · `--peek-3` · `--dark` · `--flush`
382
- API: `ppCarousel.get(id).goTo(n)`
383
-
384
- ### Footer
385
-
386
- ```html
387
- <footer class="pp-footer" role="contentinfo">
388
- <div class="pp-footer__top">
389
- <div class="pp-footer__brand">
390
- <a href="#" class="pp-footer__logo">Brand</a>
391
- <p class="pp-footer__tagline">Tagline</p>
392
- </div>
393
- <div class="pp-footer__col">
394
- <p class="pp-footer__col-title">Column</p>
395
- <ul class="pp-footer__nav" aria-label="Column links">
396
- <li><a href="#" class="pp-footer__nav-link">Link</a></li>
397
- </ul>
398
- </div>
399
- </div>
400
- <div class="pp-footer__bottom">
401
- <p class="pp-footer__legal">&copy; 2026 Brand.</p>
402
- <ul class="pp-footer__social" aria-label="Social links">
403
- <li><a href="#" class="pp-footer__social-link" aria-label="GitHub"><i data-lucide="github"></i></a></li>
404
- </ul>
405
- </div>
406
- </footer>
407
- ```
408
-
409
- Variants: `--dark` · `--accent`
410
-
411
- ### Forms
412
-
413
- #### Label
414
-
415
- ```html
416
- <span class="pp-label pp-label--primary">Primary</span>
417
- <span class="pp-label pp-label--secondary pp-label--callout">Secondary callout</span>
418
- <span class="pp-label pp-label--selectable">Selectable text</span>
419
- <span class="pp-label-row pp-label"><i data-lucide="wifi" aria-hidden="true"></i> Wi-Fi</span>
420
- ```
421
-
422
- Tiers: `--primary` · `--secondary` · `--tertiary` · `--quaternary`
423
- Scale: `--headline` · `--subheadline` · `--body` · `--callout` · `--footnote` · `--caption`
424
-
425
- #### Fieldset
426
-
427
- ```html
428
- <fieldset class="pp-fieldset">
429
- <legend>Group name</legend>
430
- <!-- controls -->
431
- </fieldset>
432
- ```
433
-
434
- Variants: `--ghost` · `--filled` · `--primary` · `--error`
435
- Legend modifiers: `--sm` · `--lg` · `--inline`
436
-
437
- #### Form Instructions
438
-
439
- ```html
440
- <!-- Place BEFORE <form> -->
441
- <div class="pp-form-instructions" role="note" aria-label="Form instructions">
442
- <p class="pp-form-instructions__title">Before you begin</p>
443
- <ul class="pp-form-instructions__list">
444
- <li class="pp-form-instructions__item">Fields marked * are required.</li>
445
- </ul>
446
- </div>
447
- ```
448
-
449
- Variants: `--neutral` · `--warning` · `--error` (use `role="alert"` for errors)
450
-
451
- #### Text Field
452
-
453
- ```html
454
- <div class="pp-field">
455
- <label class="pp-field__label" for="name">
456
- Name
457
- <abbr class="pp-field__required" aria-label="required" title="required"></abbr>
458
- </label>
459
- <input class="pp-field__input" type="text" id="name" name="name"
460
- required aria-required="true" aria-describedby="name-hint" />
461
- <span class="pp-field__hint" id="name-hint">Your full legal name.</span>
462
- </div>
463
- ```
464
-
465
- States: `--error` · `--success` · `--warning` · `--validating`
466
- Sizes: `--sm` · `--lg`
467
-
468
- #### Validation
469
-
470
- ```html
471
- <!-- Summary (place before or at top of form) -->
472
- <div class="pp-validation-summary" role="alert" aria-label="Form errors">
473
- <p class="pp-validation-summary__title">Errors prevented submission</p>
474
- <ul class="pp-validation-summary__list"></ul>
475
- </div>
476
-
477
- <!-- Confirmation checkbox -->
478
- <label class="pp-confirm">
479
- <input class="pp-confirm__input" type="checkbox" />
480
- <span class="pp-confirm__label">I confirm this action.</span>
481
- </label>
482
- <button class="pp-button pp-submit--gated" type="submit">Submit</button>
483
- ```
484
-
485
- JS API (optional — CSS works without it):
486
-
487
- ```js
488
- ppValidation.setError(input, 'Message')
489
- ppValidation.clearError(input)
490
- ppValidation.setSuccess(input, 'Message')
491
- ppValidation.setValidating(input)
492
- ppValidation.setSummary([{ input, message }], summaryEl)
493
- ```
494
-
495
- ### Gradient text
496
-
497
- ```html
498
- <h1 class="pp-gradient-text">PeppertinoCSS</h1>
499
- ```
500
-
501
- ### Header
502
-
503
- ```html
504
- <header class="pp-header">
505
- <a href="#" class="pp-header__brand">Brand</a>
506
- <nav aria-label="Main navigation">
507
- <ul class="pp-header__nav" role="menubar">
508
- <li class="pp-header__nav-item" role="none">
509
- <a href="#" class="pp-header__nav-link" role="menuitem">Link</a>
510
- </li>
511
- <li class="pp-header__nav-item" role="none">
512
- <a href="#" class="pp-header__nav-link" role="menuitem" aria-haspopup="true" aria-expanded="false">Dropdown</a>
513
- <ul class="pp-header__dropdown" role="menu">
514
- <li role="none"><a href="#" class="pp-header__dropdown-link" role="menuitem">Item</a></li>
515
- </ul>
516
- </li>
517
- </ul>
518
- </nav>
519
- <button class="pp-header__toggle" aria-expanded="false" aria-label="Toggle navigation">
520
- <span></span><span></span><span></span>
521
- </button>
522
- </header>
523
- <script src="dist/header.js" defer></script>
524
- ```
525
-
526
- ### Modal
527
-
528
- ```html
529
- <button data-modal-open="my-modal">Open</button>
530
-
531
- <div id="my-modal" class="pp-modal-backdrop"
532
- role="dialog" aria-modal="true"
533
- aria-labelledby="my-modal-title"
534
- aria-describedby="my-modal-desc"
535
- aria-hidden="true">
536
- <div class="pp-modal">
537
- <button class="pp-modal__close" data-modal-close="my-modal" aria-label="Close">✕</button>
538
- <p class="pp-modal__title" id="my-modal-title">Title</p>
539
- <p class="pp-modal__description" id="my-modal-desc">Description text.</p>
540
- <ul class="pp-modal__actions">
541
- <li><button class="pp-modal__action">Action</button></li>
542
- <li><button class="pp-modal__action pp-modal__action--cancel" data-modal-close="my-modal">Cancel</button></li>
543
- </ul>
544
- </div>
545
- </div>
546
- <script src="dist/modal.js" defer></script>
547
- ```
548
-
549
- `window.ppModal.open(id)` / `.close(id)` / `.closeAll()`
550
-
551
- ### Select
552
-
553
- ```html
554
- <div class="pp-select">
555
- <button class="pp-select__trigger" type="button" aria-label="Choose option">
556
- <span class="pp-select__value">Choose…</span>
557
- <span class="pp-select__chevron"></span>
558
- </button>
559
- <ul class="pp-select__panel" role="listbox">
560
- <li role="option"><button class="pp-select__option" data-value="a">Option A</button></li>
561
- <li role="option"><button class="pp-select__option" data-value="b">Option B</button></li>
562
- </ul>
563
- </div>
564
- <script src="dist/select.js" defer></script>
565
- ```
566
-
567
- Sizes: `.pp-select--sm` · `.pp-select--lg`
568
-
569
- ### Switch
570
-
571
- ```html
572
- <!-- Basic toggle -->
573
- <button class="pp-switch" role="switch" aria-checked="false" aria-label="Enable notifications"></button>
574
-
575
- <!-- Pre-checked -->
576
- <button class="pp-switch" role="switch" aria-checked="true" aria-label="Dark mode"></button>
577
-
578
- <!-- Sizes -->
579
- <button class="pp-switch pp-switch--sm" role="switch" aria-checked="false" aria-label="Compact mode"></button>
580
- <button class="pp-switch pp-switch--lg" role="switch" aria-checked="false" aria-label="Accessibility features"></button>
581
- ```
582
-
583
- Sizes: `--sm` (32×20px) · default (44×26px) · `--lg` (56×32px)
584
- JS handles `aria-checked` toggle on click and Space key.
585
- Event: `pp:switch:change` with `{ checked: boolean }` on the switch element.
586
-
587
- ### Tabs
588
-
589
- ```html
590
- <div class="pp-tabs" role="tablist">
591
- <button class="pp-tabs__item is-active" role="tab" aria-selected="true">Tab 1</button>
592
- <button class="pp-tabs__item" role="tab" aria-selected="false">Tab 2</button>
593
- </div>
594
- <div data-tab-panel="tab1" role="tabpanel">Panel 1</div>
595
- <div data-tab-panel="tab2" role="tabpanel" hidden>Panel 2</div>
596
- <script src="dist/tabs.js" defer></script>
597
- ```
598
-
599
- Variants: default · `--outline` · `--gradient` · `--gradient-outline`
600
- Sizes: `--sm` · `--lg`
601
- Keyboard: `←` / `→` arrows, `Home`, `End`
602
- JS API: `ppTabs.get(ref).activate(index)` — programmatically activate a tab by index.
603
- Event: `pp:tabs:change` with `{ index }` on the `.pp-tabs` element.
604
-
605
- ### Table
606
-
607
- ```html
608
- <table class="pp-table pp-table--cols-3">
609
- <tbody>
610
- <tr><td>Label</td><td>Value A</td><td>Value B</td></tr>
611
- </tbody>
612
- </table>
613
- ```
614
-
615
- Column helpers: `.pp-table--cols-1` → `.pp-table--cols-4`
616
-
617
- ### Toast
618
-
619
- ```js
620
- // Show a toast (JS required)
621
- ppToast.show({ message: 'File saved.', variant: 'success' });
622
- ppToast.show({ message: 'Sync failed.', title: 'Error', variant: 'error', duration: 6000 });
623
- ppToast.show({ message: 'Update available.', variant: 'info', position: 'bottom-center' });
624
- ```
625
-
626
- ```html
627
- <!-- Dismiss button with data attribute (no JS needed) -->
628
- <button data-toast-dismiss aria-label="Dismiss">✕</button>
629
- ```
630
-
631
- Variants: `--info` · `--success` · `--warning` · `--error` · `--neutral`
632
- Positions: `top-right` (default) · `top-left` · `top-center` · `bottom-right` · `bottom-left` · `bottom-center`
633
- Options: `message` · `title` · `variant` · `duration` (ms, default 4000) · `position`
634
- Events: `pp:toast:show` / `pp:toast:dismiss` on the toast element.
635
-
636
- ### Tooltip
637
-
638
- ```html
639
- <!-- CSS-only: shows on hover and :focus-within -->
640
- <span class="pp-tooltip">
641
- Hover me
642
- <span class="pp-tooltip__content" role="tooltip">Helpful hint</span>
643
- </span>
644
-
645
- <!-- Force-show via attribute (e.g. for testing) -->
646
- <span class="pp-tooltip">
647
- Click me
648
- <span class="pp-tooltip__content pp-tooltip__content--bottom" role="tooltip" data-show>
649
- Shown below
650
- </span>
651
- </span>
652
- ```
653
-
654
- Placements: default (top) · `--bottom` · `--left` · `--right`
655
- Shown automatically on `:hover` and `:focus-within` — no JS required.
656
- Add `data-show` to force-display for testing.
657
-
658
- ### Section
659
-
660
- ```html
661
- <section class="pp-section">
662
- <div class="pp-section__inner">
663
- <!-- content -->
664
- </div>
665
- </section>
666
- ```
667
-
668
- Variants: `--primary` · `--dark` · `--muted` · `--gradient`
669
-
670
- ---
671
-
672
- ## Utilities
673
-
674
- Single-purpose classes — no JavaScript required. Import `utilities.scss` or use the compiled CSS.
675
-
676
- | Group | Classes |
677
- |---|---|
678
- | Display | `.d-{block\|inline\|inline-block\|flex\|inline-flex\|grid\|inline-grid\|none\|contents}` |
679
- | Visibility | `.visible` `.invisible` `.sr-only` `.not-sr-only` |
680
- | Opacity | `.opacity-{0\|25\|50\|75\|100}` |
681
- | Margin | `.m-*` `.mt-*` `.mb-*` `.ml-*` `.mr-*` `.mx-*` `.my-*` (keys 0–32, `auto`) |
682
- | Padding | `.p-*` `.pt-*` `.pb-*` `.pl-*` `.pr-*` `.px-*` `.py-*` (keys 0–32) |
683
- | Gap | `.gap-*` `.gap-x-*` `.gap-y-*` (keys 0–32) |
684
- | Flex | direction, wrap, grow/shrink, justify-content, align-items, align-self |
685
- | Grid | `.grid-cols-{1–6,12}` `.grid-rows-{1–4}` `.col-span-*` `.row-span-*` |
686
- | Width | `.w-full` `.w-screen` `.w-auto` `.w-fit` `.w-min` `.w-max` `.w-half` |
687
- | Height | `.h-full` `.h-screen` `.h-auto` `.h-fit` |
688
- | Overflow | `.overflow-{auto\|hidden\|visible\|scroll}`, x/y variants |
689
- | Position | `.static` `.relative` `.absolute` `.fixed` `.sticky` |
690
- | Z-index | `.z-{below\|base\|raised\|overlay\|modal\|toast\|tooltip}` |
691
- | Border-radius | `.rounded-{none\|sm\|base\|md\|lg\|xl\|2xl\|full}` |
692
- | Shadow | `.shadow-{none\|sm\|md\|lg\|xl}` |
693
- | Cursor | `.cursor-{default\|pointer\|not-allowed\|grab\|text}` |
694
- | Responsive | `.sm-d-*` `.md-d-*` `.lg-d-*` `.xl-d-*` `.w2xl-d-*` (display only) |
695
-
696
- ---
697
-
698
- ## Dark mode
699
-
700
- Add `class="dark"` to `<html>` (or any ancestor element). All component tokens flip automatically via CSS custom properties — no extra classes needed on individual components.
701
-
702
- ```html
703
- <html class="dark">
704
- <!-- everything inside uses dark surface tokens -->
705
- </html>
706
- ```
707
-
708
- Toggle from JS using the `ppTheme` API (requires `theme.js`):
709
-
710
- ```js
711
- ppTheme.set('dark'); // switch to dark mode
712
- ppTheme.set('light'); // switch to light mode
713
- ppTheme.toggle(); // flip current mode
714
- ppTheme.get(); // → 'dark' | 'light'
715
- ```
716
-
717
- Or add `data-theme-toggle` to any button — it wires automatically:
718
-
719
- ```html
720
- <button data-theme-toggle aria-label="Toggle dark mode">Dark</button>
721
- ```
722
-
723
- The preference is persisted to `localStorage` under `pp-theme` and restored on page load. Event: `pp:theme:change` with `{ theme: 'dark' | 'light' }` dispatched on `document`.
724
-
725
- All `--pp-*` tokens are defined on `:root` as light defaults. `dark-mode.scss` overrides them under `.dark`. The neutral scale is fully inverted (50 ↔ 900), surfaces swap, and glass/shadow values are strengthened for dark backgrounds.
726
-
727
- ---
728
-
729
- ## CustomEvents reference
730
-
731
- All JS components dispatch `pp:<component>:<event>` CustomEvents that bubble. Listen at any ancestor:
732
-
733
- | Event | Dispatched on | Detail |
734
- |---|---|---|
735
- | `pp:accordion:open` | `.pp-accordion` | `{ index, trigger, panel }` |
736
- | `pp:accordion:close` | `.pp-accordion` | `{ index, trigger, panel }` |
737
- | `pp:alert:dismiss` | `.pp-alert` | — |
738
- | `pp:carousel:change` | `.pp-carousel` | `{ index, total, label }` |
739
- | `pp:header:open` | `.pp-header` | — |
740
- | `pp:header:close` | `.pp-header` | — |
741
- | `pp:modal:open` | `.pp-modal-backdrop` | — |
742
- | `pp:modal:close` | `.pp-modal-backdrop` | — |
743
- | `pp:select:change` | `.pp-select` | `{ value }` |
744
- | `pp:switch:change` | `.pp-switch` | `{ checked: boolean }` |
745
- | `pp:tabs:change` | `.pp-tabs` | `{ index }` |
746
- | `pp:theme:change` | `document` | `{ theme: 'dark' \| 'light' }` |
747
- | `pp:toast:show` | `.pp-toast` | — |
748
- | `pp:toast:dismiss` | `.pp-toast` | — |
749
-
750
- ---
751
-
752
- ## Changelog
753
-
754
- See [CHANGELOG.txt](CHANGELOG.txt)
755
-
756
- ---
757
-
758
- ## License
759
-
760
- MIT — see [LICENSE](LICENSE)
761
-
762
- ---
763
-
764
- [Codeberg](https://codeberg.org/debaditya/Peppertino)
1
+ # PeppertinoCSS — An Apple-inspired CSS framework with a little spice.
2
+
3
+ PeppertinoCSS is an Apple-inspired CSS framework built with SCSS, featuring the clean geometry and restrained elegance of Cupertino design — but with a spicy red accent instead of blue, because we're not Apple and we're not pretending to be.
4
+
5
+ ---
6
+
7
+ ## Getting started
8
+
9
+ ```bash
10
+ bun add @auriel/peppertino
11
+ ```
12
+
13
+ CDN — stylesheet only:
14
+
15
+ ```html
16
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@auriel/peppertino@latest/dist/main.min.css" />
17
+ ```
18
+
19
+ CDN — with JS components:
20
+
21
+ ```html
22
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@auriel/peppertino@latest/dist/main.min.css" />
23
+ <script src="https://cdn.jsdelivr.net/npm/@auriel/peppertino@latest/dist/peppertino.js" defer></script>
24
+ ```
25
+
26
+ SCSS import into your own build:
27
+
28
+ ```scss
29
+ @use '@auriel/peppertino/src/scss/main';
30
+ ```
31
+
32
+ Clone and build locally:
33
+
34
+ ```bash
35
+ git clone https://codeberg.org/debaditya/Peppertino
36
+ cd Peppertino
37
+ bun install
38
+ bun run dev
39
+ ```
40
+
41
+ Then open `http://localhost:3000` in your browser.
42
+
43
+ ---
44
+
45
+ ## Build scripts
46
+
47
+ | Command | Description |
48
+ |---|---|
49
+ | `bun run build` | Compile expanded and minified CSS and JS to `dist/`, then run both linters |
50
+ | `bun run build:css` | SCSS only, expanded with sourcemap |
51
+ | `bun run build:css:min` | SCSS minified, no sourcemap |
52
+ | `bun run build:js` | Bundle all `src/js/` components via esbuild |
53
+ | `bun run lint:colors` | Fail if any component SCSS uses literal hex/SCSS color vars |
54
+ | `bun run lint:bem` | Fail if any `.pp-*` class in `dist/main.css` violates BEM |
55
+ | `bun run watch:css` | Watch and recompile SCSS on save |
56
+ | `bun run watch:js` | Watch and rebundle JS on save |
57
+ | `bun run serve` | Serve project on `http://localhost:3000` |
58
+ | `bun run dev` | Build + watch CSS/JS + serve, all in parallel |
59
+
60
+ ---
61
+
62
+ ## Claude Code skill
63
+
64
+ The `agents/` directory ships a Claude Code skill that gives AI agents per-component reference documentation covering classes, variants, ARIA requirements, and JS APIs.
65
+
66
+ ### Install (project-level)
67
+
68
+ Copy the skill into your project's Claude skills directory:
69
+
70
+ ```bash
71
+ cp -r agents/peppertino .claude/skills/peppertino
72
+ ```
73
+
74
+ Then invoke it in Claude Code:
75
+
76
+ ```
77
+ /peppertino
78
+ ```
79
+
80
+ ### Install (user-level — available in all projects)
81
+
82
+ ```bash
83
+ cp -r agents/peppertino ~/.claude/skills/peppertino
84
+ ```
85
+
86
+ ### What the skill contains
87
+
88
+ | File | Covers |
89
+ |---|---|
90
+ | `skill.md` | Index, ARIA/WCAG requirements, conventions |
91
+ | `base.md` | Design tokens, spacing, breakpoints, mixins |
92
+ | `badge.md` | Badge variants, sizes, dot indicator |
93
+ | `button.md` | All button variants |
94
+ | `card.md` | Card parts, variants, grid |
95
+ | `catalog.md` | Standalone display, navigation, input, feedback, and AI/search patterns |
96
+ | `components-display.md` | Display and feedback components, motion and accessibility guidance |
97
+ | `components-navigation.md` | Standalone navigation and progress patterns |
98
+ | `components-inputs.md` | Native input patterns and optional application behavior |
99
+ | `components-ai-search.md` | Response and search presentation, streaming and privacy |
100
+ | `carousel.md` | Carousel markup, API, keyboard |
101
+ | `footer.md` | Footer columns, social links |
102
+ | `forms-fieldset.md` | Fieldset & legend |
103
+ | `forms-form-instructions.md` | Pre-form instructions, hints |
104
+ | `forms-label.md` | Label tiers, scale, icon row |
105
+ | `forms-text-field.md` | Field wrapper, input, hint, validation |
106
+ | `forms-validation.md` | Summary, confirmation checkbox, `ppValidation` API |
107
+ | `gradient.md` | Gradient text |
108
+ | `header.md` | Header, nav, dropdown, mobile drawer |
109
+ | `modal.md` | Modal, actions, `ppModal` API |
110
+ | `section.md` | Section variants, scrollbar |
111
+ | `select.md` | Native select, custom dropdown |
112
+ | `switch.md` | Toggle switch, sizes, `ppSwitch` events |
113
+ | `table.md` | Table, column helpers |
114
+ | `tabs.md` | Tabs, variants, keyboard nav |
115
+ | `toast.md` | Toast positions, variants, `ppToast` API |
116
+ | `tooltip.md` | Tooltip placements, CSS-only usage |
117
+ | `typography.md` | All typography utility classes |
118
+
119
+ The skill's `skill.md` enforces ARIA and WCAG AA compliance rules and instructs the agent to fetch authoritative specs from w3.org when uncertain.
120
+
121
+ ---
122
+
123
+ ## What's inside
124
+
125
+ ### SCSS modules (`src/scss/`)
126
+
127
+ | File | Purpose |
128
+ |---|---|
129
+ | `reset.scss` | Opinionated modern reset |
130
+ | `base.scss` | Design tokens, CSS custom properties, helper functions, base element styles |
131
+ | `accordion.scss` | `.pp-accordion` — collapsible panels; variants: `--flush`, `--dark`, `--primary` |
132
+ | `alert.scss` | `.pp-alert` — inline feedback; variants: `--info/success/warning/error/primary/neutral`, `--filled` |
133
+ | `badge.scss` | `.pp-badge` — pill badges; variants: `--primary/success/warning/error/info`, `--filled`, sizes `--sm/lg`, `--dot` |
134
+ | `button.scss` | `.pp-button`, `.pp-button--outline`, semantic variants |
135
+ | `card.scss` | `.pp-card` and variants |
136
+ | `carousel.scss` | `.pp-carousel` — CSS scroll-snap carousel |
137
+ | `dark-mode.scss` | `.dark` overrides for all `--pp-*` tokens — applied last |
138
+ | `footer.scss` | `.pp-footer` — multi-column footer |
139
+ | `forms.scss` | Aggregator for all form partials |
140
+ | `forms/fieldset.scss` | `.pp-fieldset` + `.pp-legend` |
141
+ | `forms/form-instructions.scss` | `.pp-form-instructions`, `.pp-form-hint` |
142
+ | `forms/label.scss` | `.pp-label` — Apple HIG four-tier label system |
143
+ | `forms/text-field.scss` | `.pp-field` — labelled input/textarea with validation states |
144
+ | `forms/validation.scss` | `.pp-validation-summary`, `.pp-confirm`, `.pp-field--validate` |
145
+ | `gradient.scss` | `.pp-gradient-text` |
146
+ | `header.scss` | `.pp-header` — glassmorphism sticky header |
147
+ | `modal.scss` | `.pp-modal-backdrop` + `.pp-modal` — glassmorphic modals |
148
+ | `section.scss` | `.pp-section` — full-viewport sections + custom scrollbar |
149
+ | `select.scss` | Native `<select>` restyling + `.pp-select` custom dropdown |
150
+ | `switch.scss` | `.pp-switch` — iOS-style toggle; sizes `--sm/lg` |
151
+ | `table.scss` | `.pp-table` — clean Apple-style data tables |
152
+ | `tabs.scss` | `.pp-tabs` — pill-style tabs with icon + label |
153
+ | `toast.scss` | `.pp-toast-container` + `.pp-toast` — auto-dismiss notifications |
154
+ | `tooltip.scss` | `.pp-tooltip` — CSS-only tooltip; placements `--top/bottom/left/right` |
155
+ | `typography.scss` | Utility classes for font, size, weight, spacing |
156
+ | `utilities.scss` | Single-purpose layout/spacing/display/visibility classes |
157
+ | `main.scss` | Full framework entry point |
158
+ | `activity.scss` | Contribution or activity grid presentation |
159
+ | `code-block.scss` | Code display with an optional header |
160
+ | `counter.scss` | Numeric value presentation |
161
+ | `duration.scss` | Native hours and minutes inputs |
162
+ | `folder.scss` | Native folder-style disclosure |
163
+ | `gravity-letters.scss` | Optional decorative letter motion |
164
+ | `model-picker.scss` | Native model selection styling |
165
+ | `notification.scss` | Notification link or button with a count |
166
+ | `orb.scss` | Decorative orb and grid/matrix variants |
167
+ | `otp.scss` | One-time-code input styling |
168
+ | `pill-nav.scss` | Pill-style navigation links |
169
+ | `prompt.scss` | Prompt textarea and action area |
170
+ | `rail.scss` | Table-of-contents navigation rail |
171
+ | `reactions.scss` | Native reaction selection controls |
172
+ | `response.scss` | Response content surface |
173
+ | `reveal.scss` | Content presentation surface |
174
+ | `scroll-progress.scss` | Native progress indicator styling |
175
+ | `search-results.scss` | Search result list presentation |
176
+ | `sidebar.scss` | Vertical navigation links |
177
+ | `status.scss` | Inline status indicator and label |
178
+ | `step-list.scss` | Ordered process steps and current state |
179
+ | `task-list.scss` | Native checkbox task list |
180
+ | `theme-picker.scss` | Native appearance selection controls |
181
+ | `voice-note.scss` | Container for native audio playback |
182
+ | `helpers/index.scss` | Entry point for all modular helper families |
183
+ | `helpers/color.scss` | Text, background, and border color helpers |
184
+ | `helpers/flex.scss` | Additional flex alignment, order, and basis helpers |
185
+ | `helpers/layout.scss` | Sizing, aspect ratio, overflow, and layout helpers |
186
+ | `helpers/spacing.scss` | Logical spacing helpers |
187
+ | `helpers/typography.scss` | Text alignment, wrapping, and typography helpers |
188
+ | `helpers/visibility.scss` | Responsive visibility and accessible hiding helpers |
189
+
190
+ The standalone component and helper modules can be imported individually. See the [component guide](agents/peppertino/catalog.md) and [helper reference](agents/peppertino/utilities.md) for markup, module imports, and behavior.
191
+
192
+ ### JS components (`src/js/`)
193
+
194
+ Each file is a self-contained IIFE. Import only what you need, or include `peppertino.js` for everything.
195
+
196
+ | File | Purpose |
197
+ |---|---|
198
+ | `accordion.js` | `aria-expanded`/`aria-hidden`, keyboard nav (↑ ↓ Home End), `data-allow-multiple`; `ppAccordion.get(ref)` API |
199
+ | `alert.js` | `data-alert-dismiss` wiring; `window.ppAlert.dismiss(idOrEl)` |
200
+ | `carousel.js` | ARIA wiring, IntersectionObserver sync, `ppCarousel` API |
201
+ | `header.js` | Mobile drawer, dropdown ARIA wiring for `.pp-header` |
202
+ | `modal.js` | Open/close, focus trap, focus restore, ARIA for `.pp-modal` |
203
+ | `select.js` | Keyboard nav, ARIA listbox/option for `.pp-select` |
204
+ | `switch.js` | `aria-checked` toggle, Space key, `pp:switch:change` event |
205
+ | `tabs.js` | Click + arrow key activation, ARIA tablist; `ppTabs.get(ref).activate(index)` |
206
+ | `theme.js` | `window.ppTheme.set/get/toggle`; persists to `localStorage`; `data-theme-toggle` wiring |
207
+ | `toast.js` | `window.ppToast.show({ message, title, variant, duration, position })`; auto-dismiss |
208
+ | `validation.js` | `aria-invalid` wiring, summary focus, `ppValidation` API |
209
+ | `peppertino.js` | Aggregator — imports all of the above |
210
+
211
+ The styles can be used independently of the supplied scripts. Native HTML controls provide their own behavior; button-based accordions, modal dialogs, custom selects, tabs, and other scripted controls need the supplied scripts or equivalent application code for their interaction and accessibility state. For accordions that work without JavaScript, use the native `details` and `summary` markup in the accordion guide.
212
+
213
+ ---
214
+
215
+ ## Design tokens (`base.scss`)
216
+
217
+ ### Colors — HSL channel system
218
+
219
+ All color tokens are decomposed into H/S/L channel properties so any component can form alpha tints without `rgba()`:
220
+
221
+ ```css
222
+ /* Each token ships three channel vars + a composite shorthand */
223
+ --pp-primary-h: 356;
224
+ --pp-primary-s: 99.2%;
225
+ --pp-primary-l: 46.3%;
226
+ --pp-primary: hsl(var(--pp-primary-h) var(--pp-primary-s) var(--pp-primary-l));
227
+
228
+ /* Alpha tints use the channels directly — no SCSS needed */
229
+ background: hsl(var(--pp-primary-h) var(--pp-primary-s) var(--pp-primary-l) / 0.15);
230
+ ```
231
+
232
+ Available token families: `--pp-primary`, `--pp-gradient-start`, `--pp-gradient-end`, neutral scale (`--pp-neutral-50` → `--pp-neutral-900`), semantic scales `--pp-success-*`, `--pp-warning-*`, `--pp-error-*`, `--pp-info-*` (each with 50/100/200/300/400/500/600/700/800/900 levels).
233
+
234
+ Dark mode overrides channel properties (`-l`, `-s`) rather than full hex values — single-token changes cascade everywhere.
235
+
236
+ ### Typography
237
+
238
+ ```scss
239
+ $font-sans: 'Inter', system-ui, ...
240
+ $font-mono: 'Kode Mono', ui-monospace, ...
241
+ ```
242
+
243
+ Both fonts are loaded from Google Fonts automatically via `base.scss`.
244
+
245
+ ### Spacing, radius, shadows, breakpoints
246
+
247
+ All defined as SCSS maps in `base.scss` and accessible via helper functions:
248
+
249
+ ```scss
250
+ spacing(4) // → 1rem
251
+ font-size('2xl') // → 1.5rem
252
+ radius('lg') // → 0.5rem
253
+ z('modal') // → 200
254
+ ```
255
+
256
+ ### Responsive mixins
257
+
258
+ ```scss
259
+ @include respond-to('md') { /* min-width: 768px */ }
260
+ @include respond-below('md') { /* max-width: 767px */ }
261
+ @include respond-between('sm','lg') { /* 640px – 1023px */ }
262
+ ```
263
+
264
+ Viewport breakpoints: `sm` 640px · `md` 768px · `lg` 1024px · `xl` 1280px · `2xl` 1536px · `wuxga` 1920px.
265
+
266
+ Apple device breakpoints: `iphone-se` · `iphone` · `iphone-plus` · `iphone-pro-max` · `ipad-mini` · `ipad-air` · `ipad-pro-11` · `ipad-pro-13` · `macbook-air-13` · `macbook-pro-14` · `macbook-pro-16` · `imac`
267
+
268
+ All named widths work with `respond-to`, `respond-below`, and `respond-between`. They are CSS viewport widths, not device detection: zoom, pixel density, browser chrome, orientation, and resized windows affect the width available. Design fluid layouts between breakpoints; `wuxga` describes a 1920 CSS-pixel viewport, not every 1920 × 1200 display.
269
+
270
+ ---
271
+
272
+ ## Typography utilities
273
+
274
+ ```html
275
+ <p class="font-sans font-700 text-2xl tracking-tight">Hello</p>
276
+ <p class="font-mono font-400 text-sm leading-relaxed">code prose</p>
277
+ ```
278
+
279
+ | Category | Classes |
280
+ |---|---|
281
+ | Family | `.font-sans` `.font-mono` |
282
+ | Weight | `.font-100` → `.font-900` |
283
+ | Size | `.text-xs` `.text-sm` `.text-base` `.text-lg` `.text-xl` `.text-2xl` `.text-3xl` `.text-4xl` `.text-5xl` |
284
+ | Line height | `.leading-none` `.leading-tight` `.leading-snug` `.leading-normal` `.leading-relaxed` `.leading-loose` |
285
+ | Tracking | `.tracking-tighter` `.tracking-tight` `.tracking-normal` `.tracking-wide` `.tracking-wider` `.tracking-widest` |
286
+ | Alignment | `.text-left` `.text-center` `.text-right` |
287
+ | Transform | `.uppercase` `.lowercase` `.capitalize` |
288
+ | Decoration | `.underline` `.no-underline` `.line-through` |
289
+ | Overflow | `.truncate` `.wrap-balance` |
290
+
291
+ ---
292
+
293
+ ## Components
294
+
295
+ Additional standalone modules for folder disclosure, code blocks, activity grids, step lists, counters, voice notes, status, decorative orbs, navigation, duration and OTP inputs, tasks, reactions, prompts, responses, and search results are documented in [the HTML-first component guide](agents/peppertino/catalog.md). Each `src/scss/<component>.scss` module can be imported individually and has fallback colors; application JavaScript is optional and replaceable. Live data, streaming, persistence, and other application behavior remain the consumer's responsibility.
296
+
297
+ The new `src/scss/helpers/` modules add independent color, logical spacing, flex, typography, layout, and visibility utilities. Import one family or `@use '@auriel/peppertino/src/scss/helpers'` for all of them. See [the utility reference](agents/peppertino/utilities.md) for classes, breakpoints, and accessibility notes. The helper categories were informed by [Bulma's helper documentation](https://bulma.io/documentation/helpers/).
298
+
299
+ ### Accordion
300
+
301
+ ```html
302
+ <div class="pp-accordion" data-allow-multiple>
303
+ <div class="pp-accordion__item">
304
+ <button class="pp-accordion__trigger" aria-expanded="false" aria-controls="acc-1">
305
+ Question
306
+ <svg class="pp-accordion__icon" viewBox="0 0 24 24" aria-hidden="true"><polyline points="6 9 12 15 18 9"/></svg>
307
+ </button>
308
+ <div class="pp-accordion__panel" id="acc-1" aria-hidden="true">
309
+ <p class="pp-accordion__content">Answer text.</p>
310
+ </div>
311
+ </div>
312
+ </div>
313
+ <script src="dist/accordion.js" defer></script>
314
+ ```
315
+
316
+ For an accordion that works without JavaScript, use native `<details class="pp-accordion__item">` and `<summary class="pp-accordion__trigger">` inside `.pp-accordion`; see [the accordion guide](agents/peppertino/accordion.md). Button-based triggers require the optional shim or your own state handling.
317
+
318
+ Variants: `--flush` · `--dark` · `--primary`
319
+ Attribute: `data-allow-multiple` — allow multiple panels open at once
320
+ Keyboard: `↑` / `↓` arrows, `Home`, `End`
321
+
322
+ ### Alert
323
+
324
+ ```html
325
+ <div class="pp-alert pp-alert--info" role="note">
326
+ <span class="pp-alert__icon"><i data-lucide="info" aria-hidden="true"></i></span>
327
+ <div class="pp-alert__body">
328
+ <p class="pp-alert__title">Heads up</p>
329
+ <p class="pp-alert__message">Your session expires in 10 minutes.</p>
330
+ </div>
331
+ </div>
332
+
333
+ <!-- Dismissible -->
334
+ <div class="pp-alert pp-alert--success is-dismissible" role="status" id="a1">
335
+ <span class="pp-alert__icon"><i data-lucide="circle-check" aria-hidden="true"></i></span>
336
+ <div class="pp-alert__body"><p class="pp-alert__message">Saved.</p></div>
337
+ <button class="pp-alert__dismiss" aria-label="Dismiss"
338
+ onclick="const e=document.getElementById('a1');e.classList.add('is-dismissing');setTimeout(()=>e.remove(),200);">
339
+ <i data-lucide="x" aria-hidden="true"></i>
340
+ </button>
341
+ </div>
342
+ ```
343
+
344
+ Variants: `--info` · `--success` · `--warning` · `--error` · `--primary` · `--neutral`
345
+ Modifier: `--filled` (solid background instead of tint)
346
+ States: `.is-dismissible` · `.is-dismissing` (slide-out before removal)
347
+
348
+ JS API: `window.ppAlert.dismiss(idOrEl)` — accepts an element or its `id` string.
349
+ Event: `pp:alert:dismiss` dispatched on the alert element before removal.
350
+
351
+ ### Badge
352
+
353
+ ```html
354
+ <!-- Tint variants (default) -->
355
+ <span class="pp-badge pp-badge--info">New</span>
356
+ <span class="pp-badge pp-badge--success">Active</span>
357
+ <span class="pp-badge pp-badge--warning">Review</span>
358
+ <span class="pp-badge pp-badge--error">Error</span>
359
+ <span class="pp-badge pp-badge--primary">Beta</span>
360
+
361
+ <!-- Filled (solid background) -->
362
+ <span class="pp-badge pp-badge--success pp-badge--filled">Active</span>
363
+
364
+ <!-- Sizes -->
365
+ <span class="pp-badge pp-badge--info pp-badge--sm">Small</span>
366
+ <span class="pp-badge pp-badge--info pp-badge--lg">Large</span>
367
+
368
+ <!-- Dot indicator (no text — pair with sr-only label) -->
369
+ <span class="pp-badge pp-badge--error pp-badge--dot" aria-label="3 unread"></span>
370
+ ```
371
+
372
+ Variants: `--primary` · `--success` · `--warning` · `--error` · `--info`
373
+ Modifiers: `--filled` · `--sm` · `--lg` · `--dot`
374
+
375
+ ### Button
376
+
377
+ ```html
378
+ <button class="pp-button">Primary</button>
379
+ <button class="pp-button--success">Success</button>
380
+ <button class="pp-button--warning">Warning</button>
381
+ <button class="pp-button--error">Error</button>
382
+ <button class="pp-button--dark">Dark</button>
383
+ <button class="pp-button--gradient">Gradient</button>
384
+ <button class="pp-button--ghost">Ghost</button>
385
+
386
+ <button class="pp-button--outline">Primary</button>
387
+ <button class="pp-button--outline pp-button--success">Success</button>
388
+ <button class="pp-button--outline pp-button--warning">Warning</button>
389
+ <button class="pp-button--outline pp-button--error">Error</button>
390
+ <button class="pp-button--outline pp-button--dark">Dark</button>
391
+ ```
392
+
393
+ ### Card
394
+
395
+ ```html
396
+ <div class="pp-card">...</div>
397
+ <div class="pp-card pp-card--dark">...</div>
398
+ <div class="pp-card pp-card--gradient">...</div>
399
+ <div class="pp-card pp-card--primary">...</div>
400
+ <div class="pp-card pp-card--ghost">...</div>
401
+ ```
402
+
403
+ Grid helpers: `.pp-card-grid--2` · `.pp-card-grid--3` · `.pp-card-grid--4`
404
+
405
+ ### Carousel
406
+
407
+ ```html
408
+ <div class="pp-carousel" id="my-carousel" data-label="Featured">
409
+ <div class="pp-carousel__track">
410
+ <div class="pp-carousel__slide" id="my-carousel-slide-0">...</div>
411
+ <div class="pp-carousel__slide" id="my-carousel-slide-1">...</div>
412
+ </div>
413
+ <button class="pp-carousel__prev" type="button" aria-label="Previous slide">
414
+ <svg viewBox="0 0 24 24" aria-hidden="true"><polyline points="15 18 9 12 15 6"/></svg>
415
+ </button>
416
+ <button class="pp-carousel__next" type="button" aria-label="Next slide">
417
+ <svg viewBox="0 0 24 24" aria-hidden="true"><polyline points="9 6 15 12 9 18"/></svg>
418
+ </button>
419
+ <div class="pp-carousel__dots" aria-label="Slide navigation">
420
+ <button class="pp-carousel__dot" type="button" aria-label="Go to slide 1" aria-controls="my-carousel-slide-0"></button>
421
+ <button class="pp-carousel__dot" type="button" aria-label="Go to slide 2" aria-controls="my-carousel-slide-1"></button>
422
+ </div>
423
+ <div class="pp-carousel__announcer" aria-live="polite" aria-atomic="true"></div>
424
+ </div>
425
+ <script src="dist/carousel.js" defer></script>
426
+ ```
427
+
428
+ Variants: `--peek-2` · `--peek-3` · `--dark` · `--flush`
429
+ API: `ppCarousel.get(id).goTo(n)`
430
+
431
+ ### Footer
432
+
433
+ ```html
434
+ <footer class="pp-footer" role="contentinfo">
435
+ <div class="pp-footer__top">
436
+ <div class="pp-footer__brand">
437
+ <a href="#" class="pp-footer__logo">Brand</a>
438
+ <p class="pp-footer__tagline">Tagline</p>
439
+ </div>
440
+ <div class="pp-footer__col">
441
+ <p class="pp-footer__col-title">Column</p>
442
+ <ul class="pp-footer__nav" aria-label="Column links">
443
+ <li><a href="#" class="pp-footer__nav-link">Link</a></li>
444
+ </ul>
445
+ </div>
446
+ </div>
447
+ <div class="pp-footer__bottom">
448
+ <p class="pp-footer__legal">&copy; 2026 Brand.</p>
449
+ <ul class="pp-footer__social" aria-label="Social links">
450
+ <li><a href="#" class="pp-footer__social-link" aria-label="GitHub"><i data-lucide="github"></i></a></li>
451
+ </ul>
452
+ </div>
453
+ </footer>
454
+ ```
455
+
456
+ Variants: `--dark` · `--accent`
457
+
458
+ ### Forms
459
+
460
+ #### Label
461
+
462
+ ```html
463
+ <span class="pp-label pp-label--primary">Primary</span>
464
+ <span class="pp-label pp-label--secondary pp-label--callout">Secondary callout</span>
465
+ <span class="pp-label pp-label--selectable">Selectable text</span>
466
+ <span class="pp-label-row pp-label"><i data-lucide="wifi" aria-hidden="true"></i> Wi-Fi</span>
467
+ ```
468
+
469
+ Tiers: `--primary` · `--secondary` · `--tertiary` · `--quaternary`
470
+ Scale: `--headline` · `--subheadline` · `--body` · `--callout` · `--footnote` · `--caption`
471
+
472
+ #### Fieldset
473
+
474
+ ```html
475
+ <fieldset class="pp-fieldset">
476
+ <legend>Group name</legend>
477
+ <!-- controls -->
478
+ </fieldset>
479
+ ```
480
+
481
+ Variants: `--ghost` · `--filled` · `--primary` · `--error`
482
+ Legend modifiers: `--sm` · `--lg` · `--inline`
483
+
484
+ #### Form Instructions
485
+
486
+ ```html
487
+ <!-- Place BEFORE <form> -->
488
+ <div class="pp-form-instructions" role="note" aria-label="Form instructions">
489
+ <p class="pp-form-instructions__title">Before you begin</p>
490
+ <ul class="pp-form-instructions__list">
491
+ <li class="pp-form-instructions__item">Fields marked * are required.</li>
492
+ </ul>
493
+ </div>
494
+ ```
495
+
496
+ Variants: `--neutral` · `--warning` · `--error` (use `role="alert"` for errors)
497
+
498
+ #### Text Field
499
+
500
+ ```html
501
+ <div class="pp-field">
502
+ <label class="pp-field__label" for="name">
503
+ Name
504
+ <abbr class="pp-field__required" aria-label="required" title="required"></abbr>
505
+ </label>
506
+ <input class="pp-field__input" type="text" id="name" name="name"
507
+ required aria-required="true" aria-describedby="name-hint" />
508
+ <span class="pp-field__hint" id="name-hint">Your full legal name.</span>
509
+ </div>
510
+ ```
511
+
512
+ States: `--error` · `--success` · `--warning` · `--validating`
513
+ Sizes: `--sm` · `--lg`
514
+
515
+ #### Validation
516
+
517
+ ```html
518
+ <!-- Summary (place before or at top of form) -->
519
+ <div class="pp-validation-summary" role="alert" aria-label="Form errors">
520
+ <p class="pp-validation-summary__title">Errors prevented submission</p>
521
+ <ul class="pp-validation-summary__list"></ul>
522
+ </div>
523
+
524
+ <!-- Confirmation checkbox -->
525
+ <label class="pp-confirm">
526
+ <input class="pp-confirm__input" type="checkbox" />
527
+ <span class="pp-confirm__label">I confirm this action.</span>
528
+ </label>
529
+ <button class="pp-button pp-submit--gated" type="submit">Submit</button>
530
+ ```
531
+
532
+ JS API (optional — CSS works without it):
533
+
534
+ ```js
535
+ ppValidation.setError(input, 'Message')
536
+ ppValidation.clearError(input)
537
+ ppValidation.setSuccess(input, 'Message')
538
+ ppValidation.setValidating(input)
539
+ ppValidation.setSummary([{ input, message }], summaryEl)
540
+ ```
541
+
542
+ ### Gradient text
543
+
544
+ ```html
545
+ <h1 class="pp-gradient-text">PeppertinoCSS</h1>
546
+ ```
547
+
548
+ ### Header
549
+
550
+ ```html
551
+ <header class="pp-header">
552
+ <a href="#" class="pp-header__brand">Brand</a>
553
+ <nav aria-label="Main navigation">
554
+ <ul class="pp-header__nav" role="menubar">
555
+ <li class="pp-header__nav-item" role="none">
556
+ <a href="#" class="pp-header__nav-link" role="menuitem">Link</a>
557
+ </li>
558
+ <li class="pp-header__nav-item" role="none">
559
+ <a href="#" class="pp-header__nav-link" role="menuitem" aria-haspopup="true" aria-expanded="false">Dropdown</a>
560
+ <ul class="pp-header__dropdown" role="menu">
561
+ <li role="none"><a href="#" class="pp-header__dropdown-link" role="menuitem">Item</a></li>
562
+ </ul>
563
+ </li>
564
+ </ul>
565
+ </nav>
566
+ <button class="pp-header__toggle" aria-expanded="false" aria-label="Toggle navigation">
567
+ <span></span><span></span><span></span>
568
+ </button>
569
+ </header>
570
+ <script src="dist/header.js" defer></script>
571
+ ```
572
+
573
+ ### Modal
574
+
575
+ ```html
576
+ <button data-modal-open="my-modal">Open</button>
577
+
578
+ <div id="my-modal" class="pp-modal-backdrop"
579
+ role="dialog" aria-modal="true"
580
+ aria-labelledby="my-modal-title"
581
+ aria-describedby="my-modal-desc"
582
+ aria-hidden="true">
583
+ <div class="pp-modal">
584
+ <button class="pp-modal__close" data-modal-close="my-modal" aria-label="Close">✕</button>
585
+ <p class="pp-modal__title" id="my-modal-title">Title</p>
586
+ <p class="pp-modal__description" id="my-modal-desc">Description text.</p>
587
+ <ul class="pp-modal__actions">
588
+ <li><button class="pp-modal__action">Action</button></li>
589
+ <li><button class="pp-modal__action pp-modal__action--cancel" data-modal-close="my-modal">Cancel</button></li>
590
+ </ul>
591
+ </div>
592
+ </div>
593
+ <script src="dist/modal.js" defer></script>
594
+ ```
595
+
596
+ `window.ppModal.open(id)` / `.close(id)` / `.closeAll()`
597
+
598
+ ### Select
599
+
600
+ ```html
601
+ <div class="pp-select">
602
+ <button class="pp-select__trigger" type="button" aria-label="Choose option">
603
+ <span class="pp-select__value">Choose…</span>
604
+ <span class="pp-select__chevron"></span>
605
+ </button>
606
+ <ul class="pp-select__panel" role="listbox">
607
+ <li role="option"><button class="pp-select__option" data-value="a">Option A</button></li>
608
+ <li role="option"><button class="pp-select__option" data-value="b">Option B</button></li>
609
+ </ul>
610
+ </div>
611
+ <script src="dist/select.js" defer></script>
612
+ ```
613
+
614
+ Sizes: `.pp-select--sm` · `.pp-select--lg`
615
+
616
+ ### Switch
617
+
618
+ ```html
619
+ <!-- Basic toggle -->
620
+ <button class="pp-switch" role="switch" aria-checked="false" aria-label="Enable notifications"></button>
621
+
622
+ <!-- Pre-checked -->
623
+ <button class="pp-switch" role="switch" aria-checked="true" aria-label="Dark mode"></button>
624
+
625
+ <!-- Sizes -->
626
+ <button class="pp-switch pp-switch--sm" role="switch" aria-checked="false" aria-label="Compact mode"></button>
627
+ <button class="pp-switch pp-switch--lg" role="switch" aria-checked="false" aria-label="Accessibility features"></button>
628
+ ```
629
+
630
+ Sizes: `--sm` (32×20px) · default (44×26px) · `--lg` (56×32px)
631
+ JS handles `aria-checked` toggle on click and Space key.
632
+ Event: `pp:switch:change` with `{ checked: boolean }` on the switch element.
633
+
634
+ ### Tabs
635
+
636
+ ```html
637
+ <div class="pp-tabs" role="tablist">
638
+ <button class="pp-tabs__item is-active" role="tab" aria-selected="true">Tab 1</button>
639
+ <button class="pp-tabs__item" role="tab" aria-selected="false">Tab 2</button>
640
+ </div>
641
+ <div data-tab-panel="tab1" role="tabpanel">Panel 1</div>
642
+ <div data-tab-panel="tab2" role="tabpanel" hidden>Panel 2</div>
643
+ <script src="dist/tabs.js" defer></script>
644
+ ```
645
+
646
+ Variants: default · `--outline` · `--gradient` · `--gradient-outline`
647
+ Sizes: `--sm` · `--lg`
648
+ Keyboard: `←` / `→` arrows, `Home`, `End`
649
+ JS API: `ppTabs.get(ref).activate(index)` — programmatically activate a tab by index.
650
+ Event: `pp:tabs:change` with `{ index }` on the `.pp-tabs` element.
651
+
652
+ ### Table
653
+
654
+ ```html
655
+ <table class="pp-table pp-table--cols-3">
656
+ <tbody>
657
+ <tr><td>Label</td><td>Value A</td><td>Value B</td></tr>
658
+ </tbody>
659
+ </table>
660
+ ```
661
+
662
+ Column helpers: `.pp-table--cols-1` → `.pp-table--cols-4`
663
+
664
+ ### Toast
665
+
666
+ ```js
667
+ // Show a toast (JS required)
668
+ ppToast.show({ message: 'File saved.', variant: 'success' });
669
+ ppToast.show({ message: 'Sync failed.', title: 'Error', variant: 'error', duration: 6000 });
670
+ ppToast.show({ message: 'Update available.', variant: 'info', position: 'bottom-center' });
671
+ ```
672
+
673
+ ```html
674
+ <!-- Dismiss button with data attribute (no JS needed) -->
675
+ <button data-toast-dismiss aria-label="Dismiss">✕</button>
676
+ ```
677
+
678
+ Variants: `--info` · `--success` · `--warning` · `--error` · `--neutral`
679
+ Positions: `top-right` (default) · `top-left` · `top-center` · `bottom-right` · `bottom-left` · `bottom-center`
680
+ Options: `message` · `title` · `variant` · `duration` (ms, default 4000) · `position`
681
+ Events: `pp:toast:show` / `pp:toast:dismiss` on the toast element.
682
+
683
+ ### Tooltip
684
+
685
+ ```html
686
+ <!-- CSS-only: shows on hover and :focus-within -->
687
+ <span class="pp-tooltip">
688
+ Hover me
689
+ <span class="pp-tooltip__content" role="tooltip">Helpful hint</span>
690
+ </span>
691
+
692
+ <!-- Force-show via attribute (e.g. for testing) -->
693
+ <span class="pp-tooltip">
694
+ Click me
695
+ <span class="pp-tooltip__content pp-tooltip__content--bottom" role="tooltip" data-show>
696
+ Shown below
697
+ </span>
698
+ </span>
699
+ ```
700
+
701
+ Placements: default (top) · `--bottom` · `--left` · `--right`
702
+ Shown automatically on `:hover` and `:focus-within` — no JS required.
703
+ Add `data-show` to force-display for testing.
704
+
705
+ ### Section
706
+
707
+ ```html
708
+ <section class="pp-section">
709
+ <div class="pp-section__inner">
710
+ <!-- content -->
711
+ </div>
712
+ </section>
713
+ ```
714
+
715
+ Variants: `--primary` · `--dark` · `--muted` · `--gradient`
716
+
717
+ ---
718
+
719
+ ## Utilities
720
+
721
+ Single-purpose classes — no JavaScript required. Import `utilities.scss` or use the compiled CSS.
722
+
723
+ | Group | Classes |
724
+ |---|---|
725
+ | Display | `.d-{block\|inline\|inline-block\|flex\|inline-flex\|grid\|inline-grid\|none\|contents}` |
726
+ | Visibility | `.visible` `.invisible` `.sr-only` `.not-sr-only` |
727
+ | Opacity | `.opacity-{0\|25\|50\|75\|100}` |
728
+ | Margin | `.m-*` `.mt-*` `.mb-*` `.ml-*` `.mr-*` `.mx-*` `.my-*` (keys 0–32, `auto`) |
729
+ | Padding | `.p-*` `.pt-*` `.pb-*` `.pl-*` `.pr-*` `.px-*` `.py-*` (keys 0–32) |
730
+ | Gap | `.gap-*` `.gap-x-*` `.gap-y-*` (keys 0–32) |
731
+ | Flex | direction, wrap, grow/shrink, justify-content, align-items, align-self |
732
+ | Grid | `.grid-cols-{1–6,12}` `.grid-rows-{1–4}` `.col-span-*` `.row-span-*` |
733
+ | Width | `.w-full` `.w-screen` `.w-auto` `.w-fit` `.w-min` `.w-max` `.w-half` |
734
+ | Height | `.h-full` `.h-screen` `.h-auto` `.h-fit` |
735
+ | Overflow | `.overflow-{auto\|hidden\|visible\|scroll}`, x/y variants |
736
+ | Position | `.static` `.relative` `.absolute` `.fixed` `.sticky` |
737
+ | Z-index | `.z-{below\|base\|raised\|overlay\|modal\|toast\|tooltip}` |
738
+ | Border-radius | `.rounded-{none\|sm\|base\|md\|lg\|xl\|2xl\|full}` |
739
+ | Shadow | `.shadow-{none\|sm\|md\|lg\|xl}` |
740
+ | Cursor | `.cursor-{default\|pointer\|not-allowed\|grab\|text}` |
741
+ | Responsive | `.sm-d-*` `.md-d-*` `.lg-d-*` `.xl-d-*` `.w2xl-d-*` (display only) |
742
+
743
+ ---
744
+
745
+ ## Dark mode
746
+
747
+ Add `class="dark"` to `<html>` (or any ancestor element). All component tokens flip automatically via CSS custom properties — no extra classes needed on individual components.
748
+
749
+ ```html
750
+ <html class="dark">
751
+ <!-- everything inside uses dark surface tokens -->
752
+ </html>
753
+ ```
754
+
755
+ Toggle from JS using the `ppTheme` API (requires `theme.js`):
756
+
757
+ ```js
758
+ ppTheme.set('dark'); // switch to dark mode
759
+ ppTheme.set('light'); // switch to light mode
760
+ ppTheme.toggle(); // flip current mode
761
+ ppTheme.get(); // → 'dark' | 'light'
762
+ ```
763
+
764
+ Or add `data-theme-toggle` to any button — it wires automatically:
765
+
766
+ ```html
767
+ <button data-theme-toggle aria-label="Toggle dark mode">Dark</button>
768
+ ```
769
+
770
+ The preference is persisted to `localStorage` under `pp-theme` and restored on page load. Event: `pp:theme:change` with `{ theme: 'dark' | 'light' }` dispatched on `document`.
771
+
772
+ All `--pp-*` tokens are defined on `:root` as light defaults. `dark-mode.scss` overrides them under `.dark`. The neutral scale is fully inverted (50 ↔ 900), surfaces swap, and glass/shadow values are strengthened for dark backgrounds.
773
+
774
+ ---
775
+
776
+ ## CustomEvents reference
777
+
778
+ All JS components dispatch `pp:<component>:<event>` CustomEvents that bubble. Listen at any ancestor:
779
+
780
+ | Event | Dispatched on | Detail |
781
+ |---|---|---|
782
+ | `pp:accordion:open` | `.pp-accordion` | `{ index, trigger, panel }` |
783
+ | `pp:accordion:close` | `.pp-accordion` | `{ index, trigger, panel }` |
784
+ | `pp:alert:dismiss` | `.pp-alert` | — |
785
+ | `pp:carousel:change` | `.pp-carousel` | `{ index, total, label }` |
786
+ | `pp:header:open` | `.pp-header` | — |
787
+ | `pp:header:close` | `.pp-header` | — |
788
+ | `pp:modal:open` | `.pp-modal-backdrop` | — |
789
+ | `pp:modal:close` | `.pp-modal-backdrop` | — |
790
+ | `pp:select:change` | `.pp-select` | `{ value }` |
791
+ | `pp:switch:change` | `.pp-switch` | `{ checked: boolean }` |
792
+ | `pp:tabs:change` | `.pp-tabs` | `{ index }` |
793
+ | `pp:theme:change` | `document` | `{ theme: 'dark' \| 'light' }` |
794
+ | `pp:toast:show` | `.pp-toast` | — |
795
+ | `pp:toast:dismiss` | `.pp-toast` | — |
796
+
797
+ ---
798
+
799
+ ## Changelog
800
+
801
+ See [CHANGELOG.txt](CHANGELOG.txt)
802
+
803
+ ---
804
+
805
+ ## License
806
+
807
+ MIT — see [LICENSE](LICENSE)
808
+
809
+ ---
810
+
811
+ [Codeberg](https://codeberg.org/debaditya/Peppertino)