@flowstack-ui/brick 0.1.2 → 0.1.4

package/README.md

@@ -7,6 +7,10 @@ Brick provides static CSS, semantic design tokens, light and dark appearances,
 responsive defaults, and documented customization hooks. Components are ready
 to use without requiring an application-level CSS processor.
 
+The complete stylesheet also gives the document body a token-driven canvas,
+foreground, and default body typography. Themes change those semantic tokens;
+applications can deliberately override the low-specificity foundation later.
+
 ## Installation
 
 ```bash
@@ -24,7 +28,8 @@ Import the complete stylesheet once in the application root:
 import "@flowstack-ui/brick/styles.css";
 ```
 
-New applications may opt into Brick's separate reset:
+New applications may opt into Brick's separate neutral reset for page sizing,
+margin removal, and browser normalization:
 
 ```ts
 import "@flowstack-ui/brick/reset.css";

package/dist/agents/app-bar.json

@@ -0,0 +1,57 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "app-bar",
+  "name": "AppBar",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Provide a finished top surface and one-row start, geometrically centered, and end alignment structure built on Atom AppBar.",
+  "useWhen": [
+    "A page or application header needs branding, navigation, location, search, or persistent actions on one top surface."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The need is a complete responsive shell, navigation system, or grouped-control keyboard model.",
+      "useInstead": "AppBar composed with Show/Hide, NavigationMenu or NavList, Drawer, and Toolbar as appropriate"
+    }
+  ],
+  "composition": [
+    "Compose Root > Toolbar > Start, Center, and End, then place Brick brand, navigation, text, and action components in the matching sections."
+  ],
+  "rules": [
+    {
+      "id": "appbar-structural-toolbar",
+      "level": "must",
+      "statement": "Do not treat AppBar.Toolbar as an ARIA toolbar; compose Toolbar for grouped-control keyboard behavior."
+    },
+    {
+      "id": "appbar-responsive-owner",
+      "level": "must",
+      "statement": "Keep application-specific visibility and wrapping policy outside AppBar and implement it with Brick responsive/layout components."
+    },
+    {
+      "id": "appbar-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus app-bar.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Hand-building a header row with div and flex CSS or expecting AppBar to create menus and breakpoints.",
+      "correction": "Use AppBar for the top surface and compose the dedicated navigation, layout, and visibility owners inside it."
+    }
+  ],
+  "validation": [
+    "Check geometric centering with unequal side content, truncation, zoom, narrow widths, and RTL.",
+    "Confirm landmark names, actions, navigation, and modular CSS are complete."
+  ],
+  "related": [
+    "toolbar",
+    "navigation-menu",
+    "nav-list",
+    "drawer",
+    "show",
+    "hide",
+    "stack"
+  ]
+}

package/dist/agents/app-bar.md

@@ -0,0 +1,42 @@
+# AppBar agent guide
+
+## Purpose
+
+Provide a finished top surface and one-row start, geometrically centered, and end alignment structure built on Atom AppBar.
+
+## Use when
+
+- A page or application header needs branding, navigation, location, search, or persistent actions on one top surface.
+
+## Choose something else when
+
+- The need is a complete responsive shell, navigation system, or grouped-control keyboard model. Use AppBar composed with Show/Hide, NavigationMenu or NavList, Drawer, and Toolbar as appropriate.
+
+## Required composition
+
+- Compose Root > Toolbar > Start, Center, and End, then place Brick brand, navigation, text, and action components in the matching sections.
+
+## Rules
+
+- **MUST:** Do not treat AppBar.Toolbar as an ARIA toolbar; compose Toolbar for grouped-control keyboard behavior.
+- **MUST:** Keep application-specific visibility and wrapping policy outside AppBar and implement it with Brick responsive/layout components.
+- **MUST:** Load styles.css or core.css plus app-bar.css.
+
+## Common mistakes
+
+- **Avoid:** Hand-building a header row with div and flex CSS or expecting AppBar to create menus and breakpoints. **Instead:** Use AppBar for the top surface and compose the dedicated navigation, layout, and visibility owners inside it.
+
+## Validation checklist
+
+- Check geometric centering with unequal side content, truncation, zoom, narrow widths, and RTL.
+- Confirm landmark names, actions, navigation, and modular CSS are complete.
+
+## Related guidance
+
+- `toolbar`
+- `navigation-menu`
+- `nav-list`
+- `drawer`
+- `show`
+- `hide`
+- `stack`

package/dist/agents/bottom-navigation.json

@@ -0,0 +1,55 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "bottom-navigation",
+  "name": "BottomNavigation",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Style a short, stable set of primary compact-application destinations with active state and label-visibility recipes.",
+  "useWhen": [
+    "A compact application needs a small fixed set of primary destinations at the bottom edge."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Navigation is longer, grouped, top-level disclosure navigation, or local panel switching.",
+      "useInstead": "NavList, NavigationMenu, or Tabs"
+    }
+  ],
+  "composition": [
+    "Place named Items with unique values inside Root; provide href for destinations and include text labels even when the selected visual recipe hides them."
+  ],
+  "rules": [
+    {
+      "id": "bottom-navigation-labels",
+      "level": "must",
+      "statement": "Keep every icon destination's text accessible in every label-visibility mode."
+    },
+    {
+      "id": "bottom-navigation-overlay",
+      "level": "must",
+      "statement": "When fixed or sticky, coordinate application content and safe-area spacing outside the component."
+    },
+    {
+      "id": "bottom-navigation-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus bottom-navigation.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using BottomNavigation as a generic mobile menu or removing labels from the DOM.",
+      "correction": "Use Drawer/NavList for a menu and preserve each Item label."
+    }
+  ],
+  "validation": [
+    "Check active, disabled, label visibility, safe areas, narrow widths, touch targets, focus, and RTL.",
+    "Confirm URL destinations render links and CSS is loaded."
+  ],
+  "related": [
+    "nav-list",
+    "tabs",
+    "icon-button",
+    "show",
+    "hide"
+  ]
+}

package/dist/agents/bottom-navigation.md

@@ -0,0 +1,40 @@
+# BottomNavigation agent guide
+
+## Purpose
+
+Style a short, stable set of primary compact-application destinations with active state and label-visibility recipes.
+
+## Use when
+
+- A compact application needs a small fixed set of primary destinations at the bottom edge.
+
+## Choose something else when
+
+- Navigation is longer, grouped, top-level disclosure navigation, or local panel switching. Use NavList, NavigationMenu, or Tabs.
+
+## Required composition
+
+- Place named Items with unique values inside Root; provide href for destinations and include text labels even when the selected visual recipe hides them.
+
+## Rules
+
+- **MUST:** Keep every icon destination's text accessible in every label-visibility mode.
+- **MUST:** When fixed or sticky, coordinate application content and safe-area spacing outside the component.
+- **MUST:** Load styles.css or core.css plus bottom-navigation.css.
+
+## Common mistakes
+
+- **Avoid:** Using BottomNavigation as a generic mobile menu or removing labels from the DOM. **Instead:** Use Drawer/NavList for a menu and preserve each Item label.
+
+## Validation checklist
+
+- Check active, disabled, label visibility, safe areas, narrow widths, touch targets, focus, and RTL.
+- Confirm URL destinations render links and CSS is loaded.
+
+## Related guidance
+
+- `nav-list`
+- `tabs`
+- `icon-button`
+- `show`
+- `hide`

package/dist/agents/breadcrumb.json

@@ -0,0 +1,48 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "breadcrumb",
+  "name": "Breadcrumb",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Present page ancestry as a finished named navigation trail while preserving Atom breadcrumb semantics.",
+  "useWhen": [
+    "Users need to see the current page's place in a hierarchy and navigate to ancestors."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The relationship is result pagination, local panels, or general navigation.",
+      "useInstead": "Pagination, Tabs, or NavList"
+    }
+  ],
+  "composition": [
+    "Compose Root > List with Item containing ancestor Link or the one current Page, separated by decorative Separator; use an accessible button when Ellipsis is interactive."
+  ],
+  "rules": [
+    {
+      "id": "breadcrumb-current",
+      "level": "must",
+      "statement": "Render one current Page and keep ancestor destinations as Links."
+    },
+    {
+      "id": "breadcrumb-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus breadcrumb.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Recreating the trail with spans and manual separators or making the current page a link.",
+      "correction": "Use the complete Breadcrumb anatomy and its current Page part."
+    }
+  ],
+  "validation": [
+    "Check landmark naming, current state, collapsed hierarchy, focus rings, overflow, zoom, and RTL.",
+    "Confirm separators are decorative and CSS is loaded."
+  ],
+  "related": [
+    "link",
+    "pagination",
+    "nav-list"
+  ]
+}

package/dist/agents/breadcrumb.md

@@ -0,0 +1,37 @@
+# Breadcrumb agent guide
+
+## Purpose
+
+Present page ancestry as a finished named navigation trail while preserving Atom breadcrumb semantics.
+
+## Use when
+
+- Users need to see the current page's place in a hierarchy and navigate to ancestors.
+
+## Choose something else when
+
+- The relationship is result pagination, local panels, or general navigation. Use Pagination, Tabs, or NavList.
+
+## Required composition
+
+- Compose Root > List with Item containing ancestor Link or the one current Page, separated by decorative Separator; use an accessible button when Ellipsis is interactive.
+
+## Rules
+
+- **MUST:** Render one current Page and keep ancestor destinations as Links.
+- **MUST:** Load styles.css or core.css plus breadcrumb.css.
+
+## Common mistakes
+
+- **Avoid:** Recreating the trail with spans and manual separators or making the current page a link. **Instead:** Use the complete Breadcrumb anatomy and its current Page part.
+
+## Validation checklist
+
+- Check landmark naming, current state, collapsed hierarchy, focus rings, overflow, zoom, and RTL.
+- Confirm separators are decorative and CSS is loaded.
+
+## Related guidance
+
+- `link`
+- `pagination`
+- `nav-list`

package/dist/agents/button.json

@@ -0,0 +1,49 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "button",
+  "name": "Button",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Render a finished accessible action or emphasized native link with Brick size, tone, variant, loading, and composition contracts.",
+  "useWhen": [
+    "The user triggers an action such as submit, save, open, dismiss, or retry.",
+    "A destination intentionally needs a filled, soft, outlined, or ghost action treatment."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "A destination should read as ordinary inline or standalone navigation.",
+      "useInstead": "Link"
+    }
+  ],
+  "composition": [
+    "Omit href for actions and supply href for emphasized destinations; choose tone, variant, and size from intent and add an icon only when it improves recognition."
+  ],
+  "rules": [
+    {
+      "id": "button-semantics",
+      "level": "must",
+      "statement": "Use action mode for operations and href link mode for emphasized destinations; visual prominence never justifies hiding navigation in onPress."
+    },
+    {
+      "id": "button-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus button.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Navigating from onPress without a real href.",
+      "correction": "Use Button href mode for emphasized navigation or Link for ordinary navigation."
+    }
+  ],
+  "validation": [
+    "Confirm an accessible name and action semantics.",
+    "Test focus, keyboard activation, disabled/loading behavior, and contrast in every supported appearance."
+  ],
+  "related": [
+    "@flowstack-ui/atom/agents/button",
+    "link",
+    "form"
+  ]
+}

package/dist/agents/button.md

@@ -0,0 +1,38 @@
+# Button agent guide
+
+## Purpose
+
+Render a finished accessible action or emphasized native link with Brick size, tone, variant, loading, and composition contracts.
+
+## Use when
+
+- The user triggers an action such as submit, save, open, dismiss, or retry.
+- A destination intentionally needs a filled, soft, outlined, or ghost action treatment.
+
+## Choose something else when
+
+- A destination should read as ordinary inline or standalone navigation. Use Link.
+
+## Required composition
+
+- Omit href for actions and supply href for emphasized destinations; choose tone, variant, and size from intent and add an icon only when it improves recognition.
+
+## Rules
+
+- **MUST:** Use action mode for operations and href link mode for emphasized destinations; visual prominence never justifies hiding navigation in onPress.
+- **MUST:** Load styles.css or core.css plus button.css.
+
+## Common mistakes
+
+- **Avoid:** Navigating from onPress without a real href. **Instead:** Use Button href mode for emphasized navigation or Link for ordinary navigation.
+
+## Validation checklist
+
+- Confirm an accessible name and action semantics.
+- Test focus, keyboard activation, disabled/loading behavior, and contrast in every supported appearance.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/button`
+- `link`
+- `form`

