@auriel/peppertino 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/CHANGELOG.txt +242 -224
  2. package/LICENSE +21 -21
  3. package/MIGRATION.md +52 -52
  4. package/README.md +773 -764
  5. package/agents/peppertino/SKILL.md +76 -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 +81 -0
  14. package/agents/peppertino/dark-mode.md +152 -0
  15. package/agents/peppertino/footer.md +109 -0
  16. package/agents/peppertino/forms-fieldset.md +85 -0
  17. package/agents/peppertino/forms-form-instructions.md +94 -0
  18. package/agents/peppertino/forms-label.md +110 -0
  19. package/agents/peppertino/forms-text-field.md +134 -0
  20. package/agents/peppertino/forms-validation.md +153 -0
  21. package/agents/peppertino/gradient.md +41 -0
  22. package/agents/peppertino/header.md +105 -0
  23. package/agents/peppertino/modal.md +123 -0
  24. package/agents/peppertino/section.md +56 -0
  25. package/agents/peppertino/select.md +110 -0
  26. package/agents/peppertino/switch.md +72 -0
  27. package/agents/peppertino/table.md +69 -0
  28. package/agents/peppertino/tabs.md +115 -0
  29. package/agents/peppertino/toast.md +96 -0
  30. package/agents/peppertino/tooltip.md +111 -0
  31. package/agents/peppertino/typography.md +118 -0
  32. package/agents/peppertino/utilities.md +194 -0
  33. package/agents/skill.md +65 -0
  34. package/build.js +53 -53
  35. package/dist/accordion.js +1 -1
  36. package/dist/accordion.js.map +2 -2
  37. package/dist/alert.js.map +1 -1
  38. package/dist/carousel.js.map +1 -1
  39. package/dist/header.js.map +1 -1
  40. package/dist/main.css +2566 -1008
  41. package/dist/main.css.map +1 -1
  42. package/dist/main.min.css +1 -0
  43. package/dist/modal.js.map +1 -1
  44. package/dist/peppertino.js +1 -1
  45. package/dist/peppertino.js.map +2 -2
  46. package/dist/select.js.map +1 -1
  47. package/dist/switch.js.map +1 -1
  48. package/dist/tabs.js.map +1 -1
  49. package/dist/theme.js.map +1 -1
  50. package/dist/toast.js.map +1 -1
  51. package/dist/validation.js.map +1 -1
  52. package/icon.svg +4 -0
  53. package/index.html +2172 -2098
  54. package/package.json +28 -28
  55. package/scripts/hex-to-hsl.mjs +75 -75
  56. package/scripts/lint-bem.mjs +53 -53
  57. package/scripts/lint-colors.mjs +87 -87
  58. package/site.webmanifest +18 -0
  59. package/src/js/accordion.js +105 -103
  60. package/src/js/alert.js +28 -28
  61. package/src/js/carousel.js +153 -153
  62. package/src/js/header.js +85 -85
  63. package/src/js/modal.js +138 -138
  64. package/src/js/peppertino.js +15 -15
  65. package/src/js/select.js +101 -101
  66. package/src/js/switch.js +28 -28
  67. package/src/js/tabs.js +104 -104
  68. package/src/js/theme.js +47 -47
  69. package/src/js/toast.js +79 -79
  70. package/src/js/validation.js +132 -132
  71. package/src/scss/accordion.scss +190 -156
  72. package/src/scss/activity.scss +17 -0
  73. package/src/scss/alert.scss +203 -203
  74. package/src/scss/badge.scss +90 -90
  75. package/src/scss/base.scss +511 -506
  76. package/src/scss/button.scss +119 -119
  77. package/src/scss/card.scss +121 -121
  78. package/src/scss/carousel.scss +303 -303
  79. package/src/scss/code-block.scss +22 -0
  80. package/src/scss/counter.scss +5 -0
  81. package/src/scss/dark-mode.scss +514 -514
  82. package/src/scss/duration.scss +26 -0
  83. package/src/scss/folder.scss +27 -0
  84. package/src/scss/footer.scss +224 -224
  85. package/src/scss/forms/fieldset.scss +127 -127
  86. package/src/scss/forms/form-instructions.scss +133 -133
  87. package/src/scss/forms/label.scss +115 -115
  88. package/src/scss/forms/text-field.scss +240 -240
  89. package/src/scss/forms/validation.scss +215 -215
  90. package/src/scss/forms.scss +8 -8
  91. package/src/scss/gradient.scss +11 -11
  92. package/src/scss/gravity-letters.scss +7 -0
  93. package/src/scss/header.scss +257 -238
  94. package/src/scss/helpers/color.scss +9 -0
  95. package/src/scss/helpers/flex.scss +14 -0
  96. package/src/scss/helpers/index.scss +6 -0
  97. package/src/scss/helpers/layout.scss +14 -0
  98. package/src/scss/helpers/spacing.scss +14 -0
  99. package/src/scss/helpers/typography.scss +11 -0
  100. package/src/scss/helpers/visibility.scss +9 -0
  101. package/src/scss/main.scss +49 -24
  102. package/src/scss/modal.scss +188 -188
  103. package/src/scss/model-picker.scss +5 -0
  104. package/src/scss/notification.scss +5 -0
  105. package/src/scss/orb.scss +7 -0
  106. package/src/scss/otp.scss +5 -0
  107. package/src/scss/pill-nav.scss +10 -0
  108. package/src/scss/prompt.scss +28 -0
  109. package/src/scss/rail.scss +7 -0
  110. package/src/scss/reactions.scss +5 -0
  111. package/src/scss/reset.scss +84 -84
  112. package/src/scss/response.scss +11 -0
  113. package/src/scss/reveal.scss +5 -0
  114. package/src/scss/scroll-progress.scss +4 -0
  115. package/src/scss/search-results.scss +13 -0
  116. package/src/scss/section.scss +87 -79
  117. package/src/scss/select.scss +210 -210
  118. package/src/scss/sidebar.scss +8 -0
  119. package/src/scss/status.scss +5 -0
  120. package/src/scss/step-list.scss +13 -0
  121. package/src/scss/switch.scss +121 -121
  122. package/src/scss/table.scss +89 -89
  123. package/src/scss/tabs.scss +156 -156
  124. package/src/scss/task-list.scss +18 -0
  125. package/src/scss/theme-picker.scss +5 -0
  126. package/src/scss/toast.scss +170 -170
  127. package/src/scss/tooltip.scss +126 -126
  128. package/src/scss/typography.scss +58 -58
  129. package/src/scss/utilities.scss +243 -243
  130. package/src/scss/voice-note.scss +5 -0
