ui-appearance

name	ui-appearance
description	How any bombdog surface should look. Covers which color role to use (accent vs success/danger vs wire hues vs neutrals), borders/shadows/background fills and elevation, which control element fits a decision (segmented toggle, chip toggle-group, dropdown select, check-toggle, checkbox), modal dialog vs bottom sheet, how wire states are drawn (uncut/revealed/cut/selected), and how successful vs failed cuts are expressed.
when_to_use	Apply when deciding how a surface should look — before styling any new component or state, and when reviewing UI for appearance consistency, even if the user only mentions a color, a shadow, a dialog, a chip, a wire, or an outcome badge.
user-invocable	false

UI Appearance

The design vocabulary for bombdog's UI: which appearance treatment each surface, control, and state gets. This skill owns the decisions; the project's React guidelines own the implementation mechanics (CSS Modules, @scope, ramp-step usage, motion/keyframe placement), and src/app/variables.css is the only home for token values.

Color Roles

Every color in the app belongs to exactly one role. The ramps (see variables.css) map to meanings, not decoration:

Role	Tokens	Used for
Neutral (slate)	--surface*, --border*, --text*	Chrome, cards, resting controls, text
Accent (blue)	--accent, --accent-hover, --accent-contrast	The single primary action of a surface; selection emphasis for non-wire choices (players, tabs, filter checks)
Success (grass)	--success, --success-soft, --success-text	Successful cut outcomes only
Danger (tomato)	--danger*, --danger-tint	Failed cut outcomes, destructive actions, invalid-field marking
Wire blue (sky)	--wire-blue*	Blue-wire identity only
Wire yellow (amber)	--wire-yellow*	Yellow-wire identity only
On-solid	--on-solid	Text/icons sitting on any solid step-9 fill (accent, success, danger)

Guidelines:

• MUST give each screen or sheet at most one accent-solid primary action; secondary actions stay neutral (--surface-3 + --border), and destructive triggers stay --danger-text on a neutral fill, filling solid danger only inside a confirm dialog.
• MUST reserve green/red (grass/tomato) for action outcomes, destructive actions, and invalid-input signals; MUST NOT use them to encode wire identity or wire state.
• MUST color wire-value UI with the wire hue tokens (sky for blue values, amber for yellow); MUST NOT use --accent for a wire-value choice, even a two-option one.
• MUST use --on-solid for text and icons on solid success/danger/accent fills; MUST NOT hard-code white or reuse --accent-contrast outside accent fills.
• MUST pick ramp steps by role per the step table in the project's React guidelines (css-modules-styling rules) (soft rest 3, hover 4, border 7, solid 9, text 11).

Surfaces, Borders, Shadows

Elevation has a deliberate split — each floating layer type has one delineation language, and they do not mix:

Surface kind	Treatment
In-flow card / panel	--surface-2 fill + 1px --border + --radius; no shadow
Anchored popover (select menu, dropdown menu)	--surface-2 + 1px --border + --shadow-popover; no scrim
Modal surface (bottom sheet, dialog, confirm)	--surface + 1px --border under a --scrim overlay (with 2px backdrop blur); no shadow

Guidelines:

• MUST NOT introduce new box-shadow values; the only sanctioned shadow is --shadow-popover, and only on anchored popovers.
• MUST dim every modal with the shared --scrim token on its overlay; MUST NOT re-declare an inline scrim color-mix.
• MUST use the radius roles: --radius-sm for controls and chips, --radius for cards and popovers, --radius-lg for modal surfaces; 50% only for genuinely circular dots/radios.
• MUST derive hover fills from the adjacent ramp step, per the project's React guidelines (css-modules-styling rules) (never an ad-hoc color-mix).
• SHOULD reserve --border-strong for emphasized outlines: checkbox rests, the status strip's tiny copy squares, neutral row accents.

Control Selection

Match the control to the shape of the decision, and reuse the existing component for it:

