@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214

package/src/components/icons-v2-generated/vehicles-and-delivery/.index.md

@@ -0,0 +1,36 @@
+<!-- source-hash: 10bc87374ddc44d31270589592965faf -->
+Barrel export file that re-exports all transportation and travel-related icon components from their individual modules as a single unified entry point.
+
+## Key Components
+
+All exports are React icon components in the **Transportation & Travel** category:
+
+| Group | Icons |
+|-------|-------|
+| **Road Vehicles** | `CarIcon`, `CarSideIcon`, `CarSideElectricIcon`, `CarTaxiIcon`, `BikeIcon`, `MotorbikeIcon`, `BusIcon`, `TruckIcon`, `TruckFastIcon`, `TruckDelayIcon`, `TruckMedicalIcon`, `RvIcon` |
+| **Rail & Water** | `TrainIcon`, `SpeedTrainIcon`, `TramIcon`, `TrainTunnelIcon`, `CableCarIcon`, `FerryIcon`, `SailboatIcon` |
+| **Air & Space** | `PlaneIcon`, `PlaneAltIcon`, `PlaneOffIcon`, `PlaneVerticalIcon`, `PlaneVerticalOffIcon`, `HelicopterIcon`, `Rocket01Icon`, `Rocket02Icon` |
+| **Parcels** | `Parcel01Icon`–`Parcel03Icon`, `ParcelsIcon`, plus variants (Check, Fast, Lock, Search, Star, Heart, Label, Delay) |
+| **Infrastructure** | `RoadIcon`, `RoadBarrierIcon`, `TrafficConeIcon`, `TrafficSignalIcon`, `PumpGasIcon`, `PumpElectricIcon`, `Gauge01Icon`, `Gauge02Icon` |
+| **Accessories** | `AnchorIcon`, `HelmetIcon`, `SteeringWheelIcon`, `CarBattery01Icon`, `CarBattery02Icon`, `BabyCarriageIcon`, `TrolleyIcon`, `HandParcelIcon` |
+
+## Usage Example
+
+```typescript
+import {
+  CarSideElectricIcon,
+  TruckFastIcon,
+  Parcel01CheckIcon,
+  PlaneIcon,
+  TrafficSignalIcon
+} from './transportation';
+
+// Use in a React component
+const ShipmentStatus = () => (
+  <div>
+    <TruckFastIcon size={24} />
+    <Parcel01CheckIcon size={24} color="green" />
+    <PlaneIcon size={24} />
+  </div>
+);
+```

package/src/components/icons-v2-generated/weather-and-nature/.flower-sakura-icon.md

@@ -0,0 +1,36 @@
+<!-- source-hash: 73f62f8a88e9d1c95a1eb2397e3f5878 -->
+A React SVG icon component that renders a sakura (cherry blossom) flower icon with configurable size, color, and className props.
+
+## Key Components
+
+### `FlowerSakuraIconProps`
+Interface extending `SVGProps<SVGSVGElement>` (excluding `width` and `height`) with:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `className` | `string` | `""` | CSS class name |
+| `size` | `number` | `24` | Width and height in pixels |
+| `color` | `string` | `"currentColor"` | Fill color |
+
+### `FlowerSakuraIcon`
+Functional component rendering a 24×24 viewBox SVG sakura flower with two paths — an outer petal shape and an inner center detail.
+
+## Usage Example
+
+```typescript
+import { FlowerSakuraIcon } from "./flower-sakura-icon";
+
+// Default usage
+<FlowerSakuraIcon />
+
+// Custom size and color
+<FlowerSakuraIcon size={32} color="#FF69B4" />
+
+// With Tailwind class
+<FlowerSakuraIcon className="text-pink-400" size={20} />
+
+// Inherits parent color via currentColor
+<div style={{ color: "#e91e8c" }}>
+  <FlowerSakuraIcon />
+</div>
+```

package/src/components/icons-v2-generated/weather-and-nature/.index.md

