Foundations

Colors

Components never use a raw colour. They use a semantic token, and the theme decides what that token resolves to. Dark is the reference theme; light is designed separately rather than inverted.

Surfaces

Depth in Luc UI is a luminance step plus a hairline, not a big drop shadow. Surfaces form an ordered stack.

surface.canvas--surface-canvasPage background

surface.sunken--surface-sunkenInputs, code, wells

surface.default--surface-defaultCards

surface.raised--surface-raisedPopovers, stat cards

surface.overlay--surface-overlayDialogs, tooltips

surface.interactive--surface-interactiveButtons, hover targets

surface.interactive.hover--surface-interactive-hoverHover state of the above

surface.inverse--surface-inverseInverted chips

Text

Four text levels keep hierarchy predictable. Anything below 4.5:1 against its surface is only ever used for decorative microcopy.

The quick brown fox jumps over 1,284 lazy dogs

text.primary

Titles, values, active labels

The quick brown fox jumps over 1,284 lazy dogs

text.secondary

Body copy, descriptions

The quick brown fox jumps over 1,284 lazy dogs

text.muted

Meta, captions, axis labels

text.disabled

Disabled controls and placeholders only — never body copy

Accent text — links and active emphasistext-accent

Accent

One accent. It marks selection, focus and action — nothing else.

accent.default--accent-default

accent.hover--accent-hover

accent.active--accent-active

accent.strong--accent-strong

accent.soft--accent-soft

accent.on-accent--accent-on-accentText on accent fills

Accent in context

Primary action, soft selection, and accent text.

Primary actionSelectedAccent textIcon on soft accent

Status

Status colour always ships with a label or a glyph. Colour is never the only carrier of meaning.

status.positive--positive

status.negative--negative

status.warning--warning

status.info--info

status.positive.soft--positive-soft

status.negative.soft--negative-soft

LiveHealthyDegradedPendingDownCustom label

Borders and lines

Hairlines carry most of the structure. They are always alpha-based so they sit correctly on any surface.

border.subtle--line-subtleDividers inside a surface

border.default--line-defaultControl outlines, card edges

border.strong--line-strongHover, unchecked controls

border.focus / accent--line-accentFocus and selection edges

Rules

Use bg-surface-* and text-fg-* utilities.
Add a new token to tokens.css when you need a new role.
Check contrast in both themes before shipping a new pairing.

Don't

Hard-code hex, rgb() or palette scales inside a component.
Reach for a second accent colour for “variety”.
Put the accent behind body text.