# ss-a11y

Adopt this skill: https://proskills.md/skills/other/bitjaru-styleseed-skills-ss-a11y

Page: https://proskills.md/skills/other/bitjaru-styleseed-skills-ss-a11y
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/ss-a11y/SKILL.md
size: 3731
upstream: https://github.com/bitjaru/styleseed/blob/main/skills/ss-a11y/SKILL.md

````text
---
name: ss-a11y
description: Audit a component or page for accessibility issues and fix them
argument-hint: "[file-path]"
allowed-tools: Read, Write, Edit, Grep, Glob
---

Before this workflow, follow the once-per-session [update preflight](../ss-update/references/update-preflight.md).

# Accessibility Audit
## Registry-first artifact boundary

When `.styleseed/project.json` and `.styleseed/artifacts/index.json` exist, resolve the requested artifact ID first, then read only `.styleseed/bundles/<artifact-id>.md` and `.styleseed/manifests/<artifact-id>.json`. Never fall back to the global legacy bundle for a registry project. Legacy projects may use `.styleseed/effective-rules.md` only when no registry exists.

## When NOT to use

- For general design system compliance review → use `/ss-review`
- For Nielsen UX heuristics → use `/ss-audit`
- For non-StyleSeed code (no `data-slot`, no semantic tokens) — assumes StyleSeed conventions
- For runtime testing — this is a static code audit, not a screen-reader simulation

Target: **$ARGUMENTS**

## Audit Criteria

### WCAG 2.2 AA Compliance

