@react-chess-tools/react-chess-puzzle 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @react-chess-tools/react-chess-puzzle
 
+## 1.0.5
+
+### Patch Changes
+
+- 5b74626: docs: add comprehensive documentation and Storybook redesign
+- Updated dependencies [5b74626]
+  - @react-chess-tools/react-chess-game@1.0.4
+
+## 1.0.4
+
+### Patch Changes
+
+- e678d58: chore: update dependencies
+- Updated dependencies [1c4f876]
+- Updated dependencies [e678d58]
+  - @react-chess-tools/react-chess-game@1.0.3
+
 ## 1.0.3
 
 ### Patch Changes

package/README.md

@@ -45,6 +45,44 @@
 - **TypeScript** - Full TypeScript support with comprehensive type definitions
 - **Multiple solutions** - Accept any checkmate as a solution (configurable via `solveOnCheckmate`)
 
+## Styling
+
+All components accept standard HTML attributes (`className`, `style`, `id`, `data-*`, `aria-*`), making them compatible with any CSS approach:
+
+### Tailwind CSS
+
+```tsx
+const puzzle = {
+  fen: "r1bqkbnr/pppp1ppp/2n5/4p3/4P3/5N2/PPPP1PPP/RNBQKB1R w KQkq - 2 3",
+  moves: ["d2d4", "e5d4", "f3d4"],
+  makeFirstMove: false,
+};
+
+<ChessPuzzle.Root puzzle={puzzle}>
+  <ChessPuzzle.Board className="rounded-lg shadow-lg" />
+  <div className="flex gap-2 mt-4">
+    <ChessPuzzle.Reset className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600">
+      Try Again
+    </ChessPuzzle.Reset>
+    <ChessPuzzle.Hint className="px-4 py-2 bg-gray-200 rounded hover:bg-gray-300">
+      Show Hint
+    </ChessPuzzle.Hint>
+  </div>
+</ChessPuzzle.Root>;
+```
+
+### CSS Modules
+
+```tsx
+import styles from "./Puzzle.module.css";
+
+<ChessPuzzle.Board className={styles.board} />;
+```
+
+### Custom Theme
+
+See the [ChessPuzzle.Root props](#chesspuzzleroot) for the `theme` prop to customize puzzle-specific colors (success, failure, hint).
+
 ## Installation
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-chess-tools/react-chess-puzzle",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "A lightweight, customizable React component library for rendering and interacting with chess puzzles.",
   "type": "module",
   "exports": {
@@ -42,7 +42,7 @@
   "license": "MIT",
   "dependencies": {
     "@radix-ui/react-slot": "^1.2.4",
-    "@react-chess-tools/react-chess-game": "1.0.2",
+    "@react-chess-tools/react-chess-game": "1.0.4",
     "chess.js": "^1.4.0",
     "lodash": "^4.17.21"
   },

package/src/components/ChessPuzzle/ChessPuzzle.stories.tsx

@@ -1,9 +1,16 @@
-import type { Meta } from "@storybook/react";
+import type { Meta } from "@storybook/react-vite";
 
 import React from "react";
 import { RootProps } from "./parts/Root";
 import { ChessPuzzle } from ".";
 import { ChessGame } from "@react-chess-tools/react-chess-game";
+import {
+  StoryHeader,
+  StoryContainer,
+  BoardWrapper,
+  Kbd,
+  Button,
+} from "@story-helpers";
 
 const puzzles = [
   {
@@ -18,108 +25,8 @@ const puzzles = [
   },
 ];
 
-// ============================================================================
-// Shared Story Styles
-// ============================================================================
-const storyStyles = {
-  container: {
-    display: "flex",
-    flexDirection: "column" as const,
-    alignItems: "center",
-    gap: "20px",
-    padding: "24px",
-    backgroundColor: "#f8f9fa",
-    borderRadius: "12px",
-    maxWidth: "500px",
-    margin: "0 auto",
-  },
-  header: {
-    display: "flex",
-    flexDirection: "column" as const,
-    alignItems: "center",
-    gap: "8px",
-  },
-  title: {
-    fontSize: "22px",
-    fontWeight: 700,
-    color: "#2c3e50",
-    margin: 0,
-    textAlign: "center" as const,
-  },
-  subtitle: {
-    fontSize: "14px",
-    color: "#6c757d",
-    margin: 0,
-    textAlign: "center" as const,
-  },
-  boardWrapper: {
-    backgroundColor: "#fff",
-    padding: "16px",
-    borderRadius: "10px",
-    boxShadow: "0 2px 12px rgba(0,0,0,0.08)",
-  },
-  controlsSection: {
-    display: "flex",
-    gap: "10px",
-    justifyContent: "center",
-    flexWrap: "wrap" as const,
-  },
-  button: {
-    padding: "10px 20px",
-    fontSize: "14px",
-    fontWeight: 600,
-    cursor: "pointer",
-    border: "none",
-    borderRadius: "8px",
-    backgroundColor: "#fff",
-    boxShadow: "0 2px 6px rgba(0,0,0,0.08)",
-    color: "#495057",
-    transition: "all 0.2s ease",
-  } as React.CSSProperties,
-  buttonPrimary: {
-    backgroundColor: "#4dabf7",
-    color: "#fff",
-    boxShadow: "0 2px 6px rgba(77, 171, 247, 0.3)",
-  } as React.CSSProperties,
-  buttonSuccess: {
-    backgroundColor: "#51cf66",
-    color: "#fff",
-    boxShadow: "0 2px 6px rgba(81, 207, 102, 0.3)",
-  } as React.CSSProperties,
-  hintButton: {
-    padding: "8px 16px",
-    fontSize: "13px",
-    fontWeight: 500,
-    cursor: "pointer",
-    border: "1px dashed #adb5bd",
-    borderRadius: "8px",
-    backgroundColor: "transparent",
-    color: "#868e96",
-  } as React.CSSProperties,
-  infoBox: {
-    padding: "12px 16px",
-    backgroundColor: "#e7f5ff",
-    borderRadius: "8px",
-    fontSize: "13px",
-    color: "#1864ab",
-    textAlign: "center" as const,
-  },
-  statusBadge: {
-    display: "inline-flex",
-    alignItems: "center",
-    gap: "6px",
-    padding: "6px 14px",
-    fontSize: "12px",
-    fontWeight: 600,
-    backgroundColor: "#e9ecef",
-    borderRadius: "20px",
-    color: "#495057",
-  },
-};
-
-// More on how to set up stories at: https://storybook.js.org/docs/react/writing-stories/introduction
 const meta = {
-  title: "react-chess-puzzle/Components/Puzzle",
+  title: "Packages/react-chess-puzzle/ChessPuzzle",
   component: ChessPuzzle.Root,
   tags: ["components", "puzzle"],
   argTypes: {
@@ -127,51 +34,44 @@ const meta = {
     onFail: { action: "onFail" },
   },
   parameters: {
-    actions: { argTypesRegex: "^_on.*" },
     layout: "centered",
   },
 } satisfies Meta<typeof ChessPuzzle.Root>;
 
 export default meta;
 
-// More on writing stories with args: https://storybook.js.org/docs/react/writing-stories/args
-
 export const Example = (args: RootProps) => {
   const [puzzleIndex, setPuzzleIndex] = React.useState(0);
   const puzzle = puzzles[puzzleIndex];
   return (
     <ChessPuzzle.Root {...args} puzzle={puzzle}>
-      <div style={storyStyles.container}>
-        <div style={storyStyles.header}>
-          <h3 style={storyStyles.title}>Chess Puzzle</h3>
-          <p style={storyStyles.subtitle}>Find the best move sequence</p>
-          <span style={storyStyles.statusBadge}>
-            Puzzle {puzzleIndex + 1} of {puzzles.length}
-          </span>
-        </div>
-        <div style={storyStyles.boardWrapper}>
+      <StoryContainer>
+        <StoryHeader
+          title="Chess Puzzle"
+          subtitle="Find the best move sequence"
+        />
+        <span className="inline-flex items-center gap-1.5 px-3.5 py-1.5 text-size-xs font-semibold bg-surface-alt rounded-full text-text-secondary">
+          Puzzle {puzzleIndex + 1} of {puzzles.length}
+        </span>
+        <BoardWrapper>
           <ChessPuzzle.Board />
-        </div>
-        <div style={storyStyles.controlsSection}>
+        </BoardWrapper>
+        <div className="flex gap-2.5 justify-center flex-wrap">
           <ChessPuzzle.Reset asChild>
-            <button style={storyStyles.button}>Restart</button>
+            <Button variant="outline">Restart</Button>
           </ChessPuzzle.Reset>
           <ChessPuzzle.Reset
             asChild
             puzzle={puzzles[(puzzleIndex + 1) % puzzles.length]}
             onReset={() => setPuzzleIndex((puzzleIndex + 1) % puzzles.length)}
           >
-            <button
-              style={{ ...storyStyles.button, ...storyStyles.buttonPrimary }}
-            >
-              Next Puzzle
-            </button>
+            <Button variant="default">Next Puzzle</Button>
           </ChessPuzzle.Reset>
-          <ChessPuzzle.Hint style={storyStyles.hintButton}>
-            💡 Hint
+          <ChessPuzzle.Hint asChild>
+            <Button variant="outline">Hint</Button>
           </ChessPuzzle.Hint>
         </div>
-      </div>
+      </StoryContainer>
     </ChessPuzzle.Root>
   );
 };
@@ -184,25 +84,23 @@ export const WithOrientation = (args: RootProps) => {
   };
   return (
     <ChessPuzzle.Root {...args} puzzle={puzzle}>
-      <div style={storyStyles.container}>
-        <div style={storyStyles.header}>
-          <h3 style={storyStyles.title}>Black to Move</h3>
-          <p style={storyStyles.subtitle}>
-            Board oriented from Black's perspective
-          </p>
-        </div>
-        <div style={storyStyles.boardWrapper}>
+      <StoryContainer>
+        <StoryHeader
+          title="Black to Move"
+          subtitle="Board oriented from Black's perspective"
+        />
+        <BoardWrapper>
           <ChessPuzzle.Board options={{ boardOrientation: "black" }} />
-        </div>
-        <div style={storyStyles.controlsSection}>
+        </BoardWrapper>
+        <div className="flex gap-2.5 justify-center flex-wrap">
           <ChessPuzzle.Reset asChild>
-            <button style={storyStyles.button}>Restart</button>
+            <Button variant="outline">Restart</Button>
           </ChessPuzzle.Reset>
-          <ChessPuzzle.Hint style={storyStyles.hintButton}>
-            💡 Hint
+          <ChessPuzzle.Hint asChild>
+            <Button variant="outline">Hint</Button>
           </ChessPuzzle.Hint>
         </div>
-      </div>
+      </StoryContainer>
     </ChessPuzzle.Root>
   );
 };
@@ -215,29 +113,23 @@ export const Underpromotion = (args: RootProps) => {
   };
   return (
     <ChessPuzzle.Root {...args} puzzle={puzzle}>
-      <div style={storyStyles.container}>
-        <div style={storyStyles.header}>
-          <h3 style={storyStyles.title}>Underpromotion Challenge</h3>
-          <p style={storyStyles.subtitle}>
-            Promote to a knight instead of a queen
-          </p>
-        </div>
-        <div style={storyStyles.boardWrapper}>
+      <StoryContainer>
+        <StoryHeader
+          title="Underpromotion Challenge"
+          subtitle="Promote to a knight instead of a queen"
+        />
+        <BoardWrapper>
           <ChessPuzzle.Board />
-        </div>
-        <div style={storyStyles.controlsSection}>
+        </BoardWrapper>
+        <div className="flex gap-2.5 justify-center flex-wrap">
           <ChessPuzzle.Reset asChild>
-            <button
-              style={{ ...storyStyles.button, ...storyStyles.buttonSuccess }}
-            >
-              ✓ Solved! Restart
-            </button>
+            <Button variant="default">Solved! Restart</Button>
           </ChessPuzzle.Reset>
         </div>
-        <div style={storyStyles.infoBox}>
+        <div className="px-4 py-3 bg-info border border-info-border rounded-md text-size-sm text-info-text text-center">
           Sometimes promoting to a knight is better than a queen!
         </div>
-      </div>
+      </StoryContainer>
     </ChessPuzzle.Root>
   );
 };
@@ -246,18 +138,18 @@ export const WithSounds = (args: RootProps) => {
   return (
     <ChessPuzzle.Root {...args} puzzle={puzzles[0]}>
       <ChessGame.Sounds />
-      <div style={storyStyles.container}>
-        <div style={storyStyles.header}>
-          <h3 style={storyStyles.title}>Puzzle with Sound</h3>
-          <p style={storyStyles.subtitle}>Audio feedback on every move</p>
-        </div>
-        <div style={storyStyles.boardWrapper}>
+      <StoryContainer>
+        <StoryHeader
+          title="Puzzle with Sound"
+          subtitle="Audio feedback on every move"
+        />
+        <BoardWrapper>
           <ChessPuzzle.Board />
-        </div>
-        <p style={{ fontSize: "12px", color: "#868e96", textAlign: "center" }}>
+        </BoardWrapper>
+        <p className="text-size-xs text-text-muted text-center m-0">
           Move pieces to hear different sounds
         </p>
-      </div>
+      </StoryContainer>
     </ChessPuzzle.Root>
   );
 };
@@ -274,186 +166,64 @@ export const WithKeyboardControls = (args: RootProps) => {
           d: (context) => context.methods.goToNextMove(),
         }}
       />
-      <div style={storyStyles.container}>
-        <div style={storyStyles.header}>
-          <h3 style={storyStyles.title}>Keyboard Navigation</h3>
-          <p style={storyStyles.subtitle}>Use keyboard shortcuts to navigate</p>
-        </div>
-        <div style={storyStyles.boardWrapper}>
+      <StoryContainer>
+        <StoryHeader
+          title="Keyboard Navigation"
+          subtitle="Use keyboard shortcuts to navigate"
+        />
+        <BoardWrapper>
           <ChessPuzzle.Board />
-        </div>
-        <div
-          style={{
-            display: "grid",
-            gridTemplateColumns: "repeat(3, auto)",
-            gap: "8px",
-            justifyContent: "center",
-            marginTop: "12px",
-          }}
-        >
-          <div
-            style={{
-              display: "flex",
-              alignItems: "center",
-              gap: "6px",
-              fontSize: "12px",
-              color: "#495057",
-            }}
-          >
-            <kbd
-              style={{
-                padding: "2px 8px",
-                backgroundColor: "#e9ecef",
-                border: "1px solid #ced4da",
-                borderRadius: "4px",
-                fontFamily: "monospace",
-                fontSize: "11px",
-                fontWeight: 600,
-              }}
-            >
-              W
-            </kbd>{" "}
-            Start
+        </BoardWrapper>
+        <div className="grid grid-cols-3 gap-2 justify-center mt-3">
+          <div className="flex items-center gap-1.5 text-size-xs text-text">
+            <Kbd>W</Kbd> Start
           </div>
-          <div
-            style={{
-              display: "flex",
-              alignItems: "center",
-              gap: "6px",
-              fontSize: "12px",
-              color: "#495057",
-            }}
-          >
-            <kbd
-              style={{
-                padding: "2px 8px",
-                backgroundColor: "#e9ecef",
-                border: "1px solid #ced4da",
-                borderRadius: "4px",
-                fontFamily: "monospace",
-                fontSize: "11px",
-                fontWeight: 600,
-              }}
-            >
-              A
-            </kbd>{" "}
-            Previous
+          <div className="flex items-center gap-1.5 text-size-xs text-text">
+            <Kbd>A</Kbd> Previous
           </div>
-          <div
-            style={{
-              display: "flex",
-              alignItems: "center",
-              gap: "6px",
-              fontSize: "12px",
-              color: "#495057",
-            }}
-          >
-            <kbd
-              style={{
-                padding: "2px 8px",
-                backgroundColor: "#e9ecef",
-                border: "1px solid #ced4da",
-                borderRadius: "4px",
-                fontFamily: "monospace",
-                fontSize: "11px",
-                fontWeight: 600,
-              }}
-            >
-              F
-            </kbd>{" "}
-            Flip
+          <div className="flex items-center gap-1.5 text-size-xs text-text">
+            <Kbd>F</Kbd> Flip
           </div>
-          <div
-            style={{
-              display: "flex",
-              alignItems: "center",
-              gap: "6px",
-              fontSize: "12px",
-              color: "#495057",
-            }}
-          >
-            <kbd
-              style={{
-                padding: "2px 8px",
-                backgroundColor: "#e9ecef",
-                border: "1px solid #ced4da",
-                borderRadius: "4px",
-                fontFamily: "monospace",
-                fontSize: "11px",
-                fontWeight: 600,
-              }}
-            >
-              S
-            </kbd>{" "}
-            End
+          <div className="flex items-center gap-1.5 text-size-xs text-text">
+            <Kbd>S</Kbd> End
           </div>
-          <div
-            style={{
-              display: "flex",
-              alignItems: "center",
-              gap: "6px",
-              fontSize: "12px",
-              color: "#495057",
-            }}
-          >
-            <kbd
-              style={{
-                padding: "2px 8px",
-                backgroundColor: "#e9ecef",
-                border: "1px solid #ced4da",
-                borderRadius: "4px",
-                fontFamily: "monospace",
-                fontSize: "11px",
-                fontWeight: 600,
-              }}
-            >
-              D
-            </kbd>{" "}
-            Next
+          <div className="flex items-center gap-1.5 text-size-xs text-text">
+            <Kbd>D</Kbd> Next
           </div>
         </div>
-      </div>
+      </StoryContainer>
     </ChessPuzzle.Root>
   );
 };
 
