From 1cbd1f9139cb99c17c41f3eaa9bbda97315e0355 Mon Sep 17 00:00:00 2001 From: Alex Carpenter Date: Tue, 3 Nov 2026 20:10:19 -0500 Subject: [PATCH] docs(mosaic): remove the mosaic skill and keep its rules in AGENTS.md --- .changeset/mosaic-remove-skill.md | 2 + .claude/skills/mosaic/SKILL.md | 119 ------------------ packages/mosaic/AGENTS.md | 19 +++ .../mosaic/docs}/documenting-components.md | 0 packages/mosaic/docs/migration.md | 4 +- packages/swingset/CLAUDE.md | 2 +- 6 files changed, 24 insertions(+), 122 deletions(-) create mode 100644 .changeset/mosaic-remove-skill.md delete mode 100644 .claude/skills/mosaic/SKILL.md rename {.claude/skills/mosaic/references => packages/mosaic/docs}/documenting-components.md (100%) diff --git a/.changeset/mosaic-remove-skill.md b/.changeset/mosaic-remove-skill.md new file mode 100644 index 00000000000..a845151cc84 --- /dev/null +++ b/.changeset/mosaic-remove-skill.md @@ -0,0 +1,2 @@ +--- +--- diff --git a/.claude/skills/mosaic/SKILL.md b/.claude/skills/mosaic/SKILL.md deleted file mode 100644 index f588f08e9ad..00000000000 --- a/.claude/skills/mosaic/SKILL.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -name: mosaic -description: >- - Work on Mosaic UI: styling a component with StyleX (`stylex.create`, `--cl-*` - tokens, `themeProps`), or building a flow — writing the model (the Clerk - adapter), the controller (local state, in React state or a state machine: - `setup`, states/guards/`invoke`, wired to React with `useMachine`/`useActor`/ - `useSelector`), or the view (rendering, including moving between screens with - the `Flow` component), testing a feature, or - migrating a legacy / pre-Mosaic component into the model / controller / view - split. Use when building, styling, debugging, testing, or migrating anything - Mosaic. `packages/mosaic/ARCHITECTURE.md` holds the design-system - contract; this skill is the how-to layer. ---- - -# Mosaic UI - -Two things live under Mosaic, and this skill covers the how-to for both: - -- **Styled components** are authored with **StyleX** — `stylex.create` declares - the styles, `themeProps` emits the part's public identity (the `.cl-` - class plus `data-` attrs), and `mergeStyleProps` fuses the two with the - props the part was called with. A part takes `xstyle` (StyleX atoms for its - root), never `className`/`style`. -- **Flows** follow a **model → controller → view** split — _where the data comes - from_ → _what the user is doing to it_ → _what that looks like_. What crosses - each boundary is plain data: no Clerk resource reaches the controller, no - machine snapshot reaches the view. - -"Flow" means two things here. A feature's model, controller and view are its -flow. `Flow` from `src/components/flow/` is the component that moves between -screens on one card or dialog. If a screen replaces another on the same surface, -use the component: a conditional makes the new screen pop in. See "Moving between -screens on one surface" in `packages/mosaic/docs/views.md`. - -```text -model Clerk adapter: reads Clerk hooks and resources, resolves the - environment, gates permissions, and answers with plain data plus - plain callbacks under an explicit `status`. The only layer that may - import Clerk hooks or call Clerk resource methods. - -controller Local state: what is open, what is in flight, what the view may do - next — held in React state or a state machine, whichever the - interaction's complexity calls for. Wraps the model's callbacks so - an action can report pending, hold the surface still while it runs, - and close on success. No Clerk imports. - -view Rendering: takes plain props and callbacks, renders UI, calls them - back. No Clerk imports. No data-fetching. No machine snapshot. -``` - -A machine is **not a fourth layer**, and not a requirement. It is one of the two -ways a controller can hold its state, and picking one is a complexity call: -`useState` for a boolean that never touches async, a machine once the -interaction has an async lifecycle or two values that must change together, and -sometimes both in one controller. Either way the controller returns plain props, -so the view cannot tell and neither can its tests. Criteria and worked -before/afters: `packages/mosaic/src/machine/ADOPTION.md`. - -`packages/mosaic/ARCHITECTURE.md` is the -canonical contract for the whole design system — the `--cl-*` tokens, the -`.cl-` + `data-` styling API, the CSS build, and the "Flow and data -architecture" section that defines the split. Read it for the _what_; this skill -is the _how-to_. - -`packages/mosaic/src/features/switcher/` is the fullest worked example of the split -in the repo — model, controller, view, wrapper, types, layout and styles. Copy from -it. `UserButton` wraps it, and its feature test is in -`packages/mosaic/src/features/user-button/__tests__/`. Tests go in a `__tests__/` -folder, as `packages/mosaic/docs/testing.md` describes under "Test placement". - -`packages/mosaic/AGENTS.md` loads for any work in the package. It maps common -problems (errors, pending state, focus after removal, debouncing, confirm steps) -to the shared helper that already solves them, and says to ask the user before -adding a new pattern. Check it before writing any of those by hand. - -Its "Shaping a fix" section covers bug fixes: fix the shared helper rather than -wrapping it, and treat a changed shared signature as a new pattern. Read it -before any `fix` PR. - -## Which reference to read - -Use the "Task guides" table in `packages/mosaic/AGENTS.md`. It is the shared -task index for agents, including those that do not discover this skill. Read -the guide for the layer or behavior you are changing. - -The migration workflow (`packages/mosaic/docs/migration.md`) ties the flow references together: it -treats the legacy component as the spec and drives you through the model, -controller, and view layers, then verifies parity with `parity-audit.md`. - -## Breaking changes - -While `@clerk/mosaic` is on 0.x, a breaking change is a `minor` changeset. Start -its body with `**Breaking:**`, then give an old-to-new table and a search that -finds affected usage, so an agent can migrate from the changelog alone. The -changelog ships in the npm package at -`node_modules/@clerk/mosaic/CHANGELOG.md`. - -```md ---- -'@clerk/mosaic': minor ---- - -**Breaking:** Rename a `UserButton` prop. Values and defaults are unchanged; TypeScript flags the old name. - -| Before | After | -| -------------------- | ------------------ | -| `renderTriggerLabel` | `showTriggerLabel` | - -Find usages with `git grep -n renderTriggerLabel`. -``` - -## Documenting a component in swingset - -Read [`references/documenting-components.md`](references/documenting-components.md) -for the house style: layers, `meta` conventions, each archetype's required -section order, and the finishing checklist. The rule agents most often get wrong -is under "Writing the prose": the docs describe the API as it is, never the -reasoning that produced it. diff --git a/packages/mosaic/AGENTS.md b/packages/mosaic/AGENTS.md index 82744a0bc13..5cdb17f0017 100644 --- a/packages/mosaic/AGENTS.md +++ b/packages/mosaic/AGENTS.md @@ -23,6 +23,7 @@ Read the guide for the task you are doing. Paths below are relative to this pack | Migrate legacy behavior | [Migration](docs/migration.md) | | Review migration parity | [Parity audit](docs/parity-audit.md) | | Add a public prop that shows or hides UI | [Public visibility props](docs/public-props.md) | +| Document a component in Swingset | [Documenting components](docs/documenting-components.md) | | Prove a change in a browser | [verify-mosaic](.claude/skills/verify-mosaic/SKILL.md) | ## Before editing a file @@ -147,6 +148,24 @@ Docs say what the code cannot: rules, reasons, and which tool fits which problem A PR that adds, renames or changes the signature of a shared helper in `src/hooks/`, `src/utils/`, `src/blocks/`, `src/components/form/` or `src/machine/` updates the table above, and any doc that names it, in the same PR. +## Breaking changes + +While `@clerk/mosaic` is on 0.x, a breaking change is a `minor` changeset. Start its body with `**Breaking:**`, then give an old-to-new table and a search that finds affected usage, so an agent can migrate from the changelog alone. The changelog ships in the npm package at `node_modules/@clerk/mosaic/CHANGELOG.md`. + +```md +--- +'@clerk/mosaic': minor +--- + +**Breaking:** Rename a `UserButton` prop. Values and defaults are unchanged; TypeScript flags the old name. + +| Before | After | +| -------------------- | ------------------ | +| `renderTriggerLabel` | `showTriggerLabel` | + +Find usages with `git grep -n renderTriggerLabel`. +``` + ## Lint Mosaic uses Oxlint and runs stricter lint rules than the rest of the repo. Lint with `pnpm lint` from `packages/mosaic`. diff --git a/.claude/skills/mosaic/references/documenting-components.md b/packages/mosaic/docs/documenting-components.md similarity index 100% rename from .claude/skills/mosaic/references/documenting-components.md rename to packages/mosaic/docs/documenting-components.md diff --git a/packages/mosaic/docs/migration.md b/packages/mosaic/docs/migration.md index 83e46a9edbc..e71beb3c410 100644 --- a/packages/mosaic/docs/migration.md +++ b/packages/mosaic/docs/migration.md @@ -1,8 +1,8 @@ # Migrating a component into Mosaic Migrating a legacy component means taking logic that was fused into one file and -pulling it apart into the model / controller / view layers (see the skill -overview and `packages/mosaic/ARCHITECTURE.md` → "Flow and data architecture"). +pulling it apart into the model / controller / view layers (see +`packages/mosaic/ARCHITECTURE.md` → "Flow and data architecture"). `packages/mosaic/src/features/reverification/` is a compact worked example of the finished shape: model, controller, view, types, messages, wrapper, and a feature test. diff --git a/packages/swingset/CLAUDE.md b/packages/swingset/CLAUDE.md index 8a6056f6dd4..aa8ef063dd5 100644 --- a/packages/swingset/CLAUDE.md +++ b/packages/swingset/CLAUDE.md @@ -50,4 +50,4 @@ These require reading several files together; the `README.md` covers the step-by ## Documenting Mosaic components -Before adding a component page or restructuring a story or MDX page, read the house style in `.claude/skills/mosaic/references/documenting-components.md`: layers, `meta` conventions, each archetype's required section order, and the finishing checklist. +Before adding a component page or restructuring a story or MDX page, read the house style in `packages/mosaic/docs/documenting-components.md`: layers, `meta` conventions, each archetype's required section order, and the finishing checklist.