@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/agents/commands/gemini-cli/harness/harness.toml

@@ -0,0 +1,277 @@
+# Generated by harness generate-slash-commands. Do not edit.
+description = "Natural language router to harness skills — classifies intent, confirms, dispatches"
+prompt = '''
+<context>
+Cognitive mode: analytical-classifier
+Type: rigid
+</context>
+
+<objective>
+Natural language router to harness skills — classifies intent, confirms, dispatches
+
+Phases:
+- classify: Parse intent and search skills index for matches
+- confirm: Present routing decision with scope and reasoning
+- dispatch: Invoke selected skill via run_skill with original intent
+</objective>
+
+<execution_context>
+--- SKILL.md (agents/skills/claude-code/harness-router/SKILL.md) ---
+# Harness Router
+
+> Natural language entry point to all harness skills. Classifies user intent by scope and domain, confirms the routing decision with explicit reasoning, and dispatches to the appropriate skill.
+
+## When to Use
+
+- When the user invokes `/harness` with a natural language description of what they want
+- When the user is unsure which harness skill to use
+- When the user wants to describe their intent rather than remember a command name
+- NOT when the user already knows the specific skill (e.g., `/harness:tdd`, `/harness:planning`)
+- NOT for non-harness tasks (general coding, file operations, etc.)
+
+## Process
+
+### Iron Law
+
+**The router confirms before dispatching.** Never silently route to a skill. Always present the chosen skill, scope classification, and reasoning — then wait for the user to confirm.
+
+---
+
+### Phase 1: CLASSIFY — Parse Intent and Search
+
+1. **Check for empty input.** If no intent is provided, show usage help:
+
+   ```
+   Usage: /harness <describe what you want to do>
+
+   Examples:
+     /harness fix the button spacing on the settings page
+     /harness we need a notification system
+     /harness this page is slow
+     /harness redesign how the sidebar filters work
+     /harness clean up my code
+
+   I'll figure out the right skill and process level for you.
+   ```
+
+   Stop here — do not proceed to classification.
+
+2. **Search the skill catalog.** Call `search_skills` with the user's natural language intent as the query:
+
+   ```
+   search_skills({ query: "<user's intent>" })
+   ```
+
+   This returns ranked skill matches from the skills index.
+
+3. **Classify scope.** Based on the intent language and search results, classify into one of four tiers:
+
+   | Scope | Signal Words | Description |
+   |-------|-------------|-------------|
+   | **quick-fix** | "fix", "tweak", "adjust", "change X to Y", "update", "correct" | Small, targeted change with no design decisions |
+   | **guided-change** | "redesign", "refactor", "improve how X works", "rework" | Moderate scope, some decisions but architecture is clear |
+   | **full-exploration** | "build", "create", "add a new system for", "we need", "design" | Ambiguous scope, multiple approaches, design decisions needed |
+   | **diagnostic** | "broken", "slow", "failing", "debug", "review", "check", "analyze" | Something is broken or needs analysis |
+
+   Additional scope signals:
+   - Single file or component mentioned → lower ceremony (quick-fix or guided-change)
+   - Multiple systems or no clear target → higher ceremony (full-exploration)
+   - Error messages or symptoms → diagnostic
+
+4. **Map scope to entry skill.** Use the classification and search results to select the entry skill:
+
+   | Scope | Primary Skill | Alternates (when search results indicate better match) |
+   |-------|--------------|-------------------------------------------------------|
+   | quick-fix | `harness-tdd` | `harness-refactoring` if the intent is structural |
+   | guided-change | `harness-planning` | `harness-architecture-advisor` if tradeoffs are involved |
+   | full-exploration | `harness-brainstorming` | — |
+   | diagnostic | `harness-debugging` | `harness-code-review` for review requests, `harness-perf` for performance |
+
+   If the `search_skills` results strongly favor a specific skill that differs from the scope-based default, prefer the search result. The scope classification provides the fallback when search results are ambiguous.
+
+5. **Assess confidence.** Determine whether the match is confident or ambiguous:
+   - **High confidence:** Top search result clearly dominates, scope classification aligns with it
+   - **Low confidence:** Top 2-3 results are close in score, or scope classification points to a different skill than search results
+
+---
+
+### Phase 2: CONFIRM — Present Decision with Reasoning
+
+**High confidence (single clear match):**
+
+Present the routing decision with scope classification and reasoning:
+
+```
+This looks like a [scope-level] — [one-line reasoning about why this scope].
+
+I'll route to `harness:[skill]` because [why this skill fits the intent].
+
+Proceed? (y / n / suggest another)
+```
+
+Wait for the user to confirm before proceeding.
+
+**Low confidence (ambiguous, multiple candidates):**
+
+Present the top 2-3 candidates with descriptions:
+
+```
+This could be a few things:
+
+1. `harness:[skill-1]` — [one-line description of what this skill does]
+2. `harness:[skill-2]` — [one-line description of what this skill does]
+3. `harness:[skill-3]` — [one-line description of what this skill does]
+
+Which fits best? (1 / 2 / 3)
+```
+
+Wait for the user to choose.
+
+**User rejects the suggestion:**
+
+If the user says no or suggests a different skill:
+- If they name a specific skill, confirm and dispatch to that skill
+- If they re-phrase their intent, re-run CLASSIFY with the new phrasing
+- Do not loop more than twice — if the second attempt also misses, list all available harness skills and let the user pick
+
+---
+
+### Phase 3: DISPATCH — Invoke Selected Skill
+
+1. **Pass the original intent as context.** When invoking the selected skill, include the user's original natural language intent so they do not need to repeat themselves.
+
+2. **Invoke via `run_skill`.** Call `run_skill` with the selected skill name and the user's intent as the argument:
+
+   ```
+   run_skill({ skill: "<selected-skill>", path: "<project-root>" })
+   ```
+
+   Pass the original intent through as the skill's argument context.
+
+3. **Hand off cleanly.** Once the skill is invoked, the router's job is done. The dispatched skill owns all subsequent interaction, including any downstream chaining to other skills.
+
+---
+
+## Scope Examples
+
+### Quick Fix
+**Intent:** "fix the button spacing on the settings page"
+**Classification:** quick-fix — single component, clear target, no design decisions
+**Route:** `harness-tdd`
+
+### Guided Change
+**Intent:** "redesign how the sidebar filters work"
+**Classification:** guided-change — moderate scope, clear architecture, some decisions
+**Route:** `harness-planning` or `harness-architecture-advisor`
+
+### Full Exploration
+**Intent:** "we need a notification system"
+**Classification:** full-exploration — ambiguous scope, multiple approaches, design decisions needed
+**Route:** `harness-brainstorming`
+
+### Diagnostic
+**Intent:** "this page is slow"
+**Classification:** diagnostic — performance symptom, needs investigation
+**Route:** `harness-perf`
+
+### Ambiguous
+**Intent:** "clean up my code"
+**Classification:** ambiguous — could be refactoring, dead code removal, or architecture cleanup
+**Route:** Present candidates: `harness-refactoring`, `harness-codebase-cleanup`, `harness-cleanup-dead-code`
+
+## Harness Integration
+
+- **`search_skills`** — Used in Phase 1 to match the user's natural language intent against the skill catalog. Returns ranked results based on keyword, description, and stack-signal matching.
+- **`run_skill`** — Used in Phase 3 to dispatch to the selected skill. Passes the project path and original intent as context.
+- **`harness validate`** — Not directly used by the router. Validation is the responsibility of the dispatched skill.
+
+## Success Criteria
+
+- `/harness fix the button spacing on the settings page` routes to `harness-tdd` with scope "quick-fix" and confirms before dispatching
+- `/harness we need a notification system` routes to `harness-brainstorming` with scope "full-exploration" and confirms before dispatching
+- `/harness clean up my code` (ambiguous) presents top 2-3 candidates and lets user choose
+- `/harness this page is slow` routes to a diagnostic skill with reasoning
+- `/harness redesign how the sidebar filters work` routes to `harness-planning` or `harness-architecture-advisor` with scope "guided-change"
+- Confirmation always includes: scope classification, chosen skill, and one-line reasoning
+- User can reject the suggestion and re-phrase or pick a different skill
+- Dispatched skill receives the original natural language intent as context
+- `search_skills` MCP tool is used for matching — no custom scoring code
+- `/harness` with no arguments shows usage help with examples
+
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+|----------------|---------|
+| "The intent is obvious, I can skip the confirmation step" | The Iron Law requires confirmation before every dispatch. Even obvious intents benefit from the user seeing the scope classification — it catches misunderstandings early. |
+| "I should also suggest downstream skills the dispatched skill will chain into" | Each skill owns its own transitions. Surfacing the full chain adds noise and duplicates logic that already exists in the dispatched skill. |
+| "The search results don't match well, so I'll just guess based on keywords" | If `search_skills` returns poor results, present the top candidates and let the user choose. Guessing silently is worse than admitting ambiguity. |
+| "The user rejected my suggestion twice, I should keep trying" | After two misses, list available skills and let the user pick directly. Do not loop indefinitely. |
+
+## Gates
+
+- **No silent dispatch.** Every routing decision must be confirmed by the user before the skill is invoked. No exceptions.
+- **No bypassing search_skills.** The skill catalog search must be used for matching. Do not hardcode intent-to-skill mappings or rely solely on keyword heuristics.
+- **No downstream chaining.** The router dispatches to exactly one skill. It does not pre-load or suggest the skills that will follow.
+- **No more than two re-classification attempts.** If the user rejects twice, show the full list and let them pick.
+
+## Escalation
+
+- **When `search_skills` returns no results:** The skills index may be stale or missing. Suggest the user run `harness update-skills-index` to regenerate it, then retry.
+- **When the user's intent spans multiple skills:** Ask: "This sounds like it involves both [skill A] and [skill B]. Which should we start with?" Do not attempt to dispatch to multiple skills simultaneously.
+- **When the user asks for something outside the harness skill catalog:** Say so plainly: "This doesn't match any harness skill. You may want to handle this directly, or describe the task differently if you think a harness skill should apply."
+
+
+--- skill.yaml (agents/skills/claude-code/harness-router/skill.yaml) ---
+name: harness-router
+version: "1.0.0"
+description: Natural language router to harness skills — classifies intent, confirms, dispatches
+cognitive_mode: analytical-classifier
+command_name: harness
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Read
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-router
+  args:
+    - name: intent
+      description: Natural language description of what the user wants
+      required: true
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-router
+    path: string
+type: rigid
+tier: 1
+phases:
+  - name: classify
+    description: Parse intent and search skills index for matches
+    required: true
+  - name: confirm
+    description: Present routing decision with scope and reasoning
+    required: true
+  - name: dispatch
+    description: Invoke selected skill via run_skill with original intent
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []
+addresses:
+  - signal: high-complexity
+    weight: 0.3
+
+</execution_context>
+
+<process>
+1. Try: invoke mcp__harness__run_skill with skill: "harness-router"
+2. If MCP unavailable: follow the SKILL.md workflow provided above directly
+3. Pass through any arguments provided by the user
+</process>
+'''

