@gallopsystems/agent-skills 1.29.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 (38) 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/.claude-plugin/plugin.json +1 -1
  15. package/plugins/linear/skills/linear/SKILL.md +138 -864
  16. package/plugins/linear/skills/linear/cli.md +249 -0
  17. package/plugins/linear/skills/linear/examples/backend-data-model.md +31 -0
  18. package/plugins/linear/skills/linear/examples/backend-feature.md +30 -0
  19. package/plugins/linear/skills/linear/examples/bug.md +30 -0
  20. package/plugins/linear/skills/linear/examples/discovery.md +34 -0
  21. package/plugins/linear/skills/linear/examples/frontend-feature.md +36 -0
  22. package/plugins/linear/skills/linear/examples/right-and-wrong.md +138 -0
  23. package/plugins/linear/skills/linear/examples/small-improvement.md +24 -0
  24. package/plugins/linear/skills/linear/tech-stack.md +13 -15
  25. package/plugins/nitro-testing/skills/nitro-testing/SKILL.md +3 -26
  26. package/plugins/nitro-testing/skills/nitro-testing/frontend-testing.md +7 -33
  27. package/plugins/tailwind-v4/skills/tailwind-v4/SKILL.md +12 -14
  28. package/plugins/tailwind-v4/skills/tailwind-v4/gotchas.md +13 -18
  29. package/plugins/vue-nuxt/skills/vue-nuxt/SKILL.md +2 -2
  30. package/plugins/vue-nuxt/skills/vue-nuxt/auto-imports.md +2 -2
  31. package/plugins/vue-nuxt/skills/vue-nuxt/template-idioms.md +1 -1
  32. package/plugins/vue-nuxt/skills/vue-nuxt/v-model.md +6 -6
  33. package/plugins/vue-nuxt/skills/vue-nuxt/watch.md +3 -3
  34. package/plugins/volt-primevue/.claude-plugin/plugin.json +0 -8
  35. package/plugins/volt-primevue/skills/volt-primevue/SKILL.md +0 -170
  36. package/plugins/volt-primevue/skills/volt-primevue/config.md +0 -51
  37. package/plugins/volt-primevue/skills/volt-primevue/gotchas.md +0 -140
  38. package/plugins/volt-primevue/skills/volt-primevue/theming.md +0 -137
