{
  "generatedFrom": "avatar.contract.json",
  "component": "Avatar",
  "slug": "avatar",
  "group": "Data Display",
  "tier": "leaf-lit",
  "summary": "Represent a person or entity with a photo, initials, or an icon — solo or in a stacked group.",
  "install": {
    "package": "@ahaslides-product/design",
    "registry": "https://npm.pkg.github.com",
    "scope": "@ahaslides-product",
    "auth": "Published to GitHub Packages — needs a GitHub token with read:packages. Configure the @ahaslides-product scope in .npmrc before installing.",
    "npmrc": "@ahaslides-product:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}   # a GitHub token with read:packages",
    "command": "npm i @ahaslides-product/design",
    "tokenLayer": "import '@ahaslides-product/design/tokens.css';",
    "import": "import '@ahaslides-product/design/aha-avatar';",
    "element": "aha-avatar",
    "registers": "aha-avatar"
  },
  "feeds": {
    "doc": "https://ahaslides-product.github.io/ahaslides-design/avatar/index.html",
    "md": "https://ahaslides-product.github.io/ahaslides-design/avatar/avatar.md",
    "agentJson": "https://ahaslides-product.github.io/ahaslides-design/avatar.agent.json",
    "llms": "https://ahaslides-product.github.io/ahaslides-design/avatar.llms.txt",
    "index": "https://ahaslides-product.github.io/ahaslides-design/llms.txt"
  },
  "recommendedSnippet": "html",
  "vibeCode": "Emit the HTML snippet by default — <aha-avatar> is a standard custom element that renders on open — React/Vue are thin adapters over the same element. Paste into an .html file and it renders with no build step.",
  "frameworks": {
    "react": {
      "via": "web-component",
      "ref": "aha-avatar"
    },
    "vue": {
      "via": "web-component",
      "ref": "aha-avatar"
    },
    "html": {
      "via": "web-component",
      "ref": "aha-avatar",
      "runnable": "paste-and-run — no build step, renders on open"
    }
  },
  "props": [
    {
      "name": "name",
      "type": "string",
      "default": "—",
      "desc": "Full name; initials are derived when no src/icon. Also the alt/aria-label"
    },
    {
      "name": "src",
      "type": "string",
      "default": "—",
      "desc": "Image URL; the photo content mode (overrides icon/initials)"
    },
    {
      "name": "icon",
      "type": "string",
      "default": "—",
      "desc": "DS icon name (e.g. 'system-user'); the glyph content mode when no src"
    },
    {
      "name": "size",
      "type": "'small' | 'default' | 'large' | number",
      "default": "default",
      "desc": "24 / 40 / 64 named steps, or any numeric px"
    },
    {
      "name": "shape",
      "type": "circle | square",
      "default": "circle",
      "desc": "Clip shape"
    },
    {
      "name": "color",
      "type": "token name",
      "default": "—",
      "desc": "Ground tint — an --aha-* token suffix, e.g. 'bg-positive'"
    },
    {
      "name": "max",
      "type": "number",
      "default": "—",
      "desc": "(aha-avatar-group) collapse children past this count into a +N chip"
    }
  ],
  "tokens": [
    "bg-accent",
    "purple-60",
    "bg-container",
    "radius-pill",
    "radius-default",
    "font-product"
  ],
  "spec": [
    {
      "label": "Size",
      "value": "small 24 · default 40 · large 64 (named), or any numeric px via `size`"
    },
    {
      "label": "Shape",
      "value": "circle (pill radius) · square (radius 8)"
    },
    {
      "label": "Initials",
      "value": "bg-accent #F9F5FF, purple-60 #6A1EBB, SemiBold 600"
    },
    {
      "label": "Image",
      "value": "object-fit cover, clipped to shape"
    },
    {
      "label": "Icon",
      "value": "<aha-icon> glyph by name, ~half the avatar diameter, currentColor"
    },
    {
      "label": "Color",
      "value": "ground tint from an --aha-* token via `color` (default brand tint)"
    },
    {
      "label": "Group",
      "value": "stacked overlap (-10px), 2px container-white ring, +N chip past `max`"
    }
  ],
  "opinion": {
    "whenToUse": [
      {
        "what": "Avatar",
        "when": "identifying a person or entity — a presenter, a participant, an author"
      },
      {
        "what": "Icon",
        "when": "a generic symbol, not a specific identity"
      },
      {
        "what": "Tag",
        "when": "labelling with a category rather than an identity"
      }
    ],
    "note": "Always provide `name` even when `src` is set — it becomes the alt text and the initials fallback if the image fails. Prefer initials or a photo over a generic icon for a real identity; reserve the icon mode for a placeholder/guest slot. In a group, keep sizes uniform and set `max` so the +N chip stays legible.",
    "dsv3": "COVERED — enumerated from the DS V3 Avatar + Avatar-Group component sets (fileKey MwjvUjVI0HnfwD9EwPXRAy): 'supports images, Icons, or letters' → three content modes; circle/square shapes; small/default/large sizes; a colour ground; and a stacked group with a +N overflow. Initials/icon ground uses bg-accent (#F9F5FF) with purple-60 (#6A1EBB) — the brand-tint pairing across the system; `color` overrides the ground with any --aha-* token. Circle is the pill radius; square is the default 8 radius. Group children wear a 2px bg-container ring and overlap; the +N chip inherits the group size/shape."
  },
  "surfaces": [
    "editor",
    "dashboard",
    "settings",
    "audience"
  ],
  "snippets": {
    "html": "<!-- Paste-and-run: save as .html and open in a browser. No build step.\n     <aha-avatar> is the SAME shared custom element React and Vue consume.\n     Content is one of three: `name` (initials + alt), `src` (photo), or `icon` (a DS glyph).\n     `size` is a named step (small/default/large) or any px; `shape` is circle/square;\n     `color` tints the initials/icon ground with an --aha-* token. -->\n<link rel=\"stylesheet\" href=\"https://cdn.jsdelivr.net/gh/ahaslides-product/ahaslides-design@master/lib/tokens.css\">\n<script type=\"module\">\n  import 'https://cdn.jsdelivr.net/gh/ahaslides-product/ahaslides-design@master/lib/icons.js';       // <aha-icon>\n  import 'https://cdn.jsdelivr.net/gh/ahaslides-product/ahaslides-design@master/lib/aha-avatar.js';  // <aha-avatar> + <aha-avatar-group>\n</script>\n\n<aha-avatar name=\"Ada Lovelace\"></aha-avatar>                          <!-- initials -->\n<aha-avatar name=\"Grace Hopper\" src=\"/u/grace.jpg\" size=\"large\"></aha-avatar>  <!-- photo, 64 -->\n<aha-avatar icon=\"system-user\" name=\"Guest\"></aha-avatar>              <!-- glyph -->\n<aha-avatar name=\"Square One\" shape=\"square\" size=\"small\"></aha-avatar> <!-- 24, square -->\n\n<!-- Stacked group: overlaps children, collapses the overflow past `max` into a +N chip -->\n<aha-avatar-group max=\"3\">\n  <aha-avatar name=\"Ada Lovelace\"></aha-avatar>\n  <aha-avatar name=\"Grace Hopper\"></aha-avatar>\n  <aha-avatar name=\"Alan Turing\"></aha-avatar>\n  <aha-avatar name=\"Katherine Johnson\"></aha-avatar>\n</aha-avatar-group>\n",
    "react": "import '@ahaslides-product/design/aha-avatar';   // registers <aha-avatar> + <aha-avatar-group>\n\n// A plain custom element — no wrapper needed for static props.\n// Content is one of three: `name` (initials), `src` (photo), or `icon` (a DS glyph).\nfunction AhaAvatar({ name, src, icon, size = 'default', shape = 'circle', color }) {\n  return <aha-avatar name={name} src={src} icon={icon} size={size} shape={shape} color={color} />;\n}\n\n// usage\n<AhaAvatar name=\"Ada Lovelace\" />\n<AhaAvatar name=\"Grace Hopper\" src=\"/u/grace.jpg\" size=\"large\" />\n<AhaAvatar icon=\"system-user\" name=\"Guest\" />\n\n// Stacked group with a +N overflow past `max`\n<aha-avatar-group max={3}>\n  <aha-avatar name=\"Ada Lovelace\" />\n  <aha-avatar name=\"Grace Hopper\" />\n  <aha-avatar name=\"Alan Turing\" />\n  <aha-avatar name=\"Katherine Johnson\" />\n</aha-avatar-group>\n",
    "vue": "// main.ts — register the elements + mark aha-* as custom elements\nimport '@ahaslides-product/design/aha-avatar';   // <aha-avatar> + <aha-avatar-group>\napp.config.compilerOptions.isCustomElement = (tag) => tag.startsWith('aha-');\n\n// Component.vue\n<template>\n  <aha-avatar name=\"Ada Lovelace\" />                             <!-- initials -->\n  <aha-avatar name=\"Grace Hopper\" :size=\"'large'\" />            <!-- 64 -->\n  <aha-avatar :src=\"photoUrl\" name=\"Ada Lovelace\" />           <!-- photo -->\n  <aha-avatar icon=\"system-user\" name=\"Guest\" />              <!-- glyph -->\n\n  <!-- Stacked group with a +N overflow past `max` -->\n  <aha-avatar-group max=\"3\">\n    <aha-avatar name=\"Ada Lovelace\" />\n    <aha-avatar name=\"Grace Hopper\" />\n    <aha-avatar name=\"Alan Turing\" />\n    <aha-avatar name=\"Katherine Johnson\" />\n  </aha-avatar-group>\n</template>\n"
  }
}