@@ -0,0 +1,34 @@
+<!-- source-hash: 9d9dad636cdb6841a5aa6411927da6ee -->
+Barrel export file for the **nature, weather, and environment** icon set, re-exporting all individual icon components from their respective modules.
+
+## Key Components
+
+| Category | Exports |
+|---|---|
+| Weather | `CloudWeatherBoltIcon`, `CloudWeatherDrizzleIcon`, `CloudWeatherFogIcon`, `CloudWeatherRainIcon`, `CloudWeatherSnowIcon`, `CloudWeatherSunIcon`, `HurricaneIcon`, `TornadoIcon`, `WindIcon` |
+| Temperature & Sky | `TemperatureIcon`, `TemperatureColdIcon`, `TemperatureHotIcon`, `HeatIcon`, `MoonIcon`, `MoonStarIcon`, `Sun01Icon`, `Sun02Icon`, `SunriseIcon`, `SunsetIcon`, `SnowflakeIcon` |
+| Flora | `FlowerIcon`, `FlowerSakuraIcon`, `FlowerTulipIcon`, `FlowerPlantIcon`, `LeafIcon`, `LeavesIcon`, `TreeIcon`, `TreesIcon`, `SeedlingIcon`, `SeedlingPotIcon`, `HandSeedlingIcon` |
+| Animals | `DogIcon`, `DogLeashIcon`, `PawIcon` |
+| Natural Disasters | `ExplosionIcon`, `FireIcon`, `FloodIcon`, `DrowningIcon`, `HillAvalancheIcon`, `HillRockslideIcon` |
+| Misc | `AquariumIcon`, `UfoIcon`, `RadiationIcon`, `StarsIcon`, `SparkleIcon`, `WaterDropletIcon`, `WaterWaveIcon` |
+
+## Usage Example
+
+```typescript
+import {
+  SunriseIcon,
+  TornadoIcon,
+  FlowerSakuraIcon,
+  TemperatureColdIcon,
+} from './icons/nature';
+
+// Use in a React component
+const WeatherDisplay = () => (
+  <div>
+    <SunriseIcon />
+    <TemperatureColdIcon />
+    <TornadoIcon />
+    <FlowerSakuraIcon />
+  </div>
+);
+```

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

@@ -0,0 +1,43 @@
+<!-- source-hash: f1c1fbdd04d056b4c98f44f6bacd4fb8 -->
+Unified page layout components providing two layout variants for consistent page structure across the application.
+
+## Key Components
+
+| Export | Max Width | Purpose |
+|--------|-----------|---------|
+| `PageShell` | 1920px | List pages, dashboards, wide layouts |
+| `ArticleDetailLayout` | 1280px | Articles, blog posts, release notes, case studies |
+
+**`LayoutProps` interface:**
+- `children` — page content (no additional layout wrappers needed)
+- `schemas?` — optional JSON-LD `<script>` elements (breadcrumbs, article schema, etc.)
+
+Both components render a `<main>` element with `bg-ods-bg`, `min-h-screen`, responsive horizontal padding (`px-6` / `md:px-20`), and vertical padding (`py-6` / `md:py-10`).
+
+## Usage Example
+
+```typescript
+// Wide layout for a list/dashboard page
+import { PageShell } from '@/components/article-detail-layout';
+
+export default function DevicesPage() {
+  return (
+    <PageShell>
+      <DeviceTable />
+    </PageShell>
+  );
+}
+
+// Constrained layout for a readable article/detail page
+import { ArticleDetailLayout } from '@/components/article-detail-layout';
+
+export default function BlogPost({ schema }: { schema: React.ReactNode }) {
+  return (
+    <ArticleDetailLayout schemas={schema}>
+      <ArticleContent />
+    </ArticleDetailLayout>
+  );
+}
+```
+
+> Child components should render content only — no additional `<main>`, max-width, or padding wrappers required.

package/src/components/layout/.back-button.md

@@ -0,0 +1,40 @@
+<!-- source-hash: bbc5ab0313f6e7cb301fe2ba986ea93b -->
+A reusable "Back" navigation button component that renders a left chevron icon alongside a customizable label, styled with ODS (OpenFrame Design System) tokens.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `BackButton` | `React.FC` | Main button component with chevron icon and label |
+| `BackButtonProps` | `interface` | Extends `HTMLButtonElement` attributes, omitting `children` |
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | `'Back'` | Button text displayed next to the chevron |
+| `onClick` | `MouseEventHandler` | — | Click handler for navigation logic |
+| `className` | `string` | — | Additional CSS classes merged via `cn()` |
+| `type` | `string` | `'button'` | HTML button type attribute |
+
+## Usage Example
+
+```typescript
+import { BackButton } from './components/back-button'
+import { useRouter } from 'next/navigation'
+
+export function PageHeader() {
+  const router = useRouter()
+
+  return (
+    <header>
+      <BackButton
+        label="Back to Dashboard"
+        onClick={() => router.back()}
+      />
+    </header>
+  )
+}
+```
+
+> **Note:** The `type` prop defaults to `'button'` (not `'submit'`) to prevent accidental form submissions when used inside `<form>` elements.

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

