@gallopsystems/agent-skills 1.30.0 → 1.31.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/README.md +13 -1
  2. package/package.json +1 -1
  3. package/plugins/copier-template/skills/copier-template/applying-updates.md +2 -2
  4. package/plugins/frontend-design/skills/frontend-design/SKILL.md +10 -10
  5. package/plugins/gallop-ui/.claude-plugin/plugin.json +8 -0
  6. package/plugins/gallop-ui/skills/gallop-ui/SKILL.md +108 -0
  7. package/plugins/gallop-ui/skills/gallop-ui/api-principles.md +157 -0
  8. package/plugins/gallop-ui/skills/gallop-ui/changing-the-layer.md +102 -0
  9. package/plugins/gallop-ui/skills/gallop-ui/checking-other-apps.md +108 -0
  10. package/plugins/gallop-ui/skills/gallop-ui/finding-a-component.md +92 -0
  11. package/plugins/gallop-ui/skills/gallop-ui/pitfalls.md +82 -0
  12. package/plugins/gallop-ui/skills/gallop-ui/pulling-updates.md +101 -0
  13. package/plugins/gallop-ui/skills/gallop-ui/using-in-an-app.md +122 -0
  14. package/plugins/linear/skills/linear/SKILL.md +4 -4
  15. package/plugins/linear/skills/linear/examples/frontend-feature.md +1 -1
  16. package/plugins/linear/skills/linear/tech-stack.md +12 -14
  17. package/plugins/nitro-testing/skills/nitro-testing/SKILL.md +3 -26
  18. package/plugins/nitro-testing/skills/nitro-testing/frontend-testing.md +7 -33
  19. package/plugins/tailwind-v4/skills/tailwind-v4/SKILL.md +12 -14
  20. package/plugins/tailwind-v4/skills/tailwind-v4/gotchas.md +13 -18
  21. package/plugins/vue-nuxt/skills/vue-nuxt/SKILL.md +2 -2
  22. package/plugins/vue-nuxt/skills/vue-nuxt/auto-imports.md +2 -2
  23. package/plugins/vue-nuxt/skills/vue-nuxt/template-idioms.md +1 -1
  24. package/plugins/vue-nuxt/skills/vue-nuxt/v-model.md +6 -6
  25. package/plugins/vue-nuxt/skills/vue-nuxt/watch.md +3 -3
  26. package/plugins/volt-primevue/.claude-plugin/plugin.json +0 -8
  27. package/plugins/volt-primevue/skills/volt-primevue/SKILL.md +0 -170
  28. package/plugins/volt-primevue/skills/volt-primevue/config.md +0 -51
  29. package/plugins/volt-primevue/skills/volt-primevue/gotchas.md +0 -140
  30. package/plugins/volt-primevue/skills/volt-primevue/theming.md +0 -137
package/README.md CHANGED
@@ -18,9 +18,9 @@ Then install the skills you want:
18
18
  /plugin install doctl@gallop-systems-agent-skills
19
19
  /plugin install git-github@gallop-systems-agent-skills
20
20
  /plugin install copier-template@gallop-systems-agent-skills
21
- /plugin install volt-primevue@gallop-systems-agent-skills
22
21
  /plugin install vue-nuxt@gallop-systems-agent-skills
23
22
  /plugin install frontend-design@gallop-systems-agent-skills
23
+ /plugin install gallop-ui@gallop-systems-agent-skills
24
24
  ```
25
25
 
26
26
  ## Updating
@@ -168,6 +168,18 @@ Covers:
168
168
  - Releasing versions (tag + GitHub Release) and the update-checker workflow pattern
169
169
  - Applying `copier update` in descendants: conflict triage, `.rej` files, validation
170
170
 
171
+ ### gallop-ui
172
+
173
+ Use and change gallop-ui, Gallop's shared Nuxt UI layer, vendored into each app at `layers/gallop-ui` by git subtree.
174
+ Activates in any repo with `layers/gallop-ui`.
175
+
176
+ Covers:
177
+ - Using the layer in an app: auto-imports, `pt`, `class`, `gallopUi` in `app.config`, merge order, tokens and dark mode, `/_ui`
178
+ - Finding the right component (exact, close or no match), primitives before composites, proposing a component
179
+ - API principles and the bar for an API change (owner calls, semver, codemods)
180
+ - Pulling a release: `yarn ui:pull`, `ui:migrate`, `ui:tokens`, `ui:check`, merge-commit subtree PRs
181
+ - Changing the layer, checking every app with `ui:impact` and screenshot sweeps, and working rules learned the hard way
182
+
171
183
  ## Contributing a Lesson Back
172
184
 
173
185
  Every skill ends with a **Contributing Back** section: when Claude works through
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gallopsystems/agent-skills",
3
- "version": "1.30.0",
3
+ "version": "1.31.0",
4
4
  "description": "Gallop Systems agent skills, symlinked into .claude/skills (Claude Code) and .agents/skills (Codex) on install.",
5
5
  "license": "UNLICENSED",
6
6
  "repository": {
@@ -39,7 +39,7 @@ find . -name '*.rej' # hunks copier couldn't apply
39
39
  grep _commit .copier-answers.yml # confirm the new (latest) version
40
40
  ```
41
41
 
42
- - **`--skip-tasks`**: `_tasks` (migrations, `npx volt-vue add`, seeds) only run on initial `copy`, but skip them explicitly so an update never fires surprise scaffold work (a stray migration, a regenerated component). Run any genuinely-needed task by hand afterward.
42
+ - **`--skip-tasks`**: `_tasks` (migrations, seeds) only run on initial `copy`, but skip them explicitly so an update never fires surprise scaffold work (a stray migration, a regenerated component). Run any genuinely-needed task by hand afterward.
43
43
  - **Dirty-tree refuses on untracked dirs/files too**, not just staged changes — `git stash` alone misses them. Use `--include-untracked`, or move local-tooling dirs (`.agents/`, `.claude/`, `.do/`, editor swap files) aside and restore them after.
44
44
  - **The landed version is almost always higher than the bot PR advertised** — `copier update` targets the latest tag. Read the real version from `_commit` *after* the run and title the commit/PR from that. A multi-version jump means several releases land at once — budget for more conflicts.
45
45
 
@@ -120,7 +120,7 @@ grep -nE 'first_name|last_name|deactivated_at|Number\(' <adopted-file>
120
120
  git clone --depth 1 --branch v<NEW> <template-url> /tmp/tpl-<NEW>
