penpot-audit-accessibility

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: penpot-audit-accessibility
description: "Audit a Penpot design against WCAG 2.1/2.2 AA (optionally AAA) and produce a structured severity report: color contrast, touch/target sizes, text alternatives, heading hierarchy, and keyboard/focus order. Proposes fixes — does not auto-apply. Also serves as the Evaluator in the brief-to-screen and brief-to-deck loops (scope:deck = slide contrast rules). Triggers: 'check accessibility', 'accessibility audit', 'WCAG check', 'contrast audit', 'a11y review', 'check color contrast', 'is this accessible'."
disable-model-invocation: false
version: 0.3.0
audiences: [design-system, product-designer, design-engineer, migration]
mode-default: suggest
requires:
  - shared/penpot-mcp-tool-reference.md
  - shared/plugin-api-gotchas.md
  - shared/naming-conventions.md
  - shared/modes-and-policies.md
---

# penpot-audit-accessibility — WCAG AA auditor

## 1. Title + How it works
`penpot-audit-accessibility` inspects a design and reports accessibility issues. Every mutation goes
through `execute_code` (this skill only reads); validate visually with `export_shape`; read structure
with `penpotUtils.shapeStructure` (full tool surface: `shared/penpot-mcp-tool-reference.md`). It reads the object tree
(`penpotUtils.shapeStructure`/`analyzeDescendants`), computes WCAG contrast from resolved fills, checks
sizes and semantic naming, and emits a severity-ranked report. **It proposes; it does not auto-fix.**

## 2. The One Rule That Matters Most
**Report, don't silently fix.** Every issue gets severity + impact + a concrete fix + confidence.
Acceptance criteria (AA contrast, target size) are gates — a screen isn't "done" until they pass.

## 3. Penpot MCP Tool Reference
Full surface: `shared/penpot-mcp-tool-reference.md`. Key calls: `execute_code` with
`penpotUtils.analyzeDescendants` (collect text/colors/sizes), `penpot.shapesColors(shapes)` if needed;
`export_shape` to capture evidence for the report.

## 4. Plugin API Essentials
Gotcha numbers refer to `shared/plugin-api-gotchas.md`:
- **#1** — read resolved colors from `shape.fills`/`shape.strokes` (arrays; items immutable). Text color is the Text shape's fill.
- **#5** — get dimensions from `shape.width`/`shape.height`/`shape.bounds` (read-only; this skill never resizes).
- Heading hierarchy depends on **semantic layer names** (h1…h6) — if layers are unnamed, recommend `penpot-rename-layers` first.
- Focus/keyboard order is inferred from layout order + interactions; this is heuristic, flag as such.
- Verify unfamiliar signatures with `penpot_api_info` before relying on them.

## 5. Token-Aware Brief Contract
- **Context** — what's being audited (page/selection/component); product surface.
- **Objective** — single: "audit X against WCAG 2.1 AA" (state AAA if requested).
- **Inputs** — target shapes, conformance level, any known exceptions.
- **Constraints** — read-only; no canvas mutation.
- **Acceptance Criteria** — every interactive element checked; contrast 4.5:1 (normal) / 3:1 (large & UI); targets ≥24×24 (WCAG 2.2; note 44×44 for primary); headings ordered; report complete.

**`scope:deck` (slides built by `penpot-build-deck`, evaluator in `brief-to-deck`).** The scope is the
deck page; every top-level board named `NN-…` is one slide. Adjust the rules: text ≥ 24 px, or
≥ 18.67 px with `fontWeight ≥ 700`, is *large* → 3:1; smaller text → 4.5:1 (check body copy and
captions especially on gradient/glass surfaces — average the stops and flag the result as heuristic).
Skip target-size checks (a deck has no interactive controls beyond navigation). Heading hierarchy =
exactly one `h1` per slide. Report `scope` as the deck page name and name the slide in every finding.

Act as an **accessibility specialist**.

## 6. Mandatory Workflow
**Phase 0 — Inspection.** `high_level_overview`; collect data with `scripts/collectAccessibilityData.js` (`references/01-inspection.md`).

**Phase 1 — Contrast.** `scripts/checkColorContrast.js` (`references/02-contrast-c