@canonical/pragma-cli 0.36.0 → 0.38.0

package/README.md

@@ -4,7 +4,8 @@
 
 | You want to… | Run |
 |---|---|
-| See every block in the design system | `pragma block list` — all 251, each with its tier |
+| See the blocks you build with | `pragma block list` — the top-level tiers, each row with its tier |
+| See a product tier's blocks, and the global ones under them | `pragma block list --tier apps_lxd` (`--tier all` for every tier) |
 | Read a block's full spec — anatomy, modifiers, properties | `pragma block lookup Button` |
 | Find the design system's name for something you already know | `pragma block lookup 'Nav*'` — lookups take names or globs |
 | Know which tier something belongs to | `pragma tier list`, `pragma tier lookup <name>` |
@@ -85,7 +86,7 @@ What this distribution's graph answers today:
 
 | Ask | Answer |
 |---|---|
-| `pragma block list` | **251** blocks — components, patterns, layouts, and subcomponents, each with its tier |
+| `pragma block list` | **173** blocks — components, patterns, layouts and subcomponents of the five top-level tiers, each row with its tier. **252** with `--tier all`: the other 79 sit in the ten product tiers below, and `--tier apps_lxd` adds one of those to the global blocks it builds on |
 | `pragma tier list` | **15** tiers — `global`, `apps` plus nine app tiers, `sites` plus one, `stores`, `documentation` |
 | `pragma modifier list` | **11** modifier families — Importance (Primary/Secondary/Tertiary), Anticipation (Caution/Constructive/Destructive), Criticality, Density, Lifecycle, Mode, Release, Surface, and three more |
 | `pragma standard categories` | **21** code-standard categories — react 16, css 15, lit 13, svelte 12, rust 11, storybook 11, code 10, … |

package/bundled-skills/adoption-a1-styles/SKILL.md

@@ -119,6 +119,30 @@ tokens. Two things come with it:
   fight specificity.
 - `color-scheme: light dark` on `:root` — the foundation is theme-aware out of the box.
 
+## Which variable to write
+
+The foundation's tokens arrive as CSS custom properties, and which one to write is a
+query rather than a guess:
+
+```bash
+pragma variable list --search background     # the variables around a word, with the symbol each stands for
+pragma variable lookup color-background      # one variable in full
+```
+
+`variable list` prints one row per variable — its name, the symbol it stands for, its
+tier, its visibility, its platform — and pages at `--limit` (the footer says when more
+exist). Filter to what an app may read with `--visibility public`: a variable marked
+`internal` is the design system's own plumbing, not an app's to reference.
+
+`variable lookup` takes the name WITHOUT its leading dashes and answers with the
+`- Symbol:` behind it and a `### Declarations` list — one row per declaration, each
+naming the `selector`, the `inAtRule` cascade layer, what it `emits` and the
+`file:line`. The layer in that row is the one the install's `@layer` order above is
+about, so a variable that is not doing what you expect is usually a layer question
+with a visible answer. A name the graph does not know comes back `ENTITY_NOT_FOUND`,
+which is what an app-local property looks like. (MCP: `variable_list`,
+`variable_lookup`.)
+
 ## Code standards are the gate
 
 Styling work in this track falls under the live code standards — the `styling`, `css`,

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

@@ -184,14 +184,30 @@ 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.
+A bare name resolves `ds:name` globally, so where several tiers carry the name the
+lookup answers with EVERY one of them: the full writeups concatenated, each under its
+own `## <Name>` heading with its own `- Tier:` line. They are DIFFERENT blocks —
+separately authored, with different properties and different anatomies — not repeats of
+one. So read every `- Tier:` line and pick the block whose tier the app actually
+depends on; stopping at the first heading is how a swap gets built against another
+tier's component. To address one block directly, pass its `ds:` IRI, which the lookup
+accepts: `pragma block lookup ds:global.component.badge`. The bare dotted name from a
+`block list` row is not a key — keep the `ds:` prefix or use the display 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.
+prints every tier's IRI for `pragma graph inspect <IRI>` when the list is what you want
+rather than the writeups.
+
+**Read the lookup's `### Anatomy (DSL)` section for the parts, not for the notation.**
+It tells you which parts a block has and which are optional, which is what a swap
+needs. Its style values are another matter: the anatomies are being rewritten by hand
+and written back to the document, so until a block's rewrite has landed and the pack
+has been rebuilt that section still carries the retired notation — slash paths like
+`color/text/muted`, `stack` and `flow` as display types, and `sth` placeholders. None
+of those is a token name to paste into an app stylesheet. `pragma variable lookup
+<name>` is where an app finds a variable it may write, and `anatomy-author` carries the
+notation in full.
 
 **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