@@ -0,0 +1,96 @@
1
+ # Toast
2
+
3
+ **Source:** `src/scss/toast.scss` · `src/js/toast.js`
4
+
5
+ Auto-dismissing notification toasts. `ppToast.show()` creates a container on demand, injects the toast with an SVG icon and optional progress bar, and removes it after the configured duration. No HTML scaffolding needed in advance.
6
+
7
+ ## JS API
8
+
9
+ ```js
10
+ // Minimal
11
+ ppToast.show({ message: 'File saved.' });
12
+
13
+ // Full options
14
+ ppToast.show({
15
+ message: 'Payment failed. Check card details.', // required
16
+ title: 'Error', // optional heading
17
+ variant: 'error', // 'neutral'|'info'|'success'|'warning'|'error'
18
+ duration: 6000, // ms; 0 = persistent (no auto-dismiss)
19
+ position: 'top-right', // see positions table below
20
+ });
21
+ ```
22
+
23
+ ## Positions
24
+
25
+ | Value | Screen location |
26
+ |---|---|
27
+ | `top-right` (default) | Top-right corner |
28
+ | `top-left` | Top-left corner |
29
+ | `top-center` | Top-center, horizontally centered |
30
+ | `bottom-right` | Bottom-right corner |
31
+ | `bottom-left` | Bottom-left corner |
32
+ | `bottom-center` | Bottom-center, horizontally centered |
33
+
34
+ Each position maps to a `.pp-toast-container--{position}` container created on demand. Multiple containers can coexist for different positions.
35
+
36
+ ## Color variants
37
+
38
+ | Variant | Background | Border | Icon |
39
+ |---|---|---|---|
40
+ | `neutral` (default) | `neutral-800` | `neutral-700` | info circle |
41
+ | `info` | info / 12% | info / 30% | info circle |
42
+ | `success` | success / 12% | success / 30% | circle-check |
43
+ | `warning` | warning / 12% | warning / 35% | triangle-alert |
44
+ | `error` | error / 12% | error / 30% | circle-x |
45
+
46
+ ## Manual dismiss button
47
+
48
+ Add `data-toast-dismiss` to any button inside a toast for auto-wired dismiss (event delegation, no extra JS):
49
+
50
+ ```html
51
+ <!-- You don't need to write this manually — ppToast.show() injects it automatically.
52
+ Use data-toast-dismiss if building a static toast in HTML. -->
53
+ <div class="pp-toast pp-toast--info" role="status">
54
+ <div class="pp-toast__body">
55
+ <p class="pp-toast__message">Update available.</p>
56
+ </div>
57
+ <button class="pp-toast__dismiss" data-toast-dismiss aria-label="Dismiss">✕</button>
58
+ </div>
59
+ ```
60
+
61
+ ## Events
62
+
63
+ Both events bubble and are dispatched on the individual `.pp-toast` element:
64
+
65
+ | Event | When |
66
+ |---|---|
67
+ | `pp:toast:show` | Immediately after the toast is injected into the DOM |
68
+ | `pp:toast:dismiss` | Immediately before the toast is removed (after `.is-dismissing` is added) |
69
+
70
+ ```js
71
+ document.addEventListener('pp:toast:show', (e) => {
72
+ console.log('Toast shown:', e.target);
73
+ });
74
+ ```
75
+
76
+ ## Progress bar
77
+
78
+ When `duration > 0` (not persistent), a `.pp-toast__progress` bar animates from full width to zero over the duration. The animation pauses if the user hovers the toast container (via CSS `animation-play-state`).
79
+
80
+ ## Persistent toasts
81
+
82
+ Pass `duration: 0` to prevent auto-dismiss. The toast stays until the user clicks the dismiss button.
83
+
84
+ ```js
85
+ ppToast.show({ message: 'Action required.', variant: 'warning', duration: 0 });
86
+ ```
87
+
88
+ ## Dark mode
89
+
90
+ Background and border colors adapt under `.dark` via CSS custom property tokens. No extra classes needed.
91
+
92
+ ## Common mistakes
93
+
94
+ - Calling `ppToast.show()` before `DOMContentLoaded` — `toast.js` initialises on `DOMContentLoaded`; showing a toast before init will fail silently. Use `defer` on the script tag.
95
+ - Expecting `ppToast` to be available in module scope without a script tag — `toast.js` sets `window.ppToast`; it must be loaded globally.
96
+ - Using `duration: 0` without a dismiss button — the toast will never disappear; ensure the injected markup includes a `data-toast-dismiss` element (it always does when using `ppToast.show()`).
@@ -0,0 +1,111 @@
1
+ # Tooltip
2
+
3
+ **Source:** `src/scss/tooltip.scss`
4
+
5
+ CSS-only tooltip. Shows on `:hover` and `:focus-within` — no JavaScript required. Four placement variants. Content is visually hidden until triggered; `role="tooltip"` ensures screen readers announce it when the trigger receives focus.
6
+
7
+ ## Full structure
8
+
9
+ ```html
10
+ <span class="pp-tooltip">
11
+ <!-- The trigger — any inline or block element -->
12
+ <button type="button">Hover me</button>
13
+
14
+ <!-- The tooltip content -->
15
+ <span class="pp-tooltip__content" role="tooltip">
16
+ Helpful hint text
17
+ </span>
18
+ </span>
19
+ ```
20
+
21
+ ## Placement variants
22
+
23
+ Default placement is top-center. Override with a modifier on `.pp-tooltip__content`:
24
+
25
+ | Class | Placement |
26
+ |---|---|
27
+ | (none) | Top — centered above trigger |
28
+ | `.pp-tooltip__content--bottom` | Bottom — centered below trigger |
29
+ | `.pp-tooltip__content--left` | Left — vertically centered, left of trigger |
30
+ | `.pp-tooltip__content--right` | Right — vertically centered, right of trigger |
31
+
32
+ ```html
33
+ <!-- Bottom -->
34
+ <span class="pp-tooltip">
35
+ <button type="button">Trigger</button>
36
+ <span class="pp-tooltip__content pp-tooltip__content--bottom" role="tooltip">Below</span>
37
+ </span>
38
+
39
+ <!-- Left -->
40
+ <span class="pp-tooltip">
41
+ <button type="button">Trigger</button>
42
+ <span class="pp-tooltip__content pp-tooltip__content--left" role="tooltip">Left side</span>
43
+ </span>
44
+ ```
45
+
46
+ ## Force-show
47
+
48
+ Add `data-show` to `.pp-tooltip__content` to keep the tooltip visible at all times — useful during development and testing:
49
+
50
+ ```html
51
+ <span class="pp-tooltip">
52
+ <button type="button">Trigger</button>
53
+ <span class="pp-tooltip__content pp-tooltip__content--bottom" role="tooltip" data-show>
54
+ Always visible
55
+ </span>
56
+ </span>
57
+ ```
58
+
59
+ ## On icon buttons
60
+
61
+ Wrap the button with `.pp-tooltip` and place the content after the button:
62
+
63
+ ```html
64
+ <span class="pp-tooltip">
65
+ <button class="pp-button--ghost" style="padding:0.5rem;" type="button" aria-label="Delete">
66
+ <i data-lucide="trash-2" aria-hidden="true"></i>
67
+ </button>
68
+ <span class="pp-tooltip__content pp-tooltip__content--bottom" role="tooltip">Delete</span>
69
+ </span>
70
+ ```
71
+
72
+ Do not use `title=""` as a tooltip substitute — it is not keyboard accessible and is not announced consistently across screen readers.
73
+
74
+ ## ARIA
75
+
76
+ | Attribute | Required | Value |
77
+ |---|---|---|
78
+ | `role="tooltip"` | Yes | On `.pp-tooltip__content` |
79
+ | `aria-describedby` | Recommended | Associate trigger with tooltip `id` for programmatic access |
80
+
81
+ Full accessible pattern with `aria-describedby`:
82
+
83
+ ```html
84
+ <span class="pp-tooltip">
85
+ <button type="button" aria-describedby="tip-del">Delete</button>
86
+ <span class="pp-tooltip__content pp-tooltip__content--bottom" role="tooltip" id="tip-del">
87
+ Permanently removes the item
88
+ </span>
89
+ </span>
90
+ ```
91
+
92
+ ## Styling the content
93
+
94
+ The tooltip content box uses `--pp-neutral-900` background and white text by default. Override inline for one-offs:
95
+
96
+ ```html
97
+ <span class="pp-tooltip__content" role="tooltip" style="background: var(--pp-error);">
98
+ Dangerous action
99
+ </span>
100
+ ```
101
+
102
+ ## Dark mode
103
+
104
+ Tooltip background (`--pp-neutral-900`) becomes near-black under `.dark` via the inverted neutral scale. No extra classes needed.
105
+
106
+ ## Common mistakes
107
+
108
+ - Missing `role="tooltip"` — the content is not announced as a tooltip by screen readers on focus.
109
+ - Triggering on a non-focusable element (e.g., a `<span>` with no `tabindex`) — keyboard users cannot reach the tooltip. Use a `<button>` or add `tabindex="0"`.
110
+ - Placing interactive content inside `.pp-tooltip__content` — tooltip content is not keyboard-accessible once shown; buttons or links inside a tooltip are unreachable.
111
+ - Relying on hover only for critical information — tooltip content is purely supplemental. Never gate required information behind a hover state.
@@ -0,0 +1,118 @@
1
+ # Typography
2
+
3
+ **Source:** `src/scss/typography.scss` · No JS required.
4
+
5
+ Utility classes for font family, size, weight, line height, tracking, alignment, transform, decoration, and overflow. Classes compose freely — stack as many as needed on one element.
6
+
7
+ Base element styles (h1–h6, body, code, pre) are set in `base.scss` not here.
8
+
9
+ ## Font family
10
+
11
+ ```html
12
+ <p class="font-sans">Inter, system-ui, -apple-system…</p>
13
+ <p class="font-mono">Kode Mono, ui-monospace…</p>
14
+ ```
15
+
16
+ Both fonts load from Google Fonts via `base.scss`. `font-sans` is the default body font.
17
+
18
+ ## Font weight
19
+
20
+ `.font-100` through `.font-900` in steps of 100.
21
+
22
+ ```html
23
+ <p class="font-sans font-300">Light</p>
24
+ <p class="font-sans font-400">Regular</p>
25
+ <p class="font-sans font-500">Medium</p>
26
+ <p class="font-sans font-600">SemiBold</p>
27
+ <p class="font-sans font-700">Bold</p>
28
+ <p class="font-sans font-900">Black</p>
29
+ ```
30
+
31
+ Inter supports 300, 400, 500, 600, 700, 900. Weights 100, 200, 800 will be synthesised by the browser (may look different).
32
+
33
+ ## Font size
34
+
35
+ | Class | rem | px equiv |
36
+ |---|---|---|
37
+ | `.text-xs` | 0.75rem | 12px |
38
+ | `.text-sm` | 0.875rem | 14px |
39
+ | `.text-base` | 1rem | 16px |
40
+ | `.text-lg` | 1.125rem | 18px |
41
+ | `.text-xl` | 1.25rem | 20px |
42
+ | `.text-2xl` | 1.5rem | 24px |
43
+ | `.text-3xl` | 1.875rem | 30px |
44
+ | `.text-4xl` | 2.25rem | 36px |
45
+ | `.text-5xl` | 3rem | 48px |
46
+
47
+ ## Line height
48
+
49
+ | Class | Value | Best for |
50
+ |---|---|---|
51
+ | `.leading-none` | 1 | Display, icon labels |
52
+ | `.leading-tight` | 1.25 | Headings |
53
+ | `.leading-snug` | 1.375 | Sub-headings |
54
+ | `.leading-normal` | 1.5 | UI text |
55
+ | `.leading-relaxed` | 1.625 | Body copy |
56
+ | `.leading-loose` | 2 | Spaced lists |
57
+
58
+ ## Letter spacing
59
+
60
+ | Class | Value | Best for |
61
+ |---|---|---|
62
+ | `.tracking-tighter` | -0.05em | Large display headings |
63
+ | `.tracking-tight` | -0.025em | Headings, Apple-style |
64
+ | `.tracking-normal` | 0 | Body text |
65
+ | `.tracking-wide` | 0.025em | — |
66
+ | `.tracking-wider` | 0.05em | Small caps |
67
+ | `.tracking-widest` | 0.1em | Uppercase labels, eyebrows |
68
+
69
+ ## Text alignment
70
+
71
+ `.text-left` · `.text-center` · `.text-right`
72
+
73
+ ## Text transform
74
+
75
+ `.uppercase` · `.lowercase` · `.capitalize`
76
+
77
+ ## Text decoration
78
+
79
+ `.underline` · `.no-underline` · `.line-through`
80
+
81
+ ## Overflow
82
+
83
+ | Class | Behaviour |
84
+ |---|---|
85
+ | `.truncate` | `overflow: hidden; text-overflow: ellipsis; white-space: nowrap` — clips to one line |
86
+ | `.wrap-balance` | `text-wrap: balance` — balances line lengths in headings |
87
+
88
+ ## Composing classes
89
+
90
+ ```html
91
+ <!-- Apple-style section heading -->
92
+ <h2 class="font-sans font-700 tracking-tight text-4xl">
93
+ A powerful new approach.
94
+ </h2>
95
+
96
+ <!-- Uppercase label / eyebrow -->
97
+ <p class="font-sans font-600 text-xs uppercase tracking-widest" style="color:#71717a;">
98
+ New feature
99
+ </p>
100
+
101
+ <!-- Body copy -->
102
+ <p class="font-sans font-400 text-base leading-relaxed">
103
+ Supporting text that explains the heading above.
104
+ </p>
105
+ ```
106
+
107
+ ## ARIA & accessibility
108
+
109
+ - Never use typographic styling alone to convey meaning — an element that looks like a heading must use `<h1>`–`<h6>`, not a `<p class="text-4xl font-700">`.
110
+ - `.truncate` hides content visually — if the full text is meaningful, provide it via `title` attribute or `aria-label` so AT users can access it.
111
+ - `.wrap-balance` is a progressive enhancement — it has no effect in browsers that don't support `text-wrap: balance`; do not rely on it for layout.
112
+ - Avoid setting font sizes below `text-xs` (0.75rem / 12px) — text smaller than 12px fails WCAG 1.4.4 and is difficult to read.
113
+
114
+ ## Common mistakes
115
+
116
+ - Using `<p class="font-700 text-4xl">` for headings instead of `<h2>` — semantic heading elements are required for document structure and AT navigation.
117
+ - Combining `.text-*` classes with inline `font-size` — the inline style wins; use one or the other.
118
+ - Using `.uppercase` on user-generated content or names — transforms applied in CSS are not reflected in clipboard copy; spell out uppercase text in HTML if exact casing matters.
@@ -0,0 +1,194 @@
1
+ # Utilities
2
+
3
+ ## Modular additions
4
+
5
+ Import only the helper family needed, e.g. `@use '@auriel/peppertino/src/scss/helpers/spacing';`, or import `helpers` for all six families. These modules work without `base.scss`; color tokens have fallbacks. The `u-` prefix prevents collisions with existing helpers. They are also included in `main.scss`.
6
+
7
+ - `color`: `.u-text-{primary,success,warning,error,info,surface,content,muted}`, corresponding `.u-bg-*` and `.u-border-*`, `.u-text-inherit`, `.u-bg-transparent`. Choose foreground/background pairs with sufficient contrast; a background helper does not set text color.
8
+ - `spacing`: logical `.u-{ms,me,ps,pe,mbs,mbe,pbs,pbe}-{0,1,2,3,4,5,6,8,10,12,16,20,24,32}` and `.u-ms-auto` / `.u-me-auto`. `s` and `e` mean start and end; `m` and `p` mean margin and padding, and `b` denotes the block axis. Values use quarter-rem increments.
9
+ - `flex`: `.u-flex-shrink`, `.u-self-baseline`, `.u-content-{start,end,center,between,around,stretch}`, `.u-order-{first,last,none}`, `.u-basis-{auto,full,half}`. Set flex display separately.
10
+ - `typography`: `.u-text-{start,end,justify}`, `.u-whitespace-{normal,nowrap,pre-wrap}`, `.u-break-{words,normal}`, `.u-italic`, `.u-not-italic`, `.u-tabular-nums`.
11
+ - `layout`: `.u-min-w-{0,full}`, `.u-max-w-full`, `.u-min-h-{0,screen}`, `.u-max-h-full`, `.u-aspect-{square,video}`, `.u-object-{cover,contain}`, `.u-overflow-{x,y}-scroll`, `.u-inset-0`, `.u-isolate`.
12
+ - `visibility`: `.u-hidden`, `.u-sr-only`, `.u-sr-only-focusable`, and `.u-{sm,md,lg,xl,w2xl}-hidden` at the existing minimum-width breakpoints. Hidden content is also removed from the accessibility tree; use focusable visually hidden text for skip links.
13
+
14
+ **Source:** `src/scss/utilities.scss`
15
+
16
+ Single-purpose classes with no JavaScript dependency. The utilities layer is the last non-dark-mode import in `main.scss`, so it overrides component defaults without specificity hacks.
17
+
18
+ ## Display
19
+
20
+ | Class | CSS |
21
+ |---|---|
22
+ | `.d-block` | `display: block` |
23
+ | `.d-inline` | `display: inline` |
24
+ | `.d-inline-block` | `display: inline-block` |
25
+ | `.d-flex` | `display: flex` |
26
+ | `.d-inline-flex` | `display: inline-flex` |
27
+ | `.d-grid` | `display: grid` |
28
+ | `.d-inline-grid` | `display: inline-grid` |
29
+ | `.d-none` | `display: none` |
30
+ | `.d-contents` | `display: contents` |
31
+
32
+ Responsive prefixes available for display only: `.sm-d-*` `.md-d-*` `.lg-d-*` `.xl-d-*` `.w2xl-d-*`
33
+
34
+ Note: the `2xl` breakpoint prefix is `.w2xl-` (not `.2xl-`) because CSS identifiers cannot start with a digit.
35
+
36
+ ## Visibility
37
+
38
+ | Class | CSS |
39
+ |---|---|
40
+ | `.visible` | `visibility: visible` |
41
+ | `.invisible` | `visibility: hidden` (preserves layout space) |
42
+ | `.sr-only` | Visually hidden but readable by screen readers (1×1 clip) |
43
+ | `.not-sr-only` | Reverses `.sr-only` — restores visible layout |
44
+
45
+ ## Opacity
46
+
47
+ `.opacity-0` `.opacity-25` `.opacity-50` `.opacity-75` `.opacity-100`
48
+
49
+ ## Margin
50
+
51
+ Pattern: `.m-*` `.mt-*` `.mb-*` `.ml-*` `.mr-*` `.mx-*` `.my-*`
52
+
53
+ Keys: `0 1 2 3 4 5 6 8 10 12 16 20 24 28 32 auto`
54
+
55
+ Values: key × 4px (e.g. `.mt-4` = `margin-top: 16px`). `.mx-auto` = `margin-left: auto; margin-right: auto`.
56
+
57
+ ## Padding
58
+
59
+ Pattern: `.p-*` `.pt-*` `.pb-*` `.pl-*` `.pr-*` `.px-*` `.py-*`
60
+
61
+ Keys: `0 1 2 3 4 5 6 8 10 12 16 20 24 28 32`
62
+
63
+ Values: key × 4px.
64
+
65
+ ## Gap
66
+
67
+ `.gap-*` `.gap-x-*` `.gap-y-*` — same keys and 4px multiplier as spacing above.
68
+
69
+ ## Flex
70
+
71
+ | Class | CSS |
72
+ |---|---|
73
+ | `.flex-row` | `flex-direction: row` |
74
+ | `.flex-col` | `flex-direction: column` |
75
+ | `.flex-row-reverse` | `flex-direction: row-reverse` |
76
+ | `.flex-col-reverse` | `flex-direction: column-reverse` |
77
+ | `.flex-wrap` | `flex-wrap: wrap` |
78
+ | `.flex-nowrap` | `flex-wrap: nowrap` |
79
+ | `.flex-wrap-reverse` | `flex-wrap: wrap-reverse` |
80
+ | `.flex-1` | `flex: 1 1 0%` |
81
+ | `.flex-auto` | `flex: 1 1 auto` |
82
+ | `.flex-none` | `flex: none` |
83
+ | `.flex-grow` | `flex-grow: 1` |
84
+ | `.flex-shrink` | `flex-shrink: 1` |
85
+ | `.flex-grow-0` | `flex-grow: 0` |
86
+ | `.flex-shrink-0` | `flex-shrink: 0` |
87
+
88
+ **Justify-content:** `.justify-start` `.justify-end` `.justify-center` `.justify-between` `.justify-around` `.justify-evenly`
89
+
90
+ **Align-items:** `.items-start` `.items-end` `.items-center` `.items-baseline` `.items-stretch`
91
+
92
+ **Align-self:** `.self-start` `.self-end` `.self-center` `.self-baseline` `.self-stretch` `.self-auto`
93
+
94
+ ## Grid
95
+
96
+ **Columns:** `.grid-cols-1` through `.grid-cols-6` and `.grid-cols-12`
97
+
98
+ **Rows:** `.grid-rows-1` through `.grid-rows-4`
99
+
100
+ **Col span:** `.col-span-1` through `.col-span-6` and `.col-span-12` and `.col-span-full`
101
+
102
+ **Row span:** `.row-span-1` through `.row-span-4` and `.row-span-full`
103
+
104
+ ## Width
105
+
106
+ | Class | CSS |
107
+ |---|---|
108
+ | `.w-full` | `width: 100%` |
109
+ | `.w-screen` | `width: 100vw` |
110
+ | `.w-auto` | `width: auto` |
111
+ | `.w-fit` | `width: fit-content` |
112
+ | `.w-min` | `width: min-content` |
113
+ | `.w-max` | `width: max-content` |
114
+ | `.w-half` | `width: 50%` |
115
+
116
+ ## Height
117
+
118
+ | Class | CSS |
119
+ |---|---|
120
+ | `.h-full` | `height: 100%` |
121
+ | `.h-screen` | `height: 100vh` |
122
+ | `.h-auto` | `height: auto` |
123
+ | `.h-fit` | `height: fit-content` |
124
+
125
+ ## Overflow
126
+
127
+ `.overflow-auto` `.overflow-hidden` `.overflow-visible` `.overflow-scroll`
128
+ `.overflow-x-auto` `.overflow-x-hidden` `.overflow-x-scroll`
129
+ `.overflow-y-auto` `.overflow-y-hidden` `.overflow-y-scroll`
130
+
131
+ ## Position
132
+
133
+ `.static` `.relative` `.absolute` `.fixed` `.sticky`
134
+
135
+ ## Z-index
136
+
137
+ | Class | Value | Use |
138
+ |---|---|---|
139
+ | `.z-below` | `-1` | Behind everything |
140
+ | `.z-base` | `0` | Normal stacking |
141
+ | `.z-raised` | `10` | Sticky elements, dropdowns |
142
+ | `.z-overlay` | `100` | Sidebars, drawers |
143
+ | `.z-modal` | `200` | Modals |
144
+ | `.z-toast` | `300` | Toast notifications |
145
+ | `.z-tooltip` | `400` | Tooltips |
146
+
147
+ ## Border-radius
148
+
149
+ | Class | Value |
150
+ |---|---|
151
+ | `.rounded-none` | `0` |
152
+ | `.rounded-sm` | `4px` |
153
+ | `.rounded-base` | `8px` |
154
+ | `.rounded-md` | `12px` |
155
+ | `.rounded-lg` | `16px` |
156
+ | `.rounded-xl` | `20px` |
157
+ | `.rounded-2xl` | `24px` |
158
+ | `.rounded-full` | `9999px` |
159
+
160
+ ## Shadow
161
+
162
+ `.shadow-none` `.shadow-sm` `.shadow-md` `.shadow-lg` `.shadow-xl`
163
+
164
+ Values match the `$shadow-*` SCSS variables in `base.scss`.
165
+
166
+ ## Cursor
167
+
168
+ `.cursor-default` `.cursor-pointer` `.cursor-not-allowed` `.cursor-grab` `.cursor-text`
169
+
170
+ ## Pointer events
171
+
172
+ `.pointer-events-none` `.pointer-events-auto`
173
+
174
+ ## User select
175
+
176
+ `.select-none` `.select-text` `.select-all` `.select-auto`
177
+
178
+ ## Responsive display prefixes
179
+
180
+ Display utilities only. Classes follow the pattern `.<prefix>-d-<value>`.
181
+
182
+ | Prefix | Breakpoint | Matches at |
183
+ |---|---|---|
184
+ | `.sm-d-*` | `≥ 640px` | Small tablets, large phones landscape |
185
+ | `.md-d-*` | `≥ 768px` | Tablets |
186
+ | `.lg-d-*` | `≥ 1024px` | Laptops |
187
+ | `.xl-d-*` | `≥ 1280px` | Desktops |
188
+ | `.w2xl-d-*` | `≥ 1536px` | Wide monitors |
189
+
190
+ Example: `.d-none.md-d-flex` — hidden by default, flex on tablet and up.
191
+
192
+ ## Dark mode
193
+
194
+ Utility classes have no built-in dark-mode behaviour — they apply unconditionally. If you need a class to apply only in dark mode, wrap the element in a `.dark` ancestor and use inline styles or a component-level override rather than trying to create `.dark .d-none` combinations.
@@ -0,0 +1,65 @@
1
+ # PeppertinoCSS — Agent Skill Index
2
+
3
+ This directory contains per-component reference documents for AI agents and tooling working with PeppertinoCSS. Each file covers classes, variants, ARIA requirements, and JS API for one component.
4
+
5
+ ## Index
6
+
7
+ | File | Covers |
8
+ |---|---|
9
+ | [accordion.md](accordion.md) | `.pp-accordion`, variants, `data-allow-multiple`, keyboard nav |
10
+ | [alert.md](alert.md) | `.pp-alert`, 6 variants, `--filled`, dismiss animation, `role` mapping |
11
+ | [base.md](base.md) | Design tokens, CSS custom properties, dark mode tokens, breakpoints |
12
+ | [button.md](button.md) | `.button` and all variants |
13
+ | [card.md](card.md) | `.pp-card`, variants, grid helpers |
14
+ | [carousel.md](carousel.md) | `.pp-carousel`, JS shim, `ppCarousel` API |
15
+ | [dark-mode.md](dark-mode.md) | `.dark` class, all `--pp-*` tokens, JS toggle, SCSS alias pattern |
16
+ | [footer.md](footer.md) | `.pp-footer`, columns, social links |
17
+ | [forms-fieldset.md](forms-fieldset.md) | `.pp-fieldset`, `.pp-legend` |
18
+ | [forms-form-instructions.md](forms-form-instructions.md) | `.pp-form-instructions`, `.pp-form-hint`, `.pp-form-required-note` |
19
+ | [forms-label.md](forms-label.md) | `.pp-label`, tiers, scale, `.pp-label-row` |
20
+ | [forms-text-field.md](forms-text-field.md) | `.pp-field`, input, textarea, hint, message, icon wrap |
21
+ | [forms-validation.md](forms-validation.md) | `.pp-validation-summary`, `.pp-confirm`, `ppValidation` API |
22
+ | [gradient.md](gradient.md) | `.gradient-txt` |
23
+ | [header.md](header.md) | `.pp-header`, nav, dropdown, mobile drawer |
24
+ | [modal.md](modal.md) | `.pp-modal-backdrop`, `.pp-modal`, `ppModal` API |
25
+ | [section.md](section.md) | `.pp-section`, variants, scrollbar |
26
+ | [select.md](select.md) | Native `<select>`, `.pp-select`, custom dropdown |
27
+ | [table.md](table.md) | `.pp-table`, column helpers |
28
+ | [tabs.md](tabs.md) | `.pp-tabs`, variants, panels, keyboard nav |
29
+ | [typography.md](typography.md) | Font, size, weight, spacing utility classes |
30
+ | [utilities.md](utilities.md) | Display, spacing, flex, grid, position, z-index, responsive prefixes |
31
+
32
+ ## ARIA & WCAG requirements
33
+
34
+ PeppertinoCSS is built to be accessible by default, but **correct HTML usage is the developer's responsibility**. When implementing any component:
35
+
36
+ 1. **Always apply the correct ARIA roles, states, and properties** as documented in each component file. The CSS visual states are driven by ARIA attributes — missing attributes means broken accessibility, not just broken styling.
37
+
38
+ 2. **When in doubt about an ARIA rule or WCAG criterion, fetch the authoritative source** rather than guessing:
39
+ - ARIA specification: https://www.w3.org/TR/wai-aria/
40
+ - ARIA authoring practices (patterns): https://www.w3.org/WAI/ARIA/apg/patterns/
41
+ - WCAG 2.2 quick reference: https://www.w3.org/WAI/WCAG22/quickref/
42
+ - W3C Forms Tutorial: https://www.w3.org/WAI/tutorials/forms/
43
+
44
+ 3. **Minimum WCAG conformance target is AA.** This means:
45
+ - Text contrast ≥ 4.5:1 (normal text), ≥ 3:1 (large text / UI components)
46
+ - All interactive elements keyboard accessible
47
+ - All form controls have a visible, programmatically associated label
48
+ - Error messages are identified in text and associated with the offending field
49
+ - No content relies on color alone to convey meaning
50
+
51
+ 4. **Do not assume a component is accessible just because it uses the right CSS classes.** Verify:
52
+ - Required ARIA attributes are present in the HTML
53
+ - `id` / `for` associations are correct and unique on the page
54
+ - Focus order is logical
55
+ - Dynamic state changes (open/closed, selected, invalid) are reflected in ARIA attributes
56
+
57
+ 5. **Test with a screen reader** (NVDA + Chrome, VoiceOver + Safari, or JAWS + Edge) when implementing interactive components such as modals, dropdowns, carousels, and form validation.
58
+
59
+ ## Conventions
60
+
61
+ - All components use the `pp-` prefix except buttons (`.button`).
62
+ - BEM: `pp-block__element--modifier`.
63
+ - JS shims are optional — CSS visual states are driven by classes and ARIA attributes that any JS can set.
64
+ - Icons use Lucide (`data-lucide="name"`), initialised with `lucide.createIcons()`.
65
+ - CDN: `https://cdn.jsdelivr.net/npm/@auriel/peppertino@latest/dist/`