workspace-avatars

Deterministic, theme-aware avatars with cross-stitch patterns. Same seed → same pattern, every time. Light/dark via pure CSS variables — no useDarkMode hook, no MutationObserver, no re-renders on theme change.

npm i workspace-avatars

Usage

import { WorkspaceAvatar } from "workspace-avatars";

<WorkspaceAvatar seed="acme-corp" />
<WorkspaceAvatar seed="[email protected]" config={{ style: "initials", size: "lg" }} />
<WorkspaceAvatar seed="project-x" config={{ style: "block", containerRadius: 20 }} />

That's it! Styles are included automatically.

Dark mode

The component automatically switches palettes when a .dark class is present on any parent element. Just toggle the class and the avatars update via CSS variables - no re-renders, no JavaScript.

Customizing colors

The component uses 8 deterministic color palettes. To customize any palette, define CSS variables in your global stylesheet:

:root {
  /* Override palette 0 for light mode */
  --avatar-palette-0-bg: #f5f3f0;
  --avatar-palette-0-fg: #8b7d6b;
  --avatar-palette-0-mid: #b5a89a;
}

.dark {
  /* Override palette 0 for dark mode */
  --avatar-palette-0-bg: #1c1a17;
  --avatar-palette-0-fg: #a89b88;
  --avatar-palette-0-mid: #6b5f4f;
}

Palettes are numbered 0–7. Each palette has 3 colors:

• bg — background fill
• fg — primary pattern color
• mid — secondary depth/shading color

The component automatically selects a palette by hashing the seed, but you can override any palette's colors via CSS variables. If not defined, the component uses hardcoded default colors.

Props

| Prop | Type | Default | Description | | ----------- | -------------------- | -------- | --------------------------------------------- | | seed | string | required | Any string — hash drives palette and pattern. | | config | PatternConfig | — | Override style, density, gap, padding, etc. | | className | string | — | Forwarded to outer wrapper. | | style | React.CSSProperties| — | Inline styles forwarded to outer wrapper. |

PatternConfig

| Field | Type | Default | Notes | | ----------------- | -------------------------------------------------------- | ----------- | ------------------------------------------------ | | style | "pixel" \| "block" \| "quilt" \| "initials" | "quilt" | Pattern type (8×8 / 10×10 / 9×9 grid or text). | | size | "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" | undefined | 24px → 240px. Omit for fluid sizing. | | cellRadius | 0–100 | 15 | Cell corner radius (% of cell size). | | containerRadius | 0–100 | 0 | Avatar container border-radius (% of size). | | padding | 0–100 | 0 | Outer padding (% of avatar size). | | gap | 0–100 | 10 | Gap between stitches (% of cell). | | density | 0–100 | 56 | Pattern fill density. | | depth | 0–100 | 30 | Density of secondary mid-tone "depth" thread. | | border | boolean | false | Enable border around avatar. | | borderWidth | 1–10 | 1 | Border width in pixels. | | stitchShape | "rounded" \| "square" | "rounded" | Deprecated—use cellRadius instead (no effect). |

License

MIT