@auriel/peppertino 0.5.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (134) hide show
  1. package/CHANGELOG.txt +249 -224
  2. package/LICENSE +21 -21
  3. package/MIGRATION.md +52 -52
  4. package/README.md +811 -764
  5. package/agents/peppertino/SKILL.md +84 -0
  6. package/agents/peppertino/accordion.md +134 -0
  7. package/agents/peppertino/alert.md +116 -0
  8. package/agents/peppertino/badge.md +74 -0
  9. package/agents/peppertino/base.md +252 -0
  10. package/agents/peppertino/button.md +65 -0
  11. package/agents/peppertino/card.md +82 -0
  12. package/agents/peppertino/carousel.md +147 -0
  13. package/agents/peppertino/catalog.md +83 -0
  14. package/agents/peppertino/components-ai-search.md +10 -0
  15. package/agents/peppertino/components-display.md +19 -0
  16. package/agents/peppertino/components-inputs.md +15 -0
  17. package/agents/peppertino/components-navigation.md +12 -0
  18. package/agents/peppertino/dark-mode.md +152 -0
  19. package/agents/peppertino/footer.md +109 -0
  20. package/agents/peppertino/forms-fieldset.md +85 -0
  21. package/agents/peppertino/forms-form-instructions.md +94 -0
  22. package/agents/peppertino/forms-label.md +110 -0
  23. package/agents/peppertino/forms-text-field.md +134 -0
  24. package/agents/peppertino/forms-validation.md +153 -0
  25. package/agents/peppertino/gradient.md +41 -0
  26. package/agents/peppertino/header.md +105 -0
  27. package/agents/peppertino/modal.md +123 -0
  28. package/agents/peppertino/section.md +56 -0
  29. package/agents/peppertino/select.md +110 -0
  30. package/agents/peppertino/switch.md +72 -0
  31. package/agents/peppertino/table.md +69 -0
  32. package/agents/peppertino/tabs.md +115 -0
  33. package/agents/peppertino/toast.md +96 -0
  34. package/agents/peppertino/tooltip.md +111 -0
  35. package/agents/peppertino/typography.md +118 -0
  36. package/agents/peppertino/utilities.md +194 -0
  37. package/agents/skill.md +65 -0
  38. package/build.js +53 -53
  39. package/dist/accordion.js +1 -1
  40. package/dist/accordion.js.map +2 -2
  41. package/dist/alert.js.map +1 -1
  42. package/dist/carousel.js.map +1 -1
  43. package/dist/header.js.map +1 -1
  44. package/dist/main.css +2566 -1008
  45. package/dist/main.css.map +1 -1
  46. package/dist/main.min.css +1 -0
  47. package/dist/modal.js.map +1 -1
  48. package/dist/peppertino.js +1 -1
  49. package/dist/peppertino.js.map +2 -2
  50. package/dist/select.js.map +1 -1
  51. package/dist/switch.js.map +1 -1
  52. package/dist/tabs.js.map +1 -1
  53. package/dist/theme.js.map +1 -1
  54. package/dist/toast.js.map +1 -1
  55. package/dist/validation.js.map +1 -1
  56. package/icon.svg +4 -0
  57. package/index.html +2177 -2098
  58. package/package.json +28 -28
  59. package/scripts/hex-to-hsl.mjs +75 -75
  60. package/scripts/lint-bem.mjs +53 -53
  61. package/scripts/lint-colors.mjs +87 -87
  62. package/site.webmanifest +18 -0
  63. package/src/js/accordion.js +105 -103
  64. package/src/js/alert.js +28 -28
  65. package/src/js/carousel.js +153 -153
  66. package/src/js/header.js +85 -85
  67. package/src/js/modal.js +138 -138
  68. package/src/js/peppertino.js +15 -15
  69. package/src/js/select.js +101 -101
  70. package/src/js/switch.js +28 -28
  71. package/src/js/tabs.js +104 -104
  72. package/src/js/theme.js +47 -47
  73. package/src/js/toast.js +79 -79
  74. package/src/js/validation.js +132 -132
  75. package/src/scss/accordion.scss +190 -156
  76. package/src/scss/activity.scss +17 -0
  77. package/src/scss/alert.scss +203 -203
  78. package/src/scss/badge.scss +90 -90
  79. package/src/scss/base.scss +511 -506
  80. package/src/scss/button.scss +119 -119
  81. package/src/scss/card.scss +121 -121
  82. package/src/scss/carousel.scss +303 -303
  83. package/src/scss/code-block.scss +22 -0
  84. package/src/scss/counter.scss +5 -0
  85. package/src/scss/dark-mode.scss +514 -514
  86. package/src/scss/duration.scss +26 -0
  87. package/src/scss/folder.scss +27 -0
  88. package/src/scss/footer.scss +224 -224
  89. package/src/scss/forms/fieldset.scss +127 -127
  90. package/src/scss/forms/form-instructions.scss +133 -133
  91. package/src/scss/forms/label.scss +115 -115
  92. package/src/scss/forms/text-field.scss +240 -240
  93. package/src/scss/forms/validation.scss +215 -215
  94. package/src/scss/forms.scss +8 -8
  95. package/src/scss/gradient.scss +11 -11
  96. package/src/scss/gravity-letters.scss +7 -0
  97. package/src/scss/header.scss +257 -238
  98. package/src/scss/helpers/color.scss +9 -0
  99. package/src/scss/helpers/flex.scss +14 -0
  100. package/src/scss/helpers/index.scss +6 -0
  101. package/src/scss/helpers/layout.scss +14 -0
  102. package/src/scss/helpers/spacing.scss +14 -0
  103. package/src/scss/helpers/typography.scss +11 -0
  104. package/src/scss/helpers/visibility.scss +9 -0
  105. package/src/scss/main.scss +49 -24
  106. package/src/scss/modal.scss +188 -188
  107. package/src/scss/model-picker.scss +5 -0
  108. package/src/scss/notification.scss +5 -0
  109. package/src/scss/orb.scss +7 -0
  110. package/src/scss/otp.scss +5 -0
  111. package/src/scss/pill-nav.scss +10 -0
  112. package/src/scss/prompt.scss +28 -0
  113. package/src/scss/rail.scss +7 -0
  114. package/src/scss/reactions.scss +5 -0
  115. package/src/scss/reset.scss +84 -84
  116. package/src/scss/response.scss +11 -0
  117. package/src/scss/reveal.scss +5 -0
  118. package/src/scss/scroll-progress.scss +4 -0
  119. package/src/scss/search-results.scss +13 -0
  120. package/src/scss/section.scss +87 -79
  121. package/src/scss/select.scss +210 -210
  122. package/src/scss/sidebar.scss +8 -0
  123. package/src/scss/status.scss +5 -0
  124. package/src/scss/step-list.scss +13 -0
  125. package/src/scss/switch.scss +121 -121
  126. package/src/scss/table.scss +89 -89
  127. package/src/scss/tabs.scss +156 -156
  128. package/src/scss/task-list.scss +18 -0
  129. package/src/scss/theme-picker.scss +5 -0
  130. package/src/scss/toast.scss +170 -170
  131. package/src/scss/tooltip.scss +126 -126
  132. package/src/scss/typography.scss +58 -58
  133. package/src/scss/utilities.scss +243 -243
  134. package/src/scss/voice-note.scss +5 -0
