@gallopsystems/agent-skills 1.30.0 → 1.31.1
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/ci-setup.md +18 -23
- 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
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# Making sure other apps don't break
|
|
2
|
+
|
|
3
|
+
A layer change reaches every app, and a release reaches each app's real screens. Prove both: the layer change
|
|
4
|
+
against every app's stories, and the app after a pull against its own pages. The bar is **same or better, never a
|
|
5
|
+
regression** in look, behaviour and speed, at desktop and phone width, light and dark. Every difference is either
|
|
6
|
+
intended (and explained) or fixed.
|
|
7
|
+
|
|
8
|
+
## 1. `ui:impact` across apps (for a layer change)
|
|
9
|
+
|
|
10
|
+
From a gallop-ui worktree (`node scripts/impact.mjs`), or from an app whose subtree you edited (`yarn ui:impact`):
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
node scripts/impact.mjs # every app found next to this checkout, the full affected set
|
|
14
|
+
node scripts/impact.mjs --direct # quick loop: only components whose own files changed
|
|
15
|
+
node scripts/impact.mjs --apps a,b # a subset (folder names)
|
|
16
|
+
node scripts/impact.mjs --before app # what each app sees when it pulls this, from its current version
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
It discovers every `~/Projects/<app>/layers/gallop-ui` (one checkout per repository), runs each app from a
|
|
20
|
+
`git archive` of its `HEAD` in a temp folder (never the checkout, never its `.env` or databases), and writes an HTML
|
|
21
|
+
report under `~/.cache/gallop-ui-impact/<time>/` with:
|
|
22
|
+
|
|
23
|
+
- **Call sites:** the affected components' tags in each app, file and line, flagged where a removed prop is still
|
|
24
|
+
passed.
|
|
25
|
+
- **Types:** each app's `nuxt typecheck` with the edited layer (errors the app already had aren't counted).
|
|
26
|
+
- **Looks:** every story of every affected component at 1280 and 390, light and dark, before and after, with changed
|
|
27
|
+
pixels in red.
|
|
28
|
+
|
|
29
|
+
Read the whole report. Every red diff must be one you meant. A look that changes in an app without that app touching
|
|
30
|
+
`pt` is a breaking change. Name the apps you checked and what changed in the PR. Run the full set (not `--direct`)
|
|
31
|
+
before opening the PR. Needs each app's `yarn install` and a Playwright Chromium (or Google Chrome); `--no-visual`
|
|
32
|
+
still gives call sites and types.
|
|
33
|
+
|
|
34
|
+
## 2. Grep every app for affected usage
|
|
35
|
+
|
|
36
|
+
`impact.mjs` sees tags and auto-imported calls. Also grep for what it can't see: `pt` keys, `gallopUi.pt` entries,
|
|
37
|
+
data attributes, CSS that targets layer markup, and test assertions:
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
for layer in ~/Projects/*/layers/gallop-ui; do
|
|
41
|
+
app=$(dirname "$(dirname "$layer")")
|
|
42
|
+
[ -d "$app/.git" ] || continue # a worktree (its .git is a file): the main checkout covers it
|
|
43
|
+
git -C "$app" fetch -q origin
|
|
44
|
+
echo "== $app"; git -C "$app" grep -n -E "<pattern>" origin/main -- app tests
|
|
45
|
+
done
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Grep `origin/main`, not the working tree: main checkouts may have uncommitted work and stale branches, and
|
|
49
|
+
worktrees of the same app are duplicates.
|
|
50
|
+
|
|
51
|
+
## 3. Before/after screenshot sweep (for an app after a pull, or a risky layer change)
|
|
52
|
+
|
|
53
|
+
- **Before** = the app at `origin/main` in a detached worktree; **after** = your branch. Both against the **same
|
|
54
|
+
throwaway database**, seeded once, each on its own port.
|
|
55
|
+
- Screenshot the main pages, and every page that uses an affected component, at **1280 and 390, light and dark**.
|
|
56
|
+
Force the scheme with Playwright `colorScheme`, or `?theme=dark` on `/_ui`.
|
|
57
|
+
- **Exercise the interactions,** not just the resting page: open popovers and menus, open Selects by mouse and by
|
|
58
|
+
keyboard, type into fields, turn a page, sort, drag a Board card, open a Modal over a Select.
|
|
59
|
+
- Keep the screenshots in a scratch folder, never in a repo. List every difference in the PR with the reason it
|
|
60
|
+
is intended, or fix it.
|
|
61
|
+
|
|
62
|
+
## 4. Computed-style comparison (when "looks the same" must be exact)
|
|
63
|
+
|
|
64
|
+
Pixels hide small shifts. For a component swap or a restyle, compare computed styles and box geometry with
|
|
65
|
+
Playwright: `getComputedStyle` (font size, line height, padding, colours, border, radius) and
|
|
66
|
+
`getBoundingClientRect` (height, width), old against new. Do it at rest and with `:hover`, `:focus-visible` and
|
|
67
|
+
`:active` forced through CDP (`CSS.forcePseudoState`), in light and dark. A temporary page that renders each case
|
|
68
|
+
side by side (`app/pages/zz-<name>.vue` in the throwaway worktree, never committed) makes the comparison
|
|
69
|
+
mechanical.
|
|
70
|
+
|
|
71
|
+
Check at 1280 that desktop is identical when a change was meant to be phone-only, and at 390 that fields in one row
|
|
72
|
+
still match in height and text size.
|
|
73
|
+
|
|
74
|
+
## 5. `yarn ui:probe`: bugs screenshots miss
|
|
75
|
+
|
|
76
|
+
With the app running, `yarn ui:probe --url http://127.0.0.1:<port>` drives every page at 1280 and 390, light
|
|
77
|
+
and dark. It reports fields in one row that don't match, phone text under 16px, clipped focus rings, sideways
|
|
78
|
+
scroll, contrast, stray `currentColor` borders, and flashes during sorting, paging, opening/closing and drags.
|
|
79
|
+
It blocks every write request while it clicks. `--only static` is quick. See `layers/gallop-ui/docs/probe.md`.
|
|
80
|
+
Run it after a pull and after a layer change; anything it marks as an error is a real bug until proven otherwise.
|
|
81
|
+
|
|
82
|
+
## 6. Tables
|
|
83
|
+
|
|
84
|
+
- **Inventory before replacing.** List every behaviour a table has in both layouts (sort, multi-sort, filter, paging,
|
|
85
|
+
page size, selection, row link or click, actions, reorder, empty, loading, sticky header, keyboard). That list is
|
|
86
|
+
the contract and goes in the PR body. Measure old against new, including speed on a throttled phone.
|
|
87
|
+
- **Stateful cells need `:key="row.id"`.** DataTable patches rows in place on a page turn, so a component with state
|
|
88
|
+
inside a cell slot (an inline editor, an input, an open Tooltip, local `ref` state, focus) keeps that state at the
|
|
89
|
+
same position on the next page unless it is keyed by row. Grep every `#cell-*` slot in every affected app, add the
|
|
90
|
+
key, and prove it by turning the page with the state active.
|
|
91
|
+
- Phone tables become cards by default. That is an improvement, not a regression.
|
|
92
|
+
|
|
93
|
+
## 7. Throwaway databases only
|
|
94
|
+
|
|
95
|
+
Never point a check at a real local database or a real `.env`, and **never start Docker** (no `docker run`,
|
|
96
|
+
`docker compose`, `open -a Docker` or testcontainers). Run a disposable native Postgres on your own port, from
|
|
97
|
+
Postgres.app's binaries:
|
|
98
|
+
|
|
99
|
+
```sh
|
|
100
|
+
PG=/Applications/Postgres.app/Contents/Versions/latest/bin
|
|
101
|
+
$PG/initdb --locale=en_US.UTF-8 -U postgres -D <scratch>/pgdata
|
|
102
|
+
$PG/pg_ctl -D <scratch>/pgdata -l <scratch>/pg.log -o "-p <port> -c fsync=off -c synchronous_commit=off \
|
|
103
|
+
-c full_page_writes=off -c timezone=America/New_York" start
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Point the app's DB URLs at `127.0.0.1:<port>` in an env file inside your worktree (copied from `.env.example`),
|
|
107
|
+
migrate and seed it, and stop it with `$PG/pg_ctl -D <scratch>/pgdata stop` when done. Never use ports 5432, 5433
|
|
108
|
+
or 3306, even if they are free. Before any test or push, check that both DB URLs are set and neither says 5432.
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# Finding the right component
|
|
2
|
+
|
|
3
|
+
Work down this list and stop at the first step that fits. The layer's `CLAUDE.md` ("Before you build") says the
|
|
4
|
+
same from the layer's side.
|
|
5
|
+
|
|
6
|
+
## 1. Search
|
|
7
|
+
|
|
8
|
+
```sh
|
|
9
|
+
cd <app>
|
|
10
|
+
grep -in "<words a user would say>" layers/gallop-ui/CATALOGUE.md # "date range", "kanban", "copy link"
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
- `CATALOGUE.md` is generated from each component's frontmatter. Its **"Use it for"** column holds the phrases
|
|
14
|
+
people search with (`kebab menu`, `bottom sheet`, `combobox`), and **"Replaces app copies"** names the
|
|
15
|
+
Volt/PrimeVue or app component each one replaced (`VoltDialog` → Modal, `v-tooltip` → Tooltip). Search both.
|
|
16
|
+
- Read the `.md` of every candidate: **When to use**, **When not to use** (which often names the right sibling),
|
|
17
|
+
**Functionality**, then Props, Slots and Customizing.
|
|
18
|
+
- Check composables too (`useConfirm`, `useSubmit`, `useRemoteOptions`, `useRowLink`…): the need may be behaviour,
|
|
19
|
+
not a component.
|
|
20
|
+
- Open `/_ui/<Name>` in `yarn dev` to see the stories in this app's theme.
|
|
21
|
+
- Also search the app (`git grep -n "<Name>" -- app`) for how it already does this. Copy the app's own pattern when
|
|
22
|
+
it uses the layer correctly.
|
|
23
|
+
|
|
24
|
+
## 2. Exact match: use it as it is
|
|
25
|
+
|
|
26
|
+
Use the documented props. Restyle with `class` (= `pt.root`) or `pt` for a one-off; put a look the app wants
|
|
27
|
+
everywhere in `gallopUi.pt`. Don't wrap a layer component in an app component just to preset props: use
|
|
28
|
+
`gallopUi.defaults` or the props at the call site.
|
|
29
|
+
|
|
30
|
+
## 3. Close match: bend it, don't fork it
|
|
31
|
+
|
|
32
|
+
In this order:
|
|
33
|
+
|
|
34
|
+
1. **A prop** the component already has (read the whole Props table; many options are off by default).
|
|
35
|
+
2. **A `pt` section** for a look.
|
|
36
|
+
3. **A slot** for content (`#empty`, `#item`, `#<key>-cell`, `#actions`, `#footer`…). Slot names are kebab-case.
|
|
37
|
+
|
|
38
|
+
Never:
|
|
39
|
+
|
|
40
|
+
- wrap it in an app component to add behaviour the layer should own;
|
|
41
|
+
- copy its source into `app/components`;
|
|
42
|
+
- name an app component like a layer one (shadowing; `yarn ui:check` fails);
|
|
43
|
+
- edit `layers/gallop-ui` in the app.
|
|
44
|
+
|
|
45
|
+
If it truly lacks something **any app could use** (a missing option, a missing slot), propose extending it in the
|
|
46
|
+
layer: backward compatible, existing call sites render exactly as before, `.md`, stories and tests updated in the
|
|
47
|
+
same change. Don't stretch a component past its job: if the new use changes what its value *is* (a boolean
|
|
48
|
+
instead of a choice), it is a different component.
|
|
49
|
+
|
|
50
|
+
While the layer change is pending, the app may carry a small, local workaround marked `TODO(gallop-ui): <what the
|
|
51
|
+
layer should do>`. The next `ui:pull` removes it.
|
|
52
|
+
|
|
53
|
+
## 4. No match: compose, then propose
|
|
54
|
+
|
|
55
|
+
1. **Compose layer primitives in the app** (`Card` + `DescriptionList` + `Button`…), in an app component named for
|
|
56
|
+
the app's domain.
|
|
57
|
+
2. **Propose a layer component** when either is true:
|
|
58
|
+
- a **second app** needs the same composition (the second copy is the trigger: move it to the layer as a
|
|
59
|
+
composite, and both apps adopt it);
|
|
60
|
+
- it is a **generic UI pattern** with no domain in it (a disclosure, a meter, a stepper), even if one app needs it
|
|
61
|
+
today.
|
|
62
|
+
3. Keep it in the app when it only makes sense for that app's domain.
|
|
63
|
+
|
|
64
|
+
Don't build a shallow wrapper around a library an app already uses well (a chart library, say). A layer component
|
|
65
|
+
earns its place by behaviour and a shared look.
|
|
66
|
+
|
|
67
|
+
## Primitives before composites
|
|
68
|
+
|
|
69
|
+
- **Primitives** are building blocks with their own behaviour (Button, Input, Select, Modal, Popover, Tooltip…).
|
|
70
|
+
**Composites** put primitives together for a recurring job (PageHeader, FormField, DataTable, Board,
|
|
71
|
+
CommandPalette…). The tier is in each `.md`'s frontmatter and in CATALOGUE.md's sections.
|
|
72
|
+
- **A layer composite builds only on layer primitives.** It never uses a plain element styled to look like a
|
|
73
|
+
primitive, and never an app's component. If a composite needs a primitive the layer lacks, the primitive is
|
|
74
|
+
built first.
|
|
75
|
+
- Basic composites (a few primitives, no engine, no app-shell state) come before advanced ones (tables, app shell,
|
|
76
|
+
palettes).
|
|
77
|
+
|
|
78
|
+
## Suggesting a new component to the owner
|
|
79
|
+
|
|
80
|
+
The owner decides names and whether the layer grows. Bring a short proposal, not a branch:
|
|
81
|
+
|
|
82
|
+
- **The need**, in a caller's words, and the call sites: every app and file that has a copy or would use it
|
|
83
|
+
(`git -C ~/Projects/<app> grep -n "<pattern>" origin/main -- app`).
|
|
84
|
+
- **Why the existing components don't fit:** the candidates you read and what each lacks.
|
|
85
|
+
- **The tier**, and the primitives it builds on (and any primitive that must come first).
|
|
86
|
+
- **The API sketch:** name, props, slots, events, v-model, following [api-principles.md](api-principles.md). List
|
|
87
|
+
every non-obvious name with the alternatives you considered, and a recommendation with the trade-off. Check
|
|
88
|
+
`docs/decisions.md` so you don't reopen a settled name.
|
|
89
|
+
- **What it replaces**, and whether adopting it is a scripted rewrite.
|
|
90
|
+
|
|
91
|
+
`docs/composite-candidates.md` in the gallop-ui repo lists what earlier surveys found and what was declined. Check
|
|
92
|
+
it first. An idea that isn't built yet goes in `docs/review-queue.md` as an open item.
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# Pitfalls and working rules
|
|
2
|
+
|
|
3
|
+
Rules learned the hard way while building the layer and moving every app onto it. Most cost someone real work.
|
|
4
|
+
|
|
5
|
+
## Git
|
|
6
|
+
|
|
7
|
+
- **Never `git stash`**, and never a bare `git stash pop`. Stashes are shared across every worktree of a repo, and
|
|
8
|
+
other people's stashes have been put at risk. Commit to a branch, or start from a fresh worktree.
|
|
9
|
+
- **Never `--no-verify`**, not even "temporarily". If a hook fails, fix the cause. A pre-push test that times out
|
|
10
|
+
under load: rerun that test alone, capture its name, retry the push at most twice, then report.
|
|
11
|
+
- **Don't touch uncommitted work.** Many main checkouts have it. Check `git status`, then work in a new worktree from
|
|
12
|
+
a fresh `origin/main`: `git worktree add ~/Projects/<repo>-<topic> -b <branch> origin/main`. Don't touch other
|
|
13
|
+
people's or agents' worktrees.
|
|
14
|
+
- A branch created from `origin/main` tracks main. Push with an explicit refspec: `git push -u origin <branch>`.
|
|
15
|
+
- **Subtree PRs in an app: merge commit. Layer PRs and release PRs: squash.** Getting either wrong costs a broken
|
|
16
|
+
`ui:pull` or a skipped release.
|
|
17
|
+
- Don't reword or squash the `chore(gallop-ui): pull vX.Y.Z` commit: `ui:migrate` reads it to find the previous
|
|
18
|
+
version.
|
|
19
|
+
- One commit must not mix `layers/gallop-ui` and app files (`ui:check --staged` blocks it).
|
|
20
|
+
- If a push, merge or other action is denied by permissions, stop and report it. Don't route around it.
|
|
21
|
+
|
|
22
|
+
## Processes and ports
|
|
23
|
+
|
|
24
|
+
- **Never `pkill -f`** (or any pattern kill). It has killed other agents' dev servers. Stop only what you started,
|
|
25
|
+
by its saved PID or by your own port, and always with `-sTCP:LISTEN` (without it, `lsof` also matches clients
|
|
26
|
+
connected to the port, such as a browser or an editor helper):
|
|
27
|
+
```sh
|
|
28
|
+
lsof -ti tcp:<port> -sTCP:LISTEN | xargs kill
|
|
29
|
+
```
|
|
30
|
+
- **Use your own ports.** Never 3306 (MySQL), 5432 or 5433 (Postgres), even if they look free: a cleanup on those
|
|
31
|
+
ports has killed a real database server.
|
|
32
|
+
- The shell is zsh: an unquoted `$var` holding a list doesn't word-split, there is no `timeout`, and `sed -i` needs
|
|
33
|
+
`''` (BSD). Use the Write tool or a script file instead of long heredocs.
|
|
34
|
+
|
|
35
|
+
## Databases and secrets
|
|
36
|
+
|
|
37
|
+
- **Throwaway Postgres only,** on your port, with `fsync=off`, `synchronous_commit=off`, `full_page_writes=off` and
|
|
38
|
+
`timezone=America/New_York` (slow fsync caused pre-push flakes; a zone mismatch breaks `updated_at` tests). Remove
|
|
39
|
+
it afterwards.
|
|
40
|
+
- Never migrate, seed or write a real local database. Never edit a real `.env`; copy `.env.example` into your
|
|
41
|
+
worktree. Never use or print production credentials.
|
|
42
|
+
|
|
43
|
+
## Tests
|
|
44
|
+
|
|
45
|
+
- Node 24 for hooks, tests and the codemod (`export PATH=$HOME/.nvm/versions/node/v24.11.1/bin:$PATH`, or `nvm use
|
|
46
|
+
24`). Node 22's ICU formats currency differently and fails tests.
|
|
47
|
+
- Run date-related tests under both `TZ=UTC` and `TZ=America/New_York`. Never depend on the live clock: fake the
|
|
48
|
+
timers and set the system time.
|
|
49
|
+
- Fix a flaky test deterministically (stub `requestAnimationFrame`, await the right tick), not with retries.
|
|
50
|
+
|
|
51
|
+
## Layer and app gotchas
|
|
52
|
+
|
|
53
|
+
- **`class` didn't apply?** Check whether the default is a state the component knows (write a plain class or the
|
|
54
|
+
matching `data-[size=sm]:` variant), a Reka runtime state (write the same `data-highlighted:` variant in that
|
|
55
|
+
section), or a `dark:` default your class didn't restate.
|
|
56
|
+
- **`size-*` on an `<Icon>` does nothing.** Use `text-*`.
|
|
57
|
+
- **A Tailwind class written outside `components/` in the layer is never generated.** Apps scan only
|
|
58
|
+
`layers/gallop-ui/components`.
|
|
59
|
+
- **An app component named like a layer one** shadows it, which is not allowed. `ui:check` fails on it, so delete the
|
|
60
|
+
app copy when adopting the layer's.
|
|
61
|
+
- **A pt section that recoloured a ring** may need a pseudo-element variant after a release that moved the ring
|
|
62
|
+
(Board's lane highlight moved to `after:ring-*`). Read the CHANGELOG entry.
|
|
63
|
+
- **Field text is 16px on phones** by design. Don't pin `text-sm` on fields to undo it, and remove old app-wide
|
|
64
|
+
anti-zoom CSS that duplicates it.
|
|
65
|
+
- **A closed Select is a plain button;** Reka mounts on first open. Code that keeps a `triggerRef` across the first
|
|
66
|
+
open must read it again.
|
|
67
|
+
- **DataTable cell state follows the position** on a page turn unless the stateful component has `:key="row.id"`.
|
|
68
|
+
- **Don't copy an old phone table** with `layout="table"`: phones get cards.
|
|
69
|
+
- **`/_ui` shows the wrong font?** The app sets its font from a layout. Move it to `--font-sans` in `@theme`.
|
|
70
|
+
|
|
71
|
+
## Verifying and reporting
|
|
72
|
+
|
|
73
|
+
- **A subagent's report isn't proof.** Before you report or merge its work, read the diff, check CI yourself
|
|
74
|
+
(`gh pr checks`, `gh pr view --json mergeStateStatus`), and open the screenshots.
|
|
75
|
+
- **Inspect every migrated app in a browser.** Run it, open the pages you changed, and look at them in light and
|
|
76
|
+
dark at desktop and phone width. Passing tests and a clean build don't show you what the screen looks like.
|
|
77
|
+
- **Prefer eyes over slow pixel diffs.** For a judgement on looks, a state-matrix page (every size, variant and state
|
|
78
|
+
side by side, old against new, with hover and focus forced) that the owner can open beats a long pixel-diff run.
|
|
79
|
+
Don't add a screenshot-baseline suite without a stated reason. Keep `ui:impact`, which is built for layer changes.
|
|
80
|
+
- **Log pre-existing bugs; don't fix them in the migration.** A bug the app already had on `origin/main` (a wrong
|
|
81
|
+
join, a broken address field) goes in the PR body and a ticket, not into the migration diff. That keeps the
|
|
82
|
+
migration's before/after comparison honest.
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# Pulling a gallop-ui release into an app
|
|
2
|
+
|
|
3
|
+
An app takes layer releases deliberately, one app at a time. The pull, the codemod and the hand fixes are one PR,
|
|
4
|
+
merged with a **merge commit**.
|
|
5
|
+
|
|
6
|
+
## 0. Before you start
|
|
7
|
+
|
|
8
|
+
- `git -C <app> status`. If the main checkout has uncommitted work, leave it alone: you work in a new worktree.
|
|
9
|
+
- Use Node 24 for everything (hooks, tests, the codemod).
|
|
10
|
+
- Find the current and target versions:
|
|
11
|
+
```sh
|
|
12
|
+
yarn ui:version # this app's layer
|
|
13
|
+
git ls-remote --tags git@github.com:gallop-systems/gallop-ui.git | tail -5
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## 1. Worktree and pull
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
git -C ~/Projects/<app> fetch origin
|
|
20
|
+
git -C ~/Projects/<app> worktree add ~/Projects/<app>-ui-<version> -b chore/gallop-ui-<version> origin/main
|
|
21
|
+
cd ~/Projects/<app>-ui-<version> && yarn install
|
|
22
|
+
yarn ui:pull v<X.Y.Z> # git subtree pull --squash, committed as "chore(gallop-ui): pull v<X.Y.Z>"
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
- **The pull is its own commit, with nothing else in it.** Don't amend it or reword its message:
|
|
26
|
+
`ui:migrate` finds the app's previous release from the `chore(gallop-ui): pull|add vX.Y.Z` commits in history.
|
|
27
|
+
- `ui:pull` needs a clean tree, and its error message says "commit or stash". **Don't stash.** Commit your work, or
|
|
28
|
+
start from a fresh worktree.
|
|
29
|
+
- A subtree conflict means someone edited `layers/gallop-ui` in this app. Resolve it to the release's version
|
|
30
|
+
(`git checkout --theirs -- layers/gallop-ui/<file>`) and tell the user what the local edit was. It belongs in the
|
|
31
|
+
layer repo, or in `pt`.
|
|
32
|
+
- If `yarn install` reports a new peer dependency of the layer, add it at the version in
|
|
33
|
+
`layers/gallop-ui/package.json` `peerDependencies`.
|
|
34
|
+
|
|
35
|
+
## 2. Read what changed
|
|
36
|
+
|
|
37
|
+
```sh
|
|
38
|
+
sed -n '/^## \[<X.Y.Z>\]/,/^## \[<current>\]/p' layers/gallop-ui/CHANGELOG.md
|
|
39
|
+
ls layers/gallop-ui/migrations/ layers/gallop-ui/docs/migrating-to-*.md
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
For each entry, decide: does this app call it (`git grep -n "<Component\|propName" -- app tests`), and does the call
|
|
43
|
+
site need to change? Read the affected components' `.md` "Migrating" sections. A release that crosses a major
|
|
44
|
+
version has a `docs/migrating-to-<version>.md` and a `migrations/<version>/` folder. Jumping several releases is
|
|
45
|
+
fine as long as you read every entry in between. The kit only knows the versions it has tables for, so check the
|
|
46
|
+
migration doc for how far back it reaches.
|
|
47
|
+
|
|
48
|
+
## 3. Run the codemod on a breaking release
|
|
49
|
+
|
|
50
|
+
```sh
|
|
51
|
+
yarn ui:migrate --dry # the diff and counts; nothing written
|
|
52
|
+
yarn ui:migrate # rewrites app/ and tests/, writes MIGRATION-<version>.md
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
- Commit the kit's output on its own (`chore(gallop-ui): run the <version> codemod`), then the hand fixes, so a
|
|
56
|
+
reviewer can tell the two apart.
|
|
57
|
+
- Work through every unchecked item in `MIGRATION-<version>.md` (rows marked `manual`, sites the kit listed but
|
|
58
|
+
couldn't rewrite, renamed names inside assertions). Tick each box as you go. Running the kit again is safe.
|
|
59
|
+
- Useful flags: `--only <area|Component>`, `--from <version>`, `--dir app,shared`, `--verbose`, `--check` (CI).
|
|
60
|
+
- Breaking rows are also in `layers/gallop-ui/migrations/<version>/*.json`, each with a `note`. Grep them when an
|
|
61
|
+
item is unclear.
|
|
62
|
+
|
|
63
|
+
## 4. Tokens, guards and workarounds
|
|
64
|
+
|
|
65
|
+
```sh
|
|
66
|
+
yarn ui:tokens # theme CSS vs the token contract: missing tokens, old names
|
|
67
|
+
yarn ui:check # no shadowing, no mixed commits
|
|
68
|
+
git grep -n "TODO(gallop-ui" -- app tests
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
- Add any token the release needs to the app's `main.css`, light and dark (`light-dark()`), using the app's own
|
|
72
|
+
palette. `theme/neutral.css` has the reference values.
|
|
73
|
+
- **Remove workarounds the release makes unnecessary:** `TODO(gallop-ui)` code it fixes; app `pt` that now equals
|
|
74
|
+
the layer default; wrappers, guards or global CSS that patched a layer bug. Each removal must keep the look and
|
|
75
|
+
behaviour identical. Keep a deliberate design pin (a compact filter bar, say) and say so in the PR.
|
|
76
|
+
- **DataTable cells with state:** any stateful component in a DataTable cell slot (an inline editor, an input, an
|
|
77
|
+
open Tooltip, local `ref` state, focus) needs `:key="row.id"` on it. Rows are patched in place on a page turn, so
|
|
78
|
+
without a key the state follows the position to another row. Grep every `#cell-*` slot, and prove it: with the
|
|
79
|
+
state active, turn the page and check that it didn't carry over.
|
|
80
|
+
|
|
81
|
+
## 5. Prove it
|
|
82
|
+
|
|
83
|
+
Same or better, never a regression:
|
|
84
|
+
|
|
85
|
+
- `yarn lint`, `yarn typecheck`, `yarn fmt:check`, `yarn ui:check`, `yarn build`.
|
|
86
|
+
- Backend and frontend tests under `TZ=UTC` **and** `TZ=America/New_York`, against a throwaway Postgres
|
|
87
|
+
([pitfalls.md](pitfalls.md)).
|
|
88
|
+
- A visual before/after: `origin/main` against your branch, on the same throwaway DB, at 1280 and 390, light and
|
|
89
|
+
dark. Cover the main pages, every page whose call sites or workarounds you touched, and every component the
|
|
90
|
+
changelog names. Exercise them (open popovers, Selects by mouse and keyboard, drag on a Board). Explain every
|
|
91
|
+
difference. See [checking-other-apps.md](checking-other-apps.md) for the method.
|
|
92
|
+
- No layer warnings in the dev console on the main pages.
|
|
93
|
+
|
|
94
|
+
## 6. PR and merge
|
|
95
|
+
|
|
96
|
+
- Title: `chore(gallop-ui): take v<X.Y.Z>` (or the app's convention). In the body: the version jump, what the
|
|
97
|
+
codemod changed, the hand fixes, workarounds removed, visual differences with reasons, and the test runs.
|
|
98
|
+
- **Merge with a merge commit** (`gh pr merge <n> --merge --delete-branch`). A squash merge loses the subtree
|
|
99
|
+
metadata and breaks the next `ui:pull`. Don't split the pull into its own PR either.
|
|
100
|
+
- Merge only when checks are green and the PR is CLEAN, and only if you were asked or delegated to.
|
|
101
|
+
- After merging, remove your worktree and any throwaway database.
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
# Using gallop-ui in an app
|
|
2
|
+
|
|
3
|
+
How an app consumes the layer: what is available without imports, how to restyle it, and where the truth lives.
|
|
4
|
+
Check names against the subtree's docs (`layers/gallop-ui/components/<Name>/<Name>.md`): they are versioned with the
|
|
5
|
+
layer this app has, and this file is not.
|
|
6
|
+
|
|
7
|
+
## What you get without importing anything
|
|
8
|
+
|
|
9
|
+
Nuxt picks up `layers/*` on its own. From the layer:
|
|
10
|
+
|
|
11
|
+
- **Components** in `components/<Name>/` register by name: `<Button>`, `<Select>`, `<DataTable>`, `<Modal>`… Folders
|
|
12
|
+
starting with `_` (`_field`, `_select`) are internals, never used directly.
|
|
13
|
+
- **Composables** in `composables/` are auto-imported: `useToast`, `useConfirm`, `useSubmit`, `useApiError`,
|
|
14
|
+
`useCopy`, `useColorScheme`, `useSidebar`, `useRemoteOptions`, `useUnsavedGuard`, `useRowLink`, `defineShortcuts`,
|
|
15
|
+
`defineCommands`… A `define…` composable registers something while the calling component is mounted and returns
|
|
16
|
+
nothing; a `use…` composable returns state or functions. Anything under `runtime/` is private.
|
|
17
|
+
- **Formatters** (`shared/utils/`) are auto-imported plain functions that also work on the server: `formatDate`,
|
|
18
|
+
`formatDateTime`, `formatRelative`, `formatCurrency`, `formatNumber`, `formatPercent`, `formatPhone`,
|
|
19
|
+
`formatAddress`… Use them, never `Intl`, `toLocaleString` or date-fns `format()` in a component
|
|
20
|
+
(`FORMATTERS.md`).
|
|
21
|
+
- **Mount-once pieces** go in `app.vue`: `<Toaster />` for `useToast()`, `<ConfirmDialog />` for `useConfirm()`.
|
|
22
|
+
- **Types** come from one import: `import type { Pt, GallopUiConfig } from "~~/layers/gallop-ui/types"`.
|
|
23
|
+
|
|
24
|
+
## Restyling: four levels, broad to narrow
|
|
25
|
+
|
|
26
|
+
| Level | Where | Use for |
|
|
27
|
+
|---|---|---|
|
|
28
|
+
| 1. Tokens | the app's CSS (`app/assets/css/main.css`), `--color-*` in `@theme` | The app's palette: every component follows it. |
|
|
29
|
+
| 2. App-wide classes and defaults | `app/app.config.ts` → `gallopUi.pt.<Component>.<section>`, `gallopUi.defaults.<Component>.<prop>` | The app's look for a component everywhere; app-wide `size` and the like. |
|
|
30
|
+
| 3. One instance | the `pt` prop: `:pt="{ item: 'py-1' }"` | Inner parts of one call site. |
|
|
31
|
+
| 4. One instance's root | `class` | `class` is `pt.root` at the call site. |
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
// app/app.config.ts
|
|
35
|
+
export default defineAppConfig({
|
|
36
|
+
gallopUi: {
|
|
37
|
+
timeZone: "America/New_York", // formatters' and date pickers' default zone
|
|
38
|
+
defaults: { Button: { size: "sm" } }, // an explicit prop still wins
|
|
39
|
+
pt: { DataTable: { tableView: "rounded-lg" } },
|
|
40
|
+
},
|
|
41
|
+
});
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
`gallopUi` is typed: a wrong component, section or default key is a type error, not a silent no-op. Each
|
|
45
|
+
component's `.md` "Customizing" section lists its sections. Some keys are shared (`Field` is the root of every
|
|
46
|
+
field, `Table` covers Table and DataTable's `<table>`, `Pill` also styles StatusPill, `Modal` also ConfirmDialog);
|
|
47
|
+
the README lists them.
|
|
48
|
+
|
|
49
|
+
### Merge order, and why `class` always wins
|
|
50
|
+
|
|
51
|
+
Every section merges through tailwind-merge in this order:
|
|
52
|
+
|
|
53
|
+
**layer default → app `gallopUi.pt` → `pt` prop → `class`** (for `root`).
|
|
54
|
+
|
|
55
|
+
A later class *replaces* a conflicting earlier one (`px-2` replaces the default padding); it doesn't add to it.
|
|
56
|
+
The layer writes every state it knows about (size, color, variant, disabled, invalid, checked, selected, open…) as
|
|
57
|
+
a plain class chosen in script, so a caller's class always beats it. What that means for you:
|
|
58
|
+
|
|
59
|
+
- To restyle a state the component knows, write a plain class: `class="px-2"` replaces the size's padding for
|
|
60
|
+
every size. To target one size, use the data attribute the element renders: `data-[size=sm]:px-2`.
|
|
61
|
+
- `hover:`, `focus-visible:`, `active:` defaults are replaced by the same variant: `hover:bg-surface-muted`.
|
|
62
|
+
- States Reka changes while open (`data-highlighted`, `data-[state=open]`, `data-[side=…]`) are replaced only by the
|
|
63
|
+
same variant in that section: `pt: { item: "data-highlighted:bg-fill" }`. A plain `bg-*` on an item doesn't change
|
|
64
|
+
its highlighted look.
|
|
65
|
+
- **An app's `pt` merges with the defaults; it doesn't replace them.** A default `dark:` class survives unless you
|
|
66
|
+
set the same property under `dark:`. When you recolour, restate the dark half (or, better, use tokens).
|
|
67
|
+
- Size an `<Icon>` with `text-*`, not `size-*` (@nuxt/icon sets width and height to `1em` outside Tailwind's
|
|
68
|
+
layers).
|
|
69
|
+
- Overlays (Modal, Drawer, Popover, Tooltip, DropdownMenu) portal their box away: that box is `root`, so `class`
|
|
70
|
+
still styles what you see. The backdrop is `overlay`.
|
|
71
|
+
|
|
72
|
+
## Tokens and dark mode
|
|
73
|
+
|
|
74
|
+
- **Dark mode is required in every app.** No light-only option, no pinned light colours.
|
|
75
|
+
- Each token is one `light-dark(<light>, <dark>)` declaration. What switches is `color-scheme`, set by the app's
|
|
76
|
+
strategy: the OS (`:root { color-scheme: light dark }`, the template default), or an attribute on `<html>`
|
|
77
|
+
(`data-color-scheme="light|dark"`, set from a cookie by `useColorScheme()`; no flash on first paint).
|
|
78
|
+
`TOKENS.md` has the contract; `theme/neutral.css` has every value.
|
|
79
|
+
- In app code write token classes (`bg-surface`, `text-fg-muted`, `border-line`, `bg-danger-soft`), not
|
|
80
|
+
`bg-white dark:bg-zinc-900`. Status colours are the `danger | warning | success | info` families.
|
|
81
|
+
- `yarn ui:tokens` checks the app's theme CSS against the contract: what is missing, what still has an old name.
|
|
82
|
+
- A Light / Dark / System choice is `useColorScheme()`, or `show-color-scheme` on Sidebar or TopBar.
|
|
83
|
+
- One UI font per app: `--font-sans` in `@theme` in `main.css`. Never set the font from a layout.
|
|
84
|
+
|
|
85
|
+
## Dates, times and time zones
|
|
86
|
+
|
|
87
|
+
- Instants display in `gallopUi.timeZone` (an app default; UTC with a dev warning when unset, never the browser's
|
|
88
|
+
zone, which the server can't know). Pass `timeZone` per call when it differs per user.
|
|
89
|
+
- A date-only `"2025-01-28"` is never shifted. Bind date-only fields as strings (`InputDate model-type="string"`).
|
|
90
|
+
- `InputTime`'s `"HH:mm"` model is never shifted either.
|
|
91
|
+
|
|
92
|
+
## `/_ui`: the playground in every app
|
|
93
|
+
|
|
94
|
+
`yarn dev`, then open `/_ui` (development only; production never has it):
|
|
95
|
+
|
|
96
|
+
| URL | Shows |
|
|
97
|
+
|---|---|
|
|
98
|
+
| `/_ui` | Every component, searchable, grouped by tier. |
|
|
99
|
+
| `/_ui/<Name>` | Every story of one component, plus its `.md` in a tab. |
|
|
100
|
+
| `/_ui/<Name>/<story>` | One story with prop controls. |
|
|
101
|
+
|
|
102
|
+
Query parameters: `theme=light|dark`, `width=390` (a phone frame that triggers the app's breakpoints), `bare=1`,
|
|
103
|
+
`still=1` (no animation, for screenshots). The page renders in *this* app's tokens, fonts, `gallopUi.pt` and
|
|
104
|
+
`gallopUi.defaults`, so it is what this app's users see. Use it to choose a component and to check a restyle in
|
|
105
|
+
both schemes at 390.
|
|
106
|
+
|
|
107
|
+
## Finding things in the subtree
|
|
108
|
+
|
|
109
|
+
```sh
|
|
110
|
+
grep -i "date range" layers/gallop-ui/CATALOGUE.md # which component
|
|
111
|
+
sed -n '/^## When not to use/,/^## /p' layers/gallop-ui/components/Select/Select.md
|
|
112
|
+
grep -rn "searchInput\|search-input" layers/gallop-ui/components/Select/Select.md
|
|
113
|
+
ls layers/gallop-ui/components layers/gallop-ui/composables
|
|
114
|
+
git log --oneline -3 -- layers/gallop-ui # which pull the app is on
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
## Per-app guards
|
|
118
|
+
|
|
119
|
+
- `yarn ui:check` (lefthook pre-commit, `--staged`) fails when a commit mixes `layers/gallop-ui` with app files, or an
|
|
120
|
+
app component shadows a layer component.
|
|
121
|
+
- `yarn ui:test` (pre-push, CI) runs the layer's own tests against the app's dependencies.
|
|
122
|
+
- The app's linter, formatter and Renovate ignore `layers/gallop-ui`. Don't "fix" lint in it.
|
|
@@ -131,7 +131,7 @@ Always use `@` mentions when referring to team members in comments. Use the Line
|
|
|
131
131
|
|
|
132
132
|
## Writing Issues
|
|
133
133
|
|
|
134
|
-
> **Tech stack context:** All projects use Nuxt 4 + Nitro + Kysely + PostgreSQL +
|
|
134
|
+
> **Tech stack context:** All projects use Nuxt 4 + Nitro + Kysely + PostgreSQL + gallop-ui + Tailwind CSS v4. See `tech-stack.md` for full details.
|
|
135
135
|
|
|
136
136
|
Read the examples before writing an issue — they show the voice and level of detail better than any rule:
|
|
137
137
|
|
|
@@ -171,7 +171,7 @@ A plain, sentence-case statement of the outcome — "Send a quote by email from
|
|
|
171
171
|
| Type | Sections after Context |
|
|
172
172
|
|------|------------------------|
|
|
173
173
|
| **Backend** (incl. data model) | `## Functionality` — bullets of behavior, rules, edge cases, out-of-scope |
|
|
174
|
-
| **Frontend** | `## Requirements` (checkboxes) · `## UI Notes` — repo-verified pages/components,
|
|
174
|
+
| **Frontend** | `## Requirements` (checkboxes) · `## UI Notes` — repo-verified pages/components, gallop-ui components, "Follow DESIGN_LANGUAGE.md". If the repo can't be checked, leave paths out — no "To Determine" / TBD section. |
|
|
175
175
|
| **Bug** | `## Bug` (what happens vs. what should) · `## Root cause` · `## Steps to reproduce` · `## Likely location` — replaces Context |
|
|
176
176
|
| **Discovery** | `## Open question` — the options, each with its trade-off. AC: settled with the client, recorded in "Our thinking", dependent issues updated. |
|
|
177
177
|
| **Tech Debt** | `## Requirements` · optional `## Files affected` |
|
|
@@ -218,11 +218,11 @@ Issues are assigned by role: the **Frontend/PM lead** or the **Backend lead**. T
|
|
|
218
218
|
|-----------|-----------------|
|
|
219
219
|
| Kysely migrations, schema design, complex DB queries | Backend lead |
|
|
220
220
|
| Complex Nitro API handlers (transactions, multi-table) | Backend lead |
|
|
221
|
-
| Vue pages,
|
|
221
|
+
| Vue pages, gallop-ui components, Tailwind styling, UX | Frontend/PM lead |
|
|
222
222
|
| Simple CRUD API endpoint (single table, straightforward) | Either (Frontend/PM lead can handle) |
|
|
223
223
|
| Client requirement gathering, design | Frontend/PM lead |
|
|
224
224
|
| Bug — Kysely/DB/server middleware | Backend lead |
|
|
225
|
-
| Bug — Vue/
|
|
225
|
+
| Bug — Vue/gallop-ui/Tailwind/client-side | Frontend/PM lead |
|
|
226
226
|
| Bug — fullstack | Discuss, assign based on root cause |
|
|
227
227
|
|
|
228
228
|
---
|
|
@@ -26,7 +26,7 @@ Dispatchers set the same job type on every visit of a job, which is repetitive a
|
|
|
26
26
|
|
|
27
27
|
* Components: `app/components/JobEditor.vue` (job type picker), `app/components/VisitRow.vue`, `app/components/VisitRatePreview.vue` — checked in the repo.
|
|
28
28
|
* Pages: `app/pages/jobs/[id]/edit.vue`, `app/pages/jobs/[id]/index.vue`.
|
|
29
|
-
*
|
|
29
|
+
* `Select` for the job type, `Input` for the name, `InputDate` for the date (all gallop-ui, in a `FormField`).
|
|
30
30
|
* Follow DESIGN_LANGUAGE.md — zinc palette, no decorative shadows.
|
|
31
31
|
|
|
32
32
|
## Acceptance criteria
|
|
@@ -14,9 +14,9 @@ This document describes the standard tech stack used across all Gallop Systems p
|
|
|
14
14
|
| **Query Builder** | Kysely (type-safe SQL) | ^0.28.9 |
|
|
15
15
|
| **Auth** | nuxt-auth-utils (session-based) | ^0.5.27 |
|
|
16
16
|
| **OAuth** | Google OAuth (optional) | via nuxt-auth-utils |
|
|
17
|
-
| **UI Components** |
|
|
17
|
+
| **UI Components** | gallop-ui (Nuxt layer at `layers/gallop-ui`, built on Reka UI) | vendored by git subtree |
|
|
18
18
|
| **Styling** | Tailwind CSS v4 | ^4.1.18 |
|
|
19
|
-
| **Icons** |
|
|
19
|
+
| **Icons** | `@nuxt/icon` with Iconify Lucide (`lucide:*`) | — |
|
|
20
20
|
| **Validation** | Zod | ^4.3.5 |
|
|
21
21
|
| **Date Handling** | date-fns | ^4.1.0 |
|
|
22
22
|
| **Testing** | Vitest | ^4.0.17 |
|
|
@@ -33,13 +33,13 @@ This document describes the standard tech stack used across all Gallop Systems p
|
|
|
33
33
|
|
|
34
34
|
```
|
|
35
35
|
app/ # Frontend
|
|
36
|
-
├── assets/css/main.css # Tailwind +
|
|
36
|
+
├── assets/css/main.css # Tailwind + colour tokens (light and dark)
|
|
37
37
|
├── components/ # Vue components (auto-imported)
|
|
38
38
|
├── composables/ # Vue composables (auto-imported)
|
|
39
39
|
├── layouts/ # Layout templates
|
|
40
40
|
├── middleware/ # Client-side route middleware
|
|
41
41
|
├── pages/ # File-based routing
|
|
42
|
-
└── plugins/ # Vue plugins
|
|
42
|
+
└── plugins/ # Vue plugins
|
|
43
43
|
|
|
44
44
|
server/ # Backend (Nitro)
|
|
45
45
|
├── api/ # API routes (file-based: users/index.get.ts → GET /api/users)
|
|
@@ -60,7 +60,7 @@ server/ # Backend (Nitro)
|
|
|
60
60
|
shared/ # Shared between frontend + backend
|
|
61
61
|
└── types/ # Type declarations (auth.d.ts)
|
|
62
62
|
|
|
63
|
-
|
|
63
|
+
layers/gallop-ui/ # gallop-ui layer (shared UI components, git subtree)
|
|
64
64
|
```
|
|
65
65
|
|
|
66
66
|
---
|
|
@@ -189,22 +189,20 @@ Test file locations:
|
|
|
189
189
|
- Backend: `server/**/*.test.ts` (co-located with handlers)
|
|
190
190
|
- Frontend: `app/components/**/*.test.ts`, `app/pages/**/*.test.ts`, `app/composables/**/*.test.ts`
|
|
191
191
|
|
|
192
|
-
### UI Components (
|
|
192
|
+
### UI Components (gallop-ui)
|
|
193
193
|
|
|
194
|
-
-
|
|
195
|
-
-
|
|
196
|
-
-
|
|
197
|
-
-
|
|
198
|
-
|
|
199
|
-
Available Volt components:
|
|
200
|
-
`VoltButton`, `VoltSecondaryButton`, `VoltCard`, `VoltDataTable`, `VoltDialog`, `VoltConfirmDialog`, `VoltInputText`, `VoltPassword`, `VoltSelect`, `VoltTextarea`, `VoltAvatar`, `VoltTag`, `VoltMessage`, `VoltToast`
|
|
194
|
+
- Components come from the **gallop-ui** layer at `layers/gallop-ui`. They are auto-imported by their plain names: `Button`, `Card`, `DataTable`, `Modal`, `Input`, `Select`, `FormField`, `Pill`, `Alert`, and so on. No prefix.
|
|
195
|
+
- `layers/gallop-ui/CATALOGUE.md` lists every component with a "use it for" column. Read it before building any UI. Restyle with `class` or `pt`; don't edit the layer.
|
|
196
|
+
- Feedback goes through composables: `useToast()` with `<Toaster />`, `useConfirm()` with `<ConfirmDialog />`, each mounted once.
|
|
197
|
+
- Never name a component after a layer component in `app/components` (it would shadow the layer).
|
|
198
|
+
- Use the **gallop-ui** skill for how to use and change the layer.
|
|
201
199
|
|
|
202
200
|
### Design System Essentials
|
|
203
201
|
|
|
204
202
|
- **Zinc-first palette** — zinc for almost everything, color only for semantic meaning
|
|
205
203
|
- **No decorative shadows** — shadows only on hover for interactivity
|
|
206
204
|
- **Rounding:** `rounded-xl` for inputs/buttons, `rounded-2xl` for cards
|
|
207
|
-
- **Icons:**
|
|
205
|
+
- **Icons:** Iconify Lucide names (`lucide:search`)
|
|
208
206
|
- **Refer to `DESIGN_LANGUAGE.md`** for full component styling reference
|
|
209
207
|
|
|
210
208
|
---
|