Package and copy

Package and complete-copy workflows

The three modes solve different integration problems. All use the same pinned design contract.

Mode	Use when	What you receive
package	Your web app can import @j3w1/ui	Selected implementation metadata, canonical contracts, examples and guidance; install the runtime package separately
copy	Your app should own the copied files	Complete markup, CSS, tokens, runtime closure and notices, plus kit guidance when using kit
mapping	Your host cannot use web components or already owns equivalent controls	Contracts and guidance for mapping semantic roles; no native application port is created

Install from Quick start first. These commands use the installed CLI and do not ask npx to fetch a registry package.

Package mode: load what your screen needs

import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/button.css';
import '@j3w1/ui/styles/dialog.css';
import '@j3w1/ui/register/button';
import '@j3w1/ui/register/dialog';

Per-component registration brings its required registrations; component CSS includes its style dependency closure. Load tokens once, place component styles after broad host resets, and preserve maintained markup and ARIA relationships.

@j3w1/ui/components/button exports the class without registration and supports SSR-safe imports. @j3w1/ui/register/button registers it in the browser. Do not register inside server execution. Use one package version per document. Reimporting the same registration is safe; an unrelated class occupying the tag name is a conflict.

The complete catalogue is available through @j3w1/ui/register and @j3w1/ui/styles.css. Prefer selected imports for a normal screen; the full catalogue is appropriate for a gallery.

Copy mode: take the complete closure

npx --no-install j3w1-ui copy dialog --out ./vendor/j3w1/dialog
npx --no-install j3w1-ui kit --components text-field,button,dialog --mode copy --framework vue --out ./vendor/j3w1/settings

A single component copy contains:

index.html          runnable standalone example
element.html        markup to incorporate into your app
component.css       component styles and dependencies
tokens.css          theme variables
runtime/            registration, implementation and shared chunks
manifest.json       file identities and canonical links
README.md           integration instructions
LICENSE.md          code and specimen notices

Keep these files together. Copying only element.html or one JavaScript entry loses required styling or behavior. Multi-component kits keep each requested bundle in its own directory; do not flatten identically named files.

Insert element.html, load tokens.css and component.css, and import runtime/register/<id>.js from the copied bundle. Resolve paths relative to where you serve it. Give every instance unique IDs and update for, aria-describedby, aria-controls and fragment references together. A standalone bundle needs HTTP hosting, not the documentation site or a backend.

What kit adds

npx --no-install j3w1-ui kit --components text-field,button,dialog --mode package --framework vue --out ./j3w1-package-task
npx --no-install j3w1-ui kit --components text-field,button,dialog --mode mapping --framework native --out ./j3w1-native-task

kit.json records requested IDs, framework, mode, version and implementation dependency metadata. canonical/ holds contracts; rules/ holds shared guidance; integration.md explains consumption. Package and mapping modes include selected examples/*.json. Copy mode carries actual complete bundles.

Framework labels are html, vue, react, astro and native. Native requires mapping mode. The flag supplies context; it does not convert Custom Elements into another framework's implementation or generate a complete app.

Package kits do not install dependencies. Mapping kits do not prove host compatibility. Copy kits do not wire a backend. Your application supplies those pieces.

Integrity and updates

The copy CLI checks packaged source bytes before writing, refuses unknown IDs and existing destinations, and rejects symlink destinations. Choose a new directory for an upgrade, review the diff, then incorporate the changes deliberately. Do not bypass an integrity or path check.

Keep the package lock for package use and bundle identities/notices for copy use. Preserve the canonical revision, pending decisions and deviations in either mode. theme.lock.json records canonical contract consumption; it is separate from the package manager's lockfile.

The older exports/recipes/ surface covers three maintained reference recipes. For official implementation copies of all 67 entries, use the package CLI and packages/ui/dist/copy/ described here.

Sources: public CLI, package exports, consumption guide.