Skip to content

Commit cbe4668

Browse files
chilleniouschillenious
committed
a11y wip
1 parent def7432 commit cbe4668

8 files changed

Lines changed: 916 additions & 0 deletions

File tree

‎docs/a11y/INDEX.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# PIE A11y Docs Working Model
2+
3+
This directory is the repo-side workspace for PIE accessibility audit and remediation planning. It exists so product, accessibility, QA, and engineering can work from the same artifacts while keeping Confluence, Jira, and code responsibilities distinct.
4+
5+
## Source Of Truth
6+
7+
| Surface | Owns | Does not own |
8+
| --- | --- | --- |
9+
| Repo docs in `docs/a11y` | Element coverage, scenario IDs, automated/manual boundaries, code-adjacent audit notes | Sprint status, ownership, release commitments |
10+
| Repo PRDs in `docs/prds` | Proposed or accepted product contracts for element changes | Retroactive docs for stable behavior |
11+
| Jira | Work state, assignee, sprint/release tracking, canonical ticket discussion | Detailed model/session contracts |
12+
| Confluence | Program rollups, stakeholder-facing group status, links to repo/Jira | Canonical code-adjacent behavior |
13+
14+
## Sync Model
15+
16+
Confluence pages use managed sections generated from this repo and PM-editable sections maintained in Confluence.
17+
18+
- Repo-to-Confluence sync updates only managed summary blocks.
19+
- Confluence-to-repo sync pulls only explicit status fields into structured local metadata.
20+
- The sync tool must not overwrite freeform PM notes or stakeholder discussion.
21+
- If sync markers are missing or ambiguous, stop and resolve manually.
22+
23+
## How Engineers Use This
24+
25+
- Start with [`TRACKING.md`](./TRACKING.md) for the full element matrix.
26+
- Use [`INITIATIVE-MAP.md`](./INITIATIVE-MAP.md) to understand how repo elements map to Confluence initiative groups.
27+
- Use each `docs/a11y/<element>.md` file when adding or reviewing a11y scenarios.
28+
- Treat generated Confluence pages as a publishing surface, not as the canonical source for scenario definitions.
29+
- When implementation changes require synced React packages, follow the upstream sync policy instead of editing generated outputs directly.
30+
31+
## How Product Managers Use This
32+
33+
- Work primarily in Confluence and Jira for initiative status, sequencing, scope, and acceptance discussions.
34+
- Ask an agent to pull relevant repo context before drafting or updating tickets.
35+
- Use [`_audit-template.md`](./_audit-template.md) for consistent element audit entries.
36+
- For product changes that alter element behavior, ask the agent to draft or update a PRD under `docs/prds/<slug>/PRD.md`.
37+
- Link Jira tickets to the relevant repo docs and Confluence group pages.
38+
39+
## Common Agent Prompts
40+
41+
```text
42+
Read docs/a11y/INITIATIVE-MAP.md, docs/a11y/<element>.md, and Jira PIE-123.
43+
Draft an audit update with WCAG gaps, severity, effort, sequencing, validation status, and open questions.
44+
Do not edit code.
45+
```
46+
47+
```text
48+
Use docs/prds/_template.md and docs/prds/README.md.
49+
Draft a Proposal PRD for <feature> linked to PIE-123.
50+
Keep it short and include accessibility requirements and open questions.
51+
Do not implement anything.
52+
```
53+
54+
## Sync Commands
55+
56+
- `bun run a11y:confluence:check` reports missing/stale Confluence mappings.
57+
- `bun run a11y:confluence:bootstrap -- --apply` creates missing Confluence pages and records IDs.
58+
- `bun run a11y:confluence:push -- --apply` publishes repo-managed summaries.
59+
- `bun run a11y:confluence:pull-status -- --apply` pulls PM-editable status metadata.
60+
61+
All write commands default to dry-run unless `--apply` is passed.

