This repository (Asymmetric-al/core)
These repo-owned sections are intentionally kept on top of the vendored
shadcn skill. If upstream refreshes replace this file, reconcile this overlay
before running bun run skills:sync.
Triggers
- Use for selecting, installing, composing, or customizing shadcn/ui, registry
items, themes, and wrappers in this repo.
- Use together with
packages/ui/AGENTS.md and docs/ai/rules/frontend.md.
- Do not use to switch styles, run
shadcn init / shadcn create, or introduce
Radix or React Aria. Never run shadcn init. Do not switch Core to
base-nova, base-luma, base-mira, base-rhea, base-sera,
base-vega, base-lyra, a Radix-based style, or a React Aria-based style.
Workflow
- Read
packages/ui/components.json and confirm style: "base-maia",
tailwind.baseColor: "zinc", tailwind.cssVariables: true.
- Run
bunx shadcn@latest info --json from packages/ui (never from an app).
- Search existing
@asym/ui components before adding anything new.
- For registry or generated components, inspect CLI output, adapt to Maia, and
review the full diff. Never
--overwrite without reviewing customizations.
- Use Base UI
render (not Radix asChild). Prefer semantic tokens over
literal zinc-* or hardcoded colors.
- Follow Core design-system lint for
scoped lint, raw-finding review, authoring exceptions, and checking consumers
after shared changes. To fix a specific finding, use the short
fix guide. Preserve other shadcn
guardrails and browser evidence when visible. Do not load this workflow for
unrelated work.
Checklist
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: Switching shadcn styles, running shadcn init / shadcn create, or introducing Radix / React Aria. Core UI is always Base UI + exact base-maia; pair this skill with packages/ui/AGENTS.md. Use base-ui for primitive API details after this skill.
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 (Base UI is the only primitive base; UI SDK fills only interactions no shared component provides, per
packages/ui/AGENTS.md).
- 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
- 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
Review checklist
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
1---2name: moai-library-shadcn-23description: "Build UI with Core's shadcn/Base UI system. Use for selecting, installing, composing, or customizing shadcn/ui, registry items, themes, and wrappers. Always preserve exact style `base-maia`, Zinc-oriented semantic CSS-variable tokens, and Base UI primitives. Do not use to switch styles, run `shadcn init`, or introduce Radix/React Aria. Pair with `packages/ui/AGENTS.md`."4metadata:5 source: https://skillmd.com/skills/asymmetric-al/moai-library-shadcn-26---78## This repository (Asymmetric-al/core)910These repo-owned sections are intentionally kept on top of the vendored11shadcn skill. If upstream refreshes replace this file, reconcile this overlay12before running `bun run skills:sync`.1314### Triggers1516- Use for selecting, installing, composing, or customizing shadcn/ui, registry17 items, themes, and wrappers in this repo.18- Use together with `packages/ui/AGENTS.md` and `docs/ai/rules/frontend.md`.19- Do not use to switch styles, run `shadcn init` / `shadcn create`, or introduce20 Radix or React Aria. Never run `shadcn init`. Do not switch Core to21 `base-nova`, `base-luma`, `base-mira`, `base-rhea`, `base-sera`,22 `base-vega`, `base-lyra`, a Radix-based style, or a React Aria-based style.2324### Workflow25261. Read `packages/ui/components.json` and confirm `style: "base-maia"`,27 `tailwind.baseColor: "zinc"`, `tailwind.cssVariables: true`.282. Run `bunx shadcn@latest info --json` from `packages/ui` (never from an app).293. Search existing `@asym/ui` components before adding anything new.304. For registry or generated components, inspect CLI output, adapt to Maia, and31 review the full diff. Never `--overwrite` without reviewing customizations.325. Use Base UI `render` (not Radix `asChild`). Prefer semantic tokens over33 literal `zinc-*` or hardcoded colors.346. Follow [Core design-system lint](references/design-system-lint.md) for35 scoped lint, raw-finding review, authoring exceptions, and checking consumers36 after shared changes. To fix a specific finding, use the short37 [fix guide](references/design-system-lint-fixes.md). Preserve other shadcn38 guardrails and browser evidence when visible. Do not load this workflow for39 unrelated work.4041### Checklist4243- [ ] Exact `base-maia` / Zinc / CSS variables remain unchanged44- [ ] Shared ownership stays in `packages/ui`45- [ ] Registry output adapted to Core tokens, radii, and primitives46- [ ] No `shadcn init`, preset-switch, Radix, or React Aria47- [ ] Overlay reconciled before `bun run skills:sync`4849# shadcn/ui Design System - Skill5051**Name:** `moai-library-shadcn`52**Purpose:** Build consistent, accessible UI using shadcn/ui components, tokens, and composable primitives.53Use this skill whenever selecting, installing, composing, or customizing shadcn/ui in this repo.5455**Applies when:** Working with shadcn/ui components, Tailwind tokens/themes, registry items, or component wrappers.56**Do not use when:** Switching shadcn styles, running `shadcn init` / `shadcn create`, or introducing Radix / React Aria. Core UI is always Base UI + exact `base-maia`; pair this skill with `packages/ui/AGENTS.md`. Use `base-ui` for primitive API details after this skill.5758## Rules5960- **Docs first:** Start with [reference-links.md](reference-links.md), then open the exact component doc before editing.61- **Copied-in code is first-party:** Treat `components/ui/*` as owned project code with stable conventions.62- **Prefer install over reinvention:** Use CLI/registry install paths for base components, then customize in wrappers.63- **Behavior primitives stay intact:** Keep accessibility and keyboard behavior from the Base UI-backed internals (Base UI is the only primitive base; UI SDK fills only interactions no shared component provides, per `packages/ui/AGENTS.md`).64- **Tokens over one-offs:** Centralize color, radius, spacing, and typography; avoid hardcoded one-off styles.65- **Composable APIs:** Keep props minimal, use Base UI's `render` prop intentionally (no `asChild` here), and avoid boolean-prop explosion.66- **Interoperability guardrail:** If mixing with Base UI primitives, document the boundary and keep one clear owner per interaction.6768## Workflow69701. Check whether an existing component already solves the need in `components/ui/*`.712. Open the relevant docs from [reference-links.md](reference-links.md).723. Choose install path:73 - CLI/registry install for standard components and blocks.74 - Manual composition only when customization requires it.754. Compose app-specific wrappers outside `components/ui/*`.765. Verify keyboard, focus, labels/descriptions, and light/dark behavior.776. Run scoped quality gates for changed packages.7879## Checklists8081### Implementation checklist8283- [ ] Existing shadcn component evaluated before creating new primitive84- [ ] Token-based styling used (no unnecessary arbitrary values)85- [ ] `cn()` and variants are consistent with existing patterns86- [ ] `render` prop and composition semantics are correct87- [ ] a11y behavior (focus, keyboard, ARIA) preserved8889### Review checklist9091- [ ] No duplicate component variants that should be shared92- [ ] Wrapper components are outside `components/ui/*`93- [ ] Forms include labels, help text, and error messaging94- [ ] Any Base UI crossover is explicit and justified9596## Minimal examples9798### Reuse existing primitive99100```tsx101import { Button } from "@/components/ui/button";102103export function Actions() {104 return (105 <div className="flex gap-2">106 <Button>Save</Button>107 <Button variant="secondary">Cancel</Button>108 </div>109 );110}111```112113### Extend in wrapper layer114115```tsx116import { Button } from "@/components/ui/button";117118type LoadingButtonProps = React.ComponentProps<typeof Button> & {119 loading?: boolean;120};121122export function LoadingButton({123 loading,124 children,125 ...props126}: LoadingButtonProps) {127 return (128 <Button disabled={loading} {...props}>129 {children}130 </Button>131 );132}133```134135## Additional resources136137- Full shadcn docs index: [reference-links.md](reference-links.md)138- Base primitives companion skill: [`docs/ai/skills/base-ui/SKILL.md`](../base-ui/SKILL.md)139- Base docs index: [`docs/ai/skills/base-ui/reference-links.md`](../base-ui/reference-links.md)140141## Common mistakes / pitfalls142143- Editing copied-in primitives when a thin wrapper is enough144- Ignoring docs updates and relying on stale memory145- Mixing primitive systems inside one component without clear ownership146- Breaking keyboard/focus behavior while styling