@raishin/vanguard-frontier-agentic 3.0.2 → 3.1.0

package/skills/frontend/css-architecture-design-system-review/references/token-conformance.md

@@ -0,0 +1,58 @@
+# Design token conformance patterns
+
+Use this reference when auditing hardcoded-value drift against an existing custom-property token system, including token-tier (primitive vs. semantic vs. component) conventions.
+
+## What people get wrong
+
+The naive story is:
+
+> If a codebase has CSS custom properties, any hex code or `px` value found in a stylesheet is a violation — just swap in the nearest-looking token.
+
+Wrong on two counts. First, not every hardcoded value is drift — a one-off value with no semantic meaning (e.g. a decorative `box-shadow` blur radius unique to one component) may legitimately not belong in the token system. Second, "nearest-looking" is the wrong selection criterion: swapping a hardcoded `#3B82F6` for whatever token happens to render the closest shade of blue, without checking whether that token is semantically named for a *different* purpose (e.g. `--color-danger` vs `--color-brand-primary` happening to be visually similar), silently couples unrelated UI concerns and will drift the moment either token's value changes for its actual intended purpose.
+
+## Officially grounded shape (W3C CSS Custom Properties / MDN)
+
+- CSS custom properties (`--token-name: value;`) are just inherited, cascade-participating properties — they carry no built-in type, tier, or namespace semantics. Any tiering convention (primitive/semantic/component) is a *codebase convention*, not a CSS-spec-enforced structure. Verify the codebase's actual convention before applying a generic three-tier assumption.
+- `var(--token-name, fallback)` resolves to `fallback` only if the custom property is unset or invalid at computed-value time — an empty-string or whitespace-only fallback is valid and will not error, which can silently produce unstyled output. Flag fallback values used to paper over a token that should exist but doesn't.
+- Custom properties are visible to and overridable at any DOM node via the cascade — a component-scoped token override (e.g. `.card { --spacing-gap: 8px; }`) is a normal and often correct pattern, not automatically drift.
+
+## Non-negotiable design rules
+
+### 1. Establish which token tiers actually exist in this codebase before auditing
+
+Common conventions: **primitive** (raw values: `--blue-500: #3B82F6`), **semantic** (purpose-bound: `--color-brand-primary: var(--blue-500)`), **component** (scoped: `--button-bg: var(--color-brand-primary)`). Not every codebase has all three tiers. Read the existing token file(s) first — do not assume a tier structure the codebase hasn't adopted.
+
+### 2. Flag hardcoded values only when a token exists for that exact purpose
+
+If a semantic token like `--spacing-md` exists and a new rule hardcodes `16px` where `--spacing-md` resolves to the same value, that's drift — flag it and name the token. If no token covers that specific purpose (e.g. a genuinely one-off decorative value), do not force a token substitution; note it as "no matching token — token-system gap or legitimately one-off" and let a human decide whether to add a token.
+
+### 3. Recommend the correct tier, not just the nearest value
+
+When a hardcoded value should become a token, point to the most specific applicable tier — component tier if a component-scoped token already exists for that role, semantic tier if not, primitive tier only as a last resort (raw primitives should rarely be referenced directly from component styles; that's what semantic tokens are for). Recommending a raw primitive when a semantic token already covers the case reintroduces exactly the coupling problem tokens exist to prevent.
+
+### 4. Treat `var()` fallback values as a signal, not noise
+
+A `var(--token, <hardcoded-fallback>)` pattern used defensively across many call sites for the *same* token is a sign the token itself may be missing from some build/theme context — flag it as a build/theming risk, not a per-call-site style nitpick.
+
+### 5. Do not flag legitimate component-scoped overrides as drift
+
+`.card--compact { --card-padding: var(--spacing-sm); }` is normal token-system usage (a component redefining a token it owns, still referencing the token system). Only flag when the override value is hardcoded raw instead of referencing another token, or when it silently diverges from the token's documented purpose.
+
+## Minimal safe implementation flow
+
+1. Locate and read the codebase's token definition file(s) (commonly `:root { --... }` blocks, a `tokens.css`, or a design-tokens JSON/YAML source feeding generated CSS).
+2. Determine the tier convention in use, if any.
+3. Grep the diff/file under review for raw color (`#`, `rgb(`, `hsl(`), spacing (`px`, `rem` outside of token definitions), and typography (font-family, font-size literals) values.
+4. For each hit, check whether an existing token resolves to the same or functionally equivalent value and purpose. Report a match, a "gap" (no token exists), or confirm it's an intentional one-off.
+5. Never invent a token name that doesn't exist in the codebase and present it as if it does — only recommend using tokens that are confirmed present via Read/Grep.
+
+## Adversarial checklist
+
+Before finalizing a token-conformance finding, answer these:
+
+- Does a token actually exist for this exact purpose, confirmed via Read/Grep — not assumed from naming convention alone?
+- Am I recommending the most specific applicable tier (component > semantic > primitive), or just the first token that visually matches?
+- Could this hardcoded value be a legitimate one-off rather than drift?
+- Is this `var()` fallback masking a real token-availability gap in some theme/build context?
+
+If any answer is "not sure," report it as "no matching token found — confirm with design-system owner" rather than asserting a specific token substitution as fact.

package/skills/frontend/design-token-governance-review/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: design-token-governance-review
+description: Reviews design-token source of truth and build pipelines for hardcoded-value drift and resolved WCAG 1.4.3/1.4.11 contrast compliance across theme variants (light, dark, high-contrast), grounded in the W3C Design Tokens format and current WCAG success criteria.
+allowed-tools: Read Grep Glob
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-07-02"
+  category: compliance
+---
+
+# Design Token Governance Review
+
+## Purpose
+
+A token system only delivers its promise (consistent, themeable, accessible UI) if it is actually the single source of truth. This skill catches the two most common failure modes: hardcoded values that duplicate an existing token (silent drift) and token pairings that resolve to an inaccessible contrast ratio in some theme variant that nobody re-checked after the token value changed.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- review a design-token source file or build/transform pipeline (Style Dictionary, Tokens Studio, W3C DTCG format),
+- audit whether hardcoded colors/spacing values have crept back into components,
+- verify WCAG 1.4.3 (text contrast) or 1.4.11 (non-text/UI-component contrast) compliance for token pairings,
+- review a proposed rebrand, dark-mode, or high-contrast-mode token change for contrast regressions.
+
+## Context7 Documentation Protocol
+
+Before making any claim about token-file format, `$value`/`$type` semantics, reference resolution, transform behavior, or Storybook a11y tooling, ground the claim in current library docs:
+
+1. Call `mcp__Context7__resolve-library-id` for the library in scope (`Style Dictionary`, `Storybook`) if not already resolved in this session.
+2. Call `mcp__Context7__query-docs` with a specific query before asserting version-specific behavior (transform config shape, DTCG `$type` inheritance rules, a11y-addon detection coverage, etc.).
+3. Verified library IDs for this skill's scope: Style Dictionary `/style-dictionary/style-dictionary` (DTCG format, `$value`/`$type`, `resolveReferences`/`getReferences`, `typeDtcgDelegate` for `$type` inheritance); Storybook `/storybookjs/storybook` (`@storybook/addon-a11y`, built on axe-core, documented as catching up to ~57% of WCAG issues automatically — never represent an addon-a11y pass as full conformance).
+4. If Context7 has no coverage for a claim, fall back to the W3C Design Tokens Community Group spec (`https://tr.designtokens.org/format/`) or WCAG 2.1 normative text, and mark the claim `documentation-based` rather than `verified`.
+5. Never invent a transform name, CLI flag, or token property that was not confirmed via Context7 or the W3C spec.
+
+## Lean operating rules
+
+- Always compute the resolved contrast ratio from the actual token values in scope; a token's semantic name (`--color-text-secondary`) does not guarantee its computed contrast is compliant.
+- Check every theme variant (light, dark, high-contrast) independently; a token pairing compliant in light mode can fail in dark mode with no code-level warning.
+- Distinguish a documented, intentional design-system escape hatch (a one-off spacing value explicitly allowed by governance docs) from undocumented drift; only the latter is a finding.
+- Apply WCAG 1.4.3 (4.5:1 normal text / 3:1 large text) to text-on-background token pairings and WCAG 1.4.11 (3:1) to UI-component and graphical-object contrast (borders, focus indicators, icons) — these are different success criteria with different thresholds; do not conflate them.
+- In DTCG-format token files, resolve `{group.token}` references and `$type` group-level inheritance before evaluating a value — a token's effective type/value can come from an ancestor group, not the token's own object.
+- Require that generated token build output (CSS custom properties, JS token modules) be committed with a reviewable diff against source tokens, not silently regenerated; a build-only change with no source-token diff is itself a governance finding.
+- Treat a Storybook `@storybook/addon-a11y` pass as partial automated evidence only (axe-core-class coverage, not full conformance); it does not substitute for manually verifying contrast math on token pairings the user is asking about.
+- Load the `visual-regression-storybook-review` skill instead of this one when the question is about pixel-diff baseline approval rather than token source/contrast math.
+- This is a static-review skill: read and analyze token source files, build configs, and resolved output; do not run builds, mutate token files, or execute pipeline commands.
+
+## References
+
+Load these only when needed:
+
+- [Token source and pipeline review](references/token-source-and-pipeline-review.md) — use when reviewing DTCG/Style Dictionary token structure, reference resolution, `$type` inheritance, transform/build config, or hunting for hardcoded-value drift against an existing token set.
+- [Contrast compliance review](references/contrast-compliance-review.md) — use when computing or verifying resolved contrast ratios for token pairings against WCAG 1.4.3/1.4.11 across theme variants.
+
+## Response minimum
+
+Return, at minimum:
+
+- inventory of hardcoded-value findings with file/line and the matching existing token,
+- computed contrast ratio per token pairing reviewed, per theme variant, with WCAG pass/fail against the correct success criterion (1.4.3 vs 1.4.11),
+- evidence level (computed from provided token values vs inferred, and Context7-grounded vs documentation-based),
+- recommended governance mechanism (lint rule/CI check) to prevent recurrence,
+- security caveat if the token pipeline pulls from an external API.

package/skills/frontend/design-token-governance-review/metadata.json

@@ -0,0 +1,27 @@
+{
+  "id": "design-token-governance-review",
+  "name": "Design Token Governance Review",
+  "type": "skill",
+  "provider": "frontend",
+  "harnesses": [
+    "claude-code",
+    "cursor",
+    "codex",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Reviews design-token source of truth, build/transform pipelines, and resolved contrast ratios against WCAG 1.4.3/1.4.11 to stop hardcoded values and inaccessible token pairings from shipping across themes.",
+  "source_type": "original",
+  "official_docs": [
+    "https://www.w3.org/community/design-tokens/",
+    "https://www.w3.org/TR/WCAG21/#contrast-minimum",
+    "https://www.w3.org/TR/WCAG21/#non-text-contrast",
+    "https://amzn.github.io/style-dictionary/#/"
+  ],
+  "security_notes": "Token-source pipelines pulling from Figma/Tokens Studio APIs must use scoped, rotatable personal access tokens stored only in CI secrets, never committed to token-source config files.",
+  "last_verified": "2026-07-02",
+  "path": "skills/frontend/design-token-governance-review",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/frontend/design-token-governance-review/references/contrast-compliance-review.md

@@ -0,0 +1,90 @@
+# Contrast Compliance Review
+
+Use this reference when computing or verifying resolved contrast ratios for token pairings (text-on-background, UI-component/border/icon/focus-indicator) against WCAG success criteria 1.4.3 and 1.4.11, across every theme variant a token set ships.
+
+> Version note: Storybook addon-a11y capabilities and axe-core detection coverage evolve. Verify tool behavior against installed version and current Context7 docs before asserting coverage.
+
+## What people get wrong
+
+The naive story is:
+
+> "We ran the tokens through an automated a11y check once, so contrast is handled."
+
+Wrong, for at least three reasons:
+
+1. **One theme is not all themes.** A token pairing that passes in light mode has no automatic bearing on the same semantic pairing resolved in dark mode or high-contrast mode — each theme resolves the same token *names* to different literal values, and each resolution must be checked independently.
+2. **Automated tooling has documented, partial coverage.** Storybook's `@storybook/addon-a11y` is built on axe-core and is documented (verified via Context7, `/storybookjs/storybook`) as automatically catching up to approximately 57% of WCAG issues. A clean addon-a11y run is evidence of "no automatically detectable violation in the states exercised," not evidence of full WCAG conformance.
+3. **1.4.3 and 1.4.11 are different success criteria with different scopes and thresholds.** Treating them as interchangeable produces both false passes (applying the lower non-text threshold to body text) and false alarms (applying the text threshold to a decorative icon that WCAG doesn't require to meet either).
+
+## Officially grounded thresholds (WCAG 2.1)
+
+- **1.4.3 Contrast (Minimum):** normal text and images of text must have a contrast ratio of at least **4.5:1** against its background; large-scale text (per WCAG's definition of large text) needs at least **3:1**. This applies to text-on-background token pairings — body copy, labels, placeholder text if it conveys required information, etc.
+- **1.4.11 Non-text Contrast:** visual information required to identify UI components and states (borders on input fields, focus indicators, icons that convey meaning, graphical objects required to understand content) must have a contrast ratio of at least **3:1** against adjacent color(s). This applies to a different set of token pairings than 1.4.3 — component borders, focus rings, icon-on-background — and uses a flat 3:1 threshold regardless of size.
+- Both criteria are about **resolved, rendered** contrast — the actual sRGB values that end up on screen after every token reference and theme override is applied — not about the token's declared or "intended" relationship.
+
+## Non-negotiable design rules
+
+### 1. Compute the ratio; do not eyeball it or trust the token name
+
+Resolve both sides of the pairing (foreground token, background token) to final hex/RGB values for the theme variant under review, then compute the WCAG relative-luminance contrast ratio. A name like `--text-on-surface` does not guarantee the resolved pair clears any threshold — that is exactly the kind of drift this skill exists to catch after a rebrand or a single token-value edit.
+
+### 2. Route each pairing to the correct success criterion
+
+Before computing anything, classify the pairing: is it text-on-background (1.4.3) or a UI-component/graphical-object pairing (1.4.11)? Do not apply 4.5:1 to a focus-indicator token pairing or 3:1 to body text — cite the criterion you're actually applying, and the correct threshold for it.
+
+### 3. Every theme variant is a separate finding set
+
+Light, dark, and high-contrast (or any other shipped theme) must each be evaluated independently against the tokens that variant resolves to. A pass in one variant must never be reported as if it covers another. If a theme variant is missing from what was provided, say so explicitly as an evidence gap rather than assuming parity.
+
+### 4. Automated-tool evidence is a floor, not a ceiling
+
+If the user supplies Storybook `addon-a11y` (or equivalent axe-core-based) results, treat a "no violations" result as partial coverage evidence only, and say so using the ~57% figure grounded via Context7. Do not upgrade a clean automated run to "WCAG 1.4.3/1.4.11 compliant" without independently computing the ratio for the specific pairings in scope.
+
+### 5. State-dependent tokens need their own check
+
+Hover, focus, active, and disabled states often resolve to different token values than the resting state. A resting-state pass does not imply a focus-state pass — focus indicators are explicitly in scope for 1.4.11 and are a common place for contrast regressions to hide.
+
+## Minimal safe review flow
+
+1. Enumerate the token pairings in scope and classify each as text-on-background (1.4.3) or UI-component/graphical (1.4.11).
+2. For each theme variant provided, resolve both sides of each pairing to final color values (following token references/aliases through to their literal value for that theme).
+3. Compute the WCAG relative-luminance contrast ratio for each resolved pairing.
+4. Compare against the correct threshold for the criterion (4.5:1 normal text / 3:1 large text for 1.4.3; 3:1 for 1.4.11), and record pass/fail per pairing per theme variant.
+5. If any automated-tool evidence (addon-a11y/axe-core) was supplied, report it as supplementary partial-coverage evidence, not as the basis for the pass/fail verdict on the specific pairings you computed.
+6. Flag any state (hover/focus/active/disabled) or theme variant that was not supplied as an explicit evidence gap, not a silent pass.
+
+## Adversarial checklist
+
+Before reporting a contrast finding, answer these:
+
+- Did you resolve every token reference/alias to a literal color for the specific theme variant, or did you compute against an intermediate/aliased value?
+- Is this pairing actually text, or a UI component/icon/border — and does your cited threshold match that classification?
+- Did you check this pairing in every theme variant supplied, or only the default one?
+- Did you check the focus-visible state separately, given it is explicitly a 1.4.11 concern and often uses a different token than the resting border?
+- If you're relying on an automated tool result, did you disclose its documented partial-coverage limitation rather than presenting it as a conformance determination?
+
+If you cannot answer those, the contrast finding is not ready to report.
+
+## High-risk assumptions to kill
+
+- "The design system says this pairing is accessible" — design-system documentation can be stale relative to the current resolved token values; compute, don't cite intent.
+- "It passed axe-core in Storybook, so it's WCAG compliant" — axe-core-class tooling is documented as catching a minority of WCAG issues; contrast math specifically is one of the more reliably automatable checks, but a "pass" scope is still limited to states/variants actually exercised in the stories run.
+- "Dark mode uses the same relationships as light mode, just inverted, so it's fine" — inversion does not preserve ratios; each variant's resolved values must be computed independently.
+- "It's just a decorative icon, ignore it" — if the icon is required to identify a UI component or convey state (not purely decorative), 1.4.11 applies; verify which case it is before dismissing it.
+
+## Safe verification targets
+
+- The resolved (post-reference, post-theme-override) hex/RGB value for each side of each pairing under review, for each theme variant.
+- The computed contrast ratio and the specific criterion (1.4.3 vs 1.4.11) and threshold it was checked against.
+- Any automated-tool report supplied by the user (Storybook a11y-addon panel output, CI a11y job output), labeled as partial-coverage supplementary evidence.
+
+## When to push back
+
+Push back if the user asks you to:
+
+- report a pairing as "compliant" based on the token name or design intent alone, with no resolved-value computation,
+- treat a single theme variant's result as representative of all shipped variants,
+- treat a clean automated a11y-addon run as a full WCAG conformance statement,
+- skip focus/hover/active state checks because "the resting state passed."
+
+Those are not shortcuts. They are exactly the kind of gap this review exists to close.

package/skills/frontend/design-token-governance-review/references/token-source-and-pipeline-review.md

@@ -0,0 +1,97 @@
+# Token Source and Pipeline Review
+
+Use this reference when reviewing a design-token source file, a Style Dictionary (or equivalent) build/transform config, or hunting for hardcoded-value drift in components that should be referencing an existing token.
+
+> Version note: Style Dictionary's DTCG support and transform API are evolving. Verify exact config shape and CLI flags against the installed package version and current Context7-sourced docs before asserting behavior.
+
+## What people get wrong
+
+The naive story is:
+
+> "We have a `tokens.json` file, so we have a single source of truth."
+
+Wrong. A token file is only a source of truth if:
+
+1. every component actually consumes the *built* output of that file (not a copy-pasted value),
+2. the build step is deterministic and its output is diffed/reviewed like any other generated artifact,
+3. references between tokens (`{color.brand.500}` or DTCG `{group.token}`) resolve to what the author intended, including inherited `$type`,
+4. there is exactly one place a given design decision (a specific blue, a specific spacing step) is expressed as a literal value.
+
+Most drift findings come from case 4 breaking silently: someone needed "almost that blue" for a one-off component, typed a hex literal instead of adding/aliasing a token, and nobody caught it because nothing greps for it.
+
+## Officially grounded token shape (W3C DTCG + Style Dictionary)
+
+Per the W3C Design Tokens Community Group format and Style Dictionary's DTCG support (verified via Context7, `/style-dictionary/style-dictionary`):
+
+- Tokens are expressed with `$value` and `$type` (the `$`-prefixed form is the DTCG spec; Style Dictionary v3's unprefixed `value`/`type` is the legacy form — do not assume a codebase uses one or the other without checking the actual file).
+- `$type` can be declared on a group and inherited downward to every token in that group; a token's *effective* type is not always present on the token object itself. Style Dictionary's `typeDtcgDelegate` utility performs exactly this inheritance resolution — treat a token's type as unresolved until inheritance has been applied, not as whatever key literally appears on the leaf node.
+- Token values can reference other tokens using brace syntax (e.g. `{spacing.2}`, `{colors.black}`). `resolveReferences`/`getReferences` are the documented utilities for resolving and enumerating these; a raw, unresolved reference string is not a computed value and must not be treated as one when checking contrast or any numeric threshold.
+- Style Dictionary's DTCG conversion tooling explicitly notes that refactoring common `type` values up to a shared ancestor is a distinct, not-fully-automated step from the `value`→`$value` rename — a partially converted file (renamed values, un-hoisted types) is a legitimate mid-migration state, not automatically a defect, but it changes how you must resolve `$type` per token.
+
+## Non-negotiable design rules
+
+### 1. Resolve references and inheritance before judging a value
+
+Do not evaluate `$type` or `$value` from a token's own JSON object in isolation. Walk up the group chain for `$type` inheritance and resolve `{...}` references for `$value` before treating either as ground truth for a governance or contrast finding.
+
+### 2. A literal value is not automatically drift
+
+A hardcoded value is a finding only when a token expressing the *same design decision* already exists. A one-off value with no equivalent token, explicitly scoped and documented (e.g. a documented design-system escape hatch), is not drift. Search the resolved token set for a value/near-value match before flagging.
+
+### 3. Generated output must be reviewable, not silently regenerated
+
+CSS custom properties, JS/TS token modules, platform-specific outputs (iOS, Android) generated by the build step must be committed and diffed like source code. A change to generated output with no corresponding change to token source is itself a governance finding — it means either the build was hand-edited (breaking the source-of-truth property) or the source changed without the build being re-run and reviewed together.
+
+### 4. Distinguish legacy Style Dictionary syntax from DTCG syntax explicitly
+
+Do not assume every token file in a repo uses the same syntax. Mixed syntax across files (or a partial per-file migration) changes how references resolve (`usesDtcg` option) and is itself worth flagging if undocumented.
+
+### 5. Treat external token-source APIs as a supply-chain surface
+
+A pipeline that pulls tokens from a Figma/Tokens Studio API at build time introduces a live external dependency into every build. Credentials for that pull must be scoped, rotatable, and stored only in CI secrets — never inside the token-source config file itself (config files get committed and often copied across repos).
+
+## Minimal safe review flow
+
+1. Identify the token source format in use (legacy Style Dictionary `value`/`type` vs DTCG `$value`/`$type`) — do not assume; read the file.
+2. Resolve `$type` inheritance and `{...}` references for every token pairing under review before doing anything else with the values.
+3. Grep component source for literal values (hex colors, px/rem spacing, font-weight numbers) that match or nearly match a resolved token value.
+4. For each match, confirm whether an equivalent token already exists; if yes, it is a drift finding, if no, confirm whether it is a documented escape hatch.
+5. Check whether generated build output is committed and whether its last change correlates with a source-token change.
+6. If the pipeline pulls from an external token-source API, confirm credential handling before treating the pipeline as internally sound.
+
+## Adversarial checklist
+
+Before closing out a token-source review, answer these:
+
+- Does every component in scope actually import the *built* token output, or do some import raw source JSON directly (bypassing the build's guarantees)?
+- Is there a single token file, or multiple files that could disagree on the same design decision (e.g. two different "brand primary" definitions)?
+- If `$type` is declared only at a group level, did you resolve it before comparing the token's type to what a hardcoded value implies?
+- Does the build pipeline pin its Style Dictionary (or equivalent) version, or could an unpinned transform silently change output between builds?
+- If tokens are pulled from an external API at build time, what happens on API failure — does the build fail loud, or silently fall back to a stale cached copy?
+
+If you cannot answer those, the review is incomplete.
+
+## High-risk assumptions to kill
+
+- "It's named `--color-text-secondary`, so it must be the secondary text color used everywhere" — semantic naming does not guarantee usage consistency; grep for actual consumption.
+- "The token file is DTCG format because it has `$value`" — a file can be partially migrated; check every token, not the first one.
+- "Generated CSS is just a build artifact, no need to review it" — a hand-edited generated file silently breaks the single-source-of-truth property.
+- "One-off pixel value, not worth a token" — repeated across enough components, undocumented one-offs are exactly what token systems exist to eliminate.
+
+## Safe verification targets
+
+- Diff the token source file against the last reviewed/approved version.
+- Diff generated build output (CSS/JS) against the previous commit and correlate with the source-token diff.
+- Grep component source trees for literal color/spacing values matching resolved token values.
+- If Style Dictionary is in use, check the config file's `source`, `platforms`, and any custom transforms for anything that could alter resolved values silently (e.g. a custom color transform).
+
+## When to push back
+
+Push back if the user asks you to:
+
+- approve a generated-output change with no corresponding source-token diff ("just trust the build"),
+- treat a partially DTCG-migrated file as fully migrated without checking every token,
+- skip the drift search because "we'll catch it in visual review" (visual review does not catch a hex literal that happens to render identically to its token equivalent today but will drift on the next rebrand),
+- store token-source API credentials directly in the pipeline config for convenience.
+
+Those are not shortcuts. They erase the property the token system exists to guarantee.

package/skills/frontend/e2e-testing-playwright-review/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: e2e-testing-playwright-review
+description: Reviews Playwright end-to-end test configuration -- fixtures, storageState/auth setup, CI sharding and parallelism, and toHaveScreenshot visual-assertion options -- for reliability and correct gating, grounded in current, version-specific Playwright API docs.
+allowed-tools: Read Grep Glob
+metadata:
+  author: "github: Raishin"
+  version: "0.1.0"
+  updated: "2026-07-02"
+  category: delivery
+---
+
+# E2E Testing (Playwright) Review
+
+## Purpose
+
+Playwright E2E suites fail in two directions: they're flaky enough that teams disable them, or they're so under-configured (no sharding, no masking, no stable waits) that they're slow and noisy without adding confidence. This skill reviews Playwright-specific configuration -- fixtures, auth state, parallelism, and screenshot assertions -- against current official API behavior rather than remembered API shapes that may be stale across majors.
+
+## When to use
+
+Use this skill when the user asks to:
+
+- review or configure Playwright test fixtures, `storageState`, or auth setup,
+- diagnose Playwright test flakiness (timing, animation, non-deterministic content),
+- configure CI sharding/parallelism for a Playwright suite,
+- review or tune `toHaveScreenshot` visual-assertion options (`maxDiffPixelRatio`, `mask`, `animations`).
+
+## Context7 Documentation Protocol
+
+Playwright's config shape, CLI flags, and assertion option names change across majors and are documented, not folklore -- never assert a flag, option, or "best practice" 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 not already loaded in this session.
+2. Call `mcp__Context7__resolve-library-id` with library name `Playwright` to obtain the current Context7-compatible ID (`/microsoft/playwright`); prefer the resolved ID over guessing.
+3. Call `mcp__Context7__query-docs` for the specific claim in question -- e.g. "toHaveScreenshot maxDiffPixelRatio and mask options", "shard CLI flag and blob reporter merge", "storageState project dependencies setup" -- before stating it as fact. Do this per review, not once from a prior session's memory.
+4. Prefer the official docs URLs in `official_docs` for primary normative statements (exact CLI flags, exact config shape); use Context7 to ground and cross-check the claim before writing it into a finding.
+5. If Context7 is unavailable or returns no relevant match, fall back to the `official_docs` URLs and mark the claim `documentation-based (Context7 unavailable)` rather than presenting it as freshly verified.
+6. Never invent a config key, CLI flag, assertion option, or fixture API that no queried source confirms.
+
+## Lean operating rules
+
+- Always confirm the installed Playwright version before asserting on API option names; `toHaveScreenshot` options and CLI `--shard` syntax are stable but still verify against the project's `package.json` version, not assumption.
+- Distinguish flakiness caused by real non-determinism (animation, dynamic content, network timing) from flakiness caused by weak locators or missing waits; the fix differs, and misdiagnosis just hides a real timing bug behind a wider tolerance.
+- Recommend `animations: 'disabled'` and explicit `mask`/`stylePath` for non-deterministic regions before recommending a looser `maxDiffPixelRatio`/`maxDiffPixels`/`threshold` -- widening tolerance first papers over the actual source of visual noise.
+- Treat `storageState.json` fixtures as sensitive: they must come from a dedicated test account, never a real user session, and should not be committed if they contain live tokens (see security notes below).
+- Recommend CI sharding (`--shard=N/M` with a matrix strategy plus `blob` reporter and `merge-reports`) only after confirming the suite's actual wall-clock time in CI justifies the added job complexity and report-merge step; sharding without a merge step silently drops report coverage.
+- Prefer the setup-project/`dependencies` pattern (a dedicated `setup` project producing `storageState`, consumed via `dependencies: ['setup']`) over ad hoc `globalSetup` for auth when the project already uses Playwright's project model; both are documented, but they compose differently with sharding and per-project storage state.
+- Do not conflate `fullyParallel` (parallelizes tests within a single file, in addition to across files) with CI-level sharding (`--shard`, distributes files across separate CI jobs/machines) -- they solve different bottlenecks and a suite can need one, both, or neither.
+- Load the design-token/visual-regression skill instead of this one when the question is about baseline-approval workflow or a third-party visual-review service (e.g. Chromatic), not Playwright's own `toHaveScreenshot` config.
+
+## References
+
+Load these only when needed:
+
+- [Fixtures, auth setup, and storageState security](references/fixtures-and-auth-setup.md) -- use when reviewing or designing `storageState`/auth fixtures, `setup` project dependencies, `globalSetup`, or handling of `storageState.json`/HAR files as sensitive artifacts.
+- [CI sharding and parallelism](references/ci-sharding-and-parallelism.md) -- use when configuring or reviewing `--shard`, matrix CI strategy, blob-reporter merge, `fullyParallel`, or `workers` tuning.
+- [Visual assertion tuning (toHaveScreenshot)](references/visual-assertion-tuning.md) -- use when reviewing or tuning `toHaveScreenshot`/`toMatchSnapshot` options (`animations`, `mask`, `maxDiffPixelRatio`, `maxDiffPixels`, `threshold`, `stylePath`) or diagnosing visual-diff flakiness.
+
+## Response minimum
+
+Return, at minimum:
+
+- the Playwright feature/config area in scope (fixtures, sharding, screenshot assertion),
+- evidence level and the exact Playwright version the guidance targets,
+- root cause of any flakiness identified (not just a threshold-widening patch),
+- proposed config diff (not applied) with the option names verified against docs,
+- security caveat on any `storageState`/HAR fixture reviewed.

package/skills/frontend/e2e-testing-playwright-review/metadata.json

@@ -0,0 +1,28 @@
+{
+  "id": "e2e-testing-playwright-review",
+  "name": "E2E Testing (Playwright) Review",
+  "type": "skill",
+  "provider": "frontend",
+  "harnesses": [
+    "claude-code",
+    "cursor",
+    "codex",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Reviews Playwright end-to-end test configuration, fixtures, sharding, and screenshot-assertion setup for reliability, CI parallelism, and accurate visual/behavioral gating, grounded in current Playwright API docs.",
+  "source_type": "original",
+  "official_docs": [
+    "https://playwright.dev/docs/best-practices",
+    "https://playwright.dev/docs/ci",
+    "https://playwright.dev/docs/test-snapshots",
+    "https://playwright.dev/docs/api/class-pageassertions#page-assertions-to-have-screenshot-1",
+    "https://playwright.dev/docs/test-parallel"
+  ],
+  "security_notes": "Playwright storageState.json fixtures can capture real session cookies/auth tokens if generated against a live authenticated session; require these be generated against a dedicated test account and treated as sensitive (not committed to a public repo). HAR-file recordings used for network mocking can capture real API keys in request headers -- scrub before committing.",
+  "last_verified": "2026-07-02",
+  "path": "skills/frontend/e2e-testing-playwright-review",
+  "author": "github: Raishin",
+  "version": "0.1.0"
+}

package/skills/frontend/e2e-testing-playwright-review/references/ci-sharding-and-parallelism.md

@@ -0,0 +1,24 @@
+# CI Sharding and Parallelism
+
+Use this reference when configuring or reviewing Playwright's `--shard` CLI flag, a CI matrix strategy, blob-reporter merging, `fullyParallel`, or `workers` tuning. For auth-state interactions across sharded/parallel projects, see `fixtures-and-auth-setup.md`.
+
+> Version note: the `blob` reporter and `npx playwright merge-reports` command are the documented mechanism for combining sharded results into one report. Verify exact reporter name and CLI flags against the installed version via Context7 (`/microsoft/playwright`) or the official docs before citing them in a report.
+
+## Officially grounded design points
+
+- **`fullyParallel` and sharding solve different bottlenecks.** `fullyParallel: true` in `playwright.config.ts` parallelizes tests *within a single file* in addition to across files (by default, Playwright already parallelizes across files using `workers`). CI-level sharding (`--shard=<index>/<total>`) instead splits the *set of test files* across separate CI jobs/machines. A suite bottlenecked by one huge file with many tests needs `fullyParallel`; a suite bottlenecked by total file count/CI wall-clock time needs sharding (or both).
+- **`test.describe.parallel()`** is the documented, file-scoped alternative to global `fullyParallel` -- it opts a specific `describe` block into within-file parallel execution without changing the setting for the whole suite.
+- **Sharding requires a report-merge step to remain useful.** The documented CI pattern is: a matrix job runs `npx playwright test --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}` with `reporter: 'blob'` configured, each shard uploads its `blob-report` directory as a CI artifact, and a separate downstream job downloads all shard artifacts and runs `npx playwright merge-reports --reporter html ./all-blob-reports` to produce one combined report. Sharding without this merge step means each shard produces an isolated, easy-to-miss report instead of one gating artifact.
+- **`workers`** controls the number of parallel worker processes *within* a single Playwright invocation (i.e., within one shard/CI job); it is a separate lever from both `fullyParallel` and `--shard` and is commonly constrained by the CI runner's available CPU/memory, not just desired speed.
+
+## Non-negotiable design rules
+
+1. **Do not recommend sharding to fix flakiness.** Sharding distributes work across CI jobs; it does not change whether an individual test is flaky and can even change failure order/timing in ways that mask a root cause. If the underlying request is "the suite is unreliable," diagnose flakiness first (locators, waits, isolation) and treat sharding purely as a wall-clock-time lever.
+2. **Never introduce `--shard` without also configuring `reporter: 'blob'` and a merge job.** A sharding change that lands without the corresponding merge-reports job in CI produces N disconnected reports and typically means nobody actually reviews the combined result -- treat this as an incomplete change, not a matter of taste.
+3. **Justify sharding with a measured wall-clock baseline, not a guess.** Require the current CI suite duration before recommending a specific shard count; splitting a suite that already finishes in 3 minutes into 8 shards adds CI queueing/setup overhead without meaningful benefit and increases the merge-job's own failure surface.
+4. **Tune `workers` to the CI runner's actual resources, not a fixed "more is faster" assumption.** Over-provisioning workers on a memory-constrained runner is a documented source of resource contention that manifests as flaky, not slow, tests -- which is easy to misdiagnose as an application bug.
+5. **`fail-fast: false` in a CI matrix is the documented choice for shard jobs** so that one failing shard doesn't cancel the others and hide additional failures that would otherwise surface in the same run.
+
+## Response discipline
+
+When reviewing a sharding/parallelism setup, state the current shard count and worker configuration as found (repo/CI-config evidence), the measured baseline duration if available (or explicitly flag it as missing), and whether a `merge-reports` step exists -- an incomplete shard-without-merge config is a hard finding, not a style note.

package/skills/frontend/e2e-testing-playwright-review/references/fixtures-and-auth-setup.md

@@ -0,0 +1,26 @@
+# Fixtures, Auth Setup, and storageState Security
+
+Use this reference when reviewing or designing Playwright `storageState`/auth fixtures, a `setup` project with `dependencies`, `globalSetup`, or when a `storageState.json`/HAR file needs a security review before it's committed or shared. For sharding/parallelism interactions with per-project storage state, see `ci-sharding-and-parallelism.md`.
+
+> Version note: `storageState()` option shapes (e.g. the `indexedDB` capture flag) have been added across Playwright releases. Verify exact option availability against the installed version via Context7 (`/microsoft/playwright`) or the official docs before citing a capability as available.
+
+## Officially grounded patterns
+
+Playwright's own docs describe two supported, non-exclusive ways to produce a reusable auth state:
+
+- **Setup project + `dependencies`.** A dedicated project (e.g. `{ name: 'setup', testMatch: /.*\.setup\.ts/ }`) performs authentication once and writes `storageState` to a file (e.g. `playwright/.auth/user.json`); browser-specific projects (`chromium`, `firefox`, ...) declare `dependencies: ['setup']` and set `use: { storageState: 'playwright/.auth/user.json' }` to consume it. This is the documented pattern for reusing one authenticated session across multiple projects/browsers without re-authenticating per project.
+- **`globalSetup`.** A `globalSetup` function (referenced from `playwright.config.ts`) launches a browser, performs the login flow, and calls `page.context().storageState({ path: storageState })` once before the whole run. Both the setup-project pattern and `globalSetup` are documented; the setup-project pattern is the one that composes with `dependencies` and per-project overrides, so prefer it when the project already uses Playwright's project model.
+- **API-based auth**, skipping the UI entirely: a `setup` test can call `request.post(...)` against a login endpoint and then `request.storageState({ path: authFile })` to persist cookies/tokens without driving a browser -- faster and less flaky than a UI-driven login, when the app's auth flow supports it.
+- `storageState({ path, indexedDB: true })` is the documented way to also persist IndexedDB-backed session data (relevant for apps that store tokens in IndexedDB rather than cookies/localStorage); omitting `indexedDB: true` for such an app silently drops part of the session and can cause the "auth setup ran but tests still see a logged-out state" failure mode.
+
+## Non-negotiable design rules
+
+1. **Never generate `storageState.json` against a real user's live session.** It must come from a dedicated, disposable test account with no access to production customer data. A file captured from a real session contains live cookies/tokens that are functionally equivalent to that user's credentials.
+2. **Treat `storageState.json` as a secret artifact, not a build output.** Do not commit it to a public repository. If it must persist across CI runs, store it as a short-lived CI artifact/secret with restricted access, not a tracked file in version control.
+3. **Scrub HAR-file fixtures before committing them.** HAR recordings used for network-mocking (route interception replay) capture full request/response headers, which commonly include `Authorization` headers, API keys, or session cookies. A HAR fixture that hasn't been reviewed for these is a credential-leak risk equivalent to committing a raw token.
+4. **Re-authenticate per test-account tier, not per test.** If the suite exercises multiple roles/permission levels, use multiple named `storageState` files (one per role) produced by distinct `setup` tests, rather than one shared elevated-privilege session reused everywhere -- reusing an admin session for tests that only need a standard-user role overstates the privilege the test actually needs and can mask authorization bugs.
+5. **Expire and rotate test-account credentials used to produce fixtures on a defined cadence.** A `storageState` fixture generated from a test account whose password/token never rotates is a long-lived credential sitting in CI infrastructure.
+
+## Response discipline
+
+When reviewing fixtures, state explicitly whether the `storageState`/HAR file was confirmed to originate from a dedicated test account (repo evidence: setup-test source, CI secret config) or whether that could not be confirmed from available evidence -- do not assume test-only provenance without a citation.

package/skills/frontend/e2e-testing-playwright-review/references/visual-assertion-tuning.md

@@ -0,0 +1,28 @@
+# Visual Assertion Tuning (toHaveScreenshot)
+
+Use this reference when reviewing or tuning `toHaveScreenshot`/`toMatchSnapshot` options (`animations`, `mask`, `maskColor`, `stylePath`, `maxDiffPixelRatio`, `maxDiffPixels`, `threshold`) or diagnosing visual-diff flakiness. For flakiness caused by locators/waits rather than visual noise, that is a fixtures/timing question, not a visual-assertion-tuning one.
+
+> Version note: `toHaveScreenshot` option names below are drawn from the current `PageAssertions`/`LocatorAssertions` API reference. Verify exact defaults (e.g. whether `animations` defaults to `'disabled'` in the installed version) against Context7 (`/microsoft/playwright`) or the official API reference before citing a default value as fact.
+
+## Officially grounded option set
+
+Per the official `PageAssertions.toHaveScreenshot` / `LocatorAssertions.toHaveScreenshot` API reference, the documented tuning options include:
+
+- **`animations`** -- whether to allow or disable animations in the screenshot; the framework's internal screenshot implementation passes `animations: helper.options.animations ?? 'disabled'`, i.e. animations are suppressed by default unless explicitly overridden.
+- **`mask`** -- an array of `Locator`/`ElementHandle` values to mask out of the comparison (paired with `maskColor` to control the mask's fill color).
+- **`stylePath`** -- a path to a CSS file injected into the page before the screenshot is taken, for style-level suppression of non-deterministic elements (e.g. hiding a live clock or a carousel via CSS) that isn't practical to mask element-by-element.
+- **`clip`** / **`fullPage`** -- region-of-capture controls, independent of the diff-tolerance controls below.
+- **Diff-tolerance controls**: `maxDiffPixels` (absolute pixel count allowed to differ), `maxDiffPixelRatio` (ratio of differing pixels, 0-1), and `threshold` (a per-pixel color-difference threshold for the comparator). These can be set per-assertion call or globally in `playwright.config.ts` under `expect.toHaveScreenshot` / `expect.toMatchSnapshot`.
+- Both `toHaveScreenshot` (web-first, waits for two consecutive identical screenshots before comparing -- i.e. it has its own visual-stability wait built in) and `toMatchSnapshot` (compares an already-captured `page.screenshot()` buffer) support the diff-tolerance options; they differ in whether the wait-for-stability behavior is built in.
+
+## Non-negotiable design rules
+
+1. **Fix the non-determinism before widening tolerance.** If a diff is caused by a specific known-dynamic region (a timestamp, a live counter, an animated element, ad/embed content), the documented, targeted fix is `mask` (or `stylePath` for CSS-level suppression) on that region -- not a global increase to `maxDiffPixelRatio`/`maxDiffPixels`/`threshold`. Widening global tolerance first hides real regressions in the rest of the page along with the intended noise.
+2. **Do not disable `animations` masking as a blanket policy without checking whether the default is already `'disabled'`.** Since the built-in implementation defaults `animations` to `'disabled'` unless overridden, an explicit `animations: 'allow'` (or equivalent override) in a config/test is itself worth flagging and asking why -- it re-introduces a documented source of visual flakiness.
+3. **A widened `maxDiffPixelRatio`/`maxDiffPixels` needs a stated reason tied to a specific region or rendering variance (e.g. font anti-aliasing differences across OS/CI runners), not a round number picked to make CI green.** An unexplained tolerance value is a signal the underlying flake was never diagnosed.
+4. **Global `expect.toHaveScreenshot`/`expect.toMatchSnapshot` config in `playwright.config.ts` sets the default for the whole suite; a per-call override should be justified by why that specific assertion needs different tolerance than the suite default**, not applied broadly as a workaround for one flaky test that then silently loosens every other screenshot assertion using the same call site pattern.
+5. **`omitBackground` and `scale` affect what the baseline image actually contains** (transparency handling, DPI scaling); changing either after a baseline was captured invalidates the existing baseline and requires a deliberate baseline-update pass, not an incidental config tweak.
+
+## Response discipline
+
+When reviewing visual-assertion config, cite the specific option and value found (with file reference), state whether a wider tolerance is targeted (paired with `mask`/`stylePath` for a named dynamic region) or global/unexplained, and label the API-shape claim as `documentation-based` (grounded via Context7/official API reference this session) versus `inference`.