Color And Tone

Practical reference for @domphy/ui, based on @domphy/theme.

• tone ramp: 18 steps
• contrast span: K = 9

For theory, see Theme Tone.

dataTone

dataTone is the default background tone context for a surface.

If a container sets dataTone, child elements that use themeColor(listener, "inherit", family) will resolve their background from that tone context first.

Use dataTone to choose the default surface branch before styling individual backgroundColor values.

Notes:

• if the tone is inherit, do not set dataTone; it already inherits by default and keeps the current surface context.
• shift-1 and shift-2 are explicit near-default surfaces, not the default itself.
• base means the configured base tone of the chosen color family in @domphy/theme; it is not a fixed number.
• overlay surfaces use the Invert branch.
• in the current built-in light theme, primary commonly reads near the middle accent band.
• in UI usage, base is mainly useful when you want the theme's authored default emphasis instead of hard-coding a shift-N.

Background Color

Static State

Boundary Edge

This section applies to any visual edge:

• border
• outline
• boxShadow
• any other style used as a boundary edge

Static State

Note:

• use boundary edge static state when the state is expressed by the edge itself
• if the background already carries the selected state, do not also force a selected edge unless stronger emphasis is needed

Text Color

Semantic

Static State

Note:

• use text static state when the text itself must show the static state more clearly
• text static state can appear together with background or boundary edge static state when stronger text emphasis is needed

Interaction State

Interaction state is not a separate base state.

It is a delta applied on top of the current static state.

Notes:

• choose only one role to carry the interaction state, not all three at the same time
• priority order is: background, then boundary edge, then text
• use text interaction only when background and boundary edge interaction are both absent
• static states stay 3 levels apart, while interaction changes by at most 1 or 2 levels, so hover and active do not collide with adjacent static states

Focus Visible

Use Focus Visible as a separate focus rule.

Notes:

• if Strong Edge is already used for selected or current state, do not rely on that alone for focus; add a separate focus outline

Example:

"&:focus-visible": {
  outline: (listener) => `1px solid ${themeColor(listener, "shift-6", "primary")}`,
  outlineOffset: themeSpacing(1),
}

Disabled

Disabled is handled as de-emphasis, not as a core tone state.

Notes:

• use opacity first
• tone change is optional when opacity alone is not enough
• optional tone changes bring background and text closer together instead of keeping the normal 9-step contrast distance

Color Family

Patch Reference

This table groups patches by the dataTone they set themselves.

Core Pattern

backgroundColor: (listener) => themeColor(listener, "inherit", "neutral")
color: (listener) => themeColor(listener, "shift-9", "neutral")
outline: (listener) => `1px solid ${themeColor(listener, "shift-4", "neutral")}`