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

package/src/components/icons-v2-generated/logos/.flamingo-logo-icon.md

@@ -0,0 +1,41 @@
+<!-- source-hash: 94e0936a6cceaca9424e86e63a789870 -->
+Renders the Flamingo brand logo as a scalable SVG icon React component, supporting customizable size, color, and standard SVG props.
+
+## Key Components
+
+### `FlamingoLogoIconProps`
+Extends `SVGProps<SVGSVGElement>` (excluding `width` and `height`) with:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | `""` | CSS class for the SVG element |
+| `size` | `number` | `24` | Width and height in pixels |
+| `color` | `string` | `"currentColor"` | Fill color for all SVG paths |
+
+### `FlamingoLogoIcon`
+Functional React component rendering the full Flamingo wordmark (flamingo bird + "flamingo" logotype) in a `416×120` viewBox, scaled uniformly via the `size` prop.
+
+## Usage Example
+
+```typescript
+import { FlamingoLogoIcon } from "./flamingo-logo-icon";
+
+// Default usage (24px, inherits text color)
+<FlamingoLogoIcon />
+
+// Custom size and color
+<FlamingoLogoIcon size={48} color="#FF6B6B" />
+
+// With Tailwind CSS class
+<FlamingoLogoIcon size={32} className="text-pink-500" />
+
+// Pass-through SVG props
+<FlamingoLogoIcon
+  size={40}
+  color="white"
+  aria-label="Flamingo"
+  role="img"
+/>
+```
+
+> **Note:** The `viewBox` is fixed at `0 0 416 120` (a wide, horizontal lockup). The `size` prop controls the rendered pixel dimensions uniformly, so the output will appear letterboxed. For layout-filling use cases, omit `size` and control dimensions via `className` with explicit `w-` / `h-` utilities.

package/src/components/layout/.article-detail-layout.md

@@ -1,43 +1,54 @@
-<!-- source-hash: f1c1fbdd04d056b4c98f44f6bacd4fb8 -->
-Unified page layout components providing two layout variants for consistent page structure across the application.
+<!-- source-hash: d821433e4362b660ede768aab0cf80db -->
+Provides two composable page layout wrappers — `PageShell` for wide layouts and `ArticleDetailLayout` for readable article-width pages — both rendering a centered `<main>` with configurable content boxes.
 
 ## Key Components
 
-| Export | Max Width | Purpose |
-|--------|-----------|---------|
-| `PageShell` | 1920px | List pages, dashboards, wide layouts |
-| `ArticleDetailLayout` | 1280px | Articles, blog posts, release notes, case studies |
+| Export | Max Width | Padding Strategy |
+|---|---|---|
+| `PageShell` | `1920px` | CSS custom properties (`--page-shell-*` vars via `ods-page-shell.css`) |
+| `ArticleDetailLayout` | `1280px` | Fixed: `px-6 md:px-20 py-6 md:py-10` |
 
-**`LayoutProps` interface:**
-- `children` — page content (no additional layout wrappers needed)
-- `schemas?` — optional JSON-LD `<script>` elements (breadcrumbs, article schema, etc.)
+### `LayoutProps`
 
-Both components render a `<main>` element with `bg-ods-bg`, responsive horizontal padding (`px-6` / `md:px-20`), and vertical padding (`py-6` / `md:py-10`). Neither forces `min-h-screen` — the root layout's `flex min-h-screen flex-col` → `flex-1` chain already anchors the footer to the bottom of the viewport on short pages.
+| Prop | Type | Description |
+|---|---|---|
+| `children` | `React.ReactNode` | Page content |
+| `schemas` | `React.ReactNode` | Optional JSON-LD `<script>` elements (breadcrumbs, article schema) |
+| `contentClassName` | `string` | Per-instance Tailwind override on the inner content box |
 
 ## Usage Example
 
 ```typescript
-// Wide layout for a list/dashboard page
-import { PageShell } from '@/components/article-detail-layout';
+// Wide dashboard / list page
+import { PageShell } from './article-detail-layout';
 
-export default function DevicesPage() {
+export default function DashboardPage() {
   return (
-    <PageShell>
-      <DeviceTable />
+    <PageShell schemas={<script type="application/ld+json">{...}</script>}>
+      <MyDashboardContent />
     </PageShell>
   );
 }
 
-// Constrained layout for a readable article/detail page
-import { ArticleDetailLayout } from '@/components/article-detail-layout';
+// Blog post / release note / case study
+import { ArticleDetailLayout } from './article-detail-layout';
 
-export default function BlogPost({ schema }: { schema: React.ReactNode }) {
+export default function BlogPostPage() {
   return (
-    <ArticleDetailLayout schemas={schema}>
-      <ArticleContent />
+    <ArticleDetailLayout
+      contentClassName="py-16"  // overrides default vertical padding
+      schemas={<ArticleSchema />}
+    >
+      <BlogPostContent />
     </ArticleDetailLayout>
   );
 }
 ```
 