@@ -1,140 +0,0 @@
1
- # Gotchas
2
-
3
- The ones that cost real debugging time in this stack.
4
-
5
- ## `@apply` of custom tokens in `<style>` needs `@reference "main.css"`
6
-
7
- Tailwind v4 SFC `<style>` blocks need a `@reference` to resolve `@apply`. The
8
- trap: `@reference "tailwindcss"` only loads the **default** theme — built-in
9
- colors (`zinc`, etc.) work, but your custom `@theme` tokens (`text-fg`,
10
- `bg-surface`) fail with *"Cannot apply unknown utility class."*
11
-
12
- ```vue
13
- <style scoped>
14
- /* ❌ @reference "tailwindcss"; → @apply text-fg fails */
15
- @reference "../assets/css/main.css"; /* ✅ exposes your tokens */
16
- .prose :where(h2) { @apply text-fg; }
17
- </style>
18
- ```
19
-
20
- `@reference` is relative to the SFC. Note `yarn build` validates `@apply` in
21
- `<style>`; a bare `@tailwindcss/cli` compile does **not**, so the CLI can pass
22
- while the real build fails — include `build` in your check.
23
-
24
- ## JS-driven colors can't read CSS tokens — use a reactive palette
25
-
26
- Anything that sets colors as JS values (ApexCharts, canvas, SVG attributes
27
- written from script) can't use `bg-surface`/`var(--color-fg)` — the value is
28
- baked at render. Pick concrete colors from a reactive `prefers-color-scheme`
29
- match and recompute on change:
30
-
31
- ```ts
32
- const isDark = ref(false);
33
- let mq: MediaQueryList | null = null;
34
- const sync = () => (isDark.value = mq?.matches ?? false);
35
- onMounted(() => {
36
- mq = window.matchMedia("(prefers-color-scheme: dark)");
37
- sync();
38
- mq.addEventListener("change", sync);
39
- });
40
- onBeforeUnmount(() => mq?.removeEventListener("change", sync));
41
-
42
- const palette = computed(() =>
43
- isDark.value ? { fg: "#f4f4f5", line: "#f4f4f5", grid: "#27272a" }
44
- : { fg: "#18181b", line: "#18181b", grid: "#f4f4f5" });
45
- ```
46
-
47
- Mirror the dark values from `main.css`. A chart `colors: ["#18181b"]` (near-black)
48
- is invisible on dark — invert the line to a light value via the palette.
49
-
50
- ## A bare `boolean` prop casts to `false` when absent — `withDefaults` it
51
-
52
- Vue's Boolean-prop casting: a prop typed `boolean` with **no default** coerces to
53
- `false` when the parent doesn't pass it — *not* `undefined`. So a "default-on"
54
- flag written as `responsive?: boolean` + `props.responsive !== false` is always
55
- `false` unless explicitly passed, and the feature silently never fires.
56
-
57
- ```ts
58
- // ❌ absent → false → feature off, no error
59
- const props = defineProps<{ responsive?: boolean }>();
60
- // ✅ absent → true
61
- const props = withDefaults(defineProps<{ responsive?: boolean }>(), { responsive: true });
62
- ```
63
-
64
- Not Volt-specific, but it bit the `SlidingTabs` responsive collapse, so it lives
65
- here. Any "defaults to on" boolean prop must use `withDefaults` (or invert it to
66
- an opt-out flag that naturally defaults false).
67
-
68
- ## The class merge lives in `src/volt/utils.ts` (`ptViewMerge`)
69
-
70
- When a `pt:` class won't override, or you want to change how a component's own
71
- classes combine with yours, the lever is **not** a global PrimeVue config — it's a
72
- local helper. Every vendored component sets `:ptOptions="{ mergeProps: ptViewMerge }"`,
73
- and `ptViewMerge` (in `src/volt/utils.ts`) does `twMerge(globalClass, selfClass)`
74
- then Vue `mergeProps`:
75
-
76
- ```ts
77
- export const ptViewMerge = (globalPTProps = {}, selfPTProps = {}, datasets) => {
78
- const { class: globalClass, ...globalRest } = globalPTProps;
79
- const { class: selfClass, ...selfRest } = selfPTProps;
80
- return mergeProps({ class: twMerge(globalClass, selfClass) }, globalRest, selfRest, datasets);
81
- };
82
- ```
83
-
84
- That `twMerge` is why a conflicting `pt:` utility wins (last-writer in the merge)
85
- and a plain `class` may not. Debugging an override that won't take? Look here, not
86
- at a config flag.
87
-
88
- ## Reaching internals from CSS: `data-pc-name` / `data-pc-section`
89
-
90
- When `pt:` class styling isn't enough — you need to style a component's internals
91
- from a parent `<style>` block or third-party CSS — PrimeVue stamps stable
92
- `data-pc-name="<component>"` and `data-pc-section="<section>"` attributes on its
93
- DOM. Target those instead of brittle structural selectors:
94
-
95
- ```css
96
- [data-pc-name="select"] [data-pc-section="dropdown"] { /* … */ }
97
- ```
98
-
99
- ## Styling a nested child component: the `pc`-prefixed section
100
-
101
- When one PrimeVue component renders another inside it, the inner one's `pt`
102
- section name is prefixed **`pc`** (e.g. a Badge embedded in another component is
103
- `pcBadge`). Address it through the prefix; a flat section name silently fails:
104
-
105
- ```vue
106
- <VoltSomething pt:pcBadge:root:class="bg-red-500" />
107
- ```
108
-
109
- ## State styling: use `tailwindcss-primeui`'s `p-*` variants, not edited source
110
-
111
- `tailwindcss-primeui` registers component-state variants — `p-selected:`,
112
- `p-focus:`, `p-disabled:`, `p-invalid:`, `p-editable:` — that key off PrimeVue's
113
- internal state. Reach for these via `pt:` instead of editing vendored component
114
- source to style a state:
115
-
116
- ```vue
117
- <VoltSelect pt:option:class="p-selected:bg-highlight p-focus:bg-surface-100" />
118
- ```
119
-
120
- ## PrimeIcons `.pi` is `display:inline-block` — it beats `hidden`
121
-
122
- PrimeIcons sets `display: inline-block` on `.pi`, which has higher specificity
123
- than Tailwind's `hidden` (`display:none`). Toggling an icon's visibility with bare
124
- `hidden`/`inline-block` silently fails — the icon stays visible. Use the `!`
125
- important variant:
126
-
127
- ```vue
128
- <!-- ❌ stays visible -->
129
- <i class="pi pi-x hidden sm:inline-block" />
130
- <!-- ✅ -->
131
- <i class="pi pi-x !hidden sm:!inline-block" />
132
- ```
133
-
134
- ## We don't use `@primevue/forms`
135
-
136
- This stack validates with **zod + manual wiring**, not `@primevue/forms`. The
137
- package's `zodResolver` looks tempting given how much zod is already around, but
138
- its ergonomics weren't worth the workarounds. Don't reach for it — drive
139
- validation from the zod schema directly (`safeParse` in the submit handler, or a
140
- small `useFormState`-style composable).
@@ -1,137 +0,0 @@
1
- # Theming & dark mode
2
-
3
- Dark mode follows the OS: `@media (prefers-color-scheme: dark)`. No toggle, no
4
- `dark` class on `<html>`. Tailwind v4's `dark:` variant also keys on
5
- `prefers-color-scheme` by default, so everything reacts to the same signal.
6
-
7
- There are **two color systems** in play, and the whole skill is knowing which to
8
- use where.
9
-
10
- ## The two layers
11
-
12
- | | App markup (you own) | Volt internals (vendored) |
13
- |---|---|---|
14
- | **System** | semantic `@theme` tokens | `surface-*` scale + `dark:` pairs |
15
- | **Example** | `bg-surface text-fg` | `bg-surface-0 dark:bg-surface-900` |
16
- | **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:` |
17
- | **You write** | once | both halves |
18
-
19
- ### Why not use semantic tokens everywhere (incl. Volt)?
20
-
21
- You *can* — Volt components are vendored and editable, so nothing stops you from
22
- restyling one to `bg-surface text-fg`. The reasons not to are practical, in
23
- descending order of weight:
24
-
25
- 1. **Vocabulary mismatch (the real one).** Semantic tokens are a small,
26
- opinionated set (`surface`, `surface-muted`, `line`, `fg`, `fg-muted`, …) for
27
- "card / text / border" decisions. A component library reaches all over the
28
- 0–950 ramp — subtle fills, two border weights, icon idle vs hover, elevation
29
- layering. To express all of Volt in tokens you'd expand them until they *are*
30
- the ramp, at which point you've just renamed `surface-*`.
31
- 2. **Consistency with newly-added siblings.** `volt-vue add` always scaffolds in
32
- the upstream `surface-*` + `dark:` convention, so keeping existing components on
33
- it means every Volt file reads the same way and a freshly-added one drops in
34
- without restyling. This is a mild *consistency* benefit, **not** a regeneration
35
- one: there's no `volt-vue update` and no continuous sync — you own each file the
36
- moment you add it, edits or not. (Upstream behavior fixes ride the `primevue`
37
- version bump, not a re-add.)
38
- 3. **The convention they ship in.** As generated, `--p-surface-0…950` are fixed
39
- (never flipped), so a Volt component flips by *picking the dark end* with
40
- `dark:bg-surface-900` — not by a value that changes. Semantic tokens flip the
41
- variable's value instead, so one class covers both schemes. You could rewrite
42
- a component to the token style, but then you're back to reasons 1 and 2.
43
-
44
- ## The token set
45
-
46
- Defined in `app/assets/css/main.css`: light values in a top-level `@theme`
47
- block, dark values overriding the same `--color-*` vars inside the
48
- `prefers-color-scheme: dark` media block.
49
-
50
- ```css
51
- @theme {
52
- --color-canvas: #fafafa; /* app background */
53
- --color-surface: #ffffff; /* cards, panels, dialogs */
54
- --color-surface-muted: #fafafa; /* subtle fills, row hover */
55
- --color-line: #e4e4e7; /* borders */
56
- --color-line-soft: #f4f4f5; /* soft dividers */
57
- --color-fg: #18181b; /* primary text */
58
- --color-fg-muted: #71717a; /* secondary text */
59
- --color-fg-subtle: #a1a1aa; /* tertiary text */
60
- --color-accent: #18181b; /* inverted/primary fills (buttons) */
61
- --color-on-accent: #ffffff; /* text/icon on an accent fill */
62
- --color-fill: #e4e4e7; /* neutral solid fills: avatars, tracks, dots */
63
- }
64
-
65
- @media (prefers-color-scheme: dark) {
66
- :root {
67
- --color-canvas: #09090b;
68
- --color-surface: #18181b;
69
- --color-surface-muted: #27272a;
70
- --color-line: #27272a;
71
- --color-line-soft: #27272a;
72
- --color-fg: #f4f4f5;
73
- --color-fg-muted: #b4b4bc; /* lifted off a strict mirror-invert for legibility */
74
- --color-fg-subtle: #8c8c95; /* ~5.5:1 on near-black */
75
- --color-accent: #f4f4f5; /* inverts so filled buttons read on dark */
76
- --color-on-accent: #18181b;
77
- --color-fill: #3f3f46;
78
- }
79
- }
80
- ```
81
-
82
- The dark `fg-muted` / `fg-subtle` are **lifted** off a strict mirror-invert —
83
- the perfectly-inverted values are too dark to read on near-black.
84
-
85
- ### Where each layer lives (and why it's not fighting Volt)
86
-
87
- [Volt's Nuxt setup](https://volt.primevue.org/nuxt/#css-variables) prescribes the
88
- `--p-*` palette + semantic tokens in **`:root`**, with dark mode via
89
- `@media (prefers-color-scheme: dark)`. Keep that exactly as-is — don't move
90
- `--p-*` into `@theme`; the `tailwindcss-primeui` plugin already turns them into
91
- `surface-*` / `primary-*` utilities.
92
-
93
- Your semantic tokens go in **`@theme`** instead, because that's the Tailwind v4
94
- mechanism that generates the utilities (`--color-canvas` → `bg-canvas`). Defining
95
- them only in `:root` would set the variable but produce **no class**. So:
96
-
97
- - `--p-*` → `:root` (Volt's way; plugin generates `surface-*`)
98
- - `--color-*` → `@theme` (Tailwind's way; generates `bg-surface`, `text-fg`, …)
99
-
100
- Different namespaces, no collision: `bg-surface-0` (primeui, numbered) and
101
- `bg-surface` (your token, bare) coexist. Dark values for **both** sit in the same
102
- `prefers-color-scheme` block — your `--color-*` overrides next to Volt's `--p-*`
103
- overrides.
104
-
105
- ## Ignore styled-mode theming (`definePreset`, `theme.preset`)
106
-
107
- Most PrimeVue theming docs describe **styled** mode — `definePreset`, `theme: {
108
- preset: Aura }`, component design tokens like `button.background`. Volt runs
109
- PrimeVue with **`unstyled: true`**, which turns all of that **off**: the built-in
110
- CSS and preset machinery aren't loaded, so a `definePreset`/`theme.preset` config
111
- does nothing here. If you're following a primevue.org theming tutorial and it
112
- reaches for `definePreset`, stop — that's the wrong layer. Your knobs are the
113
- `--p-*` variables in `:root` (Volt's way) plus the Tailwind `@theme` tokens above.
114
-
115
- (The `--p-*` variable **prefix** still applies — `tailwindcss-primeui` reads it.
116
- It's the preset/design-token *machinery* that's inert, not the variables.)
117
-
118
- ## The naming trap (this one bites)
119
-
120
- In Tailwind v4 the utility name is the **full** variable suffix:
121
-
122
- - `--color-fg-subtle` → `text-fg-subtle` ✅
123
- - `text-subtle` ❌ — generates **nothing**, element falls back to near-black
124
-
125
- A wrong/shortened token name fails silently (no class generated), so a
126
- suspicious "secondary text is black in dark mode" is almost always a misnamed
127
- token, not a wrong value. **Compile the CSS and grep the generated utilities** —
128
- don't eyeball the browser.
129
-
130
- ## Adding a new token
131
-
132
- 1. Add `--color-foo: <light>;` to the `@theme` block.
133
- 2. Add `--color-foo: <dark>;` inside the dark media block.
134
- 3. Use `bg-foo` / `text-foo` / `border-foo` — done, both schemes covered.
135
-
136
- No `dark:` variant, ever, for app markup. If you're typing `dark:` in a page or
137
- app component, you're reaching for the wrong layer.