claude-workspace: Skill for Claude Code

React Patterns

Component Architecture

File Structure (Co-location)

src/components/UserCard/
  UserCard.tsx          # Component implementation
  UserCard.test.tsx     # Tests
  UserCard.stories.tsx  # Storybook (optional)
  index.ts              # Barrel export

Component Template

import { type ReactNode } from 'react';

interface UserCardProps {
  /** User's display name */
  name: string;
  /** Optional avatar URL */
  avatarUrl?: string;
  /** Slot for action buttons */
  actions?: ReactNode;
}

export function UserCard({ name, avatarUrl, actions }: UserCardProps) {
  return (
    <article className="flex items-center gap-4 rounded-lg border p-4">
      <img
        src={avatarUrl ?? '/default-avatar.png'}
        alt={`${name}'s avatar`}
        className="h-12 w-12 rounded-full object-cover"
      />
      <div className="flex-1 min-w-0">
        <h3 className="truncate font-medium">{name}</h3>
      </div>
      {actions && <div className="flex gap-2">{actions}</div>}
    </article>
  );
}

Conventions:

• Named export, never default
• Props interface in same file with JSDoc
• Semantic HTML (<article>, <h3>, not <div>)
• Composition via slot props (actions, children, header)
• Defensive defaults for optional props

Component Size Limits

• Max 250 lines per component file
• Max 50 lines per function
• If exceeding, extract sub-components or custom hooks

State Handling Order (Golden Rule)

Every component that fetches data MUST handle states in this exact order:

function UserList() {
  const { data, isPending, error, refetch } = useUsers();

  // 1. Error FIRST
  if (error) {
    return <ErrorState error={error} onRetry={refetch} />;
  }

  // 2. Loading ONLY when no data
  if (isPending && !data) {
    return <UserListSkeleton />;
  }

  // 3. Empty state
  if (!data?.length) {
    return (
      <EmptyState
        icon="users"
        title="No users yet"
        description="Invite your first team member"
        action={{ label: 'Invite', onClick: openInviteModal }}
      />
    );
  }

  // 4. Success
  return (
    <ul role="list" className="divide-y">
      {data.map((user) => (
        <li key={user.id}>
          <UserCard user={user} />
        </li>
      ))}
    </ul>
  );
}