{
  "generatedFrom": "screen-heading.contract.json",
  "component": "Screen heading",
  "slug": "screen-heading",
  "group": "AhaSlides surfaces",
  "tier": "leaf-lit",
  "summary": "A product page header — a title/greeting or a breadcrumb trail on the left, action buttons on the right, responsive across desktop / tablet / phone.",
  "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-screen-heading';",
    "element": "aha-screen-heading",
    "registers": "aha-screen-heading"
  },
  "feeds": {
    "doc": "https://ahaslides-product.github.io/ahaslides-design/screen-heading/index.html",
    "md": "https://ahaslides-product.github.io/ahaslides-design/screen-heading/screen-heading.md",
    "agentJson": "https://ahaslides-product.github.io/ahaslides-design/screen-heading.agent.json",
    "llms": "https://ahaslides-product.github.io/ahaslides-design/screen-heading.llms.txt",
    "index": "https://ahaslides-product.github.io/ahaslides-design/llms.txt"
  },
  "recommendedSnippet": "html",
  "vibeCode": "Emit the HTML snippet by default — <aha-screen-heading> 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-screen-heading"
    },
    "vue": {
      "via": "web-component",
      "ref": "aha-screen-heading"
    },
    "html": {
      "via": "web-component",
      "ref": "aha-screen-heading",
      "runnable": "paste-and-run — no build step, renders on open"
    }
  },
  "props": [
    {
      "name": "title",
      "type": "string",
      "default": "—",
      "desc": "The page title — rendered via <aha-breadcrumb size=\"page-title\"> (Heading4 24/600, text-default), unless `highlight` makes it an accent greeting"
    },
    {
      "name": "highlight",
      "type": "string",
      "default": "—",
      "desc": "Optional substring of `title` rendered in color-primary — e.g. the person's name in a greeting"
    },
    {
      "name": "breadcrumb",
      "type": "JSON [{label, href?}]",
      "default": "—",
      "desc": "When present, a `›` trail renders as the page title via the reused <aha-breadcrumb size=\"page-title\"> (for a sub-page)"
    },
    {
      "name": "description",
      "type": "string",
      "default": "—",
      "desc": "Optional subtitle under the title (14px, text-secondary)"
    },
    {
      "name": "device",
      "type": "'desktop' | 'tablet' | 'phone'",
      "default": "desktop",
      "desc": "Deterministic responsive layout — phone wraps the actions below the title"
    }
  ],
  "tokens": [
    "text-default",
    "text-secondary",
    "color-primary"
  ],
  "spec": [
    {
      "label": "Type",
      "value": "title = <aha-breadcrumb size=\"page-title\"> — Heading4 24 / SemiBold 600 / line-height 1.3 / #1A1A1A (text-default) for a single-crumb page title; 18/600 with an ancestor path"
    },
    {
      "label": "Highlight",
      "value": "optional `highlight` substring of the title in color-primary #6A1EBB (a person's name) → a local greeting <h1>, matched to the breadcrumb page-title solo"
    },
    {
      "label": "Breadcrumb",
      "value": "`breadcrumb` JSON [{label, href?}] → the `›` trail renders as the page title via the reused <aha-breadcrumb size=\"page-title\"> (heading-level 1)"
    },
    {
      "label": "Description",
      "value": "optional subtitle, Plus Jakarta 14/22 · text-secondary #4A4A4A, under the title"
    },
    {
      "label": "Actions",
      "value": "slot=\"actions\" — the consumer drops <aha-button>s here (never a hand-rolled button)"
    },
    {
      "label": "Gap",
      "value": "16 between the title area and the actions · 8 title→description and between action buttons"
    },
    {
      "label": "Layout",
      "value": "desktop / tablet: title left, actions right on one row · phone: actions wrap below the title"
    }
  ],
  "opinion": {
    "whenToUse": [
      {
        "what": "Screen heading",
        "when": "the header row of a product page — a title/greeting or a hierarchy trail plus the page's primary actions"
      },
      {
        "what": "Breadcrumb",
        "when": "only the ancestor trail / page title is needed, with no right-hand actions (use <aha-breadcrumb size=\"page-title\"> directly — it IS the title this header wraps)"
      },
      {
        "what": "Card",
        "when": "a titled content container, not the page-level header"
      }
    ],
    "note": "One primary action on the right at most; the rest secondary. Use a plain `title` for a top-level page (optionally with a `highlight` name), and a `breadcrumb` trail for a sub-page — both render the page heading via the reused <aha-breadcrumb size=\"page-title\">, never a hand-rolled <h1>. Keep the title a short sentence-case phrase.",
    "dsv3": "COVERED — DS V3 Screen heading (fileKey P764iQ6y4ZwW7W3f7FLZyW, node 2237:55733; Desktop / Tablet / Phone device variants). The Desktop symbol = a Breadcrumb instance + a (hidden) description line + a Button Group. Bindings from get_variable_defs: title Heading4 24 / weight 600 / line-height 1.3 / #1A1A1A (text-default), brand-accent name #6A1EBB (color-primary), gaps 8 (GapM) and 16 (GapL), icon 16. REUSE: the title IS the shipped <aha-breadcrumb size=\"page-title\"> (a Breadcrumb instance in Figma too — the page heading, single-crumb or trailed); the actions are slotted <aha-button>s from the DS button. The only local <h1> is the accent-name greeting the breadcrumb can't render — no second breadcrumb, no hand-rolled title, no hand-rolled button."
  },
  "surfaces": [
    "dashboard",
    "editor",
    "admin",
    "settings"
  ],
  "snippets": {
    "html": "<!-- Paste-and-run: save as .html and open in a browser. No build step.\n     <aha-screen-heading> is the SAME shared custom element React and Vue consume — here in its\n     native form. The page title reuses <aha-breadcrumb size=\"page-title\"> (plain title or `›` trail);\n     the actions are slotted <aha-button>s. Theming comes only from the --aha-* tokens in tokens.css. -->\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/aha-screen-heading.js';   // registers <aha-screen-heading> (+ <aha-breadcrumb>)\n  import 'https://cdn.jsdelivr.net/gh/ahaslides-product/ahaslides-design@master/lib/aha-button.js';   // registers <aha-button> for the slotted actions\n  import 'https://cdn.jsdelivr.net/gh/ahaslides-product/ahaslides-design@master/lib/icons.js';   // registers <aha-icon> for the button glyph\n</script>\n\n<!-- A greeting with a brand-accent highlight + right-hand actions (buttons slotted in). -->\n<aha-screen-heading title=\"Welcome, Brian!\" highlight=\"Brian\" description=\"Here's what's happening across your workspace today.\">\n  <aha-button slot=\"actions\" variant=\"secondary\">Import</aha-button>\n  <aha-button slot=\"actions\" variant=\"primary\">\n    <span slot=\"icon\"><aha-icon name=\"system-plus\" size=\"16\" decorative></aha-icon></span>\n    New presentation\n  </aha-button>\n</aha-screen-heading>\n\n<!-- A sub-page header: pass a `breadcrumb` JSON array and the `›` trail renders as the title. -->\n<aha-screen-heading breadcrumb='[{\"label\":\"Presentations\",\"href\":\"/p\"},{\"label\":\"Team offsite\",\"href\":\"/p/1\"},{\"label\":\"Editor\"}]'>\n  <aha-button slot=\"actions\" variant=\"primary\">Present</aha-button>\n</aha-screen-heading>\n",
    "react": "import '@ahaslides-product/design/aha-screen-heading';   // registers <aha-screen-heading> (+ <aha-breadcrumb>)\nimport '@ahaslides-product/design/aha-button';   // registers <aha-button> for the slotted actions\nimport '@ahaslides-product/design/icons';   // registers <aha-icon> for the button glyph\n\n// Attribute-driven — React 18/19 render the element directly. `breadcrumb` is a JSON array,\n// so serialise it to the attribute; the title trail is the reused <aha-breadcrumb>.\nfunction AhaScreenHeading({ title, highlight, breadcrumb, description, device, children }) {\n  return (\n    <aha-screen-heading\n      {...(title ? { title } : {})}\n      {...(highlight ? { highlight } : {})}\n      {...(breadcrumb ? { breadcrumb: JSON.stringify(breadcrumb) } : {})}\n      {...(description ? { description } : {})}\n      {...(device ? { device } : {})}\n    >\n      {children}\n    </aha-screen-heading>\n  );\n}\n\n// usage — a greeting header with slotted action buttons\nexport function DashboardHeader({ user }) {\n  return (\n    <AhaScreenHeading title={`Welcome, ${user.name}!`} highlight={user.name}\n      description=\"Here's what's happening across your workspace today.\">\n      <aha-button slot=\"actions\" variant=\"secondary\">Import</aha-button>\n      <aha-button slot=\"actions\" variant=\"primary\">\n        <span slot=\"icon\"><aha-icon name=\"system-plus\" size={16} decorative /></span>\n        New presentation\n      </aha-button>\n    </AhaScreenHeading>\n  );\n}\n",
    "vue": "// main.ts — register the elements + mark aha-* as custom elements\nimport '@ahaslides-product/design/aha-screen-heading';   // registers <aha-screen-heading> (+ <aha-breadcrumb>)\nimport '@ahaslides-product/design/aha-button';   // registers <aha-button> for the slotted actions\nimport '@ahaslides-product/design/icons';   // registers <aha-icon> for the button glyph\napp.config.compilerOptions.isCustomElement = (tag) => tag.startsWith('aha-');\n\n// Component.vue — Vue 3 binds the same <aha-screen-heading> natively.\n<script setup>\ndefineProps({ user: Object });\n</script>\n\n<template>\n  <!-- A greeting header: brand-accent highlight + right-hand actions (slotted <aha-button>s). -->\n  <aha-screen-heading\n    :title=\"`Welcome, ${user.name}!`\"\n    :highlight=\"user.name\"\n    description=\"Here's what's happening across your workspace today.\">\n    <aha-button slot=\"actions\" variant=\"secondary\">Import</aha-button>\n    <aha-button slot=\"actions\" variant=\"primary\">\n      <span slot=\"icon\"><aha-icon name=\"system-plus\" :size=\"16\" decorative /></span>\n      New presentation\n    </aha-button>\n  </aha-screen-heading>\n\n  <!-- A sub-page header: bind a `breadcrumb` JSON array → the `›` trail renders as the title. -->\n  <aha-screen-heading\n    :breadcrumb='JSON.stringify([{label:\"Presentations\",href:\"/p\"},{label:\"Team offsite\",href:\"/p/1\"},{label:\"Editor\"}])'>\n    <aha-button slot=\"actions\" variant=\"primary\">Present</aha-button>\n  </aha-screen-heading>\n</template>\n"
  }
}