Skip-to-Content Links

Free — GPL coresize Splanned, not built

Generated from docs/plan/core/skip-to-content-links/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Core-free keyboard-navigation helper: a ‘Skip to main content’ link at the very top of the page, visible only on keyboard focus (hidden from mouse). When activated, focus jumps to the main content area, bypassing repetitive navigation links. Meets WCAG 2.4.1.

The problem

Keyboard users tab through 50 navigation links (header, sidebar, footer nav) before reaching the main content. Accessibility is painful. No quick way to jump to the article or product list.

What it does

• Skip link appears at the top of the page HTML, before any visible content
• Link is visually hidden by default (CSS: display: none or clip or off-screen positioning)
• Link becomes visible when focused (keyboard tab) with a clear, contrasting style (default: dark background, white text, 16px, positioned at top-left)
• Clicking the link sets focus to the main content area (<main> element or data-skip-target attribute)
• Works on all pages: public site, admin, post editor, product editor
• Theme editor allows customization of skip link color/text (Settings → Accessibility → Skip Links)

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 programmatic focus management — only sets focus to the main element; does not scroll or manipulate DOM beyond focus (reason: browser handles scroll on focus automatically)
• No skip links to other targets (sidebar, footer) — only main content (reason: the standard is main content only; multiple skip links create confusion)

Data model

None. Settings keys: theme_skip_link_visible (boolean, default true), theme_skip_link_color (hex), theme_skip_link_text (string, default ‘Skip to main content’). Optional; no migration.

API

• GET /api/theme/skip-link-settings
• PUT /api/theme/skip-link-settings { visible, color, text }

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 optional ‘Skip Links’ section. Merchant can set link text and color. Preview shows skip link at top of page on focus (interactive demo, must tab to see it). Default is enabled.

The seam — why this is core

Core owns the skip link DOM and focus logic. Theme owns the color/text customization.

Core owns the interface + honest skip link; accessibility is infrastructure, not a support commitment or credential.

Dependencies

• Layout template (core)
• Theme system (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 to the first focusable element (skip link) makes it visible at the top of the page
• Activating the skip link moves focus to the <main> element
• Skip link is not visible on page load (no mouse) or on mouse click
• Skip link text is customizable in theme settings and renders on the page
• Each page has a <main> element or [data-skip-target] attribute for the link to target

Risks

If no <main> element exists on the page, focus will go nowhere (or to an invalid target). Must validate that every page template includes a <main> or equivalent. Customizing skip link text to something confusing (e.g., ‘Click here’) defeats the purpose; need guidance, not enforcement.

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.