Agent integration

How agents should consume j3w1/theme

Select, install or copy, incorporate and verify the components your application needs. Do not reconstruct the theme from screenshots or scrape an entire documentation site to build one form.

The authoritative protocol is agents/consume.md at v1.1.0. The consuming application's instructions and architecture take precedence. This wiki explains the workflow; it does not override the target project.

The end-to-end workflow

1. Inspect the app. Identify framework, build, existing components, form behavior, accessibility rules and the authorized scope.
2. Pin the theme. Use v1.1.0 consistently and resolve its full commit. See Versioning. Do not combine files from different revisions.
3. Read the manifest and consumer protocol, then the compact design rules and implementation index listed below.
4. Choose a mode. Prefer package imports for compatible web apps; choose complete copies for source ownership, or mapping for an incompatible host. Reuse a provided component instead of rebuilding it from its appearance.
5. Select only the components needed. Read their contracts, examples and APIs, including dependencies and pending-decision disclosures.
6. Integrate into the app. Keep native names, labels and form ownership. Bind state with supported properties/events. Preserve application-owned backend, authentication and authorization behavior.
7. Verify and report. Exercise the real screen, keep package/archive identity and the canonical lock, and report deviations and checks that did not run.

Exact, bounded reading set

Fetch these from the same immutable revision:

Path	Purpose
theme.json	Version, profiles, entry points and pin policy
agents/consume.md	Consumption rules, eligibility, lock and deviation protocol
exports/theme.compact.md	Shared design rules in compact form
packages/ui/dist/index.json	Component IDs, maturity, contract and example paths
packages/ui/dist/contracts/<id>.json	Selected implementation API and mapping
packages/ui/dist/examples/<id>.json	Maintained complete variant markup
exports/components/<id>.json	Canonical behavior, states, roles and eligibility
exports/tokens.resolved.json	Additional alias resolution only when needed
exports/digests.json	Canonical export hashes to record

Use this base:

https://raw.githubusercontent.com/j3w1/theme/v1.1.0/

Start with these actual URLs:

• Manifest
• Consumer protocol
• Compact rules
• Implementation index
• Text-field API
• Text-field examples
• Text-field canonical contract

The package manifest contains detailed import and copy identities; read it when needed. The smaller index is sufficient for initial discovery. The portal is for visual confirmation. Its DOM, screenshots and this wiki are not sources from which to invent token values.

Install and prepare a selected task

npm install --save-exact https://github.com/j3w1/theme/releases/download/v1.1.0/j3w1-ui-1.1.0.tgz
npx --no-install j3w1-ui kit --components text-field,button,dialog --mode package --framework vue --out ./j3w1-task

Read kit.json, canonical/, rules/, integration.md and selected examples. The CLI writes a kit; it does not launch an agent, create a whole app or modify existing application files.

For complete source ownership:

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

Incorporate the bundles into the app, preserving complete runtime/CSS dependencies and notices. Use unique IDs with matching label and ARIA references. For an incompatible native host, use --mode mapping --framework native and map the canonical roles to supported host keys. See Package and copy for the exact outputs.

The agent picker helps a person compose the same choices. Agents can use the pinned index and CLI directly.

Example task: project settings in Vue

For a screen with a name field, status choice and confirmation dialog, evaluate text-field, select, button and dialog. Read those APIs and examples, generate a package or copy kit, configure Vue to recognize j3w1-*, and keep Vue's value bindings on the native inputs. Use the themed choice renderer instead of a separate application-specific dropdown.

The maintained markup, not an empty custom tag, supplies labels and inputs. The application supplies the save operation and validation rules. The Vue guide provides a complete small form, and Themed controls shows the supported enhancement for existing markup.

Configure a consumer repository once

After checking compatibility with that repository's rules, add a scoped instruction such as:

For UI surfaces assigned to j3w1/theme:
- Use v1.1.0 and the approved default profile.
- Read https://raw.githubusercontent.com/j3w1/theme/v1.1.0/agents/consume.md.
- Prefer the official package from its pinned release archive, or use its
  complete copy bundles when this repository requires source ownership.
- Read selected contracts, examples and dependencies instead of scraping pages.
- Preserve this repository's framework, behavior, security and accessibility.
- Record the canonical revision, package identity, pending decisions and deviations.
- Verify the integrated form, keyboard, focus, responsive and lifecycle behavior.

Do not import the theme repository's contributor AGENTS.md as the rules for a consuming app. It governs changing the theme itself.

What the agent should leave behind

Deliverable	What to record
Working application integration	Actual imports or complete copies, maintained markup, state/event bindings and app behavior
Package or copy identity	Exact archive dependency and package lock, or copied bundle manifests and notices
Canonical lock	Real revision, selected export digests, components, profile and deviations in theme.lock.json
Implementation report	Selected IDs/variants, framework/mode, pending decision IDs, unsupported surfaces and actual checks

Follow the lock schema and pinned protocol. Record real digests and the full commit; illustrative hashes are not a finished lock. kit.json is not a replacement for the canonical lock or package manager lockfile.

Report the consumer integration as implemented with evidence and deviations. Do not promote a profile, invent colors, omit use-and-report disclosures, or claim certification because an upstream package check passed. Check the integrated app's form values/reset, disabled states, keyboard navigation, focus return, responsive layout and lifecycle. List unavailable checks separately.

Next: Copyable agent prompts · Vue integration · Verification.