@canonical/pragma-cli 0.35.0 → 0.36.0

package/bundled-skills/adoption-a2-components/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: adoption-a2-components
+description: Swap an application's UI to Canonical design-system components one component type per PR (adoption track A2); also runs as a guided tutorial on a worked example
+---
+
+# Adoption A2 — Components
+
+The second adoption track: replace the app's existing UI elements with design-system
+components. Prerequisite: track A1 is done — styles, fonts, and icons are live, so
+swapped components land on the right foundation. That includes the root context and
+density classes (`class="app comfortable"` — A1's "Declare the surface" section):
+component geometry reads the `--density-*` channel those classes emit, and a swap onto
+a class-less root looks subtly wrong rather than broken.
+
+## When to Use
+
+- Track A1 is done and the app's UI elements should become design-system components
+- Planning or executing a component swap PR
+
+## When NOT to Use
+
+- The visual foundation is not in place — run `adoption-a1-styles` first
+- Migrating forms — a different programming model: `adoption-a3-forms`
+
+(An uncovered component TYPE is not a reason to skip the track — it is a per-type
+finding: see "The covered set is queried live" below.)
+
+## Opening move: ask, or offer the tutorial
+
+Activation is an opening, not a starting gun. Unless the first message already names
+the work, ask for the starting point — as a suggestion carrying an example, not as a
+form to fill in:
+
+> To get started, point me at the app and say which component type you'd like swapped
+> first — buttons, say — or let me inventory the app and suggest one.
+
+The inventory is cheap, so no preference is a fine answer. Ask again only for what the
+next step genuinely blocks on.
+
+If the activation message already carries the starting point, do not re-ask — say what
+you took it to be, and go.
+
+Offer the tutorial in the same breath, because this track doubles as one:
+
+> Or if you'd rather see what a swap looks like before touching your app, I can run it
+> as a tutorial: I'll take a plausible example — buttons in a small React app — and
+> walk you through one type from inventory to a finished PR.
+
+Tutorial mode is the step narration below, turned up: the same outcome-path-conclusion
+frame, with the reasoning behind each change made explicit. It runs on a scratch
+example, not on the person's app — nothing in their repo changes unless they ask.
+
+## Every step is narrated: outcome, path, conclusion
+
+Every step is addressed to the person — once before it runs, once when it ends. This is
+not tutorial manner. It holds in the ordinary flow too: the person is the design
+authority, and they can only steer a step they saw coming. A decision gate met cold is
+a decision they cannot really make.
+
+**Open** the step with what it is FOR — the outcome it should leave behind — and how
+you are about to get there. **Close** it with a sentence saying what it established and
+what that means for the step after. One sentence each is enough; the failure mode is
+silence, not length, and a step whose outcome looks obvious still gets its sentence
+rather than a shrug.
+
+Do:
+
+> **Inventory first.** The outcome is a real count of what the app uses, per component
+> type, so the first swap PR is chosen from evidence rather than instinct. The path is
+> the greps below over `src/`, deduped with counts.
+>
+> …
+>
+> So: 43 button call sites against 6 cards — buttons are the widest swap and the
+> obvious first PR, and two of those call sites use a variant the system has no
+> modifier for, which is a finding to report rather than a blocker.
+
+Don't:
+
+> Inventory: 43 buttons, 6 cards, 3 tooltips.
+
+Both carry the same facts. Only the first says what the step was trying to achieve and
+what it settled — and only the first lets the person cut in with the thing they know
+and the graph does not, which is the whole reason they are here.
+
+## Asked about the skill: methodology and outcomes first
+
+A question about what this skill does — what it covers, what its steps are, how it
+works — is answered in that order: the METHOD it applies and the OUTCOMES it leaves
+the person holding come first, the step-by-step breakdown comes after.
+
+Two or three sentences of method is enough: what the skill treats as its object, the
+discipline that makes it work, and what exists at the end that did not exist before.
+The enumeration then reads as steps in service of something, rather than as a list to
+be got through.
+
+What this prevents is a table of contents standing in for an answer. A reply opening
+with the step names tells someone who already knows the skill nothing new, and someone
+who does not, nothing at all.
+
+So, asked what this skill is:
+
+> It replaces the app's UI elements with design-system components, one component type
+> per PR, with the order chosen from a real inventory rather than instinct. You end
+> with each swapped type sitting on A1's foundation, accessibility warnings treated as
+> contract, and any type the system does not cover reported as a finding rather than
+> treated as a blocker.
+
+Then, and only then, the breakdown.
+
+## Install
+
+```bash
+bun add @canonical/react-ds-global
+```
+
+That is the universal (global) tier package. App-tier siblings, where they exist,
+follow a naming convention — the mapping is convention, not a graph field:
+`@canonical/<framework>-ds-global` for the `global` tier, `-ds-app` for the shared
+`apps` tier, and `-ds-app-<app>` for an app-specific tier (so the `apps_lxd` tier
+installs `@canonical/react-ds-app-lxd`). The `<app>` segment is the package's own
+short name, not always the tier suffix (the `apps_workplaceengineering` tier's
+package is `@canonical/svelte-ds-app-wpe`) — `pragma tier list` shows which tiers
+exist, and the derived package name must resolve before you install it. Tiers
+outside `global`/`apps*` have no package convention today: there the target package
+is a decision to raise, not to derive.
+
+```tsx
+import { Button, Badge, Card, Tooltip } from "@canonical/react-ds-global";
+```
+
+Named imports; components accept the underlying element's native HTML attributes, so
+existing `onClick`/`aria-*`/`data-*` plumbing carries over.
+
+## Code standards are the gate
+
+Every swap writes component code, and that code falls under the live code standards —
+the target framework's category (`react`, `svelte`, `lit`), plus `testing` and
+`storybook` where the swap touches those (take the actual set from the live output,
+not from this list). Pull them BEFORE the first swap of a PR and hold the Do/Don't
+pairs open while writing:
+
+```bash
+pragma standard categories                 # the live category set — never from memory
+pragma standard list --category react      # swap react for the target framework
+pragma standard lookup <name> --detail detailed
+```
+
+Apps follow the code standards as closely as the swap allows. Where swapped code has
+to deviate from a pulled standard, record the deviation in the PR next to the
+standard's name — "the old code did it this way" is a deviation to record, not a
+reason to stay silent — and ideally file it as an issue, either to bring the app into
+line later or to propose a change to the standard itself. The standards apply even
+when the app has no pragma dependency, and they are open to contribution: a missing
+or wrong standard is something to propose a change for, not to silently work around.
+
+## Inventory first (grep, don't guess)
+
+Build the swap list from the code, not from memory:
+
+```bash
+grep -rhoE '\bp-[a-z0-9-]+' src/ | sort | uniq -c | sort -rn   # Vanilla class inventory, deduped with counts
+grep -rn 'from "@canonical/react-components"' src/             # or your current component library's import
+```
+
+Group the hits by component TYPE — all buttons, all cards, all tooltips — because the
+type is the unit of work below. When you get to one type, locate its call sites with an
+anchored grep:
+
+```bash
+grep -rnE '\bp-button\b' src/   # swap p-button for the type at hand
+```
+
+Anchor on the class TOKEN, not on the attribute — a `class(Name)?="…"` pattern
+under-collects, missing template-literal (`` className={`p-button …`} ``), `clsx(…)`,
+and single-quoted call sites.
+
+## The covered set is queried live
+
+Before swapping a type, confirm the design system covers it TODAY:
+
+```bash
+pragma block list            # what exists, with tiers
+pragma block lookup <Name>   # anatomy, modifiers, properties (MCP: block_lookup)
+```
+
+A bare name can match blocks in several tiers, and `block lookup` silently picks
+one — it resolves `ds:name` globally and cannot be steered to a tier.
+Confirm the tier the lookup picked from its own `- Tier:` line; the name query below lists every tier that carries the name.
+The name query
+`pragma graph query "SELECT ?b WHERE { ?b ds:name ?n . FILTER(LCASE(?n) = LCASE('<Name>')) }"`
+prints every tier's IRI for `pragma graph inspect <IRI>`. If the lookup picked the wrong
+tier's block, read the one you want with `pragma graph inspect <IRI from that row>`
+instead.
+
+**A block being in the graph does not mean the package exports it.** The graph
+records what the design system has DOCUMENTED; the package ships what has been
+BUILT, and the two run ahead of each other in both directions. So before you
+swap a type, confirm the named export in the package you installed:
+
+```bash
+node -e "console.log(Object.keys(require('@canonical/react-ds-global')))" | tr ',' '\n' | grep -i '<Name>'
+```
+
+If the export is absent, the block is documented but not available — file the
+gap and leave the existing markup in place. Do not infer availability from a
+Storybook story either: a story can exist for a block that ships no
+implementation and no export, so a story CORROBORATES an export you have
+already confirmed, and never substitutes for it.
+
+If the name has no row and the lookup errors, the block may be a Group — `block list`/`block lookup` cover no groups; the name query above returns its IRI for `pragma graph inspect <IRI>`.
+Run it before calling a type uncovered: `Cards` and `KeyboardKeys` are groups, and both
+ship from the `@canonical/react-ds-global` this track installs. The export check above
+applies to them exactly as it does to any other block.
+
+Then check the component in a running Storybook — your app's own (track A1 set it up
+via `@canonical/storybook-config`), your team's hosted hub, or `bun run storybook`
+inside the component's package in the pragma monorepo (e.g. `packages/react/ds-global`
+— the monorepo root has no such script).
+
+> The covered set is whatever the graph answers today. Query it live — never copy its
+> output into documentation, PRs, or this skill.
+
+A gap found is a FINDING to report (and a `specify-component` candidate) — skip that
+type and keep swapping the types the system does cover; never hand-roll a lookalike
+silently.
+
+## One component type per PR
+
+The swap unit is a component TYPE across the app — all buttons in one PR — not a page.
+
+- Diffs stay reviewable: one decision, applied everywhere.
+- Accessibility regressions stay attributable to the one swap that caused them.
+- One PR reverts one decision, cleanly.
+
+## Names and boundaries changed vs Vanilla
+
+Do NOT assume a 1:1 mapping from Vanilla names and `p-*` classes. Boundaries moved:
+what was one blob may now be a component plus subcomponents (e.g. `Accordion` with
+`Accordion.Item`), and icon semantics changed to `currentColor`. The block's `ds:usage`
+When-to-use / When-not-to-use guidance decides what replaces what — read it with
+`pragma graph inspect <block IRI>` (the IRI from the block's `pragma block list` row;
+`block lookup` does not render the usage field today) — often the honest swap is a
+DIFFERENT component than the old name suggests.
+
+## Accessibility warnings are contract
+
+The components warn in dev mode when misused — for example, an icon-only `Button`
+without `aria-label`/`aria-labelledby` logs a console warning, and icons are
+decorative/aria-hidden unless labelled. Treat every such warning as a FAILED acceptance
+criterion of the swap PR: fix the usage, never silence the warning.
+
+Modifier props (e.g. `anticipation="constructive"` on `Button`) take their values from
+modifier families — read them live, list first:
+
+```bash
+pragma modifier list             # every family with its values
+pragma modifier lookup <Family>  # one family in full — take the name from the list output
+```
+
+The families a block draws from print as the last column of its `pragma block list`
+row, and in full on the block itself via `pragma graph inspect <IRI from that row>`
+(the `ds:hasModifierFamily` triples). Mapping a family to code follows two rules: the
+React prop IS the family name lowercased (`Anticipation` → `anticipation`), and the
+prop's values are the family's values lowercased with spaces as underscores
+(`In Progress` → `in_progress`) — the lookups print display casing; the code takes
+the lowercase form. A family listed on the block may have no prop on the component
+yet — check the component's types before writing it.
+
+## Verify per PR
+
+- [ ] Root context and density classes present (track A1) — swapped components size
+      from the `--density-*` channel, not from luck.
+- [ ] Zero dev-console warnings from the swapped components.
+- [ ] Keyboard pass on each swapped instance (focus, activation, escape where relevant).
+- [ ] Visual pass against the component's Storybook stories.
+
+## Next
+
+Forms are their own programming model — continue with `adoption-a3-forms`.
+
+## Support
+
+If this skill leads somewhere broken — a command that errors, guidance that
+contradicts what the live system answers, a gap the flow cannot cover — you are not
+stuck:
+
+- Raise an issue in the pragma repo: https://github.com/canonical/pragma/issues —
+  include the skill name, what was run, and expected vs. actual outcome.
+- Or contact the design-system team owners directly through your organization's
+  professional messaging channels for assistance.

