Humation Avatar

Humation Avatar

Use this skill to add Humation avatars to Zo Computer agent products, web apps, UI prototypes, and static assets.

Humation is a hand-drawn deterministic SVG avatar engine. The same seed produces the same face, which makes it a good fit for stable agent identities, persona identities, user avatars, and product characters.

What this skill does

When a Zo user wants to use Humation, first identify the target surface and choose the matching workflow.

Core rules

• For normal agent products, install Humation npm packages into the target project.
• Use @humation/react + @humation/assets-humation-1 for React UI.
• Use @humation/core + @humation/assets-humation-1 for raw SVG, backend, CLI, and worker code.
• Keep all @humation/* package versions aligned.
• zo.space page routes are the exception: do not run npm install or bun add in zo.space. Use pinned file esm.sh browser ESM imports instead.
• Use stable IDs as seeds: agent ID, persona ID, product slug, account ID, or user ID. Do not use display names as seeds.
• Save manually customized avatars as { seed, selections, colors, background }.
• Use the legacy public SVG API only when backward compatibility is required. New work should use npm packages.

Workflow 1: Add Humation to a React / Zo Site / web app

1. Inspect the target project

At the project root, check file package.json, lockfiles, README, and any project-level file AGENTS.md.

Choose the existing package manager:

• bun.lock -> bun add
• file pnpm-lock.yaml -> pnpm add
• file package-lock.json -> npm install
• If unclear, inspect project docs or ask the user before installing

2. Install packages

For React UI:

npm install @humation/react @humation/assets-humation-1
# or
bun add @humation/react @humation/assets-humation-1
# or
pnpm add @humation/react @humation/assets-humation-1

3. Add an agent avatar component

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

type AgentAvatarProps = {
  agentId: string;
  size?: number;
};

export function AgentAvatar({ agentId, size = 96 }: AgentAvatarProps) {
  return (
    <Avatar
      assets={humation1}
      seed={agentId}
      size={size}
      colors={{
        stroke: '#09111F',
        clothes: '#2F6BFF',
      }}
      background="transparent"
      title="Agent avatar"
    />
  );
}

4. Place it where the agent identity matters

Good locations:

• chat header
• agent card
• onboarding screen
• profile settings
• conversation participant list
• loading / empty state
• agent marketplace or directory cards

Workflow 2: Generate SVG with Core

Use Core for API routes, servers, CLIs, workers, and non-React environments.

npm install @humation/core @humation/assets-humation-1
# or
bun add @humation/core @humation/assets-humation-1
# or
pnpm add @humation/core @humation/assets-humation-1

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

export function renderAgentAvatarSvg(agentId: string) {
  return createAvatar(humation1, {
    seed: agentId,
    colors: {
      stroke: '#09111F',
      clothes: '#2F6BFF',
    },
    background: 'transparent',
  }).toString();
}

Return SVG from an HTTP endpoint:

const svg = renderAgentAvatarSvg(agentId);
return new Response(svg, {
  headers: {
    'content-type': 'image/svg+xml; charset=utf-8',
    'cache-control': 'public, max-age=31536000, immutable',
  },
});

Workflow 3: Create static SVG files with the bundled CLI

Use the bundled CLI when the user only needs an SVG file, or when you want to prototype an agent face before integrating it into a project.

Create a ready-to-use agent face:

bun run Skills/humation-avatar/scripts/humation-local.ts agent-face 
  --seed support-agent 
  --output /home/workspace/support-agent-face.svg

Render from a seed:

bun run Skills/humation-avatar/scripts/humation-local.ts render 
  --seed user-123 
  --output /home/workspace/user-123-avatar.svg

Render explicit parts and colors:

bun run Skills/humation-avatar/scripts/humation-local.ts render 
  --head braids 
  --body hoodie 
  --item calico-cat 
  --hair 4A3728 
  --skin F4C9A8 
  --background transparent 
  --output /home/workspace/custom-avatar.svg

Inspect JSON state:

bun run Skills/humation-avatar/scripts/humation-local.ts render 
  --seed product-agent 
  --format json 
  --pretty

List parts and create a part preview:

bun run Skills/humation-avatar/scripts/humation-local.ts manifest --pretty
bun run Skills/humation-avatar/scripts/humation-local.ts parts --slot head --pretty
bun run Skills/humation-avatar/scripts/humation-local.ts preview 
  --slot item 
  --part black-cat 
  --output /home/workspace/item-preview.svg

Workflow 4: Use Humation in a zo.space page route

zo.space routes have a fixed dependency environment. Do not install npm packages there. For page routes, use pinned browser ESM imports from file esm.sh.

import { createAvatar, createPartPreview, getPartsForSlot } from 'https://esm.sh/@humation/core@1.0.1?bundle';
import { humation1 } from 'https://esm.sh/@humation/assets-humation-1@1.0.1?bundle';

const avatar = createAvatar(humation1, {
  seed: 'zo-agent-product',
  colors: { stroke: '#09111F', clothes: '#2F6BFF' },
  background: 'transparent',
});

const dataUri = avatar.toDataUri();

Rules for zo.space:

• URL ESM imports are OK in page routes.
• Do not use URL ESM imports in API routes.
• If backend-side Humation dependencies are needed, use a Zo Site or User Service instead.
• If a static avatar is enough, generate an SVG with the CLI, upload it with update_space_asset(), and render it as <img src="/assets/...svg" />.

Current demos:

• https://yusuke.zo.space/humation-avatar — package-based Humation builder
• https://yusuke.zo.space/humation-agent — example agent product page using Humation as the agent face

Both are public zo.space pages and use browser-side package rendering rather than the legacy public SVG API.

Workflow 5: Add the official Avatar Builder UI

If the user needs a polished avatar builder in a shadcn project, use the official Humation block.

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

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

<AvatarBuilder => saveAvatar(state)} />

The block includes responsive preview, part picker, color sheet, randomize, PNG/SVG export, and JSON state copy. Prefer this block over inventing a simplified picker from scratch.

State to persist

For seed-based avatars, persist the seed.

type SeedAvatarState = {
  seed: string;
};

For customized avatars, persist the full avatar state.

type HumationAvatarState = {
  seed?: string;
  selections: {
    head?: string;
    body?: string;
    bottom?: string;
    item?: string;
    glasses?: string;
  };
  colors: {
    stroke?: string;
    hair?: string;
    skin?: string;
    clothes?: string;
    bottom?: string;
  };
  background?: string | 'transparent';
};

Common slots

Selection slots:

• head
• body
• bottom
• item
• glasses

Color slots:

• stroke
• hair
• skin
• clothes
• bottom
• background

Note: bottom is both a selection slot and a color slot. In the CLI, selection uses --bottom <part> and color uses --bottom-color <hex>.

Implementation checklist

After implementing Humation, verify:

• The package manager matched the target project
• All @humation/* package versions are aligned
• The seed uses a stable ID
• The avatar renders correctly
• The avatar remains visible on dark and light backgrounds
• SVG/data URI/API response content types are correct
• The integration does not cause large layout shifts
• For zo.space routes, get_space_errors() is clean and agent-browser preview works

Legacy Humation SVG API compatibility

Use the legacy API path only when an existing public SVG URL contract must be preserved.

bun run Skills/humation-avatar/scripts/humation-avatar.ts templates
bun run Skills/humation-avatar/scripts/humation-avatar.ts items
bun run Skills/humation-avatar/scripts/humation-avatar.ts url --zo on --color.zo FF6600
bun run Skills/humation-avatar/scripts/humation-avatar.ts download 
  --output /home/workspace/avatar.svg 
  --cat 001 
  --color.zo FF6600

Legacy API prototype rule: item and cat are mutually exclusive.

• If item is active, set cat=000
• If cat is active, set item=000
• Random generation must never enable both
• Apply the exclusivity rule again immediately before generating the final URL

Skill files

• file scripts/humation-local.ts — npm-package-based Humation local renderer CLI
• file scripts/humation-avatar.ts — legacy Humation SVG API CLI
• file references/oss-notes.md — npm package / OSS Humation integration notes
• file references/api-notes.md — legacy API structure and query notes
• file assets/example-zo-agent-face.svg — agent-face example
• file assets/example-seed-user-123.svg — seed render example
• file assets/example-black-cat-preview.svg — part preview example
• file SKILL.ja.md — Japanese backup of the skill instructions

Anti-patterns

Do not:

• Use the legacy public SVG API as the first choice for new work
• Run npm install or bun add inside a zo.space route
• Import https://esm.sh/... from a zo.space API route
• Use mutable display names as seeds
• Mix different versions of @humation/core, @humation/react, and @humation/assets-humation-1