shep: Skill for Claude Code

Web UI Component Development

Build React components following the four-tier architecture, with mandatory Storybook stories, data-testid attributes, and unit tests.

Four-Tier Hierarchy

Tier 0: ui/        -> shadcn/ui primitives (managed by CLI, rarely hand-edited)
Tier 1: common/    -> Reusable composed components (combine ui/ primitives)
Tier 2: layouts/   -> Page shells, structural wrappers (use ui/ + common/)
Tier 3: features/  -> Domain-specific views bound to routes (use all tiers)

Import rule: A tier may only import from lower tiers, never upward.

features/ -> layouts/, common/, ui/
layouts/  -> common/, ui/
common/   -> ui/
ui/       -> external packages only

File Structure

Tier 0 (ui/) — flat files, no subfolder

components/ui/
  button.tsx
  button.stories.tsx

Tier 1-3 — subfolder per component

components/common/feature-list-item/
  feature-list-item.tsx          # Implementation
  feature-list-item.stories.tsx  # Storybook stories (MANDATORY)
  index.ts                       # Barrel export

Barrel export template:

export { FeatureListItem } from './feature-list-item';
export type { FeatureListItemProps } from './feature-list-item';

After creating any Tier 1-3 component, add it to the tier-level barrel:

• components/common/index.ts
• components/layouts/index.ts
• components/features/index.ts

Component Template

'use client'; // Only if the component uses hooks, event handlers, or browser APIs

import { cn } from '@/lib/utils';

export interface MyComponentProps {
  /** Brief prop description. */
  label: string;
  className?: string;
}

export function MyComponent({ label, className }: MyComponentProps) {
  return (
    <div
      data-testid="my-component"
      className={cn('base-classes', className)}
    >
      {label}
    </div>
  );
}

Rules

1. Named exports only — no default exports for components.
2. 'use client' — add only when the component uses hooks, event handlers, or browser APIs. Omit for pure render components.
3. className prop — accept and merge via cn() for composability.
4. Props interface — always export the interface alongside the component.