commit 63b72079ea45355b1437b6ac45f239aae3036bec
Author: Corey Johnson <probablycorey@gmail.com>
Date:   Tue Jan 6 09:42:37 2026 -0800

    Add sprite library design doc
    
    Documents the Sprite component API, CSS rendering approach,
    dev tool features, and project structure.
    
    🤖 Generated with [Claude Code](https://claude.com/claude-code)
    
    Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

diff --git a/docs/plans/2026-01-05-sprite-library-design.md b/docs/plans/2026-01-05-sprite-library-design.md
new file mode 100644
index 0000000..816df8e
--- /dev/null
+++ b/docs/plans/2026-01-05-sprite-library-design.md
@@ -0,0 +1,138 @@
+# Tiny Sprites - Design
+
+A CSS-based sprite library for Hono JSX with a dev tool for tuning animations.
+
+## Sprite Component
+
+### API
+
+```tsx
+import { Sprite } from 'tiny-sprites'
+
+<Sprite
+  src="/warrior-idle.png"
+  width={32}
+  height={32}
+  frames={6}
+  frameDuration={100}
+/>
+
+// Grid layout
+<Sprite
+  src="/character.png"
+  width={32}
+  height={32}
+  frames={12}
+  columns={4}
+  frameDuration={80}
+/>
+```
+
+### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| src | string | yes | URL to spritesheet |
+| width | number | yes | Frame width in pixels |
+| height | number | yes | Frame height in pixels |
+| frames | number | yes | Total frame count |
+| frameDuration | number | yes | Milliseconds per frame |
+| columns | number | no | Columns in grid (omit for horizontal strip) |
+| class | string | no | Pass-through CSS class |
+| style | string | no | Pass-through inline styles |
+| playing | boolean | no | Animation state, default true |
+
+### Rendering
+
+The component outputs a `<div>` with inline styles plus a `<style>` block:
+
+```html
+<div style="
+  width: 32px;
+  height: 32px;
+  background-image: url('/warrior-idle.png');
+  background-size: 192px 32px;
+  animation: sprite-abc123 600ms steps(6) infinite;
+"></div>
+
+<style>
+@keyframes sprite-abc123 {
+  from { background-position: 0 0; }
+  to { background-position: -192px 0; }
+}
+</style>
+```
+
+Keyframe names are hashed from props to avoid collisions. When `playing={false}`, sets `animation-play-state: paused`.
+
+## Dev Tool
+
+A Bun server for tuning sprite animations.
+
+### Features
+
+- Drag & drop spritesheet files
+- Form inputs: width, height, frames, columns, frameDuration
+- Live preview
+- Copy generated `<Sprite />` code
+- Download spritesheet
+
+### Routes
+
+```
+GET  /                  → UI
+POST /upload            → Accept spritesheet, return temp URL
+GET  /sprites/:filename → Serve uploaded spritesheets
+```
+
+No database. Files served from temp directory.
+
+## Project Structure
+
+```
+tiny-sprites/
+├── src/
+│   ├── sprite.tsx        # <Sprite /> component
+│   ├── hash.ts           # Hash function for keyframe names
+│   └── dev/
+│       ├── cli.ts        # CLI entry point
+│       ├── server.tsx    # Dev server (Bun.serve + Hono)
+│       ├── index.tsx     # Dev tool UI page
+│       └── preview.tsx   # Live preview component
+├── assets/               # Existing sprites
+├── docs/plans/
+├── package.json
+└── tsconfig.json
+```
+
+## Package.json
+
+```json
+{
+  "name": "tiny-sprites",
+  "type": "module",
+  "exports": {
+    ".": "./src/sprite.tsx"
+  },
+  "bin": {
+    "tiny-sprites": "src/dev/cli.ts"
+  },
+  "scripts": {
+    "dev": "bun --hot src/dev/server.tsx",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "hono": "^4"
+  },
+  "devDependencies": {
+    "bun-types": "latest"
+  }
+}
+```
+
+## Dependencies
+
+- Bun (runtime)
+- Hono (routing + JSX)
+
+No other dependencies.