@shaykec/bridge 0.4.24 → 0.4.26

package/modules/accessibility-fundamentals/exercises.md

@@ -0,0 +1,88 @@
+# Accessibility Exercises
+
+## Exercise 1: Contrast Audit
+
+**Task:** Audit a real site or design file. For body text, headings, and at least two buttons/links, measure contrast ratios. Document passes (AA) and failures. For each failure, propose a fix.
+
+**Validation:**
+- [ ] At least 5 elements measured
+- [ ] Contrast ratios recorded (e.g., 4.2:1 fails; 4.5:1 passes)
+- [ ] Each failure has a concrete fix (color change, size change, or background)
+- [ ] Re-measurement shows passes after fixes
+
+**Hints:**
+1. Use WebAIM Contrast Checker or browser DevTools
+2. Large text = 18pt+ or 14pt+ bold; different threshold (3:1 for AA)
+3. Buttons: contrast against both background and any border
+
+---
+
+## Exercise 2: Keyboard-Only Form
+
+**Task:** Build a simple form (name, email, submit) that is fully usable with the keyboard. Ensure: tab order makes sense, focus is visible, errors are announced, and Enter submits.
+
+**Validation:**
+- [ ] All fields reachable and operable via Tab/Enter/Space
+- [ ] Focus ring visible on all interactive elements
+- [ ] Form can be submitted with Enter
+- [ ] Validation errors are associated with fields (e.g., `aria-describedby`) and focus moves to first error
+
+**Hints:**
+1. Use `<label for="id">` to associate labels
+2. Use `aria-describedby` for error messages
+3. Test with `:focus-visible` styles
+
+---
+
+## Exercise 3: Screen Reader Testing
+
+**Task:** Use VoiceOver or NVDA to complete a task on a site (e.g., find and click a specific link, fill a field). Document: what was announced, what was confusing, and one change that would help.
+
+**Validation:**
+- [ ] Task completed with screen reader only
+- [ ] At least 3 observations documented (announcements, confusion, gaps)
+- [ ] One concrete improvement suggested with implementation note (e.g., add `aria-label`, fix heading order)
+
+**Hints:**
+1. Use heading navigation (VoiceOver: VO+Cmd+H) to skim
+2. Use rotor/lists to jump to links or form controls
+3. Note redundant or missing announcements
+
+---
+
+## Exercise 4: Semantic HTML vs. ARIA
+
+**Task:** Given this markup, fix it for accessibility. Use semantic HTML first; add ARIA only when needed.
+
+```html
+<div onclick="submit()">Submit</div>
+<div class="checkbox" onclick="toggle()"></div>
+<img src="chart.png">
+```
+
+**Validation:**
+- [ ] "Submit" is a `<button>` or has `role="button"` + `tabindex="0"` + keyboard handler if not `<button>`
+- [ ] Checkbox uses `<input type="checkbox">` or has `role="checkbox"`, `aria-checked`, and keyboard support
+- [ ] Image has meaningful `alt` or `alt=""` if decorative
+- [ ] No ARIA when native HTML suffices
+
+**Hints:**
+1. `<button>` handles keyboard and focus automatically
+2. `<input type="checkbox">` is preferred over ARIA checkbox
+3. Ask: is the image meaningful? If not, `alt=""`
+
+---
+
+## Exercise 5: Run axe and Fix Issues
+
+**Task:** Install axe DevTools (browser extension). Run it on a page. Fix all Critical and Serious issues. Document what you changed and why.
+
+**Validation:**
+- [ ] axe shows 0 Critical and 0 Serious issues (or documented exceptions)
+- [ ] Each fix is documented (element, rule, fix applied)
+- [ ] Manual spot-check: keyboard and screen reader still work
+
+**Hints:**
+1. Common fixes: add `alt`, fix contrast, add `aria-label`, fix heading order
+2. Some issues require design changes—document and escalate
+3. Re-run axe after each fix to ensure no regressions

package/modules/accessibility-fundamentals/module.yaml

