Shadcn Parity

Use this for UI/component parity work, including shadcn-owned shell files, registry-style component authorship, React component patterns, and React Compiler/Effect decisions inside shadcn-compatible surfaces.

Comprehensive References

Load these only when the task needs the detail:

• .agents/rules/shadcn-parity/references/components.md — comprehensive component architecture reference: accessibility, asChild, composition, data attributes, artifact taxonomy, polymorphism, controlled/uncontrolled state, and component typing.
• .agents/rules/shadcn-parity/references/react.md — comprehensive React reference: React Compiler, manual memoization escape hatches, Effects, useEffectEvent, ref access, derived state, Tailwind v4 syntax, data attributes, and UI constraints.

Contract

When the user asks for shadcn parity, treat ../shadcn as the source of truth. Do not give them "inspired by shadcn". Do not abstract away the parts that matter. Clone the methodology:

• source first
• file structure first
• helper layering first
• unit tests first
• output parity first

Only diverge when:

1. the product domain is genuinely different
2. the current repo has an explicit constraint
3. the user explicitly asks for a divergence

If you diverge, say exactly why.

Ownership Rule

For kitcn init -t next, shadcn owns the app shell. kitcn owns the integration layer.

Shadcn-owned files stay shadcn-owned:

• app/layout.tsx
• app/page.tsx
• app/globals.css
• components/theme-provider.tsx
• lib/utils.ts
• components.json
• eslint.config.mjs
• next.config.mjs
• postcss.config.mjs

kitcn-owned files stay kitcn-owned:

