@auriel/peppertino 0.5.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.txt +242 -224
- package/LICENSE +21 -21
- package/MIGRATION.md +52 -52
- package/README.md +773 -764
- package/agents/peppertino/SKILL.md +76 -0
- package/agents/peppertino/accordion.md +134 -0
- package/agents/peppertino/alert.md +116 -0
- package/agents/peppertino/badge.md +74 -0
- package/agents/peppertino/base.md +252 -0
- package/agents/peppertino/button.md +65 -0
- package/agents/peppertino/card.md +82 -0
- package/agents/peppertino/carousel.md +147 -0
- package/agents/peppertino/catalog.md +81 -0
- package/agents/peppertino/dark-mode.md +152 -0
- package/agents/peppertino/footer.md +109 -0
- package/agents/peppertino/forms-fieldset.md +85 -0
- package/agents/peppertino/forms-form-instructions.md +94 -0
- package/agents/peppertino/forms-label.md +110 -0
- package/agents/peppertino/forms-text-field.md +134 -0
- package/agents/peppertino/forms-validation.md +153 -0
- package/agents/peppertino/gradient.md +41 -0
- package/agents/peppertino/header.md +105 -0
- package/agents/peppertino/modal.md +123 -0
- package/agents/peppertino/section.md +56 -0
- package/agents/peppertino/select.md +110 -0
- package/agents/peppertino/switch.md +72 -0
- package/agents/peppertino/table.md +69 -0
- package/agents/peppertino/tabs.md +115 -0
- package/agents/peppertino/toast.md +96 -0
- package/agents/peppertino/tooltip.md +111 -0
- package/agents/peppertino/typography.md +118 -0
- package/agents/peppertino/utilities.md +194 -0
- package/agents/skill.md +65 -0
- package/build.js +53 -53
- package/dist/accordion.js +1 -1
- package/dist/accordion.js.map +2 -2
- package/dist/alert.js.map +1 -1
- package/dist/carousel.js.map +1 -1
- package/dist/header.js.map +1 -1
- package/dist/main.css +2566 -1008
- package/dist/main.css.map +1 -1
- package/dist/main.min.css +1 -0
- package/dist/modal.js.map +1 -1
- package/dist/peppertino.js +1 -1
- package/dist/peppertino.js.map +2 -2
- package/dist/select.js.map +1 -1
- package/dist/switch.js.map +1 -1
- package/dist/tabs.js.map +1 -1
- package/dist/theme.js.map +1 -1
- package/dist/toast.js.map +1 -1
- package/dist/validation.js.map +1 -1
- package/icon.svg +4 -0
- package/index.html +2172 -2098
- package/package.json +28 -28
- package/scripts/hex-to-hsl.mjs +75 -75
- package/scripts/lint-bem.mjs +53 -53
- package/scripts/lint-colors.mjs +87 -87
- package/site.webmanifest +18 -0
- package/src/js/accordion.js +105 -103
- package/src/js/alert.js +28 -28
- package/src/js/carousel.js +153 -153
- package/src/js/header.js +85 -85
- package/src/js/modal.js +138 -138
- package/src/js/peppertino.js +15 -15
- package/src/js/select.js +101 -101
- package/src/js/switch.js +28 -28
- package/src/js/tabs.js +104 -104
- package/src/js/theme.js +47 -47
- package/src/js/toast.js +79 -79
- package/src/js/validation.js +132 -132
- package/src/scss/accordion.scss +190 -156
- package/src/scss/activity.scss +17 -0
- package/src/scss/alert.scss +203 -203
- package/src/scss/badge.scss +90 -90
- package/src/scss/base.scss +511 -506
- package/src/scss/button.scss +119 -119
- package/src/scss/card.scss +121 -121
- package/src/scss/carousel.scss +303 -303
- package/src/scss/code-block.scss +22 -0
- package/src/scss/counter.scss +5 -0
- package/src/scss/dark-mode.scss +514 -514
- package/src/scss/duration.scss +26 -0
- package/src/scss/folder.scss +27 -0
- package/src/scss/footer.scss +224 -224
- package/src/scss/forms/fieldset.scss +127 -127
- package/src/scss/forms/form-instructions.scss +133 -133
- package/src/scss/forms/label.scss +115 -115
- package/src/scss/forms/text-field.scss +240 -240
- package/src/scss/forms/validation.scss +215 -215
- package/src/scss/forms.scss +8 -8
- package/src/scss/gradient.scss +11 -11
- package/src/scss/gravity-letters.scss +7 -0
- package/src/scss/header.scss +257 -238
- package/src/scss/helpers/color.scss +9 -0
- package/src/scss/helpers/flex.scss +14 -0
- package/src/scss/helpers/index.scss +6 -0
- package/src/scss/helpers/layout.scss +14 -0
- package/src/scss/helpers/spacing.scss +14 -0
- package/src/scss/helpers/typography.scss +11 -0
- package/src/scss/helpers/visibility.scss +9 -0
- package/src/scss/main.scss +49 -24
- package/src/scss/modal.scss +188 -188
- package/src/scss/model-picker.scss +5 -0
- package/src/scss/notification.scss +5 -0
- package/src/scss/orb.scss +7 -0
- package/src/scss/otp.scss +5 -0
- package/src/scss/pill-nav.scss +10 -0
- package/src/scss/prompt.scss +28 -0
- package/src/scss/rail.scss +7 -0
- package/src/scss/reactions.scss +5 -0
- package/src/scss/reset.scss +84 -84
- package/src/scss/response.scss +11 -0
- package/src/scss/reveal.scss +5 -0
- package/src/scss/scroll-progress.scss +4 -0
- package/src/scss/search-results.scss +13 -0
- package/src/scss/section.scss +87 -79
- package/src/scss/select.scss +210 -210
- package/src/scss/sidebar.scss +8 -0
- package/src/scss/status.scss +5 -0
- package/src/scss/step-list.scss +13 -0
- package/src/scss/switch.scss +121 -121
- package/src/scss/table.scss +89 -89
- package/src/scss/tabs.scss +156 -156
- package/src/scss/task-list.scss +18 -0
- package/src/scss/theme-picker.scss +5 -0
- package/src/scss/toast.scss +170 -170
- package/src/scss/tooltip.scss +126 -126
- package/src/scss/typography.scss +58 -58
- package/src/scss/utilities.scss +243 -243
- package/src/scss/voice-note.scss +5 -0
|
@@ -0,0 +1,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.
|
package/agents/skill.md
ADDED
|
@@ -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/`
|