Moai Library Shadcn
Designmoai-library-shadcnMoai Library Shadcn is an Agent Skill for design published in the Asymmetric-al/core repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Build consistent, accessible UI with shadcn/ui components, Tailwind tokens, and composable primitives. Use whenever selecting, installing, composing, or customizing shadcn/ui in this repo, including registry items, themes, and component wrappers. Prefer the base-ui skill when the UI is intentionally built only with Base UI primitives.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/Asymmetric-al/core/blob/HEAD/.claude/skills/moai-library-shadcn/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/moai-library-shadcn, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
shadcn/ui Design System - Skill
Name: moai-library-shadcn
Purpose: Build consistent, accessible UI using shadcn/ui components, tokens, and composable primitives.
Use this skill whenever selecting, installing, composing, or customizing shadcn/ui in this repo.
Applies when: Working with shadcn/ui components, Tailwind tokens/themes, registry items, or component wrappers.
Do not use when: The UI is intentionally built only with Base UI primitives (use base-ui first).
Rules
- Docs first: Start with reference-links.md, then open the exact component doc before editing.
- Copied-in code is first-party: Treat
components/ui/*as owned project code with stable conventions. - Prefer install over reinvention: Use CLI/registry install paths for base components, then customize in wrappers.
- Behavior primitives stay intact: Keep accessibility and keyboard behavior from the Base UI-backed internals (this repo is Base UI only).
- Tokens over one-offs: Centralize color, radius, spacing, and typography; avoid hardcoded one-off styles.
- Composable APIs: Keep props minimal, use Base UI's
renderprop intentionally (noasChildhere), and avoid boolean-prop explosion. - Interoperability guardrail: If mixing with Base UI primitives, document the boundary and keep one clear owner per interaction.
Workflow
- Check whether an existing component already solves the need in
components/ui/*. - Open the relevant docs from reference-links.md.
- Choose install path:
- CLI/registry install for standard components and blocks.
- Manual composition only when customization requires it.
- Compose app-specific wrappers outside
components/ui/*. - Verify keyboard, focus, labels/descriptions, and light/dark behavior.
- Run scoped quality gates for changed packages.
Checklists
Implementation checklist
- Existing shadcn component evaluated before creating new primitive
- Token-based styling used (no unnecessary arbitrary values)
-
cn()and variants are consistent with existing patterns -
renderprop and composition semantics are correct - a11y behavior (focus, keyboard, ARIA) preserved
Review checklist
- No duplicate component variants that should be shared
- Wrapper components are outside
components/ui/* - Forms include labels, help text, and error messaging
- Any Base UI crossover is explicit and justified
Minimal examples
Reuse existing primitive
import { Button } from "@/components/ui/button";
export function Actions() {
return (
<div className="flex gap-2">
<Button>Save</Button>
<Button variant="secondary">Cancel</Button>
</div>
);
}
Extend in wrapper layer
import { Button } from "@/components/ui/button";
type LoadingButtonProps = React.ComponentProps<typeof Button> & {
loading?: boolean;
};
export function LoadingButton({
loading,
children,
...props
}: LoadingButtonProps) {
return (
<Button disabled={loading} {...props}>
{children}
</Button>
);
}
Additional resources
- Full shadcn docs index: reference-links.md
- Base primitives companion skill:
docs/ai/skills/base-ui/SKILL.md - Base docs index:
docs/ai/skills/base-ui/reference-links.md
Common mistakes / pitfalls
- Editing copied-in primitives when a thin wrapper is enough
- Ignoring docs updates and relying on stale memory
- Mixing primitive systems inside one component without clear ownership
- Breaking keyboard/focus behavior while styling