# OpenSpec Change: enterprise-react-skeleton

- **Change ID**: enterprise-react-skeleton
- **Package**: `@suaveplan/react-skeleton`
- **Category**: react
- **Target path**: `react/ui/react-skeleton`
- **Status**: PROPOSED
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-skeleton.md`

---

## Summary

Deliver `@suaveplan/react-skeleton` on genesis from scratch at enterprise quality. Content loading skeleton / shimmer components: `Skeleton`, `SkeletonText`, `SkeletonAvatar`, `SkeletonCard`, `SkeletonTable`, and a headless `useSkeleton` hook. Every primitive has a per-subpath export for tree-shaking. Styles published as `./styles/skeleton.css`. Genesis adds a `useSkeleton` playground story, Playwright visual-regression snapshots, `prefers-reduced-motion` shimmer freeze, and 100% test coverage.

---

## Current-state audit (genesis)

Package does not exist on genesis — fresh build.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/react-translate` (`workspace:^`) | i18n for aria-labels |
| `zod` (`catalog:forms`) | Options schemas |

External: `clsx catalog:ui`, `tailwind-merge catalog:ui`, `tslib catalog:build`. React 18 peer.

---

## Preserved public API surface

### Components

`Skeleton`, `SkeletonText`, `SkeletonAvatar`, `SkeletonCard`, `SkeletonTable`

### Hooks

`useSkeleton`

### Types

`SkeletonAnimation`, `SkeletonProps`, `SkeletonAvatarProps`, `SkeletonAvatarShape`, `SkeletonAvatarSize`, `SkeletonCardProps`, `SkeletonTableProps`, `SkeletonTextProps`, `UseSkeletonOptions`, `UseSkeletonReturn`

---

## New additions for genesis

1. **`prefers-reduced-motion` freeze** — when reduced motion is detected, `animation: none` overrides the shimmer keyframe. Documented in CSS and tested.
2. **`useSkeleton` playground story** — exercises `isLoading` toggle, custom shape prop.
3. **Playwright visual-regression snapshots** — `e2e/skeleton.spec.ts` captures snapshots of every component in loading + loaded states.
4. **Zod `UseSkeletonOptionsSchema`** — validates hook options at runtime.

---

## File layout

```text
react/ui/react-skeleton/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    components/
      skeleton/ (tsx + types + md + test + stories + index)
      skeleton-text/ (tsx + types + md + test + stories + index)
      skeleton-avatar/ (tsx + types + md + test + stories + index)
      skeleton-card/ (tsx + types + md + test + stories + index)
      skeleton-table/ (tsx + types + md + test + stories + index)
    hooks/
      use-skeleton/ (ts + types + md + test + stories + index)
    utils/
      cn.ts
    styles/
      skeleton.css
  e2e/
    skeleton.spec.ts
```