package/dist/agents/card.json

@@ -0,0 +1,50 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "card",
+  "name": "Card",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Group content about one subject in a finished static compound surface with header, content, and footer anatomy.",
+  "useWhen": [
+    "A bounded subject needs a title, supporting content, and optional actions as one visual unit."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Only generic background, border, radius, or elevation is needed.",
+      "useInstead": "Surface"
+    }
+  ],
+  "composition": [
+    "Compose Card.Root with only the Header, Title, Description, Content, and Footer parts the subject needs."
+  ],
+  "rules": [
+    {
+      "id": "card-not-clickable-div",
+      "level": "must",
+      "statement": "Do not turn the whole Card into an unnamed clickable div; place explicit Link or Button controls inside or use a valid link composition."
+    },
+    {
+      "id": "card-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus card.css and styles for nested components."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Card for every spacing group.",
+      "correction": "Use Stack or Surface when there is no bounded card subject."
+    }
+  ],
+  "validation": [
+    "Check heading order and explicit action names.",
+    "Check content flow, focus visibility, narrow widths, and appearance contrast."
+  ],
+  "related": [
+    "surface",
+    "stack",
+    "grid",
+    "button",
+    "link"
+  ]
+}

package/dist/agents/card.md

@@ -0,0 +1,39 @@
+# Card agent guide
+
+## Purpose
+
+Group content about one subject in a finished static compound surface with header, content, and footer anatomy.
+
+## Use when
+
+- A bounded subject needs a title, supporting content, and optional actions as one visual unit.
+
+## Choose something else when
+
+- Only generic background, border, radius, or elevation is needed. Use Surface.
+
+## Required composition
+
+- Compose Card.Root with only the Header, Title, Description, Content, and Footer parts the subject needs.
+
+## Rules
+
+- **MUST:** Do not turn the whole Card into an unnamed clickable div; place explicit Link or Button controls inside or use a valid link composition.
+- **MUST:** Load styles.css or core.css plus card.css and styles for nested components.
+
+## Common mistakes
+
+- **Avoid:** Using Card for every spacing group. **Instead:** Use Stack or Surface when there is no bounded card subject.
+
+## Validation checklist
+
+- Check heading order and explicit action names.
+- Check content flow, focus visibility, narrow widths, and appearance contrast.
+
+## Related guidance
+
+- `surface`
+- `stack`
+- `grid`
+- `button`
+- `link`

