tiny-sprite/docs/plans/2026-01-05-sprite-library-design.md

Tiny Sprites - Design

A CSS-based sprite library for Hono JSX with a dev tool for tuning animations.

Sprite Component

API

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:

<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

{
  "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.