@bompus/house-rules 0.0.0-stage → 0.13.0

package/skills/hr-benchmarking/scripts/process-attribution.ps1

@@ -0,0 +1,20 @@
+param([Parameter(Mandatory=$true)][string]$OutputPath,[Parameter(Mandatory=$true)][string]$StopPath)
+$ErrorActionPreference='Stop'
+$cpuCounter=New-Object System.Diagnostics.PerformanceCounter('Processor','% Processor Time','_Total')
+$memoryCounter=New-Object System.Diagnostics.PerformanceCounter('Memory','Available MBytes')
+$pageCounter=New-Object System.Diagnostics.PerformanceCounter('Memory','Pages Input/sec')
+$records=@()
+try {
+  [void]$cpuCounter.NextValue()
+  for($i=0;$i -lt 120;$i++) {
+    $items=@(); $missing=0
+    foreach($p in Get-Process) {
+      try { if($null -ne $p.CPU) { $items+=@{pid=$p.Id;name=$p.ProcessName;cpuSeconds=$p.CPU;started=$p.StartTime.ToUniversalTime().ToString('o')} } } catch { $missing++ }
+    }
+    $self=Get-Process -Id $PID
+    $records+=@{utc=[DateTime]::UtcNow.ToString('o');totalCpuPercent=$cpuCounter.NextValue();availableBytes=$memoryCounter.NextValue()*1MB;pagesInputPerSec=$pageCounter.NextValue();processes=$items;missingProcesses=$missing;observerCpuSeconds=$self.CPU;observerWorkingSet=$self.WorkingSet64}
+    if(Test-Path $StopPath) { break }
+    [Threading.Thread]::Sleep(1000)
+  }
+  ConvertTo-Json -InputObject $records -Depth 5 -Compress | Set-Content -LiteralPath $OutputPath -Encoding utf8
+} finally { $cpuCounter.Dispose();$memoryCounter.Dispose();$pageCounter.Dispose() }

package/skills/hr-benchmarking/scripts/process-attribution.py

