@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.
- package/CHANGELOG.txt +249 -224
- package/LICENSE +21 -21
- package/MIGRATION.md +52 -52
- package/README.md +811 -764
- package/agents/peppertino/SKILL.md +84 -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 +83 -0
- package/agents/peppertino/components-ai-search.md +10 -0
- package/agents/peppertino/components-display.md +19 -0
- package/agents/peppertino/components-inputs.md +15 -0
- package/agents/peppertino/components-navigation.md +12 -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 +2177 -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,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
|
+
© 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.
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# Forms — Fieldset & Legend
|
|
2
|
+
|
|
3
|
+
**Source:** `src/scss/forms/fieldset.scss` · No JS required.
|
|
4
|
+
|
|
5
|
+
Groups related form controls under a named legend. `<fieldset>` + `<legend>` is the native equivalent of `role="group"` + `aria-labelledby` — always prefer the native elements. Screen readers announce the legend text before each child control, giving users context for the group.
|
|
6
|
+
|
|
7
|
+
## Usage
|
|
8
|
+
|
|
9
|
+
```html
|
|
10
|
+
<fieldset class="pp-fieldset">
|
|
11
|
+
<legend>Shipping address</legend>
|
|
12
|
+
|
|
13
|
+
<div class="pp-field">
|
|
14
|
+
<label class="pp-field__label" for="street">Street</label>
|
|
15
|
+
<input class="pp-field__input" type="text" id="street" name="street" />
|
|
16
|
+
</div>
|
|
17
|
+
|
|
18
|
+
<div class="pp-field">
|
|
19
|
+
<label class="pp-field__label" for="city">City</label>
|
|
20
|
+
<input class="pp-field__input" type="text" id="city" name="city" />
|
|
21
|
+
</div>
|
|
22
|
+
</fieldset>
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Variants
|
|
26
|
+
|
|
27
|
+
| Class on `<fieldset>` | Appearance | When to use |
|
|
28
|
+
|---|---|---|
|
|
29
|
+
| (none) | White bg, 1px border | Default grouping |
|
|
30
|
+
| `.pp-fieldset--ghost` | Transparent border, neutral-50 bg | Subtle grouping on muted sections |
|
|
31
|
+
| `.pp-fieldset--filled` | neutral-100 bg, neutral-200 border | Inset / filled form style |
|
|
32
|
+
| `.pp-fieldset--primary` | Primary accent border + glow | Active or focused group |
|
|
33
|
+
| `.pp-fieldset--error` | Error border + glow, legend turns red | Group-level validation error |
|
|
34
|
+
|
|
35
|
+
## Disabled group
|
|
36
|
+
|
|
37
|
+
```html
|
|
38
|
+
<fieldset class="pp-fieldset" disabled aria-disabled="true">
|
|
39
|
+
<legend>Billing address</legend>
|
|
40
|
+
<!-- all inputs inside are automatically disabled -->
|
|
41
|
+
</fieldset>
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
HTML `disabled` on `<fieldset>` disables all child form elements natively. `aria-disabled="true"` communicates the state to AT that may not respect the native attribute. The CSS adds `opacity: 0.5` and `pointer-events: none`.
|
|
45
|
+
|
|
46
|
+
## Legend sizes
|
|
47
|
+
|
|
48
|
+
Apply to the `<legend>` element (or any element with `.pp-legend` for non-fieldset groups):
|
|
49
|
+
|
|
50
|
+
| Class | Size | Style | When to use |
|
|
51
|
+
|---|---|---|---|
|
|
52
|
+
| `.pp-legend--sm` | xs | uppercase | Compact / dense layouts |
|
|
53
|
+
| (none) | sm | uppercase, semibold | Default |
|
|
54
|
+
| `.pp-legend--lg` | base | bold, no uppercase | Top-level section headings |
|
|
55
|
+
| `.pp-legend--inline` | — | flex row | Icon + legend text |
|
|
56
|
+
|
|
57
|
+
```html
|
|
58
|
+
<fieldset class="pp-fieldset pp-fieldset--primary">
|
|
59
|
+
<legend class="pp-legend pp-legend--inline">
|
|
60
|
+
<i data-lucide="credit-card" aria-hidden="true"></i>
|
|
61
|
+
Payment details
|
|
62
|
+
</legend>
|
|
63
|
+
<!-- controls -->
|
|
64
|
+
</fieldset>
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## How the float trick works
|
|
68
|
+
|
|
69
|
+
`<legend>` must be a direct DOM child of `<fieldset>` for correct AT semantics. A plain `display: block` legend would collapse into the top border. The CSS uses `float: left; width: 100%` to pull the legend out of normal flow while keeping it a DOM child, and `& + * { clear: both }` to push subsequent children below it.
|
|
70
|
+
|
|
71
|
+
**Do not** add `overflow: hidden` to `.pp-fieldset` — it would clear the float prematurely and break the layout.
|
|
72
|
+
|
|
73
|
+
## ARIA & accessibility
|
|
74
|
+
|
|
75
|
+
- Use `<fieldset>` + `<legend>` rather than `<div role="group">` + `<span>` — native semantics are more reliably supported across AT.
|
|
76
|
+
- The legend text is the accessible name for the group — keep it short and descriptive. Avoid generic names like "Section 1".
|
|
77
|
+
- For groups with a validation error, use `.pp-fieldset--error` and add a `.pp-field__message` inside the fieldset (not inside a specific field) to describe the group-level error. Set `aria-describedby` on the `<fieldset>` pointing to that message.
|
|
78
|
+
- Never nest `<fieldset>` inside `<fieldset>` in ways that confuse the group boundary — multiple levels of nesting are valid but each legend must clearly scope its group.
|
|
79
|
+
|
|
80
|
+
## Common mistakes
|
|
81
|
+
|
|
82
|
+
- Adding `overflow: hidden` to `.pp-fieldset` — breaks the float-based legend layout.
|
|
83
|
+
- Using `<h3>` or other headings as the legend — the `<legend>` element itself already acts as the group label; wrapping it in a heading creates redundant document structure.
|
|
84
|
+
- Omitting `aria-disabled="true"` when using the `disabled` attribute — some AT ignore the native `disabled` on fieldsets; the explicit ARIA attribute ensures the state is announced.
|
|
85
|
+
- Applying `pp-fieldset--error` without a visible error message — the color change alone does not communicate the error; always include descriptive text.
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# Forms — Form Instructions
|
|
2
|
+
|
|
3
|
+
**Source:** `src/scss/forms/form-instructions.scss` · No JS required.
|
|
4
|
+
|
|
5
|
+
Provides structured instructions before a form, and lightweight hints inside a form. Screen readers switch to "Forms Mode" when entering a `<form>` element and typically only announce form controls — content placed **before** the `<form>` is read in normal reading mode and is guaranteed to reach the user before they begin filling in fields.
|
|
6
|
+
|
|
7
|
+
## Pre-form instructions block
|
|
8
|
+
|
|
9
|
+
```html
|
|
10
|
+
<!-- ✅ BEFORE <form> — announced in normal reading mode -->
|
|
11
|
+
<div class="pp-form-instructions" role="note" aria-label="Form completion instructions">
|
|
12
|
+
<p class="pp-form-instructions__title">Before you begin</p>
|
|
13
|
+
<ul class="pp-form-instructions__list">
|
|
14
|
+
<li class="pp-form-instructions__item">
|
|
15
|
+
Fields marked <abbr aria-label="required" title="required">*</abbr> are required.
|
|
16
|
+
</li>
|
|
17
|
+
<li class="pp-form-instructions__item">
|
|
18
|
+
Dates must be entered as <code>DD/MM/YYYY</code>.
|
|
19
|
+
</li>
|
|
20
|
+
<li class="pp-form-instructions__item">
|
|
21
|
+
Passwords must be at least 8 characters including one number.
|
|
22
|
+
</li>
|
|
23
|
+
</ul>
|
|
24
|
+
</div>
|
|
25
|
+
|
|
26
|
+
<form>
|
|
27
|
+
<!-- form controls -->
|
|
28
|
+
</form>
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Use `role="alert"` instead of `role="note"` when showing an error summary that must interrupt the user immediately (e.g. after a failed submit).
|
|
32
|
+
|
|
33
|
+
## Variants
|
|
34
|
+
|
|
35
|
+
| Class on `.pp-form-instructions` | Border | Background | Text | When to use |
|
|
36
|
+
|---|---|---|---|---|
|
|
37
|
+
| (none) | primary left | primary tint | neutral-800 / neutral-600 | General instructions |
|
|
38
|
+
| `--neutral` | neutral-400 left | neutral-50 | inherited | Informational, low emphasis |
|
|
39
|
+
| `--warning` | warning left | warning tint | amber-800 | Caution — data may be irreversible |
|
|
40
|
+
| `--error` | error left | error tint | primary-dark | Error summary (pair with `role="alert"`) |
|
|
41
|
+
|
|
42
|
+
## In-form hint
|
|
43
|
+
|
|
44
|
+
A lightweight note inside the form for contextual guidance that applies to a section, not a single field.
|
|
45
|
+
|
|
46
|
+
```html
|
|
47
|
+
<form>
|
|
48
|
+
<p class="pp-form-hint">
|
|
49
|
+
<i data-lucide="info" aria-hidden="true"></i>
|
|
50
|
+
Changes to your billing address take effect on the next billing cycle.
|
|
51
|
+
</p>
|
|
52
|
+
|
|
53
|
+
<!-- fields -->
|
|
54
|
+
</form>
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Not a replacement for field-level `aria-describedby` hint text — use both where appropriate.
|
|
58
|
+
|
|
59
|
+
## Required-field legend
|
|
60
|
+
|
|
61
|
+
Place near the top of the form (or before it) to explain the required marker:
|
|
62
|
+
|
|
63
|
+
```html
|
|
64
|
+
<p class="pp-form-required-note">
|
|
65
|
+
Fields marked <abbr aria-label="required" title="required">*</abbr> are required.
|
|
66
|
+
</p>
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
The `<abbr>` uses `aria-label="required"` so screen readers say "required" instead of "asterisk".
|
|
70
|
+
|
|
71
|
+
## Choosing `role="note"` vs `role="alert"`
|
|
72
|
+
|
|
73
|
+
| Scenario | Role |
|
|
74
|
+
|---|---|
|
|
75
|
+
| Pre-form instructions on page load | `role="note"` |
|
|
76
|
+
| Format guidance, tips | `role="note"` |
|
|
77
|
+
| Error summary injected after failed submit | `role="alert"` |
|
|
78
|
+
| Validation summary (see [forms-validation.md](forms-validation.md)) | `role="alert"` |
|
|
79
|
+
|
|
80
|
+
`role="alert"` causes AT to interrupt the user and announce the content immediately. Use it only when the content is genuinely urgent — overuse desensitises users.
|
|
81
|
+
|
|
82
|
+
## ARIA & accessibility
|
|
83
|
+
|
|
84
|
+
- Pre-form instructions must be placed **before** `<form>` — not inside it. Inside a form, AT in Forms Mode may skip non-interactive content.
|
|
85
|
+
- Provide `aria-label` on the `.pp-form-instructions` block to give it an accessible name as a landmark-equivalent region.
|
|
86
|
+
- The bullet dots (via `::before`) are decorative — they carry no ARIA semantics. The `<li>` structure of `.pp-form-instructions__list` already communicates list membership to AT.
|
|
87
|
+
- Do not rely solely on color to distinguish instruction variants (WCAG 1.4.1) — the border and background change together with color, satisfying this requirement.
|
|
88
|
+
|
|
89
|
+
## Common mistakes
|
|
90
|
+
|
|
91
|
+
- Placing the instructions block inside `<form>` — screen readers in Forms Mode will likely skip it.
|
|
92
|
+
- Using `role="alert"` for static page-load instructions — this causes AT to interrupt the user unnecessarily; use `role="note"`.
|
|
93
|
+
- Forgetting `aria-label` on the instructions block — without it, AT has no name for the region.
|
|
94
|
+
- Using the `--error` variant without switching to `role="alert"` — the red styling alone does not cause AT to announce the content.
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# Forms — Label
|
|
2
|
+
|
|
3
|
+
**Source:** `src/scss/forms/label.scss` · No JS required.
|
|
4
|
+
|
|
5
|
+
Static, uneditable text displayed throughout the interface. Mirrors Apple's four-tier label color system and Dynamic Type scale. `.pp-label` is for display text — for form control labels that describe an input, use `<label for="id">` with `.pp-field__label` from [forms-text-field.md](forms-text-field.md).
|
|
6
|
+
|
|
7
|
+
## Importance tiers
|
|
8
|
+
|
|
9
|
+
Four tiers match Apple's `label`, `secondaryLabel`, `tertiaryLabel`, and `quaternaryLabel` system colors. Implemented as CSS custom properties on `:root` so they can be overridden at any scope.
|
|
10
|
+
|
|
11
|
+
| Class | CSS variable | Light color | Contrast on white |
|
|
12
|
+
|---|---|---|---|
|
|
13
|
+
| `.pp-label--primary` | `--pp-label-primary` | `#18181b` | 16.1:1 ✓ AAA |
|
|
14
|
+
| `.pp-label--secondary` | `--pp-label-secondary` | `#71717a` | 4.6:1 ✓ AA |
|
|
15
|
+
| `.pp-label--tertiary` | `--pp-label-tertiary` | `#a1a1aa` | 3.1:1 ✓ AA large text |
|
|
16
|
+
| `.pp-label--quaternary` | `--pp-label-quaternary` | `#d4d4d8` | Decorative only |
|
|
17
|
+
|
|
18
|
+
**Quaternary** (`#d4d4d8`) does not meet WCAG AA — use only for watermarks, placeholders, and purely decorative text where no information is conveyed.
|
|
19
|
+
|
|
20
|
+
```html
|
|
21
|
+
<span class="pp-label pp-label--primary">Main content label</span>
|
|
22
|
+
<span class="pp-label pp-label--secondary">Supporting information</span>
|
|
23
|
+
<span class="pp-label pp-label--tertiary">Unavailable or hint text</span>
|
|
24
|
+
<span class="pp-label pp-label--quaternary">Watermark copy</span>
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Dynamic Type scale
|
|
28
|
+
|
|
29
|
+
Mirrors Apple's text style categories. Combine with tier classes.
|
|
30
|
+
|
|
31
|
+
| Class | Size | Weight | Line height | Typical use |
|
|
32
|
+
|---|---|---|---|---|
|
|
33
|
+
| `.pp-label--headline` | 1.25rem / 20px | semibold | 1.25 | Section headings in views |
|
|
34
|
+
| `.pp-label--subheadline` | 1rem / 16px | medium | 1.4 | Sub-headings, group labels |
|
|
35
|
+
| `.pp-label--body` | 1rem / 16px | regular | 1.5 | Body copy in lists and views |
|
|
36
|
+
| `.pp-label--callout` | 0.875rem / 14px | regular | 1.5 | Supporting copy, captions |
|
|
37
|
+
| `.pp-label--footnote` | 0.75rem / 12px | regular | 1.4 | Legal text, footnotes |
|
|
38
|
+
| `.pp-label--caption` | 0.75rem / 12px | medium, uppercase | 1.4 | Column headers, eyebrows |
|
|
39
|
+
|
|
40
|
+
```html
|
|
41
|
+
<span class="pp-label pp-label--headline pp-label--primary">
|
|
42
|
+
Storage
|
|
43
|
+
</span>
|
|
44
|
+
<span class="pp-label pp-label--callout pp-label--secondary">
|
|
45
|
+
Manage your storage and iCloud settings.
|
|
46
|
+
</span>
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Modifiers
|
|
50
|
+
|
|
51
|
+
### Selectable
|
|
52
|
+
|
|
53
|
+
Per Apple HIG: "make useful label text selectable" for content like error codes, IP addresses, and serial numbers.
|
|
54
|
+
|
|
55
|
+
```html
|
|
56
|
+
<span class="pp-label pp-label--selectable pp-label--body">
|
|
57
|
+
192.168.1.1
|
|
58
|
+
</span>
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`user-select: text` and `cursor: text` are set. Without this modifier, labels have `user-select: none`.
|
|
62
|
+
|
|
63
|
+
### Truncation
|
|
64
|
+
|
|
65
|
+
```html
|
|
66
|
+
<span class="pp-label pp-label--truncate pp-label--body" style="max-width: 200px;">
|
|
67
|
+
This text is too long and will be truncated with an ellipsis.
|
|
68
|
+
</span>
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Requires `display: block` (set by `--truncate`) and a constrained width on the element or a parent.
|
|
72
|
+
|
|
73
|
+
## Icon + label row
|
|
74
|
+
|
|
75
|
+
The `.pp-label-row` wrapper creates an inline flex row for symbol + text pairings, following Apple's icon + label convention.
|
|
76
|
+
|
|
77
|
+
```html
|
|
78
|
+
<span class="pp-label-row pp-label pp-label--body">
|
|
79
|
+
<i data-lucide="wifi" aria-hidden="true"></i>
|
|
80
|
+
Wi-Fi Connected
|
|
81
|
+
</span>
|
|
82
|
+
|
|
83
|
+
<span class="pp-label-row pp-label pp-label--callout pp-label--secondary">
|
|
84
|
+
<i data-lucide="battery-charging" aria-hidden="true"></i>
|
|
85
|
+
Charging — 84%
|
|
86
|
+
</span>
|
|
87
|
+
|
|
88
|
+
<span class="pp-label-row pp-label pp-label--callout pp-label--tertiary">
|
|
89
|
+
<i data-lucide="bluetooth" aria-hidden="true"></i>
|
|
90
|
+
Bluetooth unavailable
|
|
91
|
+
</span>
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Icons in label rows must be `aria-hidden="true"` — they are decorative; the text conveys the meaning.
|
|
95
|
+
|
|
96
|
+
## ARIA & accessibility
|
|
97
|
+
|
|
98
|
+
- `.pp-label` is for **display text** — do not confuse it with `<label for="id">` which is for form control association.
|
|
99
|
+
- `role="label"` is not a valid ARIA role — do not add it.
|
|
100
|
+
- Labels have `user-select: none` by default (they are read, not copied). Apply `--selectable` only when the content is useful to copy.
|
|
101
|
+
- Quaternary labels must not carry meaningful information — if a user needs to read it, use a higher tier with sufficient contrast.
|
|
102
|
+
- When a label describes state (available, unavailable, loading), pair the color tier with an icon or text that conveys the same state — do not rely on color alone (WCAG 1.4.1).
|
|
103
|
+
- Screen readers announce `.pp-label` text normally — no additional ARIA needed for static display labels.
|
|
104
|
+
|
|
105
|
+
## Common mistakes
|
|
106
|
+
|
|
107
|
+
- Using `.pp-label` instead of `<label for="id">` for form controls — `.pp-label` has no association with inputs.
|
|
108
|
+
- Using `.pp-label--quaternary` for informational text — contrast is too low for content that must be read.
|
|
109
|
+
- Omitting `aria-hidden="true"` on icons in `.pp-label-row` — AT will attempt to announce the SVG, producing noise like "wifi graphic".
|
|
110
|
+
- Combining `--truncate` without a constrained parent width — text will not truncate without a width boundary.
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# Forms — Text Field
|
|
2
|
+
|
|
3
|
+
**Source:** `src/scss/forms/text-field.scss`
|
|
4
|
+
JS optional — `validation.js` auto-wires `aria-describedby` on init. All visual states are CSS-only, driven by classes and ARIA attributes.
|
|
5
|
+
|
|
6
|
+
## Full structure
|
|
7
|
+
|
|
8
|
+
```html
|
|
9
|
+
<div class="pp-field">
|
|
10
|
+
|
|
11
|
+
<label class="pp-field__label" for="email">
|
|
12
|
+
Email address
|
|
13
|
+
<abbr class="pp-field__required" aria-label="required" title="required"></abbr>
|
|
14
|
+
</label>
|
|
15
|
+
|
|
16
|
+
<input class="pp-field__input"
|
|
17
|
+
type="email"
|
|
18
|
+
id="email"
|
|
19
|
+
name="email"
|
|
20
|
+
placeholder="you@example.com"
|
|
21
|
+
required
|
|
22
|
+
aria-required="true"
|
|
23
|
+
aria-describedby="email-hint email-msg"
|
|
24
|
+
autocomplete="email" />
|
|
25
|
+
|
|
26
|
+
<span class="pp-field__hint" id="email-hint">
|
|
27
|
+
We'll only use this for account notifications.
|
|
28
|
+
</span>
|
|
29
|
+
|
|
30
|
+
<!-- Message is hidden until a validation state is applied -->
|
|
31
|
+
<span class="pp-field__message" id="email-msg" role="alert"></span>
|
|
32
|
+
|
|
33
|
+
</div>
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Parts
|
|
37
|
+
|
|
38
|
+
| Class | Element | Typography | Notes |
|
|
39
|
+
|---|---|---|---|
|
|
40
|
+
| `.pp-field` | `<div>` | — | Flex-column, `gap: 0.25rem` |
|
|
41
|
+
| `.pp-field__label` | `<label>` | sm, medium, neutral-700 | `for` must match input `id` |
|
|
42
|
+
| `.pp-field__required` | `<abbr>` | sm, semibold, primary-dark | `aria-label="required"` overrides "asterisk" |
|
|
43
|
+
| `.pp-field__optional` | `<span>` | xs, regular, neutral-400 | No ARIA needed — decorative |
|
|
44
|
+
| `.pp-field__input` | `<input>` | base, regular | Any `type` attribute works |
|
|
45
|
+
| `.pp-field__textarea` | `<textarea>` | base, regular | Resizable vertically, `min-height: 96px` |
|
|
46
|
+
| `.pp-field__hint` | `<span>` | xs, regular, neutral-600 | Must have `id`; wire via `aria-describedby` |
|
|
47
|
+
| `.pp-field__message` | `<span>` | xs, medium | Must have `id`; `role="alert"` on error messages |
|
|
48
|
+
| `.pp-field__count` | `<span>` | xs, neutral-400 | Character counter — add `aria-live="polite"` |
|
|
49
|
+
|
|
50
|
+
## Optional field
|
|
51
|
+
|
|
52
|
+
```html
|
|
53
|
+
<label class="pp-field__label" for="company">
|
|
54
|
+
Company
|
|
55
|
+
<span class="pp-field__optional">optional</span>
|
|
56
|
+
</label>
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Do not use both `--required` and `--optional` on the same label.
|
|
60
|
+
|
|
61
|
+
## Textarea
|
|
62
|
+
|
|
63
|
+
```html
|
|
64
|
+
<div class="pp-field">
|
|
65
|
+
<label class="pp-field__label" for="bio">Bio</label>
|
|
66
|
+
<textarea class="pp-field__textarea" id="bio" name="bio"
|
|
67
|
+
aria-describedby="bio-hint bio-count"
|
|
68
|
+
maxlength="200"></textarea>
|
|
69
|
+
<div style="display:flex; justify-content:space-between; align-items:center;">
|
|
70
|
+
<span class="pp-field__hint" id="bio-hint">Tell us about yourself.</span>
|
|
71
|
+
<span class="pp-field__count" id="bio-count" aria-live="polite">0 / 200</span>
|
|
72
|
+
</div>
|
|
73
|
+
</div>
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Validation states
|
|
77
|
+
|
|
78
|
+
All states are on the `.pp-field` wrapper. The CSS then targets `.pp-field__input`, `.pp-field__textarea`, and `.pp-field__message` inside it.
|
|
79
|
+
|
|
80
|
+
| Class on `.pp-field` | Border | Message text color | When to use |
|
|
81
|
+
|---|---|---|---|
|
|
82
|
+
| `.pp-field--error` | `$color-error` | primary-dark (#a8000c, 7.0:1) | Invalid input |
|
|
83
|
+
| `.pp-field--success` | `$color-success` | green-700 (#15803d, 5.9:1) | Valid, confirmed |
|
|
84
|
+
| `.pp-field--warning` | `$color-warning` | amber-800 (#92400e, 7.6:1) | Approaching limit, caution |
|
|
85
|
+
| `.pp-field--validating` | neutral-300 | — | Async check pending |
|
|
86
|
+
|
|
87
|
+
Note: `$color-error` (#ef4444) is 3.0:1 on white — used for borders and icons only. Error **text** uses `$color-primary-dark` (#a8000c, 7.0:1) to meet WCAG AA.
|
|
88
|
+
|
|
89
|
+
## Icon wrap
|
|
90
|
+
|
|
91
|
+
```html
|
|
92
|
+
<!-- Leading icon -->
|
|
93
|
+
<div class="pp-field__input-wrap">
|
|
94
|
+
<span class="pp-field__icon" aria-hidden="true">
|
|
95
|
+
<i data-lucide="search"></i>
|
|
96
|
+
</span>
|
|
97
|
+
<input class="pp-field__input" type="search" id="q" />
|
|
98
|
+
</div>
|
|
99
|
+
|
|
100
|
+
<!-- Trailing icon -->
|
|
101
|
+
<div class="pp-field__input-wrap pp-field__input-wrap--trail">
|
|
102
|
+
<input class="pp-field__input" type="text" id="code" />
|
|
103
|
+
<span class="pp-field__icon pp-field__icon--trail" aria-hidden="true">
|
|
104
|
+
<i data-lucide="copy"></i>
|
|
105
|
+
</span>
|
|
106
|
+
</div>
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Icons in the wrap are decorative — always `aria-hidden="true"`. If the icon is interactive (e.g. a clear button), it must be a `<button>` with an `aria-label`.
|
|
110
|
+
|
|
111
|
+
## Sizes
|
|
112
|
+
|
|
113
|
+
| Class on `.pp-field` | Padding | Font | Radius |
|
|
114
|
+
|---|---|---|---|
|
|
115
|
+
| `.pp-field--sm` | compact | sm | base |
|
|
116
|
+
| (none) | `10px 1rem` | base | md |
|
|
117
|
+
| `.pp-field--lg` | `0.75rem 1.25rem` | lg | lg |
|
|
118
|
+
|
|
119
|
+
## ARIA requirements
|
|
120
|
+
|
|
121
|
+
- `<label for="id">` must match the input's `id` — never omit this association.
|
|
122
|
+
- `aria-required="true"` alongside HTML `required` — some older AT do not read the native attribute.
|
|
123
|
+
- `aria-describedby` should reference **all** descriptive elements: hint id, message id, character count id — space-separated.
|
|
124
|
+
- `aria-invalid="true"` on the input when in error state; `"false"` when successfully validated.
|
|
125
|
+
- Error `.pp-field__message` should carry `role="alert"` so it is announced when dynamically injected.
|
|
126
|
+
- `aria-live="polite"` on character counters so updates are announced without interrupting.
|
|
127
|
+
|
|
128
|
+
## Common mistakes
|
|
129
|
+
|
|
130
|
+
- Omitting `for` / `id` association — the label is not programmatically linked to the input; AT announces "unlabelled".
|
|
131
|
+
- Putting `role="alert"` on a hint — hints are static; `role="alert"` should only be on elements that change dynamically to report an error.
|
|
132
|
+
- Using a placeholder as the only label — placeholders disappear on input and are not a substitute for a visible `<label>`.
|
|
133
|
+
- Wiring `aria-describedby` to the label id — the label is already announced via `for`/`id` association; `aria-describedby` is for additional descriptions (hint, error).
|
|
134
|
+
- Forgetting to update `aria-invalid` when clearing an error — leaving `aria-invalid="true"` after a field is corrected causes AT to announce it as still invalid.
|