Shadcn To Zaidan

Shadcn to Zaidan

Use this skill as the workflow contract for porting shadcn-style React components, examples, docs, and blocks into Zaidan. Use .agents/skills/react-to-solid/SKILL.md for React-to-SolidJS syntax and primitive translation rules.

Use .agents/skills/zaidan/SKILL.md instead for consumer-side installation, adding published registry items, or choosing components for a SolidJS product.

Inputs

Accept any mix of:

• Component names, such as dialog, button, or data-table
• Raw source URLs
• External shadcn-style registry URLs
• Source, playground, docs, or example URLs
• Filter patterns when syncing from a registry
• Dry-run requests that should report resolved work without editing
• Extra transformation guidance from the user

Repository Sync Policy

For a full shadcn sync in this repository, use these defaults unless the user explicitly overrides them:

• Resolve the latest stable shadcn npm release, then pin the entire sync to its immutable shadcn@<version> Git tag and peeled commit. Never mix a release snapshot with moving main URLs.
• Use the current Base UI catalog and API under registry/bases/base as the upstream source of truth. Existing Zaidan APIs do not constrain the port.
• Implement primitives in this order: Kobalte equivalent, then Corvu equivalent, then vanilla SolidJS. For non-primitive React dependencies, search for a maintained SolidJS flavor before writing an adapter.
• Port installable components, every demo referenced by their MDX, and their Create examples.
• Exclude Form, Data Table, Date Picker, and Typography as installable sync targets. Zaidan handles those concerns separately.
• Replace Sonner with the Base Toast surface implemented on Kobalte Toast. Do not keep a Sonner alias, redirect, registry item, generated artifact, or solid-sonner dependency.
• Keep one Sidebar component. Do not create separate documentation surfaces for its floating, icon, or inset variants.
• Treat Accordion, Card, and Resizable documentation content as complete. When their sources or examples change, perform only a reference-integrity pass for preview/source names and any line-based code excerpts.

Resolve a stable release before fetching sources. Record the version, tag, and peeled commit in every plan or report. A typical resolution is:

curl -s https://registry.npmjs.org/shadcn/latest
git ls-remote --tags https://github.com/shadcn-ui/ui.git \
  "refs/tags/shadcn@<version>*"

Use the peeled ^{} commit when an annotated tag returns two refs.

URL templates may contain <name> or {component} placeholders. Replace them with the source component name before fetching.

Workflow

When asked to port a component:

1. Determine whether the source is a release-pinned shadcn item, a raw source URL, or an external shadcn-style registry/component.
2. For a full sync, inventory the pinned catalog before changing files. Classify every surface as missing, stale, current, replacement, composition/guide, or excluded. Diff existing Zaidan sources as well as missing ones.
3. Resolve registry metadata, component source, MDX, MDX-referenced demos, and Create example as distinct upstream artifacts. Inspect actual imports; registry metadata alone is not a reliable dependency graph.
4. Get a live URL for the original React component when available, then inspect it with a browser to understand behavior, states, keyboard interactions, responsive behavior, and edge cases.
5. Transform the component, docs, and examples with help from the react-to-solid skill.
6. Update all eight style slices affected by the component. Start from the upstream semantic style classes, then verify selectors, data attributes, and CSS variables against the actual Kobalte/Corvu/Solid DOM.
7. Run the transformed component, focused docs demos, and Create gallery locally and test each applicable artifact with a browser.
8. If running inside this Zaidan repo, update src/registry/kobalte/registry.json.
9. Validate with focused checks and broader checks when appropriate.

Use judgment for the details. This workflow covers new ports and release syncs of existing registry items, especially when changes touch docs, examples, styles, registry metadata, or browser behavior. Split independent work across subagents with clear prompts when that helps.

Shadcn Sources

Use the pinned release tag or commit in place of <ref>. Do not substitute main during a release sync.

Use curl -s for raw file fetches.

External Sources

For external shadcn-style registries, prefer explicit inputs from the user:

• Registry URL or source file URL
• Playground or documentation URL where the React original can be observed
• Docs URL or template, if docs should be synced into Zaidan
• Example URL or template, if examples should be synced into Zaidan

Prefix external target names only when needed to avoid collisions.

Zaidan Targets

The active registry namespace is kobalte.

Read nearby files before writing and match local conventions.

Focused docs demos are default-export modules. <ComponentPreview name="x" /> must resolve the same examples/docs/x.tsx module at runtime and when injecting displayed source. Keep slugs aligned across MDX frontmatter, UI source, registry item, and Create example.