@gallopsystems/agent-skills 1.30.0 → 1.31.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/README.md +13 -1
  2. package/package.json +1 -1
  3. package/plugins/copier-template/skills/copier-template/applying-updates.md +2 -2
  4. package/plugins/frontend-design/skills/frontend-design/SKILL.md +10 -10
  5. package/plugins/gallop-ui/.claude-plugin/plugin.json +8 -0
  6. package/plugins/gallop-ui/skills/gallop-ui/SKILL.md +108 -0
  7. package/plugins/gallop-ui/skills/gallop-ui/api-principles.md +157 -0
  8. package/plugins/gallop-ui/skills/gallop-ui/changing-the-layer.md +102 -0
  9. package/plugins/gallop-ui/skills/gallop-ui/checking-other-apps.md +108 -0
  10. package/plugins/gallop-ui/skills/gallop-ui/finding-a-component.md +92 -0
  11. package/plugins/gallop-ui/skills/gallop-ui/pitfalls.md +82 -0
  12. package/plugins/gallop-ui/skills/gallop-ui/pulling-updates.md +101 -0
  13. package/plugins/gallop-ui/skills/gallop-ui/using-in-an-app.md +122 -0
  14. package/plugins/linear/skills/linear/SKILL.md +4 -4
  15. package/plugins/linear/skills/linear/examples/frontend-feature.md +1 -1
  16. package/plugins/linear/skills/linear/tech-stack.md +12 -14
  17. package/plugins/nitro-testing/skills/nitro-testing/SKILL.md +3 -26
  18. package/plugins/nitro-testing/skills/nitro-testing/frontend-testing.md +7 -33
  19. package/plugins/tailwind-v4/skills/tailwind-v4/SKILL.md +12 -14
  20. package/plugins/tailwind-v4/skills/tailwind-v4/gotchas.md +13 -18
  21. package/plugins/vue-nuxt/skills/vue-nuxt/SKILL.md +2 -2
  22. package/plugins/vue-nuxt/skills/vue-nuxt/auto-imports.md +2 -2
  23. package/plugins/vue-nuxt/skills/vue-nuxt/template-idioms.md +1 -1
  24. package/plugins/vue-nuxt/skills/vue-nuxt/v-model.md +6 -6
  25. package/plugins/vue-nuxt/skills/vue-nuxt/watch.md +3 -3
  26. package/plugins/volt-primevue/.claude-plugin/plugin.json +0 -8
  27. package/plugins/volt-primevue/skills/volt-primevue/SKILL.md +0 -170
  28. package/plugins/volt-primevue/skills/volt-primevue/config.md +0 -51
  29. package/plugins/volt-primevue/skills/volt-primevue/gotchas.md +0 -140
  30. package/plugins/volt-primevue/skills/volt-primevue/theming.md +0 -137
@@ -301,13 +301,7 @@ export default isNuxtEnv
301
301
  }
302
302
  ```
303
303
 
304
- **Nuxt test config** (`nuxt.config.test.ts`):
305
- ```typescript
306
- export default defineNuxtConfig({
307
- modules: ["@primevue/nuxt-module"], // Include UI libraries
308
- ssr: false, // Disable SSR for simpler component testing
309
- });
310
- ```
304
+ The `nuxt` environment boots the app's real `nuxt.config.ts`, so the gallop-ui layer, `@nuxt/icon` and every auto-import are already there. No separate test config, no module list.
311
305
 
312
306
  ### File Organization
313
307
 
@@ -428,26 +422,9 @@ describe("Task Detail Page", () => {
428
422
  });
429
423
  ```
430
424
 
431
- ### Stubbing UI Library Components
425
+ ### UI Layer Components
432
426
 
433
- For PrimeVue or other UI libraries, stub complex components:
434
-
435
- ```typescript
436
- import { mountSuspended } from "@nuxt/test-utils/runtime";
437
- import ToastService from "primevue/toastservice";
438
- import ConfirmationService from "primevue/confirmationservice";
439
-
440
- const wrapper = await mountSuspended(MyComponent, {
441
- global: {
442
- plugins: [ToastService, ConfirmationService],
443
- stubs: {
444
- DataTable: true,
445
- Column: true,
446
- Dialog: true,
447
- },
448
- },
449
- });
450
- ```
427
+ Mount the real gallop-ui components; don't stub them and don't register services. `useToast()` and `useConfirm()` provide their state on the app the first time they run in setup, so a component that calls them mounts as is. To assert a toast or a confirmation, mock the composable (`mockNuxtImport("useToast", ...)`) or render `<Toaster />` / `<ConfirmDialog />` next to the component. Component props and `pt`: see the **gallop-ui** skill.
451
428
 
