Hand-drawn kawaii avatar engine for your app. One seed in, one deterministic avatar out. No AI, no API calls.

MIT licensed. Code and assets are both MIT. See License.

Docs

• Your app needs user avatars and you want a consistent, hand-drawn illustration style
• You want deterministic output: same seed always produces the same avatar
• You want to own the component: install from npm, or copy the source into your project

npm install @humation/react @humation/assets-humation-1

import { Avatar } from '@humation/react';
import { humation1 } from '@humation/assets-humation-1';

// Automatic — same seed always renders the same avatar
<Avatar assets={humation1} seed={user.id} size={96} />

// Manual — pick parts and colors by name
<Avatar
  assets={humation1}
  selections={{ head: 'braids', body: 'hoodie', item: 'calico-cat' }}
  colors={{ hair: '#4A3728' }}
/>

seed generates a deterministic combination from any string (user ID, email, etc.). selections lets you pick exact parts per slot. You can combine both — selections overrides whatever seed would have chosen for those slots.

For a complete avatar creation UI, install the shadcn block:

npx shadcn@latest add humation-labs/humation/avatar-builder

import { AvatarBuilder } from '@/components/humation/avatar-builder';

<AvatarBuilder onChange={(state) => saveAvatar(state)} />

The block copies app-owned source into your project. It includes a responsive preview, part picker, color sheet, randomize, PNG/SVG export, and JSON state copy. Start from this block instead of asking an AI coding tool to invent an avatar picker from scratch.

Use the core helpers to build a part selection interface:

import { createPartPreview, getPartsForSlot } from '@humation/core';
import { humation1 } from '@humation/assets-humation-1';

// List all available head parts
const heads = getPartsForSlot(humation1, 'head');
// → [{ name: 'braids', id: 'hm1-p-...', ... }, ...]

// Render a thumbnail for each part
const thumbnail = createPartPreview(humation1, heads[0], {
  colors: { hair: '#4A3728' },
}).toDataUri();
// → data:image/svg+xml;charset=utf-8,...  (use as <img src>)

getPartsForUiGroup(humation1, 'cat') returns parts grouped by UI category (e.g. all cat variants across slots). Available slots: head, body, bottom, item, glasses.

npx skills add humation-labs/humation --skill humation-avatar

This installs concise package-selection and implementation guidance for agents that support Skills.sh.

npm install @humation/core @humation/assets-humation-1

import { createAvatar } from '@humation/core';
import { humation1 } from '@humation/assets-humation-1';

const svg = createAvatar(humation1, { seed: 'felix' }).toString();

const custom = createAvatar(humation1, {
  selections: { head: 'wavy-long', body: 'hoodie', item: 'black-cat' },
  colors: { hair: '#123456', skin: '#FFEECC' },
}).toString();

Works in Node, Deno, Bun, edge functions — anywhere that runs JavaScript. Output is a self-contained SVG string with no external dependencies.

To persist a user's avatar, save the selections and colors:

const state = {
  selections: { head: 'braids', body: 'hoodie', item: 'calico-cat' },
  colors: { hair: '#4A3728', skin: '#F4C9A8' },
};

// Later, restore:
<Avatar assets={humation1} selections={state.selections} colors={state.colors} />

For seed-based avatars, save the seed string. For manually customized avatars, save the selections object (part names per slot) and colors object. Part names are stable across versions; canonical IDs (hm1-p-000023) are also accepted for guaranteed stability.

Deterministic rendering. seed → FNV-1a hash → part selection per slot. Same seed, same SVG. No network, no randomness.

CSS variable recoloring. Rendered SVGs use var(--hm-hair), var(--hm-skin), etc. — recoloring is a pure CSS cascade, no re-render:

.dark .avatar { --hm-stroke: #e5e5e5; --hm-clothes: #2a2a2a; }

Named parts. Every part has a unique name within its slot (braids, hoodie, camera). Use getPartsForSlot() to list available parts programmatically.

Color slots. hair, clothes, bottom, skin, stroke, background. Hex values work with or without #.

v1.0.0

bun install
bun run typecheck
bun run test          # builds packages, runs asset tests, renders the example
bun run pack:smoke    # packs npm tarballs and installs them in a clean project

The Node example writes examples/node/out/avatar.svg and avatar.html:

bun run example:node

New to the codebase? Start with docs/design-decisions.md — the one-page summary of every locked design decision and the remaining release work.

Release tooling (see docs/humation-oss-release-checklist.md):

bun run release:check               # publish blockers; fails until release is prepared
bun run release:prepare -- 0.1.0    # dry run
bun run release:prepare -- 0.1.0 --write

MIT. See LICENSE for details.