# 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.

