refactor(a11y): one component per file, UnoCSS over CSS, stories for all

- Split the multi-component files (header/violations/icons/summary/fix-prompts)
  into one component per file: Header, MetaLine, Summary, SummaryBar, Switch,
  EmptyState, ViolationRow, RouteGroup, ViolationList, FixPromptsDialog. Shared
  view types + helpers move to lib/violation-view.ts.
- Replace the ~920-line bespoke styles.css with UnoCSS utilities built on
  @antfu/design semantic tokens (bg-base/color-muted/border-base/…). The one
  domain color (WCAG severity) rides an inline --impact CSS var consumed by
  arbitrary-value utilities. styles.css now only carries the root reset,
  scrollbar, and reduced-motion guard.
- Add a Storybook story for every component.

Co-authored-with an agent.

Author: antfubot

plugins/a11y/src/spa/app.tsx

@@ -1,15 +1,17 @@
 import type { Impact, PinTarget, Violation, ViolationNode } from '../shared/protocol.ts'
-import type { SelectedItem } from './components/fix-prompts.tsx'
-import type { RouteGroupModel, SelectionApi } from './components/violations.tsx'
+import type { SelectedItem } from './lib/fix-prompt.ts'
+import type { RouteGroupModel, SelectionApi } from './lib/violation-view.ts'
 import { batch, createEffect, createMemo, createSignal, Match, on, Show, Switch } from 'solid-js'
 import { emptyCounts } from '../shared/protocol.ts'
-import { FixPromptsDialog } from './components/fix-prompts.tsx'
-import { Header, MetaLine } from './components/header.tsx'
-import { CheckCircle, PlugIcon } from './components/icons.tsx'
-import { SummaryBar } from './components/summary.tsx'
-import { ruleCardId, ViolationList } from './components/violations.tsx'
+import { EmptyState } from './components/EmptyState.tsx'
+import { FixPromptsDialog } from './components/FixPromptsDialog.tsx'
+import { Header } from './components/Header.tsx'
+import { MetaLine } from './components/MetaLine.tsx'
+import { SummaryBar } from './components/SummaryBar.tsx'
+import { ViolationList } from './components/ViolationList.tsx'
 import { createA11yChannel } from './lib/channel.ts'
 import { connectDevframeState } from './lib/devframe.ts'
+import { ruleCardId } from './lib/violation-view.ts'
 
 const SNIPPET = '<script type="module" src="…/inject.js"></script>'
 const AUTOSCAN_KEY = 'devframes:plugin:a11y:autoscan'
