Focus Indicators

Free — GPL coresize Splanned, not built

Generated from docs/plan/core/focus-indicators/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Core-free UI component that ensures keyboard-navigable elements (links, buttons, form inputs, menu items) have visible focus indicators meeting WCAG 2.4.7 (at least 3:1 contrast ratio against adjacent colors). Applies to admin and public site.

The problem

Keyboard-only users cannot see which element is focused. Navigation is impossible. Tab key highlights nothing, and the user has no idea where they are on the page or which button they are about to activate.

What it does

• Global CSS rule for :focus-visible pseudo-class on all focusable elements (buttons, links, inputs, selects, textareas, [tabindex])
• Focus ring is a 2–3px contrasting border (default: 2px solid #000 or #FFF depending on theme) or outline with sufficient contrast
• Focus ring does not disappear on keyboard navigation (only on mouse click, per :focus-visible)
• Admin can customize focus-ring color/width/style in theme settings (Theme → Accessibility → Focus Indicators)
• Focus ring applies to all state (hover, active, disabled); disabled elements can have a muted focus style
• Public site theme respects the focus-ring setting; bundled themes include accessible focus styles by default

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• No automatic focus management (e.g., moving focus on modal open) — that is up to each component (reason: focus management is context-dependent, not a global CSS problem)
• No focus-order remapping — tab order follows DOM order by default (reason: changing tab order is a component-level concern, not a theme concern)

Data model

Settings keys: theme_focus_color (hex), theme_focus_width (px), theme_focus_style (solid | dashed | dotted). No schema migration.

API

• GET /api/theme/focus-settings
• PUT /api/theme/focus-settings { color, width, style }

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Theme editor gains ‘Focus Indicators’ section under Accessibility. Merchant can set focus ring color (color picker with contrast validator), width (1–4px), and style. Preview shows a sample button with the configured focus style. Default theme ships with dark/light focus rings that meet 4.5:1 contrast.

The seam — why this is core

Core owns the :focus-visible CSS rule and the settings. Themes inherit the core focus style unless they override it (allowed, but bundled themes do not).

Core owns the interface + honest focus renderer; accessibility is infrastructure, not a per-country obligation or credential.

Dependencies

• Theme system (core)
• CSS render pipeline (core)
• Settings (core)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Tabbing through public site shows a visible focus ring (at least 2px, at least 3:1 contrast) on every focusable element
• Clicking a button removes the focus ring (only shows on keyboard nav, not mouse)
• Admin theme editor allows merchant to change focus ring color from default to custom value
• Custom focus color is applied to public site immediately after save (no rebuild required)
• Focus ring on disabled button is visible but uses a muted color (e.g., 50% opacity)

Risks

Focusable elements that are not semantic HTML (div[tabindex]) will not get the focus ring unless a component adds it; only semantic elements get :focus-visible. CSS library or third-party scripts might suppress :focus-visible; need to audit dependencies. Some older browsers do not support :focus-visible; need fallback to :focus.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.