add-ui-component

Start by inspecting a similar existing component, then define a component contract covering props, events, and states. Build the smallest useful version with semantic structure, apply the repo's design tokens and cn() utility, and add render and interaction tests.

Use headless accessibility primitives like Radix UI, Base UI, or Ark UI for interactive components. They provide WAI-ARIA roles, keyboard focus management, and escape key handling so you do not reinvent focus trap logic.

Prefer compound component patterns like Dialog.Root and Dialog.Content over mega-components with dozens of boolean props. Composition keeps components understandable and avoids prop-soup complexity that is hard to maintain.

Push the use client directive as deep down the component tree as possible, following the leaf pattern. Keep Server Components at the top and pass interactive client components down as children to maximize SSR benefits.

Never use useState for continuous values like pointer physics or scroll progress. Bind continuous motion to motion/react values such as useMotionValue and useTransform to avoid unnecessary re-renders.

Verify conformance to design tokens, run an axe-devtools accessibility scan, strip non-repository CSS, and conduct a peer code review. Do not present AI-generated components as production-ready without these checks and a visual regression baseline.