package/dist/agents/skills/README.md

@@ -37,13 +37,14 @@ agents/skills/
 - `initialize-harness-project` - Scaffold new project
 - `add-harness-component` - Add components
 
-### Graph Integration Levels
+### Skill Catalog
 
-**Graph-Transformed** (7 skills): harness-code-review, validate-context-engineering, detect-doc-drift, cleanup-dead-code, harness-parallel-agents, enforce-architecture, harness-onboarding
+The library contains **540 skills** across all 4 platforms (claude-code, gemini-cli, cursor, codex), including:
 
-**Graph-Enhanced** (5 skills): harness-execution, harness-planning, harness-architecture-advisor, harness-refactoring, align-documentation
-
-**Graph-Enabled** (5 new skills): harness-impact-analysis, harness-dependency-health, harness-hotspot-detector, harness-test-advisor, harness-knowledge-mapper
+- **74 harness-\* skills** — methodology, workflow, and operational skills (brainstorming, planning, execution, code-review, debugging, release-readiness, etc.)
+- **55 design-\* skills** — design knowledge across color, typography, layout, Gestalt, interaction, motion, design systems, platform languages, and process
+- **Framework skills** — react, vue, angular, svelte, astro, next, nuxt, node, nestjs, graphql, trpc, prisma, drizzle, tanstack, redux, xstate, zod, and more
+- **Knowledge skills** — gof patterns, owasp security, otel observability, test patterns, microservices, events, resilience, typescript, and more
 
 ## Usage
 

