@adia-ai/adia-ui-factory 0.2.3 → 0.8.0

package/skills/adia-ui-kit/references/patterns-forms.md

@@ -1,223 +0,0 @@
-# Form Patterns
-
-## Basic Form
-
-```html
-<card-ui>
-  <header>
-    <span slot="heading" variant="section">Create Account</span>
-    <span slot="description">Fill in your details</span>
-  </header>
-  <section>
-    <form>
-      <col-ui gap="4">
-        <input-ui label="Full Name" name="name" required placeholder="Jane Doe"></input-ui>
-        <input-ui label="Email" name="email" type="email" required placeholder="jane@example.com"></input-ui>
-        <input-ui label="Password" name="password" type="password" required minlength="8"></input-ui>
-        <field-ui label="Bio">
-          <textarea-ui name="bio" placeholder="Tell us about yourself"></textarea-ui>
-        </field-ui>
-        <select-ui label="Role" name="role">
-          <option value="developer">Developer</option>
-          <option value="designer">Designer</option>
-          <option value="manager">Manager</option>
-        </select-ui>
-        <check-ui name="terms" label="I agree to the terms"></check-ui>
-        <button-ui text="Create Account" variant="primary" type="submit" stretch></button-ui>
-      </col-ui>
-    </form>
-  </section>
-</card-ui>
-```
-
-## Key Rules
-
-- Use a raw `<form>` element to wrap fields for native submit serialization
-- Every field needs a `name` for form data collection
-- Use `label` attribute (not a separate `<label>` element)
-- Use `required`, `minlength`, `maxlength`, `pattern` for constraint validation
-- Custom error messages: `data-msg-required="Please enter your name"` etc.
-- `<button-ui type="submit">` triggers submission
-- `form-submit` event: `{ detail: { action, method, data } }`
-- Form validates on submit automatically — surfaces errors on invalid fields
-- On input after error: re-validates to clear as soon as value is valid
-
-## Validation
-
-```html
-<!-- Built-in constraints -->
-<input-ui label="Email" name="email" type="email" required
-  data-msg-required="Email is required"
-  data-msg-pattern="Enter a valid email">
-</input-ui>
-
-<input-ui label="Username" name="user" required minlength="3" maxlength="20"
-  pattern="[a-z0-9_]+"
-  data-msg-pattern="Only lowercase letters, numbers, and underscores">
-</input-ui>
-```
-
-Programmatic validation:
-```js
-const field = document.querySelector('input-ui[name="email"]');
-field.validate();           // returns boolean, surfaces error
-field.setInvalid('Custom error message');
-field.setValid();
-```
-
-## Login Form
-
-```html
-<card-ui size="lg" style="max-width:400px">
-  <header center>
-    <span slot="heading" variant="section">Welcome back</span>
-    <span slot="description">Sign in to your account</span>
-  </header>
-  <section>
-    <form action="/api/login" method="post">
-      <col-ui gap="4">
-        <input-ui label="Email" name="email" type="email" required prefix="envelope"></input-ui>
-        <input-ui label="Password" name="password" type="password" required suffix="eye"></input-ui>
-        <row-ui justify="between" align="center">
-          <check-ui name="remember" label="Remember me"></check-ui>
-          <a href="/forgot" style="font-size:var(--a-font-size-xs)">Forgot password?</a>
-        </row-ui>
-        <button-ui text="Sign In" variant="primary" type="submit" stretch></button-ui>
-      </col-ui>
-    </form>
-  </section>
-</card-ui>
-```
-
-## Settings Panel with Toggles
-
-```html
-<card-ui>
-  <header divider>
-    <span slot="heading" variant="section">Notifications</span>
-    <span slot="description">Manage how you receive notifications</span>
-  </header>
-  <section>
-    <col-ui gap="4">
-      <row-ui justify="between" align="center">
-        <col-ui gap="1">
-          <strong>Email notifications</strong>
-          <small style="color:var(--a-canvas-text-subtle)">Receive updates via email</small>
-        </col-ui>
-        <switch-ui name="email-notif"></switch-ui>
-      </row-ui>
-      <divider-ui></divider-ui>
-      <row-ui justify="between" align="center">
-        <col-ui gap="1">
-          <strong>Push notifications</strong>
-          <small style="color:var(--a-canvas-text-subtle)">Browser push alerts</small>
-        </col-ui>
-        <switch-ui name="push-notif"></switch-ui>
-      </row-ui>
-    </col-ui>
-  </section>
-</card-ui>
-```
-
-## Input with Icons
-
-```html
-<input-ui label="Search" prefix="magnifying-glass" placeholder="Search..."></input-ui>
-<input-ui label="Amount" prefix="currency-dollar" placeholder="0.00"></input-ui>
-<input-ui label="Password" type="password" suffix="eye"></input-ui>
-```
-
-## Where field affordances go — status text vs buttons vs captions
-
-Three different homes. Pick by what the affordance **is**, not where it visually sits:
-
-| Affordance | Home | Result |
-|---|---|---|
-| Short **status / label text** — "Required", "Results: 12", "Light", "USD" | input-ui `prefix=` / `suffix=` (string props) | renders **inside** the input chrome, before/after the value; input stays full-width |
-| **Interactive controls** — clear, copy, ⌘K hint, open-in-modal | `<button-ui slot="leading">` / `slot="trailing">` (or `<kbd-ui slot="trailing">`) **inside `<input-ui>`** | installed into the chrome; DOM order `prefix → leading → value → suffix → trailing` |
-| A caption / count / submit **beside** the field (outside the input box) | `slot="trailing"` / `slot="action"` on the **`<field-ui>`** (not the input) | sits next to the input row, not inside the chrome |
-
-```html
-<!-- status text in-chrome → input suffix; clear button → input trailing slot -->
-<field-ui inline label="Filter">
-  <input-ui placeholder="Name or tag" suffix="Results: 12">
-    <button-ui slot="trailing" icon="x" variant="ghost" aria-label="Clear"></button-ui>
-  </input-ui>
-</field-ui>
-```
-
-**Don't** put short status text in a `slot="trailing"` element — the affordance slots are for interactive controls; text belongs in `suffix`/`prefix` so it stays in-chrome and the input keeps full width. (bug-55 / bug-60.)
-
-## Raw Input (embedded in custom container)
-
-```html
-<card-ui>
-  <section>
-    <row-ui gap="2" align="center">
-      <icon-ui name="magnifying-glass"></icon-ui>
-      <input-ui raw placeholder="Search anything..." style="flex:1"></input-ui>
-    </row-ui>
-  </section>
-</card-ui>
-```
-
-`raw` strips background, border, padding, radius, outline, and height from `input-ui`.
-
-## OTP Input
-
-```html
-<card-ui size="lg" style="max-width:400px;text-align:center">
-  <header center>
-    <span slot="heading" variant="section">Verify your email</span>
-    <span slot="description">Enter the 6-digit code</span>
-  </header>
-  <section>
-    <col-ui gap="4" style="align-items:center">
-      <otp-input-ui length="6"></otp-input-ui>
-      <button-ui text="Verify" variant="primary" stretch></button-ui>
-    </col-ui>
-  </section>
-</card-ui>
-```
-
-## Wired Form (with A007)
-
-A form that fetches data, validates, and submits via wiring:
-
-```json
-{
-  "type": "wireComponents",
-  "surfaceId": "profile",
-  "data": {
-    "sources": [{ "id": "user", "path": "/user", "uri": "resource://users/{userId}", "refresh": "once" }],
-    "params": { "userId": { "from": "route", "key": "id" } }
-  },
-  "state": {
-    "controllers": [{ "id": "form", "type": "FormController", "host": "form-root", "config": { "validateOn": "blur" } }]
-  },
-  "actions": [{
-    "event": "form-submit", "source": "form-root",
-    "handler": "submit-resource", "method": "PUT", "uri": "resource://users/{userId}",
-    "body": { "from": "event-detail", "key": "data" },
-    "onSuccess": { "notify": "Profile saved" },
-    "onError": { "notify": "Save failed" }
-  }]
-}
-```
-
-Fields bind to the data model: `"value": { "path": "/user/name" }` — auto-populated from fetch.
-
-## Date, Color, Slider
-
-```html
-<field-ui label="Appointment">
-  <datetime-picker-ui name="appt"></datetime-picker-ui>
-</field-ui>
-<field-ui label="Date of Birth">
-  <calendar-picker-ui name="dob"></calendar-picker-ui>
-</field-ui>
-<field-ui label="Brand Color">
-  <color-picker-ui name="color"></color-picker-ui>
-</field-ui>
-<slider-ui min="0" max="100" value="50"></slider-ui>
-```

