create-top-secret-starter 0.13.0 → 0.15.0

package/backend-overlay/web/src/components/sidebar-user.tsx

@@ -0,0 +1,33 @@
+import { Link } from '@tanstack/react-router'
+
+import { useSession } from '@/api/auth'
+import { SidebarMenuButton, useSidebar } from '@/components/ui/sidebar'
+
+const initialsOf = (email: string) => email.slice(0, 2).toUpperCase()
+
+// the account row in the sidebar footer, reading the Better Auth session
+export const SidebarUser = () => {
+  const { data: session } = useSession()
+  const { isMobile, setOpenMobile } = useSidebar()
+  if (!session) return null
+
+  const { email } = session.user
+  return (
+    <SidebarMenuButton
+      size='lg'
+      tooltip={email}
+      render={<Link to='/' onClick={() => isMobile && setOpenMobile(false)} />}
+    >
+      <span
+        aria-hidden='true'
+        className='flex size-8 shrink-0 items-center justify-center rounded-lg bg-sidebar-accent text-xs font-medium text-sidebar-accent-foreground'
+      >
+        {initialsOf(email)}
+      </span>
+      <span className='flex min-w-0 flex-col leading-tight'>
+        <span className='truncate text-xs text-muted-foreground'>Signed in as</span>
+        <span className='truncate font-medium'>{email}</span>
+      </span>
+    </SidebarMenuButton>
+  )
+}

package/backend-overlay/web-router/src/routes/sign-in.tsx