package/dist/agents/skills/claude-code/a11y-aria-patterns/SKILL.md

@@ -0,0 +1,183 @@
+# ARIA Patterns
+
+> Apply ARIA roles, states, and properties correctly to enhance assistive technology support for custom widgets
+
+## When to Use
+
+- Building custom interactive widgets that have no native HTML equivalent
+- Adding accessible names or descriptions to elements
+- Announcing dynamic content changes to screen readers
+- Indicating expanded/collapsed, selected, or error states
+- When native HTML semantics are insufficient (and only then)
+
+## Instructions
+
+1. **Follow the first rule of ARIA: do not use ARIA if native HTML works.** A `<button>` is better than `<div role="button">`. A `<nav>` is better than `<div role="navigation">`. ARIA overrides semantics; native HTML provides them for free.
+
+2. **Use `aria-label` and `aria-labelledby` to provide accessible names.** Every interactive element needs an accessible name — screen readers announce it.
+
+```tsx
+// aria-label — inline text label (when no visible label exists)
+<button aria-label="Close dialog">
+  <XIcon />
+</button>
+
+// aria-labelledby — reference a visible label element
+<h2 id="dialog-title">Confirm Deletion</h2>
+<div role="dialog" aria-labelledby="dialog-title">
+```
+
+- Prefer `aria-labelledby` over `aria-label` when a visible text element exists — it avoids translation gaps.
+- `aria-label` replaces the element's visible text for screen readers. If the button says "X", `aria-label="Close"` makes screen readers say "Close button."
+
+3. **Use `aria-describedby` for supplementary information.** Unlike `aria-labelledby` (which names the element), `aria-describedby` provides additional context read after the name.
+
+```tsx
+<input
+  type="password"
+  aria-label="Password"
+  aria-describedby="password-help"
+/>
+<p id="password-help">Must be at least 8 characters with one number.</p>
+```
+
+4. **Use `aria-live` regions to announce dynamic content.** When content updates without a page reload (toast notifications, form validation, live scores), use `aria-live` to announce the change.
+
+```tsx
+// polite — waits for the screen reader to finish current speech
+<div aria-live="polite" role="status">
+  {statusMessage}
+</div>
+
+// assertive — interrupts current speech (use sparingly)
+<div aria-live="assertive" role="alert">
+  {errorMessage}
+</div>
+```
+
+- Render the live region in the DOM before populating it — screen readers only track changes to existing live regions.
+- Use `role="status"` for informational updates and `role="alert"` for urgent errors.
+
+5. **Use state attributes to reflect widget state.** Keep ARIA states synchronized with visual state.
+
+```tsx
+// Expandable section
+<button
+  aria-expanded={isOpen}
+  aria-controls="panel-1"
+  onClick={() => setIsOpen(!isOpen)}
+>
+  Settings
+</button>
+<div id="panel-1" hidden={!isOpen}>
+  {/* panel content */}
+</div>
+
+// Toggle button
+<button aria-pressed={isMuted} onClick={toggleMute}>
+  Mute
+</button>
+
+// Disabled state
+<button aria-disabled={isSubmitting} onClick={isSubmitting ? undefined : handleSubmit}>
+  Submit
+</button>
+```
+
+6. **Use `aria-hidden="true"` to hide decorative or redundant content from screen readers.** Icons next to text labels, decorative images, and duplicate content should be hidden.
+
+```tsx
+<button>
+  <SearchIcon aria-hidden="true" />
+  <span>Search</span>
+</button>
+```
+
+Do not use `aria-hidden="true"` on focusable elements — it creates a confusing state where the element receives focus but is invisible to assistive technology.
+
+7. **Use roles for custom widgets that have no native equivalent.** Common role patterns:
+
+```tsx
+// Tab interface
+<div role="tablist">
+  <button role="tab" aria-selected={activeTab === 0} aria-controls="panel-0">Tab 1</button>
+  <button role="tab" aria-selected={activeTab === 1} aria-controls="panel-1">Tab 2</button>
+</div>
+<div role="tabpanel" id="panel-0" aria-labelledby="tab-0">Content 1</div>
+
+// Combobox (autocomplete)
+<input role="combobox" aria-expanded={isOpen} aria-controls="listbox-1" aria-activedescendant={activeOptionId} />
+<ul role="listbox" id="listbox-1">
+  <li role="option" id="opt-1" aria-selected={selected === 'opt-1'}>Option 1</li>
+</ul>
+
+// Alert dialog
+<div role="alertdialog" aria-labelledby="alert-title" aria-describedby="alert-desc">
+  <h2 id="alert-title">Delete Account?</h2>
+  <p id="alert-desc">This action cannot be undone.</p>
+  <button>Cancel</button>
+  <button>Delete</button>
+</div>
+```
+
+8. **Use `aria-invalid` and `aria-errormessage` for form validation errors.**
+
+```tsx
+<input
+  aria-invalid={!!errors.email}
+  aria-errormessage={errors.email ? 'email-error' : undefined}
+/>;
+{
+  errors.email && (
+    <span id="email-error" role="alert">
+      {errors.email}
+    </span>
+  );
+}
+```
+
+## Details
+
+**ARIA categories:**
+
+- **Roles:** Define what an element is (e.g., `tab`, `dialog`, `alert`, `progressbar`). Set once; do not change dynamically.
+- **States:** Dynamic boolean/tristate values that change with user interaction (e.g., `aria-expanded`, `aria-selected`, `aria-pressed`).
+- **Properties:** Relatively static attributes that describe relationships or characteristics (e.g., `aria-label`, `aria-describedby`, `aria-controls`).
+
+**The five rules of ARIA:**
+
+1. Do not use ARIA if native HTML works.
+2. Do not change native semantics (do not put `role="button"` on an `<a>`).
+3. All interactive ARIA elements must be keyboard-operable.
+4. Do not use `role="presentation"` or `aria-hidden="true"` on focusable elements.
+5. All interactive elements must have an accessible name.
+
+**Common mistakes:**
+
+- Adding `role="button"` without keyboard support (Enter and Space activation)
+- Using `aria-label` on non-interactive elements where it has no effect
+- Setting `aria-expanded` without updating it when state changes
+- Overusing `aria-live="assertive"` (interrupts users constantly)
+- Using `aria-hidden="true"` on a parent containing focusable children
+
+**Testing:** Use the accessibility tree in browser DevTools to verify that ARIA attributes produce the expected accessible name, role, and state.
+
+## Source
+
+https://www.w3.org/TR/wai-aria-1.2/
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/claude-code/a11y-aria-patterns/skill.yaml

