decision-documentation

Name: decision-documentation
Author: Owl-Listener

82stars25forks

How to install decision-documentation?

owl-listener/inclusive-design-skills/decision-documentation

$npx -y skills add Owl-Listener/inclusive-design-skills --skill decision-documentation

Installs into the current project.

Summary

Document accessibility decisions and the reasoning behind them so they survive team changes, redesigns, and time. Use when making accessibility tradeoffs, choosing between approaches, or when a decision needs to be recorded for future reference. Triggers on: accessibility decisio

Files · 1

View on GitHub

SKILL.md

1	# Accessibility Decision Documentation
2
3	Record accessibility decisions so that future teams understand not
4	just what was decided, but why — preventing the cycle where good
5	decisions get reversed because nobody remembers the reasoning.
6
7	## Why This Matters
8
9	Accessibility barriers accumulate quietly through redesigns, framework
10	updates, staff turnover, and rushed deadlines. The most common cause
11	isn't malice or ignorance — it's a new team member changing something
12	without knowing why it was built that way.
13
14	Documentation is the immune system. It protects good decisions from
15	being undone by people who weren't in the room.
16
17	## Decision Record Format
18
19	For each significant accessibility decision, record:
20
21	### Title
22	A clear, searchable name.
23	"Form validation: inline errors instead of summary banner"
24
25	### Date and Author
26	When was this decided and by whom.
27
28	### Context
29	What situation prompted this decision? What were the constraints?
30	"During user testing, 3 out of 5 participants with cognitive
31	disabilities missed the error summary banner at the top of the page.
32	They corrected individual fields but didn't scroll up to see the
33	banner, so they didn't know the form hadn't submitted."
34
35	### Decision
36	What was decided, specifically.
37	"All form validation errors will appear inline directly below
38	the field that needs correction. The error summary banner is
39	removed. Errors are announced to screen readers via
40	aria-describedby on each field."
41
42	### Alternatives Considered
43	What other options were evaluated and why they were rejected.
44	"We considered keeping the summary banner alongside inline errors,
45	but testing showed it created confusion — users didn't know which
46	error indication to follow."
47
48	### Accessibility Impact
49	Who benefits from this decision and how.
50	"Benefits users with cognitive disabilities (don't need to
51	remember which fields had errors), screen reader users (errors
52	announced in context), and all users (faster error correction)."
53
54	### Risks and Tradeoffs
55	What might go wrong or what was sacrificed.
56	"If a form has many errors, the user sees them one at a time as
57	they move through fields, rather than all at once. For long forms,
58	this could mean more scrolling. We accept this tradeoff because
59	contextual errors have higher fix rates in testing."
60
61	### Evidence
62	What research, testing, or standards support this decision.
63	"User testing session 2024-03-15 (5 participants, 3 with cognitive
64	disabilities). WCAG 2.2 SC 3.3.1 (Error Identification)."
65
66	## When to Document
67
68	Document a decision when:
69	- You chose between two or more accessibility approaches
70	- You made a tradeoff that reduces accessibility in one area
71	to improve it in another
72	- You decided NOT to fix something (and why)
73	- You implemented something differently from WCAG techniques
74	for a good reason
75	- A design pattern was chosen specifically for accessibility reasons
76	- User testing revealed an accessibility insight that changed direction
77
78	## Where to Store
79
80	- In the codebase alongside the code (preferred — travels with
81	the implementation)
82	- In a shared decision log (wiki, Notion, Confluence)
83	- In design system documentation (for system-level decisions)
84	- Never only in someone's head or in a Slack thread
85
86	## Assessment Questions
87
88	1. Are accessibility decisions documented with reasoning?
89	2. Can a new team member find out why something was built a
90	specific way?
91	3. Are tradeoffs explicitly recorded?
92	4. Is documentation stored where it won't be lost?

People who liked this also viewed

6 picks

Type

decision-documentation

82stars25forks

View on GitHub

How to install decision-documentation?

owl-listener/inclusive-design-skills/decision-documentation

$npx -y skills add Owl-Listener/inclusive-design-skills --skill decision-documentation

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Accessibility Decision Documentation
2
3	Record accessibility decisions so that future teams understand not
4	just what was decided, but why — preventing the cycle where good
5	decisions get reversed because nobody remembers the reasoning.
6
7	## Why This Matters
8
9	Accessibility barriers accumulate quietly through redesigns, framework
10	updates, staff turnover, and rushed deadlines. The most common cause
11	isn't malice or ignorance — it's a new team member changing something
12	without knowing why it was built that way.
13
14	Documentation is the immune system. It protects good decisions from
15	being undone by people who weren't in the room.
16
17	## Decision Record Format
18
19	For each significant accessibility decision, record:
20
21	### Title
22	A clear, searchable name.
23	"Form validation: inline errors instead of summary banner"
24
25	### Date and Author
26	When was this decided and by whom.
27
28	### Context
29	What situation prompted this decision? What were the constraints?
30	"During user testing, 3 out of 5 participants with cognitive
31	disabilities missed the error summary banner at the top of the page.
32	They corrected individual fields but didn't scroll up to see the
33	banner, so they didn't know the form hadn't submitted."
34
35	### Decision
36	What was decided, specifically.
37	"All form validation errors will appear inline directly below
38	the field that needs correction. The error summary banner is
39	removed. Errors are announced to screen readers via
40	aria-describedby on each field."
41
42	### Alternatives Considered
43	What other options were evaluated and why they were rejected.
44	"We considered keeping the summary banner alongside inline errors,
45	but testing showed it created confusion — users didn't know which
46	error indication to follow."
47
48	### Accessibility Impact
49	Who benefits from this decision and how.
50	"Benefits users with cognitive disabilities (don't need to
51	remember which fields had errors), screen reader users (errors
52	announced in context), and all users (faster error correction)."
53
54	### Risks and Tradeoffs
55	What might go wrong or what was sacrificed.
56	"If a form has many errors, the user sees them one at a time as
57	they move through fields, rather than all at once. For long forms,
58	this could mean more scrolling. We accept this tradeoff because
59	contextual errors have higher fix rates in testing."
60
61	### Evidence
62	What research, testing, or standards support this decision.
63	"User testing session 2024-03-15 (5 participants, 3 with cognitive
64	disabilities). WCAG 2.2 SC 3.3.1 (Error Identification)."
65
66	## When to Document
67
68	Document a decision when:
69	- You chose between two or more accessibility approaches
70	- You made a tradeoff that reduces accessibility in one area
71	to improve it in another
72	- You decided NOT to fix something (and why)
73	- You implemented something differently from WCAG techniques
74	for a good reason
75	- A design pattern was chosen specifically for accessibility reasons
76	- User testing revealed an accessibility insight that changed direction
77
78	## Where to Store
79
80	- In the codebase alongside the code (preferred — travels with
81	the implementation)
82	- In a shared decision log (wiki, Notion, Confluence)
83	- In design system documentation (for system-level decisions)
84	- Never only in someone's head or in a Slack thread
85
86	## Assessment Questions
87
88	1. Are accessibility decisions documented with reasoning?
89	2. Can a new team member find out why something was built a
90	specific way?
91	3. Are tradeoffs explicitly recorded?
92	4. Is documentation stored where it won't be lost?

People who liked this also viewed

6 picks

Type