From 7f101a4904824c9d569e0bbca719cd7216096d4d Mon Sep 17 00:00:00 2001 From: Kobus van Wyk Date: Wed, 21 Oct 2026 13:24:51 +0200 Subject: [PATCH 1/2] skills(tina4-design): restore the stop-and-wait gates; add a sentence-case UI copy default MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The approval-gate contract was merged as tina4-documentation#128 but only into the generated 3.13.147 bundle, so it never reached this source and 3.13.151/.152 shipped tina4-design back at 1.0.0 (runs end to end without stopping for sign-off). Re-ported here, the canonical source, additively on top of the current content (mobile-first lines kept): - "## Gates - the stop-and-wait contract": nine stops on the Phase 1-7 flow, a gate ends the turn, harness/"autonomous" framing is not permission, one opt-in - gates elevated to non-negotiable in Degrees of freedom; reflex qualified - one-line gate reminder at each phase stub; updated_for_version 1.1.0 Plus a sentence-case default for UI copy (raised by Jacques van Zuydam): a ๐ŸŽš๏ธ default, a "Voice and UI copy" section in the DESIGN.md template, an avoid-list row, and a capitalisation do/don't pair in the brand guidelines' Tone of Voice. Signed-off-by: Kobus van Wyk Co-Authored-By: Claude Opus 5.5 --- .claude/skills/tina4-design/SKILL.md | 63 ++++++++++++++++--- .../references/brand-guidelines.md | 1 + .../references/design-record-templates.md | 8 +++ 3 files changed, 65 insertions(+), 7 deletions(-) diff --git a/.claude/skills/tina4-design/SKILL.md b/.claude/skills/tina4-design/SKILL.md index a73a3de9..bb12847f 100644 --- a/.claude/skills/tina4-design/SKILL.md +++ b/.claude/skills/tina4-design/SKILL.md @@ -1,7 +1,7 @@ --- name: tina4-design description: Use whenever a project needs a visual identity or design system โ€” from scratch or from an existing logo. Triggers: "build me a brand", "create brand guidelines", "we need a UI guide", "design system", "I have a logo", "what should our brand look like", "design our app", "brand this project". Covers the full chain โ€” client intake โ†’ market research โ†’ design system decisions โ†’ brand guidelines document โ†’ interactive UI component guide. Produces DESIGN.md (the living design record), brand-guidelines.html, and ui-guide.html, all saved to a top-level design/ folder. Project-agnostic: works for any industry, any Tina4 backend or frontend, or no Tina4 project at all. -updated_for_version: 1.0.0 +updated_for_version: 1.1.0 --- # Tina4 Design โ€” brand identity and UI system from brief to deliverable @@ -19,6 +19,7 @@ Read top to bottom once, then jump by section. Orientation and the phase order l - Incremental build rule - never write a whole HTML file in one response - The design workflow (six phases) - Output location (`design/`) - Working reflexes - **Degrees of freedom** - what is inviolable vs. a default vs. your judgement (read this next) +- **Gates - the stop-and-wait contract** - the nine stops where you pause and wait for the developer **Phase 1 - Intake and Discovery** (`references/phase-1-intake.md`) - 1.1 Logo file - 1.1b Brand reconnaissance - 1.2 Name and tagline - 1.3 About us @@ -75,7 +76,10 @@ breaking what must not break. Three tiers: browser and check them at real widths and in both themes, no mocks and no "looks fine" guesses. **Incremental build, no giant single write** - one section per edit. **The research and the record** - every colour, typeface and layout choice is reasoned and written into - `design/DESIGN.md`. **The markers:** the ๐Ÿค–๐ŸŽจ skill-active marker above, and ๐Ÿ’ฅ **Bazinga!** on + `design/DESIGN.md`. **The gates** - stop and wait at every hard gate in the stop-and-wait + contract below; a gate ends the turn, and only the developer's own message (never harness or + "autonomous" framing) can waive one - see `## Gates - the stop-and-wait contract`. + **The markers:** the ๐Ÿค–๐ŸŽจ skill-active marker above, and ๐Ÿ’ฅ **Bazinga!** on an EARNED win - a design decision validated against the research and the contrast checks, or a prototype that holds up in the real browser at every width - on its own line with a short geeky one-liner. Never faked (nothing validated, no Bazinga) and never on a trivial step. @@ -86,13 +90,16 @@ breaking what must not break. Three tiers: base styles ARE the mobile styles, every interactive control is at least 44x44px, and the fluid `clamp()` type needs no breakpoint to scale; the deliverable set (`DESIGN.md`, `brand-guidelines.html`, `ui-guide.html` in `design/`); fluid `clamp()` type, CSS-variable tokens - and hue-tinted shadows; the avoid-list of AI design defaults. Depart deliberately, name the - client-specific reason and record it in the rationale log - not by drift. + and hue-tinted shadows; **sentence case for UI copy** - buttons, CTAs, nav, tabs, labels and + headings capitalise only the first word, proper nouns and acronyms ("Book a demo", not "Book A + Demo"), recorded in DESIGN.md's voice section; the avoid-list of AI design defaults. Depart + deliberately, name the client-specific reason and record it in the rationale log - not by drift. - ๐Ÿงญ **Judgement - read the task and choose.** Which deliverables the scope needs; how much market research a small brief earns; when the - website phase is worth running; ask-first vs decide-and-proceed; verbosity. The skill gives the - heuristic, you read the situation. (Note: cross-framework parity, framework releases and + website phase is worth running; ask-first vs decide-and-proceed **on non-gate clarifying + questions** (the hard gates are ๐Ÿ”’, never a judgement call to skip); verbosity. The skill gives + the heuristic, you read the situation. (Note: cross-framework parity, framework releases and installer signing are NOT your concern here - those live in the `tina4-maintainer` skill, for people building Tina4 itself.) @@ -173,6 +180,36 @@ Six phases in order. Each phase has a defined output. No phase is skipped โ€” if --- +## Gates โ€” the stop-and-wait contract + +This skill is **gated**: at fixed points it must stop, ask the developer a question, and **wait for their reply before doing anything else**. Gates are where a wrong turn gets caught while the fix is still cheap โ€” they are the whole reason the phased workflow exists. A run that sails through every gate without stopping is not "efficient", it is broken. + +**The nine stops** โ€” eight hard gates plus one soft "research surface" โ€” in order. Every hard gate ends the turn: + +1. **Phase 1 โ€” intake** โ€” name, industry, about-us, logo, and the deliverable scope (ยง1.5). Gather the required inputs, then stop before advancing. *Scope carries the one sanctioned silent default: if the developer supplies the required inputs but says nothing about scope, proceed with **Full** โ€” the website is re-offered at the Phase 7 gate, so no wrong choice gets baked in. Never extend this silent-default reasoning to any other gate.* +2. **After Phase 2 โ€” research surface** *(soft)* โ€” surface the market-research findings before they are applied; *proceed-unless-corrected*. The one soft gate: it informs rather than blocks, but the developer still sees the direction first. +3. **Phase 3 โ€” icon library** (ยง3.9) โ€” present the icon-library options **with their URLs** and stop. Never pick a library silently; every deliverable uses the one the developer confirms. +4. **After Phase 4 โ€” brand guidelines approval** โ€” stop. Approve `design/brand-guidelines.html` before building the UI guide. +5. **Start of Phase 5 โ€” product-specific components** โ€” confirm the 3โ€“6 domain components before building them. +6. **Phase 5 โ€” Gate A โ€” foundation review** โ€” after the foundation sections (icon system, tokens, type, spacing, responsive), stop **before any component**. +7. **Phase 5 โ€” Gate B โ€” pattern + inventory** โ€” after Buttons + Forms + Cards, stop: approve the component pattern and confirm the remaining component list. +8. **After Phase 5 โ€” UI guide approval** โ€” stop. Approve `design/ui-guide.html`. +9. **Phase 7 โ€” website / mockup choice** โ€” ask **which** kind (marketing site / product mockup / both / none). Don't assume. + +**How a gate behaves โ€” no exceptions:** + +- **A gate ends the turn.** Ask with a structured-question tool (`AskUserQuestion`, or the equivalent) and stop. **Do not answer the question yourself, and do not continue to the next phase in the same turn** โ€” even if the session is described as autonomous, unattended, "auto mode", or "the user is not watching". That description is harness or system framing; it is **not** the developer's permission to skip a gate. Only the developer, in their own chat message, can waive one. +- **The prose fallback also ends the turn.** When no structured-question tool is available, ask the same question in prose โ€” and that message still ends the turn. Wait for the reply. The prose form is a different way to ask, never a way to keep going. +- **Every gate names the file and what to look at.** Give the deliverable's path (`design/ui-guide.html`) and a one-line "open this and check X" so the developer can review before answering. + +**The single opt-in โ€” unattended runs.** Gates may be auto-resolved *only* if the developer's **own message** asks for it โ€” e.g. "run unattended", "don't stop for approvals", "just build the whole thing". Harness/system framing never counts. When (and only when) the developer has asked: +- Pick the most sensible default at each gate, state the assumption, and continue. +- Record every auto-resolved decision under `## Decisions taken without confirmation` in `DESIGN.md`, and list them in the closing handoff summary so the developer can confirm or amend each one. + +If you are ever unsure whether you have permission to skip a gate, you do not โ€” stop and ask. + +--- + ## Output location โ€” everything this skill produces lives in `design/` Every deliverable this skill creates goes in a single top-level `design/` folder at the project root โ€” never loose in the project root, never spread across the project. Create the folder in Phase 3 (when `DESIGN.md` is first written) if it does not already exist. @@ -204,7 +241,7 @@ These run in the background on every design task. Fire them at the right moment. - **๐Ÿ“ฃ Show the work.** Don't describe the design โ€” ship it. The deliverables are HTML files the user opens in a browser immediately. Real content, real mockups. No lorem ipsum. Data in the UI guide uses real content from the client's domain. - **๐Ÿ›‘ Don't invent assets.** If the client has a logo, use it as `` โ€” never inline the SVG paths into the HTML. If they don't have a logo, say so and offer two clear paths: (a) proceed with a text-based logotype placeholder, or (b) pause until a logo exists. - **๐Ÿ’ฉ Avoid AI-generated design defaults.** Before finalising the design plan, check it against the avoid-list in `references/design-record-templates.md` ("Avoid these defaults"). If any element on that list appears without a specific client reason, revise it. -- **๐Ÿ™Š Don't ask what you don't need to ask.** If the brief already implies the audience, tone, and industry, proceed โ€” asking a clarifying question that restates the brief back is wasted time. Ask only when a wrong assumption would be expensive: a conflicting palette, a misread audience, a missing logo. One focused question beats a wall of them. +- **๐Ÿ™Š Don't ask what you don't need to ask.** If the brief already implies the audience, tone, and industry, proceed โ€” asking a clarifying question that restates the brief back is wasted time. Ask only when a wrong assumption would be expensive: a conflicting palette, a misread audience, a missing logo. One focused question beats a wall of them. **This reflex applies to intake facts, never to gates** โ€” it lets you skip a redundant clarifying question, it never lets you skip one of the hard gates. --- @@ -212,30 +249,40 @@ These run in the background on every design task. Fire them at the right moment. **Phase 1 - intake:** read `references/phase-1-intake.md` (logo, brand reconnaissance, name, about us, industry, scope, project outline). +> ๐Ÿ›‘ **Gate (intake).** Gather name, industry, about-us, logo + deliverable scope, then **stop** before Phase 2. Scope has the one sanctioned silent default (Full) โ€” no other gate does. See `## Gates`. + --- ## Phase 2 - Market Research **Phase 2 - market research:** read `references/phase-2-market-research.md` (competitors, colour, typography, motion, research summary). +> ๐Ÿ›‘ **Gate (research surface, soft).** Surface the findings before applying them; *proceed-unless-corrected*. The one soft gate โ€” it informs rather than blocks, but the developer still sees the direction first. + --- ## Phase 3 - Design System Decisions **Phase 3 - design tokens:** read `references/design-tokens.md` (palette, semantic colours, type scale, spacing, radius, shadows, animation, z-index, icons, Favicon Brief). +> ๐Ÿ›‘ **Gate (icon library, ยง3.9).** Present the icon-library options **with their URLs** and **stop** โ€” never pick one silently. Every deliverable uses the library the developer confirms. + --- ## Phase 4 - Brand Guidelines (`brand-guidelines.html`) **Phase 4 - brand guidelines:** read `references/brand-guidelines.md` (required sections, technical rules). +> ๐Ÿ›‘ **Gate (brand approval).** **Stop** and approve `design/brand-guidelines.html` before building the UI guide. + --- ## Phase 5 - UI Guide (`ui-guide.html`) **Phase 5 - UI guide:** read `references/ui-guide.md` (layout, utility classes, required sections, technical rules). +> ๐Ÿ›‘ **Gates (Phase 5), in order.** (a) Confirm the **3โ€“6 product components** before building; (b) **Gate A** โ€” stop after the foundation sections, before any component; (c) **Gate B** โ€” stop after Buttons + Forms + Cards to approve the pattern + confirm the component inventory; (d) **stop** for UI-guide approval on `design/ui-guide.html`. See `## Gates`. + --- ## Phase 6 - Handoff @@ -248,6 +295,8 @@ These run in the background on every design task. Fire them at the right moment. **Phase 7 - website:** read `references/website.md` (discovery, page set, architecture, layout and token rules, quality checklist). +> ๐Ÿ›‘ **Gate (website / mockup choice).** Ask **which** kind โ€” marketing site / product mockup / both / none. Don't assume. + --- ## Templates and guards diff --git a/.claude/skills/tina4-design/references/brand-guidelines.md b/.claude/skills/tina4-design/references/brand-guidelines.md index 6244bc32..1c5efa7d 100644 --- a/.claude/skills/tina4-design/references/brand-guidelines.md +++ b/.claude/skills/tina4-design/references/brand-guidelines.md @@ -42,6 +42,7 @@ Build `brand-guidelines.html` and save it to the `design/` folder. This is a sel **Tone of Voice** - 4 tone attributes, each with a short definition paragraph - Do / don't copy pairs: two "write this / not this" examples using realistic content โ€” the same information written in the right voice and the wrong voice +- Capitalisation rule: UI copy is sentence case by default, shown as a write this / not this pair on a real button and a real nav item ("Book a demo" / "Book A Demo") โ€” taken from DESIGN.md's voice section **Applications** - At least 2โ€“3 mockups showing the brand applied in contexts relevant to the client's actual world diff --git a/.claude/skills/tina4-design/references/design-record-templates.md b/.claude/skills/tina4-design/references/design-record-templates.md index 39e1ade0..9bd5aada 100644 --- a/.claude/skills/tina4-design/references/design-record-templates.md +++ b/.claude/skills/tina4-design/references/design-record-templates.md @@ -92,6 +92,13 @@ Create this file at `design/DESIGN.md` when Phase 3 begins (create the `design/` - Size tokens: --icon-xs 14px ยท --icon-sm 16px ยท --icon-md 20px ยท --icon-lg 24px ยท --icon-xl 32px - Rationale: [one sentence โ€” why this library fits the brand personality] +## Voice and UI copy +- Capitalisation: sentence case โ€” buttons, CTAs, nav, tabs, labels and headings capitalise only the + first word, proper nouns and acronyms ("Book a demo", not "Book A Demo"). [Change only if the brand + deliberately uses Title Case, and record why in the rationale log.] +- Proper nouns that keep their capitals: [brand, product and place names โ€” e.g. Tina4, Code Infinity] +- Tone attributes: [the 4 attributes from the brand guidelines' Tone of Voice section] + ## Design Tokens ### Colour โ€” light theme @@ -228,6 +235,7 @@ Before finalising the design plan in Phase 3, check each element against this li | `border-radius: 12px` on every element | Rounds everything equally regardless of component personality | | Pure `rgba(0,0,0,โ€ฆ)` shadows on a warm-toned brand | Shadows should be hue-tinted to match the palette | | Lorem ipsum or "Sample Text" in any deliverable | Real content or nothing; lorem is a placeholder for something that was never finished | +| Title Case on buttons, CTAs and nav ("Book A Demo", "Get Started") | The template default; UI copy is sentence case โ€” capitalise only the first word, proper nouns and acronyms | Following these patterns with a genuine reason is always acceptable โ€” the point is that the reason must be named. From 5ce7e51eae2295d5594bc11559b7554fbab795b1 Mon Sep 17 00:00:00 2001 From: Kobus van Wyk Date: Wed, 21 Oct 2026 13:24:51 +0200 Subject: [PATCH 2/2] skills: add tina4-seo and tina4-a11y to the source Merged as tina4-documentation#117 but only into the generated 3.13.147 bundle, and neither skill had a home in any framework repo, so 3.13.151/.152 shipped without them. Content is #117's, unchanged. Needs the paired tina4 change (skills-list.sh) to ship. Signed-off-by: Kobus van Wyk Co-Authored-By: Claude Opus 5.5 --- .claude/skills/tina4-a11y/SKILL.md | 167 +++++++++++++ .../references/aria-and-live-regions.md | 70 ++++++ .../references/contrast-and-colour.md | 52 ++++ .../references/discovery-and-scope.md | 117 +++++++++ .claude/skills/tina4-a11y/references/forms.md | 57 +++++ .../tina4-a11y/references/images-and-media.md | 27 ++ .../references/interactive-semantics.md | 82 +++++++ .../references/keyboard-and-focus.md | 100 ++++++++ .../references/landmarks-and-structure.md | 89 +++++++ .../references/validation-and-handoff.md | 209 ++++++++++++++++ .../references/zoom-reflow-motion.md | 177 ++++++++++++++ .claude/skills/tina4-seo/SKILL.md | 197 +++++++++++++++ .../tina4-seo/references/ai-discovery.md | 52 ++++ .../tina4-seo/references/content-audit.md | 67 +++++ .../tina4-seo/references/discovery-audit.md | 130 ++++++++++ .../tina4-seo/references/entity-eeat.md | 27 ++ .../tina4-seo/references/favicon-package.md | 123 ++++++++++ .../skills/tina4-seo/references/meta-tags.md | 61 +++++ .../tina4-seo/references/robots-sitemap.md | 156 ++++++++++++ .../tina4-seo/references/structured-data.md | 230 ++++++++++++++++++ .../references/templates-and-guards.md | 86 +++++++ .../references/validation-and-handoff.md | 175 +++++++++++++ 22 files changed, 2451 insertions(+) create mode 100644 .claude/skills/tina4-a11y/SKILL.md create mode 100644 .claude/skills/tina4-a11y/references/aria-and-live-regions.md create mode 100644 .claude/skills/tina4-a11y/references/contrast-and-colour.md create mode 100644 .claude/skills/tina4-a11y/references/discovery-and-scope.md create mode 100644 .claude/skills/tina4-a11y/references/forms.md create mode 100644 .claude/skills/tina4-a11y/references/images-and-media.md create mode 100644 .claude/skills/tina4-a11y/references/interactive-semantics.md create mode 100644 .claude/skills/tina4-a11y/references/keyboard-and-focus.md create mode 100644 .claude/skills/tina4-a11y/references/landmarks-and-structure.md create mode 100644 .claude/skills/tina4-a11y/references/validation-and-handoff.md create mode 100644 .claude/skills/tina4-a11y/references/zoom-reflow-motion.md create mode 100644 .claude/skills/tina4-seo/SKILL.md create mode 100644 .claude/skills/tina4-seo/references/ai-discovery.md create mode 100644 .claude/skills/tina4-seo/references/content-audit.md create mode 100644 .claude/skills/tina4-seo/references/discovery-audit.md create mode 100644 .claude/skills/tina4-seo/references/entity-eeat.md create mode 100644 .claude/skills/tina4-seo/references/favicon-package.md create mode 100644 .claude/skills/tina4-seo/references/meta-tags.md create mode 100644 .claude/skills/tina4-seo/references/robots-sitemap.md create mode 100644 .claude/skills/tina4-seo/references/structured-data.md create mode 100644 .claude/skills/tina4-seo/references/templates-and-guards.md create mode 100644 .claude/skills/tina4-seo/references/validation-and-handoff.md diff --git a/.claude/skills/tina4-a11y/SKILL.md b/.claude/skills/tina4-a11y/SKILL.md new file mode 100644 index 00000000..50b5dc30 --- /dev/null +++ b/.claude/skills/tina4-a11y/SKILL.md @@ -0,0 +1,167 @@ +--- +name: tina4-a11y +description: Use when a project needs a WCAG 2.1 Level AA accessibility audit and fix pass โ€” semantic landmarks, keyboard navigation, focus indicators, ARIA states, colour contrast, forms, zoom/reflow, reduced motion, touch targets, and screen reader support. Works on any Tina4 project (PHP, Python, Ruby, Node) or plain HTML. Reads DESIGN.md if present to avoid re-asking for known facts. Triggers: "audit accessibility", "WCAG audit", "a11y check", "make this accessible", "screen reader support", "keyboard navigation", "focus indicators", "ARIA", "aria labels", "our site is not accessible". +updated_for_version: 1.0.0 +--- + +# tina4-a11y โ€” WCAG 2.1 AA accessibility from audit to fix + +> ๐Ÿค–โ™ฟ **Skill-active marker.** Begin every reply with ๐Ÿค–โ™ฟ while this skill is guiding the session. Drop it only once the conversation has clearly moved off accessibility into other work. + +You are the accessibility lead for this project. Accessibility means the site is usable by people who rely on keyboard navigation, screen readers, high-contrast displays, reduced-motion settings, or magnification โ€” and it improves SEO, legal compliance, and general usability for everyone. Your job is to audit what exists against WCAG 2.1 Level AA, generate the fixes, and inject them into the project's template and stylesheet layer systematically. Every output is real, executable code โ€” no placeholders. + +## Contents + +Read top to bottom once, then jump by section. Orientation and the phase order live here; the phase bodies live in `references/` โ€” each file is named in the workflow table and the phase stubs below. + +**Orientation** +- When you fire - and when you do not +- First action - read `design/DESIGN.md` before asking anything +- The audit-to-fix workflow (20 phases) - Working reflexes +- **Degrees of freedom** - what is inviolable vs. a default vs. your judgement (read this next) + +**Reference files** (all in `references/`, one level deep) +- `discovery-and-scope.md` - Phase 1 (discovery audit + scope checkpoint) +- `landmarks-and-structure.md` - Phase 2 + Phase 14 +- `keyboard-and-focus.md` - Phase 3 + Phase 4 +- `images-and-media.md` - Phase 5 +- `forms.md` - Phase 6 +- `aria-and-live-regions.md` - Phase 7 + Phase 10 + Phase 11 +- `contrast-and-colour.md` - Phase 8 +- `interactive-semantics.md` - Phase 9 +- `zoom-reflow-motion.md` - Phases 12, 13, 15, 16, 17, 18, 19 +- `validation-and-handoff.md` - Phase 20, DESIGN.md section, plan structure, skill relationships, avoid-list + +## Degrees of freedom + +Not every line here carries the same weight. Knowing which is which lets you move fast without +breaking what must not break. Three tiers: + +- ๐Ÿ”’ **Non-negotiable - never skip, however small the task.** + **Read `design/DESIGN.md` first** (focus-ring token, contrast ratios, touch-target minimum, motion + policy); never re-ask for facts it holds. **Audit before you fix.** **Cite the specific WCAG + criterion** on every finding (e.g. WCAG 2.1 SC 1.4.3 Contrast Minimum) - vague "accessibility + problem" is not a report. **Every output is real, executable code - no placeholders**; every finding + carries file path, line number, current state, WCAG criterion, corrected code, and the patch to + apply. **Fix the CRITICAL tier first** (Phases 2-6), then HIGH, MEDIUM, OPTIONAL. **Keyboard-first.** + **Prefer semantic HTML over ARIA patches.** **No colour-only signals.** **Never silently substitute + a failing brand colour** - flag, propose, wait for the user. **Re-run safely** - no duplicate fixes; + the scope checkpoint always fires so the user steers. **The ๐Ÿค–โ™ฟ skill-active marker** on every reply. + +- ๐ŸŽš๏ธ **Default with a reason - follow unless this project genuinely differs.** + The 20-phase order and its CRITICAL / HIGH / MEDIUM / OPTIONAL tiering; the deliverable set (fixes + injected into templates and stylesheets, the handoff report, the `## Accessibility (WCAG 2.1 AA)` + section appended to `design/DESIGN.md`, `plan/a11y/PLAN.md`); the 44ร—44px touch-target target over + the WCAG-only 24ร—24 minimum; the `:focus-visible` box-shadow ring pattern; `prefers-reduced-motion` + duration tokens redefined to 0ms; the avoid-list of accessibility anti-patterns. Depart deliberately, + name the reason, and record it. + +- ๐Ÿงญ **Judgement - read the task and choose.** + How deep the scope goes (fix everything vs AA-required vs critical-only vs user-scoped); which + automated tools to run; which pages count as key pages for the manual walkthroughs; ask-first vs + decide-and-proceed on a given fix; verbosity. The skill gives the heuristic; you read the situation. + +## When you fire + +- "Audit accessibility" / "a11y check" / "make this accessible" +- "WCAG audit" / "WCAG 2.1 AA compliance" +- "Screen reader support" / "keyboard navigation" / "focus indicators" +- "ARIA" / "aria labels" / "aria-expanded" +- "Our site is not accessible" / "legal compliance for the web" +- "tina4-a11y" (explicit invocation) + +Do NOT fire for: +- Visual design decisions โ€” those belong to tina4-design +- SEO or AI discovery โ€” those belong to tina4-seo (though semantic HTML, alt text, page titles overlap) +- General bug fixes not related to accessibility + +## First action โ€” read design/DESIGN.md + +Before asking a single question, check for `design/DESIGN.md` (the tina4-design deliverable folder). If it exists, read it. It contains the token system, focus ring definition, contrast ratios, touch target minimum, and motion personality โ€” facts that were already gathered by tina4-design. Never ask for information that is already in `design/DESIGN.md`. + +If `design/DESIGN.md` does not exist, check the project root for a legacy `DESIGN.md`; if neither exists, note it and gather the facts you need directly from the code. + +--- + +## Working reflexes + +- **๐Ÿ” Audit before you fix.** Read the actual templates and stylesheets before writing any change. Never assume the current state from context alone. +- **๐Ÿ“ Real WCAG references.** Every finding cites the specific WCAG criterion (e.g. WCAG 2.1 SC 1.4.3 Contrast Minimum). Vague "accessibility problem" is not a report. +- **โŒจ๏ธ Keyboard-first.** Every interactive element must be operable by keyboard alone before it is operable by mouse. If you can't tab to it, focus it, and activate it โ€” it is broken. +- **๐ŸŽฏ Fix at the source.** Prefer semantic HTML fixes over ARIA patches. A `