@@ -0,0 +1,107 @@
+"""Finite Linux CPU attribution; does not acquire admission, stop processes or print argv."""
+import argparse
+import json
+import os
+from pathlib import Path
+import resource
+import time
+from datetime import datetime, timezone
+
+
+def read_process(stat):
+    end = stat.rfind(")")
+    fields = stat[end + 2:].split()
+    return {"name": stat[stat.find("(") + 1:end], "parentPid": int(fields[1]),
+            "cpuTicks": int(fields[11]) + int(fields[12]),
+            "reapedChildCpuTicks": int(fields[13]) + int(fields[14]), "birthTicks": fields[19],
+            "rssPages": int(fields[21])}
+
+
+def snapshot(proc=Path("/proc")):
+    processes = {}
+    missing = 0
+    started = time.monotonic()
+    for path in proc.iterdir():
+        if not path.name.isdigit():
+            continue
+        try:
+            processes[int(path.name)] = read_process((path / "stat").read_text(encoding="utf-8", errors="replace"))
+        except (OSError, ValueError, IndexError):
+            missing += 1
+    cpu_lines = [line.split() for line in (proc / "stat").read_text().splitlines() if line.startswith("cpu")]
+    ticks = list(map(int, cpu_lines[0][1:9]))
+    per_cpu = {line[0][3:]: list(map(int, line[1:9])) for line in cpu_lines[1:]}
+    peak = int(next(line for line in (proc / "self/status").read_text().splitlines()
+                    if line.startswith("VmHWM:")).split()[1]) * 1024
+    usage = resource.getrusage(resource.RUSAGE_SELF)
+    return {"monotonic": time.monotonic(), "utc": datetime.now(timezone.utc).isoformat(),
+            # Busy excludes idle, iowait and steal: steal is time the hypervisor ran
+            # something else, not work by any guest thread.
+            "hostBusyTicks": sum(ticks) - ticks[3] - ticks[4] - ticks[7],
+            "cpuBusyTicks": {cpu: sum(t) - t[3] - t[4] - t[7] for cpu, t in per_cpu.items()},
+            "processes": processes,
+            "missingProcesses": missing, "scanSeconds": time.monotonic() - started,
+            "observerCpuSeconds": usage.ru_utime + usage.ru_stime,
+            "observerPeakRssBytes": peak}
+
+
+def cpu_busy_cores(before, after, scale):
+    # A CPU brought online or offline between snapshots has no interval value;
+    # report it as None so a gate cannot read it as idle.
+    return {cpu: (after[cpu] - before[cpu]) / scale if cpu in before and cpu in after else None
+            for cpu in sorted(before.keys() | after.keys(), key=int)}
+
+
+def compare(before, after, hz):
+    seconds = after["monotonic"] - before["monotonic"]
+    rows = []
+    prior = before["processes"]
+    current = after["processes"]
+    matched = set()
+    for pid, process in current.items():
+        old = prior.get(pid)
+        if old is None or old["birthTicks"] != process["birthTicks"]:
+            continue
+        matched.add(pid)
+        cpu = process["cpuTicks"] - old["cpuTicks"]
+        # When the parent reaps children, their total CPU is added to its
+        # cutime/cstime. The delta attributes that CPU to the parent; it can
+        # include CPU the children used before the interval started.
+        reaped = process.get("reapedChildCpuTicks", 0) - old.get("reapedChildCpuTicks", 0)
+        if cpu > 0 or reaped > 0:
+            rows.append({"pid": pid, **process, "busyCores": cpu / hz / seconds,
+                         "reapedChildCores": reaped / hz / seconds})
+    return {"startUtc": before["utc"], "endUtc": after["utc"], "seconds": seconds,
+            "hostBusyCores": (after["hostBusyTicks"] - before["hostBusyTicks"]) / hz / seconds,
+            "cpuBusyCores": cpu_busy_cores(before.get("cpuBusyTicks", {}), after.get("cpuBusyTicks", {}),
+                                           hz * seconds),
+            "unmatchedBefore": len(prior) - len(matched),
+            "unmatchedAfter": len(current) - len(matched),
+            "processCpu": sorted(rows, key=lambda row: -row["busyCores"])}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--seconds", type=int, default=20)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    if not 1 <= args.seconds <= 300:
+        parser.error("seconds must be between 1 and 300")
+    hz = os.sysconf("SC_CLK_TCK")
+    samples = [snapshot()]
+    for _ in range(args.seconds):
+        time.sleep(1)
+        samples.append(snapshot())
+    intervals = [compare(a, b, hz) for a, b in zip(samples, samples[1:])]
+    result = {"version": 2, "observerPid": os.getpid(), "clockTicksPerSecond": hz,
+              "bootId": Path("/proc/sys/kernel/random/boot_id").read_text().strip(),
+              "samples": samples, "intervals": intervals,
+              "limits": "Snapshots miss processes that start and exit between samples. reapedChildCores attributes children's CPU to the parent in the interval it reaps them, including CPU they used before the interval. Busy CPU excludes idle, iowait and steal. CPU attribution does not prove interference or grant admission. Observer overhead is included; no negligible-impact claim."}
+    args.output.write_text(json.dumps(result, indent=2))
+    print(json.dumps({"output": str(args.output), "intervals": len(intervals),
+                      "peakHostBusyCores": max(row["hostBusyCores"] for row in intervals),
+                      "observerPeakRssBytes": samples[-1]["observerPeakRssBytes"]}))
+
+
+if __name__ == "__main__":
+    main()

package/skills/hr-better-accessibility/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Jakub Krehel
+Copyright (c) 2026 Emil Kowalski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/hr-better-accessibility/NOTICE.md

