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

package/src/components/ui/.square-avatar.md

@@ -1,49 +1,52 @@
-<!-- source-hash: 5ede4b179e76c93d7dbba4fcff5327a9 -->
-A flexible avatar component that displays a user image or falls back to initials, supporting both square and round variants with multiple size options.
+<!-- source-hash: 697a56bf02c863691fb32cd7dc26e986 -->
+A React component that renders a square or round avatar with image support, authenticated image resolution, and an initials-based fallback when no image is available or fails to load.
 
 ## Key Components
 
 ### `SquareAvatarProps`
-Extends `React.HTMLAttributes<HTMLDivElement>` with:
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `src` | `string` | — | Image URL |
-| `alt` | `string` | — | Image alt text (also used for initials fallback) |
-| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Controls dimensions (32/40/48/64px) |
-| `fallback` | `string` | — | Preferred string for generating initials |
+|---|---|---|---|
+| `src` | `string` | — | Image URL (resolved through auth hook) |
+| `alt` | `string` | — | Alt text; also used to derive initials fallback |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Named size bucket |
+| `sizePx` | `number` | — | Exact pixel size; overrides `size` |
+| `fallback` | `string` | — | String used to derive initials (takes priority over `alt`) |
 | `variant` | `'square' \| 'round'` | `'square'` | Border radius style |
+| `initialsClassName` | `string` | — | Tailwind overrides for initials font/color |
 
-### `SquareAvatar`
-A memoized, forwarded-ref component that renders an image with automatic graceful degradation to initials on load error or missing `src`.
+### Exports
 
-**Fallback behavior:** Uses `getFirstLastInitials()` on `fallback ?? alt`, rendering `'?'` if neither yields initials. The initials layer uses `text-ods-text-primary` to maintain WCAG AA contrast across accent-fill backgrounds (e.g. Mingo cyan, current-user pink).
+- **`SquareAvatar`** — Memoized, forwarded-ref `div` wrapping an authed `Image` and an initials layer.
 
 ## Usage Example
 
 ```typescript
-// Image avatar
+import { SquareAvatar } from "@openframe/ui";
+
+// Basic image avatar
 <SquareAvatar
-  src="https://example.com/avatar.jpg"
+  src="https://cdn.example.com/user.jpg"
   alt="Jane Doe"
-  size="lg"
-  variant="round"
+  size="md"
 />
 
-// Initials-only avatar (no src)
+// Initials-only fallback
 <SquareAvatar
   fallback="Jane Doe"
-  size="md"
-  variant="square"
+  size="sm"
+  variant="round"
 />
 
-// With custom className and forwarded ref
-const ref = React.useRef<HTMLDivElement>(null);
+// Exact pixel size with custom initials styling
 <SquareAvatar
-  ref={ref}
-  src={userAvatarUrl}
-  alt={userName}
-  size="xl"
-  className="ring-2 ring-ods-flamingo-pink"
+  src={user.avatarUrl}
+  alt={user.name}
+  sizePx={28}
+  initialsClassName="text-[10px] text-white"
 />
-```
+```
+
+**Fallback behaviour:** if `src` is absent or the image fires an `onError` event, the initials layer (derived via `getFirstLastInitials`) becomes visible. The initials color resolves through the CSS variable `--ods-avatar-initials`, falling back to `--color-text-primary`, so host themes can supply a contrast-correct value without breaking unstyled avatars.
+
+**Source:** [`square-avatar.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/square-avatar.tsx)

package/src/components/ui/.stacked-rows-panel.md