@@ -16,13 +16,26 @@ const SignInFormSchema = z.object({
 })
 
 const FIELDS = [
-  { name: 'email', label: 'Email', type: 'email', autoComplete: 'email' },
-  { name: 'password', label: 'Password', type: 'password', autoComplete: 'current-password' }
+  {
+    name: 'email',
+    label: 'Email',
+    type: 'email',
+    autoComplete: 'email',
+    placeholder: 'you@example.com'
+  },
+  {
+    name: 'password',
+    label: 'Password',
+    type: 'password',
+    autoComplete: 'current-password',
+    placeholder: '••••••••'
+  }
 ] as const satisfies ReadonlyArray<{
   name: keyof SignInInput
   label: string
   type: string
   autoComplete: string
+  placeholder: string
 }>
 
 export const Route = createFileRoute('/sign-in')({
@@ -61,6 +74,7 @@ function SignInPage() {
                   id={field.name}
                   type={field.type}
                   autoComplete={field.autoComplete}
+                  placeholder={field.placeholder}
                   aria-invalid={Boolean(error)}
                   aria-describedby={error ? `${field.name}-error` : undefined}
                   {...register(field.name)}

package/backend-overlay/web-router/src/routes/sign-up.tsx

@@ -18,14 +18,27 @@ const SignUpFormSchema = z.object({
 })
 
 const FIELDS = [
-  { name: 'name', label: 'Name', type: 'text', autoComplete: 'name' },
-  { name: 'email', label: 'Email', type: 'email', autoComplete: 'email' },
-  { name: 'password', label: 'Password', type: 'password', autoComplete: 'new-password' }
+  { name: 'name', label: 'Name', type: 'text', autoComplete: 'name', placeholder: 'Ada Lovelace' },
+  {
+    name: 'email',
+    label: 'Email',
+    type: 'email',
+    autoComplete: 'email',
+    placeholder: 'you@example.com'
+  },
+  {
+    name: 'password',
+    label: 'Password',
+    type: 'password',
+    autoComplete: 'new-password',
+    placeholder: 'At least 8 characters'
+  }
 ] as const satisfies ReadonlyArray<{
   name: keyof SignUpInput
   label: string
   type: string
   autoComplete: string
+  placeholder: string
 }>
 
 export const Route = createFileRoute('/sign-up')({
@@ -64,6 +77,7 @@ function SignUpPage() {
                   id={field.name}
                   type={field.type}
                   autoComplete={field.autoComplete}
+                  placeholder={field.placeholder}
                   aria-invalid={Boolean(error)}
                   aria-describedby={error ? `${field.name}-error` : undefined}
                   {...register(field.name)}

package/backend-overlay/web-start/src/routes/sign-in.tsx

@@ -17,13 +17,26 @@ const SignInFormSchema = z.object({
 })
 
 const FIELDS = [
-  { name: 'email', label: 'Email', type: 'email', autoComplete: 'email' },
-  { name: 'password', label: 'Password', type: 'password', autoComplete: 'current-password' }
+  {
+    name: 'email',
+    label: 'Email',
+    type: 'email',
+    autoComplete: 'email',
+    placeholder: 'you@example.com'
+  },
+  {
+    name: 'password',
+    label: 'Password',
+    type: 'password',
+    autoComplete: 'current-password',
+    placeholder: '••••••••'
+  }
 ] as const satisfies ReadonlyArray<{
   name: keyof SignInInput
   label: string
   type: string
   autoComplete: string
+  placeholder: string
 }>
 
 export const Route = createFileRoute('/sign-in')({
@@ -65,6 +78,7 @@ function SignInPage() {
                   id={field.name}
                   type={field.type}
                   autoComplete={field.autoComplete}
+                  placeholder={field.placeholder}
                   aria-invalid={Boolean(error)}
                   aria-describedby={error ? `${field.name}-error` : undefined}
                   {...register(field.name)}

package/backend-overlay/web-start/src/routes/sign-up.tsx

@@ -19,14 +19,27 @@ const SignUpFormSchema = z.object({
 })
 
 const FIELDS = [
-  { name: 'name', label: 'Name', type: 'text', autoComplete: 'name' },
-  { name: 'email', label: 'Email', type: 'email', autoComplete: 'email' },
-  { name: 'password', label: 'Password', type: 'password', autoComplete: 'new-password' }
+  { name: 'name', label: 'Name', type: 'text', autoComplete: 'name', placeholder: 'Ada Lovelace' },
+  {
+    name: 'email',
+    label: 'Email',
+    type: 'email',
+    autoComplete: 'email',
+    placeholder: 'you@example.com'
+  },
+  {
+    name: 'password',
+    label: 'Password',
+    type: 'password',
+    autoComplete: 'new-password',
+    placeholder: 'At least 8 characters'
+  }
 ] as const satisfies ReadonlyArray<{
   name: keyof SignUpInput
   label: string
   type: string
   autoComplete: string
+  placeholder: string
 }>
 
 export const Route = createFileRoute('/sign-up')({
@@ -68,6 +81,7 @@ function SignUpPage() {
                   id={field.name}
                   type={field.type}
                   autoComplete={field.autoComplete}
+                  placeholder={field.placeholder}
                   aria-invalid={Boolean(error)}
                   aria-describedby={error ? `${field.name}-error` : undefined}
                   {...register(field.name)}

package/features.json

@@ -6,6 +6,7 @@
     "off": {
       "remove": [
         "src/components/app-sidebar.tsx",
+        "src/components/sidebar-user.tsx",
         "src/components/app-shell.tsx",
         "src/components/ui/sidebar.tsx",
         "src/components/ui/sheet.tsx",
@@ -26,7 +27,6 @@
         "src/components/orders",
         "src/mocks/orders.ts",
         "src/components/ui/table.tsx",
-        "src/components/ui/dialog.tsx",
         "src/components/ui/dropdown-menu.tsx",
         "src/components/ui/select.tsx",
         "e2e/orders.spec.ts"

package/index.js

@@ -23,7 +23,10 @@ const BACKEND_WEB_DEPS = { '@elysia/eden': '^1.4.10', 'better-auth': '^1.7.3' }
 // optional example features; features.json lists what each one removes when it is off
 const FEATURES = {
   sidebar: { label: 'Sidebar shell', hint: 'collapsible nav, ⌘B, state persisted' },
-  table: { label: 'Orders table', hint: 'TanStack Table, URL-synced filters and sorting' },
+  table: {
+    label: 'Orders table',
+    hint: 'TanStack Table, URL-synced sorting, pin and drag columns'
+  },
   realtime: { label: 'Live dashboard', hint: 'WebSocket metrics feed, recharts' }
 }
 const FEATURE_IDS = Object.keys(FEATURES)
@@ -245,11 +248,10 @@ const substitute = (file, pairs) =>
       return text.replaceAll(from, to)
     }, source)
   )
-// the project name lands in the document title/description and the demo home page
+// the project name lands in the document title/description and the sidebar brand
 const nameTargets = base => [
   path.join(base, 'index.html'),
   path.join(base, 'src', 'site.ts'),
-  path.join(base, 'src', 'routes', '_authenticated', 'index.tsx'),
   path.join(base, 'src', 'components', 'app-sidebar.tsx')
 ]
 const applyName = files => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-top-secret-starter",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Scaffold a Vite + React 19 + TypeScript + shadcn starter with TanStack Router",
   "keywords": [
     "create",

package/templates/template-router/.claude/skills/better-accessibility/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: better-accessibility
+description: Helps your project comply with accessibility standards and best practices.
+---
+
+# Accessibility
+
+Most accessibility is free if you use the platform. Native elements ship with keyboard support, real labels announce themselves and a visible focus ring is one CSS rule.
+
+Write every fix in the project's styling system, and use the exact values below rather than familiar-looking substitutes.
+
+Reviewing means two walks. Keyboard-only, where every flow completes without a mouse. Then screen-reader, where every control announces a name, a role and its state. When unsure, take the platform default over a custom rebuild, and remove ARIA rather than add it.
+
+Contrast measurement and color fixes belong to `better-colors`. Text sizing and iOS input zoom belong to `better-typography`. Spatial RTL layout belongs to `better-layout`.
+
+## Native elements first
+
+The first rule of ARIA: don't use ARIA when a native element exists. `<button>` for actions, `<a href>` for navigation, never `<div onClick>`. A real link must support Cmd/Ctrl/middle-click. No ARIA is better than bad ARIA. See [semantics-and-aria.md](semantics-and-aria.md) for landmarks, button-vs-link and disabled states.
+
+## Visible focus rings
+
+Style `:focus-visible`, not bare `:focus`. Keyboard users get a ring and mouse users usually don't. Prefer the browser's unmodified indicator.
+
+A custom ring needs a project focus token or another explicit color. Verify the whole indicator against every adjacent color it crosses, `currentColor` included. Use at least a `2px` solid perimeter or an equivalent visible area. Never use `outline: none` without a verified replacement, and preserve system colors in forced-colors mode. Recipes are in [focus-and-keyboard.md](focus-and-keyboard.md).
+
+## Full keyboard support
+
+Every pointer interaction needs a keyboard path. Follow the ARIA APG patterns: Escape closes overlays, arrow keys move within composite widgets, Tab moves between widgets, Enter and Space activate.
+
+Use only `tabindex="0"` to join the natural tab order and `tabindex="-1"` for programmatic focus. Positive values break that order. Composite widgets use roving tabindex, where the active item is `0` and every other is `-1`.
+
+## Trap and restore focus
+
+Modals set `inert` on the background content, move focus inside on open and return focus to the trigger on close. Add `overscroll-behavior: contain` so background content doesn't scroll.
+
+## Minimum hit area
+
+WCAG 2.5.8's Level AA baseline is a 24×24 CSS-pixel target, or one of its spacing, equivalent-control, inline, user-agent and essential exceptions. Aim for 44×44px on touch and 40×40px on desktop where density permits. Extend with a pseudo-element when the visible element should stay smaller.
+
+Never let extended hit areas overlap. Give decorative layers `pointer-events: none`, so a glow never swallows the clicks meant for the control beneath it. Sizes and collision rules are in [hit-areas.md](hit-areas.md).
+
+## Label and type every control
+
+Every input gets a `<label for>` or a wrapping `<label>`. A placeholder is never a label. Label and control share one hit target, with no dead zone between a checkbox and its text.
+
+Add `autocomplete` with a meaningful `name`, plus the `type` and `inputmode` that summon the right keyboard. Never block paste; users paste passwords and one-time codes. See [forms.md](forms.md).
+
+## Errors that announce
+
+Keep submit enabled until the request starts, then disable with a spinner and the original label. Validate on submit. Mark failing fields `aria-invalid="true"`, point `aria-describedby` at the inline error text and focus the first invalid field.
+
+Use native `disabled` when a control is genuinely unavailable. Reach for `aria-disabled="true"` only when it should stay focusable, then block pointer, keyboard and form behavior in code and style the state explicitly.
+
+## Accessible names everywhere
+
+Icon-only buttons need a descriptive `aria-label`. Visible label text must appear in the accessible name. Decorative elements get `aria-hidden="true"`, never on a focusable element.
+
+## Don't rely on color alone
+
+Status needs a redundant cue: an icon, text, or an underline alongside the color. Work out which WCAG contrast requirement applies, then use `better-colors` to measure the rendered pair. When it fails, report the pair and the requirement it misses, and leave the colors alone unless asked.
+
+## Honor prefers-reduced-motion
+
+Wrap motion in `@media (prefers-reduced-motion: no-preference)` so it is opt-in. Under reduced motion, replace slides and scales with opacity crossfades, and kill parallax and autoplay entirely.
+
+Two rules hold regardless of the preference. Autoplaying media needs a visible pause control, and toasts carrying an action or an error stay until dismissed. See [motion-and-zoom.md](motion-and-zoom.md).
+
+## Announce dynamic content
+
+Three mechanisms, three jobs. `aria-describedby` carries field-specific validation. A polite live region (`role="status"`) carries non-urgent updates not tied to a control, such as toasts and result counts. `role="alert"` carries urgent untied errors and nothing else.
+
+Repeated polite announcements need a stable empty region rendered before its text updates. Dynamically inserted alerts vary in support, so test them on the screen readers you target. See [screen-readers.md](screen-readers.md).
+
+## Alt text by purpose
+
+Decorative images get `alt=""`. Informative images describe the meaning. Functional images describe the action: a search icon button is `alt="Search"`, not `alt="magnifying glass"`.
+
+## Structure is navigation
+
+Use headings that describe their sections and form a coherent outline. Give the page one `<h1>` and nest the levels below it without skipping. Expose one visible primary `<main>` landmark. When repeated navigation or chrome precedes it, make a "Skip to content" link the first focusable element. Anchored headings get `scroll-margin-top`.
+
+## Survive zoom and text resize
+
+The page must work at 200% zoom and reflow at 320px width without horizontal scrolling. Use `min-height` rather than fixed `height` on text containers. Prefer `rem` breakpoints where they fit the codebase, and never let the viewport meta cap how far the reader can zoom.
+
+## Before you finish
+
+| Mistake | Fix |
+| --- | --- |
+| Custom focus color assumed to work everywhere | Verify it against every adjacent color and in forced-colors mode |
+| Repeated polite update inconsistently announced | Keep a stable empty status region and update its text |
+| `assertive` live region for a routine toast | Use `polite`; reserve `assertive` for errors |
+| `aria-hidden="true"` on a focusable element | Remove it or make the element non-focusable |
+| Submit disabled until the form is valid | Keep it enabled; validate on submit and focus the first error |
+| Hover treatment stuck after a tap on touch | Gate hover styling with `@media (hover: hover)` |
+| Tooltip on a natively `disabled` control | Text beside it, or `aria-disabled` so it stays focusable |
+
+## Reporting
+
+**Severity.** `HIGH` prevents a task, hides content from assistive technology, or creates a systemic failure. `MEDIUM` makes an interaction meaningfully harder. `LOW` is isolated polish.
+
+**Verification.** Without a browser: accessible names on every interactive element, keyboard handlers on non-native controls, focus styles, `prefers-reduced-motion` guards and form labels bound to their inputs. With one: tab the flow in order, read computed names and roles from the accessibility tree, confirm a visible focus indicator at every stop and run an automated audit. Report every check you could not run as `Not verified`.
+
+**Format.** Group findings under the principle each violates, ordered by severity, one row per root cause listing every location it appears in:
+
+| Severity | Location | Before | After | Why |
+| --- | --- | --- | --- | --- |
+
+`Location` is `path/to/file:line`. `Why` names the principle and the user impact.
+
+End with `Block` when any `HIGH` remains, `Approve` otherwise, leaving the rest in the table as work to do. Never `Approve` coverage you did not inspect. With nothing to report, state "No actionable accessibility findings" and report verification.

package/templates/template-router/.claude/skills/better-accessibility/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Better Accessibility"
+  short_description: "Focus, keyboard, ARIA, forms and screen readers"

package/templates/template-router/.claude/skills/better-accessibility/focus-and-keyboard.md

@@ -0,0 +1,131 @@
+# Focus and keyboard
+
+Focus rings, skip links, tabindex, focus trapping and the APG keyboard patterns.
+
+## Focus rings
+
+Style `:focus-visible`, not bare `:focus`. The browser shows it for keyboard and assistive-tech focus and suppresses it for mouse clicks, where focus is already obvious. Never write `outline: none` or `focus:outline-none` without a visible replacement, which removes keyboard navigation for sighted keyboard users.
+
+Prefer the browser's unmodified focus indicator, which adapts to platform and forced-color settings without the author predicting every background. Adding only `outline-offset` preserves it. A custom `outline: 2px solid` with no color renders `currentColor`, which is not automatically accessible, because the outline may cross colors unlike the text's own background. The preference order:
+
+```css
+/* Best: keep the browser ring, just give it breathing room */
+:focus-visible {
+  outline-offset: 2px;
+}
+
+/* Custom ring when the design requires one: use the project's verified token */
+:focus-visible {
+  outline: 2px solid var(--focus-ring);
+  outline-offset: 2px;
+}
+```
+
+```tsx
+// Tailwind: use the project's focus token or established focus-ring utility
+<button className="focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--focus-ring)]">
+  Save
+</button>
+```
+
+A custom focus indicator must meet the applicable project or WCAG target for visible area and change of contrast. Inspect the whole perimeter against every adjacent color it crosses: component fills, page surfaces, images, gradients, hover and selected states. A token, brand color, or `currentColor` passes only when that rendered check does.
+
+In `forced-colors: active` (Windows High Contrast), keep the default color adjustment or name a system color such as `Highlight`. `forced-color-adjust: none` freezes the authored color, so use it only where you have checked the control stays perceivable.
+
+Group focus styles with `:focus-within` when a wrapper should light up while an inner input has focus (e.g. a search box with an icon inside the border).
+
+## Skip link
+
+Target `<main id="main">` and visually hide the link until focused:
+
+```css
+.skip-link {
+  position: absolute;
+  inset-inline-start: -999px;
+}
+.skip-link:focus {
+  inset-inline-start: 16px;
+  top: 16px;
+}
+```
+
+```html
+<body>
+  <a class="skip-link" href="#main">Skip to content</a>
+  <header>…</header>
+  <main id="main">…</main>
+</body>
+```
+
+Give in-page anchor targets `scroll-margin-top`, such as `80px` under a sticky header, so the target isn't hidden when jumped to.
+
+## tabindex rules
+
+- `tabindex="0"`: adds an element to the natural tab order. Only for custom interactive elements that aren't natively focusable.
+- `tabindex="-1"`: focusable via JavaScript only (`el.focus()`). Use for headings you move focus to, modal containers and roving-tabindex members.
+- Positive `tabindex`: never. It hijacks the tab order for the whole page. Fix the DOM order instead.
+
+### Roving tabindex
+
+Composite widgets, meaning tabs, menus, toolbars and radio groups, occupy one Tab stop. The active item has `tabindex="0"`, all others `tabindex="-1"`, and arrow keys move both focus and the `0`:
+
+```tsx
+<div role="tablist">
+  {tabs.map((tab, i) => (
+    <button
+      role="tab"
+      tabIndex={i === activeIndex ? 0 : -1}
+      aria-selected={i === activeIndex}
+      onKeyDown={handleArrowKeys} // ArrowLeft/ArrowRight move activeIndex, wrapping
+    >
+      {tab.label}
+    </button>
+  ))}
+</div>
+```
+
+## Focus trapping and restoration
+
+Modals must trap focus. Put `inert` on everything behind the dialog, which removes background content from the tab order and from assistive tech in one move:
+
+```tsx
+// On open
+document.getElementById("app-content").inert = true;
+const dialog = dialogRef.current;
+(dialog.querySelector("[autofocus]") ??
+  dialog.querySelector("button, [href], input, select, textarea"))?.focus();
+
+// On close
+document.getElementById("app-content").inert = false;
+triggerRef.current?.focus(); // always return focus to the element that opened it
+```
+
+Prefer native `<dialog>` with `showModal()`, which gives you the trap, the `inert` background and Escape handling for free. A custom overlay that can't use it needs `role="dialog"`, `aria-modal="true"` and an accessible name via `aria-labelledby`. Either way:
+
+- On open, focus the first focusable element. For destructive confirmations, focus the least destructive action instead.
+- On close, return focus to the trigger, or to the nearest logical container if the trigger is gone.
+- Add `overscroll-behavior: contain` on the dialog so scrolling inside never scrolls the page behind it.
+
+## Keyboard patterns (ARIA APG)
+
+Native elements come with these behaviors; custom widgets must implement them. A role is a promise. Give something `role="tab"` and users expect the full tab keyboard model.
+
+| Widget | Keys |
+| --- | --- |
+| Dialog | Tab/Shift+Tab cycle inside (wrap at ends); Escape closes |
+| Tabs | Arrow keys move between tabs (wrapping); Tab exits to the panel; Home/End jump to first/last |
+| Menu button | Enter/Space/ArrowDown opens and focuses first item; ArrowUp opens and focuses last; arrows navigate; Escape closes and refocuses the button |
+| Disclosure / accordion | Header is a `<button aria-expanded>`; Enter and Space toggle |
+| Combobox | ArrowDown opens/moves into the list; Enter accepts; Escape closes and returns to the input; typing filters |
+| Listbox / radio group | Arrow keys move selection; one Tab stop for the whole group |
+
+Universal rules:
+
+- Escape dismisses whatever opened last: tooltip, then menu, then dialog.
+- Arrow keys, not Tab, move within a composite widget; Tab moves between widgets.
+- Tabs choose activation mode: automatic (panel switches on arrow focus) when panels render instantly, manual (Enter/Space to activate) when switching is expensive.
+- Enter submits the focused input's form. In `<textarea>`, Enter inserts a newline and ⌘/Ctrl+Enter submits.
+
+## SPA route changes
+
+Client-side navigation doesn't reset focus or announce anything. On route change, update `document.title` to match the new context, then move focus to the new view's `<h1>` (given `tabindex="-1"`) or to `<main>`. Restore scroll position on back and forward navigation, and scroll to top on forward navigation.

package/templates/template-router/.claude/skills/better-accessibility/forms.md

@@ -0,0 +1,84 @@
+# Forms
+
+Labels, autocomplete, error messaging, input types and submit behavior.
+
+## Labels
+
+Every control needs a programmatic label: `<label for>` pointing at the input's `id`, or a wrapping `<label>`. A placeholder is never a label. It disappears the moment the user types and usually fails contrast.
+
+```html
+<!-- Good: explicit association -->
+<label for="email">Email</label>
+<input id="email" type="email" autocomplete="email" />
+
+<!-- Good: wrapping label, so label and control share one hit target -->
+<label>
+  <input type="checkbox" /> Send me updates
+</label>
+```
+
+Label and control share one hit target, so clicking "Send me updates" toggles the checkbox with no dead zone between them. Mark required fields with native `required` plus a visible indicator explained once per form ("* required").
+
+A placeholder used *in addition to* a label shows an example of the expected format: `placeholder="name@company.com"`.
+
+## Error messaging
+
+The complete pattern:
+
+```html
+<label for="email">Email</label>
+<input
+  id="email"
+  type="email"
+  autocomplete="email"
+  aria-invalid="true"
+  aria-describedby="email-error"
+/>
+<p id="email-error">Enter a valid email address.</p>
+```
+
+- `aria-invalid="true"` on the failing field, removed once fixed.
+- `aria-describedby` links the field to its inline error so screen readers announce it with the field.
+- Errors render inline beside their fields, with an icon or text. Never a red border alone, which is a color-only cue.
+- On submit, focus the first invalid field.
+- Allow incomplete submission so validation can surface. Never disable submit until valid (see below).
+- Accept free text and validate after. Never block typing or filter characters as the user types. Trim values before validating, because autocomplete and text expansion add trailing spaces.
+
+## Autocomplete and input types
+
+`autocomplete` with a meaningful `name` fills forms in one tap and is a WCAG requirement (1.3.5) for fields about the user. The common tokens:
+
+| Field | `autocomplete` |
+| --- | --- |
+| Name | `name` (or `given-name` / `family-name`) |
+| Email | `email` |
+| Phone | `tel` |
+| Address | `street-address`, `address-line1`, `postal-code`, `country` |
+| Card | `cc-number`, `cc-exp`, `cc-csc`, `cc-name` |
+| Login | `username`, `current-password` |
+| Signup / reset | `new-password` |
+| 2FA code | `one-time-code` |
+
+Prefix with a section where relevant: `autocomplete="shipping street-address"`.
+
+Correct `type` and `inputmode` pick the right mobile keyboard:
+
+| Input | Use |
+| --- | --- |
+| Email, URL, phone | `type="email"`, `type="url"`, `type="tel"` |
+| OTP / PIN / card number | `type="text" inputmode="numeric"` (keeps text semantics, no spinner) |
+| Money, decimals | `type="text" inputmode="decimal"` |
+| True numeric quantity | `type="number"` |
+
+Disable spellcheck on emails, codes and usernames: `spellcheck="false"`.
+
+## Never fight the user's tools
+
+- Stay compatible with password managers and 2FA autofill: real `<form>`, correct `autocomplete`, no fake inputs.
+
+## Submit behavior
+
+- Keep submit enabled until the request starts, then disable it and show a spinner *beside the original label*. "Save" with a spinner, not a bare spinner. The label is what tells assistive tech which button is busy.
+- Announce results. Success goes through a polite live region. On failure, focus the first invalid field, which is itself the announcement. Reserve `role="alert"` for form-level errors not tied to a field ([screen-readers.md](screen-readers.md)).
+- Warn on unsaved changes before navigation, and never lose typed input to a re-render. Hydration must preserve focus and value.
+- Enter submits from any focused input; in `<textarea>`, ⌘/Ctrl+Enter submits.

package/templates/template-router/.claude/skills/better-accessibility/hit-areas.md

@@ -0,0 +1,94 @@
+# Hit areas
+
+Target sizes, expanding hit areas without changing visual size and collision rules.
+
+## Target sizes
+
+Separate the conformance baseline from larger usability targets:
+
+| Standard | Minimum |
+| --- | --- |
+| WCAG 2.5.8 (AA) | 24×24px, the hard floor |
+| WCAG 2.5.5 (AAA) | 44×44px |
+| Apple HIG | 44×44pt |
+| Material Design | 48×48dp |
+
+WCAG 2.5.8 Level AA requires a 24×24 CSS-pixel target or one of its exceptions. Treat 44px as the recommended touch target for primary controls and 40px as a useful desktop target where density permits. Smaller controls are not automatic failures. Check the spacing, equivalent-control, inline, user-agent and essential exceptions before reporting one.
+
+Under the spacing exception, an undersized target passes when a 24px circle centered on its bounding box intersects no other target and no other undersized target's circle. In the simple case, 20px targets need a 4px gap.
+
+The visible element can stay small; the hit area is what must be big. Anything that looks clickable must be clickable across its whole visual extent, with no dead zones. A checkbox and its label share one hit target.
+
+## Expanding the hit area
+
+Where the visible element is smaller, say a 20×20 checkbox, extend the hit area with a pseudo-element. Put it on the wrapping `<label>` or `<button>`, never on the `<input>`, because replaced elements don't render `::before`/`::after` reliably.
+
+### CSS example
+
+```css
+/* Small checkbox with expanded 44px hit area, on the wrapping label */
+.checkbox-label {
+  position: relative;
+  width: 20px;
+  height: 20px;
+}
+
+.checkbox-label::after {
+  content: "";
+  position: absolute;
+  top: 50%;
+  left: 50%; /* physical centering: direction-independent */
+  transform: translate(-50%, -50%);
+  width: 44px;
+  height: 44px;
+}
+```
+
+### Tailwind example
+
+```tsx
+<button className="relative size-5 after:absolute after:top-1/2 after:left-1/2 after:size-11 after:-translate-1/2">
+  <CheckIcon />
+</button>
+```
+
+### Layout alternative
+
+Where the element can afford real box size, skip the pseudo-element and let the box be the target. That hands the browser real geometry for scrolling and gestures:
+
+```css
+.icon-button {
+  min-width: 44px;
+  min-height: 44px;
+  display: inline-grid;
+  place-items: center;
+}
+```
+
+## Collision rule
+
+Where the extended hit area overlaps another interactive element, shrink the pseudo-element to the largest size that does not collide. Two interactive elements never have overlapping hit areas.
+
+## Decorative layers
+
+A decorative layer painted over interactive content absorbs every pointer event its box covers: a gradient scrim, a glow, a blurred sheen, a full-bleed `::after`. The control underneath looks live and does nothing, and no hit-area sizing fixes it.
+
+Give each one `pointer-events: none` (Tailwind `pointer-events-none`) so events reach the control below, plus `aria-hidden="true"` to keep it out of the accessibility tree:
+
+```css
+.card-glow {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+```
+
+Keep pointer events on any layer the user is meant to hit: a modal scrim that dismisses on click is a control, not decoration.
+
+## Touch behavior
+
+- Add `touch-action: manipulation` to interactive elements to remove the double-tap-to-zoom delay on mobile.
+- Set `touch-action: none` on a surface implementing its own pan, zoom, or drag gestures, so the browser stops claiming them for scrolling and pinch-zoom. Scope it to that surface; at page level it removes scrolling.
+- Set `-webkit-tap-highlight-color` to match the design instead of the default gray flash.
+- Put hover-only styling behind `@media (hover: hover)`. On touch, `:hover` latches after a tap and holds until the user taps elsewhere, so it reads as a stuck selected state. Tailwind 4's `hover:` variant already compiles under this query.
+- Prefer generous targets and clear affordances over finicky interactions such as tiny drag handles and precise hover zones.