‎docs/a11y/INITIATIVE-MAP.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# PIE A11y Initiative Map
2+
3+
This map connects the repo's element-level a11y docs to the Confluence initiative structure for PIE Elements Universal Access (WCAG).
4+
5+
## Initiative Groups
6+
7+
| Initiative group | Confluence intent | Repo docs | Primary scenario focus |
8+
| --- | --- | --- | --- |
9+
| Group 1A | MC/MS, EBSR, Passages | [`multiple-choice`](./multiple-choice.md), [`ebsr`](./ebsr.md), [`passage`](./passage.md) | Choice semantics, two-part grouping, passage reading structure |
10+
| Group 1B | Inline Dropdown, ECR, CQT | [`inline-dropdown`](./inline-dropdown.md), [`explicit-constructed-response`](./explicit-constructed-response.md), [`mc-populated-blank`](./mc-populated-blank.md) | Cloze controls, embedded response fields, CQT populated blank variants |
11+
| Group 2 | Match List, Drag in the Blank, Categorize, Placement Ordering, Image Cloze Association, Hot Spot | [`match-list`](./match-list.md), [`drag-in-the-blank`](./drag-in-the-blank.md), [`categorize`](./categorize.md), [`placement-ordering`](./placement-ordering.md), [`image-cloze-association`](./image-cloze-association.md), [`hotspot`](./hotspot.md) | Spatial interaction, drag alternatives, image/target alternatives |
12+
| Group 1C | Math Editor, Math Inline | [`math-inline`](./math-inline.md), [`math-templated`](./math-templated.md); shared surfaces `@pie-lib/math-input`, `@pie-lib/math-toolbar`, `@pie-lib/math-input-svelte` | Math editor naming, keypad workflow, rendered math alternatives |
13+
| Group 1D | CR / Extended Text Entry | [`extended-text-entry`](./extended-text-entry.md); shared surface `@pie-lib/editable-html-tip-tap` | Rich text editor, supplemental character panels, feedback and annotations |
14+
| Group 3 | Graphing, Number Line, Match Table, Select Text, Charting, Drawing Response, Math-Templated, Graphing Solution Set, Fraction Model | [`graphing`](./graphing.md), [`number-line`](./number-line.md), [`matrix`](./matrix.md), [`select-text`](./select-text.md), [`charting`](./charting.md), [`drawing-response`](./drawing-response.md), [`math-templated`](./math-templated.md), [`graphing-solution-set`](./graphing-solution-set.md), [`fraction-model`](./fraction-model.md) | Graph/canvas alternatives, table relationships, visual data and pointer-heavy workflows |
15+
| Repo tracked outside current initiative grouping | Elements covered by the repo that are not clearly named in the initiative | [`likert`](./likert.md), [`match`](./match.md), [`rubric`](./rubric.md), [`complex-rubric`](./complex-rubric.md), [`multi-trait-rubric`](./multi-trait-rubric.md), [`simple-cloze`](./simple-cloze.md), [`venn-classification`](./venn-classification.md) | Preserve visibility so future initiative scope does not miss them |
16+
17+
## Shared Surfaces
18+
19+
Some initiative work is not owned by a single element package.
20+
21+
| Shared surface | Used by | Tracking note |
22+
| --- | --- | --- |
23+
| `@pie-lib/math-input` | `math-inline`, `math-templated`, rich text math entry | Track under Group 1C because editor accessibility affects multiple elements. |
24+
| `@pie-lib/math-toolbar` | Math entry experiences | Track with Math Editor / Math Inline for keypad and toolbar workflow. |
25+
| `@pie-lib/math-input-svelte` | Svelte math field surfaces | Track with Group 1C when Svelte delivery/authoring uses the shared field. |
26+
| `@pie-lib/editable-html-tip-tap` | Extended text entry and authoring/editor flows | Track under Group 1D for baseline rich text editor and supplemental panels. |
27+
28+
## Reporting Expectations
29+
30+
- Scenario IDs and automated checks come from `apps/element-demo/src/lib/a11y/scenarios/catalog.ts`.
31+
- Findings and suggested Jira titles come from the Axe scenario report.
32+
- Confluence group pages summarize status and sequencing.
33+
- Jira tickets own assignment, sprint, and release state.

