@a11y-lens/cli 0.5.0 → 0.6.0

package/README.md

@@ -43,6 +43,31 @@ a11y-lens is an AI reviewer, not a deterministic linter. The same files reviewed
 
 This is deliberate: only clear `error`-severity violations gate and warnings never block, precisely because AI output varies run to run. (This note belongs here, in the tool's own README — not in the `AGENTS.md` rules block that `init` injects into a consuming project, which is reserved for the accessibility rules themselves.)
 
+## Levels: what gets checked, and what gets shown
+
+Not every project needs every check. Each check in the rule set is tagged by who it helps:
+
+- **`core`**: checks that help everyone. They cover accessible names on icon-only controls, labels that are not placeholders, names that match the visible label, autocomplete on identity fields, full keyboard operation, and focus that is moved, returned and never lost.
+- **`full`**: the core checks plus the ones that are specific to screen readers. They cover headings and landmarks, alt text, complete ARIA patterns, errors tied to their fields, and live-region announcements for async results and loading.
+
+A `full` review is a superset of a `core` one, so code written to `full` passes `core`.
+
+Set the level for the whole team in the repository:
+
+```json
+// a11y-lens.config.json at the repository root (or the "a11y-lens" field of the root package.json)
+{ "level": "core", "report": "errors" }
+```
+
+| Setting | Values | Default |
+|---|---|---|
+| `level` | `core`: only `[core]` checks are sent to the agent. `full`: all checks. | `full` |
+| `report` | `errors`: print errors, and say how many warnings were hidden. `all`: print everything. | `all` |
+
+The defaults run the same checks and print the same output as earlier versions, so upgrading changes nothing a project would notice until it opts in. The rule text itself now carries the tags. `A11Y_LENS_LEVEL` and `A11Y_LENS_REPORT` override the file for one run. `--strict` always prints warnings, because it makes them fail the commit. An unknown value is warned about and replaced by the default.
+
+These levels are not WCAG's A/AA/AAA. They sort checks by who benefits, not by conformance level.
+
 ## Install
 
 a11y-lens has two layers — install either or both:
@@ -89,6 +114,8 @@ Escape hatches: `A11Y_LENS_SKIP=1 git commit …` or `git commit --no-verify`.
 | `A11Y_LENS_AGENT` | same as `--agent` |
 | `A11Y_LENS_MODEL` | model passed to `claude` |
 | `A11Y_LENS_TIMEOUT_MS` | agent timeout in milliseconds (default `180000`) |
+| `A11Y_LENS_LEVEL` | `core` or `full` for this run, over the project's setting |
+| `A11Y_LENS_REPORT` | `errors` or `all` for this run, over the project's setting |
 | `A11Y_LENS_SKIP=1` | skip the check entirely |
 
 ## Skipped checks

package/bin/a11y-lens.mjs

@@ -8,6 +8,7 @@ import { detectAgent, runAgent } from '../src/agent.mjs';
 import { buildPrompt } from '../src/prompt.mjs';
 import { parseFindings, printReport, exitCodeFor } from '../src/report.mjs';
 import { recordPending, listPending, clearReviewed, clearEntry, contentOf, pendingDir } from '../src/pending.mjs';
+import { loadConfig } from '../src/config.mjs';
 
 const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -33,6 +34,16 @@ Environment:
   A11Y_LENS_MODEL                     model override passed to claude (optional)
   A11Y_LENS_SKIP=1                    skip the check entirely (escape hatch)
   A11Y_LENS_TIMEOUT_MS                agent timeout in ms (default 180000)
+  A11Y_LENS_LEVEL=core|full           override the project's level (see below)
+  A11Y_LENS_REPORT=errors|all         override the project's report setting
+
+Project settings, in a11y-lens.config.json at the repository root (or the
+"a11y-lens" field of package.json):
+  { "level": "core", "report": "errors" }
+  level   core = checks that help everyone (names, keyboard, focus);
+          full = those plus screen-reader-specific checks (default)
+  report  errors = print errors only, and count the hidden warnings;
+          all = print everything (default). --strict always prints all.
 
 Infrastructure failures (no agent CLI, no network, agent error) never block:
 a11y-lens warns and exits 0. Only accessibility findings gate. When a staged
@@ -100,6 +111,12 @@ function warnPending() {
   }
 }
 
