# OSHUN V1 Contrast And Focus-Indicator Rules

Status: Accepted v1.0  
Owner: OSHUN Design + Product + Engineering  
Last Updated: March 26, 2026  
Implements: `V1-UX-068`  
Related:

- `docs/releases/v1/design/ux-principles.md`
- `docs/releases/v1/design/readability-standards.md`
- `docs/releases/v1/design/customer-visual-thesis.md`
- `docs/releases/v1/design/admin-visual-thesis.md`
- `docs/releases/v1/scope/minimal-chrome-rules.md`
- `docs/releases/v1/specs/shared-component-accessibility-standards.md`
- `docs/releases/v1/scope/interaction-feedback-rules.md`
- `apps/oshun/web/src/design-system/globals-v2.css`
- `apps/oshun/web/src/design-system/tokens.ts`
- `apps/oshun/web/src/design-system/components/Button.tsx`
- `apps/oshun/web/src/design-system/components/IconButton.tsx`
- `apps/oshun/web/src/design-system/components/SearchInput.tsx`
- `apps/oshun/web/src/design-system/components/FormField.tsx`
- `apps/oshun/web/src/components/studio/StudioHathorEconomyModelingWorkspace.tsx`
- `apps/oshun/mobile/src/__tests__/nonfunctional/accessibility-ci.test.ts`
- `docs/releases/v1/specs/todos.md`

## 1. Purpose

This document defines the canonical rules for:

- text contrast
- non-text contrast
- keyboard focus indicators
- focus visibility under sticky or dense UI
- high-contrast accommodations

The goal is not to make OSHUN loud.

The goal is to preserve the product's minimal, composed visual system while
still making interactive states unmistakable for keyboard users, low-vision
users, and users navigating dense or accent-heavy surfaces.

## 2. Current Repo Signals, External Scan, And Gap

The current repo already contains strong accessibility and visual signals:

- `READABILITY_STANDARDS.md` already requires WCAG AA text contrast and
  readability under scaling and reflow.
- `OSHUN_V1_SHARED_COMPONENT_ACCESSIBILITY_STANDARDS.md` already says focus
  indicators must remain visible, states cannot rely on color alone, and
  components must remain usable at `200%` zoom.
- `globals-v2.css` already defines a global `:focus-visible` outline and a
  `focus-within` surface treatment.
- `tokens.ts` already exposes semantic accent and status colors plus a reusable
  focus-ring helper.
- `SearchInput.tsx` and `FormField.tsx` already pair border changes with a
  focused halo instead of relying on motion alone.
- current Studio operator workspaces already expose explicit
  `high-contrast=enabled` modes and test that posture in accessibility QA.
- mobile accessibility CI already treats text contrast, icon contrast, touch
  targets, and logical focus order as first-class regression categories.
- the customer visual thesis already says richness should come from contrast,
  spacing, and material treatment before heavy chrome, and that domain accent
  may tint focus areas.
- the admin visual thesis already says background treatment must support focus
  and severity must read through controlled accents rather than visual noise.

External accessibility guidance sharpens the requirements:

- WCAG text contrast still anchors OSHUN at `4.5:1` for normal text and `3:1`
  for qualifying large text.
- WCAG non-text contrast requires `3:1` contrast for visual information needed
  to identify controls and states such as selected, focused, or checked.
- WCAG 2.2 Focus Appearance requires an author-styled focus indicator area at
  least equivalent to a `2px` perimeter of the unfocused control and a `3:1`
  change of contrast between focused and unfocused states.
- W3C technique `C40` recommends a two-color focus indicator for mixed
  backgrounds and warns against relying on `box-shadow` alone because forced
  colors may suppress it.
- WCAG 2.2 Focus Not Obscured calls out sticky headers, sticky footers, and
  floating panels as common ways authors hide focused items.
- GOV.UK focus guidance uses two highly contrasting colors so focus remains
  visible on both light and dark surfaces.

Inference from those sources plus the repo state:

- OSHUN already values calm contrast and visible focus.
- OSHUN still needs one explicit rule set explaining exactly how contrast and
  focus should behave on dark shells, gradient surfaces, dense admin tables,
  operator rows, image-led cards, and sticky-action layouts.

## 3. Canonical Thesis

Minimal is not the same as low-contrast.

OSHUN should feel quiet at rest and explicit in action.

That means:

- low noise by default
- strong state change on interaction
- focus that is visible without being theatrical
- contrast that carries meaning without flattening the whole interface

The resting surface may be restrained.

The focused surface must be unmistakable.

## 4. Numeric Baseline

### 4.1 Text Contrast

Use these minimums:

- normal text: `4.5:1`
- large text: `3:1`

Preferred OSHUN stance:

- mission-critical labels, buttons, and table text should usually still target
  `4.5:1` even when they technically qualify as large text
- helper and placeholder text that affects task completion is not exempt from
  readable contrast

### 4.2 Non-Text Contrast

Any visual information required to identify a control or state must meet at
least `3:1` against adjacent colors.