@@ -0,0 +1,46 @@
+# Source notices
+
+This notice accompanies the hr-better-accessibility bundle when copied on its own.
+
+## jakubkrehel/skills
+
+Source: https://github.com/jakubkrehel/skills (compared at revision `267330e1adfc66a718fb65fa6918c1f06d0a689e`)
+
+- `skills/hr-better-accessibility/`, `skills/hr-better-colors/`, `skills/hr-better-layout/`,
+  `skills/hr-better-typography/` and `skills/hr-better-writing/`: adapted skill bundles,
+  including their supporting references and discovery metadata.
+
+Copyright (c) 2026 Jakub Krehel
+
+## emilkowalski/skills
+
+Source: https://github.com/emilkowalski/skills (compared at revision `e8a175de22ae1e49370fc144c1f3bb9aeedf988d`)
+
+- `skills/hr-better-accessibility/` and `skills/hr-better-layout/`: mobile behavior and
+  viewport guidance adapted from `skills/mobile-native/SKILL.md`.
+
+Copyright (c) 2026 Emil Kowalski
+
+## house-rules and MIT permission notice
+
+MIT License
+
+Copyright (c) 2026 Aaron Queen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/hr-better-accessibility/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: hr-better-accessibility
+description: "Accessibility rules for web UI: native elements, keyboard and focus, form labels and errors, accessible names, live regions, reduced motion, zoom and reflow. Use when building or reviewing web markup, forms, dialogs or interactive controls."
+license: MIT
+metadata:
+  upstream: https://github.com/jakubkrehel/skills
+  upstream_ref: 267330e1adfc66a718fb65fa6918c1f06d0a689e
+  upstream_path: skills/better-accessibility/
+  local_patches: "Use-when description; reduced-motion kill switch spares spinners; 320px reflow keeps the 2D-content exception; carousel pan-y, touch-callout and real-hardware check (from emilkowalski/skills mobile-native)"
+  house_rules_patches: "Portable provenance and review verdict; unique SVG title and desc ids"
+  mobile_native_source: https://github.com/emilkowalski/skills/blob/e8a175de22ae1e49370fc144c1f3bb9aeedf988d/skills/mobile-native/SKILL.md
+---
+
+# 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 `hr-better-colors`. Text sizing and iOS input zoom belong to `hr-better-typography`. Spatial RTL layout belongs to `hr-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 `hr-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. Tables, maps and code blocks may scroll inside their own container. 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.
+
+Report `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/skills/hr-better-accessibility/agents/openai.yaml

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

package/skills/hr-better-accessibility/focus-and-keyboard.md

@@ -0,0 +1,130 @@
+# 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-style:solid] 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. Prefer native `<dialog>` so the browser manages background inertness and initial focus:
+
+```tsx
+// On open: the browser honors eligible autofocus targets and skips disabled controls.
+dialogRef.current?.showModal();
+
+// On close
+dialogRef.current?.close();
+triggerRef.current?.focus(); // return focus to the element that opened it
+```
+
+For a custom modal, make the background `inert` and use the project's tested focus-management utility. Prefer an eligible autofocus target, then a visible, enabled focusable control. Skip hidden, disabled and inert candidates. If none exists, focus the dialog container with `tabindex="-1"`. Restore background interactivity when closing.
+
+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, prefer the eligible autofocus target, then a visible, enabled focusable control; use the container fallback when neither exists. For destructive confirmations, choose the least destructive action.
+- 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/skills/hr-better-accessibility/forms.md

@@ -0,0 +1,82 @@
+# 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/skills/hr-better-accessibility/hit-areas.md

@@ -0,0 +1,98 @@
+# 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
+
+- Use `touch-action: manipulation` where removing the mobile tap delay is needed. It permits panning and pinch zoom but disables double-tap zoom on that element; keep the default when that gesture should remain available.
+- 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 `touch-action: pan-y` on a horizontal carousel or swipe track that handles horizontal movement itself, so the browser keeps vertical page scrolling. A native `scroll-snap-type: x mandatory` track needs neither the gesture code nor the property.
+- Set `-webkit-tap-highlight-color` to match the design instead of the default gray flash.
+- Use `-webkit-touch-callout: none` only when a specific control needs to suppress Safari's long-press callout. Preserve it on links and images where users need native copy, share or link actions, including content links.
+- 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.
+
+Desktop emulation cannot verify all mobile browser behavior. Check hover, tap behavior, safe areas and keyboard interaction on supported devices, or report those checks as `Not verified`.