121
121
  ```
122
122
 
123
- When a conflict reflects a deliberate template convention change (snake_case session fields, a renamed env var), migrating *toward* the template and updating the few consumers kills future churn — unless it's an intentional permanent fork (styled-PrimeVue vs Volt, a deliberately different env-var name), which you keep.
123
+ When a conflict reflects a deliberate template convention change (snake_case session fields, a renamed env var), migrating *toward* the template and updating the few consumers kills future churn — unless it's an intentional permanent fork (a deliberately different auth provider, a deliberately different env-var name), which you keep.
124
124
 
125
125
  **`.rej` files** — copier couldn't apply a hunk because the local file diverged too far. A `.rej` is a unified diff of *just the rejected hunk*; the target file was left untouched there. Triage each:
126
126
 
@@ -38,7 +38,7 @@ The first three are the foundational lenses — every other principle and rule s
38
38
  - **Color carries meaning, not decoration.** Color should encode state, category, or status (success/warning/danger/info, entity types, lifecycle stages). Don't color things just to make them look lively. A user should be able to glance at the screen and infer meaning from the color alone.
39
39
  - **Icons are accents, not decoration.** Icons earn their place when they speed up scanning (status indicators, action buttons, type markers next to a label). They don't earn their place as ornaments next to every heading or list item. Sparing use makes the icons that *do* appear actually informative.
40
40
  - **Match the neighborhood.** Before introducing a new visual pattern (a new card style, a new button variant, a new color), look at adjacent pages/components in the same repo. If the pattern already exists, reuse it. If it doesn't, ask whether this surface really needs to be different.
41
- - **Use the design system, not bespoke styles.** Prefer existing component-library primitives (PrimeVue / Volt / Tailwind tokens) over hand-rolled CSS. If a token or component doesn't fit, push on whether the design should change to fit the system before adding custom styles.
41
+ - **Use the design system, not bespoke styles.** Prefer the gallop-ui layer's components and the app's Tailwind tokens (see the **gallop-ui** skill) over hand-rolled CSS. If a token or component doesn't fit, push on whether the design should change to fit the system before adding custom styles.
42
42
  - **Consistency builds trust.** Use familiar patterns and standard controls. A "Settings" button looks like settings buttons elsewhere; a destructive action looks destructive everywhere. Novelty in interaction patterns has to earn its place.
43
43
  - **Aesthetic integrity.** The visual style matches the function. A serious tool looks serious; a playful experience can look playful. Don't dress a workspace tool in marketing gloss, and don't make a casual app feel bureaucratic.
44
44
  - **Hierarchy first, decoration second.** Before picking colors or borders, make sure the visual weight (size, spacing, contrast) tells the user what's most important on the screen. Decoration should reinforce hierarchy, not compete with it.
@@ -145,9 +145,9 @@ The first three are the foundational lenses — every other principle and rule s
145
145
 
146
146
  #### Inline `pt` / styling objects in the template — don't lift them into `<script setup>`
147
147
 
148
- - **Rule:** When passing a `pt` object (PrimeVue / Volt) or any other static style/config object to a component, write it inline on the element in the template: `:pt="{ table: '...', column: { headerCell: '...' } }"`. Don't declare it as a `const tablePt = {...}` in `<script setup>` and reference it. Same for one-off prop objects that are pure styling (e.g. `:pt:root` shorthand, inline class maps). Only lift to the script when the object is genuinely reused across multiple elements *or* when it's computed from reactive state.
149
- - **Why:** Two reasons. (1) **Tailwind only sees classes that appear in template source** — its JIT scanner extracts class names from template strings at build time. Classes hidden inside `<script setup>` JS strings (`const tablePt = { ... "bg-zinc-50" ... }`) may not be compiled into the CSS bundle until the JS executes, which can produce a flash of unstyled content. Inline `pt:section:class="..."` puts the classes where the scanner can find them. (2) It keeps the styling next to the markup it styles — the template should be readable top-to-bottom without bouncing into the script to resolve identifiers. Lifting static `pt` objects fragments where styling lives and mirrors a React pattern that doesn't fit Vue SFCs. This has come up repeatedly in code review on list and detail pages.
150
- - **How to apply:** Default `pt` (and similar static config objects) inline. If the same `pt` is duplicated across 3+ elements, extract it — otherwise inline it, even if the object is large. Prefer `pt:section:class="..."` shorthand where the customization is a single section.
148
+ - **Rule:** When passing a gallop-ui `pt` object or any other static style/config object to a component, write it inline on the element in the template: `:pt="{ headerCell: '...', cell: '...' }"`. Don't declare it as a `const tablePt = {...}` in `<script setup>` and reference it. Same for one-off prop objects that are pure styling (e.g. `class` on a layer component, which is shorthand for `pt.root`; inline class maps). Only lift to the script when the object is genuinely reused across multiple elements *or* when it's computed from reactive state.
149
+ - **Why:** Two reasons. (1) **Tailwind only sees classes that appear in template source** — its JIT scanner extracts class names from template strings at build time. Classes hidden inside `<script setup>` JS strings (`const tablePt = { ... "bg-zinc-50" ... }`) may not be compiled into the CSS bundle until the JS executes, which can produce a flash of unstyled content. Inline `:pt="{ ... }"` puts the classes where the scanner can find them. (2) It keeps the styling next to the markup it styles — the template should be readable top-to-bottom without bouncing into the script to resolve identifiers. Lifting static `pt` objects fragments where styling lives and mirrors a React pattern that doesn't fit Vue SFCs. This has come up repeatedly in code review on list and detail pages.
150
+ - **How to apply:** Default `pt` (and similar static config objects) inline. If the same `pt` is duplicated across 3+ elements, extract it — otherwise inline it, even if the object is large. Prefer `class` where the customization is only the root, and a `pt` section string (`:pt="{ cell: 'px-2' }"`) otherwise. An app-wide look belongs in `gallopUi.pt` in `app.config`, not repeated per page.
151
151
 
152
152
 
153
153
  #### Cards are flat and structural, not visually elevated
@@ -184,7 +184,7 @@ The first three are the foundational lenses — every other principle and rule s
184
184
 
185
185
  - **Rule:** Any page whose primary job is to present a list or table of records shows the total number of records in the view — **as a bare number rendered right next to the page title, never in a table footer.** The preferred form is the count sitting immediately after the `<h2>` title: a baseline-aligned, muted `tabular-nums` span showing *just the number* (`Clients` then `3`) — **not** "3 clients", and **not** a `<tfoot>` "N clients" summary row. If a list page already has a `<tfoot>` total (record count and/or aggregate sums like "total active projects"), remove the whole footer and move the record count up next to the title; footer-only aggregate sums can be dropped unless the user asks to keep them. The count reflects what's actually in view: when filters or search narrow the set, the number updates to the filtered total (optionally "12 of 47" when a filter is active). Keep it low-key — small, muted type — not a hero stat.
186
186
  - **Why:** On a list surface the size of the collection is first-order information: it tells the user whether they're looking at 8 things or 800, whether a filter did anything, and whether a page finished loading. Leaving it out makes the user scroll or guess. The count as a number by the title is preferred over a footer summary row — the footer buries the fact at the bottom where it's found only after scrolling, and repeats the entity noun the title already states. It's cheap to render and it's the kind of small competence signal that makes a tool feel trustworthy. This is the concrete form of the "a brief count under a header is fine" allowance above — on list pages it's not just allowed, it's expected.
187
- - **How to apply:** Put the count inline with the title as part of the header treatment. The pattern in this stack (Nuxt/Volt/Tailwind):
187
+ - **How to apply:** Put the count inline with the title as part of the header treatment. The pattern in this stack (Nuxt/gallop-ui/Tailwind; `PageHeader` has a `count` prop that does this for you, so use it on list pages):
188
188
  ```vue