@@ -0,0 +1,43 @@
+slug: accessibility-fundamentals
+title: "Accessibility -- WCAG Fundamentals for Designers"
+version: 1.0.0
+description: "Learn WCAG principles, conformance levels, and practical a11y patterns for inclusive design."
+category: ux-design
+tags: [accessibility, wcag, a11y, inclusive-design, screen-readers, aria]
+difficulty: beginner
+
+xp:
+  read: 10
+  walkthrough: 30
+  exercise: 20
+  quiz: 15
+  quiz-perfect-bonus: 10
+
+time:
+  quick: 5
+  read: 15
+  guided: 45
+
+prerequisites: []
+related: [design-critique, react-fundamentals]
+
+triggers:
+  - "What are WCAG guidelines?"
+  - "How do I make my app accessible?"
+  - "What is ARIA and when should I use it?"
+  - "How do screen readers work?"
+
+visuals:
+  diagrams: [diagram-mermaid, diagram-flow]
+  quiz-types: [quiz-matching, quiz-timed-choice]
+  playground: bash
+  web-embeds: true
+  slides: true
+
+sources:
+  - url: "https://www.w3.org/WAI/WCAG21/quickref/"
+    label: "WCAG 2.1 Quick Reference"
+    type: docs
+  - url: "https://webaim.org"
+    label: "WebAIM"
+    type: docs

package/modules/accessibility-fundamentals/quick-ref.md

@@ -0,0 +1,71 @@
+# Accessibility Quick Reference
+
+## WCAG POUR
+
+| Principle | Focus |
+|-----------|-------|
+| **Perceivable** | Text alternatives, captions, color not sole indicator |
+| **Operable** | Keyboard, time, no seizure triggers |
+| **Understandable** | Readable, predictable, input help |
+| **Robust** | Valid markup, assistive-tech compatible |
+
+## Conformance Levels
+
+| Level | Typical Use |
+|-------|-------------|
+| A | Minimum baseline |
+| AA | Target for most sites; legal requirement in many places |
+| AAA | Enhanced; not always feasible |
+
+## Contrast (AA)
+
+| Content | Ratio |
+|---------|-------|
+| Normal text | 4.5:1 |
+| Large text (18pt+ or 14pt+ bold) | 3:1 |
+| UI components | 3:1 |
+
+## Semantic HTML
+
+| Purpose | Element |
+|---------|---------|
+| Heading | `<h1>`–`<h6>` |
+| Link | `<a href="">` |
+| Button | `<button>` |
+| Form | `<label>`, `<input>`, `<select>`, `<textarea>` |
+| Landmarks | `<header>`, `<main>`, `<nav>`, `<footer>`, `<article>`, `<aside>` |
+
+## ARIA Quick Guide
+
+| Use | Example |
+|-----|---------|
+| Label | `aria-label="Close dialog"` |
+| Description | `aria-describedby="error-1"` |
+| State | `aria-expanded`, `aria-selected`, `aria-checked` |
+| Live region | `aria-live="polite"` |
+
+**Rule:** Prefer HTML; use ARIA when HTML isn't enough.
+
+## Alt Text
+
+| Image Type | Alt |
+|------------|-----|
+| Informative | Describe content/function |
+| Decorative | `alt=""` |
+| Complex | `alt` summary + long description |
+
+## Keyboard
+
+- Tab order follows visual order
+- Focus visible (ring)
+- No keyboard traps
+- Enter/Space activate buttons and links
+
+## Testing
+
+| Tool | Purpose |
+|------|---------|
+| axe DevTools | In-browser WCAG audit |
+| Lighthouse | Audit + performance |
+| WAVE | Visual a11y feedback |
+| Screen readers | NVDA, VoiceOver, TalkBack |

package/modules/accessibility-fundamentals/quiz.md

