# accessible-design

Adopt this skill: https://proskills.md/skills/other/kinwisenz-devops-ui-ux-designer-skills-accessible-design

Page: https://proskills.md/skills/other/kinwisenz-devops-ui-ux-designer-skills-accessible-design
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/accessible-design/SKILL.md
size: 5337
sha: d640b16fb6844862b2669c86d43fceb845f7c7b4
upstream: https://github.com/kinwisenz-devops/ui-ux-designer/blob/main/skills/accessible-design/SKILL.md

````text
---
name: accessible-design
description: >
  Use when checking or designing for accessibility on mobile, tablet or desktop:
  touch target size, contrast, text scaling, screen readers (VoiceOver,
  TalkBack), keyboard and switch use, reduce motion, WCAG 2.2 criteria, or an
  accessibility checklist for a design. Do not use for general visual styling
  (visual-design-system), legal compliance claims, or writing accessibility
  code for a framework.
---

# Accessible Design

Stance: frozen are WCAG 2.2 AA as the floor, platform minimums for touch, and no information carried by one sense only. Flexible are how each requirement is met in a given design.

## Hard rules

- Touch targets: 44 x 44 pt on iOS (28 pt hard minimum), 48 x 48 dp on Android and the web, 8 dp apart; WCAG 2.2 AA floor is 24 x 24 CSS px or 24 px of spacing. Mechanism: small or crowded targets cause mis-taps and exclude people with tremor; the visible icon may be smaller if the hit area is padded.
- Contrast 4.5:1 for text and 3:1 for large text and meaningful controls (WCAG 1.4.3, 1.4.11). Mechanism: low contrast fails low vision and glare.
- Text must scale to large sizes and reflow at 320 CSS px without clipping (WCAG 1.4.4, 1.4.10). Mechanism: fixed-height boxes cut off enlarged text.
- Every control has a name, role and state a screen reader can announce; reading order follows visual order. Mechanism: unlabeled icon buttons are silent or read as "button".
- Do not rely on gestures, drags or multi-finger input alone; give a single-tap or button path (WCAG 2.5.7). Mechanism: switch, voice and keyboard users cannot perform them.
- Focus is always visible and not hidden behind sticky bars (WCAG 2.4.11). Mechanism: keyboard and switch users lose their place.
- Never use colour, sound, haptics or motion as the only signal. Mechanism: each fails for some users; pair them.
- Sign-in must not demand memory tests, puzzles or transcription without alternatives (WCAG 3.3.8). Mechanism: cognitive load blocks access; allow paste, password managers and passkeys.
- State accessibility claims as "meets criterion X at level AA" with the check made; never "fully accessible" or "compliant". Mechanism: conformance needs scope and evidence.
- Act only on what the user asked. Before answering or changing anything, open the relevant files and check what is already done; report only what you checked, never guess, and do not redo finished work. Reason: guesses and repeated work waste the user's credit.

## Gate

| Situation | Action |
|---|---|
| Quick design check | Run the checklist; mark untested items |
| Formal audit requested | Say what an automated and manual check cover; recommend testing with disabled users; no compliance claim |
| A hard-to-hit control needed (dense map pins) | Treat as the "essential" exception; offer an alternative way |
| Request to drop a requirement for looks | Offer a design that keeps the requirement (padded hit area, darker shade) |

## Steps

1. **Targets.** Measure hit areas, not visuals. Use [targets-and-contrast.md](references/targets-and-contrast.md).
2. **Contrast.** Compute ratios for text, icons, borders and focus rings, in each theme.
3. **Text scaling.** Check largest system size and browser zoom to 400 percent.
4. **Screen reader pass.** Name every control; set order; group; mark decorative images; announce state changes.
5. **Input alternatives.** Check one-finger, keyboard, switch and voice paths for each task.
6. **Motion and time.** Honour reduce motion; avoid flashing; allow extensions on time limits.
7. **Errors and help.** Identify the field, explain the fix; keep help in a consistent place (WCAG 3.2.6).
8. **Report** what passed, failed and was not tested, with the criterion for each.

## Checklist (copy into the reply and tick as you go)

```text
- [ ] Targets sized and spaced per platform
- [ ] Contrast checked in each theme
- [ ] Largest text and 320 CSS px tested
- [ ] Names, roles, order set for a screen reader
- [ ] Single-pointer alternative for gestures and drags
- [ ] Visible focus, not obscured
- [ ] No signal carried by one sense only
- [ ] Authentication has an alternative
- [ ] Untested items listed
```

