React Component Development Guidelines

Purpose

Establish consistency and best practices for React components in Gemini-Subtitle-Pro using React 19, TypeScript 5.8, and TailwindCSS 4.

When to Use This Skill

Automatically activates when working on:

• Creating or modifying React components
• Building pages, modals, dialogs, forms
• Styling with TailwindCSS
• Working with React hooks
• Implementing state management
• Performance optimization

Quick Start

New Component Checklist

• Location: Place in src/components/[feature]/
• TypeScript: Define proper props interface
• Styling: Use TailwindCSS with clsx and tw-merge
• Path Aliases: Use @components/*, @hooks/*, etc.
• State: Use appropriate state pattern (local, context, etc.)
• i18n: Use useTranslation for all user-facing text

Component Architecture

File Organization

src/components/
├── common/              # Shared components (Button, Modal, etc.)
├── layout/              # Layout components (Header, Sidebar, etc.)
├── subtitle/            # Subtitle-related components
├── settings/            # Settings components
├── workspace/           # Workspace components
└── [feature]/           # Feature-specific components

Naming Conventions

• Components: PascalCase – SubtitleEditor.tsx
• Hooks: camelCase with use prefix – useSubtitleParser.ts
• Utils: camelCase – formatTimestamp.ts

Core Principles

1. Always Use Path Aliases

// ❌ NEVER: Relative paths
import { Button } from '../../components/common/Button';

// ✅ ALWAYS: Path aliases
import { Button } from '@components/common/Button';
import { useWorkspace } from '@hooks/useWorkspace';
import { SubtitleEntry } from '@types/subtitle';

2. Define Props Interface

// ✅ ALWAYS: Clear prop types
interface SubtitleEditorProps {
  entries: SubtitleEntry[];
  onUpdate: (index: number, entry: SubtitleEntry) => void;
  isReadOnly?: boolean;
}

export function SubtitleEditor({ entries, onUpdate, isReadOnly = false }: SubtitleEditorProps) {
  // ...
}

3. Use TailwindCSS with clsx

import { clsx } from 'clsx';
import { twMerge } from 'tailwind-merge';

// ✅ Conditional classes
<div className={twMerge(clsx(
  'rounded-lg p-4',
  isActive && 'bg-blue-500 text-white',
  isDisabled && 'opacity-50 cursor-not-allowed'
))}>

4. Use i18n for All Text

import { useTranslation } from 'react-i18next';

export function SettingsPanel() {
  const { t } = useTranslation();

  return (
    <h1>{t('settings.title')}</h1>
  );
}

Resource Files

For detailed guidelines, see the resources directory:

• component-patterns.md – Component design patterns
• styling-guide.md – TailwindCSS styling patterns
• hooks-patterns.md – Custom hooks patterns
• performance.md – Performance optimization