@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,65 @@
1
+ # Button
2
+
3
+ **Source:** `src/scss/button.scss` · No JS required.
4
+
5
+ Buttons are pill-shaped (980px radius), Apple body tracking (`-0.022em`), 17px font size. The base class is `.pp-button`. Variants are BEM modifiers — combine `.pp-button--outline` with a color modifier for outline+color combinations.
6
+
7
+ ## Filled variants
8
+
9
+ ```html
10
+ <button class="pp-button">Primary</button>
11
+ <button class="pp-button--success">Success</button>
12
+ <button class="pp-button--warning">Warning</button>
13
+ <button class="pp-button--error">Error</button>
14
+ <button class="pp-button--dark">Dark</button>
15
+ <button class="pp-button--gradient">Gradient</button>
16
+ <button class="pp-button--ghost">Ghost</button>
17
+ ```
18
+
19
+ ## Outline variants
20
+
21
+ Outline variants use combinable modifiers — apply `.pp-button--outline` together with a color modifier:
22
+
23
+ ```html
24
+ <button class="pp-button--outline">Primary outline</button>
25
+ <button class="pp-button--outline pp-button--success">Success outline</button>
26
+ <button class="pp-button--outline pp-button--warning">Warning outline</button>
27
+ <button class="pp-button--outline pp-button--error">Error outline</button>
28
+ <button class="pp-button--outline pp-button--dark">Dark outline</button>
29
+ ```
30
+
31
+ ## Class reference
32
+
33
+ | Class | Background | Text | Use for |
34
+ |---|---|---|---|
35
+ | `.pp-button` | `$color-primary` | white | Primary CTA |
36
+ | `.pp-button--outline` | transparent | `$color-primary` | Secondary action |
37
+ | `.pp-button--success` | `#16a34a` | white | Confirm, save |
38
+ | `.pp-button--warning` | `#d97706` | white | Caution actions |
39
+ | `.pp-button--error` | `$color-error` | white | Destructive actions |
40
+ | `.pp-button--dark` | `$color-neutral-900` | white | Dark surface contexts |
41
+ | `.pp-button--gradient` | gold→red gradient | white | Hero / promotional |
42
+ | `.pp-button--ghost` | transparent | surface | Tertiary, toolbar |
43
+ | `.pp-button--outline + color modifier` | transparent | variant color | Secondary destructive etc. |
44
+
45
+ ## Combinable outline rule
46
+
47
+ `.pp-button--outline.pp-button--success` (two modifier classes on one element) overrides the outline base with success-specific border/text color and hover. This works for `--success`, `--warning`, `--error`, and `--dark`.
48
+
49
+ Do **not** combine `.pp-button--outline` with `.pp-button--gradient` or `.pp-button--ghost` — those variants handle their own state internally.
50
+
51
+ ## ARIA & accessibility
52
+
53
+ - Use `<button>` elements, not `<a>` styled as buttons, unless navigating to a URL.
54
+ - If using `<a>`, add `role="button"` and handle keyboard `Enter`/`Space`.
55
+ - Always provide a meaningful text label or `aria-label` — icon-only buttons must have `aria-label`.
56
+ - Disabled state: add `disabled` attribute (not just `opacity`) so the button is removed from tab order.
57
+ - Loading state: add `aria-busy="true"` and `aria-label="Loading…"` while async work runs.
58
+ - Destructive actions should be confirmed — see [forms-validation.md](forms-validation.md) for the confirmation checkbox pattern.
59
+
60
+ ## Common mistakes
61
+
62
+ - Do not stack two independent modifier variants (e.g. `.pp-button--success.pp-button--error`) — pick one semantic color per button.
63
+ - Do not use `<div>` or `<span>` for buttons; they are not keyboard accessible by default.
64
+ - `.pp-button--ghost` on a dark background needs a custom `color` override — its default text color is `$color-on-surface` (dark).
65
+ - `.pp-button--gradient` reverses the gradient direction on `:hover` — do not add a custom `background` that overrides this.
@@ -0,0 +1,82 @@
1
+ # Card
2
+
3
+ **Source:** `src/scss/card.scss` · No JS required.
4
+
5
+ Cards are white-background containers with 16px radius, `$shadow-md`, and a subtle lift on hover. They use flex-column layout so the footer always sticks to the bottom regardless of content height.
6
+
7
+ ## Full structure
8
+
9
+ ```html
10
+ <div class="pp-card">
11
+ <p class="pp-card__eyebrow">Category</p>
12
+ <p class="pp-card__title">Card title</p>
13
+ <p class="pp-card__body">Supporting description text that explains the card content in more detail.</p>
14
+ <div class="pp-card__footer">
15
+ <button class="button">Learn more</button>
16
+ </div>
17
+ </div>
18
+ ```
19
+
20
+ ## With media
21
+
22
+ ```html
23
+ <div class="pp-card">
24
+ <img class="pp-card__media" src="photo.jpg" alt="Descriptive alt text" />
25
+ <p class="pp-card__eyebrow">Feature</p>
26
+ <p class="pp-card__title">Media card</p>
27
+ <p class="pp-card__body">Image bleeds edge-to-edge above the content.</p>
28
+ </div>
29
+ ```
30
+
31
+ `.pp-card__media` uses `aspect-ratio: 16/9`, `object-fit: cover`, and negative margins to bleed to the card edges.
32
+
33
+ ## Parts
34
+
35
+ | Class | Element | Typography | Color |
36
+ |---|---|---|---|
37
+ | `.pp-card__eyebrow` | `<p>` | xs, semibold, 0.08em tracking, uppercase | `$color-primary` |
38
+ | `.pp-card__title` | `<p>` | xl, bold, line-height 1.25 | `$color-neutral-900` |
39
+ | `.pp-card__body` | `<p>` | sm, regular, line-height 1.6 | `$color-neutral-500` |
40
+ | `.pp-card__footer` | `<div>` | — flex row, gap 0.75rem, top border | `$color-border` |
41
+ | `.pp-card__media` | `<img>/<video>` | 16:9, cover | neutral-100 background |
42
+
43
+ ## Variants
44
+
45
+ | Class | Surface | Eyebrow | Title | Body |
46
+ |---|---|---|---|---|
47
+ | (none) | white | primary | neutral-900 | neutral-500 |
48
+ | `.pp-card--primary` | `$color-primary` | white 60% | white | white 75% |
49
+ | `.pp-card--dark` | `neutral-900` | primary-light | white | neutral-400 |
50
+ | `.pp-card--gradient` | gold→red | white 70% | white | white 80% |
51
+ | `.pp-card--ghost` | transparent | — | — | — fills white on hover |
52
+
53
+ ## Grid
54
+
55
+ ```html
56
+ <div class="pp-card-grid pp-card-grid--3">
57
+ <div class="pp-card">...</div>
58
+ <div class="pp-card">...</div>
59
+ <div class="pp-card">...</div>
60
+ </div>
61
+ ```
62
+
63
+ All grid variants collapse to a single column below 768px.
64
+
65
+ | Class | Desktop columns |
66
+ |---|---|
67
+ | `.pp-card-grid--2` | 2 |
68
+ | `.pp-card-grid--3` | 3 |
69
+ | `.pp-card-grid--4` | 4 |
70
+
71
+ ## ARIA & accessibility
72
+
73
+ - Cards are not interactive by default — do not add `role="button"` to a card unless the entire card is clickable.
74
+ - If the whole card is a link, wrap content in `<a>` and ensure the link text (or `aria-label`) describes the destination, not just "Read more".
75
+ - `<img>` inside `.pp-card__media` must have descriptive `alt` text; use `alt=""` only if the image is purely decorative and the card title already describes it.
76
+ - Do not put interactive elements (buttons, links) inside a card that is itself wrapped in an `<a>` — nested interactive elements break keyboard navigation.
77
+
78
+ ## Common mistakes
79
+
80
+ - `.pp-card__footer` uses `margin-top: auto` to push to the bottom — it only works if the parent `.pp-card` has `min-height` or contains variable-height siblings. In equal-height grids this is automatic.
81
+ - `.pp-card__media` applies negative margins to bleed — do not add `overflow: hidden` to `.pp-card` or the bleed will be clipped.
82
+ - On `.pp-card--primary` and `--gradient`, the eyebrow color is overridden to white variants — do not set `color` on `.pp-card__eyebrow` directly inside these variants.
@@ -0,0 +1,147 @@
1
+ # Carousel
2
+
3
+ **Source:** `src/scss/carousel.scss` · `src/js/carousel.js`
4
+
5
+ CSS scroll-snap carousel. All motion is handled by `scroll-snap-type: x mandatory` on `.pp-carousel__track` — no JS is needed for scrolling. The JS shim wires ARIA roles, syncs dots/buttons to the CSS scroll position via `IntersectionObserver`, and exposes `ppCarousel`.
6
+
7
+ ## Full structure
8
+
9
+ ```html
10
+ <div class="pp-carousel" id="my-carousel" data-label="Featured products">
11
+
12
+ <div class="pp-carousel__track">
13
+
14
+ <div class="pp-carousel__slide" id="my-carousel-slide-0">
15
+ <img class="pp-carousel__media" src="slide1.jpg" alt="Product A on white background" />
16
+ <div class="pp-carousel__caption">
17
+ <p class="pp-carousel__caption-title">Product A</p>
18
+ <p class="pp-carousel__caption-body">Available in three finishes.</p>
19
+ </div>
20
+ </div>
21
+
22
+ <div class="pp-carousel__slide" id="my-carousel-slide-1">
23
+ <img class="pp-carousel__media" src="slide2.jpg" alt="Product B on white background" />
24
+ <div class="pp-carousel__caption">
25
+ <p class="pp-carousel__caption-title">Product B</p>
26
+ <p class="pp-carousel__caption-body">New for 2026.</p>
27
+ </div>
28
+ </div>
29
+
30
+ </div>
31
+
32
+ <button class="pp-carousel__prev" type="button" aria-label="Previous slide">
33
+ <svg viewBox="0 0 24 24" aria-hidden="true">
34
+ <polyline points="15 18 9 12 15 6"/>
35
+ </svg>
36
+ </button>
37
+ <button class="pp-carousel__next" type="button" aria-label="Next slide">
38
+ <svg viewBox="0 0 24 24" aria-hidden="true">
39
+ <polyline points="9 6 15 12 9 18"/>
40
+ </svg>
41
+ </button>
42
+
43
+ <div class="pp-carousel__dots" aria-label="Slide navigation">
44
+ <button class="pp-carousel__dot" type="button"
45
+ aria-label="Go to slide 1"
46
+ aria-controls="my-carousel-slide-0"></button>
47
+ <button class="pp-carousel__dot" type="button"
48
+ aria-label="Go to slide 2"
49
+ aria-controls="my-carousel-slide-1"></button>
50
+ </div>
51
+
52
+ <div class="pp-carousel__announcer" aria-live="polite" aria-atomic="true"></div>
53
+
54
+ </div>
55
+ <script src="dist/carousel.js" defer></script>
56
+ ```
57
+
58
+ ## Parts
59
+
60
+ | Class | Description |
61
+ |---|---|
62
+ | `.pp-carousel` | Root — `position: relative; overflow: hidden; border-radius: 16px` |
63
+ | `.pp-carousel__track` | Scrollable flex row — `scroll-snap-type: x mandatory`, hides scrollbar |
64
+ | `.pp-carousel__slide` | Snap target — `flex: 0 0 100%` by default; must have unique `id` |
65
+ | `.pp-carousel__media` | Full-bleed image — `object-fit: cover`, `width: 100%` |
66
+ | `.pp-carousel__caption` | Overlay at slide bottom — gradient scrim, white text |
67
+ | `.pp-carousel__caption-title` | xl semibold |
68
+ | `.pp-carousel__caption-body` | sm, white 75% |
69
+ | `.pp-carousel__prev` / `.pp-carousel__next` | Absolute-positioned pill controls |
70
+ | `.pp-carousel__dots` | Container for dot buttons — plain `<div>`, no list role |
71
+ | `.pp-carousel__dot` | Individual navigation button — `aria-controls` must point to slide `id` |
72
+ | `.pp-carousel__announcer` | Visually-hidden live region — JS writes current slide label here |
73
+ | `.pp-carousel__autoplay` | Optional play/pause toggle button |
74
+
75
+ ## Variants
76
+
77
+ | Class on `.pp-carousel` | Slide width | Description |
78
+ |---|---|---|
79
+ | (none) | 100% | Full-width, one slide at a time |
80
+ | `.pp-carousel--peek-2` | 85% | Next slide peeks through on the right |
81
+ | `.pp-carousel--peek-3` | 72% | More of the next slide visible |
82
+ | `.pp-carousel--dark` | — | Dark controls and dots |
83
+ | `.pp-carousel--flush` | — | No border-radius on root, track, or caption |
84
+
85
+ On mobile (< 768px) peek variants collapse to 92% width.
86
+
87
+ ## Autoplay toggle
88
+
89
+ ```html
90
+ <button class="pp-carousel__autoplay" type="button"
91
+ aria-label="Pause autoplay" aria-pressed="true">
92
+ <svg class="pp-carousel__autoplay-icon--pause"><!-- pause icon --></svg>
93
+ <svg class="pp-carousel__autoplay-icon--play"><!-- play icon --></svg>
94
+ </button>
95
+ ```
96
+
97
+ Add `pp-carousel--playing` or `pp-carousel--paused` to the root to swap icons via CSS. The button fires a `pp-carousel:autoplay` custom event. **Autoplay scheduling is the developer's responsibility** — the shim only manages UI state.
98
+
99
+ Per WCAG 2.2.2, any auto-playing content that lasts more than 5 seconds must have a pause mechanism. `.pp-carousel__autoplay` is that mechanism.
100
+
101
+ ## How JS sync works
102
+
103
+ 1. `IntersectionObserver` watches all slides against the track as the viewport.
104
+ 2. When a slide reaches 50% visibility it is considered "current".
105
+ 3. `syncUI()` updates `aria-hidden` on all slides, `is-active` / `aria-current` on dots, and `disabled` / `aria-disabled` on prev/next buttons.
106
+ 4. `requestAnimationFrame` clears then writes the current slide label to `.pp-carousel__announcer` — the brief gap flushes the previous aria-live announcement.
107
+
108
+ ## JS API — `ppCarousel`
109
+
110
+ ```js
111
+ const c = ppCarousel.get('my-carousel'); // by id string
112
+ const c = ppCarousel.get(element); // by DOM element
113
+
114
+ c.goTo(1); // scroll to slide index 1 (0-based)
115
+ c.current(); // returns current index
116
+ c.total; // total slide count
117
+
118
+ ppCarousel.instances; // object of all instances keyed by id
119
+ ```
120
+
121
+ ## Keyboard
122
+
123
+ | Key | Context | Action |
124
+ |---|---|---|
125
+ | `←` / `→` | Focused track or dot | Previous / next slide |
126
+ | `Home` | Focused track or dot | First slide |
127
+ | `End` | Focused track or dot | Last slide |
128
+ | `↑` / `↓` | Focused dot | Previous / next slide (same as ← / →) |
129
+
130
+ ## ARIA requirements
131
+
132
+ | Element | Required |
133
+ |---|---|
134
+ | `.pp-carousel` root | `role="region"` + `aria-roledescription="carousel"` + `aria-label` (set by JS from `data-label` or existing `aria-label`) |
135
+ | `.pp-carousel__track` | `aria-live="off"` (announcements go through `.pp-carousel__announcer` instead) |
136
+ | `.pp-carousel__slide` | `role="group"` + `aria-roledescription="slide"` + unique `id` + `aria-hidden="true/false"` |
137
+ | `.pp-carousel__dot` | `aria-label="Go to slide N"` + `aria-controls` → slide `id` + `aria-current="true/false"` |
138
+ | `.pp-carousel__prev` / `.pp-carousel__next` | `aria-label` + `aria-disabled="true/false"` |
139
+ | `.pp-carousel__announcer` | `aria-live="polite"` + `aria-atomic="true"` |
140
+
141
+ ## Common mistakes
142
+
143
+ - Omitting `id` attributes on slides — `aria-controls` on dot buttons will not resolve, and `IntersectionObserver`-based slide detection relies on element identity.
144
+ - Using `<ol>/<li>` wrappers for dots — `role="listitem"` children inside `role="tablist"` (or any role the dots inherit) creates invalid ownership; dots must be plain `<button>` elements.
145
+ - Adding `role="tablist"` to the dots container — dots are not tabs; the `tablist → tab` ownership requires a direct parent-child relationship broken by `<li>` wrappers.
146
+ - Not providing `data-label` or `aria-label` on the root — the JS fallback is "Carousel N" which is not descriptive for AT users.
147
+ - Using the carousel for a single slide — no navigation needed; use a standard image or hero section instead.
@@ -0,0 +1,81 @@
1
+ # Additional HTML-first components
2
+
3
+ These original Peppertino patterns cover component types surveyed in [Rare UI's catalog](https://www.rareui.com/components). Each is a separate `src/scss/<name>.scss` module with fallback colors. Import a module by itself or use `main.scss`; no JavaScript or other component stylesheet is required. Peppertino's `--pp-*` tokens override the fallbacks when available. HTML examples below require unique IDs where indicated. Native HTML provides the interactions described; applications own any data loading, persistence, submission, or updating.
4
+
5
+ ## Display
6
+
7
+ ```html
8
+ <details class="pp-folder">
9
+ <summary class="pp-folder__header">Project files</summary>
10
+ <div class="pp-folder__body"><a href="/notes">Notes</a></div>
11
+ </details>
12
+
13
+ <figure class="pp-code-block">
14
+ <figcaption class="pp-code-block__header">example.css</figcaption>
15
+ <pre><code>color: red;</code></pre>
16
+ </figure>
17
+
18
+ <figure class="pp-activity">
19
+ <figcaption>Contribution activity: 3 contributions this week</figcaption>
20
+ <div class="pp-activity__grid" aria-hidden="true">
21
+ <span class="pp-activity__day" data-level="0"></span>
22
+ <span class="pp-activity__day" data-level="3"></span>
23
+ </div>
24
+ </figure>
25
+
26
+ <ol class="pp-step-list" aria-label="Setup progress">
27
+ <li>Account</li><li aria-current="step">Preferences</li><li>Finish</li>
28
+ </ol>
29
+ <output class="pp-counter" aria-label="42 items">42</output>
30
+ <span class="pp-gravity-letters" aria-label="Hi"><span class="pp-gravity-letters__letter" aria-hidden="true">H</span><span class="pp-gravity-letters__letter" aria-hidden="true">i</span></span>
31
+ <div class="pp-voice-note"><span>Voice note</span><audio controls src="note.mp3">Audio playback is unavailable. <a href="note.mp3">Download the recording</a>.</audio></div>
32
+ ```
33
+
34
+ The activity grid is decorative; provide a useful text summary or accessible data table. The step list is a static indicator; navigation or playback is application-owned. The counter displays its supplied value; interpolation is optional application code. For a no-JavaScript FAQ, use the folder's native `details` and `summary` markup for each question. Letter effects retain an accessible label and respect reduced-motion preferences.
35
+
36
+ ## Status and visual treatments
37
+
38
+ ```html
39
+ <span class="pp-status" role="status"><span class="pp-status__indicator" aria-hidden="true"></span>Working</span>
40
+ <div class="pp-orb" aria-hidden="true"></div>
41
+ <div class="pp-orb pp-orb--grid" aria-hidden="true"></div>
42
+ <div class="pp-orb pp-orb--matrix" aria-hidden="true"></div>
43
+ <div class="pp-reveal"><p>Content remains available without animation.</p></div>
44
+ ```
45
+
46
+ Orbs are decorative. `--pp-orb-size` controls their size. The reveal treatment deliberately keeps content visible by default; animation can be added by the application with reduced-motion support.
47
+
48
+ ## Navigation
49
+
50
+ ```html
51
+ <nav class="pp-sidebar" aria-label="Main"><a href="/" aria-current="page">Home</a><a href="/settings">Settings</a></nav>
52
+ <nav class="pp-rail" aria-label="On this page"><ol><li><a href="#overview">Overview</a></li><li><a href="#details">Details</a></li></ol></nav>
53
+ <nav class="pp-pill-nav" aria-label="Views"><a href="/all" aria-current="page">All</a><a href="/saved">Saved</a></nav>
54
+ <label for="reading">Reading progress</label><progress class="pp-scroll-progress" id="reading" value="0" max="100">0%</progress>
55
+ ```
56
+
57
+ The sidebar supports ordinary links with pointer, touch and keyboard; applications may add bounce, hook or proximity effects without hiding navigation from other inputs. Update the progress element's `value` (and fallback text if desired) using application code; omit `value` for indeterminate progress. A static progress value is not automatically tied to scroll.
58
+
59
+ ## Inputs and feedback
60
+
61
+ ```html
62
+ <fieldset class="pp-duration"><legend>Duration</legend><label>Hours <input type="number" name="hours" min="0" value="0"></label><label>Minutes <input type="number" name="minutes" min="0" max="59" value="0"></label></fieldset>
63
+ <label for="otp">Verification code</label><input class="pp-otp" id="otp" name="code" inputmode="numeric" autocomplete="one-time-code" pattern="[0-9]*">
64
+ <fieldset class="pp-theme-picker"><legend>Appearance</legend><label><input type="radio" name="theme" value="system" checked> System</label><label><input type="radio" name="theme" value="light"> Light</label><label><input type="radio" name="theme" value="dark"> Dark</label></fieldset>
65
+ <ul class="pp-task-list"><li><label><input type="checkbox" name="task" value="draft"><span>Write draft</span></label></li></ul>
66
+ <fieldset class="pp-reactions"><legend>Reaction</legend><label><input type="radio" name="reaction" value="like"> 👍 Like</label><label><input type="radio" name="reaction" value="love"> ❤️ Love</label></fieldset>
67
+ <a class="pp-notification" href="/notifications" aria-label="Notifications, 3 unread">🔔<span class="pp-notification__count" aria-hidden="true">3</span></a>
68
+ ```
69
+
70
+ The duration fields use native constraint validation. Theme radios record a selection but do not change or persist a theme without application code. Tasks and reactions are native controls; submit or persist their values as needed. Use a normal labelled `type="password"` field for password entry, and the existing error button variant plus a server-side confirmation flow for deletion. A reveal-password toggle or client-side confirmation requires application behavior; don't present a dead button as a working control.
71
+
72
+ ## AI and search
73
+
74
+ ```html
75
+ <label for="model">Model</label><select class="pp-model-picker" id="model" name="model"><option>Default</option><option>Alternative</option></select>
76
+ <form class="pp-prompt" action="/prompt" method="post"><label for="prompt">Your request</label><textarea id="prompt" name="prompt" required></textarea><div class="pp-prompt__actions"><span>Describe what you need</span><button type="submit">Send</button></div></form>
77
+ <article class="pp-response" aria-label="Response"><p>Response content goes here.</p></article>
78
+ <section class="pp-search-results" aria-label="Search results"><ol><li><a href="/result">Result title</a><p>Summary of the result.</p></li></ol></section>
79
+ ```
80
+
81
+ Use native form submissions when an endpoint is available. Streaming, model selection effects, search retrieval, and live announcements are application responsibilities. Do not put a rapidly streaming response in an assertive live region; announce completion or concise status separately. Never place secrets in client-side markup.
@@ -0,0 +1,152 @@
1
+ # Dark Mode
2
+
3
+ **Source:** `src/scss/dark-mode.scss` · `src/scss/base.scss`
4
+
5
+ Class-based dark mode system. Toggle by adding `.dark` to `<html>` or any ancestor element. Never `@media (prefers-color-scheme: dark)` — PeppertinoCSS uses an explicit class so the user's browser preference does not override an in-app toggle.
6
+
7
+ ## Activation
8
+
9
+ ```html
10
+ <!-- Page-wide dark mode -->
11
+ <html class="dark">
12
+
13
+ <!-- Scoped dark pane (independent of global toggle) -->
14
+ <div class="dark" style="background: #18181b; padding: 24px; border-radius: 16px;">
15
+ <!-- all children render in dark mode regardless of <html> class -->
16
+ </div>
17
+ ```
18
+
19
+ ## JS toggle (recommended pattern)
20
+
21
+ ```js
22
+ (function () {
23
+ const html = document.documentElement;
24
+ const btn = document.getElementById('dark-toggle');
25
+ const sun = document.getElementById('dark-icon-sun');
26
+ const moon = document.getElementById('dark-icon-moon');
27
+
28
+ function apply(dark) {
29
+ html.classList.toggle('dark', dark);
30
+ sun.style.display = dark ? '' : 'none';
31
+ moon.style.display = dark ? 'none' : '';
32
+ localStorage.setItem('pp-dark', dark ? '1' : '0');
33
+ }
34
+
35
+ // Restore persisted preference before first paint
36
+ apply(localStorage.getItem('pp-dark') === '1');
37
+
38
+ btn.addEventListener('click', () => apply(!html.classList.contains('dark')));
39
+ })();
40
+ ```
41
+
42
+ Place the inline script immediately after `</header>` so preference is restored before the rest of the page renders. `localStorage` key is `pp-dark` — store `'1'` for dark, `'0'` for light.
43
+
44
+ ## Token system
45
+
46
+ `:root` in `base.scss` declares all design tokens as CSS custom properties (`--pp-*`). `dark-mode.scss` overrides them under `.dark`. Component SCSS uses SCSS variables that compile to `var(--pp-*)` expressions, so no component file contains a media query or a duplicated selector.
47
+
48
+ ### Neutral scale
49
+
50
+ | Token | Light | Dark |
51
+ |---|---|---|
52
+ | `--pp-neutral-50` | `#fafafa` | `#18181b` |
53
+ | `--pp-neutral-100` | `#f4f4f5` | `#27272a` |
54
+ | `--pp-neutral-200` | `#e4e4e7` | `#3f3f46` |
55
+ | `--pp-neutral-300` | `#d4d4d8` | `#52525b` |
56
+ | `--pp-neutral-400` | `#a1a1aa` | `#71717a` |
57
+ | `--pp-neutral-500` | `#71717a` | `#a1a1aa` |
58
+ | `--pp-neutral-600` | `#52525b` | `#d4d4d8` |
59
+ | `--pp-neutral-700` | `#3f3f46` | `#e4e4e7` |
60
+ | `--pp-neutral-800` | `#27272a` | `#f4f4f5` |
61
+ | `--pp-neutral-900` | `#18181b` | `#fafafa` |
62
+
63
+ The scale is fully inverted: 50 ↔ 900, 100 ↔ 800, etc.
64
+
65
+ ### Surface tokens
66
+
67
+ | Token | Light | Dark |
68
+ |---|---|---|
69
+ | `--pp-surface` | `#ffffff` | `#18181b` |
70
+ | `--pp-on-surface` | `#18181b` | `#fafafa` |
71
+ | `--pp-border` | `#e4e4e7` | `#3f3f46` |
72
+
73
+ ### Background tokens
74
+
75
+ | Token | Light | Dark |
76
+ |---|---|---|
77
+ | `--pp-bg-card` | `#ffffff` | `#27272a` |
78
+ | `--pp-bg-input` | `#ffffff` | `#27272a` |
79
+ | `--pp-bg-select` | `#ffffff` | `#27272a` |
80
+ | `--pp-bg-select-panel` | `#ffffff` | `rgb(39 39 42 / 0.97)` |
81
+ | `--pp-bg-header` | `rgb(255 255 255 / 0.65)` | `rgb(24 24 27 / 0.80)` |
82
+ | `--pp-bg-header-mobile` | `rgb(255 255 255 / 0.9)` | `rgb(24 24 27 / 0.95)` |
83
+ | `--pp-bg-dropdown` | `rgb(255 255 255 / 0.85)` | `rgb(39 39 42 / 0.95)` |
84
+ | `--pp-bg-footer` | `#f4f4f5` | `#18181b` |
85
+ | `--pp-section-muted-bg` | `#f4f4f5` | `#27272a` |
86
+
87
+ ### Glass tokens
88
+
89
+ | Token | Light | Dark |
90
+ |---|---|---|
91
+ | `--pp-glass-border` | `rgb(255 255 255 / 0.3)` | `rgb(255 255 255 / 0.10)` |
92
+ | `--pp-glass-hover` | `rgb(0 0 0 / 0.05)` | `rgb(255 255 255 / 0.06)` |
93
+
94
+ ### Shadow tokens
95
+
96
+ Shadows are strengthened in dark mode (higher black opacity):
97
+
98
+ | Token | Light | Dark |
99
+ |---|---|---|
100
+ | `--pp-shadow-sm` | `0 1px 2px 0 rgb(0 0 0 / 0.05)` | `0 1px 2px 0 rgb(0 0 0 / 0.30)` |
101
+ | `--pp-shadow-md` | `0 4px 6px -1px rgb(0 0 0 / 0.10), …` | `0 4px 6px -1px rgb(0 0 0 / 0.40), …` |
102
+ | `--pp-shadow-lg` | `0 10px 15px -3px rgb(0 0 0 / 0.10), …` | `0 10px 15px -3px rgb(0 0 0 / 0.50), …` |
103
+ | `--pp-shadow-xl` | `0 20px 25px -5px rgb(0 0 0 / 0.10), …` | `0 20px 25px -5px rgb(0 0 0 / 0.60), …` |
104
+
105
+ ## SCSS alias pattern
106
+
107
+ SCSS variables in `base.scss` point to the CSS custom properties:
108
+
109
+ ```scss
110
+ // base.scss (excerpt)
111
+ $bg-card: var(--pp-bg-card);
112
+ $on-surface: var(--pp-on-surface);
113
+ $color-border: var(--pp-border);
114
+ ```
115
+
116
+ Component SCSS uses these SCSS variables — e.g. `background: $bg-card` — which compiles to `background: var(--pp-bg-card)`. Changing the `.dark` token value then updates every component automatically at runtime.
117
+
118
+ Do not use SCSS colour functions (lighten/darken) on CSS var references — these are resolved at compile time when the var is still a string, and will fail silently. Use `rgb()` / `oklch()` expressions or hardcoded values in the dark override block instead.
119
+
120
+ ## Inline-style overrides
121
+
122
+ `dark-mode.scss` includes attribute-selector overrides for hardcoded inline colors that cannot easily be templated:
123
+
124
+ ```scss
125
+ .dark [style*="color:#71717a"] { color: #{$color-neutral-400} !important; }
126
+ .dark [style*="color:#52525b"] { color: #{$color-neutral-400} !important; }
127
+ .dark [style*="color:#18181b"] { color: #{$color-neutral-50} !important; }
128
+ ```
129
+
130
+ These handle the section label colours scattered through `index.html` as inline styles. When generating new HTML, prefer `var(--pp-on-surface)` in inline styles over hardcoded hex values to avoid needing additional attribute selectors.
131
+
132
+ ## Component dark overrides
133
+
134
+ Components that required explicit per-selector dark overrides (beyond token inheritance):
135
+
136
+ - **Accordion** — trigger active state keeps primary colour; panel tint uses primary token
137
+ - **Alert** — all six soft variants have per-variant dark tints with recalculated text colours
138
+ - **Carousel** — controls and indicator dots remapped
139
+ - **Table** — striped row bg and hover overlays recalculated
140
+ - **Select** — panel backdrop remapped
141
+
142
+ Components that inherit automatically via token replacement (no explicit dark selector needed):
143
+
144
+ - Button, Card, Header, Footer, Section, Forms (fieldset, text-field, validation)
145
+
146
+ ## Common mistakes
147
+
148
+ - Using `@media (prefers-color-scheme: dark)` instead of `.dark` — PeppertinoCSS never uses the media query; doing so creates a parallel system that fights the class-based toggle.
149
+ - Relying on `localStorage.getItem('pp-dark')` without a null check — a first-time visitor returns `null`, which coerces to `false`; initialise to a default explicitly.
150
+ - Using SCSS `lighten()` / `darken()` on tokens — these functions receive `var(--pp-…)` as a string at compile time; the result is not a colour and will produce no output.
151
+ - Hardcoding colours in new HTML as inline `style="color: #18181b"` — add `var(--pp-on-surface)` inline or the text goes invisible in dark mode.
152
+ - Wrapping a `.dark` pane but forgetting a background colour — the pane inherits its parent's (light) background; add `background: var(--pp-surface)` or an explicit dark value.
@@ -0,0 +1,109 @@
1
+ # Footer
2
+
3
+ **Source:** `src/scss/footer.scss` · No JS required.
4
+
5
+ The footer is a `<footer role="contentinfo">` landmark. It consists of a top grid (brand + nav columns) and a bottom bar (legal + social). It must be the last element in `<body>` — it is the only component exempt from A→Z ordering.
6
+
7
+ ## Full structure
8
+
9
+ ```html
10
+ <footer class="pp-footer pp-footer--accent" role="contentinfo">
11
+ <div class="pp-footer__top">
12
+
13
+ <!-- Brand block — always first, spans full width on mobile -->
14
+ <div class="pp-footer__brand">
15
+ <a href="#" class="pp-footer__logo">BrandName</a>
16
+ <p class="pp-footer__tagline">Short one-line description of the product.</p>
17
+ </div>
18
+
19
+ <!-- Nav columns — repeat as needed (up to 4 before xl, unlimited after) -->
20
+ <div class="pp-footer__col">
21
+ <p class="pp-footer__col-title">Product</p>
22
+ <ul class="pp-footer__nav" aria-label="Product links">
23
+ <li><a href="#" class="pp-footer__nav-link">Features</a></li>
24
+ <li><a href="#" class="pp-footer__nav-link">Pricing</a></li>
25
+ <li><a href="#" class="pp-footer__nav-link">Changelog</a></li>
26
+ </ul>
27
+ </div>
28
+
29
+ <div class="pp-footer__col">
30
+ <p class="pp-footer__col-title">Resources</p>
31
+ <ul class="pp-footer__nav" aria-label="Resource links">
32
+ <li><a href="#" class="pp-footer__nav-link">Documentation</a></li>
33
+ <li><a href="#" class="pp-footer__nav-link">GitHub</a></li>
34
+ </ul>
35
+ </div>
36
+
37
+ </div>
38
+
39
+ <div class="pp-footer__bottom">
40
+ <p class="pp-footer__legal">
41
+ &copy; 2026 BrandName. Released under the
42
+ <a href="#" target="_blank" rel="noopener noreferrer">MIT License</a>.
43
+ </p>
44
+ <ul class="pp-footer__social" aria-label="Social links">
45
+ <li>
46
+ <a href="https://github.com/..." class="pp-footer__social-link"
47
+ aria-label="GitHub" target="_blank" rel="noopener noreferrer">
48
+ <i data-lucide="github"></i>
49
+ </a>
50
+ </li>
51
+ <li>
52
+ <a href="https://npmjs.com/..." class="pp-footer__social-link"
53
+ aria-label="npm" target="_blank" rel="noopener noreferrer">
54
+ <i data-lucide="package"></i>
55
+ </a>
56
+ </li>
57
+ </ul>
58
+ </div>
59
+ </footer>
60
+ ```
61
+
62
+ ## Parts
63
+
64
+ | Class | Element | Description |
65
+ |---|---|---|
66
+ | `.pp-footer` | `<footer>` | Outer shell — padding, border-top |
67
+ | `.pp-footer__top` | `<div>` | CSS grid: `1fr repeat(3, auto)`, expands to 4 auto cols at `xl` |
68
+ | `.pp-footer__brand` | `<div>` | Brand + tagline — spans full width on mobile |
69
+ | `.pp-footer__logo` | `<a>` | Brand name link, semibold lg |
70
+ | `.pp-footer__tagline` | `<p>` | Muted description, sm |
71
+ | `.pp-footer__col` | `<div>` | Nav column, `min-width: 140px` |
72
+ | `.pp-footer__col-title` | `<p>` | xs, semibold, 0.08em tracking, uppercase |
73
+ | `.pp-footer__nav` | `<ul>` | Column link list — requires `aria-label` |
74
+ | `.pp-footer__nav-link` | `<a>` | neutral-500, hover → neutral-900 |
75
+ | `.pp-footer__bottom` | `<div>` | Flex row — legal left, social right |
76
+ | `.pp-footer__legal` | `<p>` | xs, neutral-400, inline `<a>` links supported |
77
+ | `.pp-footer__social` | `<ul>` | Icon link list — requires `aria-label` |
78
+ | `.pp-footer__social-link` | `<a>` | 32px circle, icon centered — requires `aria-label` |
79
+
80
+ ## Variants
81
+
82
+ | Class on `.pp-footer` | Description |
83
+ |---|---|
84
+ | `.pp-footer--dark` | neutral-900 background; all text and border colors inverted to light |
85
+ | `.pp-footer--accent` | Removes top border; adds 3px gradient (gold→red) strip at very top |
86
+
87
+ `--dark` and `--accent` can be combined: `class="pp-footer pp-footer--dark pp-footer--accent"`.
88
+
89
+ ## Responsive layout
90
+
91
+ - **Desktop (≥ xl):** brand + up to 4 nav columns side by side.
92
+ - **Tablet (< xl, ≥ 768px):** brand + 3 auto columns.
93
+ - **Mobile (< 768px):** 2-column grid; brand spans full width above the columns.
94
+ - **Small mobile (< 480px):** single column, everything stacked.
95
+
96
+ ## ARIA & accessibility
97
+
98
+ - `<footer>` has an implicit `role="contentinfo"` landmark — always use the native element, not `<div role="contentinfo">`.
99
+ - Every `.pp-footer__nav` `<ul>` must have `aria-label` describing which set of links it contains — multiple lists on the same page would otherwise be indistinguishable to AT.
100
+ - Every `.pp-footer__social-link` icon button must have `aria-label` — the icon alone provides no accessible name.
101
+ - External links should have `target="_blank" rel="noopener noreferrer"` and optionally a visually-hidden "opens in new tab" notice or `aria-label` suffix.
102
+ - The `<p class="pp-footer__col-title">` is presentational — it is NOT a heading and must not use `<h*>` elements (footer columns are not document sections).
103
+
104
+ ## Common mistakes
105
+
106
+ - Using `<h3>` or other heading elements for `.pp-footer__col-title` — column titles are labels, not document headings; this breaks heading hierarchy.
107
+ - Omitting `aria-label` from `.pp-footer__nav` lists — screen readers cannot distinguish "Product links" from "Resource links" without it.
108
+ - Omitting `aria-label` from icon-only `.pp-footer__social-link` buttons — icons have no text content so AT announces nothing useful.
109
+ - Adding `role="contentinfo"` to `<footer>` explicitly — it is redundant; `<footer>` inside `<body>` already carries that role implicitly.