shadcn-adapt-guide

Converts shadcn/ui components into Nexus design system components with token mapping and tests.

1|1|Updated Dec 18, 2025
One-click install
npx skills add https://github.com/nexuslabs-ai/nexus --skill shadcn-adapt-guide-nexuslabs-ai
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: shadcn-adapt-guide
Source: https://github.com/nexuslabs-ai/nexus/tree/main/.agents/skills/shadcn-adapt-guide
Command: npx skills add https://github.com/nexuslabs-ai/nexus --skill shadcn-adapt-guide-nexuslabs-ai

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Porting a shadcn/ui component into the Nexus design system by hand is error-prone: raw Tailwind classes must be remapped to semantic tokens, the nx: prefix applied, sizing converted to padding-based density utilities, and Storybook tests written. This Skill turns that port into a deterministic recipe so each component lands as a first-class Nexus component in one commit. ## Core Features & Use Cases - Deterministic transform pipeline: Orient (read the archetype reference component), fetch the canonical shadcn source, transform via a Reflex Check of token and pattern rules, then verify with typecheck, lint, and Storybook tests. - Token and pattern enforcement: Maps shadcn utilities to Nexus semantic tokens via shadcn-divergences.md, applies the nx: prefix, data-slot attributes, focus-ring outline pattern, and padding-based control sizing. - Full component bar: Generates stories with play functions, a11y checks, dependency wiring, icon registration, and package exports, closing the tracked issue with one PR. - Use Case: Given issue #163 asking to add the shadcn checkbox component, the Skill reads switch.tsx as the archetype, fetches the shadcn source, rewrites it with Nexus tokens, adds stories, and ships a green PR. ## Quick Start Ask the agent to adapt the shadcn checkbox component into a Nexus component following this guide.

Frequently Asked Questions about shadcn-adapt-guide

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I adapt a shadcn/ui component into the Nexus design system?▼

Follow the recipe: read the closest shipped Nexus archetype component, fetch the canonical shadcn source, rewrite it using the Reflex Check token mappings, add stories with play functions, wire the dependency and exports, then run typecheck, lint, and Storybook tests until green.

How are shadcn Tailwind classes mapped to Nexus tokens?▼

Raw Tailwind classes are replaced with semantic Nexus tokens defined in shadcn-divergences.md, using the nx: prefix before every modifier. Primitive classes like bg-blue-500 and incomplete ones like bg-primary are never used; dark: modifiers are deleted because semantic tokens carry their dark values.

What replaces shadcn's bg-accent and ring utilities in Nexus?▼

Nexus has no accent token, so bg-accent maps by context: background-hover for controls, popover-hover for menu items, container-hover for list rows. Ring utilities are replaced with nx:focus-visible:outline-2, outline-focus-default, and a tokenized outline offset.

Does the adaptation keep the shadcn component's public API?▼

Yes. Prop names, the asChild pattern, handler signatures, and the destructive variant name are preserved. Internally, destructive maps to Nexus error-* tokens, but the public API shape stays compatible with shadcn usage.

Why does Nexus use padding-based sizing instead of fixed heights?▼

Fixed heights like h-10 break density modes. Controls use the role utility nx:py-control-{sm,md,lg}, which resolves per the data-density attribute at runtime. Documented exceptions include progress bars, avatars, and modals.

What verification gates must pass before the adapted component ships?▼

The pnpm typecheck for @nexus_ds/react, the canonical eslint gate with zero warnings, and Storybook story tests including automatic a11y checks must all pass. Failures are fixed in the same PR; deferring follow-ups is not allowed.