@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.
- package/CHANGELOG.txt +242 -224
- package/LICENSE +21 -21
- package/MIGRATION.md +52 -52
- package/README.md +773 -764
- package/agents/peppertino/SKILL.md +76 -0
- package/agents/peppertino/accordion.md +134 -0
- package/agents/peppertino/alert.md +116 -0
- package/agents/peppertino/badge.md +74 -0
- package/agents/peppertino/base.md +252 -0
- package/agents/peppertino/button.md +65 -0
- package/agents/peppertino/card.md +82 -0
- package/agents/peppertino/carousel.md +147 -0
- package/agents/peppertino/catalog.md +81 -0
- package/agents/peppertino/dark-mode.md +152 -0
- package/agents/peppertino/footer.md +109 -0
- package/agents/peppertino/forms-fieldset.md +85 -0
- package/agents/peppertino/forms-form-instructions.md +94 -0
- package/agents/peppertino/forms-label.md +110 -0
- package/agents/peppertino/forms-text-field.md +134 -0
- package/agents/peppertino/forms-validation.md +153 -0
- package/agents/peppertino/gradient.md +41 -0
- package/agents/peppertino/header.md +105 -0
- package/agents/peppertino/modal.md +123 -0
- package/agents/peppertino/section.md +56 -0
- package/agents/peppertino/select.md +110 -0
- package/agents/peppertino/switch.md +72 -0
- package/agents/peppertino/table.md +69 -0
- package/agents/peppertino/tabs.md +115 -0
- package/agents/peppertino/toast.md +96 -0
- package/agents/peppertino/tooltip.md +111 -0
- package/agents/peppertino/typography.md +118 -0
- package/agents/peppertino/utilities.md +194 -0
- package/agents/skill.md +65 -0
- package/build.js +53 -53
- package/dist/accordion.js +1 -1
- package/dist/accordion.js.map +2 -2
- package/dist/alert.js.map +1 -1
- package/dist/carousel.js.map +1 -1
- package/dist/header.js.map +1 -1
- package/dist/main.css +2566 -1008
- package/dist/main.css.map +1 -1
- package/dist/main.min.css +1 -0
- package/dist/modal.js.map +1 -1
- package/dist/peppertino.js +1 -1
- package/dist/peppertino.js.map +2 -2
- package/dist/select.js.map +1 -1
- package/dist/switch.js.map +1 -1
- package/dist/tabs.js.map +1 -1
- package/dist/theme.js.map +1 -1
- package/dist/toast.js.map +1 -1
- package/dist/validation.js.map +1 -1
- package/icon.svg +4 -0
- package/index.html +2172 -2098
- package/package.json +28 -28
- package/scripts/hex-to-hsl.mjs +75 -75
- package/scripts/lint-bem.mjs +53 -53
- package/scripts/lint-colors.mjs +87 -87
- package/site.webmanifest +18 -0
- package/src/js/accordion.js +105 -103
- package/src/js/alert.js +28 -28
- package/src/js/carousel.js +153 -153
- package/src/js/header.js +85 -85
- package/src/js/modal.js +138 -138
- package/src/js/peppertino.js +15 -15
- package/src/js/select.js +101 -101
- package/src/js/switch.js +28 -28
- package/src/js/tabs.js +104 -104
- package/src/js/theme.js +47 -47
- package/src/js/toast.js +79 -79
- package/src/js/validation.js +132 -132
- package/src/scss/accordion.scss +190 -156
- package/src/scss/activity.scss +17 -0
- package/src/scss/alert.scss +203 -203
- package/src/scss/badge.scss +90 -90
- package/src/scss/base.scss +511 -506
- package/src/scss/button.scss +119 -119
- package/src/scss/card.scss +121 -121
- package/src/scss/carousel.scss +303 -303
- package/src/scss/code-block.scss +22 -0
- package/src/scss/counter.scss +5 -0
- package/src/scss/dark-mode.scss +514 -514
- package/src/scss/duration.scss +26 -0
- package/src/scss/folder.scss +27 -0
- package/src/scss/footer.scss +224 -224
- package/src/scss/forms/fieldset.scss +127 -127
- package/src/scss/forms/form-instructions.scss +133 -133
- package/src/scss/forms/label.scss +115 -115
- package/src/scss/forms/text-field.scss +240 -240
- package/src/scss/forms/validation.scss +215 -215
- package/src/scss/forms.scss +8 -8
- package/src/scss/gradient.scss +11 -11
- package/src/scss/gravity-letters.scss +7 -0
- package/src/scss/header.scss +257 -238
- package/src/scss/helpers/color.scss +9 -0
- package/src/scss/helpers/flex.scss +14 -0
- package/src/scss/helpers/index.scss +6 -0
- package/src/scss/helpers/layout.scss +14 -0
- package/src/scss/helpers/spacing.scss +14 -0
- package/src/scss/helpers/typography.scss +11 -0
- package/src/scss/helpers/visibility.scss +9 -0
- package/src/scss/main.scss +49 -24
- package/src/scss/modal.scss +188 -188
- package/src/scss/model-picker.scss +5 -0
- package/src/scss/notification.scss +5 -0
- package/src/scss/orb.scss +7 -0
- package/src/scss/otp.scss +5 -0
- package/src/scss/pill-nav.scss +10 -0
- package/src/scss/prompt.scss +28 -0
- package/src/scss/rail.scss +7 -0
- package/src/scss/reactions.scss +5 -0
- package/src/scss/reset.scss +84 -84
- package/src/scss/response.scss +11 -0
- package/src/scss/reveal.scss +5 -0
- package/src/scss/scroll-progress.scss +4 -0
- package/src/scss/search-results.scss +13 -0
- package/src/scss/section.scss +87 -79
- package/src/scss/select.scss +210 -210
- package/src/scss/sidebar.scss +8 -0
- package/src/scss/status.scss +5 -0
- package/src/scss/step-list.scss +13 -0
- package/src/scss/switch.scss +121 -121
- package/src/scss/table.scss +89 -89
- package/src/scss/tabs.scss +156 -156
- package/src/scss/task-list.scss +18 -0
- package/src/scss/theme-picker.scss +5 -0
- package/src/scss/toast.scss +170 -170
- package/src/scss/tooltip.scss +126 -126
- package/src/scss/typography.scss +58 -58
- package/src/scss/utilities.scss +243 -243
- package/src/scss/voice-note.scss +5 -0
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# Header
|
|
2
|
+
|
|
3
|
+
For long desktop dropdowns, add `.pp-header__dropdown--columns` to the dropdown list. It uses two columns at widths of at least 768 CSS pixels and keeps items in reading and keyboard order. On smaller screens it remains a single-column mobile drawer. The menu scrolls when its content exceeds the available height.
|
|
4
|
+
|
|
5
|
+
**Source:** `src/scss/header.scss` · `src/js/header.js`
|
|
6
|
+
|
|
7
|
+
Sticky glassmorphism navigation bar, 56px tall, `z-index: 100` (overlay). The brand sits on the left; nav links on the right; a hamburger toggle appears below 768px. JS handles mobile drawer open/close, dropdown keyboard navigation, and ARIA state toggling.
|
|
8
|
+
|
|
9
|
+
## Full structure
|
|
10
|
+
|
|
11
|
+
```html
|
|
12
|
+
<header class="pp-header">
|
|
13
|
+
|
|
14
|
+
<a href="#hero" class="pp-header__brand">BrandName</a>
|
|
15
|
+
|
|
16
|
+
<nav aria-label="Main navigation">
|
|
17
|
+
<ul class="pp-header__nav" role="menubar">
|
|
18
|
+
|
|
19
|
+
<!-- Simple nav link -->
|
|
20
|
+
<li class="pp-header__nav-item" role="none">
|
|
21
|
+
<a href="#about" class="pp-header__nav-link" role="menuitem"
|
|
22
|
+
aria-current="page">About</a>
|
|
23
|
+
</li>
|
|
24
|
+
|
|
25
|
+
<!-- Nav link with dropdown -->
|
|
26
|
+
<li class="pp-header__nav-item" role="none">
|
|
27
|
+
<a href="#products" class="pp-header__nav-link" role="menuitem"
|
|
28
|
+
aria-haspopup="true" aria-expanded="false" id="products-trigger">Products</a>
|
|
29
|
+
<ul class="pp-header__dropdown" role="menu"
|
|
30
|
+
aria-label="Products" aria-labelledby="products-trigger">
|
|
31
|
+
<li role="none">
|
|
32
|
+
<a href="#features" class="pp-header__dropdown-link" role="menuitem">Features</a>
|
|
33
|
+
</li>
|
|
34
|
+
<li role="none">
|
|
35
|
+
<a href="#pricing" class="pp-header__dropdown-link" role="menuitem">Pricing</a>
|
|
36
|
+
</li>
|
|
37
|
+
</ul>
|
|
38
|
+
</li>
|
|
39
|
+
|
|
40
|
+
</ul>
|
|
41
|
+
</nav>
|
|
42
|
+
|
|
43
|
+
<!-- Mobile hamburger — hidden above 768px -->
|
|
44
|
+
<button class="pp-header__toggle" type="button"
|
|
45
|
+
aria-expanded="false" aria-label="Toggle navigation"
|
|
46
|
+
aria-controls="main-nav">
|
|
47
|
+
<span></span>
|
|
48
|
+
<span></span>
|
|
49
|
+
<span></span>
|
|
50
|
+
</button>
|
|
51
|
+
|
|
52
|
+
</header>
|
|
53
|
+
<script src="dist/header.js" defer></script>
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Parts
|
|
57
|
+
|
|
58
|
+
| Class | Element | Description |
|
|
59
|
+
|---|---|---|
|
|
60
|
+
| `.pp-header` | `<header>` | Sticky bar, `height: 56px`, glassmorphism blur |
|
|
61
|
+
| `.pp-header__brand` | `<a>` | Logo/brand link — semibold, hover → primary |
|
|
62
|
+
| `.pp-header__nav` | `<ul>` | Horizontal nav list — `role="menubar"` |
|
|
63
|
+
| `.pp-header__nav-item` | `<li>` | Nav item wrapper — `role="none"` |
|
|
64
|
+
| `.pp-header__nav-link` | `<a>` | Nav link — `role="menuitem"`, active via `aria-current="page"` or `.is-active` |
|
|
65
|
+
| `.pp-header__dropdown` | `<ul>` | Dropdown panel — `role="menu"`, shown on hover/focus-within |
|
|
66
|
+
| `.pp-header__dropdown-link` | `<a>` | Dropdown item — `role="menuitem"` |
|
|
67
|
+
| `.pp-header__toggle` | `<button>` | Hamburger — visible only below 768px |
|
|
68
|
+
|
|
69
|
+
## Dropdown behaviour
|
|
70
|
+
|
|
71
|
+
- **Desktop:** dropdown appears on `:hover` and `:focus-within` via CSS — no JS required for the basic open state.
|
|
72
|
+
- **Mobile:** dropdown is inlined (static position, no animation) inside the drawer.
|
|
73
|
+
- JS adds `.is-open` to `.pp-header__nav-item` for programmatic control and updates `aria-expanded` on the trigger.
|
|
74
|
+
- The three `<span>` children of `.pp-header__toggle` animate into a × when `aria-expanded="true"` is set.
|
|
75
|
+
|
|
76
|
+
## Active link
|
|
77
|
+
|
|
78
|
+
```html
|
|
79
|
+
<a href="#current-page" class="pp-header__nav-link" role="menuitem" aria-current="page">
|
|
80
|
+
Current Page
|
|
81
|
+
</a>
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
CSS styles `[aria-current="page"]` and `.is-active` identically — use `aria-current` for semantic correctness.
|
|
85
|
+
|
|
86
|
+
## ARIA requirements
|
|
87
|
+
|
|
88
|
+
| Element | Required ARIA |
|
|
89
|
+
|---|---|
|
|
90
|
+
| `<nav>` | `aria-label="Main navigation"` (or your label) |
|
|
91
|
+
| `<ul class="pp-header__nav">` | `role="menubar"` |
|
|
92
|
+
| `<li class="pp-header__nav-item">` | `role="none"` |
|
|
93
|
+
| `<a class="pp-header__nav-link">` | `role="menuitem"` |
|
|
94
|
+
| Dropdown trigger `<a>` | `aria-haspopup="true"` + `aria-expanded="false/true"` |
|
|
95
|
+
| `<ul class="pp-header__dropdown">` | `role="menu"` + `aria-label` |
|
|
96
|
+
| `<li>` inside dropdown | `role="none"` |
|
|
97
|
+
| `<a class="pp-header__dropdown-link">` | `role="menuitem"` |
|
|
98
|
+
| `.pp-header__toggle` | `aria-expanded`, `aria-label`, `aria-controls` pointing to nav id |
|
|
99
|
+
|
|
100
|
+
## Common mistakes
|
|
101
|
+
|
|
102
|
+
- Omitting `role="none"` on `<li>` wrappers — the default `listitem` role conflicts with `menuitem` children under a `menubar`/`menu`.
|
|
103
|
+
- Using `aria-haspopup="menu"` instead of `aria-haspopup="true"` — both are valid but `"true"` is more broadly supported.
|
|
104
|
+
- Adding `role="navigation"` to `<nav>` — redundant; `<nav>` already carries that role implicitly.
|
|
105
|
+
- Forgetting `aria-controls` on the mobile toggle — screen readers need to know which element the button controls.
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Modal
|
|
2
|
+
|
|
3
|
+
**Source:** `src/scss/modal.scss` · `src/js/modal.js`
|
|
4
|
+
|
|
5
|
+
Glassmorphic action sheet pattern. The backdrop blurs the page behind the modal. The modal container uses frosted glass (rgba white + backdrop-filter). A gradient accent strip appears at the top of the modal. JS provides focus trap, Escape-to-close, and focus restoration.
|
|
6
|
+
|
|
7
|
+
## Full structure
|
|
8
|
+
|
|
9
|
+
```html
|
|
10
|
+
<!-- Trigger -->
|
|
11
|
+
<button class="button" data-modal-open="confirm-modal">Delete item</button>
|
|
12
|
+
|
|
13
|
+
<!-- Modal — placed anywhere in <body>, outside normal flow -->
|
|
14
|
+
<div id="confirm-modal"
|
|
15
|
+
class="pp-modal-backdrop"
|
|
16
|
+
role="dialog"
|
|
17
|
+
aria-modal="true"
|
|
18
|
+
aria-labelledby="confirm-modal-title"
|
|
19
|
+
aria-describedby="confirm-modal-desc"
|
|
20
|
+
aria-hidden="true">
|
|
21
|
+
|
|
22
|
+
<div class="pp-modal">
|
|
23
|
+
<button class="pp-modal__close"
|
|
24
|
+
data-modal-close="confirm-modal"
|
|
25
|
+
aria-label="Close dialog">✕</button>
|
|
26
|
+
|
|
27
|
+
<p class="pp-modal__title" id="confirm-modal-title">Delete item</p>
|
|
28
|
+
<p class="pp-modal__description" id="confirm-modal-desc">
|
|
29
|
+
This action cannot be undone. The item will be permanently removed.
|
|
30
|
+
</p>
|
|
31
|
+
|
|
32
|
+
<ul class="pp-modal__actions">
|
|
33
|
+
<li>
|
|
34
|
+
<button class="pp-modal__action pp-modal__action--destructive">
|
|
35
|
+
Delete permanently
|
|
36
|
+
</button>
|
|
37
|
+
</li>
|
|
38
|
+
<li>
|
|
39
|
+
<button class="pp-modal__action pp-modal__action--cancel"
|
|
40
|
+
data-modal-close="confirm-modal">
|
|
41
|
+
Cancel
|
|
42
|
+
</button>
|
|
43
|
+
</li>
|
|
44
|
+
</ul>
|
|
45
|
+
</div>
|
|
46
|
+
|
|
47
|
+
</div>
|
|
48
|
+
<script src="dist/modal.js" defer></script>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Native `<dialog>` variant
|
|
52
|
+
|
|
53
|
+
```html
|
|
54
|
+
<dialog id="my-dialog" class="pp-modal-backdrop">
|
|
55
|
+
<div class="pp-modal">...</div>
|
|
56
|
+
</dialog>
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Use `ppModal.open('my-dialog')` — the shim calls `dialog.showModal()` automatically. Native `<dialog>` gets browser-managed focus trap and Escape handling in addition to the JS shim.
|
|
60
|
+
|
|
61
|
+
## Parts
|
|
62
|
+
|
|
63
|
+
| Class | Element | Description |
|
|
64
|
+
|---|---|---|
|
|
65
|
+
| `.pp-modal-backdrop` | `<div>` or `<dialog>` | Fixed overlay, `backdrop-filter: blur(8px) saturate(120%)` |
|
|
66
|
+
| `.pp-modal` | `<div>` | Container, `max-width: 420px`, frosted glass, `border-radius: 20px` |
|
|
67
|
+
| `.pp-modal__title` | `<p>` | Bold lg, white — must have `id` matching `aria-labelledby` |
|
|
68
|
+
| `.pp-modal__description` | `<p>` | sm, white 70% — must have `id` matching `aria-describedby` |
|
|
69
|
+
| `.pp-modal__actions` | `<ul>` | Pill button list, flex-column |
|
|
70
|
+
| `.pp-modal__action` | `<button>` | Full-width pill, white glass style |
|
|
71
|
+
| `.pp-modal__action--destructive` | modifier | Red tint, for irreversible actions |
|
|
72
|
+
| `.pp-modal__action--cancel` | modifier | Muted, for dismiss/cancel |
|
|
73
|
+
| `.pp-modal__close` | `<button>` | 28px circle in top-right corner |
|
|
74
|
+
|
|
75
|
+
## Open states
|
|
76
|
+
|
|
77
|
+
The backdrop is hidden by default. It becomes visible when **any one** of these is true:
|
|
78
|
+
|
|
79
|
+
| State | How to set |
|
|
80
|
+
|---|---|
|
|
81
|
+
| `[open]` attribute | Native `<dialog>` via `showModal()` |
|
|
82
|
+
| `.is-open` class | Added by JS or manually |
|
|
83
|
+
| `aria-hidden="false"` | Set by JS or manually |
|
|
84
|
+
|
|
85
|
+
## JS API
|
|
86
|
+
|
|
87
|
+
```js
|
|
88
|
+
// Programmatic control
|
|
89
|
+
ppModal.open('confirm-modal')
|
|
90
|
+
ppModal.close('confirm-modal')
|
|
91
|
+
ppModal.closeAll()
|
|
92
|
+
|
|
93
|
+
// Data attribute triggers (no JS calls needed in markup)
|
|
94
|
+
<button data-modal-open="confirm-modal">Open</button>
|
|
95
|
+
<button data-modal-close="confirm-modal">Close</button>
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
JS automatically:
|
|
99
|
+
- Sets `aria-hidden="false"` on open, `"true"` on close
|
|
100
|
+
- Traps focus (Tab/Shift+Tab stays inside modal)
|
|
101
|
+
- Closes on Escape key
|
|
102
|
+
- Closes on backdrop click (outside `.pp-modal`)
|
|
103
|
+
- Restores focus to the element that opened the modal
|
|
104
|
+
|
|
105
|
+
## ARIA requirements
|
|
106
|
+
|
|
107
|
+
| Attribute | Where | Value |
|
|
108
|
+
|---|---|---|
|
|
109
|
+
| `role="dialog"` | `.pp-modal-backdrop` | Required (implicit on `<dialog>`) |
|
|
110
|
+
| `aria-modal="true"` | `.pp-modal-backdrop` | Tells AT to ignore content behind the modal |
|
|
111
|
+
| `aria-labelledby` | `.pp-modal-backdrop` | ID of `.pp-modal__title` |
|
|
112
|
+
| `aria-describedby` | `.pp-modal-backdrop` | ID of `.pp-modal__description` |
|
|
113
|
+
| `aria-hidden` | `.pp-modal-backdrop` | `"true"` when closed, `"false"` when open |
|
|
114
|
+
| `aria-label="Close dialog"` | `.pp-modal__close` | Button has no text content |
|
|
115
|
+
| `id` | `.pp-modal__title` + `.pp-modal__description` | Must match `aria-labelledby`/`aria-describedby` |
|
|
116
|
+
|
|
117
|
+
## Common mistakes
|
|
118
|
+
|
|
119
|
+
- Omitting `aria-modal="true"` — without it, screen readers may read the page content behind the modal.
|
|
120
|
+
- Not setting `aria-hidden="true"` on the closed modal — AT will still find and read hidden modal content.
|
|
121
|
+
- Forgetting unique `id` values for title and description — if multiple modals are on the page, each title/description pair needs unique ids.
|
|
122
|
+
- Placing modals inside other interactive containers (forms, sections with `overflow: hidden`) — modals must be direct children of `<body>` or sit at the top of the stacking context.
|
|
123
|
+
- Using `display: none` to hide a modal that should use `aria-hidden` — the JS shim manages visibility via class and attribute, not inline style.
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Section
|
|
2
|
+
|
|
3
|
+
**Source:** `src/scss/section.scss` · No JS required.
|
|
4
|
+
|
|
5
|
+
Sections are full-viewport content blocks. Each section occupies `100dvh` minimum, centers its content, and has `scroll-margin-top: 56px` to account for the sticky 56px header when navigating via anchor links.
|
|
6
|
+
|
|
7
|
+
## Usage
|
|
8
|
+
|
|
9
|
+
```html
|
|
10
|
+
<section id="hero" class="pp-section pp-section--gradient">
|
|
11
|
+
<div class="pp-section__inner">
|
|
12
|
+
<h1 class="font-sans font-700 tracking-tight">Heading</h1>
|
|
13
|
+
<p class="font-sans font-400 text-lg leading-relaxed">Supporting copy.</p>
|
|
14
|
+
<button class="button">Call to action</button>
|
|
15
|
+
</div>
|
|
16
|
+
</section>
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Parts
|
|
20
|
+
|
|
21
|
+
| Class | Description |
|
|
22
|
+
|---|---|
|
|
23
|
+
| `.pp-section` | Full-viewport block — `min-height: 100dvh`, flex-column, centered, `padding: 4rem 2rem` |
|
|
24
|
+
| `.pp-section__inner` | Content wrapper — `max-width: 960px`, flex-column, `gap: 1.5rem`, `text-align: center` |
|
|
25
|
+
|
|
26
|
+
To left-align inner content, add `style="align-items:flex-start;"` or a utility class to `.pp-section__inner`.
|
|
27
|
+
|
|
28
|
+
## Variants
|
|
29
|
+
|
|
30
|
+
| Class | Background | Text color | Typical use |
|
|
31
|
+
|---|---|---|---|
|
|
32
|
+
| (none) | `$color-surface` (white) | `$color-on-surface` | Default content sections |
|
|
33
|
+
| `.pp-section--primary` | `$color-primary` (#e90111) | white | Promotional / CTA sections |
|
|
34
|
+
| `.pp-section--dark` | `$color-neutral-900` | `$color-neutral-50` | Feature highlights, testimonials |
|
|
35
|
+
| `.pp-section--muted` | `$color-neutral-100` | inherited | Alternating zebra rows |
|
|
36
|
+
| `.pp-section--gradient` | gold→red 135° | white | Hero sections |
|
|
37
|
+
|
|
38
|
+
## Custom scrollbar
|
|
39
|
+
|
|
40
|
+
`section.scss` defines the global page scrollbar:
|
|
41
|
+
- **Track:** transparent
|
|
42
|
+
- **Thumb:** gold→red gradient, no border-radius
|
|
43
|
+
- **Width:** 16px (webkit), `auto` for Firefox with `$gradient-end` color
|
|
44
|
+
|
|
45
|
+
## ARIA & accessibility
|
|
46
|
+
|
|
47
|
+
- Use semantic sectioning elements — `<section>`, `<main>`, `<article>`, `<aside>` — not `<div class="pp-section">`.
|
|
48
|
+
- Every `<section>` should have an accessible name: either a heading (`<h2>`) inside it, or `aria-labelledby` pointing to a heading, or `aria-label` if there is no visible heading.
|
|
49
|
+
- `id` attributes on sections enable anchor navigation — always include them for linkable sections.
|
|
50
|
+
- On `--primary` and `--gradient` variants, child text inherits white — ensure any inline colored text still meets 4.5:1 contrast against the section background.
|
|
51
|
+
|
|
52
|
+
## Common mistakes
|
|
53
|
+
|
|
54
|
+
- Do not nest `.pp-section` inside `.pp-section` — sections are top-level page blocks.
|
|
55
|
+
- `.pp-section__inner` centers by default. For left-aligned forms or tables, override `align-items` and `text-align` inline or with utilities.
|
|
56
|
+
- `scroll-margin-top: 56px` only works when navigating via anchor links (`href="#id"`). If using smooth-scroll JS, ensure it accounts for the header height too.
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# Select
|
|
2
|
+
|
|
3
|
+
**Source:** `src/scss/select.scss` · `src/js/select.js`
|
|
4
|
+
|
|
5
|
+
Two patterns: a CSS-restyled native `<select>` (simplest, most accessible), and a fully custom `.pp-select` dropdown (richer UI, more ARIA required). Use the native `<select>` unless you need custom option rendering.
|
|
6
|
+
|
|
7
|
+
## Native `<select>`
|
|
8
|
+
|
|
9
|
+
Automatically styled — no class required.
|
|
10
|
+
|
|
11
|
+
```html
|
|
12
|
+
<label for="framework">Framework</label>
|
|
13
|
+
<select id="framework" name="framework">
|
|
14
|
+
<option value="">Choose…</option>
|
|
15
|
+
<option value="peppertino">PeppertinoCSS</option>
|
|
16
|
+
<option value="tailwind">Tailwind</option>
|
|
17
|
+
</select>
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Always pair with a `<label>` — never rely on placeholder text alone for labelling.
|
|
21
|
+
|
|
22
|
+
## Custom `.pp-select`
|
|
23
|
+
|
|
24
|
+
```html
|
|
25
|
+
<div class="pp-select">
|
|
26
|
+
|
|
27
|
+
<button class="pp-select__trigger" type="button"
|
|
28
|
+
aria-label="Choose a color"
|
|
29
|
+
aria-haspopup="listbox"
|
|
30
|
+
aria-expanded="false"
|
|
31
|
+
aria-controls="color-panel">
|
|
32
|
+
<span class="pp-select__value">Choose a color</span>
|
|
33
|
+
<span class="pp-select__chevron" aria-hidden="true"></span>
|
|
34
|
+
</button>
|
|
35
|
+
|
|
36
|
+
<ul class="pp-select__panel" id="color-panel" role="listbox" aria-label="Colors">
|
|
37
|
+
|
|
38
|
+
<li role="option" aria-selected="false">
|
|
39
|
+
<button class="pp-select__option" data-value="red">Primary Red</button>
|
|
40
|
+
</li>
|
|
41
|
+
<li role="option" aria-selected="true">
|
|
42
|
+
<button class="pp-select__option is-selected" data-value="gold">Gradient Gold</button>
|
|
43
|
+
</li>
|
|
44
|
+
|
|
45
|
+
<!-- Divider between groups -->
|
|
46
|
+
<li role="separator" class="pp-select__divider"></li>
|
|
47
|
+
|
|
48
|
+
<!-- Option group -->
|
|
49
|
+
<li role="group" aria-label="Neutrals" style="list-style:none;">
|
|
50
|
+
<span class="pp-select__group-label">Neutrals</span>
|
|
51
|
+
<ul role="group" style="list-style:none;padding:0;margin:0;">
|
|
52
|
+
<li role="option" aria-selected="false">
|
|
53
|
+
<button class="pp-select__option" data-value="light">Light</button>
|
|
54
|
+
</li>
|
|
55
|
+
</ul>
|
|
56
|
+
</li>
|
|
57
|
+
|
|
58
|
+
</ul>
|
|
59
|
+
</div>
|
|
60
|
+
<script src="dist/select.js" defer></script>
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Parts
|
|
64
|
+
|
|
65
|
+
| Class | Element | Description |
|
|
66
|
+
|---|---|---|
|
|
67
|
+
| `.pp-select` | `<div>` | Wrapper — `position: relative` |
|
|
68
|
+
| `.pp-select__trigger` | `<button>` | Opens the panel — styled as an input |
|
|
69
|
+
| `.pp-select__value` | `<span>` | Displays current selection |
|
|
70
|
+
| `.pp-select__chevron` | `<span>` | Animated down arrow — rotates 180° when open |
|
|
71
|
+
| `.pp-select__panel` | `<ul>` | Dropdown list — `role="listbox"` |
|
|
72
|
+
| `.pp-select__option` | `<button>` | Option button inside `<li role="option">` |
|
|
73
|
+
| `.pp-select__divider` | `<li>` | `role="separator"` horizontal rule |
|
|
74
|
+
| `.pp-select__group-label` | `<span>` | Uppercase xs group heading |
|
|
75
|
+
|
|
76
|
+
## Sizes
|
|
77
|
+
|
|
78
|
+
| Class on `.pp-select` | Padding | Font |
|
|
79
|
+
|---|---|---|
|
|
80
|
+
| `.pp-select--sm` | compact | sm |
|
|
81
|
+
| (none) | default | base |
|
|
82
|
+
| `.pp-select--lg` | large | lg |
|
|
83
|
+
|
|
84
|
+
## Open states
|
|
85
|
+
|
|
86
|
+
The panel opens when any one of these is true:
|
|
87
|
+
|
|
88
|
+
- `.pp-select` has `.is-open`
|
|
89
|
+
- The trigger has `aria-expanded="true"`
|
|
90
|
+
- Focus is within `.pp-select` (CSS `:focus-within` fallback)
|
|
91
|
+
|
|
92
|
+
## ARIA requirements — critical details
|
|
93
|
+
|
|
94
|
+
| Element | Role | Additional required attributes |
|
|
95
|
+
|---|---|---|
|
|
96
|
+
| `.pp-select__trigger` | button (implicit) | `aria-haspopup="listbox"`, `aria-expanded`, `aria-controls` → panel id, `aria-label` |
|
|
97
|
+
| `.pp-select__panel` | `role="listbox"` | `aria-label` describing what is being selected |
|
|
98
|
+
| `<li>` wrapping each option | `role="option"` | `aria-selected="true/false"` — **on the `<li>`, not the inner `<button>`** |
|
|
99
|
+
| Divider `<li>` | `role="separator"` | — |
|
|
100
|
+
| Group `<li>` | `role="group"` | `aria-label` for group name |
|
|
101
|
+
|
|
102
|
+
**Critical:** `role="option"` must go on the `<li>` directly under `role="listbox"`. Placing it on the nested `<button>` breaks the required listbox → option ownership and triggers ARIA validation errors.
|
|
103
|
+
|
|
104
|
+
## Common mistakes
|
|
105
|
+
|
|
106
|
+
- Putting `role="option"` on the `<button>` instead of the `<li>` — breaks listbox ownership model.
|
|
107
|
+
- Omitting `aria-label` on the trigger — `<span class="pp-select__value">` text is not an accessible button name.
|
|
108
|
+
- Forgetting `aria-selected` on `<li role="option">` — AT cannot announce current selection without it.
|
|
109
|
+
- Using a bare `<span>` group label without wrapping in `<li role="group">` — leaves `<li>` elements outside valid parent context.
|
|
110
|
+
- Not updating `aria-expanded` on the trigger when the panel opens/closes — the JS shim handles this, but custom implementations must too.
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Switch
|
|
2
|
+
|
|
3
|
+
**Source:** `src/scss/switch.scss` · `src/js/switch.js`
|
|
4
|
+
|
|
5
|
+
iOS-style toggle switch. CSS provides the full visual baseline — the thumb slides via `translateX` driven by `aria-checked`. JS wires the toggle on click and Space key, and dispatches a CustomEvent.
|
|
6
|
+
|
|
7
|
+
## Full structure
|
|
8
|
+
|
|
9
|
+
```html
|
|
10
|
+
<!-- Off -->
|
|
11
|
+
<button class="pp-switch" role="switch" aria-checked="false" aria-label="Enable notifications"></button>
|
|
12
|
+
|
|
13
|
+
<!-- On -->
|
|
14
|
+
<button class="pp-switch" role="switch" aria-checked="true" aria-label="Dark mode"></button>
|
|
15
|
+
|
|
16
|
+
<!-- In a settings row -->
|
|
17
|
+
<label style="display:flex; justify-content:space-between; align-items:center; padding:0.875rem 1rem;">
|
|
18
|
+
<span>Push notifications</span>
|
|
19
|
+
<button class="pp-switch" role="switch" aria-checked="false" aria-label="Push notifications"></button>
|
|
20
|
+
</label>
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Required ARIA
|
|
24
|
+
|
|
25
|
+
| Attribute | Required | Value |
|
|
26
|
+
|---|---|---|
|
|
27
|
+
| `role="switch"` | Yes | Always |
|
|
28
|
+
| `aria-checked` | Yes | `"true"` or `"false"` |
|
|
29
|
+
| `aria-label` or `aria-labelledby` | Yes | Describes what the switch controls |
|
|
30
|
+
|
|
31
|
+
`aria-checked` is the source of truth for visual state — the thumb position and track color are both driven by this attribute. Without it, the switch has no visual state and no accessibility semantics.
|
|
32
|
+
|
|
33
|
+
## Size modifiers
|
|
34
|
+
|
|
35
|
+
| Class | Width | Height | Thumb | Thumb translate |
|
|
36
|
+
|---|---|---|---|---|
|
|
37
|
+
| `.pp-switch--sm` | 32px | 20px | 14×14px | 12px |
|
|
38
|
+
| (default) | 44px | 26px | 20×20px | 18px |
|
|
39
|
+
| `.pp-switch--lg` | 56px | 32px | 26×26px | 24px |
|
|
40
|
+
|
|
41
|
+
## JS API
|
|
42
|
+
|
|
43
|
+
`switch.js` auto-initialises all `[role="switch"]` and `.pp-switch` elements on `DOMContentLoaded`. No manual init needed.
|
|
44
|
+
|
|
45
|
+
**Event:**
|
|
46
|
+
|
|
47
|
+
```js
|
|
48
|
+
switchEl.addEventListener('pp:switch:change', (e) => {
|
|
49
|
+
console.log(e.detail.checked); // boolean
|
|
50
|
+
});
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
The event bubbles — listen at any ancestor.
|
|
54
|
+
|
|
55
|
+
**Manual toggle (if needed):**
|
|
56
|
+
|
|
57
|
+
```js
|
|
58
|
+
const sw = document.querySelector('.pp-switch');
|
|
59
|
+
sw.setAttribute('aria-checked', 'true');
|
|
60
|
+
// switch.js listens for direct aria-checked changes too
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Dark mode
|
|
64
|
+
|
|
65
|
+
Track background uses `--pp-neutral-300` (off) and `--pp-primary` (on) — both adapt automatically under `.dark`. No extra classes needed.
|
|
66
|
+
|
|
67
|
+
## Common mistakes
|
|
68
|
+
|
|
69
|
+
- Missing `aria-checked` — the switch has no visual state; both track color and thumb position depend on this attribute.
|
|
70
|
+
- Setting `type="checkbox"` instead of `role="switch"` on a `<button>` — use `<input type="checkbox">` with a custom styled label, or use `<button role="switch">` (never both at once).
|
|
71
|
+
- Omitting `aria-label` when the switch has no adjacent visible label — screen readers will announce "switch" with no description of what it controls.
|
|
72
|
+
- Using a `<div>` instead of `<button>` — `<button>` is keyboard focusable by default; `<div>` requires `tabindex="0"` and explicit keyboard handling.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Table
|
|
2
|
+
|
|
3
|
+
**Source:** `src/scss/table.scss` · No JS required.
|
|
4
|
+
|
|
5
|
+
Apple-style comparison tables with clean borders, alternating row shading, and equal-width columns defined by a modifier class. Designed for feature comparison and spec sheets — not for large data sets.
|
|
6
|
+
|
|
7
|
+
## Usage
|
|
8
|
+
|
|
9
|
+
```html
|
|
10
|
+
<table class="pp-table pp-table--cols-3">
|
|
11
|
+
<thead>
|
|
12
|
+
<tr>
|
|
13
|
+
<th scope="col">Feature</th>
|
|
14
|
+
<th scope="col">Standard</th>
|
|
15
|
+
<th scope="col">Pro</th>
|
|
16
|
+
</tr>
|
|
17
|
+
</thead>
|
|
18
|
+
<tbody>
|
|
19
|
+
<tr>
|
|
20
|
+
<td>Storage</td>
|
|
21
|
+
<td>256 GB</td>
|
|
22
|
+
<td>512 GB</td>
|
|
23
|
+
</tr>
|
|
24
|
+
<tr>
|
|
25
|
+
<td>Memory</td>
|
|
26
|
+
<td>8 GB</td>
|
|
27
|
+
<td>16 GB</td>
|
|
28
|
+
</tr>
|
|
29
|
+
</tbody>
|
|
30
|
+
</table>
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Column helpers
|
|
34
|
+
|
|
35
|
+
The column modifier sets `grid-template-columns` (or equivalent) so all columns share equal width. **One modifier is required** — without it the table renders with browser-default column sizing.
|
|
36
|
+
|
|
37
|
+
| Class | Columns |
|
|
38
|
+
|---|---|
|
|
39
|
+
| `.pp-table--cols-1` | 1 equal column |
|
|
40
|
+
| `.pp-table--cols-2` | 2 equal columns |
|
|
41
|
+
| `.pp-table--cols-3` | 3 equal columns |
|
|
42
|
+
| `.pp-table--cols-4` | 4 equal columns |
|
|
43
|
+
|
|
44
|
+
## Row label pattern
|
|
45
|
+
|
|
46
|
+
The first column is conventionally used as a row label (the "feature" column in a comparison table). No special class is needed — the alternating row shading and border styling applies uniformly.
|
|
47
|
+
|
|
48
|
+
```html
|
|
49
|
+
<tr>
|
|
50
|
+
<td>Chip</td> <!-- row label -->
|
|
51
|
+
<td>Apple M4</td>
|
|
52
|
+
<td>Apple M4 Pro</td>
|
|
53
|
+
</tr>
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## ARIA & accessibility
|
|
57
|
+
|
|
58
|
+
- Use `<th>` for all header cells, never `<td>` — this is required for screen readers to announce column/row context.
|
|
59
|
+
- Add `scope="col"` to column headers and `scope="row"` to row headers.
|
|
60
|
+
- For tables with both row and column headers, use `scope="rowgroup"` / `scope="colgroup"` as appropriate.
|
|
61
|
+
- Provide a `<caption>` if the table's purpose is not clear from surrounding text — this is the table's accessible name.
|
|
62
|
+
- Do not use tables for layout — only for genuinely tabular data.
|
|
63
|
+
- On mobile, consider whether the table needs horizontal scrolling. Wrap in a `<div style="overflow-x:auto;">` if it may overflow narrow viewports.
|
|
64
|
+
|
|
65
|
+
## Common mistakes
|
|
66
|
+
|
|
67
|
+
- Omitting the column modifier class produces unstyled column widths — always add `.pp-table--cols-N`.
|
|
68
|
+
- Using `<td>` for header cells breaks screen reader announcements of column/row context.
|
|
69
|
+
- Do not put interactive elements (buttons, selects) inside cells unless the table is genuinely an interactive data grid — in that case, full `role="grid"` semantics are required.
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# Tabs
|
|
2
|
+
|
|
3
|
+
**Source:** `src/scss/tabs.scss` · `src/js/tabs.js`
|
|
4
|
+
|
|
5
|
+
Pill-style tab bar. Each tab can optionally control a panel via `data-tab-target` / `data-tab-panel`. JS wires ARIA and handles keyboard navigation — CSS provides the full visual baseline without JS.
|
|
6
|
+
|
|
7
|
+
## With panels
|
|
8
|
+
|
|
9
|
+
```html
|
|
10
|
+
<div class="pp-tabs" role="tablist" aria-label="Account settings">
|
|
11
|
+
<button class="pp-tabs__item is-active" role="tab"
|
|
12
|
+
aria-selected="true" tabindex="0"
|
|
13
|
+
data-tab-target="general">
|
|
14
|
+
<i data-lucide="settings" aria-hidden="true"></i>
|
|
15
|
+
General
|
|
16
|
+
</button>
|
|
17
|
+
<button class="pp-tabs__item" role="tab"
|
|
18
|
+
aria-selected="false" tabindex="-1"
|
|
19
|
+
data-tab-target="privacy">
|
|
20
|
+
<i data-lucide="shield" aria-hidden="true"></i>
|
|
21
|
+
Privacy
|
|
22
|
+
</button>
|
|
23
|
+
<button class="pp-tabs__item" role="tab"
|
|
24
|
+
aria-selected="false" tabindex="-1"
|
|
25
|
+
data-tab-target="notifications">
|
|
26
|
+
<i data-lucide="bell" aria-hidden="true"></i>
|
|
27
|
+
Notifications
|
|
28
|
+
</button>
|
|
29
|
+
</div>
|
|
30
|
+
|
|
31
|
+
<div data-tab-panel="general" role="tabpanel">
|
|
32
|
+
<p>General settings content.</p>
|
|
33
|
+
</div>
|
|
34
|
+
<div data-tab-panel="privacy" role="tabpanel" hidden aria-hidden="true">
|
|
35
|
+
<p>Privacy settings content.</p>
|
|
36
|
+
</div>
|
|
37
|
+
<div data-tab-panel="notifications" role="tabpanel" hidden aria-hidden="true">
|
|
38
|
+
<p>Notification settings content.</p>
|
|
39
|
+
</div>
|
|
40
|
+
|
|
41
|
+
<script src="dist/tabs.js" defer></script>
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
JS automatically sets `aria-controls` on tabs and `aria-labelledby` on panels from the `data-tab-target` / `data-tab-panel` values.
|
|
45
|
+
|
|
46
|
+
## Without panels (display-only tabs)
|
|
47
|
+
|
|
48
|
+
```html
|
|
49
|
+
<div class="pp-tabs" role="tablist" aria-label="View mode">
|
|
50
|
+
<button class="pp-tabs__item is-active" role="tab" aria-selected="true" tabindex="0">Grid</button>
|
|
51
|
+
<button class="pp-tabs__item" role="tab" aria-selected="false" tabindex="-1">List</button>
|
|
52
|
+
</div>
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Omit `data-tab-target` and panels entirely — JS still wires ARIA states.
|
|
56
|
+
|
|
57
|
+
## Variants
|
|
58
|
+
|
|
59
|
+
| Class on `.pp-tabs` | Active tab style |
|
|
60
|
+
|---|---|
|
|
61
|
+
| (none) | Filled primary red pill |
|
|
62
|
+
| `.pp-tabs--outline` | Outline pill, primary border |
|
|
63
|
+
| `.pp-tabs--gradient` | Gradient fill (gold→red) |
|
|
64
|
+
| `.pp-tabs--gradient-outline` | Gradient outline |
|
|
65
|
+
|
|
66
|
+
## Sizes
|
|
67
|
+
|
|
68
|
+
| Class on `.pp-tabs` | Description |
|
|
69
|
+
|---|---|
|
|
70
|
+
| `.pp-tabs--sm` | Compact padding, sm font |
|
|
71
|
+
| (none) | Default |
|
|
72
|
+
| `.pp-tabs--lg` | Larger padding, lg font |
|
|
73
|
+
|
|
74
|
+
## Active state
|
|
75
|
+
|
|
76
|
+
The active tab has both `.is-active` class and `aria-selected="true"`. CSS uses both selectors — remove either and the visual state breaks.
|
|
77
|
+
|
|
78
|
+
Inactive tabs have `tabindex="-1"`. The active tab has `tabindex="0"`. This implements the **roving tabindex** pattern — only one tab is in the tab order at a time; arrow keys move between tabs.
|
|
79
|
+
|
|
80
|
+
## ARIA requirements
|
|
81
|
+
|
|
82
|
+
| Element | Required |
|
|
83
|
+
|---|---|
|
|
84
|
+
| `.pp-tabs` | `role="tablist"` + `aria-label` describing the tab group |
|
|
85
|
+
| `.pp-tabs__item` | `role="tab"` + `aria-selected="true/false"` + `tabindex="0/-1"` |
|
|
86
|
+
| Active tab | `aria-selected="true"` + `tabindex="0"` |
|
|
87
|
+
| Inactive tabs | `aria-selected="false"` + `tabindex="-1"` |
|
|
88
|
+
| Panel | `role="tabpanel"` + `aria-labelledby` (tab id) + `hidden` when inactive |
|
|
89
|
+
|
|
90
|
+
## Keyboard navigation
|
|
91
|
+
|
|
92
|
+
| Key | Action |
|
|
93
|
+
|---|---|
|
|
94
|
+
| `←` | Activate and focus previous tab |
|
|
95
|
+
| `→` | Activate and focus next tab |
|
|
96
|
+
| `Home` | Activate and focus first tab |
|
|
97
|
+
| `End` | Activate and focus last tab |
|
|
98
|
+
| `Tab` | Move focus out of the tablist to the active panel |
|
|
99
|
+
|
|
100
|
+
## Custom events
|
|
101
|
+
|
|
102
|
+
```js
|
|
103
|
+
document.querySelector('.pp-tabs').addEventListener('pp-tabs:change', (e) => {
|
|
104
|
+
console.log(e.detail.value); // data-tab-target value
|
|
105
|
+
console.log(e.detail.label); // visible tab text
|
|
106
|
+
});
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
## Common mistakes
|
|
110
|
+
|
|
111
|
+
- Omitting `aria-label` on the tablist — AT cannot identify what the tabs control without it.
|
|
112
|
+
- Setting all tabs to `tabindex="0"` — only the active tab should be in the tab order; arrow keys handle the rest.
|
|
113
|
+
- Forgetting `hidden` on inactive panels — they remain visible without it.
|
|
114
|
+
- Using `display:none` on panels instead of `hidden` — both work visually, but `hidden` is semantically cleaner and matches what JS sets.
|
|
115
|
+
- Placing tabs inside a `<ul>` — tabs use `<div role="tablist">` with `<button role="tab">` children; the list element is not needed and adds implicit list semantics.
|