@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/components/ui/.alert.md

@@ -1,44 +1,49 @@
-<!-- source-hash: 658b99c6617a2e2c02da90f0de25e855 -->
-A reusable React Alert component system with customizable variants and structured content sections for displaying notifications and status messages.
+<!-- source-hash: d1d0661fd41f76c7fee69513f105b5c9 -->
+Accessible alert component with three style variants (`default`, `destructive`, `warning`) built using `class-variance-authority` and React's `forwardRef`.
 
 ## Key Components
 
-- **Alert**: Main container component with variant-based styling (default, destructive)
-- **AlertTitle**: Header component for alert titles with consistent typography
-- **AlertDescription**: Content wrapper for alert body text with optimized line spacing
-- **alertVariants**: CVA configuration defining visual styles and behavior for different alert types
+| Export | Type | Description |
+|--------|------|-------------|
+| `Alert` | `React.forwardRef` | Root container with `role="alert"`, accepts `variant` prop and optional SVG icon child |
+| `AlertTitle` | `React.forwardRef` | Renders as `<h5>` for the alert heading |
+| `AlertDescription` | `React.forwardRef` | Body text container with relaxed line-height for paragraph children |
+| `alertVariants` | `cva` config | CVA variant map driving Tailwind classes for each alert style |
+
+### Variants
+
+| Variant | Use Case |
+|---------|----------|
+| `default` | General informational messages |
+| `destructive` | Errors or dangerous actions |
+| `warning` | Cautionary notices (uses ODS warning tokens) |
 
 ## Usage Example
 
 ```typescript
-import { Alert, AlertTitle, AlertDescription } from "./alert"
-import { AlertTriangle, CheckCircle } from "lucide-react"
+import { Alert, AlertTitle, AlertDescription } from "./components/ui/alert"
+import { AlertTriangle } from "lucide-react"
 
-// Basic alert
+// Default
 <Alert>
-  <AlertTitle>Heads up!</AlertTitle>
-  <AlertDescription>
-    You can add components to your app using the cli.
-  </AlertDescription>
+  <AlertTitle>Heads up</AlertTitle>
+  <AlertDescription>Your session will expire in 5 minutes.</AlertDescription>
 </Alert>
 
-// Destructive alert with icon
+// Destructive with icon
 <Alert variant="destructive">
   <AlertTriangle className="h-4 w-4" />
   <AlertTitle>Error</AlertTitle>
-  <AlertDescription>
-    Your session has expired. Please log in again.
-  </AlertDescription>
+  <AlertDescription>Failed to sync device inventory.</AlertDescription>
 </Alert>
 
-// Success alert (using default variant with custom styling)
-<Alert className="border-green-200 bg-green-50">
-  <CheckCircle className="h-4 w-4 text-green-600" />
-  <AlertTitle>Success</AlertTitle>
-  <AlertDescription>
-    Your changes have been saved successfully.
-  </AlertDescription>
+// Warning
+<Alert variant="warning">
+  <AlertTitle>License expiring</AlertTitle>
+  <AlertDescription>Renew within 7 days to avoid service interruption.</AlertDescription>
 </Alert>
 ```
 