‎docs/a11y/_audit-template.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# <Element Or Surface> A11y Audit
2+
3+
Initiative group: Group 1A / Group 1B / Group 2 / Group 1C / Group 1D / Group 3 / Outside current initiative grouping
4+
5+
Related Jira: TBD
6+
7+
Confluence: TBD
8+
9+
Status: Not scoped / Scoped / In remediation / In validation / Accepted
10+
11+
Priority: P1 / P2 / P3 / TBD
12+
13+
Effort: XS / S / M / L / XL / TBD
14+
15+
## Scope
16+
17+
Describe the element or shared surface and the user-facing workflows included in this audit.
18+
19+
## Automated Coverage
20+
21+
- Scenario IDs:
22+
- Axe coverage:
23+
- Custom checks:
24+
- Current report status:
25+
26+
## Open WCAG Gaps
27+
28+
| Gap | WCAG 2.2 criterion | Severity | Evidence | Proposed remediation |
29+
| --- | --- | --- | --- | --- |
30+
| TBD | TBD | TBD | TBD | TBD |
31+
32+
## Manual Validation
33+
34+
- Keyboard workflow:
35+
- Screen reader workflow:
36+
- Color / contrast / non-text meaning:
37+
- Platform validation target:
38+
39+
## Acceptance Notes
40+
41+
List concise acceptance criteria or link to a PRD if the work changes product behavior.
42+
43+
## Open Questions
44+
45+
- [ ] TBD

‎docs/a11y/confluence-map.json‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
{
2+
"schemaVersion": 1,
3+
"cloudId": "6b6fffef-32f8-44d1-82ea-ad3773ab29c8",
4+
"siteUrl": "https://illuminate.atlassian.net",
5+
"spaceId": "18331566138",
6+
"rootPageId": "19292586001",
7+
"rootTitle": "PIE Elements Universal Access (WCAG)",
8+
"pages": [
9+
{
10+
"slug": "working-model",
11+
"title": "Repo / Working Model",
12+
"localPath": "docs/a11y/INDEX.md",
13+
"pageId": "19332301229",
14+
"parentSlug": null,
15+
"sync": "repo-managed-with-pm-status"
16+
},
17+
{
18+
"slug": "initiative-map",
19+
"title": "A11y Initiative Map",
20+
"localPath": "docs/a11y/INITIATIVE-MAP.md",
21+
"pageId": "19331220010",
22+
"parentSlug": null,
23+
"sync": "repo-managed-with-pm-status"
24+
},
25+
{
26+
"slug": "group-1a",
27+
"title": "Group 1A: MC/MS, EBSR, Passages",
28+
"localPath": "docs/a11y/TRACKING.md",
29+
"pageId": "19332104616",
30+
"parentSlug": null,
31+
"sync": "generated-group-summary"
32+
},
33+
{
34+
"slug": "group-1b",
35+
"title": "Group 1B: Inline Dropdown, ECR, CQT",
36+
"localPath": "docs/a11y/TRACKING.md",
37+
"pageId": "19329090333",
38+
"parentSlug": null,
39+
"sync": "generated-group-summary"
40+
},
41+
{
42+
"slug": "group-2",
43+
"title": "Group 2: Drag / Spatial / Image",
44+
"localPath": "docs/a11y/TRACKING.md",
45+
"pageId": "19329090353",
46+
"parentSlug": null,
47+
"sync": "generated-group-summary"
48+
},
49+
{
50+
"slug": "group-1c",
51+
"title": "Group 1C: Math Editor / Math Inline",
52+
"localPath": "docs/a11y/TRACKING.md",
53+
"pageId": "19333710011",
54+
"parentSlug": null,
55+
"sync": "generated-group-summary"
56+
},
57+
{
58+
"slug": "group-1d",
59+
"title": "Group 1D: CR / Extended Text Entry",
60+
"localPath": "docs/a11y/TRACKING.md",
61+
"pageId": "19333054742",
62+
"parentSlug": null,
63+
"sync": "generated-group-summary"
64+
},
65+
{
66+
"slug": "group-3",
67+
"title": "Group 3: Math / Graphing / Drawing",
68+
"localPath": "docs/a11y/TRACKING.md",
69+
"pageId": "19332759944",
70+
"parentSlug": null,
71+
"sync": "generated-group-summary"
72+
},
73+
{
74+
"slug": "prd-index",
75+
"title": "PRD Index",
76+
"localPath": "docs/prds",
77+
"pageId": "19329221447",
78+
"parentSlug": null,
79+
"sync": "generated-prd-index"
80+
}
81+
]
82+
}