@@ -0,0 +1,100 @@
+# Accessibility Quiz
+
+## Question 1
+
+What does the "P" in POUR stand for?
+
+A) Performance
+B) Perceivable
+C) Portable
+D) Progressive
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: POUR stands for Perceivable, Operable, Understandable, Robust. Perceivable means information and UI must be presentable in ways users can perceive—e.g., text alternatives, captions, color not as the only indicator. -->
+
+## Question 2
+
+What is the minimum contrast ratio for normal body text at WCAG AA?
+
+A) 3:1
+B) 4.5:1
+C) 7:1
+D) 2:1
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: WCAG AA requires 4.5:1 for normal text and 3:1 for large text (18pt+ or 14pt+ bold). AAA requires 7:1 for normal text. 3:1 is for large text and UI components. -->
+
+## Question 3
+
+When should you use ARIA?
+
+A) Always—it makes everything accessible
+B) Only when native HTML doesn't provide the needed semantics or behavior
+C) Never—ARIA is deprecated
+D) Only for custom components
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Use native HTML first (e.g., <button>, <label>). Add ARIA only when HTML isn't enough—e.g., for custom widgets, live regions, or complex interactions. Redundant or incorrect ARIA can hurt accessibility. -->
+
+## Question 4
+
+For a decorative image (e.g., a background pattern or spacer), what should the alt attribute be?
+
+A) "Decorative image"
+B) "Image"
+C) Empty: alt=""
+D) Omit the alt attribute entirely
+
+<!-- ANSWER: C -->
+<!-- EXPLANATION: Decorative images should have alt="" (empty string) so screen readers skip them. Omitting alt entirely can cause the filename or URL to be announced. "Decorative image" or "Image" is redundant noise. -->
+
+## Question 5
+
+What percentage of accessibility issues can automated tools reliably catch?
+
+A) About 90%
+B) About 50%
+C) About 30%
+D) Nearly 100%
+
+<!-- ANSWER: C -->
+<!-- EXPLANATION: Automated tools catch roughly 30% of accessibility issues. Many problems—keyboard traps, confusing focus order, unclear labels, cognitive overload—require manual testing with keyboard and screen readers. -->
+
+## Question 6
+
+Which element is best for a button that triggers an action?
+
+A) <div role="button" tabindex="0">
+B) <a href="#">Click here</a>
+C) <button>Submit</button>
+D) <span class="button">Submit</span>
+
+<!-- ANSWER: C -->
+<!-- EXPLANATION: <button> is native, focusable, keyboard-operable (Enter/Space), and announced correctly by screen readers. Div/span with role="button" requires manual keyboard handlers and focus management. Links are for navigation, not actions. -->
+
+## Question 7
+
+<!-- VISUAL: quiz-matching -->
+
+Match each POUR principle to an example:
+
+A) Perceivable → 1) Alt text for images, captions for video
+B) Operable → 2) Keyboard accessible, no keyboard traps
+C) Understandable → 3) Clear labels, consistent navigation
+D) Robust → 4) Valid HTML, works across assistive technologies
+
+<!-- ANSWER: A1,B2,C3,D4 -->
+<!-- EXPLANATION: Perceivable = present info in ways users can perceive (alt text, captions). Operable = keyboard access, no traps. Understandable = clear, consistent UI. Robust = works with assistive tech. -->
+
+## Question 8
+
+<!-- VISUAL: quiz-matching -->
+
+Match each WCAG conformance level to its description:
+
+A) Level A → 1) Minimum; essential for basic accessibility
+B) Level AA → 2) Enhanced; addresses major barriers; common target
+C) Level AAA → 3) Highest; addresses most barriers; not required for all content
+
+<!-- ANSWER: A1,B2,C3 -->
+<!-- EXPLANATION: Level A is the minimum baseline. Level AA is the common target for most sites. Level AAA is the highest and not achievable for all content types. -->

package/modules/accessibility-fundamentals/resources.md

