# DESIGN.md · Boring Avatars (AV-004)

> Written for AI coding agents. Values marked **OFFICIAL** come from the documented source named below; values marked **ESTIMATED** were measured by us from our own screenshots and are approximate. Never treat ESTIMATED values as official brand tokens.

## Overview
- Type: Avatar Library · Category: J. Avatars and Illustrations
- Platforms: Web
- Color theme: Pastel · Layout pattern: Card grid · Mood: Playful, geometric
- License / terms: React library: MIT (boring-avatars v2.0.4 on npm). The hosted avatar service is a separate subscription product
- Industry: Open-source design assets
- Patterns: Generator / playground, In-context product preview

Open-source React component that generates abstract SVG avatars (marble, beam, pixel, sunset, ring, bauhaus) from a name and a palette you provide.

### Analysis (ours)
boringavatars.com (our capture) sets everything in a monospace typeface: a short left column (‘Generate unique SVG avatars’, a one-paragraph description and a GitHub button with the star count), and a large soft teal-gray panel (#C1D8D9, ESTIMATED) that works like a live playground. Palette chips and variant toggles float above the panel; a row of named avatars sits over the copyable component code (‘<Avatar colors={[…]} variant="beam" />’), and below that the same avatars appear inside realistic mock UI: a feed post, a chat thread, a profile card with follower counts. Lesson: showing generated avatars inside real interface patterns proves they work in context, and the palette you pass in is the whole brand. Pitfall: the React library is MIT, but the hosted avatar service is a separate subscription product, so don’t confuse the two.

### Best practices (ours)
- Pass your own 5-color palette so the abstract avatars match your brand.
- Use one variant (beam for faces, marble or bauhaus for teams or workspaces) across the product.
- Generate from a stable ID, not a display name that users can change.
- Preview avatars inside your real list, chat and profile layouts before committing.

### Usage terms at a glance (our summary, not legal advice)
- Commercial use: Yes (MIT library); hosted service is paid
- Attribution: Keep the MIT notice in code
- Redistribution: Library: MIT terms
- How you get it: npm React component

## Color tokens
No official color tokens documented for this entry.

ESTIMATED · dominant colors measured from our screenshot(s) of the source site (median-cut quantization; share = % of pixels). Approximate, not official:

- `#FFFFFF` ~27%
- `#C1D8D9` ~14%
- `#919C9D` ~8%

## Typography
No official type scale documented for this entry; use the product’s own typography guidance.

## Spacing, radii, shadows
Not documented for this entry. Do not invent values; derive from your own design system.

## Components
No component inventory documented for this entry.

## Layout rules
- Observed layout pattern: **Card grid** (from our captures).

## Usage
```
npm i boring-avatars
import Avatar from 'boring-avatars';
<Avatar name="Maria Mitchell" variant="beam" colors={['#16140F','#D9411E','#F3F0E8','#E8B04B','#5E584C']} />
```

## Do’s and don’ts
- Do: Use soft tonal surfaces with one stronger accent for actions.
- Don’t: Don’t rely on pastel-on-pastel for text; check contrast.
- Do: follow the source’s license/terms listed above.
- Don’t: present ESTIMATED colors as official tokens.

## Sources
- https://boringavatars.com/
- Library entry: https://design-library-byt.pages.dev/entry/AV-004