-// Puzzle with multiple checkmate solutions for testing solveOnCheckmate prop
 const multiMatePuzzle = {
   fen: "7k/R7/1R6/2Q5/4Q3/8/8/7K w - - 0 1",
-  moves: ["a7a8"], // Canonical solution
+  moves: ["a7a8"],
   makeFirstMove: false,
 };
 
 export const MultiMatePuzzle = (args: RootProps) => {
   return (
     <ChessPuzzle.Root {...args} puzzle={multiMatePuzzle}>
-      <div style={storyStyles.container}>
-        <div style={storyStyles.header}>
-          <h3 style={storyStyles.title}>Flexible Checkmate</h3>
-          <p style={storyStyles.subtitle}>
-            Any checkmate move solves the puzzle
-          </p>
-        </div>
-        <div
-          style={{
-            ...storyStyles.infoBox,
-            backgroundColor: "#d3f9d8",
-            color: "#2b8a3e",
-          }}
-        >
+      <StoryContainer>
+        <StoryHeader
+          title="Flexible Checkmate"
+          subtitle="Any checkmate move solves the puzzle"
+        />
+        <div className="px-4 py-3 bg-success-bg border border-success rounded-md text-size-sm text-success-text text-center">
           <strong>solveOnCheckmate=true (default)</strong>
           <br />
           Try Qc8#, Qf8#, Rb8#, or the canonical Ra8#
         </div>
-        <div style={storyStyles.boardWrapper}>
+        <BoardWrapper>
           <ChessPuzzle.Board />
-        </div>
-        <div style={storyStyles.controlsSection}>
+        </BoardWrapper>
+        <div className="flex gap-2.5 justify-center flex-wrap">
           <ChessPuzzle.Reset asChild>
-            <button style={storyStyles.button}>Restart</button>
+            <Button variant="outline">Restart</Button>
           </ChessPuzzle.Reset>
         </div>
-      </div>
+      </StoryContainer>
     </ChessPuzzle.Root>
   );
 };
