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

## ChatShell
- chat-shell is a behavior wrapper; don't nest col-ui/row-ui inside it directly — author the structural DOM using [data-chat-*] markers instead.

## EditorShell
- editor-shell is a layout skeleton. Children must follow the documented structural DOM; the element wires behavior, not content.

## GenRoot
- gen-root is an integration shell. Prefer admin-shell for admin UIs; use gen-root only for chat+canvas tooling.

## AppShell
- admin-shell 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.

