OpenParable
Skip to content
← Back to skills

Moai Library Shadcn

Design
moai-library-shadcn

Moai 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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 render prop intentionally (no asChild here), and avoid boolean-prop explosion.
  • Interoperability guardrail: If mixing with Base UI primitives, document the boundary and keep one clear owner per interaction.

Workflow

  1. Check whether an existing component already solves the need in components/ui/*.
  2. Open the relevant docs from reference-links.md.
  3. Choose install path:
    • CLI/registry install for standard components and blocks.
    • Manual composition only when customization requires it.
  4. Compose app-specific wrappers outside components/ui/*.
  5. Verify keyboard, focus, labels/descriptions, and light/dark behavior.
  6. 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
  • render prop 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

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