mosaic

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-<slot> class plus data-<axis> 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.

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.

references/mosaic-architecture.md (repo root, read by all agents) is the canonical contract for the whole design system — the --cl-* tokens, the .cl-<slot> + data-<axis> 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/user-button/ is the fullest worked example of the split in the repo — model, controller, view, wrapper, types, messages, and a feature test. Copy from it.

Which reference to read

The migration workflow (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.

Documenting a component in swingset

packages/swingset/CLAUDE.md is the house style — archetypes, required section order, meta conventions. One rule on top of it, because it is the one agents get wrong:

The docs describe the API as it is. They do not carry the reasoning that produced it. No "not a size, because…", no rejected alternatives, no history of what the prop used to be. A reader is there to learn what the thing does, and every sentence of rationale is a sentence they have to skim past to find it. State the behaviour plainly and briefly, then stop.

<!-- no -->

### Variant

Which surface the dialog holds, and so the geometry it is given. Not a `size`,
because these are different surfaces rather than one surface at two widths — a
second card width would be a size of the `card` variant, with nowhere to sit on
this axis.

<!-- yes -->

### Variant

Which surface the dialog holds, and the geometry that comes with it.

This is the opposite of the rule for code, where a comment earns its place by explaining what the code cannot say for itself — the cascade fight behind a null, the measured reason a duration is what it is. Keep that reasoning where a future maintainer will hit it, which is the source file. The trade you rejected belongs in a code comment or the PR description; the docs get the conclusion.