Godui Component Creation

GodUI Component Creation

GodUI core (@godui/components) is shadcn/ui, animated: every component is a drop-in replacement for its shadcn new-york-v4 counterpart (same file, exports, props, data-slots, Radix primitives) with motion that runs only on the compositor. Lab — GodUI's expressive, experimental pieces beyond the shadcn catalog — lives in @godui/lab (packages/lab), maintained as-is with a report-only GPU badge; don't add new components there.

Quick reference

1. Create the component

Vendor shadcn's current new-york-v4 source first (node packages/components/scripts/vendor-shadcn.mjs {name}), then copy it to src/ui/{name}.tsx and change only classes and motion. Keep its public surface identical: file name, named exports, props, data-slot attributes, the radix-ui import, shadcn's own utility classes (including z-50, which wins over the z-index scale here — parity first). Add the header comment naming the snapshot. API changes are additive only; an extra DOM element needs its own data-slot and is listed as an extraSlots entry in the parity test.

Imports stay install-shaped — @/lib/utils, @/components/ui/<x>, @/hooks/<x> — never relative; the shadcn CLI rewrites @/ on install.

"use client"

// GodUI Popover — mirrors shadcn/ui new-york-v4 components/ui/popover.tsx (registry snapshot 2026-10-01).
// Motion: scales from the trigger and drifts 4px out of it on a spring; fades. GPU-only.

import { Popover as PopoverPrimitive } from "radix-ui"
import type * as React from "react"
import { cn } from "@/lib/utils"

function PopoverContent({ className, align = "center", sideOffset = 4, ...props }: React.ComponentProps<typeof PopoverPrimitive.Content>) {
  return (
    <PopoverPrimitive.Portal>
      <PopoverPrimitive.Content
        data-slot="popover-content"
        align={align}
        sideOffset={sideOffset}
        className={cn(
          "z-50 w-72 origin-(--radix-popover-content-transform-origin) rounded-md border bg-popover p-4 text-popover-foreground shadow-md outline-hidden data-[side=bottom]:[--godui-enter-y:-0.25rem] data-[side=left]:[--godui-enter-x:0.25rem] data-[side=right]:[--godui-enter-x:-0.25rem] data-[side=top]:[--godui-enter-y:0.25rem] data-[state=open]:animate-godui-popover-in data-[state=closed]:animate-godui-popover-out",
          className
        )}
        {...props}
      />
    </PopoverPrimitive.Portal>
  )
}

Add export * from "./ui/{name}"; to packages/components/src/index.ts.

Parity test shape (src/ui/{name}.test.tsx):

import * as Shadcn from "../../test/shadcn/popover";
import { expectSlotParity, slotTree } from "../../test/parity";
import * as Godui from "./popover";

function Usage({ ui }: { ui: typeof Shadcn }) { /* shadcn's canonical demo, built from ui.* */ }

const { unmount } = render(<Usage ui={Shadcn} />);
const expected = slotTree();
unmount();
render(<Usage ui={Godui} />); // tsc: GodUI props must accept everything shadcn's do
expectSlotParity(slotTree(), expected);

2. Ensure Tailwind scans component files

This is the most common reason styles don't apply.

packages/components/styles.css must include:

@import "tailwindcss";
@import "./theme/light.css";
@import "./theme/dark.css";

@source "./src";

Consuming apps also scan explicitly:

• apps/storybook/src/tailwind.css → @source "../node_modules/@godui/components/src" (and …/@godui/lab/src)
• apps/docs/src/app/globals.css → @source "../../../../packages/components/src" (and …/packages/lab/src)

If utilities like bg-primary render unstyled, verify @source "./src" exists and restart the dev server. Both apps already depend on @godui/components via workspace:* and it is in the docs transpilePackages — no pnpm install needed for a new component in the shared package.

3. Styling approach — inline Tailwind only

Author all component styles as inline Tailwind utilities in the .tsx. Do not create CSS files or add @layer components blocks. styles.css is the Tailwind entry only (@import, @theme, @custom-variant, @keyframes).

Express CSS-heavy designs (3D buttons, sprite masks, gradients, state machines) with utilities + arbitrary values rather than a stylesheet:

