@auriel/peppertino 0.4.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 -136
- package/LICENSE +21 -21
- package/MIGRATION.md +52 -0
- package/README.md +773 -622
- 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 +41 -4
- package/dist/accordion.js.map +2 -2
- package/dist/alert.js +26 -0
- package/dist/alert.js.map +7 -0
- package/dist/carousel.js +4 -0
- package/dist/carousel.js.map +2 -2
- package/dist/header.js +1 -0
- package/dist/header.js.map +2 -2
- package/dist/main.css +3610 -1343
- package/dist/main.css.map +1 -1
- package/dist/main.min.css +1 -0
- package/dist/modal.js +2 -0
- package/dist/modal.js.map +2 -2
- package/dist/peppertino.js +244 -15
- package/dist/peppertino.js.map +3 -3
- package/dist/select.js +2 -4
- package/dist/select.js.map +2 -2
- package/dist/switch.js +29 -0
- package/dist/switch.js.map +7 -0
- package/dist/tabs.js +27 -7
- package/dist/tabs.js.map +2 -2
- package/dist/theme.js +47 -0
- package/dist/theme.js.map +7 -0
- package/dist/toast.js +69 -0
- package/dist/toast.js.map +7 -0
- package/dist/validation.js.map +1 -1
- package/icon.svg +4 -0
- package/index.html +2172 -1902
- package/package.json +28 -26
- package/scripts/hex-to-hsl.mjs +75 -0
- package/scripts/lint-bem.mjs +53 -0
- package/scripts/lint-colors.mjs +87 -0
- package/site.webmanifest +18 -0
- package/src/js/accordion.js +105 -61
- package/src/js/alert.js +28 -0
- package/src/js/carousel.js +153 -148
- package/src/js/header.js +85 -84
- package/src/js/modal.js +138 -134
- package/src/js/peppertino.js +15 -11
- package/src/js/select.js +101 -103
- package/src/js/switch.js +28 -0
- package/src/js/tabs.js +104 -94
- package/src/js/theme.js +47 -0
- package/src/js/toast.js +79 -0
- 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 -204
- package/src/scss/badge.scss +90 -0
- package/src/scss/base.scss +511 -305
- package/src/scss/button.scss +119 -121
- package/src/scss/card.scss +121 -121
- package/src/scss/carousel.scss +303 -313
- package/src/scss/code-block.scss +22 -0
- package/src/scss/counter.scss +5 -0
- package/src/scss/dark-mode.scss +514 -474
- 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 -20
- 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 -0
- 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 -0
- package/src/scss/tooltip.scss +126 -0
- 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,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.
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
# Forms — Validation
|
|
2
|
+
|
|
3
|
+
**Source:** `src/scss/forms/validation.scss` · `src/js/validation.js`
|
|
4
|
+
|
|
5
|
+
All visual validation states are driven by CSS classes and ARIA attributes. The `ppValidation` JS API is optional — set the same attributes and classes from your own code and the CSS responds identically. This separation means the CSS framework is fully usable without any PeppertinoCSS JS.
|
|
6
|
+
|
|
7
|
+
## How state is communicated
|
|
8
|
+
|
|
9
|
+
| What changes | CSS trigger | ARIA trigger |
|
|
10
|
+
|---|---|---|
|
|
11
|
+
| Red border on input | `.pp-field--error` on wrapper | `aria-invalid="true"` on input |
|
|
12
|
+
| Green border on input | `.pp-field--success` on wrapper | `aria-invalid="false"` on input |
|
|
13
|
+
| Amber border on input | `.pp-field--warning` on wrapper | — |
|
|
14
|
+
| Spinner on input | `.pp-field--validating` on wrapper | (remove `aria-invalid`) |
|
|
15
|
+
| Error text color | `.pp-field--error` → `.pp-field__message` | — |
|
|
16
|
+
|
|
17
|
+
Both CSS class and ARIA attribute selectors are independent — setting only the ARIA attribute triggers the border color; setting only the class triggers the full state styling including message color.
|
|
18
|
+
|
|
19
|
+
## Native HTML5 validation opt-in
|
|
20
|
+
|
|
21
|
+
```html
|
|
22
|
+
<div class="pp-field pp-field--validate">
|
|
23
|
+
<label class="pp-field__label" for="email">Email</label>
|
|
24
|
+
<input class="pp-field__input" type="email" id="email"
|
|
25
|
+
required aria-required="true" />
|
|
26
|
+
<span class="pp-field__hint">Enter a valid email address.</span>
|
|
27
|
+
</div>
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
`.pp-field--validate` enables `:valid` / `:invalid` pseudo-class styling. Without this class, fields are never styled by browser validation on page load — preventing red borders on untouched required fields.
|
|
31
|
+
|
|
32
|
+
Modern browsers also support `:user-valid` / `:user-invalid` which only style after the user has interacted. PeppertinoCSS handles both as progressive enhancement.
|
|
33
|
+
|
|
34
|
+
## `aria-invalid` attribute selectors
|
|
35
|
+
|
|
36
|
+
These work without `.pp-field--validate`, without JS, and without adding any class:
|
|
37
|
+
|
|
38
|
+
```html
|
|
39
|
+
<input class="pp-field__input" aria-invalid="true" /> <!-- red border + red focus ring -->
|
|
40
|
+
<input class="pp-field__input" aria-invalid="false" /> <!-- green border + green focus ring -->
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
This is the recommended approach for server-rendered validation — set `aria-invalid` in your server template and the CSS handles the rest.
|
|
44
|
+
|
|
45
|
+
## Validation summary
|
|
46
|
+
|
|
47
|
+
A linked error list placed before or at the top of the form. Use `role="alert"` so it is announced immediately when it appears (e.g. after a failed submit). Hidden by default.
|
|
48
|
+
|
|
49
|
+
```html
|
|
50
|
+
<!-- Ideally before <form> or at the very top of it -->
|
|
51
|
+
<div class="pp-validation-summary" role="alert"
|
|
52
|
+
aria-label="Form errors" id="my-summary">
|
|
53
|
+
<p class="pp-validation-summary__title">
|
|
54
|
+
<i data-lucide="circle-x" aria-hidden="true"></i>
|
|
55
|
+
2 errors prevented this form from being submitted
|
|
56
|
+
</p>
|
|
57
|
+
<ul class="pp-validation-summary__list">
|
|
58
|
+
<!-- ppValidation.setSummary() populates this, or do it yourself -->
|
|
59
|
+
<li class="pp-validation-summary__item">
|
|
60
|
+
<a href="#email">Email address is not valid.</a>
|
|
61
|
+
</li>
|
|
62
|
+
<li class="pp-validation-summary__item">
|
|
63
|
+
<a href="#password">Password must be at least 8 characters.</a>
|
|
64
|
+
</li>
|
|
65
|
+
</ul>
|
|
66
|
+
</div>
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Show by adding `.is-visible` or setting `aria-hidden="false"`. When `ppValidation.setSummary()` shows the summary it also moves focus to it, so the AT user is immediately taken to the error list.
|
|
70
|
+
|
|
71
|
+
Each error item should link to the offending field via `href="#field-id"`. Clicking the link focuses the field (handled by the JS shim, or implement yourself).
|
|
72
|
+
|
|
73
|
+
## Confirmation checkbox (WCAG 3.3.4)
|
|
74
|
+
|
|
75
|
+
For irreversible actions (permanent deletion, financial transactions), require explicit user confirmation:
|
|
76
|
+
|
|
77
|
+
```html
|
|
78
|
+
<form id="delete-form">
|
|
79
|
+
<label class="pp-confirm pp-confirm--destructive">
|
|
80
|
+
<input class="pp-confirm__input" type="checkbox"
|
|
81
|
+
id="confirm-delete"
|
|
82
|
+
aria-describedby="confirm-delete-desc" />
|
|
83
|
+
<span class="pp-confirm__label" id="confirm-delete-desc">
|
|
84
|
+
I understand that deleting my account is permanent and all data will be removed.
|
|
85
|
+
</span>
|
|
86
|
+
</label>
|
|
87
|
+
|
|
88
|
+
<button class="button-error pp-submit--gated" type="submit">
|
|
89
|
+
Delete account
|
|
90
|
+
</button>
|
|
91
|
+
</form>
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
`.pp-submit--gated` is disabled via CSS `:has()` until the checkbox inside the same `<form>` is checked — no JS required. Add `form:has(...)` is the selector pattern; it requires the button and checkbox to share a `<form>` ancestor.
|
|
95
|
+
|
|
96
|
+
## Variants
|
|
97
|
+
|
|
98
|
+
| Class on `.pp-confirm` | Border | Background | Label color |
|
|
99
|
+
|---|---|---|---|
|
|
100
|
+
| (none) | neutral-200 → primary when checked | neutral-50 | neutral-700 |
|
|
101
|
+
| `.pp-confirm--destructive` | error-tint → error when checked | error-tint | primary-dark |
|
|
102
|
+
|
|
103
|
+
## JS API — `ppValidation`
|
|
104
|
+
|
|
105
|
+
All methods are optional. The CSS responds to the classes and attributes regardless of how they are set.
|
|
106
|
+
|
|
107
|
+
```js
|
|
108
|
+
// Mark a field as invalid — adds .pp-field--error, aria-invalid="true",
|
|
109
|
+
// creates/updates .pp-field__message, updates aria-describedby
|
|
110
|
+
ppValidation.setError(inputEl, 'Email address is not valid.')
|
|
111
|
+
|
|
112
|
+
// Remove error state — .pp-field--error removed, aria-invalid="false",
|
|
113
|
+
// message text cleared
|
|
114
|
+
ppValidation.clearError(inputEl)
|
|
115
|
+
|
|
116
|
+
// Mark as successfully validated
|
|
117
|
+
ppValidation.setSuccess(inputEl, 'Username is available.')
|
|
118
|
+
|
|
119
|
+
// Mark as pending async check — adds .pp-field--validating, removes aria-invalid
|
|
120
|
+
ppValidation.setValidating(inputEl)
|
|
121
|
+
|
|
122
|
+
// Populate summary, show it, move focus to it
|
|
123
|
+
// errors: [{ input: Element | 'id-string', message: 'Error text' }]
|
|
124
|
+
ppValidation.setSummary(errors, summaryEl)
|
|
125
|
+
// → pass empty array to hide the summary
|
|
126
|
+
ppValidation.setSummary([], summaryEl)
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Custom events fired on the `.pp-field` element:
|
|
130
|
+
|
|
131
|
+
| Event | When | Detail |
|
|
132
|
+
|---|---|---|
|
|
133
|
+
| `pp-field:error` | `setError()` is called | `{ input, message }` |
|
|
134
|
+
| `pp-field:clear` | `clearError()` is called | `{ input }` |
|
|
135
|
+
|
|
136
|
+
## Auto-init
|
|
137
|
+
|
|
138
|
+
On `DOMContentLoaded`, `validation.js` scans all `.pp-field` elements and auto-wires `aria-describedby` from each input to its `.pp-field__hint` and `.pp-field__message` elements — merging with any existing `aria-describedby` values rather than overwriting them.
|
|
139
|
+
|
|
140
|
+
## ARIA requirements
|
|
141
|
+
|
|
142
|
+
- `role="alert"` on the summary — causes AT to announce it immediately when `.is-visible` makes it appear.
|
|
143
|
+
- `aria-invalid="true"` on each invalid input — required for AT to identify the field as erroneous.
|
|
144
|
+
- Confirmation checkboxes must have a programmatically associated visible label — `aria-describedby` pointing to the label text is sufficient; do not rely on placeholder or tooltip.
|
|
145
|
+
- Error message text must identify which field has the error when the message appears outside the field context (e.g. in the summary).
|
|
146
|
+
|
|
147
|
+
## Common mistakes
|
|
148
|
+
|
|
149
|
+
- Using `role="alert"` for static page-load instructions — this interrupts users unnecessarily; use `role="note"` for content present on load.
|
|
150
|
+
- Not focusing the summary after showing it — AT users will not know the summary appeared unless focus moves to it; `ppValidation.setSummary()` handles this.
|
|
151
|
+
- Leaving `aria-invalid="true"` after correcting an error — AT continues to announce the field as invalid; always call `clearError()` or set `aria-invalid="false"` after correction.
|
|
152
|
+
- Using `.pp-submit--gated` without the button inside a `<form>` that contains the `.pp-confirm__input` — the CSS `:has()` selector requires both to share a form ancestor.
|
|
153
|
+
- Setting only the CSS class without `aria-invalid` — the border color changes but AT still does not know the field is invalid.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# Gradient Text
|
|
2
|
+
|
|
3
|
+
**Source:** `src/scss/gradient.scss` · No JS required.
|
|
4
|
+
|
|
5
|
+
Applies the PeppertinoCSS signature gradient (gold `#ffcf67` → red `#ea5753` at 135°) clipped to text using `-webkit-background-clip: text` and `color: transparent`.
|
|
6
|
+
|
|
7
|
+
## Usage
|
|
8
|
+
|
|
9
|
+
```html
|
|
10
|
+
<h1 class="pp-gradient-text font-sans font-700 tracking-tight">PeppertinoCSS</h1>
|
|
11
|
+
<p class="pp-gradient-text font-sans font-400 text-xl">The quick brown fox.</p>
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Works on any element. Combine freely with typography utility classes for size, weight, and tracking.
|
|
15
|
+
|
|
16
|
+
## How it works
|
|
17
|
+
|
|
18
|
+
```css
|
|
19
|
+
.pp-gradient-text {
|
|
20
|
+
background: linear-gradient(135deg, #ffcf67, #ea5753);
|
|
21
|
+
-webkit-background-clip: text;
|
|
22
|
+
-webkit-text-fill-color: transparent;
|
|
23
|
+
background-clip: text;
|
|
24
|
+
color: transparent;
|
|
25
|
+
}
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
`color: transparent` is the fallback for browsers that do not support `background-clip: text` — text becomes invisible in that case. All modern browsers support this.
|
|
29
|
+
|
|
30
|
+
## ARIA & accessibility
|
|
31
|
+
|
|
32
|
+
- Gradient text meets WCAG contrast only when used on a **white or very light background**. The effective perceived contrast of gradient text varies across the gradient — do not use gradient text for body copy or form labels.
|
|
33
|
+
- Ideal uses: large headings (≥ 24px), hero text, display copy — where the text weight and size compensate for variable contrast.
|
|
34
|
+
- Do not use gradient text for error messages, warnings, or any text that conveys state — color alone cannot communicate meaning (WCAG 1.4.1).
|
|
35
|
+
- Screen readers read gradient text normally — no additional ARIA needed.
|
|
36
|
+
|
|
37
|
+
## Common mistakes
|
|
38
|
+
|
|
39
|
+
- `.pp-gradient-text` sets `color: transparent` which overrides any `color` utility class. Do not combine with color attempts — use size and weight classes only.
|
|
40
|
+
- Does not work on `<input>` or `<textarea>` placeholder text — use only on static text elements.
|
|
41
|
+
- On dark section backgrounds, the gold end of the gradient may have insufficient contrast. Use on `pp-section--dark` only for large, heavy display text.
|