This Claude skill streamlines React UI development by enforcing industry-standard patterns and project-specific conventions. It optimizes the creation and maintenance of functional components, ensuring consistent state management, JSDoc documentation, and high-performance rendering logic within JSX environments.

When should I use react-ui?

react-ui is useful in the following scenarios: • Scenario 1: Generating standardized React functional components with integrated JSDoc for robust prop-type definition and documentation. • Scenario 2: Implementing performance optimizations using useMemo, useCallback, and React.memo to ensure smooth 60fps UI updates in complex applications. • Scenario 3: Refactoring legacy UI code into modern React architectures while adhering to specific file organization and BEM-based CSS modules. • Scenario 4: Developing isolated UI components using Ladle stories for visual testing and documentation. • Scenario 5: Debugging and optimizing state management patterns to prevent unnecessary re-renders and maintain a clean data flow between parent and child components.

name	react-ui
description	Apply React patterns and conventions when working on UI components. Use when editing files in src/ui/, creating React components, or discussing state management. Auto-apply for JSX files.

React UI Skill

This project is migrating from Canvas-only to React + Canvas (Plan 127). Apply these patterns for UI work.

Current Architecture

Debug Panel: src/ui/DebugPanel.jsx - React-based debug UI
Stories: src/stories/*.stories.jsx - Ladle for component development
Canvas: Rendering layer remains Canvas 2D

Component Patterns

Functional Components Only

// Prefer
export function DebugPanel({ gameState, onToggle }) {
  return <div>...</div>;
}

// Avoid class components

Props Interface (JSDoc since no TypeScript)

/**
 * @param {Object} props
 * @param {GameState} props.gameState - Current game state
 * @param {Function} props.onToggle - Toggle callback
 */
export function DebugPanel({ gameState, onToggle }) {

State Management

Use useState for local component state
Use useRef for mutable values that don't trigger re-render
Keep game state in parent, pass down as props

Performance (Plan 128, 129)

// Memoize expensive computations
const computedValue = useMemo(() => expensiveCalc(data), [data]);

// Memoize callbacks passed to children
const handleClick = useCallback(() => doThing(), [dependency]);

// Memoize components that receive stable props
const MemoizedChild = React.memo(ChildComponent);

File Organization

src/ui/
├── DebugPanel.jsx       # Main debug panel component
├── DebugPanel.css       # Component styles
├── DebugPanel.test.jsx  # Component tests
└── [future components]

Stories (Ladle)

Create stories for visual development:

// src/stories/ComponentName.stories.jsx
export default {
  title: 'UI/ComponentName',
};

export const Default = () => <ComponentName />;
export const WithData = () => <ComponentName data={mockData} />;

CSS Conventions

Use CSS modules or plain CSS (no CSS-in-JS currently)
Co-locate styles: Component.jsx + Component.css
Use BEM-like naming: .debug-panel__section

CSS Anti-Patterns for 60fps Updates

NEVER use CSS transitions on elements updated via requestAnimationFrame or every-frame React renders:

/* BAD - transition fights with 60fps updates, causes flickering */
.progress-fill {
  transition: stroke-dashoffset 0.1s ease-out;
}

/* GOOD - no transition for frequently-updated elements */
.progress-fill {
  /* Direct value updates, no transition */
}

When React re-renders at 60fps, CSS transitions try to animate each change over their duration. But React updates faster than the transition completes, causing visual artifacts (flickering, "tweaking out").

If smooth animation is needed, use JavaScript animation (RAF) or React Spring, not CSS transitions.

Testing React Components

// src/ui/DebugPanel.test.jsx
import { render, screen } from '@testing-library/react';
import { DebugPanel } from './DebugPanel';

describe('DebugPanel', () => {
  it('renders wave info when gameState provided', () => {
    render(<DebugPanel gameState={mockState} />);
    expect(screen.getByText(/wave height/i)).toBeInTheDocument();
  });
});

Reference Plans

plans/tooling/127-declarative-ui-layer.md - React migration
plans/tooling/128-react-performance-optimization.md - Performance
plans/tooling/129-react-18-concurrent-migration.md - React 18 features

react-ui

When & Why to Use This Skill

Use Cases