@@ -0,0 +1,109 @@
1
+ # Footer
2
+
3
+ **Source:** `src/scss/footer.scss` · No JS required.
4
+
5
+ The footer is a `<footer role="contentinfo">` landmark. It consists of a top grid (brand + nav columns) and a bottom bar (legal + social). It must be the last element in `<body>` — it is the only component exempt from A→Z ordering.
6
+
7
+ ## Full structure
8
+
9
+ ```html
10
+ <footer class="pp-footer pp-footer--accent" role="contentinfo">
11
+ <div class="pp-footer__top">
12
+
13
+ <!-- Brand block — always first, spans full width on mobile -->
14
+ <div class="pp-footer__brand">
15
+ <a href="#" class="pp-footer__logo">BrandName</a>
16
+ <p class="pp-footer__tagline">Short one-line description of the product.</p>
17
+ </div>
18
+
19
+ <!-- Nav columns — repeat as needed (up to 4 before xl, unlimited after) -->
20
+ <div class="pp-footer__col">
21
+ <p class="pp-footer__col-title">Product</p>
22
+ <ul class="pp-footer__nav" aria-label="Product links">
23
+ <li><a href="#" class="pp-footer__nav-link">Features</a></li>
24
+ <li><a href="#" class="pp-footer__nav-link">Pricing</a></li>
25
+ <li><a href="#" class="pp-footer__nav-link">Changelog</a></li>
26
+ </ul>
27
+ </div>
28
+
29
+ <div class="pp-footer__col">
30
+ <p class="pp-footer__col-title">Resources</p>
31
+ <ul class="pp-footer__nav" aria-label="Resource links">
32
+ <li><a href="#" class="pp-footer__nav-link">Documentation</a></li>
33
+ <li><a href="#" class="pp-footer__nav-link">GitHub</a></li>
34
+ </ul>
35
+ </div>
36
+
37
+ </div>
38
+
39
+ <div class="pp-footer__bottom">
40
+ <p class="pp-footer__legal">
41
+ &copy; 2026 BrandName. Released under the
42
+ <a href="#" target="_blank" rel="noopener noreferrer">MIT License</a>.
43
+ </p>
44
+ <ul class="pp-footer__social" aria-label="Social links">
45
+ <li>
46
+ <a href="https://github.com/..." class="pp-footer__social-link"
47
+ aria-label="GitHub" target="_blank" rel="noopener noreferrer">
48
+ <i data-lucide="github"></i>
49
+ </a>
50
+ </li>
51
+ <li>
52
+ <a href="https://npmjs.com/..." class="pp-footer__social-link"
53
+ aria-label="npm" target="_blank" rel="noopener noreferrer">
54
+ <i data-lucide="package"></i>
55
+ </a>
56
+ </li>
57
+ </ul>
58
+ </div>
59
+ </footer>
60
+ ```
61
+
62
+ ## Parts
63
+
64
+ | Class | Element | Description |
65
+ |---|---|---|
66
+ | `.pp-footer` | `<footer>` | Outer shell — padding, border-top |
67
+ | `.pp-footer__top` | `<div>` | CSS grid: `1fr repeat(3, auto)`, expands to 4 auto cols at `xl` |
68
+ | `.pp-footer__brand` | `<div>` | Brand + tagline — spans full width on mobile |
69
+ | `.pp-footer__logo` | `<a>` | Brand name link, semibold lg |
70
+ | `.pp-footer__tagline` | `<p>` | Muted description, sm |
71
+ | `.pp-footer__col` | `<div>` | Nav column, `min-width: 140px` |
72
+ | `.pp-footer__col-title` | `<p>` | xs, semibold, 0.08em tracking, uppercase |
73
+ | `.pp-footer__nav` | `<ul>` | Column link list — requires `aria-label` |
74
+ | `.pp-footer__nav-link` | `<a>` | neutral-500, hover → neutral-900 |
75
+ | `.pp-footer__bottom` | `<div>` | Flex row — legal left, social right |
76
+ | `.pp-footer__legal` | `<p>` | xs, neutral-400, inline `<a>` links supported |
77
+ | `.pp-footer__social` | `<ul>` | Icon link list — requires `aria-label` |
78
+ | `.pp-footer__social-link` | `<a>` | 32px circle, icon centered — requires `aria-label` |
79
+
80
+ ## Variants
81
+
82
+ | Class on `.pp-footer` | Description |
83
+ |---|---|
84
+ | `.pp-footer--dark` | neutral-900 background; all text and border colors inverted to light |
85
+ | `.pp-footer--accent` | Removes top border; adds 3px gradient (gold→red) strip at very top |
86
+
87
+ `--dark` and `--accent` can be combined: `class="pp-footer pp-footer--dark pp-footer--accent"`.
88
+
89
+ ## Responsive layout
90
+
91
+ - **Desktop (≥ xl):** brand + up to 4 nav columns side by side.
92
+ - **Tablet (< xl, ≥ 768px):** brand + 3 auto columns.
93
+ - **Mobile (< 768px):** 2-column grid; brand spans full width above the columns.
94
+ - **Small mobile (< 480px):** single column, everything stacked.
95
+
96
+ ## ARIA & accessibility
97
+
98
+ - `<footer>` has an implicit `role="contentinfo"` landmark — always use the native element, not `<div role="contentinfo">`.
99
+ - Every `.pp-footer__nav` `<ul>` must have `aria-label` describing which set of links it contains — multiple lists on the same page would otherwise be indistinguishable to AT.
100
+ - Every `.pp-footer__social-link` icon button must have `aria-label` — the icon alone provides no accessible name.
101
+ - External links should have `target="_blank" rel="noopener noreferrer"` and optionally a visually-hidden "opens in new tab" notice or `aria-label` suffix.
102
+ - The `<p class="pp-footer__col-title">` is presentational — it is NOT a heading and must not use `<h*>` elements (footer columns are not document sections).
103
+
104
+ ## Common mistakes
105
+
106
+ - Using `<h3>` or other heading elements for `.pp-footer__col-title` — column titles are labels, not document headings; this breaks heading hierarchy.
107
+ - Omitting `aria-label` from `.pp-footer__nav` lists — screen readers cannot distinguish "Product links" from "Resource links" without it.
108
+ - Omitting `aria-label` from icon-only `.pp-footer__social-link` buttons — icons have no text content so AT announces nothing useful.
109
+ - Adding `role="contentinfo"` to `<footer>` explicitly — it is redundant; `<footer>` inside `<body>` already carries that role implicitly.
@@ -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.