@flowstack-ui/agent-tools 0.1.0-bootstrap.0

package/public/packages/brick/0.1.11/components/hover-card.txt

@@ -0,0 +1,156 @@
+# HoverCard
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: hover-card
+
+# HoverCard agent guide
+
+## Purpose
+
+Present a finished supplemental, nonessential, non-interactive preview from a genuine link or similarly meaningful trigger while Atom owns hover, focus-visible, dismissal, portal, and positioning behavior.
+
+## Use when
+
+- A genuine link or other focusable subject benefits from a richer passive preview whose information is redundant with the destination or visible page.
+
+## Choose something else when
+
+- The content is a brief text hint, contains controls or required actions, must hold focus, or is essential on touch and non-hover input. Use Tooltip, Popover, Dialog, or visible inline content.
+
+## Required composition
+
+- Compose HoverCard.Root with HoverCard.Trigger asChild around a genuine semantic link, plus HoverCard.Portal and HoverCard.Content; add HoverCard.Arrow only when the styled preview needs a pointer. Content may contain passive Brick text, Avatar, Badge, and layout components but no interactive descendants.
+- Choose Content size sm, md, or lg from preview measure. Brick keeps non-Arrow children in its private scrolling viewport and Arrow as a direct Content child; do not target the private viewport. Reproduce any local Appearance scope on portalled Content.
+
+## Rules
+
+- **MUST:** Keep every essential fact and required action available outside Content because touch does not open HoverCard and the preview is not promised to assistive technology.
+- **MUST:** Do not put links, buttons, inputs, menus, or required interaction inside Content; use Popover for interactive floating content.
+- **MUST:** Preserve Trigger's genuine native destination, complete accessible name, action, and tab order through asChild or render; do not add popup, expanded, controls, or dialog semantics.
+- **MUST:** Preserve Atom's mouse-capable hover, focus-visible opening, delays, safe pointer corridor, Escape handling, and touch and compatibility-event suppression; touch must retain the native Trigger action without opening the preview.
+- **MUST:** Keep Content generic and nonsemantic, choose size only for bounded measure, let the private viewport own constrained scrolling, and keep optional Arrow as a direct Content child.
+- **SHOULD:** Style and validate from the collision-resolved data-side and available viewport bounds rather than assuming the requested placement always wins.
+- **MUST:** When Portal leaves a local Appearance scope, reproduce that scope on Content or target a portal container inside it.
+- **MUST:** Load styles.css or core.css plus hover-card.css and every composed child component stylesheet.
+
+## Common mistakes
+
+- **Avoid:** Putting a profile action or essential fact only in HoverCard, expecting touch to open it, or adding popup ARIA relationships. **Instead:** Keep the preview passive and redundant, preserve the trigger destination, and use Popover or visible content when users must interact or access the information.
+- **Avoid:** Using HoverCard for a short label, targeting its private viewport, or assuming portalled Content inherits local Appearance. **Instead:** Use Tooltip for brief hints, customize only public parts and tokens, and make the portal scope explicit.
+
+## Validation checklist
+
+- Verify the genuine Trigger destination and name, controlled and disabled state, mouse hover and focus-visible opening, delays, Trigger-to-Content pointer corridor, Escape, focus stability, and that touch taps and long presses preserve native Trigger activation without opening.
+- Audit Content for no essential or interactive descendants and no popup ARIA; verify portal and render composition, three bounded sizes, private scrolling, direct optional Arrow, collision flips and shifts, and available-size containment.
+- Verify 256px containment, zoom, long localization, LTR and RTL, reduced motion, forced colors, light and dark portalled appearance, and complete CSS.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/hover-card`
+- `tooltip`
+- `popover`
+- `dialog`
+- `link`
+- `avatar`
+- `badge`
+- `appearance`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "hover-card",
+  "name": "HoverCard",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present a finished supplemental, nonessential, non-interactive preview from a genuine link or similarly meaningful trigger while Atom owns hover, focus-visible, dismissal, portal, and positioning behavior.",
+  "useWhen": [
+    "A genuine link or other focusable subject benefits from a richer passive preview whose information is redundant with the destination or visible page."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The content is a brief text hint, contains controls or required actions, must hold focus, or is essential on touch and non-hover input.",
+      "useInstead": "Tooltip, Popover, Dialog, or visible inline content"
+    }
+  ],
+  "composition": [
+    "Compose HoverCard.Root with HoverCard.Trigger asChild around a genuine semantic link, plus HoverCard.Portal and HoverCard.Content; add HoverCard.Arrow only when the styled preview needs a pointer. Content may contain passive Brick text, Avatar, Badge, and layout components but no interactive descendants.",
+    "Choose Content size sm, md, or lg from preview measure. Brick keeps non-Arrow children in its private scrolling viewport and Arrow as a direct Content child; do not target the private viewport. Reproduce any local Appearance scope on portalled Content."
+  ],
+  "rules": [
+    {
+      "id": "hover-card-supplemental",
+      "level": "must",
+      "statement": "Keep every essential fact and required action available outside Content because touch does not open HoverCard and the preview is not promised to assistive technology."
+    },
+    {
+      "id": "hover-card-noninteractive",
+      "level": "must",
+      "statement": "Do not put links, buttons, inputs, menus, or required interaction inside Content; use Popover for interactive floating content."
+    },
+    {
+      "id": "hover-card-trigger-native",
+      "level": "must",
+      "statement": "Preserve Trigger's genuine native destination, complete accessible name, action, and tab order through asChild or render; do not add popup, expanded, controls, or dialog semantics."
+    },
+    {
+      "id": "hover-card-input-contract",
+      "level": "must",
+      "statement": "Preserve Atom's mouse-capable hover, focus-visible opening, delays, safe pointer corridor, Escape handling, and touch and compatibility-event suppression; touch must retain the native Trigger action without opening the preview."
+    },
+    {
+      "id": "hover-card-content-anatomy",
+      "level": "must",
+      "statement": "Keep Content generic and nonsemantic, choose size only for bounded measure, let the private viewport own constrained scrolling, and keep optional Arrow as a direct Content child."
+    },
+    {
+      "id": "hover-card-positioning",
+      "level": "should",
+      "statement": "Style and validate from the collision-resolved data-side and available viewport bounds rather than assuming the requested placement always wins."
+    },
+    {
+      "id": "hover-card-theme-scope",
+      "level": "must",
+      "statement": "When Portal leaves a local Appearance scope, reproduce that scope on Content or target a portal container inside it."
+    },
+    {
+      "id": "hover-card-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus hover-card.css and every composed child component stylesheet."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Putting a profile action or essential fact only in HoverCard, expecting touch to open it, or adding popup ARIA relationships.",
+      "correction": "Keep the preview passive and redundant, preserve the trigger destination, and use Popover or visible content when users must interact or access the information."
+    },
+    {
+      "mistake": "Using HoverCard for a short label, targeting its private viewport, or assuming portalled Content inherits local Appearance.",
+      "correction": "Use Tooltip for brief hints, customize only public parts and tokens, and make the portal scope explicit."
+    }
+  ],
+  "validation": [
+    "Verify the genuine Trigger destination and name, controlled and disabled state, mouse hover and focus-visible opening, delays, Trigger-to-Content pointer corridor, Escape, focus stability, and that touch taps and long presses preserve native Trigger activation without opening.",
+    "Audit Content for no essential or interactive descendants and no popup ARIA; verify portal and render composition, three bounded sizes, private scrolling, direct optional Arrow, collision flips and shifts, and available-size containment.",
+    "Verify 256px containment, zoom, long localization, LTR and RTL, reduced motion, forced colors, light and dark portalled appearance, and complete CSS."
+  ],
+  "related": [
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "hover-card",
+      "versionPolicy": "installed-exact"
+    },
+    "tooltip",
+    "popover",
+    "dialog",
+    "link",
+    "avatar",
+    "badge",
+    "appearance"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/icon-button.txt

@@ -0,0 +1,119 @@
+# IconButton
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: icon-button
+
+# IconButton agent guide
+
+## Purpose
+
+Provide a compact finished icon-only action or deliberate icon-only navigation control with an explicit accessible name.
+
+## Use when
+
+- A familiar icon represents one action and visible button text would be redundant in the available space.
+- A compact rail or similarly constrained navigation context deliberately uses a recognizable icon-only destination.
+
+## Choose something else when
+
+- A destination needs persistent visible explanatory text or should read as an ordinary inline or standalone link. Use Link or a navigation collection's Link part.
+- The control represents a persistent pressed selection. Use Toggle.
+
+## Required composition
+
+- Place one decorative Icon or SVG inside IconButton, provide an accessible label through the component's naming API, and supply href when the control is a destination. Tooltip may supplement an unfamiliar icon but never replaces the control name.
+
+## Rules
+
+- **MUST:** Give every IconButton a concise discernible accessible name; the icon alone and a portalled Tooltip are not names.
+- **MUST:** Use the default button path for operations and supply href for a deliberate icon-only navigation destination so the final host remains a native anchor.
+- **MUST:** Keep temporary aria-expanded feedback distinct from a persistent pressed selection; use Toggle when the state itself is the user-controlled value.
+- **MUST:** Load styles.css or core.css plus icon-button.css and icon.css when using Brick Icon.
+
+## Common mistakes
+
+- **Avoid:** Using a random glyph, code icon for GitHub, an unlabeled SVG inside a generic button, a command button without href for a route, or Tooltip as the only name. **Instead:** Use the correct icon asset in a named IconButton, supply href for navigation, and keep Tooltip supplemental.
+
+## Validation checklist
+
+- Check accessible name, button versus anchor semantics, href, icon alignment, touch target, focus ring, Tooltip discovery when present, expanded disclosure feedback, disabled/loading states, contrast, and forced colors.
+- Confirm component CSS and every composed Tooltip or Icon stylesheet are loaded.
+
+## Related guidance
+
+- `button`
+- `icon`
+- `link`
+- `toolbar`
+- `tooltip`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "icon-button",
+  "name": "IconButton",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Provide a compact finished icon-only action or deliberate icon-only navigation control with an explicit accessible name.",
+  "useWhen": [
+    "A familiar icon represents one action and visible button text would be redundant in the available space.",
+    "A compact rail or similarly constrained navigation context deliberately uses a recognizable icon-only destination."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "A destination needs persistent visible explanatory text or should read as an ordinary inline or standalone link.",
+      "useInstead": "Link or a navigation collection's Link part"
+    },
+    {
+      "condition": "The control represents a persistent pressed selection.",
+      "useInstead": "Toggle"
+    }
+  ],
+  "composition": [
+    "Place one decorative Icon or SVG inside IconButton, provide an accessible label through the component's naming API, and supply href when the control is a destination. Tooltip may supplement an unfamiliar icon but never replaces the control name."
+  ],
+  "rules": [
+    {
+      "id": "icon-button-name",
+      "level": "must",
+      "statement": "Give every IconButton a concise discernible accessible name; the icon alone and a portalled Tooltip are not names."
+    },
+    {
+      "id": "icon-button-semantics",
+      "level": "must",
+      "statement": "Use the default button path for operations and supply href for a deliberate icon-only navigation destination so the final host remains a native anchor."
+    },
+    {
+      "id": "icon-button-expanded-feedback",
+      "level": "must",
+      "statement": "Keep temporary aria-expanded feedback distinct from a persistent pressed selection; use Toggle when the state itself is the user-controlled value."
+    },
+    {
+      "id": "icon-button-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus icon-button.css and icon.css when using Brick Icon."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using a random glyph, code icon for GitHub, an unlabeled SVG inside a generic button, a command button without href for a route, or Tooltip as the only name.",
+      "correction": "Use the correct icon asset in a named IconButton, supply href for navigation, and keep Tooltip supplemental."
+    }
+  ],
+  "validation": [
+    "Check accessible name, button versus anchor semantics, href, icon alignment, touch target, focus ring, Tooltip discovery when present, expanded disclosure feedback, disabled/loading states, contrast, and forced colors.",
+    "Confirm component CSS and every composed Tooltip or Icon stylesheet are loaded."
+  ],
+  "related": [
+    "button",
+    "icon",
+    "link",
+    "toolbar",
+    "tooltip"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/icon.txt

@@ -0,0 +1,160 @@
+# Icon
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: icon
+
+# Icon agent guide
+
+## Purpose
+
+Normalize one consumer-authored SVG with Brick sizing, semantic foreground, alignment, direction, and decorative-or-informative accessibility semantics.
+
+## Use when
+
+- An authored SVG needs Brick size, currentColor-based tone, alignment, or opt-in directional RTL mirroring.
+
+## Choose something else when
+
+- The graphic performs an action or needs its own touch target. Use Button, IconButton, Toggle, or the owning interactive component.
+- The content is a photo, raster asset, responsive media object, fallback, or loading state. Use Image.
+- The graphic is a logo, illustration, chart, or multiregion visual with independent semantics. Use an application-owned SVG or media composition with explicit semantics.
+
+## Required composition
+
+- Pass exactly one consumer-authored SVG element; prefer the default span wrapper and use asChild only when the direct root must remain that SVG.
+- When visible nearby text already provides the meaning, keep Icon decorative; when a standalone icon conveys information, provide label or aria-labelledby.
+- Inside an icon-only control, label the control and leave its nested Icon decorative.
+
+## Rules
+
+- **MUST:** Use Icon only for visual content; never use it as an interactive host or touch target.
+- **MUST:** Keep the decorative default when meaning is redundant, or provide exactly one nonempty label or aria-labelledby reference when the standalone graphic is informative.
+- **MUST:** Give an icon-only Button, IconButton, Toggle, or other control its accessible name on the control, not on its nested Icon.
+- **SHOULD:** Use currentColor for single-color SVG fills or strokes so Brick tone and inherited control state can apply.
+- **MUST:** Enable directional only for glyphs whose meaning reverses in RTL, such as arrows and forward/back controls.
+- **MUST:** Use asChild only with one direct non-interactive SVG; never compose Icon onto a button, anchor, input, or other interactive host.
+- **MUST:** Use Brick Stack, layout components, or an owning component icon slot for sibling alignment instead of wrapper spans or application offsets.
+- **MUST:** Load styles.css or core.css plus icon.css.
+
+## Common mistakes
+
+- **Avoid:** Using a raw SVG with ad hoc width, color, alignment, or ARIA inside ordinary Brick composition. **Instead:** Wrap the authored SVG in Icon, choose the semantic size/tone recipe, and let the owning Stack or control align it.
+- **Avoid:** Giving both the control and its nested Icon the same accessible label. **Instead:** Label the control and keep the nested Icon decorative to prevent duplicate announcements.
+- **Avoid:** Using directional on logos, status symbols, checks, clocks, or other glyphs that do not reverse meaning in RTL. **Instead:** Leave directional false unless the glyph itself communicates direction.
+
+## Validation checklist
+
+- Check decorative and informative accessibility trees, icon-only control naming, all sizes and tones, currentColor adoption, flex shrinking, and RTL directional mirroring.
+- Confirm asChild targets only one SVG and that CSS is present.
+
+## Related guidance
+
+- `icon-button`
+- `image`
+- `button`
+- `stack`
+- `text`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "icon",
+  "name": "Icon",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Normalize one consumer-authored SVG with Brick sizing, semantic foreground, alignment, direction, and decorative-or-informative accessibility semantics.",
+  "useWhen": [
+    "An authored SVG needs Brick size, currentColor-based tone, alignment, or opt-in directional RTL mirroring."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The graphic performs an action or needs its own touch target.",
+      "useInstead": "Button, IconButton, Toggle, or the owning interactive component"
+    },
+    {
+      "condition": "The content is a photo, raster asset, responsive media object, fallback, or loading state.",
+      "useInstead": "Image"
+    },
+    {
+      "condition": "The graphic is a logo, illustration, chart, or multiregion visual with independent semantics.",
+      "useInstead": "an application-owned SVG or media composition with explicit semantics"
+    }
+  ],
+  "composition": [
+    "Pass exactly one consumer-authored SVG element; prefer the default span wrapper and use asChild only when the direct root must remain that SVG.",
+    "When visible nearby text already provides the meaning, keep Icon decorative; when a standalone icon conveys information, provide label or aria-labelledby.",
+    "Inside an icon-only control, label the control and leave its nested Icon decorative."
+  ],
+  "rules": [
+    {
+      "id": "icon-not-control",
+      "level": "must",
+      "statement": "Use Icon only for visual content; never use it as an interactive host or touch target."
+    },
+    {
+      "id": "icon-accessibility-mode",
+      "level": "must",
+      "statement": "Keep the decorative default when meaning is redundant, or provide exactly one nonempty label or aria-labelledby reference when the standalone graphic is informative."
+    },
+    {
+      "id": "icon-control-name",
+      "level": "must",
+      "statement": "Give an icon-only Button, IconButton, Toggle, or other control its accessible name on the control, not on its nested Icon."
+    },
+    {
+      "id": "icon-current-color",
+      "level": "should",
+      "statement": "Use currentColor for single-color SVG fills or strokes so Brick tone and inherited control state can apply."
+    },
+    {
+      "id": "icon-directional",
+      "level": "must",
+      "statement": "Enable directional only for glyphs whose meaning reverses in RTL, such as arrows and forward/back controls."
+    },
+    {
+      "id": "icon-as-child",
+      "level": "must",
+      "statement": "Use asChild only with one direct non-interactive SVG; never compose Icon onto a button, anchor, input, or other interactive host."
+    },
+    {
+      "id": "icon-layout",
+      "level": "must",
+      "statement": "Use Brick Stack, layout components, or an owning component icon slot for sibling alignment instead of wrapper spans or application offsets."
+    },
+    {
+      "id": "icon-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus icon.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using a raw SVG with ad hoc width, color, alignment, or ARIA inside ordinary Brick composition.",
+      "correction": "Wrap the authored SVG in Icon, choose the semantic size/tone recipe, and let the owning Stack or control align it."
+    },
+    {
+      "mistake": "Giving both the control and its nested Icon the same accessible label.",
+      "correction": "Label the control and keep the nested Icon decorative to prevent duplicate announcements."
+    },
+    {
+      "mistake": "Using directional on logos, status symbols, checks, clocks, or other glyphs that do not reverse meaning in RTL.",
+      "correction": "Leave directional false unless the glyph itself communicates direction."
+    }
+  ],
+  "validation": [
+    "Check decorative and informative accessibility trees, icon-only control naming, all sizes and tones, currentColor adoption, flex shrinking, and RTL directional mirroring.",
+    "Confirm asChild targets only one SVG and that CSS is present."
+  ],
+  "related": [
+    "icon-button",
+    "image",
+    "button",
+    "stack",
+    "text"
+  ]
+}
+```

