{
  "name": "A11yKit AI Rules Pack",
  "version": "1.0.0",
  "updated": "2026-11-19",
  "site": "https://doggonug-cpu.github.io/a11y-ui-kit/",
  "note": "Paste-ready instruction files for AI coding tools. One canonical set of rules, packaged for Cursor, Claude Code, Windsurf, GitHub Copilot and AGENTS.md-style agents.",
  "core": {
    "targetPx": 48,
    "contrastBody": "7:1 (AAA) — this kit ships 18.4:1",
    "focusRing": "4px solid #FFE066, 3px offset, :focus-visible only",
    "baseFont": "19px / 1.6, max ~72ch per line",
    "korean": "word-break: keep-all; never break a Korean word mid-word",
    "assets": "no audio files, no external requests, no framework, no bundler"
  },
  "packs": {
    "cursor": {
      "id": "cursor",
      "label": "Cursor",
      "target": ".cursor/rules/a11y-senior-ui.mdc",
      "apply": "alwaysApply",
      "body": "---\ndescription: Senior-first, WCAG-minded UI rules for this project (A11yKit)\nglobs: [\"**/*.html\", \"**/*.css\", \"**/*.js\", \"**/*.jsx\", \"**/*.tsx\", \"**/*.vue\"]\nalwaysApply: true\n---\n\n# Senior-first UI rules\n\nApply these rules to every UI change in this project. They come from A11yKit, a\ncomponent kit built for 70-year-old hands and low-vision eyes. Do not restyle the\nproject to match a trend; match these constraints.\n\n## 1. Targets and focus\n- Interactive elements are at least 48x48 CSS px; primary actions 56-64px tall.\n- 12px or more between adjacent targets. Never place two actions closer than 8px.\n- Grow the hit area with padding, not transform: scale().\n- Focus ring: 4px solid #FFE066, 3px offset, :focus-visible only, never clipped by\n  overflow:hidden. Keyboard order follows visual order.\n\n## 2. Text and contrast\n- Body text at least 7:1 contrast (WCAG AAA). Reference pair: #F3F6F9 on #06090F = 18.4:1.\n- Secondary text at least 4.5:1; aim for 7:1.\n- Base font 19px, line-height 1.6, no justified text, about 72ch per line maximum.\n- Korean: word-break: keep-all. Use overflow-wrap: anywhere only for URLs and codes.\n- Survive 200% browser zoom and a 320px viewport: no horizontal scroll, no clipped text.\n- Never signal state with colour alone: add an icon, a word, weight or underline.\n\n## 3. Semantics and announcements\n- Use real <button>, <a>, <input>, <select>, <dialog>. A div with a click handler is a bug.\n- Labels sit above the field and are tied with for/id. A placeholder is never the label.\n- Every status change writes into an existing role=\"status\" aria-live=\"polite\" element.\n  Errors (and only errors) use role=\"alert\".\n- Groups of choices use fieldset/legend or role=\"radiogroup\" with aria-checked and\n  roving tabindex (one tab stop, arrows move).\n- Dialogs use <dialog>.showModal(), trap nothing by hand, close on Escape, and return\n  focus to the trigger.\n- Expose state with aria-pressed / aria-checked / aria-current / aria-expanded, not with\n  a CSS class alone.\n\n## 4. Sound and motion (optional, never required)\n- If sound is added, synthesize it with Web Audio inside the user's gesture. No audio\n  files, at most one tone per 80ms, and a mute switch whose choice persists.\n- Every sound cue is mirrored by visible text and a live-region announcement.\n- Respect prefers-reduced-motion: no transforms, autoplay, parallax or marquee.\n- Reserve space (min-height) so a status message never shifts the layout.\n\n## 5. Code shape\n- Ship plain HTML, CSS and one vanilla JS block per component unless the project already\n  has a framework. No CDN, no tracking script, no telemetry, no external requests.\n- Colours and spacing come from CSS custom properties; no repeated magic numbers.\n- Prefer native elements over ARIA. ARIA only fills gaps native HTML cannot.\n\n## 6. Before you say it is done\n- Tab through the whole flow: every control reachable and operable with the keyboard only.\n- Screen-reader pass: name, role, state and live announcements all present.\n- 200% zoom and 320px width: no horizontal scroll, nothing clipped.\n- Measure contrast for each text/background pair you introduced.\n- Zero console errors and zero failed network requests.\n- Name the A11yKit component ids you reused (list_components, get_component via MCP).\n\nFull component index: https://doggonug-cpu.github.io/a11y-ui-kit/llms.txt\n"
    },
    "claude-code": {
      "id": "claude-code",
      "label": "Claude Code",
      "target": "CLAUDE.md",
      "apply": "project memory",
      "body": "# CLAUDE.md - senior-first UI rules (A11yKit)\n\nThis project targets older and low-vision users. Follow these rules for every UI\nchange; they override stylistic defaults and library conventions.\n\n## Targets and focus\n- Interactive elements >= 48x48 CSS px, primary actions 56-64px tall, >= 12px gaps.\n- Focus: 4px solid #FFE066 ring, 3px offset, :focus-visible only, never clipped.\n- Keyboard order = visual order. No keyboard traps, no focus loss on close.\n\n## Text and contrast\n- Body text >= 7:1 contrast (AAA); reference #F3F6F9 on #06090F = 18.4:1.\n- Secondary text >= 4.5:1. Base font 19px, line-height 1.6, <= ~72ch per line.\n- Korean: word-break: keep-all. Survive 200% zoom and 320px width with no horizontal scroll.\n- State is never colour-only: pair colour with icon, word, weight or underline.\n\n## Semantics\n- Real button/a/input/dialog; visible label above each field tied with for/id.\n- role=\"status\" aria-live=\"polite\" for status, role=\"alert\" only for errors.\n- Radio groups: fieldset/legend or role=\"radiogroup\" + aria-checked + roving tabindex.\n- <dialog>.showModal() for modals; Escape closes; focus returns to trigger.\n- aria-pressed / aria-checked / aria-current / aria-expanded expose state.\n\n## Sound and motion\n- Optional Web Audio tones only (no files, <= 1 per 80ms) with a persistent mute switch,\n  always mirrored in visible text and the live region.\n- Honour prefers-reduced-motion. Reserve space so messages never shift layout.\n\n## Code\n- Plain HTML + CSS + one vanilla JS block unless the project already uses a framework.\n- No CDN, no telemetry, no external requests. CSS custom properties for colour/spacing.\n\n## Done means\n- Full keyboard walkthrough, screen-reader pass, 200% zoom and 320px check, contrast\n  measured, zero console errors, zero failed requests.\n- List the A11yKit component ids reused. If you need the exact source, ask for it with\n  the a11y-kit MCP tools (list_components, get_component, get_ai_prompt,\n  check_wcag_checklist) instead of inventing markup.\n\nComponent index: https://doggonug-cpu.github.io/a11y-ui-kit/llms.txt\n"
    },
    "windsurf": {
      "id": "windsurf",
      "label": "Windsurf",
      "target": ".windsurfrules",
      "apply": "workspace rules",
      "body": "# .windsurfrules - senior-first UI (A11yKit)\n\nScope: every HTML, CSS and JS file in this workspace. These rules win over style\npreferences and library defaults.\n\n- Targets: interactive elements >= 48x48 CSS px (56-64px for primary actions), >= 12px\n  between neighbours. Padding grows the hit area, never transform: scale().\n- Focus: 4px #FFE066 ring with 3px offset, :focus-visible only, never clipped.\n- Contrast: body text >= 7:1 (AAA), secondary >= 4.5:1. Base 19px / 1.6, <= ~72ch.\n- Korean text: word-break: keep-all; no mid-word breaks.\n- Layout: correct at 200% zoom and 320px width, no horizontal scroll, no clipped text.\n- State is never colour-only: icon, word, weight or underline always accompany colour.\n- Native semantics first: button, a, input, select, dialog; labels above fields, tied by\n  for/id. Placeholders are never labels.\n- Live regions: role=\"status\" aria-live=\"polite\" for status, role=\"alert\" for errors.\n- Radio groups: fieldset/legend or role=\"radiogroup\" with aria-checked and roving tabindex.\n- Modals: <dialog>.showModal(), Escape closes, focus returns to the trigger.\n- State via aria-pressed / aria-checked / aria-current / aria-expanded, not classes alone.\n- Sound only as optional Web Audio tones synthesised in the gesture (no files, <= 1 per\n  80ms), with a persistent mute switch and the same message in visible text.\n- Honour prefers-reduced-motion; reserve min-height so messages do not shift layout.\n- Ship plain HTML + CSS + one vanilla JS block; no CDN, no tracking, no external requests.\n- Finish with: keyboard-only walkthrough, screen-reader pass, 200% zoom and 320px check,\n  measured contrast, zero console errors, and a list of A11yKit component ids reused.\n\nComponent index and copy-ready source: https://doggonug-cpu.github.io/a11y-ui-kit/llms.txt\n"
    },
    "copilot": {
      "id": "copilot",
      "label": "GitHub Copilot",
      "target": ".github/copilot-instructions.md",
      "apply": "repository instructions",
      "body": "# Copilot instructions - senior-first UI (A11yKit)\n\nThis repository builds interfaces for older and low-vision users. Apply these rules to\nevery suggestion you make for HTML, CSS, JS and component code.\n\n## Non-negotiables\n1. Touch and click targets >= 48x48 CSS px; primary actions 56-64px; >= 12px gaps.\n2. Focus ring 4px #FFE066, 3px offset, :focus-visible only, never clipped.\n3. Body text contrast >= 7:1 (AAA). Reference: #F3F6F9 on #06090F = 18.4:1.\n4. Base font 19px, line-height 1.6, line length <= ~72ch, no justified text.\n5. Korean: word-break: keep-all.\n6. State never conveyed by colour alone - add icon, word, weight or underline.\n7. Real semantic elements; visible label above every field, tied with for/id.\n8. role=\"status\" aria-live=\"polite\" for status changes; role=\"alert\" only for errors.\n9. Dialogs are <dialog>.showModal(); Escape closes; focus returns to the trigger.\n10. Works at 200% zoom and 320px width with no horizontal scroll.\n\n## Avoid\n- div or span as a button, placeholder-only labels, hidden focus outlines.\n- Colour-only success/error/selected states, animated transitions that ignore\n  prefers-reduced-motion, layout shifts when a message appears.\n- Audio files, CDN scripts, trackers, external font or icon requests.\n- Inventing component markup: reuse the A11yKit ids instead.\n\n## Done means\nKeyboard-only walkthrough, screen-reader pass, 200% zoom and 320px check, contrast\nmeasured, zero console errors, and the list of A11yKit component ids reused.\n\nComponent index: https://doggonug-cpu.github.io/a11y-ui-kit/llms.txt\n"
    },
    "agents": {
      "id": "agents",
      "label": "AGENTS.md",
      "target": "AGENTS.md",
      "apply": "agent-agnostic (Codex, Gemini CLI, Cline, Zed)",
      "body": "# AGENTS.md - senior-first UI rules (A11yKit)\n\nApplies to any coding agent working in this repository: Codex, Gemini CLI, Cline, Zed,\nDevin, or a custom runner. Read this before editing UI files.\n\n## Constraints\n- Targets >= 48x48 CSS px (56-64px primary), >= 12px apart, no scale() hit areas.\n- Focus ring 4px #FFE066 with 3px offset on :focus-visible, never clipped.\n- Body text >= 7:1 contrast; secondary >= 4.5:1; 19px base, 1.6 line-height, <= ~72ch.\n- Korean: word-break: keep-all. No mid-word breaks, no justified text.\n- 200% zoom and 320px width must stay usable without horizontal scrolling.\n- Colour is never the only state signal.\n- Semantic HTML first; labels above fields tied with for/id; no placeholder-only labels.\n- Status via role=\"status\" aria-live=\"polite\"; errors via role=\"alert\".\n- Choice groups: fieldset/legend or role=\"radiogroup\" + aria-checked + roving tabindex.\n- Modals: <dialog>.showModal(), Escape closes, focus returns to the trigger.\n- Optional sound: Web Audio tones only, mute switch persisted, mirrored in text.\n- prefers-reduced-motion respected; no layout shift when messages appear.\n- Plain HTML + CSS + one vanilla JS block; no CDN, no tracker, no external request.\n\n## Verify before finishing\n1. Keyboard-only walkthrough of the whole flow.\n2. Screen reader: names, roles, states, announcements.\n3. 200% zoom, 320px width: no horizontal scroll.\n4. Contrast measured per text/background pair.\n5. Zero console errors, zero failed requests.\n6. Report the A11yKit component ids reused.\n\nIf you need exact source or a WCAG checklist, use the a11y-kit MCP server:\nlist_components, get_component, get_ai_prompt, check_wcag_checklist.\nIndex: https://doggonug-cpu.github.io/a11y-ui-kit/llms.txt\n"
    }
  },
  "order": ["cursor", "claude-code", "windsurf", "copilot", "agents"]
}