• components/providers.tsx
• lib/convex/*
• .env.local
• convex/*
• concave.json
• package.json baseline patches
• <functionsDir>/tsconfig.json
• tsconfig.json alias patch for @convex/*

The rule is simple:

• add kitcn files
• patch the seam
• do not replace shadcn shell files wholesale

For the current Next scaffold, the acceptable shell patches are narrow:

• patch layout.tsx to mount Providers
• patch tsconfig.json to add @convex/*
• patch components.json only when tailwind.css must follow src/ vs root

For kitcn init, overwrite behavior must match that ownership split:

• shell seam patches apply directly
• kitcn-owned replacement files prompt per file in interactive mode
• --yes skips conflicting owned replacements
• --overwrite is the only bulk replacement hammer

If you find yourself authoring a full replacement for a shadcn-owned file, you are probably doing it wrong.

Universal Create Matrix

Public templates stay concrete:

• kitcn init -t next
• kitcn init -t vite

Internally, kitcn only has two scaffold modes:

• next-app
• react

Framework detection should feel like shadcn, not like a fake kitcn abstraction:

• next-app maps to next-app
• next-pages, vite, react-router, tanstack-start, and manual map to react
• unsupported frameworks should fail clearly

init -t stays universal. Keep it narrow.

init -t always owns:

• the detected app shell plus the kitcn seam
• convex/functions/schema.ts
• convex/functions/http.ts
• convex/lib/crpc.ts
• convex/lib/get-env.ts
• <functionsDir>/tsconfig.json
• root tsconfig.json patch
• .gitignore entries for .convex/ and .concave/
• components/providers.tsx
• lib/convex/*
• .env.local
• baseline scripts: codegen, convex:dev, typecheck:convex, root typecheck

Next-only baseline pieces:

• /convex messages demo
• lib/convex/server.ts
• lib/convex/rsc.tsx
• narrow shell seam patches:
  • layout.tsx
  • tsconfig.json
  • components.json

React-mode baseline keeps the client core only:

• no RSC files
• no Next-only provider/server helpers
• no /convex demo in v1
• Vite is the concrete reference for this mode

init -t options stay narrow:

• -t next
• -t vite
• --backend convex|concave
• --cwd
• --name
• --defaults
• --yes
• --prod
• --preview-name
• --deployment-name
• --env-file

Do not grow init -t with fake feature flags.

Optional capability belongs in add:

• kitcn add auth
• kitcn add ratelimit
• kitcn add resend

Auth is the first real bundle. It patches the init -t baseline and owns:

• auth server config/runtime
• auth client files
• auth-aware provider wiring
• auth env through get-env
• auth cRPC families:
  • optionalAuth*
  • auth*

Mode split:

• next-app: minimal /auth page + provider/client/server wiring
• react: auth server config/runtime, auth client, provider wiring, auth env, and auth cRPC families only

Auth v1 does not own:

• role/admin policy
• orgs/invitations
• anonymous upgrade flows
• app-specific auth UX beyond minimal sign-in/session wiring

Rule:

• universal starter scaffold = init -t
• in-place adoption = init
• optional/invasive/app-policy features = add
• if a capability already fits cleanly as a first-party plugin, do not stuff it into init -t

Registry Comparison

kitcn should match shadcn on the data model as closely as possible.

Same shape:

• one item module per folder under packages/kitcn/src/cli/registry/items/<item>/<item>-item.ts
• each item declares files
• each item declares package dependencies
• each item declares internal item dependencies

Current kitcn divergence:

• the registry stays internal for now
• install is not just file copy
• add flows patch existing kitcn seam files based on project mode

That extra install layer is what kitcn adds beyond plain shadcn registry resolution:

• register schema extensions into schema.ts
• patch crpc.ts, http.ts, providers, and get-env.ts
• resolve different roots for next-app vs react
• maintain plugins.lock.json
• install pinned package specs when needed
• run codegen and post-add hooks

Rule:

• keep the item files as close to shadcn RegistryItem as possible
• keep the dynamic patching in install/runtime code
• do not shove kitcn-specific behavior back into the item shape unless shadcn has a real equivalent

Create

fixtures/* is not hand-authored. It is a normalized snapshot of real CLI output.

The important bit:

• committed template _generated/* output comes from real kitcn codegen during kitcn init -t
• it is not copied from repo fixtures
• it is not written by hand
• template-mode init -t must fail if real codegen cannot be produced
• do not call kitcn codegen directly from the fixture script

Why not direct kitcn codegen?

• a fresh temp app may still need Convex bootstrap before codegen can succeed
• that bootstrap can become interactive if you bypass create's bootstrap flow
• kitcn init -t next already owns the whole sequence: scaffold -> dependency install -> codegen -> bootstrap retry -> codegen retry
• the fixture script should consume that contract, not reimplement half of it

Repo automation adds two deliberate details:

• tooling/fixtures.ts owns committed starters: next, next-auth, vite, vite-auth
• that uses the same public backend selector users can use elsewhere
• template sync intentionally chooses Concave because it is more agent/CI-friendly here
• default CLI behavior is still backend convex unless config or --backend says otherwise
• manual runtime lives in tooling/scenarios.ts, materialized under tmp/scenarios/*

Human Repro

To regenerate the checked-in fixture:

bun run fixtures:sync

To verify the fixture still matches fresh CLI output:

bun run fixtures:check

To materialize runnable tmp apps for manual runtime:

bun run scenario:prepare all

Why this exists:

• committed fixtures/*/package.json stays normalized to workspace:*
• fixtures:check swaps that to a packed local tarball before validation
• manual runtime happens in tmp/scenarios/*, never in fixtures/*
• use @.claude/skills/scenarios/scenarios.mdc for runtime proof after prepare; it owns which scenario keys stop at scenario:dev, which ones add test:auth and test:e2e, and which ones must use scenario:check

fixtures:check is not just a diff. It validates the fresh generated app with:

bun install
bun typecheck

Next starters also run bun lint. Vite starters intentionally skip lint in this lane because shadcn's default eslint . sweeps generated/runtime files.

It validates against the current local package under test, not the last published npm version:

• pack the current local kitcn package to a tarball
• install that tarball into the generated temp app

If you need the slower rebuild-first lane, use:

bun run fixtures:check:full

Agent Repro

When checking parity or drift:

1. run bun run fixtures:sync instead of editing fixtures/* by hand
2. run bun run fixtures:check
3. if drift remains, fix kitcn init -t next, not the fixture

Real Generation Flow

tooling/fixtures.ts does this:

1. create a temp directory

2. for each committed starter, run the local CLI:

   bunx kitcn --backend concave init -t <next|vite> --yes --cwd <tmp> --name <starter>
   

   For auth starters, follow with:

   bunx kitcn --backend concave add auth --yes
   

3. let create run the actual scaffold flow:

   • run shadcn init -t next
   • apply kitcn overlay files and patches
   • install kitcn baseline deps
   • run kitcn codegen via the init-owned backend adapter

4. if codegen needs Convex bootstrap, create bootstraps Convex and reruns real codegen

   • for template sync, the selected backend is Concave
   • outside that flow, backend still resolves normally from config/CLI

5. validate the fresh generated app:

   • pack local kitcn to a tarball
   • rewrite the generated app to install that tarball
   • bun install
   • bun typecheck
   • bun lint only for templates whose registry entry enables lint

6. copy the generated app into fixtures/<starter>

7. apply repo-only normalization:

   • strip volatile artifacts (node_modules, .next, lockfiles, etc.)
   • rewrite kitcn to workspace:*
   • remove CONVEX_DEPLOYMENT noise from .env.local

That means the fixture is allowed to normalize repo-local junk, but it is not allowed to invent user-facing files.

Do not change this into:

bunx kitcn init -t next --yes --cwd <tmp> --name next
cd <tmp>/next
bunx kitcn codegen

That skips the point of create owning bootstrap/codegen orchestration and can reintroduce interactive or half-bootstrapped failure modes.

Rule

If fixtures/next differs from fresh output, assume the CLI is wrong first. Do not "fix" fixture drift by patching the fixture directly unless the change is strictly part of repo-only normalization.

Primary Sources

Start here before editing:

• ../shadcn/packages/shadcn/src/commands
• ../shadcn/packages/shadcn/src/utils
• ../shadcn/packages/shadcn/test

Prefer shadcn's non-e2e tests over guessing intended behavior.

Method

1. Map direct analogs

Build a parity map between the local surface and the shadcn surface.

Check:

• command files
• utility files
• file boundaries
• exported helpers
• parsing/option ownership
• formatter/logger/spinner ownership
• unit tests

If there is a direct analog, mirror it.

2. Read code and tests before edits

Read the matching shadcn implementation and the relevant unit tests before changing local code.

Do not stop at the happy path source file. Read the tests too. That is where the real contract usually lives.

3. Port tests first

For parity work, the first useful move is usually test porting.

Port/adapt shadcn's non-e2e tests for:

• command parsing
• formatter output
• path matching
• dry-run/diff/view behavior
• compare/normalization behavior
• logger/spinner interactions when relevant

Adjust only the domain-specific payloads, paths, and names.

Do not add dead legacy tests like "old API no longer exists". Just delete the old path.

4. Copy structure, not just behavior

If shadcn splits logic into command modules and shared utilities, mirror that split locally.

Prefer:

• same file boundaries
• same helper names
• same call flow
• same responsibility split

Avoid:

• thin wrapper files that still delegate everything into one giant legacy file
• new local abstractions invented only to avoid copying the proven pattern
• "cleaned up" rewrites that quietly drift from shadcn
• full-file local templates for shadcn-owned shell files

5. Copy presentation too

Parity includes UX, not just logic.

Mirror:

• colors
• logger/highlighter vocabulary
• spinner lifecycle
• summary boxes
• aligned sections
• diff/view formatting
• truncation hints

If local dependencies differ, keep the behavior and shape the same with the closest local equivalent.

6. Keep local extensions narrow

If the repo needs a stronger behavior than shadcn, keep it behind the same surface.

Good:

• same compare utility shape, stronger AST equivalence inside
• same dry-run formatter shape, different plan payload underneath
• same shadcn shell, kitcn files mounted through minimal patches

Bad:

• separate helper stack "because our use case is special"
• extra compatibility shims
• alternate command surface
• replacing shadcn output just because patching feels annoying

7. Delete conflicting legacy paths

If an old local abstraction conflicts with the parity target, remove it.

Do not keep:

• backward-compat aliases
• compatibility wrappers
• fallback parsing for removed flags
• parallel old/new code paths

Make the result look like it was built that way from the start.

Parity Checklist

Before calling the work done, verify:

• matching command/module ownership exists
• matching utility layering exists
• matching human output shape exists
• matching unit-test granularity exists
• relevant shadcn non-e2e tests were ported or consciously adapted
• remaining divergences are explicit and justified

Anti-Patterns

If you catch yourself doing any of these, stop:

• "I captured the spirit"
• "I built a cleaner local abstraction"
• "I kept the old path for safety"
• "I only matched the terminal output"
• "I skipped the tests because behavior looked obvious"
• "I rewrote the shadcn file because it was faster"

That is how parity rots into fan fiction.

Output Rule

When reporting parity work back to the user, state:

1. what was cloned directly
2. what tests were ported/adapted
3. any intentional divergence

If there was no divergence, say so plainly.