@pnx-mixtape/mxds 0.1.0-rc.4 → 0.1.0-rc.6

package/.claude/skills/create-mxds-component/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: create-mxds-component
+description: Scaffold a new mxds component (React/Twig/Web-Component) via tools/scaffold-component.mjs, then fill in real props/markup/CSS/stories/README. Use when asked to create/add a new mxds component in this repo.
+---
+
+# Create an mxds component
+
+This repo has no manual scaffolding step for new components — use `tools/scaffold-component.mjs` to generate the boilerplate, then fill in the real implementation. Follow every step below as a directive, not a suggestion.
+
+## Prerequisites
+
+1. Decide the **category**: `Atom`, `Component`, `Form`, or `Layout` (no Molecule tier exists).
+2. Decide the **PascalName** (e.g. `SocialShare`).
+3. Read `docs/ComponentArchitecture.md` if you haven't already this session.
+4. Pick one existing component in the same category as a reference for structure and tone (e.g. `src/Component/Tag` for a simple one, `src/Component/Sticky` for one with a Web Component).
+5. **If the new component composes or embeds another existing mxds component** (e.g. it renders a `Button`, `Icon`, or `Tag` internally), read that component's **full README**, not just its prop table, before writing any markup that uses its classes. Modifier classes are frequently only valid in combination — e.g. Button's README documents under `### Outline combination` that `mx-button--outline` has no effect on its own and must be paired with a colour modifier like `mx-button--dark`. Guessing a class name from memory or from the enum list alone will produce output that looks plausible but is wrong; the README is the source of truth for combination rules.
+
+## Step 1 — Run the CLI
+
+Dry-run first if you're unsure which stacks apply:
+
+```
+node tools/scaffold-component.mjs <Category> <PascalName> --dry-run
+```
+
+Passing no `--react`/`--webcomponent`/`--twig` flags generates all three (the default — most components provide all three formats). Pass specific flags to scaffold only what's needed (e.g. `--twig` only, for Twig-only additions).
+
+Then run for real (drop `--dry-run`) and **confirm the printed barrel diff looks right** — it shows the exact lines inserted into `src/elements.ts` and `src/react.ts`.
+
+Flags:
+
+- `--description="..."` — one-line summary used in the generated README.
+- `--force` — allow overwriting an existing `src/<Category>/<PascalName>/` directory.
+- `--prefix=mx` — only change this for the external-reuse case documented in `notes/ComponentToolingPlan.md`; real mxds components always use the default `mx-` prefix.
+
+## Step 2 — Fill in the stubs
+
+The generator produces minimal-but-valid files, not finished components. Replace every `TODO` and placeholder:
+
+- **Props/types** — real prop names, types, and defaults (defaults live in destructuring, not the type alias).
+- **Twig** — real variables, `attributes` usage, any conditional markup.
+- **CSS** — real `mx-` BEM classes, logical properties, `/* @public */` markers above overridable custom properties.
+- **Web Component** — real lifecycle behaviour (event listeners registered with `{ signal: this.controller.signal }`, cleaned up via `disconnectedCallback()`).
+- **Stories** — real variants beyond the single generated `Default`-style story.
+- **README** — section order is fixed: `## CSS Import` → `## Twig` → `## HTML` (+ `Web Component` if applicable) → `## React` → `## Modifiers` → `## Accessibility` → `## Customisation`. Cross-stack behavioural differences go in a `### React ⇄ Twig parity` subsection. Add a `→ Used in context:` footer if the component ends up used in `mockups/`.
+- **`{Pascal}.figma.ts`** (generated whenever `--react` is included) — this is only a shell: a `url=TODO` header comment and a minimal `figma.code` example. Don't hand-write the real mapping from guesswork. Once the component has a real Figma frame to map to, load the **`code-to-figma-code-connect`** skill (it should be available as a global skill; if not yet installed, prompt the user to add it from the pnx skills repo) and follow its `.figma.ts` authoring cookbook (slots, enums, instance-swaps) rather than improvising the file's shape.
+  - Known gap as of this writing: `import figma from "figma"` resolves via the `@figma/code-connect` devDependency, which exists on the `figma-connect` branch but not yet on `main`/this branch. Until those branches converge, a freshly generated `.figma.ts` will fail `pnpm lint-ts` with `Cannot find module 'figma'` — that's expected, not something to "fix" by improvising a workaround in the generated file.
+
+## Step 3 — Checklist
+
+Run through `docs/ComponentArchitecture.md`'s "Component Checklist" section before considering the component done.
+
+## Step 4 — Verify before done
+
+Run, in order, and fix anything that fails:
+
+```
+pnpm lint-classes
+pnpm audit-parity --component <Name>
+pnpm lint
+pnpm test
+```
+
+`lint-classes`/`audit-parity` aren't wired into `pnpm lint`/CI yet (the baseline had pre-existing findings that need triage first — see `tools/lint-classnames.allowlist.json` / `docs/ParityMatrix.md`), so run them explicitly. Anything they flag on your new component is real signal — fix it, or if it's an intentional divergence, document it (a `### React ⇄ Twig parity` README subsection, or an allowlist entry with a reason) rather than ignoring the output.
+
+Then manually check the component renders correctly in both `pnpm dev-html` (Twig/Web-Component Storybook) and `pnpm dev-react` (React Storybook).
+
+Before calling it done, grep your new files for any class borrowed from another mxds component (e.g. `mx-button--`, `mx-icon--`) and re-open that component's README to confirm the usage matches its documented combination rules — don't rely on memory from Prerequisites step 5.
+
+## Step 5 — Update DESIGN.md
+
+`DESIGN.md` is a separate, hand-maintained reference for AI design tools (Claude Design etc.) — it is **not** regenerated automatically from `src/`, and forgetting this step is easy since nothing in `pnpm lint`/`pnpm test` catches the omission. A component isn't done until it's listed here too. Add two entries, in the category matching where you scaffolded (`Atom`/`Component`/`Form`/`Layout`):
+
+1. **Component Inventory** (`## Component Inventory` → the `### Atoms`/`### Components`/`### Forms`/`### Layout` table for your category) — one row: `` `PascalName` `` + a one-line description matching the README's opening line.
+2. **Canonical class inventory** (`## Canonical class inventory` → the matching `### Atoms`/`### Components`/`### Forms`/`### Layout` table) — one row listing every public `mx-*` class the component's CSS defines (grep `\.mx-[a-zA-Z0-9_-]+` across the component's own `.css` files — skip classes borrowed from other components, e.g. `mx-carousel`/`mx-dialog` inside a Gallery that composes them, since those are already listed under their own component).
+
+Keep both tables in the same alphabetical order as the surrounding rows, then run `npx oxfmt DESIGN.md` to fix table column alignment before finishing.