@adia-ai/a2ui-corpus 0.0.1

package/catalog-a2ui_0_9_rules.txt

@@ -0,0 +1,54 @@
+# AdiaUI Catalog — LLM Rules (v0.9)
+
+# Cross-component and contextual constraints that the JSON Schema validator
+# cannot express. Concatenated into the agent system prompt.
+# Generated from each component YAML's `a2ui.rules:` entries.
+
+## Card
+- The card's <header> grid activates only for DIRECT-child slotted elements. If you need an icon column, place the icon element (avatar-ui, icon-ui) directly in the header with slot="icon" — not inside a wrapper.
+- Heading slot accepts inline badges/metadata: <span slot="heading"><text-ui strong>Title</text-ui><badge-ui text="New" variant="accent"></badge-ui></span> renders title + badge on one row.
+- Description slot also accepts bare <p> or <small> elements as siblings of the heading — they participate in the grid's row 2 without needing slot="description".
+- Multiple <section> siblings are allowed and stack vertically. [bleed] on a section removes its margin for edge-to-edge content (tables, charts); [padding] adds a canvas-scrim background for hero regions.
+- Footer with a [slot="description"] + [slot="action"] pair triggers justify-content: space-between — useful for a "Last saved …" note on the left and a Save/Cancel button group on the right.
+
+## Grid
+- For asymmetric column ratios, use [columns="N"] plus [span="M"] on the child that should be wider. Never set grid-template-columns via style — it bypasses the component API and reads as a local hack.
+- Canonical ratios: 1:1 → columns="2"; 2:1 → columns="3" + span="2"; 3:1 → columns="4" + span="3"; 3:2 → columns="5" + span="3"+"2"; 4:1 → columns="5" + span="4". Round unusual ratios (e.g. 7:5) to 3:2.
+- The default (no columns attribute) gives equal auto-columns flowing in a single row. Prefer the explicit numeric attribute for dashboard rows so the layout is predictable when items wrap.
+
+## Chat
+- adia-chat is a behavior wrapper; don't nest col-ui/row-ui inside it directly — author the structural DOM using [data-chat-*] markers instead.
+
+## Editor
+- adia-editor is a layout skeleton. Children must follow the documented structural DOM; the element wires behavior, not content.
+
+## AppNavGroup
+- Must be a direct child of app-nav-ui.
+- Children must be app-nav-item-ui, not arbitrary components.
+
+## AppNavItem
+- Must be a descendant of app-nav-ui (direct child or via app-nav-group-ui).
+- Only one sibling may have selected=true at a time; prefer calling nav.select() over setting the attribute manually.
+
+## AppNav
+- app-nav-ui is the only valid parent of app-nav-group-ui.
+- app-nav-item-ui may be a direct child of app-nav-ui OR nested inside app-nav-group-ui.
+
+## AppShell
+- app-shell-ui is a behavior wrapper; its children are native HTML landmarks (aside, main, header). Don't wrap them in col-ui/row-ui — app-shell.css handles grid layout based on [data-sidebar] attributes.
+
+## GenUI
+- gen-ui-ui is an integration shell. Prefer app-shell-ui for admin UIs; use gen-ui-ui only for chat+canvas tooling.
+
+## SectionNavGroup
+- Must be a direct child of section-nav-ui.
+- Children must be section-nav-item-ui.
+
+## SectionNavItem
+- Must be a descendant of section-nav-ui (direct child or via section-nav-group-ui).
+
+## SectionNav
+- section-nav-ui is the only valid parent of section-nav-group-ui.
+- section-nav-item-ui may be a direct child of section-nav-ui OR nested inside section-nav-group-ui.
+- Use section-nav-ui beside an article inside an app-shell section; don't nest app-nav inside it.
+

package/compositions/_schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "A2UI Composition",
+  "description": "A pattern expressed as references to fragments + inline nodes. Same A2UI flat-adjacency structure as a legacy Pattern, except nodes may carry a `$fragment` field instead of a `component`. At resolve time, the composer expands each $fragment reference into the fragment's template with slot bindings applied, producing a standard A2UI tree.",
+  "type": "object",
+  "required": ["name", "kind", "domain", "template"],
+  "properties": {
+    "$schema":     { "type": "string" },
+    "name":        { "type": "string" },
+    "version":     { "type": "integer", "default": 1 },
+    "kind":        { "const": "composition" },
+    "domain":      { "type": "string" },
+    "description": { "type": "string" },
+    "tags":        { "type": "object" },
+    "keywords":    { "type": "array", "items": { "type": "string" } },
+    "related":     { "type": "array", "items": { "type": "string" } },
+
+    "template": {
+      "type": "array",
+      "description": "Flat A2UI adjacency. A node is either (a) a normal A2UI component node OR (b) a fragment reference: { id, $fragment: 'fragment-name', bindings: { slotName: value }, children?: [...] }. Fragment refs may accept a `children` override to inject extra children into the fragment's root (e.g., adding more form fields to a card section).",
+      "items": { "type": "object" }
+    },
+
+    "wiring": { "type": "object" }
+  }
+}

