@doow/skeleton-ui

Internal Doow package for React/Next-first, structure-aware loading skeletons.

Source repository: Doow-Dev/doow-skeleton-ui

Problem

Doow apps need loading states that preserve the final layout without maintaining
parallel hand-written skeleton markup for common UI surfaces such as cards,
lists, tables, forms, dashboards, and other structured application views.
@doow/skeleton-ui renders placeholder-safe children,
measures their real DOM structure in a client boundary, and overlays tokenized
skeleton blocks.

When To Use

Use this package for loading UI where the final layout is known and placeholder-safe data can render the real component tree. Good targets include cards, lists, tables, forms, dashboard panels, and responsive summaries.

When Not To Use

Use a spinner, progress indicator, or status message instead when work duration is unknown, the user is submitting or deleting data, the final layout is not known, or placeholder data would be misleading.

Install And Setup

pnpm add @doow/skeleton-ui

In a Next.js App Router root layout or app-level stylesheet entry:

import "@doow/skeleton-ui/skeleton.css";
import "@doow/skeleton-ui/ssr.css";

skeleton.css styles hydrated overlays. ssr.css hides placeholder-safe child content before hydration and provides the runtime marker used for development warnings.

Current Public API

import {
  Skeleton,
  createSkeletonId,
  createSkeletonRows,
  createSkeletonText,
} from "@doow/skeleton-ui/react";
import "@doow/skeleton-ui/skeleton.css";
import "@doow/skeleton-ui/ssr.css";

const skeletonUsers = createSkeletonRows((index) => ({
  id: createSkeletonId("user", index),
  name: createSkeletonText("md"),
}), 3);

<Skeleton loading={loading} preset="card">
  <UserCard user={user ?? skeletonUsers[0]} />
</Skeleton>;

The default API remains React/Next-first. Raw Web Component usage is not planned as the normal Doow engineer experience.

Entry Points And Version Support

• @doow/skeleton-ui/react: primary React client API.
• @doow/skeleton-ui/next: alpha Next.js entry for Next >=16.2.4; it currently re-exports the React API and may gain Next-specific helpers later.
• @doow/skeleton-ui/core: advanced framework-free measurement and overlay model APIs.
• @doow/skeleton-ui/testing: alpha testing entry point; currently exposes package status metadata only.

Presets

Presets are generic defaults for measurement limits, count gaps, and debug names: card, list, table, form, and dashboard. Explicit props always win over preset defaults.

SkeletonTable remains table-library agnostic. It is not coupled to TanStack Table, AG Grid, doow-client internals, or route-specific row models.

Escape Hatches

Use Doow-owned data attributes only when natural measurement is not enough: data-doow-skeleton-ignore, data-doow-skeleton-box, data-doow-skeleton-measure-children, data-doow-skeleton-width, data-doow-skeleton-height, and data-doow-skeleton-radius.

Accessibility

While loading, the root uses aria-busy, child placeholder content is hidden from assistive technology and interaction, and the overlay is aria-hidden. loadingLabel is quiet by default and does not create repeated live announcements during resize or mutation remeasurement.

Design Tokens

Skeleton colors and radii use Doow CSS variables with fallbacks. The current mapping is provisional until doow-client validation confirms light and dark fit across the selected real targets.

Performance And Debugging

Measurements are rounded, compared before state updates, and scheduled through a debounced frame boundary. Development warnings are deduplicated per component instance and cover missing SSR CSS, zero blocks, expensive measurement, high block counts, maxBlocks, maxDepth, and continuously changing layouts. Use debug and onMeasure during local validation, not as product UI.

Storybook

Run:

pnpm storybook

Required examples live under Skeleton/Card, Skeleton/List, Skeleton/Table, Skeleton/Form, Skeleton/Dashboard, Skeleton/Responsive, Skeleton/DarkMode, Skeleton/ReducedMotion, Skeleton/EscapeHatches, and Skeleton/PerformanceDebug.

Validation And Publishing

doow-client is the first validation target. Keep validation scoped to limited proof-of-integration examples or targeted replacements for the license plan table, renewals calendar, and dashboard metric card. Do not broadly migrate handwritten skeletons yet.

Private npm publishing should be gated on build output, Storybook examples, SSR behavior, hydration, light/dark token fit, reduced motion, and no noisy warnings.

Migration Path

Migration from handwritten skeletons is future work. The expected path is small targeted replacements first, documentation of gaps, then broader migration only after the generic abstraction proves itself in real Doow UI.

Attribution

Portions of the skeleton measurement implementation are adapted from phantom-ui by Aejkatappaja, licensed under MIT.

Local Commands

pnpm install
pnpm typecheck
pnpm build
pnpm test
pnpm storybook

Documentation

• API surface
• Usage guide
• Adoption guide
• Anti-patterns
• Setup checklist

These links intentionally point to GitHub so they work from npmjs.com and from the published package README. The same files are also included in the npm tarball for offline reference.