package/bundled-skills/adoption-a3-forms/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: adoption-a3-forms
+description: Migrate application forms to the Canonical form system built on react-hook-form (adoption track A3); also runs as a guided tutorial on a worked example
+---
+
+# Adoption A3 — Forms
+
+The third adoption track: move the app's forms onto the design-system form package.
+Prerequisite: track A1 (A2 recommended). Understand what this track is before starting:
+the form system is a DIFFERENT PROGRAMMING MODEL built on react-hook-form, not a restyle
+of your existing inputs.
+
+## When to Use
+
+- Track A1 is done and the app's forms should move onto the design-system form package
+- A form is being built or rewritten and should use the `Form`/`Field` model from the
+  start
+- A form contains an input type the system does not cover — the `custom` escape hatch
+  below keeps it inside the `Form` (and the gap is a finding to report)
+
+## When NOT to Use
+
+- The visual foundation is not in place yet — run `adoption-a1-styles` first
+- Swapping non-form components — that is `adoption-a2-components`
+
+## Opening move: ask, or offer the tutorial
+
+Activation is an opening, not a starting gun. Unless the first message already names
+the work, ask for the starting point — as a suggestion carrying an example, not as a
+form to fill in:
+
+> To get started, point me at the app and say which form you'd like moved first — or
+> let me find the forms and suggest a starting one.
+
+The smallest real form is usually the best first move: the programming-model switch is
+easier to see on a short one. Ask again only for what the next step genuinely blocks
+on.
+
+If the activation message already carries the starting point, do not re-ask — say what
+you took it to be, and go.
+
+Offer the tutorial in the same breath, because this track doubles as one:
+
+> Or if you'd rather see the model before touching your forms, I can run it as a
+> tutorial: I'll take a plausible example — a couple of text fields and a select — and
+> walk you through the migration on it.
+
+Tutorial mode is the step narration below, turned up: the same outcome-path-conclusion
+frame, with the reasoning behind each change made explicit. It runs on a scratch
+example, not on the person's app — nothing in their repo changes unless they ask.
+
+## Every step is narrated: outcome, path, conclusion
+
+Every step is addressed to the person — once before it runs, once when it ends. This is
+not tutorial manner. It holds in the ordinary flow too: the person is the design
+authority, and they can only steer a step they saw coming. A decision gate met cold is
+a decision they cannot really make.
+
+**Open** the step with what it is FOR — the outcome it should leave behind — and how
+you are about to get there. **Close** it with a sentence saying what it established and
+what that means for the step after. One sentence each is enough; the failure mode is
+silence, not length, and a step whose outcome looks obvious still gets its sentence
+rather than a shrug.
+
+Do:
+
+> **The first field conversion.** The outcome is one field moved onto the `Form`/`Field`
+> model, proving the wiring end to end before the rest follow. The path is to replace
+> the input with a `<Field>` and let `Form` own the state `useState` was holding.
+>
+> …
+>
+> So: the field validates and submits through react-hook-form and the local `useState`
+> is gone — every remaining field is the same move, except the file upload, which needs
+> the `custom` escape hatch.
+
+Don't:
+
+> Converted the email field. Works.
+
+Both carry the same facts. Only the first says what the step was trying to achieve and
+what it settled — and only the first lets the person cut in with the thing they know
+and the graph does not, which is the whole reason they are here.
+
+## Asked about the skill: methodology and outcomes first
+
+A question about what this skill does — what it covers, what its steps are, how it
+works — is answered in that order: the METHOD it applies and the OUTCOMES it leaves
+the person holding come first, the step-by-step breakdown comes after.
+
+Two or three sentences of method is enough: what the skill treats as its object, the
+discipline that makes it work, and what exists at the end that did not exist before.
+The enumeration then reads as steps in service of something, rather than as a list to
+be got through.
+
+What this prevents is a table of contents standing in for an answer. A reply opening
+with the step names tells someone who already knows the skill nothing new, and someone
+who does not, nothing at all.
+
+So, asked what this skill is:
+
+> It moves forms onto the design-system form package, and the thing to understand
+> before starting is that this is a DIFFERENT PROGRAMMING MODEL built on
+> react-hook-form — fields as data, `Form` owning the state — not a restyle of the
+> existing inputs. You end with forms on the `Form`/`Field` model, and anything the
+> system does not cover kept inside the `Form` through the `custom` escape hatch.
+
+Then, and only then, the breakdown.
+
+## Install + the forms styles import
+
+```bash
+bun add @canonical/react-ds-global-form @canonical/styles
+```
+
+Then BOTH stylesheets in the root stylesheet:
+
+```css
+@import url("@canonical/styles");
+@import url("@canonical/react-ds-global-form/dist/esm/index.css");
+```
+
+The first brings the global reset and tokens; the second the input chrome and field
+layout. The package builds on top of `@canonical/react-ds-global`.
+
+Forms are the heaviest consumer of the density system: control heights, field spacing,
+and baseline seating all read the `--density-*` channel, which only emits real values
+when the app root carries its context and density classes
+(`class="app comfortable"` — track A1's "Declare the surface" section). Confirm those
+classes before judging any form layout: without them the primitives silently fall back
+to app-comfortable values, and a `dense` or site-surface form renders with the wrong
+geometry.
+
+## Code standards are the gate
+
+Form migration is component code, and it falls under the live code standards — the
+`react` category at minimum, plus `testing` where the migration touches tests (take
+the actual set from the live output, not from this list). Pull them BEFORE the first
+field conversion and hold the Do/Don't pairs open while writing:
+
+```bash
+pragma standard categories                 # the live category set — never from memory
+pragma standard list --category react
+pragma standard lookup <name> --detail detailed
+```
+
+Apps follow the code standards as closely as the migration allows. Where a
+conversion has to deviate from a pulled standard, record the deviation in the PR next
+to the standard's name — and ideally file it as an issue, either to bring the app
+into line later or to propose a change to the standard itself. The standards apply
+even when the app has no pragma dependency, and they are open to contribution: a
+missing or wrong standard is something to propose a change for, not to silently work
+around.
+
+## The react-hook-form switch
+
+Form state moves INTO the form system:
+
+- `<Form onSubmit={…}>` wraps a react-hook-form `FormProvider`. Pass your own `useForm`
+  return via the `methods` prop when you need external control; otherwise `defaultValues`
+  and `mode` are enough and the Form calls `useForm` internally.
+- `Field` reads the form context via `useFormContext` — **a `Field` outside a `Form` is
+  a bug**, not a styling choice.
+- Migrating a form means DELETING its `useState`/`onChange` handler plumbing, not
+  wrapping it. If the old state code survives the migration, the migration is not done.
+
+## Fields as data
+
+Each field is a declaration, not an assembly of label + input + error markup:
+
+```tsx
+<Form onSubmit={handleSubmit}>
+  <Field name="email" inputType="email" label="Email address" description="Work address preferred" />
+</Form>
+```
+
+`inputType` is a discriminated union selecting the input subcomponent — text, textarea,
+select, checkbox, radio-style choices, date/time, phone, combobox, and more — and the
+label, description, and error wiring come with the frame.
+
+> The covered set is whatever the graph answers today. Query it live — never copy its
+> output into documentation, PRs, or this skill.
+
+Enumerate the input types that exist TODAY from the package's `Field` types and its
+Storybook stories — not from this skill.
+
+## The custom escape hatch
+
+A one-off input stays INSIDE the system:
+
+```tsx
+<Field name="tags" inputType="custom" CustomComponent={TagPicker} label="Tags" />
+```
+
+`CustomComponent` is a `React.ComponentType<InputProps>`: it keeps react-hook-form
+registration, the label/description/error framing, and validation. The escape hatch is
+for the INPUT, never for leaving the `Form`.
+
+## WIP-stage warnings
+
+Input maturity is graph data, not folklore. Before building on an input type, read its
+documentation stage — the stage lives on the block's graph entity:
+
+```bash
+pragma block list                 # find the input's row — it carries the block's IRI
+pragma graph inspect <block IRI>  # every triple, including ds:documentationStage
+```
+
+Look the row up under the PACKAGE COMPONENT's name, not the `inputType` token — the
+union maps several tokens onto one component (`"text"`, `"email"`, `"tel"` and `"url"`
+all render `TextField`/`TextInput`; `"file"` renders `FileUploadField`; `"choices"`
+renders `ChoicesField`). Read the component a token selects from the package's `Field`
+types above, then find THAT name's row.
+
+An input name can be declared at more than one tier, so the list can carry a row per
+tier — names resolve globally, not within one tier. To list every tier that declares
+the name, the name query
+`pragma graph query "SELECT ?b WHERE { ?b ds:name ?n . FILTER(LCASE(?n) = LCASE('<Name>')) }"`
+prints every tier's IRI. Inspect the one whose tier matches the package you
+installed — `global` for `@canonical/react-ds-global-form`'s inputs; the stage
+below is per-block, so another tier's row answers about a different block.
+
+Read whatever `ds:documentationStage` tag comes back — the tag vocabulary is the
+graph's, not this skill's, so do not expect a fixed value list; if the predicate is
+absent, no stage is recorded for that block. The tag's MEANING is graph data too —
+inspect the tag entity itself:
+
+```bash
+pragma graph inspect ds:tag.<name>   # the tag the stage read returned; ds:whenToApply says what it means
+```
+
+Split the action on what `ds:whenToApply` says. A tag meaning the block was rejected
+or triaged out, or that it is only PROPOSED or postponed — not yet accepted into the
+system: do NOT build on that input — raise it as a gap (the `custom` escape hatch
+covers the form meanwhile). A tag meaning the documentation is unfinished: the block
+may change under you — SAY SO in the migration PR rather than discovering it in
+production. A tag whose `ds:whenToApply` comes back blank: the stage's meaning is
+unrecorded — treat it as unknown, and say so in the PR.
+
+Debug aid: `@canonical/storybook-addon-form-state` adds a Storybook panel showing the
+live react-hook-form state while you exercise a story.
+
+## Verify
+
+- [ ] Root context and density classes present (track A1) — field spacing and control
+      seating read the `--density-*` channel.
+- [ ] Submit round-trip works, with validation errors surfaced per field.
+- [ ] The whole form is completable keyboard-only.
+- [ ] Zero dev-console warnings from the form components.
+
+## Support
+
+If this skill leads somewhere broken — a command that errors, guidance that
+contradicts what the live system answers, a gap the flow cannot cover — you are not
+stuck:
+
+- Raise an issue in the pragma repo: https://github.com/canonical/pragma/issues —
+  include the skill name, what was run, and expected vs. actual outcome.
+- Or contact the design-system team owners directly through your organization's
+  professional messaging channels for assistance.