package/compositions/agent/ai-streaming-response.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "../_schema.json",
+  "name": "ai-streaming-response",
+  "version": 1,
+  "kind": "composition",
+  "domain": "agent",
+  "description": "AI response card with streaming text — shows the agent's answer as it generates.",
+  "tags": { "purpose": ["agent", "ai", "stream"], "complexity": "atomic", "layout": "stacked" },
+  "keywords": ["ai", "streaming", "response", "agent output", "stream", "llm"],
+
+  "template": [
+    { "id": "root", "component": "Card", "children": ["sec"] },
+    { "id": "sec", "component": "Section", "children": ["col"] },
+    { "id": "col", "component": "Column", "children": ["label", "stream"], "gap": "2" },
+    { "id": "label","component": "Text", "variant": "caption", "color": "muted", "textContent": "Assistant" },
+    { "id": "stream","component": "Stream",
+      "textContent": "Analyzing your request and generating a response…" }
+  ]
+}

package/compositions/agent/ai-streaming-response.yaml

@@ -0,0 +1,32 @@
+# Generated by scripts/generate-yaml-scaffolds.mjs
+# Narrative doc — JSON sibling remains the canonical machine source.
+# Fill in TODO sections by hand.
+
+$schema: ../../../../../scripts/schemas/composition.yaml.schema.json
+kind: composition
+name: ai-streaming-response
+domain: agent
+description: >-
+  AI response card with streaming text — shows the agent's answer as it generates.
+keywords:
+  - ai
+  - streaming
+  - response
+  - agent output
+  - stream
+  - llm
+tags:
+  purpose:
+    - agent
+    - ai
+    - stream
+  complexity: atomic
+  layout: stacked
+related: []
+fragments_used: []
+use-cases:
+  - "TODO: primary use case"
+wiring-intent:
+  summary: Static composition (no interactive wiring).
+  controllers: []
+  actions: []

package/compositions/agent/alert-banner.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "../_schema.json",
+  "name": "alert-banner",
+  "version": 1,
+  "kind": "composition",
+  "domain": "agent",
+  "description": "Dismissible alert banner with message text and an action button — for cookie consent, warnings, notices.",
+  "tags": {
+    "purpose": ["notice", "warning", "consent"],
+    "complexity": "atomic",
+    "layout": "row"
+  },
+  "keywords": ["alert", "banner", "notice", "warning", "cookie consent", "dismiss"],
+
+  "template": [
+    { "id": "root", "component": "Alert", "variant": "info", "children": ["row"] },
+    { "id": "row",  "component": "Row", "children": ["msg", "actions"], "gap": "3", "align": "center" },
+    { "id": "msg",  "component": "Text", "variant": "body",
+      "textContent": "We use cookies to improve your experience. Read our privacy policy." },
+    { "id": "actions", "$fragment": "dual-cta-row",
+      "bindings": { "primaryLabel": "Accept", "secondaryLabel": "Dismiss" } }
+  ]
+}

package/compositions/agent/alert-banner.yaml

@@ -0,0 +1,34 @@
+# Generated by scripts/generate-yaml-scaffolds.mjs
+# Narrative doc — JSON sibling remains the canonical machine source.
+# Fill in TODO sections by hand.
+
+$schema: ../../../../../scripts/schemas/composition.yaml.schema.json
+kind: composition
+name: alert-banner
+domain: agent
+description: >-
+  Dismissible alert banner with message text and an action button — for cookie consent, warnings, notices.
+keywords:
+  - alert
+  - banner
+  - notice
+  - warning
+  - cookie consent
+  - dismiss
+tags:
+  purpose:
+    - notice
+    - warning
+    - consent
+  complexity: atomic
+  layout: row
+related: []
+fragments_used:
+  - fragment: dual-cta-row
+    prefix: ""
+use-cases:
+  - "TODO: primary use case"
+wiring-intent:
+  summary: Static composition (no interactive wiring).
+  controllers: []
+  actions: []