452
429
  ### Testing Utility Functions
453
430
 
@@ -61,17 +61,7 @@ export default isNuxtEnv
61
61
 
62
62
  ## Nuxt Test Configuration
63
63
 
64
- Create a minimal Nuxt config for testing:
65
-
66
- ```typescript
67
- // nuxt.config.test.ts
68
- export default defineNuxtConfig({
69
- modules: [
70
- "@primevue/nuxt-module", // Include UI libraries your components need
71
- ],
72
- ssr: false, // Simplifies component testing
73
- });
74
- ```
64
+ No extra config file. With `VITEST_ENV=nuxt` (`environment: "nuxt"`) vitest boots the app's own `nuxt.config.ts`, so the gallop-ui layer and every auto-import are available, and `hookTimeout` should stay at 30s (each file boots Nuxt; 10s fails under pre-push load).
75
65
 
76
66
  ## Package.json Scripts
77
67
 
@@ -265,44 +255,28 @@ describe("Task Detail Page", () => {
265
255
  });
266
256
  ```
267
257
 
268
- ### Testing with UI Libraries (PrimeVue)
258
+ ### Testing with the UI Layer (gallop-ui)
269
259
 
270
- Stub complex components and register required services:
260
+ Mount the real layer components. There is nothing to register or stub, and no service plugins:
271
261
 
272
262
  ```typescript
273
263
  import { describe, it, expect } from "vitest";
274
264
  import { mountSuspended } from "@nuxt/test-utils/runtime";
275
- import ToastService from "primevue/toastservice";
276
- import ConfirmationService from "primevue/confirmationservice";
277
265
  import ProjectForm from "./ProjectForm.vue";
278
266
 
279
267
  describe("ProjectForm", () => {
280
268
  it("renders form fields", async () => {
281
269
  const wrapper = await mountSuspended(ProjectForm, {
282
- props: {
283
- project: { id: 1, name: "", status: "draft" },
284
- },
285
- global: {
286
- plugins: [ToastService, ConfirmationService],
287
- stubs: {
288
- // Stub complex PrimeVue components
289
- DataTable: true,
290
- Column: true,
291
- Dialog: true,
292
- Calendar: true,
293
- Dropdown: true,
294
- // Keep simple components
295
- InputText: false,
296
- Button: false,
297
- },
298
- },
270
+ props: { project: { id: 1, name: "", status: "draft" } },
299
271
  });
300
272
 
301
- expect(wrapper.exists()).toBe(true);
273
+ expect(wrapper.find("input").exists()).toBe(true);
302
274
  });
303
275
  });
304
276
  ```
305
277
 
278
+ `useToast()` and `useConfirm()` set up their own state when called in setup. To assert on them, mock the composable with `mockNuxtImport` or render `<Toaster />` / `<ConfirmDialog />` in the test. Prop and `pt` details: the **gallop-ui** skill.
279
+
306
280
  ### Testing User Interactions
307
281
 
308
282
  ```typescript
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: tailwind-v4
3
- description: Work effectively with Tailwind CSS v4 (the CSS-first model) in a Nuxt/Vite + PrimeVue/Volt stack. Use when editing Tailwind CSS, configuring @theme/@source/@import, setting up dark mode, defining design tokens, or debugging classes that silently don't apply. Covers the v3→v4 traps an LLM trained on v3 falls into.
3
+ description: Work effectively with Tailwind CSS v4 (the CSS-first model) in a Nuxt/Vite + gallop-ui stack. Use when editing Tailwind CSS, configuring @theme/@source/@import, setting up dark mode, defining design tokens, or debugging classes that silently don't apply. Covers the v3→v4 traps an LLM trained on v3 falls into.
4
4
  ---
5
5
 
6
6
  # Tailwind CSS v4
@@ -26,8 +26,7 @@ There is **no `tailwind.config.js`/`.ts`**. The whole config is in your CSS entr
26
26
 
