@gallopsystems/agent-skills 1.4.0 → 1.5.0

package/README.md

@@ -18,6 +18,7 @@ Then install the skills you want:
 /plugin install doctl@gallop-systems-agent-skills
 /plugin install git-github@gallop-systems-agent-skills
 /plugin install copier-template@gallop-systems-agent-skills
+/plugin install volt-primevue@gallop-systems-agent-skills
 ```
 
 ## Updating

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gallopsystems/agent-skills",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Gallop Systems Claude Code skills, symlinked into .claude/skills on install.",
   "license": "UNLICENSED",
   "repository": {

package/plugins/volt-primevue/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "volt-primevue",
+  "description": "Volt (unstyled PrimeVue + Tailwind) UI: adding components, pt: pass-through styling, the surface-* vs semantic-token color model, and prefers-color-scheme dark mode",
+  "version": "1.0.0",
+  "author": {
+    "name": "yeedle"
+  }
+}

package/plugins/volt-primevue/skills/volt-primevue/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: volt-primevue
+description: Build UIs with Volt (unstyled PrimeVue + Tailwind). Covers adding components, pt: pass-through customization, choosing components, and the two-layer color model for prefers-color-scheme dark mode.
+---
+
+# Volt + PrimeVue UI
+
+Volt components are **PrimeVue unstyled components styled with Tailwind**. They
+ship as source you vendor into `src/volt/` and register with a `Volt` prefix, so
+you own the markup but track upstream styling conventions.
+
+## When to Use This Skill
+
+- Building UI in a Nuxt + Tailwind v4 + PrimeVue/Volt project
+- Adding or customizing a Volt component
+- Anything color/theme/dark-mode related in this stack
+- Deciding between a Volt component and a hand-rolled one
+
+## What Volt is
+
+- PrimeVue **unstyled** components + Tailwind classes, vendored under `src/volt/`.
+- Registered with a `Volt` prefix via `nuxt.config.ts` (`<VoltButton>`, `<VoltCard>`, …).
+- `app/assets/css/main.css` has `@source "../../../src/volt";` so Tailwind scans
+  the vendored sources for class names. If a Volt class isn't generating, that
+  `@source` line is the first thing to check.
+
+## Adding components
+
+Use the CLI — **never hand-create a Volt component**:
+
+```bash
+npx volt-vue add MultiSelect      # adds src/volt/MultiSelect.vue
+```
+
+Hand-writing one means you've guessed the PrimeVue part structure and the
+`surface-*`/`dark:` conventions; the generator gets both right and stays
+consistent with upstream.
+
+## Customization — `pt:` pass-through
+
+Volt uses PrimeVue's pass-through API. Target a component's internal section with
+`pt:<section>:class`:
+
+```vue
+<VoltButton pt:root:class="bg-zinc-900 hover:bg-zinc-800" />
+<VoltCard pt:root:class="rounded-2xl" pt:body:class="p-6" />
+```
+
+**Use `pt:`, not a plain `class`.** Volt merges classes with
+[tailwind-merge](https://volt.primevue.org/overview/#twmerge), and the two paths
+differ in precedence:
+
+- `pt:{section}:class` is **merged with the component's defaults** and reliably
+  overrides them — `pt:root:class="bg-primary"` wins.
+- A plain `class="bg-primary"` has **lower precedence and may not apply** — its
+  conflicting utilities can lose to the component's own classes.
+
+So `<VoltInputText pt:root:class="bg-primary" />` works; `<VoltInputText
+class="bg-primary" />` may silently not.
+
+What `pt:` **can't** do is change DOM — it only restyles sections the component
+already renders. To add an element the component doesn't have (e.g. an animated
+overlay), you have two honest options, because Volt components are **vendored and
+yours to edit** (see [Choosing a component](#choosing-a-component-volt-vs-custom)):
+edit the component's source in `src/volt/`, or build a standalone component.
+
+## Choosing a component: Volt vs custom
+
+Volt gives you selection semantics + accessibility for free. The question is only
+whether you need DOM/behavior the component doesn't render — and remember Volt
+components are **vendored and editable**, so "the component doesn't do X" has
+three answers, not two: restyle via `pt:`, **edit the source in `src/volt/`**, or
+build standalone.
+
+Worked example — **segmented toggle** (`SelectButton` vs a custom `SlidingTabs`):
+
+- `VoltSelectButton` ships v-model, single/multi-select, label+icon options, and
+  proper radiogroup a11y, with a *highlighted-active* look.
+- A custom `SlidingTabs` adds an **animated indicator** (a single shared element
+  that measures the active button and slides), responsive label collapse, and
+  token-matched styling.
+- The slide **can't** come from `pt:` — `SelectButton` toggles a background class
+  per button and has no shared, position-measured overlay, and `pt:` changes
+  classes, not DOM. But that doesn't force a rewrite: since the source lives in
+  `src/volt/SelectButton.vue`, adding the indicator **there** is a legitimate
+  option (you keep its a11y + selection model).
+
+So the real decision:
+
+- **No animation needed → `SelectButton` as-is** (`pt:` to match your design).
+  Free a11y + multi-select; don't reinvent it.
+- **Animated indicator / responsive collapse needed →** either **edit the
+  vendored `SelectButton`** (keep its a11y, accept that you now own that file and
+  lose easy `volt-vue add` regeneration) **or build a standalone `SlidingTabs`**
+  (clean and decoupled, but you owe the a11y yourself — `role="group"` +
+  `aria-pressed` at minimum). Standalone wins when it's a *filter* toggle rather
+  than a form field; editing the source wins when you want the full input
+  semantics.
+
+## Theming & dark mode
+
+This is the part people get wrong. Read **[theming.md](./theming.md)** — the
+two-layer color model (`surface-*` for Volt, semantic tokens for your markup),
+why they can't be unified, and the `prefers-color-scheme` mechanics.
+
+The one-paragraph version: dark mode follows the OS via
+`@media (prefers-color-scheme: dark)`. **Your app markup** uses semantic `@theme`
+tokens (`bg-surface`, `text-fg`, `border-line`) written **once** — the
+`--color-*` var flips in the dark media block, so there's no `dark:` half to
+forget. **Volt internals** stay on the `surface-*` scale with explicit `dark:`
+pairs — they need the full 0–950 ramp, and leaving them as `volt-vue add`
+generated them keeps regeneration easy. You *could* restyle a vendored component
+to tokens (it's your code), but the small token set can't express the whole ramp,
+so don't — tokens for your opinionated markup, `surface-*` for the component
+library.
+
+## Gotchas
+
+See **[gotchas.md](./gotchas.md)** — the ones that cost real debugging time:
+
+- `@reference "main.css"` (not `"tailwindcss"`) for `@apply` of custom tokens in
+  SFC `<style>` blocks.
+- JS-driven colors (ApexCharts, canvas) can't read CSS tokens — pick them from a
+  reactive `prefers-color-scheme` palette.
+- A bare `boolean` prop casts to `false` when absent — default it with
+  `withDefaults`, never rely on `undefined`.

package/plugins/volt-primevue/skills/volt-primevue/gotchas.md

@@ -0,0 +1,66 @@
+# Gotchas
+
+The ones that cost real debugging time in this stack.
+
+## `@apply` of custom tokens in `<style>` needs `@reference "main.css"`
+
+Tailwind v4 SFC `<style>` blocks need a `@reference` to resolve `@apply`. The
+trap: `@reference "tailwindcss"` only loads the **default** theme — built-in
+colors (`zinc`, etc.) work, but your custom `@theme` tokens (`text-fg`,
+`bg-surface`) fail with *"Cannot apply unknown utility class."*
+
+```vue
+<style scoped>
+/* ❌ @reference "tailwindcss";  → @apply text-fg fails */
+@reference "../assets/css/main.css";   /* ✅ exposes your tokens */
+.prose :where(h2) { @apply text-fg; }
+</style>
+```
+
+`@reference` is relative to the SFC. Note `yarn build` validates `@apply` in
+`<style>`; a bare `@tailwindcss/cli` compile does **not**, so the CLI can pass
+while the real build fails — include `build` in your check.
+
+## JS-driven colors can't read CSS tokens — use a reactive palette
+
+Anything that sets colors as JS values (ApexCharts, canvas, SVG attributes
+written from script) can't use `bg-surface`/`var(--color-fg)` — the value is
+baked at render. Pick concrete colors from a reactive `prefers-color-scheme`
+match and recompute on change:
+
+```ts
+const isDark = ref(false);
+let mq: MediaQueryList | null = null;
+const sync = () => (isDark.value = mq?.matches ?? false);
+onMounted(() => {
+  mq = window.matchMedia("(prefers-color-scheme: dark)");
+  sync();
+  mq.addEventListener("change", sync);
+});
+onBeforeUnmount(() => mq?.removeEventListener("change", sync));
+
+const palette = computed(() =>
+  isDark.value ? { fg: "#f4f4f5", line: "#f4f4f5", grid: "#27272a" }
+               : { fg: "#18181b", line: "#18181b", grid: "#f4f4f5" });
+```
+
+Mirror the dark values from `main.css`. A chart `colors: ["#18181b"]` (near-black)
+is invisible on dark — invert the line to a light value via the palette.
+
+## A bare `boolean` prop casts to `false` when absent — `withDefaults` it
+
+Vue's Boolean-prop casting: a prop typed `boolean` with **no default** coerces to
+`false` when the parent doesn't pass it — *not* `undefined`. So a "default-on"
+flag written as `responsive?: boolean` + `props.responsive !== false` is always
+`false` unless explicitly passed, and the feature silently never fires.
+
+```ts
+// ❌ absent → false → feature off, no error
+const props = defineProps<{ responsive?: boolean }>();
+// ✅ absent → true
+const props = withDefaults(defineProps<{ responsive?: boolean }>(), { responsive: true });
+```
+
+Not Volt-specific, but it bit the `SlidingTabs` responsive collapse, so it lives
+here. Any "defaults to on" boolean prop must use `withDefaults` (or invert it to
+an opt-out flag that naturally defaults false).

package/plugins/volt-primevue/skills/volt-primevue/theming.md

@@ -0,0 +1,123 @@
+# Theming & dark mode
+
+Dark mode follows the OS: `@media (prefers-color-scheme: dark)`. No toggle, no
+`dark` class on `<html>`. Tailwind v4's `dark:` variant also keys on
+`prefers-color-scheme` by default, so everything reacts to the same signal.
+
+There are **two color systems** in play, and the whole skill is knowing which to
+use where.
+
+## The two layers
+
+| | App markup (you own) | Volt internals (vendored) |
+|---|---|---|
+| **System** | semantic `@theme` tokens | `surface-*` scale + `dark:` pairs |
+| **Example** | `bg-surface text-fg` | `bg-surface-0 dark:bg-surface-900` |
+| **How it flips** | the `--color-*` var changes value in the dark media block | each shade is fixed; the component picks the dark end with `dark:` |
+| **You write** | once | both halves |
+
+### Why not use semantic tokens everywhere (incl. Volt)?
+
+You *can* — Volt components are vendored and editable, so nothing stops you from
+restyling one to `bg-surface text-fg`. The reasons not to are practical, in
+descending order of weight:
+
+1. **Vocabulary mismatch (the real one).** Semantic tokens are a small,
+   opinionated set (`surface`, `surface-muted`, `line`, `fg`, `fg-muted`, …) for
+   "card / text / border" decisions. A component library reaches all over the
+   0–950 ramp — subtle fills, two border weights, icon idle vs hover, elevation
+   layering. To express all of Volt in tokens you'd expand them until they *are*
+   the ramp, at which point you've just renamed `surface-*`.
+2. **Regeneration convenience.** `volt-vue add` scaffolds a component in the
+   upstream `surface-*` + `dark:` convention. Restyle it and you own that file —
+   re-adding or pulling a newer version later means redoing your edits. Leaving
+   Volt as-generated keeps that escape hatch cheap. (This is a convenience cost,
+   not "you diverge from upstream forever" — there's no continuous sync; you add
+   once and own it either way.)
+3. **The convention they ship in.** As generated, `--p-surface-0…950` are fixed
+   (never flipped), so a Volt component flips by *picking the dark end* with
+   `dark:bg-surface-900` — not by a value that changes. Semantic tokens flip the
+   variable's value instead, so one class covers both schemes. You could rewrite
+   a component to the token style, but then you're back to reasons 1 and 2.
+
+## The token set
+
+Defined in `app/assets/css/main.css`: light values in a top-level `@theme`
+block, dark values overriding the same `--color-*` vars inside the
+`prefers-color-scheme: dark` media block.
+
+```css
+@theme {
+  --color-canvas: #fafafa;        /* app background */
+  --color-surface: #ffffff;       /* cards, panels, dialogs */
+  --color-surface-muted: #fafafa; /* subtle fills, row hover */
+  --color-line: #e4e4e7;          /* borders */
+  --color-line-soft: #f4f4f5;     /* soft dividers */
+  --color-fg: #18181b;            /* primary text */
+  --color-fg-muted: #71717a;      /* secondary text */
+  --color-fg-subtle: #a1a1aa;     /* tertiary text */
+  --color-accent: #18181b;        /* inverted/primary fills (buttons) */
+  --color-on-accent: #ffffff;     /* text/icon on an accent fill */
+  --color-fill: #e4e4e7;          /* neutral solid fills: avatars, tracks, dots */
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-canvas: #09090b;
+    --color-surface: #18181b;
+    --color-surface-muted: #27272a;
+    --color-line: #27272a;
+    --color-line-soft: #27272a;
+    --color-fg: #f4f4f5;
+    --color-fg-muted: #b4b4bc;    /* lifted off a strict mirror-invert for legibility */
+    --color-fg-subtle: #8c8c95;   /* ~5.5:1 on near-black */
+    --color-accent: #f4f4f5;      /* inverts so filled buttons read on dark */
+    --color-on-accent: #18181b;
+    --color-fill: #3f3f46;
+  }
+}
+```
+
+The dark `fg-muted` / `fg-subtle` are **lifted** off a strict mirror-invert —
+the perfectly-inverted values are too dark to read on near-black.
+
+### Where each layer lives (and why it's not fighting Volt)
+
+[Volt's Nuxt setup](https://volt.primevue.org/nuxt/#css-variables) prescribes the
+`--p-*` palette + semantic tokens in **`:root`**, with dark mode via
+`@media (prefers-color-scheme: dark)`. Keep that exactly as-is — don't move
+`--p-*` into `@theme`; the `tailwindcss-primeui` plugin already turns them into
+`surface-*` / `primary-*` utilities.
+
+Your semantic tokens go in **`@theme`** instead, because that's the Tailwind v4
+mechanism that generates the utilities (`--color-canvas` → `bg-canvas`). Defining
+them only in `:root` would set the variable but produce **no class**. So:
+
+- `--p-*` → `:root` (Volt's way; plugin generates `surface-*`)
+- `--color-*` → `@theme` (Tailwind's way; generates `bg-surface`, `text-fg`, …)
+
+Different namespaces, no collision: `bg-surface-0` (primeui, numbered) and
+`bg-surface` (your token, bare) coexist. Dark values for **both** sit in the same
+`prefers-color-scheme` block — your `--color-*` overrides next to Volt's `--p-*`
+overrides.
+
+## The naming trap (this one bites)
+
+In Tailwind v4 the utility name is the **full** variable suffix:
+
+- `--color-fg-subtle` → `text-fg-subtle`  ✅
+- `text-subtle` ❌ — generates **nothing**, element falls back to near-black
+
+A wrong/shortened token name fails silently (no class generated), so a
+suspicious "secondary text is black in dark mode" is almost always a misnamed
+token, not a wrong value. **Compile the CSS and grep the generated utilities** —
+don't eyeball the browser.
+
+## Adding a new token
+
+1. Add `--color-foo: <light>;` to the `@theme` block.
+2. Add `--color-foo: <dark>;` inside the dark media block.
+3. Use `bg-foo` / `text-foo` / `border-foo` — done, both schemes covered.
+
+No `dark:` variant, ever, for app markup. If you're typing `dark:` in a page or
+app component, you're reaching for the wrong layer.