189
189
  <div class="flex items-baseline gap-2">
190
190
  <h2 class="text-base font-medium text-fg">Clients</h2>
@@ -249,7 +249,7 @@ The first three are the foundational lenses — every other principle and rule s
249
249
 
250
250
  #### Inputs in flex/grid cells must stretch to fill — `w-full min-w-0` on the input, `min-w-0` on the cell
251
251
 
252
- - **Rule:** When placing an input (text, select, date, etc.) inside a flex column or grid cell, give the input `w-full min-w-0` (via `pt:root:class` for Volt/PrimeVue components) and the parent cell `min-w-0`. Don't rely on the input's intrinsic ~20ch browser-default width to "happen to fit." For multi-column rows (e.g. city / state / zip), define explicit grid track sizes (`grid-cols-[1fr_110px_96px]`) and let inputs fill each track.
252
+ - **Rule:** When placing an input (text, select, date, etc.) inside a flex column or grid cell, give the input `w-full min-w-0` (via `class`, which is `pt.root`, on gallop-ui components; `Input` and `Select` with an icon or clear button wrap the field, so `class` then sizes the wrapper) and the parent cell `min-w-0`. Don't rely on the input's intrinsic ~20ch browser-default width to "happen to fit." For multi-column rows (e.g. city / state / zip), define explicit grid track sizes (`grid-cols-[1fr_110px_96px]`) and let inputs fill each track.
253
253
  - **Why:** Inputs render at their native size by default and ignore their grid/flex track width. In constrained surfaces — especially modals — that pushes the layout past the container and triggers horizontal scroll. Min-width defaults on flex/grid items compound the problem. A common failure: a "new record" modal that scrolls side-to-side because each input claimed its native width inside a ~480px dialog.
254
254
  - **How to apply:** Every input inside a dialog, panel, or constrained surface gets `pt:root:class="w-full min-w-0"` (or `class="w-full min-w-0"` for native inputs). Each containing flex/grid cell gets `min-w-0`. For belt-and-braces in modals, `overflow-x-hidden` on the form is fine. Don't try to fix overflow by widening the dialog — fix the elasticity.
255
255
 
@@ -284,8 +284,8 @@ The first three are the foundational lenses — every other principle and rule s
284
284
  #### Buttons and controls are *small* — delicate, compact, never chunky
285
285
 
286
286
  - **Rule:** Default button height is **~26–28px**, not 36px or 40px. Inputs, selects, segmented controls, and chips match: ~26–30px tall. Padding is tight (~8–10px horizontal, ~4–6px vertical). Radii are small (`rounded-md`, ~4–6px). Icon-only buttons are square at the same height (~26–28px box) with a 14–16px icon inside. Borders are 1px and low-contrast. Filled "primary" buttons get a single subtle background color, no gradient, no inner highlight, no shadow.
287
- - **Why:** The preferred aesthetic reads as delicate and tool-like — controls sit quietly and don't dominate the layout. Default component-library button sizes (Tailwind UI, shadcn, PrimeVue defaults) are typically one or two steps too big for this; they feel chunky and consumer-app-y when shipped as-is.
288
- - **How to apply:** Override the default size of every button/input/select to land in the 26–28px range. In shadcn-style libraries, prefer the `sm` (or even `xs`/custom) size variant for controls; in Tailwind, this is roughly `h-7` (28px) or `h-6` (24px) for the most delicate feel. Make sure the hit-target rule is still met via padding even when the visual is small.
287
+ - **Why:** The preferred aesthetic reads as delicate and tool-like — controls sit quietly and don't dominate the layout. Default component-library button sizes (Tailwind UI, shadcn, other kits' defaults) are typically one or two steps too big for this; they feel chunky and consumer-app-y when shipped as-is.
288
+ - **How to apply:** In a gallop-ui app, set the size once, app-wide: `gallopUi.defaults` in `app.config.ts` (`{ Button: { size: "sm" }, Input: { size: "sm" } }`). Don't repeat `size="sm"` or `h-7` at each call site. On phones the layer keeps field text at 16px with a 24px line, so iOS doesn't zoom on focus, whatever the size; don't override that with a `text-*` class. Outside the layer, `h-7` (28px) is the target. Make sure the hit-target rule is still met via padding even when the visual is small.
289
289
 
290
290
  #### Button labels are verbs that name the action — never "OK," "Yes," or "Submit"
291
291
 
@@ -315,9 +315,9 @@ The first three are the foundational lenses — every other principle and rule s
315
315
 
316
316
  #### Successful mutations get a toast; form errors stay inline in the form
317
317
 