‎docs/prds/PM_GUIDE.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# PM Guide: PRDs, Jira, And Confluence
2+
3+
This repo can be used directly from Cursor or Claude Code for product drafting, but it should not replace Jira or Confluence.
4+
5+
## What To Edit Where
6+
7+
| Work | Primary location | Notes |
8+
| --- | --- | --- |
9+
| Product contract for a new element or substantial behavior change | `docs/prds/<slug>/PRD.md` | Start from `_template.md`; keep it short and mark `Status: Proposal` until reviewed. |
10+
| A11y audit, coverage, and remediation scope | `docs/a11y` | Use `docs/a11y/_audit-template.md` and link to Jira/Confluence. |
11+
| Ticket status, owner, sprint, release | Jira | Ask the agent to update Jira only when you explicitly want it to write. |
12+
| Stakeholder rollup and initiative status | Confluence | Repo-managed sections are synced; PM status sections are edited in Confluence. |
13+
14+
## Drafting A PRD With An Agent
15+
16+
Use a prompt like:
17+
18+
```text
19+
Read docs/prds/README.md, docs/prds/_template.md, Jira PIE-123, and the relevant docs/a11y files.
20+
Draft a Proposal PRD under docs/prds/<slug>/PRD.md.
21+
Keep it to one screen, include accessibility requirements, and list open questions.
22+
Do not implement code.
23+
```
24+
25+
## Linking Jira
26+
27+
- Add a short `Related Jira` line near the top of the PRD or a11y audit doc.
28+
- Add the repo path to the Jira issue description or as a Jira comment.
29+
- Do not create follow-up tickets unless a human explicitly asks for them.
30+
31+
## Working With Confluence
32+
33+
- Use Confluence pages for the PM/program view.
34+
- Use `docs/a11y/INDEX.md` for the source-of-truth rules.
35+
- Use the Confluence sync commands to publish repo-managed summaries and pull PM status blocks.
36+
- If a Confluence page and repo PRD disagree, treat the repo PRD as canonical for product contract details and update Confluence as a summary.
37+
38+
## Review Expectations
39+
40+
Before moving a PRD from `Proposal` to `Accepted`:
41+
42+
- Product agrees the goals and non-goals are right.
43+
- Engineering agrees the proposed model/session surface is implementable.
44+
- Accessibility concerns are covered or explicitly tracked as open questions.
45+
- Jira links point to the implementation or remediation work.

‎docs/prds/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,3 +141,5 @@ A few practical rules to keep PRDs useful with LLMs in the loop:
141141
- **Don't accept LLM-generated padding.** If a PRD draft has long generic sections about "Performance" or "Security" that say nothing element-specific, delete them. A short PRD that contains only true claims beats a long PRD that pads with truisms.
142142

143143
See [`venn-classification/PRD.md`](./venn-classification/PRD.md) for an example PRD that anchors the expected length and tone.
144+
145+
For a product-manager-oriented workflow that connects PRDs to Jira and Confluence, see [`PM_GUIDE.md`](./PM_GUIDE.md).

‎package.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,11 @@
3333
"test:a11y": "bun run --cwd apps/element-demo test:a11y",
3434
"test:a11y:inventory": "bun run --cwd apps/element-demo test:a11y:inventory",
3535
"test:a11y:headed": "bun run --cwd apps/element-demo test:a11y:headed",
36+
"a11y:confluence:check": "node scripts/a11y-confluence-sync.mjs check",
37+
"a11y:confluence:dry-run": "node scripts/a11y-confluence-sync.mjs dry-run",
38+
"a11y:confluence:bootstrap": "node scripts/a11y-confluence-sync.mjs bootstrap",
39+
"a11y:confluence:push": "node scripts/a11y-confluence-sync.mjs push",
40+
"a11y:confluence:pull-status": "node scripts/a11y-confluence-sync.mjs pull-status",
3641
"test:iife": "node scripts/run-iife-suite.mjs",
3742
"test:iife:bundle": "bun run --cwd apps/element-demo test:iife:bundle",
3843
"test:iife:e2e": "bun run --cwd apps/element-demo test:e2e:iife:suite",

0 commit comments

Comments
 (0)