@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.
- package/README.md +13 -1
- package/package.json +1 -1
- package/plugins/copier-template/skills/copier-template/applying-updates.md +2 -2
- package/plugins/frontend-design/skills/frontend-design/SKILL.md +10 -10
- package/plugins/gallop-ui/.claude-plugin/plugin.json +8 -0
- package/plugins/gallop-ui/skills/gallop-ui/SKILL.md +108 -0
- package/plugins/gallop-ui/skills/gallop-ui/api-principles.md +157 -0
- package/plugins/gallop-ui/skills/gallop-ui/changing-the-layer.md +102 -0
- package/plugins/gallop-ui/skills/gallop-ui/checking-other-apps.md +108 -0
- package/plugins/gallop-ui/skills/gallop-ui/finding-a-component.md +92 -0
- package/plugins/gallop-ui/skills/gallop-ui/pitfalls.md +82 -0
- package/plugins/gallop-ui/skills/gallop-ui/pulling-updates.md +101 -0
- package/plugins/gallop-ui/skills/gallop-ui/using-in-an-app.md +122 -0
- package/plugins/linear/skills/linear/SKILL.md +4 -4
- package/plugins/linear/skills/linear/examples/frontend-feature.md +1 -1
- package/plugins/linear/skills/linear/tech-stack.md +12 -14
- package/plugins/nitro-testing/skills/nitro-testing/SKILL.md +3 -26
- package/plugins/nitro-testing/skills/nitro-testing/frontend-testing.md +7 -33
- package/plugins/tailwind-v4/skills/tailwind-v4/SKILL.md +12 -14
- package/plugins/tailwind-v4/skills/tailwind-v4/gotchas.md +13 -18
- package/plugins/vue-nuxt/skills/vue-nuxt/SKILL.md +2 -2
- package/plugins/vue-nuxt/skills/vue-nuxt/auto-imports.md +2 -2
- package/plugins/vue-nuxt/skills/vue-nuxt/template-idioms.md +1 -1
- package/plugins/vue-nuxt/skills/vue-nuxt/v-model.md +6 -6
- package/plugins/vue-nuxt/skills/vue-nuxt/watch.md +3 -3
- package/plugins/volt-primevue/.claude-plugin/plugin.json +0 -8
- package/plugins/volt-primevue/skills/volt-primevue/SKILL.md +0 -170
- package/plugins/volt-primevue/skills/volt-primevue/config.md +0 -51
- package/plugins/volt-primevue/skills/volt-primevue/gotchas.md +0 -140
- 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.
|