package/compositions/agent/chat-interface.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "../_schema.json",
+  "name": "chat-interface",
+  "version": 2,
+  "kind": "composition",
+  "domain": "agent",
+  "description": "Chat interface with message bubbles (sent and received) using the Chat primitive plus a composer row with input and send button. Visually distinguishes user vs agent messages.",
+  "tags": {
+    "purpose": [
+      "chat",
+      "messaging",
+      "agent"
+    ],
+    "complexity": "medium",
+    "layout": "stacked"
+  },
+  "keywords": [
+    "chat",
+    "message",
+    "bubbles",
+    "conversation",
+    "messaging",
+    "ai chat",
+    "chat interface",
+    "message bubbles",
+    "sent",
+    "received",
+    "composer",
+    "chat bubbles",
+    "chat history",
+    "send message",
+    "conversation view"
+  ],
+  "template": [
+    {
+      "id": "root",
+      "component": "Card",
+      "children": [
+        "hdr",
+        "sec",
+        "ftr"
+      ]
+    },
+    {
+      "id": "hdr",
+      "$fragment": "card-header-heading",
+      "bindings": {
+        "heading": "Chat"
+      }
+    },
+    {
+      "id": "sec",
+      "component": "Section",
+      "children": [
+        "chat"
+      ]
+    },
+    {
+      "id": "chat",
+      "component": "Chat",
+      "children": [
+        "b1",
+        "b2",
+        "b3",
+        "b4"
+      ]
+    },
+    {
+      "id": "b1",
+      "component": "Text",
+      "role": "assistant",
+      "variant": "body",
+      "textContent": "Hi \u2014 how can I help you today?"
+    },
+    {
+      "id": "b2",
+      "component": "Text",
+      "role": "user",
+      "variant": "body",
+      "textContent": "I'd like to reset my password."
+    },
+    {
+      "id": "b3",
+      "component": "Text",
+      "role": "assistant",
+      "variant": "body",
+      "textContent": "Sure \u2014 I just sent a reset link to your email."
+    },
+    {
+      "id": "b4",
+      "component": "Text",
+      "role": "user",
+      "variant": "body",
+      "textContent": "Got it, thanks!"
+    },
+    {
+      "id": "ftr",
+      "component": "Footer",
+      "children": [
+        "composer"
+      ]
+    },
+    {
+      "id": "composer",
+      "component": "Row",
+      "children": [
+        "input",
+        "send"
+      ],
+      "gap": "2",
+      "align": "center"
+    },
+    {
+      "id": "input",
+      "component": "Input",
+      "name": "message",
+      "placeholder": "Type a message\u2026"
+    },
+    {
+      "id": "send",
+      "component": "Button",
+      "variant": "primary",
+      "icon": "send",
+      "text": "Send"
+    }
+  ]
+}

package/compositions/agent/chat-interface.yaml

@@ -0,0 +1,34 @@
+# Generated by scripts/generate-yaml-scaffolds.mjs
+# Narrative doc — JSON sibling remains the canonical machine source.
+# Fill in TODO sections by hand.
+
+$schema: ../../../../../scripts/schemas/composition.yaml.schema.json
+kind: composition
+name: chat-interface
+domain: agent
+description: >-
+  Chat interface with message bubbles from alternating speakers plus a composer input at the bottom.
+keywords:
+  - chat
+  - message
+  - bubbles
+  - conversation
+  - messaging
+  - ai chat
+tags:
+  purpose:
+    - chat
+    - messaging
+    - agent
+  complexity: medium
+  layout: stacked
+related: []
+fragments_used:
+  - fragment: card-header-heading
+    prefix: ""
+use-cases:
+  - "TODO: primary use case"
+wiring-intent:
+  summary: Static composition (no interactive wiring).
+  controllers: []
+  actions: []