package/dist/agents/checkbox.json

@@ -0,0 +1,49 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "checkbox",
+  "name": "Checkbox",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Render a finished independent checked, unchecked, or mixed selection with Atom interaction and form behavior.",
+  "useWhen": [
+    "A user independently turns an option on or off, or an aggregate parent represents mixed child selection."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Exactly one option must be selected from a set.",
+      "useInstead": "RadioGroup"
+    }
+  ],
+  "composition": [
+    "Compose Checkbox.Root with Checkbox.Indicator and a visible associated label, usually inside Field or Fieldset."
+  ],
+  "rules": [
+    {
+      "id": "checkbox-label",
+      "level": "must",
+      "statement": "Give every checkbox a visible associated label unless context is genuinely redundant and an accessible name remains."
+    },
+    {
+      "id": "checkbox-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus checkbox.css and any Field/Fieldset styles used."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Checkbox for a one-of-many choice.",
+      "correction": "Use RadioGroup for mutually exclusive options."
+    }
+  ],
+  "validation": [
+    "Toggle with Space, pointer, and touch.",
+    "Inspect checked/mixed and disabled states, label hit target, submitted value, focus, and contrast."
+  ],
+  "related": [
+    "@flowstack-ui/atom/agents/checkbox",
+    "field",
+    "fieldset",
+    "radio-group"
+  ]
+}