@@ -465,33 +235,25 @@ export const MultiMatePuzzleStrict = (args: RootProps) => {
       puzzle={multiMatePuzzle}
       solveOnCheckmate={false}
     >
-      <div style={storyStyles.container}>
-        <div style={storyStyles.header}>
-          <h3 style={storyStyles.title}>Strict Checkmate</h3>
-          <p style={storyStyles.subtitle}>
-            Only the canonical solution is accepted
-          </p>
-        </div>
-        <div
-          style={{
-            ...storyStyles.infoBox,
-            backgroundColor: "#ffe3e3",
-            color: "#c92a2a",
-          }}
-        >
+      <StoryContainer>
+        <StoryHeader
+          title="Strict Checkmate"
+          subtitle="Only the canonical solution is accepted"
+        />
+        <div className="px-4 py-3 bg-danger-bg border border-danger rounded-md text-size-sm text-danger-text text-center">
           <strong>solveOnCheckmate=false</strong>
           <br />
           Only Ra8# is accepted. Alternative mates like Qc8# will fail!
         </div>
-        <div style={storyStyles.boardWrapper}>
+        <BoardWrapper>
           <ChessPuzzle.Board />
-        </div>
-        <div style={storyStyles.controlsSection}>
+        </BoardWrapper>
+        <div className="flex gap-2.5 justify-center flex-wrap">
           <ChessPuzzle.Reset asChild>
-            <button style={storyStyles.button}>Restart</button>
+            <Button variant="outline">Restart</Button>
           </ChessPuzzle.Reset>
         </div>
-      </div>
+      </StoryContainer>
     </ChessPuzzle.Root>
   );
 };

