@auriel/peppertino 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/CHANGELOG.txt +242 -224
  2. package/LICENSE +21 -21
  3. package/MIGRATION.md +52 -52
  4. package/README.md +773 -764
  5. package/agents/peppertino/SKILL.md +76 -0
  6. package/agents/peppertino/accordion.md +134 -0
  7. package/agents/peppertino/alert.md +116 -0
  8. package/agents/peppertino/badge.md +74 -0
  9. package/agents/peppertino/base.md +252 -0
  10. package/agents/peppertino/button.md +65 -0
  11. package/agents/peppertino/card.md +82 -0
  12. package/agents/peppertino/carousel.md +147 -0
  13. package/agents/peppertino/catalog.md +81 -0
  14. package/agents/peppertino/dark-mode.md +152 -0
  15. package/agents/peppertino/footer.md +109 -0
  16. package/agents/peppertino/forms-fieldset.md +85 -0
  17. package/agents/peppertino/forms-form-instructions.md +94 -0
  18. package/agents/peppertino/forms-label.md +110 -0
  19. package/agents/peppertino/forms-text-field.md +134 -0
  20. package/agents/peppertino/forms-validation.md +153 -0
  21. package/agents/peppertino/gradient.md +41 -0
  22. package/agents/peppertino/header.md +105 -0
  23. package/agents/peppertino/modal.md +123 -0
  24. package/agents/peppertino/section.md +56 -0
  25. package/agents/peppertino/select.md +110 -0
  26. package/agents/peppertino/switch.md +72 -0
  27. package/agents/peppertino/table.md +69 -0
  28. package/agents/peppertino/tabs.md +115 -0
  29. package/agents/peppertino/toast.md +96 -0
  30. package/agents/peppertino/tooltip.md +111 -0
  31. package/agents/peppertino/typography.md +118 -0
  32. package/agents/peppertino/utilities.md +194 -0
  33. package/agents/skill.md +65 -0
  34. package/build.js +53 -53
  35. package/dist/accordion.js +1 -1
  36. package/dist/accordion.js.map +2 -2
  37. package/dist/alert.js.map +1 -1
  38. package/dist/carousel.js.map +1 -1
  39. package/dist/header.js.map +1 -1
  40. package/dist/main.css +2566 -1008
  41. package/dist/main.css.map +1 -1
  42. package/dist/main.min.css +1 -0
  43. package/dist/modal.js.map +1 -1
  44. package/dist/peppertino.js +1 -1
  45. package/dist/peppertino.js.map +2 -2
  46. package/dist/select.js.map +1 -1
  47. package/dist/switch.js.map +1 -1
  48. package/dist/tabs.js.map +1 -1
  49. package/dist/theme.js.map +1 -1
  50. package/dist/toast.js.map +1 -1
  51. package/dist/validation.js.map +1 -1
  52. package/icon.svg +4 -0
  53. package/index.html +2172 -2098
  54. package/package.json +28 -28
  55. package/scripts/hex-to-hsl.mjs +75 -75
  56. package/scripts/lint-bem.mjs +53 -53
  57. package/scripts/lint-colors.mjs +87 -87
  58. package/site.webmanifest +18 -0
  59. package/src/js/accordion.js +105 -103
  60. package/src/js/alert.js +28 -28
  61. package/src/js/carousel.js +153 -153
  62. package/src/js/header.js +85 -85
  63. package/src/js/modal.js +138 -138
  64. package/src/js/peppertino.js +15 -15
  65. package/src/js/select.js +101 -101
  66. package/src/js/switch.js +28 -28
  67. package/src/js/tabs.js +104 -104
  68. package/src/js/theme.js +47 -47
  69. package/src/js/toast.js +79 -79
  70. package/src/js/validation.js +132 -132
  71. package/src/scss/accordion.scss +190 -156
  72. package/src/scss/activity.scss +17 -0
  73. package/src/scss/alert.scss +203 -203
  74. package/src/scss/badge.scss +90 -90
  75. package/src/scss/base.scss +511 -506
  76. package/src/scss/button.scss +119 -119
  77. package/src/scss/card.scss +121 -121
  78. package/src/scss/carousel.scss +303 -303
  79. package/src/scss/code-block.scss +22 -0
  80. package/src/scss/counter.scss +5 -0
  81. package/src/scss/dark-mode.scss +514 -514
  82. package/src/scss/duration.scss +26 -0
  83. package/src/scss/folder.scss +27 -0
  84. package/src/scss/footer.scss +224 -224
  85. package/src/scss/forms/fieldset.scss +127 -127
  86. package/src/scss/forms/form-instructions.scss +133 -133
  87. package/src/scss/forms/label.scss +115 -115
  88. package/src/scss/forms/text-field.scss +240 -240
  89. package/src/scss/forms/validation.scss +215 -215
  90. package/src/scss/forms.scss +8 -8
  91. package/src/scss/gradient.scss +11 -11
  92. package/src/scss/gravity-letters.scss +7 -0
  93. package/src/scss/header.scss +257 -238
  94. package/src/scss/helpers/color.scss +9 -0
  95. package/src/scss/helpers/flex.scss +14 -0
  96. package/src/scss/helpers/index.scss +6 -0
  97. package/src/scss/helpers/layout.scss +14 -0
  98. package/src/scss/helpers/spacing.scss +14 -0
  99. package/src/scss/helpers/typography.scss +11 -0
  100. package/src/scss/helpers/visibility.scss +9 -0
  101. package/src/scss/main.scss +49 -24
  102. package/src/scss/modal.scss +188 -188
  103. package/src/scss/model-picker.scss +5 -0
  104. package/src/scss/notification.scss +5 -0
  105. package/src/scss/orb.scss +7 -0
  106. package/src/scss/otp.scss +5 -0
  107. package/src/scss/pill-nav.scss +10 -0
  108. package/src/scss/prompt.scss +28 -0
  109. package/src/scss/rail.scss +7 -0
  110. package/src/scss/reactions.scss +5 -0
  111. package/src/scss/reset.scss +84 -84
  112. package/src/scss/response.scss +11 -0
  113. package/src/scss/reveal.scss +5 -0
  114. package/src/scss/scroll-progress.scss +4 -0
  115. package/src/scss/search-results.scss +13 -0
  116. package/src/scss/section.scss +87 -79
  117. package/src/scss/select.scss +210 -210
  118. package/src/scss/sidebar.scss +8 -0
  119. package/src/scss/status.scss +5 -0
  120. package/src/scss/step-list.scss +13 -0
  121. package/src/scss/switch.scss +121 -121
  122. package/src/scss/table.scss +89 -89
  123. package/src/scss/tabs.scss +156 -156
  124. package/src/scss/task-list.scss +18 -0
  125. package/src/scss/theme-picker.scss +5 -0
  126. package/src/scss/toast.scss +170 -170
  127. package/src/scss/tooltip.scss +126 -126
  128. package/src/scss/typography.scss +58 -58
  129. package/src/scss/utilities.scss +243 -243
  130. package/src/scss/voice-note.scss +5 -0
