Color field

Overview

link

Web

tanrei-color-field

schedule

SwiftUI

TanreiColorField

radio_button_unchecked

Jetpack Compose

TanreiColorField

radio_button_unchecked

Flutter

TanreiColorField

radio_button_unchecked

React Native

ColorField

radio_button_unchecked

Variants not shipped in

tanrei: filled, outlined

Generated from docs/status/status.json, specs/color-field.spec.json

A color field with a picker button, and one whose color the product refuses

Use a color field where people set a color as a value: a brand color in a theme, the color of a label or a category. They read it, type it or paste it from another tool, and see a sample of it beside the text. The field is drawn and measured as the text field of the same variant and size.

Built from a field and a color input. The field is the frame: the label, the required or optional mark, the help and the error. The color input is the control: the box, the swatch, the value as text and the picker button. The color field draws nothing of its own and has no token: every property it has is a property of one of the two, given to it unchanged.

It is a block as wide as the place it is put in, and its box fills it. It has no width of its own: for a narrower field, give it a narrower place. It is a field already, so it is never placed inside a field.

It draws no picker of its own. With picker, a button at the end asks for one: the browser’s, or a surface the product presents.

On the web it is <tanrei-color-field>. The other platforms have not implemented it yet.

Usage

link

value is a number sign and six hexadecimal digits in lowercase (#0f766e), or an empty string for no color. It is never a half-typed text: while the input holds something that is not a color, value is empty.

<form>
  <tanrei-color-field name="brand" label="Brand color" value="#0f766e"
    required required-text="Required"
    supporting-text="Six hexadecimal digits, like #0f766e."
    invalid-text="Enter six hexadecimal digits, like #0f766e."
    picker picker-label="Choose color"></tanrei-color-field>
</form>

<script type="module">
  import '@tanrei/web/components/color-field';

  const brand = document.querySelector('tanrei-color-field');
  // The value changed: a color, or an empty string. It is already the new one.
  brand.addEventListener('input', () => preview(brand.value));
  // The person committed a changed value: focus left, Enter, or the picker closed.
  brand.addEventListener('change', () => save(brand.value));
  // A text that is not a color was committed. The field keeps it and shows invalidText,
  // which is also what detail.message carries.
  brand.addEventListener('entryerror', (e) => console.log(e.detail.text, e.detail.message));
  // To present a picker of your own: cancel the request, open it, and set value to what was picked.
  brand.addEventListener('pickerrequest', (e) => {
    e.preventDefault();
    openMyPicker(e.detail.value).then((color) => (brand.value = color));
  });
</script>

import { ColorField } from '@tanrei/react';

<ColorField label="Brand color" value={brand} picker pickerLabel="Choose color"
  invalidText="Enter six hexadecimal digits, like #0f766e."
  onChange={(event) => setBrand(event.currentTarget.value)} />

One level down

link

The same field, written by hand from its two members, is the same picture, and to assistive technology the same text box with the same name, description and states:

<tanrei-field label="Brand color" required required-text="Required"
  supporting-text="Six hexadecimal digits, like #0f766e.">
  <tanrei-color-input name="brand" value="#0f766e"
    invalid-text="Enter six hexadecimal digits, like #0f766e."
    picker picker-label="Choose color"></tanrei-color-input>
</tanrei-field>

The same field written by hand: a field with a color input in it

Go one level down when you need an arrangement the color field does not offer:

You need	Use
A label, the box, help and an error	The color field
Something of your own inside the frame, beside or below the box	A field with a color input and your own element in it
The box alone, in a row or a column that already names the color: the tones of a palette, a cell of a table	The color input alone, named by its own label

What changes one level down is where things are said. name and value are on the color input, which is then the control the form meets, and its events are heard on it. label, error, disabled and the requirement stay on the field, which passes them to the control: do not set the input’s own. The color field does nothing that the field and the color input written by hand do not do.

Specs

link

An empty color field, white, black, a large one, a disabled one — and the box alone, a color input, in a row that names its color

The field

link

Part	What it is
Label	Above the container (stacked), where the field draws it, or floating inside it (filled, outlined), where the color input draws it. It is the accessible name, drawn or hidden with labelHidden
Requirement mark	After the label: the requirement tag in its required form, an asterisk or nothing for required; the requirement tag in its optional form for optional
Swatch	A sample of the value at the start of the container: a small square filled with exactly the value’s color, inside a hairline. Empty, it is the hairline alone. It is not a control
Input	The value as text. One line, which scrolls
Picker button	With picker: an icon-only text Button at the end, named by pickerLabel
Supporting text	A line of help, starting where the value’s text starts, after the swatch. While the field is in error the error text takes its place (below it, where the design system keeps both) — errorText while error is true, and invalidText while the committed text is not a color, or errorText where invalidText is empty

The three variants and the three sizes, small (32), medium (40) and large (56), are the text field’s. The default system ships stacked only. The swatch stands where a text field’s leading icon stands, at that icon’s size, so a color field under a text field with a leading icon shares its start edges.

Nothing is mixed into the swatch: no hover, no error tint, no shadow. A sample that changes under the pointer is a wrong sample. Disabled, its fill is drawn fainter and its edge is kept.

The value and the text

link

When	What happens
The person types, pastes or dictates	Nothing is refused or rewritten. The whole text is read: if it is a color, value is that color, otherwise empty. input fires when value changed
Focus leaves, or Enter	The text is committed. A color is rewritten in the value’s own form. change fires if the value differs from the last committed one
The committed text is not a color	The text stays. The field is in error and shows invalidText, and entryerror fires. The error ends at the next edit
The text is empty	value is empty. That is never an error of the field’s
The product sets value	The color is shown, whatever was typed. No event fires

A text reads as a color when, with the spaces around it left out, it is exactly six hexadecimal digits, in either case, with or without the number sign: 0F766E, #0f766e and #0F766E are all #0f766e.

Everything else is no color: three digits (#0f7), eight (#0f766e80), a name (teal), a functional notation (rgb(15, 118, 110)). Three digits are no color while a person types, because the text passes through them on the way to six; when the text is committed they are read as the six they stand for, as CSS reads them: #0f7 becomes #00ff77. There is no alpha and no wide-gamut color.

Nothing is reported while a person is still typing. An entry error is raised only when they commit.

The picker

link

With picker, the field shows a button at its end. Activating it fires pickerrequest, which carries the value.

The product	What happens
Does nothing	The field presents the browser’s own color picker. Each pick is an edit by the person: the text, the swatch, input. When the picker closes, change fires and focus is on the picker button
Cancels the request	The field presents nothing. The product opens its own surface, anchored to the field, and sets value to what was picked. That surface returns focus to the picker button when it closes

With the picker button shown, a press on the swatch opens the picker, as a press on the button does; focus does not move to the input, and the button stays the keyboard’s way. Without the button, a press on the swatch focuses the input, as a press anywhere else on the field does.

What each member gives

link

• From the field: the properties label, labelHidden, supportingText, errorText, error, disabled, required, optional, requiredMark, requiredText and optionalText; the slot label-icon; the tokens comp.field.*.
• From the color input: the properties variant, size, value, invalidText, picker and pickerLabel; the events input, change, pickerRequest and entryError; the tokens comp.input-box.* for the box, which every input box reads, and comp.color-input.* for the swatch.

The color input has a label, a labelHidden, an error and a disabled of its own. They are not what the color field sets: its label is the field’s, which names the input and, in a filled or an outlined field, is what floats in the box.

Tokens

link

The color field has no token of its own. Its box reads the color input’s tokens and its rows — the label, the mark, the help and the error — read the field’s tokens, wherever they are set. The table below lists the field’s. To change one instance, set a member’s token on it:

<tanrei-color-field label="Brand color"
  style="--tanrei-comp-field-label-gap: 12px"></tanrei-color-field>

Anatomy

Anatomy

Drawn over the fixture stacked-empty, as the web package draws it.

Part	Description
1 field	The Field: the label row with its glyph and its requirement mark, and the supporting row with the help and the error text. In a look whose input floats the label it draws no label row.
2 color-input	The color input, as the Field's one control: the box, the swatch, the value as text, the picker button, and the label that floats in the box in the looks that float one.

Properties

Property	Type	Default	Description
variant	stacked | filled | outlined	"stacked"	The text input's three looks, so that a color input is drawn as the text inputs beside it. Stacked is a filled box that shows focus and error with a line inside its edge and draws no label: the label of the Field that frames it stands above it. Filled and outlined float the label inside the box. Use one style per form. A design system may leave some out (the Tanrei system ships stacked only) or add values. — Color input
size	small | medium | large	"medium"	Minimum height of the container: stacked 32 / 40 / 56, as tall as a Button of the same size, so that the box and a Button side by side in one row stand as tall as each other; filled and outlined 40 / 48 / 56, which hold the label that floats inside them. These are the text input's three sizes, small for a bar, a toolbar or a dense row of controls. The hit area always meets the minimum target. A design system may add values. — Color input
value	string	""	The color the input holds: a number sign and six hexadecimal digits in lowercase ("#0f766e"), an opaque sRGB color; or empty for no color. It is never a half-typed text: while the input holds something that is not a color, value is empty. — Color input What the color field reports as its own is the value its color input holds, in that value's own form (CLF-43, CLI-16, CLI-21).
label	string	""	Names the control, visibly and to assistive technology. Required, unless the control names itself (a checkbox or a switch with its own label): then leave it empty and the field adds only help and an error. — Field Names the color input. In a filled or outlined look the input draws it, floating in its box, and the Field draws no label row (FLD-25, CLI-15).
labelHidden	boolean	false	Does not draw the label, which stays the accessible name. For a control whose visible label is elsewhere (a table column, a toolbar). — Field Hides the label wherever it would be drawn: the Field's row, or the input's floating label (FLD-25).
supportingText	string	""	Help shown below the control and given to assistive technology as the control's description. While the field is in error it gives way to errorText, unless the design system keeps both (comp.field.error-text.placement append). — Field
errorText	string	""	Shown while error is true, in supportingText's place — or below it, which then stays, where the design system's comp.field.error-text.placement is append: what is wrong and how to put it right, in words. — Field
error	boolean	false	Puts the field in the error condition: the error text is drawn, the control is exposed as invalid and, where it has an error condition of its own, drawn in it. What a value means is the product's to validate; the field never sets this itself. — Field The Field puts its color input in the input's own error condition (FLD-8, CLI-9).
disabled	boolean	false	Disables the control and draws the frame as disabled. Disable a framed control here, not on the control, so that its label follows. — Field The Field disables its color input, the picker button with it (FLD-14, CLI-31); the color field is then left out of its form (CLF-44).
required	boolean	false	What the form asks of the control: true exposes it as required and draws the required mark beside the label. It never validates: a missing answer is the product's to report with error. — Field The Field exposes its color input as required (FLD-10, CLI-11).
optional	boolean	false	Draws the optional tag after the label and adds optionalText to the control's description, because assistive technology has no state for it. Ignored while required is true: a control is never both. — Field
requiredMark	auto | tag | asterisk | none	"auto"	How this control shows that it is required: tag is a small filled Tag with requiredText, asterisk is "*" after the label, none draws nothing and keeps the semantics. Auto takes comp.field.requirement.mark, which follows sys.behavior.requirement-mark, the system's one answer. Ignored unless required is true. — Field
requiredText	string	""	The text of the required tag, in the product's language ("Required", "必須"). The product's: Tanrei has no word for it. Empty reads the product's words; with neither, FLD-24 says what is drawn. — Field
optionalText	string	""	The text of the optional tag, in the product's language ("Optional", "任意"); also read to assistive technology as part of the description. The product's: Tanrei has no word for it. Empty reads the product's words. — Field
invalidText	string	""	The words for an input committed with a text that is not a color ("Enter six hexadecimal digits, like #0f766e"), in the product's language: given to the Field that frames the input, which shows them as its error text (CLI-20). While it is empty that Field shows its own errorText. — Color input Shown by the Field, in its supporting row (FLD-28).
picker	boolean	false	Shows the picker button. Activated, it emits pickerRequest, and where the platform has a color picker of its own the input presents that picker unless the product cancelled the request. The input draws no picker surface itself. — Color input
pickerLabel	string	""	The accessible name of the picker button ("Choose color"). Required while picker is shown. — Color input

Slots

Slot	Description
label-icon	A glyph before the label. — Field

Events

Event	Description
input	The person changed the value — by an edit of the text that made it a color, another color or no color, or by a pick in the platform's picker; carries the new value. Not emitted when the product sets value, nor for an edit that leaves value as it was. — Color input
change	The person committed a changed value: focus left the input, the action key was pressed, or the platform's picker closed; carries the value. — Color input
pickerRequest	The person activated the picker button; carries the value. Cancelling it keeps the input from presenting the platform's picker: the product then presents its own surface and sets value to what was picked. — Color input
entryError	The person committed a text that is not empty and is not a color; carries the text as typed and invalidText, the words the input has for it (empty where the product gave none: the Field that frames the input then shows its own errorText). — Color input

States

Behavior

Requirements in EARS form. Every platform implementation is tested against these ids.

ID	Requirement
CLF-43	THE color field SHALL be a Field that frames one color input, and nothing else. It SHALL give label, labelHidden, supportingText, errorText, error, disabled, required, optional, requiredMark, requiredText and optionalText to its Field and variant, size, value, invalidText, picker and pickerLabel to its color input, each unchanged; SHALL hold the label-icon slot for its Field; and SHALL emit its color input's events as its own, each once. THE color field SHALL be as wide as the place it stands in, and its color input SHALL fill it: it is a block with no width of its own, as its Field is (FLD-1), around a control that fills the width it is given (CLI-44). Its value SHALL at every moment be the value its color input holds — a color in the value's own form, or the empty string (CLI-16) — and not the text the product set where the two differ (CLI-21). It SHALL draw no part of its own, hold no state of its own and have no token of its own: what it shows, how it behaves and what it exposes to assistive technology SHALL be exactly what that Field and that color input do when a product places the one in the other (FLD-1 to FLD-28; CLI-1 to CLI-44) — the label row and its requirement mark (FLD-2 to FLD-6), or the label that floats in the box with the Field's row left out (FLD-25, CLI-15, CLI-7); the supporting row, started at the value's text, after the swatch (FLD-7 to FLD-9, FLD-26, CLI-43); the name, the description and the states (FLD-10, FLD-11, FLD-14, CLI-11); and the entry error of a text that is not a color, shown in the Field's row (FLD-28, CLI-20).
CLF-44	WHERE the platform has forms (the web) THE color field SHALL be the one control the form sees: it SHALL take name, submit its color input's value, reset to the value it was first given, restore it on navigation, report to the form's constraint validation exactly what its color input would report there (CLI-11, CLI-20), and be left out WHILE disabled is true or a disabled group of the form holds it; its color input and its Field SHALL take no part in the form themselves. WHEN the action key asks for the form's submission (CLI-19) the form asked SHALL be the color field's own.
CLF-45	WHEN the color field is given focus — by the product, by a press on any part of it that FLD-12 or CLI-24 gives to the input, or by a form that reports its validity — THE color field SHALL pass the focus to the input of its color input, never to the picker button, and SHALL add no stop to the focus order: the stops inside it are its color input's, in that input's order (the input, then the picker button while it is shown, CLI-13). WHILE focus is anywhere inside it, the picker button included, THE color field SHALL count as focused for its Field, whose rows take their focused colors (FLD-13); the box takes its own only WHILE its input has focus (CLI-22). WHEN a picker the color input presented closes, focus SHALL be on the picker button (CLI-29), inside the color field.
CLF-46	IF the color field is placed in a Field THE color field SHALL in debug builds report that it is a field already and that the bare control is the color input, and both SHALL still render (FLD-15). WHILE it stands in a field group THE color field SHALL follow that group's disabled, through its own Field, and take nothing else from the group (FGR-20).
CLF-47	THE color field SHALL have no words of its own and SHALL read none: requiredText and optionalText are read by its Field (FLD-24), each from the instance's prop and then from the product's words; invalidText and pickerLabel are the instance's alone and are given to its color input as they are (CLI-42).
CLF-48	WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE color field SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on the element that carries its role — an id reference by the elements it names in the host's tree or a tree around it, an error message as part of the description while the color field is invalid — except those the color field owns (aria-label, aria-labelledby, aria-disabled), which it SHALL move and not expose: its name is label (CLF-43). WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE color field SHALL take it off that element. WHEN the product sets an aria- attribute the color field owns THE color field SHALL report it in debug builds.

Platform name mapping

Parity does not mean identical APIs. Each platform uses its own idiom for the same contract.

Spec	Web	SwiftUI	Jetpack Compose	Flutter	React Native
Component	tanrei-color-field	TanreiColorField	TanreiColorField	TanreiColorField	ColorField
variant · Property	variant	variant	variant	variant	variant
size · Property	size	size	size	size	size
value · Property	value	hex	value	controller	value
label · Property	label	label	label	labelText	label
labelHidden · Property	labelHidden	labelsHidden	labelHidden	labelHidden	labelHidden
supportingText · Property	supportingText	supportingText	supportingText	helperText	supportingText
errorText · Property	errorText	errorText	errorText	errorText	errorText
error · Property	error	error	isError	isError	error
disabled · Property	disabled	disabled	enabled	enabled	disabled
required · Property	required	isRequired	required	required	required
optional · Property	optional	isOptional	optional	optional	optional
requiredMark · Property	requiredMark	requiredMark	requiredMark	requiredMark	requiredMark
requiredText · Property	requiredText	requiredText	requiredText	requiredText	requiredText
optionalText · Property	optionalText	optionalText	optionalText	optionalText	optionalText
invalidText · Property	invalidText	invalidText	invalidText	invalidText	invalidText
picker · Property	picker	showsPicker	onPickerRequest	onPickerRequest	onPickerRequest
pickerLabel · Property	pickerLabel	pickerLabel	pickerContentDescription	pickerSemanticLabel	pickerAccessibilityLabel
input · Event	input	hex	onValueChange	onChanged	onValueChange
change · Event	change	onCommit	onCommit	onCommit	onEndEditing
pickerRequest · Event	pickerrequest	onPickerRequest	onPickerRequest	onPickerRequest	onPickerRequest
entryError · Event	entryerror	onEntryError	onEntryError	onEntryError	onEntryError
Notes	The tag tanrei-color-field, the class TanreiColorField, the React name ColorField. The element is composed as every composed element on the web is (the web package's README, Composed elements); what follows is what is particular to it. Members: <tanrei-field> holding one <tanrei-color-input> in its default slot; the product places none. The host is display: block. Value member: tanrei-color-input. The host is the form's element — name, the value and its state, validity anchored on the input, reset to the value attribute, restore, form, a disabled fieldset — and the input inside has no name. Props, set as properties on the member each is from. On the Field: label, labelHidden, supportingText, errorText, error, disabled, required, optional, requiredMark, requiredText, optionalText. On the color input: variant, size, value, invalidText, picker, pickerLabel. Attributes are the members' own, kebab-case: label-hidden, supporting-text, error-text, required-mark, required-text, optional-text, invalid-text, picker-label. Props of one name on both members — label, labelHidden, error, disabled — are the Field's; the input's are never set by the element and reach the input through the connection. Events: input, change, pickerrequest and entryerror are the color input's own composed events and leave by themselves, with the host as their target and value already new; pickerrequest stays cancelable from outside, and the input reads the result of its own dispatch before it opens the browser's picker. None is stopped and none is copied. Their detail types are the member's, re-exported: TanreiColorInputPickerRequestDetail, TanreiColorInputEntryErrorDetail. The color input changes a value the product sets without an event — it holds 0F766E as #0f766e, and a text that is not a color as empty (CLI-21) — so the host's value is the value member's at every moment, read back changed with no event (CLF-43). Slots: label-icon is passed to the Field by a slot element of the same name, rendered only while the host has a child for it. The element has no default slot. Parts: the member hosts are field and color-input. Exported from the Field: label, label-icon, requirement-label, supporting-text. Exported from the color input: container, outline, active-indicator, label, requirement-label, swatch, input, picker-button. Two names collide, label and requirement-label. Each is exported with its member's name before it, always (field-label, color-input-label, field-requirement-label, color-input-requirement-label), and under the bare name from both members as well, because the two are one thing to a person and are never drawn at once: FLD-25 is the sentence that holds it. Focus: the shadow root does not delegate. focus() and blur() call the color input's; a press on the label row focuses the input by FLD-12, a press on the box by CLI-24, and a press on the help does nothing. The browser's picker is opened by the color input from inside its own shadow root, in the user activation of the press on its picker button: two shadow roots deep, which showPicker() allows. The connection is the Field's with its control (FLD-25, FLD-26, FLD-28; CLI-43); the element takes no part in it. Parts and tokens of its own: none. The element writes no custom property: --tanrei-comp-field-*, --tanrei-comp-input-box-* and --tanrei-comp-color-input-* reach the members by inheritance, and one color field is set apart by setting any of them on the element. What its twin cannot do that it does: nothing. The twin: <tanrei-field label="Brand color" required supporting-text="Six hexadecimal digits, like #0f766e."><tanrei-color-input name="brand" value="#0f766e" picker picker-label="Choose color"></tanrei-color-input></tanrei-field>. Words: the element has none and reads none (CLF-47).	Not built on this platform yet: the color input as a view of its own and the color field as the Field around it, reading comp.input-box, comp.color-input and comp.field tokens. TanreiColorField(_ label:, hex: Binding<String>, showsPicker:, pickerLabel:, onCommit:, onPickerRequest:, onEntryError:); labelHidden follows the .labelsHidden() environment and disabled follows .disabled(_:). The text element, the system color picker and the swatch are the color input's and are in its note. The product's words are read by the Field from the \.tanreiWords environment value.	Not built on this platform yet: the color input as a composable of its own and the color field as the Field around it, reading comp.input-box, comp.color-input and comp.field tokens. Compose idiom, as TextField: TanreiColorField(value, onValueChange, label, …); the caller keeps value (state hoisting), enabled is the inverse flag and isError keeps Compose's name. The picker button is shown when onPickerRequest is not null. The rest is the color input's and is in its note. The product's words are read by the Field from LocalTanreiWords.	Not built on this platform yet: the color input as a widget of its own and the color field as the Field around it, reading comp.input-box, comp.color-input and comp.field tokens. Flutter idiom, as TextField and InputDecoration: labelText, helperText, errorText and enabled keep Flutter's names, enabled being the inverse flag. TanreiColorFormField wraps it as a FormField<String>. The rest is the color input's and is in its note. The product's words are read by the Field from the TanreiWords inherited widget.	Not built on this platform yet: the color input as a component of its own and the color field as the Field around it, reading comp.input-box, comp.color-input and comp.field tokens. <ColorField label="Brand color" value={value} onValueChange={setValue} />. The rest is the color input's and is in its note. The product's words are read by the Field from the TanreiWordsProvider context.

Tokens

Token	Aliases	Resolved (light)
--tanrei-comp-field-counter-gap	sys.space.space200	16px
--tanrei-comp-field-error-text-gap	sys.space.space50	4px
--tanrei-comp-field-error-text-placement	—	0
--tanrei-comp-field-label-icon-gap	sys.space.space100	8px
--tanrei-comp-field-label-icon-size	sys.icon.small	20px
--tanrei-comp-field-label-gap	sys.space.space100	8px
--tanrei-comp-field-motion-state-duration	sys.motion.role.state.default	250ms
--tanrei-comp-field-motion-state-easing	sys.motion.easing.state	cubic-bezier(0.2, 0, 0, 1)
--tanrei-comp-field-requirement-asterisk-gap	sys.space.space25	2px
--tanrei-comp-field-requirement-gap	sys.space.space100	8px
--tanrei-comp-field-requirement-mark	sys.behavior.requirement-mark	0
--tanrei-comp-field-standard-counter-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-standard-disabled-counter-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-text-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-counter-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-label-icon-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-label-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-required-asterisk-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-supporting-text-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-error-value-text-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-label-icon-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-label-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-required-asterisk-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-supporting-text-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-disabled-value-text-color	—	#1b1b1b · 38%
--tanrei-comp-field-standard-error-text-color	sys.color.error	#cd262f
--tanrei-comp-field-standard-error-counter-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-standard-error-label-icon-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-standard-error-label-color	sys.color.on-surface	#1b1b1b
--tanrei-comp-field-standard-error-required-asterisk-color	sys.color.primary	#1b1b1b
--tanrei-comp-field-standard-error-supporting-text-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-standard-error-value-text-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-standard-focused-counter-color	—	#4b4b4b
--tanrei-comp-field-standard-focused-error-text-color	—	#cd262f
--tanrei-comp-field-standard-focused-error-counter-color	—	#4b4b4b
--tanrei-comp-field-standard-focused-error-label-icon-color	—	#4b4b4b
--tanrei-comp-field-standard-focused-error-label-color	—	#1b1b1b
--tanrei-comp-field-standard-focused-error-required-asterisk-color	—	#1b1b1b
--tanrei-comp-field-standard-focused-error-supporting-text-color	—	#4b4b4b
--tanrei-comp-field-standard-focused-error-value-text-color	—	#4b4b4b
--tanrei-comp-field-standard-focused-label-icon-color	—	#4b4b4b
--tanrei-comp-field-standard-focused-label-color	—	#1b1b1b
--tanrei-comp-field-standard-focused-required-asterisk-color	—	#1b1b1b
--tanrei-comp-field-standard-focused-supporting-text-color	—	#4b4b4b
--tanrei-comp-field-standard-focused-value-text-color	—	#4b4b4b
--tanrei-comp-field-standard-label-icon-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-standard-label-color	sys.color.on-surface	#1b1b1b
--tanrei-comp-field-standard-required-asterisk-color	sys.color.primary	#1b1b1b
--tanrei-comp-field-standard-supporting-text-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-standard-value-text-color	sys.color.on-surface-variant	#4b4b4b
--tanrei-comp-field-supporting-text-gap	sys.space.space50	4px
--tanrei-comp-field-value-text-gap	sys.space.space200	16px
--tanrei-comp-field-label-typescale	sys.typescale.label	500 14px/1.4286
--tanrei-comp-field-supporting-text-typescale	sys.typescale.label-small	500 12px/1.3333
--tanrei-comp-field-value-text-typescale	sys.typescale.label	500 14px/1.4286

Fixtures

Canonical renderings. Every platform snapshots each fixture under the same id so the results can be compared.

variant: stacked (27)

stacked-empty

label: Brand color

stacked-filled

value: #0f766e label: Brand color

stacked-large

size: large value: #0f766e label: Brand color

stacked-label-hidden

value: #0f766e label: Brand color labelHidden: true

stacked-supporting

value: #0f766e label: Brand color supportingText: Six hexadecimal digits, like #0f766e.

stacked-white

value: #ffffff label: Page background

stacked-black

value: #000000 label: Text

stacked-picker

value: #0f766e label: Brand color picker: true pickerLabel: Choose color

stacked-picker-empty

label: Brand color picker: true pickerLabel: Choose color

stacked-picker-large

size: large value: #0f766e label: Brand color picker: true pickerLabel: Choose color

stacked-error

value: #fde047 label: Brand color errorText: Too light for white text. Choose a darke… error: true

stacked-error-picker

value: #fde047 label: Brand color errorText: Too light for white text. Choose a darke… error: true picker: true pickerLabel: Choose color

stacked-disabled

value: #0f766e label: Brand color disabled: true

stacked-picker-disabled

value: #0f766e label: Brand color disabled: true picker: true pickerLabel: Choose color

stacked-label-icon

value: #0f766e label: Brand color slots: label-icon

stacked-required

value: #0f766e label: Brand color required: true requiredText: Required

stacked-optional

label: Accent color optional: true optionalText: Optional

stacked-required-asterisk

value: #0f766e label: Brand color required: true requiredMark: asterisk

stacked-required-label-icon

value: #0f766e label: Brand color required: true requiredText: Required slots: label-icon

stacked-required-error

label: Brand color errorText: Choose a brand color. error: true required: true requiredText: Required

stacked-required-disabled

value: #0f766e label: Brand color disabled: true required: true requiredText: Required

stacked-required-ja

value: #0f766e label: ブランドカラー required: true requiredText: 必須 picker: true pickerLabel: 色を選択

stacked-optional-ja

label: アクセントカラー supportingText: # と 6 桁の 16 進数で入力します。 optional: true optionalText: 任意

stacked-required-rtl

value: #0f766e label: لون العلامة required: true requiredText: مطلوب picker: true pickerLabel: اختيار اللون direction: rtl

stacked-error-rtl

value: #fde047 label: צבע המותג errorText: בהיר מדי לטקסט לבן. בחרו צבע כהה יותר. error: true direction: rtl slots: label-icon

ltr-label-rtl

value: #0f766e label: Brand color (HEX) supportingText: sRGB, 6 digits direction: rtl

long-label

value: #0f766e label: The color of the primary buttons, the li… supportingText: Six hexadecimal digits after a number si… required: true requiredText: Required

variant: filled (5)

filled-empty

variant: filled label: Brand color

filled-filled

variant: filled value: #0f766e label: Brand color

filled-picker

variant: filled value: #0f766e label: Brand color picker: true pickerLabel: Choose color

filled-error

variant: filled value: #fde047 label: Brand color errorText: Too light for white text. Choose a darke… error: true

filled-disabled

variant: filled value: #0f766e label: Brand color disabled: true

variant: outlined (7)

outlined-empty

variant: outlined label: Brand color

outlined-filled

variant: outlined value: #0f766e label: Brand color

outlined-large

variant: outlined size: large value: #0f766e label: Brand color

outlined-picker

variant: outlined value: #0f766e label: Brand color picker: true pickerLabel: Choose color

outlined-error

variant: outlined value: #fde047 label: Brand color errorText: Too light for white text. Choose a darke… error: true

outlined-disabled

variant: outlined value: #0f766e label: Brand color disabled: true

outlined-required

variant: outlined value: #0f766e label: Brand color required: true requiredText: Required

Generated from specs/color-field.spec.json, tokens/comp/field.tokens.json, design/tokens/

What the web draws differently

link

• The element’s shadow root holds a <tanrei-field> with a <tanrei-color-input> in it, and nothing else. Importing the element defines both.
• The color field is a form-associated element. It takes name and submits value: the color, or an empty string. It resets to the value attribute, and reports a missing value while required and value is empty, and a bad input while an entry error lasts. Its two members add no entry to the form.
• value is always the color input’s: a value set as 0F766E is read back as #0f766e, and one that is not a color as an empty string.
• input and change are plain events: read value from the element. pickerrequest and entryerror are CustomEvents with detail.value and with detail.text and detail.message. They are the color input’s own events, with the element as their target. detail.message is invalidText, and empty where you gave none — also while the field shows errorText in its place.
• Parts: field and color-input are the two members. Their own parts have the same names here as one level down: label-icon, supporting-text; container, outline, active-indicator, swatch, input, picker-button. label and requirement-label are the drawn ones, whichever member draws them; field-label, color-input-label, field-requirement-label and color-input-requirement-label name one member’s.
• The element is not focusable itself and has no role: focus() goes to the input, never to the picker button. A press on the label row, on the box, on the swatch (while there is no picker button) or on a floating label focuses the input. A press on the help or the error text does nothing.
• The label and the help take their focused colors while focus is anywhere in the field, the picker button included. The box takes its own only while its input has focus.
• Name it with label — with label-hidden where the label is not to be drawn — and never with aria-label, which names nothing here.
• The element has no words of its own. requiredText and optionalText are empty until you give them. A required field without requiredText shows the asterisk where the tag would stand.
• The browser’s picker differs by browser: a popup of the page in Chromium, the system’s color window in Firefox and Safari. Its look, placement and keys are the browser’s.
• A text in full-width characters (＃０ｆ７６６ｅ) is not read as a color.
• Before the element is defined it has no size. Reserve the height.

Guidelines

link

Color field or text field

link

Aspect	Color field	Text field
Holds	One color, as # and six digits	Any text
Shows	A sample of the color beside the text	The text
Checks	That the text is a color	Nothing

For a color that is shown and not edited, draw a sample with its value or its name in text beside it. A color field is for a color people set.

Do

link

• Write a label that says what the color is for, and keep it visible in a form.
• Say the form of the value in supportingText. It stays while the field is in error, so invalidText need not repeat it.
• Name the color in words in supportingText where that matters (“Teal”). A hexadecimal value says little about how a color looks.
• Give pickerLabel whenever picker is set.
• Validate what the color means yourself — its contrast against a background, a color already taken — and say it with error and errorText.
• Use a color input in a row that already names each color, such as the tones of a palette: it is the box alone, named by its own label.

Don’t

link

• Don’t tell a color by the swatch alone. The value is text; a person who cannot tell two samples apart reads two different values.
• Don’t treat an empty value as an error by itself. required never validates.
• Don’t set aria-invalid or error while a person is typing. Wait for change or entryerror.
• Don’t put a color field inside a field. It is a field already; the control a field frames is the color input.

Accessibility

link

Role

textbox

Labeling

The color field adds nothing to what its members expose and coordinates nothing: the Field gives the color input its name, its description and its required, invalid and disabled states (FLD-8, FLD-10, FLD-11, FLD-14), and the color input carries them on its own element (CLI-11). Assistive technology meets one text box named by label whose value is the color as text, and, while picker is true, one button named by pickerLabel — exactly as it meets a Field around a color input written by hand.

Minimum target

The hit area meets the minimum target size even when the visual size is smaller. minimum 32px · pointer 44px · spacing 8px · touch 48px

Keyboard

Keys	Action
Every key	The color input's (its accessibility block; CLI-13, CLI-19, CLI-28). The color field handles no key and adds no focus stop (CLF-45).

Notes

• One level down is the same thing: a Field with a color input in it. Every fixture has that pair as its twin, and the accessibility tree of the two is the same (CLF-43).
• On the web the two members stand in the color field's own shadow root, so the form meets the color field and not the input (CLF-44); focus passes through to the input (CLF-45).
• The color is never told by the swatch alone (WCAG 1.4.1), an error is always words (WCAG 3.3.1), and the swatch alone keeps its color in forced colors: each is the color input's or the Field's, and is said there (CLI-25, CLI-35, FLD-7, FLD-17).

Generated from specs/color-field.spec.json, tokens/sys/measure.tokens.json

What the component handles

link

• The input is a text field. Its name is label, drawn or hidden, and its value is the text it shows.
• The shown supporting or error text is its description, with optionalText while the field is optional.
• It is exposed as invalid while error is true or an entry error lasts, and as required while required is set.
• An error that appears while the field has focus is announced once, politely. It never takes focus away.
• The swatch is decorative and hidden from assistive technology: the value’s text says the color.
• The picker button is a separate button, named by pickerLabel, that is exposed as opening a dialog. It is a focus stop after the input. Focus given to the field itself always goes to the input.
• Nothing is announced when the value changes, and the field adds no name of the color.
• While an input method is composing, the field reads nothing and handles no key.
• The field’s hit area meets the minimum target, and the picker button is a full target.
• At 200% text the label and the help wrap. The value stays on one line, and scrolls; the swatch keeps its size.
• In forced colors the field gains an edge and takes the person’s colors. The swatch alone keeps the value’s color, because showing that color is what it is for; its edge is the text color.
• In a right-to-left layout the field is mirrored: the swatch at the right, the picker button at the left. The value itself stays left to right.

Known gaps on the web:

• The browser’s picker is not Tanrei’s: its accessibility is the browser’s own.
• Before the element is defined, nothing is drawn.

What you need to do

link

• Give every color field a label.
• Write invalidText and pickerLabel on the field, in the language of the page. Give requiredText and optionalText on the field, or once for the whole product with setWords({ requiredText, optionalText }). See The product’s words.
• Validate the color yourself, set error, and write errorText so that it says how to put the color right.
• If you present your own picker, open it from the picker button, give it a name, and return focus to the button when it closes.