@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
package/README.md CHANGED
@@ -1,764 +1,773 @@
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
+ | `carousel.md` | Carousel markup, API, keyboard |
97
+ | `footer.md` | Footer columns, social links |
98
+ | `forms-fieldset.md` | Fieldset & legend |
99
+ | `forms-form-instructions.md` | Pre-form instructions, hints |
100
+ | `forms-label.md` | Label tiers, scale, icon row |
101
+ | `forms-text-field.md` | Field wrapper, input, hint, validation |
102
+ | `forms-validation.md` | Summary, confirmation checkbox, `ppValidation` API |
103
+ | `gradient.md` | Gradient text |
104
+ | `header.md` | Header, nav, dropdown, mobile drawer |
105
+ | `modal.md` | Modal, actions, `ppModal` API |
106
+ | `section.md` | Section variants, scrollbar |
107
+ | `select.md` | Native select, custom dropdown |
108
+ | `switch.md` | Toggle switch, sizes, `ppSwitch` events |
109
+ | `table.md` | Table, column helpers |
110
+ | `tabs.md` | Tabs, variants, keyboard nav |
111
+ | `toast.md` | Toast positions, variants, `ppToast` API |
112
+ | `tooltip.md` | Tooltip placements, CSS-only usage |
113
+ | `typography.md` | All typography utility classes |
114
+
115
+ 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.
116
+
117
+ ---
118
+
119
+ ## What's inside
120
+
121
+ ### SCSS modules (`src/scss/`)
122
+
123
+ | File | Purpose |
124
+ |---|---|
125
+ | `reset.scss` | Opinionated modern reset |
126
+ | `base.scss` | Design tokens, CSS custom properties, helper functions, base element styles |
127
+ | `accordion.scss` | `.pp-accordion` — collapsible panels; variants: `--flush`, `--dark`, `--primary` |
128
+ | `alert.scss` | `.pp-alert` — inline feedback; variants: `--info/success/warning/error/primary/neutral`, `--filled` |
129
+ | `badge.scss` | `.pp-badge` — pill badges; variants: `--primary/success/warning/error/info`, `--filled`, sizes `--sm/lg`, `--dot` |
130
+ | `button.scss` | `.pp-button`, `.pp-button--outline`, semantic variants |
131
+ | `card.scss` | `.pp-card` and variants |
132
+ | `carousel.scss` | `.pp-carousel` — CSS scroll-snap carousel |
133
+ | `dark-mode.scss` | `.dark` overrides for all `--pp-*` tokens — applied last |
134
+ | `footer.scss` | `.pp-footer` — multi-column footer |
135
+ | `forms.scss` | Aggregator for all form partials |
136
+ | `forms/fieldset.scss` | `.pp-fieldset` + `.pp-legend` |
137
+ | `forms/form-instructions.scss` | `.pp-form-instructions`, `.pp-form-hint` |
138
+ | `forms/label.scss` | `.pp-label` — Apple HIG four-tier label system |
139
+ | `forms/text-field.scss` | `.pp-field` — labelled input/textarea with validation states |
140
+ | `forms/validation.scss` | `.pp-validation-summary`, `.pp-confirm`, `.pp-field--validate` |
141
+ | `gradient.scss` | `.pp-gradient-text` |
142
+ | `header.scss` | `.pp-header` — glassmorphism sticky header |
143
+ | `modal.scss` | `.pp-modal-backdrop` + `.pp-modal` — glassmorphic modals |
144
+ | `section.scss` | `.pp-section` — full-viewport sections + custom scrollbar |
145
+ | `select.scss` | Native `<select>` restyling + `.pp-select` custom dropdown |
146
+ | `switch.scss` | `.pp-switch` — iOS-style toggle; sizes `--sm/lg` |
147
+ | `table.scss` | `.pp-table` — clean Apple-style data tables |
148
+ | `tabs.scss` | `.pp-tabs` — pill-style tabs with icon + label |
149
+ | `toast.scss` | `.pp-toast-container` + `.pp-toast` — auto-dismiss notifications |
150
+ | `tooltip.scss` | `.pp-tooltip` — CSS-only tooltip; placements `--top/bottom/left/right` |
151
+ | `typography.scss` | Utility classes for font, size, weight, spacing |
152
+ | `utilities.scss` | Single-purpose layout/spacing/display/visibility classes |
153
+
154
+ ### JS components (`src/js/`)
155
+
156
+ Each file is a self-contained IIFE. Import only what you need, or include `peppertino.js` for everything.
157
+
158
+ | File | Purpose |
159
+ |---|---|
160
+ | `accordion.js` | `aria-expanded`/`aria-hidden`, keyboard nav (↑ ↓ Home End), `data-allow-multiple`; `ppAccordion.get(ref)` API |
161
+ | `alert.js` | `data-alert-dismiss` wiring; `window.ppAlert.dismiss(idOrEl)` |
162
+ | `carousel.js` | ARIA wiring, IntersectionObserver sync, `ppCarousel` API |
163
+ | `header.js` | Mobile drawer, dropdown ARIA wiring for `.pp-header` |
164
+ | `modal.js` | Open/close, focus trap, focus restore, ARIA for `.pp-modal` |
165
+ | `select.js` | Keyboard nav, ARIA listbox/option for `.pp-select` |
166
+ | `switch.js` | `aria-checked` toggle, Space key, `pp:switch:change` event |
167
+ | `tabs.js` | Click + arrow key activation, ARIA tablist; `ppTabs.get(ref).activate(index)` |
168
+ | `theme.js` | `window.ppTheme.set/get/toggle`; persists to `localStorage`; `data-theme-toggle` wiring |
169
+ | `toast.js` | `window.ppToast.show({ message, title, variant, duration, position })`; auto-dismiss |
170
+ | `validation.js` | `aria-invalid` wiring, summary focus, `ppValidation` API |
171
+ | `peppertino.js` | Aggregator — imports all of the above |
172
+
173
+ 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.
174
+
175
+ ---
176
+
177
+ ## Design tokens (`base.scss`)
178
+
179
+ ### Colors — HSL channel system
180
+
181
+ All color tokens are decomposed into H/S/L channel properties so any component can form alpha tints without `rgba()`:
182
+
183
+ ```css
184
+ /* Each token ships three channel vars + a composite shorthand */
185
+ --pp-primary-h: 356;
186
+ --pp-primary-s: 99.2%;
187
+ --pp-primary-l: 46.3%;
188
+ --pp-primary: hsl(var(--pp-primary-h) var(--pp-primary-s) var(--pp-primary-l));
189
+
190
+ /* Alpha tints use the channels directly — no SCSS needed */
191
+ background: hsl(var(--pp-primary-h) var(--pp-primary-s) var(--pp-primary-l) / 0.15);
192
+ ```
193
+
194
+ 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).
195
+
196
+ Dark mode overrides channel properties (`-l`, `-s`) rather than full hex values — single-token changes cascade everywhere.
197
+
198
+ ### Typography
199
+
200
+ ```scss
201
+ $font-sans: 'Inter', system-ui, ...
202
+ $font-mono: 'Kode Mono', ui-monospace, ...
203
+ ```
204
+
205
+ Both fonts are loaded from Google Fonts automatically via `base.scss`.
206
+
207
+ ### Spacing, radius, shadows, breakpoints
208
+
209
+ All defined as SCSS maps in `base.scss` and accessible via helper functions:
210
+
211
+ ```scss
212
+ spacing(4) // → 1rem
213
+ font-size('2xl') // → 1.5rem
214
+ radius('lg') // → 0.5rem
215
+ z('modal') // → 200
216
+ ```
217
+
218
+ ### Responsive mixins
219
+
220
+ ```scss
221
+ @include respond-to('md') { /* min-width: 768px */ }
222
+ @include respond-below('md') { /* max-width: 767px */ }
223
+ @include respond-between('sm','lg') { /* 640px – 1023px */ }
224
+ ```
225
+
226
+ Viewport breakpoints: `sm` 640px · `md` 768px · `lg` 1024px · `xl` 1280px · `2xl` 1536px · `wuxga` 1920px.
227
+
228
+ 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`
229
+
230
+ 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.
231
+
232
+ ---
233
+
234
+ ## Typography utilities
235
+
236
+ ```html
237
+ <p class="font-sans font-700 text-2xl tracking-tight">Hello</p>
238
+ <p class="font-mono font-400 text-sm leading-relaxed">code prose</p>
239
+ ```
240
+
241
+ | Category | Classes |
242
+ |---|---|
243
+ | Family | `.font-sans` `.font-mono` |
244
+ | Weight | `.font-100` → `.font-900` |
245
+ | Size | `.text-xs` `.text-sm` `.text-base` `.text-lg` `.text-xl` `.text-2xl` `.text-3xl` `.text-4xl` `.text-5xl` |
246
+ | Line height | `.leading-none` `.leading-tight` `.leading-snug` `.leading-normal` `.leading-relaxed` `.leading-loose` |
247
+ | Tracking | `.tracking-tighter` `.tracking-tight` `.tracking-normal` `.tracking-wide` `.tracking-wider` `.tracking-widest` |
248
+ | Alignment | `.text-left` `.text-center` `.text-right` |
249
+ | Transform | `.uppercase` `.lowercase` `.capitalize` |
250
+ | Decoration | `.underline` `.no-underline` `.line-through` |
251
+ | Overflow | `.truncate` `.wrap-balance` |
252
+
253
+ ---
254
+
255
+ ## Components
256
+
257
+ 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.
258
+
259
+ 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/).
260
+
261
+ ### Accordion
262
+
263
+ ```html
264
+ <div class="pp-accordion" data-allow-multiple>
265
+ <div class="pp-accordion__item">
266
+ <button class="pp-accordion__trigger" aria-expanded="false" aria-controls="acc-1">
267
+ Question
268
+ <svg class="pp-accordion__icon" viewBox="0 0 24 24" aria-hidden="true"><polyline points="6 9 12 15 18 9"/></svg>
269
+ </button>
270
+ <div class="pp-accordion__panel" id="acc-1" aria-hidden="true">
271
+ <p class="pp-accordion__content">Answer text.</p>
272
+ </div>
273
+ </div>
274
+ </div>
275
+ <script src="dist/accordion.js" defer></script>
276
+ ```
277
+
278
+ 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.
279
+
280
+ Variants: `--flush` · `--dark` · `--primary`
281
+ Attribute: `data-allow-multiple` — allow multiple panels open at once
282
+ Keyboard: `↑` / `↓` arrows, `Home`, `End`
283
+
284
+ ### Alert
285
+
286
+ ```html
287
+ <div class="pp-alert pp-alert--info" role="note">
288
+ <span class="pp-alert__icon"><i data-lucide="info" aria-hidden="true"></i></span>
289
+ <div class="pp-alert__body">
290
+ <p class="pp-alert__title">Heads up</p>
291
+ <p class="pp-alert__message">Your session expires in 10 minutes.</p>
292
+ </div>
293
+ </div>
294
+
295
+ <!-- Dismissible -->
296
+ <div class="pp-alert pp-alert--success is-dismissible" role="status" id="a1">
297
+ <span class="pp-alert__icon"><i data-lucide="circle-check" aria-hidden="true"></i></span>
298
+ <div class="pp-alert__body"><p class="pp-alert__message">Saved.</p></div>
299
+ <button class="pp-alert__dismiss" aria-label="Dismiss"
300
+ onclick="const e=document.getElementById('a1');e.classList.add('is-dismissing');setTimeout(()=>e.remove(),200);">
301
+ <i data-lucide="x" aria-hidden="true"></i>
302
+ </button>
303
+ </div>
304
+ ```
305
+
306
+ Variants: `--info` · `--success` · `--warning` · `--error` · `--primary` · `--neutral`
307
+ Modifier: `--filled` (solid background instead of tint)
308
+ States: `.is-dismissible` · `.is-dismissing` (slide-out before removal)
309
+
310
+ JS API: `window.ppAlert.dismiss(idOrEl)` — accepts an element or its `id` string.
311
+ Event: `pp:alert:dismiss` dispatched on the alert element before removal.
312
+
313
+ ### Badge
314
+
315
+ ```html
316
+ <!-- Tint variants (default) -->
317
+ <span class="pp-badge pp-badge--info">New</span>
318
+ <span class="pp-badge pp-badge--success">Active</span>
319
+ <span class="pp-badge pp-badge--warning">Review</span>
320
+ <span class="pp-badge pp-badge--error">Error</span>
321
+ <span class="pp-badge pp-badge--primary">Beta</span>
322
+
323
+ <!-- Filled (solid background) -->
324
+ <span class="pp-badge pp-badge--success pp-badge--filled">Active</span>
325
+
326
+ <!-- Sizes -->
327
+ <span class="pp-badge pp-badge--info pp-badge--sm">Small</span>
328
+ <span class="pp-badge pp-badge--info pp-badge--lg">Large</span>
329
+
330
+ <!-- Dot indicator (no text — pair with sr-only label) -->
331
+ <span class="pp-badge pp-badge--error pp-badge--dot" aria-label="3 unread"></span>
332
+ ```
333
+
334
+ Variants: `--primary` · `--success` · `--warning` · `--error` · `--info`
335
+ Modifiers: `--filled` · `--sm` · `--lg` · `--dot`
336
+
337
+ ### Button
338
+
339
+ ```html
340
+ <button class="pp-button">Primary</button>
341
+ <button class="pp-button--success">Success</button>
342
+ <button class="pp-button--warning">Warning</button>
343
+ <button class="pp-button--error">Error</button>
344
+ <button class="pp-button--dark">Dark</button>
345
+ <button class="pp-button--gradient">Gradient</button>
346
+ <button class="pp-button--ghost">Ghost</button>
347
+
348
+ <button class="pp-button--outline">Primary</button>
349
+ <button class="pp-button--outline pp-button--success">Success</button>
350
+ <button class="pp-button--outline pp-button--warning">Warning</button>
351
+ <button class="pp-button--outline pp-button--error">Error</button>
352
+ <button class="pp-button--outline pp-button--dark">Dark</button>
353
+ ```
354
+
355
+ ### Card
356
+
357
+ ```html
358
+ <div class="pp-card">...</div>
359
+ <div class="pp-card pp-card--dark">...</div>
360
+ <div class="pp-card pp-card--gradient">...</div>
361
+ <div class="pp-card pp-card--primary">...</div>
362
+ <div class="pp-card pp-card--ghost">...</div>
363
+ ```
364
+
365
+ Grid helpers: `.pp-card-grid--2` · `.pp-card-grid--3` · `.pp-card-grid--4`
366
+
367
+ ### Carousel
368
+
369
+ ```html
370
+ <div class="pp-carousel" id="my-carousel" data-label="Featured">
371
+ <div class="pp-carousel__track">
372
+ <div class="pp-carousel__slide" id="my-carousel-slide-0">...</div>
373
+ <div class="pp-carousel__slide" id="my-carousel-slide-1">...</div>
374
+ </div>
375
+ <button class="pp-carousel__prev" type="button" aria-label="Previous slide">
376
+ <svg viewBox="0 0 24 24" aria-hidden="true"><polyline points="15 18 9 12 15 6"/></svg>
377
+ </button>
378
+ <button class="pp-carousel__next" type="button" aria-label="Next slide">
379
+ <svg viewBox="0 0 24 24" aria-hidden="true"><polyline points="9 6 15 12 9 18"/></svg>
380
+ </button>
381
+ <div class="pp-carousel__dots" aria-label="Slide navigation">
382
+ <button class="pp-carousel__dot" type="button" aria-label="Go to slide 1" aria-controls="my-carousel-slide-0"></button>
383
+ <button class="pp-carousel__dot" type="button" aria-label="Go to slide 2" aria-controls="my-carousel-slide-1"></button>
384
+ </div>
385
+ <div class="pp-carousel__announcer" aria-live="polite" aria-atomic="true"></div>
386
+ </div>
387
+ <script src="dist/carousel.js" defer></script>
388
+ ```
389
+
390
+ Variants: `--peek-2` · `--peek-3` · `--dark` · `--flush`
391
+ API: `ppCarousel.get(id).goTo(n)`
392
+
393
+ ### Footer
394
+
395
+ ```html
396
+ <footer class="pp-footer" role="contentinfo">
397
+ <div class="pp-footer__top">
398
+ <div class="pp-footer__brand">
399
+ <a href="#" class="pp-footer__logo">Brand</a>
400
+ <p class="pp-footer__tagline">Tagline</p>
401
+ </div>
402
+ <div class="pp-footer__col">
403
+ <p class="pp-footer__col-title">Column</p>
404
+ <ul class="pp-footer__nav" aria-label="Column links">
405
+ <li><a href="#" class="pp-footer__nav-link">Link</a></li>
406
+ </ul>
407
+ </div>
408
+ </div>
409
+ <div class="pp-footer__bottom">
410
+ <p class="pp-footer__legal">&copy; 2026 Brand.</p>
411
+ <ul class="pp-footer__social" aria-label="Social links">
412
+ <li><a href="#" class="pp-footer__social-link" aria-label="GitHub"><i data-lucide="github"></i></a></li>
413
+ </ul>
414
+ </div>
415
+ </footer>
416
+ ```
417
+
418
+ Variants: `--dark` · `--accent`
419
+
420
+ ### Forms
421
+
422
+ #### Label
423
+
424
+ ```html
425
+ <span class="pp-label pp-label--primary">Primary</span>
426
+ <span class="pp-label pp-label--secondary pp-label--callout">Secondary callout</span>
427
+ <span class="pp-label pp-label--selectable">Selectable text</span>
428
+ <span class="pp-label-row pp-label"><i data-lucide="wifi" aria-hidden="true"></i> Wi-Fi</span>
429
+ ```
430
+
431
+ Tiers: `--primary` · `--secondary` · `--tertiary` · `--quaternary`
432
+ Scale: `--headline` · `--subheadline` · `--body` · `--callout` · `--footnote` · `--caption`
433
+
434
+ #### Fieldset
435
+
436
+ ```html
437
+ <fieldset class="pp-fieldset">
438
+ <legend>Group name</legend>
439
+ <!-- controls -->
440
+ </fieldset>
441
+ ```
442
+
443
+ Variants: `--ghost` · `--filled` · `--primary` · `--error`
444
+ Legend modifiers: `--sm` · `--lg` · `--inline`
445
+
446
+ #### Form Instructions
447
+
448
+ ```html
449
+ <!-- Place BEFORE <form> -->
450
+ <div class="pp-form-instructions" role="note" aria-label="Form instructions">
451
+ <p class="pp-form-instructions__title">Before you begin</p>
452
+ <ul class="pp-form-instructions__list">
453
+ <li class="pp-form-instructions__item">Fields marked * are required.</li>
454
+ </ul>
455
+ </div>
456
+ ```
457
+
458
+ Variants: `--neutral` · `--warning` · `--error` (use `role="alert"` for errors)
459
+
460
+ #### Text Field
461
+
462
+ ```html
463
+ <div class="pp-field">
464
+ <label class="pp-field__label" for="name">
465
+ Name
466
+ <abbr class="pp-field__required" aria-label="required" title="required"></abbr>
467
+ </label>
468
+ <input class="pp-field__input" type="text" id="name" name="name"
469
+ required aria-required="true" aria-describedby="name-hint" />
470
+ <span class="pp-field__hint" id="name-hint">Your full legal name.</span>
471
+ </div>
472
+ ```
473
+
474
+ States: `--error` · `--success` · `--warning` · `--validating`
475
+ Sizes: `--sm` · `--lg`
476
+
477
+ #### Validation
478
+
479
+ ```html
480
+ <!-- Summary (place before or at top of form) -->
481
+ <div class="pp-validation-summary" role="alert" aria-label="Form errors">
482
+ <p class="pp-validation-summary__title">Errors prevented submission</p>
483
+ <ul class="pp-validation-summary__list"></ul>
484
+ </div>
485
+
486
+ <!-- Confirmation checkbox -->
487
+ <label class="pp-confirm">
488
+ <input class="pp-confirm__input" type="checkbox" />
489
+ <span class="pp-confirm__label">I confirm this action.</span>
490
+ </label>
491
+ <button class="pp-button pp-submit--gated" type="submit">Submit</button>
492
+ ```
493
+
494
+ JS API (optional — CSS works without it):
495
+
496
+ ```js
497
+ ppValidation.setError(input, 'Message')
498
+ ppValidation.clearError(input)
499
+ ppValidation.setSuccess(input, 'Message')
500
+ ppValidation.setValidating(input)
501
+ ppValidation.setSummary([{ input, message }], summaryEl)
502
+ ```
503
+
504
+ ### Gradient text
505
+
506
+ ```html
507
+ <h1 class="pp-gradient-text">PeppertinoCSS</h1>
508
+ ```
509
+
510
+ ### Header
511
+
512
+ ```html
513
+ <header class="pp-header">
514
+ <a href="#" class="pp-header__brand">Brand</a>
515
+ <nav aria-label="Main navigation">
516
+ <ul class="pp-header__nav" role="menubar">
517
+ <li class="pp-header__nav-item" role="none">
518
+ <a href="#" class="pp-header__nav-link" role="menuitem">Link</a>
519
+ </li>
520
+ <li class="pp-header__nav-item" role="none">
521
+ <a href="#" class="pp-header__nav-link" role="menuitem" aria-haspopup="true" aria-expanded="false">Dropdown</a>
522
+ <ul class="pp-header__dropdown" role="menu">
523
+ <li role="none"><a href="#" class="pp-header__dropdown-link" role="menuitem">Item</a></li>
524
+ </ul>
525
+ </li>
526
+ </ul>
527
+ </nav>
528
+ <button class="pp-header__toggle" aria-expanded="false" aria-label="Toggle navigation">
529
+ <span></span><span></span><span></span>
530
+ </button>
531
+ </header>
532
+ <script src="dist/header.js" defer></script>
533
+ ```
534
+
535
+ ### Modal
536
+
537
+ ```html
538
+ <button data-modal-open="my-modal">Open</button>
539
+
540
+ <div id="my-modal" class="pp-modal-backdrop"
541
+ role="dialog" aria-modal="true"
542
+ aria-labelledby="my-modal-title"
543
+ aria-describedby="my-modal-desc"
544
+ aria-hidden="true">
545
+ <div class="pp-modal">
546
+ <button class="pp-modal__close" data-modal-close="my-modal" aria-label="Close">✕</button>
547
+ <p class="pp-modal__title" id="my-modal-title">Title</p>
548
+ <p class="pp-modal__description" id="my-modal-desc">Description text.</p>
549
+ <ul class="pp-modal__actions">
550
+ <li><button class="pp-modal__action">Action</button></li>
551
+ <li><button class="pp-modal__action pp-modal__action--cancel" data-modal-close="my-modal">Cancel</button></li>
552
+ </ul>
553
+ </div>
554
+ </div>
555
+ <script src="dist/modal.js" defer></script>
556
+ ```
557
+
558
+ `window.ppModal.open(id)` / `.close(id)` / `.closeAll()`
559
+
560
+ ### Select
561
+
562
+ ```html
563
+ <div class="pp-select">
564
+ <button class="pp-select__trigger" type="button" aria-label="Choose option">
565
+ <span class="pp-select__value">Choose…</span>
566
+ <span class="pp-select__chevron"></span>
567
+ </button>
568
+ <ul class="pp-select__panel" role="listbox">
569
+ <li role="option"><button class="pp-select__option" data-value="a">Option A</button></li>
570
+ <li role="option"><button class="pp-select__option" data-value="b">Option B</button></li>
571
+ </ul>
572
+ </div>
573
+ <script src="dist/select.js" defer></script>
574
+ ```
575
+
576
+ Sizes: `.pp-select--sm` · `.pp-select--lg`
577
+
578
+ ### Switch
579
+
580
+ ```html
581
+ <!-- Basic toggle -->
582
+ <button class="pp-switch" role="switch" aria-checked="false" aria-label="Enable notifications"></button>
583
+
584
+ <!-- Pre-checked -->
585
+ <button class="pp-switch" role="switch" aria-checked="true" aria-label="Dark mode"></button>
586
+
587
+ <!-- Sizes -->
588
+ <button class="pp-switch pp-switch--sm" role="switch" aria-checked="false" aria-label="Compact mode"></button>
589
+ <button class="pp-switch pp-switch--lg" role="switch" aria-checked="false" aria-label="Accessibility features"></button>
590
+ ```
591
+
592
+ Sizes: `--sm` (32×20px) · default (44×26px) · `--lg` (56×32px)
593
+ JS handles `aria-checked` toggle on click and Space key.
594
+ Event: `pp:switch:change` with `{ checked: boolean }` on the switch element.
595
+
596
+ ### Tabs
597
+
598
+ ```html
599
+ <div class="pp-tabs" role="tablist">
600
+ <button class="pp-tabs__item is-active" role="tab" aria-selected="true">Tab 1</button>
601
+ <button class="pp-tabs__item" role="tab" aria-selected="false">Tab 2</button>
602
+ </div>
603
+ <div data-tab-panel="tab1" role="tabpanel">Panel 1</div>
604
+ <div data-tab-panel="tab2" role="tabpanel" hidden>Panel 2</div>
605
+ <script src="dist/tabs.js" defer></script>
606
+ ```
607
+
608
+ Variants: default · `--outline` · `--gradient` · `--gradient-outline`
609
+ Sizes: `--sm` · `--lg`
610
+ Keyboard: `←` / `→` arrows, `Home`, `End`
611
+ JS API: `ppTabs.get(ref).activate(index)` — programmatically activate a tab by index.
612
+ Event: `pp:tabs:change` with `{ index }` on the `.pp-tabs` element.
613
+
614
+ ### Table
615
+
616
+ ```html
617
+ <table class="pp-table pp-table--cols-3">
618
+ <tbody>
619
+ <tr><td>Label</td><td>Value A</td><td>Value B</td></tr>
620
+ </tbody>
621
+ </table>
622
+ ```
623
+
624
+ Column helpers: `.pp-table--cols-1` → `.pp-table--cols-4`
625
+
626
+ ### Toast
627
+
628
+ ```js
629
+ // Show a toast (JS required)
630
+ ppToast.show({ message: 'File saved.', variant: 'success' });
631
+ ppToast.show({ message: 'Sync failed.', title: 'Error', variant: 'error', duration: 6000 });
632
+ ppToast.show({ message: 'Update available.', variant: 'info', position: 'bottom-center' });
633
+ ```
634
+
635
+ ```html
636
+ <!-- Dismiss button with data attribute (no JS needed) -->
637
+ <button data-toast-dismiss aria-label="Dismiss">✕</button>
638
+ ```
639
+
640
+ Variants: `--info` · `--success` · `--warning` · `--error` · `--neutral`
641
+ Positions: `top-right` (default) · `top-left` · `top-center` · `bottom-right` · `bottom-left` · `bottom-center`
642
+ Options: `message` · `title` · `variant` · `duration` (ms, default 4000) · `position`
643
+ Events: `pp:toast:show` / `pp:toast:dismiss` on the toast element.
644
+
645
+ ### Tooltip
646
+
647
+ ```html
648
+ <!-- CSS-only: shows on hover and :focus-within -->
649
+ <span class="pp-tooltip">
650
+ Hover me
651
+ <span class="pp-tooltip__content" role="tooltip">Helpful hint</span>
652
+ </span>
653
+
654
+ <!-- Force-show via attribute (e.g. for testing) -->
655
+ <span class="pp-tooltip">
656
+ Click me
657
+ <span class="pp-tooltip__content pp-tooltip__content--bottom" role="tooltip" data-show>
658
+ Shown below
659
+ </span>
660
+ </span>
661
+ ```
662
+
663
+ Placements: default (top) · `--bottom` · `--left` · `--right`
664
+ Shown automatically on `:hover` and `:focus-within` — no JS required.
665
+ Add `data-show` to force-display for testing.
666
+
667
+ ### Section
668
+
669
+ ```html
670
+ <section class="pp-section">
671
+ <div class="pp-section__inner">
672
+ <!-- content -->
673
+ </div>
674
+ </section>
675
+ ```
676
+
677
+ Variants: `--primary` · `--dark` · `--muted` · `--gradient`
678
+
679
+ ---
680
+
681
+ ## Utilities
682
+
683
+ Single-purpose classes — no JavaScript required. Import `utilities.scss` or use the compiled CSS.
684
+
685
+ | Group | Classes |
686
+ |---|---|
687
+ | Display | `.d-{block\|inline\|inline-block\|flex\|inline-flex\|grid\|inline-grid\|none\|contents}` |
688
+ | Visibility | `.visible` `.invisible` `.sr-only` `.not-sr-only` |
689
+ | Opacity | `.opacity-{0\|25\|50\|75\|100}` |
690
+ | Margin | `.m-*` `.mt-*` `.mb-*` `.ml-*` `.mr-*` `.mx-*` `.my-*` (keys 0–32, `auto`) |
691
+ | Padding | `.p-*` `.pt-*` `.pb-*` `.pl-*` `.pr-*` `.px-*` `.py-*` (keys 0–32) |
692
+ | Gap | `.gap-*` `.gap-x-*` `.gap-y-*` (keys 0–32) |
693
+ | Flex | direction, wrap, grow/shrink, justify-content, align-items, align-self |
694
+ | Grid | `.grid-cols-{1–6,12}` `.grid-rows-{1–4}` `.col-span-*` `.row-span-*` |
695
+ | Width | `.w-full` `.w-screen` `.w-auto` `.w-fit` `.w-min` `.w-max` `.w-half` |
696
+ | Height | `.h-full` `.h-screen` `.h-auto` `.h-fit` |
697
+ | Overflow | `.overflow-{auto\|hidden\|visible\|scroll}`, x/y variants |
698
+ | Position | `.static` `.relative` `.absolute` `.fixed` `.sticky` |
699
+ | Z-index | `.z-{below\|base\|raised\|overlay\|modal\|toast\|tooltip}` |
700
+ | Border-radius | `.rounded-{none\|sm\|base\|md\|lg\|xl\|2xl\|full}` |
701
+ | Shadow | `.shadow-{none\|sm\|md\|lg\|xl}` |
702
+ | Cursor | `.cursor-{default\|pointer\|not-allowed\|grab\|text}` |
703
+ | Responsive | `.sm-d-*` `.md-d-*` `.lg-d-*` `.xl-d-*` `.w2xl-d-*` (display only) |
704
+
705
+ ---
706
+
707
+ ## Dark mode
708
+
709
+ 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.
710
+
711
+ ```html
712
+ <html class="dark">
713
+ <!-- everything inside uses dark surface tokens -->
714
+ </html>
715
+ ```
716
+
717
+ Toggle from JS using the `ppTheme` API (requires `theme.js`):
718
+
719
+ ```js
720
+ ppTheme.set('dark'); // switch to dark mode
721
+ ppTheme.set('light'); // switch to light mode
722
+ ppTheme.toggle(); // flip current mode
723
+ ppTheme.get(); // → 'dark' | 'light'
724
+ ```
725
+
726
+ Or add `data-theme-toggle` to any button — it wires automatically:
727
+
728
+ ```html
729
+ <button data-theme-toggle aria-label="Toggle dark mode">Dark</button>
730
+ ```
731
+
732
+ 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`.
733
+
734
+ 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.
735
+
736
+ ---
737
+
738
+ ## CustomEvents reference
739
+
740
+ All JS components dispatch `pp:<component>:<event>` CustomEvents that bubble. Listen at any ancestor:
741
+
742
+ | Event | Dispatched on | Detail |
743
+ |---|---|---|
744
+ | `pp:accordion:open` | `.pp-accordion` | `{ index, trigger, panel }` |
745
+ | `pp:accordion:close` | `.pp-accordion` | `{ index, trigger, panel }` |
746
+ | `pp:alert:dismiss` | `.pp-alert` | — |
747
+ | `pp:carousel:change` | `.pp-carousel` | `{ index, total, label }` |
748
+ | `pp:header:open` | `.pp-header` | — |
749
+ | `pp:header:close` | `.pp-header` | — |
750
+ | `pp:modal:open` | `.pp-modal-backdrop` | — |
751
+ | `pp:modal:close` | `.pp-modal-backdrop` | — |
752
+ | `pp:select:change` | `.pp-select` | `{ value }` |
753
+ | `pp:switch:change` | `.pp-switch` | `{ checked: boolean }` |
754
+ | `pp:tabs:change` | `.pp-tabs` | `{ index }` |
755
+ | `pp:theme:change` | `document` | `{ theme: 'dark' \| 'light' }` |
756
+ | `pp:toast:show` | `.pp-toast` | — |
757
+ | `pp:toast:dismiss` | `.pp-toast` | — |
758
+
759
+ ---
760
+
761
+ ## Changelog
762
+
763
+ See [CHANGELOG.txt](CHANGELOG.txt)
764
+
765
+ ---
766
+
767
+ ## License
768
+
769
+ MIT — see [LICENSE](LICENSE)
770
+
771
+ ---
772
+
773
+ [Codeberg](https://codeberg.org/debaditya/Peppertino)