-> Child components should render content only — no additional `<main>`, max-width, or padding wrappers required.
+## Notes
+
+- `PageShell` intentionally omits `min-h-screen` — the root `app/layout.tsx` already manages viewport height via a `flex min-h-screen flex-col` / `flex-1` chain; adding it here would create dead space in sibling-content layouts.
+- `PageShell` padding is controlled by CSS custom properties set on any ancestor element — no prop threading or context required.
+- `ArticleDetailLayout` does **not** participate in the `--page-shell-*` var system; its spacing is self-contained and fixed by default.
+
+**Source:** [`article-detail-layout.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/article-detail-layout.tsx)

package/src/components/layout/.page-container.md

@@ -1,17 +1,15 @@
-<!-- source-hash: 601f78e11aff8ba0205359b5d858638e -->
-Unified page container component that supports both legacy layout patterns and a new advanced UI pattern with variants, titles, actions, and responsive headers.
+<!-- source-hash: 81afde4015f7335e53f265e0e5802d4d -->
+A unified page container component that supports both a legacy layout pattern and an advanced UI pattern with variant-based layouts, headers, back buttons, and configurable actions.
 
 ## Key Components
 
-### Exported Types
-- **`PageContainerProps`** — Union type supporting `LegacyPageContainerProps` and `AdvancedPageContainerProps`
+- **`PageContainer`** – Main exported component. Detects which interface is in use via `isAdvancedProps()` and delegates to the appropriate renderer.
+- **`LegacyPageContainerProps`** – Backward-compatible interface for full-width background sections with configurable max-width and padding.
+- **`AdvancedPageContainerProps`** – Modern interface supporting `variant`, `title`, `subtitle`, `backButton`, `headerActions`, `actions`, and `menuActions`.
+- **`renderLegacyPageContainer`** – Preserves original layout behavior with configurable `as` element, background, and padding.
+- **`renderAdvancedPageContainer`** – Renders variant-aware layouts (`list`, `detail`, `form`, `content`) with responsive headers and mobile-fixed action bars.
 
-### Main Export
-- **`PageContainer`** — Auto-detects prop interface via `isAdvancedProps()` type guard and delegates to the appropriate renderer
-
-### Internal Renderers
-- **`renderLegacyPageContainer`** — Wraps content in a configurable semantic element (`section`, `div`, `main`, `article`) with optional full-width background
-- **`renderAdvancedPageContainer`** — Renders variant-aware layout (`list` | `detail` | `form` | `content`) with header, back button, title, subtitle, and `PageActions`
+> **Deprecated:** Use `PageLayout` from `'../layout/page-layout'` instead.
 
 ## Usage Example
 
@@ -21,25 +19,29 @@ Unified page container component that supports both legacy layout patterns and a
   <h1>Content</h1>
 </PageContainer>
 
-// Advanced - list page
+// Advanced — detail page with back button and actions
 <PageContainer
-  variant="list"
-  title="Devices"
-  subtitle="All managed devices"
-  actions={[{ label: 'Add Device', onClick: handleAdd }]}
+  variant="detail"
+  title="Ticket #1234"
+  subtitle="Open · High Priority"
+  backButton={{ label: 'Back to Tickets', onClick: () => router.back() }}
+  actions={[
+    { label: 'Save', onClick: handleSave, variant: 'primary' },
+    { label: 'Cancel', onClick: handleCancel },
+  ]}
 >
-  <DeviceTable />
+  <TicketDetail />
 </PageContainer>
 
-// Advanced - detail page with back button
+// Advanced — list page with header actions
 <PageContainer
-  variant="detail"
-  title="Device Details"
-  backButton={{ label: 'Back', onClick: () => router.back() }}
-  headerActions={<StatusBadge status="online" />}
+  variant="list"
+  title="Devices"
+  headerActions={<SearchBar />}
+  actions={[{ label: 'Add Device', onClick: handleAdd, icon: PlusIcon }]}
 >
-  <DeviceDetail />
+  <DeviceTable />
 </PageContainer>
 ```
 
-> **Deprecated:** Prefer `PageLayout` from `'../layout/page-layout'` for new implementations.
+**Source:** [`page-container.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/page-container.tsx)

package/src/components/layout/.page-heading.md

@@ -0,0 +1,48 @@
+<!-- source-hash: ec06a9a2f14fb05a94b7ed963648a5fb -->
+Renders a canonical page-level heading (`<h1>` or `<h2>`) with an optional description paragraph, serving as the single source of truth for the ODS `text-h1`/`text-h2` typography tokens across the library.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `PAGE_HEADING_CLASS` | `string` | Tailwind class string for the ODS `text-h1` token (40/48/56px, Azeret Mono semibold) |
+| `SECTION_HEADING_CLASS` | `string` | Tailwind class string for the ODS `text-h2` sub-title token (24/32/32px) |
+| `PageHeadingProps` | `interface` | Props for the `PageHeading` component |
+| `PageHeading` | `function` | Unified heading component rendering the heading element + optional description |
+
+### `PageHeadingProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — | Heading content; plain text or nodes |
+| `as` | `'h1' \| 'h2'` | `'h1'` | Semantic heading level |
+| `description` | `ReactNode` | — | Supporting copy rendered as a `<p>` |
+| `className` | `string` | — | Extra classes merged onto the heading |
+| `descriptionClassName` | `string` | — | Extra classes merged onto the description `<p>` |
+
+## Usage Example
+
+```typescript
+import { PageHeading, PAGE_HEADING_CLASS, SECTION_HEADING_CLASS } from './page-heading'
+
+// Standard page title with description
+<PageHeading description="Manage your connected devices and configurations.">
+  Devices
+</PageHeading>
+
+// Section heading when an h1 already exists above (e.g. hero)
+<PageHeading as="h2" description="Filter by status or region.">
+  Active Endpoints
+</PageHeading>
+
+// With an accent span and extra margin class
+<PageHeading className="mt-8">
+  Welcome to <span className="text-accent">OpenFrame</span>
+</PageHeading>
+
+// Apply the token class directly without the component (rare cases)
+<h2 className={PAGE_HEADING_CLASS}>Custom Heading</h2>
+<h3 className={SECTION_HEADING_CLASS}>Custom Section</h3>
+```
+
+> **Never hardcode pixel sizes or re-assert letter-spacing** for page or section headings — use `<PageHeading>` or the exported class constants. See the [source](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/page-heading.tsx) for full implementation details.

package/src/components/layout/.page-layout.md

@@ -1,50 +1,55 @@
-<!-- source-hash: 8a798bc4d9131ab38604adc9a1b7d675 -->
-Reusable page layout wrapper that provides consistent structure with an optional header (`TitleBlock`), configurable actions, and standardized spacing for full-page views.
+<!-- source-hash: 44f28568881e9535e5366a847627bff9 -->
+Canonical page chrome component for OpenFrame surfaces, providing a consistent layout container with an optional header (`TitleBlock`), spacing, and action slots.
 
 ## Key Components
 
 ### `PageLayout` (default export)
-Main layout component accepting the following props:
+Main layout wrapper that composes a `TitleBlock` header and a flex content area. The header renders conditionally when any of `title`, `subtitle`, `image`, `backButton`, `actions`, `selector`, or `loading` are provided (and `showHeader` is not `false`).
+
+### `PageLayoutProps`
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `children` | `ReactNode` | — | Page content |
-| `title` | `string` | — | Page heading |
-| `subtitle` | `string` | — | Secondary heading |
+|---|---|---|---|
+| `title` | `string` | — | Page title text |
+| `subtitle` | `string` | — | Subtitle text below title |
 | `image` | `{ src, alt? }` | — | Header image |
 | `backButton` | `{ label?, onClick }` | — | Back navigation button |
 | `actions` | `PageActionButton[]` | — | Action buttons rendered in the header |
-| `actionsVariant` | `'icon-buttons' \| 'primary-buttons' \| 'menu-primary'` | `'icon-buttons'` | Controls button style/layout |
-| `menuActions` | `ActionsMenuGroup[]` | — | Grouped dropdown menu actions |
+| `actionsVariant` | `'icon-buttons' \| 'primary-buttons' \| 'menu-primary'` | `'icon-buttons'` | Action button display style |
+| `menuActions` | `ActionsMenuGroup[]` | — | Grouped menu actions |
 | `selector` | `ReactNode` | — | Desktop-only slot (e.g. `TabSelector`) |
-| `headerVariant` | `'plain' \| 'card'` | — | `card` adds background, border, and mobile padding |
-| `showHeader` | `boolean` | `true` | Conditionally renders the header block |
-| `className` | `string` | — | Outer wrapper class override |
-| `contentClassName` | `string` | — | Content area class override |
-
-### Re-exports
-- `TitleBlock` + `TitleBlockProps` — header sub-component
-- `PageActionButton` — action button type
+| `headerVariant` | `'plain' \| 'card'` | — | Adds card chrome on mobile when `'card'` |
+| `titleSize` | `'h1' \| 'h2'` | `'h2'` | Title typography size |
+| `titleAdornment` | `ReactNode` | — | Inline node next to the title (e.g. a status tag) |
+| `loading` | `boolean` | — | Renders skeleton bars at stable header height |
+| `titleWrap` | `boolean` | `false` | Allows long titles to wrap instead of truncating |
+| `showHeader` | `boolean` | `true` | Suppresses the entire header block |
+| `className` | `string` | — | Applied to the outer wrapper |
+| `contentClassName` | `string` | — | Applied to the content area |
 
 ## Usage Example
 
 ```typescript
 import { PageLayout } from './page-layout'
 
-export default function SettingsPage() {
+export function MyPage() {
   return (
     <PageLayout
-      title="Settings"
-      subtitle="Manage your preferences"
-      backButton={{ label: 'Back', onClick: () => router.back() }}
-      actions={[{ label: 'Save', onClick: handleSave }]}
+      title="Devices"
+      subtitle="Manage your connected devices"
+      actions={[{ label: 'Add Device', onClick: handleAdd }]}
       actionsVariant="primary-buttons"
-      headerVariant="card"
+      headerVariant="plain"
     >
-      <SettingsForm />
+      <DeviceList />
     </PageLayout>
   )
 }
 ```
 
-> When `actionsVariant="primary-buttons"`, the content area automatically gains `pb-28` on mobile to prevent overlap with sticky action buttons.
+> ⛔️ **Frozen component** — this file is locked by design. Do not modify markup, CSS, or props without explicit human sign-off. See the file header for the full freeze rationale and sanctioned exceptions.
+
+## Re-exports
+
+- `TitleBlock`, `TITLE_BLOCK_MIN_HEIGHT`, `TitleBlockProps` — from `./title-block`
+- `PageActionButton` — from `../ui/page-actions`

package/src/components/layout/.title-block.md

@@ -1,42 +1,61 @@
-<!-- source-hash: ff0ecf9e6a81a5b5db96e020586aff9d -->
-A client-side page header component that renders a title, optional subtitle, entity image, back button, and action controls in a responsive layout.
+<!-- source-hash: 35e8c14f44c16d1c08ed20917e13456c -->
+Renders the title/subtitle/back-button/actions chrome block used by `PageLayout`. This component is **frozen** — it defines the canonical page header baseline across all OpenFrame pages and must not be structurally modified without explicit human sign-off.
 
 ## Key Components
 
-- **`TitleBlockProps`** — Interface defining all configurable props including title, subtitle, image, navigation, actions, and visual variant
-- **`TitleBlock`** — Main exported component handling layout for page-level headings with responsive behavior (`plain` vs `card` variants)
-- **`variant`** — Controls visual treatment: `plain` (default, transparent) collapses `card` style (bordered, padded) on `md+` breakpoints
+### `TitleBlock` (default export)
+Primary component rendering the full page title chrome. Accepts the following props:
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | — | Page title text |
+| `subtitle` | `string` | — | Secondary descriptor |
+| `image` | `{ src, alt? }` | — | Entity image rendered beside title |
+| `backButton` | `{ label?, onClick }` | — | Back navigation (desktop-only) |
+| `actions` | `PageActionButton[]` | — | Action buttons rendered inline with title |
+| `actionsVariant` | `'icon-buttons' \| 'primary-buttons' \| 'menu-primary'` | `'icon-buttons'` | Action button style |
+| `menuActions` | `ActionsMenuGroup[]` | — | Overflow menu action groups |
+| `selector` | `ReactNode` | — | Desktop-only slot (e.g. `TabSelector`) |
+| `variant` | `'plain' \| 'card'` | `'plain'` | Visual container style |
+| `titleSize` | `'h1' \| 'h2'` | `'h2'` | Title typography size |
+| `titleAdornment` | `ReactNode` | — | Inline node after title (e.g. status `Tag`) |
+| `loading` | `boolean` | — | Swaps title/subtitle text for skeleton bars |
+| `titleWrap` | `boolean` | `false` | Allows multi-line title instead of truncation |
+
+### `TitleTextSkeleton`
+Internal component rendering inline skeleton bars that preserve line-box height during loading state — the header remains pixel-identical in height whether loaded or loading.
+
+### `TITLE_BLOCK_MIN_HEIGHT`
+Exported Tailwind class string (`'min-h-11 md:min-h-12'`) ensuring consistent header height regardless of whether action buttons are present. Reusable by other page chrome components.
 
 ## Usage Example
 
 ```typescript
-import { TitleBlock } from './title-block'
+import { TitleBlock } from '@/components/layout/title-block'
 
-// Basic usage
+// Basic usage — frozen h2 baseline
 <TitleBlock
   title="Devices"
-  subtitle="Manage all enrolled devices"
+  subtitle="All managed endpoints"
   backButton={{ label: 'Back', onClick: () => router.back() }}
-  actions={[
-    { label: 'Add Device', icon: PlusIcon, onClick: handleAdd },
-  ]}
+  actions={[{ label: 'Add Device', onClick: handleAdd }]}
   actionsVariant="primary-buttons"
 />
 
-// With entity image and card variant (e.g. mobile-first detail pages)
+// Help Center page — sanctioned h1 override
 <TitleBlock
-  title="Acme Corp"
-  subtitle="Enterprise Client"
-  image={{ src: '/logos/acme.png', alt: 'Acme Corp' }}
-  variant="card"
-  actions={[{ label: 'Edit', icon: EditIcon, onClick: handleEdit }]}
-  menuActions={[{ label: 'More', items: [...] }]}
-  selector={<TabSelector tabs={tabs} />}
+  title="Getting Started"
+  titleSize="h1"
+  titleAdornment={<Tag variant="info">New</Tag>}
+  titleWrap
 />
-```
 
-## Notes
+// Loading skeleton (height preserved)
+<TitleBlock
+  title="Releases"
+  subtitle="Recent updates"
+  loading
+/>
+```
 
-- The `selector` slot (e.g. a `TabSelector`) is desktop-only and rendered alongside actions
-- Back button is hidden on mobile (`hidden md:inline-flex`)
-- Title truncates with `title` attribute tooltip when content overflows
+> **Note:** This component is intentionally frozen. New page chrome designs must be implemented as separate components. See the in-file freeze notice for full rationale and the list of sanctioned exceptions. Source: [`title-block.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/components/layout/title-block.tsx)

package/src/components/loading/.card-skeleton.md

@@ -1,54 +1,47 @@
-<!-- source-hash: b4a4c7c8c54bac836e374bc9dd198d5b -->
-Reusable skeleton loading components for card UI elements, providing animated placeholder states that match the structure of vendor, blog, category, and alternative card layouts.
+<!-- source-hash: 496defa565da946c17804f2b3bb78de3 -->
+Unified card skeleton component providing consistent loading states for the four card types used across the application (`vendor`, `blog`, `category`, `alternative`).
 
 ## Key Components
 
 | Export | Description |
-|--------|-------------|
+|---|---|
 | `CardSkeleton` | Single card skeleton with variant-based layout rendering |
 | `CardSkeletonGrid` | Responsive grid of `CardSkeleton` instances for list loading states |
-| `CardSkeletonProps` | Interface defining variant, visibility toggles, and styling options |
+| `VendorCardContent` | Internal — logo, title, description, stats, and tag area |
+| `BlogCardContent` | Internal — OG image, title, chips, description, author, and metadata footer |
+| `CategoryCardContent` | Internal — icon grid, title, description, and action button |
+| `AlternativeCardContent` | Internal — avatar, title, description, and optional action button |
 
-**Internal sub-components (not exported):**
+### `CardSkeletonProps`
 
-| Component | Mirrors |
-|-----------|---------|
-| `VendorCardContent` | Logo, title, category, description, stats, and tag |
-| `BlogCardContent` | OG image, title chips, description, author, and date metadata |
-| `CategoryCardContent` | Icon grid, title, description, and action button |
-| `AlternativeCardContent` | Avatar, title, description, and optional action button |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `'vendor' \| 'blog' \| 'category' \| 'alternative'` | `'vendor'` | Selects the matching card layout |
+| `showActions` | `boolean` | `true` | Renders action button area |
+| `showMetadata` | `boolean` | `true` | Renders footer metadata row |
+| `containerClassName` | `string` | — | Overrides default card background and border classes |
+| `className` | `string` | — | Appended to the card container |
 
 ## Usage Example
 
 ```typescript
-import { CardSkeleton, CardSkeletonGrid } from "./card-skeleton"
+import { CardSkeleton, CardSkeletonGrid } from "@/components/skeletons/card-skeleton"
 
-// Single skeleton while fetching one vendor
-<CardSkeleton variant="vendor" showActions showMetadata />
+// Single vendor card loading state
+<CardSkeleton variant="vendor" />
 
-// Full loading grid for a blog listing page
-<CardSkeletonGrid
-  variant="blog"
-  count={4}
-  showActions={false}
-  showMetadata
-  className="my-8"
-/>
+// Blog card without metadata footer
+<CardSkeleton variant="blog" showMetadata={false} />
 
-// Category grid without custom container styling
+// Grid of 9 vendor skeletons
+<CardSkeletonGrid count={9} variant="vendor" />
+
+// Grid of blog skeletons with custom container style
 <CardSkeletonGrid
-  variant="category"
-  count={8}
-  containerClassName="bg-neutral-900 border border-neutral-700"
+  count={4}
+  variant="blog"
+  containerClassName="bg-white border border-gray-200"
 />
 ```
 
-## Props Reference
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `variant` | `'vendor' \| 'blog' \| 'category' \| 'alternative'` | `'vendor'` | Card layout to replicate |
-| `showActions` | `boolean` | `true` | Renders action button placeholder |
-| `showMetadata` | `boolean` | `true` | Renders footer metadata placeholder |
-| `containerClassName` | `string` | `bg-ods-card border border-ods-border` | Overrides card container background and border |
-| `count` *(grid only)* | `number` | `6` | Number of skeleton cards to render |
+> Grid column counts are variant-aware: `vendor` uses a 3-column layout at `lg`, `blog` uses 2-column at `md`, `category` uses 4-column at `lg`, and `alternative` is always single-column.

package/src/components/loading/.category-card-skeleton.md

@@ -1,41 +1,43 @@
-<!-- source-hash: 2ce1ed4f74bd8adbc4a828190f04cf96 -->
-A React skeleton component that displays a loading placeholder for category cards with animated shimmer effects while content is being fetched.
+<!-- source-hash: 345b2538bd8f070fb84d13df78fe015f -->
+Loading state placeholder for a category card UI component, rendering animated skeletons for icons, text, and a button while content is being fetched.
 
 ## Key Components
 
-- **CategoryCardSkeleton** - Main skeleton component that mimics the layout of a category card
-- **CategoryCardSkeletonProps** - Interface defining optional className for styling customization
-- **UnifiedSkeleton** - Imported base skeleton component for shapes and animations
-- **TextSkeleton** - Imported text-specific skeleton components for headings and body text
+- **`CategoryCardSkeleton`** — Main export. Renders an `<article>` with `role="status"` and `aria-label` for accessibility compliance during loading states.
+- **`UnifiedSkeleton`** — Used for circular icon placeholders (10 items) and the rectangular arrow button placeholder.
+- **`TextSkeleton.Heading` / `TextSkeleton.Body`** — Specialized text skeleton variants for the card's title and description lines.
 
 ## Usage Example
 
 ```typescript
 import { CategoryCardSkeleton } from './category-card-skeleton'
 
-// Basic usage
+// Basic usage in a loading state
 function CategoryGrid() {
-  const [loading, setLoading] = useState(true)
-  const [categories, setCategories] = useState([])
-
   return (
     <div className="grid grid-cols-3 gap-4">
-      {loading ? (
-        // Show skeleton placeholders while loading
-        Array.from({ length: 6 }).map((_, i) => (
-          <CategoryCardSkeleton key={i} />
-        ))
-      ) : (
-        categories.map(category => (
-          <CategoryCard key={category.id} {...category} />
-        ))
-      )}
+      {isLoading
+        ? Array.from({ length: 6 }).map((_, i) => (
+            <CategoryCardSkeleton key={i} />
+          ))
+        : categories.map((cat) => (
+            <CategoryCard key={cat.id} {...cat} />
+          ))}
     </div>
   )
 }
 
-// With custom styling
-<CategoryCardSkeleton className="shadow-lg border-blue-200" />
+// With custom className override
+<CategoryCardSkeleton className="col-span-2 border-dashed" />
 ```
 
-The component renders a structured skeleton with 10 circular icon placeholders, text content blocks of varying widths, and an action button placeholder, all with proper ARIA labels for accessibility.
+## Structure
+
+| Region | Skeleton Element |
+|---|---|
+| Icons row | 10 × circular `UnifiedSkeleton` (40×40px) |
+| Heading | `TextSkeleton.Heading` at 75% width |
+| Body lines | 2 × `TextSkeleton.Body` at 50% / 100% width |
+| Arrow button | Rectangular `UnifiedSkeleton` (48×48px, 6px radius) |
+
+**Source:** [`flamingo-stack/openframe-oss-lib`](https://github.com/flamingo-stack/openframe-oss-lib)

package/src/components/loading/.device-card-skeleton.md

@@ -1,27 +1,35 @@
-<!-- source-hash: 778a7f2774363f614672d36f1704ffb9 -->
-Loading skeleton component that mimics the exact layout of a `DeviceCard` to prevent layout shifts during data fetching.
+<!-- source-hash: 54aa570e451e331c157161933707661b -->
+Loading skeleton components that mirror the exact layout of `DeviceCard` to prevent layout shifts during data fetching.
 
 ## Key Components
 
 ### `DeviceCardSkeleton`
-A single animated placeholder card matching the three-row `DeviceCard` structure:
+A single animated placeholder card replicating the three-row structure of `DeviceCard`:
 - **Row 1:** Device icon + device name + more button
 - **Row 2:** OS badge + organization icon + organization name
 - **Row 3:** Status badge + last seen timestamp
 
+Uses `animate-pulse` on placeholder elements and matches exact dimensions to eliminate layout jumps.
+
 | Prop | Type | Description |
 |------|------|-------------|
-| `className` | `string?` | Additional CSS classes |
+| `className` | `string` | Optional additional CSS classes |
 
 ### `DeviceCardSkeletonGrid`
-Renders a responsive grid of `DeviceCardSkeleton` instances, matching the `DevicesGrid` responsive column layout.
+A responsive grid wrapper that renders `count` skeleton cards, matching the `DevicesGrid` column layout.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `count` | `number?` | `12` | Number of skeleton cards to render |
-| `className` | `string?` | — | Additional CSS classes |
+| `count` | `number` | `12` | Number of skeleton cards to render |
+| `className` | `string` | — | Optional additional CSS classes |
+
+**Responsive breakpoints:**
 
-**Responsive columns:** 1 → 2 (md) → 4 (lg)
+| Breakpoint | Columns |
+|-----------|---------|
+| Mobile | 1 |
+| `md` (tablet) | 2 |
+| `lg` (desktop) | 4 |
 
 ## Usage Example
 
@@ -29,19 +37,18 @@ Renders a responsive grid of `DeviceCardSkeleton` instances, matching the `Devic
 // Single skeleton card
 import { DeviceCardSkeleton } from "./device-card-skeleton"
 
-function DeviceDetailLoader() {
-  return <DeviceCardSkeleton className="max-w-sm" />
+function DevicePanel({ isLoading }: { isLoading: boolean }) {
+  if (isLoading) return <DeviceCardSkeleton />
+  return <DeviceCard />
 }
 
-// Full grid during page load
+// Skeleton grid during list fetch
 import { DeviceCardSkeletonGrid } from "./device-card-skeleton"
 
 function DevicesPage({ isLoading, devices }) {
-  if (isLoading) {
-    return <DeviceCardSkeletonGrid count={8} />
-  }
+  if (isLoading) return <DeviceCardSkeletonGrid count={8} />
   return <DevicesGrid devices={devices} />
 }
 ```
 
-> Both components include ARIA attributes (`role="status"` and `aria-label`) for screen reader accessibility during loading states.
+**Source:** [`device-card-skeleton.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/device-card-skeleton.tsx)