## Examples

**Example 1: icon toolbar**
User says: "Check this toolbar of five 24 px icons for accessibility."
Actions: measure hit areas; propose 48 dp padded areas with 8 dp gaps; require accessible names for each icon; check icon contrast at 3:1.
Result: a list of failures with fixes and criterion numbers.

**Example 2: ask for a certificate**
User says: "Tell me this app is WCAG compliant."
Actions: decline a blanket claim; state which criteria were checked and how; list untested areas.
Result: an honest scoped statement.

## Common issues

- **Icon buttons read as just "button".** Cause: no accessible name. Fix: add a label matching the visible meaning.
- **Large text breaks the layout.** Cause: fixed heights. Fix: allow growth and wrap.
- **Custom control invisible to a screen reader.** Cause: no role or state exposed. Fix: use the platform control or expose role, name and value.

## References

- [targets-and-contrast.md](references/targets-and-contrast.md): target sizes, contrast values and WCAG 2.2 mobile criteria.

## Next

[ux-review-and-testing](../ux-review-and-testing/SKILL.md) to run the checks with real users.
````

## File: skills/accessible-design/references/targets-and-contrast.md
size: 2692
sha: 9511f1c5b9178659c47dd9e2917ff4dd62a0e4c1
upstream: https://github.com/kinwisenz-devops/ui-ux-designer/blob/main/skills/accessible-design/references/targets-and-contrast.md

```text
# Targets, contrast and WCAG 2.2 criteria

Contents: target sizes, spacing, contrast values, WCAG 2.2 criteria that matter on mobile, testing tools.

## Touch target sizes

| Source | Recommended | Minimum |
|---|---|---|
| Apple HIG, iOS and iPadOS | 44 x 44 pt | 28 x 28 pt |
| Apple HIG, macOS | 28 x 28 pt | 20 x 20 pt |
| Apple HIG, visionOS | 60 x 60 pt | 28 x 28 pt |
| Android accessibility help | 48 x 48 dp (about 9 mm) | keep 48 |
| web.dev | about 48 CSS px, 8 px apart | |
| WCAG 2.2 SC 2.5.8, Level AA | | 24 x 24 CSS px, or a 24 px circle around the target not touching another |
| WCAG 2.2 SC 2.5.5, Level AAA | | 44 x 44 CSS px |

Spacing: Apple suggests about 12 pt around bezelled controls and 24 pt around borderless ones. Android suggests 8 dp between targets.

Exceptions to 2.5.8: spacing, an equivalent control on the page, inline links in text, browser-controlled controls, essential size.

Technique: keep the visible icon small and pad the hit area (padding, minimum size, or an enlarged touch area). On the web, enlarge only for touch with the coarse pointer media query.

## Contrast

| Item | Minimum ratio | Criterion |
|---|---|---|
| Text up to 17 pt (not bold) | 4.5:1 | 1.4.3 AA |
| Text 18 pt and above, or bold | 3:1 | 1.4.3 AA |
| Icons, input borders, focus indicators | 3:1 | 1.4.11 AA |
| Disabled controls | exempt, but keep them recognisable | |

Support Increase Contrast and test both light and dark themes.

## WCAG 2.2 criteria with mobile impact

| Criterion | Level | Plain meaning |
|---|---|---|
| 1.4.4 Resize Text | AA | text can reach 200 percent without loss |
| 1.4.10 Reflow | AA | works at 320 CSS px wide, no two-way scrolling (maps, tables, video exempt) |
| 2.4.11 Focus Not Obscured (Minimum) | AA | focused item not fully hidden by sticky content |
| 2.5.7 Dragging Movements | AA | any drag has a single-pointer alternative |
| 2.5.8 Target Size (Minimum) | AA | 24 x 24 CSS px or spacing |
| 3.2.6 Consistent Help | A | help options stay in the same relative place |
| 3.3.7 Redundant Entry | A | do not ask for the same information twice in one process |
| 3.3.8 Accessible Authentication (Minimum) | AA | no memory test, puzzle or transcription without an alternative |

W3C has no separate mobile standard: WCAG 2 applies to mobile web, native and hybrid apps, and a WCAG2Mobile draft explains how.

## Testing tools

- Android: Accessibility Scanner, TalkBack, Espresso accessibility checks.
- iOS: Accessibility Inspector, VoiceOver, Dynamic Type and Increase Contrast settings.
- Web: browser zoom to 400 percent, keyboard-only pass, contrast checker.
- Real users with disabilities give evidence automated tools cannot.
```

