Shade new component

Shade — new component / pattern checklist

Before marking a Shade component or pattern done, this checklist must pass.

Files and naming

• File: kebab-case (dropdown-menu.tsx) — matches ShadCN CLI output. Don't rename for casing.
• Exported identifier: PascalCase (DropdownMenu).
• Hooks, functions, variables: camelCase.
• Sibling <name>.stories.tsx is required (same folder).
• Inside Shade itself, import via the @/ alias (@/lib/utils, @/components/ui/input-surface).

Storybook title prefix

Layer	Title
Primitive	Primitives / <Name>
Component	Components / <Name>
Recipe	Recipes / <Name>
Pattern	Patterns / <Name>
Token gallery	Tokens / <Topic>

Required on every story file:

• tags: ['autodocs']
• parameters.docs.description.component — short one-line summary
• Per-story parameters.docs.description.story — one-liner explaining when to use that variant
• One story per important variant/state. Many small focused stories > one prose-heavy story.

Component shape

import * as React from 'react';
import {cva, type VariantProps} from 'class-variance-authority';
import {cn} from '@/lib/utils';

const thingVariants = cva('base-classes-here', {
    variants: {
        variant: {default: '...', destructive: '...'},
        size: {default: '...', sm: '...'}
    },
    defaultVariants: {variant: 'default', size: 'default'}
});

export interface ThingProps
    extends React.HTMLAttributes<HTMLDivElement>,
    VariantProps<typeof thingVariants> {}

const Thing = React.forwardRef<HTMLDivElement, ThingProps>(
    ({className, variant, size, ...props}, ref) => (
        <div
            ref={ref}
            className={cn(thingVariants({variant, size, className}))}
            {...props}
        />
    )
);
Thing.displayName = 'Thing';

export {Thing, thingVariants};

Hard requirements:

• className forwarded and merged via cn() — never overwritten, never dropped. Applies to every component that renders DOM.
• Visual/interactive props only (variant, size, loading). No workflow props (isMembersPage, layoutMode) — those mean you actually need a Pattern wrapper.
• Multi-region components expose compound subcomponents (.Title, .Actions, .Body) — not a prop bag.