@@ -0,0 +1,29 @@
+# Accessibility — Resources
+
+## Videos
+
+- [Web Accessibility Perspectives](https://www.w3.org/WAI/perspective-videos/) — W3C. Short videos on keyboard, captions, alt text, and more.
+- [A11y with Lindsey](https://www.youtube.com/playlist?list=PLNYkxOF6rcICWx0C9LVWWVqvHlYJyqw7g) — Chrome Developers. Practical accessibility for web developers.
+- [Screen Reader Demo](https://www.youtube.com/watch?v=dEbl5jvLKGQ) — WebAIM. How screen readers interpret pages.
+
+## Articles and Readings
+
+- [WCAG 2.1 Quick Reference](https://www.w3.org/WAI/WCAG21/quickref/) — W3C. Filterable list of success criteria and techniques.
+- [WebAIM Articles](https://webaim.org/articles/) — Screen reader testing, ARIA, contrast, and more.
+- [A List Apart: Accessibility](https://alistapart.com/topic/accessibility/) — A List Apart. Design and development for accessibility.
+- [Inclusive Design Principles](https://inclusivedesignprinciples.org/) — Seven principles for inclusive design.
+- [MDN Accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility) — MDN. Technical reference for ARIA, semantics, and testing.
+
+## Books
+
+- **A Web for Everyone** by Sarah Horton and Whitney Quesenbery — Designing accessible user experiences. Rosenfeld Media.
+- **Inclusive Design Patterns** by Heydon Pickering — Code patterns for accessible components. Smashing Magazine.
+
+## Tools
+
+- [axe DevTools](https://www.deque.com/axe/devtools/) — Browser extension for automated WCAG audits.
+- [WAVE](https://wave.webaim.org/) — Visual accessibility evaluation tool.
+- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) — Check color contrast ratios.
+- [Lighthouse](https://developers.google.com/web/tools/lighthouse) — Built into Chrome DevTools; includes accessibility audit.
+- [NVDA](https://www.nvaccess.org/) — Free screen reader for Windows.
+- [VoiceOver](https://support.apple.com/guide/voiceover/welcome/mac) — Built-in screen reader for macOS and iOS.

package/modules/accessibility-fundamentals/walkthrough.md

@@ -0,0 +1,80 @@
+# Accessibility Walkthrough — Learn by Doing
+
+## Before We Begin
+
+Accessibility isn't a checklist—it's about whether people can perceive, operate, and understand your interface. WCAG organizes this as POUR: Perceivable, Operable, Understandable, Robust.
+
+**Diagnostic question:** Think of a site you use often. What happens when you can't use a mouse? When you zoom to 200%? When images don't load? Which of those experiences have you designed for?
+
+**Checkpoint:** You can name at least one barrier someone might face and connect it to one POUR principle (perceivable, operable, understandable, or robust).
+
+---
+
+## Step 1: Check Color Contrast
+
+<!-- hint:diagram mermaid-type="flowchart" topic="POUR principles" -->
+<!-- hint:embed url="https://webaim.org/resources/contrastchecker/" -->
+
+**Embed:** https://webaim.org/resources/contrastchecker/
+
+**Task:** Pick a webpage or design. Use a contrast checker (WebAIM, DevTools, or axe) to verify that body text meets 4.5:1 (AA) and that buttons/links meet 3:1 against their backgrounds.
+
+**Question:** What would you change if the contrast failed? How does this affect users with low vision or in bright light?
+
+**Checkpoint:** The user can state the contrast ratio for at least one text/background pair and identify fixes if it fails.
+
+---
+
+## Step 2: Navigate with Keyboard Only
+
+<!-- hint:terminal -->
+
+**Task:** Unplug your mouse (or pretend). Use only Tab, Enter, Space, and arrow keys to complete a task on a site (e.g., submit a form, open a menu). Note any traps, missing focus, or confusing order.
+
+**Question:** Where did focus go that surprised you? What would improve the experience?
+
+**Checkpoint:** The user completes the task keyboard-only and identifies at least one improvement.
+
+---
+
+## Step 3: Audit a Page for Accessibility
+
+**Embed:** https://www.w3.org/WAI/WCAG21/quickref/
+
+**Task:** Run axe DevTools or Lighthouse on a page. Fix the top 3 issues (or document why you can't). Re-run the audit to confirm.
+
+**Question:** Which issues were quick to fix vs. requiring design/structural changes? What would you prioritize?
+
+**Checkpoint:** The user runs an audit, addresses issues, and can explain the impact of the fixes.
+
+---
+
+## Step 4: Use a Screen Reader
+
+**Task:** Enable VoiceOver (macOS: Cmd+F5) or NVDA (Windows). Navigate a simple form or list. Don't look at the screen—listen only.
+
+**Question:** What was announced that you didn't expect? What was missing or confusing?
+
+**Checkpoint:** The user completes a short task using a screen reader and can describe what they heard.
+
+---
+
+## Step 5: Fix Semantic HTML and ARIA
+
+**Task:** Find a page or component that uses `<div>` for buttons or non-labeled form fields. Rewrite it with semantic HTML (`<button>`, `<label>`) or add ARIA only where HTML isn't enough.
+
+**Question:** When did native HTML solve the problem without ARIA? When did you need ARIA?
+
+**Checkpoint:** The user produces accessible markup and can justify when ARIA was necessary.
+
+---
+
+## Step 6: Design an Accessible Flow
+
+**Task:** Sketch or describe an accessible checkout flow. Include: skip link, heading hierarchy, form labels, error handling, focus management for a success message, and keyboard access to all controls.
+
+**Question:** Which decisions were driven purely by accessibility, and which also improved the experience for everyone?
+
+**Checkpoint:** The user's design addresses keyboard, screen reader, contrast, and focus, and they can explain the rationale.
+
+<!-- hint:celebrate -->

package/modules/adr-writing/content.md

@@ -0,0 +1,121 @@
+# Architecture Decision Records — Documenting the Why
+
+<!-- hint:slides topic="ADRs: why decisions get lost, ADR structure and template, lifecycle, when to write vs skip" slides="4" -->
+
+## Why Decisions Get Lost
+
+Teams make dozens of architecture choices: database, framework, deployment model. Months later, nobody remembers *why* we chose PostgreSQL over MongoDB, or why we put the auth service in a separate repo. Knowledge lives in Slack, emails, and people's heads. New joiners repeat debates. Old decisions get "rediscovered" and overturned without context.
+
+**ADRs fix that** by creating a durable record of the reasoning behind important choices.
+
+## What Is an ADR?
+
+An **Architecture Decision Record** (ADR) is a short, standalone document that captures a single architectural decision, the context that drove it, and the consequences. It answers: *What did we decide? Why? What are the tradeoffs?*
+
+## Standard Format
+
+A typical ADR has five sections:
+
+| Section | Purpose |
+|---------|---------|
+| **Title** | Short, descriptive (e.g., "Use Redis for session storage") |
+| **Status** | proposed, accepted, deprecated, superseded |
+| **Context** | What forces, constraints, or options led to this decision? |
+| **Decision** | What we decided — clear and actionable |
+| **Consequences** | Positive and negative outcomes, follow-up work |
+
+Example:
+
+```markdown
+# ADR-001: Use Redis for session storage
+
+## Status
+Accepted (2024-03-15)
+
+## Context
+We need shared session state across multiple app instances.
+Options: in-memory (not shared), DB (slow), Redis (fast, shared).
+
+## Decision
+Use Redis with a 24h TTL for session storage.
+
+## Consequences
+- Positive: Fast, horizontally scalable
+- Negative: Extra infra; need Redis HA in prod
+- Follow-up: Set up Redis Sentinel
+```
+
+## When to Write One (and When Not To)
+
+**Write when:**
+- The decision affects multiple teams or services
+- Reversing it would be costly
+- Future developers will wonder "why did we do this?"
+
+**Skip when:**
+- Trivial or reversible (e.g., formatting style)
+- Temporary workaround you'll fix next sprint
+- Purely operational (restart policy) unless it has architectural impact
+
+## Lightweight vs Heavyweight
+
+- **Lightweight:** One file per decision, Markdown, in the repo. Fast to write.
+- **Heavyweight:** Formal review, templates, tooling (e.g., Log4brains). Use when governance matters.
+
+Most teams start lightweight and add structure if needed.
+
+## ADR Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> Proposed
+    Proposed --> Accepted: Approved
+    Proposed --> Rejected: Discarded
+    Accepted --> Deprecated: No longer relevant
+    Accepted --> Superseded: Replaced by new ADR
+    Deprecated --> [*]
+    Superseded --> [*]
+```
+
+| Status | Meaning |
+|--------|---------|
+| **Proposed** | Under discussion |
+| **Accepted** | Active decision |
+| **Deprecated** | No longer followed; not replaced |
+| **Superseded** | Replaced by another ADR (link it) |
+
+## Storing ADRs in the Repo
+
+Common layout:
+
+```
+docs/adr/
+  0001-use-redis-for-sessions.md
+  0002-migrate-to-graphql.md
+  0003-adopt-event-sourcing.md
+```
+
+Numbering preserves order. Some teams use dates: `2024-03-15-use-redis.md`.
+
+## Tooling
+
+- **adr-tools** — CLI to create, link, and supersede ADRs
+- **Log4brains** — Web UI to browse and search ADRs; integrates with Git
+- **template** — A simple Markdown template in the repo is often enough
+
+## Common Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| Writing too late | Write when you decide; memory fades fast |
+| Too much detail | One decision per ADR; keep it 1–2 pages |
+| Not linking to code | Add a line: "Implemented in `src/auth/session.js`" |
+| No consequences | List at least one negative; honesty helps future readers |
+| Never updating status | Deprecate or supersede when decisions change |
+
+## Key Takeaways
+
+- ADRs capture **why**, not just **what**
+- One decision per record
+- Store them in the repo; make them discoverable
+- Update status when decisions change

package/modules/adr-writing/exercises.md

@@ -0,0 +1,81 @@
+# ADR Writing Exercises
+
+## Exercise 1: Write an ADR for a Database Choice
+
+**Task:** Write a full ADR for: "We chose PostgreSQL over MongoDB for the main application database." Include Title, Status, Context (options, constraints), Decision, Consequences (positive and negative).
+
+**Validation:**
+- [ ] All five sections present
+- [ ] Context explains the options and constraints
+- [ ] Decision is clear and actionable
+- [ ] At least one negative consequence included
+
+**Hints:**
+1. Context: need ACID, relational data, team familiarity, existing tooling
+2. Consequences: PostgreSQL — strong consistency, ecosystem; negative — schema migrations, scaling writes
+3. Keep it under 1–2 pages
+
+---
+
+## Exercise 2: Supersede an Old ADR
+
+**Task:** You have ADR-003: "Use REST for all APIs (Accepted)". The team later decides to add GraphQL for mobile. Write ADR-007 that supersedes ADR-003 for the mobile API only. Include a reference to ADR-003 and explain the change.
+
+**Validation:**
+- [ ] ADR-007 has Status: Accepted
+- [ ] ADR-007 references/supersedes ADR-003
+- [ ] Context explains why the original decision no longer fully applies
+- [ ] ADR-003 would be updated to Status: Superseded by ADR-007
+
+**Hints:**
+1. "This ADR supersedes ADR-003 for mobile clients only."
+2. Update ADR-003's status to "Superseded by ADR-007"
+3. Context: mobile needs fewer round-trips, flexible querying
+
+---
+
+## Exercise 3: Lightweight vs Heavyweight
+
+**Task:** Compare lightweight ADRs (Markdown in repo, no tooling) vs heavyweight (formal review, Log4brains, templates). List 2 pros and 2 cons of each. When would you recommend a team switch from lightweight to heavyweight?
+
+**Validation:**
+- [ ] Pros and cons for both approaches
+- [ ] A clear trigger for when to add process (e.g., compliance, many teams, governance)
+
+**Hints:**
+1. Lightweight: fast, low friction, might get inconsistent
+2. Heavyweight: discoverable, consistent, more overhead
+3. Switch when: audit needs, many ADRs, cross-team coordination
+
+---
+
+## Exercise 4: Context That Helps Future Readers
+
+**Task:** You're writing an ADR for "We use feature flags for all production releases." Write a Context section that would help someone in 2 years understand *why* — include what problem it solved and what the alternative was (e.g., long-lived branches, big-bang releases).
+
+**Validation:**
+- [ ] Problem is stated clearly
+- [ ] Alternative approach(es) are mentioned
+- [ ] A new joiner could understand the rationale without asking
+
+**Hints:**
+1. Problem: risky deployments, hard to roll back, long merge cycles
+2. Alternative: branch per feature, merge at release
+3. Include constraints: team size, release frequency
+
+---
+
+## Exercise 5: Deprecate Without Replacement
+
+**Task:** Write an ADR that deprecates a previous decision: "We no longer use Redis for rate limiting; we switched to an API gateway feature." This deprecation has no replacement ADR (the new approach is configured, not a separate architecture decision). Document it appropriately.
+
+**Validation:**
+- [ ] Status: Deprecated
+- [ ] Context explains what changed and why
+- [ ] References the original ADR if one existed
+- [ ] States that the capability now lives elsewhere (gateway config)
+
+**Hints:**
+1. "This ADR deprecates ADR-005 (Use Redis for rate limiting)."
+2. Context: gateway provides rate limiting; one less moving part
+3. No superseding ADR needed — operational change

package/modules/adr-writing/module.yaml

@@ -0,0 +1,41 @@
+slug: adr-writing
+title: "Architecture Decision Records -- Documenting the Why"
+version: 1.0.0
+description: "Document architecture decisions with ADRs—format, lifecycle, and tooling."
+category: architecture
+tags: [adr, architecture, documentation, decisions, technical-writing]
+difficulty: intermediate
+
+xp:
+  read: 15
+  walkthrough: 40
+  exercise: 25
+  quiz: 20
+  quiz-perfect-bonus: 10
+
+time:
+  quick: 5
+  read: 15
+  guided: 45
+
+prerequisites: []
+related: [system-design, technical-debt]
+
+triggers:
+  - "What is an ADR?"
+  - "How do I document architecture decisions?"
+  - "Why should I write ADRs?"
+  - "What's the format for an architecture decision record?"
+
+visuals:
+  diagrams: [diagram-flow, diagram-mermaid]
+  quiz-types: [quiz-drag-order, quiz-timed-choice]
+  slides: true
+
+sources:
+  - url: "https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions"
+    label: "Michael Nygard's ADR Article"
+    type: docs
+  - url: "https://adr.github.io"
+    label: "ADR GitHub Organisation"
+    type: docs