# Skeleton

Package: @commenda/pathfinder@0.1.0
Page: /docs/components/skeleton
Figma: https://www.figma.com/design/dn7BkGYEfIyP0o2zfesfVh/The-System?node-id=262-2

```tsx
import { SkeletonGroup, SkeletonText } from '@commenda/pathfinder/skeleton';
<SkeletonGroup label="Loading filings">
  <SkeletonText />
</SkeletonGroup>;
```


## Installation [#installation]

```sh
pnpm --filter your-app add "@commenda/pathfinder@workspace:*"
```

Import `@commenda/pathfinder/styles.css` once after host CSS. Styles are precompiled with Tailwind v4; consumers need no Tailwind scanning. Interactive callbacks belong in client components in Next.js App Router.

## Usage [#usage]

```tsx
import { SkeletonGroup, SkeletonText } from '@commenda/pathfinder/skeleton';
<SkeletonGroup label="Loading filings">
  <SkeletonText />
</SkeletonGroup>;
```

## API reference [#api-reference]

| Prop | Type | Requirement | Behavior |
| --- | --- | --- | --- |
| `shape` | `"circle" \| "text" \| "block"` | optional | text |
| `width` | `Property.Width<string \| number>` | optional | Match incoming content |
| `height` | `Property.Height<string \| number>` | optional | Match incoming content |
| `animate` | `boolean` | optional | true; reduced motion is static |
| `className` | `string` | optional | Additional classes for the component root. |

The application owns the 300 ms delay to avoid flashes. After about 10 seconds, offer meaningful progress or recovery; never fabricate a percentage. Render stable headers, filters and buttons immediately. Match the content layout and show 5–8 list rows. Group placeholders into one loading region; each shape is decorative.

## Examples [#examples]

### Shapes [#shapes]


```tsx
<SkeletonGroup label="Loading shapes example">
  <Skeleton />
  <Skeleton shape="circle" />
  <Skeleton shape="block" />
</SkeletonGroup>;
```


### List [#list]


```tsx
<SkeletonGroup label="Loading list example">
  {Array.from({ length: 5 }, (_, index) => (
    <SkeletonListRow key={index} />
  ))}
</SkeletonGroup>;
```


### Card [#card]


```tsx
<SkeletonGroup label="Loading card example">
  <SkeletonCard />
</SkeletonGroup>;
```


### Static [#static]


```tsx
<SkeletonGroup label="Loading static example" animate={false}>
  <SkeletonText />
</SkeletonGroup>;
```


Read the [design guidance](/docs/components/skeleton#design-rules) before using these components.

## Design rules [#design-rules]

Figma guidance and reviewed implementation decisions for this component. Rule IDs remain stable for source comments and AI references.

### Skeleton — 262:2 [#skeleton--2622]

- **SKELETON-01:** Match the arriving layout, including row height, columns, padding and card frames. Skeleton content, never stable headers, filters, tabs or buttons. Do not skeleton menus, toasts or dialog shells; loading content inside a dialog may use it.
- **SKELETON-02:** One named loading region with decorative shapes. Show 5–8 list rows. Use one synchronized 1.5-second linear shimmer phase for shapes mounted together; reduced motion stays still.
- **SKELETON-03:** Applications delay presentation by 300 ms to avoid flashes. After about 10 seconds, provide progress or useful recovery. Never invent a known percentage; unknown task length uses indeterminate Progress. Single controls use their own loading indicator.
- **SKELETON-04:** Pearl 200; text height 10/radius 4, block radius 6, circle full. Text preset widths 100/92/64%, gap 8. List row: 32 px avatar, 10 px name, 8 px metadata, gap 8, trailing value width 48; padding 12/16 and gap 12. Card: white, 0.5 px border, radius 12, padding/gaps 16, header icon 24, two text lines, optional media height 120, two footer placeholders.