Shadcn Parity

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