Add skip-to-content link and global keyboard focus visibility

apps/web/src/components/AppShell.tsx

@@ -26,6 +26,7 @@ import { OnboardingProvider } from './onboarding';
 import { ChoosePathWizard } from './onboarding/choose-path/ChoosePathWizard';
 import { RecentChatsDropdown } from './RecentChatsDropdown';
 import { SidebarProjectList } from './SidebarProjectList';
+import { SkipToContent } from './SkipToContent';
 import { ThemeSwitcher } from './ThemeSwitcher';
 import { ZenPeekRail } from './ZenPeekRail';
 
@@ -264,6 +265,7 @@ export function AppShell({ children }: AppShellProps) {
       <OnboardingProvider>
       <ChoosePathWizard />
       <div className="flex flex-col h-screen">
+        <SkipToContent />
         <header className="relative z-30 flex items-center justify-between px-4 py-2 glass-chrome glass-panel-container glass-composited border-x-0 border-t-0 after:content-[''] after:absolute after:bottom-0 after:left-[10%] after:right-[10%] after:h-0.5 after:bg-[radial-gradient(ellipse_at_center,var(--sam-chrome-accent-glow)_0%,transparent_70%)] after:blur-[1px] after:pointer-events-none">
           {/* Title on the left */}
           <Link to="/dashboard">
@@ -290,7 +292,7 @@ export function AppShell({ children }: AppShellProps) {
           </div>
         </header>
 
-        <main className="sam-main-content flex-1 min-h-0 overflow-y-auto overflow-x-hidden flex flex-col min-w-0">
+        <main id="main-content" className="sam-main-content flex-1 min-h-0 overflow-y-auto overflow-x-hidden flex flex-col min-w-0">
           {children ?? <Outlet />}
         </main>
 
@@ -331,6 +333,7 @@ export function AppShell({ children }: AppShellProps) {
       className="grid h-screen overflow-hidden transition-[grid-template-columns] duration-200 ease-out motion-reduce:transition-none"
       style={{ gridTemplateColumns: `${navWidthForMode(focusMode)}px 1fr`, gridTemplateRows: 'minmax(0, 1fr) auto' }}
     >
+      <SkipToContent />
       {/* Announce Focus Mode changes to assistive tech (mode is cycled via the
           "F" key or the toggle, so screen readers need a live region). */}
       <div aria-live="polite" className="sr-only">
@@ -450,7 +453,7 @@ export function AppShell({ children }: AppShellProps) {
         </aside>
       )}
 
-      <main className="sam-main-content flex-1 overflow-y-auto overflow-x-hidden flex flex-col min-w-0" style={{ gridRow: '1' }}>
+      <main id="main-content" className="sam-main-content flex-1 overflow-y-auto overflow-x-hidden flex flex-col min-w-0" style={{ gridRow: '1' }}>
         {children ?? <Outlet />}
       </main>
 

apps/web/src/components/SkipToContent.tsx

@@ -0,0 +1,10 @@
+export function SkipToContent() {
+  return (
+    <a
+      href="#main-content"
+      className="sam-skip-to-content sr-only focus:not-sr-only focus:fixed focus:top-2 focus:left-2 focus:z-[9999] focus:px-4 focus:py-2 focus:rounded-md focus:text-sm focus:font-medium focus:no-underline"
+    >
+      Skip to content
+    </a>
+  );
+}

apps/web/src/index.css

@@ -114,6 +114,32 @@
   }
 }
 