package/src/components/ChessPuzzle/ThemePuzzle.stories.tsx

@@ -1,21 +1,22 @@
-import type { Meta } from "@storybook/react";
+import type { Meta } from "@storybook/react-vite";
 import React, { useState } from "react";
 import { ChessPuzzle } from "./index";
 import { defaultPuzzleTheme } from "../../theme/defaults";
 import type { ChessPuzzleTheme } from "../../theme/types";
+import { ColorInput, copyToClipboard } from "@story-helpers";
 
-const meta = {
-  title: "react-chess-puzzle/Theme/Playground",
+const meta: Meta<typeof ChessPuzzle.Root> = {
+  title: "Packages/react-chess-puzzle/Theming/Playground",
   component: ChessPuzzle.Root,
   tags: ["theme", "puzzle"],
   decorators: [
     (Story) => (
-      <div style={{ maxWidth: "900px" }}>
+      <div className="max-w-story-xl">
         <Story />
       </div>
     ),
   ],
-} satisfies Meta<typeof ChessPuzzle.Root>;
+};
 
 export default meta;
 
@@ -25,60 +26,10 @@ const samplePuzzle = {
   makeFirstMove: false,
 };
 
-// Color picker component
-const ColorInput: React.FC<{
-  label: string;
-  value: string;
-  onChange: (value: string) => void;
-}> = ({ label, value, onChange }) => {
-  const rgbaToHex = (rgba: string): string => {
-    const match = rgba.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/);
-    if (match) {
-      const r = parseInt(match[1]).toString(16).padStart(2, "0");
-      const g = parseInt(match[2]).toString(16).padStart(2, "0");
-      const b = parseInt(match[3]).toString(16).padStart(2, "0");
-      return `#${r}${g}${b}`;
-    }
-    return value.startsWith("#") ? value : "#000000";
-  };
-
-  const hexToRgba = (hex: string, alpha: number = 0.5): string => {
-    const r = parseInt(hex.slice(1, 3), 16);
-    const g = parseInt(hex.slice(3, 5), 16);
-    const b = parseInt(hex.slice(5, 7), 16);
-    return `rgba(${r}, ${g}, ${b}, ${alpha})`;
-  };
-
-  return (
-    <div
-      style={{
-        display: "flex",
-        alignItems: "center",
-        gap: "8px",
-        marginBottom: "8px",
-      }}
-    >
-      <input
-        type="color"
-        value={rgbaToHex(value)}
-        onChange={(e) => onChange(hexToRgba(e.target.value))}
-        style={{ width: "40px", height: "30px", cursor: "pointer" }}
-      />
-      <span style={{ fontSize: "12px", minWidth: "100px" }}>{label}</span>
-      <input
-        type="text"
-        value={value}
-        onChange={(e) => onChange(e.target.value)}
-        style={{ fontSize: "11px", width: "180px", padding: "4px" }}
-      />
-    </div>
-  );
-};
-
 export const PuzzlePlayground = () => {
   const [theme, setTheme] = useState<ChessPuzzleTheme>(defaultPuzzleTheme);
   const [copied, setCopied] = useState(false);
-  const [puzzleKey, setPuzzleKey] = useState(0);
+  const [copyError, setCopyError] = useState(false);
 
   const updatePuzzleColor = (
     key: keyof ChessPuzzleTheme["puzzle"],
@@ -93,105 +44,109 @@ export const PuzzlePlayground = () => {
     }));
   };
 