+/** Settings for this run; `--strict` gates on warnings, so it always shows them. */
+function runSettings(args) {
+  const config = loadConfig();
+  return { level: config.level, report: args.flags.strict ? 'all' : config.report };
+}
+
 function commandCheck(args) {
   if (args.flags.pending) return commandCheckPending(args);
   warnPending();
@@ -122,7 +139,8 @@ function commandCheck(args) {
   const detection = detectAgent(args.flags.agent);
   if (detection.error) softFail(detection.error);
 
-  const { prompt, dropped } = buildPrompt(reviewable);
+  const settings = runSettings(args);
+  const { prompt, dropped } = buildPrompt(reviewable, { level: settings.level });
   for (const path of dropped) {
     console.warn(`a11y-lens: dropped ${path} (prompt size budget exceeded)`);
   }
@@ -149,7 +167,7 @@ function commandCheck(args) {
   // typecheck aborted in parallel — is answered.
   if (staged) clearReviewed(included.map((f) => f.path));
 
-  printReport(parsed.findings, { agentName: detection.name });
+  printReport(parsed.findings, { agentName: detection.name, report: settings.report });
   process.exit(exitCodeFor(parsed.findings, { strict: args.flags.strict }));
 }
 
@@ -170,6 +188,7 @@ function commandCheckPending(args) {
 
   const detection = detectAgent(args.flags.agent);
   if (detection.error) softFail(`${detection.error}; ${entries.length} file(s) remain pending`);
+  const settings = runSettings(args);
 
   const batches = new Map();
   for (const item of [...entries].sort((a, b) => a.entry.at.localeCompare(b.entry.at))) {
@@ -193,7 +212,7 @@ function commandCheckPending(args) {
     }
     if (files.length === 0) continue;
 
-    const { prompt, dropped } = buildPrompt(files);
+    const { prompt, dropped } = buildPrompt(files, { level: settings.level });
     const included = files.filter((f) => !dropped.includes(f.path));
     if (included.length === 0) {
       console.warn(`a11y-lens: every file skipped at ${batch[0].entry.at} exceeds the prompt budget — they stay pending.`);
@@ -221,7 +240,7 @@ function commandCheckPending(args) {
     }
   }
 
-  printReport(findings, { agentName: detection.name });
+  printReport(findings, { agentName: detection.name, report: settings.report });
   if (remaining) console.warn(`a11y-lens: ${remaining} file(s) are still pending — run ${RECHECK} again.`);
   process.exit(exitCodeFor(findings, { strict: args.flags.strict }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a11y-lens/cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "publishConfig": {
     "access": "public"
   },

package/skills/a11y-lens/SKILL.md

@@ -20,11 +20,13 @@ Before writing or reviewing UI code, read the reference file for each category t
 | Click/hover handlers, shortcuts, drag, carousels | [references/05-keyboard-interaction.md](references/05-keyboard-interaction.md) |
 | Overlays, route changes, async results, toasts, loading | [references/06-focus-management.md](references/06-focus-management.md) |
 
-Core stances that apply everywhere:
+**Levels.** Every check is tagged `[core]` or `[full]`. `[core]` checks help everyone — accessible names, keyboard operation, focus that is never lost. `[full]` checks are screen-reader specific — headings and landmarks, alt text, ARIA patterns, live-region announcements. If the project sets `"level": "core"` (in `a11y-lens.config.json`, or the `"a11y-lens"` field of `package.json`), apply only the `[core]` checks and `[core]` examples; otherwise apply all of them.
+
+Stances at every level (items that belong only to `full` are marked):
 
 1. **Prefer native elements** (`button`, `select`, `details`, `dialog`) — they ship the complete pattern for free. A custom widget must implement the **whole** APG pattern; a partial pattern is worse than none.
-2. **Placeholder is not a label. Hover is not a keyboard path. CSS state is not ARIA state.**
-3. Severity discipline: `error` = clear violations (keyboard-dead interactive elements, unnamed icon-only controls, incomplete claimed ARIA patterns, unmanaged overlay focus, silenced informative images). Judgment calls are `warning`.
+2. **Placeholder is not a label. Hover is not a keyboard path.** At `full`, also: **CSS state is not ARIA state.**
+3. Severity discipline: `error` = clear violations (keyboard-dead interactive elements, unnamed icon-only controls, unmanaged overlay focus; at `full`, also incomplete claimed ARIA patterns and silenced informative images). Judgment calls are `warning`.
 
 ## Commit-time gate (CLI)
 

package/skills/a11y-lens/references/01-landmarks-headings.md

@@ -13,16 +13,18 @@ sources: [WCAG 1.3.1, WCAG 2.4.1, WCAG 2.4.6, axe-core region/heading rules]
 
 ## Semantic checks (what you review)
 
-1. **Heading hierarchy must describe the document outline, not the visual design.**
+1. `[full]` **Heading hierarchy must describe the document outline, not the visual design.**
    - Exactly one `h1` per page/view; levels must not skip downward (h1 → h3 with no h2 is an `error`).
    - A heading chosen for its font size rather than its outline position is a violation — check whether the level makes sense relative to surrounding headings, not whether it "looks right".
    - In SPAs, per-route views count as pages: a route component rendering only `h3`s is an `error` even if some layout file has an `h1` elsewhere — flag it as `warning` and say why (cannot see full composition).
-2. **`section` needs an accessible name to be a landmark.** A bare `section` used as a styling wrapper should be a `div`; a `section` that truly groups content needs `aria-labelledby` pointing at its heading (`warning`).
-3. **Landmark labels must be distinguishable.** Two `nav` elements require distinct `aria-label`s ("primary", "breadcrumb") — identical or missing labels on repeated landmarks is a `warning`.
-4. **Visual titles that are not headings.** A styled `div`/`p` acting as an obvious section title (short text, followed by related content, styled prominently) should be a heading (`warning`).
+2. `[full]` **`section` needs an accessible name to be a landmark.** A bare `section` used as a styling wrapper should be a `div`; a `section` that truly groups content needs `aria-labelledby` pointing at its heading (`warning`).
+3. `[full]` **Landmark labels must be distinguishable.** Two `nav` elements require distinct `aria-label`s ("primary", "breadcrumb") — identical or missing labels on repeated landmarks is a `warning`.
+4. `[full]` **Visual titles that are not headings.** A styled `div`/`p` acting as an obvious section title (short text, followed by related content, styled prominently) should be a heading (`warning`).
 
 ## Examples
 
+### `[full]` Outline and landmark
+
 Bad — outline skips and decorative section:
 
 ```jsx

package/skills/a11y-lens/references/02-images-alt.md

@@ -13,27 +13,41 @@ sources: [WCAG 1.1.1, eslint-plugin-jsx-a11y alt-text/img-redundant-alt, axe-cor
 
 ## Semantic checks (what you review)
 
-1. **Does the `alt` actually describe the image's function or content in context?**
+1. `[full]` **Does the `alt` actually describe the image's function or content in context?**
    - `alt="banner"`, `alt="icon"`, `alt="img_03"`, filename-derived alt → `error`. These pass static linters and fail humans.
    - An image inside a link: alt must describe the **destination/action**, not the picture ("에이닷 전화 다운로드", not "스마트폰 그림") — mismatch is `warning`.
-2. **Decorative images must be explicitly silenced**, not given filler alt. Purely decorative → `alt=""` (and `aria-hidden="true"` for inline SVG). Filler like `alt="장식"` is `warning`.
-3. **Informative images must not be silenced.** `alt=""` on an image that plainly carries information (chart, badge with a number, screenshot referenced by the copy) is an `error`.
-4. **Icon-only interactive elements.** A button/link whose only content is an icon (SVG, icon font, emoji) needs an accessible name (`aria-label` or visually-hidden text). Check the name describes the **action** ("닫기", not "X 아이콘"). Missing → `error`; vague → `warning`.
-5. **Text baked into images** (event banners with dates/prices in pixels) — the alt or adjacent text must carry the same information; otherwise `warning`.
-6. **CSS background-images conveying meaning** have no alt channel at all — if the diff shows meaningful content moved into a background-image, flag `warning` with the visually-hidden-text remedy.
+2. `[full]` **Decorative images must be explicitly silenced**, not given filler alt. Purely decorative → `alt=""` (and `aria-hidden="true"` for inline SVG). Filler like `alt="장식"` is `warning`.
+3. `[full]` **Informative images must not be silenced.** `alt=""` on an image that plainly carries information (chart, badge with a number, screenshot referenced by the copy) is an `error`.
+4. `[core]` **Icon-only interactive elements.** A button/link whose only content is an icon (SVG, icon font, emoji) needs an accessible name (`aria-label` or visually-hidden text). Check the name describes the **action** ("닫기", not "X 아이콘"). Missing → `error`; vague → `warning`.
+5. `[full]` **Text baked into images** (event banners with dates/prices in pixels) — the alt or adjacent text must carry the same information; otherwise `warning`.
+6. `[full]` **CSS background-images conveying meaning** have no alt channel at all — if the diff shows meaningful content moved into a background-image, flag `warning` with the visually-hidden-text remedy.
 
 ## Examples
 
+### `[core]` Icon-only button
+
+Bad — no name:
+
+```jsx
+<button><CloseIcon /></button>
+```
+
+Good:
+
+```jsx
+<button aria-label="닫기"><CloseIcon aria-hidden="true" /></button>
+```
+
+### `[full]` Image inside a link
+
 Bad — passes static linting, fails semantically:
 
 ```jsx
 <a href="/download"><img src="/hero-phone.png" alt="phone image" /></a>
-<button><CloseIcon /></button>
 ```
 
 Good:
 
 ```jsx
 <a href="/download"><img src="/hero-phone.png" alt="에이닷 전화 앱 다운로드" /></a>
-<button aria-label="닫기"><CloseIcon aria-hidden="true" /></button>
 ```

package/skills/a11y-lens/references/03-forms-labels.md

@@ -12,27 +12,43 @@ sources: [WCAG 1.3.1, WCAG 3.3.1, WCAG 3.3.2, WCAG 4.1.2, eslint-plugin-jsx-a11y
 
 ## Semantic checks (what you review)
 
-1. **Placeholder is not a label.** A control whose only "label" is `placeholder` is an `error` — it disappears on input and has no reliable AT exposure. Check the diff for inputs that visually rely on placeholder alone.
-2. **The accessible name must match the visible label.** If a visible text label says "휴대폰 번호" but `aria-label="phone"`, voice-control users cannot target it (WCAG 2.5.3 Label in Name) → `warning`.
-3. **Errors must be programmatically tied to their field.** Rendering an error message as a sibling `<p className="error">` with no `aria-describedby` on the input and no `aria-invalid` is `error` when the diff introduces validation UI. A live-updating error summary should use `role="alert"` or `aria-live="assertive"` — but only one, not both stacked.
-4. **Required and disabled semantics.** Visually-marked required fields (asterisk, "필수") need `required` or `aria-required="true"` (`warning`). A visually "disabled" button that is actually a styled `div` or keeps focus without `disabled`/`aria-disabled` misleads AT → `warning`.
-5. **Grouped controls need a group name.** Radio sets / related checkboxes introduced without `fieldset`+`legend` (or `role="radiogroup"` + `aria-labelledby`) → `warning`: each option is announced with no question attached.
-6. **Autocomplete on identity fields.** Login/checkout fields for name, email, tel, address should carry `autocomplete` tokens (WCAG 1.3.5) → `warning` when the diff adds such fields bare.
+1. `[core]` **Placeholder is not a label.** A control whose only "label" is `placeholder` is an `error` — it disappears on input and has no reliable AT exposure. Check the diff for inputs that visually rely on placeholder alone.
+2. `[core]` **The accessible name must match the visible label.** If a visible text label says "휴대폰 번호" but `aria-label="phone"`, voice-control users cannot target it (WCAG 2.5.3 Label in Name) → `warning`.
+3. `[full]` **Errors must be programmatically tied to their field.** Rendering an error message as a sibling `<p className="error">` with no `aria-describedby` on the input and no `aria-invalid` is `error` when the diff introduces validation UI. A live-updating error summary should use `role="alert"` or `aria-live="assertive"` — but only one, not both stacked.
+4. `[full]` **Required and disabled semantics.** Visually-marked required fields (asterisk, "필수") need `required` or `aria-required="true"` (`warning`). A visually "disabled" button that is actually a styled `div` or keeps focus without `disabled`/`aria-disabled` misleads AT → `warning`.
+5. `[full]` **Grouped controls need a group name.** Radio sets / related checkboxes introduced without `fieldset`+`legend` (or `role="radiogroup"` + `aria-labelledby`) → `warning`: each option is announced with no question attached.
+6. `[core]` **Autocomplete on identity fields.** Login/checkout fields for name, email, tel, address should carry `autocomplete` tokens (WCAG 1.3.5) → `warning` when the diff adds such fields bare.
 
 ## Examples
 
+### `[core]` Label and autocomplete
+
 Bad:
 
 ```jsx
 <input placeholder="이메일" value={email} onChange={...} />
-{error && <p className="error">이메일 형식이 아닙니다</p>}
 ```
 
 Good:
 
 ```jsx
 <label htmlFor="email">이메일</label>
-<input id="email" type="email" autoComplete="email" value={email}
+<input id="email" type="email" autoComplete="email" value={email} onChange={...} />
+```
+
+### `[full]` Error tied to its field
+
+Bad:
+
+```jsx
+<input id="email" type="email" value={email} onChange={...} />
+{error && <p className="error">이메일 형식이 아닙니다</p>}
+```
+
+Good:
+
+```jsx
+<input id="email" type="email" value={email} onChange={...}
        aria-invalid={!!error} aria-describedby={error ? "email-error" : undefined} />
 {error && <p id="email-error" role="alert">이메일 형식이 아닙니다</p>}
 ```

package/skills/a11y-lens/references/04-aria-widgets.md

@@ -17,20 +17,22 @@ sources: [W3C WAI-ARIA APG patterns, WCAG 4.1.2, eslint-plugin-jsx-a11y role-* r
 
 For any custom widget in the diff, identify which APG pattern it is imitating, then verify the pattern is **complete** — states, properties, and relationships all present. Missing pieces of a claimed pattern are `error`.
 
-1. **Combobox / select-like** (custom dropdown, autocomplete):
+1. `[full]` **Combobox / select-like** (custom dropdown, autocomplete):
    - Trigger: `role="combobox"`, `aria-expanded` toggling, `aria-controls` → listbox id, `aria-haspopup="listbox"` where appropriate.
    - Popup: `role="listbox"`, options `role="option"` with `aria-selected`; active option tracked via `aria-activedescendant` on the combobox (or roving focus — one or the other, not both).
    - A styled `div` dropdown with only `onClick` handlers and none of the above is the classic failure → `error`.
-2. **Dialog / modal**: `role="dialog"` + `aria-modal="true"`, labelled by its title. Background content must be inert or `aria-hidden` while open. (Focus behavior → rules/06.)
-3. **Tabs**: `role="tablist"` / `tab` / `tabpanel`, `aria-selected` on the active tab, `aria-controls` ↔ `aria-labelledby` linkage between tab and panel.
-4. **Menu**: `role="menu"`/`menuitem` is for **command menus**, not site navigation. Nav links wrapped in `role="menu"` is a misuse → `warning` (breaks expected keyboard model).
-5. **Switch vs checkbox vs button**: a toggle announced as what it visually is — `role="switch"` needs `aria-checked`, not `aria-pressed`; mixing the two vocabularies is `warning`.
-6. **State must live in ARIA, not only in CSS.** `className={isOpen ? 'open' : ''}` with no `aria-expanded` change means AT never hears the state change → `error` for expand/collapse triggers.
-7. **`aria-hidden` on focusable content** or on an element containing focusable children → `error` (focusable but invisible to AT).
-8. **Redundant/contradictory ARIA**: `role="button"` on `button`, `aria-label` duplicating identical visible text where unnecessary → `notice`-level `warning`; contradiction (label says one thing, visible text another) → follow rules/03 §2.
+2. `[full]` **Dialog / modal**: `role="dialog"` + `aria-modal="true"`, labelled by its title. Background content must be inert or `aria-hidden` while open. (Focus behavior → rules/06.)
+3. `[full]` **Tabs**: `role="tablist"` / `tab` / `tabpanel`, `aria-selected` on the active tab, `aria-controls` ↔ `aria-labelledby` linkage between tab and panel.
+4. `[full]` **Menu**: `role="menu"`/`menuitem` is for **command menus**, not site navigation. Nav links wrapped in `role="menu"` is a misuse → `warning` (breaks expected keyboard model).
+5. `[full]` **Switch vs checkbox vs button**: a toggle announced as what it visually is — `role="switch"` needs `aria-checked`, not `aria-pressed`; mixing the two vocabularies is `warning`.
+6. `[full]` **State must live in ARIA, not only in CSS.** `className={isOpen ? 'open' : ''}` with no `aria-expanded` change means AT never hears the state change → `error` for expand/collapse triggers.
+7. `[full]` **`aria-hidden` on focusable content** or on an element containing focusable children → `error` (focusable but invisible to AT).
+8. `[full]` **Redundant/contradictory ARIA**: `role="button"` on `button`, `aria-label` duplicating identical visible text where unnecessary → `notice`-level `warning`; contradiction (label says one thing, visible text another) → follow rules/03 §2.
 
 ## Examples
 
+### `[full]` Combobox
+
 Bad — half a combobox:
 
 ```jsx

package/skills/a11y-lens/references/05-keyboard-interaction.md

@@ -13,19 +13,21 @@ sources: [WCAG 2.1.1, WCAG 2.1.2, W3C WAI-ARIA APG keyboard patterns, eslint-plu
 
 ## Semantic checks (what you review)
 
-1. **Every pointer interaction needs a keyboard equivalent — the right one.** Adding `onKeyDown` that only handles Enter on a `div` "button" is incomplete: native buttons fire on Enter **and** Space. Check the handler actually implements the expected key set, not just any key (`error` if a claimed interactive element is keyboard-dead, `warning` if the key set is partial).
-2. **Widget key sets must match the APG pattern being imitated:**
+1. `[core]` **Every pointer interaction needs a keyboard equivalent — the right one.** Adding `onKeyDown` that only handles Enter on a `div` "button" is incomplete: native buttons fire on Enter **and** Space. Check the handler actually implements the expected key set, not just any key (`error` if a claimed interactive element is keyboard-dead, `warning` if the key set is partial).
+2. `[core]` **Widget key sets must match the APG pattern being imitated:**
    - Combobox/listbox: `ArrowDown`/`ArrowUp` move the active option, `Enter` selects, `Escape` closes, `Home`/`End` jump, printable characters typeahead (typeahead is `warning`-level, the rest `error` if absent).
    - Tabs: `ArrowLeft`/`ArrowRight` between tabs (roving tabindex), `Tab` leaves the tablist into the panel.
    - Dialog: `Escape` closes; `Tab` cycles inside (focus trap — see rules/06).
    - Menu: arrows navigate, `Escape` closes and returns focus to the trigger.
-3. **Hover-only affordances.** Content or controls revealed only on `:hover`/`onMouseEnter` with no focus/keyboard path (tooltips, hover menus, card action buttons) → `error`: keyboard users can never reach them. Also flag `onMouseDown`-only handlers (skips keyboard AND breaks click-drag expectations).
-4. **No keyboard traps.** Custom key handling that `preventDefault()`s Tab without providing an exit is an `error` (WCAG 2.1.2). Legitimate traps (modal dialogs) must be escapable via `Escape`.
-5. **Scroll/drag-only interactions** (carousels, sliders, drag-to-reorder) need button or keyboard alternatives → `warning`.
-6. **Global shortcuts on printable keys** without a modifier or an off-switch collide with AT and text input → `warning` (WCAG 2.1.4).
+3. `[core]` **Hover-only affordances.** Content or controls revealed only on `:hover`/`onMouseEnter` with no focus/keyboard path (tooltips, hover menus, card action buttons) → `error`: keyboard users can never reach them. Also flag `onMouseDown`-only handlers (skips keyboard AND breaks click-drag expectations).
+4. `[core]` **No keyboard traps.** Custom key handling that `preventDefault()`s Tab without providing an exit is an `error` (WCAG 2.1.2). Legitimate traps (modal dialogs) must be escapable via `Escape`.
+5. `[core]` **Scroll/drag-only interactions** (carousels, sliders, drag-to-reorder) need button or keyboard alternatives → `warning`.
+6. `[core]` **Global shortcuts on printable keys** without a modifier or an off-switch collide with AT and text input → `warning` (WCAG 2.1.4).
 
 ## Examples
 
+### `[core]` Hover-only reveal
+
 Bad — mouse-only reveal:
 
 ```jsx

package/skills/a11y-lens/references/06-focus-management.md

@@ -12,18 +12,20 @@ sources: [WCAG 2.4.3, WCAG 2.4.7, WCAG 3.2.1, W3C WAI-ARIA APG dialog/disclosure
 
 ## Semantic checks (what you review)
 
-1. **Opening an overlay must move focus into it; closing must return focus to the trigger.** A modal/drawer/popover in the diff that only toggles visibility state with no `focus()` call in either direction → `error`. Focus landing on the container is acceptable (`tabIndex={-1}` + label); focus landing nowhere (document.body) is the failure.
-2. **Focus trap completeness.** While a modal is open, `Tab` from the last focusable element must wrap to the first (and Shift+Tab the reverse). A "trap" implemented by `aria-hidden` on the background but with tab order still escaping → `error`.
-3. **Removing the focused element.** Deleting a list item, closing a tab, dismissing a toast that currently holds focus must move focus somewhere sensible (next item, list container, heading) — otherwise focus resets to `body` and keyboard users are lost → `warning`.
-4. **Route changes in SPAs.** Client-side navigation that only swaps content leaves focus and screen-reader context on the old page. New route should move focus to the new view's heading or main container, or announce via live region → `warning` when the diff adds routing.
-5. **Async results need announcement.** Content that appears after a delay (search results, form submission outcome, "저장되었습니다" toast) is silent to AT unless in an `aria-live` region (`polite` for results, `assertive`/`role="alert"` for errors) → `warning`; toast components with no live region → `error`.
-6. **Loading states.** Spinner-only loading (`<Spinner />` with no text, no `aria-busy`, no live announcement) → `warning`. Skeleton screens should be `aria-hidden` so AT doesn't read placeholder noise.
-7. **No focus stealing.** Auto-focusing an input on page load is acceptable for single-purpose pages (login); yanking focus on timers, carousel advance, or validation-while-typing → `warning` (WCAG 3.2.1 On Focus).
-8. **`scrollIntoView`/anchor jumps without focus.** Scrolling a target into view visually while focus stays behind creates divergence between sighted and keyboard experience → `warning`.
+1. `[core]` **Opening an overlay must move focus into it; closing must return focus to the trigger.** A modal/drawer/popover in the diff that only toggles visibility state with no `focus()` call in either direction → `error`. Focus landing on the container is acceptable (`tabIndex={-1}` + label); focus landing nowhere (document.body) is the failure.
+2. `[core]` **Focus trap completeness.** While a modal is open, `Tab` from the last focusable element must wrap to the first (and Shift+Tab the reverse). A "trap" implemented by `aria-hidden` on the background but with tab order still escaping → `error`.
+3. `[core]` **Removing the focused element.** Deleting a list item, closing a tab, dismissing a toast that currently holds focus must move focus somewhere sensible (next item, list container, heading) — otherwise focus resets to `body` and keyboard users are lost → `warning`.
+4. `[full]` **Route changes in SPAs.** Client-side navigation that only swaps content leaves focus and screen-reader context on the old page. New route should move focus to the new view's heading or main container, or announce via live region → `warning` when the diff adds routing.
+5. `[full]` **Async results need announcement.** Content that appears after a delay (search results, form submission outcome, "저장되었습니다" toast) is silent to AT unless in an `aria-live` region (`polite` for results, `assertive`/`role="alert"` for errors) → `warning`; toast components with no live region → `error`.
+6. `[full]` **Loading states.** Spinner-only loading (`<Spinner />` with no text, no `aria-busy`, no live announcement) → `warning`. Skeleton screens should be `aria-hidden` so AT doesn't read placeholder noise.
+7. `[core]` **No focus stealing.** Auto-focusing an input on page load is acceptable for single-purpose pages (login); yanking focus on timers, carousel advance, or validation-while-typing → `warning` (WCAG 3.2.1 On Focus).
+8. `[core]` **`scrollIntoView`/anchor jumps without focus.** Scrolling a target into view visually while focus stays behind creates divergence between sighted and keyboard experience → `warning`.
 
 ## Examples
 
-Bad — modal with no focus contract:
+### `[core]` Modal focus contract
+
+Bad — focus goes nowhere on open, and nowhere on close:
 
 ```jsx
 {isOpen && <div className="modal"><h2>요금제 변경</h2>…</div>}
@@ -38,9 +40,19 @@ useEffect(() => {
 }, [isOpen]);
 
 {isOpen && (
-  <div ref={dialogRef} role="dialog" aria-modal="true"
-       aria-labelledby="plan-title" tabIndex={-1}>
-    <h2 id="plan-title">요금제 변경</h2>…
+  <div ref={dialogRef} tabIndex={-1} aria-label="요금제 변경">
+    <h2>요금제 변경</h2>…
   </div>
 )}
 ```
+
+### `[full]` Modal semantics
+
+The same modal, announced as one: `role="dialog"`, `aria-modal="true"` and a label (rules/04 §2).
+
+```jsx
+<div ref={dialogRef} role="dialog" aria-modal="true"
+     aria-labelledby="plan-title" tabIndex={-1}>
+  <h2 id="plan-title">요금제 변경</h2>…
+</div>
+```

package/src/config.mjs

@@ -0,0 +1,83 @@
+// Project settings: which checks run (`level`) and which findings are shown (`report`).
+//
+// Read from the repository, because what a team checks is a team decision: `a11y-lens.config.json`
+// at the git top level, else the `"a11y-lens"` field of its `package.json`. Environment variables
+// override either, for one person trying something out. A bad value is warned about and replaced by
+// the default — never an error, since a commit is never blocked by infrastructure.
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const LEVELS = ['core', 'full'];
+export const REPORTS = ['errors', 'all'];
+// The defaults are what every version before 0.6.0 did, so upgrading changes nothing by itself.
+export const DEFAULTS = { level: 'full', report: 'all' };
+
+function repoRoot(cwd) {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    return cwd;
+  }
+}
+
+/** `{ value }`, `{ missing: true }`, or `{ error }` — a file that is there but unreadable is worth a warning. */
+function readJson(path) {
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch {
+    return { missing: true };
+  }
+  try {
+    return { value: JSON.parse(text) };
+  } catch (err) {
+    return { error: String(err?.message ?? err) };
+  }
+}
+
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+export function loadConfig({ cwd = process.cwd(), env = process.env, warn = (m) => console.warn(m) } = {}) {
+  const root = repoRoot(cwd);
+  let settings = {};
+  let source = 'defaults';
+
+  const file = join(root, 'a11y-lens.config.json');
+  const fromFile = readJson(file);
+  if (fromFile.error) {
+    warn(`a11y-lens: ignoring ${file} (${fromFile.error})`);
+  } else if (!fromFile.missing) {
+    if (isPlainObject(fromFile.value)) {
+      settings = fromFile.value;
+      source = 'a11y-lens.config.json';
+    } else {
+      warn(`a11y-lens: ignoring ${file} (expected an object)`);
+    }
+  } else {
+    const pkg = readJson(join(root, 'package.json'));
+    const field = pkg.value?.['a11y-lens'];
+    if (field !== undefined) {
+      if (isPlainObject(field)) {
+        settings = field;
+        source = 'package.json';
+      } else {
+        warn('a11y-lens: ignoring the "a11y-lens" field in package.json (expected an object)');
+      }
+    }
+  }
+
+  const pick = (key, allowed, envName) => {
+    for (const [value, from] of [[env[envName], envName], [settings[key], source]]) {
+      if (value === undefined || value === '') continue;
+      if (allowed.includes(value)) return value;
+      warn(`a11y-lens: ignoring ${key} "${value}" from ${from} (expected ${allowed.join(' | ')})`);
+    }
+    return DEFAULTS[key];
+  };
+
+  return {
+    level: pick('level', LEVELS, 'A11Y_LENS_LEVEL'),
+    report: pick('report', REPORTS, 'A11Y_LENS_REPORT'),
+  };
+}

package/src/prompt.mjs

@@ -8,12 +8,51 @@ const RULES_DIR = join(
 );
 const MAX_TOTAL_BYTES = 160_000;
 
-export function loadRules() {
-  return readdirSync(RULES_DIR)
+// Named per level so the prompt never cites a check the level left out — an agent told that
+// "incomplete claimed ARIA patterns" are errors reviews ARIA patterns whether or not they are listed.
+const SEVERITY_EXAMPLES = {
+  core: 'keyboard-dead interactive elements, missing accessible names on icon-only controls, focus not managed on overlays',
+  full: 'keyboard-dead interactive elements, missing accessible names on icon-only controls, incomplete claimed ARIA patterns, focus not managed on overlays, informative images silenced',
+};
+
+const LEVEL_TAG = /^`\[(core|full)\]`/;
+
+/**
+ * One rule file cut down to a level. `full` is the file as written. `core` keeps the numbered
+ * semantic checks and the example subsections tagged `[core]`, and drops a file with none — so what
+ * the agent is shown is only what it is asked to check. Numbers are kept, because other files refer
+ * to checks by number ("rules/03 §2").
+ */
+export function filterRule(text, level) {
+  if (level === 'full') return text;
+  const sections = text.split(/(?=^## )/m);
+  let kept = 0;
+  const out = sections.map((section) => {
+    if (section.startsWith('## Semantic checks')) {
+      const [intro, ...items] = section.split(/(?=^\d+\. )/m);
+      const chosen = items.filter((item) => item.replace(/^\d+\. /, '').match(LEVEL_TAG)?.[1] === level);
+      kept += chosen.length;
+      return intro + chosen.join('');
+    }
+    if (section.startsWith('## Examples')) {
+      const [intro, ...subsections] = section.split(/(?=^### )/m);
+      const chosen = subsections.filter((sub) => sub.replace(/^### /, '').match(LEVEL_TAG)?.[1] === level);
+      return chosen.length ? intro + chosen.join('') : '';
+    }
+    return section;
+  });
+  return kept === 0 ? null : out.join('');
+}
+
+/** The rule files at `level`, joined, and the ids of the categories that survived. */
+export function loadRules(level = 'full') {
+  const files = readdirSync(RULES_DIR)
     .filter((name) => name.endsWith('.md'))
     .sort()
-    .map((name) => readFileSync(join(RULES_DIR, name), 'utf8'))
-    .join('\n\n---\n\n');
+    .map((name) => filterRule(readFileSync(join(RULES_DIR, name), 'utf8'), level))
+    .filter((text) => text !== null);
+  const ids = files.map((text) => text.match(/^id: (\S+)$/m)?.[1]).filter(Boolean);
+  return { text: files.join('\n\n---\n\n'), ids };
 }
 
 function numbered(content) {
@@ -27,8 +66,8 @@ function numbered(content) {
  * Assemble the review prompt. Files over the total budget are dropped
  * (caller already reported per-file skips); we report drops via the return value.
  */
-export function buildPrompt(files) {
-  const rules = loadRules();
+export function buildPrompt(files, { level = 'full' } = {}) {
+  const { text: rules, ids } = loadRules(level);
   const included = [];
   const dropped = [];
   let budget = MAX_TOTAL_BYTES;
@@ -68,13 +107,13 @@ Respond with ONLY a JSON array — no prose, no markdown fences. Each finding:
 {
   "file": "path as given above",
   "line": <number from the line-number prefix>,
-  "ruleId": "one of: landmarks-headings | images-alt | forms-labels | aria-widgets | keyboard-interaction | focus-management",
+  "ruleId": "one of: ${ids.join(' | ')}",
   "severity": "error" | "warning",
   "message": "what is wrong and why it matters, one or two sentences",
   "suggestion": "the concrete fix, one sentence or a short code hint"
 }
 
-Severity discipline: "error" only for clear violations named as error in the rules (keyboard-dead interactive elements, missing accessible names on icon-only controls, incomplete claimed ARIA patterns, focus not managed on overlays, informative images silenced). Judgment calls are "warning". If the code is clean, respond with [].`;
+Severity discipline: "error" only for clear violations named as error in the rules (${SEVERITY_EXAMPLES[level]}). Judgment calls are "warning". ${level === 'core' ? 'Check only the rules above; this project has chosen not to review the others, so do not report them. ' : ''}If the code is clean, respond with [].`;
 
   return { prompt, dropped };
 }

package/src/report.mjs

@@ -31,9 +31,20 @@ export function parseFindings(text) {
   return { error: 'could not parse agent output as a findings array' };
 }
 
-export function printReport(findings, { agentName } = {}) {
+/**
+ * `report: 'errors'` shows errors only and says how many warnings it held back — the count, so a
+ * clean-looking run is not mistaken for a run that found nothing.
+ */
+export function printReport(allFindings, { agentName, report = 'all' } = {}) {
+  const findings = report === 'errors' ? allFindings.filter((f) => f.severity === 'error') : allFindings;
+  const hidden = allFindings.length - findings.length;
+  // On the last line, beside the totals it qualifies: printed above the report, the count was
+  // followed by a footer saying "0 warning(s)" — a clean-looking run again.
+  const hiddenNote = hidden ? `, ${YELLOW}${hidden} warning(s) hidden${RESET} ${DIM}(report: errors)${RESET}` : '';
   if (findings.length === 0) {
-    console.log(`a11y-lens: no findings ${DIM}(reviewed by ${agentName})${RESET}`);
+    console.log(hidden
+      ? `a11y-lens: no errors${hiddenNote} ${DIM}(reviewed by ${agentName})${RESET}`
+      : `a11y-lens: no findings ${DIM}(reviewed by ${agentName})${RESET}`);
     return;
   }
   const byFile = new Map();
@@ -56,7 +67,7 @@ export function printReport(findings, { agentName } = {}) {
   const warnings = findings.length - errors;
   console.log(
     `\na11y-lens: ${errors ? RED : ''}${errors} error(s)${RESET}, ` +
-    `${warnings ? YELLOW : ''}${warnings} warning(s)${RESET} ` +
+    (hidden ? `${hiddenNote.slice(2)} ` : `${warnings ? YELLOW : ''}${warnings} warning(s)${RESET} `) +
     `${DIM}(reviewed by ${agentName})${RESET}`,
   );
 }

package/templates/agents-snippet.md

@@ -12,6 +12,8 @@ When writing or modifying UI code (JSX/TSX/HTML/Vue/Svelte), apply the rule set
 - `05-keyboard-interaction.md` — full APG key sets, no hover-only affordances, no keyboard traps
 - `06-focus-management.md` — overlays move and return focus; async results are announced via live regions
 
+Each check is tagged `[core]` or `[full]`. If this project's `a11y-lens.config.json` (or the `"a11y-lens"` field of `package.json`) sets `"level": "core"`, apply only the `[core]` checks — the commit-time review checks nothing else.
+
 Tip: agents with skills support get richer guidance via `npx skills add jo-duchan/a11y-lens`.
 
 Self-check against these categories before finishing any UI task — it is cheaper than failing the pre-commit gate.