package/skills/adia-ui-kit/references/patterns-layout.md

@@ -1,326 +0,0 @@
-# Layout Patterns
-
-## Card — The Universal Container
-
-Every surface is built from cards. The content model is mandatory.
-
-```html
-<card-ui>
-  <header>
-    <span slot="icon"><icon-ui name="users"></icon-ui></span>
-    <span slot="heading" variant="section">Team Members</span>
-    <span slot="description">Active members in your workspace</span>
-    <button-ui slot="action" text="Add" variant="ghost" icon="plus" size="sm"></button-ui>
-  </header>
-  <section>
-    <col-ui gap="2">
-      <!-- content always inside col-ui -->
-    </col-ui>
-  </section>
-  <footer divider>
-    <span slot="description">12 members total</span>
-    <button-ui slot="action" text="View All" variant="outline" size="sm"></button-ui>
-  </footer>
-</card-ui>
-```
-
-Header grid adapts to present slots:
-- `icon` + `action`: `max-content 1fr max-content`
-- `icon` only: `max-content 1fr`
-- `action` only: `1fr max-content`
-- Neither: `1fr`
-
-`[divider]` on header/footer adds a border separator with padding.
-`[center]` on header centers text and items.
-`[bleed]` on section removes padding (edge-to-edge content like images or tables).
-
-## Card Sizes
-
-```html
-<card-ui size="xl">Hero-level — largest inset, biggest radius</card-ui>
-<card-ui size="lg">Spacious — old default card scale</card-ui>
-<card-ui>Default (md) — standard card</card-ui>
-<card-ui size="sm">Compact — row-level density</card-ui>
-<card-ui size="xs">Ultra-dense — minimal inset</card-ui>
-```
-
-Each size sets: `--inset` (padding), `--radius`, `--gap`, and all heading/text font sizes.
-
-## Card Variants
-
-```html
-<card-ui variant="outlined">Visible border, transparent background, no shadow</card-ui>
-<card-ui variant="filled">Filled background</card-ui>
-<card-ui variant="ghost">Transparent background and border</card-ui>
-<card-ui raw>No background, border, or shadow — structural wrapper only</card-ui>
-<card-ui elevation="0">Flat (no shadow)</card-ui>
-<card-ui elevation="2">Medium shadow</card-ui>
-<card-ui elevation="3">Strong shadow</card-ui>
-```
-
-`raw` strips all chrome. The card's content model (header/section/footer) still applies.
-
-## Stack Layout
-
-```html
-<!-- Vertical stack -->
-<col-ui gap="4">
-  <input-ui label="Name"></input-ui>
-  <input-ui label="Email"></input-ui>
-  <button-ui text="Submit" variant="primary"></button-ui>
-</col-ui>
-
-<!-- Horizontal row -->
-<row-ui gap="2" justify="between" align="center">
-  <span>Total: $49.99</span>
-  <button-ui text="Pay Now" variant="primary"></button-ui>
-</row-ui>
-
-<!-- Nested: action bar -->
-<row-ui justify="between">
-  <button-ui text="Back" variant="ghost"></button-ui>
-  <row-ui gap="2">
-    <button-ui text="Cancel" variant="outline"></button-ui>
-    <button-ui text="Save" variant="primary"></button-ui>
-  </row-ui>
-</row-ui>
-```
-
-`justify` values: `start`, `end`, `center`, `between`, `around`, `evenly`.
-`align` values: `start`, `end`, `center`, `stretch`, `baseline`.
-
-All three string props (`gap`, `align`, `justify`) on `col-ui` and `row-ui` accept `@bp` responsive notation — see **Responsive Layout** below.
-
-## Grid
-
-```html
-<!-- Equal columns -->
-<grid-ui columns="3" gap="4">
-  <card-ui>Card 1</card-ui>
-  <card-ui>Card 2</card-ui>
-  <card-ui>Card 3</card-ui>
-</grid-ui>
-
-<!-- Asymmetric: 3:2 split -->
-<grid-ui columns="5" gap="4">
-  <card-ui span="3">Wide</card-ui>
-  <card-ui span="2">Narrow</card-ui>
-</grid-ui>
-```
-
-Canonical ratios: `2:1 → columns="3" + span="2"` · `3:2 → columns="5" + span="3"+"2"` · `4:1 → columns="5" + span="4"` · `3:1 → columns="4" + span="3"`.
-
-Never set `grid-template-columns` via inline style — use `columns=` and child `span=` instead. `columns` and `gap` both accept `@bp` notation.
-
-> ⚠️ **`gap=` and `columns=` take NUMERIC tokens, NOT size keywords.** Valid: `gap="3"`, `gap="4"`, `gap="6"`, `columns="3"`, `columns="2 4@md"`. **Invalid**: `gap="md"`, `gap="lg"`, `gap="small"`, `columns="auto"`. The numbers map to `--a-space-N` density tokens — `gap="4"` resolves to `var(--a-space-4)`. Size keywords are a `<button-ui size="sm">` / `<badge-ui size="lg">` convention; layout primitives use numeric density tokens. Same rule applies to `col-ui` and `row-ui` `gap=`. Anti-pattern visible in agent-generated DOM: `<grid-ui columns="3" gap="md">` — renders without gap (invalid token falls back to default 0 or browser default).
-
-## Responsive Layout
-
-Props on `grid-ui`, `col-ui`, `row-ui`, `text-ui`, and `block-ui` accept `@bp` annotations for viewport-driven layout. No media queries, no utility classes, no hidden elements.
-
-### Syntax
-
-Append `@breakpoint` to any value that should apply from that breakpoint upward. The unannotated value is the mobile-first base (smallest screens). The largest annotation that is ≤ the active breakpoint wins.
-
-```
-columns="1 2@sm 4@lg"   →  1 at xs · 2 at sm/md · 4 at lg/xl
-gap="2 4@md"            →  2 below md · 4 from md up
-justify="start between@md"
-```
-
-### Breakpoint scale
-
-| Name | Min-width | Typical target |
-|---|---|---|
-| `xs` | 0 px | Portrait phone (base — no annotation needed) |
-| `sm` | 480 px | Large phone / portrait tablet |
-| `md` | 768 px | Landscape tablet |
-| `lg` | 1024 px | Small desktop |
-| `xl` | 1280 px | Standard desktop+ |
-
-### Supported props
-
-| Component | Responsive props |
-|---|---|
-| `grid-ui` | `columns`, `gap` |
-| `col-ui` | `gap`, `align`, `justify` |
-| `row-ui` | `gap`, `align`, `justify`; `wrap-at="bp"` for responsive wrap |
-| `text-ui` | `size` |
-| `block-ui` | `padding`, `margin` |
-
-### Common patterns
-
-```html
-<!-- Dashboard KPI grid: 2×2 on mobile, 4-up from tablet -->
-<grid-ui columns="2 4@md" gap="4">
-  <card-ui>...</card-ui>
-  <card-ui>...</card-ui>
-  <card-ui>...</card-ui>
-  <card-ui>...</card-ui>
-</grid-ui>
-
-<!-- Chart + sidebar: stacked on mobile, 3:2 split from tablet -->
-<grid-ui columns="1 5@md" gap="4">
-  <card-ui span="3">Chart</card-ui>
-  <card-ui span="2">Sidebar</card-ui>
-</grid-ui>
-
-<!-- 3-up strip: stacked on mobile, side-by-side from tablet -->
-<grid-ui columns="1 3@md" gap="4">
-  <card-ui>Team</card-ui>
-  <card-ui>Actions</card-ui>
-  <card-ui>Storage</card-ui>
-</grid-ui>
-
-<!-- Toolbar: stacked + tight on mobile, spread + roomy on desktop -->
-<row-ui gap="2 4@md" justify="start between@md" align="start center@md" wrap>
-  <text-ui strong>Recent transactions</text-ui>
-  <row-ui gap="2">
-    <button-ui text="Export" variant="outline"></button-ui>
-    <button-ui text="+ New" variant="primary"></button-ui>
-  </row-ui>
-</row-ui>
-
-<!-- Responsive text size -->
-<text-ui variant="heading" size="sm md@lg">Welcome back</text-ui>
-
-<!-- Less padding on mobile -->
-<block-ui padding="sm md@lg">...</block-ui>
-```
-
-**Responsive wrap** — boolean attrs like `wrap` can't use `@bp` value syntax; use `wrap-at="bp"` instead:
-
-```html
-&lt;!-- Toolbar: single row on desktop, wraps on mobile --&gt;
-&lt;row-ui gap="2 3@md" wrap-at="sm"&gt;
-  &lt;input-ui placeholder="Search..."&gt;&lt;/input-ui&gt;
-  &lt;button-ui text="Export" variant="outline"&gt;&lt;/button-ui&gt;
-  &lt;button-ui text="+ New" variant="primary"&gt;&lt;/button-ui&gt;
-&lt;/row-ui&gt;
-```
-
-**Anti-pattern:** never write `@media` blocks, inline `style=`, or hidden-element tricks for layout breakpoints on these components. The `@bp` attribute is the canonical path and is understood by the A2UI generation pipeline.
-
-## App Shell
-
-Full application layout with sidebar, header bar, and content area.
-
-```html
-<admin-shell mode="sidebar">
-  <nav slot="sidebar">
-    <sidebar-ui>
-      <header><span slot="heading" variant="section">MyApp</span></header>
-      <nav-ui>
-        <a href="/" data-active>Dashboard</a>
-        <a href="/settings">Settings</a>
-        <a href="/team">Team</a>
-      </nav-ui>
-    </sidebar-ui>
-  </nav>
-  <header slot="header">
-    <row-ui justify="between" align="center" style="padding:var(--a-space-2) var(--a-space-4)">
-      <h3 variant="section">Dashboard</h3>
-      <avatar-ui text="Jane" size="sm"></avatar-ui>
-    </row-ui>
-  </header>
-  <main slot="content">
-    <!-- page content -->
-  </main>
-</app-shell-ui>
-```
-
-Modes: `sidebar` (default), `sidebar-collapsed`, `header-only`, `minimal`.
-
-**Pitfall — flat CSS selector collapses shell layout (FB-04):**
-Consumer boilerplate sometimes includes a `/* Shell fill */` block:
-```css
-/* ❌ collapses the shell */
-admin-shell { display: block; height: 100dvh; }
-```
-Because `admin-shell` is a custom element, a flat CSS selector on the tag name wins the cascade when imported after the shell's own stylesheet (`display: flex` from the component). The entire sidebar + content grid collapses to a block stack. **Never set `display` on `admin-shell` directly.** The shell already manages its own display. To fill the viewport, set `height: 100dvh` on the `<body>` or a wrapping `<div>` instead, or use `min-height`:
-```css
-/* ✅ safe */
-body { margin: 0; height: 100dvh; display: flex; flex-direction: column; }
-admin-shell { flex: 1; min-height: 0; }
-```
-To adjust shell geometry, override the shell's CSS custom properties (e.g. `--page-sidebar-width-leading`, `--page-header-height`) rather than the component's structural CSS.
-
-## Tabs
-
-Tabs are a button strip. Content panels are **siblings**, not children.
-
-```html
-<col-ui gap="4">
-  <tabs-ui value="profile">
-    <tab-ui value="profile" text="Profile"></tab-ui>
-    <tab-ui value="security" text="Security"></tab-ui>
-    <tab-ui value="billing" text="Billing"></tab-ui>
-  </tabs-ui>
-  <!-- Panels shown/hidden based on active tab -->
-  <card-ui><!-- profile panel --></card-ui>
-</col-ui>
-```
-
-Variants: `line` (underline indicator) or `pill` (filled background).
-
-## Modal / Dialog / Drawer
-
-Modal is a chromeless overlay — child content owns all visual styling:
-
-```html
-<modal-ui open size="md">
-  <card-ui>
-    <header><span slot="heading" variant="section">Confirm</span></header>
-    <section><p>Are you sure?</p></section>
-    <footer>
-      <button-ui text="Cancel" variant="outline"></button-ui>
-      <button-ui text="Confirm" variant="primary"></button-ui>
-    </footer>
-  </card-ui>
-</modal-ui>
-```
-
-Dialog for simple confirmations (uses `<confirm-dialog-ui>` from web-modules/feedback):
-```html
-<confirm-dialog-ui title="Delete?" description="This cannot be undone." confirm-text="Delete" cancel-text="Keep"></confirm-dialog-ui>
-```
-
-Drawer slides from an edge:
-```html
-<drawer-ui open side="right">
-  <header><span slot="heading" variant="section">Details</span></header>
-  <section>Content</section>
-</drawer-ui>
-```
-
-## Theming
-
-```html
-<!-- CSS-only preset (zero JS) -->
-<div theme="ocean">
-  <card-ui>Ocean themed</card-ui>
-</div>
-
-<!-- Interactive theme switcher (renders preset buttons + optional sliders) -->
-<popover-ui>
-  <button-ui slot="trigger" text="Theme"></button-ui>
-  <theme-panel slot="content" parametric presets scheme-toggle></theme-panel>
-</popover-ui>
-```
-
-Presets: default, ocean, forest, sunset, lavender, rose, slate, midnight.
-
-Parametric tuning (applied as CSS custom properties on the wrapping element when `[parametric]` is set on `<theme-panel>`): `--a-density`, `--a-radius-k`, `--a-chroma`, `--a-space-scale`, `--a-shadow-scale`, `--a-motion-scale`.
-
-## Headings
-
-Use `[variant]` for visual emphasis — `<h1>`-`<h6>` are purely structural:
-
-```html
-<h1 variant="display">Hero text</h1>
-<h2 variant="title">Page title</h2>
-<h3 variant="section">Section heading</h3>
-<span variant="label">Label text</span>
-<span variant="eyebrow">Overline</span>
-<span variant="caption">Caption</span>
-```