-  const copyTheme = () => {
-    const themeCode = `const myPuzzleTheme: PartialChessPuzzleTheme = {
+  const themeCode = `const myPuzzleTheme: PartialChessPuzzleTheme = {
   puzzle: ${JSON.stringify(theme.puzzle, null, 4)}
 };`;
-    navigator.clipboard.writeText(themeCode);
-    setCopied(true);
-    setTimeout(() => setCopied(false), 2000);
-  };
 
-  const resetPuzzle = () => {
-    setPuzzleKey((k) => k + 1);
+  const handleCopy = async () => {
+    const success = await copyToClipboard(themeCode);
+    if (success) {
+      setCopied(true);
+      setCopyError(false);
+      setTimeout(() => setCopied(false), 2000);
+    } else {
+      setCopyError(true);
+      setTimeout(() => setCopyError(false), 3000);
+    }
   };
 
   return (
-    <div style={{ display: "flex", gap: "24px", flexWrap: "wrap" }}>
-      <div style={{ flex: "1", minWidth: "300px" }}>
-        <h3 style={{ marginBottom: "16px" }}>Puzzle Theme Editor</h3>
-
-        <div style={{ marginBottom: "16px" }}>
-          <strong>Puzzle Colors</strong>
-          <div style={{ marginTop: "8px" }}>
-            <ColorInput
-              label="Success"
-              value={theme.puzzle.success}
-              onChange={(v) => updatePuzzleColor("success", v)}
-            />
-            <ColorInput
-              label="Failure"
-              value={theme.puzzle.failure}
-              onChange={(v) => updatePuzzleColor("failure", v)}
-            />
-            <ColorInput
-              label="Hint"
-              value={theme.puzzle.hint}
-              onChange={(v) => updatePuzzleColor("hint", v)}
-            />
+    <div className="flex flex-col gap-6 font-sans">
+      {/* Top row: Preview + Controls */}
+      <div className="flex gap-6 items-start">
+        {/* Preview */}
+        <div className="flex flex-col gap-2">
+          <h3 className="text-size-sm font-semibold text-text">Preview</h3>
+          <div className="max-w-story-lg">
+            <ChessPuzzle.Root puzzle={samplePuzzle} theme={theme}>
+              <ChessPuzzle.Board />
+              <div className="mt-2 flex gap-2">
+                <ChessPuzzle.Hint asChild>
+                  <button className="py-1 px-3 text-size-xs border border-border rounded bg-surface hover:bg-surface-alt">
+                    Hint
+                  </button>
+                </ChessPuzzle.Hint>
+                <ChessPuzzle.Reset asChild>
+                  <button className="py-1 px-3 text-size-xs border border-border rounded bg-surface hover:bg-surface-alt">
+                    Reset
+                  </button>
+                </ChessPuzzle.Reset>
+              </div>
+            </ChessPuzzle.Root>
           </div>
+          <p className="text-size-xs text-text-muted">
+            Solution: Bxd7+, Nxd7, Qb8+, Nxb8, Rd8#
+          </p>
         </div>
 
-        <div style={{ display: "flex", gap: "8px", marginBottom: "16px" }}>
-          <button
-            onClick={copyTheme}
-            style={{
-              padding: "8px 16px",
-              backgroundColor: copied ? "#4caf50" : "#2196f3",
-              color: "white",
-              border: "none",
-              borderRadius: "4px",
-              cursor: "pointer",
-            }}
-          >
-            {copied ? "Copied!" : "Copy Theme Code"}
-          </button>
-          <button
-            onClick={resetPuzzle}
-            style={{
-              padding: "8px 16px",
-              backgroundColor: "#666",
-              color: "white",
-              border: "none",
-              borderRadius: "4px",
-              cursor: "pointer",
-            }}
-          >
-            Reset Puzzle
-          </button>
-        </div>
+        {/* Controls */}
+        <div className="flex flex-col gap-3 flex-1">
+          <h3 className="text-size-sm font-semibold text-text">
+            Puzzle Colors
+          </h3>
+
+          <div className="p-3 bg-surface-alt rounded border border-border">
+            <div className="space-y-2">
+              <ColorInput
+                label="Success"
+                value={theme.puzzle.success}
+                onChange={(v) => updatePuzzleColor("success", v)}
+              />
+              <ColorInput
+                label="Failure"
+                value={theme.puzzle.failure}
+                onChange={(v) => updatePuzzleColor("failure", v)}
+              />
+              <ColorInput
+                label="Hint"
+                value={theme.puzzle.hint}
+                onChange={(v) => updatePuzzleColor("hint", v)}
+              />
+            </div>
+          </div>
 
-        <div style={{ fontSize: "12px", color: "#666" }}>
-          <p>
-            <strong>How to test colors:</strong>
-          </p>
-          <ul style={{ paddingLeft: "16px" }}>
-            <li>Click "Hint" to see the hint color</li>
-            <li>Make a correct move to see success color</li>
-            <li>Make a wrong move to see failure color</li>
-            <li>Click "Reset" to try again</li>
-          </ul>
+          <div className="p-3 bg-surface-alt rounded border border-border text-size-xs text-text-muted">
+            <p className="font-semibold text-text mb-2">How to test:</p>
+            <ul className="pl-4 space-y-1">
+              <li>Click "Hint" to see the hint color</li>
+              <li>Make a correct move to see success color</li>
+              <li>Make a wrong move to see failure color</li>
+            </ul>
+          </div>
         </div>
       </div>
 
-      <div style={{ flex: "1", minWidth: "350px" }}>
-        <h3 style={{ marginBottom: "16px" }}>Preview</h3>
-        <div style={{ maxWidth: "400px" }}>
-          <ChessPuzzle.Root key={puzzleKey} puzzle={samplePuzzle} theme={theme}>
-            <ChessPuzzle.Board />
-            <div style={{ marginTop: "8px", display: "flex", gap: "8px" }}>
-              <ChessPuzzle.Hint asChild>
-                <button style={{ padding: "6px 12px" }}>Hint</button>
-              </ChessPuzzle.Hint>
-              <ChessPuzzle.Reset asChild>
-                <button style={{ padding: "6px 12px" }}>Reset</button>
-              </ChessPuzzle.Reset>
-            </div>
-          </ChessPuzzle.Root>
+      {/* Bottom: Generated Code */}
+      <div className="flex flex-col gap-2">
+        <h3 className="text-size-sm font-semibold text-text">Generated Code</h3>
+        <div className="relative">
+          <pre className="text-size-xs font-mono bg-surface-alt p-4 rounded border border-border overflow-auto text-text">
+            {themeCode}
+          </pre>
+          <button
+            onClick={handleCopy}
+            className={`absolute top-3 right-3 px-2 py-1 text-size-xs rounded ${
+              copyError
+                ? "bg-danger text-white"
+                : copied
+                  ? "bg-success text-white"
+                  : "bg-accent text-white hover:opacity-90"
+            }`}
+            aria-label="Copy theme code"
+          >
+            {copyError ? "Failed" : copied ? "Copied!" : "Copy"}
+          </button>
         </div>
-        <p style={{ fontSize: "12px", color: "#666", marginTop: "8px" }}>
-          Solution: Bxd7+, Nxd7, Qb8+, Nxb8, Rd8#
-        </p>
       </div>
     </div>
   );
@@ -219,30 +174,22 @@ export const PuzzleThemeExamples = () => {
   };
 
   return (
-    <div>
-      <h2 style={{ marginBottom: "24px" }}>Puzzle Theme Examples</h2>
-      <div
-        style={{
-          display: "grid",
-          gridTemplateColumns: "repeat(auto-fit, minmax(300px, 1fr))",
-          gap: "24px",
-        }}
-      >
+    <div className="font-sans">
+      <h2 className="mb-6">Puzzle Theme Examples</h2>
+      <div className="grid grid-cols-[repeat(auto-fit,minmax(300px,1fr))] gap-6">
         {Object.entries(customThemes).map(([name, theme]) => (
           <div key={name}>
-            <h4 style={{ marginBottom: "8px", textTransform: "capitalize" }}>
-              {name}
-            </h4>
+            <h4 className="mb-2 capitalize">{name}</h4>
             <ChessPuzzle.Root puzzle={samplePuzzle} theme={theme}>
               <ChessPuzzle.Board />
-              <div style={{ marginTop: "8px", display: "flex", gap: "8px" }}>
+              <div className="mt-2 flex gap-2">
                 <ChessPuzzle.Hint asChild>
-                  <button style={{ padding: "4px 8px", fontSize: "12px" }}>
+                  <button className="py-1 px-2 text-size-xs border border-border rounded-sm bg-surface">
                     Hint
                   </button>
                 </ChessPuzzle.Hint>
                 <ChessPuzzle.Reset asChild>
-                  <button style={{ padding: "4px 8px", fontSize: "12px" }}>
+                  <button className="py-1 px-2 text-size-xs border border-border rounded-sm bg-surface">
                     Reset
                   </button>
                 </ChessPuzzle.Reset>
@@ -264,34 +211,31 @@ export const PartialPuzzleTheme = () => {
   };
 
   return (
-    <div style={{ maxWidth: "500px" }}>
+    <div className="max-w-story-lg font-sans">
       <h3>Partial Puzzle Theme</h3>
-      <p style={{ fontSize: "14px", color: "#666", marginBottom: "16px" }}>
+      <p className="text-size-sm text-text-muted mb-4 m-0">
         Only override the hint color to gold. Success and failure use defaults.
       </p>
       <ChessPuzzle.Root puzzle={samplePuzzle} theme={partialTheme}>
         <ChessPuzzle.Board />
-        <div style={{ marginTop: "8px", display: "flex", gap: "8px" }}>
+        <div className="mt-2 flex gap-2">
           <ChessPuzzle.Hint asChild>
-            <button style={{ padding: "6px 12px" }}>Show Gold Hint</button>
+            <button className="py-1.5 px-3 text-size-sm border border-border rounded-sm bg-surface">
+              Show Gold Hint
+            </button>
           </ChessPuzzle.Hint>
           <ChessPuzzle.Reset asChild>
-            <button style={{ padding: "6px 12px" }}>Reset</button>
+            <button className="py-1.5 px-3 text-size-sm border border-border rounded-sm bg-surface">
+              Reset
+            </button>
           </ChessPuzzle.Reset>
         </div>
       </ChessPuzzle.Root>
-      <details style={{ marginTop: "16px" }}>
-        <summary style={{ cursor: "pointer", fontSize: "14px" }}>
+      <details className="mt-4">
+        <summary className="cursor-pointer text-size-sm">
           View theme code
         </summary>
-        <pre
-          style={{
-            fontSize: "11px",
-            background: "#f5f5f5",
-            padding: "12px",
-            overflow: "auto",
-          }}
-        >
+        <pre className="text-size-xs bg-surface-alt p-3 overflow-auto border border-border rounded-sm">
           {JSON.stringify(partialTheme, null, 2)}
         </pre>
       </details>

package/src/docs/Theming.mdx

@@ -1,255 +0,0 @@
-{/* Theming.mdx */}
-import { Meta, ColorPalette, ColorItem } from '@storybook/blocks';
-
-<Meta title="react-chess-puzzle/Theming" />
-
-# Puzzle Theming
-
-React Chess Puzzle extends the game theming system with puzzle-specific colors for hints, success, and failure states.
-
-## Quick Start
-
-Pass a theme to `ChessPuzzle.Root` to customize puzzle appearance:
-
-```tsx
-import { ChessPuzzle } from "@react-chess-tools/react-chess-puzzle";
-
-const puzzle = {
-  fen: "4kb1r/p2r1ppp/4qn2/1B2p1B1/4P3/1Q6/PPP2PPP/2KR4 w k - 0 1",
-  moves: ["Bxd7+", "Nxd7", "Qb8+", "Nxb8", "Rd8#"],
-};
-
-function App() {
-  return (
-    <ChessPuzzle.Root
-      puzzle={puzzle}
-      theme={{ puzzle: { hint: "rgba(255, 215, 0, 0.6)" } }}
-    >
-      <ChessPuzzle.Board />
-      <ChessPuzzle.Hint>Show Hint</ChessPuzzle.Hint>
-    </ChessPuzzle.Root>
-  );
-}
-```
-
-## Puzzle Theme Structure
-
-The puzzle theme extends `ChessGameTheme` with an additional `puzzle` section:
-
-```typescript
-interface ChessPuzzleTheme extends ChessGameTheme {
-  puzzle: {
-    success: string; // Color for correct moves (RGBA)
-    failure: string; // Color for incorrect moves (RGBA)
-    hint: string; // Color for hint squares (RGBA)
-  };
-}
-```
-
-## Puzzle-Specific Colors
-
-The puzzle theme adds three new color options:
-
-<table>
-  <thead>
-    <tr>
-      <th>Color</th>
-      <th>Usage</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>
-        <code>puzzle.success</code>
-      </td>
-      <td>Highlights squares when a correct move is made</td>
-    </tr>
-    <tr>
-      <td>
-        <code>puzzle.failure</code>
-      </td>
-      <td>Highlights squares when an incorrect move is made</td>
-    </tr>
-    <tr>
-      <td>
-        <code>puzzle.hint</code>
-      </td>
-      <td>Highlights the hint square(s) when hint is requested</td>
-    </tr>
-  </tbody>
-</table>
-
-## Creating a Custom Puzzle Theme
-
-You can customize both game and puzzle colors:
-
-```tsx
-import { ChessPuzzle } from "@react-chess-tools/react-chess-puzzle";
-import type { PartialChessPuzzleTheme } from "@react-chess-tools/react-chess-puzzle";
-
-const neonTheme: PartialChessPuzzleTheme = {
-  // Customize board colors (inherited from game theme)
-  board: {
-    lightSquare: { backgroundColor: "#2a2a2a" },
-    darkSquare: { backgroundColor: "#1a1a1a" },
-  },
-  // Customize game state colors
-  state: {
-    lastMove: "rgba(0, 255, 255, 0.4)",
-  },
-  // Customize puzzle-specific colors
-  puzzle: {
-    success: "rgba(0, 255, 127, 0.6)",
-    failure: "rgba(255, 0, 127, 0.6)",
-    hint: "rgba(0, 191, 255, 0.6)",
-  },
-};
-
-function App() {
-  return (
-    <ChessPuzzle.Root puzzle={puzzle} theme={neonTheme}>
-      <ChessPuzzle.Board />
-    </ChessPuzzle.Root>
-  );
-}
-```
-
-## Partial Theme Overrides
-
-Override only the puzzle colors you need:
-
-```tsx
-// Only change the hint color to gold
-const goldHint: PartialChessPuzzleTheme = {
-  puzzle: {
-    hint: "rgba(255, 215, 0, 0.6)",
-  },
-};
-
-// Only change success/failure colors
-const customFeedback: PartialChessPuzzleTheme = {
-  puzzle: {
-    success: "rgba(0, 200, 100, 0.7)",
-    failure: "rgba(200, 0, 50, 0.7)",
-  },
-};
-```
-
-## Theme Inheritance
-
-Puzzle themes inherit all game theme properties. You can:
-
-1. **Only specify puzzle colors** - game colors use defaults
-2. **Only specify game colors** - puzzle colors use defaults
-3. **Mix both** - customize any combination
-
-```tsx
-// Example: Custom board + default puzzle colors
-const customBoard: PartialChessPuzzleTheme = {
-  board: {
-    lightSquare: { backgroundColor: "#e8e8e8" },
-    darkSquare: { backgroundColor: "#4a4a4a" },
-  },
-};
-
-// Example: Default board + custom puzzle colors
-const customPuzzle: PartialChessPuzzleTheme = {
-  puzzle: {
-    success: "rgba(100, 255, 100, 0.5)",
-    failure: "rgba(255, 100, 100, 0.5)",
-    hint: "rgba(100, 100, 255, 0.5)",
-  },
-};
-```
-
-## Using Theme Utilities
-
-### mergePuzzleTheme
-
-Merge a partial puzzle theme with defaults:
-
-```tsx
-import {
-  mergePuzzleTheme,
-  defaultPuzzleTheme,
-} from "@react-chess-tools/react-chess-puzzle";
-
-const myTheme = mergePuzzleTheme({
-  puzzle: { hint: "rgba(255, 215, 0, 0.6)" },
-});
-// myTheme is now a complete ChessPuzzleTheme
-```
-
-### useChessPuzzleTheme Hook
-
-Access the current puzzle theme from any component:
-
-```tsx
-import { useChessPuzzleTheme } from "@react-chess-tools/react-chess-puzzle";
-
-function HintButton() {
-  const theme = useChessPuzzleTheme();
-
-  return (
-    <button style={{ backgroundColor: theme.puzzle.hint }}>Show Hint</button>
-  );
-}
-```
-
-## Default Puzzle Colors
-
-<ColorPalette>
-  <ColorItem
-    title="Puzzle Colors"
-    subtitle="Puzzle state feedback"
-    colors={{
-      Success: "rgba(172, 206, 89, 0.5)",
-      Failure: "rgba(201, 52, 48, 0.5)",
-      Hint: "rgba(27, 172, 166, 0.5)",
-    }}
-  />
-</ColorPalette>
-
-## Example Theme Variations
-
-### Pastel Theme
-
-```tsx
-const pastelTheme: PartialChessPuzzleTheme = {
-  puzzle: {
-    success: "rgba(152, 251, 152, 0.6)", // Pale green
-    failure: "rgba(255, 182, 193, 0.6)", // Light pink
-    hint: "rgba(173, 216, 230, 0.6)", // Light blue
-  },
-};
-```
-
-### High Contrast Theme
-
-```tsx
-const highContrastTheme: PartialChessPuzzleTheme = {
-  puzzle: {
-    success: "rgba(0, 255, 0, 0.7)",
-    failure: "rgba(255, 0, 0, 0.7)",
-    hint: "rgba(0, 255, 255, 0.7)",
-  },
-};
-```
-
-## TypeScript Support
-
-All puzzle theme types are exported:
-
-```typescript
-import type {
-  ChessPuzzleTheme,
-  PartialChessPuzzleTheme,
-  PuzzleStateTheme,
-} from "@react-chess-tools/react-chess-puzzle";
-```
-
-## Next Steps
-
-- Try the **[Puzzle Theme Playground](/story/react-chess-puzzle-theme-playground--puzzle-playground)** to experiment with colors
-- See **[Puzzle Theme Examples](/story/react-chess-puzzle-theme-playground--puzzle-theme-examples)** for inspiration
-- Check out **[Game Theming](/docs/react-chess-game-theming--docs)** for board and state color options