@@ -1,12 +1,32 @@
-<!-- source-hash: 5eb52e6779e6d0d0828920da4c48f44b -->
-A standardized layout component that provides consistent structure and functionality for all list-based pages in the OpenFrame application, including search, filtering, and mobile-responsive design patterns.
+<!-- source-hash: 32c9dcb06a56d3c5fa171224fc048981 -->
+A deprecated layout component for list-based pages in OpenFrame, providing a standardized structure with a title header, full-width search bar with debouncing, optional mobile filter modal, and a main content area for tables or grids.
 
 ## Key Components
 
-- **`ListPageLayout`** - Main layout component with title header, search bar, and content area
-- **`ListPageLayoutProps`** - TypeScript interface defining component props including search, filtering, and mobile configuration options
-- **Mobile Filter Integration** - Built-in support for mobile filter modal with sort and filter capabilities
-- **Debounced Search** - Integrated search functionality with 500ms debounce for performance optimization
+### `ListPageLayoutProps`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `title` | `string` | Page title displayed in the header |
+| `searchPlaceholder` | `string` | Placeholder text for the search input |
+| `searchValue` | `string` | Controlled search input value |
+| `onSearch` | `(term: string) => void` | Callback fired after 500ms debounce |
+| `headerActions` | `React.ReactNode` | Optional content rendered right-aligned in the header |
+| `actions` | `PageActionButton[]` | Action buttons passed to the page container |
+| `mobileFilterGroups` | `FilterGroup[]` | Filter groups shown in the mobile filter modal |
+| `mobileSortConfig` | `SortConfig` | Sort columns available in the mobile filter modal |
+| `stickyHeader` | `boolean` | Makes the search bar sticky on scroll |
+| `error` | `string \| null` | Renders a `PageError` instead of the layout |
+| `padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | Inner padding size (default: `'sm'`) |
+| `background` | `'default' \| 'card' \| 'transparent'` | Background style (default: `'default'`) |
+
+### `ListPageLayout`
+
+The main exported function component. Internally manages:
+
+- **Local search state** synced with the controlled `searchValue` prop
+- **Debounced search** — `onSearch` fires 500ms after the user stops typing
+- **Mobile filter visibility** — a `Filter02Icon` button toggling a `FilterModal` overlay, rendered only when `mobileFilterGroups` or `mobileSortConfig` are provided
 
 ## Usage Example
 
@@ -15,38 +35,27 @@ import { ListPageLayout } from './list-page-layout'
 import { Button } from '../ui'
 
 function DevicesPage() {
-  const [searchTerm, setSearchTerm] = useState('')
+  const [search, setSearch] = useState('')
   const [filters, setFilters] = useState({})
 
   return (
     <ListPageLayout
-      title="Device Management"
-      headerActions={
-        <div className="flex gap-2">
-          <Button variant="outline">Export</Button>
-          <Button>Add Device</Button>
-        </div>
-      }
+      title="Devices"
       searchPlaceholder="Search devices..."
-      searchValue={searchTerm}
-      onSearch={setSearchTerm}
+      searchValue={search}
+      onSearch={setSearch}
+      headerActions={<Button>Refresh</Button>}
       mobileFilterGroups={[
-        {
-          id: 'status',
-          label: 'Status',
-          options: [
-            { id: 'online', label: 'Online' },
-            { id: 'offline', label: 'Offline' }
-          ]
-        }
+        { id: 'status', label: 'Status', options: [{ value: 'online', label: 'Online' }] },
       ]}
       onMobileFilterChange={setFilters}
       currentMobileFilters={filters}
+      stickyHeader
     >
-      <DeviceTable data={filteredDevices} />
+      <DevicesTable />
     </ListPageLayout>
   )
 }
 ```
 
-The component provides a consistent layout structure with a title header, optional action buttons, debounced search bar, and mobile-responsive filter modal. It's designed to standardize the appearance and behavior of list pages throughout the application while supporting flexible content through the children prop.
+> **Deprecated** — Use `PageLayout` from `'../layout/page-layout'` instead.

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

@@ -1,56 +1,45 @@
-<!-- source-hash: 8dcbf27d582bedb7a355f6a4841a68f7 -->
-A versatile React container component that provides both legacy layout functionality and advanced page structure patterns with responsive headers, actions, and variants.
+<!-- 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.
 
 ## Key Components
 
