Quick start

Quick start

Install v1.1.0, see a working component, then integrate it into your application. Node 24 or newer is required for the package CLI. The web runtime uses Custom Elements and ES modules. See Verification for tested environments.

1. Install from the release

In an existing npm project:

npm install --save-exact https://github.com/j3w1/theme/releases/download/v1.1.0/j3w1-ui-1.1.0.tgz

Keep package.json and your package-manager lockfile. They record the archive dependency and its integrity. This is a package installation, not a live import from the documentation website.

For explicit pre-install verification, download j3w1-ui-1.1.0.tgz and release.json from the same release. Put them in one directory, save this as verify-release.mjs there, and run it:

import { readFile } from 'node:fs/promises';
import { createHash } from 'node:crypto';

const manifest = JSON.parse(await readFile('release.json', 'utf8'));
if (manifest.name !== '@j3w1/ui' || manifest.version !== '1.1.0' ||
    manifest.file !== 'j3w1-ui-1.1.0.tgz') {
  throw new Error('Unexpected release identity');
}
const bytes = await readFile('j3w1-ui-1.1.0.tgz');
const actual = 'sha256-' + createHash('sha256').update(bytes).digest('base64');
if (actual !== manifest.sha256 || bytes.length !== manifest.bytes) {
  throw new Error('Release archive does not match release.json');
}
console.log('Release identity, length and SHA-256 match.');

node verify-release.mjs
npm install --save-exact ./j3w1-ui-1.1.0.tgz

A hash match proves agreement with the downloaded manifest; it does not replace choosing the trusted release source. Registry installation is an alternative only after the exact version is actually published to npm.

2. Discover what is installed

npx --no-install j3w1-ui list

The output lists component IDs and imports. Pick a small first task, such as text-field, button and dialog. Components lists all 67 entries and where their APIs and examples live.

3. Open a complete example

npx --no-install j3w1-ui copy text-field --out ./j3w1-preview

Serve j3w1-preview with your existing local HTTP server and open its index.html. For example, if Python 3 is installed:

python -m http.server 8080 --bind 127.0.0.1 --directory ./j3w1-preview

Open http://127.0.0.1:8080/. ES modules must be served over HTTP; double-clicking an HTML file is not the supported workflow. The CLI refuses an existing output directory, so choose a new directory for another copy.

4. Use the component in your application

For a bundler-based browser entry:

import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/text-field.css';
import '@j3w1/ui/register/text-field';

Insert maintained markup from node_modules/@j3w1/ui/dist/examples/text-field.json, the generated element.html, or the component page. An empty <j3w1-text-field> does not create a label or input. Preserve native children and canonical classes; make IDs unique when reusing an example.

Use Vue integration for a complete SFC, or Web integration for HTML, React and Astro placement rules.

5. Give an agent a bounded kit

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

Read kit.json, selected examples, canonical/, rules/ and integration.md. Package mode produces integration instructions and contracts, not another copy of the installed runtime. Use --mode copy for complete source bundles. See Package and copy and Agent prompts.

6. Verify your integration

Check labels, keyboard focus, required fields, successful FormData, reset, disabled states and narrow layout in your actual app. If you use a dialog, test Escape and focus return. Keep the exact package identity and theme revision alongside any unsupported mappings or deviations. See Verification.

Next: Vue integration · Themed controls · Troubleshooting.