package/dist/agents/checkbox.md

@@ -0,0 +1,38 @@
+# Checkbox agent guide
+
+## Purpose
+
+Render a finished independent checked, unchecked, or mixed selection with Atom interaction and form behavior.
+
+## Use when
+
+- A user independently turns an option on or off, or an aggregate parent represents mixed child selection.
+
+## Choose something else when
+
+- Exactly one option must be selected from a set. Use RadioGroup.
+
+## Required composition
+
+- Compose Checkbox.Root with Checkbox.Indicator and a visible associated label, usually inside Field or Fieldset.
+
+## Rules
+
+- **MUST:** Give every checkbox a visible associated label unless context is genuinely redundant and an accessible name remains.
+- **MUST:** Load styles.css or core.css plus checkbox.css and any Field/Fieldset styles used.
+
+## Common mistakes
+
+- **Avoid:** Using Checkbox for a one-of-many choice. **Instead:** Use RadioGroup for mutually exclusive options.
+
+## Validation checklist
+
+- Toggle with Space, pointer, and touch.
+- Inspect checked/mixed and disabled states, label hit target, submitted value, focus, and contrast.
+
+## Related guidance
+
+- `@flowstack-ui/atom/agents/checkbox`
+- `field`
+- `fieldset`
+- `radio-group`