@@ -0,0 +1,61 @@
+<!-- source-hash: 4d62db34d742074664628fd26198e37d -->
+A bordered card component that stacks rows vertically, supporting full-width title rows, multi-column data rows, and arbitrary content rows with ODS-compliant styling.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `StackedRowsPanel` | Component | Root container; renders an optional uppercase title above a bordered, rounded card |
+| `PanelColumn` | Interface | Defines a single column cell with `value`, `label`, `icon`, `leadingIcon`, `href`, `width`, `align`, and `hideAt` |
+| `PanelRow` | Interface | Defines a row with either `columns` (1 = full-width, N = multi-column) or arbitrary `content` |
+| `StackedRowsPanelProps` | Interface | Props for `StackedRowsPanel`: `rows`, optional `title`, optional `className` |
+| `PanelColumnAlign` | Type | `"left" \| "center" \| "right"` |
+| `PanelHideAt` | Type | `"md" \| "lg" \| "xl"` — responsive column visibility breakpoints |
+| `CellValue` | Internal | Renders the `value` (h4) + `label` (h6) pair with optional inline icon and link |
+| `PanelCell` | Internal | Resolves layout variant: custom `content`, `leadingIcon` banner, or standard value/label stack |
+| `PanelRowView` | Internal | Switches between full-width, multi-column, and arbitrary-content row layouts |
+
+## Usage Example
+
+```typescript
+import { StackedRowsPanel } from "@/components/stacked-rows-panel"
+import { Tag } from "@/components/tag"
+
+// Multi-column detail card with an optional title
+<StackedRowsPanel
+  title="Device Summary"
+  rows={[
+    {
+      id: "header",
+      columns: [
+        {
+          key: "device-name",
+          value: "MacBook Pro 16",
+          label: "Device Name",
+        },
+      ],
+    },
+    {
+      id: "details",
+      columns: [
+        { key: "os",     value: "macOS 14.4", label: "Operating System" },
+        { key: "status", value: <Tag variant="success">Online</Tag>, label: "Status" },
+        { key: "owner",  value: "Jane Smith",  label: "Assigned To", hideAt: "md" },
+      ],
+    },
+    {
+      id: "external",
+      columns: [
+        {
+          key: "docs",
+          value: "View Docs",
+          label: "External Link",
+          href: "https://flamingo.run/docs",
+        },
+      ],
+    },
+  ]}
+/>
+```
+
+**Source:** [`stacked-rows-panel.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/stacked-rows-panel.tsx)

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

@@ -1,37 +1,43 @@
-<!-- source-hash: 03e68088323281da2f3ddac5a1dabf62 -->
-A client-side React component that renders styled status/label badges with configurable size variants and color schemes using `class-variance-authority`.
+<!-- source-hash: 0935f3d6a806783b496a5b5cb096c40a -->
+Reusable status badge component implementing the OpenFrame Design System (ODS) badge specifications, with support for multiple color schemes, density variants, and a dedicated OpenFrame generation mode.
 
 ## Key Components
 
-- **`statusBadgeVariants`** — CVA variant config defining two axes:
-  - `variant`: `"card"` (default, larger) or `"button"` (compact, stamp-like)
-  - `colorScheme`: `cyan`, `pink`, `yellow`, `green`, `purple`, `success`, `error`, `warning`, `default`, `accentBorder`, `errorBorder`, `whiteBorder`
-- **`StatusBadge`** — Main exported `<span>`-based component
-- **`singleLine`** prop — Opt-out flag for the `button` variant's multi-word vertical stacking behavior
+### `StatusBadge` (default export)
+A polymorphic `<span>`-based badge component built with `class-variance-authority`. Supports two density variants and multiple semantic color schemes, including border-only styles for task-type badges.
+
+### `statusBadgeVariants`
+CVA variant configuration exposing two axes:
+- **`variant`**: `card` (standalone, full ODS caption composite) | `button` (dense inline stamp, 10px scale)
+- **`colorScheme`**: `cyan` | `pink` | `yellow` | `green` | `purple` | `success` | `error` | `warning` | `default` | `accentBorder` | `errorBorder` | `whiteBorder`
+
+### `genBadgeBgOpacity(gen: number): number`
+Returns the accent background opacity (%) for a given OpenFrame generation tier. Gen 1 is strongest (30%), fading progressively for later generations.
+
+### `generationTierFromLabel(label: string | null | undefined): number`
+Parses a whole-number generation tier from a ClickUp Target Version label (e.g. `"Gen1.5"` → `1`). Fractional gens share their tier's tint.
 
 ## Usage Example
 
 ```typescript
-import { StatusBadge } from './status-badge';
+import { StatusBadge, generationTierFromLabel } from './status-badge';
 
-// Default card badge
+// Semantic color scheme
 <StatusBadge text="Active" colorScheme="success" />
 
-// Compact button badge with stacked multi-word text
-<StatusBadge text="TO DO" variant="button" colorScheme="warning" />
-
-// Compact button badge, single line (inline chat context)
-<StatusBadge text="IN PROGRESS" variant="button" colorScheme="cyan" singleLine />
-
-// Border-only accent badge (task type)
-<StatusBadge text="BUG" colorScheme="errorBorder" />
+// Dense inline stamp with multi-word stacking
+<StatusBadge text="TO DO" variant="button" colorScheme="default" />
 
-// Custom class override
-<StatusBadge text="Custom" colorScheme="purple" className="rounded-full" />
-```
+// Inline stamp, single line (no vertical stacking)
+<StatusBadge text="TO DO" variant="button" singleLine />
 
-## Notes
+// Generation chip (overrides colorScheme)
+<StatusBadge
+  text="Gen2"
+  variant="button"
+  gen={generationTierFromLabel("Gen2")}
+/>
 
-- Renders as `<span>` (not `<div>`) to remain HTML-valid inside inline contexts such as `<p>`, `<a>`, or markdown-rendered content
-- `variant="button"` with multi-word text auto-stacks each word vertically (stamp effect); pass `singleLine` to disable
-- Extends `React.HTMLAttributes<HTMLSpanElement>`, so all standard span props (`id`, `onClick`, `aria-*`, etc.) are forwarded
+// Border-only task type badge
+<StatusBadge text="Bug" colorScheme="errorBorder" />
+```

package/src/components/ui/.status-indicator.md

@@ -1,35 +1,49 @@
-<!-- source-hash: 4f6de0d7bd5f42eb6b6564ff3beaa57b -->
-A reusable React component that displays color-coded status indicators with optional links, supporting success, pending, error, and missing states.
+<!-- source-hash: f8c79cfcf658780fb28170a6d9b4181f -->
+A client-side React component that renders a colored status dot paired with a label, optionally wrapped in an external link.
 
 ## Key Components
 
-- **StatusIndicator**: Main functional component that renders a colored dot with status text
-- **StatusIndicatorProps**: TypeScript interface defining component props
-- **getStatusColor**: Internal utility function that maps status types to corresponding Tailwind CSS classes
+### `StatusIndicatorProps`
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `status` | `'success' \| 'pending' \| 'error' \| 'missing'` | ✅ | Determines dot and text color |
+| `label` | `string` | ✅ | Display text next to the dot |
+| `href` | `string` | ❌ | If provided, wraps the indicator in an external `<a>` tag |
+
+### `StatusIndicator`
+
+Maps each status to ODS design token classes:
+
+| Status | Color Token |
+|--------|-------------|
+| `success` | `ods-success` (green) |
+| `pending` | `ods-warning` (yellow) |
+| `error` | `ods-error` (red) |
+| `missing` | `ods-warning` (yellow) |
 
 ## Usage Example
 
 ```typescript
-import { StatusIndicator } from './status-indicator';
+// Static status display
+<StatusIndicator status="success" label="Connected" />
 
-// Basic status display
-<StatusIndicator status="success" label="Database Connected" />
+// Error state
+<StatusIndicator status="error" label="Service Unavailable" />
 
-// Status with clickable link
-<StatusIndicator 
-  status="error" 
-  label="API Unreachable" 
-  href="https://status.api.example.com" 
+// Clickable indicator linking to an external resource
+<StatusIndicator
+  status="pending"
+  label="Awaiting Approval"
+  href="https://dashboard.example.com/approvals/123"
 />
 
-// Different status states
-<StatusIndicator status="pending" label="Deployment in Progress" />
-<StatusIndicator status="missing" label="Configuration Required" />
+// Missing configuration
+<StatusIndicator status="missing" label="API Key Not Set" />
 ```
 
-The component automatically applies appropriate colors:
-- **Success**: Green dot and text
-- **Pending/Missing**: Orange dot and text  
-- **Error**: Red dot and text
+## Notes
 
-When an `href` prop is provided, the entire indicator becomes a clickable link that opens in a new tab. The component uses DM Sans font and includes hover effects for linked indicators.
+- Uses `"use client"` — must run in a browser context (Next.js App Router).
+- The `href` variant opens in a new tab with `rel="noopener noreferrer"` for security.
+- Color tokens (`ods-success`, `ods-warning`, `ods-error`) are defined in the ODS (OpenFrame Design System) Tailwind config. Ensure the theme is loaded in your Tailwind setup.

package/src/components/ui/.tab-content.md

@@ -1,39 +1,51 @@
-<!-- source-hash: 708030f1b7cd1bda4a84ea3e23f38945 -->
-A React component that renders dynamic tab content with automatic fallback to an empty state when no component is provided.
+<!-- source-hash: 7db2c87fb86524e2e57b6d346f5a61f2 -->
+Renders a dynamic tab panel by mounting a given React component or displaying a configurable empty state when no matching tab component is found.
 
 ## Key Components
 
-- **TabContent**: Main component that conditionally renders either a dynamic tab component or an empty state
-- **TabContentProps**: TypeScript interface defining component props including active tab name, component to render, and customization options
-- **Empty State**: Built-in fallback UI with customizable title and description for missing or invalid tabs
+### `TabContent`
+A client-side React component that conditionally renders a tab's content component or a fallback empty state UI.
+
+**Props (`TabContentProps`):**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `activeTab` | `string` | — | Name of the currently active tab (used in fallback message) |
+| `TabComponent` | `React.ComponentType<any> \| null` | — | Component to render; `null` triggers the empty state |
+| `componentProps` | `any` | — | Props spread into `TabComponent` when rendered |
+| `className` | `string` | — | Additional CSS classes for the wrapper |
+| `emptyStateTitle` | `string` | `"Tab Not Found"` | Heading shown in the empty state |
+| `emptyStateDescription` | `string` | — | Custom message; defaults to `"The selected tab '...' could not be found."` |
+| `minHeight` | `string` | `"min-h-[400px]"` | Tailwind min-height applied to the wrapper and empty state container |
 
 ## Usage Example
 
 ```typescript
 import { TabContent } from './tab-content'
-import { UserProfile } from './user-profile'
-
-function MyTabs() {
-  const [activeTab, setActiveTab] = useState('profile')
-  
-  // Component mapping
-  const tabComponents = {
-    profile: UserProfile,
-    settings: null // Will show empty state
-  }
-  
+import { OverviewPanel } from './panels/OverviewPanel'
+
+const TAB_MAP: Record<string, React.ComponentType<any>> = {
+  overview: OverviewPanel,
+}
+
+function MyTabs({ activeTab }: { activeTab: string }) {
+  const TabComponent = TAB_MAP[activeTab] ?? null
+
   return (
     <TabContent
       activeTab={activeTab}
-      TabComponent={tabComponents[activeTab]}
+      TabComponent={TabComponent}
       componentProps={{ userId: '123' }}
-      className="bg-white rounded-lg"
-      emptyStateTitle="Coming Soon"
-      emptyStateDescription="This feature is under development"
-      minHeight="min-h-[500px]"
+      emptyStateTitle="Panel Unavailable"
+      emptyStateDescription="Please select a valid tab from the navigation."
+      minHeight="min-h-[600px]"
     />
   )
 }
 ```
 
-The component automatically handles missing components by displaying a centered empty state with customizable messaging, making it ideal for tab interfaces where some tabs may not be implemented yet.
+## Notes
+
+- Marked `'use client'` — requires a Next.js App Router client boundary.
+- Uses [`cn`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/utils/cn.ts) for conditional Tailwind class merging.
+- The empty state is centered both vertically and horizontally within the min-height container.

package/src/components/ui/.tab-navigation.md

@@ -1,73 +1,63 @@
-<!-- source-hash: 98a7f0660803887b4fe8c81807718051 -->
-Accessible, scrollable tab navigation component with optional URL synchronization and render prop support for content rendering.
+<!-- source-hash: 4f81360202d7fa9875b28cdae48c29a5 -->
+Accessible, scrollable tab navigation bar component with optional URL synchronization, overflow scroll shadows, and support for both controlled and URL-driven active tab state.
 
 ## Key Components
 
 ### `TabNavigation`
-Main component that renders a horizontal tab bar with scroll overflow handling, fade gradients, and flexible state management modes.
-
-### Interfaces
-
-| Export | Description |
-|--------|-------------|
-| `TabItem` | Tab definition — `id`, `label`, `icon`, optional `component` and status `indicator` |
-| `TabNavigationUrlSyncOptions` | URL sync config — `paramName` (default: `'tab'`) and `replaceState` (default: `true`) |
-
-### Utility Functions
-
-| Function | Description |
-|----------|-------------|
-| `getTabById` | Finds a `TabItem` by `id` from a tabs array |
-| `getTabComponent` | Returns the `component` for a given tab id, or `null` |
+The primary exported component that renders a horizontal scrollable tab strip. Supports two operating modes:
+- **Controlled mode** — driven by `activeTab` / `onTabChange` props
+- **URL sync mode** — reads/writes the active tab from search params (e.g. `?tab=overview`), enabling deep linking and browser back/forward navigation
+
+### `TabItem`
+Interface describing each tab entry:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | ✅ | Unique identifier used in state and URL |
+| `label` | `string` | ✅ | Visible tab text |
+| `icon` | `SVGComponent` | ❌ | Icon rendered beside the label |
+| `indicator` | `'success' \| 'warning' \| 'error'` | ❌ | Status badge dot |
+| `component` | `ComponentType` | ❌ | Optional content component reference |
+
+### `TabNavigationUrlSyncOptions`
+Configuration object for URL synchronization:
+- `paramName` — query param name (default: `'tab'`)
+- `replaceState` — use `history.replace` instead of `push` (default: `true`)
 
 ## Usage Example
 
-**Controlled mode (no URL sync):**
-
 ```typescript
-import { TabNavigation, TabItem } from './tab-navigation'
-import { HomeIcon, SettingsIcon } from 'lucide-react'
-
-const tabs: TabItem[] = [
-  { id: 'home', label: 'Home', icon: HomeIcon },
-  { id: 'settings', label: 'Settings', icon: SettingsIcon, indicator: 'warning' },
-]
-
+// Controlled mode
 <TabNavigation
-  tabs={tabs}
-  activeTab={activeTab}
-  onTabChange={setActiveTab}
->
-  {(tab) => <div>Content for: {tab}</div>}
-</TabNavigation>
-```
-
-**URL sync mode (persists active tab in query string):**
+  tabs={[
+    { id: 'overview', label: 'Overview' },
+    { id: 'settings', label: 'Settings', indicator: 'warning' },
+  ]}
+  activeTab={currentTab}
+  onTabChange={setCurrentTab}
+/>
 
-```typescript
+// URL sync mode with render prop
 <TabNavigation
   tabs={tabs}
-  urlSync={{ paramName: 'section', replaceState: true }}
-  defaultTab="home"
+  urlSync={{ paramName: 'tab', replaceState: true }}
+  defaultTab="overview"
 >
-  {(activeTab) => <ActiveTabContent tabId={activeTab} />}
+  {(activeTab) => <ContentPanel tab={activeTab} />}
 </TabNavigation>
-```
 
-**Forced scroll gradients with custom shadow color:**
-
-```typescript
+// Stretched tabs with forced gradients
 <TabNavigation
   tabs={tabs}
+  stretchTabs
   showRightGradient
   shadowClassName="from-black"
-  urlSync
 />
 ```
 
-## Behavior Notes
+## Notes
 
-- Scroll overflow is detected via `ResizeObserver` and `scroll` events — fade gradients appear automatically on overflowing edges
-- The bottom border line fades to transparent on edges with active scroll shadows
-- URL sync mode reacts to browser back/forward navigation via `searchParams` changes
-- `indicator` dots render as color-coded badges (`error` → red, `warning` → accent yellow, `success` → green) over the tab icon
+- Horizontal mouse wheel scrolling is intercepted and normalized across deltaMode variants (pixel, line, page)
+- On mount, the active tab snaps instantly into view (`auto`); subsequent changes scroll smoothly
+- Left/right fade gradients appear automatically on overflow, or can be forced via `showLeftGradient` / `showRightGradient`
+- Source: [`tab-navigation.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/tab-navigation.tsx)

package/src/components/ui/.tab-selector.md

@@ -1,40 +1,57 @@
-<!-- source-hash: 0e28e1e106dbf76027ae86587226825d -->
-A accessible, styled tab selector component that renders a group of toggle buttons for switching between views or options, supporting icons, badges, disabled states, and two visual variants.
+<!-- source-hash: 3ee9242b5f7936c8afca1ad57b705677 -->
+A styled tab selector component that renders a group of toggle buttons for switching between named views or modes, supporting icons, badges, two visual variants, and disabled states.
 
 ## Key Components
 
-### Interfaces
-- **`TabSelectorItem`** — Defines individual tab configuration: `id`, optional `label`, `ariaLabel` (required for icon-only tabs), `icon`, `disabled`, and `badge`
-- **`TabSelectorProps`** — Component props including `value`, `onValueChange`, `items`, `variant`, `label`, `disabled`, and `className`
-
-### Component
-- **`TabSelector`** — Controlled tab button group that maps `items` to styled `<button>` elements, applying active/disabled/hover styles based on state and variant
+### `TabSelectorItem`
+Configuration object for each tab button:
+
+| Property | Type | Description |
+|---|---|---|
+| `id` | `string` | Unique identifier |
+| `label` | `string?` | Display text (omit for icon-only tabs) |
+| `ariaLabel` | `string?` | Required when `label` is omitted |
+| `icon` | `ReactNode?` | Leading icon |
+| `disabled` | `boolean?` | Disables this specific tab |
+| `badge` | `ReactNode?` | Trailing badge element |
+
+### `TabSelectorProps`
+| Property | Type | Description |
+|---|---|---|
+| `value` | `string` | Currently selected tab id |
+| `onValueChange` | `(value: string) => void` | Selection change handler |
+| `items` | `TabSelectorItem[]` | Tabs to render |
+| `variant` | `'primary' \| 'secondary'` | Active tab highlight style (default: `'primary'`) |
+| `label` | `string?` | Optional heading above the selector |
+| `disabled` | `boolean?` | Disables the entire selector |
+| `className` | `string?` | Additional root container classes |
+
+### `TabSelector`
+The exported component. Renders a pill-style container with flex buttons — active tab receives accent background (`primary`) or surface background (`secondary`); inactive tabs are transparent with hover state.
 
 ## Usage Example
 
 ```typescript
-import { TabSelector } from './tab-selector'
+import { TabSelector, TabSelectorItem } from './tab-selector'
 import { LayoutGrid, List } from 'lucide-react'
 
-const [view, setView] = React.useState('grid')
-
-<TabSelector
-  value={view}
-  onValueChange={setView}
-  label="View Mode"
-  variant="primary"
-  items={[
-    { id: 'grid', label: 'Grid', icon: <LayoutGrid /> },
-    { id: 'list', label: 'List', icon: <List /> },
-    { id: 'map',  label: 'Map',  disabled: true },
-  ]}
-/>
-```
-
-## Notes
-
-| Prop | Default | Description |
-|------|---------|-------------|
-| `variant` | `primary` | `primary` uses accent background; `secondary` uses surface grey |
-| `disabled` | `undefined` | Disables all tabs when set; overrides per-item `disabled` |
-| `ariaLabel` | — | Required on items where `label` is omitted (icon-only) |
+const tabs: TabSelectorItem[] = [
+  { id: 'grid', label: 'Grid', icon: <LayoutGrid /> },
+  { id: 'list', label: 'List', icon: <List /> },
+  { id: 'archive', label: 'Archive', disabled: true },
+]
+
+function ViewToggle() {
+  const [view, setView] = React.useState('grid')
+
+  return (
+    <TabSelector
+      value={view}
+      onValueChange={setView}
+      items={tabs}
+      variant="secondary"
+      label="View"
+    />
+  )
+}
+```

package/src/components/ui/.tabs.md

@@ -1,41 +1,54 @@
-<!-- source-hash: d5dd75145a233121b84df9bbdd129b81 -->
-A React tabs component built on Radix UI primitives that provides accessible, styled tab navigation with customizable appearance and keyboard support.
+<!-- source-hash: 41600349bb11b006dae1275c44f0e683 -->
+A **deprecated** Radix UI-based tabs component set that wraps `@radix-ui/react-tabs` with legacy shadcn/ui styling tokens. All exports are marked for migration to `TabNavigation` from `components/ui/tab-navigation`.
+
+> ⚠️ **Deprecated:** Do not use in new code. Migrate to [`TabNavigation`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/components/ui/tab-navigation.tsx) which provides ODS tokens, URL-sync, and overflow scroll shadows.
 
 ## Key Components
 
-- **`Tabs`** - Root container component (alias for `TabsPrimitive.Root`)
-- **`TabsList`** - Container for tab triggers with muted background styling
-- **`TabsTrigger`** - Individual tab button with active/inactive states and focus management
-- **`TabsContent`** - Content panel that displays when corresponding tab is active
+| Export | Type | Description |
+|---|---|---|
+| `Tabs` | Component | Root wrapper — alias for `TabsPrimitive.Root` |
+| `TabsList` | Component | Container for tab trigger buttons; styled with `bg-muted` and `rounded-md` |
+| `TabsTrigger` | Component | Individual tab button; applies active-state background and shadow via `data-[state=active]` |
+| `TabsContent` | Component | Panel rendered when its associated trigger is active |
+
+All components forward refs and accept the full props of their underlying Radix primitive.
 
 ## Usage Example
 
 ```typescript
-import { Tabs, TabsList, TabsTrigger, TabsContent } from "./components/ui/tabs"
+import { Tabs, TabsList, TabsTrigger, TabsContent } from "./tabs"
 
-function MyTabs() {
+// ⚠️ Deprecated — use TabNavigation for new code
+export function LegacyTabExample() {
   return (
-    <Tabs defaultValue="overview" className="w-full">
+    <Tabs defaultValue="overview">
       <TabsList>
         <TabsTrigger value="overview">Overview</TabsTrigger>
-        <TabsTrigger value="analytics">Analytics</TabsTrigger>
-        <TabsTrigger value="settings">Settings</TabsTrigger>
+        <TabsTrigger value="details">Details</TabsTrigger>
       </TabsList>
-      
+
       <TabsContent value="overview">
-        <div>Overview content here</div>
+        <p>Overview content</p>
       </TabsContent>
-      
-      <TabsContent value="analytics">
-        <div>Analytics dashboard</div>
-      </TabsContent>
-      
-      <TabsContent value="settings">
-        <div>Settings panel</div>
+      <TabsContent value="details">
+        <p>Details content</p>
       </TabsContent>
     </Tabs>
   )
 }
 ```
 
-All components use `forwardRef` for proper ref forwarding and include comprehensive accessibility features like keyboard navigation, focus management, and ARIA attributes through Radix UI primitives.
+## Migration
+
+Replace with `TabNavigation` from `components/ui/tab-navigation`:
+
+```typescript
+// Before (deprecated)
+import { Tabs, TabsList, TabsTrigger, TabsContent } from "./tabs"
+
+// After
+import { TabNavigation } from "components/ui/tab-navigation"
+```
+
+**Source:** [`tabs.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/components/ui/tabs.tsx)