@auriel/peppertino 0.5.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (134) hide show
  1. package/CHANGELOG.txt +249 -224
  2. package/LICENSE +21 -21
  3. package/MIGRATION.md +52 -52
  4. package/README.md +811 -764
  5. package/agents/peppertino/SKILL.md +84 -0
  6. package/agents/peppertino/accordion.md +134 -0
  7. package/agents/peppertino/alert.md +116 -0
  8. package/agents/peppertino/badge.md +74 -0
  9. package/agents/peppertino/base.md +252 -0
  10. package/agents/peppertino/button.md +65 -0
  11. package/agents/peppertino/card.md +82 -0
  12. package/agents/peppertino/carousel.md +147 -0
  13. package/agents/peppertino/catalog.md +83 -0
  14. package/agents/peppertino/components-ai-search.md +10 -0
  15. package/agents/peppertino/components-display.md +19 -0
  16. package/agents/peppertino/components-inputs.md +15 -0
  17. package/agents/peppertino/components-navigation.md +12 -0
  18. package/agents/peppertino/dark-mode.md +152 -0
  19. package/agents/peppertino/footer.md +109 -0
  20. package/agents/peppertino/forms-fieldset.md +85 -0
  21. package/agents/peppertino/forms-form-instructions.md +94 -0
  22. package/agents/peppertino/forms-label.md +110 -0
  23. package/agents/peppertino/forms-text-field.md +134 -0
  24. package/agents/peppertino/forms-validation.md +153 -0
  25. package/agents/peppertino/gradient.md +41 -0
  26. package/agents/peppertino/header.md +105 -0
  27. package/agents/peppertino/modal.md +123 -0
  28. package/agents/peppertino/section.md +56 -0
  29. package/agents/peppertino/select.md +110 -0
  30. package/agents/peppertino/switch.md +72 -0
  31. package/agents/peppertino/table.md +69 -0
  32. package/agents/peppertino/tabs.md +115 -0
  33. package/agents/peppertino/toast.md +96 -0
  34. package/agents/peppertino/tooltip.md +111 -0
  35. package/agents/peppertino/typography.md +118 -0
  36. package/agents/peppertino/utilities.md +194 -0
  37. package/agents/skill.md +65 -0
  38. package/build.js +53 -53
  39. package/dist/accordion.js +1 -1
  40. package/dist/accordion.js.map +2 -2
  41. package/dist/alert.js.map +1 -1
  42. package/dist/carousel.js.map +1 -1
  43. package/dist/header.js.map +1 -1
  44. package/dist/main.css +2566 -1008
  45. package/dist/main.css.map +1 -1
  46. package/dist/main.min.css +1 -0
  47. package/dist/modal.js.map +1 -1
  48. package/dist/peppertino.js +1 -1
  49. package/dist/peppertino.js.map +2 -2
  50. package/dist/select.js.map +1 -1
  51. package/dist/switch.js.map +1 -1
  52. package/dist/tabs.js.map +1 -1
  53. package/dist/theme.js.map +1 -1
  54. package/dist/toast.js.map +1 -1
  55. package/dist/validation.js.map +1 -1
  56. package/icon.svg +4 -0
  57. package/index.html +2177 -2098
  58. package/package.json +28 -28
  59. package/scripts/hex-to-hsl.mjs +75 -75
  60. package/scripts/lint-bem.mjs +53 -53
  61. package/scripts/lint-colors.mjs +87 -87
  62. package/site.webmanifest +18 -0
  63. package/src/js/accordion.js +105 -103
  64. package/src/js/alert.js +28 -28
  65. package/src/js/carousel.js +153 -153
  66. package/src/js/header.js +85 -85
  67. package/src/js/modal.js +138 -138
  68. package/src/js/peppertino.js +15 -15
  69. package/src/js/select.js +101 -101
  70. package/src/js/switch.js +28 -28
  71. package/src/js/tabs.js +104 -104
  72. package/src/js/theme.js +47 -47
  73. package/src/js/toast.js +79 -79
  74. package/src/js/validation.js +132 -132
  75. package/src/scss/accordion.scss +190 -156
  76. package/src/scss/activity.scss +17 -0
  77. package/src/scss/alert.scss +203 -203
  78. package/src/scss/badge.scss +90 -90
  79. package/src/scss/base.scss +511 -506
  80. package/src/scss/button.scss +119 -119
  81. package/src/scss/card.scss +121 -121
  82. package/src/scss/carousel.scss +303 -303
  83. package/src/scss/code-block.scss +22 -0
  84. package/src/scss/counter.scss +5 -0
  85. package/src/scss/dark-mode.scss +514 -514
  86. package/src/scss/duration.scss +26 -0
  87. package/src/scss/folder.scss +27 -0
  88. package/src/scss/footer.scss +224 -224
  89. package/src/scss/forms/fieldset.scss +127 -127
  90. package/src/scss/forms/form-instructions.scss +133 -133
  91. package/src/scss/forms/label.scss +115 -115
  92. package/src/scss/forms/text-field.scss +240 -240
  93. package/src/scss/forms/validation.scss +215 -215
  94. package/src/scss/forms.scss +8 -8
  95. package/src/scss/gradient.scss +11 -11
  96. package/src/scss/gravity-letters.scss +7 -0
  97. package/src/scss/header.scss +257 -238
  98. package/src/scss/helpers/color.scss +9 -0
  99. package/src/scss/helpers/flex.scss +14 -0
  100. package/src/scss/helpers/index.scss +6 -0
  101. package/src/scss/helpers/layout.scss +14 -0
  102. package/src/scss/helpers/spacing.scss +14 -0
  103. package/src/scss/helpers/typography.scss +11 -0
  104. package/src/scss/helpers/visibility.scss +9 -0
  105. package/src/scss/main.scss +49 -24
  106. package/src/scss/modal.scss +188 -188
  107. package/src/scss/model-picker.scss +5 -0
  108. package/src/scss/notification.scss +5 -0
  109. package/src/scss/orb.scss +7 -0
  110. package/src/scss/otp.scss +5 -0
  111. package/src/scss/pill-nav.scss +10 -0
  112. package/src/scss/prompt.scss +28 -0
  113. package/src/scss/rail.scss +7 -0
  114. package/src/scss/reactions.scss +5 -0
  115. package/src/scss/reset.scss +84 -84
  116. package/src/scss/response.scss +11 -0
  117. package/src/scss/reveal.scss +5 -0
  118. package/src/scss/scroll-progress.scss +4 -0
  119. package/src/scss/search-results.scss +13 -0
  120. package/src/scss/section.scss +87 -79
  121. package/src/scss/select.scss +210 -210
  122. package/src/scss/sidebar.scss +8 -0
  123. package/src/scss/status.scss +5 -0
  124. package/src/scss/step-list.scss +13 -0
  125. package/src/scss/switch.scss +121 -121
  126. package/src/scss/table.scss +89 -89
  127. package/src/scss/tabs.scss +156 -156
  128. package/src/scss/task-list.scss +18 -0
  129. package/src/scss/theme-picker.scss +5 -0
  130. package/src/scss/toast.scss +170 -170
  131. package/src/scss/tooltip.scss +126 -126
  132. package/src/scss/typography.scss +58 -58
  133. package/src/scss/utilities.scss +243 -243
  134. package/src/scss/voice-note.scss +5 -0
