@react-chess-tools/react-chess-game/src/docs/Theming.mdx

react-chess-game is a React component bridging chess.js with react-chessboard to offer a full-featured, ready-to-integrate chess board experience.

{/* Theming.mdx */}
import { Meta, ColorPalette, ColorItem } from '@storybook/blocks';

<Meta title="react-chess-game/Theming" />

# Theming

React Chess Tools provides a comprehensive theming system that allows you to customize the look and feel of your chess boards. You can customize board colors, move highlights, check indicators, and more.

## Quick Start

The simplest way to use a theme is to pass it to the `theme` prop on `ChessGame.Root`:

```tsx
import { ChessGame, themes } from "@react-chess-tools/react-chess-game";

function App() {
  return (
    <ChessGame.Root theme={themes.lichess}>
      <ChessGame.Board />
    </ChessGame.Root>
  );
}
```

## Available Preset Themes

We provide three built-in themes:

<table>
  <thead>
    <tr>
      <th>Theme</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>
        <code>themes.default</code>
      </td>
      <td>Classic brown/beige board with yellow highlights</td>
    </tr>
    <tr>
      <td>
        <code>themes.lichess</code>
      </td>
      <td>Lichess.org inspired with green highlights</td>
    </tr>
    <tr>
      <td>
        <code>themes.chessCom</code>
      </td>
      <td>Chess.com inspired with green board and yellow highlights</td>
    </tr>
  </tbody>
</table>

```tsx
import { themes } from "@react-chess-tools/react-chess-game";

// Use a preset theme
<ChessGame.Root theme={themes.lichess}>
  <ChessGame.Board />
</ChessGame.Root>;
```

## Theme Structure

A complete theme has the following structure:

```typescript
interface ChessGameTheme {
  board: {
    lightSquare: CSSProperties; // Style for light squares
    darkSquare: CSSProperties; // Style for dark squares
  };
  state: {
    lastMove: string; // Color for last move highlight (RGBA)
    check: string; // Color for check highlight (RGBA)
    activeSquare: string; // Color for selected piece (RGBA)
    dropSquare: CSSProperties; // Style for valid drop target
  };
  indicators: {
    move: string; // Color for move dot indicators (RGBA)
    capture: string; // Color for capture ring indicators (RGBA)
  };
}
```

## Creating a Custom Theme

You can create a fully custom theme by defining all properties:

```tsx
import { ChessGame } from "@react-chess-tools/react-chess-game";
import type { ChessGameTheme } from "@react-chess-tools/react-chess-game";

const darkTheme: ChessGameTheme = {
  board: {
    lightSquare: { backgroundColor: "#4a4a4a" },
    darkSquare: { backgroundColor: "#2d2d2d" },
  },
  state: {
    lastMove: "rgba(100, 150, 255, 0.5)",
    check: "rgba(255, 50, 50, 0.6)",
    activeSquare: "rgba(100, 150, 255, 0.5)",
    dropSquare: { backgroundColor: "rgba(100, 150, 255, 0.3)" },
  },
  indicators: {
    move: "rgba(200, 200, 200, 0.2)",
    capture: "rgba(255, 100, 100, 0.3)",
  },
};

function App() {
  return (
    <ChessGame.Root theme={darkTheme}>
      <ChessGame.Board />
    </ChessGame.Root>
  );
}
```

## Partial Theme Overrides

You don't need to specify all theme properties. You can override only the colors you want to change, and the rest will use the default values:

```tsx
import { ChessGame } from "@react-chess-tools/react-chess-game";
import type { PartialChessGameTheme } from "@react-chess-tools/react-chess-game";

// Only override specific colors
const customTheme: PartialChessGameTheme = {
  state: {
    lastMove: "rgba(147, 112, 219, 0.5)", // Purple
    check: "rgba(255, 165, 0, 0.6)", // Orange
  },
};

function App() {
  return (
    <ChessGame.Root theme={customTheme}>
      <ChessGame.Board />
    </ChessGame.Root>
  );
}
```

## Theme Utilities

### mergeTheme

Use `mergeTheme` to merge a partial theme with the default theme:

```tsx
import {
  mergeTheme,
  defaultGameTheme,
} from "@react-chess-tools/react-chess-game";

const myTheme = mergeTheme({
  state: { lastMove: "rgba(0, 255, 0, 0.5)" },
});
// myTheme is now a complete ChessGameTheme with only lastMove changed
```

### mergeThemeWith

Use `mergeThemeWith` to extend any base theme:

```tsx
import {
  mergeThemeWith,
  lichessTheme,
} from "@react-chess-tools/react-chess-game";

const customLichess = mergeThemeWith(lichessTheme, {
  board: {
    lightSquare: { backgroundColor: "#e8e8e8" },
  },
});
```

## Using the Theme Hook

For advanced use cases, you can access the current theme from any component inside `ChessGame.Root`:

```tsx
import { useChessGameTheme } from "@react-chess-tools/react-chess-game";

function CustomComponent() {
  const theme = useChessGameTheme();

  return (
    <div style={{ backgroundColor: theme.state.lastMove }}>
      Current last move color: {theme.state.lastMove}
    </div>
  );
}
```

## Runtime Theme Switching

Themes can be switched at runtime by updating the `theme` prop:

```tsx
import { useState } from "react";
import { ChessGame, themes } from "@react-chess-tools/react-chess-game";

function App() {
  const [currentTheme, setCurrentTheme] = useState(themes.default);

  return (
    <div>
      <ChessGame.Root theme={currentTheme}>
        <ChessGame.Board />
      </ChessGame.Root>

      <div>
        <button onClick={() => setCurrentTheme(themes.default)}>Default</button>
        <button onClick={() => setCurrentTheme(themes.lichess)}>Lichess</button>
        <button onClick={() => setCurrentTheme(themes.chessCom)}>
          Chess.com
        </button>
      </div>
    </div>
  );
}
```

## Default Theme Colors

<ColorPalette>
  <ColorItem
    title="Board Colors"
    subtitle="Light and dark squares"
    colors={{
      "Light Square": "#f0d9b5",
      "Dark Square": "#b58863",
    }}
  />
  <ColorItem
    title="State Colors"
    subtitle="Game state highlights"
    colors={{
      "Last Move": "rgba(255, 255, 0, 0.5)",
      Check: "rgba(255, 0, 0, 0.5)",
      "Active Square": "rgba(255, 255, 0, 0.5)",
      "Drop Target": "rgba(255, 255, 0, 0.4)",
    }}
  />
  <ColorItem
    title="Indicator Colors"
    subtitle="Move and capture indicators"
    colors={{
      "Move Dot": "rgba(0, 0, 0, 0.1)",
      "Capture Ring": "rgba(1, 0, 0, 0.1)",
    }}
  />
</ColorPalette>

## TypeScript Support

All theme types are fully exported for TypeScript users:

```typescript
import type {
  ChessGameTheme,
  PartialChessGameTheme,
  BoardTheme,
  StateTheme,
  IndicatorTheme,
} from "@react-chess-tools/react-chess-game";
```

## Next Steps

- Try the **[Theme Playground](/story/react-chess-game-theme-playground--playground)** to experiment with colors interactively
- See **[Theme Presets](/story/react-chess-game-theme-presets--all-presets)** for visual comparison of built-in themes
- Check out **[Puzzle Theming](/docs/react-chess-puzzle-theming--docs)** for puzzle-specific theme options