@auriel/peppertino 0.6.0 → 0.7.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 +16 -0
- package/README.md +97 -5
- package/agents/peppertino/SKILL.md +11 -1
- package/agents/peppertino/catalog.md +2 -0
- package/agents/peppertino/components-ai-search.md +10 -0
- package/agents/peppertino/components-display.md +19 -0
- package/agents/peppertino/components-inputs.md +15 -0
- package/agents/peppertino/components-navigation.md +12 -0
- package/agents/peppertino/glass.md +16 -0
- package/agents/peppertino/utilities.md +1 -0
- package/agents/skill.md +5 -65
- package/dist/main.css +1056 -848
- package/dist/main.css.map +1 -1
- package/dist/main.min.css +1 -1
- package/index.html +28 -1
- package/package.json +1 -1
- package/src/scss/glass/_material.scss +23 -0
- package/src/scss/glass-button.scss +23 -0
- package/src/scss/glass-nav.scss +21 -0
- package/src/scss/glass-panel.scss +10 -0
- package/src/scss/helpers/glass.scss +5 -0
- package/src/scss/helpers/index.scss +1 -0
- package/src/scss/main.scss +4 -1
package/CHANGELOG.txt
CHANGED
|
@@ -4,6 +4,22 @@ PeppertinoCSS — Changelog
|
|
|
4
4
|
All notable changes are documented here in reverse chronological order.
|
|
5
5
|
Versioning follows semver. Dates are YYYY-MM-DD.
|
|
6
6
|
|
|
7
|
+
------------------------------------------------------------------------
|
|
8
|
+
v0.7.0 — 2026-11-22
|
|
9
|
+
------------------------------------------------------------------------
|
|
10
|
+
|
|
11
|
+
- Added an independently importable `.glass` material utility and standalone
|
|
12
|
+
glass panel, button, and navigation components.
|
|
13
|
+
- Added opaque fallbacks and reduced-transparency and forced-colors support.
|
|
14
|
+
- Updated the demo, source inventory, project structure, and agent guidance.
|
|
15
|
+
|
|
16
|
+
------------------------------------------------------------------------
|
|
17
|
+
v0.6.1 — 2026-11-22
|
|
18
|
+
------------------------------------------------------------------------
|
|
19
|
+
|
|
20
|
+
- Completed the README source inventory and added focused agent references
|
|
21
|
+
for display, navigation, inputs, AI/search, accessibility, and optional JS.
|
|
22
|
+
|
|
7
23
|
------------------------------------------------------------------------
|
|
8
24
|
v0.6.0 — 2026-11-22
|
|
9
25
|
------------------------------------------------------------------------
|
package/README.md
CHANGED
|
@@ -59,9 +59,9 @@ Then open `http://localhost:3000` in your browser.
|
|
|
59
59
|
|
|
60
60
|
---
|
|
61
61
|
|
|
62
|
-
##
|
|
62
|
+
## Agent reference and skill
|
|
63
63
|
|
|
64
|
-
The `agents/` directory
|
|
64
|
+
The `agents/peppertino/` directory contains the reusable Peppertino skill and its component references. Its entry point is [`SKILL.md`](agents/peppertino/SKILL.md); [`agents/skill.md`](agents/skill.md) points to that index. The guides cover component markup, modular SCSS imports, accessibility, Apple HIG considerations, and which behavior requires application code. They are included in the npm package.
|
|
65
65
|
|
|
66
66
|
### Install (project-level)
|
|
67
67
|
|
|
@@ -77,6 +77,8 @@ Then invoke it in Claude Code:
|
|
|
77
77
|
/peppertino
|
|
78
78
|
```
|
|
79
79
|
|
|
80
|
+
For Codex, copy the same directory to `~/.codex/skills/peppertino` and invoke it as `$peppertino` in a new session.
|
|
81
|
+
|
|
80
82
|
### Install (user-level — available in all projects)
|
|
81
83
|
|
|
82
84
|
```bash
|
|
@@ -87,13 +89,20 @@ cp -r agents/peppertino ~/.claude/skills/peppertino
|
|
|
87
89
|
|
|
88
90
|
| File | Covers |
|
|
89
91
|
|---|---|
|
|
90
|
-
| `
|
|
92
|
+
| `SKILL.md` | Skill entry point, reference index, accessibility, and conventions |
|
|
93
|
+
| `accordion.md` | Native and script-enhanced accordions |
|
|
94
|
+
| `alert.md` | Alert variants and optional dismissal behavior |
|
|
91
95
|
| `base.md` | Design tokens, spacing, breakpoints, mixins |
|
|
92
96
|
| `badge.md` | Badge variants, sizes, dot indicator |
|
|
93
97
|
| `button.md` | All button variants |
|
|
94
98
|
| `card.md` | Card parts, variants, grid |
|
|
95
99
|
| `catalog.md` | Standalone display, navigation, input, feedback, and AI/search patterns |
|
|
100
|
+
| `components-display.md` | Display and feedback components, motion and accessibility guidance |
|
|
101
|
+
| `components-navigation.md` | Standalone navigation and progress patterns |
|
|
102
|
+
| `components-inputs.md` | Native input patterns and optional application behavior |
|
|
103
|
+
| `components-ai-search.md` | Response and search presentation, streaming and privacy |
|
|
96
104
|
| `carousel.md` | Carousel markup, API, keyboard |
|
|
105
|
+
| `dark-mode.md` | Dark theme tokens and optional theme behavior |
|
|
97
106
|
| `footer.md` | Footer columns, social links |
|
|
98
107
|
| `forms-fieldset.md` | Fieldset & legend |
|
|
99
108
|
| `forms-form-instructions.md` | Pre-form instructions, hints |
|
|
@@ -101,6 +110,7 @@ cp -r agents/peppertino ~/.claude/skills/peppertino
|
|
|
101
110
|
| `forms-text-field.md` | Field wrapper, input, hint, validation |
|
|
102
111
|
| `forms-validation.md` | Summary, confirmation checkbox, `ppValidation` API |
|
|
103
112
|
| `gradient.md` | Gradient text |
|
|
113
|
+
| `glass.md` | `.glass` utility, independent glass components, fallbacks, and customization |
|
|
104
114
|
| `header.md` | Header, nav, dropdown, mobile drawer |
|
|
105
115
|
| `modal.md` | Modal, actions, `ppModal` API |
|
|
106
116
|
| `section.md` | Section variants, scrollbar |
|
|
@@ -111,13 +121,41 @@ cp -r agents/peppertino ~/.claude/skills/peppertino
|
|
|
111
121
|
| `toast.md` | Toast positions, variants, `ppToast` API |
|
|
112
122
|
| `tooltip.md` | Tooltip placements, CSS-only usage |
|
|
113
123
|
| `typography.md` | All typography utility classes |
|
|
124
|
+
| `utilities.md` | Utility classes and separately importable helper families |
|
|
114
125
|
|
|
115
|
-
The skill
|
|
126
|
+
The skill describes an accessibility target and links to authoritative guidance; using the skill or classes alone does not guarantee compliance. Check the rendered interface, keyboard behavior, contrast, and assistive technology support in the consuming application.
|
|
116
127
|
|
|
117
128
|
---
|
|
118
129
|
|
|
119
130
|
## What's inside
|
|
120
131
|
|
|
132
|
+
### Project structure
|
|
133
|
+
|
|
134
|
+
```text
|
|
135
|
+
Peppertino/
|
|
136
|
+
├── agents/
|
|
137
|
+
│ ├── skill.md # Pointer to the current skill index
|
|
138
|
+
│ └── peppertino/ # SKILL.md and component/utility guides
|
|
139
|
+
├── src/
|
|
140
|
+
│ ├── js/ # Optional JavaScript shims and aggregator
|
|
141
|
+
│ └── scss/
|
|
142
|
+
│ ├── main.scss # Full framework entry point
|
|
143
|
+
│ ├── forms/ # Form partials
|
|
144
|
+
│ ├── glass/ # Shared Sass-only glass mixin
|
|
145
|
+
│ ├── helpers/ # Independently importable helper families
|
|
146
|
+
│ └── *.scss # Component, foundation, and utility modules
|
|
147
|
+
├── scripts/ # Color and naming checks, color conversion
|
|
148
|
+
├── dist/ # Generated CSS and JavaScript (Git-ignored)
|
|
149
|
+
├── index.html # Local component and utility demo
|
|
150
|
+
├── icon.svg, site.webmanifest # Demo icon and web app metadata
|
|
151
|
+
├── build.js # JavaScript build configuration
|
|
152
|
+
├── package.json, package-lock.json
|
|
153
|
+
├── README.md, CHANGELOG.txt, MIGRATION.md
|
|
154
|
+
└── LICENSE
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
The full source file inventory follows. `dist/` is produced by `bun run build` and is included in the npm package; it is not tracked in Git.
|
|
158
|
+
|
|
121
159
|
### SCSS modules (`src/scss/`)
|
|
122
160
|
|
|
123
161
|
| File | Purpose |
|
|
@@ -130,7 +168,7 @@ The skill's `skill.md` enforces ARIA and WCAG AA compliance rules and instructs
|
|
|
130
168
|
| `button.scss` | `.pp-button`, `.pp-button--outline`, semantic variants |
|
|
131
169
|
| `card.scss` | `.pp-card` and variants |
|
|
132
170
|
| `carousel.scss` | `.pp-carousel` — CSS scroll-snap carousel |
|
|
133
|
-
| `dark-mode.scss` | `.dark`
|
|
171
|
+
| `dark-mode.scss` | `.dark` token and component overrides |
|
|
134
172
|
| `footer.scss` | `.pp-footer` — multi-column footer |
|
|
135
173
|
| `forms.scss` | Aggregator for all form partials |
|
|
136
174
|
| `forms/fieldset.scss` | `.pp-fieldset` + `.pp-legend` |
|
|
@@ -150,6 +188,45 @@ The skill's `skill.md` enforces ARIA and WCAG AA compliance rules and instructs
|
|
|
150
188
|
| `tooltip.scss` | `.pp-tooltip` — CSS-only tooltip; placements `--top/bottom/left/right` |
|
|
151
189
|
| `typography.scss` | Utility classes for font, size, weight, spacing |
|
|
152
190
|
| `utilities.scss` | Single-purpose layout/spacing/display/visibility classes |
|
|
191
|
+
| `main.scss` | Full framework entry point |
|
|
192
|
+
| `activity.scss` | Contribution or activity grid presentation |
|
|
193
|
+
| `code-block.scss` | Code display with an optional header |
|
|
194
|
+
| `counter.scss` | Numeric value presentation |
|
|
195
|
+
| `duration.scss` | Native hours and minutes inputs |
|
|
196
|
+
| `folder.scss` | Native folder-style disclosure |
|
|
197
|
+
| `gravity-letters.scss` | Optional decorative letter motion |
|
|
198
|
+
| `model-picker.scss` | Native model selection styling |
|
|
199
|
+
| `notification.scss` | Notification link or button with a count |
|
|
200
|
+
| `orb.scss` | Decorative orb and grid/matrix variants |
|
|
201
|
+
| `otp.scss` | One-time-code input styling |
|
|
202
|
+
| `pill-nav.scss` | Pill-style navigation links |
|
|
203
|
+
| `prompt.scss` | Prompt textarea and action area |
|
|
204
|
+
| `rail.scss` | Table-of-contents navigation rail |
|
|
205
|
+
| `reactions.scss` | Native reaction selection controls |
|
|
206
|
+
| `response.scss` | Response content surface |
|
|
207
|
+
| `reveal.scss` | Content presentation surface |
|
|
208
|
+
| `scroll-progress.scss` | Native progress indicator styling |
|
|
209
|
+
| `search-results.scss` | Search result list presentation |
|
|
210
|
+
| `sidebar.scss` | Vertical navigation links |
|
|
211
|
+
| `status.scss` | Inline status indicator and label |
|
|
212
|
+
| `step-list.scss` | Ordered process steps and current state |
|
|
213
|
+
| `task-list.scss` | Native checkbox task list |
|
|
214
|
+
| `theme-picker.scss` | Native appearance selection controls |
|
|
215
|
+
| `voice-note.scss` | Container for native audio playback |
|
|
216
|
+
| `helpers/index.scss` | Entry point for all modular helper families |
|
|
217
|
+
| `helpers/color.scss` | Text, background, and border color helpers |
|
|
218
|
+
| `helpers/flex.scss` | Additional flex alignment, order, and basis helpers |
|
|
219
|
+
| `helpers/layout.scss` | Sizing, aspect ratio, overflow, and layout helpers |
|
|
220
|
+
| `helpers/spacing.scss` | Logical spacing helpers |
|
|
221
|
+
| `helpers/typography.scss` | Text alignment, wrapping, and typography helpers |
|
|
222
|
+
| `helpers/visibility.scss` | Responsive visibility and accessible hiding helpers |
|
|
223
|
+
| `helpers/glass.scss` | `.glass` material utility for existing elements |
|
|
224
|
+
| `glass/_material.scss` | Shared Sass mixin; emits no CSS by itself |
|
|
225
|
+
| `glass-panel.scss` | Standalone glass surface component |
|
|
226
|
+
| `glass-button.scss` | Standalone native glass button |
|
|
227
|
+
| `glass-nav.scss` | Standalone glass navigation surface |
|
|
228
|
+
|
|
229
|
+
The standalone component and helper modules can be imported individually. See the [component guide](agents/peppertino/catalog.md) and [helper reference](agents/peppertino/utilities.md) for markup, module imports, and behavior.
|
|
153
230
|
|
|
154
231
|
### JS components (`src/js/`)
|
|
155
232
|
|
|
@@ -254,6 +331,21 @@ All named widths work with `respond-to`, `respond-below`, and `respond-between`.
|
|
|
254
331
|
|
|
255
332
|
## Components
|
|
256
333
|
|
|
334
|
+
### Glass materials
|
|
335
|
+
|
|
336
|
+
Import `@use '@auriel/peppertino/src/scss/helpers/glass';` for the `.glass` utility, or import individual `glass-panel`, `glass-button`, and `glass-nav` modules. These modules are also included in `main.scss`. Glass components provide their own material and do not need `.glass`:
|
|
337
|
+
|
|
338
|
+
```html
|
|
339
|
+
<div class="pp-card glass">An existing card with a glass surface</div>
|
|
340
|
+
<section class="pp-glass-panel">A standalone glass panel</section>
|
|
341
|
+
<button class="pp-glass-button" type="button">Continue</button>
|
|
342
|
+
<nav class="pp-glass-nav" aria-label="Example"><a href="/" aria-current="page">Home</a><a href="/settings">Settings</a></nav>
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
Set `--pp-glass-tint`, `--pp-glass-opaque`, `--pp-glass-text`, `--pp-glass-edge`, or `--pp-glass-blur` to customize. The defaults use Peppertino's surface and text tokens, with fallback colors when those tokens are absent; a standalone dark theme can supply its own values. The material falls back to an opaque surface without backdrop-filter or color-mix support, or when reduced transparency or forced colors are requested. Test contrast against actual backgrounds and light/dark themes. These are web CSS effects, not Apple's native Liquid Glass material; [Apple's material guidance](https://developer.apple.com/design/human-interface-guidelines/materials) recommends reserving prominent glass effects for functional layers and maintaining legibility.
|
|
346
|
+
|
|
347
|
+
The `.glass` helper changes material properties, including text, background, border color, and backdrop filter; it preserves layout and does not add interaction. Component hover and active styles can override the material, so check combinations with existing modifiers. None of the glass modules requires JavaScript.
|
|
348
|
+
|
|
257
349
|
Additional standalone modules for folder disclosure, code blocks, activity grids, step lists, counters, voice notes, status, decorative orbs, navigation, duration and OTP inputs, tasks, reactions, prompts, responses, and search results are documented in [the HTML-first component guide](agents/peppertino/catalog.md). Each `src/scss/<component>.scss` module can be imported individually and has fallback colors; application JavaScript is optional and replaceable. Live data, streaming, persistence, and other application behavior remain the consumer's responsibility.
|
|
258
350
|
|
|
259
351
|
The new `src/scss/helpers/` modules add independent color, logical spacing, flex, typography, layout, and visibility utilities. Import one family or `@use '@auriel/peppertino/src/scss/helpers'` for all of them. See [the utility reference](agents/peppertino/utilities.md) for classes, breakpoints, and accessibility notes. The helper categories were informed by [Bulma's helper documentation](https://bulma.io/documentation/helpers/).
|
|
@@ -9,7 +9,16 @@ This directory contains per-component reference documents for AI agents and tool
|
|
|
9
9
|
|
|
10
10
|
## Index
|
|
11
11
|
|
|
12
|
-
For
|
|
12
|
+
For standalone component markup and imports, see [catalog.md](catalog.md). Read the focused references relevant to the task:
|
|
13
|
+
|
|
14
|
+
- [components-display.md](components-display.md): folder, code, activity, counter, steps, status, notifications, audio, and decorative effects.
|
|
15
|
+
- [components-navigation.md](components-navigation.md): sidebar, rail, pill navigation, and progress.
|
|
16
|
+
- [components-inputs.md](components-inputs.md): duration, OTP, theme, tasks, reactions, model picker, and prompt.
|
|
17
|
+
- [components-ai-search.md](components-ai-search.md): response and search presentation, streaming and privacy boundaries.
|
|
18
|
+
- [utilities.md](utilities.md): individually importable helper families and accessible visibility.
|
|
19
|
+
- [glass.md](glass.md): glass utility and standalone components, customization, accessibility, and fallbacks.
|
|
20
|
+
|
|
21
|
+
Prefer native HTML behavior and modular SCSS. Do not introduce a dependency on Peppertino's JavaScript for new component styling; consumer scripts are optional and replaceable. Use short transitions that respect reduced motion; any new keyframe animation uses three points.
|
|
13
22
|
|
|
14
23
|
| File | Covers |
|
|
15
24
|
|---|---|
|
|
@@ -28,6 +37,7 @@ For the additional standalone HTML-first modules, see [catalog.md](catalog.md).
|
|
|
28
37
|
| [forms-text-field.md](forms-text-field.md) | `.pp-field`, input, textarea, hint, message, icon wrap |
|
|
29
38
|
| [forms-validation.md](forms-validation.md) | `.pp-validation-summary`, `.pp-confirm`, `ppValidation` API |
|
|
30
39
|
| [gradient.md](gradient.md) | `.pp-gradient-text` |
|
|
40
|
+
| [glass.md](glass.md) | `.glass` utility and standalone glass panel, button, and navigation |
|
|
31
41
|
| [header.md](header.md) | `.pp-header`, nav, dropdown, mobile drawer |
|
|
32
42
|
| [modal.md](modal.md) | `.pp-modal-backdrop`, `.pp-modal`, `ppModal` API |
|
|
33
43
|
| [section.md](section.md) | `.pp-section`, variants, scrollbar |
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
These original Peppertino patterns cover component types surveyed in [Rare UI's catalog](https://www.rareui.com/components). Each is a separate `src/scss/<name>.scss` module with fallback colors. Import a module by itself or use `main.scss`; no JavaScript or other component stylesheet is required. Peppertino's `--pp-*` tokens override the fallbacks when available. HTML examples below require unique IDs where indicated. Native HTML provides the interactions described; applications own any data loading, persistence, submission, or updating.
|
|
4
4
|
|
|
5
|
+
For detailed accessibility, HIG, and JavaScript guidance, see [display and feedback](components-display.md), [navigation](components-navigation.md), [inputs](components-inputs.md), and [AI and search](components-ai-search.md). See [utilities](utilities.md) for the modular helper families.
|
|
6
|
+
|
|
5
7
|
## Display
|
|
6
8
|
|
|
7
9
|
```html
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# Response, search, and application-owned behavior
|
|
2
|
+
|
|
3
|
+
`response.scss` and `search-results.scss` are standalone presentation modules. `prompt.scss` and `model-picker.scss` are covered in [components-inputs.md](components-inputs.md); complete markup is in [catalog.md](catalog.md). Consult Apple's [design principles](https://developer.apple.com/design/human-interface-guidelines/design-principles), [writing](https://developer.apple.com/design/human-interface-guidelines/writing), and [privacy](https://developer.apple.com/design/human-interface-guidelines/privacy) as relevant to the product.
|
|
4
|
+
|
|
5
|
+
- `.pp-response` provides a surface for response content; it does not fetch, stream, parse, sanitize, or announce it. Render untrusted text safely, preserve readable content without animation, and provide a concise separate status for completion or errors instead of announcing every streamed token.
|
|
6
|
+
- `.pp-search-results` provides a styled container and list spacing. It does not query a search service, rank results, or generate links. Use meaningful links, identify the results region, and provide useful loading, empty, and error states when applicable.
|
|
7
|
+
- Form actions, model choices, streaming, search, persistence, and backend validation belong to the consuming application. Use semantic HTML and a real server endpoint where appropriate so the baseline can remain usable without JavaScript; scripts are replaceable enhancements, not a requirement for styling.
|
|
8
|
+
- Make network and privacy behavior clear when it matters to a person's choice. Do not present mock output as a live result, place secrets in client-side markup, or imply that the CSS implements an AI or search service.
|
|
9
|
+
|
|
10
|
+
Use short, purposeful transitions with reduced-motion support. New keyframe animations, if needed, use three points; avoid blocking reading or input while effects run.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Display and feedback components
|
|
2
|
+
|
|
3
|
+
Use with [catalog.md](catalog.md), which contains working markup. Each named module is an independently importable `src/scss/<name>.scss`; these modules do not ship JavaScript. Apply the [HIG design principles](https://developer.apple.com/design/human-interface-guidelines/design-principles), [accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility), and [motion](https://developer.apple.com/design/human-interface-guidelines/motion) guidance to the actual platform and task.
|
|
4
|
+
|
|
5
|
+
| Module | What the CSS supplies | Consumer behavior |
|
|
6
|
+
|---|---|---|
|
|
7
|
+
| `folder` | `.pp-folder` disclosure surface and header | Use native `details` / `summary`; no script needed for toggling. |
|
|
8
|
+
| `code-block` | `.pp-code-block`, header and scrollable `pre` | Render escaped code; syntax highlighting or clipboard actions require application code. Do not show an inert copy button. |
|
|
9
|
+
| `activity` | `.pp-activity__grid` and `.pp-activity__day[data-level]` levels 0–4 | Supply data and an accessible text summary or table; color alone must not convey values. |
|
|
10
|
+
| `counter` | `.pp-counter` numeric styling | Supply an accurate text value. Any interpolation is optional; do not announce every animation frame. |
|
|
11
|
+
| `step-list` | `.pp-step-list` and `aria-current="step"` emphasis | Supply ordered steps and current state; it does not advance or navigate by itself. |
|
|
12
|
+
| `status` | `.pp-status` and `.pp-status__indicator` | Keep a meaningful textual status. Use a polite status region when updates should be announced. |
|
|
13
|
+
| `notification` | `.pp-notification` and count badge | Supply a real destination or action and an accessible name including the unread count; update both count and name together. |
|
|
14
|
+
| `voice-note` | `.pp-voice-note` container | Use native `<audio controls>` with an accessible label and a fallback link; loading and recording are application responsibilities. |
|
|
15
|
+
| `orb` | Decorative `.pp-orb`, `--grid`, `--matrix`, and `--pp-orb-size` | Mark purely decorative graphics `aria-hidden`; do not rely on them to communicate status. |
|
|
16
|
+
| `reveal` | `.pp-reveal` content surface | Content is visible by default. Effects are application-owned and must not hide essential information without script. |
|
|
17
|
+
| `gravity-letters` | `.pp-gravity-letters` and `__letter` hover transitions | Preserve a readable accessible name, hide duplicate decorative letters from assistive technology, and keep text legible without motion. |
|
|
18
|
+
|
|
19
|
+
Keep motion brief and purposeful. Respect `prefers-reduced-motion`; if authoring keyframes, use exactly three keyframe points. CSS defines presentation; consumers may add or replace scripts without altering the baseline. Test readable text, zoom, keyboard focus, reduced motion, and light/dark contrast. Validate real assistive technology behavior before claiming compliance.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Input and choice components
|
|
2
|
+
|
|
3
|
+
Use the examples in [catalog.md](catalog.md). Each module is separately importable and has no bundled JavaScript. Apply Apple's [text field](https://developer.apple.com/design/human-interface-guidelines/text-fields), [entering data](https://developer.apple.com/design/human-interface-guidelines/entering-data), and [accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility) guidance, adapting it to the web and target platform.
|
|
4
|
+
|
|
5
|
+
| Module | Native baseline | Consumer responsibilities |
|
|
6
|
+
|---|---|---|
|
|
7
|
+
| `duration` | `.pp-duration` fieldset with labelled number inputs and native min/max validation. | Choose sensible limits and validate on the server; do not assume CSS clamps values. Preserve keyboard and spinner operation. |
|
|
8
|
+
| `otp` | `.pp-otp` styles one labelled input; `autocomplete="one-time-code"` and `inputmode="numeric"` can assist entry. | Preserve leading zeros and paste/autofill; validate the intended format. Avoid splitting input unless there is a demonstrated need. |
|
|
9
|
+
| `theme-picker` | `.pp-theme-picker` styles a radio group. | Apply and persist the selection in application code; without it the form still collects the choice. Do not claim it switches themes by itself. |
|
|
10
|
+
| `task-list` | `.pp-task-list` styles checkboxes and checked text. | Persist or submit changes in application code; associate each checkbox with its label. |
|
|
11
|
+
| `reactions` | `.pp-reactions` styles native labelled radio controls. | Save or submit the choice and supply textual labels alongside emoji. |
|
|
12
|
+
| `model-picker` | `.pp-model-picker` styles a native `<select>`. | Supply accurate options, a visible label, and application behavior for the selection. |
|
|
13
|
+
| `prompt` | `.pp-prompt` styles a label, textarea, and `__actions`. | Use a real form and endpoint for no-script submission when feasible; script-driven submission must preserve keyboard use, validation, and error feedback. |
|
|
14
|
+
|
|
15
|
+
Use visible persistent labels, appropriate input types and autocomplete, and text errors associated with the field. Placeholder text is supplemental. Give controls room at large text sizes and avoid relying on color to convey errors. Keep application code replaceable: attach behavior to semantic markup or documented classes, do not make the SCSS depend on a framework or a particular script. Do not insert credentials or personal data into client-side examples.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# Navigation and progress components
|
|
2
|
+
|
|
3
|
+
See [catalog.md](catalog.md) for markup. `sidebar`, `rail`, `pill-nav`, and `scroll-progress` are separate SCSS modules with no JavaScript dependency. Follow Apple's [layout](https://developer.apple.com/design/human-interface-guidelines/layout), [navigation](https://developer.apple.com/design/human-interface-guidelines/navigation), and [accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility) guidance where relevant.
|
|
4
|
+
|
|
5
|
+
| Module | Baseline | Optional application behavior |
|
|
6
|
+
|---|---|---|
|
|
7
|
+
| `sidebar` | `.pp-sidebar` styles ordinary links; `aria-current="page"` marks the current page. | Routing may update the current page; pointer proximity must never be required to reveal or use links. |
|
|
8
|
+
| `rail` | `.pp-rail` styles an ordered list of in-page anchors. | Update `aria-current` as the visible section changes if scroll tracking is implemented. |
|
|
9
|
+
| `pill-nav` | `.pp-pill-nav` styles links and `aria-current="page"`. | Navigation follows normal link behavior; this is not a tab widget or a script-driven tablist. |
|
|
10
|
+
| `scroll-progress` | `.pp-scroll-progress` styles a native `<progress>`. | Compute and update its `value` if reporting live progress. A static value does not track scrolling automatically; omit `value` for an indeterminate progress indicator. |
|
|
11
|
+
|
|
12
|
+
Give navigation landmarks distinguishable accessible names and links real destinations. Keep source, reading, and focus order coherent; use text or another non-color distinction for the active state. Layout should adapt to available width and text size, rather than infer a device from viewport width. Ensure destinations work with script disabled where possible. Do not add ARIA roles or keyboard overrides that conflict with native links or `<progress>`.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Glass utility and components
|
|
2
|
+
|
|
3
|
+
`src/scss/helpers/glass.scss` exposes `.glass` for existing elements. `glass-panel.scss`, `glass-button.scss`, and `glass-nav.scss` define `.pp-glass-panel`, `.pp-glass-button`, and `.pp-glass-nav` independently: do not add `.glass` to make them work. Each module imports a Sass-only mixin from `glass/_material.scss`, which emits no styles on its own. The utility is also in the helpers aggregator; all modules are in `main.scss`.
|
|
4
|
+
|
|
5
|
+
```html
|
|
6
|
+
<div class="pp-card glass">Existing component</div>
|
|
7
|
+
<section class="pp-glass-panel">Panel content</section>
|
|
8
|
+
<button class="pp-glass-button" type="button">Continue</button>
|
|
9
|
+
<nav class="pp-glass-nav" aria-label="Views"><a href="/" aria-current="page">Home</a><a href="/saved">Saved</a></nav>
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
Use semantic native HTML; glass is presentation and supplies no interaction. Consumers can attach their own scripts without depending on Peppertino JavaScript. Style links and buttons with meaningful labels, visible focus, and actual destinations or actions. The utility changes the background, foreground color, border color, and backdrop filter but not layout; other component hover or active selectors may override it.
|
|
13
|
+
|
|
14
|
+
Customize `--pp-glass-tint`, `--pp-glass-opaque`, `--pp-glass-text`, `--pp-glass-edge`, and `--pp-glass-blur` as needed. Defaults use framework tokens when available and fall back to light colors when imported alone; standalone dark themes should supply dark values. Without supported backdrop filtering and color mixing, the surface is opaque. Reduced-transparency and forced-colors preferences remove the effect and use a solid surface.
|
|
15
|
+
|
|
16
|
+
Apply this effect selectively to maintain visual hierarchy and text contrast on real backgrounds. Apple's [materials guidance](https://developer.apple.com/design/human-interface-guidelines/materials) distinguishes functional layers from content layers and recommends using Liquid Glass sparingly; these CSS effects are inspired by translucent materials and do not implement Apple's native system material. Test contrast, keyboard focus, zoom, light/dark themes, unsupported filters, forced colors, and reduced transparency. Keep motion brief, respect reduced motion, and use three keyframe points if adding keyframes.
|
|
@@ -10,6 +10,7 @@ Import only the helper family needed, e.g. `@use '@auriel/peppertino/src/scss/he
|
|
|
10
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
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
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
|
+
- `glass`: `.glass` applies a translucent material to an existing element, with an opaque fallback and reduced-transparency support. See [glass.md](glass.md) for contrast, standalone imports, and the independent glass components.
|
|
13
14
|
|
|
14
15
|
**Source:** `src/scss/utilities.scss`
|
|
15
16
|
|
package/agents/skill.md
CHANGED
|
@@ -1,65 +1,5 @@
|
|
|
1
|
-
# PeppertinoCSS
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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/`
|
|
1
|
+
# PeppertinoCSS agent reference
|
|
2
|
+
|
|
3
|
+
The maintained skill entry point and reference index is [peppertino/SKILL.md](peppertino/SKILL.md). It routes to component, form, utility, accessibility, and glass-material guides in the same directory.
|
|
4
|
+
|
|
5
|
+
Use semantic HTML and independently importable SCSS where possible. JavaScript behavior is optional and replaceable; consult the relevant component reference to distinguish native functionality from application-owned behavior.
|