@raishin/vanguard-frontier-agentic 3.0.2 → 3.1.0

package/skills/frontend/html-semantics-accessibility-review/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: html-semantics-accessibility-review
+description: Review HTML markup and rendered DOM structure for correct native-element usage, valid heading/landmark hierarchy, and WAI-ARIA APG-conformant custom-widget patterns; produce a WCAG 2.2-grounded verdict with APG pattern citations for every custom interactive control, flagging anything that needs live screen-reader verification beyond static review.
+allowed-tools: Read Grep Glob Bash(git diff:*) WebFetch
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-07-02"
+  category: compliance
+---
+
+# HTML Semantics & Accessibility Review
+
+## Purpose
+
+Automated a11y linters (axe, Lighthouse) catch roughly 30-50% of WCAG issues by design — they cannot verify whether a custom widget's keyboard interaction matches its intended pattern, whether ARIA correctly reflects (or wrongly overrides) native semantics, or whether a heading/landmark outline actually helps a screen-reader user navigate. This skill performs the manual, spec-grounded review that closes that gap: matching every custom interactive element against a specific WAI-ARIA APG pattern, verifying heading/landmark structure, and catching redundant or conflicting ARIA before it ships.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- review a pull request or component for HTML semantics or accessibility correctness,
+- verify a custom widget (modal, dropdown, tabs, combobox, accordion, etc.) against WAI-ARIA APG patterns,
+- audit heading level and landmark structure on a page or component tree,
+- check whether ARIA roles/states/properties are correctly applied or redundant/conflicting with native semantics,
+- assess WCAG 2.2 conformance risk for markup changes ahead of a compliance audit.
+
+## Context7 Documentation Protocol
+
+Element semantics, implicit ARIA-role mappings, and attribute-support tables change as the HTML and ARIA specs evolve — never assert them from memory.
+
+1. Call `ToolSearch` with query `"context7"` (or `"select:mcp__Context7__resolve-library-id,mcp__Context7__query-docs"`) to load the Context7 tools if they are not already loaded in this session.
+2. Call `mcp__Context7__resolve-library-id` for the relevant documentation set — for this skill that is almost always MDN (`/mdn/content`, or `/websites/developer_mozilla_en-us` if the former lacks coverage for the query). Resolve the WAI-ARIA APG or WCAG spec source too if the review needs primary-spec wording rather than MDN's paraphrase.
+3. Call `mcp__Context7__query-docs` for the specific element, role, or attribute in question — e.g. "implicit ARIA role for `<nav>`", "APG combobox keyboard pattern", "tabindex focus-order behavior" — before ruling on it. Do this per review, not once from memory of a prior session.
+4. Prefer the official spec/MDN wording over this skill's own paraphrase when the two could be read to disagree; cite the resolved doc URL in the finding.
+5. If Context7 is unavailable or returns no relevant match, fall back to the URLs in `official_docs` / `references/apg-pattern-index.md`, and explicitly mark the claim `documentation-based (Context7 unavailable)` rather than presenting it as freshly verified.
+6. Never invent an ARIA role, state, property, or implicit-semantics mapping that no queried source confirms.
+
+## Lean operating rules
+
+- First rule of ARIA: no ARIA is better than bad ARIA. Prefer a native element (`<button>`, `<dialog>`, `<details>`, `<nav>`) over a JS-reimplemented equivalent with ARIA bolted on, unless the platform genuinely has no equivalent.
+- Never accept 'axe/Lighthouse passed' as sufficient evidence for a custom interactive widget — manually match it against a specific APG pattern URL, including its full keyboard model (not just Tab/Enter — Escape, Home, End, Arrow keys per the pattern).
+- Treat heading-level skips (h1→h3) and missing/duplicate landmarks as blocking findings, not style notes — they break screen-reader page-navigation shortcuts.
+- Never approve positive `tabindex` values; require `tabindex="0"`/`"-1"` plus correct DOM order instead.
+- Flag `aria-hidden="true"` on any ancestor of a focusable/interactive descendant — this creates an unreachable-but-focusable or reachable-but-hidden trap.
+- Query current MDN/WAI-ARIA APG docs (see Context7 Documentation Protocol) for the specific element/role in question before ruling; element semantics and ARIA support tables change with spec updates — never assert support/behavior from memory.
+- Anything requiring live screen-reader verification (actual NVDA/JAWS/VoiceOver behavior) gets flagged as a residual risk, not asserted as verified from static review alone.
+- Label every claim as `live evidence`, `spec-cited`, `documentation-based`, or `inference` so the reviewer knows what's actually been verified vs. reasoned about.
+
+## References
+
+Load these only when needed:
+
+- [WCAG success-criterion mapping](references/wcag-criterion-mapping.md) — use when a finding needs to be tied to a specific WCAG 2.2 success criterion for a compliance-audit deliverable.
+- [APG pattern quick-index](references/apg-pattern-index.md) — use when identifying which APG pattern matches a given custom widget (modal, combobox, tabs, tree, menu, disclosure, etc.) before doing the deep keyboard-model comparison.
+- [Heading and landmark structure rules](references/heading-landmark-rules.md) — use when auditing page-level or component-tree-level outline structure, including nested-landmark and multiple-landmark-of-same-type edge cases.
+
+## Response minimum
+
+Return, at minimum:
+
+- the element/component in scope and its semantic verdict (native-element compliant / needs ARIA / needs restructure),
+- for any custom interactive widget: the specific APG pattern URL cited, or an explicit flag that none matches and a native element should be used instead,
+- the heading/landmark outline diff (before/after) when structure changed,
+- every ARIA attribute added or removed, with its WAI-ARIA 1.2 role/state justification,
+- residual risk notes for anything requiring live assistive-technology verification beyond this static review.