27
27
  ```css
28
28
  @import "tailwindcss"; /* NOT @tailwind base/components/utilities */
29
- @import "tailwindcss-primeui";
30
- @source "../../../src/volt"; /* scan sources Tailwind won't auto-detect */
29
+ @source "../../../layers"; /* scan sources Tailwind won't auto-detect */
31
30
 
32
31
  @theme {
33
32
  --color-surface: #ffffff; /* defines the bg-surface / text-surface utilities */
@@ -46,7 +45,7 @@ export default defineNuxtConfig({ vite: { plugins: [tailwindcss()] } });
46
45
  Do **not** add `@nuxtjs/tailwindcss`, a `postcss.config.js` with `tailwindcss: {}`,
47
46
  or `@tailwind base/components/utilities` — those are v3 and either no-op or break.
48
47
  `tailwindcss` itself must be a direct dependency (alongside `@tailwindcss/vite`),
49
- or `tailwindcss-primeui` raises peer-dependency warnings.
48
+ or tooling that peers on it raises peer-dependency warnings.
50
49
 
51
50
  ## Design tokens: `@theme` vs `:root`
52
51
 
@@ -58,16 +57,16 @@ or `tailwindcss-primeui` raises peer-dependency warnings.
58
57
  `bg-surface-strong` with no matching token) **generates nothing, with no error**
59
58
  — the element just renders unstyled. First thing to check when a custom color
60
59
  "does nothing": does the token name match exactly?
61
- - **Inverse for PrimeUI:** PrimeVue's `--p-*` variables stay in `:root`. The
62
- `tailwindcss-primeui` plugin turns those into utilities — don't move them into
63
- `@theme`.
60
+ - **gallop-ui reads a fixed token set** (`canvas`, `surface`, `fg`, `line`, `accent`, `field`…; the contract
61
+ is `layers/gallop-ui/TOKENS.md`). The app defines each in `@theme` with a dark override, so layer components
62
+ and your own markup flip together. Add a token the layer doesn't know and you also own its dark value.
64
63
 
65
64
  ## `@source` — v4 only generates classes from scanned files
66
65
 
67
66
  v4 auto-detects content, but skips files outside the project's default roots (and
68
67
  anything gitignored). Classes used **only** inside a vendored/library directory
69
- (e.g. Volt components in `src/volt`) get purged and silently go missing. Point
70
- Tailwind at them: `@source "../../../src/volt";`. If a vendored component's
68
+ (e.g. a Nuxt layer's components) get purged and silently go missing. Point
69
+ Tailwind at them with `@source`. If a vendored component's
71
70
  classes aren't generating, check this line first.
72
71
 
73
72
  ## Dark mode
@@ -101,8 +100,8 @@ default. Two consequences:
101
100
  ## More gotchas
102
101
 
103
102
  The full set mined from real debugging sessions — `@apply` in scoped `<style>`,
104
- JS-driven colors that can't read tokens, `@import url()` ordering, the PrimeUI
105
- surface ramp vs flipping tokens, and more — is in
103
+ JS-driven colors that can't read tokens, `@import url()` ordering, why raw
104
+ palette classes plus `dark:` don't mix with tokens, and more — is in
106
105
  [gotchas.md](gotchas.md). Read it when touching CSS in this stack.
107
106
 
108
107
  ## Optional tooling
@@ -114,9 +113,8 @@ class discovery, but it does not encode the stack-specific gotchas above.
114
113
 
115
114
  ## Related
116
115
 
117
- - **PrimeVue/Volt component styling** (`pt:` pass-through, `ptViewMerge`,
118
- `data-pc-*`, `@apply` + `@reference` in SFC `<style>`, reactive chart palettes):
119
- see the **volt-primevue** skill — it owns the component layer; this skill owns
116
+ - **Component styling** (the gallop-ui layer's components, `pt` and `class`, colour
117
+ tokens): see the **gallop-ui** skill. It owns the component layer; this skill owns
120
118
  the Tailwind-v4 fundamentals.
121
119
 
122
120
  ## Contributing Back
@@ -1,7 +1,7 @@
1
1
  # Tailwind v4 Gotchas
2
2
 
3
3
  Mined from real debugging sessions in this stack (Nuxt/Vite + Tailwind v4 +
4
- PrimeVue/Volt). Each is a place where a class silently did nothing, a v3 habit
4
+ gallop-ui). Each is a place where a class silently did nothing, a v3 habit
5
5
  broke, or the fix was non-obvious.
6
6
 
7
7
  ## `@apply` of custom tokens in a `<style>` block needs `@reference` to YOUR css
@@ -30,8 +30,7 @@ variables directly — `color: var(--color-fg)` always works with no `@reference
30
30
 
31
31
  Note: a full `yarn build` validates `@apply` in `<style>`; a bare
32
32
  `@tailwindcss/cli` compile does **not** — the CLI can pass while the real build
33
- fails. Include `build` in your check. (The SFC-specific details live in the
34
- **volt-primevue** skill's gotchas.)
33
+ fails. Include `build` in your check.
35
34
 
36
35
  ## `@import url(...)` must come before `@import "tailwindcss"`
37
36
 
@@ -52,20 +51,17 @@ written from script) can't use `bg-surface`/`var(--color-fg)` — the value is b
52
51
  at render and won't follow `prefers-color-scheme`. A `colors: ["#18181b"]`
