---

name: react-component-dev description: React/TypeScript component development guidelines for Gemini-Subtitle-Pro. Use when creating components, pages, modals, forms, or working with TailwindCSS, hooks, and React 19 patterns. Covers component architecture, styling with Tailwind, state management, performance optimization, and accessibility.

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

Copysrc/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

Copy// ❌ 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

Copy// ✅ 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

Copyimport { 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

Copyimport { 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