@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
@@ -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.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "linear",
3
- "description": "Create, triage, and manage Linear issues at Gallop Systems following team conventions: cycle placement, issue templates, project / milestone hierarchy, project refresh, and cycle rebalance. Includes a bash GraphQL CLI for the operations the Linear MCP server doesn't expose.",
3
+ "description": "Create, triage, and manage Linear issues at Gallop Systems following team conventions: issue status, issue templates, and the project / milestone hierarchy. Includes a Node GraphQL CLI for the operations the Linear MCP server doesn't expose.",
4
4
  "version": "1.0.0",
5
5
  "author": {
6
6
  "name": "Gallop Systems"