Decision shape	Control
2–3 exclusive options that must stay visible	Segmented buttons (aria-pressed) — outcome toggle, cut-value picker
Pick wire value(s)	WirePad chip grid (Radix ToggleGroup)
Pick player(s)	PlayerPicker chips (+ ⋯ overflow menu for rare choices)
One choice from a list of ≥4 named options	SelectField dropdown
Multi-select filters	Check-toggle buttons (check-in-box + aria-pressed)
Plain boolean form field	Native checkbox with accent-color
Committing a destructive action	Centered AlertDialog confirm

Guidelines:

• MUST reuse the existing control component for a decision shape instead of hand-rolling a lookalike (any wire-value choice renders WirePad).
• MUST express selection through Radix data-state on Radix controls and aria-pressed on plain buttons; MUST NOT add bespoke selected classes.
• MUST render a selected chip/segment as a solid fill (accent for non-wire choices, wire hue for wire values), not a border-only change.
• MUST size tap targets at ≥44px for primary-flow controls and ≥36px for compact toolbar triggers.
• MUST style disabled controls as opacity: 0.5 with cursor: not-allowed; no other disabled opacities.

Modal Dialogs vs Bottom Sheets

Two modal surface types exist, split by what the user is doing:

• Any multi-field create/edit/filter flow opens the shared BottomSheet component: a bottom sheet on narrow viewports, a centered dialog on wide ones, with drag-to-dismiss and depth-aware nesting.
• Destructive confirmations (reset, delete) use a compact centered AlertDialog — min(92vw, 26rem), --radius-lg — whose confirming action is the only solid-danger button on screen.

Guidelines:

• MUST open form-like modal flows in the shared BottomSheet; MUST NOT hand-roll overlay/sheet chrome per component.
• MUST reserve AlertDialog for destructive commitments; a data-entry flow is never an AlertDialog.
• MUST give every modal overlay and content both enter and leave animations plus a reduced-motion fallback, per the project's React guidelines (motion-and-transitions rules).
• MUST order confirm actions as neutral Cancel then trailing solid-danger confirm.

Wire Indicator States

Wire visuals are a layered language: hue carries identity, fill carries knowledge, strikethrough/hollow carries cut — each layer moves independently:

Wire state	Treatment
Picker chip at rest	Soft hue background (step 3) + hue border (step 7) + hue text (step 11)
Selected in a picker	Solid hue fill (step 9) + --wire-*-contrast text
Known / revealed / held (uncut)	Same solid hue fill as selected — "we know this wire"
In play, location unknown	Dashed neutral outline (--border; --border-strong for tiny glyphs) + muted text or transparent fill
Cut	Strikethrough on the wire number; copy squares hollow (--surface-3 + --border-strong); never an outcome color
Unknown value ("?")	Neutral: --surface-3/--border at rest, solid --text-muted when selected

Guidelines:

• MUST render passive known-wire indicators (status player cells, move-log chips, starting-info chips, revealed status copies) as solid hue fills.
• MUST render in-play-but-unlocated wire facts as dashed outlines, and cut wires with a non-color cue (strikethrough and/or hollow squares) so color is never the only channel.
• MUST NOT tint any wire state with success/danger colors; outcomes belong to moves, not wires.
• MUST keep the "?"/unknown value on the neutral treatment so it never masquerades as a real hue.

Cut Outcome Treatment

Success/fail intensity is split by whether the element is interactive:

• Interactive pressed state (outcome toggle): solid --success/--danger fill, --on-solid text, Check/X icon.
• Passive indicator (move-log badge): soft tint (--success-soft/--danger-soft) + step-11 text (--success-text/--danger-text) + small Check/X icon.
• Row edge accent (move-log): 3px solid --success/--danger, --border-strong for neutral moves.

Guidelines:

• MUST use solid outcome fills only on interactive pressed states; passive read-only indicators use the soft-tint treatment.
• MUST pair every outcome color with a Check/X icon or explicit wording, so the outcome reads without color.
• MUST keep the status strip outcome-colorless; a cut is expressed through the wire-state layer (strikethrough + hollow), not green/red.