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

package/src/components/loading/.margin-report-skeleton.md

@@ -1,54 +1,49 @@
-<!-- source-hash: a465f87f85ec79ae37576015929fe094 -->
-A full-page loading skeleton for the Margin Report view, rendering animated placeholder blocks that mirror the report's layout sections while optionally displaying an overlay with a CTA or status message.
+<!-- source-hash: 748f0d8dedeec3d8bb5c7d5b38cb4fb6 -->
+A full-page loading skeleton for the Margin Report view, rendering placeholder shimmer blocks that mirror the report's layout sections while data is being fetched.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `MarginReportSkeleton` | `React.FC` | Main skeleton component with pulse animation and optional overlay |
-| `MarginReportSkeletonProps` | `interface` | Props contract for the skeleton component |
+### `MarginReportSkeleton`
 
-### Props
+Main export. Renders a multi-section skeleton layout matching the Margin Report structure.
+
+**Props (`MarginReportSkeletonProps`):**
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `animate` | `boolean` | `true` | Toggles CSS `animate-pulse` on the root element |
-| `description` | `React.ReactNode` | — | Explanatory text rendered above the overlay content |
-| `overlayContent` | `React.ReactNode` | — | Node rendered in a centered fixed overlay (e.g. button, spinner) |
-
-### Skeleton Sections Rendered
-
-```text
-├── Header (title + subtitle bars)
-├── Summary cards (3-column grid)
-├── MSP Profile + Report Info (2-column grid)
-├── Vendor lists — Commercial & Open-Source stacks (2-column, 5 rows each)
-├── Strategic Recommendations header + cards (3-column grid)
-└── OpenFrame value section (header + 3 value cards)
-```
+|---|---|---|---|
+| `animate` | `boolean` | `true` | Toggles Tailwind `animate-pulse` shimmer |
+| `description` | `React.ReactNode` | — | Text shown above the overlay content |
+| `overlayContent` | `React.ReactNode` | — | Node rendered in a centered fixed overlay (e.g. CTA button, spinner) |
+
+**Skeleton sections rendered (in order):**
+
+1. **Header** — title and subtitle placeholders
+2. **Summary cards** — 3-column grid of `h-32` blocks
+3. **MSP Profile & Report Info** — 2-column card row with icon + text shimmer
+4. **Vendor solution lists** — Commercial Stack / Open-Source Stack columns, each with 5 vendor rows (icon + name + cost placeholders)
+5. **Strategic Recommendations** — section heading + 3-column card grid
+6. **OpenFrame value section** — header with logo + 3-column value card grid
+7. **CTA Overlay** — conditionally renders a semi-transparent overlay with `overlayContent` fixed-centered on screen
 
 ## Usage Example
 
 ```typescript
-// Basic animated skeleton while data loads
+import { MarginReportSkeleton } from './margin-report-skeleton';
+
+// Basic shimmer while loading
 <MarginReportSkeleton />
 
-// Static skeleton with a gated CTA overlay
+// With overlay CTA (e.g. prompt user to generate report)
 <MarginReportSkeleton
-  animate={false}
-  description="Generate your free Margin Report to unlock insights."
+  animate={true}
+  description="Your margin report is ready to generate."
   overlayContent={
-    <Button onClick={handleGenerate}>
-      Generate Report
-    </Button>
+    <button onClick={handleGenerate}>Generate Report</button>
   }
 />
 
-// Skeleton with a loading spinner overlay
-<MarginReportSkeleton
-  description="Calculating your margins…"
-  overlayContent={<Spinner size="lg" />}
-/>
+// Static (no animation) for testing/screenshots
+<MarginReportSkeleton animate={false} />
 ```
 