• group / peer on the parent + group-hover: / group-focus-visible: / group-active: on children — replaces .parent:hover .child descendant selectors.
• group-data-[variant=default]: / data-[status=loading]: — replaces [data-variant="x"] state selectors. Keep the data-* attributes on the element.
• has-[…]:, placeholder:, motion-reduce:, focus-within: — replace :has(), ::placeholder, prefers-reduced-motion, :focus-within.
• Arbitrary properties [background:linear-gradient(...)], [mask-image:var(--mask)], [perspective:800px], [transform:rotateX(35deg)] — for color-mix gradients, sprite masks, 3D. Asset URLs: import the asset and pass it through an inline style={{ "--mask": \url(${asset})` }}` CSS var.
• Size scales stay token-driven: px-[var(--button-px-md)] text-[length:var(--button-text-md)] (the --button-* tokens live in @theme). Map size → static utility strings in a Record.
• Animations use animate-<name> utilities backed by a --animate-* token (never a ${var} nested in an arbitrary value — the scanner can't resolve it). Prefer the shared animate-godui-* keyframes from godui-motion. A component-only @keyframes + token live in two spots: styles.css (so Storybook/docs render) and the component's own registry.json entry (cssVars.theme token + css @keyframes). Keep them out of godui-theme and godui-motion.
• Transitions name compositor properties only — transition-opacity, transition-transform, transition-[translate,scale], transition-[opacity,filter]. Never bare transition, transition-colors, transition-shadow or transition-all (the gate fails them).

Only @keyframes and the @theme token layer belong in CSS. Everything visual is a utility class on the element.

Motion — strict GPU-only (required, CI-gated)

Core components animate only transform (translate / scale / rotate), opacity and filter. There is no allowlist — the gate in packages/components/src/motion-gate/ scans every core source file, styles.css and every registry.json css block with @godui/motion-lint in strict mode and fails pnpm test on anything else. Cheap paint counts too: no color/background-color/border-color transitions, no bare Tailwind transition, no transition-colors.

CSS-first. Enter/exit and state motion are CSS keyframes keyed on Radix data-[state=open|closed] (and data-[side=…]), using the godui-motion tokens:

Sizes snap, positions FLIP. Never animate height, width, grid-template-rows or max-height. Let the size change instantly; mark siblings that move with data-flip and call useFlipGroup(containerRef, trigger) so they glide with an inverse translate; fade/slide the revealed content in with a keyframe.

Hover/press feedback. Color changes snap, or put the hover color on an overlay whose opacity transitions. Shadows: a static-shadow layer whose opacity animates. Focus rings: a pseudo-element ring animating opacity + scale, never ring/box-shadow transitions.

Reduced motion is built into the shared keyframes: every godui-* keyframe multiplies its movement by --godui-motion, which only :root sets (0 under prefers-reduced-motion), so a local [--godui-enter-distance:100%] still collapses to a fade; durations shorten and useFlipGroup skips. Your own transform transitions (switch thumb, tab indicator, hover lift) are not covered — add motion-reduce:transition-none / motion-reduce:translate-none etc.

Gestures only → motion (framer). Drag-to-dismiss (drawer, toast swipe), carousel drag, slider thumb spring. animate/initial/exit/while* objects may contain only transform/opacity/filter keys — the gate scans them.

Prove it at runtime. Add apps/storybook/motion-trace/{name}.spec.ts:

import { type Page, test } from "@playwright/test";
import { expectGpuOnly, traceInteraction } from "./trace";

test("{name} opens on the compositor", async ({ page }) => {
  const result = await traceInteraction(page, {
    storyId: "ui-{name}--default",
    act: async (p: Page) => {
      await p.getByRole("button", { name: "Open" }).click();
    },
    windowMs: 600,
  });
  expectGpuOnly(result);
});

Run with pnpm --filter storybook test:motion-trace (real time only — never --virtual-time-budget).

4. Storybook story

import { MyComponent, type MyComponentProps } from "@godui/components";
import type { Meta, StoryObj } from "@storybook/react-vite";

const meta = {
  title: "UI/MyComponent",
  component: MyComponent,
  tags: ["autodocs"],
  parameters: { layout: "centered" },
} satisfies Meta<typeof MyComponent>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Primary: Story = {
  args: { children: "Default", variant: "primary" } satisfies MyComponentProps,
};

Include stories for each variant, sizes, and disabled state.

5. Docs page

Core docs have no category folder. Each component is its own folder so the Learn tab can sit beside it: create apps/docs/content/docs/components/{name}/index.mdx (the main page) — the Learn tab is learn.mdx in the same folder (see §5.5).

Component pages are Workbench-first and minimal: stage examples as <Example> tabs, then only Installation → Usage → API in the Docs drawer. No lead paragraph, no motion prose. API = one ### <Part> per exported part (one line naming what it renders / is built on + "accepts all its props", then a Prop | Type | Default | Description table of the wrapper's own props/defaults and the key library props; trivial styled parts get the sentence only).

Motion docs live on the Learn tab (learn.mdx), after </LearnPlayer>: a What's animated table (interaction, keyframe/token, properties, easing, duration) before ## Why GPU-only, and a closing ## Replacing shadcn note (same file path, same API, install overwrites components/ui/{name}.tsx).

---
title: My Component
description: Short description.
workbench: true
---

import { MyComponent } from "@godui/components";
import { MyComponentDemo } from "@/components/demos/my-component-demo";

<Workbench>

<Example
  label="Default"
  story="ui-mycomponent"
  code={`import { MyComponent } from "@/components/ui/my-component";

export function MyComponentDemo() {
  return <MyComponent variant="primary">Example</MyComponent>;
}`}
>
  <MyComponentDemo />
</Example>

{/* More variants = more <Example label="…"> tabs only — never ## headings between them */}

## Installation
<ComponentInstall name="my-component" />

## Usage
\`\`\`tsx
import { MyComponent } from "@/components/ui/my-component";
\`\`\`

## API

### MyComponent

Renders a native `<div>` and accepts all of its props.

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `variant` | `"primary" \| "secondary"` | `"primary"` | Visual style |

</Workbench>

Core pages carry no date frontmatter (no "New" badges in the nav).

Workbench, Example, and ComponentInstall are registered globally in apps/docs/src/components/mdx.tsx.

Demo layout kit (apps/docs/src/components/demos/_kit.tsx)

Do not nest max-w-* under fullWidth unless the demo intentionally builds an inset scene.

Example content standard (stage tabs)

Every component page should feel like it was authored with the same taste — not a mix of “Press me” fillers and full desktop scenes.

Polish ceiling: bare control centered on the stage is the default. Reserve DemoScene / habitat chrome (wallpaper, menu bars) for environmental components (dock, backgrounds, pointer playgrounds) — don’t under-author buttons to look random, and don’t over-author every control into a fake desktop.

Mobile preview (required check). The Workbench stage has a desktop/mobile toggle; mobile renders the demo inside a 360px <iframe> so real @media queries fire. Demos must be fluid so they don't overflow it, without changing the desktop rendering:

• Swap a fixed w-[26rem] for w-full max-w-[26rem] — on the wide desktop container this still resolves to 26rem (identical), but shrinks below 360px on mobile.
• Any padding/margin you add purely to keep the card off the mobile edges must be mobile-only — gate it with max-sm: (e.g. max-sm:px-4, max-sm:mx-4) so desktop stays byte-for-byte the same. Never add flat px-4/mx-4 that also hits desktop.

Always flip the toggle to mobile AND back to desktop: mobile must not clip or h-scroll, desktop must look exactly as before (see §8).

MDX <p>-in-<p> hydration trap (happens frequently). Inside Example children, any text sitting on its own line inside a block element gets wrapped by MDX in an extra <p>. If that element is itself a <p> (or the preview already lives inside prose), you get <p> nested in <p> → In HTML, <p> cannot be a descendant of <p> and a hydration error. Keep text inline on the same line as its tag:

<!-- WRONG — MDX wraps the text in its own <p> -->
<p className="...">
  Your content sits above the background.
</p>

<!-- RIGHT — text inline, no extra <p> -->
<p className="...">Your content sits above the background.</p>

This is render-only (the live children), so eslint / biome won't catch it — it only shows in docs:dev. Same trap applies to any block tag with multi-line bare text.

Parameterized installs (Lab backgrounds only). A component whose install should bake a choice is served by the dynamic route apps/docs/src/app/r/lab/[item]/route.ts (wrapping @godui/lab/registry) via a ?variant= query param — not by shadcn build. Such items are left out of registry-lab.json so the route owns /r/lab/{name}.json (the /r/{name}.json and /r/extras/{name}.json rewrites reach it too), the generated component carries its overridable defaults inside // @default-props:start/end markers (the route swaps that block), and the install command is the full-URL form shadcn add "https://godui.design/r/lab/{name}.json?variant=…". The interactive picker lives in apps/docs/src/components/background-showcase.tsx.

Nav: Components are listed in the main sidebar through the root apps/docs/content/docs/meta.json (add components/{name} to its Components section, alphabetical); Lab is header-only. Also add {name} to apps/docs/content/docs/components/meta.json (pages entries are paths relative to that folder, e.g. "popover") — the index preview-count test reads its length. A page absent from either file won't appear.

Also add a <PreviewCard> for the component to apps/docs/content/docs/components/index.mdx (hand-maintained). <PreviewCard> (registered globally in mdx.tsx) takes href + title with the description as children, and renders a live placeholder preview on top (see §6):

<PreviewCard href="/docs/components/my-component" title="My Component">
  One-line description of what it does.
</PreviewCard>