godui

Imported from LucasBassetti/godui (AGENTS.md). Install upstream with npx skills add LucasBassetti/godui. Copyright stays with the author.

GodUI — Agent Rules

GodUI is a design system monorepo (pnpm + Turbo): @godui/components (packages/components, core — animated shadcn/ui drop-ins), @godui/lab (packages/lab, Lab — expressive, experimental pieces beyond the shadcn catalog, maintained as-is, report-only GPU badge), docs (apps/docs, Next.js + Fumadocs), and Storybook (apps/storybook).

Skills live in .agents/skills/ (.claude/skills and .cursor/skills symlink to it). Read the relevant SKILL.md before starting the matching task.

Commands

Use pnpm — never npm or yarn.

When to invoke which skill

• Creating or modifying a component → invoke godui-component-creation first. (component-creation is the generic background variant.)
• Any color / token / palette / dark-mode / contrast work → invoke oklch-skill.
• UI polish — animation, hover, shadow, border-radius, typography, micro-interaction, "feels off" → invoke make-interfaces-feel-better (and frontend-design).

Component checklist (core shadcn drop-ins) — not done until all exist

1. Source: packages/components/src/ui/<name>.tsx, mirroring shadcn new-york-v4 components/ui/<name>.tsx — same exports, props, data-slots and Radix packages. Header comment names the shadcn version it mirrors. API changes are additive only.
2. export * from "./ui/<name>"; added to packages/components/src/index.ts
3. Entry in root registry.json (registry:ui, registryDependencies includes @godui/godui-motion + the shadcn deps upstream declares), then pnpm build:registry
4. Storybook story apps/storybook/src/stories/ui/<name>.stories.tsx (title UI/<Name> with spaces for multi-word names, e.g. UI/Alert Dialog → story id ui-alert-dialog, matching the docs slug; tags: ["autodocs"]) and a trace spec apps/storybook/motion-trace/<name>.spec.ts using traceInteraction + expectGpuOnly
5. Vitest packages/components/src/ui/<name>.test.tsx: parity, behaviour (open/close, keyboard), reduced motion. Parity = vendor shadcn's source (node packages/components/scripts/vendor-shadcn.mjs <name> → test/shadcn/<name>.tsx, never edit it), render the same Usage({ ui }) through both modules and expectSlotParity(slotTree(), expected, [extraSlots]) (test/parity.ts); typing ui: typeof Shadcn and passing GodUI makes tsc prove props are a superset
6. Docs page apps/docs/content/docs/components/<name>/index.mdx (no category folder) + learn.mdx beside it; <name> in apps/docs/content/docs/components/meta.json and components/<name> in the root apps/docs/content/docs/meta.json (components are listed in the main sidebar; Lab is header-only); a <PreviewCard> under its group in components/index.mdx plus a hover-animated skeleton preview apps/docs/src/components/card-previews/core/<name>.tsx registered in card-previews/registry.tsx. No date frontmatter on core pages (no New badges). Learn scenes show no words: real components get skeleton bars/icons

Project gotchas (non-obvious — these bite repeatedly)

• GPU-only, strict, no allowlist. Core may animate only transform/translate/scale/rotate, opacity, filter. No transition, transition-colors, transition-shadow, transition-all, no animated height/width/box-shadow/background-position/color. Sizes snap; moved siblings FLIP with useFlipGroup. Hover color changes snap or fade an overlay's opacity. pnpm --filter @godui/components test gates it (src/motion-gate/).

• Motion tokens come from godui-motion (core styles.css + the godui-motion registry item): animate-godui-* keyframes on Radix data-[state=open|closed], ease-spring-snappy|smooth|bouncy (CSS linear()), --godui-duration-*. Reduced motion is built into the animate-godui-* keyframes (root-only --godui-motion multiplier) and useFlipGroup; component-level transform transitions (switch thumb, tab indicator, hover lifts) still need motion-reduce: handling.

• Lab lives in packages/lab (registry registry-lab.json → /r/lab/, namespace @godui-lab, docs /docs/lab/<category>/<name>, stories Lab/<Category>/<Name>). Not held to the core GPU-only contract (report-only GPU badge). Core shadcn drop-ins go in packages/components. Don't add new components to Lab. Lab was called Extras: next.config.ts keeps /docs/extras/* (308) and /r/extras/* (rewrite, same JSON) working, and the MCP still accepts @godui-extras/ — don't remove those.