package/public/packages/brick/0.1.11/components/image.txt

@@ -0,0 +1,163 @@
+# Image
+
+Source: @flowstack-ui/brick@0.1.11
+Kind: component
+ID: image
+
+# Image agent guide
+
+## Purpose
+
+Provide styled resilient media with Atom loading/fallback behavior, sizing recipes, and accessible image semantics.
+
+## Use when
+
+- A product image, brand asset, illustration, content image, or larger editorial/profile portrait needs Brick sizing, authored aspect ratio, fit, focal position, radius, loading, or fallback presentation.
+
+## Choose something else when
+
+- A person or entity needs a compact fixed-square identity token with explicit fallback content. Use Avatar.
+- A framework optimizer provides a required measured optimization Brick does not expose. Use a documented Image adapter that preserves semantics and reports the capability gap.
+
+## Required composition
+
+- Compose Image.Content and optional Image.Fallback inside Image.Root; use Brick Stack or layout components around it rather than wrapper spans for alignment.
+- In a React Server Component, import ImageRoot, ImageContent, and ImageFallback directly; the compound Image namespace is intended for client module composition.
+- Keep source state on Image.Root, then pass intrinsic width and height plus native responsive delivery props such as srcSet, sizes, loading, decoding, and fetchPriority to Image.Content.
+
+## Rules
+
+- **MUST:** Use Brick Image for ordinary interface media; document any native or framework image fallback and the missing capability.
+- **MUST:** Provide meaningful alt text, or alt="" for a decorative image.
+- **MUST:** For a profile portrait, preserve the person's name as alt when the portrait communicates identity; use alt="" only when that specific portrait is intentionally decorative.
+- **MUST:** Reserve intrinsic width and height or an authored parent aspect ratio so image arrival does not create layout shift.
+- **MUST:** When a rendered slot changes materially by viewport or container, provide source candidates and an accurate sizes contract so the browser does not receive one oversized raster by default.
+- **MUST:** Do not lazy-load a measured or strongly expected LCP image; keep it directly discoverable, load it eagerly, and use high fetch priority only for the small number of truly critical images.
+- **MUST:** Use native lazy loading for ordinary deferred images; when an exact application proximity or intent boundary is required, let the application decide when to attach the source because loading=lazy remains a browser scheduling hint.
+- **MUST:** Use explicit fill when Image must consume a parent-established block size, such as Surface.Media; retain fit and position for the intended crop.
+- **MUST:** Name and preserve the parent sizing box when fill is used; Image propagates into available geometry but does not create that geometry.
+- **MUST:** Load styles.css or core.css plus image.css.
+- **MUST:** Use direct named Image parts across a React Server Component boundary instead of wrapping the complete consumer in use client.
+
+## Common mistakes
+
+- **Avoid:** Using next/image automatically, forcing a larger authored profile portrait into Avatar's compact square recipe, wrapping Image in spans for ordinary alignment, applying one blanket alt decision to all portraits, sending one desktop raster to every slot, or lazy-loading the likely LCP image. **Instead:** Start with Brick Image for larger authored media, use Avatar for compact identity, decide alt from each image's context, reserve geometry, provide responsive candidates and accurate sizes, keep critical media discoverable, and adapt only for a measured missing optimizer capability.
+
+## Validation checklist
+
+- Check loaded, loading, error, cached, narrow and wide source selection, transferred bytes, priority, parent-fill geometry, crop, layout shift, contextual alt text—including identity-bearing and intentionally decorative portraits—contrast of fallback content, and RTL where relevant.
+- For delivery-sensitive media, verify cold, warm, constrained-network, blocked-image, first-viewport, and post-proximity behavior; keep localhost timing separate from production or field evidence.
+- Confirm CSS and any adapter report are complete.
+
+## Related guidance
+
+- `aspect-ratio`
+- `stack`
+- `avatar`
+- `surface`
+
+## Machine record
+
+```json
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "image",
+  "name": "Image",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Provide styled resilient media with Atom loading/fallback behavior, sizing recipes, and accessible image semantics.",
+  "useWhen": [
+    "A product image, brand asset, illustration, content image, or larger editorial/profile portrait needs Brick sizing, authored aspect ratio, fit, focal position, radius, loading, or fallback presentation."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "A person or entity needs a compact fixed-square identity token with explicit fallback content.",
+      "useInstead": "Avatar"
+    },
+    {
+      "condition": "A framework optimizer provides a required measured optimization Brick does not expose.",
+      "useInstead": "a documented Image adapter that preserves semantics and reports the capability gap"
+    }
+  ],
+  "composition": [
+    "Compose Image.Content and optional Image.Fallback inside Image.Root; use Brick Stack or layout components around it rather than wrapper spans for alignment.",
+    "In a React Server Component, import ImageRoot, ImageContent, and ImageFallback directly; the compound Image namespace is intended for client module composition.",
+    "Keep source state on Image.Root, then pass intrinsic width and height plus native responsive delivery props such as srcSet, sizes, loading, decoding, and fetchPriority to Image.Content."
+  ],
+  "rules": [
+    {
+      "id": "image-brick-first",
+      "level": "must",
+      "statement": "Use Brick Image for ordinary interface media; document any native or framework image fallback and the missing capability."
+    },
+    {
+      "id": "image-alt",
+      "level": "must",
+      "statement": "Provide meaningful alt text, or alt=\"\" for a decorative image."
+    },
+    {
+      "id": "image-portrait-alt",
+      "level": "must",
+      "statement": "For a profile portrait, preserve the person's name as alt when the portrait communicates identity; use alt=\"\" only when that specific portrait is intentionally decorative."
+    },
+    {
+      "id": "image-layout",
+      "level": "must",
+      "statement": "Reserve intrinsic width and height or an authored parent aspect ratio so image arrival does not create layout shift."
+    },
+    {
+      "id": "image-responsive-delivery",
+      "level": "must",
+      "statement": "When a rendered slot changes materially by viewport or container, provide source candidates and an accurate sizes contract so the browser does not receive one oversized raster by default."
+    },
+    {
+      "id": "image-lcp-delivery",
+      "level": "must",
+      "statement": "Do not lazy-load a measured or strongly expected LCP image; keep it directly discoverable, load it eagerly, and use high fetch priority only for the small number of truly critical images."
+    },
+    {
+      "id": "image-deferred-delivery",
+      "level": "must",
+      "statement": "Use native lazy loading for ordinary deferred images; when an exact application proximity or intent boundary is required, let the application decide when to attach the source because loading=lazy remains a browser scheduling hint."
+    },
+    {
+      "id": "image-parent-fill",
+      "level": "must",
+      "statement": "Use explicit fill when Image must consume a parent-established block size, such as Surface.Media; retain fit and position for the intended crop."
+    },
+    {
+      "id": "image-parent-owner",
+      "level": "must",
+      "statement": "Name and preserve the parent sizing box when fill is used; Image propagates into available geometry but does not create that geometry."
+    },
+    {
+      "id": "image-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus image.css."
+    },
+    {
+      "id": "image-rsc-parts",
+      "level": "must",
+      "statement": "Use direct named Image parts across a React Server Component boundary instead of wrapping the complete consumer in use client."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using next/image automatically, forcing a larger authored profile portrait into Avatar's compact square recipe, wrapping Image in spans for ordinary alignment, applying one blanket alt decision to all portraits, sending one desktop raster to every slot, or lazy-loading the likely LCP image.",
+      "correction": "Start with Brick Image for larger authored media, use Avatar for compact identity, decide alt from each image's context, reserve geometry, provide responsive candidates and accurate sizes, keep critical media discoverable, and adapt only for a measured missing optimizer capability."
+    }
+  ],
+  "validation": [
+    "Check loaded, loading, error, cached, narrow and wide source selection, transferred bytes, priority, parent-fill geometry, crop, layout shift, contextual alt text—including identity-bearing and intentionally decorative portraits—contrast of fallback content, and RTL where relevant.",
+    "For delivery-sensitive media, verify cold, warm, constrained-network, blocked-image, first-viewport, and post-proximity behavior; keep localhost timing separate from production or field evidence.",
+    "Confirm CSS and any adapter report are complete."
+  ],
+  "related": [
+    "aspect-ratio",
+    "stack",
+    "avatar",
+    "surface"
+  ]
+}
+```