spirit

AI merch design generator. Text in, print-ready apparel design out.

spirit turns short text prompts into screen-print ready apparel designs. The pipeline is garment-aware: prompts are expanded with garment context, placement geometry, and print-friendly style hints before being sent to the image provider. Outputs come back at full print resolution with transparent backgrounds.

The repo ships with both a Python backend (FastAPI) and a TypeScript React SDK so you can drop the design picker into any app.

What it does

1. User types a short prompt: "vintage skating dragon"
2. Spirit expands it: "vintage skating dragon. screen-printed t-shirt graphic. centered composition, balanced. vector style, bold lines, high contrast. transparent background. printable, no fine gradients, no photorealism"
3. Sends to the image provider with print-resolution dimensions and a tuned negative prompt
4. Returns a Design ready to be slapped on a mockup or sent to a printer

Backend (Python)

cd backend
pip install -e ".[dev]"
export REPLICATE_API_TOKEN="..."
uvicorn spirit.api.app:create_app --factory --reload

The service is now at http://localhost:8000. Swagger UI at /docs.

SDK (TypeScript / React)

cd sdk
npm install
npm run build

import { SpiritClient, useGenerate, DesignPreview } from "@spirit/sdk";

const client = new SpiritClient({ baseUrl: "http://localhost:8000" });

function App() {
  const { generate, design, loading } = useGenerate(client);
  return (
    <>
      <button onClick={() => generate({ prompt: "skating dragon", garment: "tshirt" })}>
        {loading ? "..." : "generate"}
      </button>
      <DesignPreview design={design} />
    </>
  );
}

Garments and placements

Spirit understands these garments:

tshirt, hoodie, longsleeve, crewneck, tank, cap, tote, sticker

And these placements:

front_center, front_pocket, back_center, left_chest, sleeve, hem

Each placement applies different composition hints and bleed/safe-area constraints during prompt expansion. A pocket-print and a back-print do not get the same prompt even with the same source idea.

Brand kits

A brand kit locks designs to a project's palette and style:

from spirit.storage.brand_kit import BrandKit, BrandKitStore

kit = BrandKit(
    id="bk_acme",
    name="ACME",
    palette_hex=["#000000", "#FF6B00", "#FFFFFF"],
    style_keywords=["geometric", "minimal", "industrial"],
)
BrandKitStore().save(kit)

Pass the kit id when generating and Spirit injects the kit's palette and keywords into the prompt expansion stage.

Layout

backend/
    spirit/         FastAPI service + generators + prompts
    tests/          pytest suite
sdk/
    src/            TypeScript React SDK
    tests/          vitest suite
docs/               design notes
examples/           example brand kits and config files

License

MIT.