• No new CSS files; no @layer components blocks. Author component styles as inline Tailwind utilities in the .tsx (group/peer + data-[…] variants + arbitrary properties for masks/3D/gradients). styles.css is the Tailwind entry only — @import, @theme, @custom-variant, @keyframes. Reference animations with animate-<name> utilities, never a ${var} nested inside an arbitrary value (the scanner can't resolve it — write the class literal).

• Keyframes are per-component, not in the shared theme (shared enter/exit keyframes live in godui-motion). A component's @keyframes + its --animate-* token live in two places: styles.css (so Storybook/docs render) and that component's own registry.json entry (cssVars.theme for the token + css for the @keyframes). Keep them out of the godui-theme entry — the theme is pure design tokens, so installing one component pulls only its own animations. Shared keyframes (e.g. magic-rainbow on button/tab/input) are repeated in each entry; the shadcn CLI dedupes them on install. No per-component @layer components block.

• registry.json is hand-maintained. Add the new entry, run pnpm build:registry; do not reformat existing entries.

• Static Tailwind classes only. Never build class names dynamically (grid-cols-${n}) — the scanner can't see interpolated classes. Map to static strings.

• No raw var(--color-*) inside @layer blocks — renders the wrong theme color. Use Tailwind utilities (bg-primary, text-foreground, …).

• Border-ring mask needs inline longhand mask props. Tailwind [mask:...] shorthand resets clip/composite — write the longhands.

• Theme tokens: sRGB-clamped base chroma + @media (color-gamut: p3) to restore richer chroma. oklch-skill governs all color tokens.

• Use the z-index scale (z-base, z-raised, z-overlay, z-sticky, z-popover, z-modal, z-toast), never arbitrary z values.

• Add "use client" only where shadcn has it or the component uses hooks / client APIs. Core components follow shadcn v4: React 19 function components with ref as a prop (no forwardRef). Lab components keep their existing forwardRef style.

• Core source imports are install-shaped (@/lib/utils, @/components/ui/<x>, @/hooks/<x>), never relative — the shadcn CLI rewrites @/ on install. The aliases live in 4 places: packages/components/{tsconfig.json,vitest.config.ts}, apps/docs/tsconfig.json (exact @/lib/utils only — docs owns other @/lib/*), apps/storybook/{tsconfig.json,vite.config.ts}.

• Third-party CSS injected unlayered (sonner, vaul) beats Tailwind's @layer utilities at any specificity — overriding it needs ! ([transition-property:opacity]!). Audit the library's stylesheet in a unit test so upgrades can't add paint transitions back.

• Chrome won't composite the individual rotate/scale/translate properties on an <svg> (compositeFailed 1<<19). Rotate icons with [transform:rotate(…)] + transition-[transform], or animate a wrapper.

• More Chrome compositing traps (each one measured as compositeFailed in a trace): an animation with no visible change (hold at opacity 0.99 / fade 0 → 0.01, never a true no-op); filter: blur that moves pixels (dropped from the Calendar month change); a later opacity keyframe on an element that earlier ran an opacity transition, and a CSS translate transition on an element whose WAAPI translate animations were cancelled (reason 64 — move the second motion to a different property, e.g. transform: translate()). A CSS transition and a WAAPI animation drift apart on reversal (Chrome shortens reversed transitions): put pieces that must stay glued on one WAAPI clock. Two that cost layout, not compositing (counted as layout frames in a trace): an absolute/out-of-flow pseudo-element inside an element running a transform animation lays out every frame (make it an in-flow block, e.g. after:block after:size-full); and an opacity reaching or leaving 1 adds or drops a paint layer, one layout per flip (give the element isolation: isolate so it always has one, or keep it from flipping).

• Mount rule: a selection pop plays only after a change, never on first paint, remount or menu open (menu items mount on every open). Pattern = checkbox.tsx: useState of the last value, compare during render, set data-animate (useAnimateOnChange, @/hooks/use-animate-on-change, ships in godui-motion), gate the keyframe on it (data-[animate=true]: / group-data-[animate=true]/<item>:). When the animated element is Presence-managed (a Radix *Indicator), the gate must also require its "on" state (…:data-[state=checked]:animate-…): otherwise the commit that unchecks it adds the keyframe, Presence sees a new animation and the indicator re-pops before it disappears. Radio items read their group's value from a GodUI context; parts with no checked prop (Combobox check, chips) pop only if they mount after their container (a mounted state its layout effect sets, read once in useState). Test both "does not pop on first paint" and "pops after a change", assert the keyframe class is never applied bare, and trace that a deselected indicator is gone within a frame (motion-trace/deselect.ts).

• Animating a fill in the caller's colors (Checkbox ink): keep shadcn's data-[state=checked]:bg-* on the root but don't paint it (bg-clip-text; the root has no text), and let the animated child pick the color up with bg-inherit (an intermediate element inherits it without painting it the same way). For an exit, the root's colors are already the unchecked ones: pin the old ones inline on the exiting element. Radix calls an uncontrolled onCheckedChange after the commit, so read pre-change DOM in onClickCapture. A child that rests at a non-none scale/translate gets its own layer and paints over in-flow later siblings; make those relative.

• Ref merges forward a React 19 callback ref's cleanup: merge a local ref with the caller's via useMergedRef(local, ref) (@/hooks/use-merged-ref, ships in godui-motion); it returns a cleanup that calls the caller's (else ref(null)) and nulls the local ref. Never hand-roll typeof ref === "function".

• Consumers' jsdom has no getAnimations, matchMedia or animationend. Anything that waits on an animation needs a fallback that settles at once (Calendar fill layer) or on a token-length timer (Sidebar useMoving waits only on the animations its move started — fresh ones — and gives up one --godui-duration-slow after the longest should have ended, scaled by playbackRate; derive such caps from the animations, never a fixed token: traces slow the clock); guard typeof window.matchMedia === "function". This repo's vitest.setup.ts polyfills them, which hides the bug — test with the polyfill deleted.

• react-day-picker animate: rdp classList.adds the classNames animation values, so each must be a single token (a space throws and unmounts the calendar); its cleanup runs on the old caption's animationend, which strips the enter classes, so that caption animation sets the clock for the whole month change.

• Radix NavigationMenu (1.2.22) drops Presence's ref under React 19 (NavigationMenuViewportItem overrides ref), so viewport content exits never play; navigation-menu-viewport-frame.tsx re-inserts an inert ghost of the exiting content. It also toggles a hover-opened item shut on the following click; the frame swallows that click. Re-check both on Radix upgrades.

• Trace specs: traceInteraction(page, { storyId, setup?, act, windowMs }) — setup runs before tracing (open a dialog to trace its close). expectGpuOnly(result, { maxLayoutFrames }) counts frames containing layout (events < 8ms apart merge) (default 1, the frame animations finish); raise it only for a documented discrete snap (accordion close = 2: the commit, then the hold ending). Enter keyframes fill backwards (a forwards fill keeps a transform that makes the element the containing block for fixed-position children — it clipped dropdown sub-menus); each enter animation that finishes costs one discrete layout frame, so components whose animations end at staggered times (drawer, tooltip hop) allow 2. A trace that passes must be shown to fail when the GPU fix is removed, or it proves nothing (e.g. same-height toasts never exercise height).

• Sliding indicators use useActiveIndicator (@/hooks/use-active-indicator, ships in godui-motion): Tabs, single Toggle Group and Command. It slides on attribute changes (selection) and snaps on inserts/removals/resizes. The item's own active background must stay until the container reports data-indicator="ready": gate it with group-not-data-[indicator=ready]/<group>: (Tabs) or not-in-[[data-slot=<container>][data-indicator=ready]]: (Command), so the server render matches shadcn. If the item component is also used on its own (Toggle), leave shadcn's class untouched and add the override in the container's item instead (in-[[data-slot=toggle-group][data-indicator=ready]]:data-[state=on]:bg-transparent); a gated variant is emitted after a call site's plain data-[state=on]:bg-* and would beat it. Don't let an injected indicator break shadcn's first:/last: item classes; scope them with [&:nth-child(1_of_[data-slot=<item>])].

• useFlipGroup shares one running-animation map across all groups (an element moved by one group can be another group's candidate, e.g. sibling Collapsibles), and re-baselines only once nothing is mid-FLIP.

• FLIP signals: components whose height snaps (Combobox chips) render a tiny signal child that bumps a reducer on mount/unmount; useFlipGroup watches that version. Skip the signal under asChild (Slot needs one child).

• Accordion fakes a height animation exactly (the pattern for any reveal): the panel's overflow-hidden box translates -h → 0 while its content translates +h → 0 — they cancel, so text holds still and only the clip edge sweeps — and the rows below FLIP from -h on the same duration + curve, so they ride the edge. A MutationObserver on items' data-state + flushSync runs it in the click's task (before the snapped layout paints). Closing panels go absolute at once (rows rise immediately) and a near-no-op hold keyframe (opacity → 0.99; Chrome won't composite a no-visible-change animation) keeps Radix from hiding them mid-sweep. Radix keeps a closed panel's element (hidden, children dropped) — forwards fills survive on it. A box translated over its trigger needs pointer-events-none (content pointer-events-auto). The engine is useReveal (@/hooks/use-reveal, ships in godui-motion), shared with Collapsible; the hold keyframe is godui-reveal-hold (godui-motion). Collapsible has no wrapper: it counter-translates the box's direct children, clips only while data-sweeping, and falls back to a fade for loose text, inline/display: contents children or a box that paints. Nested roots glide by their own displacement minus the nearest ancestor root's. useFlipGroup won't re-baseline while a foreign finite translate animation (a sweep) runs on its container or candidates.

• Docs demos live in apps/docs/src/components/demos/core/<name>-demo.tsx and import from @godui/components; the Example code string is the demo with imports rewritten to @/components/ui/*. Learn articles reuse the kit in apps/docs/src/components/learn/core/ (KeyframeScene, SpringCurveScene, FlipScene, AutoPlayScene, LiveResult).

Before claiming done / committing

• Parallel agents share one git index. Stage with an explicit path list (never git add -A/.), check git diff --cached --name-only right before committing, and unstage anything that isn't yours with git restore --staged <path>. Build Storybook / serve traces on your own output dir and port.
• Run pnpm check and pnpm test — both must pass.
• If registry.json or any component changed, run pnpm build:registry.