@flowstack-ui/brick 0.1.9 → 0.1.11

package/dist/agents/hover-card.json

@@ -0,0 +1,94 @@
+{
+  "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/dist/agents/hover-card.md

@@ -0,0 +1,51 @@
+# 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`

package/dist/agents/icon-button.json

@@ -5,29 +5,39 @@
   "package": "@flowstack-ui/brick",
   "layer": "brick",
   "kind": "component",
-  "purpose": "Provide a compact finished action control for a single recognizable icon with an explicit accessible name.",
+  "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 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": "The control navigates, needs visible explanatory text, or is an arbitrary clickable surface.",
-      "useInstead": "Link, Button, or another owning component"
+      "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 and provide an accessible label through the component's naming API."
+    "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 is not a name."
+      "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-action",
+      "id": "icon-button-expanded-feedback",
       "level": "must",
-      "statement": "Use IconButton for actions, not ordinary navigation."
+      "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",
@@ -37,17 +47,18 @@
   ],
   "commonMistakes": [
     {
-      "mistake": "Using a random glyph, code icon for GitHub, or unlabeled SVG inside a generic button.",
-      "correction": "Use the correct icon asset in a named IconButton."
+      "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, icon alignment, touch target, focus ring, disabled/loading states, contrast, and forced colors.",
-    "Confirm component CSS is loaded."
+    "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/dist/agents/icon-button.md

@@ -2,38 +2,42 @@
 
 ## Purpose
 
-Provide a compact finished action control for a single recognizable icon with an explicit accessible name.
+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
 
-- The control navigates, needs visible explanatory text, or is an arbitrary clickable surface. Use Link, Button, or another owning component.
+- 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 and provide an accessible label through the component's naming API.
+- 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 is not a name.
-- **MUST:** Use IconButton for actions, not ordinary navigation.
+- **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, or unlabeled SVG inside a generic button. **Instead:** Use the correct icon asset in a named IconButton.
+- **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, icon alignment, touch target, focus ring, disabled/loading states, contrast, and forced colors.
-- Confirm component CSS is loaded.
+- 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`

package/dist/agents/image.json

@@ -7,9 +7,13 @@
   "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, or content image needs Brick sizing, fit, radius, loading, or fallback presentation."
+    "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"
@@ -17,7 +21,8 @@
   ],
   "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."
+    "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": [
     {
@@ -30,10 +35,30 @@
       "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": "should",
-      "statement": "Reserve dimensions or aspect ratio to prevent layout shift."
+      "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",
@@ -58,12 +83,13 @@
   ],
   "commonMistakes": [
     {
-      "mistake": "Using next/image automatically, wrapping Image in spans for ordinary alignment, or duplicating the caption in alt text.",
-      "correction": "Start with Brick Image, use Brick layout components, and adapt only for a measured missing optimizer capability."
+      "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, responsive size, parent-fill geometry, crop, layout shift, alt text, contrast of fallback content, and RTL where relevant.",
+    "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": [

package/dist/agents/image.md

@@ -6,22 +6,28 @@ Provide styled resilient media with Atom loading/fallback behavior, sizing recip
 
 ## Use when
 
-- A product image, brand asset, illustration, or content image needs Brick sizing, fit, radius, loading, or fallback presentation.
+- 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.
-- **SHOULD:** Reserve dimensions or aspect ratio to prevent layout shift.
+- **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.
@@ -29,11 +35,12 @@ Provide styled resilient media with Atom loading/fallback behavior, sizing recip
 
 ## Common mistakes
 
-- **Avoid:** Using next/image automatically, wrapping Image in spans for ordinary alignment, or duplicating the caption in alt text. **Instead:** Start with Brick Image, use Brick layout components, and adapt only for a measured missing optimizer capability.
+- **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, responsive size, parent-fill geometry, crop, layout shift, alt text, contrast of fallback content, and RTL where relevant.
+- 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

package/dist/agents/input.json

@@ -16,7 +16,7 @@
     }
   ],
   "composition": [
-    "Place Input inside one Field.Root after Field.Label; provide name, type, and autocomplete appropriate to the data."
+    "Place Input inside one Field.Root after Field.Label; provide name, type, and autocomplete appropriate to the data. Use outline when the containing surface should remain visible and soft when Input should own a filled plane."
   ],
   "rules": [
     {
@@ -41,7 +41,12 @@
     "Test focus, entry, autofill, invalid/disabled states, zoom, and both appearances."
   ],
   "related": [
-    "@flowstack-ui/atom/agents/input",
+    {
+      "kind": "package",
+      "package": "@flowstack-ui/atom",
+      "id": "input",
+      "versionPolicy": "installed-exact"
+    },
     "field",
     "textarea"
   ]

package/dist/agents/input.md

@@ -14,7 +14,7 @@ Render finished native single-line text entry with Brick sizing, states, and Ato
 
 ## Required composition
 
-- Place Input inside one Field.Root after Field.Label; provide name, type, and autocomplete appropriate to the data.
+- Place Input inside one Field.Root after Field.Label; provide name, type, and autocomplete appropriate to the data. Use outline when the containing surface should remain visible and soft when Input should own a filled plane.
 
 ## Rules