OpenParable
Skip to content
← Back to skills

Mosaic

Development
mosaic

Mosaic is an Agent Skill for development published in the clerk/javascript repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Work on Mosaic UI: styling a component with slot recipes (`defineSlotRecipe` / `useRecipe` / slots / variants), or building a flow — authoring a state machine (`setup`, states/guards/`invoke`, wiring to React with `useMachine`/`useActor`/ `useSelector`), writing the controller (Clerk adapter) or view (rendering) layer, testing any of those layers, or migrating a legacy / pre-Mosaic component into the machine / controller / view split. Use when building, styling, debugging, testing, or migrating anything Mosaic. `references/mosaic-architecture.md` (repo root) holds the design-system contract; this skill is the how-to layer.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/clerk/javascript/blob/HEAD/.claude/skills/mosaic/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/mosaic, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Mosaic UI

Two things live under Mosaic, and this skill covers the how-to for both:

  • Styled components are authored with slot recipes — one recipe owns a part's slot identity (data-cl-slot), variants, state, and appearance cascade; useRecipe resolves it and hands back per-slot props to spread.
  • Flows follow a machine → controller → view split that keeps Clerk resource logic out of visual components and makes behavior testable without a running Clerk app:
machine     Pure flow rules: states, events, guards, async invokes, errors.
            No React hooks. No Clerk hooks. No Clerk resource objects.

controller  Clerk/data adapter: reads Clerk hooks/resources, injects async
            effects into machine context, gates permissions, derives view props.
            The only layer that may import Clerk hooks or call resource methods.

view        Rendering only: receives a snapshot plus explicit props, renders UI,
            sends events. No Clerk imports. No data-fetching. No mutations.

references/mosaic-architecture.md (repo root, read by all agents) is the canonical contract for the whole design system — tokens, theme delivery, the data-cl-* styling API, slot recipes, appearance/cascade/scope, and the "Flow and data architecture" section that defines the split. Read it for the what; this skill is the how-to.

Which reference to read

You are…Read
Styling a component (slot recipes, useRecipe, variants, slots)references/styling.md
Authoring or debugging a state machine, or wiring one to Reactreferences/machines.md → in-tree machine/README.md
Writing the controller (Clerk adapter, permissions, revalidate)references/controllers.md
Writing the view (rendering a snapshot, sending events)references/views.md
Testing a machine, controller, or viewreferences/testing.md
Migrating a legacy component into Mosaic (the end-to-end workflow)references/migration.md
Running the parity audit that guards a migrationreferences/parity-audit.md

The migration workflow (migration.md) ties the flow references together: it treats the legacy component as the spec and drives you through the machine, controller, and view layers, then verifies parity with parity-audit.md.