package/compositions/agent/command-palette.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "../_schema.json",
+  "name": "command-palette",
+  "version": 2,
+  "kind": "composition",
+  "domain": "agent",
+  "description": "Command palette with a search Input for filtering and a keyboard-navigable Command list of executable actions with icons and keyboard shortcut hints.",
+  "tags": {
+    "purpose": [
+      "command",
+      "search",
+      "quick-action",
+      "navigation"
+    ],
+    "complexity": "medium",
+    "layout": "stacked"
+  },
+  "keywords": [
+    "command palette",
+    "cmdk",
+    "quick action",
+    "command search",
+    "command list",
+    "fuzzy search",
+    "cmd+k",
+    "ctrl+k",
+    "spotlight",
+    "quick switcher",
+    "launcher",
+    "keyboard navigation",
+    "keyboard shortcuts",
+    "action menu",
+    "command menu",
+    "palette"
+  ],
+  "template": [
+    {
+      "id": "root",
+      "component": "Card",
+      "children": [
+        "hdr",
+        "sec"
+      ]
+    },
+    {
+      "id": "hdr",
+      "component": "Header",
+      "children": [
+        "input"
+      ]
+    },
+    {
+      "id": "input",
+      "component": "Input",
+      "name": "q",
+      "placeholder": "Type a command or search\u2026",
+      "icon": "search"
+    },
+    {
+      "id": "sec",
+      "component": "Section",
+      "children": [
+        "cmd"
+      ]
+    },
+    {
+      "id": "cmd",
+      "component": "Command",
+      "children": [
+        "c1",
+        "c2",
+        "c3",
+        "c4",
+        "c5"
+      ]
+    },
+    {
+      "id": "c1",
+      "component": "ActionItem",
+      "icon": "file-plus",
+      "text": "Create new document",
+      "shortcut": "\u2318N"
+    },
+    {
+      "id": "c2",
+      "component": "ActionItem",
+      "icon": "settings",
+      "text": "Open settings",
+      "shortcut": "\u2318,"
+    },
+    {
+      "id": "c3",
+      "component": "ActionItem",
+      "icon": "user-plus",
+      "text": "Invite teammate",
+      "shortcut": "\u2318I"
+    },
+    {
+      "id": "c4",
+      "component": "ActionItem",
+      "icon": "search",
+      "text": "Search help articles",
+      "shortcut": "?"
+    },
+    {
+      "id": "c5",
+      "component": "ActionItem",
+      "icon": "log-out",
+      "text": "Sign out",
+      "shortcut": "\u2318Q"
+    }
+  ]
+}

package/compositions/agent/command-palette.yaml

@@ -0,0 +1,30 @@
+# Generated by scripts/generate-yaml-scaffolds.mjs
+# Narrative doc — JSON sibling remains the canonical machine source.
+# Fill in TODO sections by hand.
+
+$schema: ../../../../../scripts/schemas/composition.yaml.schema.json
+kind: composition
+name: command-palette
+domain: agent
+description: >-
+  Command palette search — universal quick-action input with a list of matching commands.
+keywords:
+  - command palette
+  - cmdk
+  - quick action
+  - command search
+tags:
+  purpose:
+    - command
+    - search
+    - quick-action
+  complexity: simple
+  layout: stacked
+related: []
+fragments_used: []
+use-cases:
+  - "TODO: primary use case"
+wiring-intent:
+  summary: Static composition (no interactive wiring).
+  controllers: []
+  actions: []

package/compositions/agent/empty-state.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "../_schema.json",
+  "name": "empty-state",
+  "version": 1,
+  "kind": "composition",
+  "domain": "agent",
+  "description": "Empty state with illustration, explanation, and a primary action — shown when a list/view has no content or on error recovery.",
+  "tags": {
+    "purpose": ["empty-state", "error", "onboarding"],
+    "complexity": "atomic",
+    "layout": "centered"
+  },
+  "keywords": ["empty", "empty state", "no results", "no data", "no items", "illustration", "nothing", "get started", "onboarding placeholder"],
+
+  "template": [
+    { "id": "root", "component": "EmptyState", "children": ["col"] },
+    { "id": "col",  "component": "Column", "children": ["tile", "btn"], "gap": "3", "align": "center" },
+    { "id": "tile", "$fragment": "icon-title-description",
+      "bindings": { "icon": "inbox", "title": "Nothing here yet", "description": "Items you create will appear on this page." } },
+    { "id": "btn", "component": "Button", "variant": "primary", "text": "Get started" }
+  ]
+}

package/compositions/agent/empty-state.yaml