@@ -0,0 +1,43 @@
+name: a11y-aria-patterns
+version: '1.0.0'
+description: Apply ARIA roles, states, and properties correctly to enhance assistive technology support
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.tsx'
+  - '**/*.html'
+  - '**/*.vue'
+  - '**/*.svelte'
+  - '**/*.astro'
+related_skills:
+  - a11y-semantic-html
+  - a11y-keyboard-navigation
+  - a11y-screen-reader-testing
+stack_signals:
+  - accessibility
+  - react
+  - typescript
+keywords:
+  - aria
+  - roles
+  - aria-label
+  - aria-describedby
+  - aria-live
+  - aria-expanded
+  - aria-hidden
+metadata:
+  author: community
+  upstream: w3.org/TR/wai-aria-1.2
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/a11y-color-contrast/SKILL.md

@@ -0,0 +1,156 @@
+# Color Contrast and Color Independence
+
+> Ensure sufficient color contrast ratios and never use color as the sole means of conveying information
+
+## When to Use
+
+- Choosing text and background color combinations
+- Designing UI states (error, success, warning) that rely on color
+- Building data visualizations, charts, or status indicators
+- Reviewing designs for WCAG 2.1 AA or AAA compliance
+- Supporting users with low vision or color vision deficiency
+
+## Instructions
+
+1. **Meet minimum contrast ratios.** WCAG 2.1 AA requires:
+   - **Normal text** (under 18pt / 24px, or under 14pt / 18.5px bold): **4.5:1** contrast ratio
+   - **Large text** (18pt+ or 14pt+ bold): **3:1** contrast ratio
+   - **Non-text UI components** (icons, borders, form controls): **3:1** against adjacent colors
+
+```css
+/* Good — #1a1a1a on #ffffff = 17.4:1 */
+.body-text {
+  color: #1a1a1a;
+  background: #ffffff;
+}
+
+/* Bad — #999999 on #ffffff = 2.8:1 (fails AA) */
+.muted-text {
+  color: #999999;
+  background: #ffffff;
+}
+
+/* Acceptable for large text — #767676 on #ffffff = 4.5:1 */
+.large-heading {
+  color: #767676;
+  font-size: 24px;
+  font-weight: bold;
+}
+```
+
+2. **Never use color alone to convey information.** Always pair color with a secondary indicator — text, icons, patterns, or underlines.
+
+```tsx
+// Bad — only color distinguishes error from success
+<span style={{ color: 'red' }}>Failed</span>
+<span style={{ color: 'green' }}>Passed</span>
+
+// Good — color + icon + text label
+<span style={{ color: '#d32f2f' }}>
+  <ErrorIcon aria-hidden="true" /> Failed
+</span>
+<span style={{ color: '#2e7d32' }}>
+  <CheckIcon aria-hidden="true" /> Passed
+</span>
+```
+
+3. **Test link visibility without relying on color alone.** Links within body text should have an underline or other non-color visual distinction. If you remove underlines, ensure a 3:1 contrast ratio between link color and surrounding text color.
+
+```css
+/* Safe — underline present */
+a {
+  color: #005fcc;
+  text-decoration: underline;
+}
+
+/* Also safe — 3:1 contrast between link color and body text color, plus underline on hover/focus */
+a {
+  color: #005fcc;
+  text-decoration: none;
+}
+a:hover,
+a:focus {
+  text-decoration: underline;
+}
+```
+
+4. **Design form validation with multiple cues.** Do not rely solely on a red border to indicate errors. Add an error message, an icon, or both.
+
+```tsx
+<div>
+  <label htmlFor="email">Email</label>
+  <input
+    id="email"
+    aria-invalid={!!error}
+    aria-describedby={error ? 'email-error' : undefined}
+    style={{ borderColor: error ? '#d32f2f' : '#ccc' }}
+  />
+  {error && (
+    <p id="email-error" role="alert" style={{ color: '#d32f2f' }}>
+      <ErrorIcon aria-hidden="true" /> {error}
+    </p>
+  )}
+</div>
+```
+
+5. **Use patterns, shapes, or labels in data visualizations.** Charts with color-coded series are unreadable for color-blind users. Add patterns, direct labels, or shape markers.
+
+6. **Check contrast for all interactive states.** Hover, focus, active, disabled, and selected states all need to meet contrast requirements against their backgrounds.
+
+7. **Test with simulated color vision deficiency.** Chrome DevTools > Rendering > Emulate vision deficiencies. Test with protanopia, deuteranopia, tritanopia, and achromatopsia.
+
+8. **Design high-contrast mode support.** Windows High Contrast Mode overrides your colors. Use `forced-colors` media query to ensure readability.
+
+```css
+@media (forced-colors: active) {
+  .custom-checkbox {
+    border: 2px solid ButtonText;
+  }
+}
+```
+
+## Details
+
+**WCAG contrast levels:**
+
+- **AA (minimum):** 4.5:1 for normal text, 3:1 for large text and UI components
+- **AAA (enhanced):** 7:1 for normal text, 4.5:1 for large text
+- Target AA for all projects; target AAA for government, healthcare, and financial applications
+
+**Contrast ratio formula:** Based on relative luminance of the two colors. Use tools to calculate — do not eyeball it.
+
+**Recommended tools:**
+
+- Browser DevTools: Hover over elements to see contrast ratio in the color picker
+- WebAIM Contrast Checker: https://webaim.org/resources/contrastchecker/
+- axe DevTools: Flags contrast violations automatically
+- Stark (Figma plugin): Check contrast during design
+
+**Color-blind-safe palettes:** Approximately 8% of males and 0.5% of females have color vision deficiency. Red-green is the most common. Avoid red/green as the only distinction. Blue/orange is generally safe across all types.
+
+**Common mistakes:**
+
+- Placeholder text with insufficient contrast (often fails AA)
+- Disabled states that are indistinguishable from enabled states
+- Focus indicators that disappear against the background
+- Charts using red, green, and yellow without patterns or labels
+
+## Source
+
+https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.