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 · 4.0.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.

Markup

<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@4.0.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@4.0.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

Specimen density

Specimen profile

Field `field`

Family: Basic forms
Maturity: stable
Priority: R1
Since: 0.1.0
Native control: native <label for> with aria-describedby on the control — APG pattern
specified
demonstrated

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.

Report an issue with this component

Tokens

Focus a role to inspect its values; follow its link for persistent usage and source details.

Part	Role	Value	Use
`root.text`	`color.text.default`approveduse	`#e99499`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`label.text`	`color.text.bright`approveduse	`#ffa2a7`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`label.required-mark`	`color.status.danger.text`observeduse	`#f07178`	D-041 readable error text on neutral surfaces and native warning tints.
`control.bg`	`color.surface.input`approveduse	`#000000`	Form-control fill.
`control.border`	`color.border.control`approveduse	`#c81a1a`	D-041 owner correction: red control and floating-frame borders, distinct from rose text.
`control.border-invalid`	`color.status.danger.border`observeduse	`#e53935`	Danger border, 2px on invalid inputs.
`control.text-disabled`	`color.text.disabled`approveduse	`#a3676b`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`control.bg-disabled`	`color.interaction.disabled.bg`approveduse	`#0d0707`	D-041 interaction.disabled.bg: color.primitive.modern.panel.
`control.border-disabled`	`color.border.disabled`approveduse	`#482b2b`	D-041 border.disabled: color.primitive.modern.divider.
`help.text`	`color.text.muted`approveduse	`#d4868b`	D-041 owner correction: rose is the default UI and reading foreground; near-white is reserved for document headings, highlights and contrast-critical fills.
`message.text`	`color.status.danger.text`observeduse	`#f07178`	D-041 readable error text on neutral surfaces and native warning tints.

State matrix

Every declared state and combination, statically rendered; the default cell is live. Sizes: compact, comfortable (switch with the density control above).

State	Default
`default`	Host name required Letters, digits and hyphens; shown in the bar. ✕ Hyphens cannot start or end the name.
`required`
`invalid`
`disabled`

Purpose

Gives every control the same label, description and error treatment: the control specifies its box, the field what sits above and below it and how they are linked. Every form control renders inside a field or a fieldset.

Anatomy

Parts as listed in the anatomy.

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`, 1px `color.border.disabled`; help unchanged	`disabled`; cursor: not-allowed

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

Keyboard

Adds no behaviour; clicking the label focuses the control (native for).

Accessibility

Every control has a programmatic label; placeholder text is never the label. The message keeps its glyph, so the state is not colour-only. Text meets 4.5:1; disabled text is exempt, with a house floor of 3:1.

Portability

No pseudo-elements: the required 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 left of the control. Placeholder as the only label. An error shown by a red border alone. A message that replaces the help in the DOM. A colour-only required mark. An asterisk with no text alternative. Two controls in one field.

Contrast report

8 declared pairs measured on resolved sRGB values with the WCAG 2.x formula; 0 waived (decorative only), 0 failing. A pass is a design target for the named role, not an application-wide conformance claim.

Pair	State	Kind	Foreground	Background	Ratio	Min	Result
field default text	default	text	`color.text.bright` `#ffa2a7`	`color.surface.default` `#0d0707`	10.45	4.5	pass
field required text	required	text	`color.status.danger.text` `#f07178`	`color.surface.default` `#0d0707`	6.98	4.5	pass
field invalid text	invalid	text	`color.status.danger.text` `#f07178`	`color.surface.default` `#0d0707`	6.98	4.5	pass
help text on the panel surface	—	text	`color.text.muted` `#d4868b`	`color.surface.default` `#0d0707`	7.22	4.5	pass
help text on the canvas	—	text	`color.text.muted` `#d4868b`	`color.surface.canvas` `#000000`	7.58	4.5	pass
disabled label (exempt; house floor 3:1)	disabled	ui	`color.text.disabled` `#a3676b`	`color.surface.default` `#0d0707`	4.48	3	pass
disabled control text (exempt; house floor 3:1)	disabled	ui	`color.text.disabled` `#a3676b`	`color.interaction.disabled.bg` `#0d0707`	4.48	3	pass
disabled border (exempt)	disabled	ui	`color.border.disabled` `#482b2b`	`color.interaction.disabled.bg` `#0d0707`	1.58	1	pass

Keys

Key	Action
`Tab / Shift+Tab`	Reaches the control; the label is not a tab stop.

For agents

Component JSON ·Implementation brief ·Build a task kit ·

Stress fixtures: FX-LONG FX-320 FX-ZOOM-200 FX-I18N FX-RTL FX-RM FX-HC FX-DENSITY FX-STATE-MATRIX

j3w1 / theme

j3w1 / command

Field

Live variants

default

Install and register

Copy the complete implementation

Public API

attributes

properties

methods

events

Dependencies and verification

Canonical specification

Field `field`

Tokens

State matrix

Purpose

Anatomy

States

Keyboard

Accessibility

Portability

Non-examples

Contrast report

Keys

For agents

Live variants

default

Install and register

Copy the complete implementation

Public API

attributes

properties

methods

events

Dependencies and verification

Canonical specification

Field field

Tokens

State matrix

Purpose

Anatomy

States

Keyboard

Accessibility

Portability

Non-examples

Contrast report

Keys

For agents

Field `field`