Web integration

Integrating into web applications

For compatible web apps, start with the official @j3w1/ui 1.1.0 package or its complete copies. The theme also supports canonical role mapping when your application must retain another framework's controls.

Choose an integration route

Your app	Recommended starting point
Vue 3 JavaScript	Vue integration
Bundled HTML/JavaScript	Tokens + selected styles + browser registration + maintained native markup
React	Native JSX children, browser registration, refs for complex properties and imperative APIs
Astro	CSS in frontmatter, static native markup, registration in a browser script
No bundler	Complete copy distribution, served over HTTP
Existing framework-owned controls	Map canonical semantic roles into supported framework theme keys; document deviations

Common imports

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

Insert the full maintained example from examples/text-field.json or its component page. Custom Elements use light DOM; labels, native inputs, class names and ARIA references are part of composition. An empty wrapper is not a complete input.

Load token CSS once. Component CSS includes its dependency closure and is scoped to the custom tag. Load it after broad app resets; later global selectors can still interfere. Avoid multiple package versions in one document.

React integration

The supported guide targets React 19 Custom Elements behavior. Keep native JSX children, use defaultValue for an uncontrolled native input, and bind complex custom-element properties through a ref. Register in browser execution. Attach j3w1-* listeners with addEventListener when needed and remove them in effect cleanup. Read the event payload from detail and consult that component's API.

Do not assume a wrapper's property is React form state. Submit the actual native form and read FormData. Follow the application's SSR/client boundaries. Class imports from @j3w1/ui/components/* do not register elements; register/* belongs in the browser.

Astro integration

---
import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/button.css';
---
<j3w1-button id="example-action">
  <button class="button" type="button">
    <span class="button-loading" aria-hidden="true">⋯</span>
    <span class="button-label">Open settings</span>
  </button>
</j3w1-button>
<script>
  import '@j3w1/ui/register/button';
</script>

Registration is in the browser script, not server frontmatter. The example renders a button; wire your application's action explicitly. Essential labels/content remain in static HTML. Interactive behavior still needs JavaScript as documented by the component.

Plain HTML without a bundler

Generate a complete copy with the installed CLI and serve its index.html over HTTP. Incorporate element.html, tokens.css, component.css and the entire runtime closure into your own application. Do not point a bare browser import at @j3w1/ui/... without a bundler or suitable import resolution. Do not use file: URLs for the module workflow.

Existing frameworks and CSS-only mapping

Read exports/theme.compact.md, selected exports/components/<id>.json, and resolved tokens at one immutable revision. Use exports/tokens.css for canonical custom properties. Map semantic roles to the host's supported theme keys; do not invent values or replace the host's behavior merely to match a screenshot.

Token CSS alone does not supply all component markup, behavior or application layout. Preserve focus, contrast, keyboard interaction and form semantics. Record unsupported geometry or host limitations as deviations. Tokens, Accessibility and Agent integration explain the rules and lock record.

Framework-neutral form and lifecycle rules

• Boolean attributes are presence-based: disabled="false" is still disabled. Remove the attribute or set the supported property to false.
• Put arrays/objects into declared properties, not string attributes. Use only APIs documented for that component.
• Native input/change and documented custom events have different payloads. Canceling a reporting event does not necessarily undo a value change.
• Give repeated instances unique IDs and update label/ARIA references together.
• If a framework replaces the native children, call refresh() after the DOM update. Clean up application listeners and explicit enhancement roots on unmount.
• The application owns server operations, uploads, persistence, authentication and authorization.

Source: versioned web consumption guide. Next: Forms · Themed controls · Troubleshooting.