-> **Note:** When `overlayContent` is provided, a semi-transparent overlay (`bg-ods-card/80`) covers the entire skeleton. The overlay content is viewport-centered via `fixed` positioning with pointer-events re-enabled only on the CTA container.
+**Source:** [`margin-report-skeleton.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/margin-report-skeleton.tsx)

package/src/components/loading/.openmsp-heartbeat.md

@@ -1,47 +1,45 @@
-<!-- source-hash: 9b080f2c1d6ef86ef972fc514cc318df -->
-A React component that displays an animated loading screen with a pulsing heart-like animation, progress indicator, and status message for OpenMSP report generation.
+<!-- source-hash: da03f70685b81a05475fa7db2ce0079d -->
+A full-screen loading component that displays an animated heartbeat logo with progress tracking, designed for long-running background operations like report generation.
 
 ## Key Components
 
-- **OpenmspHeartbeatLoader** - Main component that creates a full-screen loading interface with:
-  - Animated OpenMSP logo with heartbeat-style pulsing animation
-  - Progress percentage display
-  - Customizable status label
-  - Background processing notification
-  - Accessibility support with ARIA labels
+### `OpenmspHeartbeatLoader`
+
+A React client component that renders a centered loading screen with:
+
+- **Heartbeat animation** — inline `@keyframes` CSS (`heartbeatInline`) simulating a lub-dub double-beat pulse on the OpenMSP logo, avoiding Tailwind purge issues
+- **`OpenmspLogo`** — branded logo with customized bubble colors, scaled responsively (`w-16`/`h-16` → `w-24`/`h-24`)
+- **Progress indicator** — displays integer percentage (0–100) with secondary `/100%` label
+- **Status label** — configurable message defaulting to `"Processing…"`
+- **User reassurance message** — informs users they can navigate away safely
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `className` | `string` | `''` | Additional CSS classes for the outer container |
+| `progress` | `number` | `0` | Completion percentage (0–100) |
+| `label` | `string` | `"Processing…"` | Status message shown below progress |
+| `barWidth` | `string` | `'w-128'` | Tailwind width class for the content column |
 
 ## Usage Example
 
 ```typescript
-// Basic usage with default settings
-<OpenmspHeartbeatLoader />
-
-// With progress tracking
-<OpenmspHeartbeatLoader 
-  progress={45} 
-  label="Analyzing data..." 
-/>
-
-// With custom styling and progress bar width
-<OpenmspHeartbeatLoader 
-  className="bg-gray-100" 
-  progress={75}
-  label="Generating final report..."
-  barWidth="w-96"
-/>
-
-// In a report generation flow
-function ReportGenerator() {
-  const [progress, setProgress] = useState(0);
-  const [status, setStatus] = useState("Initializing...");
+import { OpenmspHeartbeatLoader } from './openmsp-heartbeat';
+
+export default function ReportPage() {
+  const [progress, setProgress] = React.useState(42);
 
   return (
-    <OpenmspHeartbeatLoader 
+    <OpenmspHeartbeatLoader
       progress={progress}
-      label={status}
+      label="Generating your MSP report…"
+      barWidth="w-96"
     />
   );
 }
 ```
 
-The component features a distinctive double-beat heartbeat animation (lub-dub pattern) that cycles every 3.6 seconds, providing visual feedback during long-running background processes while allowing users to navigate away safely.
+## Source
+
+[`openmsp-heartbeat.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/openmsp-heartbeat.tsx)

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

@@ -1,46 +1,43 @@
-<!-- source-hash: 254d5d86afe2187734cde56c533fc995 -->
-Loading skeleton component that renders a placeholder matching the exact layout and dimensions of an `OrganizationCard`, preventing layout shifts during data fetching.
+<!-- source-hash: 42afed7b963d9c8db89ec0c7a70f20ee -->
+Loading skeleton component that replicates the exact layout and dimensions of an `OrganizationCard`, preventing layout shifts during data fetching.
 
 ## Key Components
 
 ### `OrganizationCardSkeleton`
 Single card skeleton with three configurable sections:
-- **Header** — 60×60px org logo placeholder + title/subtitle text skeletons
-- **Description** — Fixed 48px height with two-line body text skeletons (toggled via `showDescription`)
-- **Footer** — Two stat items (icon + caption) and a tag/badge placeholder (toggled via `showFooter`)
+- **Header** — 60×60px org logo placeholder + title + subtitle text skeletons
+- **Description** — Fixed 48px height, two-line body text skeletons (toggled via `showDescription`)
+- **Footer** — Two icon+stat pairs and a tag/badge placeholder (toggled via `showFooter`)
 
 ### `OrganizationCardSkeletonGrid`
-Renders a responsive grid of `OrganizationCardSkeleton` instances:
-- Mobile: 1 column | Tablet (`md`): 2 columns | Desktop (`lg`): 3 columns
+Renders a responsive grid of `OrganizationCardSkeleton` instances. Defaults to 12 cards across a 1→2→3 column responsive layout.
 
 ### `OrganizationCardSkeletonProps`
+
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `className` | `string` | — | Additional CSS classes |
-| `containerClassName` | `string` | — | Overrides card background & border |
-| `showFooter` | `boolean` | `true` | Renders footer stats area |
-| `showDescription` | `boolean` | `true` | Renders description area |
+|---|---|---|---|
+| `className` | `string` | — | Additional CSS classes on the card |
+| `containerClassName` | `string` | — | Overrides background/border of the card container |
+| `showFooter` | `boolean` | `true` | Renders the stats/badge footer row |
+| `showDescription` | `boolean` | `true` | Renders the description area |
 
 ## Usage Example
 
 ```typescript
-// Single card skeleton
-<OrganizationCardSkeleton
-  showDescription={true}
-  showFooter={true}
-/>
+// Single skeleton card
+import { OrganizationCardSkeleton } from "./organization-card-skeleton"
+
+<OrganizationCardSkeleton showFooter={true} showDescription={true} />
+
+// Grid skeleton while fetching a list
+import { OrganizationCardSkeletonGrid } from "./organization-card-skeleton"
 
-// Full grid skeleton during data load
 <OrganizationCardSkeletonGrid
   count={9}
   showFooter={true}
   showDescription={false}
-  className="my-4"
+  className="my-6"
 />
+```
 
-// Custom container styling
-<OrganizationCardSkeleton
-  containerClassName="bg-gray-900 border border-gray-700"
-  showFooter={false}
-/>
-```
+> Both components set `role="status"` and `aria-label` for screen reader accessibility during loading states.

package/src/components/loading/.organization-icon-skeleton.md

@@ -1,41 +1,53 @@
-<!-- source-hash: 31726d42ed65c56efadaa8abd3f2fc5b -->
-A React skeleton loading component that provides visual placeholders for organization icons while data is loading, ensuring consistent layout and preventing visual jumps during loading states.
+<!-- source-hash: 45999614de7204fe66e3d0b2ca239d81 -->
+Loading skeleton component that renders a placeholder for `OrganizationIcon`/`VendorIcon` during async data fetching, preventing layout shifts by matching the icon's exact dimensions and styling.
 
 ## Key Components
 
-- **OrganizationIconSkeleton**: Main skeleton component with configurable size, background, and styling options
-- **OrganizationIconSkeletonProps**: TypeScript interface defining component props including size variants, styling options, and accessibility features
-- **sizeClasses**: Size mapping object that matches OrganizationIcon dimensions exactly (xs: 24px to xl: 64px)
-- **backgroundClasses**: Background style variants (dark, light, white) for different UI contexts
+### `OrganizationIconSkeletonProps`
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'l' \| 'xl'` | `'md'` | Pixel size variant (24px–64px) |
+| `className` | `string` | `''` | Additional Tailwind/CSS classes |
+| `showBackground` | `boolean` | `true` | Toggles the container background and border |
+| `backgroundStyle` | `'dark' \| 'light' \| 'white'` | `'dark'` | Background color variant |
+
+### `OrganizationIconSkeleton`
+The exported functional component. Renders an animated pulse placeholder (`animate-pulse`) sized to match the target icon exactly.
+
+**Size → class mapping:**
+
+| Size | Class | Pixels |
+|------|-------|--------|
+| `xs` | `w-6 h-6` | 24px |
+| `sm` | `w-8 h-8` | 32px |
+| `md` | `w-10 h-10` | 40px |
+| `lg` | `w-12 h-12` | 48px |
+| `l` | `w-14 h-14` | 56px |
+| `xl` | `w-16 h-16` | 64px |
 
 ## Usage Example
 
 ```typescript
-import { OrganizationIconSkeleton } from './organization-icon-skeleton'
+// Default — organizations table / dashboard
+<OrganizationIconSkeleton size="md" />
 
-// Basic usage in a table (default md size)
-<OrganizationIconSkeleton />
+// Devices table
+<OrganizationIconSkeleton size="sm" />
 
-// Device card with smaller size
-<OrganizationIconSkeleton size="sm" backgroundStyle="light" />
+// Detail / profile view
+<OrganizationIconSkeleton size="xl" backgroundStyle="light" />
 
-// Detail view with large size
-<OrganizationIconSkeleton 
-  size="xl" 
-  backgroundStyle="white"
-  className="shadow-sm"
-/>
+// Icon-only, no background container
+<OrganizationIconSkeleton size="sm" showBackground={false} />
 
-// Without background container
-<OrganizationIconSkeleton 
-  size="lg" 
-  showBackground={false}
+// White card background with extra margin
+<OrganizationIconSkeleton
+  size="lg"
+  backgroundStyle="white"
+  className="mr-3"
 />
-
-// Loading list with multiple skeletons
-{Array.from({ length: 3 }).map((_, i) => (
-  <OrganizationIconSkeleton key={i} size="md" />
-))}
 ```
 
-The component includes proper ARIA labels for accessibility and uses CSS animations for the pulsing skeleton effect. It maintains exact visual parity with the actual OrganizationIcon component to ensure seamless loading transitions.
+## Source
+
+[`organization-icon-skeleton.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/organization-icon-skeleton.tsx)

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

@@ -1,20 +1,28 @@
-<!-- source-hash: d81e064ec80f99a3beddcfc15467f602 -->
-Skeleton loading components for the page layout, providing animated placeholders that match the structure of major UI sections including headers, heroes, sidebars, articles, and vendor detail pages.
+<!-- source-hash: faa2b999162e0192fd42b39cf2569ca0 -->
+Provides skeleton UI components that mirror real page layout elements (announcement bar, header, hero, sidebar, article, vendor detail) during loading states, built with Tailwind CSS and animated pulse effects.
 
 ## Key Components
 
 | Export | Description |
-|--------|-------------|
-| `AnnouncementBarSkeleton` | Matches `AnnouncementBar` with logo, text lines, and close button placeholders |
-| `HeaderSkeleton` | Sticky header with logo, nav links, and action button skeletons |
-| `HeroSkeleton` | Full-width hero section with title, subtitle, and CTA placeholders |
+|---|---|
+| `AnnouncementBarSkeleton` | Skeleton for top announcement bars with logo, text, and close button |
+| `HeaderSkeleton` | Sticky header skeleton with logo, nav links, and action buttons (responsive) |
+| `HeroSkeleton` | Full-width hero section skeleton with title, subtitle, and CTA |
 | `SearchContainerSkeleton` | Search input with optional filter chip row |
-| `CategorySidebarSkeleton` | Sidebar mimicking `MultiLevelNavigation` with folder/file icons and README badges |
+| `CategorySidebarSkeleton` | File-tree sidebar skeleton mimicking `MultiLevelNavigation` with folder/file icons and badges |
 | `BreadcrumbSkeleton` | Horizontal breadcrumb trail with separator dots |
-| `ResultsHeaderSkeleton` | Results count and sort controls placeholder |
-| `TwoColumnLayoutSkeleton` | Responsive grid wrapper accepting custom sidebar/main content with configurable `sidebarPosition` |
-| `ArticleLayoutSkeleton` | Full article page skeleton with header, featured image, and paragraph blocks |
-| `VendorDetailLayoutSkeleton` | Vendor detail page with breadcrumb, hero logo/title area, and responsive layout |
+| `ResultsHeaderSkeleton` | Results count / sort bar skeleton |
+| `TwoColumnLayoutSkeleton` | Composable two-column grid (sidebar + main), supports left/right sidebar position |
+| `ArticleLayoutSkeleton` | Full article skeleton: tags, title, metadata, featured image, and 12 body paragraphs |
+| `VendorDetailLayoutSkeleton` | Vendor detail page skeleton with breadcrumb, hero logo/title, and responsive layout |
+
+### Props
+
+| Component | Key Props |
+|---|---|
+| `SearchContainerSkeleton` | `showFilters?: boolean`, `className?: string` |
+| `TwoColumnLayoutSkeleton` | `sidebarContent?: ReactNode`, `mainContent?: ReactNode`, `sidebarPosition?: 'left' \| 'right'` |
+| All others | `className?: string` |
 
 ## Usage Example
 
@@ -23,24 +31,38 @@ import {
   HeaderSkeleton,
   TwoColumnLayoutSkeleton,
   CategorySidebarSkeleton,
+  ArticleLayoutSkeleton,
 } from "./page-layout-skeleton"
 
-// Drop-in loading state for a browse page
-function BrowsePage() {
-  if (isLoading) {
-    return (
-      <>
-        <HeaderSkeleton />
-        <TwoColumnLayoutSkeleton
-          sidebarContent={<CategorySidebarSkeleton />}
-          sidebarPosition="left"
-        />
-      </>
-    )
-  }
-  return <ActualContent />
+// Drop-in page loading state
+function CatalogPageSkeleton() {
+  return (
+    <>
+      <HeaderSkeleton />
+      <TwoColumnLayoutSkeleton
+        sidebarPosition="left"
+        sidebarContent={<CategorySidebarSkeleton />}
+        // mainContent defaults to <CardSkeletonGrid count={6} />
+      />
+    </>
+  )
+}
+
+// Slot in a custom main area
+function ArticlePage() {
+  return (
+    <TwoColumnLayoutSkeleton
+      mainContent={<ArticleLayoutSkeleton />}
+      sidebarPosition="right"
+    />
+  )
 }
+```
+
+## Notes
+
+- All skeletons use `bg-ods-skeleton` / `bg-ods-border` design tokens and `animate-pulse` for consistent motion.
+- `TwoColumnLayoutSkeleton` defaults to `CategorySidebarSkeleton` + `CardSkeletonGrid` when no children are provided.
+- `CategorySidebarSkeleton` hard-codes 11 navigation items to closely mirror the actual `MultiLevelNavigation` shape, including README badges and chevron icons.
 
-// Inline search skeleton with filters hidden
-<SearchContainerSkeleton showFilters={false} className="my-4" />
-```
+**Source:** [`page-layout-skeleton.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/page-layout-skeleton.tsx)

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

@@ -1,40 +1,39 @@
-<!-- source-hash: 8c0e5c74de8bbbd5020de8b54978e503 -->
-Accessible loading placeholder component providing a base `UnifiedSkeleton` with specialized sub-components for consistent skeleton UI across the application.
+<!-- source-hash: 2711fbf4f1f9d8e6410975aacc0cd4de -->
+A unified skeleton loading component library providing accessible, animated placeholder elements for content loading states across the application.
 
 ## Key Components
 
-### `UnifiedSkeleton` (base component)
-Core skeleton element with dark theme styling (`#2A2A2A` base), pulse animation, and full accessibility support.
+### `UnifiedSkeleton`
+Base skeleton component accepting:
+- `variant` — Shape style: `default` (rounded), `text` (rounded-sm), `circular`, `rectangular`
+- `width` / `height` — Custom dimensions; defaults to full width with variant-based height
+- `animate` — Toggles pulse animation; respects `prefers-reduced-motion` via `motion-reduce:animate-none`
+- `aria-label` — Screen reader label (defaults to `"Loading content"`)
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `variant` | `'default' \| 'text' \| 'circular' \| 'rectangular'` | `'default'` | Shape/border-radius style |
-| `width` | `string \| number` | — | Custom width override |
-| `height` | `string \| number` | — | Custom height override |
-| `animate` | `boolean` | `true` | Toggle pulse animation (respects `prefers-reduced-motion`) |
-| `aria-label` | `string` | `"Loading content"` | Screen reader label |
-
-### `TextSkeleton` namespace
+### `TextSkeleton`
+Namespace of text-specific variants:
 | Export | Use Case |
-|--------|----------|
-| `TextSkeleton.Heading` | H1/H2 placeholders (`h-8` → `h-12`) |
-| `TextSkeleton.Subheading` | H3/H4 placeholders (`h-6` → `h-8`) |
-| `TextSkeleton.Body` | Paragraph text (`h-4` → `h-5`) |
-| `TextSkeleton.Caption` | Metadata/captions (`h-3` → `h-4`) |
+|---|---|
+| `TextSkeleton.Heading` | H1/H2 placeholders |
+| `TextSkeleton.Subheading` | H3/H4 placeholders |
+| `TextSkeleton.Body` | Paragraph text |
+| `TextSkeleton.Caption` | Captions and metadata |
 
-### `InteractiveSkeleton` namespace
+### `InteractiveSkeleton`
+UI control placeholders:
 | Export | Use Case |
-|--------|----------|
-| `InteractiveSkeleton.Button` | Fixed-width button placeholder |
-| `InteractiveSkeleton.Input` | Full-width input field placeholder |
-| `InteractiveSkeleton.Chip` | Pill-shaped filter chip placeholder |
+|---|---|
+| `InteractiveSkeleton.Button` | CTA buttons |
+| `InteractiveSkeleton.Input` | Form fields |
+| `InteractiveSkeleton.Chip` | Filter chips |
 
-### `MediaSkeleton` namespace
+### `MediaSkeleton`
+Media and icon placeholders:
 | Export | Use Case |
-|--------|----------|
-| `MediaSkeleton.Avatar` | Circular avatar (`sm/md/lg`) |
-| `MediaSkeleton.CardImage` | `1200×630` aspect-ratio image (matches OG card, prevents layout shift) |
-| `MediaSkeleton.Icon` | Square icon placeholder (`sm/md/lg`) |
+|---|---|
+| `MediaSkeleton.Avatar` | Profile images (`sm`/`md`/`lg`) |
+| `MediaSkeleton.CardImage` | OG-ratio card images (1200×630) |
+| `MediaSkeleton.Icon` | Icons (`sm`/`md`/`lg`) |
 
 ## Usage Example
 
@@ -46,24 +45,22 @@ import {
   MediaSkeleton,
 } from "./unified-skeleton"
 
-// Basic usage
-<UnifiedSkeleton variant="rectangular" height={200} />
+// Custom skeleton
+<UnifiedSkeleton variant="rectangular" width={200} height={100} />
 
 // Composing a card loading state
-function TicketCardSkeleton() {
+function CardSkeleton() {
   return (
-    <div className="flex gap-3 p-4">
-      <MediaSkeleton.Avatar size="md" />
-      <div className="flex-1 space-y-2">
-        <TextSkeleton.Heading className="w-3/4" />
-        <TextSkeleton.Body />
-        <TextSkeleton.Caption className="w-1/2" />
+    <div className="flex flex-col gap-3 p-4">
+      <MediaSkeleton.CardImage />
+      <div className="flex items-center gap-2">
+        <MediaSkeleton.Avatar size="sm" />
+        <TextSkeleton.Subheading className="w-48" />
       </div>
+      <TextSkeleton.Body />
+      <TextSkeleton.Body className="w-3/4" />
       <InteractiveSkeleton.Button />
     </div>
   )
 }
-
-// Disable animation (e.g. for snapshot tests)
-<UnifiedSkeleton animate={false} aria-label="Loading ticket list" />
 ```

package/src/components/loading/.users-grid-skeleton.md

@@ -1,45 +1,26 @@
-<!-- source-hash: b81e47a927a9ff4d5803ff0d1171b304 -->
-A skeleton loading component that displays a placeholder table structure while user data is being fetched, providing visual feedback during loading states.
+<!-- source-hash: b6ac8db23428c76629b002b2787c23ba -->
+A loading skeleton placeholder for the users data grid, rendering an animated pulsing table with header columns and configurable blank rows while user data is being fetched.
 
 ## Key Components
 
-- **`UsersGridSkeleton`** - Main skeleton component that renders an animated placeholder table
-- **`Props`** interface defining:
-  - `rows` - Number of skeleton rows to display (defaults to 10)
-  - `className` - Optional additional CSS classes for styling
-
-## Features
-
-- **Responsive Design**: Horizontal scroll for mobile compatibility with `overflow-x-auto`
-- **Pulse Animation**: Built-in `animate-pulse` class for loading feedback
-- **Fixed Structure**: Matches actual users grid with 5 columns (Name, Email, Role, Created, Last Sign-In)
-- **Customizable Rows**: Configurable number of skeleton rows based on expected data size
-- **Theme Integration**: Uses ODS (design system) color tokens and styling
+- **`UsersGridSkeleton`** — Default export component that renders a full-width table skeleton with five fixed columns: Name, Email, Role, Created, and Last Sign-In.
+- **`Props`** — Interface accepting `rows` (number of skeleton rows to render, defaults to `10`) and an optional `className` for style overrides.
 
 ## Usage Example
 
 ```typescript
-import { UsersGridSkeleton } from './users-grid-skeleton'
-
-// Basic usage with default 10 rows
-function UsersList() {
-  const [loading, setLoading] = useState(true)
-  const [users, setUsers] = useState([])
-
-  if (loading) {
-    return <UsersGridSkeleton />
-  }
-
-  return <UsersGrid users={users} />
-}
-
-// Custom row count and styling
-function AdminPanel() {
-  return (
-    <UsersGridSkeleton 
-      rows={5}
-      className="shadow-lg"
-    />
-  )
-}
-```
+import { UsersGridSkeleton } from "./users-grid-skeleton"
+
+// Default: 10 skeleton rows
+<UsersGridSkeleton />
+
+// Custom row count and additional styling
+<UsersGridSkeleton rows={5} className="mt-4" />
+```
+
+## Notes
+
+- Uses `animate-pulse` for the loading shimmer effect via Tailwind CSS.
+- Columns are statically defined as `['Name', 'Email', 'Role', 'Created', 'Last Sign-In']` — matching the expected shape of the users table.
+- Each skeleton cell renders a full-width `h-4` bar using the `ods-border` design token, consistent with the OpenFrame design system.
+- The `cn` utility (from [`utils/cn`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/utils/cn.ts)) merges class names, allowing external `className` overrides without conflicts.