#### 1. Perceivable
- **Color contrast**: Text must meet 4.5:1 (normal) or 3:1 (large/bold text)
  - Check `text-muted-foreground` (#717182) on `bg-background` (#FFFFFF) = 4.6:1 (passes)
  - Check `text-brand` on white (verify contrast with your skin's brand color)
  - Flag any custom colors that don't meet ratio
- **Non-text contrast**: UI controls/graphics must meet 3:1
- **Text alternatives**: All `<img>` need `alt`, icons need `aria-label` when meaningful
- **Color independence**: Don't convey info by color alone (add icons/text)

#### 2. Operable
- **Touch targets**: Minimum 44x44px (`min-h-11 min-w-11`) on touch surfaces
  - Flag undersized touch hit areas, not approved pointer-first desktop controls merely for being 36–40px tall
  - Pointer-first controls follow the resolved contract; preserve keyboard access and applicable accessibility floors
  - Icon buttons need an explicit hit area appropriate to the input mode
- **Keyboard navigation**: All interactive elements must be keyboard-accessible
  - Tab order should be logical
  - `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`
- **Motion**: Animations must respect `prefers-reduced-motion`
  ```css
  @media (prefers-reduced-motion: reduce) {
    *, *::before, *::after {
      animation-duration: 0.01ms !important;
      transition-duration: 0.01ms !important;
    }
  }
  ```

#### 3. Understandable
- **Labels**: Form inputs must have visible labels or `aria-label`
- **Error messages**: Form errors must be programmatically associated (`aria-describedby`)
- **Language**: `<html lang="en">` (or appropriate language code for your project)

#### 4. Robust
- **Semantic HTML**: Use appropriate elements (`<button>`, `<nav>`, `<main>`, `<header>`)
- **ARIA**: Use Radix UI components (they handle ARIA automatically)
- **Roles**: Custom interactive elements need proper `role` attributes

## Design System Token Reference

| Token | Minimum Contrast | Note |
|-------|-----------------|------|
| `--foreground` | 7:1+ | Body text — verify with your skin |
| `--muted-foreground` | 4.5:1+ | Secondary text — verify with your skin |
| `--brand` | 4.5:1+ | Accent — verify with your skin's brand color |
| `--destructive` | 4.5:1+ | Error — verify with your skin |
| `--success` | 3:1+ | Large text/icons only — verify with your skin |
| `--warning` | 4.5:1+ | Warning text — some skins need a darker variant |

## Output

1. **Issues found**: List with severity (Critical/Major/Minor)
2. **Auto-fixes**: Apply fixes directly where possible
3. **Manual review needed**: Flag items that need human judgment
````

## File: README.md
upstream: https://github.com/bitjaru/styleseed/blob/main/README.md

````text
<div align="center">

<br />

# StyleSeed

### Make AI coding agents keep your design system<br />across screens, sessions, and teammates.

<sub>You choose the design decisions. StyleSeed compiles them into the rules an agent reads before each screen, then checks the rendered result. <b>Support experts, not replace them with a collection of tastes.</b> Open source, for Claude Code · Codex · Cursor.</sub>

<br />
<br />

<a href="https://styleseed-demo.vercel.app/showcase">
  <img src="showcase/v26-compare.png" width="720" alt="Same product, same prompt — left: default AI output, right: with StyleSeed rules locked" />
</a>

**Same product. Same prompt. Only the rules changed.**

</div>

**Measured on 120 rendered benchmark cells:** the enforced gate improved both Codex and Claude Code by **+5.3 points**. Raw rules alone were inconsistent (Codex +1.6, Claude Code −3.7), which is why StyleSeed ships a render → score → revise loop—not a prompt dump. **[Read BENCH-V1 and inspect the raw evidence →](https://styleseed-demo.vercel.app/gate)**

## Easy Start (30 seconds)

Our goal is repeatable application of expert judgment, not a claim of expert-level output today.
The engine compiles selected rules, preserves project choices, and supports code and rendered
checks. A score does not replace human design acceptance.
[Product principles](engine/PRODUCT-PRINCIPLES.md) · [Quality-first roadmap](ROADMAP.md)

**1. Open a terminal in your project folder and run this command.** Requires Node.js/npm.

> **Already installed?** [Update and consolidate your existing skill list](https://styleseed-demo.vercel.app/upgrade). One request covers the same install scope, verified backup, and revision checks.

```bash
npx -y skills add bitjaru/styleseed -a codex claude-code -y --copy
```

Installs the core skills for **Codex and Claude Code together, with no agent, skill, or install-mode menus**.
It copies the skills into this project. It does not install globally or change other projects.

**2. Send one message to your agent.** Start a fresh session if the skills do not appear.

- **Codex:** `$styleseed Help improve this screen. Preserve our existing design choices and show me what needs a decision.`
- **Claude Code:** `/styleseed Help improve this screen. Preserve our existing design choices and show me what needs a decision.`

Only `styleseed` is registered. It selects the needed internal workflow from your request.
Choose unresolved design decisions together, then inspect the actual rendered result.

<details>
<summary>Only use one agent, or want to choose the options yourself?</summary>

- Codex only: `npx -y skills add bitjaru/styleseed -a codex -y --copy`
- Claude Code only: `npx -y skills add bitjaru/styleseed -a claude-code -y --copy`
- Cursor or another agent: `npx skills add bitjaru/styleseed` → your agent → Project → Copy.
- In the interactive list, **Codex is already included under Universal**. Do not look for it again under Additional agents.
- `-y` skips installer questions; it does not bypass your coding agent's tool permissions.

</details>

[Claude Code guide](https://styleseed-demo.vercel.app/claude-code-ui-design) · [Codex guide](https://styleseed-demo.vercel.app/codex-ui-design) · [See examples](https://styleseed-demo.vercel.app/showcase) · [Need help?](#troubleshooting--i-applied-styleseed-but-the-ui-still-looks-bad)

### Evaluating the repository?

Use the **[three-minute verification path](https://styleseed-demo.vercel.app/evaluate)** to test a
clean public install before trusting the README. The source-level
[evaluator quickstart](docs/EVALUATOR-QUICKSTART.md) then connects that install to the published
release manifest, Windows PowerShell evidence, CI, SBOM, benchmark boundary, and production build.

> **Want a first PR?** Fix a doc, add a regression fixture, improve a skin, or claim a
> [`good first issue`](https://github.com/bitjaru/styleseed/issues?q=is%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22).
> Small docs and test fixes need no proposal. See the [15-minute contribution path](CONTRIBUTING.md#first-pr-in-about-15-minutes).

For a fixed evaluation version, use the **[v5.0.0 release archive](https://github.com/bitjaru/styleseed/releases/tag/v5.0.0)** and its checksums. The default `bitjaru/styleseed` command follows mutable `main`.

### Upgrading an existing 23-skill install

Reinstall through the same channel. Then ask `StyleSeed, consolidate my old skill entries`.
The update workflow verifies the new unified payload and archives only unmodified old `ss-*`
directories outside skill discovery; modified copies remain for review. Restart the agent session.
Use `$styleseed build` / `/styleseed build` instead of the former `$ss-build` / `/ss-build`
registrations. All 22 workflows remain bundled; selecting only `styleseed` is now sufficient.

## What the current rules check

StyleSeed ships **74 craft rules** and a **0–100 scored gate** that tells an installed agent to
revise screens below 80 before presentation. Checks must be interpreted through the selected
grammar and project contract, not as universal taste. The workflow must actually be invoked;
a markdown file alone cannot block delivery, and 80 points is not expert approval.

| Check | Why |
|---|---|
| Unselected default accent | require an intentional, recorded color role |
| Emoji as UI icons 🚗 🧺 ⭐ | inject random colors, render differently per OS |
| The icon-in-a-chip above every feature card | gen-1 AI tell — decoration pretending to be information |
| Same-weight cards that hide the current priority | the #1 machine-composed tell; truly equivalent options may share weight |
| Accidental flat-black backgrounds | use the selected grammar's surface model; explicit supported exceptions differ |
| Type sizes outside the selected scale | prevent unintentional hierarchy drift |
| Hardcoded hex in components | tokens only — otherwise the lock can't hold across screens |

<sub>Banning the defaults isn't enough — agents converge on new uniforms once the old ones are blocked. That's why the rules come with an enforced score-then-fix loop, not a checklist. [What happens after install ↓](#what-happens-after-easy-start)</sub>

<div align="center">

<br />

<a href="https://styleseed-demo.vercel.app">
  <img src="showcase/demo.gif" width="560" alt="Same chat UI morphing across Toss, Raycast, and Arc brand skins" />
</a>

**One component. Three token skins.** Same chat UI morphing across Toss · Raycast · Arc-inspired
token sets. A skin changes color and type material; a StyleSeed brand recipe changes the actual
geometry, containment, controls, collections, density, and motion.

<sub>Skins are *inspired-by* token sets, not recreations. [Compare the nine structural recipes →](https://styleseed-demo.vercel.app/recipes)</sub>

<br />

[![▶ Live Demo](https://img.shields.io/badge/▶_Live_Demo-Open-111111?style=for-the-badge&logoColor=white)](https://styleseed-demo.vercel.app)
&nbsp;
[![▶ Motion Gallery](https://img.shields.io/badge/▶_Motion_Gallery-Live-8B5CF6?style=for-the-badge&logoColor=white)](https://styleseed-demo.vercel.app/motion)

![74 design rules](https://badgen.net/badge/rules/74/8B5CF6)
![1 skill](https://badgen.net/badge/skills/1/6C5CE7)
![8 output grammars](https://badgen.net/badge/grammars/8/2563EB)
![5 adapters](https://badgen.net/badge/adapters/5/0F766E)
![9 brand recipes](https://badgen.net/badge/recipes/9/DB2777)
![8 palette recipes](https://badgen.net/badge/palettes/8/D56A45)
![7 brand skins](https://badgen.net/badge/skins/7/6C5CE7)
[![GitHub stars](https://badgen.net/github/stars/bitjaru/styleseed)](https://github.com/bitjaru/styleseed/stargazers)
[![License](https://badgen.net/github/license/bitjaru/styleseed)](https://github.com/bitjaru/styleseed/blob/main/LICENSE)
[![Mentioned in Awesome AI Tools for UI](https://awesome.re/mentioned-badge.svg)](https://github.com/maxbogo/awesome-ai-tools-for-ui)

<br />

**Expert decisions become repeatable instructions — not one univer
````
