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

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

File layout

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

2.7 KiB Raw Blame History