53
52
  (near-black) chart line is invisible on dark. Compute a palette from a
54
53
  `window.matchMedia("(prefers-color-scheme: dark)")` match and recompute on its
55
- `change` event. (The volt-primevue skill has the Vue composable version.)
54
+ `change` event (VueUse's `usePreferredDark` does this in Vue).
56
55
 
57
- ## Two surface systems: PrimeUI's ramp is fixed, your `@theme` tokens flip
56
+ ## Tokens flip, raw palette classes don't
58
57
 
59
- - PrimeUI's `--p-surface-0 … --p-surface-950` ramp is defined **once** and does
60
- **not** change with the theme. `bg-surface-0` is always white — to go dark you
61
- need an explicit `dark:bg-surface-900` pair. Vendored Volt components rely on
62
- this full 0–950 ramp.
63
- - Your `@theme` semantic tokens (`--color-surface`, `--color-fg`) **flip their
64
- value** in the dark `@media` block, so `bg-surface` needs no `dark:`.
58
+ - Your `@theme` semantic tokens (`--color-surface`, `--color-fg`, `--color-line`) change value in the dark
59
+ block, so `bg-surface` needs no `dark:`. gallop-ui components are written the same way.
60
+ - A raw palette class (`bg-white`, `text-zinc-700`) is fixed. It needs a `dark:` pair, and forgetting it gives
61
+ white stripes on dark.
65
62
 
66
- Rule: tokenize only the markup you own (pages, your components). Leave vendored
67
- Volt components on the `surface-*` ramp + `dark:` pairs so they stay
68
- upstream-compatible. Mixing the two is what produces white-striped tables on dark.
63
+ Rule: use tokens in app markup, so there is no `dark:` half to forget. Keep raw palette classes for meaning-carrying
64
+ hues (red for an error, green for success). Don't restyle layer components with `dark:` pairs: change the token.
69
65
 
70
66
  ## Don't port a v3 `tailwind.config.js` into a v4 app
71
67
 
@@ -86,7 +82,6 @@ trigger an infinite dev-server regeneration loop. Use `@tailwindcss/vite`.
86
82
 
87
83
  ## Benign noise
88
84
 
89
- Under Yarn (esp. PnP), `@tailwindcss/vite` and `tailwindcss-primeui` may emit
90
- "doesn't provide vite/tailwindcss" unmet-peer-dependency warnings even though the
91
- deps resolve transitively. These are safe to ignore — they are not a config bug.
92
- (Adding `tailwindcss` as a direct dependency silences the `tailwindcss-primeui` one.)
85
+ Under Yarn (esp. PnP), `@tailwindcss/vite` may emit a "doesn't provide vite/tailwindcss"
86
+ unmet-peer-dependency warning even though the deps resolve transitively. It is safe to ignore,
87
+ and not a config bug. (Adding `tailwindcss` as a direct dependency silences the `tailwindcss` one.)
@@ -8,7 +8,7 @@ description: Author Vue 3 components inside a Nuxt 4 app. Covers Nuxt auto-impor
8
8
  Patterns for writing Vue 3 `<script setup>` components inside a Nuxt 4 app. This
9
9
  is the **frontend authoring** slice — the data layer (`useFetch`/`$fetch`, SSR
10
10
  storage, hydration, `definePageMeta`/auth) lives in the `nuxt-nitro-api` skill;
11
- Volt/PrimeVue styling and dark mode live in `volt-primevue`. This skill
11
+ components, styling and dark mode live in `gallop-ui`. This skill
12
12
  cross-links to those rather than restating them.
13
13
 
14
14
  ## When to Use This Skill
@@ -51,7 +51,7 @@ instead of testing those pieces as plain Vue functions.
51
51
  3. **`computed` for derivation, `watch` for escaping the graph.** If a watcher body just assigns one reactive value from others, it's a `computed`. Need to write a value back? A `computed` can have a setter — reach for a writable `computed` or `defineModel` before a sync watcher. Keep computed getters pure (no fetch, no mutation, no DOM).
52
52
  4. **Tie effects to lifecycle.** DOM measurement, listeners, observers, and timers go in `onMounted` and are torn down in `onUnmounted`. A computed reading live DOM geometry needs an explicit re-measure signal (DOM size isn't reactive). Before hand-rolling that effect-plus-teardown, check whether a **VueUse** composable already wraps it (`vueuse.md`) — they bundle the cleanup.
53
53
  5. **Call composables at the top of `<script setup>`** — never inside a callback or a template expression (both lose Nuxt's request scope). Derive display state with `computed`, guarding for possibly-null data.
54
- 6. **Defer to the right skill.** Fetch/SSR/auth/middleware → `nuxt-nitro-api`. Volt components, `pt:` styling, color tokens, dark mode → `volt-primevue`. Don't duplicate them here.
54
+ 6. **Defer to the right skill.** Fetch/SSR/auth/middleware → `nuxt-nitro-api`. UI components, `pt` styling, color tokens, dark mode → `gallop-ui`. Don't duplicate them here.
55
55
 
56
56
  ## Contributing Back
57
57
 
@@ -22,7 +22,7 @@ PascalCased filename:
22
22
  - **Guessing the bare filename fails silently.** `<FileUpload>` for `form/FileUpload.vue` resolves to nothing — no error, just an unrendered tag. If a component "isn't showing up," check the prefix first.
23
23
  - **Want a clean unprefixed tag?** Either explicitly import it
24
24
  (`import EstimateHeader from '~/components/estimates/EstimateHeader.vue'`), or
25
- register a directory with a prefix in `nuxt.config` (`components: [{ path: '../src/volt', prefix: 'Volt' }]` → `<VoltButton>`).
25
+ register a directory with a prefix in `nuxt.config` (`components: [{ path: '~/components/forms', prefix: 'Form' }]` → `<FormInput>`).
26
26
 
27
27
  ## What auto-imports (no `import` line)
28
28
 
@@ -36,7 +36,7 @@ naming collision.
36
36
 
37
37
  ## What does NOT auto-import (import explicitly)
38
38
 
39
- - **Third-party composables/components:** `useToast` from `'primevue/usetoast'`, `Column` from `'primevue/column'`, `date-fns` helpers, etc.
39
+ - **Third-party composables/components:** `date-fns` helpers, a Mapbox or Tiptap class, a composable from a package that is not a Nuxt module, etc. (gallop-ui's components, `useToast()`, `useConfirm()` and the `format*` helpers are auto-imported from the layer.)
40
40
  - **TypeScript types** — interfaces, enums, type aliases are never auto-imported. `import type { Foo } from '...'`.
41
41
  - **`server/utils`** — auto-imported on the *server* only, never into client code.
42
42
  - **Vitest unit tests** — plain `*.test.ts` files do NOT get Nuxt's auto-import context. Import the composable/util under test explicitly: `import { useFormatters } from './useFormatters'`. (Component tests via `@nuxt/test-utils/runtime` + `mountSuspended` DO have the context — see the `nitro-testing` skill.)
@@ -109,7 +109,7 @@ a dialog clipped inside a scrolling panel):
109
109
  <Teleport to="body"><div class="modal">…</div></Teleport>
110
110
  ```
111
111
 
112
- `<Teleport>` is auto-imported. (Volt/PrimeVue overlays already teleport
112
+ `<Teleport>` is auto-imported. (gallop-ui's `Modal`, `Drawer` and `Popover` already teleport
113
113
  internally; this is for your own hand-rolled overlays.)
114
114
 
115
115
  ## `<KeepAlive>` caches toggled-component state
@@ -40,15 +40,15 @@ const [model, modifiers] = defineModel<string>({
40
40
 
41
41
  ## The computed-proxy — for forwarding an existing model
42
42
 
43
- When you wrap a component that already has its own `v-model` (a Volt/PrimeVue
44
- `Dialog`'s `visible`, say), or you need a named local handle or a value
43
+ When you wrap a component that already has its own `v-model` (a gallop-ui
44
+ `Modal`'s `open`, say), or you need a named local handle or a value
45
45
  transform, use a writable `computed` over `props` + `emit`:
46
46
 
47
47
  ```ts
48
- const props = defineProps<{ visible: boolean }>()
49
- const emit = defineEmits<{ 'update:visible': [v: boolean] }>()
50
- const visible = computed({ get: () => props.visible, set: (v) => emit('update:visible', v) })
51
- // <Dialog v-model:visible="visible" />
48
+ const props = defineProps<{ open: boolean }>()
49
+ const emit = defineEmits<{ 'update:open': [v: boolean] }>()
50
+ const open = computed({ get: () => props.open, set: (v) => emit('update:open', v) })
51
+ // <Modal v-model:open="open" />
52
52
  ```
53
53
 
54
54
  A `computed({ get, set })` transforms a *forwarded* value shape (date string ↔
@@ -63,7 +63,7 @@ Only when the effect crosses **out of** the reactive graph:
63
63
  auto-refetches; see `nuxt-nitro-api/fetch-patterns.md`). Reach for `watch` only
64
64
  for imperative `$fetch` keyed off a single id.
65
65
  - **Drive a non-Vue library** — Tiptap, a Leaflet/Google map, a signature canvas,
66
- a PrimeVue popover you `.hide()` imperatively.
66
+ a Mapbox popup you `.remove()` imperatively.
67
67
  - **DOM / timers** — `document.body.style.overflow`, a debounce `setTimeout`, a
68
68
  polling `setInterval` (clear it in `onUnmounted`).
69
69
  - **Persist** — a `localStorage`/`useCookie` write, debounced auto-save of a
@@ -73,8 +73,8 @@ Only when the effect crosses **out of** the reactive graph:
73
73
  below). A write-back watch is the right tool only when the URL can't model the
74
74
  state: a ref with **two distinct "empty" states** (e.g. a filter that defaults to
75
75
  `"Open"` on load but clears to `null` — an absent param can map to only one of
76
- them), or a **composite object fanning out to many params** (a PrimeVue filter
77
- object) that a one-ref-per-param `useRouteQuery` can't express.
76
+ them), or a **composite object fanning out to many params** (a filter
77
+ object with six fields) that a one-ref-per-param `useRouteQuery` can't express.
78
78
  - **Re-seed local state on dialog open** — `watch(visible, (v) => { if (v) initForm() })`.
79
79
  The single most common legit pattern. Its one-liner is `whenever(visible, initForm)`
80
80
  (see `vueuse.md`); a compound guard keeps its inner half —
@@ -1,8 +0,0 @@
1
- {
2
- "name": "volt-primevue",
3
- "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",
4
- "version": "1.0.0",
5
- "author": {
6
- "name": "yeedle"
7
- }
8
- }
@@ -1,170 +0,0 @@
1
- ---
2
- name: volt-primevue
3
- 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.
4
- ---
5
-
6
- # Volt + PrimeVue UI
7
-
8
- Volt components are **PrimeVue unstyled components styled with Tailwind**. They
9
- ship as source you vendor into `src/volt/` and register with a `Volt` prefix, so
10
- you own the markup but track upstream styling conventions.
11
-
12
- ## When to Use This Skill
13
-
14
- - Building UI in a Nuxt + Tailwind v4 + PrimeVue/Volt project
15
- - Adding or customizing a Volt component
16
- - Anything color/theme/dark-mode related in this stack
17
- - Deciding between a Volt component and a hand-rolled one
18
-
19
- ## What Volt is
20
-
21
- - PrimeVue **unstyled** components + Tailwind classes, vendored under `src/volt/`.
22
- - Registered with a `Volt` prefix via `nuxt.config.ts` (`<VoltButton>`, `<VoltCard>`, …).
23
- - `app/assets/css/main.css` has `@source "../../../src/volt";` so Tailwind scans
24
- the vendored sources for class names. If a Volt class isn't generating, that
25
- `@source` line is the first thing to check.
26
-
27
- ## Adding components
28
-
29
- Use the CLI — **never hand-create a Volt component**:
30
-
31
- ```bash
32
- npx volt-vue add MultiSelect # adds src/volt/MultiSelect.vue
33
- ```
34
-
35
- Hand-writing one means you've guessed the PrimeVue part structure and the
36
- `surface-*`/`dark:` conventions; the generator gets both right and stays
37
- consistent with upstream.
38
-
39
- **`volt-vue add` is a one-time fetch, not a sync channel.** Volt's docs are
40
- explicit that vendored components [aren't meant to be updated](https://volt.primevue.org/overview/)
41
- — once added, the file is yours and editing it is the *expected* path, not a
42
- fallback. There's no `volt-vue update`. Upstream **behavior/structure** fixes
43
- arrive by bumping the **`primevue`** version (the unstyled logic is imported from
44
- it); the **styling** is yours to keep. So "edit the vendored source" carries no
45
- hidden regeneration penalty — that escape hatch was never there to lose.
46
-
47
- ## Customization — `pt:` pass-through
48
-
49
- Volt uses PrimeVue's pass-through API. Target a component's internal section with
50
- `pt:<section>:class`:
51
-
52
- ```vue
53
- <VoltButton pt:root:class="bg-zinc-900 hover:bg-zinc-800" />
54
- <VoltCard pt:root:class="rounded-2xl" pt:body:class="p-6" />
55
- ```
56
-
57
- **Use `pt:`, not a plain `class`.** Volt merges classes with
58
- [tailwind-merge](https://volt.primevue.org/overview/#twmerge), and the two paths
59
- differ in precedence:
60
-
61
- - `pt:{section}:class` is **merged with the component's defaults** and reliably
62
- overrides them — `pt:root:class="bg-primary"` wins.
63
- - A plain `class="bg-primary"` has **lower precedence and may not apply** — its
64
- conflicting utilities can lose to the component's own classes.
65
-
66
- So `<VoltInputText pt:root:class="bg-primary" />` works; `<VoltInputText
67
- class="bg-primary" />` may silently not.
68
-
69
- Both paths run through **`ptViewMerge` in `src/volt/utils.ts`**
70
- (`twMerge(globalClass, selfClass)` + Vue `mergeProps`), wired onto every component
71
- via `:ptOptions="{ mergeProps: ptViewMerge }"`. That local helper — not a global
72
- config — is the actual override point; it's *why* `pt:` reliably wins. To change
73
- merge behavior across components, edit `utils.ts`. See [gotchas.md](./gotchas.md).
74
-
75
- ### Restyle component states with `p-*` variants
76
-
77
- Per-state styling (active, focus, disabled, invalid) is expressed declaratively in
78
- the class string via `tailwindcss-primeui` variants — `p-selected:`, `p-focus:`,
79
- `p-disabled:`, `p-editable:`, `p-invalid:` (you'll see them throughout the
80
- vendored sources). They're plain Tailwind variants, so you can **override a state's
81
- look through `pt:`** without touching DOM or source:
82
-
83
- ```vue
84
- <VoltSelect pt:option:class="p-selected:bg-highlight p-focus:bg-surface-100" />
85
- ```
86
-
87
- Reach for these before editing vendored source — restyling the *active* or
88
- *disabled* appearance rarely needs a source edit.
89
-
90
- What `pt:` **can't** do is change DOM — it only restyles sections the component
91
- already renders. To add an element the component doesn't have (e.g. an animated
92
- overlay), you have two honest options, because Volt components are **vendored and
93
- yours to edit** (see [Choosing a component](#choosing-a-component-volt-vs-custom)):
94
- edit the component's source in `src/volt/`, or build a standalone component.
95
-
96
- ## Choosing a component: Volt vs custom
97
-
98
- Volt gives you selection semantics + accessibility for free. The question is only
99
- whether you need DOM/behavior the component doesn't render — and remember Volt
100
- components are **vendored and editable**, so "the component doesn't do X" has
101
- three answers, not two: restyle via `pt:`, **edit the source in `src/volt/`**, or
102
- build standalone.
103
-
104
- Worked example — **segmented toggle** (`SelectButton` vs a custom `SlidingTabs`).
105
- *Illustrative:* `SelectButton` isn't vendored in every project (e.g. not in this
106
- repo's `src/volt/` by default) — you'd `npx volt-vue add SelectButton` first.
107
-
108
- - `VoltSelectButton` ships v-model, single/multi-select, label+icon options, and
109
- proper radiogroup a11y, with a *highlighted-active* look.
110
- - A custom `SlidingTabs` adds an **animated indicator** (a single shared element
111
- that measures the active button and slides), responsive label collapse, and
112
- token-matched styling.
113
- - The active/focus/disabled *look* **is** `pt:`-reachable (via the `p-selected:`/
114
- `p-focus:` variants above). What `pt:` can't add is the **shared sliding
115
- element** — `SelectButton` toggles a per-button background and has no single
116
- position-measured overlay, and `pt:` changes classes, not DOM. Adding that
117
- indicator means editing the vendored `SelectButton.vue` (you keep its a11y +
118
- selection model) or building standalone.
119
-
120
- So the real decision:
121
-
122
- - **No animation needed → `SelectButton` as-is** (`pt:` to match your design).
123
- Free a11y + multi-select; don't reinvent it.
124
- - **Animated indicator / responsive collapse needed →** either **edit the
125
- vendored `SelectButton`** (keep its a11y; you own the file — which is true the
126
- moment you `volt-vue add` it anyway, so there's no regeneration to forfeit) **or
127
- build a standalone `SlidingTabs`** (clean and decoupled, but you owe the a11y
128
- yourself — `role="group"` + `aria-pressed` at minimum). Standalone wins when
129
- it's a *filter* toggle rather than a form field; editing the source wins when
130
- you want the full input semantics.
131
-
132
- ## Theming & dark mode
133
-
134
- This is the part people get wrong. Read **[theming.md](./theming.md)** — the
135
- two-layer color model (`surface-*` for Volt, semantic tokens for your markup),
136
- why they can't be unified, and the `prefers-color-scheme` mechanics.
137
-
138
- The one-paragraph version: dark mode follows the OS via
139
- `@media (prefers-color-scheme: dark)`. **Your app markup** uses semantic `@theme`
140
- tokens (`bg-surface`, `text-fg`, `border-line`) written **once** — the
141
- `--color-*` var flips in the dark media block, so there's no `dark:` half to
142
- forget. **Volt internals** stay on the `surface-*` scale with explicit `dark:`
143
- pairs — they need the full 0–950 ramp, and leaving them as `volt-vue add`
144
- generated them keeps regeneration easy. You *could* restyle a vendored component
145
- to tokens (it's your code), but the small token set can't express the whole ramp,
146
- so don't — tokens for your opinionated markup, `surface-*` for the component
147
- library.
148
-
149
- ## Gotchas
150
-
151
- See **[gotchas.md](./gotchas.md)** — the ones that cost real debugging time:
152
-
153
- - `@reference "main.css"` (not `"tailwindcss"`) for `@apply` of custom tokens in
154
- SFC `<style>` blocks.
155
- - JS-driven colors (ApexCharts, canvas) can't read CSS tokens — pick them from a
156
- reactive `prefers-color-scheme` palette.
157
- - A bare `boolean` prop casts to `false` when absent — default it with
158
- `withDefaults`, never rely on `undefined`.
159
- - The class merge lives in `ptViewMerge` (`src/volt/utils.ts`) — the lever when a
160
- `pt:` override won't take.
161
- - `data-pc-name` / `data-pc-section` to reach internals from CSS; `pc`-prefixed
162
- section names (`pt:pcBadge:…`) for nested child components.
163
- - We deliberately **don't** use `@primevue/forms` — zod + manual wiring instead.
164
-
165
- ## Plugin config
166
-
167
- See **[config.md](./config.md)** for PrimeVue plugin options beyond colors —
168
- global `pt` defaults, `ptOptions` merge behavior, `zIndex` overlay stacking, and
169
- `locale`. (Keep `unstyled: true`; styled-mode `definePreset`/`theme.preset` are
170
- inert — see [theming.md](./theming.md).)
@@ -1,51 +0,0 @@
1
- # PrimeVue plugin config
2
-
3
- Options passed where PrimeVue is registered (`app.use(PrimeVue, { … })` / the Nuxt
4
- module config), beyond colors. Volt runs **`unstyled: true`** — keep that; it's
5
- what makes the components unstyled (and what makes styled-mode theming inert; see
6
- [theming.md](./theming.md)).
7
-
8
- ## App-wide section styling: global `pt`
9
-
10
- Instead of repeating the same `pt:` on every call site, set defaults once with a
11
- global `pt` object keyed by lowercase component name → sections. A component-level
12
- `pt:` still overrides the global:
13
-
14
- ```ts
15
- app.use(PrimeVue, {
16
- unstyled: true,
17
- pt: {
18
- dialog: { header: { class: "border-b border-line" } }, // every dialog's header
19
- select: { dropdown: { class: "text-fg-muted" } },
20
- },
21
- ptOptions: { mergeSections: true, mergeProps: true },
22
- });
23
- ```
24
-
25
- `ptOptions` governs how global + local combine: `mergeSections` (default `true`)
26
- merges section objects; `mergeProps` (default `false`) merges class/listener
27
- props rather than replacing. Set `mergeProps: true` if you want a call-site
28
- `pt:` to *add to* the global classes instead of replacing them. (Note the vendored
29
- components already pass their own `mergeProps: ptViewMerge` per-component — see
30
- [gotchas.md](./gotchas.md).)
31
-
32
- ## Config knobs worth knowing
33
-
34
- ```ts
35
- app.use(PrimeVue, {
36
- unstyled: true,
37
- zIndex: { modal: 1100, overlay: 1000, menu: 1000, tooltip: 1100 }, // overlay stacking
38
- locale: { /* aria, filter, date strings — overrides built-in en defaults */ },
39
- });
40
- ```
41
-
42
- - **`zIndex`** — the dial when a Volt overlay (dialog, menu, tooltip) renders
43
- under or over app chrome. Defaults: modal/tooltip `1100`, overlay/menu `1000`.
44
- - **`locale`** — overrides all built-in aria labels, filter/date/pagination
45
- strings (i18n, or just rewording an aria label).
46
- - **`inputVariant: 'outlined' | 'filled'`** — default `outlined`; affects input
47
- styling defaults.
48
- - **`ripple`** — irrelevant under unstyled (no ripple CSS), harmless if set.
49
-
50
- Don't set `theme` / `definePreset` — inert under `unstyled: true`
51
- ([theming.md](./theming.md)).