@@ -223,7 +225,7 @@ export function App() {
 
     // A dashboard/summary activation (or one with no target) just scrolls to top.
     if (params.tab === 'dashboard' || !route) {
-      document.querySelector('.scroll')?.scrollTo({ top: 0, behavior: 'smooth' })
+      document.querySelector('#a11y-scroll')?.scrollTo({ top: 0, behavior: 'smooth' })
       return
     }
 
@@ -270,7 +272,7 @@ export function App() {
   }
 
   return (
-    <div class="app">
+    <div class="flex flex-col h-full min-h-0 bg-base color-base font-sans">
       <Header
         agentReady={channel.agentReady()}
         scanning={channel.scanning()}
@@ -280,48 +282,42 @@ export function App() {
       />
       <MetaLine
         url={activeReport()?.url}
-        route={activeReport()?.route}
         engine={engine()}
         backend={devframe.backend}
         status={devframe.status}
       />
 
-      <p class="visually-hidden" aria-live="polite">{announce()}</p>
+      <p class="sr-only" aria-live="polite">{announce()}</p>
 
-      <div class="scroll">
+      <div id="a11y-scroll" class="a11y-scroll flex-1 min-h-0 overflow-y-auto px-4 pb-5">
         <Switch>
           {/* No agent has announced itself on this origin yet. */}
           <Match when={!channel.state() && !channel.agentReady()}>
-            <div class="state">
-              <PlugIcon class="state__glyph" />
-              <p class="state__title">No page connected</p>
-              <p class="state__body">
-                Load the inspector agent in the app you want to check, then this
-                panel will list its accessibility issues live.
-              </p>
-              <code class="state__code">{SNIPPET}</code>
-            </div>
+            <EmptyState
+              icon="i-ph-plugs-duotone text-4xl"
+              title="No page connected"
+              body="Load the inspector agent in the app you want to check, then this panel will list its accessibility issues live."
+              code={SNIPPET}
+            />
           </Match>
 
           {/* Agent present, first state not in yet. */}
           <Match when={!channel.state()}>
-            <div class="state">
-              <PlugIcon class="state__glyph" />
-              <p class="state__title">Scanning the page…</p>
-              <p class="state__body">Running axe-core against the connected document.</p>
-            </div>
+            <EmptyState
+              icon="i-ph-plugs-duotone text-4xl"
+              title="Scanning the page…"
+              body="Running axe-core against the connected document."
+            />
           </Match>
 
           {/* Report in, nothing to flag. */}
           <Match when={totalFilterable() === 0}>
-            <div class="state state--clean">
-              <CheckCircle class="state__glyph" />
-              <p class="state__title">No violations</p>
-              <p class="state__body">
-                axe-core found nothing to flag across the tracked routes. Re-run
-                after changes to keep it that way.
-              </p>
-            </div>
+            <EmptyState
+              clean
+              icon="i-ph-check-circle-duotone text-4xl"
+              title="No violations"
+              body="axe-core found nothing to flag across the tracked routes. Re-run after changes to keep it that way."
+            />
           </Match>
 
           {/* Single page: summary band + grouped violations. */}
@@ -344,16 +340,19 @@ export function App() {
             <Show
               when={shownViolations() > 0}
               fallback={(
-                <div class="state">
-                  <CheckCircle class="state__glyph" />
-                  <p class="state__title">Nothing matches the filter</p>
-                  <p class="state__body">
-                    {totalFilterable()}
-                    {' '}
-                    {totalFilterable() === 1 ? 'rule' : 'rules'}
-                    {' at other severities. Clear the filter to see them.'}
-                  </p>
-                </div>
+                <EmptyState
+                  clean
+                  icon="i-ph-check-circle-duotone text-4xl"
+                  title="Nothing matches the filter"
+                  body={(
+                    <>
+                      {totalFilterable()}
+                      {' '}
+                      {totalFilterable() === 1 ? 'rule' : 'rules'}
+                      {' at other severities. Clear the filter to see them.'}
+                    </>
+                  )}
+                />
               )}
             >
               <ViolationList

plugins/a11y/src/spa/components/EmptyState.stories.tsx

@@ -0,0 +1,38 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite'
+import { EmptyState } from './EmptyState.tsx'
+
+// The centered full-height message shown when there's nothing to list.
+const meta = {
+  title: 'A11y/EmptyState',
+  component: EmptyState,
+  parameters: { layout: 'fullscreen' },
+} satisfies Meta<typeof EmptyState>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const NoPage: Story = {
+  args: {
+    icon: 'i-ph-plugs-duotone text-4xl',
+    title: 'No page connected',
+    body: 'Load the inspector agent in the app you want to check, then this panel will list its accessibility issues live.',
+    code: '<script type="module" src="…/inject.js"></script>',
+  },
+}
+
+export const Scanning: Story = {
+  args: {
+    icon: 'i-ph-plugs-duotone text-4xl',
+    title: 'Scanning the page…',
+    body: 'Running axe-core against the connected document.',
+  },
+}
+
+export const Clean: Story = {
+  args: {
+    clean: true,
+    icon: 'i-ph-check-circle-duotone text-4xl',
+    title: 'No violations',
+    body: 'axe-core found nothing to flag across the tracked routes.',
+  },
+}

plugins/a11y/src/spa/components/EmptyState.tsx

@@ -0,0 +1,32 @@
+import type { JSX } from 'solid-js'
+import { Show } from 'solid-js'
+
+interface EmptyStateProps {
+  /** Icon utility class (with its own size), e.g. `i-ph-plugs-duotone text-4xl`. */
+  icon: string
+  title: string
+  body: JSX.Element
+  /** Tints the glyph success-green for the "all clear" case. */
+  clean?: boolean
+  /** Optional code snippet shown below the body. */
+  code?: string
+}
+
+/**
+ * The centered full-height message shown when there's nothing to list: no page
+ * connected, scanning, all-clear, or filtered-to-empty.
+ */
+export function EmptyState(props: EmptyStateProps) {
+  return (
+    <div class="flex flex-col items-center justify-center gap-3 h-full p-8 text-center color-muted">
+      <span aria-hidden class={`${props.icon} ${props.clean ? 'text-success' : 'color-faint'}`} />
+      <p class="text-[15px] font-semibold color-base">{props.title}</p>
+      <p class="text-xs leading-relaxed max-w-[38ch]">{props.body}</p>
+      <Show when={props.code}>
+        <code class="font-mono text-[11.5px] color-muted bg-secondary border border-base rounded-lg px-3 py-2.5 whitespace-pre-wrap break-all text-left max-w-full">
+          {props.code}
+        </code>
+      </Show>
+    </div>
+  )
+}

plugins/a11y/src/spa/components/FixPromptsDialog.stories.tsx

@@ -0,0 +1,22 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite'
+import type { SelectedItem } from './FixPromptsDialog.tsx'
+import { makeViolation } from './_fixtures.ts'
+import { FixPromptsDialog } from './FixPromptsDialog.tsx'
+
+// The fix-prompts dialog: gathers the selected violations' context into one
+// paste-ready AI prompt, with a copy button.
+const meta = {
+  title: 'A11y/FixPromptsDialog',
+  component: FixPromptsDialog,
+  parameters: { layout: 'fullscreen' },
+} satisfies Meta<typeof FixPromptsDialog>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+const items: SelectedItem[] = [
+  { route: '/', url: 'https://example.test/', violation: makeViolation('image-alt', 'critical', 1) },
+  { route: '/forms', url: 'https://example.test/forms', violation: makeViolation('label', 'serious', 1) },
+]
+
+export const TwoViolations: Story = { args: { items, onClose: () => {} } }

…/a11y/src/spa/components/fix-prompts.tsx …/src/spa/components/FixPromptsDialog.tsxplugins/a11y/src/spa/components/fix-prompts.tsx renamed to plugins/a11y/src/spa/components/FixPromptsDialog.tsx plugins/a11y/src/spa/components/fix-prompts.tsx renamed to plugins/a11y/src/spa/components/FixPromptsDialog.tsx

@@ -1,10 +1,11 @@
 import type { SelectedItem } from '../lib/fix-prompt.ts'
 import { createMemo, createSignal, For, onCleanup, onMount, Show } from 'solid-js'
+import { button } from '../design'
 import { buildFixPrompt } from '../lib/fix-prompt.ts'
 
 export type { SelectedItem } from '../lib/fix-prompt.ts'
 
-interface DialogProps {
+interface FixPromptsDialogProps {
   items: SelectedItem[]
   onClose: () => void
 }
@@ -14,7 +15,7 @@ interface DialogProps {
  * button. Built to the same accessibility bar the tool enforces: labelled
  * dialog, Escape/backdrop to close, focus moved in on open.
  */
-export function FixPromptsDialog(props: DialogProps) {
+export function FixPromptsDialog(props: FixPromptsDialogProps) {
   const prompt = createMemo(() => buildFixPrompt(props.items))
   const ruleCount = () => props.items.length
   const [copied, setCopied] = createSignal(false)
@@ -39,45 +40,45 @@ export function FixPromptsDialog(props: DialogProps) {
   onCleanup(() => removeEventListener('keydown', onKeyDown))
 
   return (
-    <div class="modal" onClick={() => props.onClose()}>
+    <div class="fixed inset-0 z-modal-content flex items-center justify-center p-6 bg-black/55 backdrop-blur-sm" onClick={() => props.onClose()}>
       <div
-        class="modal__card"
+        class="flex flex-col gap-3 w-[min(680px,100%)] max-h-full p-4 bg-secondary border border-base rounded-xl shadow-2xl"
         role="dialog"
         aria-modal="true"
         aria-labelledby="fix-prompts-title"
         onClick={e => e.stopPropagation()}
       >
-        <div class="modal__head">
+        <div class="flex items-start gap-2.5">
           <div>
-            <h2 id="fix-prompts-title" class="modal__title">Fix prompts</h2>
-            <p class="modal__sub">
+            <h2 id="fix-prompts-title" class="m-0 text-[15px] font-semibold color-base">Fix prompts</h2>
+            <p class="mt-0.5 text-xs color-muted">
               {ruleCount()}
               {' '}
               {ruleCount() === 1 ? 'violation' : 'violations'}
               {' '}
               selected — copy the prompt into your AI assistant.
             </p>
           </div>
-          <button type="button" ref={closeBtn} class="modal__close" aria-label="Close" onClick={() => props.onClose()}>
+          <button type="button" ref={closeBtn} class="ml-auto inline-flex p-1.5 rounded color-muted cursor-pointer transition hover:bg-active hover:color-base outline-none focus-visible:ring-2 focus-visible:ring-primary-500/40" aria-label="Close" onClick={() => props.onClose()}>
             <span aria-hidden class="i-ph-x shrink-0" />
           </button>
         </div>
 
-        <textarea class="modal__text" readonly aria-label="Generated fix prompt">{prompt()}</textarea>
+        <textarea class="flex-1 min-h-60 resize-none w-full p-3 bg-base border border-base rounded-lg font-mono text-[11.5px] leading-relaxed color-base whitespace-pre overflow-auto outline-none focus-visible:ring-2 focus-visible:ring-primary-500/40" readonly aria-label="Generated fix prompt">{prompt()}</textarea>
 
-        <div class="modal__actions">
-          <span class="modal__hint">
+        <div class="flex items-center gap-2.5">
+          <span class="min-w-0 truncate text-[11px] color-faint">
             <For each={props.items}>
               {(item, i) => (
                 <>
                   <Show when={i() > 0}>{', '}</Show>
-                  <code>{item.violation.ruleId}</code>
+                  <code class="font-mono">{item.violation.ruleId}</code>
                 </>
               )}
             </For>
           </span>
           <span class="flex-1" />
-          <button type="button" class="modal__btn" onClick={copy}>
+          <button type="button" class={button({ variant: 'primary', size: 'sm' })} onClick={copy}>
             <span aria-hidden class={`shrink-0 ${copied() ? 'i-ph-check' : 'i-ph-copy'}`} />
             {copied() ? 'Copied' : 'Copy prompt'}
           </button>

plugins/a11y/src/spa/components/Header.stories.tsx

@@ -0,0 +1,20 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite'
+import { Header } from './Header.tsx'
+
+// The top nav bar: brand, connection status dot, generate-prompts, and rescan.
+const meta = {
+  title: 'A11y/Header',
+  component: Header,
+  parameters: { layout: 'fullscreen' },
+} satisfies Meta<typeof Header>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+function noop() {}
+const base = { selectedCount: 0, onGenerate: noop, onRescan: noop }
+
+export const Connected: Story = { args: { ...base, agentReady: true, scanning: false } }
+export const Scanning: Story = { args: { ...base, agentReady: true, scanning: true } }
+export const WithSelection: Story = { args: { ...base, agentReady: true, scanning: false, selectedCount: 3 } }
+export const Disconnected: Story = { args: { ...base, agentReady: false, scanning: false } }

plugins/a11y/src/spa/components/Header.tsx

@@ -0,0 +1,56 @@
+import { Show } from 'solid-js'
+import { button, nav, navBrand } from '../design'
+
+interface HeaderProps {
+  agentReady: boolean
+  scanning: boolean
+  selectedCount: number
+  onGenerate: () => void
+  onRescan: () => void
+}
+
+/** The top nav bar: brand, connection status, generate-prompts, and rescan. */
+export function Header(props: HeaderProps) {
+  const statusLabel = () =>
+    !props.agentReady ? 'No page connected' : props.scanning ? 'Scanning…' : 'Connected'
+  const dotClass = () =>
+    !props.agentReady ? 'bg-neutral-400' : props.scanning ? 'bg-primary-500 animate-pulse' : 'bg-success'
+
+  return (
+    <header class={nav()}>
+      <span class={navBrand()}>
+        <span aria-hidden class="i-ph-person-simple-circle-duotone text-base color-active" />
+        <span>A11y Inspector</span>
+      </span>
+      <span class="flex-1" />
+      <span class="inline-flex items-center gap-1.5 text-xs color-muted select-none">
+        <span class={`size-2 rounded-full shrink-0 ${dotClass()}`} />
+        {statusLabel()}
+      </span>
+      <button
+        type="button"
+        class={button({ variant: 'secondary', size: 'sm' })}
+        onClick={() => props.onGenerate()}
+        disabled={props.selectedCount === 0}
+        title="Generate AI fix prompts for the selected violations"
+      >
+        <span aria-hidden class="i-ph-sparkle-duotone shrink-0" />
+        Generate fix prompts
+        <Show when={props.selectedCount > 0}>
+          <span class="inline-flex items-center justify-center min-w-4 h-4 px-1 rounded-full bg-active text-[10px] font-bold tabular-nums">
+            {props.selectedCount}
+          </span>
+        </Show>
+      </button>
+      <button
+        type="button"
+        class={button({ variant: 'primary', size: 'sm' })}
+        onClick={() => props.onRescan()}
+        disabled={!props.agentReady || props.scanning}
+      >
+        <span aria-hidden class="i-ph-arrows-clockwise shrink-0" classList={{ 'animate-spin': props.scanning }} />
+        Rescan
+      </button>
+    </header>
+  )
+}