## File: README.md
upstream: https://github.com/kinwisenz-devops/ui-ux-designer/blob/main/README.md

````text
```
██╗   ██╗██╗    ██╗   ██╗██╗  ██╗
██║   ██║██║    ██║   ██║╚██╗██╔╝
██║   ██║██║    ██║   ██║ ╚███╔╝
██║   ██║██║    ██║   ██║ ██╔██╗
╚██████╔╝██║    ╚██████╔╝██╔╝ ██╗
 ╚═════╝ ╚═╝     ╚═════╝ ╚═╝  ╚═╝
██████╗ ███████╗███████╗██╗ ██████╗ ███╗   ██╗███████╗██████╗
██╔══██╗██╔════╝██╔════╝██║██╔════╝ ████╗  ██║██╔════╝██╔══██╗
██║  ██║█████╗  ███████╗██║██║  ███╗██╔██╗ ██║█████╗  ██████╔╝
██║  ██║██╔══╝  ╚════██║██║██║   ██║██║╚██╗██║██╔══╝  ██╔══██╗
██████╔╝███████╗███████║██║╚██████╔╝██║ ╚████║███████╗██║  ██║
╚═════╝ ╚══════╝╚══════╝╚═╝ ╚═════╝ ╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝
```

<div align="center">

# 📱 UI UX Designer

**Mobile-first UI and UX design skills that also work on tablet and desktop, for designers, developers and their agents.**

