⚡ Design System Quick Reference

📁 File Structure (REQUIRED)

src/components/shared/ComponentName/
├── ComponentName.tsx          # Main component
├── ComponentName.stories.tsx  # Storybook stories  
├── ComponentName.test.tsx     # Unit tests
└── index.ts                   # Exports

🔧 Component Template

// ComponentName.tsx
export interface ComponentNameProps {
  variant?: 'primary' | 'secondary' | 'outline';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  loading?: boolean;
  children: React.ReactNode;
}

export const ComponentName: React.FC<ComponentNameProps> = ({
  variant = 'primary',
  size = 'md',
  disabled = false,
  loading = false,
  children,
  ...props
}) => {
  return (
    <div
      className={cn(
        baseClasses,
        variantClasses[variant],
        sizeClasses[size],
        disabled && 'disabled-styles',
        loading && 'loading-styles'
      )}
      aria-disabled={disabled}
      aria-busy={loading}
      {...props}
    >
      {children}
    </div>
  );
};

📖 Required Stories

// REQUIRED: Default, Variants, Sizes, States, Accessibility
export const Default: Story = { args: { children: 'Content' } };
export const Variants: Story = { render: () => <div>All variants</div> };
export const Sizes: Story = { render: () => <div>All sizes</div> };
export const States: Story = { render: () => <div>All states</div> };
export const Accessibility: Story = { render: () => <div>A11y examples</div> };

🧪 Required Tests

// REQUIRED: Rendering, Props, Events, Accessibility
it('renders correctly', () => { /* test */ });
it('applies variant classes', () => { /* test */ });
it('handles click events', () => { /* test */ });
it('has accessibility attributes', () => { /* test */ });

♿ Accessibility Checklist

• Keyboard navigation support
• Screen reader compatible
• ARIA attributes included
• Focus management
• Color contrast (4.5:1 ratio)
• Semantic HTML

⚡ Performance Limits

• Bundle size: < 5KB per component
• Total system: < 50KB gzipped
• Load time: < 2 seconds
• Accessibility score: 100%

🎨 Design Tokens

// Use these, not hardcoded values
import { colors, spacing, typography } from '../../tokens';

// ✅ Good
className="bg-primary-500 p-4 text-body"

// ❌ Bad  
className="bg-blue-500 p-4 text-sm"

📝 Naming Conventions

• Components: PascalCase (Button, ActivityCard)
• Files: PascalCase (Button.tsx, Button.stories.tsx)
• Props: camelCase (onClick, ariaLabel)
• Types: PascalCase + Props (ButtonProps)

🚨 Common Mistakes

1. Missing accessibility - Always include ARIA attributes
2. Hardcoded values - Use design tokens
3. Inconsistent naming - Follow PascalCase
4. Missing tests - Every component needs tests
5. Incomplete stories - Include all required types

📞 Quick Commands

# Create new component
mkdir src/components/shared/NewComponent
touch src/components/shared/NewComponent/NewComponent.{tsx,stories.tsx,test.tsx,index.ts}

# Test locally
npm run storybook
npm run test

# Check bundle size
npm run build
npm run perf:analyze

🔗 Resources

• Onboarding Guide: docs/design-system/cursor-onboarding-guide.md
• Component Template: docs/design-system/component-template.md
• Prompt Templates: docs/design-system/cursor-prompt-template.md
• Storybook: http://localhost:6006
• Design Tokens: src/tokens/

---

Remember: Consistency, accessibility, and performance are non-negotiable!