-- **PageContainer** - Main component supporting both legacy and advanced usage patterns
-- **LegacyPageContainerProps** - Interface for backward-compatible layout functionality
-- **AdvancedPageContainerProps** - Interface for new UI patterns with variants, headers, and actions
-- **isAdvancedProps** - Type guard function to differentiate between usage patterns
+### Exported Types
+- **`PageContainerProps`** — Union type supporting `LegacyPageContainerProps` and `AdvancedPageContainerProps`
+
+### 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`
 
 ## Usage Example
 
 ```typescript
-// Legacy usage (backward compatible)
-<PageContainer 
-  backgroundClassName="bg-gray-100"
-  contentPadding="p-6"
-  maxWidth="max-w-6xl"
->
-  <h1>Your Content</h1>
+// Legacy usage
+<PageContainer backgroundClassName="bg-gray-100" contentPadding="px-6 py-4">
+  <h1>Content</h1>
 </PageContainer>
 
-// Advanced usage with variant-specific layouts
+// Advanced - list page
 <PageContainer
-  variant="detail"
-  title="User Profile"
-  subtitle="Manage user information and settings"
-  backButton={{
-    label: "Back to Users",
-    onClick: () => router.back()
-  }}
-  actions={[
-    { label: "Edit", onClick: handleEdit, variant: "primary" },
-    { label: "Delete", onClick: handleDelete, variant: "destructive" }
-  ]}
-  padding="md"
-  background="card"
+  variant="list"
+  title="Devices"
+  subtitle="All managed devices"
+  actions={[{ label: 'Add Device', onClick: handleAdd }]}
 >
-  <div>Page content goes here</div>
+  <DeviceTable />
 </PageContainer>
 
-// Form variant with custom header actions
+// Advanced - detail page with back button
 <PageContainer
-  variant="form"
-  title="Create New Project"
-  headerActions={<Button variant="outline">Save Draft</Button>}
-  actions={[
-    { label: "Cancel", onClick: handleCancel },
-    { label: "Create", onClick: handleSubmit, variant: "primary" }
-  ]}
+  variant="detail"
+  title="Device Details"
+  backButton={{ label: 'Back', onClick: () => router.back() }}
+  headerActions={<StatusBadge status="online" />}
 >
-  <ProjectForm />
+  <DeviceDetail />
 </PageContainer>
 ```
 
-The component automatically handles responsive layouts, mobile-optimized action buttons, and provides consistent spacing and styling across different page types.
+> **Deprecated:** Prefer `PageLayout` from `'../layout/page-layout'` for new implementations.

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

@@ -0,0 +1,50 @@
+<!-- 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.
+
+## Key Components
+
+### `PageLayout` (default export)
+Main layout component accepting the following props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | — | Page content |
+| `title` | `string` | — | Page heading |
+| `subtitle` | `string` | — | Secondary heading |
+| `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 |
+| `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
+
+## Usage Example
+
+```typescript
+import { PageLayout } from './page-layout'
+
+export default function SettingsPage() {
+  return (
+    <PageLayout
+      title="Settings"
+      subtitle="Manage your preferences"
+      backButton={{ label: 'Back', onClick: () => router.back() }}
+      actions={[{ label: 'Save', onClick: handleSave }]}
+      actionsVariant="primary-buttons"
+      headerVariant="card"
+    >
+      <SettingsForm />
+    </PageLayout>
+  )
+}
+```
+
+> When `actionsVariant="primary-buttons"`, the content area automatically gains `pb-28` on mobile to prevent overlap with sticky action buttons.

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

@@ -0,0 +1,42 @@
+<!-- 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.
+
+## 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
+
+## Usage Example
+
+```typescript
+import { TitleBlock } from './title-block'
+
+// Basic usage
+<TitleBlock
+  title="Devices"
+  subtitle="Manage all enrolled devices"
+  backButton={{ label: 'Back', onClick: () => router.back() }}
+  actions={[
+    { label: 'Add Device', icon: PlusIcon, onClick: handleAdd },
+  ]}
+  actionsVariant="primary-buttons"
+/>
+
+// With entity image and card variant (e.g. mobile-first detail pages)
+<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} />}
+/>
+```
+
+## Notes
+
+- 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

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

@@ -1,45 +1,54 @@
-<!-- source-hash: 275660d702885f476e326afc5abc6cbb -->
-A comprehensive skeleton loading component system that provides consistent card loading states across different layouts and variants in the application.
+<!-- 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.
 
 ## Key Components
 