318
- - **Rule:** When a create/update/delete succeeds, show a brief success toast (e.g. `severity: "success"`, `life: 3000`, summary names what happened, detail names the affected entity — "Client created" + the company name). Mount the toast container **once in the default layout** (`<VoltToast position="bottom-right" />`), not per-page. Errors that the user needs to fix in a still-open form (validation, server rejection) render **inline** in the form — never as a toast that disappears while they're correcting the field. Toasts are for "this is now done" feedback; inline messages are for "fix this and try again."
318
+ - **Rule:** When a create/update/delete succeeds, show a brief success toast (e.g. `color: "success"`, title names what happened, description names the affected entity — "Client created" + the company name). Mount `<Toaster />` **once, in `app.vue`** (gallop-ui's layer; never per page, and a second one warns in dev). Errors that the user needs to fix in a still-open form (validation, server rejection) render **inline** in the form — never as a toast that disappears while they're correcting the field. Toasts are for "this is now done" feedback; inline messages are for "fix this and try again."
319
319
  - **Why:** Success toasts give the immediate confirmation users need ("did that actually save?") without blocking the next action. But surface-specific errors in toasts vanish before the user has fixed the input, forcing them to remember what went wrong. Splitting the two channels — toast for completion, inline for in-context errors — is what makes mutations feel both responsive and forgiving.
320
- - **How to apply:** In layouts, mount `<VoltToast position="bottom-right" />` once. In pages with mutations, `import { useToast } from "primevue/usetoast"` and `const toast = useToast()`. On success: close the dialog, refresh the data, then `toast.add({ severity: "success", summary, detail, life: 3000 })`. On error: keep the dialog open, render the message inline near the form (`<p class="text-[12px] text-red-600">`). Use the API-returned entity in the toast detail when possible — confirms the server actually persisted what the user typed.
320
+ - **How to apply:** Mount `<Toaster />` once in `app.vue`. In pages with mutations, `const { toast } = useToast()` (auto-imported from the layer; call it in setup, not in a handler). On success: close the dialog, refresh the data, then `toast({ title, description, color: "success" })`. The default `duration` is 5000ms; leave it. On error: keep the dialog open, render the message inline near the form with `<Alert color="error">` (or `FormField`'s `error`). Use the API-returned entity in the toast description when possible, since that confirms the server actually persisted what the user typed.
321
321
 
322
322
  #### Confirmations are reserved for irreversible actions; everything else gets undo
323
323
 
@@ -0,0 +1,8 @@
1
+ {
2
+ "name": "gallop-ui",
3
+ "description": "Use and change gallop-ui, Gallop's shared Nuxt UI layer (vendored at layers/gallop-ui by git subtree): finding the right component, pt and app.config styling, API principles, pulling releases and running the codemod, changing the layer, and checking that other apps don't break",
4
+ "version": "1.0.0",
5
+ "author": {
6
+ "name": "Gallop Systems"
7
+ }
8
+ }
@@ -0,0 +1,108 @@
1
+ ---
2
+ name: gallop-ui
3
+ description: Use and change gallop-ui, Gallop's shared Nuxt UI layer that every Gallop app vendors at `layers/gallop-ui` by git subtree (it replaced PrimeVue/Volt). Use whenever you work in a repo that has a `layers/gallop-ui` folder and touch UI (pages, components, forms, tables, styling, dark mode, `app.config` `gallopUi`), when choosing or building a component, when pulling a gallop-ui release (`yarn ui:pull`, `ui:migrate`), when changing the layer itself (the gallop-systems/gallop-ui repo), or when anyone asks about Gallop UI components, `pt`, tokens or `/_ui`.
4
+ ---
5
+
6
+ # gallop-ui
7
+
8
+ gallop-ui is Gallop's shared UI: Vue components, composables and formatters, built as a **Nuxt layer**. Every Gallop
9
+ app holds a copy at `layers/gallop-ui`, pulled from `gallop-systems/gallop-ui` with `git subtree` at a tagged
10
+ release, so an app's repository is complete on its own (no registry, no token, easy hand-over). It replaced
11
+ PrimeVue and Volt in every app. The layer is behaviour on **Reka UI**, styled with **Tailwind 4** and the app's
12
+ colour tokens.
13
+
14
+ - **The copier-nuxt template** scaffolds new apps with the layer already added, the `yarn ui:*` scripts
15
+ (`scripts/gallop-ui.mjs`), Tailwind pointed at the layer, lefthook guards and the layer's tests in CI. The template
16
+ ships infrastructure on its own cadence; the layer ships UI faster, by subtree.
17
+ - **Which apps use it:** every app made from the template. The layer may not name clients, so the list isn't kept
18
+ in it. Find them on this machine with `ls -d ~/Projects/*/layers/gallop-ui`, which is also how `yarn ui:impact`
19
+ finds them.
20
+ - **The source of truth is the layer's own docs, in the subtree, at the app's version.** Don't trust memory, or
21
+ this skill, for a prop name: read the file.
22
+
23
+ | File (under `layers/gallop-ui/`) | What it answers |
24
+ |---|---|
25
+ | `CATALOGUE.md` | Every component and composable, what it is, "use it for" phrases. Start here. |
26
+ | `components/<Name>/<Name>.md` | One component: when (not) to use, props, slots, events, `pt` sections, examples, migrating, a11y. |
27
+ | `CLAUDE.md` | The layer's rules for people and agents who change it. |
28
+ | `README.md` | Adding the layer, taking versions, customizing (`pt`, `gallopUi`), restyling states. |
29
+ | `TOKENS.md`, `FORMATTERS.md` | The colour-token contract; `formatDate`, `formatCurrency`… and time zones. |
30
+ | `CHANGELOG.md`, `migrations/<version>/`, `docs/migrating-to-*.md` | What changed, and the codemod tables. |
31
+ | `docs/decisions.md` | Settled API names and who decided them. Read before proposing a rename. |
32
+ | `docs/playground.md` | `/_ui` and `yarn ui:impact`. |
33
+
34
+ `yarn ui:version` prints the app's layer version.
35
+
36
+ ## Core rules
37
+
38
+ 1. **Never edit `layers/gallop-ui` in an app** for an app's need. Restyle with `class`, `pt` or `gallopUi.pt`;
39
+ change the layer in the gallop-ui repo ([changing-the-layer.md](changing-the-layer.md)).
40
+ 2. **Never shadow.** No file in `app/components` may register under a layer component's name. Adopting a layer
41
+ component deletes the app's copy in the same change. `yarn ui:check` enforces it.
42
+ 3. **The docs in the subtree win.** Before using a component, read its `.md`. Before writing a prop, check it there.
43
+ 4. **Dark mode is required.** Every app ships it. Colours come from tokens, never a raw palette class plus `dark:`.
44
+ 5. **Same or better, never a regression** — in look, behaviour and speed, light and dark, desktop and phone. Explain
45
+ every visual difference you cause.
46
+ 6. **Naming and API calls go to the owner.** You may decide implementation; you don't decide a new public name.
47
+ 7. **Client-neutral layer.** No client names, data, domain terms, screenshots or URLs in the layer: code, docs,
48
+ tests, commit messages, PR text.
49
+ 8. **Subtree PRs in an app are merged with a merge commit, never squashed.** Layer PRs are squashed.
50
+ 9. **Git hygiene:** never `git stash`, never `--no-verify`, never `pkill -f`; work in a new worktree; leave
51
+ uncommitted work alone ([pitfalls.md](pitfalls.md)).
52
+
53
+ ## Which component? (decision procedure)
54
+
55
+ 1. **Search.** `grep -i "<what you need>" layers/gallop-ui/CATALOGUE.md` (the "Use it for" column lists the phrases
56
+ people search with), then read the `.md` of every candidate, especially "When not to use". Browse `/_ui` in
57
+ `yarn dev` to see it in the app's own theme.
58
+ 2. **Exact match:** use it. Restyle with `class` (= `pt.root`) or `pt`; an app-wide look goes in `gallopUi.pt`.
59
+ 3. **Close match:** prefer, in order, a prop, a `pt` section, a slot. Don't wrap it to bolt on behaviour, don't fork
60
+ it, don't shadow it. If it truly lacks an option every app could use, propose extending it in the layer
61
+ (backward compatible).
62
+ 4. **No match:** compose layer primitives in the app. Propose a layer component when a second app needs the same
63
+ thing or it is a generic pattern. Composites in the layer are built only from layer primitives; a missing
64
+ primitive is built first.
65
+
66
+ Detail, and how to propose a component: [finding-a-component.md](finding-a-component.md).
67
+
68
+ ## Pull an update (decision procedure)
69
+
70
+ New worktree from `origin/main` → `yarn ui:pull vX.Y.Z` (its own commit; needs a clean tree) → read `CHANGELOG.md`
71
+ and `migrations/` between the two versions → on a breaking release, `yarn ui:migrate --dry`, then `yarn ui:migrate`
72
+ and work its checklist → `yarn ui:tokens`, `yarn ui:check` → remove workarounds the release makes unnecessary → full
73
+ tests and a before/after visual sweep → PR, merged with a **merge commit**.
74
+ Steps and commands: [pulling-updates.md](pulling-updates.md).
75
+
76
+ ## Change the layer (decision procedure)
77
+
78
+ Worktree of the gallop-ui repo from `origin/main` → read its `CLAUDE.md` and `docs/decisions.md` → change, keeping
79
+ the four files per component (`.vue`, `.md`, `.stories.ts`, `.test.ts`) in step → `yarn test`, `yarn typecheck`,
80
+ `yarn catalogue`, `yarn docs:check` → look at `/_ui` light and dark, at 1280 and 390 → `node scripts/impact.mjs`
81
+ across every app → Conventional Commit, PR, squash-merged only when CLEAN.
82
+ Steps: [changing-the-layer.md](changing-the-layer.md). Proving other apps don't break:
83
+ [checking-other-apps.md](checking-other-apps.md).
84
+
85
+ ## Reference files
86
+
87
+ - [using-in-an-app.md](using-in-an-app.md): auto-imports, `pt`, `class`, `gallopUi` in `app.config`, merge order,
88
+ tokens and dark mode, formatters, `/_ui`.
89
+ - [finding-a-component.md](finding-a-component.md): exact, close and no match; primitives vs composites; proposing
90
+ a component.
91
+ - [api-principles.md](api-principles.md): the API rules every component follows, and the bar for an API change.
92
+ - [pulling-updates.md](pulling-updates.md): taking a release into an app, the codemod, proof.
93
+ - [changing-the-layer.md](changing-the-layer.md): building or changing a component in the gallop-ui repo, and
94
+ releasing.
95
+ - [checking-other-apps.md](checking-other-apps.md): `ui:impact`, screenshot sweeps, computed styles, grepping call
96
+ sites, the DataTable `:key` rule.
97
+ - [pitfalls.md](pitfalls.md): working rules learned the hard way.
98
+
99
+ ## Contributing Back
100
+
101
+ This skill grows by adding what it doesn't cover yet. If you just worked through something in this domain that this
102
+ skill did not cover (an error you had to figure out, behaviour that doesn't match what's documented above, a
103
+ workflow knot), ask the user: **"Want me to contribute this back to the gallop-ui skill?"**
104
+
105
+ If yes, run `/contribute-skill`. If that command is not available, do the equivalent inline: distill the generic
106
+ lesson (placeholders only: no client names, IDs, domains or secrets), then branch or fork
107
+ [gallop-systems/agent-skills](https://github.com/gallop-systems/agent-skills) and open a PR editing this skill. A
108
+ rule about the layer's own API belongs in the layer's docs (`CLAUDE.md`, a component `.md`), not here.
@@ -0,0 +1,157 @@
1
+ # API principles
2
+
3
+ The rules every gallop-ui component follows. Use them to read an API you haven't seen, to review a change, and to
4
+ sketch a new component. The layer's `CLAUDE.md` is the enforced version, and `docs/decisions.md` records who
5
+ decided each name. When this file and the layer disagree, the layer wins: tell the user so this file gets fixed.
6
+
7
+ ## The goal
8
+
9
+ **An intuitive API is a prime goal, equal to the look.** Ask of every name and shape: would a new developer or
10
+ agent guess it without the docs? Would they misuse it?
11
+
12
+ - **Names say what a thing does, never how it is built.** `Select` with `search-input`, not a `Select` /
13
+ `SelectMenu` split that mirrors two Reka primitives. `DateCalendar`, because "Calendar" means a scheduling calendar.
14
+ - **One concept, one name; one behaviour, one prop.** Two components that differ only by a behaviour are one
15
+ component with a prop. The same idea on two components has the same prop name and values.
16
+ - **Flat, plain props over shaped objects:** InputDate `time`, not `granularity="minute"`.
17
+ - **Leave room for what's coming.** Don't take a name that a component we'll want later needs: the date grid is
18
+ `DateCalendar` because `Calendar` belongs to a future scheduling calendar. Before you choose a name, ask what
19
+ else it could mean in a UI kit.
20
+ - **Nuxt UI's vocabulary is the default, not a rule.** Use its name when it is clear to a caller; drop it when the
21
+ name or split reflects implementation. Never copy PrimeVue/Volt's API (`severity`, `fluid`, PrimeVue `pt` keys).
22
+ - **Fix a bad name before a release ships it**, rather than keeping it because apps use it. That is what the codemod
23
+ is for.
24
+
25
+ ## Shared props
26
+
27
+ | Prop | Values | Meaning |
28
+ |---|---|---|
29
+ | `color` | `primary \| neutral \| success \| info \| warning \| error` | What kind of thing it is. |
30
+ | `variant` | `solid \| soft \| subtle \| outline \| ghost \| link` | How loud it is. |
31
+ | `size` | `xs \| sm \| md \| lg \| xl` | App-wide default in `gallopUi.defaults.<Component>.size`. |
32
+ | `block` | boolean | Full width. |
33
+ | `disabled`, `loading`, `invalid`, `readonly`, `clearable` | | The same meaning everywhere. `clearable` is an x in the field that empties it. |
34
+
35
+ A component implements only the values apps use. Never a synonym (`tone`, `severity`, `kind`, `fluid`), and no new
36
+ colours: an app's extra button colour maps onto an existing `color`.
37
+
38
+ ## Naming patterns
39
+
40
+ - **`show<Thing>` for a boolean that adds a control:** `showClose`, `showToggle`, `showSearch`, `showSelectAll`,
41
+ `showStepper`, `showColorScheme`. A feature boolean stays an adjective or noun: `clearable`, `sticky`,
42
+ `collapsible`, `range`, `multiple`.
43
+ - **The listener rule:** a listener may switch on a control that does nothing without it. `@add` shows Board's "+",
44
+ `@back` shows PageHeader's back button (`back-to` stays the link form), `@row-click` makes DataTable rows
45
+ clickable, `@search` turns Select or Input to server search. Don't add a `show<Thing>` for a control whose only
46
+ job is to emit that event.
47
+ - **Events** are kebab-case (`clear-filters`, `load-more`). Present tense for a request the caller acts on (`move`,
48
+ `remove`, `search`), past tense for a notice that something happened (`copied`, `move-refused`). Overlays keep
49
+ Nuxt UI's `after:enter` / `after:leave`.
50
+ - **Accessible names:** `label` is always visible text. A landmark's name is the native `aria-label` (with a
51
+ built-in default such as Sidebar "Main"); a sub-part's name is a `*AriaLabel` prop (`backAriaLabel`,
52
+ `menuAriaLabel`). Every icon-only control needs a name.
53
+ - **Accessors are named after their thing:** `rowKey`, `cardKey`, `labelKey`, `valueKey`. A prop that is a function
54
+ of a row says so: DataTable `rowTo(row)`, `cardTo(row)`, `cardLinkLabel(row)`. A plain `to` always holds a
55
+ destination (`RouteLocationRaw`; an absolute URL opens in a new tab).
56
+ - **Nouns are singular:** `noun="invoice"`; plurals come from `pluralize`, with `pluralNoun` for odd words.
57
+ - **Controllers** of something that opens return `{ isOpen, open, close, toggle }`. A controller of two things
58
+ prefixes each with its thing: `useSidebar()` gives `isCollapsed`, `collapse()`, `expand()`, `toggleCollapsed()`
59
+ and `isDrawerOpen`.
60
+ - **`define…` vs `use…`:** `define…` registers something for the component's lifetime and returns nothing;
61
+ `use…` returns state or functions.
62
+
63
+ ## State: controlled or managed
64
+
65
+ - **One rule for state props** (`open`, `page`, `selected`, `collapsed`, `searchTerm`…): the prop is *controlled*
66
+ when the caller passes it **and** listens to its `update:` event; otherwise the component manages it, seeded from
67
+ the prop. That is Vue's `defineModel` rule; the layer uses `defineModel` or `useControllable`
68
+ (`runtime/useControllable.ts`).
69
+ - **Anything that opens has `v-model:open`** (Modal, Drawer, Popover, DropdownMenu, Select…), so a caller can open it
70
+ from code or just let it manage itself.
71
+ - A value input's `modelValue` (Input, Select, Checkbox, Switch…) is the one exception: pure-controlled, no value of
72
+ its own.
73
+ - `v-model` types follow the mode (`multiple` gives an array), so call sites typecheck without casts.
74
+
75
+ ## Contracts that repeat
76
+
77
+ - **Empty state:** `empty` is the title text everywhere, defaulting to "No {plural noun}". Every list has an
78
+ `#empty` slot (slot props `{ searchTerm }` on Select, `{ lane }` on Board, nothing elsewhere). An empty *value*
79
+ in a cell or description prints `fallback` (the em dash by default).
80
+ - **Refusals are "a reason string, or nothing":** a string means "refused, and here is why" (shown to the user);
81
+ `null`/`undefined`/`false` means allowed.
82
+ - **Predicates are named for the negative, `…Disabled`, like the `disabled` prop** (owner, 1.0): they return `true`
83
+ or a reason string to refuse. DataTable `selectDisabled(row)`, column `disabled(row)`, Board `cardDisabled(card)`,
84
+ `moveDisabled(move)`, lane `disabled`. Never `selectable`/`canMove`/`enabled`. `locked` is only Modal and Drawer:
85
+ can't be dismissed.
86
+ - **A function that runs when something is missing is `on…`**, never `fallback` (`fallback` is always text):
87
+ `defineSearchShortcut({ onNoSearchField })`.
88
+ - **`show<Thing>` adds a control.** A prop that only moves where a control appears says so: PageHeader
89
+ `menuOnDesktop`.
90
+ - **Choice items** take `labelKey` / `valueKey` (Select, RadioGroup, SegmentedControl, Tabs, Input suggestions,
91
+ `useRemoteOptions`); `valueKey` defaults to `"value"`.
92
+ - **Menu items** share one `MenuItem` shape: `label`, `icon`, `to`, `target`, `onSelect(event)`, `kbd`, `disabled`,
93
+ `class`. DropdownMenu, Sidebar, TopBar and CommandPalette extend it (CommandPalette identifies an item by `id`).
94
+ - **Looks:** `ghost` is no box and no rule (Card, Stat); `ruled` is Card's ruled band; `elevated` a raised card;
95
+ `divided` puts rules between parts.
96
+
97
+ - **Never show one thing and save another.** A field whose typed text isn't a valid value (a date, a time, a number)
98
+ reverts to the saved value on blur or Enter and briefly shows the invalid border. It never keeps the text on
99
+ screen while the model holds something else, and never drops the input silently.
100
+
101
+ ## What belongs in the layer
102
+
103
+ - **One look across apps.** When one app does something differently from all the others (a floating label, its
104
+ own field style), redesign that app to match the rest rather than add an option to keep the oddity.
105
+ - **No shallow wrappers around a library an app already uses well** (a chart library, say). A layer component earns
106
+ its place through shared behaviour and a shared look, not by renaming another library's props.
107
+
108
+ ## `pt` sections and slots
109
+
110
+ - `class` is always `pt.root`. An overlay's `root` is its panel; its backdrop is `overlay`.
111
+ - Inside a list, an item's parts are `item`, `itemLabel`, `itemDescription`, `itemIcon`; a group heading is
112
+ `groupLabel`.
113
+ - `icon` is only the component's own leading icon; other icons are named for their job (`toggleIcon`, `zoneIcon`,
114
+ `checkIcon`).
115
+ - A field's popup is `panel`; Tabs' panels are `tabPanel`; a title-plus-description block is `text`; an inner
116
+ wrapper is `inner`; `content` is only Card's slot area.
117
+ - **Slots are kebab-case, sections camelCase:** `#item-label` fills `pt.itemLabel`, `#trailing-icon` fills
118
+ `pt.trailingIcon`.
119
+ - A section per enum value only where values differ in colour (`neutral-soft`, `primary-solid`). Never a section
120
+ per size.
121
+
122
+ ## Cross-cutting requirements
123
+
124
+ - **Time zones:** anything that formats or picks a date-time takes a `timeZone`, defaulting to `gallopUi.timeZone`.
125
+ Date-only strings are never shifted. The server and the browser print the same text. Date tests run under
126
+ `TZ=UTC` and `TZ=America/New_York`.
127
+ - **Dark mode** is designed and checked for every component; colours come only from tokens.
128
+ - **Phones:** tables render as cards below `md` by default, derived from the columns, with every feature still
129
+ working (sort, select, row links, paging, actions). An old phone table becoming cards is an improvement, not a
130
+ regression; don't use `layout="table"` to keep one. Field text is 16px below `md` (iOS zooms into smaller
131
+ fields); desktop sizes are unchanged.
132
+ - **Use existing libraries first:** VueUse (`useRouteQuery` from `@vueuse/router`, `useEventListener`,
133
+ `refAutoReset`…), Reka UI for focus, keyboard and ARIA, and the template's dependencies. A new layer dependency
134
+ means every app adds it, so ask first. If an app-level library is missing, add it to the template rather than
135
+ re-implementing it.
136
+ - **Client-neutral:** no client names, data or domain terms in the layer. Examples use orders, projects, people.
137
+ - **Same or better, never a regression,** in look, behaviour and speed. Inventory every behaviour before replacing
138
+ something, and measure old against new.
139
+ - **Performance through measured docs, not strict thresholds.** About 200ms for an interaction on a throttled phone
140
+ is acceptable when the component's `.md` has a measured "Performance" section (what is slow at what size, what to
141
+ do). Take cheap, safe wins; flag anything several times slower than before.
142
+ - **Escape hatches are labelled:** DataTable's TanStack `table` is exposed but unstable, with no semver guarantee;
143
+ use the stable helpers (selected rows, toggle-all) instead.
144
+
145
+ ## The bar for an API change
146
+
147
+ - **Naming and API calls go to the owner.** Implementation, tests and internal structure are yours. Present a
148
+ naming call with the options, the trade-offs, and your recommendation tied to the principles above. Don't just
149
+ agree with whichever option was mentioned last. Check `docs/decisions.md` first and don't reopen a settled call
150
+ without new evidence.
151
+ - **Backward compatible by default:** a new prop or option must leave every existing call site rendering exactly as
152
+ before. A look that changes without the caller touching `pt` is a breaking change.
153
+ - **Breaking changes after 1.0** need a major release, a `CHANGELOG.md` note, and a row per change in
154
+ `migrations/<version>/<area>.json` with a `codemod` the kit can apply (`rename`, `invert-to`, `wrap-array`…) or
155
+ `manual` with a `locate` and a note. `yarn ui:migrate` then rewrites apps and writes the checklist. Before 1.0,
156
+ breaking changes landed in minor versions; that grace is over.
157
+ - Batch breaking renames into one release with one codemod rather than trickling them out.
@@ -0,0 +1,102 @@
1
+ # Changing the layer
2
+
3
+ Fixes and features for the layer are made **in the gallop-ui repo** (`gallop-systems/gallop-ui`), not in an app's
4
+ `layers/gallop-ui`. Apps then take the change with `yarn ui:pull` once it is released. A change here reaches every
5
+ app, so the bar is higher than for app code: backward compatible, documented, tested, and checked in every app.
6
+
7
+ The layer's `CLAUDE.md` is the authority on its rules. Read it, `docs/decisions.md` (settled names) and
8
+ `docs/review-queue.md` (open questions) before you start.
9
+
10
+ ## 1. Worktree
11
+
12
+ ```sh
13
+ git -C ~/Projects/gallop-ui fetch origin
14
+ git -C ~/Projects/gallop-ui worktree add ~/Projects/gallop-ui-<topic> -b <type>/<topic> origin/main
15
+ cd ~/Projects/gallop-ui-<topic> && yarn install
16
+ export PATH=$HOME/.nvm/versions/node/v24.11.1/bin:$PATH # Node 24, as in CI (or `nvm use 24`)
17
+ ```
18
+
19
+ (The layer's README also describes editing `layers/gallop-ui` in an app and sending it back with `yarn ui:push`.
20
+ Don't use that route unless the owner asks for it. If you do, the layer change is a commit of its own with no app
21
+ files, and `ui:check --staged` enforces that.)
22
+
23
+ ## 2. Build it
24
+
25
+ - **API first.** Sketch names, props, slots, events and v-model against [api-principles.md](api-principles.md), and
26
+ inventory how the apps would call it (`git -C ~/Projects/<app> grep -n "<pattern>" origin/main -- app`). Take any
27
+ non-obvious name to the owner before building on it.
28
+ - **Four files per component** in `components/<Name>/`, kept in step in the same change:
29
+ - `<Name>.vue`: `usePt` for every section a caller might restyle, `inheritAttrs: false`, `class` merged last,
30
+ state classes chosen in script (never `data-[x]:` defaults, never `!`), `size: () => appDefault("<Name>",
31
+ "size", "md")`;
32
+ - `<Name>.md`: frontmatter (`name`, `tier`, `summary`, `use-for`, `related`, optional `replaces`, `built-on`),
33
+ then When to use, When not to use, Functionality, Props, Slots, Events, Expose, Customizing, Examples,
34
+ (Performance), Migrating, Accessibility. Every prop, slot and event has a row;
35
+ - `<Name>.stories.ts`: the `/_ui` controls and named examples (format in `runtime/stories.ts`). A new behaviour
36
+ gets a story;
37
+ - `<Name>.test.ts`: behaviour tests (Vitest and @vue/test-utils).
38
+ - A new component with a `pt` goes into `GallopUiPt` in `types.ts`; a sized one into `GallopUiDefaults`.
39
+ - Colours only from tokens. A new token goes in `TOKENS.md`, `theme/neutral.css`, `runtime/tokens.ts` and the
40
+ migration table, and needs a copier-template PR adding it to `template/app/assets/css/main.css`.
41
+ - Tailwind classes live under `components/` (apps scan only that folder). Shared class-holding code goes in
42
+ `components/_<name>/`. Behaviour goes in `runtime/`; only public composables go in `composables/`.
43
+ - Allowed imports: `vue`, `reka-ui`, `@vueuse/core`, `@internationalized/date`, `@tanstack/vue-table` (DataTable),
44
+ `pluralize`, `<Icon>`, and `twMerge` from `runtime/merge.ts` (never `tailwind-merge` directly). Anything new is a
45
+ peer dependency every app must add: ask first.
46
+ - Client-neutral everywhere: generic examples (orders, projects, people), in code, docs, tests, commit messages and
47
+ the PR.
48
+
49
+ ## 3. Tests
50
+
51
+ ```sh
52
+ yarn test:run # Vitest: components in plain Vue with small Nuxt stand-ins
53
+ yarn typecheck # extends the layer from playground/ and runs nuxi typecheck, as an app's vue-tsc would
54
+ yarn catalogue # regenerate CATALOGUE.md from the frontmatter (CI runs `yarn catalogue --check`)
55
+ yarn docs:check # doc sections and order, rows for every slot/event, real `related:` names, client-name check
56
+ yarn tokens:check # if you touched tokens
57
+ ```
58
+
59
+ - **No live clock in tests.** Pin time with `vi.useFakeTimers()` / `vi.setSystemTime()`, and pass `timeZone`
60
+ explicitly. A test that depends on today's date or the machine's zone will fail on someone else's machine.
61
+ - Run date-related tests under `TZ=UTC` and `TZ=America/New_York`.
62
+ - Use Node 24 locally. Older Node's ICU formats currency differently, and CI runs 24.
63
+ - `tests/classWins.test.ts`, `tests/tokens.test.ts` and `tests/catalogue.test.ts` enforce the state-class, token and
64
+ four-file rules. Fix the code, not the test.
65
+
66
+ ## 4. Look at it
67
+
68
+ - **`/_ui` in a real app:** make a throwaway, detached worktree of an app (never its real branch), copy your layer
69
+ over its subtree, and run it on your own port:
70
+ ```sh
71
+ git -C ~/Projects/<app> worktree add --detach <scratch>/<app>-preview origin/main
72
+ rsync -a --delete --exclude node_modules --exclude .git --exclude .yarn ~/Projects/gallop-ui-<topic>/ <scratch>/<app>-preview/layers/gallop-ui/
73
+ cd <scratch>/<app>-preview && yarn install && yarn dev --port <your port>
74
+ ```
75
+ Open `/_ui/<Name>`: every story, **light and dark, at 1280 and at 390** (`?theme=dark&width=390`). Never commit
76
+ or push from that worktree. Remove it when done.
77
+ - **Every app:** `node scripts/impact.mjs` from your gallop-ui worktree compares against `origin/main` in every app
78
+ on the machine: call sites, new type errors, and before/after screenshots of every affected story. Every changed
79
+ screenshot must be one you meant. See [checking-other-apps.md](checking-other-apps.md).
80
+
81
+ ## 5. Commit, PR, merge
82
+
83
+ - **Conventional Commits**, because release-please cuts versions from them: `feat(<Name>): …` for a new component
84
+ or option, `fix(<Name>): …`, `docs: …`, `perf(<Name>): …`. A breaking change is `feat(<Name>)!: …` with a
85
+ `BREAKING CHANGE:` footer, a `CHANGELOG`-ready description, and a `migrations/<version>/` row. Commits end with
86
+ the `Co-Authored-By` trailer you were given.
87
+ - The PR body: what changed and why, the apps you checked with `impact.mjs` and what changed in each, and any naming
88
+ call the owner still has to make. End it with the Claude Code line you were given.
89
+ - Record a decision the owner made in `docs/decisions.md`. Add an open question to `docs/review-queue.md`, and delete
90
+ an item there when it is done.
91
+ - **Layer PRs are squash-merged**, with the PR title as the Conventional Commit. A merge commit hides the change
92
+ from release-please.
93
+ - Merge only when checks are green **and** `gh pr view <n> --json mergeStateStatus` says `CLEAN`, and only if you
94
+ were asked or delegated to. Never `--admin`.
95
+
96
+ ## 6. Releases
97
+
98
+ - release-please opens or updates a release PR (`chore(main): release X.Y.Z`) after each merge. **Release PRs don't
99
+ trigger CI** (they are pushed with the workflow token). Close and reopen the PR to start the required checks;
100
+ repeat if needed until it is CLEAN, then squash-merge it. That creates the `vX.Y.Z` tag that `ui:pull` takes.
101
+ - Never bump `package.json` or tag by hand. To force a version, put `Release-As: X.Y.Z` in a commit body on main.
102
+ - After the release, roll it into apps one at a time ([pulling-updates.md](pulling-updates.md)).