[![Validate skills](https://github.com/KinwiseNZ-DevOps/ui-ux-designer/actions/workflows/validate.yml/badge.svg)](https://github.com/KinwiseNZ-DevOps/ui-ux-designer/actions/workflows/validate.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Agent skills](https://img.shields.io/badge/agent_skills-9-8A2BE2)](https://agentskills.io)
[![Format](https://img.shields.io/badge/format-SKILL.md-orange)](https://agentskills.io/specification)
[![Tooling](https://img.shields.io/badge/tooling-stdlib_only-success)](scripts/skills_tool.py)

</div>

Table of contents:

- [Skills](#skills)
- [How they fit together](#how-they-fit-together)
- [Install](#install)
- [Usage](#usage)
- [Validate](#validate)
- [Layout](#layout)
- [Works with other repos](#works-with)
- [Status and limits](#status-and-limits)

---

> [!IMPORTANT]
> **Principle: design for the smallest screen, the thumb and the slowest moment first, then add space for larger screens without removing function, and never trade accessibility for looks.**

These skills help an agent design, review and document interfaces for phones first, then tablets and desktops. They are grounded in Apple's Human Interface Guidelines, Android and WCAG 2.2 guidance, Nielsen Norman Group research, and the Toptal and Mockflow mobile UX articles, and every number is attributed to its source. They follow the open [Agent Skills](https://agentskills.io/specification) format and work in Claude Code, Codex, Cursor, Copilot, OpenCode or any SKILL.md-compatible agent.

---

<a id="skills"></a>
## 🧩 Skills

<!-- catalogue:begin -->
| Skill | Purpose |
|---|---|
| [`accessible-design`](skills/accessible-design/SKILL.md) | Do not use for general visual styling (visual-design-system), legal compliance claims, or writing accessibility code for a framework. |
| [`adaptive-layout-and-spacing`](skills/adaptive-layout-and-spacing/SKILL.md) | Covers hierarchy, grouping, safe areas, edge-to-edge, size classes and reflow. |
| [`interaction-feedback-and-forms`](skills/interaction-feedback-and-forms/SKILL.md) | Do not use for navigation structure (navigation-and-flows), colour and type (visual-design-system) or a full accessibility audit (accessible-design). |
| [`mobile-ux-foundations`](skills/mobile-ux-foundations/SKILL.md) | Covers research first, one primary action, feature prioritisation, mobile constraints (interruptions, one hand, weak signal) and onboarding. |
| [`navigation-and-flows`](skills/navigation-and-flows/SKILL.md) | Do not use for form fields and messages (interaction-feedback-and-forms), screen spacing (adaptive-layout-and-spacing) or documenting site maps (ux-documentation-and-handoff). |
| [`ui-ux-designer`](skills/ui-ux-designer/SKILL.md) | Routes mobile-first design work (UX principles, layout, navigation, feedback and forms, visual design, accessibility, documentation, review) to focused skills and enforces shared guardrails. |
| [`ux-documentation-and-handoff`](skills/ux-documentation-and-handoff/SKILL.md) | Do not use for choosing the design itself (the design skills), for running usability tests (ux-review-and-testing) or for software documentation such as a README. |
| [`ux-review-and-testing`](skills/ux-review-and-testing/SKILL.md) | Do not use for designing a screen from scratch (the design skills), writing hand-off documents (ux-documentation-and-handoff) or a formal accessibility conformance claim (accessible-design). |
| [`visual-design-system`](skills/visual-design-system/SKILL.md) | Do not use for a full accessibility audit (accessible-design), screen layout (adaptive-layout-and-spacing) or brand strategy and illustration. |
<!-- catalogue:end -->

---

<a id="how-they-fit-together"></a>
## 🗺️ How they fit together

```mermaid
flowchart TD
    R["📱 ui-ux-designer<br/>routes and enforces mobile-first guardrails"]
    R --> F["🎯 mobile-ux-foundations<br/>research, priorities, constraints"]
    R --> L["📐 adaptive-layout-and-spacing<br/>hierarchy, safe areas, size classes"]
    R --> N["🧭 navigation-and-flows<br/>IA, tab bars, sheets, gestures"]
    R --> I["💬 interaction-feedback-and-forms<br/>feedback, forms, states, motion"]
    R --> V["🎨 visual-design-system<br/>type, colour, dark mode, tokens"]
    R --> A["♿ accessible-design<br/>targets, contrast, WCAG 2.2"]
    R --> D["📝 ux-documentation-and-handoff<br/>personas, specs, hand-off"]
    R --> T["✅ ux-review-and-testing<br/>heuristics, usability tests"]
```

A typical project runs foundations first, then layout and navigation, then interaction and visual design, with accessibility checked throughout, documentation written as decisions settle, and review before release.

---

<a id="install"></a>
## 📦 Install

> [!TIP]
> Install the router skill **plus every sibling skill it links to**; routers reference siblings by relative path.

**Claude Code plugin** (installs the skills and any agent profiles together):

```text
/plugin marketplace add KinwiseNZ-DevOps/ui-ux-designer
/plugin install ui-ux-designer@ui-ux-designer-marketplace
```

Or copy or symlink the `skills/` subfolders you want into your agent's skills directory:

| Agent | Where skills live |
|---|---|
| Claude Code | `~/.claude/skills/` or a project's `.claude/skills/` |
| Codex · Cursor · Copilot · OpenCode · Windsurf | the agent's own SKILL.md discovery path |

---

### Always on

In Claude Code, UI UX Designer loads a short ruleset into sessions in app and UI projects once the plugin is installed. It enforces mobile first, source-attributed target sizes and contrast, full state specs and gesture alternatives. It tells you its state at the start of each session and costs roughly 450 tokens.

| Mode | What it does |
|---|---|
| `on` | The rules apply in every session |
| `auto` (default) | The rules apply only in projects that look relevant: projects with a `pubspec.yaml`, React Native, Expo or Tailwind in `package.json`, `Package.swift` or an `AndroidManifest.xml` |
| `off` | The rules do not load |

- Say **"stop design mode"** to pause it for the current session, and **"start design mode"** to resume.
- Ask Claude to **set the saved mode to on, off or auto**. It writes that word into `~/.claude/.ui-ux-designer.mode`. You can also edit that file yourself, and deleting it returns to the default (`auto`).
- It needs Node on the machine, because the start-up hook runs a small Node script. Without Node the hook quietly does nothing.
- Other agents have no start-up hook here. Paste `skills/ui-ux-designer/references/always-on-rules.md` into that agent's instruction file instead.

### Safety checks

The same hooks run a few checks while you work. Each one only asks, warns or adds a reminder; none changes your files on its own.

| Check | What it does | On by default |
|---|---|---|
| `dangerGuard` | Asks before risky commands: force pushes, `git reset --hard`, `rm -r`, dropping data, `docker compose down -v`, publishing a package | Yes |
| `secretsGuard` | Asks before writing keys, tokens or `.env` files | Yes |
| `packageGuard` | Asks if a package about to be installed does not exist on PyPI, npm or pub.dev, because the name may be invented | Yes |
| `licenseGuard` | Warns after installing an npm or PyPI package with a GPL-family 
````