package/skills/frontend/html-semantics-accessibility-review/metadata.json

@@ -0,0 +1,29 @@
+{
+  "id": "html-semantics-accessibility-review",
+  "name": "HTML Semantics & Accessibility Review",
+  "type": "skill",
+  "provider": "frontend",
+  "harnesses": [
+    "claude-code",
+    "cursor",
+    "codex",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Reviews markup for correct native-element usage, valid heading/landmark structure, and WAI-ARIA APG-conformant custom-widget patterns, producing a WCAG-grounded verdict with APG citations for every custom interactive element and flags for anything needing live assistive-technology verification.",
+  "source_type": "original",
+  "official_docs": [
+    "https://html.spec.whatwg.org/multipage/",
+    "https://www.w3.org/WAI/ARIA/apg/",
+    "https://www.w3.org/TR/wai-aria-1.2/",
+    "https://www.w3.org/TR/WCAG22/",
+    "https://developer.mozilla.org/en-US/docs/Web/HTML",
+    "https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA"
+  ],
+  "security_notes": "Do not hardcode or request user PII, real screen-reader session logs, or authenticated-app URLs in review examples. Flag markup that binds unsanitized user content directly into the DOM (innerHTML/outerHTML/document.write) as an XSS-adjacent finding even though the primary fix is JS-side. Treat WCAG conformance findings as compliance-relevant (ADA/Section 508/EN 301 549 exposure) and label them as such rather than 'style nitpicks'.",
+  "last_verified": "2026-07-02",
+  "path": "skills/frontend/html-semantics-accessibility-review",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/frontend/html-semantics-accessibility-review/references/apg-pattern-index.md

@@ -0,0 +1,55 @@
+# APG Pattern Quick-Index
+
+Use this reference when a component under review is a custom (JS-driven) interactive widget and you need to identify which WAI-ARIA Authoring Practices Guide (APG) pattern applies before comparing its actual keyboard/role/state implementation against the canonical model.
+
+## What people get wrong
+
+The common bad assumption is:
+
+> "I added `role="button"` and a click handler, so it's accessible."
+
+Wrong. A role only tells assistive technology what the element *is*; it does nothing for keyboard operability, focus management, or state exposure. Every non-trivial custom widget corresponds to exactly one (sometimes zero) APG pattern, and that pattern defines a full contract: role, required/optional states and properties, and a specific keyboard interaction model — not just "Enter activates it."
+
+> Version note: WAI-ARIA and the APG evolve. Confirm the pattern's current keyboard model and required ARIA attributes via Context7 (`/mdn/content`) or the live `https://www.w3.org/WAI/ARIA/apg/patterns/` page before ruling — do not cite this file's summaries as the final word.
+
+## Non-negotiable design rule: match first, judge second
+
+Before writing any finding about a custom widget, identify its APG pattern by name. If no pattern fits, that itself is a finding: either the widget should not exist as a custom control (use a native element), or it needs a `role="group"`/`role="region"` treatment with no interactive-widget semantics at all. Never invent ad-hoc ARIA for a shape that doesn't match a documented pattern.
+
+## Common widget → pattern map (starting point, not exhaustive)
+
+| Widget seen in markup | Likely APG pattern | Minimum keyboard model to verify |
+|---|---|---|
+| Modal / overlay dialog | Dialog (Modal) | Focus moves into dialog on open; `Tab`/`Shift+Tab` trapped inside; `Escape` closes; focus returns to trigger on close |
+| Non-modal panel toggle | Disclosure (Show/Hide) | `Enter`/`Space` toggles; `aria-expanded` reflects state; no focus trap |
+| Dropdown menu (app-style, not `<select>`) | Menu / Menu Button | `Enter`/`Space`/`ArrowDown` opens; `ArrowUp`/`ArrowDown` moves; `Escape` closes and returns focus; `Home`/`End` jump to first/last |
+| Custom text input with suggestions | Combobox | `ArrowDown` opens/moves listbox; `Escape` closes without selecting; `Enter` selects active option; `aria-activedescendant` or roving `tabindex` tracks active option |
+| Tab strip | Tabs | Arrow keys move between tabs (auto- or manual-activation, pick one and document which); `Tab` key exits to panel; only active tab is in the sequential tab order |
+| Accordion | Accordion (built from Disclosure) | Each header toggles its own panel independently; heading semantics preserved (see heading-landmark-rules.md) |
+| Tree view (file explorer style) | Tree View | `ArrowUp`/`ArrowDown` moves; `ArrowRight`/`ArrowLeft` expands/collapses or moves to child/parent; `*` expands all siblings (optional) |
+| Custom slider | Slider | `ArrowLeft`/`ArrowRight` (or `Up`/`Down`) adjusts by step; `Home`/`End` jump to min/max; `aria-valuenow`/`aria-valuemin`/`aria-valuemax` kept in sync |
+| Toast / live status message | Alert or Status (live region, not a focusable widget) | No keyboard model — it must not steal focus; verify `role="alert"` (assertive, interrupting) vs `role="status"` (polite) is the deliberate choice, not a default |
+
+## Verification targets
+
+For each matched pattern, confirm in the markup/code:
+
+- the root and child elements carry the pattern's required roles (native-implicit or explicit `role=`),
+- every required `aria-*` state/property from the pattern is present and kept in sync with actual UI state (not just set once at mount),
+- the full keyboard model is implemented, not a subset — a widget with only mouse/click handlers and no `keydown` logic fails regardless of correct roles,
+- focus is visible (no `outline: none` without a replacement focus style) and moves predictably on open/close/select.
+
+## High-risk assumptions to kill
+
+- "It has the right `role`, so it's done" — role without keyboard model and state sync is theater.
+- "Semantic-sounding class name (`.dropdown-menu`) means it follows the Menu pattern" — check the actual DOM/role/keydown handlers, not the class name.
+- "We tested with the mouse and it felt fine" — APG conformance is a keyboard-first and AT-first contract; mouse-only QA proves nothing about it.
+- "It matched a pattern last time we reviewed it" — widgets drift as code changes; re-verify against the current implementation every review, not from memory of a prior review.
+
+## When to push back
+
+Push back if the user asks to:
+
+- add ARIA roles/states to make a widget "look accessible" without implementing the pattern's keyboard model,
+- ship a custom widget where a native element (`<select>`, `<details>`, `<dialog>`) would satisfy the requirement with less code and less risk,
+- treat "no pattern fits perfectly" as license to skip APG entirely rather than picking the closest pattern or reconsidering the widget design.

package/skills/frontend/html-semantics-accessibility-review/references/heading-landmark-rules.md

@@ -0,0 +1,54 @@
+# Heading and Landmark Structure Rules
+
+Use this reference when auditing the document outline of a page or component tree — heading hierarchy, landmark regions, and how components compose into a whole page's navigation structure.
+
+## What people get wrong
+
+The common bad assumption is:
+
+> "Headings are for visual size; I'll pick whichever `<h*>` looks right at this font size, and CSS will fix the rest."
+
+Wrong. Screen-reader users navigate primarily by heading level and landmark region — jumping "next heading," "next level-2 heading," or "next landmark" without reading surrounding text. A heading chosen for visual weight instead of document structure breaks that navigation model even when the page looks fine visually.
+
+## Non-negotiable design rules
+
+### 1. Heading levels must not skip
+
+`<h1>` → `<h3>` with no `<h2>` between them is a structural break, not a style inconsistency. It reads to a screen-reader user as "I jumped past something — did I miss content?" Every component that renders a heading must accept its heading level as a prop/parameter from its parent context rather than hardcoding a level, so composed pages stay contiguous.
+
+### 2. Exactly one `<h1>` per page (not per component)
+
+A component library that hardcodes `<h1>` internally breaks the instant it's composed twice on one page, or nested inside a page that already has its own `<h1>`. Components should default to accepting a level and render the semantically-correct `<h1>`–`<h6>` element for that level (not just visually restyle a `<div>`).
+
+### 3. Landmarks must be unique-per-page or explicitly labeled
+
+A page may have only one unlabeled `<main>`, one unlabeled `<banner>` (`<header>` at the top level, not nested in `<article>`/`<section>`), and one unlabeled `<contentinfo>` (`<footer>` at the top level). Multiple instances of the same landmark type (e.g., two `<nav>` regions — primary nav and breadcrumb nav) MUST each carry a distinct accessible name via `aria-label` or `aria-labelledby`, or AT users hear "navigation, navigation" with no way to distinguish them.
+
+### 4. Prefer semantic elements over `role=` on `<div>`
+
+`<nav>`, `<main>`, `<header>`, `<footer>`, `<aside>`, `<section>` (with an accessible name) carry implicit landmark roles. Adding `role="navigation"` to a `<div>` works but is strictly worse than using `<nav>` — it adds a maintenance burden (the role can drift out of sync with a renamed/refactored element) for no benefit. Flag `role=` landmark attributes on generic elements as a downgrade unless there's a documented reason (e.g., legacy browser support matrix) — see MDN ARIA landmark-role guidance via the Context7 Documentation Protocol in SKILL.md for the "semantic HTML first" rule.
+
+### 5. `<section>` and `<aside>` need an accessible name to count as landmarks
+
+A bare `<section>` with no `aria-label`/`aria-labelledby`/heading-derived name does not expose as a landmark to most assistive technology — it is a generic grouping only. Do not report "landmark added" unless the accessible-name requirement is also met.
+
+## Minimal safe audit flow
+
+1. Extract the full heading tree (level + text) for the page or component in isolation.
+2. Extract the full landmark tree (type + accessible name, or "unlabeled" if none).
+3. Diff both trees against the pre-change version when reviewing a delta; against W3C rules from scratch when reviewing a new page.
+4. Flag: any level skip, any second unlabeled instance of a unique-landmark type, any component that hardcodes a heading level instead of accepting one from its parent.
+5. For component-tree-only reviews (no full-page context available), state explicitly that heading-level correctness cannot be fully verified without knowing the mount context, and flag it as a residual risk rather than asserting compliance.
+
+## Verification targets
+
+- Render (or read) the full page and extract the accessibility tree / heading outline via a real DOM inspection when live evidence is available; note this as `live evidence`.
+- When only source is available (no live render), derive the outline from JSX/template structure and label the finding `inference` — a dynamically-computed heading level (e.g., `level={depth + 1}`) cannot be fully verified statically without knowing all call sites.
+
+## When to push back
+
+Push back if the user says:
+
+- "just use `<div class="h2">`, we'll style it to look right" — that produces zero navigable structure for AT users regardless of visual styling,
+- "we don't need `aria-label` on the second nav, screen-reader users will figure it out from context" — they cannot; landmark lists present regions out of visual context,
+- "heading levels don't matter as long as visually it looks like a hierarchy" — visual hierarchy and semantic hierarchy are independent axes; both must be correct.

package/skills/frontend/html-semantics-accessibility-review/references/wcag-criterion-mapping.md

@@ -0,0 +1,40 @@
+# WCAG 2.2 Success-Criterion Mapping
+
+Use this reference when a finding from this skill needs to be tied to a specific WCAG 2.2 success criterion (SC) for a compliance-audit deliverable — e.g. when the output feeds an ADA / Section 508 / EN 301 549 conformance report and "looks wrong" is not an acceptable citation.
+
+## Grounding rule
+
+This file gives a starting map from common findings to likely SC numbers so review output cites *something* concrete instead of vague prose. It does not replace reading the actual SC "Understanding" doc for edge cases — verify exact wording and Level (A/AA/AAA) against `https://www.w3.org/TR/WCAG22/` or via the Context7 Documentation Protocol before finalizing a compliance-facing citation, since SC numbering and scope can be easy to misremember (e.g., confusing 4.1.2 Name/Role/Value with 1.3.1 Info and Relationships).
+
+## Finding → likely success criterion
+
+| Finding category | Likely SC (Level) | Why |
+|---|---|---|
+| Heading level skip / missing heading structure | 1.3.1 Info and Relationships (A) | Structure conveyed visually must also be conveyed programmatically |
+| Duplicate unlabeled landmark of the same type | 1.3.1 Info and Relationships (A), 2.4.1 Bypass Blocks (A) | Landmarks are the mechanism for bypassing repeated content; ambiguous landmarks break that mechanism |
+| Custom widget missing/incorrect role | 4.1.2 Name, Role, Value (A) | AT must be able to programmatically determine the role of every UI component |
+| Custom widget state (`aria-expanded`, `aria-checked`, etc.) not kept in sync with actual UI state | 4.1.2 Name, Role, Value (A) | Same SC — "Value" includes states that change |
+| Custom widget missing full keyboard operability (e.g. no `Escape`, no arrow-key navigation per its APG pattern) | 2.1.1 Keyboard (A) | All functionality must be operable through a keyboard interface |
+| Positive `tabindex` values / illogical focus order | 2.4.3 Focus Order (A) | Focus order must preserve meaning and operability |
+| `outline: none` / removed focus indicator with no replacement | 2.4.7 Focus Visible (AA) | Keyboard focus indicator must be visible |
+| `aria-hidden="true"` trapping a focusable descendant | 4.1.2 Name, Role, Value (A), 2.1.1 Keyboard (A) | Element is reachable by keyboard but hidden from AT (or vice versa) — a dual failure |
+| Toast/alert stealing focus or interrupting unexpectedly | 4.1.3 Status Messages (AA) | Status messages must be programmatically determinable without receiving focus |
+| Native element replaced with unlabeled `<div>`/`<span>` + click handler (fake button/link) | 4.1.2 Name, Role, Value (A), 2.1.1 Keyboard (A) | No role exposed, no keyboard access by default |
+| Missing/incorrect accessible name on interactive control (icon-only button, ambiguous link text) | 4.1.2 Name, Role, Value (A), 2.4.4 Link Purpose (In Context) (A) | Control lacks a determinable/discriminable accessible name |
+
+## Non-negotiable rule for compliance-facing output
+
+Never present an SC citation as authoritative without the Level (A/AA/AAA) attached — an auditor reading "1.3.1" without a level cannot assess conformance-target scope (most orgs target AA). If uncertain of the exact SC number for a novel finding, say so explicitly (`inference — needs SC verification`) rather than guessing a plausible-sounding number; a wrong citation in a compliance deliverable is worse than an honest gap.
+
+## Verification targets
+
+- Cross-check any SC number cited in this table against the live WCAG 2.2 "Understanding" page for that SC before it goes into a compliance-audit-facing deliverable (not required for a routine PR review comment, where this table's mapping is sufficient).
+- For AAA-level findings, flag explicitly that AAA is rarely a required conformance target — do not imply a blocking failure at AAA carries the same severity as an A/AA failure unless the user has stated AAA is their target.
+
+## When to push back
+
+Push back if the user asks to:
+
+- label every accessibility finding as a single generic "WCAG violation" for a compliance deliverable without SC-level granularity — auditors and legal teams need the specific criterion and level,
+- downgrade a Level A finding to "nice to have" — Level A is the floor of any recognized conformance claim (WCAG A/AA/AAA, Section 508, EN 301 549 all build on Level A as mandatory),
+- treat this skill's static-review findings as a substitute for a full conformance audit — this skill narrows and grounds findings but does not replace testing with real assistive technology across the criteria this file does not cover (e.g., color contrast, captions, timing).

package/skills/frontend/i18n-l10n-readiness-review/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: i18n-l10n-readiness-review
+description: Audit frontend code for internationalization readiness — externalized ICU MessageFormat strings, Intl-based date/number/currency/plural formatting, correct lang/dir attribute propagation, and RTL-safe CSS logical properties — before translation vendor engagement, with CLDR plural-rule detail loaded only when auditing countable strings.
+allowed-tools: Read Grep Glob
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-07-02"
+  category: compliance
+---
+
+# i18n/l10n Readiness Review
+
+## Purpose
+
+Teams routinely discover — after paying a translation vendor — that string concatenation
+can't express another language's word order, pluralization breaks outside English's
+one/other split, or RTL layouts mirror visually but not functionally. Fixing these after
+translation means re-engineering already-translated strings, re-running the vendor
+pipeline, and eating the schedule slip. This skill audits pluralization architecture
+(ICU MessageFormat / CLDR plural categories), `Intl`-based formatting, `lang`/`dir`
+attribute propagation, and RTL-safe layout so the codebase is structurally
+translation-ready *before* any string reaches a translator. It does not translate
+anything itself.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- audit a codebase for hardcoded/non-externalized user-facing strings,
+- review pluralization logic against CLDR plural categories for target locales,
+- review date/number/currency formatting for `Intl` API usage vs manual string-building,
+- review layout/CSS for RTL-market readiness,
+- assess overall i18n/l10n readiness before a new-market launch or vendor engagement.
+
+## Lean operating rules
+
+- First establish the target locale list, including at least one locale with more than
+  two CLDR plural categories (e.g., Arabic: 6, Polish: 4, Russian: 4) if any countable
+  strings exist — English's one/other split hides most pluralization bugs. If the user
+  has not named target locales, ask; do not assume English-only is sufficient for a
+  "readiness" review.
+- Flag string concatenation for user-facing countable/orderable/gendered content as a
+  structural defect, not a style nit — `"You have " + count + " items"` cannot be
+  correctly localized without ICU MessageFormat (`{count, plural, ...}`) or an
+  equivalent, because plural-category counts and word order both vary by locale.
+- Verify date/number/currency/plural values use `Intl.DateTimeFormat`,
+  `Intl.NumberFormat`, or `Intl.PluralRules` (or a library wrapping them, e.g.
+  FormatJS/`react-intl`, `next-intl`, `i18next` with ICU) rather than manual string
+  building, hardcoded separators, or naive `Math.round`/string concatenation for
+  currency.
+- Check that the `dir` attribute (and `lang`) actually reach the rendered document root
+  (`<html lang dir>`) and stay in sync with the active locale, and that layout uses CSS
+  logical properties (`margin-inline-start`, `padding-inline-end`, `inset-inline-start`)
+  instead of physical properties (`margin-left`, `padding-right`, `left`) wherever an
+  RTL-market launch is on the roadmap, even if RTL isn't shipped yet — retrofitting
+  physical properties across a whole codebase later is expensive.
+- Do not treat the presence of a language switcher, an `i18next`/`next-intl`
+  dependency, or a `locales/` translation-file structure as proof of readiness — a
+  library being installed does not mean it is used correctly everywhere. Verify the
+  underlying formatting/pluralization/layout mechanics independently, file by file.
+- Never author, insert, or "helpfully" translate actual copy into another language;
+  that is the translation vendor's job. Only flag strings for extraction and hand off
+  the inventory to whoever owns translation.
+- Verify icons/imagery conveying directionality (arrows, forward/back/next controls,
+  progress indicators) have a documented RTL-mirroring plan when RTL is in scope —
+  logical CSS properties fix layout flow but do not auto-flip iconography.
+- Treat ICU plural-category coverage as version/library-sensitive: verify the exact
+  syntax and category set against current FormatJS/ECMA-402/CLDR references rather than
+  assuming a fixed one/few/many split applies to every language.
+
+## Context7 Documentation Protocol
+
+Before making any claim about ICU MessageFormat syntax, `Intl` API behavior, or a
+specific i18n library's plural/formatting API, ground it via Context7:
+
+1. Call `resolve-library-id` for the library in scope (e.g., `formatjs`, `next-intl`,
+   `react-intl`, `i18next`) or the runtime spec area (`ECMA-402`/`Intl`).
+2. Call `query-docs` for the specific syntax or API behavior before citing it (plural
+   category names, `selectordinal` syntax, `Intl.PluralRules` options, locale-matching
+   behavior).
+3. Prefer official docs (FormatJS docs, TC39 ECMA-402 spec, MDN `Intl`, Unicode CLDR)
+   over memory — plural rule sets and `Intl` option names are locale- and
+   spec-version-sensitive.
+4. If Context7 has no coverage for a library in scope, fall back to the official docs
+   listed below and mark the claim `documentation-based (uncertain — no Context7
+   coverage)`.
+5. Never invent ICU syntax, `Intl` constructor options, or CLDR plural-category names.
+   Verified from Context7 (FormatJS docs) for this skill: the canonical CLDR plural
+   categories are `zero`, `one`, `two`, `few`, `many`, `other` (not every language uses
+   every category — e.g. English uses only `one`/`other`; Arabic uses all six), and ICU
+   MessageFormat also supports exact-value matches via `=N` (e.g. `=0 {No items}`)
+   layered alongside category matches.
+
+## References
+
+Load these only when needed:
+
+- [Pluralization and ICU MessageFormat audit](references/pluralization-icu-messageformat.md)
+  — use only when auditing countable/orderable strings against CLDR plural categories
+  or reviewing ICU MessageFormat/`Intl.PluralRules` usage.
+- [Intl formatting audit](references/intl-formatting-audit.md) — use only when
+  reviewing date, number, currency, or list formatting for manual-string-building
+  defects vs correct `Intl` API usage.
+- [RTL and logical-property layout audit](references/rtl-logical-properties-audit.md)
+  — use only when reviewing `lang`/`dir` attribute propagation, CSS logical properties,
+  or directional-iconography readiness for RTL markets.
+
+## Response minimum
+
+Return, at minimum:
+
+- the target locale list driving the review (including any RTL or
+  multi-plural-category locale considered),
+- hardcoded-string inventory with file:line for user-facing countable/orderable/
+  concatenated content,
+- pluralization audit against the actual CLDR categories required for the target
+  locale(s), not just one/other,
+- RTL/logical-CSS-property findings if RTL is in scope or roadmapped, including
+  `lang`/`dir` propagation status,
+- explicit statement that translation itself was not performed by this skill and that
+  findings are a structural-readiness audit, not a translation deliverable.

package/skills/frontend/i18n-l10n-readiness-review/metadata.json

@@ -0,0 +1,28 @@
+{
+  "id": "i18n-l10n-readiness-review",
+  "name": "i18n/l10n Readiness Review",
+  "type": "skill",
+  "provider": "frontend",
+  "harnesses": [
+    "codex",
+    "claude-code",
+    "cursor",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Skill for auditing i18n architecture (ICU MessageFormat, Intl-based formatting, CLDR pluralization, RTL layout) so a frontend is structurally translation-ready before any translation vendor engagement.",
+  "source_type": "adapted",
+  "official_docs": [
+    "https://www.w3.org/International/",
+    "https://cldr.unicode.org/",
+    "https://tc39.es/ecma402/",
+    "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl",
+    "https://www.w3.org/International/articles/article-text-direction"
+  ],
+  "security_notes": "Static review only; never fabricates or inserts translated strings (that is a human/vendor task). Does not process real user-submitted locale/PII data.",
+  "last_verified": "2026-07-02",
+  "path": "skills/frontend/i18n-l10n-readiness-review",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/frontend/i18n-l10n-readiness-review/references/intl-formatting-audit.md

@@ -0,0 +1,101 @@
+# Intl Formatting Audit
+
+Use this reference only when reviewing date, number, currency, or list formatting for
+manual-string-building defects versus correct `Intl` API usage.
+
+> Version note: `Intl` constructor options are ECMA-402-spec-version-sensitive and
+> browser/runtime-support-sensitive. Verify option names (e.g., `Intl.NumberFormat`
+> `style`/`currencyDisplay`/`notation`) against the current ECMA-402 spec or MDN before
+> asserting a given option is safe to use, and check the project's minimum supported
+> runtime for coverage gaps.
+
+## What people get wrong
+
+The common bad assumption is:
+
+> "Formatting a date or currency amount is just string interpolation with the right
+> separators for each locale."
+
+That undercounts the problem. Locale-correct formatting is not just
+comma-vs-period-for-decimals — it includes:
+
+1. **Digit systems** — not every locale uses Western Arabic numerals (0-9); some use
+   native digit systems, which `Intl.NumberFormat` handles automatically when correctly
+   invoked and manual formatting will not.
+2. **Currency symbol placement and spacing** — varies by locale independent of the
+   currency itself (e.g., `$100` vs `100 $` vs `100$`); hardcoding a symbol-prefix
+   pattern breaks for locales that place it differently.
+3. **Date component order and calendar system** — month/day/year order is not
+   universal, and some locales/config combinations use non-Gregorian calendars.
+4. **Grouping separators** — thousands separators vary (`,` / `.` / space / none) and
+   are not simply swappable via find-and-replace on a fixed pattern.
+5. **List formatting** ("A, B, and C" vs "A, B и C") — conjunction/list-joining rules
+   are locale-specific and easy to miss because they're rarely tested.
+
+## Non-negotiable review rules
+
+1. **Any manually-constructed date string** (`` `${month}/${day}/${year}` ``,
+   string-padding a day/month) is a structural defect for any codebase with more than
+   one target locale — flag it regardless of whether the current output happens to
+   look correct for the developer's own locale.
+2. **Any manually-formatted currency/number string** (custom thousands-separator
+   insertion, hardcoded `$` prefix, `toFixed(2)` treated as "locale-safe currency
+   formatting") is a defect. `toFixed(2)` produces a numeric string with no locale
+   awareness at all — flag it explicitly, since it is a very common false-safe pattern.
+3. **Verify the locale passed into `Intl.*Format` constructors is the actual active
+   application locale**, not a hardcoded `'en-US'` left over from initial development
+   or scaffolding — a codebase can use `Intl.NumberFormat` correctly and still be
+   non-localized if the locale argument is hardcoded.
+4. **Currency formatting must specify `currency` explicitly and correctly per
+   transaction/display context** (`Intl.NumberFormat(locale, { style: 'currency',
+   currency: 'USD' })`) — do not accept a numeric-only format with a manually
+   concatenated currency symbol as equivalent.
+5. **Check for `Intl` availability assumptions on server vs client** — if
+   locale/currency data availability differs between the runtime's `Intl`
+   implementation and what's expected (e.g., a minimal/embedded runtime lacking full
+   CLDR data), flag it as a verification item rather than assuming full coverage.
+
+## Minimal safe audit flow
+
+1. Grep for manual date-building patterns (string concatenation with `/`, `-`, month
+   names arrays indexed by number) and manual currency/number formatting
+   (`toFixed`, manual separator insertion, hardcoded currency symbols).
+2. Grep for `Intl.DateTimeFormat`, `Intl.NumberFormat`, `Intl.ListFormat`,
+   `Intl.PluralRules`, `Intl.RelativeTimeFormat` usage and confirm the locale argument
+   is dynamic (sourced from application locale state), not a hardcoded literal.
+3. For currency displays, confirm `style: 'currency'` and an explicit `currency` code
+   are present, not a generic number format with a bolted-on symbol.
+4. For any library wrapping `Intl` (FormatJS, `next-intl`, `i18next`), confirm it is
+   actually invoked at the display sites in scope rather than assumed present because
+   it exists in `package.json`.
+5. Record each finding as file:line, the specific manual-formatting pattern found, and
+   which `Intl` API should replace it.
+
+## Adversarial checklist
+
+Before clearing formatting as "ready," answer these:
+
+- Is the locale argument passed to every `Intl.*Format` call dynamic, or is any of them
+  hardcoded to a default locale?
+- Does currency formatting specify an explicit currency code per context, or is a
+  single currency assumed globally?
+- Are there any `toFixed()` calls being treated as currency-safe?
+- Does date formatting handle non-Gregorian calendar locales if any target locale
+  requires one, or is Gregorian assumed unconditionally?
+- Is list-joining ("A, B, and C") formatted with `Intl.ListFormat` or hardcoded
+  English conjunction rules?
+
+If you cannot answer these, the formatting audit is incomplete — say so rather than
+declaring readiness.
+
+## When to push back
+
+Push back if the user asks to:
+
+- "just add a locale-to-symbol lookup table instead of `Intl.NumberFormat`" — that
+  reimplements a subset of CLDR data by hand and will drift from the real locale rules
+  over time.
+- treat visual correctness in one locale (usually the developer's own) as proof of
+  correctness for all target locales.
+- skip verifying the locale argument is dynamic because "it works in dev" — dev
+  environments frequently default to a single hardcoded locale, masking the defect.

package/skills/frontend/i18n-l10n-readiness-review/references/pluralization-icu-messageformat.md

@@ -0,0 +1,132 @@
+# Pluralization and ICU MessageFormat Audit
+
+Use this reference only when auditing countable or orderable strings against CLDR
+plural categories, or reviewing ICU MessageFormat / `Intl.PluralRules` usage.
+
+> Version note: ICU MessageFormat syntax and the exact `Intl.PluralRules` option set
+> are spec/library-version-sensitive. Verify plural-category coverage and syntax
+> against current FormatJS docs, the TC39 ECMA-402 spec, and Unicode CLDR before
+> flagging or clearing a finding.
+
+## What people get wrong
+
+The common bad assumption is:
+
+> "Pluralization is `count === 1 ? singular : plural`. Ship it."
+
+That is an English-only mental model, and it silently breaks every language that isn't
+English (and even breaks English's `zero` case: "0 items" reads oddly next to "no
+items" depending on style guide). Unicode CLDR defines up to **six** plural categories
+per locale — `zero`, `one`, `two`, `few`, `many`, `other` — and which subset a language
+uses is not predictable from English intuition:
+
+- English: `one`, `other` only.
+- Chinese, Japanese, Korean: `other` only (no grammatical number at all).
+- Arabic: all six categories (`zero`, `one`, `two`, `few`, `many`, `other`).
+- Polish, Russian: `one`, `few`, `many`, `other` (four categories, with nontrivial
+  numeric-range rules for `few` vs `many`).
+- Welsh: all six categories, with different numeric boundaries than Arabic.
+
+A codebase hardcoded to a binary singular/plural split cannot express any of the
+non-English cases correctly, no matter how good the translation is — the *structure*
+is the defect, not the wording.
+
+## Officially grounded ICU MessageFormat shape (verified via Context7 / FormatJS docs)
+
+ICU MessageFormat's `plural` argument type matches a numeric value against plural
+categories, with an escape hatch for exact-value overrides:
+
+```
+{itemCount, plural,
+    =0 {You have no items.}
+    one {You have # item.}
+    other {You have # items.}
+}
+```
+
+- `=0`, `=1`, etc. match an exact numeric value regardless of plural category — use
+  this for language-independent special cases like "no items" rather than relying on
+  `zero` (which many languages, including English, do not use as a grammatical
+  category).
+- `#` inside a plural branch is replaced with the formatted number itself; prefer it
+  over re-interpolating the same variable, per the FormatJS `prefer-pound-in-plural`
+  lint rule — re-interpolating `{itemCount}` inside the branch instead of `#` is a
+  correctness/consistency smell to flag.
+- `selectordinal` uses the same category set for ordinal forms (1st/2nd/3rd/4th in
+  English maps to `one`/`two`/`few`/`other`); do not conflate `plural` and
+  `selectordinal` — ordinal and cardinal plural rules differ per locale.
+- `select` (non-numeric) is the correct construct for gendered or enumerated branching
+  (e.g., `{gender, select, female {She} male {He} other {They}}`), not further
+  string-concatenation hacks.
+
+## Non-negotiable review rules
+
+1. **Any string containing a runtime count and user-facing text is a plural-format
+   candidate.** Concatenation (`count + " item" + (count !== 1 ? "s" : "")`) or
+   template-literal interpolation of a raw count into a fixed-plurality string is a
+   structural defect — flag it with file:line, not as a nit.
+2. **Do not accept "we only ship English" as an exemption** if the readiness review's
+   stated target locale list includes any non-English locale, or if the user is asking
+   about vendor-readiness generically. Ask for the target locale list if it wasn't
+   given — a plural defect invisible in English (one/other) can be a shipped-breaking
+   bug in Arabic or Polish.
+3. **Check that the plural/selectordinal library in use actually enforces
+   locale-correct category resolution** (e.g., `Intl.PluralRules(locale).select(n)`,
+   or a library — FormatJS/`react-intl`, `next-intl`, `i18next` with an ICU plugin —
+   that delegates to it) rather than a hand-rolled category function. A hand-rolled
+   `n === 1` check anywhere in the pipeline defeats CLDR-correct pluralization even if
+   the message strings themselves use ICU syntax.
+4. **Verify translators, not developers, control the plural branches per locale.** If
+   the plural-branch structure is hardcoded per-language in application code instead of
+   in the externalized message file, translators cannot add/remove categories for their
+   locale (e.g., adding `few`/`many` branches for Polish) without a code change —
+   flag this as a translation-workflow blocker, not just a formatting nit.
+5. **selectordinal and plural must not be conflated** even when the surface English
+   text looks similar; verify the intended semantics (count vs rank) match the ICU
+   argument type used.
+
+## Minimal safe audit flow
+
+1. Grep for user-facing string literals interpolating a numeric variable directly
+   (`` `${count} item` ``, `count + ' item'`, template literals with a count and no
+   plural handling).
+2. For each hit, confirm whether it flows through an ICU-aware formatter
+   (`FormatMessage`/`t()` with a `plural` argument, `Intl.PluralRules`) or is raw
+   concatenation.
+3. For every ICU `plural`/`selectordinal` message found, confirm branch coverage
+   against the CLDR categories actually required for the stated target locale list —
+   not just whether `one`/`other` exist.
+4. Confirm the count value passed in is a plain number (or correctly extracted from a
+   formatted value) — passing an already-formatted string (`"1,000"`) into a plural
+   selector breaks category resolution.
+5. Record findings as file:line plus the specific CLDR category gap (e.g., "Polish
+   requires `few`/`many` branches; message defines only `one`/`other`").
+
+## Adversarial checklist
+
+Before clearing a pluralization implementation as "ready," answer these:
+
+- What locale(s) actually need more than `one`/`other`, and does the target locale
+  list include any of them?
+- Is the plural-category selection delegated to `Intl.PluralRules`/an ICU library, or
+  hand-rolled?
+- Can a translator add a missing CLDR category for their locale without an engineering
+  change?
+- Are ordinal (`selectordinal`) and cardinal (`plural`) uses distinguished correctly?
+- Does any message pass a pre-formatted (comma-grouped, localized) number into the
+  plural selector instead of the raw numeric value?
+
+If you cannot answer these, the pluralization audit is incomplete — say so rather than
+declaring readiness.
+
+## When to push back
+
+Push back if the user asks to:
+
+- "just ship one/other, we'll fix it if a translator complains" — that defers a
+  structural defect into the vendor pipeline, which is exactly the expensive rework
+  this skill exists to prevent.
+- treat a passing English-only test suite as proof of pluralization correctness — it
+  cannot exercise categories English doesn't have.
+- hardcode per-locale plural logic in application code "to save time" — that blocks
+  translators from being able to fix their own locale's grammar without a release.