-The component automatically positions SVG icons and maintains proper spacing between elements using CSS selectors. All components are built with `forwardRef` for proper ref handling and include semantic HTML with appropriate ARIA roles.
+> **Icon support:** Placing an SVG/icon as a direct child of `Alert` automatically positions it absolutely at top-left and offsets sibling content via the `[&>svg~*]:pl-7` selector — no extra wrapper needed.
+
+**Source:** [`alert.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/alert.tsx)

package/src/components/ui/.allowed-domains-input.md

@@ -1,40 +1,49 @@
-<!-- source-hash: 4488babe1708a2df7fd49ce4d01e1ce8 -->
-A client-side React component for managing a list of allowed domains, supporting add/remove operations with optional validation, duplicate prevention, and error display.
+<!-- source-hash: c8820213197bd11f26ff9ef8929a556d -->
+A controlled React component for managing a list of allowed domains, supporting dynamic addition/removal, optional validation, and inline error display.
 
 ## Key Components
 
 ### `AllowedDomainsInputProps`
 
 | Prop | Type | Description |
-|------|------|-------------|
+|---|---|---|
 | `value` | `string[]` | Controlled list of current domains |
-| `onChange` | `(domains: string[]) => void` | Callback when domain list changes |
-| `onValidate` | `(domain: string) => { valid, error?, cleanedDomain? }` | Optional custom domain validator |
+| `onChange` | `(domains: string[]) => void` | Callback fired when the domain list changes |
+| `onValidate` | `(domain: string) => { valid: boolean; error?: string; cleanedDomain?: string }` | Optional custom validator; can return a sanitized domain |
 | `label` | `string` | Field label (default: `"Allowed Domains"`) |
 | `placeholder` | `string` | Input placeholder (default: `"example.com"`) |
 | `disabled` | `boolean` | Disables all interactions |
 | `error` | `string \| null` | External error message |
-| `helperText` | `string` | Helper text shown when no error is present |
+| `helperText` | `string` | Assistive text shown when no error is present |
+| `className` | `string` | Additional CSS classes |
 
 ### `AllowedDomainsInput`
 
 A `forwardRef` component that renders:
-- **Existing domain rows** — each as a disabled `Input` with an `X` remove button
-- **New domain input** — accepts `Enter` key or "Add Domain" button to submit
-- **Validation feedback** — displays external `error` or internal `localError`
+- Existing domains as read-only inputs with individual remove (`X`) buttons
+- A text input for entering new domains (supports `Enter` key to submit)
+- An **Add Domain** button with a `PlusCircle` icon
+- Inline error and helper text display
+
+Duplicate domains are silently rejected. Local validation errors are cleared on each input change.
 
 ## Usage Example
 
 ```typescript
 import { AllowedDomainsInput } from "@/components/ui/allowed-domains-input"
+import { useState } from "react"
 
-function SettingsForm() {
-  const [domains, setDomains] = React.useState<string[]>(["flamingo.run"])
+function DomainSettings() {
+  const [domains, setDomains] = useState<string[]>(["flamingo.run"])
 
   const validateDomain = (domain: string) => {
     const cleaned = domain.toLowerCase().replace(/^https?:\/\//, "")
-    const valid = /^[a-z0-9.-]+\.[a-z]{2,}$/.test(cleaned)
-    return { valid, error: valid ? undefined : "Enter a valid domain", cleanedDomain: cleaned }
+    const isValid = /^[a-z0-9.-]+\.[a-z]{2,}$/.test(cleaned)
+    return {
+      valid: isValid,
+      error: isValid ? undefined : "Enter a valid domain (e.g. example.com)",
+      cleanedDomain: cleaned,
+    }
   }
 
   return (
@@ -42,10 +51,12 @@ function SettingsForm() {
       value={domains}
       onChange={setDomains}
       onValidate={validateDomain}
-      helperText="Only users from these domains can sign in."
+      helperText="Only users from these domains can access the workspace."
     />
   )
 }
 ```
 
-> **Note:** Duplicate domains are silently ignored. If `onValidate` returns a `cleanedDomain`, that normalized value is stored instead of the raw input.
+## Source
+
+[`allowed-domains-input.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/components/ui/allowed-domains-input.tsx)

package/src/components/ui/.announcement-bar-view.md

@@ -0,0 +1,46 @@
+<!-- source-hash: 1b172d10def6d4e816cd2e6d05c9ff8e -->
+Presentational announcement/notification bar component that renders a fixed 44px single-line strip with icon, message, CTA, and dismiss slots — no data fetching or state management.
+
+## Key Components
+
+### `AnnouncementBarView`
+The sole export. A layout-only React component implementing the announcement bar pattern: one line of text, one compact CTA, and a trailing slot, all within a 44px-tall strip.
+
+### `AnnouncementBarViewProps`
+
+| Prop | Type | Description |
+|---|---|---|
+| `startAdornment` | `ReactNode` | Leading icon slot (20px below `md`, 24px above) |
+| `title` | `string \| ReactElement` | Bar message — plain strings get `text-h6` + truncation; elements own their markup |
+| `actionBlock` | `ReactElement` | Primary CTA, hidden below 800px breakpoint |
+| `endAdornment` | `ReactElement` | Trailing slot (e.g. dismiss button), outside tap target |
+| `onContentClick` | `() => void` | Mobile-only tap handler; no-op at `md`+ where CTA is visible |
+| `contentClassName` | `string` | Extra classes for the padded content row |
+| `className` | `string` | Surface styling (background, text color, theme scope) |
+| `style` | `CSSProperties` | Inline styles for the root element |
+
+### `MD_QUERY`
+Internal constant `(min-width: 800px)` — mirrors the `screens.md` Tailwind breakpoint. Guards `onContentClick` to prevent firing when the CTA is visible.
+
+## Usage Example
+
+```typescript
+import { AnnouncementBarView } from './announcement-bar-view';
+import { InfoIcon } from '../icons';
+import { Button } from '../button';
+
+<AnnouncementBarView
+  className="bg-brand-primary text-white"
+  startAdornment={<InfoIcon size={20} />}
+  title="New feature available — upgrade your plan to unlock it."
+  actionBlock={
+    <Button size="compact" variant="secondary" onClick={handleUpgrade}>
+      Upgrade
+    </Button>
+  }
+  endAdornment={<DismissButton onClick={handleDismiss} />}
+  onContentClick={handleUpgrade}
+/>
+```
+
+> ⚠️ **Design is locked.** The 44px height, `text-h6` scale, and single-row layout are owner-approved and must not be changed without explicit written sign-off. See [source](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/announcement-bar-view.tsx) for the full rationale comment.

package/src/components/ui/.autocomplete.md

@@ -1,23 +1,31 @@
-<!-- source-hash: c483f7e7ed16ddf489c0f0b85c84e31b -->
-A fully-featured autocomplete/combobox input component supporting both single and multi-select modes, with keyboard navigation, tag display, filtering, and creatable options.
+<!-- source-hash: fc6dd8036da3bf735d64b0d45b0be40c -->
+A fully-featured autocomplete/combobox React component supporting single and multi-select modes, keyboard navigation, tag overflow, creatable options, and server-side filtering.
 
 ## Key Components
 
 ### Types & Interfaces
-- **`AutocompleteOption<T>`** — Shape of each selectable option (`label` + `value`)
-- **`AutocompleteInputChangeReason`** — Union of `'input' | 'reset' | 'clear'`
-- **`AutocompleteSingleProps<T>`** — Props for single-select mode
-- **`AutocompleteMultipleProps<T>`** — Props for multi-select mode (adds `maxItems`, `renderTag`, `limitTags`, etc.)
-- **`AutocompleteProps<T>`** — Discriminated union of the two modes
-
-### Internal Logic
-- **`AutocompleteInner`** — Core render function wrapped with `forwardRef`, managing:
-  - Controlled/uncontrolled input value state
-  - Dropdown open/close via Radix `PopoverPrimitive`
-  - Option filtering (client-side or delegated via `disableClientFilter`)
-  - Keyboard navigation (`ArrowDown/Up`, `Enter`, `Escape`)
-  - Tag overflow via `useAutoLimitTags` hook
-  - `freeSolo` and `creatable` modes
+
+| Export | Description |
+|---|---|
+| `AutocompleteOption<T>` | Shape of a selectable option: `{ label, value }` |
+| `AutocompleteInputChangeReason` | `'input' \| 'reset' \| 'clear'` — reason passed to `onInputChange` |
+| `AutocompleteSingleProps<T>` | Props for single-select mode |
+| `AutocompleteMultipleProps<T>` | Props for multi-select mode (adds `maxItems`, `renderTag`, `limitTags`, `getLimitTagsText`) |
+| `AutocompleteProps<T>` | Union of single and multiple prop types |
+
+### Core Behaviors
+
+- **Single mode** — selects one value; input shows selected label when closed, clears on open (configurable via `clearOnOpen`)
+- **Multi mode** — toggles values in an array; renders selected items as tags with auto-limiting overflow (`limitTags: number | "auto"`)
+- **Creatable** — shows a `+ Create` option when no results match; blocked by `maxCreateLength`
+- **Server-side filtering** — set `disableClientFilter: true` and drive options via `onInputChange`
+- **Controlled input** — pass `inputValue` to fully control the text field
+- **Keyboard navigation** — arrow keys, Enter, and Escape supported via `highlightedIndex` state
+
+### Internal Hooks & Utilities
+
+- `useAutoLimitTags` — calculates how many tags fit the container width
+- `useImperativeHandle` — exposes the container `div` ref to parent via `forwardRef`
 
 ## Usage Example
 
@@ -26,29 +34,34 @@ A fully-featured autocomplete/combobox input component supporting both single an
 <Autocomplete
   options={[{ label: "Option A", value: "a" }, { label: "Option B", value: "b" }]}
   value={selected}
-  onChange={(val) => setSelected(val)}
-  label="Pick one"
-  placeholder="Search..."
+  onChange={setSelected}
+  placeholder="Select an option"
+  label="My Field"
 />
 
-// Multi-select with tag limit and creatable
+// Multi-select with tag limit and creatable options
 <Autocomplete
   multiple
   options={options}
   value={selectedValues}
-  onChange={(vals) => setSelectedValues(vals)}
+  onChange={setSelectedValues}
   limitTags={3}
   creatable
-  onCreateOption={(input) => persistNewOption(input)}
-  label="Tags"
+  onCreateOption={(label) => saveToServer(label)}
+  maxCreateLength={50}
 />
 
 // Server-side filtering
 <Autocomplete
   options={serverOptions}
-  value={value}
-  onChange={setValue}
+  value={selected}
+  onChange={setSelected}
   disableClientFilter
-  onInputChange={(query, reason) => fetchOptions(query)}
+  onInputChange={(value) => fetchOptions(value)}
+  loading={isFetching}
 />
-```
+```
+
+## Source
+
+[`autocomplete.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/autocomplete.tsx)

package/src/components/ui/.badge.md

@@ -1,40 +1,43 @@
-<!-- source-hash: 88aa5dbba51bdd21ac31415ed974140c -->
-A reusable Badge component built with class-variance-authority that provides consistent styling for status indicators, labels, and categorization elements.
+<!-- source-hash: 4da43817dbb4ea0bdd621a35dd80c8f4 -->
+Renders a styled inline badge component using `cva` for variant-based class management, supporting five visual states tied to ODS design tokens.
 
 ## Key Components
 
-- **Badge**: Main component function that renders a styled div element
-- **BadgeProps**: TypeScript interface extending HTML div attributes with variant props
-- **badgeVariants**: CVA-powered style variants including default, secondary, destructive, outline, and success styles
+- **`badgeVariants`** — `cva` configuration defining base styles and five variants: `default`, `secondary`, `destructive`, `outline`, and `success`. Base styles lock badge text at `12px` (not the `text-h6` composite) per ODS token spec.
+- **`Badge`** — Functional component rendering a `<div>` with composed class names. Accepts all standard `HTMLDivElement` attributes plus a `variant` prop.
+- **`BadgeProps`** — Exported interface extending `React.HTMLAttributes<HTMLDivElement>` and `VariantProps<typeof badgeVariants>`.
+
+## Variants
+
+| Variant | Use Case |
+|---|---|
+| `default` | Primary brand color |
+| `secondary` | Muted/secondary emphasis |
+| `destructive` | Error or danger state |
+| `outline` | Bordered, no fill |
+| `success` | Positive/success state (ODS token) |
 
 ## Usage Example
 
 ```typescript
-import { Badge } from "./badge"
-
-function StatusIndicator() {
-  return (
-    <div className="flex gap-2">
-      <Badge variant="default">Default</Badge>
-      <Badge variant="success">Active</Badge>
-      <Badge variant="destructive">Error</Badge>
-      <Badge variant="outline">Draft</Badge>
-      <Badge className="bg-blue-500 text-white">Custom</Badge>
-    </div>
-  )
-}
-
-// Usage in lists or cards
-function UserCard({ status }: { status: string }) {
-  return (
-    <div className="p-4 border rounded">
-      <h3>User Profile</h3>
-      <Badge variant={status === "active" ? "success" : "secondary"}>
-        {status}
-      </Badge>
-    </div>
-  )
-}
+import { Badge } from "@/components/ui/badge"
+
+// Default
+<Badge>Active</Badge>
+
+// With variant
+<Badge variant="success">Resolved</Badge>
+<Badge variant="destructive">Failed</Badge>
+<Badge variant="outline">Pending</Badge>
+
+// With custom class
+<Badge variant="secondary" className="uppercase tracking-wide">
+  Beta
+</Badge>
 ```
 
-The component leverages Tailwind CSS classes and supports custom styling through the `className` prop while maintaining consistent design system patterns.
+## Notes
+
+- Requires the `cn` utility from [`../../utils/cn`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/utils/cn.ts).
+- The `"use client"` directive marks this as a React Client Component.
+- Font weight references the ODS semantic token `--font-weight-semibold` rather than a hardcoded Tailwind class.

package/src/components/ui/.brand-association-card.md

@@ -1,23 +1,19 @@
-<!-- source-hash: d0a2530b7492095645c20b724f126d0d -->
+<!-- source-hash: 585cbb6811e0a4bfee9cb696fd04216d -->
 A client-side React card component that displays a brand association item with an icon, title, description, and an external link button.
 
 ## Key Components
 
 ### Interfaces
 
-| Interface | Description |
-|-----------|-------------|
-| `BrandAssociationItem` | Data model for a single card — accepts a React component or element as icon, plus title, description, button text, and link URL |
-| `BrandAssociationCardProps` | Props for the card component; wraps `BrandAssociationItem` with an optional `className` |
+- **`BrandAssociationItem`** — Data shape for a card entry, containing:
+  - `icon` — Accepts either a React component type or a pre-rendered React element
+  - `title`, `description`, `buttonText`, `link` — Display content and navigation target
 
-### `BrandAssociationCard`
+- **`BrandAssociationCardProps`** — Props for the card component (`item` + optional `className`)
 
-The primary exported component. Renders a styled card with:
+### Exports
 
-- **Icon** — handles both raw `React.ReactElement` and `React.ComponentType` via an internal `renderIcon()` helper
-- **Title** — displayed as an `h3` with ODS primary text styling
-- **Description** — secondary text using DM Sans font
-- **CTA Button** — an outline `Button` with an `ExternalLink` icon that opens the provided `link` in a new tab
+- **`BrandAssociationCard`** — The primary card component. Internally uses a `renderIcon` helper that handles both raw React elements and component types (rendering the latter at `size={120}` with `w-20 h-20` classes).
 
 ## Usage Example
 
@@ -26,16 +22,24 @@ import { BrandAssociationCard } from './brand-association-card';
 import { ShieldCheck } from 'lucide-react';
 
 const item = {
-  icon: ShieldCheck,
+  icon: ShieldCheck,               // component type
   title: 'Security Tools',
-  description: 'Browse our curated list of security integrations.',
+  description: 'Browse our curated security integrations.',
   buttonText: 'Integrations',
-  link: 'https://flamingo.run/integrations',
+  link: 'https://openframe.ai/integrations',
 };
 
-export default function Page() {
-  return <BrandAssociationCard item={item} className="rounded-xl" />;
-}
+<BrandAssociationCard item={item} className="rounded-lg" />
+
+// Pre-rendered element also accepted:
+const item2 = {
+  icon: <ShieldCheck size={80} color="#FF5A1F" />,  // React element
+  // ...
+};
 ```
 
-> **Note:** The `icon` prop accepts either a component type (e.g., a Lucide icon) or a pre-rendered `React.ReactElement`. When passing a component, it is rendered at `120px` size with `w-20 h-20` Tailwind classes applied automatically.
+## Notes
+
+- Uses `'use client'` — intended for Next.js App Router client components.
+- The `Button` component's `openInNewTab` prop and `ExternalLink` icon are applied automatically.
+- Source: [`brand-association-card.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/brand-association-card.tsx)

package/src/components/ui/.breadcrumb.md

@@ -1,17 +1,17 @@
-<!-- source-hash: cb8e8ae598fa4e3046aa0545d0ea86b2 -->
-Accessible breadcrumb navigation component built on semantic HTML with full ARIA support, using Radix UI's `Slot` for flexible rendering.
+<!-- source-hash: e96bf18f995c9fd275aa6298571a6e80 -->
+Accessible breadcrumb navigation component built on native HTML elements with Radix UI's `Slot` primitive for flexible rendering.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `Breadcrumb` | `nav` wrapper | Root container with `aria-label="breadcrumb"` |
-| `BreadcrumbList` | `ol` element | Ordered list of breadcrumb items |
-| `BreadcrumbItem` | `li` element | Individual breadcrumb entry wrapper |
-| `BreadcrumbLink` | `a` element | Clickable navigation link; supports `asChild` for custom renderers |
-| `BreadcrumbPage` | `span` element | Current page indicator (`aria-current="page"`, non-interactive) |
-| `BreadcrumbSeparator` | `li` element | Visual divider, defaults to `ChevronRight`; accepts custom children |
-| `BreadcrumbEllipsis` | `span` element | Collapsed items indicator using `MoreHorizontal` icon |
+| Export | Element | Purpose |
+|---|---|---|
+| `Breadcrumb` | `<nav>` | Root wrapper with `aria-label="breadcrumb"` |
+| `BreadcrumbList` | `<ol>` | Ordered list of breadcrumb items |
+| `BreadcrumbItem` | `<li>` | Individual breadcrumb entry |
+| `BreadcrumbLink` | `<a>` / Slot | Clickable navigation link; supports `asChild` for custom renderers |
+| `BreadcrumbPage` | `<span>` | Current page indicator (`aria-current="page"`, non-interactive) |
+| `BreadcrumbSeparator` | `<li>` | Decorative divider; defaults to `ChevronRight`, accepts custom children |
+| `BreadcrumbEllipsis` | `<span>` | Collapsed items indicator using `MoreHorizontal` icon |
 
 ## Usage Example
 
@@ -24,9 +24,9 @@ import {
   BreadcrumbPage,
   BreadcrumbSeparator,
   BreadcrumbEllipsis,
-} from "@/components/ui/breadcrumb"
+} from "@openframe-oss-lib/ui"
 
-export function AppBreadcrumb() {
+export function Nav() {
   return (
     <Breadcrumb>
       <BreadcrumbList>
@@ -51,4 +51,8 @@ export function AppBreadcrumb() {
 }
 ```
 
-> **`asChild` pattern:** Pass `asChild` to `BreadcrumbLink` to delegate rendering to a child component (e.g., a router `Link`), inheriting all props via Radix UI `Slot`.
+**Notes:**
+- `BreadcrumbLink` accepts `asChild` to delegate rendering to a child component (e.g., Next.js `<Link>`).
+- `BreadcrumbSeparator` renders a custom separator when provided children.
+- All components forward refs and accept standard HTML element props.
+- Source: [`breadcrumb.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/breadcrumb.tsx)

package/src/components/ui/.bullet-list.md

@@ -1,38 +1,50 @@
-<!-- source-hash: 61e38ca748fb412e4ec00e0fad6f9d71 -->
-A React component for rendering customizable bulleted lists with flexible styling and icon options.
+<!-- source-hash: 0668ba93667ff20c23b93aa4bdbe8f38 -->
+A client-side React component that renders a styled bullet list with customizable icons, colors, spacing, and layout. Accepts both plain strings and structured `BulletListItem` objects.
 
 ## Key Components
 
-- **`BulletList`** - Main component that renders a list of items with customizable bullet icons
-- **`BulletListItem`** - Interface for individual list items with optional ID
-- **`BulletListProps`** - Configuration interface for bullet appearance, spacing, and styling
-- **`spacingMap`** - Predefined spacing options (sm/md/lg) using Tailwind classes
+### Interfaces
+
+- **`BulletListItem`** — Structured item shape with required `text` and optional `id` fields
+- **`BulletListProps`** — Full props interface for the `BulletList` component
+
+### Exports
+
+- **`BulletList`** — Main component that renders a vertically spaced list with icon bullets
+
+### Props
+
+| Prop | Type | Default |
+|---|---|---|
+| `items` | `string[] \| BulletListItem[]` | *(required)* |
+| `bulletColor` | `string` | `var(--color-text-primary)` |
+| `bulletIcon` | `React.ComponentType` | `ShapeCircleDashIcon` |
+| `bulletSize` | `number` | `16` |
+| `textClassName` | `string` | `text-h4 text-ods-text-primary` |
+| `itemClassName` | `string` | `flex items-start gap-3` |
+| `containerClassName` | `string` | `''` |
+| `spacing` | `'sm' \| 'md' \| 'lg'` | `'md'` |
 
 ## Usage Example
 
 ```typescript
 import { BulletList } from './bullet-list';
-import { CustomIcon } from './icons';
+import { CheckIcon } from '../icons';
 
-// Simple string array
-<BulletList 
-  items={["First item", "Second item", "Third item"]}
-  spacing="lg"
-/>
+// With plain strings
+<BulletList items={['Deploy in minutes', 'No vendor lock-in', 'AI-powered automation']} />
 
-// Advanced configuration with custom styling
-<BulletList 
+// With structured items and custom icon
+<BulletList
   items={[
-    { text: "Custom bullet color", id: "item-1" },
-    { text: "Different icon", id: "item-2" }
+    { id: 'feat-1', text: 'Automated ticketing' },
+    { id: 'feat-2', text: 'Real-time monitoring' },
   ]}
-  bulletColor="#ff6b6b"
-  bulletIcon={CustomIcon}
-  bulletSize={20}
-  spacing="sm"
-  textClassName="text-lg font-bold"
-  containerClassName="bg-gray-100 p-4 rounded-lg"
+  bulletIcon={CheckIcon}
+  bulletColor="var(--color-accent)"
+  spacing="lg"
+  textClassName="text-body text-ods-text-secondary"
 />
 ```
 
-The component automatically normalizes string arrays to `BulletListItem` objects and provides responsive typography with DM Sans font by default. Each item is rendered with a flex layout for proper bullet alignment.
+**Source:** [`bullet-list.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/bullet-list.tsx)