This applies to:

- control borders when they define the control
- icons that communicate function
- carets when author-styled
- selected-state indicators
- warning or error rails
- focus indicators

### 4.3 Focus Indicator Math

Author-styled focus indicators must satisfy all of these:

- at least `3:1` change of contrast between focused and unfocused states
- at least the area of a `2px` perimeter of the unfocused control, or an
  equivalent area
- visible enough that the focused component is not entirely hidden by
  author-created content

### 4.4 Two-Color Focus Preference

When OSHUN places focus over variable or mixed backgrounds, the preferred focus
pattern uses two contrasting indicator colors.

For a two-color ring:

- the two indicator colors should contrast with each other by at least `9:1`
- each visible band should be at least `2px` when that band alone may need to
  satisfy the minimum area requirement

## 5. Core Rules

### 5.1 Resting States Stay Quiet, Not Invisible

Minimal chrome may reduce:

- shadow depth
- decorative borders
- permanent accent saturation

Minimal chrome may not reduce:

- legibility
- control discoverability
- state contrast
- focus visibility

### 5.2 Domain Accent Cannot Be The Only Focus Signal

Accent color may tint focus, selection, or local context, but the user must not
need perfect color perception or brand familiarity to find focus.

Focus must remain identifiable through:

- perimeter
- contrast
- thickness
- offset

not accent hue alone.

### 5.3 Focus, Selection, Hover, And Error Must Stay Distinct

These states answer different questions:

- hover: what the pointer is over
- focus: where keyboard interaction is
- selection: what is active or chosen
- error: what is invalid or blocked

Do not collapse them into one border color or one glow treatment.

### 5.4 Focus Cannot Depend On Motion

Animation may stage the arrival of a focus indicator, but the final visible
state must stand on its own.

No component passes by:

- a brief pulse only
- a momentary scale jump only
- a transient glow that fades to near-invisible

### 5.5 Contrast Must Be Judged In Real Adjacency

Check the colors actually touching the element, not the token name in isolation.

This matters especially for:

- inset borders
- internal focus rings
- translucent panels
- image-led surfaces
- gradient backgrounds
- mixed-surface cards

## 6. Text And UI Contrast Rules

### 6.1 Text Before Decoration

If a layout tradeoff exists, preserve readable text before decorative mood.

Reduce first:

- shadow
- blur
- texture intensity
- accent wash

before reducing text contrast.

### 6.2 Essential Secondary Text Still Needs Real Contrast

Muted text is allowed only when it remains readable for its role.

Do not use faint tertiary text for:

- field labels
- tab labels
- actionable metadata
- validation help
- queue row identity

### 6.3 Borders Must Pass When Borders Carry Meaning

If a border is the primary cue that a control exists, it must meet `3:1`.

Light grey `1px` borders on white or near-white backgrounds are non-canonical
when they are the only control boundary.

### 6.4 Icons Need Contrast When They Carry Meaning

Decorative icons may stay subtle.

Functional icons such as:

- search
- dropdown arrows
- close actions
- state symbols
- step indicators

must meet non-text contrast expectations.

## 7. Focus-Indicator Rules

### 7.1 Default OSHUN Focus Pattern

The default preferred pattern for keyboard focus is:

- a visible perimeter outside or at the edge of the control
- at least `2px` effective thickness
- contrast that is reliable on the local background
- a shape that follows the control or its bounding box

### 7.2 Single-Color Rings Are Allowed Only On Stable Backgrounds

Use a single-color focus indicator only when the surrounding surface is stable
enough that the ring clearly passes on every intended state.

Examples:

- a known solid form panel
- a stable toolbar background
- a controlled admin row background

### 7.3 Two-Color Rings Are Preferred On Mixed Backgrounds

Use a two-color focus treatment when the focused element may sit on:

- gradients
- imagery
- domain accent fills
- mixed dark and light sections
- unknown operator density themes

Examples:

- light inner ring plus dark outer ring
- dark inner ring plus light outer ring

### 7.4 Do Not Rely On `box-shadow` Alone

`box-shadow` may reinforce focus, but it must not be the only author-supplied
focus cue.

Keep an `outline`, border, or equivalent fallback so focus survives:

- forced colors
- shadow suppression
- low-quality displays
- dense background textures

### 7.5 Inset Focus Needs Extra Thickness

If the indicator is inset within the control rather than outside it, increase
thickness as needed so the remaining visible area still satisfies the minimum
focus area requirement.

Thin internal rings often fail even when they look elegant.

### 7.6 Prose Links Need A Different Focus Pattern

Inline text links should not use the same focus treatment as boxed controls.

Preferred prose-link focus patterns:

- high-contrast text background
- retained readable text color
- underline or bottom border that remains visible

### 7.7 Icon-Only Controls Need Bounding Focus

For icon buttons, use focus around the whole hit area or button boundary, not
around the glyph alone.

The user needs to see the interactive target, not just the pictogram.

