@r1z4x/tezgah 1.0.0

package/skills/design-library/cognitive-accessibility/skills/focus-attention-design/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: focus-attention-design
+description: "Design interfaces that support sustained focus and reduce distractions. Use when designing for users with ADHD, attention difficulties, anxiety, or any context where focus matters — dashboards, reading experiences, task flows, forms, learning interfaces. Triggers on: focus, distraction, ADHD, attention, too busy, cluttered, visual noise, autoplay, notifications, pop-ups, interruptions."
+---
+
+# Focus and Attention Design
+
+Design interfaces that help people maintain focus on their task by
+removing unnecessary distractions and giving users control over their
+attention environment.
+
+## Core Principle
+
+Every element on screen should serve the user's current task.
+If it exists for the business but not for the user, it is a distraction.
+
+## Design Patterns
+
+### Single Purpose
+- One primary action per screen or section
+- Secondary actions visually de-emphasised (smaller, muted colour, text link)
+- Remove decorative elements that don't serve the task
+- Hide advanced options behind "Show more" or "Advanced"
+- Present choices sequentially, not simultaneously, when possible
+
+### Interruption Control
+- No autoplay audio or video
+- No pop-ups that aren't triggered by user action
+- Allow users to dismiss or defer notifications
+- Save state before showing any modal — closing it must not lose work
+- Never remove content from the screen without user action
+- If a banner or alert is needed, make it dismissable and non-blocking
+
+### Visual Calm
+- Generous whitespace between sections
+- Limited colour palette (3–4 colours for UI elements)
+- Subtle borders and dividers, not heavy lines
+- No flashing, blinking, or rapidly changing content
+- Animation only for functional feedback (loading, transitions)
+- Always respect prefers-reduced-motion
+
+### Time Sensitivity
+- Avoid time limits unless absolutely essential
+- If time limits exist, warn well before expiry
+- Provide easy extension (one click, not multi-step)
+- Allow at least 20 seconds per required decision
+- Save progress automatically in timed contexts
+- For session timeouts: save state and allow seamless return
+
+## Assessment Questions
+
+For each screen, ask:
+1. What is the ONE thing the user should do here?
+2. Is that one thing the most visually prominent element?
+3. What on this screen competes for attention? Can it be removed or muted?
+4. Can the user control interruptions (notifications, modals, autoplay)?
+5. Is there artificial urgency that doesn't serve the user?
+
+## Anti-Patterns to Flag
+
+- Countdown timers on non-time-sensitive actions
+- "Only 2 left!" urgency messaging
+- Autoplay video or audio
+- Multiple competing calls to action
+- Chat widgets that pop up unsolicited
+- Moving or animated advertisements near task areas
+- Layout shifts that redirect attention

