Corey Johnson
63b72079ea
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>
139 lines
2.9 KiB
Markdown
139 lines
2.9 KiB
Markdown
# 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.
|