## 8. Composite Widgets, Rows, And Dense Surfaces

### 8.1 Focus And Selection Must Be Separate

In listboxes, grids, tables, and queue rows:

- focus shows the keyboard location
- selection shows the active item set

Do not use one identical blue border for both.

### 8.2 Row Focus Needs A Strong Structural Cue

Dense admin rows should use a focus treatment large enough to survive crowded
metadata, badges, and inline actions.

Preferred patterns:

- full-row perimeter
- full-row background shift plus contrasting edge
- high-contrast row rail plus clear bounding change

### 8.3 Group Focus Is Acceptable Only When It Clarifies The Workflow

For composite widgets, the group focus indicator may satisfy the requirement, or
a subcomponent indicator may satisfy it.

Choose the one that best reflects where the next keyboard action will land.

Do not show a vague container glow that fails to identify the actual active
subcomponent.

## 9. Sticky UI, Overlays, And Obscuration

### 9.1 Focus Must Not Hide Behind Sticky Chrome

Sticky headers, sticky footers, cookie banners, floating trays, and
modal-adjacent layers must not fully cover the focused control.

Use:

- scroll padding
- inset spacing
- modal focus trapping
- layout offsets

to preserve visibility.

### 9.2 Sticky Action Bars Need Focus Clearance

Long forms and review flows may use sticky bars, but those bars must not cover
the next tabbable field or its indicator.

If a sticky bar overlaps the focused element, the layout fails this rule even if
the control technically remains in the DOM.

### 9.3 Overlays Must Carry Their Own Focus Clarity

Dialogs, sheets, menus, and command palettes must:

- move focus in
- keep focus visible
- restore focus out

Background chrome should not compete visually with the modal focus state.

## 10. High-Contrast Modes And Overrides

### 10.1 High-Contrast Mode Is A Supplement, Not An Excuse

Optional high-contrast toggles are valuable for operator-heavy surfaces.

They do not reduce the baseline requirement that the default interface already
meets WCAG-compliant contrast and visible focus standards.

### 10.2 High-Contrast Mode Should Increase Signal, Not Add Ornament

When enabled, high-contrast mode may strengthen:

- borders
- text/background separation
- focus perimeters
- state rails

It should not add unnecessary glow, skeuomorphism, or animation.

### 10.3 Forced Colors Must Retain Focus

If a surface uses custom focus styling, verify that focus remains visible when
system or browser forced-color behavior suppresses shadows and custom fills.

## 11. Pattern-Specific Guidance

### 11.1 Forms And Inputs

Inputs should communicate focus through:

- a passing border treatment
- a clearly visible perimeter or halo
- preserved label readability

Error state may change border color, but focus must still remain separately
legible.

### 11.2 Buttons

Buttons may stay visually restrained at rest.

On focus, the indicator must rise above:

- fill color
- domain tint
- destructive red
- disabled adjacency

without relying only on a slight brightness shift.

### 11.3 Image-Led Cards And Rich Media

If the background is complex, place focus on:

- an enclosing frame
- a matte perimeter
- a contrasting overlay edge

Do not trust a single accent line on top of photography or video.

### 11.4 Minimal-Chrome Customer Surfaces

Customer surfaces may keep low permanent border weight, but interactive states
must become decisively clearer on focus.

Calm is preserved through limited simultaneous emphasis, not through nearly
invisible focus.

## 12. Explicit Anti-Patterns

These patterns are non-canonical for OSHUN V1:

- `outline: none` without an equivalent passing replacement
- focus visible only through `box-shadow`
- low-contrast grey borders as the sole input boundary on light backgrounds
- accent-only focus on gradients, photography, or tinted cards
- using the same treatment for focus, selection, and error
- relying on placeholder text or faint icons to identify a control
- sticky bars or banners that fully cover the focused item
- declaring high-contrast mode while default mode still fails baseline contrast

## 13. Acceptance Criteria

OSHUN contrast and focus behavior is correct only when all of these are true:

- normal text meets `4.5:1`, and qualifying large text meets at least `3:1`
- required non-text UI indicators meet `3:1`
- author-styled focus indicators provide at least `3:1` change of contrast
- focus indicator area is at least equivalent to a `2px` perimeter of the
  control or an equivalent area
- focus remains visible on dark, light, accent-heavy, and mixed backgrounds
- focus is not fully hidden by sticky or overlay chrome
- forced-color or shadow-suppressed environments still retain a visible focus
  cue
- focus, selection, hover, and error remain visually distinct

## 14. Delivery Checklist For Coding Agents

When building or revising OSHUN UI:

- validate text, icon, border, and focus contrast on the real adjacent
  backgrounds
- prefer two-color or otherwise contrast-robust focus on mixed backgrounds
- keep an outline or equivalent fallback when using `box-shadow`
- test keyboard focus at `200%` zoom and with sticky chrome active
- verify dense rows, tables, and listboxes keep focus separate from selection
- confirm high-contrast mode strengthens the surface without becoming the only
  accessible mode
