shadcn-adapt-guide · git:20261015.b1aaad5 · 2026-10-15 · sha256 8917eda6281c5c3a
shadcn-adapt-guide git:20261015.b1aaad5A
Immutable. This exact content never changes and is served at /api/v1/blob/8917eda6281c5c3a.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_joammgtx6biyceco/8917eda6281c5c3a3bc52d49127091288de5695f3a7f932b8715eb8f973c5e3a.json
Then /plugin install shadcn-adapt-guide@markdownregistry-joammgtx6biyceco in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: shadcn-adapt-guide
description: Adapt a shadcn/ui component into a first-class Nexus component. Use when porting, adapting, converting, or translating a shadcn (or shadcn/ui) component to Nexus — mapping tokens via shadcn-divergences.md, applying the nx: prefix, data attributes, component sizing, the focus-ring pattern, and Storybook play-fn tests. Triggers on "adapt X to Nexus", "port shadcn X", "add the X component" for the Component library epic, or a shadcn source URL/issue asking to bring a component into the design system.
allowed-tools:
- Read
- Grep
- Glob
- Bash
- Edit
- Write
- WebSearch
- WebFetch
user-invocable: false
---
# Shadcn Adapt Guide
## Purpose
Deterministically turn one shadcn/ui component into a first-class Nexus component that meets the full component bar. The mapping is **known**, so this is a recipe, not open-ended implementation: orient → transform → verify. Do not write a multi-phase plan or wait for approval — the steps below are the plan.
## Rules are the spec — reference, never duplicate
The authoritative rules live in `.claude/rules/*.md`. This guide orchestrates them; it never copies the token tables inline (that would drift from the source). Open a rule file when the Reflex Check points you at it.
| Rule | What it owns |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `shadcn-divergences.md` | **THE** shadcn→Nexus token mapping, sizing, data-attrs, focus, checklist |
| `base-*.json` (surface/nav tokens) | Surface/elevation tokens (container/popover/overlay), the `nav-*` namespace |
| `testing-react.md` | Required stories, play-fns, a11y, and story coverage audit |
| `packages/core/tokens/` | Token names — verify a token exists before using it |
| `code-quality.md`, `composition-over-render-props.md`, `extract-inline-handlers.md`, `guard-clauses.md`, `useeffect-escape-hatch.md`, `code-comments.md`, `no-follow-up-deferral.md`, `project-stage.md` | General code discipline |
## Input
One component (e.g. `checkbox`), a shadcn source URL, or a tracked issue (#162–#177 under epic #161). **One component per run → one commit → one PR.**
## Archetype → reference component
Before writing, read the closest **shipped** Nexus component and mirror it exactly — structure, `data-slot`, focus, exports, JSDoc. Don't invent a new shape.
| If the component is… | Mirror | Examples |
| --------------------------------------- | --------------------------------- | --------------------------------- |
| A Radix form control | `switch.tsx` | checkbox, radio-group, progress |
| An overlay (portal + overlay + z-index) | `dialog.tsx` | alert-dialog, sheet, popover |
| A menu/list with items | `select.tsx`, `dropdown-menu.tsx` | command |
| CVA enum/compound variants | `button.tsx`, `badge.tsx` | (variant-heavy components) |
| A styled element + focus/aria-invalid | `input.tsx` | textarea, input-otp slot |
| Pure markup, no Radix | compose primitives + `cn` | table, skeleton, separator, label |
| Nav / sidebar chrome | `nav-*` tokens | sidebar |
## Process
### Step 1 — Orient (read before write)
1. If a tracked issue exists: `gh issue view {N} --json title,body` — it specifies the exports, dep, remaps, icons, and acceptance for this component.
2. Pick the archetype above and **read that reference file end-to-end**. It is your template.
3. Skim the relevant rows of `shadcn-divergences.md`.
### Step 2 — Get the canonical shadcn source
- Fetch via the `shadcn` skill, the shadcn registry (`https://ui.shadcn.com/r/...`), or WebFetch of the source. Read the **whole** file.
- Research the npm dep you'll add (Radix primitive / `cmdk` / `sonner` / `input-otp` / `react-hook-form`) — don't guess its API: `"{lib} {version} docs"`.
### Step 3 — Transform (deterministic + Reflex Check)
Rewrite the source into the Nexus component, mirroring the archetype and applying the **Reflex Check** below. Preserve the public API shape — prop names, the `asChild` pattern, handler signatures, and the `destructive` variant name.
### Step 4 — Stories
Author `{Name}.stories.tsx` per `testing-react.md`: Default, one per variant + size, Disabled, interaction (click/keyboard) with play-fns, WithDataAttributes (play), and a render-based AllVariants. a11y runs automatically. For a non-standard showcase name or interaction equivalence, follow the archetype equivalence policy in `testing-react.md`.
### Step 5 — Wire
- Add the dep to `packages/react/package.json` (alphabetical) → `pnpm install`.
- Add any new icon to `packages/react/src/lib/icons.ts` (Tabler re-export).
- `export * from './components/{name}/{name}'` in `packages/react/src/index.ts`.
- Import another component by its file (`'../button/button'`), never its folder.
### Step 6 — Verify (real gates; fix until green)
Run these and fix everything before reporting — no deferral (`no-follow-up-deferral.md`):
- `pnpm --filter @nexus_ds/react typecheck`
- `pnpm lint` — the canonical gate (`eslint . --max-warnings 0`), and it passes on a current tree (`.claude/worktrees/` is config-ignored, so `eslint .` doesn't recurse it). For a faster loop while iterating, scope to your files: `npx eslint packages/react/src/components/{name}/{name}.tsx`.
- Story tests per `testing-react.md` (`pnpm test:storybook`); a11y violations fail the run.
## Reflex Check
Read at the start; re-fire whenever a trigger lights up. The trigger is the thing you're about to type; the arrow is what to do instead.
- _Pasting a shadcn `className`?_ → strip raw Tailwind; put `nx:` **before** every modifier (`nx:hover:…`, not `hover:nx:…`); map each utility to a **semantic** token via `shadcn-divergences.md` — never `bg-primary` (incomplete) or `bg-blue-500` (primitive). (`shadcn-divergences.md`)
- _See `bg-accent` / `text-accent-foreground` / `hover:bg-accent`?_ → there is **no `accent` token** in Nexus; map **by context** — ghost/control hover → `background-hover`, menu/dropdown item → `popover-hover`, list/card row → `container-hover`. If the surface isn't inferable, ask rather than guess. (`shadcn-divergences.md` § Accent)
- _See a `dark:` modifier?_ → delete it. Semantic tokens already carry their dark value. (`shadcn-divergences.md`)
- _See `ring-*` / `focus:ring` / `ring-offset`?_ → use `nx:focus-visible:outline-2 nx:focus-visible:outline-focus-default` (Button adds `nx:focus-visible:outline-offset-2`; fields swap `outline-2` for `nx:focus-visible:outline-default` plus `nx:focus-visible:border-focus-default`); invalid fields add `nx:aria-invalid:focus-visible:outline-focus-error nx:aria-invalid:focus-visible:border-focus-error`. Drop any `outline-none` on the same element, and swap `nx:transition-colors` for `nx:transition-control` (or `nx:transition-field` on a field) — `transition-colors` carries `outline-color`, which fades the ring in, and `pnpm lint` fails the pair. (mirror `input.tsx`; spec: `/foundations/focus`)
- _Sizing a control?_ → copy the `size` variants straight from `button.tsx` (it covers both the text and icon-only shapes) or `input.tsx`. Don't derive a scale of your own.
- _Adding any element?_ → `data-slot="{name}"` (+ `data-variant`/`data-size` if it has them).
- _shadcn uses `destructive`?_ → keep the **variant name** `destructive` in the public API; map internals to `error-*` tokens. (`shadcn-divergences.md`)
- _Overlay / portal / floating layer?_ → mirror `dialog.tsx`: `nx:bg-overlay` scrim, `nx:bg-container`/`nx:bg-popover` surface, `nx:z-modal` (dialog/sheet/alert-dialog) or `nx:z-popover` (popover/command), tw-animate-css fade/zoom/slide.
- _Nav / sidebar chrome?_ → `nav-*` namespace (`nx:bg-nav-background`, `nx:hover:bg-nav-item-hover`, `nx:border-nav-border`), not the base surface tokens.
- _Defining a prop typed `(…) => ReactNode` / `ComponentType` / a `mode` discriminator?_ → use `children`/named slots or per-mode components. (`composition-over-render-props.md`)
- _Inline JSX handler 3+ lines or branching?_ → extract a named `handleX` above `return`. (`extract-inline-handlers.md`)
- _Reaching for `useEffect`?_ → external systems only (subscriptions, DOM measurement); never to sync React state. (`useeffect-escape-hatch.md`)
- _Typing `// TODO` / "for now" / "follow-up"?_ → don't. Fix in this PR, or `// TODO(#N):` against a tracked issue. (`code-comments.md`, `no-follow-up-deferral.md`)
- _Tempted by a backcompat shim / deprecation / feature flag?_ → delete or rename in place; this is pre-production. (`project-stage.md`)
- _A semantic token you need doesn't exist?_ → **stop and surface it.** Don't reach for a primitive or invent one; the token set is the contract. (`packages/core/tokens/`)
## Definition of done
- [ ] Public API shape preserved; `asChild` where interactive
- [ ] `nx:` prefix before all modifiers; semantic token paths only; no `dark:` on semantic tokens
- [ ] `data-slot` (+ `data-variant`/`data-size`); sizing copied from the archetype component
- [ ] Named interface + JSDoc on custom props; focus ring = `outline-focus-default`, with the 2px offset on Button only
- [ ] Stories with play-fns + AllVariants; a11y clean
- [ ] Dep added + installed; icons added; exported from `src/index.ts`
- [ ] `typecheck` + `eslint packages` + story tests all green
- [ ] One component, one commit, `Closes #N`
## Notes
- **Spacing:** a control sizes itself with a fixed height plus numeric inline padding — mirror the archetype rather than deriving a scale. Role-named spacing utilities still exist, but only for container and layout roles; `packages/tailwind/spacing-utilities.css` is the current set. There is no `control-*` spacing family — it was dropped in #489 when every component moved to numeric spacing.
- **Don't over-plan.** The recipe above _is_ the plan — no planning doc, no approval gate. Orient, transform, verify, report.