-- **CardSkeleton** - Main unified skeleton component supporting vendor, blog, category, and alternative card layouts
-- **CardSkeletonGrid** - Grid wrapper for displaying multiple skeleton cards with responsive layouts
-- **VendorCardContent** - Skeleton matching vendor cards with logo, title, description, and stats
-- **BlogCardContent** - Skeleton for blog posts with image, title, chips, and metadata
-- **CategoryCardContent** - Skeleton for category cards with icon grid and content
-- **AlternativeCardContent** - Skeleton for vendor comparison/alternative cards
+| 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 |
+
+**Internal sub-components (not exported):**
+
+| 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 |
 
 ## Usage Example
 
 ```typescript
-import { CardSkeleton, CardSkeletonGrid } from './card-skeleton'
+import { CardSkeleton, CardSkeletonGrid } from "./card-skeleton"
 
-// Single vendor card skeleton
-<CardSkeleton 
-  variant="vendor" 
-  showActions={true} 
-  showMetadata={true} 
-/>
+// Single skeleton while fetching one vendor
+<CardSkeleton variant="vendor" showActions showMetadata />
 
-// Blog card grid while loading
-<CardSkeletonGrid 
-  count={6} 
+// Full loading grid for a blog listing page
+<CardSkeletonGrid
   variant="blog"
-  className="custom-grid"
+  count={4}
+  showActions={false}
+  showMetadata
+  className="my-8"
 />
 
-// Category cards with custom styling
-<CardSkeleton 
+// Category grid without custom container styling
+<CardSkeletonGrid
   variant="category"
-  containerClassName="bg-custom border-custom"
-/>
-
-// Alternative vendor cards (no metadata)
-<CardSkeleton 
-  variant="alternative"
-  showActions={false}
+  count={8}
+  containerClassName="bg-neutral-900 border border-neutral-700"
 />
 ```
 
-The component uses the unified skeleton system for consistent animations and styling, with each variant precisely matching the structure and dimensions of its corresponding real card component for seamless loading transitions.
+## 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 |

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

@@ -1,43 +1,47 @@
-<!-- source-hash: 683fe375c683dcca047380ff0dd11c94 -->
-A React TypeScript component providing loading skeleton placeholders for device cards and device grids, maintaining exact layout dimensions to prevent content jumping during data loading.
+<!-- source-hash: 778a7f2774363f614672d36f1704ffb9 -->
+Loading skeleton component that mimics the exact layout of a `DeviceCard` to prevent layout shifts during data fetching.
 
 ## Key Components
 
-- **`DeviceCardSkeleton`** - Individual device card loading skeleton with three-row layout (device info, OS/organization, status/last seen)
-- **`DeviceCardSkeletonGrid`** - Responsive grid container for multiple device card skeletons with configurable count
-- **`DeviceCardSkeletonProps`** - Interface defining optional className prop for styling customization
-- **`OrganizationIconSkeleton`** - Imported component for organization icon placeholder
+### `DeviceCardSkeleton`
+A single animated placeholder card matching the three-row `DeviceCard` structure:
+- **Row 1:** Device icon + device name + more button
+- **Row 2:** OS badge + organization icon + organization name
+- **Row 3:** Status badge + last seen timestamp
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `className` | `string?` | Additional CSS classes |
+
+### `DeviceCardSkeletonGrid`
+Renders a responsive grid of `DeviceCardSkeleton` instances, matching the `DevicesGrid` responsive column layout.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `count` | `number?` | `12` | Number of skeleton cards to render |
+| `className` | `string?` | — | Additional CSS classes |
+
+**Responsive columns:** 1 → 2 (md) → 4 (lg)
 
 ## Usage Example
 
 ```typescript
-import { DeviceCardSkeleton, DeviceCardSkeletonGrid } from './device-card-skeleton'
+// Single skeleton card
+import { DeviceCardSkeleton } from "./device-card-skeleton"
 
-// Single device card skeleton
-function LoadingDevice() {
-  return <DeviceCardSkeleton className="mb-4" />
+function DeviceDetailLoader() {
+  return <DeviceCardSkeleton className="max-w-sm" />
 }
 
-// Grid of device skeletons while loading
-function DevicesLoadingView() {
-  return (
-    <div className="p-4">
-      <DeviceCardSkeletonGrid 
-        count={8} 
-        className="mt-6"
-      />
-    </div>
-  )
-}
+// Full grid during page load
+import { DeviceCardSkeletonGrid } from "./device-card-skeleton"
 
-// Conditional rendering during data fetch
 function DevicesPage({ isLoading, devices }) {
   if (isLoading) {
-    return <DeviceCardSkeletonGrid count={12} />
+    return <DeviceCardSkeletonGrid count={8} />
   }
-  
   return <DevicesGrid devices={devices} />
 }
 ```
 
-The skeleton components use CSS animations and semantic ARIA labels for accessibility, with responsive breakpoints matching the actual device grid layout (1-4 columns based on screen size).
+> Both components include ARIA attributes (`role="status"` and `aria-label`) for screen reader accessibility during loading states.