J3W1 / DESIGN SYSTEM

Field

The label, control, help and message wrapper that every form control sits in; it fixes the stacking order, the required mark, the description links and the invalid message.

stable · LIGHT DOM · 1.1.0

Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.

Standalone example ↗Copy file manifest Canonical JSON Vue gallery ↗Prepare an agent kit →

Live variants

default

Host name

Letters, digits and hyphens; shown in the bar.

✕ Hyphens cannot start or end the name.

<j3w1-field id="example-field-default"><div class="field">
  <label class="field-label" for="example-field-default-fd-host">Host name <span class="field-required" aria-hidden="true">*</span><span class="field-required sr-only"> required</span></label>
  <div class="field-control">
    <input class="field-input" id="example-field-default-fd-host" type="text" value="workstation" aria-describedby="example-field-default-fd-host-help example-field-default-fd-host-message" name="example-field-default-fd-host">
  </div>
  <p class="field-help" id="example-field-default-fd-host-help">Letters, digits and hyphens; shown in the bar.</p>
  <p class="field-message" id="example-field-default-fd-host-message">✕ Hyphens cannot start or end the name.</p>
</div></j3w1-field>

Install and register

Use the exact version. If npm publication is pending, install the release tarball from the installation guide.

npm install --save-exact @j3w1/ui@1.1.0

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

Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.

Vue SFC, React, Astro and plain HTML integration →

Copy the complete implementation

npx --package=@j3w1/ui@1.1.0 j3w1-ui copy field --out ./vendor/j3w1/field

The CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.

Public API

attributes

Name	Type / signature	Meaning
`disabled`	`CustomEvent`	Disable the native controls owned by this instance.
`loading`	`CustomEvent`	Mark the primary control busy and prevent duplicate activation.

properties

Name	Type / signature	Meaning
`disabled`	`boolean`	Delegates disabled state to native children.
`name`	`string`	Native control name; application form keys remain explicit.

methods

Name	Type / signature	Meaning
`refresh`	`(): void`	Reconnect behavior after replacing native child structure.
`focus`	`(options?: FocusOptions): void`	Focus the first usable native control.

events

Name	Type / signature	Meaning

Dependencies and verification

Registered components: none. Style dependencies: none.

Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.

Full implementation manifest, API and token dependency closure

Canonical specification

Purpose

The wrapper that gives every control the same label, description and error treatment. Controls specify their box; the field specifies what sits above and below it and how they are linked. Every form control in this theme is rendered inside a field or a fieldset.

Anatomy

Label above the control, always stacked; the control slot; help text below in color.text.muted; the validation message, which takes the help slot visually while help stays in the DOM and aria-describedby lists both. The required mark is present in the markup and shown only when the control is required.

States

State	Visual	Non-colour channel
default	label `color.text.bright`; help `color.text.muted`; control as its own component	—
required	`*` after the label in `color.status.danger.text` plus visually hidden “required”	`required` attribute; the mark
invalid	the control’s 2px `color.status.danger.border`; message with the ✕ glyph in `color.status.danger.text`; help visually hidden	border width 1 → 2px; glyph; `aria-invalid`
disabled	label and control text `color.text.disabled`; control `color.interaction.disabled.bg` with 1px `color.border.disabled`; help unchanged	`disabled`; cursor: not-allowed

Precedence: disabled > invalid; required is shown in every state.

Keyboard

The field adds no behaviour. Clicking the label focuses the control (native for). Focus order inside the field is the control’s own.

Accessibility

Every control has a programmatic label; placeholder text is never the label. Help and message are linked with aria-describedby in that order so the description is read before the error. aria-invalid="true" is set only after interaction or submit. The message keeps its glyph so the state is not colour-only. Contrast: label 10.10:1, help 5.66:1, message 5.26:1 on the panel surface; disabled label 3.24:1 (exempt).

Portability

Plain block layout; the only pseudo-element is nothing, the mark is real markup. Hosts without aria-describedby put help and message in the control’s tooltip or accessible description and record it.

Non-examples

A floating label inside the control. A label to the left of the control. Placeholder text as the only label. An error shown by a red border alone. A message that replaces the help text in the DOM. A required mark that is only a colour change. An asterisk with no text alternative. Two controls in one field.