package/skills/design-library/cognitive-accessibility/skills/memory-load-reduction/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: memory-load-reduction
+description: "Design interfaces that minimise demands on working memory. Use when designing multi-step flows, dashboards, comparison tools, forms that span multiple screens, or any interface where users need to remember information across steps or sessions. Triggers on: memory, remember, forget, carry forward, multi-step, users drop off, too many steps, lose their place, context."
+---
+
+# Memory Load Reduction
+
+Design systems that remember so users don't have to. Working memory holds
+roughly 4 items. Every piece of information the user must carry across
+screens, steps, or sessions is a potential failure point.
+
+## Core Principle
+
+If the system can remember it, the user shouldn't have to.
+
+## Design Patterns
+
+### Persistent Context
+- Show key selections throughout a multi-step flow
+  (chosen product, plan, date visible on every step)
+- Display running totals in shopping and financial contexts
+- Keep the user's search query visible in results
+- In multi-step forms, show a summary sidebar of completed steps
+
+### Forward Carry
+- Never re-ask information the system already has
+- Pre-fill fields from earlier steps or previous sessions
+- Carry context between screens (if the user selected "Business",
+  don't ask "Personal or Business?" again)
+- Remember user preferences across sessions
+
+### External Memory Aids
+- "Compare" features so users don't need to remember options
+- Recently viewed and recently used lists
+- Copy-to-clipboard for reference numbers and codes
+- Print-friendly versions of complex information
+- Bookmarking or favouriting for later reference
+
+### Save and Resume
+- Auto-save progress in any flow longer than 3 steps
+- Allow users to return to where they left off
+- Show when progress was last saved
+- Send a reminder link for abandoned multi-step tasks
+- Never require starting over when a session expires
+
+### Chunked Process
+- Break tasks into 3–7 clearly labelled steps
+- One decision per step where possible
+- Allow forward and backward movement between steps
+- Show progress: "Step 2 of 4: Choose your plan"
+- Provide a review/summary screen before final submission
+
+## Assessment Questions
+
+1. Does the user need to remember anything from a previous screen?
+2. Is any information hidden that the user might need to reference?
+3. Can the user leave and come back without losing progress?
+4. Are there places where the user needs to transfer information
+   between screens manually (e.g., write down a code)?
+5. Does the system re-ask for information it already knows?

package/skills/design-library/cognitive-accessibility/skills/plain-language-design/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: plain-language-design
+description: "Write and review content for plain language accessibility. Use when writing interface copy, error messages, instructions, onboarding text, help content, legal or medical information, forms, or any user-facing text. Triggers on: plain language, reading level, simplify text, jargon, hard to understand, nobody reads this, unclear copy, rewrite, too complicated, ESL, literacy, readability."
+---
+
+# Plain Language Design
+
+Write and evaluate content so that people with cognitive disabilities,
+low literacy, non-native language skills, or high stress can understand it
+on the first read.
+
+Plain language is not dumbed-down language. It is clear language. It
+respects the reader's time and cognitive resources.
+
+## The Tests
+
+### 5-Second Test
+Can someone read this sentence and understand it in 5 seconds?
+If not, rewrite.
+
+### Jargon Test
+Would someone outside your industry understand every word?
+If not, replace the word or define it inline.
+
+### Action Test
+For any instruction or button: is the next step completely unambiguous?
+"Save and continue" beats "Next". "Delete this item" beats "Remove".
+
+### Passive Voice Test
+Passive voice hides who does what.
+"Your application has been rejected" → "We could not approve your
+application. Here's what to do next."
+
+### Sentence Length Test
+- Aim for 15–20 words per sentence maximum
+- One idea per sentence
+- One instruction per paragraph
+
+## Common Replacements
+
+| Instead of | Use |
+|-----------|-----|
+| utilise | use |
+| facilitate | help |
+| implement | set up / start |
+| terminate | end / stop |
+| prior to | before |
+| in order to | to |
+| at this point in time | now |
+| in the event that | if |
+| with regard to | about |
+| commence | start |
+| sufficient | enough |
+| subsequent | next |
+| indicate | show / tell |
+| modify | change |
+
+## Readability Benchmarks
+
+- General public: grade 6–8 reading level
+- Specialist audience: define terms, short sentences
+- Critical content (medical, legal, financial): plain language summary
+  alongside the full text
+- Buttons, labels, error messages: grade 4–6 always
+
+## How to Review
+
+1. Read every piece of text aloud — stumbles reveal complexity
+2. Check sentence length (count words — flag any over 25)
+3. Identify jargon, acronyms, and idioms
+4. Verify every instruction has a clear, single action
+5. Check that error messages say: what happened + why + what to do
+
+## Output Format
+
+When reviewing: present a table of flagged text with the original,
+the issue, and a rewritten version. When writing: produce plain language
+content with a note on the target reading level achieved.

package/skills/design-library/cognitive-accessibility/skills/review/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: review
+description: "Run a full cognitive accessibility review of a flow, screen, or interface. Chains: cognitive-load-assessment, plain-language-design, wayfinding-navigation, error-prevention-recovery, focus-attention-design, memory-load-reduction."
+---
+
+# Cognitive Accessibility Review
+
+Run a comprehensive cognitive accessibility review. This command chains
+six skills into a structured assessment.
+
+## Process
+
+### Phase 1: Context
+Identify the interface, flow, or content to review. Establish:
+- Who uses this and what cognitive state they're likely in
+- What the stakes are (low, medium, high)
+- What cognitive demands the task makes
+
+### Phase 2: Cognitive Load Assessment
+Using the **cognitive-load-assessment** skill, evaluate each screen or
+step across all six dimensions: decisions, memory, new concepts, steps,
+reading complexity, and visual complexity.
+
+### Phase 3: Language Review
+Using the **plain-language-design** skill, review all user-facing text
+for readability, jargon, ambiguity, and action clarity.
+
+### Phase 4: Wayfinding Check
+Using the **wayfinding-navigation** skill, verify that users always know
+where they are, where they can go, and how to get back.
+
+### Phase 5: Error & Focus Review
+Using **error-prevention-recovery** and **focus-attention-design** skills,
+review error handling patterns and identify distractions or attention
+hazards.
+
+### Phase 6: Memory Load Check
+Using the **memory-load-reduction** skill, identify any place where
+users must remember information across screens, steps, or sessions.
+
+## Output
+
+Present findings as a structured report:
+
+1. **Executive summary** — overall cognitive accessibility rating and top 3
+   issues
+2. **Screen-by-screen findings** — table of issues by screen/step with
+   severity (critical / major / minor)
+3. **Prioritised recommendations** — specific fixes ranked by impact and
+   effort
+4. **Population impact** — which user groups are most affected by each issue
+
+Severity definitions:
+- **Critical** — prevents task completion for users with cognitive disabilities
+- **Major** — causes significant difficulty or confusion
+- **Minor** — creates friction but doesn't block completion

package/skills/design-library/cognitive-accessibility/skills/simplify/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: simplify
+description: "Simplify content and interactions to reduce cognitive load. Chains: plain-language-design, cognitive-load-assessment, focus-attention-design. Use when given content, a flow, or an interface that needs to be made more accessible."
+---
+
+# Simplify
+
+Take existing content, a flow, or an interface and produce a
+cognitively simplified version.
+
+## Process
+
+### Step 1: Assess Current Load
+Using **cognitive-load-assessment**, evaluate the current state. Identify
+the highest-load elements and classify them as intrinsic or extraneous.
+
+### Step 2: Simplify Language
+Using **plain-language-design**, rewrite all user-facing text:
+- Reduce to grade 6–8 reading level (grade 4–6 for critical content)
+- Replace jargon with plain alternatives
+- Shorten sentences to 15–20 words maximum
+- Make every instruction specific and single-action
+
+### Step 3: Reduce Visual and Interaction Load
+Using **focus-attention-design**, reduce the interface to essentials:
+- Identify the one primary action per screen
+- De-emphasise or remove secondary elements
+- Remove decorative elements that don't serve the task
+- Simplify navigation to the minimum effective depth
+
+### Step 4: Present Before and After
+Show the original alongside the simplified version with annotations
+explaining each change and why it improves cognitive accessibility.
+
+## Output
+
+Deliver the simplified version with a change log that explains every
+modification. This allows the team to make informed decisions about
+which simplifications to adopt.

package/skills/design-library/cognitive-accessibility/skills/wayfinding-navigation/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: wayfinding-navigation
+description: "Design navigation and information architecture for cognitive accessibility. Use when designing or reviewing navigation, site maps, page hierarchies, breadcrumbs, search, multi-step flows, or any structure where users need to find content and know where they are. Triggers on: users get lost, navigation, wayfinding, information architecture, breadcrumbs, findability, site map, confusing structure, where am I."
+---
+
+# Wayfinding and Navigation
+
+Design navigation so that people with cognitive and memory difficulties
+can find content, understand where they are, and get back to where they
+were — without relying on memory.
+
+## Core Principle
+
+Users should always be able to answer three questions instantly:
+1. **Where am I?**
+2. **Where can I go?**
+3. **How do I get back?**
+
+If any answer requires more than 1 second of thought, the navigation
+has failed.
+
+## Design Patterns
+
+### Signpost Pattern
+- Breadcrumbs in hierarchies deeper than 2 levels
+- Step indicators in multi-step flows ("Step 2 of 4")
+- Active section highlighted in navigation
+- Page titles that match the link that brought the user here
+
+### Minimal Path Pattern
+- Important actions reachable in 1–2 clicks from any screen
+- Breadth over depth — flatten deep hierarchies
+- Shortcuts to frequently used content
+- "Back to [last meaningful location]" always available
+
+### Multiple Routes Pattern
+- Search AND browse AND shortcuts for all important content
+- Don't force a single path to any destination
+- "Jump to" links for long pages
+- Recently visited and frequently used sections accessible
+
+### Chunking Pattern
+- Break long content into headed sections (3–5 paragraphs each max)
+- Table of contents for pages longer than 3 screens
+- Progressive disclosure for detail
+- Group related form fields into labelled fieldsets
+
+## Assessment Checklist
+
+- [ ] Every page has a clear, descriptive title
+- [ ] Navigation is consistent across all pages (same position, same order)
+- [ ] Current location is always visually indicated
+- [ ] Breadcrumbs or back links are present in hierarchies
+- [ ] Multi-step flows show progress and allow backward movement
+- [ ] Search is available on every page
+- [ ] Important actions are reachable in 2 clicks or fewer
+- [ ] Headings describe content (not just categories)
+- [ ] Link text describes the destination (no "click here")
+
+## Output Format
+
+When reviewing: identify navigation failures with specific locations
+and recommended fixes. When designing: present the information
+architecture with cognitive accessibility annotations.

package/skills/design-library/design-research/skills/behavioural-analytics/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: behavioural-analytics
+description: Read funnels, retention curves, and event data as a designer — separating a design problem from a tracking artefact. Use when handed product data you did not design and asked why people drop off. For choosing what to measure, use `metrics-definition` (ux-strategy); for running a controlled test, use `a-b-test-design` (prototyping-testing).
+---
+# Behavioural Analytics
+You are an expert in reading product data the way a designer must: to locate a problem, not to prove one.
+## What You Do
+You take a funnel, a retention curve, or an event stream that someone else instrumented, and produce a short list of ranked hypotheses about where the design is failing and what would confirm or kill each one. You do not define the metric — that has already happened — and you do not run the experiment. You decide what is worth looking at next.
+## Before You Trust the Number
+Most surprising numbers are wrong before they are interesting. Rule these out before forming a single design hypothesis:
+- **The event does not mean what its name says.** `checkout_completed` may fire on render, not on payment. Read the tracking definition, not the label.
+- **The denominator moved.** A conversion drop with a flat numerator is an acquisition change, not a design change.
+- **The step is not a step.** Funnels imply an order the product does not enforce. If users can skip, return, or arrive mid-flow, a "drop-off" is often a path the funnel cannot see.
+- **A release, a holiday, or a campaign lands on the same date.** Line up deploys and marketing before attributing anything to the interface.
+- **The platform split is hiding the effect.** An aggregate that barely moves often conceals one platform falling and another rising.
+A number that survives all five is worth designing against. One that does not is a data question, and answering it as a design question wastes a cycle.
+## Reading the Shape
+The shape carries more meaning than the value:
+- **A cliff at one step** — something is blocking. A requirement, an error, a demand for information the user does not have yet.
+- **A slope across many steps** — nothing is blocking; the flow is simply too long. Removing one step will move it only slightly.
+- **Retention that falls then flattens** — you have a real core of users and a bad first run. The flat part is the product working.
+- **Retention that keeps falling** — no core yet. Onboarding fixes will not save this; the value proposition is the problem.
+- **A bimodal time-on-task** — two populations doing different things in one flow. Segment before designing, or you will design for a mean that describes nobody.
+## From Shape to Hypothesis
+A hypothesis is only useful when it forbids something. "Users are confused at step three" forbids nothing. "Users abandon at step three because the address form rejects valid non-UK postcodes" predicts a specific error rate in a specific segment, and dies cleanly if that rate is flat.
+For each hypothesis state: the segment it applies to, the observation that would kill it, and whether the answer needs data you already have, a session recording, or a conversation. Rank by how cheaply each can be killed, not by how likely you think it is.
+## Best Practices
+- Look at the segment before the average; an aggregate is a claim that everyone behaves alike
+- Say how confident you are and why, in the same breath as the finding
+- Prefer the smallest cohort that still answers the question — big numbers hide the mechanism
+- Do not read a step change from a chart without checking what shipped that week
+- Do not treat a statistically significant difference as a large one; ask what it is worth before designing for it
+- Not for deciding whether the numbers or the interviews are right when they conflict — that is `qual-quant-triangulation`

package/skills/design-library/design-research/skills/qual-quant-triangulation/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: qual-quant-triangulation
+description: Reconcile what the numbers say with what users say, and design the study that settles it rather than restates it. Use when behavioural data and research findings point different ways. For reading the data on its own, use `behavioural-analytics`; for synthesising interviews on their own, use `affinity-diagram`.
+---
+# Qual-Quant Triangulation
+You are an expert in what to do when the dashboard and the interviews disagree.
+## What You Do
+You take two accounts of the same behaviour — one measured, one reported — and work out what their disagreement means, which one answers the question actually being asked, and what the next study has to look like to settle it. The output is a decision about what to believe and one study design, not a summary of both sources.
+## Disagreement Is Information
+Teams treat a conflict as a problem with one source. It is usually a signal in its own right, and the shape of it tells you where to look:
+| What you see | What it usually means |
+| --- | --- |
+| Data shows abandonment; users report no difficulty | They abandoned for a reason they do not attribute to the interface — price, timing, or a decision made before arriving |
+| Users report a serious problem; data shows no effect | The affected segment is small, or the problem happens before instrumentation starts |
+| Data improved; users report it feels worse | You optimised a proxy. The metric moved, the experience did not |
+| Users are enthusiastic; retention is flat | Stated preference, not revealed. Enthusiasm in a session is not a return visit |
+| Both look fine; the business outcome does not | You are measuring the task, not the goal the task serves |
+The last two are the expensive ones, because nothing looks wrong until much later.
+## Which Source Answers Which Question
+Give each question to the source that can actually answer it, and stop asking the other:
+- **What happened, how often, and where** — behavioural data. Interviews are a poor census; people misremember frequency badly.
+- **Why, and what they were trying to do** — research. No amount of event data recovers intent.
+- **Whether the thing is worth building at all** — neither, on its own. That is a judgment, and dressing it as a finding is how teams launder a decision they already made.
+When someone asks a why-question of a dashboard, or a how-many-question of six interviews, the disagreement you are looking at is not real. It is a category error.
+## Designing the Study That Settles It
+A resolving study is narrower than either original. Write down, before running it: the specific claim in dispute, what result would make you drop the qualitative account, and what result would make you drop the quantitative one. If no result could change your mind, you are not resolving the conflict, you are building a case.
+Prefer the cheap instrument that discriminates. A session recording of the disputed step usually beats another round of interviews and another dashboard. If the dispute is about *why*, add measurement to the qualitative session rather than running two studies.
+## Best Practices
+- Name which source is load-bearing for the decision before you look at either
+- Weight revealed behaviour over stated preference when they conflict on the same question
+- Check that both sources describe the same population before calling it a contradiction — different segments are not a disagreement
+- Do not average the two accounts into a compromise finding; a middle position neither source supports is worse than picking one
+- Do not resolve a conflict by re-running the study that produced the answer you prefer

package/skills/design-library/inclusive-interaction/skills/audit/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: audit
+description: "Audit an interface for multi-modal interaction support. Chains: keyboard-navigation, touch-target-design, multi-modal-input, gesture-alternatives, feedback-and-status, motion-sensitivity. Use when reviewing an existing interface for interaction accessibility."
+---
+
+# Inclusive Interaction Audit
+
+Run a comprehensive audit of how an interface supports diverse input
+methods, output channels, and physical abilities.
+
+## Process
+
+### Phase 1: Keyboard Pass
+Using **keyboard-navigation**, attempt every task using only the keyboard.
+Document: unreachable elements, focus order issues, missing focus
+indicators, keyboard traps, and missing skip links.
+
+### Phase 2: Touch and Pointer Pass
+Using **touch-target-design**, measure all interactive elements.
+Document: undersized targets, insufficient spacing, precision-dependent
+interactions, and missing tap alternatives.
+
+### Phase 3: Input Alternatives Check
+Using **multi-modal-input** and **gesture-alternatives**, verify that
+every interaction has at least two input methods. Document: single-input
+dependencies, disabled paste fields, gesture-only features, and
+missing alternatives for complex interactions.
+
+### Phase 4: Feedback and Motion Check
+Using **feedback-and-status** and **motion-sensitivity**, verify that
+all feedback reaches multiple senses and that motion is safe.
+Document: colour-only indicators, missing screen reader announcements,
+dangerous motion, and prefers-reduced-motion support.
+
+## Output
+
+Present findings as a structured report:
+
+1. **Summary** — overall interaction accessibility rating and critical
+   blockers
+2. **Input method matrix** — table showing which tasks work with which
+   input methods (keyboard, pointer, touch, voice)
+3. **Issue list** — each issue with severity, affected input method,
+   affected users, and specific fix
+4. **Prioritised fixes** — ranked by number of users unblocked
+
+Severity definitions:
+- **Critical** — a task cannot be completed with a common input method
+- **Major** — a task is significantly harder with certain input methods
+- **Minor** — friction exists but the task can be completed

package/skills/design-library/inclusive-interaction/skills/design-flow/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: design-flow
+description: "Design an interaction flow with inclusive input and output options from the start. Chains: multi-modal-input, keyboard-navigation, touch-target-design, feedback-and-status. Use when designing a new feature, flow, or interface and you want to build inclusive interaction in from the beginning."
+---
+
+# Design Inclusive Interaction Flow
+
+Design a new interaction flow that supports diverse input methods and
+provides accessible feedback from the start — not retrofitted after.
+
+## Process
+
+### Step 1: Identify All Interactions
+List every point in the flow where the user must act:
+- Click/tap a button
+- Enter text
+- Make a selection
+- Navigate between steps
+- Drag, swipe, or gesture
+- Respond to a prompt
+
+### Step 2: Assign Input Methods
+Using **multi-modal-input**, for each interaction specify how it works
+across at least three input methods:
+- Keyboard: what keys or shortcuts activate it?
+- Pointer/touch: what is the target size and spacing?
+- Voice (where applicable): what command triggers it?
+
+Flag any interaction that only works with one input method.
+
+### Step 3: Design the Keyboard Layer
+Using **keyboard-navigation**, define:
+- Tab order through all interactive elements
+- Focus management for modals, dropdowns, and dynamic content
+- Skip links and landmark navigation
+- Keyboard shortcuts for frequent actions (document them)
+
+### Step 4: Specify Targets
+Using **touch-target-design**, specify:
+- Minimum sizes for all interactive elements
+- Spacing between adjacent targets
+- Thumb zone placement for mobile primary actions
+
+### Step 5: Design Feedback
+Using **feedback-and-status**, for each interaction specify:
+- What the user sees (visual feedback)
+- What a screen reader announces (text alternative)
+- What happens on success, error, and loading states
+- How feedback works with colour, icon, and text combined
+
+## Output
+
+Deliver an interaction specification that includes:
+- Flow diagram with interaction points marked
+- Input method matrix (task × input method)
+- Focus order map
+- Target size annotations
+- Feedback specification per interaction

package/skills/design-library/inclusive-interaction/skills/feedback-and-status/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: feedback-and-status
+description: "Design feedback and status communication that works across senses — visual, auditory, and haptic. Use when designing loading states, success messages, progress indicators, notifications, alerts, or any system response to user action. Triggers on: feedback, status, notification, alert, loading, progress, success message, confirmation, toast, snackbar, screen reader announcement, aria-live, colour alone."
+---
+
+# Feedback and Status Design
+
+Design system feedback that reaches every user — regardless of whether
+they can see the screen, hear audio, or feel vibration. No single
+sense should be the only channel.
+
+## Core Principle
+
+Never communicate status through one sense alone. What happens if the
+user can't see it? Can't hear it? Can't feel it?
+
+## The Multi-Channel Rule
+
+Every piece of feedback should work through at least two channels:
+
+| Feedback type | Visual | Text | Sound | Haptic |
+|--------------|--------|------|-------|--------|
+| Success | Green tick | "Saved successfully" | Confirmation tone | Short vibration |
+| Error | Red highlight | Specific error message | Alert tone | Double vibration |
+| Loading | Spinner/bar | "Loading..." | None (silence) | None |
+| Warning | Yellow banner | Warning text | Optional tone | Optional vibration |
+
+Screen readers are a critical third channel — all visual feedback must
+be announced to assistive technology.
+
+## Design Patterns
+
+### Don't Rely on Colour Alone
+- Red/green is invisible to 8% of men with colour vision deficiency
+- Always combine colour with: icon, text label, pattern, or position
+- Error states: red + error icon + text description
+- Success states: green + tick icon + text confirmation
+- Test: does this still communicate the same thing in greyscale?
+
+### Immediate Feedback
+- Button press: visual change within 100ms (pressed state)
+- Form submission: loading indicator within 1 second
+- Completion: success message within 2 seconds of finishing
+- Error: highlight the specific field, not just a banner at the top
+
+### Persistent vs. Transient Feedback
+- **Transient** (toast/snackbar): only for non-critical confirmations.
+  Show for at least 5 seconds. Include a way to review missed messages.
+- **Persistent** (inline): for errors, warnings, and anything the user
+  needs to act on. Never auto-dismiss error messages.
+- Screen reader users miss transient messages — use aria-live="polite"
+  for non-urgent updates, aria-live="assertive" for critical alerts.
+
+### Progress Communication
+- Determinate progress (known duration): show percentage or step count
+- Indeterminate progress (unknown duration): show spinner with
+  text like "Loading your results..."
+- Long processes (over 10 seconds): add estimated time remaining
+- Very long processes: allow background processing with notification
+  on completion
+
+### Status Without Vision
+- All status changes must be announced to screen readers
+- Use aria-live regions for dynamic content updates
+- Don't rely on visual position alone to convey status
+  (e.g., a moved item in a kanban board needs a text announcement)
+- Error messages must be programmatically associated with their
+  field (aria-describedby)
+
+## Assessment Questions
+
+1. Is colour ever the only indicator of status?
+2. Can a screen reader user perceive every status change?
+3. Are error messages persistent until resolved?
+4. Do transient messages display long enough to be read?
+5. Does every user action produce perceivable feedback?