@@ -0,0 +1,35 @@
+# Generated by scripts/generate-yaml-scaffolds.mjs
+# Narrative doc — JSON sibling remains the canonical machine source.
+# Fill in TODO sections by hand.
+
+$schema: ../../../../../scripts/schemas/composition.yaml.schema.json
+kind: composition
+name: empty-state
+domain: agent
+description: >-
+  Empty state with illustration, explanation, and a primary action — shown when a list/view has no content or on error recovery.
+keywords:
+  - empty
+  - empty state
+  - no results
+  - illustration
+  - error state
+  - retry
+  - nothing
+tags:
+  purpose:
+    - empty-state
+    - error
+    - onboarding
+  complexity: atomic
+  layout: centered
+related: []
+fragments_used:
+  - fragment: icon-title-description
+    prefix: ""
+use-cases:
+  - "TODO: primary use case"
+wiring-intent:
+  summary: Static composition (no interactive wiring).
+  controllers: []
+  actions: []

package/compositions/agent/error-state-retry.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "../_schema.json",
+  "name": "error-state-retry",
+  "version": 1,
+  "kind": "composition",
+  "domain": "agent",
+  "description": "Error state card with an error alert/icon, failure explanation, and prominent Retry button plus a secondary recovery action. Shown when an operation fails and the user can retry.",
+  "tags": {
+    "purpose": ["error-state", "feedback", "recovery"],
+    "complexity": "atomic",
+    "layout": "centered"
+  },
+  "keywords": [
+    "error", "error state", "error message", "failure", "failed",
+    "retry", "retry button", "try again", "reload", "refresh",
+    "something went wrong", "unable to load", "request failed",
+    "network error", "connection error", "problem", "alert", "recovery"
+  ],
+
+  "template": [
+    { "id": "root", "component": "Card", "children": ["col"] },
+    { "id": "col",  "component": "Column", "children": ["alert", "tile", "actions"], "gap": "3", "align": "center" },
+    { "id": "alert", "component": "Alert", "variant": "danger",
+      "title": "Something went wrong",
+      "description": "We couldn't complete that request. Check your connection and try again." },
+    { "id": "tile", "$fragment": "icon-title-description",
+      "bindings": { "icon": "alert-circle", "title": "Request failed", "description": "The server returned an error. Retrying may resolve the issue." } },
+    { "id": "actions", "component": "Row", "gap": "2", "align": "center", "children": ["retry", "cancel"] },
+    { "id": "retry",  "component": "Button", "variant": "primary", "icon": "refresh-cw", "text": "Retry" },
+    { "id": "cancel", "component": "Button", "variant": "ghost", "text": "Go back" }
+  ]
+}

package/compositions/agent/loading-skeleton.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "../_schema.json",
+  "name": "loading-skeleton",
+  "version": 1,
+  "kind": "composition",
+  "domain": "agent",
+  "description": "Skeleton placeholder mimicking a card layout — shown during data loading for perceived-performance.",
+  "tags": {
+    "purpose": ["loading", "skeleton", "placeholder"],
+    "complexity": "atomic",
+    "layout": "stacked"
+  },
+  "keywords": ["skeleton", "loading", "placeholder", "shimmer", "loader"],
+
+  "template": [
+    { "id": "root", "component": "Card", "children": ["hdr", "sec"] },
+    { "id": "hdr", "component": "Header", "children": ["sk-title"] },
+    { "id": "sk-title", "component": "Skeleton", "width": "40%", "height": "1.5rem" },
+    { "id": "sec", "component": "Section", "children": ["col"] },
+    { "id": "col", "component": "Column", "children": ["l1", "l2", "l3"], "gap": "2" },
+    { "id": "l1", "component": "Skeleton", "width": "100%", "height": "1rem" },
+    { "id": "l2", "component": "Skeleton", "width": "90%",  "height": "1rem" },
+    { "id": "l3", "component": "Skeleton", "width": "75%",  "height": "1rem" }
+  ]
+}

package/compositions/agent/loading-skeleton.yaml

@@ -0,0 +1,31 @@
+# Generated by scripts/generate-yaml-scaffolds.mjs
+# Narrative doc — JSON sibling remains the canonical machine source.
+# Fill in TODO sections by hand.
+
+$schema: ../../../../../scripts/schemas/composition.yaml.schema.json
+kind: composition
+name: loading-skeleton
+domain: agent
+description: >-
+  Skeleton placeholder mimicking a card layout — shown during data loading for perceived-performance.
+keywords:
+  - skeleton
+  - loading
+  - placeholder
+  - shimmer
+  - loader
+tags:
+  purpose:
+    - loading
+    - skeleton
+    - placeholder
+  complexity: atomic
+  layout: stacked
+related: []
+fragments_used: []
+use-cases:
+  - "TODO: primary use case"
+wiring-intent:
+  summary: Static composition (no interactive wiring).
+  controllers: []
+  actions: []