ICU UI Kit Demo

A Preact gallery for ICU UI Kit controls, theme tokens, notifications, and loading skeletons. The Bones section compares build and runtime capture and provides controls for animations, transitions, capture policy, and cache behavior.

Build And Run

Requires npm 12.2.0 with Node 22.22.2+ in the Node 22 line, Node 24.15.0+ in the Node 24 line, or Node 26+. Git is required to install the tag-pinned UI kit dependency declared in package.json.

From the repository root:

npm ci
npm run typecheck
npm run build:dist
npm start

The production server serves dist/ at http://localhost:3000 by default. HOST defaults to 0.0.0.0; PORT defaults to 3000. npm run dev starts Vite for development, and npm run preview serves a Vite build locally.

The project .npmrc disables install-time lifecycle scripts and permits only directly declared Git dependencies. The installed kit must contain built exports and support the APIs used by this checkout. For unreleased kit changes, use a matching local build as described below before building the demo.

Choose A Kit Build

The installed package is used by default, including with ICU_KIT=dist. ICU_KIT=source selects a sibling icu-ui-kit checkout when its source stylesheet exists; otherwise it falls back to the installed package.

ICU_KIT_PATH selects an explicit local kit directory. With ICU_KIT=source, its source must exist. Otherwise, the demo aliases the Preact, core, and style imports to that directory's dist/.

ICU_KIT_PATH=../icu-ui-kit ICU_KIT=source npm run dev
ICU_KIT_PATH=../icu-ui-kit ICU_KIT=dist npm run build

Build the local kit first when selecting dist/. The Vite plugin, devtools imports, and TypeScript declarations still resolve from the installed package, so that package must also match the APIs being previewed. An explicit path does not replace every package subpath. Keep production builds on the released, lockfile-pinned package.

Preview Skeletons

Open /#bones to compare all nine animation styles with build and runtime capture. The bundled Inter font provides consistent comparison geometry; the System Font control demonstrates font-dependent widths and wrapping. Both methods use the same text-height normalization and paragraph shapes. The bundled font is covered by public/fonts/Inter-LICENSE.txt.

BonesBoundary, withBones, BoneSuspense, named lazy sheets, and the structural inspector demonstrate integration. hasData retains available content during refresh. The canvas example combines a captured header with a separately owned runtime region and pauses measurement during resizing. Clear Runtime Cache discards cached geometry and refreshes active captures.

Use one skeleton owner per region. Build capture is the default; use runtime capture for content whose geometry cannot be known ahead of time. Runtime measurement requires mounted presentation content or a captured fallback. Keep persistent controls outside the hidden region. Private layout geometry should use memory, with caches cleared when identity changes.

Capture And Verify

bones.config.json defines fixture URLs, responsive profiles, output sheets, CSS, and a lazy registry. Fixtures render real presentation components with synthetic data and wait for the bundled font.

Configure BROWSERLESS_URL and BROWSERLESS_TOKEN for Browserless v2. Set BONES_ORIGIN to an origin that the service can reach, and use the default root asset prefix (BASE_PATH=/) for capture:

npm run bones
npm run bones:check

Both commands rebuild and temporarily serve the demo on port 4173; that port must be free. The default origin is http://127.0.0.1:4173, which works only when Browserless can reach that address. The wrapper uses a sibling icu-ui-kit/scripts/icu-bones.mjs if present, otherwise the installed kit's CLI. ICU_KIT_PATH does not select this CLI.

Capture writes generated JSON, CSS, and the registry. Rebuild afterward to include new captures in the served bundle. Check compares regenerated outputs and validates rendered build/runtime geometry. Do not edit captured rectangles manually.

For automatic recapture with the Vite development server, set BONES_WATCH=1 and a reachable BONES_ORIGIN. Keep the same Browserless credentials configured. Generated outputs are excluded from the watch queue.

npm run verify builds and checks the gallery in Chromium; use CHROME_PATH to select an executable. npm run verify:dist selects installed kit exports for the build and verification. These checks require a local Chromium browser and a root-prefix build (BASE_PATH=/); capture and geometry checks use Browserless separately.

Serve Under A Path Prefix

BASE_PATH is a build-time asset prefix, defaulting to /. For example, BASE_PATH=/ui-kit/ npm run build:dist builds assets for that prefix. Keep the trailing slash on the asset prefix; page links use the slashless entry. A shared-host proxy must route both /ui-kit and /ui-kit/ assets to the service and strip the prefix before forwarding file paths.

Dockerfile builds with a frozen install and defaults to BASE_PATH=/ui-kit/. Its runtime serves on port 3000. Override the build argument for a different asset prefix. nixpacks.toml also uses a frozen install and runs the same static server.

The server gives hashed assets/ files immutable caching and sends other files with no-cache. Missing paths return the application HTML, so it should be routed only within the demo's assigned prefix.

License

MIT — see LICENSE.