@@ -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,83 @@
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
+ For detailed accessibility, HIG, and JavaScript guidance, see [display and feedback](components-display.md), [navigation](components-navigation.md), [inputs](components-inputs.md), and [AI and search](components-ai-search.md). See [utilities](utilities.md) for the modular helper families.
6
+
7
+ ## Display
8
+
9
+ ```html
10
+ <details class="pp-folder">
11
+ <summary class="pp-folder__header">Project files</summary>
12
+ <div class="pp-folder__body"><a href="/notes">Notes</a></div>
13
+ </details>
14
+
15
+ <figure class="pp-code-block">
16
+ <figcaption class="pp-code-block__header">example.css</figcaption>
17
+ <pre><code>color: red;</code></pre>
18
+ </figure>
19
+
20
+ <figure class="pp-activity">
21
+ <figcaption>Contribution activity: 3 contributions this week</figcaption>
22
+ <div class="pp-activity__grid" aria-hidden="true">
23
+ <span class="pp-activity__day" data-level="0"></span>
24
+ <span class="pp-activity__day" data-level="3"></span>
25
+ </div>
26
+ </figure>
27
+
28
+ <ol class="pp-step-list" aria-label="Setup progress">
29
+ <li>Account</li><li aria-current="step">Preferences</li><li>Finish</li>
30
+ </ol>
31
+ <output class="pp-counter" aria-label="42 items">42</output>
32
+ <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>
33
+ <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>
34
+ ```
35
+
36
+ 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.
37
+
38
+ ## Status and visual treatments
39
+
40
+ ```html
41
+ <span class="pp-status" role="status"><span class="pp-status__indicator" aria-hidden="true"></span>Working</span>
42
+ <div class="pp-orb" aria-hidden="true"></div>
43
+ <div class="pp-orb pp-orb--grid" aria-hidden="true"></div>
44
+ <div class="pp-orb pp-orb--matrix" aria-hidden="true"></div>
45
+ <div class="pp-reveal"><p>Content remains available without animation.</p></div>
46
+ ```
47
+
48
+ 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.
49
+
50
+ ## Navigation
51
+
52
+ ```html
53
+ <nav class="pp-sidebar" aria-label="Main"><a href="/" aria-current="page">Home</a><a href="/settings">Settings</a></nav>
54
+ <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>
55
+ <nav class="pp-pill-nav" aria-label="Views"><a href="/all" aria-current="page">All</a><a href="/saved">Saved</a></nav>
56
+ <label for="reading">Reading progress</label><progress class="pp-scroll-progress" id="reading" value="0" max="100">0%</progress>
57
+ ```
58
+
59
+ 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.
60
+
61
+ ## Inputs and feedback
62
+
63
+ ```html
64
+ <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>
65
+ <label for="otp">Verification code</label><input class="pp-otp" id="otp" name="code" inputmode="numeric" autocomplete="one-time-code" pattern="[0-9]*">
66
+ <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>
67
+ <ul class="pp-task-list"><li><label><input type="checkbox" name="task" value="draft"><span>Write draft</span></label></li></ul>
68
+ <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>
69
+ <a class="pp-notification" href="/notifications" aria-label="Notifications, 3 unread">🔔<span class="pp-notification__count" aria-hidden="true">3</span></a>
70
+ ```
71
+
72
+ 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.
73
+
74
+ ## AI and search
75
+
76
+ ```html
77
+ <label for="model">Model</label><select class="pp-model-picker" id="model" name="model"><option>Default</option><option>Alternative</option></select>
78
+ <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>
79
+ <article class="pp-response" aria-label="Response"><p>Response content goes here.</p></article>
80
+ <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>
81
+ ```
82
+
83
+ 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,10 @@
1
+ # Response, search, and application-owned behavior
2
+
3
+ `response.scss` and `search-results.scss` are standalone presentation modules. `prompt.scss` and `model-picker.scss` are covered in [components-inputs.md](components-inputs.md); complete markup is in [catalog.md](catalog.md). Consult Apple's [design principles](https://developer.apple.com/design/human-interface-guidelines/design-principles), [writing](https://developer.apple.com/design/human-interface-guidelines/writing), and [privacy](https://developer.apple.com/design/human-interface-guidelines/privacy) as relevant to the product.
4
+
5
+ - `.pp-response` provides a surface for response content; it does not fetch, stream, parse, sanitize, or announce it. Render untrusted text safely, preserve readable content without animation, and provide a concise separate status for completion or errors instead of announcing every streamed token.
6
+ - `.pp-search-results` provides a styled container and list spacing. It does not query a search service, rank results, or generate links. Use meaningful links, identify the results region, and provide useful loading, empty, and error states when applicable.
7
+ - Form actions, model choices, streaming, search, persistence, and backend validation belong to the consuming application. Use semantic HTML and a real server endpoint where appropriate so the baseline can remain usable without JavaScript; scripts are replaceable enhancements, not a requirement for styling.
8
+ - Make network and privacy behavior clear when it matters to a person's choice. Do not present mock output as a live result, place secrets in client-side markup, or imply that the CSS implements an AI or search service.
9
+
10
+ Use short, purposeful transitions with reduced-motion support. New keyframe animations, if needed, use three points; avoid blocking reading or input while effects run.
@@ -0,0 +1,19 @@
1
+ # Display and feedback components
2
+
3
+ Use with [catalog.md](catalog.md), which contains working markup. Each named module is an independently importable `src/scss/<name>.scss`; these modules do not ship JavaScript. Apply the [HIG design principles](https://developer.apple.com/design/human-interface-guidelines/design-principles), [accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility), and [motion](https://developer.apple.com/design/human-interface-guidelines/motion) guidance to the actual platform and task.
4
+
5
+ | Module | What the CSS supplies | Consumer behavior |
6
+ |---|---|---|
7
+ | `folder` | `.pp-folder` disclosure surface and header | Use native `details` / `summary`; no script needed for toggling. |
8
+ | `code-block` | `.pp-code-block`, header and scrollable `pre` | Render escaped code; syntax highlighting or clipboard actions require application code. Do not show an inert copy button. |
9
+ | `activity` | `.pp-activity__grid` and `.pp-activity__day[data-level]` levels 0–4 | Supply data and an accessible text summary or table; color alone must not convey values. |
10
+ | `counter` | `.pp-counter` numeric styling | Supply an accurate text value. Any interpolation is optional; do not announce every animation frame. |
11
+ | `step-list` | `.pp-step-list` and `aria-current="step"` emphasis | Supply ordered steps and current state; it does not advance or navigate by itself. |
12
+ | `status` | `.pp-status` and `.pp-status__indicator` | Keep a meaningful textual status. Use a polite status region when updates should be announced. |
13
+ | `notification` | `.pp-notification` and count badge | Supply a real destination or action and an accessible name including the unread count; update both count and name together. |
14
+ | `voice-note` | `.pp-voice-note` container | Use native `<audio controls>` with an accessible label and a fallback link; loading and recording are application responsibilities. |
15
+ | `orb` | Decorative `.pp-orb`, `--grid`, `--matrix`, and `--pp-orb-size` | Mark purely decorative graphics `aria-hidden`; do not rely on them to communicate status. |
16
+ | `reveal` | `.pp-reveal` content surface | Content is visible by default. Effects are application-owned and must not hide essential information without script. |
17
+ | `gravity-letters` | `.pp-gravity-letters` and `__letter` hover transitions | Preserve a readable accessible name, hide duplicate decorative letters from assistive technology, and keep text legible without motion. |
18
+
19
+ Keep motion brief and purposeful. Respect `prefers-reduced-motion`; if authoring keyframes, use exactly three keyframe points. CSS defines presentation; consumers may add or replace scripts without altering the baseline. Test readable text, zoom, keyboard focus, reduced motion, and light/dark contrast. Validate real assistive technology behavior before claiming compliance.
@@ -0,0 +1,15 @@
1
+ # Input and choice components
2
+
3
+ Use the examples in [catalog.md](catalog.md). Each module is separately importable and has no bundled JavaScript. Apply Apple's [text field](https://developer.apple.com/design/human-interface-guidelines/text-fields), [entering data](https://developer.apple.com/design/human-interface-guidelines/entering-data), and [accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility) guidance, adapting it to the web and target platform.
4
+
5
+ | Module | Native baseline | Consumer responsibilities |
6
+ |---|---|---|
7
+ | `duration` | `.pp-duration` fieldset with labelled number inputs and native min/max validation. | Choose sensible limits and validate on the server; do not assume CSS clamps values. Preserve keyboard and spinner operation. |
8
+ | `otp` | `.pp-otp` styles one labelled input; `autocomplete="one-time-code"` and `inputmode="numeric"` can assist entry. | Preserve leading zeros and paste/autofill; validate the intended format. Avoid splitting input unless there is a demonstrated need. |
9
+ | `theme-picker` | `.pp-theme-picker` styles a radio group. | Apply and persist the selection in application code; without it the form still collects the choice. Do not claim it switches themes by itself. |
10
+ | `task-list` | `.pp-task-list` styles checkboxes and checked text. | Persist or submit changes in application code; associate each checkbox with its label. |
11
+ | `reactions` | `.pp-reactions` styles native labelled radio controls. | Save or submit the choice and supply textual labels alongside emoji. |
12
+ | `model-picker` | `.pp-model-picker` styles a native `<select>`. | Supply accurate options, a visible label, and application behavior for the selection. |
13
+ | `prompt` | `.pp-prompt` styles a label, textarea, and `__actions`. | Use a real form and endpoint for no-script submission when feasible; script-driven submission must preserve keyboard use, validation, and error feedback. |
14
+
15
+ Use visible persistent labels, appropriate input types and autocomplete, and text errors associated with the field. Placeholder text is supplemental. Give controls room at large text sizes and avoid relying on color to convey errors. Keep application code replaceable: attach behavior to semantic markup or documented classes, do not make the SCSS depend on a framework or a particular script. Do not insert credentials or personal data into client-side examples.
@@ -0,0 +1,12 @@
1
+ # Navigation and progress components
2
+
3
+ See [catalog.md](catalog.md) for markup. `sidebar`, `rail`, `pill-nav`, and `scroll-progress` are separate SCSS modules with no JavaScript dependency. Follow Apple's [layout](https://developer.apple.com/design/human-interface-guidelines/layout), [navigation](https://developer.apple.com/design/human-interface-guidelines/navigation), and [accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility) guidance where relevant.
4
+
5
+ | Module | Baseline | Optional application behavior |
6
+ |---|---|---|
7
+ | `sidebar` | `.pp-sidebar` styles ordinary links; `aria-current="page"` marks the current page. | Routing may update the current page; pointer proximity must never be required to reveal or use links. |
8
+ | `rail` | `.pp-rail` styles an ordered list of in-page anchors. | Update `aria-current` as the visible section changes if scroll tracking is implemented. |
9
+ | `pill-nav` | `.pp-pill-nav` styles links and `aria-current="page"`. | Navigation follows normal link behavior; this is not a tab widget or a script-driven tablist. |
10
+ | `scroll-progress` | `.pp-scroll-progress` styles a native `<progress>`. | Compute and update its `value` if reporting live progress. A static value does not track scrolling automatically; omit `value` for an indeterminate progress indicator. |
11
+
12
+ Give navigation landmarks distinguishable accessible names and links real destinations. Keep source, reading, and focus order coherent; use text or another non-color distinction for the active state. Layout should adapt to available width and text size, rather than infer a device from viewport width. Ensure destinations work with script disabled where possible. Do not add ARIA roles or keyboard overrides that conflict with native links or `<progress>`.
@@ -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.