@auriel/peppertino 0.6.1 → 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 CHANGED
@@ -4,6 +4,15 @@ 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
+
7
16
  ------------------------------------------------------------------------
8
17
  v0.6.1 — 2026-11-22
9
18
  ------------------------------------------------------------------------
package/README.md CHANGED
@@ -59,9 +59,9 @@ Then open `http://localhost:3000` in your browser.
59
59
 
60
60
  ---
61
61
 
62
- ## Claude Code skill
62
+ ## Agent reference and skill
63
63
 
64
- The `agents/` directory ships a Claude Code skill that gives AI agents per-component reference documentation covering classes, variants, ARIA requirements, and JS APIs.
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,7 +89,9 @@ cp -r agents/peppertino ~/.claude/skills/peppertino
87
89
 
88
90
  | File | Covers |
89
91
  |---|---|
90
- | `skill.md` | Index, ARIA/WCAG requirements, conventions |
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 |
@@ -98,6 +102,7 @@ cp -r agents/peppertino ~/.claude/skills/peppertino
98
102
  | `components-inputs.md` | Native input patterns and optional application behavior |
99
103
  | `components-ai-search.md` | Response and search presentation, streaming and privacy |
100
104
  | `carousel.md` | Carousel markup, API, keyboard |
105
+ | `dark-mode.md` | Dark theme tokens and optional theme behavior |
101
106
  | `footer.md` | Footer columns, social links |
102
107
  | `forms-fieldset.md` | Fieldset & legend |
103
108
  | `forms-form-instructions.md` | Pre-form instructions, hints |
@@ -105,6 +110,7 @@ cp -r agents/peppertino ~/.claude/skills/peppertino
105
110
  | `forms-text-field.md` | Field wrapper, input, hint, validation |
106
111
  | `forms-validation.md` | Summary, confirmation checkbox, `ppValidation` API |
107
112
  | `gradient.md` | Gradient text |
113
+ | `glass.md` | `.glass` utility, independent glass components, fallbacks, and customization |
108
114
  | `header.md` | Header, nav, dropdown, mobile drawer |
109
115
  | `modal.md` | Modal, actions, `ppModal` API |
110
116
  | `section.md` | Section variants, scrollbar |
@@ -115,13 +121,41 @@ cp -r agents/peppertino ~/.claude/skills/peppertino
115
121
  | `toast.md` | Toast positions, variants, `ppToast` API |
116
122
  | `tooltip.md` | Tooltip placements, CSS-only usage |
117
123
  | `typography.md` | All typography utility classes |
124
+ | `utilities.md` | Utility classes and separately importable helper families |
118
125
 
119
- The skill's `skill.md` enforces ARIA and WCAG AA compliance rules and instructs the agent to fetch authoritative specs from w3.org when uncertain.
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.
120
127
 
121
128
  ---
122
129
 
123
130
  ## What's inside
124
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
+
125
159
  ### SCSS modules (`src/scss/`)
126
160
 
127
161
  | File | Purpose |
@@ -134,7 +168,7 @@ The skill's `skill.md` enforces ARIA and WCAG AA compliance rules and instructs
134
168
  | `button.scss` | `.pp-button`, `.pp-button--outline`, semantic variants |
135
169
  | `card.scss` | `.pp-card` and variants |
136
170
  | `carousel.scss` | `.pp-carousel` — CSS scroll-snap carousel |
137
- | `dark-mode.scss` | `.dark` overrides for all `--pp-*` tokens — applied last |
171
+ | `dark-mode.scss` | `.dark` token and component overrides |
138
172
  | `footer.scss` | `.pp-footer` — multi-column footer |
139
173
  | `forms.scss` | Aggregator for all form partials |
140
174
  | `forms/fieldset.scss` | `.pp-fieldset` + `.pp-legend` |
@@ -186,6 +220,11 @@ The skill's `skill.md` enforces ARIA and WCAG AA compliance rules and instructs
186
220
  | `helpers/spacing.scss` | Logical spacing helpers |
187
221
  | `helpers/typography.scss` | Text alignment, wrapping, and typography helpers |
188
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 |
189
228
 
190
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.
191
230
 
@@ -292,6 +331,21 @@ All named widths work with `respond-to`, `respond-below`, and `respond-between`.
292
331
 
293
332
  ## Components
294
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
+
295
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.
296
350
 
297
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/).
@@ -16,6 +16,7 @@ For standalone component markup and imports, see [catalog.md](catalog.md). Read
16
16
  - [components-inputs.md](components-inputs.md): duration, OTP, theme, tasks, reactions, model picker, and prompt.
17
17
  - [components-ai-search.md](components-ai-search.md): response and search presentation, streaming and privacy boundaries.
18
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.
19
20
 
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.
21
22
 
@@ -36,6 +37,7 @@ Prefer native HTML behavior and modular SCSS. Do not introduce a dependency on P
36
37
  | [forms-text-field.md](forms-text-field.md) | `.pp-field`, input, textarea, hint, message, icon wrap |
37
38
  | [forms-validation.md](forms-validation.md) | `.pp-validation-summary`, `.pp-confirm`, `ppValidation` API |
38
39
  | [gradient.md](gradient.md) | `.pp-gradient-text` |
40
+ | [glass.md](glass.md) | `.glass` utility and standalone glass panel, button, and navigation |
39
41
  | [header.md](header.md) | `.pp-header`, nav, dropdown, mobile drawer |
40
42
  | [modal.md](modal.md) | `.pp-modal-backdrop`, `.pp-modal`, `ppModal` API |
41
43
  | [section.md](section.md) | `.pp-section`, variants, scrollbar |
@@ -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 — 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/`
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.