+/* ── Skip-to-content link ── */
+@layer base {
+  .sam-skip-to-content:focus {
+    background-color: var(--sam-color-focus-ring);
+    color: #000;
+  }
+}
+
+/* ── Global focus-visible ring for interactive elements ──
+   Form elements already have custom focus styles above (box-shadow ring).
+   This adds a visible focus indicator for all other interactive elements
+   (buttons, links, tabs, etc.) when navigated to via keyboard. */
+@layer base {
+  :focus-visible {
+    outline: 2px solid var(--sam-color-focus-ring);
+    outline-offset: 2px;
+  }
+
+  /* Form elements keep their existing box-shadow focus style instead */
+  input:focus-visible,
+  textarea:focus-visible,
+  select:focus-visible {
+    outline: none;
+  }
+}
+
 /* ── SAM-specific utility (not replaceable by Tailwind) ── */
 @layer utilities {
   .min-h-screen { min-height: var(--sam-app-height); }

apps/web/tests/unit/accessibility.test.tsx

@@ -0,0 +1,122 @@
+import { render as baseRender, type RenderOptions, screen } from '@testing-library/react';
+import type { ReactElement } from 'react';
+import { MemoryRouter } from 'react-router';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+
+import { AppShell } from '../../src/components/AppShell';
+import { SkipToContent } from '../../src/components/SkipToContent';
+import { ThemeProvider } from '../../src/contexts/ThemeContext';
+
+function render(ui: ReactElement, options?: Omit<RenderOptions, 'wrapper'>) {
+  return baseRender(ui, { wrapper: ThemeProvider, ...options });
+}
+
+let matchMediaMatches = false;
+beforeAll(() => {
+  Object.defineProperty(window, 'matchMedia', {
+    writable: true,
+    value: vi.fn().mockImplementation((query: string) => ({
+      get matches() { return matchMediaMatches; },
+      media: query,
+      onchange: null,
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  });
+});
+
+vi.mock('../../src/components/AuthProvider', () => ({
+  useAuth: () => ({
+    user: { name: 'Test User', email: 'test@example.com', image: null },
+    isSuperadmin: false,
+  }),
+}));
+
+vi.mock('../../src/lib/auth', () => ({
+  signOut: vi.fn(),
+}));
+
+vi.mock('../../src/hooks/useProjectData', () => ({
+  useProjectList: () => ({ projects: [], loading: false }),
+}));
+
+vi.mock('../../src/components/GlobalAudioPlayer', () => ({
+  GlobalAudioPlayer: () => null,
+}));
+
+describe('SkipToContent component', () => {
+  it('renders a skip link pointing to #main-content', () => {
+    render(
+      <MemoryRouter>
+        <SkipToContent />
+      </MemoryRouter>,
+    );
+    const link = screen.getByText('Skip to content');
+    expect(link).toBeDefined();
+    expect(link.tagName).toBe('A');
+    expect(link.getAttribute('href')).toBe('#main-content');
+  });
+
+  it('has sr-only class by default (visually hidden until focused)', () => {
+    render(
+      <MemoryRouter>
+        <SkipToContent />
+      </MemoryRouter>,
+    );
+    const link = screen.getByText('Skip to content');
+    expect(link.className).toContain('sr-only');
+  });
+});
+
+describe('AppShell accessibility', () => {
+  it('renders a skip-to-content link on desktop', () => {
+    matchMediaMatches = true;
+    render(
+      <MemoryRouter>
+        <AppShell />
+      </MemoryRouter>,
+    );
+    const links = screen.getAllByText('Skip to content');
+    expect(links.length).toBeGreaterThanOrEqual(1);
+    expect(links[0].getAttribute('href')).toBe('#main-content');
+  });
+
+  it('renders a skip-to-content link on mobile', () => {
+    matchMediaMatches = false;
+    render(
+      <MemoryRouter>
+        <AppShell />
+      </MemoryRouter>,
+    );
+    const links = screen.getAllByText('Skip to content');
+    expect(links.length).toBeGreaterThanOrEqual(1);
+    expect(links[0].getAttribute('href')).toBe('#main-content');
+  });
+
+  it('renders main element with id="main-content" on desktop', () => {
+    matchMediaMatches = true;
+    render(
+      <MemoryRouter>
+        <AppShell />
+      </MemoryRouter>,
+    );
+    const main = document.getElementById('main-content');
+    expect(main).not.toBeNull();
+    expect(main?.tagName).toBe('MAIN');
+  });
+
+  it('renders main element with id="main-content" on mobile', () => {
+    matchMediaMatches = false;
+    render(
+      <MemoryRouter>
+        <AppShell />
+      </MemoryRouter>,
+    );
+    const main = document.getElementById('main-content');
+    expect(main).not.toBeNull();
+    expect(main?.tagName).toBe('MAIN');
+  });
+});