@@ -0,0 +1,76 @@
1
+ ---
2
+ name: peppertino
3
+ description: PeppertinoCSS component reference. Use when writing or reviewing HTML/SCSS that uses PeppertinoCSS classes, ARIA attributes, or JS APIs. Covers all components, design tokens, breakpoints, and WCAG/ARIA requirements.
4
+ ---
5
+
6
+ # PeppertinoCSS — Agent Skill Index
7
+
8
+ This directory contains per-component reference documents for AI agents and tooling working with PeppertinoCSS. Each file covers classes, variants, ARIA requirements, and JS API for one component.
9
+
10
+ ## Index
11
+
12
+ For the additional standalone HTML-first modules, see [catalog.md](catalog.md).
13
+
14
+ | File | Covers |
15
+ |---|---|
16
+ | [accordion.md](accordion.md) | `.pp-accordion`, variants, `data-allow-multiple`, keyboard nav, `ppAccordion` API |
17
+ | [alert.md](alert.md) | `.pp-alert`, 6 variants, `--filled`, dismiss animation, `role` mapping, `ppAlert` API |
18
+ | [badge.md](badge.md) | `.pp-badge`, 5 variants, `--filled`, sizes, dot indicator |
19
+ | [base.md](base.md) | HSL design tokens, CSS custom properties, dark mode channels, breakpoints |
20
+ | [button.md](button.md) | `.pp-button` and all variants |
21
+ | [card.md](card.md) | `.pp-card`, variants, grid helpers |
22
+ | [carousel.md](carousel.md) | `.pp-carousel`, JS shim, `ppCarousel` API |
23
+ | [dark-mode.md](dark-mode.md) | `.dark` class, HSL channel overrides, `ppTheme` API |
24
+ | [footer.md](footer.md) | `.pp-footer`, columns, social links |
25
+ | [forms-fieldset.md](forms-fieldset.md) | `.pp-fieldset`, `.pp-legend` |
26
+ | [forms-form-instructions.md](forms-form-instructions.md) | `.pp-form-instructions`, `.pp-form-hint`, `.pp-form-required-note` |
27
+ | [forms-label.md](forms-label.md) | `.pp-label`, tiers, scale, `.pp-label-row` |
28
+ | [forms-text-field.md](forms-text-field.md) | `.pp-field`, input, textarea, hint, message, icon wrap |
29
+ | [forms-validation.md](forms-validation.md) | `.pp-validation-summary`, `.pp-confirm`, `ppValidation` API |
30
+ | [gradient.md](gradient.md) | `.pp-gradient-text` |
31
+ | [header.md](header.md) | `.pp-header`, nav, dropdown, mobile drawer |
32
+ | [modal.md](modal.md) | `.pp-modal-backdrop`, `.pp-modal`, `ppModal` API |
33
+ | [section.md](section.md) | `.pp-section`, variants, scrollbar |
34
+ | [select.md](select.md) | Native `<select>`, `.pp-select`, custom dropdown |
35
+ | [switch.md](switch.md) | `.pp-switch`, sizes, `aria-checked`, `pp:switch:change` event |
36
+ | [table.md](table.md) | `.pp-table`, column helpers |
37
+ | [tabs.md](tabs.md) | `.pp-tabs`, variants, panels, keyboard nav, `ppTabs` API |
38
+ | [toast.md](toast.md) | `ppToast.show()`, positions, variants, events |
39
+ | [tooltip.md](tooltip.md) | `.pp-tooltip`, 4 placements, CSS-only, ARIA |
40
+ | [typography.md](typography.md) | Font, size, weight, spacing utility classes |
41
+ | [utilities.md](utilities.md) | Display, spacing, flex, grid, position, z-index, responsive prefixes |
42
+
43
+ ## ARIA & WCAG requirements
44
+
45
+ PeppertinoCSS is built to be accessible by default, but **correct HTML usage is the developer's responsibility**. When implementing any component:
46
+
47
+ 1. **Always apply the correct ARIA roles, states, and properties** as documented in each component file. The CSS visual states are driven by ARIA attributes — missing attributes means broken accessibility, not just broken styling.
48
+
49
+ 2. **When in doubt about an ARIA rule or WCAG criterion, fetch the authoritative source** rather than guessing:
50
+ - ARIA specification: https://www.w3.org/TR/wai-aria/
51
+ - ARIA authoring practices (patterns): https://www.w3.org/WAI/ARIA/apg/patterns/
52
+ - WCAG 2.2 quick reference: https://www.w3.org/WAI/WCAG22/quickref/
53
+ - W3C Forms Tutorial: https://www.w3.org/WAI/tutorials/forms/
54
+
55
+ 3. **Minimum WCAG conformance target is AA.** This means:
56
+ - Text contrast ≥ 4.5:1 (normal text), ≥ 3:1 (large text / UI components)
57
+ - All interactive elements keyboard accessible
58
+ - All form controls have a visible, programmatically associated label
59
+ - Error messages are identified in text and associated with the offending field
60
+ - No content relies on color alone to convey meaning
61
+
62
+ 4. **Do not assume a component is accessible just because it uses the right CSS classes.** Verify:
63
+ - Required ARIA attributes are present in the HTML
64
+ - `id` / `for` associations are correct and unique on the page
65
+ - Focus order is logical
66
+ - Dynamic state changes (open/closed, selected, invalid) are reflected in ARIA attributes
67
+
68
+ 5. **Test with a screen reader** (NVDA + Chrome, VoiceOver + Safari, or JAWS + Edge) when implementing interactive components such as modals, dropdowns, carousels, and form validation.
69
+
70
+ ## Conventions
71
+
72
+ - All components use the `pp-` prefix: `.pp-button`, `.pp-badge`, `.pp-switch`, etc.
73
+ - BEM: `pp-block__element--modifier`. Combinable modifiers: `.pp-button--outline.pp-button--success`.
74
+ - JS shims are optional — CSS visual states are driven by classes and ARIA attributes that any JS can set.
75
+ - Icons use Lucide (`data-lucide="name"`), initialised with `lucide.createIcons()`.
76
+ - CDN: `https://cdn.jsdelivr.net/npm/@auriel/peppertino@latest/dist/`
@@ -0,0 +1,134 @@
1
+ # Accordion
2
+
3
+ **Source:** `src/scss/accordion.scss` · `src/js/accordion.js`
4
+
5
+ The CSS animates a single-child panel to its natural height in supporting browsers, and falls back to an instant, unclipped open state. Motion is disabled for reduced-motion preferences. The optional JS shim updates `aria-expanded` / `aria-hidden`, manages single-open vs multi-open mode, and adds arrow-key navigation for button-based accordions. For a fully functional no-JavaScript accordion, use native disclosure:
6
+
7
+ ```html
8
+ <div class="pp-accordion">
9
+ <details class="pp-accordion__item">
10
+ <summary class="pp-accordion__trigger">Question</summary>
11
+ <div class="pp-accordion__panel"><p class="pp-accordion__content">Answer</p></div>
12
+ </details>
13
+ </div>
14
+ ```
15
+
16
+ Native disclosure works without scripts; it opens immediately and has native keyboard behavior. For custom button markup, application code must synchronize the trigger's `aria-expanded` and the panel's `aria-hidden` (and `.is-open`, if used). CSS does not toggle button state itself.
17
+
18
+ ## Full structure
19
+
20
+ ```html
21
+ <div class="pp-accordion" data-allow-multiple>
22
+
23
+ <div class="pp-accordion__item">
24
+ <button class="pp-accordion__trigger" type="button"
25
+ aria-expanded="true" aria-controls="acc-panel-1">
26
+ What is PeppertinoCSS?
27
+ <svg class="pp-accordion__icon" viewBox="0 0 24 24" aria-hidden="true">
28
+ <polyline points="6 9 12 15 18 9"/>
29
+ </svg>
30
+ </button>
31
+ <div class="pp-accordion__panel is-open"
32
+ id="acc-panel-1" aria-hidden="false">
33
+ <p class="pp-accordion__content">
34
+ An Apple-inspired CSS framework with a spicy red accent.
35
+ </p>
36
+ </div>
37
+ </div>
38
+
39
+ <div class="pp-accordion__item">
40
+ <button class="pp-accordion__trigger" type="button"
41
+ aria-expanded="false" aria-controls="acc-panel-2">
42
+ Does it require JavaScript?
43
+ <svg class="pp-accordion__icon" viewBox="0 0 24 24" aria-hidden="true">
44
+ <polyline points="6 9 12 15 18 9"/>
45
+ </svg>
46
+ </button>
47
+ <div class="pp-accordion__panel"
48
+ id="acc-panel-2" aria-hidden="true">
49
+ <p class="pp-accordion__content">
50
+ No. JS adds ARIA state and keyboard navigation on top of the CSS baseline.
51
+ </p>
52
+ </div>
53
+ </div>
54
+
55
+ </div>
56
+ <script src="dist/accordion.js" defer></script>
57
+ ```
58
+
59
+ ## Parts
60
+
61
+ | Class | Description |
62
+ |---|---|
63
+ | `.pp-accordion` | Root container — `border-radius: 16px`, 1px border, card bg, `box-shadow: $shadow-sm` |
64
+ | `.pp-accordion__item` | Row wrapper — `border-bottom: 1px solid $color-border`; last child has no border |
65
+ | `.pp-accordion__trigger` | Full-width `<button>` — flex row, chevron on right; primary color + neutral-50 bg when active |
66
+ | `.pp-accordion__icon` | Inline SVG chevron (18×18) — rotates 180° when `aria-expanded="true"` |
67
+ | `.pp-accordion__panel` | Collapsible region; single-child panels animate their natural height for 200ms where supported |
68
+ | `.pp-accordion__content` | Inner text — sm, neutral-500, `line-height: 1.6` |
69
+
70
+ ## Open state
71
+
72
+ The panel opens when **either** condition is true (CSS checks both):
73
+
74
+ ```css
75
+ .pp-accordion__panel[aria-hidden='false'], /* JS-driven */
76
+ .pp-accordion__panel.is-open /* class-driven fallback */
77
+ ```
78
+
79
+ Set both when opening/closing to keep CSS and AT in sync.
80
+
81
+ ## Variants
82
+
83
+ | Class on `.pp-accordion` | Description |
84
+ |---|---|
85
+ | (none) | Default — bordered card with rounded corners |
86
+ | `.pp-accordion--flush` | No outer border, radius, or shadow; only inter-item dividers; trigger hover is transparent |
87
+ | `.pp-accordion--dark` | Fixed dark surface (`neutral-900` bg, `neutral-700` borders) — independent of `.dark` page toggle |
88
+ | `.pp-accordion--primary` | Open trigger gets `$color-primary` background, white text; open panel gets a 4% primary tint |
89
+
90
+ ## Attribute: `data-allow-multiple`
91
+
92
+ Place on `.pp-accordion`. When present the JS shim allows multiple panels to be open simultaneously. Without it, opening one panel closes all others.
93
+
94
+ ```html
95
+ <div class="pp-accordion" data-allow-multiple>…</div>
96
+ ```
97
+
98
+ ## JS API
99
+
100
+ The shim initializes existing accordions when the script runs. `window.ppAccordion.get(id)` exposes `open(index)`, `close(index)`, and `toggleAll()` for button-based items. Load the script with `defer`; dynamically added accordions need application-provided initialization. Native `<details>` items are left to the browser.
101
+
102
+ ## Keyboard
103
+
104
+ | Key | Action |
105
+ |---|---|
106
+ | `Enter` / `Space` | Toggle the focused panel open/closed |
107
+ | `↓` | Move focus to the next trigger (wraps) |
108
+ | `↑` | Move focus to the previous trigger (wraps) |
109
+ | `Home` | Move focus to the first trigger |
110
+ | `End` | Move focus to the last trigger |
111
+
112
+ Arrow keys only move focus — they do not open panels.
113
+
114
+ ## ARIA requirements
115
+
116
+ | Element | Required attributes |
117
+ |---|---|
118
+ | `.pp-accordion__trigger` | `aria-expanded="true/false"` · `aria-controls="<panel-id>"` |
119
+ | `.pp-accordion__panel` | `id` matching the trigger's `aria-controls` · `aria-hidden="true/false"` |
120
+ | `.pp-accordion__icon` | `aria-hidden="true"` (decorative) |
121
+
122
+ The accordion root has no required ARIA role beyond its native `<div>`. Do not add `role="list"` to items — they are not list items.
123
+
124
+ ## Dark mode
125
+
126
+ The default accordion (no variant) responds automatically to a `.dark` ancestor via `--pp-bg-card`, `--pp-border`, and `--pp-neutral-100` tokens. The explicit `.pp-accordion--dark` variant is fixed and does **not** change further with the page dark toggle.
127
+
128
+ ## Common mistakes
129
+
130
+ - Setting `aria-expanded` on the panel instead of the trigger — the attribute belongs on the control (`<button>`), not the controlled region.
131
+ - Omitting `aria-controls` / `id` — the JS shim falls back to `trigger.nextElementSibling`, but explicit IDs are required for correct AT association.
132
+ - Using `<a>` tags as triggers — accordion triggers must be `<button>` elements; links navigate, buttons toggle.
133
+ - Not including the chevron SVG — the icon is not injected by JS; it must be in the HTML.
134
+ - Nesting `.pp-accordion` inside another `.pp-accordion__panel` without unique IDs — `aria-controls` must reference a unique `id` per page.
@@ -0,0 +1,116 @@
1
+ # Alert
2
+
3
+ **Source:** `src/scss/alert.scss`
4
+
5
+ Inline feedback messages. CSS-only — no JS shim. Every alert enters with a 200ms slide-down animation. Dismissible alerts play a slide-up exit animation before removal. Use the correct `role` attribute for each semantic type.
6
+
7
+ ## Full structure
8
+
9
+ ```html
10
+ <!-- Non-dismissible -->
11
+ <div class="pp-alert pp-alert--info" role="note">
12
+ <span class="pp-alert__icon">
13
+ <i data-lucide="info" aria-hidden="true"></i>
14
+ </span>
15
+ <div class="pp-alert__body">
16
+ <p class="pp-alert__title">Heads up</p>
17
+ <p class="pp-alert__message">Your session expires in 10 minutes.</p>
18
+ </div>
19
+ </div>
20
+
21
+ <!-- Dismissible -->
22
+ <div class="pp-alert pp-alert--success is-dismissible" role="status" id="alert-1">
23
+ <span class="pp-alert__icon">
24
+ <i data-lucide="circle-check" aria-hidden="true"></i>
25
+ </span>
26
+ <div class="pp-alert__body">
27
+ <p class="pp-alert__title">Saved</p>
28
+ <p class="pp-alert__message">Your changes have been published.</p>
29
+ </div>
30
+ <button class="pp-alert__dismiss" type="button" aria-label="Dismiss alert"
31
+ onclick="
32
+ const el = document.getElementById('alert-1');
33
+ el.classList.add('is-dismissing');
34
+ setTimeout(() => el.remove(), 200);
35
+ ">
36
+ <i data-lucide="x" aria-hidden="true"></i>
37
+ </button>
38
+ </div>
39
+ ```
40
+
41
+ ## Parts
42
+
43
+ | Class | Description |
44
+ |---|---|
45
+ | `.pp-alert` | Root — flex row, `border-radius: 12px`, 1px border, 200ms enter animation |
46
+ | `.pp-alert__icon` | Leading icon slot — 18×18, `flex-shrink: 0`, `margin-top: 2px` |
47
+ | `.pp-alert__body` | Text container — `flex: 1` |
48
+ | `.pp-alert__title` | Semibold label line — sm size, inherits color |
49
+ | `.pp-alert__message` | Body text — regular weight, 85% opacity |
50
+ | `.pp-alert__dismiss` | Absolute-positioned close button — 24×24 circle, top-right; only present when `.is-dismissible` is on root |
51
+
52
+ ## Color variants
53
+
54
+ | Class | Background | Border | Text | Icon |
55
+ |---|---|---|---|---|
56
+ | `.pp-alert--info` | blue / 8% | blue / 30% | `#1e3a5f` | `$color-info` |
57
+ | `.pp-alert--success` | green / 8% | green / 30% | `#14532d` | `$color-success` |
58
+ | `.pp-alert--warning` | amber / 10% | amber / 35% | `#78350f` | `$color-warning` |
59
+ | `.pp-alert--error` | red / 8% | red / 30% | `#7f1d1d` | `$color-error` |
60
+ | `.pp-alert--primary` | primary / 7% | primary / 30% | `$color-primary-dark` | `$color-primary` |
61
+ | `.pp-alert--neutral` | `neutral-100` | `neutral-200` | `neutral-700` | `neutral-500` |
62
+
63
+ All soft-variant text colors meet WCAG AA (≥ 4.5:1) on their tinted backgrounds.
64
+
65
+ ## Filled modifier
66
+
67
+ Add `.pp-alert--filled` alongside any color variant for a solid background with white text.
68
+
69
+ ```html
70
+ <div class="pp-alert pp-alert--filled pp-alert--error" role="alert">
71
+ <span class="pp-alert__icon"><i data-lucide="circle-x" aria-hidden="true"></i></span>
72
+ <div class="pp-alert__body"><p class="pp-alert__message">Payment failed.</p></div>
73
+ </div>
74
+ ```
75
+
76
+ Filled variants use the raw semantic color as the background. White text on `$color-info` (#3b82f6) is 3.0:1 — use for large/bold text only, or prefer the soft variant for body text.
77
+
78
+ ## Animations
79
+
80
+ | State | Animation |
81
+ |---|---|
82
+ | On render | `pp-alert-in` — 200ms, `opacity: 0 → 1`, `translateY(-6px → 0)` |
83
+ | `.is-dismissing` | `pp-alert-out` — 180ms, fade + slide up + `max-height → 0`; **remove the element after 200ms** |
84
+
85
+ ```js
86
+ // Correct dismiss pattern
87
+ function dismiss(id) {
88
+ const el = document.getElementById(id);
89
+ el.classList.add('is-dismissing');
90
+ setTimeout(() => el.remove(), 200);
91
+ }
92
+ ```
93
+
94
+ ## `role` mapping
95
+
96
+ | Variant | Correct `role` | Notes |
97
+ |---|---|---|
98
+ | `--error` | `role="alert"` | Announced immediately by AT |
99
+ | `--success` | `role="status"` | Polite announcement |
100
+ | `--warning` | `role="note"` | Supplemental, not urgent |
101
+ | `--info` | `role="note"` | Supplemental |
102
+ | `--primary` | `role="note"` | Supplemental |
103
+ | `--neutral` | `role="note"` | Supplemental |
104
+
105
+ Never use `role="alert"` for non-error alerts — it triggers an immediate, interruptive screen reader announcement.
106
+
107
+ ## Dark mode
108
+
109
+ All soft variants are overridden under `.dark` in `dark-mode.scss` with higher-opacity tinted backgrounds and lighter text colors that maintain WCAG AA contrast on dark surfaces. Filled variants are unchanged (white text on solid color is unaffected by surface changes).
110
+
111
+ ## Common mistakes
112
+
113
+ - Missing `role` — without `role="alert"` or `role="status"`, dynamic alerts inserted into the DOM will not be announced by screen readers.
114
+ - Removing the element without `.is-dismissing` first — the exit animation never plays; the content jumps out instantly.
115
+ - Using `.pp-alert__title` without `.pp-alert__message` (or vice versa) — both are optional but the title must come before the message in source order.
116
+ - Placing `.pp-alert__dismiss` outside `.is-dismissible` — the dismiss button relies on `position: absolute` inside a `position: relative` root; without `.is-dismissible` the positioning breaks and the button overlaps content.
@@ -0,0 +1,74 @@
1
+ # Badge
2
+
3
+ **Source:** `src/scss/badge.scss`
4
+
5
+ Pill-shaped status indicators. CSS-only — no JS required. Used for statuses, counts, labels, and dot indicators.
6
+
7
+ ## Full structure
8
+
9
+ ```html
10
+ <!-- Tint variant (default) -->
11
+ <span class="pp-badge pp-badge--info">New</span>
12
+
13
+ <!-- Filled variant -->
14
+ <span class="pp-badge pp-badge--success pp-badge--filled">Active</span>
15
+
16
+ <!-- Dot indicator (no text — provide sr-only label) -->
17
+ <span class="pp-badge pp-badge--error pp-badge--dot" aria-label="3 unread notifications"></span>
18
+
19
+ <!-- In context -->
20
+ <span>Messages <span class="pp-badge pp-badge--error pp-badge--filled">3</span></span>
21
+ ```
22
+
23
+ ## Parts
24
+
25
+ | Class | Description |
26
+ |---|---|
27
+ | `.pp-badge` | Root — inline-flex, pill border-radius, xs font-size, font-weight 500 |
28
+ | `.pp-badge--dot` | Collapses to 8×8px circle; no text, no padding; pair with `aria-label` on the element |
29
+
30
+ ## Color variants
31
+
32
+ | Class | Background | Border | Text |
33
+ |---|---|---|---|
34
+ | `.pp-badge--primary` | primary / 10% | primary / 25% | `--pp-primary` |
35
+ | `.pp-badge--success` | success / 10% | success / 25% | `--pp-success` |
36
+ | `.pp-badge--warning` | warning / 10% | warning / 25% | `--pp-warning` |
37
+ | `.pp-badge--error` | error / 10% | error / 25% | `--pp-error` |
38
+ | `.pp-badge--info` | info / 10% | info / 25% | `--pp-info` |
39
+
40
+ ## Filled modifier
41
+
42
+ Add `.pp-badge--filled` alongside any color variant for a solid background with white text.
43
+
44
+ ```html
45
+ <span class="pp-badge pp-badge--primary pp-badge--filled">Beta</span>
46
+ ```
47
+
48
+ ## Size modifiers
49
+
50
+ | Class | Font size | Padding |
51
+ |---|---|---|
52
+ | `.pp-badge--sm` | xs (smaller) | 1px vertical, 6px horizontal |
53
+ | (default) | xs | 2px vertical, 8px horizontal |
54
+ | `.pp-badge--lg` | sm | 3px vertical, 10px horizontal |
55
+
56
+ ## Dot indicator
57
+
58
+ `.pp-badge--dot` ignores padding and text, rendering a fixed 8×8px circle. Used for presence indicators and unread counts.
59
+
60
+ ```html
61
+ <!-- Always provide an aria-label — dot badges have no visible text -->
62
+ <span class="pp-badge pp-badge--error pp-badge--dot" aria-label="3 unread"></span>
63
+ <span class="pp-badge pp-badge--success pp-badge--dot" aria-label="Online"></span>
64
+ ```
65
+
66
+ ## Dark mode
67
+
68
+ Tint backgrounds and borders adapt automatically under `.dark` via HSL channel tokens. No extra classes needed.
69
+
70
+ ## Common mistakes
71
+
72
+ - Missing `aria-label` on dot badges — they have no visible text, so screen readers announce nothing without it.
73
+ - Nesting block elements inside a badge — `.pp-badge` is inline-flex; put only text or a count inside.
74
+ - Using both `--sm`/`--lg` and `--dot` — size modifiers do not apply to dot badges (fixed 8×8px).
@@ -0,0 +1,252 @@
1
+ # Base — Design Tokens & Utilities
2
+
3
+ **Source:** `src/scss/base.scss`
4
+
5
+ All design tokens are defined as SCSS variables with `!default` — you can override any of them before importing PeppertinoCSS in your own SCSS. Helper functions (`spacing()`, `font-size()`, `radius()`, `z()`) are used throughout all component stylesheets.
6
+
7
+ ## Colors
8
+
9
+ ```scss
10
+ // Brand
11
+ $color-primary: #e90111 // 4.5:1 on white ✓ AA
12
+ $color-primary-light: #ff4d5a // 3.0:1 on white — use for large text or decorative only
13
+ $color-primary-dark: #a8000c // 7.0:1 on white ✓ AAA — use for error text
14
+
15
+ $color-accent: #f77f00
16
+
17
+ // Gradient
18
+ $gradient-start: #ffcf67 // gold
19
+ $gradient-end: #ea5753 // red
20
+
21
+ // Neutrals (use for text, borders, backgrounds)
22
+ $color-neutral-50: #fafafa // page background
23
+ $color-neutral-100: #f4f4f5 // muted sections
24
+ $color-neutral-200: #e4e4e7 // borders ($color-border)
25
+ $color-neutral-300: #d4d4d8 // decorative only on white (1.8:1)
26
+ $color-neutral-400: #a1a1aa // placeholder text (4.6:1 on white ✓ AA)
27
+ $color-neutral-500: #71717a // secondary text (4.6:1 on white ✓ AA)
28
+ $color-neutral-600: #52525b // hint text (7.2:1 on white ✓ AAA)
29
+ $color-neutral-700: #3f3f46 // label text
30
+ $color-neutral-800: #27272a
31
+ $color-neutral-900: #18181b // primary text (16.1:1 on white ✓ AAA)
32
+
33
+ // Semantic
34
+ $color-success: #22c55e // 2.3:1 on white — use border/icon only; text needs green-700 (#15803d, 5.9:1)
35
+ $color-warning: #f59e0b // use border/icon only; text needs amber-800 (#92400e, 7.6:1)
36
+ $color-error: #ef4444 // 3.0:1 — use border/icon only; text uses $color-primary-dark
37
+ $color-info: #3b82f6
38
+ ```
39
+
40
+ **Contrast rule:** `$color-success`, `$color-warning`, and `$color-error` do not meet WCAG AA on white backgrounds — use them only for borders and icons. For text that communicates these states, use the darker tokens listed above.
41
+
42
+ ## Typography tokens
43
+
44
+ ```scss
45
+ $font-sans: 'Inter', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif
46
+ $font-mono: 'Kode Mono', ui-monospace, 'Cascadia Code', 'Courier New', monospace
47
+
48
+ $font-size-base: 1rem // 16px
49
+ $line-height-base: 1.6
50
+ ```
51
+
52
+ ### Font size function
53
+
54
+ ```scss
55
+ // Keys: xs | sm | base | lg | xl | 2xl | 3xl | 4xl | 5xl
56
+ font-size('sm') // → 0.875rem
57
+ font-size('xl') // → 1.25rem
58
+ font-size('4xl') // → 2.25rem
59
+ ```
60
+
61
+ ### Font weight map
62
+
63
+ ```scss
64
+ // Keys: light | regular | medium | semibold | bold | black
65
+ map.get($font-weights, 'semibold') // → 600
66
+ map.get($font-weights, 'bold') // → 700
67
+ ```
68
+
69
+ ## Spacing
70
+
71
+ Multiples of 0.25rem. Use `spacing()` everywhere instead of raw `rem` values to maintain consistency.
72
+
73
+ ```scss
74
+ // Keys: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | 12 | 16 | 20 | 24 | 32
75
+ spacing(1) // → 0.25rem (4px)
76
+ spacing(2) // → 0.5rem (8px)
77
+ spacing(4) // → 1rem (16px)
78
+ spacing(6) // → 1.5rem (24px)
79
+ spacing(8) // → 2rem (32px)
80
+ spacing(16) // → 4rem (64px)
81
+ ```
82
+
83
+ ## Border radius
84
+
85
+ ```scss
86
+ // Keys: none | sm | base | md | lg | xl | 2xl | full
87
+ radius('none') // → 0
88
+ radius('sm') // → 0.125rem
89
+ radius('base') // → 0.25rem
90
+ radius('md') // → 0.375rem
91
+ radius('lg') // → 0.5rem
92
+ radius('xl') // → 0.75rem
93
+ radius('2xl') // → 1rem
94
+ radius('full') // → 9999px
95
+ ```
96
+
97
+ ## Shadows
98
+
99
+ Elevation-based. Use `$shadow-sm` for subtle lift, `$shadow-xl` for modals and popovers.
100
+
101
+ ```scss
102
+ $shadow-sm // 0 1px 2px 0 rgb(0 0 0 / 0.05)
103
+ $shadow // 0 1px 3px + 1px 2px
104
+ $shadow-md // 0 4px 6px + 2px 4px
105
+ $shadow-lg // 0 10px 15px + 4px 6px
106
+ $shadow-xl // 0 20px 25px + 8px 10px
107
+ ```
108
+
109
+ ## Z-index
110
+
111
+ ```scss
112
+ // Keys: below | base | raised | overlay | modal | toast | tooltip
113
+ z('below') // → -1
114
+ z('raised') // → 10
115
+ z('overlay') // → 100 (header)
116
+ z('modal') // → 200
117
+ z('toast') // → 300
118
+ z('tooltip') // → 400
119
+ ```
120
+
121
+ ## Transitions
122
+
123
+ ```scss
124
+ $transition-fast: 100ms ease // hover states, button active
125
+ $transition-base: 200ms ease // open/close, transforms
126
+ $transition-slow: 400ms ease // page-level transitions
127
+ ```
128
+
129
+ ## Breakpoints
130
+
131
+ ### Tailwind-compatible — use with `respond-to()`
132
+
133
+ | Key | px | Device |
134
+ |---|---|---|
135
+ | `sm` | 640px | Landscape phones |
136
+ | `md` | 768px | Tablets, iPad mini |
137
+ | `lg` | 1024px | Small laptops, iPad Pro 13" |
138
+ | `xl` | 1280px | Desktops, MacBook Air |
139
+ | `2xl` | 1536px | Wide desktops |
140
+
141
+ ### Apple device breakpoints — use with `respond-to()`, `respond-below()`, `respond-between()`, and `$mac-breakpoints`
142
+
143
+ These names represent CSS viewport widths rather than device detection. Widths vary with zoom, browser chrome, orientation, and window sizing; design fluid layouts between them. The additional `wuxga` breakpoint is 1920 CSS pixels and is available to all three mixins, independently of the physical display resolution.
144
+
145
+ | Key | px | Device |
146
+ |---|---|---|
147
+ | `iphone-se` | 375px | iPhone SE, iPhone 13 mini |
148
+ | `iphone` | 390px | iPhone 14 / 15 / 16 |
149
+ | `iphone-plus` | 430px | iPhone 14 Plus / 15 Plus |
150
+ | `iphone-pro-max` | 440px | iPhone 15 Pro Max / 16 Pro Max |
151
+ | `ipad-mini` | 768px | iPad mini 6th gen |
152
+ | `ipad-air` | 820px | iPad Air portrait |
153
+ | `ipad-pro-11` | 834px | iPad Pro 11" portrait |
154
+ | `ipad-pro-13` | 1024px | iPad Pro 13" portrait |
155
+ | `macbook-air-13` | 1280px | MacBook Air 13" |
156
+ | `macbook-pro-14` | 1512px | MacBook Pro 14" |
157
+ | `macbook-pro-16` | 1728px | MacBook Pro 16" |
158
+ | `imac` | 2560px | iMac 24" |
159
+
160
+ ### Responsive mixins
161
+
162
+ ```scss
163
+ // min-width (mobile-first)
164
+ @include respond-to('md') { } // ≥ 768px
165
+
166
+ // max-width
167
+ @include respond-below('md') { } // < 768px (767px max-width)
168
+
169
+ // range
170
+ @include respond-between('sm', 'lg') { } // 640px – 1023px
171
+ ```
172
+
173
+ ## CSS custom properties
174
+
175
+ All design tokens are exposed as CSS custom properties on `:root` so they can be overridden at runtime (dark mode, theming). The SCSS variables listed above are aliases that compile to `var(--pp-*)` references — do not use SCSS colour functions on them.
176
+
177
+ ### Full token list
178
+
179
+ ```css
180
+ :root {
181
+ /* Neutral scale */
182
+ --pp-neutral-50: #fafafa;
183
+ --pp-neutral-100: #f4f4f5;
184
+ --pp-neutral-200: #e4e4e7;
185
+ --pp-neutral-300: #d4d4d8;
186
+ --pp-neutral-400: #a1a1aa;
187
+ --pp-neutral-500: #71717a;
188
+ --pp-neutral-600: #52525b;
189
+ --pp-neutral-700: #3f3f46;
190
+ --pp-neutral-800: #27272a;
191
+ --pp-neutral-900: #18181b;
192
+
193
+ /* Surface */
194
+ --pp-surface: #ffffff;
195
+ --pp-on-surface: #18181b;
196
+ --pp-border: #e4e4e7;
197
+
198
+ /* Component backgrounds */
199
+ --pp-bg-card: #ffffff;
200
+ --pp-bg-input: #ffffff;
201
+ --pp-bg-select: #ffffff;
202
+ --pp-bg-select-panel: #ffffff;
203
+ --pp-bg-header: rgb(255 255 255 / 0.65);
204
+ --pp-bg-header-mobile: rgb(255 255 255 / 0.9);
205
+ --pp-bg-dropdown: rgb(255 255 255 / 0.85);
206
+ --pp-bg-footer: #f4f4f5;
207
+ --pp-section-muted-bg: #f4f4f5;
208
+
209
+ /* Glass */
210
+ --pp-glass-border: rgb(255 255 255 / 0.3);
211
+ --pp-glass-hover: rgb(0 0 0 / 0.05);
212
+
213
+ /* Shadows */
214
+ --pp-shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
215
+ --pp-shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.10), 0 2px 4px -2px rgb(0 0 0 / 0.10);
216
+ --pp-shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.10), 0 4px 6px -4px rgb(0 0 0 / 0.10);
217
+ --pp-shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.10), 0 8px 10px -6px rgb(0 0 0 / 0.10);
218
+ }
219
+ ```
220
+
221
+ ### Dark mode override
222
+
223
+ `dark-mode.scss` overrides all of the above under `.dark`. See [dark-mode.md](dark-mode.md) for the complete token flip table and JS toggle pattern.
224
+
225
+ The key principle: component SCSS never hard-codes `#fff` or `#18181b` — it always goes through a CSS var. This means adding `.dark` to any ancestor is sufficient to re-theme everything inside it.
226
+
227
+ ### SCSS → CSS var alias pattern
228
+
229
+ ```scss
230
+ // In base.scss
231
+ $bg-card: var(--pp-bg-card);
232
+ $on-surface: var(--pp-on-surface);
233
+ $color-border: var(--pp-border);
234
+ $color-neutral-100: var(--pp-neutral-100);
235
+ // etc.
236
+
237
+ // In card.scss — compiles to the var() reference, not a literal colour
238
+ .pp-card {
239
+ background: $bg-card; // → background: var(--pp-bg-card)
240
+ }
241
+ ```
242
+
243
+ **Never** pass a `$variable` alias to SCSS colour functions (`lighten()`, `darken()`, `rgba()`) — those resolve at compile time when the value is still a string. Use `rgb()` with a separate `--pp-*` token, or create a new token if you need a tint.
244
+
245
+ ## Base element styles
246
+
247
+ `base.scss` sets default styles on `body`, `h1`–`h6`, `code`, and `pre`:
248
+
249
+ - `body`: `font-family: $font-sans`, `font-size: 1rem`, `line-height: 1.6`
250
+ - `h1`–`h6`: bold, `line-height: 1.25`; sizes from `font-size('5xl')` (h1) down to `font-size('lg')` (h6)
251
+ - `code`/`pre`: `font-family: $font-mono`, `font-size: 0.875rem`
252
+ - `pre`: `overflow-x: auto`, `padding: 1rem`, neutral-100 background, md radius