package/dist/agents/container.json

@@ -0,0 +1,54 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "container",
+  "name": "Container",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Own consistent centered content width, logical page gutters, and size variants for sections and application shells.",
+  "useWhen": [
+    "Page or section content needs a shared maximum inline size and responsive logical gutters."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The region needs a visual boundary or only a local one-axis relationship.",
+      "useInstead": "Surface/Card or Stack"
+    }
+  ],
+  "composition": [
+    "Place section content inside Container, then use Stack or Grid for internal relationships; let full-bleed backgrounds live outside it."
+  ],
+  "rules": [
+    {
+      "id": "container-width-owner",
+      "level": "must",
+      "statement": "Use Container rather than repeating application max-width, auto-margin, and gutter CSS across sections."
+    },
+    {
+      "id": "container-not-surface",
+      "level": "must",
+      "statement": "Do not use Container as a visual card or background owner."
+    },
+    {
+      "id": "container-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus container.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Applying a separate max-width class to every page section or nesting Containers without a width reason.",
+      "correction": "Use one deliberate Container boundary per aligned content region."
+    }
+  ],
+  "validation": [
+    "Check gutters and max width at all adopted breakpoints, zoom levels, and RTL.",
+    "Confirm full-bleed and contained regions align intentionally and CSS is loaded."
+  ],
+  "related": [
+    "stack",
+    "grid",
+    "surface",
+    "card"
+  ]
+}

package/dist/agents/container.md

@@ -0,0 +1,39 @@
+# Container agent guide
+
+## Purpose
+
+Own consistent centered content width, logical page gutters, and size variants for sections and application shells.
+
+## Use when
+
+- Page or section content needs a shared maximum inline size and responsive logical gutters.
+
+## Choose something else when
+
+- The region needs a visual boundary or only a local one-axis relationship. Use Surface/Card or Stack.
+
+## Required composition
+
+- Place section content inside Container, then use Stack or Grid for internal relationships; let full-bleed backgrounds live outside it.
+
+## Rules
+
+- **MUST:** Use Container rather than repeating application max-width, auto-margin, and gutter CSS across sections.
+- **MUST:** Do not use Container as a visual card or background owner.
+- **MUST:** Load styles.css or core.css plus container.css.
+
+## Common mistakes
+
+- **Avoid:** Applying a separate max-width class to every page section or nesting Containers without a width reason. **Instead:** Use one deliberate Container boundary per aligned content region.
+
+## Validation checklist
+
+- Check gutters and max width at all adopted breakpoints, zoom levels, and RTL.
+- Confirm full-bleed and contained regions align intentionally and CSS is loaded.
+
+## Related guidance
+
+- `stack`
+- `grid`
+- `surface`
+- `card`