diff --git a/ACCESSIBILITY-EXECUTIVE-EMAIL-DRAFT.md b/ACCESSIBILITY-EXECUTIVE-EMAIL-DRAFT.md new file mode 100644 index 0000000000..376e477e26 --- /dev/null +++ b/ACCESSIBILITY-EXECUTIVE-EMAIL-DRAFT.md @@ -0,0 +1,52 @@ +# Executive Email Draft - Accessibility Program Setup Complete + +## Subject Line Options + +1. az_quickstart accessibility program is organized and ready for review +2. Accessibility planning and GitHub dashboard are ready for Friday discussion +3. WCAG 2.2 AA planning structure is now in place for az_quickstart + +## Email Draft + +Hello, + +I completed the accessibility planning and GitHub organization work for the az_quickstart WCAG 2.2 AA effort today. + +The main result is that the work is now organized as a structured program rather than a flat list of defects. We now have a live GitHub board, a single umbrella issue, phased parent issues, and a linked set of delivery issues that the team can use for Friday’s planning discussion. + +Key artifacts: + +- Project board: https://github.com/orgs/az-digital/projects/285 +- Umbrella issue: https://github.com/az-digital/az_quickstart/issues/5533 +- Review plan in GitHub: https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-REVIEW-PLAN.md +- GitHub execution plan in GitHub: https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-GITHUB-PROJECT-PLAN.md + +The work is organized into five phases: + +1. Accessibility guardrails and verification setup +2. Global user experience blockers +3. High-risk interactive components +4. Content and template semantics +5. Verification and release readiness + +This gives the team a clearer way to prioritize the work by user impact and release risk. + +The recommended approach is intentionally well targeted. Rather than spreading effort evenly across every finding, the first wave should focus on changes that create immediate and noticeable improvement in common user journeys. + +For Friday, the most important remaining decisions are: + +1. What verification standard should apply before implementation begins. +2. Which issues are patch-safe versus minor-release work. +3. Which ambiguous items should remain in the discussion queue until the team agrees on scope. + +No implementation work has started as part of this setup. The purpose of today’s work was to create the planning structure so the team can have a more disciplined discussion before coding begins. + +Because this package is broader than a normal issue review, it may make sense to hold a dedicated meeting focused on reviewing the planning materials and confirming the initial direction. + +The project dashboard itself is a standing program asset and is not tied to a feature or bug branch. The dedicated planning branch only stores the supporting documents for review. + +This message is ready to send as written. It uses live GitHub links for the board, umbrella issue, and supporting documents. + +Thanks, + +Jeff \ No newline at end of file diff --git a/ACCESSIBILITY-FINAL-REVIEW-EMAIL.md b/ACCESSIBILITY-FINAL-REVIEW-EMAIL.md new file mode 100644 index 0000000000..ac5309448e --- /dev/null +++ b/ACCESSIBILITY-FINAL-REVIEW-EMAIL.md @@ -0,0 +1,90 @@ +# Final Review Email - Accessibility Program Package + +## Subject Line Options + +1. az_quickstart accessibility review package and Friday planning materials +2. Accessibility program review materials are ready for Friday +3. WCAG 2.2 AA planning package for az_quickstart is ready for review + +## Send-Ready Email + +Hello everyone, + +I completed the accessibility planning and GitHub organization work for the az_quickstart WCAG 2.2 AA effort today, and the full review package is now ready for everyone to review before Friday. + +## Executive Summary + +The accessibility work is now organized as a structured program rather than a flat list of findings. We have: + +1. A completed source-level accessibility review. +2. A phased remediation and verification plan. +3. A live GitHub project board. +4. An umbrella issue and linked phase and delivery issues. +5. A narrowed Friday decision queue. +6. Meeting materials and supporting documents for discussion. + +No implementation work has started. The purpose of today’s work was to make sure the team can review the findings, discuss the open decisions, and align on scope and sequencing before any coding begins. + +## Primary Review Links + +- [Project board](https://github.com/orgs/az-digital/projects/285) +- [Umbrella issue](https://github.com/az-digital/az_quickstart/issues/5533) +- [Consolidated send-out brief](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-SENDOUT-BRIEF.md) +- [One-page Friday handout](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-FRIDAY-HANDOUT.md) + +## Detailed Planning Documents + +- [Accessibility review plan](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-REVIEW-PLAN.md) +- [GitHub execution plan](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-GITHUB-PROJECT-PLAN.md) +- [Phase 0.1 verification proposal](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-P0.1-VERIFICATION-PROPOSAL.md) +- [Phase 0.2 scanner workflow plan](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md) +- [Manual verification playbook](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-MANUAL-VERIFICATION-PLAYBOOK.md) +- [Scanner triage guide](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-SCANNER-TRIAGE-GUIDE.md) +- [Release sign-off checklist](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md) +- [Representative URL inventory and environment map](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md) + +## Friday Meeting Materials + +- [Meeting agenda](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-FRIDAY-MEETING-AGENDA.md) +- [Facilitator script](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-FRIDAY-FACILITATOR-SCRIPT.md) +- [Presentation talk track](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-LIVE-PRESENTATION-TALK-TRACK.md) +- [Project views handoff](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-PROJECT-VIEWS-HANDOFF.md) +- [Post-meeting notes template](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-POST-MEETING-NOTES-TEMPLATE.md) + +## Friday Decision Queue + +These are the issues that currently require explicit team decisions before implementation should begin: + +1. [#5533 - Umbrella program issue](https://github.com/az-digital/az_quickstart/issues/5533) +2. [#5541 - Verification policy and representative page matrix](https://github.com/az-digital/az_quickstart/issues/5541) +3. [#5550 - Marketing Cloud export route decision](https://github.com/az-digital/az_quickstart/issues/5550) +4. [#5544 - Gallery carousel release direction](https://github.com/az-digital/az_quickstart/issues/5544) +5. [#5545 - Date picker release direction](https://github.com/az-digital/az_quickstart/issues/5545) + +## Recommended First-Wave Candidates + +If the Friday decisions are confirmed, these are the strongest first-wave candidates: + +1. [#5541](https://github.com/az-digital/az_quickstart/issues/5541) +2. [#5539](https://github.com/az-digital/az_quickstart/issues/5539) +3. [#5538](https://github.com/az-digital/az_quickstart/issues/5538) +4. [#5540](https://github.com/az-digital/az_quickstart/issues/5540) +5. [#5537](https://github.com/az-digital/az_quickstart/issues/5537) +6. [#5514](https://github.com/az-digital/az_quickstart/issues/5514) + +## What I Recommend Everyone Review Before Friday + +If time is limited, review these in order: + +1. The [one-page Friday handout](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-FRIDAY-HANDOUT.md) +2. The [project board](https://github.com/orgs/az-digital/projects/285) +3. The [umbrella issue](https://github.com/az-digital/az_quickstart/issues/5533) +4. The [review plan](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-REVIEW-PLAN.md) + +Thanks, + +Jeff + +## Notes + +This email is ready to send as written. It uses live GitHub links for the board and issues, while the supporting documents are published from the dedicated planning branch so recipients can review everything in the browser. \ No newline at end of file diff --git a/ACCESSIBILITY-FRIDAY-FACILITATOR-SCRIPT.md b/ACCESSIBILITY-FRIDAY-FACILITATOR-SCRIPT.md new file mode 100644 index 0000000000..79be7e6bbb --- /dev/null +++ b/ACCESSIBILITY-FRIDAY-FACILITATOR-SCRIPT.md @@ -0,0 +1,199 @@ +# Friday Facilitator Script - az_quickstart Accessibility Program + +## Purpose + +This script is a facilitator aid for the Friday accessibility planning meeting. It is designed to keep the conversation focused on decisions, sequencing, and ownership rather than drifting into solution design. + +Use this alongside: + +- [ACCESSIBILITY-FRIDAY-MEETING-AGENDA.md](ACCESSIBILITY-FRIDAY-MEETING-AGENDA.md) +- [ACCESSIBILITY-P0.1-VERIFICATION-PROPOSAL.md](ACCESSIBILITY-P0.1-VERIFICATION-PROPOSAL.md) +- [ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md](ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md) +- [ACCESSIBILITY-MANUAL-VERIFICATION-PLAYBOOK.md](ACCESSIBILITY-MANUAL-VERIFICATION-PLAYBOOK.md) +- [ACCESSIBILITY-SCANNER-TRIAGE-GUIDE.md](ACCESSIBILITY-SCANNER-TRIAGE-GUIDE.md) +- [ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md](ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md) +- [ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md](ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md) +- [GitHub project board](https://github.com/orgs/az-digital/projects/285) +- [Umbrella program issue #5533](https://github.com/az-digital/az_quickstart/issues/5533) + +These Phase 0 support documents are preliminary working drafts. The facilitator should frame them as decision aids for [#5532](https://github.com/az-digital/az_quickstart/issues/5532), [#5541](https://github.com/az-digital/az_quickstart/issues/5541), and [#5539](https://github.com/az-digital/az_quickstart/issues/5539), not as finalized policy. + +## Facilitator Goal + +At the end of the meeting, the team should be aligned on: + +1. What the program includes. +2. What decisions are still open. +3. Which work should be considered first. +4. What must be true before implementation begins. + +## Opening Script + +Suggested opening: + +"The purpose of today’s meeting is to review the accessibility program structure, confirm the decisions that affect scope and release planning, and agree on the first wave of work. We are not starting implementation today. We are making sure the work is organized correctly before implementation begins." + +Suggested framing note for the facilitator: + +"The recommended approach is intentionally targeted. We should start with the changes that create immediate, noticeable improvement for users on common journeys, then use the broader program structure to sequence the deeper work responsibly." + +## Section-by-Section Talking Points + +### 1. Program Overview + +Open with: + +- [Project board](https://github.com/orgs/az-digital/projects/285) +- [Umbrella issue #5533](https://github.com/az-digital/az_quickstart/issues/5533) + +Talking points: + +1. The work is now structured as a program, not a flat accessibility backlog. +2. The issues are grouped into phases so the team can prioritize by user impact and delivery risk. +3. The project board contains the umbrella issue, the phase parents, and the child issues needed for planning. + +Prompt: + +"Does the program structure itself feel right before we discuss individual items?" + +Likely decision to capture: + +- Confirm or adjust the five-phase structure. + +### 2. Prioritization Lens + +Talking points: + +1. The current backlog is written to prioritize the user experience, not just technical cleanup. +2. Global barriers and high-risk interaction failures should generally come before lower-visibility semantic cleanup. +3. The board metadata now distinguishes likely patch work, minor work, and items that still need a release decision. + +Prompt: + +"Do we agree that the default order should be global blockers first, then high-risk components, then semantic and governance cleanup?" + +Likely decision to capture: + +- Confirm the prioritization model or note any institutional override. + +### 3. Phase Review + +Walk the team through these parent issues in order: + +1. [#5532](https://github.com/az-digital/az_quickstart/issues/5532) +2. [#5535](https://github.com/az-digital/az_quickstart/issues/5535) +3. [#5531](https://github.com/az-digital/az_quickstart/issues/5531) +4. [#5536](https://github.com/az-digital/az_quickstart/issues/5536) +5. [#5534](https://github.com/az-digital/az_quickstart/issues/5534) + +For each phase, ask: + +1. "Is this phase scoped correctly?" +2. "Is anything missing?" +3. "Is anything here actually a later or earlier phase item?" +4. "Do the current release target assumptions feel right?" + +Likely decisions to capture: + +- Scope confirmation by phase +- Phase shifts if any issues are misplaced + +### 4. Friday Decision Queue + +Use these issues as the explicit decision queue: + +- [#5533](https://github.com/az-digital/az_quickstart/issues/5533) +- [#5541](https://github.com/az-digital/az_quickstart/issues/5541) +- [#5550](https://github.com/az-digital/az_quickstart/issues/5550) +- [#5544](https://github.com/az-digital/az_quickstart/issues/5544) +- [#5545](https://github.com/az-digital/az_quickstart/issues/5545) + +These issues now carry the `needs discussion` label and are intended to represent the narrowest useful Friday decision queue. + +Talking points: + +1. [#5541](https://github.com/az-digital/az_quickstart/issues/5541) determines the verification standard for everything else. +2. [#5539](https://github.com/az-digital/az_quickstart/issues/5539) is now supported by a preliminary scanner workflow plan, manual verification playbook, triage guide, sign-off checklist, and URL inventory. +2. [#5550](https://github.com/az-digital/az_quickstart/issues/5550) is an architectural and product-boundary decision. +3. [#5544](https://github.com/az-digital/az_quickstart/issues/5544) and [#5545](https://github.com/az-digital/az_quickstart/issues/5545) are currently set to `Undecided` because they are the most likely to shift between a narrower patch approach and a fuller minor-release approach. + +Additional framing note: + +"The new Phase 0 documents should be reviewed as working drafts that support the board's Phase 0 placemarkers. They are here to accelerate decisions, not to bypass them." + +Recommended starting positions to bring into the room: + +1. Treat Marketing Cloud export routes as browser-facing until the team explicitly confirms fragment-only usage. +2. Approve a representative page matrix that is intentionally narrow, high-value, and built around common journeys plus the highest-risk widgets. +3. Use the representative page matrix as the release gate for both patch and minor releases rather than waiting for full-site coverage. +4. Keep gallery carousel and date-picker structural rewrites in minor-release territory unless the team identifies a narrower patch-safe path. + +Prompts: + +1. "Which of these truly need a team decision before work begins?" +2. "Which of these are clearly minor-release work, and which might still be narrowed into patch-safe work?" +3. "Which open questions require discovery versus a policy decision?" +4. "Are the preliminary Phase 0 working drafts directionally correct enough to use as the working basis for implementation planning on #5541 and #5539?" + +Likely decisions to capture: + +- Final Friday decision list +- Patch versus minor direction for the ambiguous items +- Any spikes or follow-up analysis needed + +### 5. First Implementation Wave + +Recommended candidates to confirm: + +- [#5541](https://github.com/az-digital/az_quickstart/issues/5541) +- [#5539](https://github.com/az-digital/az_quickstart/issues/5539) +- [#5538](https://github.com/az-digital/az_quickstart/issues/5538) +- [#5540](https://github.com/az-digital/az_quickstart/issues/5540) +- [#5537](https://github.com/az-digital/az_quickstart/issues/5537) +- [#5514](https://github.com/az-digital/az_quickstart/issues/5514) + +Prompt: + +"If we had to define the first implementation wave today, which of these are truly ready once the decision items are settled?" + +Facilitator reminder: + +Keep the discussion anchored on immediate impact. The first wave should improve navigation, naming, announcements, and reachability in places users will notice right away. + +Likely decision to capture: + +- Confirm the first wave or identify dependencies that still block it. + +### 6. Ownership and Next Steps + +Prompts: + +1. "Who owns the Phase 0 policy and verification decisions?" +2. "Who owns keeping the board metadata current after Friday?" +3. "Which issues need updates immediately after the meeting?" +4. "What is the explicit signal that allows implementation planning to begin?" +5. "Who owns converting the preliminary Phase 0 drafts into approved working documents after the meeting?" + +Likely decisions to capture: + +- Owners +- Immediate follow-up edits +- Next planning checkpoint + +## Redirect Lines for Common Meeting Drift + +If the conversation becomes too implementation-specific: + +"Let’s capture that as an implementation note, but keep this meeting focused on whether the work belongs in scope, what phase it belongs in, and whether it is patch-safe or minor-release work." + +If the conversation becomes too broad: + +"Let’s bring it back to the current decision queue and make sure we leave with clear release and verification decisions." + +If the conversation gets stuck on one issue: + +"Let’s decide whether this needs a policy decision, a spike, or a delivery issue update, and then keep moving." + +## Suggested Closing Script + +"We now have a structured program, a defined decision queue, and a clearer sense of what belongs in the first wave. The next step is to reflect today’s decisions in the issues and board metadata, and only then move into implementation planning." \ No newline at end of file diff --git a/ACCESSIBILITY-FRIDAY-HANDOUT.md b/ACCESSIBILITY-FRIDAY-HANDOUT.md new file mode 100644 index 0000000000..1e03ef56f6 --- /dev/null +++ b/ACCESSIBILITY-FRIDAY-HANDOUT.md @@ -0,0 +1,95 @@ +# Friday Handout - Accessibility Program Snapshot + +## Purpose + +This is the one-page briefing version of the az_quickstart accessibility program for Friday’s discussion. + +## Start Here + +- [Project board](https://github.com/orgs/az-digital/projects/285) +- [Umbrella issue](https://github.com/az-digital/az_quickstart/issues/5533) + +## Executive Summary + +The accessibility work is now organized as a structured program with a completed review, a phased plan, a live GitHub board, and a narrow decision queue for Friday. + +No implementation work has started. Friday is a planning and prioritization meeting. + +## What Exists Now + +1. Accessibility review plan: + [ACCESSIBILITY-REVIEW-PLAN.md](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-REVIEW-PLAN.md) +2. GitHub execution plan: + [ACCESSIBILITY-GITHUB-PROJECT-PLAN.md](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-GITHUB-PROJECT-PLAN.md) +3. Project board: + [Accessibility Program - az_quickstart](https://github.com/orgs/az-digital/projects/285) + +## Preliminary Phase 0 Working Drafts + +These documents now support the Phase 0 work on the board and should be treated as preliminary working drafts for Friday discussion, not finalized operating policy. + +Phase 0 anchor issues: + +1. [#5532 - Phase 0 parent issue](https://github.com/az-digital/az_quickstart/issues/5532) +2. [#5541 - Verification policy and representative page matrix](https://github.com/az-digital/az_quickstart/issues/5541) +3. [#5539 - Accessibility regression gate task](https://github.com/az-digital/az_quickstart/issues/5539) + +Operational drafts: + +1. [Phase 0.1 verification proposal](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-P0.1-VERIFICATION-PROPOSAL.md) +2. [Phase 0.2 scanner workflow plan](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md) +3. [Manual verification playbook](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-MANUAL-VERIFICATION-PLAYBOOK.md) +4. [Scanner triage guide](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-SCANNER-TRIAGE-GUIDE.md) +5. [Release sign-off checklist](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md) +6. [Representative URL inventory and environment map](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md) + +## Friday Decision Queue + +These issues still need explicit team direction: + +1. [#5533 - Umbrella program issue](https://github.com/az-digital/az_quickstart/issues/5533) +2. [#5541 - Verification policy and representative page matrix](https://github.com/az-digital/az_quickstart/issues/5541) +3. [#5550 - Marketing Cloud export route decision](https://github.com/az-digital/az_quickstart/issues/5550) +4. [#5544 - Gallery carousel release direction](https://github.com/az-digital/az_quickstart/issues/5544) +5. [#5545 - Date picker release direction](https://github.com/az-digital/az_quickstart/issues/5545) + +## Recommended Immediate-Impact First Wave + +If the Friday decisions are confirmed, the strongest first-wave candidates are the ones most likely to create immediate, noticeable improvement in common user journeys: + +1. [#5541](https://github.com/az-digital/az_quickstart/issues/5541) +2. [#5539](https://github.com/az-digital/az_quickstart/issues/5539) +3. [#5538](https://github.com/az-digital/az_quickstart/issues/5538) +4. [#5540](https://github.com/az-digital/az_quickstart/issues/5540) +5. [#5537](https://github.com/az-digital/az_quickstart/issues/5537) +6. [#5514](https://github.com/az-digital/az_quickstart/issues/5514) + +## What Friday Needs To Decide + +1. What verification standard should apply before implementation begins. +2. Which issues are patch-safe versus minor-release work. +3. Which undecided items need additional discovery before implementation planning. +4. Whether the recommended first wave should stand as currently proposed. +5. Whether the preliminary Phase 0 working drafts for [#5541](https://github.com/az-digital/az_quickstart/issues/5541) and [#5539](https://github.com/az-digital/az_quickstart/issues/5539) are directionally correct enough to use as the working basis for implementation planning. + +## Recommended Starting Positions + +These are recommended starting positions for discussion, not pre-made decisions: + +1. Treat Marketing Cloud export routes as browser-facing until fragment-only use is explicitly confirmed. +2. Use a targeted representative page matrix built around common journeys and the highest-risk widgets. +3. Block new serious or critical regressions on those representative pages for both patch and minor releases. +4. Keep the first implementation wave focused on user-facing improvements that are meaningful and noticeable right away. + +## Supporting Materials + +- [Meeting agenda](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-FRIDAY-MEETING-AGENDA.md) +- [Facilitator script](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-FRIDAY-FACILITATOR-SCRIPT.md) +- [Talk track](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-LIVE-PRESENTATION-TALK-TRACK.md) +- [Phase 0.1 verification proposal](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-P0.1-VERIFICATION-PROPOSAL.md) +- [Phase 0.2 scanner workflow plan](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md) +- [Manual verification playbook](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-MANUAL-VERIFICATION-PLAYBOOK.md) +- [Scanner triage guide](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-SCANNER-TRIAGE-GUIDE.md) +- [Release sign-off checklist](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md) +- [Representative URL inventory and environment map](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md) +- [Consolidated send-out brief](https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-SENDOUT-BRIEF.md) \ No newline at end of file diff --git a/ACCESSIBILITY-FRIDAY-MEETING-AGENDA.md b/ACCESSIBILITY-FRIDAY-MEETING-AGENDA.md new file mode 100644 index 0000000000..6711c5dc75 --- /dev/null +++ b/ACCESSIBILITY-FRIDAY-MEETING-AGENDA.md @@ -0,0 +1,159 @@ +# Friday Meeting Agenda - az_quickstart Accessibility Program + +## Purpose + +This meeting is intended to align the team on the accessibility program structure, confirm the release and verification decisions that affect scope, and agree on what work should move forward first. + +This is a planning and prioritization meeting. It is not an implementation kickoff. + +## Pre-Read + +Review these materials before the meeting if possible: + +- [ACCESSIBILITY-REVIEW-PLAN.md](ACCESSIBILITY-REVIEW-PLAN.md) +- [ACCESSIBILITY-GITHUB-PROJECT-PLAN.md](ACCESSIBILITY-GITHUB-PROJECT-PLAN.md) +- [ACCESSIBILITY-P0.1-VERIFICATION-PROPOSAL.md](ACCESSIBILITY-P0.1-VERIFICATION-PROPOSAL.md) +- [ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md](ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md) +- [ACCESSIBILITY-MANUAL-VERIFICATION-PLAYBOOK.md](ACCESSIBILITY-MANUAL-VERIFICATION-PLAYBOOK.md) +- [ACCESSIBILITY-SCANNER-TRIAGE-GUIDE.md](ACCESSIBILITY-SCANNER-TRIAGE-GUIDE.md) +- [ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md](ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md) +- [ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md](ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md) +- [ACCESSIBILITY-PROJECT-VIEWS-HANDOFF.md](ACCESSIBILITY-PROJECT-VIEWS-HANDOFF.md) +- [GitHub project board](https://github.com/orgs/az-digital/projects/285) +- [Umbrella program issue #5533](https://github.com/az-digital/az_quickstart/issues/5533) + +These Phase 0 supporting documents should be treated as preliminary working drafts for meeting review, not finalized operating policy. + +## Meeting Goal + +Leave the meeting with: + +1. Agreement on the scope and structure of the accessibility program. +2. Agreement on the release and verification decisions that affect prioritization. +3. Agreement on the first implementation wave, without starting work yet. +4. Agreement on whether the preliminary Phase 0 working drafts linked to [#5532](https://github.com/az-digital/az_quickstart/issues/5532), [#5541](https://github.com/az-digital/az_quickstart/issues/5541), and [#5539](https://github.com/az-digital/az_quickstart/issues/5539) are the right working direction. + +## Proposed Agenda + +### 1. Program Overview - 10 minutes + +Start here: + +- [Project board](https://github.com/orgs/az-digital/projects/285) +- [Umbrella program issue #5533](https://github.com/az-digital/az_quickstart/issues/5533) + +Discussion points: + +1. What was completed today. +2. Why the work is now organized as a phased program rather than a single defect list. +3. How the board, parent issues, and child issues should be used going forward. + +### 2. User Impact and Prioritization Lens - 10 minutes + +Discussion points: + +1. Confirm that the team wants to prioritize the work by user friction and risk to task completion. +2. Confirm that global blockers and high-risk components should come before lower-visibility semantic cleanup. +3. Confirm whether any institution-specific risks should change the order. + +### 3. Phase-by-Phase Review - 20 minutes + +Review in this order: + +1. [Phase 0 - #5532](https://github.com/az-digital/az_quickstart/issues/5532) +2. [Phase 1 - #5535](https://github.com/az-digital/az_quickstart/issues/5535) +3. [Phase 2 - #5531](https://github.com/az-digital/az_quickstart/issues/5531) +4. [Phase 3 - #5536](https://github.com/az-digital/az_quickstart/issues/5536) +5. [Phase 4 - #5534](https://github.com/az-digital/az_quickstart/issues/5534) + +For each phase, answer: + +1. Does the scope feel correct? +2. Is anything missing? +3. Does anything belong in a different phase? +4. Is the release target direction reasonable? + +### 4. Decision Checkpoints - 15 minutes + +These decisions should be made before implementation starts: + +1. Are Marketing Cloud export routes browser-facing pages or fragment-only outputs? +2. What is the representative page matrix for CI and manual verification? +3. Should accessibility regressions block patch releases, minor releases, or both? +4. Which issues clearly belong in patch releases, and which should remain minor-release candidates? +5. Should the preliminary Phase 0 working drafts for [#5541](https://github.com/az-digital/az_quickstart/issues/5541) and [#5539](https://github.com/az-digital/az_quickstart/issues/5539) stand as the working direction while final URLs, environment details, and sign-off ownership are still being settled? + +Recommended starting positions for discussion: + +1. Treat Marketing Cloud export routes as browser-facing until the team explicitly confirms fragment-only usage, because that is the safer accessibility assumption. +2. Start with a targeted representative page matrix built around common journeys and high-risk components rather than trying to certify the whole site at once. +3. Block new serious or critical accessibility regressions on the approved representative pages for both patch and minor releases, so the verification bar is real but still scoped. +4. Keep the first implementation wave focused on immediate, noticeable user-facing change on common pages, and leave broader structural rewrites in later phases unless the scope can be narrowed safely. + +### 5. Friday Triage Items - 15 minutes + +Review the items most likely to need explicit team decisions: + +- [#5533](https://github.com/az-digital/az_quickstart/issues/5533) +- [#5541](https://github.com/az-digital/az_quickstart/issues/5541) +- [#5550](https://github.com/az-digital/az_quickstart/issues/5550) +- [#5539](https://github.com/az-digital/az_quickstart/issues/5539) +- [#5545](https://github.com/az-digital/az_quickstart/issues/5545) +- [#5544](https://github.com/az-digital/az_quickstart/issues/5544) + +Suggested focus: + +1. Which items are safe patch-release candidates. +2. Which items should remain minor-release work. +3. Which items need more discovery before they are implementation-ready. +4. Whether the new Phase 0 operating docs are directionally correct enough to support the project board's Phase 0 work without being treated as final policy. + +### 6. Confirm First Implementation Wave - 10 minutes + +Recommended immediate-impact first wave for discussion: + +1. [#5541](https://github.com/az-digital/az_quickstart/issues/5541) +2. [#5539](https://github.com/az-digital/az_quickstart/issues/5539) +3. [#5538](https://github.com/az-digital/az_quickstart/issues/5538) +4. [#5540](https://github.com/az-digital/az_quickstart/issues/5540) +5. [#5537](https://github.com/az-digital/az_quickstart/issues/5537) +6. [#5514](https://github.com/az-digital/az_quickstart/issues/5514) + +The goal is to confirm a well-targeted first wave that creates meaningful and noticeable improvement quickly, not to start coding in the meeting. + +### 7. Close With Assignments and Next Steps - 10 minutes + +Confirm: + +1. Who owns Phase 0 decisions. +2. Who will maintain the board and issue metadata. +3. Which issues need follow-up edits after the meeting. +4. What constitutes approval to begin implementation planning. +5. Who owns finalizing the preliminary Phase 0 docs after the meeting. + +## Suggested Outcome Notes Template + +Use this structure to capture decisions live during the meeting: + +### Confirmed + +- Scope decisions: +- Release decisions: +- Verification decisions: +- First-wave decisions: + +### Needs Follow-Up + +- Open questions: +- Missing data: +- Metadata or issue cleanup: + +### Deferred + +- Items intentionally postponed: + +## Facilitator Notes + +1. Keep the conversation focused on sequence and decision quality, not solution design. +2. Use the project board and the umbrella issue as the anchor for discussion. +3. If the team starts drifting into implementation detail, pull the conversation back to scope, release, and verification decisions. \ No newline at end of file diff --git a/ACCESSIBILITY-GITHUB-PROJECT-PLAN.md b/ACCESSIBILITY-GITHUB-PROJECT-PLAN.md new file mode 100644 index 0000000000..0ac3921806 --- /dev/null +++ b/ACCESSIBILITY-GITHUB-PROJECT-PLAN.md @@ -0,0 +1,647 @@ +# GitHub Project Plan for the az_quickstart Accessibility Program + +## Purpose + +This document translates the accessibility review into a GitHub-ready delivery plan for az_quickstart. + +Use this document before implementation starts to: + +1. Set up the GitHub project structure. +2. Open the right issues in the right order. +3. Describe each issue in user-centered language so prioritization is clear to product, engineering, design, QA, and maintainers. +4. Keep the current short-term carousel work scoped tightly while the broader program is planned and delivered in phases. + +This document is a companion to [ACCESSIBILITY-REVIEW-PLAN.md](ACCESSIBILITY-REVIEW-PLAN.md). + +## Live GitHub Artifacts + +The planning structure described in this document has now been created in GitHub. + +### Project Dashboard + +- Project board: [Accessibility Program - az_quickstart](https://github.com/orgs/az-digital/projects/285) + +### Program Issue + +- Umbrella issue: [#5533 - A11Y Program: WCAG 2.2 AA accessibility remediation for az_quickstart](https://github.com/az-digital/az_quickstart/issues/5533) + +### Phase Parent Issues + +- [#5532 - A11Y Phase 0: Accessibility guardrails and verification setup](https://github.com/az-digital/az_quickstart/issues/5532) +- [#5535 - A11Y Phase 1: Global user experience blockers](https://github.com/az-digital/az_quickstart/issues/5535) +- [#5531 - A11Y Phase 2: High-risk interactive components](https://github.com/az-digital/az_quickstart/issues/5531) +- [#5536 - A11Y Phase 3: Content and template semantics](https://github.com/az-digital/az_quickstart/issues/5536) +- [#5534 - A11Y Phase 4: Verification and release readiness](https://github.com/az-digital/az_quickstart/issues/5534) + +### Delivery Issues + +#### Phase 0 + +- [#5541 - A11Y P0.1: Define representative page coverage and verification policy for accessibility testing](https://github.com/az-digital/az_quickstart/issues/5541) +- [#5539 - A11Y P0.2: Add accessibility regression checks to CI for representative Quickstart pages](https://github.com/az-digital/az_quickstart/issues/5539) + +#### Phase 1 + +- [#5538 - A11Y P1.1: Make repeated page navigation skippable so users can reach content faster](https://github.com/az-digital/az_quickstart/issues/5538) +- [#5540 - A11Y P1.2: Make search and pagination controls understandable at first use](https://github.com/az-digital/az_quickstart/issues/5540) +- [#5537 - A11Y P1.3: Make site messages announce the right information at the right urgency](https://github.com/az-digital/az_quickstart/issues/5537) + +#### Phase 2 + +- [#5542 - A11Y P2.1: Make the select-menu block clear, valid, and easy to recover from when no option is chosen](https://github.com/az-digital/az_quickstart/issues/5542) +- [#5543 - A11Y P2.2: Make accordion sections announce the right section name and relationship](https://github.com/az-digital/az_quickstart/issues/5543) +- [#5514 - AZ Carousel: Slick library generates multiple critical ARIA violations (WCAG 4.1.2, 1.3.1)](https://github.com/az-digital/az_quickstart/issues/5514) +- [#5544 - A11Y P2.4: Make photo gallery carousels understandable to screen-reader and keyboard users](https://github.com/az-digital/az_quickstart/issues/5544) +- [#5546 - A11Y P2.5: Make alphabetical listing filtering and jump navigation clear to assistive-technology users](https://github.com/az-digital/az_quickstart/issues/5546) +- [#5545 - A11Y P2.6: Make the calendar picker behave in a familiar way for keyboard and screen-reader users](https://github.com/az-digital/az_quickstart/issues/5545) + +#### Phase 3 + +- [#5547 - A11Y P3.1: Make publication tables easier to understand cell by cell for screen-reader users](https://github.com/az-digital/az_quickstart/issues/5547) +- [#5551 - A11Y P3.2: Preserve meaningful image descriptions in Marketing Cloud layouts](https://github.com/az-digital/az_quickstart/issues/5551) +- [#5550 - A11Y P3.3: Decide whether Marketing Cloud export routes are fragments or full browser-facing pages](https://github.com/az-digital/az_quickstart/issues/5550) +- [#5549 - A11Y P3.4: Document and tighten guidance for meaningful versus decorative image patterns](https://github.com/az-digital/az_quickstart/issues/5549) + +#### Phase 4 + +- [#5548 - A11Y P4.1: Run accessibility verification on representative pages before release](https://github.com/az-digital/az_quickstart/issues/5548) + +### Current GitHub Setup Notes + +- The project board is organization-scoped because GitHub Projects v2 cannot be repository-scoped. +- The board is linked to `az-digital/az_quickstart` and contains the umbrella issue, all phase issues, and all delivery issues listed above. +- The project board is a standing program dashboard and is not tied to a feature or bug branch. +- The existing Slick accessibility issue [#5514](https://github.com/az-digital/az_quickstart/issues/5514) was intentionally reused as the Phase 2 carousel defect instead of creating a duplicate. +- Parent-child issue relationships are live in GitHub. +- The project description and readme have been updated to reflect the accessibility program and source planning documents. +- The dedicated planning branch stores supporting documents only. It is not an implementation branch. + +### Friday Support Documents + +- Meeting agenda: [ACCESSIBILITY-FRIDAY-MEETING-AGENDA.md](ACCESSIBILITY-FRIDAY-MEETING-AGENDA.md) +- Facilitator script: [ACCESSIBILITY-FRIDAY-FACILITATOR-SCRIPT.md](ACCESSIBILITY-FRIDAY-FACILITATOR-SCRIPT.md) +- Post-meeting notes template: [ACCESSIBILITY-POST-MEETING-NOTES-TEMPLATE.md](ACCESSIBILITY-POST-MEETING-NOTES-TEMPLATE.md) +- Live presentation talk track: [ACCESSIBILITY-LIVE-PRESENTATION-TALK-TRACK.md](ACCESSIBILITY-LIVE-PRESENTATION-TALK-TRACK.md) +- Phase 0.1 verification proposal: [ACCESSIBILITY-P0.1-VERIFICATION-PROPOSAL.md](ACCESSIBILITY-P0.1-VERIFICATION-PROPOSAL.md) +- Phase 0.2 scanner workflow plan: [ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md](ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md) +- Manual verification playbook: [ACCESSIBILITY-MANUAL-VERIFICATION-PLAYBOOK.md](ACCESSIBILITY-MANUAL-VERIFICATION-PLAYBOOK.md) +- Scanner triage guide: [ACCESSIBILITY-SCANNER-TRIAGE-GUIDE.md](ACCESSIBILITY-SCANNER-TRIAGE-GUIDE.md) +- Release sign-off checklist: [ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md](ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md) +- Representative URL inventory and environment map: [ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md](ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md) +- Saved-view handoff for manual GitHub setup: [ACCESSIBILITY-PROJECT-VIEWS-HANDOFF.md](ACCESSIBILITY-PROJECT-VIEWS-HANDOFF.md) +- Email draft summarizing today's work: [ACCESSIBILITY-PROGRAM-EMAIL-DRAFT.md](ACCESSIBILITY-PROGRAM-EMAIL-DRAFT.md) +- Executive email draft: [ACCESSIBILITY-EXECUTIVE-EMAIL-DRAFT.md](ACCESSIBILITY-EXECUTIVE-EMAIL-DRAFT.md) +- Consolidated send-out brief: [ACCESSIBILITY-SENDOUT-BRIEF.md](ACCESSIBILITY-SENDOUT-BRIEF.md) +- Final send-ready email: [ACCESSIBILITY-FINAL-REVIEW-EMAIL.md](ACCESSIBILITY-FINAL-REVIEW-EMAIL.md) +- One-page Friday handout: [ACCESSIBILITY-FRIDAY-HANDOUT.md](ACCESSIBILITY-FRIDAY-HANDOUT.md) + +## Recommended GitHub Operating Model + +Use the existing repository issue templates rather than inventing a separate workflow. + +### Umbrella Program Issue + +Suggested template: Feature request + +Suggested title: WCAG 2.2 AA accessibility remediation program for az_quickstart + +Use the umbrella issue to explain the program goal, link the audit, link every phase issue, and keep one public status summary for the whole initiative. + +### Phase Issues + +Suggested template: Task + +Create one task issue per phase: + +1. Phase 0 - Accessibility guardrails and verification setup +2. Phase 1 - Global user experience blockers +3. Phase 2 - High-risk interactive components +4. Phase 3 - Content and template semantics +5. Phase 4 - Verification and release readiness + +Each phase issue should contain a checklist of child issues and link back to the umbrella program issue. + +### Delivery Issues + +Use these templates by issue type: + +1. User-facing behavior change: User story +2. Implementation or tooling work: Task +3. Investigation or decision work: Spike +4. Narrow defect with reproducible behavior: Bug report + +### How to Treat the Current Carousel PR + +The active pull request at [PR #5528](https://github.com/az-digital/az_quickstart/pull/5528) should stay narrow. + +Recommended position: + +1. Keep it as the short-term Slick stabilization change only. +2. Link it to a single delivery issue about keyboard access in Slick slides. +3. Do not expand that PR into the full carousel, gallery, or program-wide accessibility initiative. + +That keeps review risk low and avoids mixing a tactical patch with broader structural remediation. + +## Recommended GitHub Project Setup + +Create one GitHub Project v2 called: Accessibility Program - az_quickstart + +Recommended custom fields: + +1. Phase: Phase 0, Phase 1, Phase 2, Phase 3, Phase 4 +2. Priority: P0, P1, P2 +3. Area: Theme, Widget, Content, Tooling, Verification +4. User Impact: Broad, High-risk flow, Targeted, Preventive +5. Verification Type: Automated, Manual, Both +6. WCAG Area: Navigation, Forms, Dynamic updates, Media, Tables, Tooling +7. Release Target: Patch, Minor, Undecided + +Recommended status columns: + +1. Planned +2. Ready +3. In Progress +4. In Review +5. Needs Verification +6. Done + +Recommended labels: + +1. `a11y` +2. `a11y:global` +3. `a11y:component` +4. `a11y:content` +5. `a11y:tooling` +6. `a11y:verification` +7. `priority:p0` +8. `priority:p1` +9. `priority:p2` +10. `release:patch` +11. `release:minor` + +## Program Sequence + +The work should be opened and delivered in this order: + +1. Open the umbrella program issue. +2. Open the Phase 0 spike and Phase 0 CI task. +3. Open Phase 1 issues for skip navigation, search naming, pager naming, and status message behavior. +4. Open Phase 2 issues for select menu, accordion, carousel, alphabetical listing, and date picker work. +5. Open Phase 3 issues for tables, Marketing Cloud templates, and background-image guidance. +6. Use Phase 4 as the release gate and close it only when verification is complete. + +## Decision Points to Settle Before Coding Starts + +These should be resolved first because they affect scope and acceptance criteria. + +1. Confirm whether Marketing Cloud export routes are browser-facing pages or fragment-only outputs. +2. Confirm the representative page matrix the team will use for CI and manual verification. +3. Confirm whether accessibility regressions will block patch releases, minor releases, or both. +4. Confirm which issues can be delivered in patch releases versus which ones are disruptive enough to target a minor release. + +## Assessment of User-Facing Issue Language + +The current issue set is strong enough for Friday's planning discussion. The issue bodies already explain: + +1. What the user is trying to do. +2. What is getting in the way today. +3. Why the problem matters in user terms. +4. What success should look like after the work is complete. + +No blocking rewrite is required before discussion. + +If the team wants even tighter product framing after Friday, the most valuable optional improvements would be: + +1. Add a short `Who is affected` line to the highest-priority issues. +2. Add a short `How we will know this is better` line to the highest-priority issues. +3. Standardize a `Dependencies and release notes` section only on issues that are likely to cross patch versus minor release boundaries. + +Those improvements would polish the backlog, but they are not necessary to make prioritization understandable now. The larger need was the program structure, hierarchy, and board visibility, and that is now in place. + +Since the initial planning pass, the Friday decision queue has been tightened further by applying the `needs discussion` label only to the issues that still require explicit team decisions and by keeping those items set to `Release Target = Undecided` on the project board. + +## Phase 0 - Accessibility Guardrails and Verification Setup + +Phase goal: make accessibility work measurable, repeatable, and safe to ship. + +### Issue 0.1 - Define the accessibility page matrix and verification policy + +Suggested template: Spike + +Suggested title: Define representative page coverage and verification policy for accessibility testing + +What is the problem that we want to solve? + +The audit identified broad accessibility risk, but the project does not yet have a shared agreement on which pages and user journeys must pass before release. + +Why this matters to users + +Users do not experience Quickstart as isolated widgets. They experience a full site. If the team only tests one component at a time, important accessibility problems can still ship in the real journeys that people use every day. + +Conditions of satisfaction + +- [ ] The representative page matrix is documented. +- [ ] The assistive-technology test matrix is documented. +- [ ] The minimum verification bar for patch and minor releases is documented. +- [ ] A recommended next step and estimated effort are documented. + +Suggested labels: `a11y`, `a11y:verification`, `priority:p0` + +Recommended working direction: [ACCESSIBILITY-P0.1-VERIFICATION-PROPOSAL.md](ACCESSIBILITY-P0.1-VERIFICATION-PROPOSAL.md). That proposal assumes the GitHub Accessibility Scanner is the primary automated checker and that the required Windows screen-reader matrix includes JAWS with both Chrome and Edge. + +### Issue 0.2 - Add an accessibility regression gate to CI + +Suggested template: Task + +Suggested title: Add accessibility regression checks to CI for representative Quickstart pages + +Why this matters to users + +Accessibility fixes only help users if they stay fixed. Without an automated regression gate, the same barriers can quietly return in later work and users end up losing access again. + +Conditions of satisfaction + +- [ ] CI runs accessibility checks against the approved representative pages. +- [ ] New serious or critical accessibility regressions fail the check. +- [ ] Results are easy for maintainers to review in pull requests. +- [ ] The workflow is documented for contributors. + +Suggested labels: `a11y`, `a11y:tooling`, `priority:p0`, `release:patch` + +Initial implementation direction: use the GitHub Accessibility Scanner against approved representative live URLs, then add narrower supplemental checks later only where the scanner cannot reach an authenticated or preview-only flow. + +Concrete implementation planning: [ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md](ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md). + +Operational support documents: [ACCESSIBILITY-MANUAL-VERIFICATION-PLAYBOOK.md](ACCESSIBILITY-MANUAL-VERIFICATION-PLAYBOOK.md), [ACCESSIBILITY-SCANNER-TRIAGE-GUIDE.md](ACCESSIBILITY-SCANNER-TRIAGE-GUIDE.md), [ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md](ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md), and [ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md](ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md). + +## Phase 1 - Global User Experience Blockers + +Phase goal: remove the issues that affect the largest share of users across most pages. + +### Issue 1.1 - Make it easy to skip repeated navigation and reach the main content + +Suggested template: User story + +Suggested title: Make repeated page navigation skippable so users can reach content faster + +User Story(s) + +As a keyboard user, I'd like to skip repeated page navigation and move directly to the main content, in order to reach the part of the page I came for without unnecessary effort. + +As a screen-reader user, I'd like the skip link to land on a reliable main content target, in order to understand that I have reached the primary content area. + +Why this matters to users + +When this does not work, people who use a keyboard or screen reader may need to move through the same header and navigation on every page before they can start reading. That makes ordinary browsing slower, more tiring, and less predictable. + +Conditions of satisfaction + +- [ ] The skip link points to one stable main-content target on standard pages. +- [ ] The main landmark can receive focus programmatically after skip navigation. +- [ ] Keyboard testing confirms the user lands in the primary content area. +- [ ] Screen-reader testing confirms the destination is announced clearly. + +Suggested labels: `a11y`, `a11y:global`, `priority:p0`, `release:patch` + +### Issue 1.2 - Give global search and pagination controls clear names + +Suggested template: User story + +Suggested title: Make search and pagination controls understandable at first use + +User Story(s) + +As a visitor using assistive technology, I'd like search and pagination controls to have clear accessible names, in order to understand what each control does without guessing. + +Why this matters to users + +Unnamed or poorly named controls create hesitation at core site entry points. Users can end up on a page where they can type a search but cannot tell what the submit button is, or they can reach a pagination landmark that is described with an internal token rather than a human-readable label. + +Conditions of satisfaction + +- [ ] The global search submit button has a clear accessible name. +- [ ] Pagination landmarks use human-readable labels. +- [ ] Search and pagination controls are understandable in screen-reader rotor and landmark views. +- [ ] Keyboard testing confirms the controls remain fully usable. + +Suggested labels: `a11y`, `a11y:global`, `priority:p0`, `release:patch` + +### Issue 1.3 - Make status messages helpful without being disruptive + +Suggested template: User story + +Suggested title: Make site messages announce the right information at the right urgency + +User Story(s) + +As a screen-reader user, I'd like routine confirmations to be announced politely and urgent failures to be announced urgently, in order to stay informed without being interrupted unnecessarily. + +Why this matters to users + +If every message is treated like an emergency, routine updates become noisy and stressful. Users can miss what actually matters because everything sounds equally urgent. + +Conditions of satisfaction + +- [ ] Routine informational and success messages are announced politely. +- [ ] Error and urgent warning messages are announced assertively only when appropriate. +- [ ] Duplicate or repeated announcements are avoided. +- [ ] Manual screen-reader verification confirms the behavior is clear and not noisy. + +Suggested labels: `a11y`, `a11y:global`, `priority:p0`, `release:patch` + +## Phase 2 - High-Risk Interactive Components + +Phase goal: repair the custom widgets and interactive flows most likely to block access entirely. + +### Issue 2.1 - Make select-menu navigation understandable and recoverable + +Suggested template: User story + +Suggested title: Make the select-menu block clear, valid, and easy to recover from when no option is chosen + +User Story(s) + +As a visitor using keyboard navigation or assistive technology, I'd like the select-menu block to clearly tell me its current state and any error I need to fix, in order to complete navigation confidently. + +Why this matters to users + +Right now the widget can tell a user that the control is disabled while still appearing usable, and it relies on a popover-style error that may not be announced correctly. That creates uncertainty and can make a simple navigation task feel broken. + +Conditions of satisfaction + +- [ ] The widget uses programmatically associated error messaging. +- [ ] Accessibility state matches the real interactive state. +- [ ] Focus styling is clearly visible. +- [ ] Screen-reader and keyboard testing confirm the widget is understandable and recoverable. + +Suggested labels: `a11y`, `a11y:component`, `priority:p0`, `release:patch` + +### Issue 2.2 - Make accordion sections announce the correct context + +Suggested template: User story + +Suggested title: Make accordion sections announce the right section name and relationship + +User Story(s) + +As a screen-reader user, I'd like each accordion panel to be correctly tied to its trigger, in order to know which section I opened and where I am on the page. + +Why this matters to users + +When section relationships are wired incorrectly, users can hear incomplete or misleading context when they move into accordion content. That makes scanning and comparing sections harder. + +Conditions of satisfaction + +- [ ] Each accordion trigger has a stable ID. +- [ ] Each panel is labelled by its corresponding trigger. +- [ ] The accordion parent relationship is correctly configured. +- [ ] Screen-reader testing confirms the open section is announced clearly. + +Suggested labels: `a11y`, `a11y:component`, `priority:p1`, `release:patch` + +### Issue 2.3 - Keep Slick carousel content reachable by keyboard + +Suggested template: Bug report + +Suggested title: Restore keyboard access to interactive content in Slick slides after slide changes + +Problem/Motivation + +The short-term Slick accessibility patch removes focusability from controls inside hidden slides, but it does not restore those controls when the slide becomes visible. + +Why this matters to users + +Users can reach a carousel and still be blocked from links or buttons that appear on later slides. From the user perspective, the content is visible but not actually reachable. + +Proposed resolution + +Store original focusability information and recalculate interactive descendants on initialization and slide changes so only truly hidden slides are removed from the tab order. + +Expected behavior + +When a slide becomes active, its interactive content becomes reachable by keyboard again. + +Suggested labels: `a11y`, `a11y:component`, `priority:p0`, `release:patch` + +### Issue 2.4 - Make gallery carousels understandable and predictable + +Suggested template: User story + +Suggested title: Make photo gallery carousels understandable to screen-reader and keyboard users + +User Story(s) + +As a screen-reader user, I'd like the gallery carousel to tell me what it is, which slide I am on, and how many slides exist, in order to navigate the gallery with confidence. + +As a keyboard user, I'd like gallery controls and slide content to remain reachable and predictable, in order to browse the gallery without confusion. + +Why this matters to users + +Without a clear carousel name, slide numbering, and state updates, users can move through the gallery without knowing where they are or whether new content has appeared. + +Conditions of satisfaction + +- [ ] The carousel has a clear accessible name. +- [ ] Slides expose understandable position information. +- [ ] Active slide changes are communicated clearly. +- [ ] Keyboard interaction remains complete and predictable. + +Suggested labels: `a11y`, `a11y:component`, `priority:p1`, `release:minor` + +### Issue 2.5 - Make alphabetical listings respond clearly to search and A to Z navigation + +Suggested template: User story + +Suggested title: Make alphabetical listing filtering and jump navigation clear to assistive-technology users + +User Story(s) + +As a screen-reader user, I'd like filtering changes to be announced clearly, in order to know whether my search found results. + +As a keyboard user, I'd like A to Z navigation to move me to the destination section, in order to continue reading from the place I chose. + +Why this matters to users + +Today the page changes visually, but users may not hear that results changed and may not land in the selected section after using the alphabet navigation. That makes the feature feel unreliable. + +Conditions of satisfaction + +- [ ] Result counts or no-results status are announced through a polite live region. +- [ ] A to Z navigation moves focus to the destination section or preserves reliable native navigation behavior. +- [ ] Keyboard-only testing confirms the jump behavior is usable. +- [ ] Screen-reader testing confirms filter changes are understandable. + +Suggested labels: `a11y`, `a11y:component`, `priority:p0`, `release:patch` + +### Issue 2.6 - Make the date picker work with standard assistive-technology patterns + +Suggested template: User story + +Suggested title: Make the calendar picker behave in a familiar way for keyboard and screen-reader users + +User Story(s) + +As a screen-reader user, I'd like the calendar picker to use familiar navigation patterns, in order to choose a date without fighting the control. + +As a keyboard user, I'd like focus in the calendar picker to stay visible and easy to track, in order to complete date entry confidently. + +Why this matters to users + +The current picker uses aggressive announcement behavior and application-style semantics that can interrupt reading commands and create an unusually noisy experience. For many users, that turns a basic date selection task into a frustrating interaction. + +Conditions of satisfaction + +- [ ] The picker no longer relies on application mode. +- [ ] Routine navigation is not announced as urgent. +- [ ] Focus indication is clear in supported light themes. +- [ ] Manual NVDA and VoiceOver checks confirm the picker follows familiar patterns. + +Suggested labels: `a11y`, `a11y:component`, `priority:p0`, `release:minor` + +## Phase 3 - Content and Template Semantics + +Phase goal: make structured content understandable and preserve meaning in author-driven outputs. + +### Issue 3.1 - Make publication tables easier to understand row by row + +Suggested template: User story + +Suggested title: Make publication tables easier to understand cell by cell for screen-reader users + +User Story(s) + +As a screen-reader user, I'd like publication tables to expose clear row and column context, in order to understand each value without having to guess what it belongs to. + +Why this matters to users + +When a data table lacks a caption or proper row headers, users can hear cell content without enough context to know what they are looking at. That turns structured information into a memory exercise. + +Conditions of satisfaction + +- [ ] Publication tables include a caption or equivalent table name. +- [ ] Row and column header relationships are clear. +- [ ] Screen-reader table navigation confirms context is preserved cell by cell. + +Suggested labels: `a11y`, `a11y:content`, `priority:p1`, `release:patch` + +### Issue 3.2 - Make Marketing Cloud images preserve their meaning + +Suggested template: User story + +Suggested title: Preserve meaningful image descriptions in Marketing Cloud layouts + +User Story(s) + +As a person using assistive technology, I'd like meaningful Marketing Cloud images to expose the same meaning that sighted users get, in order to receive the full message instead of an incomplete version. + +Why this matters to users + +If a content image is always marked decorative, users who rely on alternative text can miss key information, branding context, or campaign meaning entirely. + +Conditions of satisfaction + +- [ ] Meaningful images can carry author-provided alternative text. +- [ ] Only explicitly decorative images are hidden from assistive technology. +- [ ] Documentation explains when empty alt text is appropriate. + +Suggested labels: `a11y`, `a11y:content`, `priority:p0`, `release:patch` + +### Issue 3.3 - Decide how browser-facing Marketing Cloud exports should behave + +Suggested template: Spike + +Suggested title: Decide whether Marketing Cloud export routes are fragments or full browser-facing pages + +What is the problem that we want to solve? + +The current export shell strips normal page-level semantics. That may be fine for fragments, but it is not fine for a browser-facing page. + +Why this matters to users + +If an export page is opened directly in a browser without proper page structure, assistive-technology users can lose navigation landmarks and page identity. That makes the content harder to review independently. + +Conditions of satisfaction + +- [ ] The intended route behavior is documented. +- [ ] A recommendation is made for either fragment-only use or full document semantics. +- [ ] Follow-up implementation work is estimated and linked. + +Suggested labels: `a11y`, `a11y:content`, `priority:p1` + +### Issue 3.4 - Audit background-image and decorative-image patterns + +Suggested template: Task + +Suggested title: Document and tighten guidance for meaningful versus decorative image patterns + +Why this matters to users + +If meaningful content is delivered through CSS backgrounds or mistakenly treated as decorative, some users will never receive that information at all. + +Conditions of satisfaction + +- [ ] High-risk background-image and decorative-image patterns are documented. +- [ ] Guidance exists for when images must be exposed as content. +- [ ] Follow-up implementation issues are opened for any confirmed problems. + +Suggested labels: `a11y`, `a11y:content`, `priority:p1` + +## Phase 4 - Verification and Release Readiness + +Phase goal: prove that the repaired experience works on rendered pages and keep it working. + +### Issue 4.1 - Verify the repaired experience on representative pages before release + +Suggested template: Task + +Suggested title: Run accessibility verification on representative pages before release + +Why this matters to users + +Users do not benefit from code that looks compliant in review but fails in the browser. This issue is the final quality check that confirms repaired behavior actually works where users encounter it. + +Conditions of satisfaction + +- [ ] Automated checks pass on the representative page matrix. +- [ ] Keyboard-only verification passes on the representative page matrix. +- [ ] NVDA and VoiceOver checks pass for the highest-risk flows. +- [ ] Any remaining risks are documented before release. + +Suggested labels: `a11y`, `a11y:verification`, `priority:p0` + +## Suggested First Two Iterations + +### Iteration 1 + +Open and deliver these issues first: + +1. Issue 0.1 - verification spike +2. Issue 0.2 - CI regression gate +3. Issue 1.1 - skip navigation +4. Issue 1.2 - search and pagination naming +5. Issue 1.3 - status message urgency +6. Issue 2.3 - Slick keyboard access defect + +This set gives immediate user value and reduces the chance that new fixes regress. + +### Iteration 2 + +Then open and deliver these issues: + +1. Issue 2.1 - select menu +2. Issue 2.2 - accordion +3. Issue 2.5 - alphabetical listing +4. Issue 2.6 - date picker +5. Issue 3.2 - Marketing Cloud alt text +6. Issue 3.1 - publication table semantics + +## Recommended Next GitHub Actions + +1. Open the umbrella feature request issue and link [ACCESSIBILITY-REVIEW-PLAN.md](ACCESSIBILITY-REVIEW-PLAN.md) and this document. +2. Create the GitHub Project v2 board with the recommended fields. +3. Open Issue 0.1 and Issue 0.2 immediately. +4. Open the Phase 1 issues and mark them `priority:p0`. +5. Create a single issue for Slick keyboard access and link [PR #5528](https://github.com/az-digital/az_quickstart/pull/5528) to that issue only. +6. Do not begin broader implementation until the team agrees on the page matrix, release policy, and whether Marketing Cloud exports are browser-facing. + +These steps have now been completed in GitHub, with the exception of future implementation work. \ No newline at end of file diff --git a/ACCESSIBILITY-LIVE-PRESENTATION-TALK-TRACK.md b/ACCESSIBILITY-LIVE-PRESENTATION-TALK-TRACK.md new file mode 100644 index 0000000000..69abe524d2 --- /dev/null +++ b/ACCESSIBILITY-LIVE-PRESENTATION-TALK-TRACK.md @@ -0,0 +1,102 @@ +# Accessibility Program Live Presentation Talk Track + +## Purpose + +Use this talk track for a 5 to 7 minute walkthrough of the accessibility program during the Friday meeting. + +## Goal of the Walkthrough + +Explain what was completed, how the work is now organized, what decisions still need to be made, and what the team should align on before implementation starts. + +## 5 to 7 Minute Speaking Order + +### Minute 0 to 1 - What Was Completed + +Suggested script: + +"Today’s work focused on organization, not implementation. I completed the accessibility review and turned it into a structured GitHub program with an umbrella issue, phase parent issues, delivery issues, and a project board. I also added preliminary Phase 0 working drafts for the verification policy and scanner rollout so Friday’s conversation can stay focused on decisions instead of starting from a blank page." + +References: + +- Project board: https://github.com/orgs/az-digital/projects/285 +- Umbrella issue: https://github.com/az-digital/az_quickstart/issues/5533 +- Phase 0 parent: https://github.com/az-digital/az_quickstart/issues/5532 +- P0.1 verification policy: https://github.com/az-digital/az_quickstart/issues/5541 +- P0.2 scanner gate: https://github.com/az-digital/az_quickstart/issues/5539 + +### Minute 1 to 2 - What Exists in GitHub Now + +Suggested script: + +"The work is now grouped into five phases: guardrails and verification, global blockers, high-risk interactive components, content and template semantics, and final verification and release readiness. That gives us a way to discuss order, release risk, and ownership clearly. The Phase 0 issues now also have preliminary working drafts behind them, which means we can review a concrete direction for verification without pretending those documents are final." + +References: + +- Phase 0: https://github.com/az-digital/az_quickstart/issues/5532 +- Phase 1: https://github.com/az-digital/az_quickstart/issues/5535 +- Phase 2: https://github.com/az-digital/az_quickstart/issues/5531 +- Phase 3: https://github.com/az-digital/az_quickstart/issues/5536 +- Phase 4: https://github.com/az-digital/az_quickstart/issues/5534 + +### Minute 2 to 3 - How the Work Is Prioritized + +Suggested script: + +"The issues are written to prioritize user friction and delivery risk. The current structure puts global blockers and high-risk interaction failures ahead of lower-visibility cleanup. That is the default recommendation unless the team sees a reason to reorder based on institutional risk or release commitments." + +### Minute 3 to 4 - What Still Needs Decisions + +Suggested script: + +"I narrowed the Friday decision queue to the items that still need explicit team direction. Those are the umbrella program issue, the verification policy spike, the Marketing Cloud export decision, and two items that still sit between patch-safe and minor-release territory: the gallery carousel and the date picker. Supporting that, there is now a preliminary Phase 0 working set for #5541 and #5539 covering the scanner workflow, manual verification, triage, release sign-off, and representative URL inventory." + +Decision queue: + +- https://github.com/az-digital/az_quickstart/issues/5533 +- https://github.com/az-digital/az_quickstart/issues/5541 +- https://github.com/az-digital/az_quickstart/issues/5550 +- https://github.com/az-digital/az_quickstart/issues/5544 +- https://github.com/az-digital/az_quickstart/issues/5545 + +### Minute 4 to 5 - Recommended First Wave + +Suggested script: + +"Assuming the team confirms the release and verification decisions, the most sensible first wave is the verification policy, the CI regression gate, the skip link, search and pager naming, status message behavior, and the existing Slick accessibility defect. That gives us both immediate user value and a safer foundation for later work." + +References: + +- https://github.com/az-digital/az_quickstart/issues/5541 +- https://github.com/az-digital/az_quickstart/issues/5539 +- https://github.com/az-digital/az_quickstart/issues/5538 +- https://github.com/az-digital/az_quickstart/issues/5540 +- https://github.com/az-digital/az_quickstart/issues/5537 +- https://github.com/az-digital/az_quickstart/issues/5514 + +### Minute 5 to 6 - What We Need From the Team Today + +Suggested script: + +"What I need from the team today is not implementation detail. I need agreement on scope, release direction, verification expectations, the first implementation wave, and whether the new Phase 0 drafts are the right working direction for #5541 and #5539. Once those are settled, we can update the board and move into implementation planning cleanly." + +### Optional Minute 6 to 7 - Close + +Suggested script: + +"If we leave today with those decisions made, the next step is straightforward: update the issue metadata, confirm ownership, and begin implementation planning without having to reopen basic program-structure questions." + +## Short Version If Time Is Tight + +If you only have 2 to 3 minutes, say this: + +"I completed the accessibility planning and GitHub setup so the work is now organized as a real program. We have a live board, an umbrella issue, phase parent issues, and child issues grouped by user impact and release risk. The main decisions still open are the verification policy, the Marketing Cloud export direction, and whether the gallery carousel and date picker stay minor-release work or can be narrowed further. If we agree on those decisions today, we can move into implementation planning with a much cleaner first wave." + +Suggested add-on if there is another 20 seconds: + +"We also now have preliminary Phase 0 working drafts tied to #5532, #5541, and #5539. Those drafts are not final policy, but they give the team something concrete to approve, adjust, or reject instead of discussing verification in the abstract." + +## Presenter Notes + +1. Stay at the level of program design, not implementation detail. +2. Use the board and umbrella issue as visual anchors. +3. If people dive into solution specifics too early, redirect to phase placement, release target, or verification requirement. \ No newline at end of file diff --git a/ACCESSIBILITY-MANUAL-VERIFICATION-PLAYBOOK.md b/ACCESSIBILITY-MANUAL-VERIFICATION-PLAYBOOK.md new file mode 100644 index 0000000000..d3fa3ad487 --- /dev/null +++ b/ACCESSIBILITY-MANUAL-VERIFICATION-PLAYBOOK.md @@ -0,0 +1,293 @@ +# Accessibility Manual Verification Playbook + +## Purpose + +This playbook defines how az_quickstart should run manual accessibility verification after the automated scanner pass. It is intended to support Phase 0 verification work, release sign-off, and user acceptance for the highest-risk user journeys identified in the accessibility review. + +This document does not replace the representative page matrix or the scanner workflow. It tells reviewers what to do after the automated gate runs and what outcomes should be treated as pass, fail, or release risk. + +## How To Use This Playbook + +1. Start with the approved representative URLs from [ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md](ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md). +2. Confirm whether the review is for a patch profile or a minor-release profile. +3. Run the automated scan first. +4. Run the manual checks in this document on the affected pages and flows. +5. Record results in [ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md](ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md). + +## Required Review Conditions + +1. Use the same live environment that the automated scanner used when practical. +2. Review pages at 100 percent zoom and 200 percent zoom. +3. Use a keyboard without a mouse for the keyboard-only pass. +4. Confirm both success and failure paths when a flow includes validation or status messages. +5. Record every skip, partial pass, or uncertainty in the release sign-off checklist rather than treating it as a silent pass. + +## Required Manual Matrix + +The baseline manual matrix for release verification is: + +1. NVDA with Firefox on Windows. +2. NVDA with Chrome on Windows. +3. JAWS with Chrome on Windows. +4. JAWS with Edge on Windows. +5. VoiceOver with Safari on macOS. +6. VoiceOver with Safari on iOS when the release changes mobile interaction, mobile layout, or mobile media behavior. + +TalkBack with Chrome on Android should be added when the release materially changes mobile forms, mobile navigation, or mobile media interaction. + +## Release Scope Rules + +### Patch Profile + +Use the patch profile for smaller releases and targeted fixes. + +1. Run keyboard-only checks on every changed representative page. +2. Run manual screen-reader checks on every affected high-risk flow. +3. Include JAWS with Chrome and JAWS with Edge when the change affects Windows-facing interactive behavior. +4. Include VoiceOver on iOS when the change affects mobile interaction. + +### Minor-Release Profile + +Use the minor-release profile for broader work. + +1. Run keyboard-only checks across the full representative page matrix. +2. Run the full required screen-reader matrix for all high-risk flows in scope. +3. Record unresolved risks explicitly before release approval. + +## Core Flow Checks + +The sections below define the minimum expected outcomes for the highest-risk flows already identified in the planning package. + +### Global Shell And Skip Link + +Run this on the front page and at least one standard content page. + +Steps: + +1. Load the page from the top. +2. Press `Tab` until the skip link is visible. +3. Activate the skip link. +4. Continue keyboard navigation from the destination. +5. Repeat with the required screen readers. + +Expected results: + +1. The skip link appears predictably. +2. Activation moves focus to the main content target. +3. The destination is announced clearly as the main content area. +4. The user can continue reading or tabbing from the destination without being thrown back into repeated navigation. + +### Search And Pager Controls + +Run this on the search results page or another representative page that exposes search and pagination. + +Steps: + +1. Move to the search input and search submit control by keyboard. +2. Confirm the accessible name of the search submit control. +3. Move through the pagination landmark and links. +4. Repeat with the required screen readers. + +Expected results: + +1. The search submit control has a clear accessible name. +2. Pagination landmarks use human-readable labels. +3. Screen-reader landmark and rotor views describe the controls understandably. +4. Keyboard use remains complete and predictable. + +### Status Messages And Alerts + +Run this on a page that can trigger both routine status feedback and an error or urgent warning. + +Steps: + +1. Trigger a routine success or informational message. +2. Trigger an error or urgent warning if the page supports it. +3. Listen for announcement timing and repetition. +4. Repeat with the required screen readers. + +Expected results: + +1. Routine informational or success messages are announced politely. +2. Error messages are announced urgently only when appropriate. +3. Messages do not duplicate or repeat unnecessarily. +4. Users can continue their task without disruptive announcement noise. + +### Select-Menu Block + +Run this on a page that uses the custom select-menu block. + +Steps: + +1. Tab to the control. +2. Inspect focus visibility before interacting. +3. Trigger the empty or invalid path. +4. Select a valid option and confirm recovery. +5. Repeat with the required screen readers. + +Expected results: + +1. Focus is clearly visible. +2. The control's announced state matches its real interactive state. +3. Error messaging is associated programmatically with the field. +4. The user can recover from the invalid path without ambiguity. + +### Accordion Sections + +Run this on a page that uses the custom accordion component. + +Steps: + +1. Move through accordion triggers by keyboard. +2. Open and close multiple sections. +3. Move into the expanded content. +4. Repeat with the required screen readers. + +Expected results: + +1. Each trigger announces the correct section context. +2. Expanded content is tied to the correct trigger. +3. Keyboard access remains complete. +4. Users do not lose track of which section is open. + +### Alphabetical Listing + +Run this on a page using the alphabetical listing view. + +Steps: + +1. Use the filter or search field. +2. Trigger both a result case and a no-results case. +3. Use A to Z jump navigation. +4. Confirm where focus lands after navigation. +5. Repeat with the required screen readers. + +Expected results: + +1. Result changes are announced clearly. +2. No-results status is announced clearly. +3. A to Z navigation lands the user in the destination section or preserves reliable native behavior. +4. The updated state is understandable without visual cues alone. + +### Photo Gallery Carousel + +Run this on a page with the photo gallery carousel. + +Steps: + +1. Move to the carousel by keyboard. +2. Identify the accessible name of the carousel. +3. Move between slides. +4. Confirm what is announced when the active slide changes. +5. Repeat with the required screen readers. + +Expected results: + +1. The carousel has a clear accessible name. +2. Slide position is understandable, such as slide number and total count. +3. Active slide changes are communicated clearly. +4. Keyboard access remains complete and predictable. + +### Date Picker + +Run this on an event page or other representative page that exposes the date picker. + +Steps: + +1. Open the picker by keyboard. +2. Move between dates, months, or years as supported. +3. Listen for announcement behavior during routine navigation. +4. Review focus visibility during movement. +5. Repeat with the required screen readers. + +Expected results: + +1. Routine navigation is not announced as urgent. +2. The picker behaves like a familiar date-selection control rather than an application-mode trap. +3. Focus remains easy to track. +4. Users can select a date without fighting the control. + +### Publication Tables + +Run this on the publication table page or publication administration table page. + +Steps: + +1. Move to the table. +2. Confirm whether the table exposes a usable name or caption. +3. Navigate cell by cell with the screen reader. +4. Confirm row and column context while moving. + +Expected results: + +1. The table has a clear name or caption. +2. Row and column context remains understandable during navigation. +3. The primary label cell behaves like a row header where needed. +4. Users do not hear ambiguous values without context. + +### Marketing Cloud Layouts And Export Route + +Run this on the approved representative Marketing Cloud layout and export route. + +Steps: + +1. Confirm whether the layout includes meaningful images. +2. Review whether meaningful images expose informative alternative text. +3. Load the export route directly in a browser. +4. Confirm whether landmarks, page identity, and document context remain understandable. + +Expected results: + +1. Meaningful images are not hidden as decorative by default. +2. Explicitly decorative images stay appropriately decorative. +3. Browser-facing export pages preserve enough page-level semantics to remain understandable. +4. Any unresolved export-route ambiguity is recorded as a release risk, not ignored. + +### Authentication-Related Flow + +Run this only on an approved representative authentication-related page that can be tested safely. + +Steps: + +1. Move through the login or authentication flow by keyboard. +2. Confirm focus order, field naming, and error recovery. +3. Repeat with the required Windows and Apple screen-reader combinations that are in scope. + +Expected results: + +1. The flow is keyboard operable. +2. Fields and actions are clearly named. +3. Error handling is understandable and recoverable. +4. The result should be recorded as verified, deferred, or blocked by environment limitations. + +## Pass, Fail, And Risk Handling + +### Pass + +Mark a check as pass only when the outcome is clear and repeatable in the tested environment. + +### Fail + +Mark a check as fail when a user cannot complete the task reliably, when state or announcement behavior is misleading, or when focus and navigation break task completion. + +### Release Risk + +Mark a check as release risk when: + +1. The flow could not be verified because the environment was not available. +2. The behavior is ambiguous and needs team review. +3. The issue does not fully block the release but creates real user risk that decision-makers must acknowledge. + +## Evidence To Capture + +For each failed or risky check, record: + +1. Representative page ID or URL. +2. Flow tested. +3. Browser and assistive technology used. +4. Short description of the observed behavior. +5. Whether the issue appears to be a regression, an existing baseline issue, or an environment limitation. + +## Recommended Next Step + +Use this playbook together with [ACCESSIBILITY-SCANNER-TRIAGE-GUIDE.md](ACCESSIBILITY-SCANNER-TRIAGE-GUIDE.md), [ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md](ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md), and [ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md](ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md) so the automated and manual parts of Phase 0 use the same scope and terminology. \ No newline at end of file diff --git a/ACCESSIBILITY-P0.1-VERIFICATION-PROPOSAL.md b/ACCESSIBILITY-P0.1-VERIFICATION-PROPOSAL.md new file mode 100644 index 0000000000..58291d7487 --- /dev/null +++ b/ACCESSIBILITY-P0.1-VERIFICATION-PROPOSAL.md @@ -0,0 +1,156 @@ +# Phase 0.1 Proposal: Representative Page Coverage and Verification Policy + +## Purpose + +This document proposes the delivery scope for A11Y P0.1. It turns the current accessibility review and issue set into a concrete recommendation for what az_quickstart should verify before release, how that verification should be performed, and what decisions still need explicit team approval. + +This proposal is intended to support the existing planning issue for Phase 0.1 and to give the team a practical starting point for implementation planning in Phase 0.2. + +## Recommended Direction + +1. Use the GitHub Accessibility Scanner as the primary automated accessibility checker for representative live URLs. +2. Use a mixed verification model that combines automated scanning, keyboard-only checks, screen-reader checks, and release-time user acceptance review. +3. Start with a brownfield baseline so the team can inventory existing issues before enforcing a no-regressions gate for new serious or critical findings. +4. Require a smaller but mandatory verification set for patch releases and a broader full-matrix verification set for minor releases. +5. Until the team explicitly decides otherwise, treat Marketing Cloud export routes as browser-facing pages for verification purposes because that is the safer accessibility assumption. + +## Why This Fits The Current Repository + +The current review already identifies the highest-risk surfaces: skip navigation, search and pager naming, status-message urgency, the select-menu widget, accordion relationships, the alphabetical listing, gallery carousel behavior, the date picker, publication tables, and Marketing Cloud templates. + +The repository already uses GitHub Actions, but it does not currently have an explicit accessibility gate in [package.json](package.json) or [.github/workflows/ci.yml](.github/workflows/ci.yml). That means Phase 0.1 should define a policy that fits the existing GitHub-based workflow and produces findings that maintainers can review in the same place they already review code. + +The GitHub Accessibility Scanner fits that need well because it scans live URLs, creates GitHub-native findings, and gives the team a practical way to track regressions over time. + +## Proposed Representative Page Matrix + +The first approved page matrix should cover page types and flows rather than only isolated components. The team can fill in the exact URLs after agreeing on the canonical examples. + +1. Front page or top-level landing page using the standard global shell. +2. Standard content page with the default main-content area and skip-link behavior. +3. Sidebar or block-heavy content page that exercises alternate layout regions. +4. Search results page that exposes the search submit control and pager naming. +5. A page with a reliable routine status-message trigger and an error-message trigger. +6. A page that uses the select-menu block. +7. An alphabetical listing page with search filtering and A to Z jump navigation. +8. A page with the photo gallery carousel. +9. An event page or equivalent page that exposes the date picker. +10. A publication table page or publication administration page that exercises table semantics. +11. A login or authentication-related page that is part of the normal user journey. +12. A Marketing Cloud export route. + +## Proposed Automated Checking Model + +### Primary Tool + +Use the GitHub Accessibility Scanner as the primary automated checker in CI. + +### Why This Tool Is Recommended + +1. It is GitHub-native and fits the repository's existing workflow model. +2. It scans rendered live pages rather than only static source. +3. It creates reviewable findings in GitHub, which improves visibility for maintainers. +4. It supports regression tracking across repeated scans. + +### Recommended Operating Model + +1. Run an initial baseline scan against the approved representative URLs on the default branch or a stable staging environment. +2. Use that baseline to distinguish existing debt from new regressions. +3. Once the baseline is established, fail on new serious or critical findings on the approved representative pages. +4. Keep moderate and minor findings visible for triage, but do not block on them during initial rollout. + +### Environment Requirement + +The GitHub Accessibility Scanner requires live URLs. + +The preferred target is a preview or staging environment that reflects the branch under review. If per-branch preview URLs are not yet available, the fallback is to run the scanner against a stable staging environment until preview infrastructure exists. + +### Supplemental Checks + +The GitHub Accessibility Scanner should be the primary automated tool, not the only form of verification. Where the scanner cannot reach an authenticated flow, a preview-only route, or a hard-to-reproduce interaction, the team should supplement it with targeted manual testing and, if needed later in Phase 0.2, a narrower local automation layer. + +## Proposed Manual Verification And User Acceptance Model + +Automation will not cover announcement quality, real keyboard experience, or browser and assistive-technology differences. Phase 0.1 should therefore define a manual verification and user acceptance matrix alongside the automated gate. + +### Keyboard And Visual Checks + +1. Keyboard-only navigation on every representative page in scope for the release. +2. Focus visibility review at 100 percent and 200 percent zoom. +3. Verification that skip links, landmarks, dialogs, live regions, and custom widgets behave predictably without a mouse. + +### Required Screen Reader And Browser Matrix + +The required manual matrix for release verification should be: + +1. NVDA with Firefox on Windows. +2. NVDA with Chrome on Windows. +3. JAWS with Chrome on Windows. +4. JAWS with Edge on Windows. +5. VoiceOver with Safari on macOS. +6. VoiceOver with Safari on iOS. + +### Conditional Mobile Coverage + +TalkBack with Chrome on Android should be added when the release materially changes mobile navigation, mobile forms, or mobile media interactions. + +### Why JAWS On Both Chrome And Edge Should Be Included + +Chrome and Edge can expose small but meaningful differences in how enterprise Windows users experience the same page with JAWS. Requiring both combinations makes the acceptance model more resilient and reduces the chance that a fix looks correct in one Windows browser but degrades in another common deployment path. + +## Proposed Verification Bar By Release Type + +### Patch Releases + +Patch releases should use a smaller but mandatory verification set. + +1. Scan the patch representative subset with the GitHub Accessibility Scanner. +2. Include at minimum the front page, a standard page shell, a search or pager page, a status-message example, and every page type directly affected by the release. +3. Run keyboard-only checks on every changed flow. +4. Run manual screen-reader checks on affected high-risk flows, including JAWS with Chrome and JAWS with Edge when the release changes Windows-facing interactive behavior. +5. Block the release on new serious or critical findings in the approved patch subset. + +### Minor Releases + +Minor releases should use the full representative page matrix. + +1. Scan the full representative matrix with the GitHub Accessibility Scanner. +2. Run keyboard-only checks across the full matrix. +3. Complete the full required screen-reader and browser matrix for high-risk flows. +4. Produce a short release-readiness summary of unresolved known risks before release approval. + +## Proposed User Acceptance Outcome + +Phase 0.1 should treat user acceptance as a release decision input rather than a final afterthought. + +Before a release is considered ready, the team should be able to answer these questions clearly: + +1. Did the GitHub Accessibility Scanner find any new serious or critical regressions on the approved representative pages? +2. Did keyboard-only testing confirm that the changed flows remain usable? +3. Did NVDA, JAWS, and VoiceOver checks confirm that names, roles, states, focus handling, and announcements remain understandable? +4. Are any remaining known risks documented clearly enough for maintainers to make a release decision? + +## Decisions Needed To Close Phase 0.1 + +1. Which deployed environment will provide the live URLs for the GitHub Accessibility Scanner? +2. Which exact page instances will become the approved representative URLs for each page type in the matrix? +3. Should the blocking threshold be new serious and critical findings only, or should the team include moderate findings later after the baseline stabilizes? +4. Which role owns final manual verification sign-off before release? + +## Recommended Phase 0.1 Deliverables + +At close, A11Y P0.1 should produce: + +1. An approved representative page matrix. +2. An approved browser and assistive-technology matrix. +3. An approved verification bar for patch releases and minor releases. +4. An explicit decision to use the GitHub Accessibility Scanner as the primary automated checking tool. +5. A written handoff into A11Y P0.2 so the CI implementation work starts with a settled policy. + +## Estimated Effort And Recommended Next Step + +1. Half a day to confirm page types, owners, and candidate URLs. +2. Half a day to confirm the required manual matrix and release thresholds. +3. One to two days to translate the approved policy into a working A11Y P0.2 implementation plan. + +The recommended next step is to approve this policy direction, then implement a proof of concept GitHub Accessibility Scanner workflow against a small representative subset before expanding it to the full matrix. The concrete implementation model is documented in [ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md](ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md). \ No newline at end of file diff --git a/ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md b/ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md new file mode 100644 index 0000000000..ff90604d97 --- /dev/null +++ b/ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md @@ -0,0 +1,352 @@ +# Phase 0.2 Plan: GitHub Accessibility Scanner Workflow + +## Purpose + +This document proposes the implementation plan for A11Y P0.2. It translates the Phase 0.1 verification policy into a concrete workflow model for automated accessibility checking, regression gating, and manual verification handoff inside the existing GitHub-based development process. + +This document does not implement the workflow yet. It defines the operating model, the files that should be added, the rollout sequence, and the decisions that must be settled before the workflow becomes a required release gate. + +## Relationship To Phase 0.1 + +Phase 0.1 answers what the project should verify. + +Phase 0.2 answers how the project should run that verification in practice. + +The Phase 0.1 proposal already recommends: + +1. The GitHub Accessibility Scanner as the primary automated accessibility checker. +2. A representative page matrix based on real page types and user journeys. +3. A mixed verification model that combines automated checks, keyboard testing, screen-reader checks, and release-time user acceptance. +4. A required Windows screen-reader matrix that includes JAWS with both Chrome and Edge. + +Phase 0.2 should implement that policy without changing it. + +## Recommended Outcome + +At close, A11Y P0.2 should give az_quickstart a working accessibility regression gate that: + +1. Uses the GitHub Accessibility Scanner against approved live URLs. +2. Runs inside GitHub Actions and produces results that maintainers can review in GitHub. +3. Establishes a brownfield baseline before blocking on regressions. +4. Fails on new serious or critical accessibility regressions after the baseline is approved. +5. Hands off clearly into required manual keyboard and screen-reader verification for affected flows. + +## Recommended Workflow Model + +### Primary Automated Tool + +Use `github/accessibility-scanner@v2` as the primary automated checker. + +### Why This Model Fits The Repository + +1. The repository already uses GitHub Actions for CI. +2. The current accessibility planning package is already organized around GitHub-native workflows, issues, and board tracking. +3. The scanner works on rendered live pages, which matches the Phase 0 requirement to verify runtime behavior rather than only source code. +4. The scanner gives maintainers a GitHub-visible way to track accessibility regressions over time. + +### What The Workflow Should Not Try To Do Initially + +1. It should not try to replace all manual verification. +2. It should not try to scan every possible route on day one. +3. It should not block every existing accessibility issue in a brownfield codebase before a baseline exists. +4. It should not automatically expand into authenticated or unstable preview routes until the environment model is proven. + +## Required Inputs And Preconditions + +The GitHub Accessibility Scanner requires live URLs. That means the first implementation decision is environmental, not YAML-level. + +### Required Preconditions + +1. A stable set of live URLs for the approved representative pages. +2. A GitHub token with the permissions required by the scanner workflow. +3. Agreement on whether the first rollout uses a shared staging environment, per-branch preview URLs, or a temporary fallback. +4. Agreement on the patch subset versus full minor-release page matrix. + +### Recommended Environment Order + +1. Preferred: pull-request preview URLs that reflect the branch under review. +2. Acceptable fallback: a stable staging environment used for proof of concept and baseline creation. +3. Deferred: authenticated scanning for flows that need CAS or similar login behavior. + +### Recommended Secrets And Inputs + +The exact names can change, but the plan should assume a small and explicit set of workflow inputs: + +1. A token secret for the scanner workflow. +2. A base URL or URL manifest source for the scan target environment. +3. Optional authentication context inputs for future authenticated scanning. +4. A cache key strategy so the baseline and regression history remain stable across runs. + +## Proposed Repository Artifacts + +Phase 0.2 should be implemented as a small set of explicit files rather than a single workflow file that hard-codes policy. + +The operational companion documents for this plan are: + +1. [ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md](ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md) +2. [ACCESSIBILITY-MANUAL-VERIFICATION-PLAYBOOK.md](ACCESSIBILITY-MANUAL-VERIFICATION-PLAYBOOK.md) +3. [ACCESSIBILITY-SCANNER-TRIAGE-GUIDE.md](ACCESSIBILITY-SCANNER-TRIAGE-GUIDE.md) +4. [ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md](ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md) + +### Workflow File + +Recommended file: + +`.github/workflows/accessibility-scanner.yml` + +This workflow should own the GitHub Accessibility Scanner integration and the regression gate. + +### Representative URL Manifests + +Recommended files: + +1. `.github/accessibility/pages.patch.txt` +2. `.github/accessibility/pages.minor.txt` + +These files should list approved live URLs, one per line, so the policy can change without rewriting the workflow logic. + +### Contributor And Maintainer Guidance + +Recommended file: + +`.github/accessibility/README.md` + +This document should explain: + +1. What the scanner is checking. +2. Which URLs are in scope. +3. What causes a blocking failure. +4. How maintainers should interpret scanner-created findings. +5. What manual verification still must happen after the automated run. + +### Release Verification Checklist + +The release-time operational checklist is documented in [ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md](ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md). The workflow implementation should leave room for that checklist because manual sign-off is part of the release gate, not an optional side process. + +## Proposed Trigger Model + +The workflow should support more than one execution pattern because patch-release verification and broader release-readiness verification are not the same thing. + +### Pull Request Trigger + +Use pull requests for the smallest reliable automated gate. + +Recommended behavior: + +1. Run against the approved patch subset by default. +2. Surface new serious or critical regressions clearly. +3. Keep the result lightweight enough to be practical for normal review. + +### Workflow Dispatch Trigger + +Use manual dispatch for broader verification windows. + +Recommended behavior: + +1. Allow maintainers to choose the patch or minor profile. +2. Allow maintainers to target a known environment when needed. +3. Use this path for pre-release full-matrix verification. + +### Scheduled Trigger + +Use a scheduled run on the default branch or stable environment after the first rollout stabilizes. + +Recommended behavior: + +1. Re-scan the full representative matrix. +2. Catch regressions introduced outside ordinary PR timing. +3. Keep a continuous picture of accessibility drift over time. + +## Proposed Page-Profile Model + +### Patch Profile + +The patch profile should be the minimum mandatory automated set. + +It should include: + +1. Front page or standard landing page. +2. Standard page shell. +3. Search or pager example. +4. Status-message example. +5. Any representative page type directly affected by the PR or release. + +### Minor Profile + +The minor profile should include the full representative page matrix approved in Phase 0.1. + +That should cover: + +1. Front page. +2. Standard content page. +3. Sidebar or alternate layout page. +4. Search results page. +5. Status-message example. +6. Select-menu page. +7. Alphabetical listing page. +8. Photo gallery carousel page. +9. Date picker page. +10. Publication table page. +11. Login or authentication-related page where practical. +12. Marketing Cloud export route. + +## Proposed Baseline And Gating Strategy + +This repository is a brownfield accessibility project. The workflow should therefore roll out in stages. + +### Stage 1 - Proof Of Concept + +1. Run the scanner against a small patch subset. +2. Confirm that the target environment, URLs, workflow permissions, and result visibility all behave as expected. +3. Do not make the check required yet. + +### Stage 2 - Baseline Creation + +1. Run the scanner against the approved initial subset. +2. Review the findings with maintainers. +3. Decide how existing findings will be treated as baseline debt. +4. Confirm that the cache strategy is stable enough for regression detection. + +### Stage 3 - Required Regression Gate + +1. Turn the workflow into a required PR check for the approved subset. +2. Fail on new serious or critical regressions. +3. Keep moderate and minor findings visible without blocking during the initial enforcement window. + +### Stage 4 - Broader Coverage + +1. Expand to the full minor-release matrix. +2. Add scheduled runs once the basic PR workflow is stable. +3. Add authenticated coverage later only if the environment model is ready. + +## Proposed Finding And Review Policy + +### Blocking Threshold + +Recommended initial threshold: + +1. Block on new serious findings. +2. Block on new critical findings. +3. Record but do not initially block on new moderate or minor findings. + +### Result Visibility + +The workflow should make results easy to interpret in pull requests. + +Recommended behavior: + +1. Post a clear pass or fail result in GitHub Actions. +2. Keep accessibility results distinct from lint and unit-test failures. +3. Link maintainers to the relevant scanner output or findings summary. + +### Scanner-Created Issues + +The GitHub Accessibility Scanner can create GitHub issues for findings. That can be useful, but it can also create noise if enabled too early. + +Recommended position for the first rollout: + +1. Allow the proof of concept and baseline decision to happen before turning on broad issue creation against the main repository. +2. If issue creation is enabled early, use a tightly scoped proof-of-concept subset to avoid flooding the backlog. +3. Do not rely on automatic Copilot assignment in the first rollout. +4. Revisit issue automation after the team is comfortable with the volume and triage pattern. + +## Proposed Manual Verification Handoff + +The automated workflow should end in a clear handoff, not in a false claim that automation is sufficient. + +### Required Manual Checks After Automated Pass + +1. Keyboard-only verification on affected representative pages. +2. Focus visibility review on affected flows. +3. NVDA with Firefox verification for affected flows. +4. NVDA with Chrome verification for affected flows. +5. JAWS with Chrome verification for affected Windows-facing interactive flows. +6. JAWS with Edge verification for affected Windows-facing interactive flows. +7. VoiceOver with Safari on macOS verification for affected flows. +8. VoiceOver with Safari on iOS when the change materially affects mobile interaction. + +### Manual Sign-Off Rule + +Phase 0.2 should define who records the manual acceptance outcome before release. That can be QA, maintainers, Campus Web Services, or another named owner, but the plan should not leave the sign-off role implicit. + +## Proposed Workflow Skeleton + +The implementation should stay simple. The exact YAML can change, but the workflow shape should look roughly like this: + +```yaml +name: Accessibility Scanner + +on: + pull_request: + workflow_dispatch: + inputs: + profile: + description: Scan profile + required: true + default: patch + schedule: + - cron: '0 12 * * 1-5' + +jobs: + accessibility-scan: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Resolve scan profile + run: | + # Select patch or minor URL manifest + + - name: Run GitHub Accessibility Scanner + uses: github/accessibility-scanner@v2 + with: + urls: ${{ steps.resolve.outputs.urls }} + repository: az-digital/az_quickstart + token: ${{ secrets.A11Y_SCANNER_TOKEN }} + cache_key: cached_results-azqs-${{ inputs.profile || 'patch' }}.json + skip_copilot_assignment: true + + - name: Summarize results + run: | + # Make pass or fail status easy to review +``` + +This is only a structural outline. The final implementation should reflect the approved environment model and the approved URL manifests. + +## Dependencies + +Phase 0.2 depends on these decisions being settled: + +1. Which environment will supply live URLs. +2. Which exact URLs belong in the patch profile. +3. Which exact URLs belong in the minor profile. +4. Whether scanner-created issues should be enabled in the main repository immediately or deferred until after the baseline review. +5. Who owns manual verification sign-off. + +## Recommended Deliverables For A11Y P0.2 + +At close, A11Y P0.2 should produce: + +1. One workflow file for the GitHub Accessibility Scanner. +2. One approved patch URL manifest. +3. One approved minor URL manifest. +4. One maintainer-facing readme for interpreting scanner results. +5. One documented baseline and gating policy. +6. One explicit manual-verification handoff rule. +7. One operational document set for URL inventory, manual verification, triage, and sign-off. + +## Estimated Effort + +1. Half a day to settle the environment and URL source model. +2. Half a day to build the first patch subset manifests. +3. Half a day to implement the proof-of-concept workflow. +4. Half a day to review baseline output and tune the rollout. + +The practical estimate is one to two days for a proof-of-concept implementation and policy tuning pass, assuming the live environment question is already settled. + +## Recommended Next Step + +Approve the workflow model in this document, then implement a proof-of-concept GitHub Accessibility Scanner workflow against the patch subset first. + +After that proof of concept, the team should review the output volume, confirm the baseline strategy, and only then turn the check into a required regression gate. \ No newline at end of file diff --git a/ACCESSIBILITY-POST-MEETING-NOTES-TEMPLATE.md b/ACCESSIBILITY-POST-MEETING-NOTES-TEMPLATE.md new file mode 100644 index 0000000000..234e17d6a3 --- /dev/null +++ b/ACCESSIBILITY-POST-MEETING-NOTES-TEMPLATE.md @@ -0,0 +1,127 @@ +# Accessibility Program Post-Meeting Notes Template + +## Purpose + +Use this template to capture the outcomes of the Friday planning meeting for the az_quickstart accessibility program. + +Reference points: + +- Project board: https://github.com/orgs/az-digital/projects/285 +- Umbrella issue: https://github.com/az-digital/az_quickstart/issues/5533 + +## Meeting Details + +- Date: +- Time: +- Facilitator: +- Note taker: +- Attendees: + +## Meeting Objective + +Confirm the scope, decision queue, release direction, and first implementation wave for the az_quickstart accessibility program before implementation begins. + +## Decisions Confirmed + +### Program Scope + +- Confirmed: +- Adjusted: +- Out of scope: + +### Release Direction + +- Patch-release candidates: +- Minor-release candidates: +- Still undecided: + +### Verification Direction + +- Representative page matrix: +- Assistive-technology matrix: +- Regression gate expectations: +- Manual verification expectations: +- Preliminary Phase 0 docs adopted as working direction for [#5541](https://github.com/az-digital/az_quickstart/issues/5541) and [#5539](https://github.com/az-digital/az_quickstart/issues/5539): +- Docs that remain provisional after the meeting: + +### First Implementation Wave + +- Approved first-wave issues: +- Dependencies before work starts: +- Explicit non-starters for now: + +## Issue-Level Outcomes + +Use this section to capture direct outcomes for the Friday decision queue. + +### [#5533](https://github.com/az-digital/az_quickstart/issues/5533) - Umbrella Program Issue + +- Outcome: +- Follow-up needed: + +### [#5541](https://github.com/az-digital/az_quickstart/issues/5541) - Verification Policy Spike + +- Outcome: +- Follow-up needed: + +### [#5539](https://github.com/az-digital/az_quickstart/issues/5539) - Accessibility Regression Gate Task + +- Outcome: +- Follow-up needed: + +### [#5550](https://github.com/az-digital/az_quickstart/issues/5550) - Marketing Cloud Export Route Decision + +- Outcome: +- Follow-up needed: + +### [#5544](https://github.com/az-digital/az_quickstart/issues/5544) - Gallery Carousel Direction + +- Outcome: +- Follow-up needed: + +### [#5545](https://github.com/az-digital/az_quickstart/issues/5545) - Date Picker Direction + +- Outcome: +- Follow-up needed: + +## Metadata Updates Required After the Meeting + +- Issues to remove `needs discussion` from: +- Issues to keep as `Release Target = Undecided`: +- Issues to change to `Release Target = Patch`: +- Issues to change to `Release Target = Minor`: +- Issues to move to `Needs Verification` later: +- Board status changes needed: + +## Ownership and Follow-Up + +- Program owner: +- Board and metadata owner: +- Phase 0 owner: +- First-wave engineering owner(s): +- Verification owner(s): + +## Open Questions + +- +- +- + +## Deferred Items + +- +- +- + +## Communication Actions + +- Meeting summary to send: +- Stakeholders to notify: +- Docs to update: +- GitHub issues to update: + +## Go / No-Go for Implementation Planning + +- Decision: +- Conditions that must still be met: +- Earliest expected next planning checkpoint: \ No newline at end of file diff --git a/ACCESSIBILITY-PROGRAM-EMAIL-DRAFT.md b/ACCESSIBILITY-PROGRAM-EMAIL-DRAFT.md new file mode 100644 index 0000000000..a1c2ddecb4 --- /dev/null +++ b/ACCESSIBILITY-PROGRAM-EMAIL-DRAFT.md @@ -0,0 +1,63 @@ +# Email Draft - Accessibility Planning Work Completed Today + +## Subject Line Options + +1. Accessibility planning and GitHub program setup completed for az_quickstart +2. az_quickstart accessibility program is now organized for Friday review +3. WCAG 2.2 AA planning artifacts and GitHub dashboard are ready for Friday discussion + +## Email Draft + +Hello team, + +I completed the accessibility planning and GitHub organization work for the az_quickstart WCAG 2.2 AA effort today. + +The main outcome is that the work is now structured as a program rather than a flat list of defects. That means we have a clear umbrella issue, phase-based parent issues, delivery issues grouped by area, and a GitHub project board that can support Friday's discussion without starting implementation work yet. + +What is now in place: + +- A source-level accessibility review and remediation plan in GitHub: + - https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-REVIEW-PLAN.md +- A GitHub execution plan with issue structure and phase logic: + - https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-GITHUB-PROJECT-PLAN.md +- A live GitHub project board: + - https://github.com/orgs/az-digital/projects/285 +- An umbrella program issue: + - https://github.com/az-digital/az_quickstart/issues/5533 + +The issue hierarchy is already created in GitHub and organized into these phases: + +- Phase 0: Accessibility guardrails and verification setup +- Phase 1: Global user experience blockers +- Phase 2: High-risk interactive components +- Phase 3: Content and template semantics +- Phase 4: Verification and release readiness + +The existing Slick accessibility issue https://github.com/az-digital/az_quickstart/issues/5514 was reused inside the program rather than duplicated, so the current carousel work remains connected to the broader effort. + +I also prepared supporting documents for Friday: + +- Meeting agenda: + - https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-FRIDAY-MEETING-AGENDA.md +- Recommended project views and manual setup guide: + - https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-PROJECT-VIEWS-HANDOFF.md +- Facilitator script: + - https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-FRIDAY-FACILITATOR-SCRIPT.md +- Consolidated send-out brief: + - https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-SENDOUT-BRIEF.md + +One limitation to note: GitHub Projects v2 does not currently expose saved view creation through the available automation surface, so the board itself is created and populated, but the recommended saved views still need to be created manually in the GitHub UI. I documented the exact view definitions in the handoff note above. + +From a content and product perspective, I do not think the issue descriptions need a major rewrite before Friday. They already explain the user goal, the current friction, why the problem matters, and what success looks like. If we want to polish them further after the meeting, the best optional improvement would be to add a short `Who is affected` and `How we will know this is better` line to the highest-priority issues. + +For Friday, I recommend we focus the discussion on: + +1. Confirming the release and verification decisions that affect scope. +2. Confirming which issues are safe patch candidates versus minor-release work. +3. Confirming the first implementation wave, without starting execution yet. + +This message is ready to send as written. The board remains a program-level GitHub asset, and the supporting documents are published from the dedicated planning branch so the links are browser-accessible in GitHub. + +Thanks, + +Jeff \ No newline at end of file diff --git a/ACCESSIBILITY-PROJECT-VIEWS-HANDOFF.md b/ACCESSIBILITY-PROJECT-VIEWS-HANDOFF.md new file mode 100644 index 0000000000..3f44a03a82 --- /dev/null +++ b/ACCESSIBILITY-PROJECT-VIEWS-HANDOFF.md @@ -0,0 +1,174 @@ +# Accessibility Project Views Handoff + +## Purpose + +This document defines the recommended saved views for the GitHub project board used by the az_quickstart accessibility program. + +Project board: + +- [Accessibility Program - az_quickstart](https://github.com/orgs/az-digital/projects/285) + +## Important Limitation + +GitHub Projects v2 currently exposes saved views as readable through the available CLI and GraphQL tooling, but not writable. That means these views could not be created programmatically through the available agent tools. + +The board and issue metadata are in place. The views below should be created manually in the GitHub project UI. + +## Recommended Views + +### 1. Phase View + +Purpose: + +Use this as the main planning view for Friday. It gives a full-program view grouped by phase. + +Recommended configuration: + +- Layout: Table or Board +- Group by: `Phase` +- Sort by: `Priority`, then `Status` +- Visible fields: + - Title + - Phase + - Priority + - User Impact + - Release Target + - Status + +Recommended use: + +Use this view when discussing whether the work is sequenced correctly. + +### 2. Patch Candidates + +Purpose: + +Show only issues that are currently positioned as likely patch-release work. + +Recommended configuration: + +- Layout: Table +- Filter: `Release Target` is `Patch` +- Sort by: `Priority`, then `Phase` +- Visible fields: + - Title + - Phase + - Priority + - User Impact + - Verification Type + - Status + +Recommended use: + +Use this view when deciding what is low-risk enough to include in short-term delivery. + +### 3. Needs Decision + +Purpose: + +Show the issues that need explicit discussion before implementation should begin. + +Recommended configuration: + +- Layout: Table +- Filter recommendation: + - `Release Target` is `Undecided` + - Or issue label contains `needs discussion` + - Or issue is a spike +- Sort by: `Priority`, then `Phase` +- Visible fields: + - Title + - Phase + - Priority + - Release Target + - Status + +Recommended use: + +Use this view for Friday triage and scope-confirmation discussions. + +Note: + +This view will work better if the team consistently uses `needs discussion` on issues that require an explicit decision. + +### 4. Verification Queue + +Purpose: + +Show the items that require planned validation and release-readiness checks. + +Recommended configuration: + +- Layout: Table +- Preferred filter: + - `Status` is `Needs Verification` + - Optional secondary filter: `Verification Type` is `Manual` or `Both` +- Sort by: `Phase`, then `Priority` +- Visible fields: + - Title + - Phase + - Verification Type + - Priority + - Status + +Recommended use: + +Use this view near release planning or whenever the team is preparing manual validation. + +Note: + +This view becomes most useful once items begin moving into `Needs Verification`. + +### 5. Leadership Summary + +Purpose: + +Provide a concise view for non-engineering stakeholders who want status and impact rather than implementation detail. + +Recommended configuration: + +- Layout: Table +- Filter: none required +- Sort by: `Priority`, then `Phase` +- Visible fields: + - Title + - Phase + - Priority + - User Impact + - Release Target + - Status + +Recommended use: + +Use this view when summarizing program status, scope, and release direction for leadership or product stakeholders. + +## Suggested Metadata Hygiene Before and After Friday + +To make the views more useful, consider the following light governance steps: + +1. Use `needs discussion` only on issues that truly require Friday decisions. +2. Move issues into `Needs Verification` only when they are actually ready for manual or release-gate validation. +3. Keep `Release Target` current so the Patch Candidates view stays trustworthy. +4. Keep `User Impact` and `Priority` aligned so the Leadership Summary view remains useful. + +## Current Friday Decision Queue + +The following issues are the current recommended Friday discussion queue and now carry the `needs discussion` label: + +1. [#5533 - A11Y Program: WCAG 2.2 AA accessibility remediation for az_quickstart](https://github.com/az-digital/az_quickstart/issues/5533) +2. [#5541 - A11Y P0.1: Define representative page coverage and verification policy for accessibility testing](https://github.com/az-digital/az_quickstart/issues/5541) +3. [#5550 - A11Y P3.3: Decide whether Marketing Cloud export routes are fragments or full browser-facing pages](https://github.com/az-digital/az_quickstart/issues/5550) +4. [#5544 - A11Y P2.4: Make photo gallery carousels understandable to screen-reader and keyboard users](https://github.com/az-digital/az_quickstart/issues/5544) +5. [#5545 - A11Y P2.6: Make the calendar picker behave in a familiar way for keyboard and screen-reader users](https://github.com/az-digital/az_quickstart/issues/5545) + +These items are also set to `Release Target = Undecided` on the project board so they stand out as genuine decision items rather than implied implementation commitments. + +## Suggested Friday Core View Set + +If the team only creates a few saved views before Friday, create these first: + +1. Phase View +2. Needs Decision +3. Patch Candidates + +Those three views will support the most important planning conversations. \ No newline at end of file diff --git a/ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md b/ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md new file mode 100644 index 0000000000..c2aeb58508 --- /dev/null +++ b/ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md @@ -0,0 +1,102 @@ +# Accessibility Release Sign-Off Checklist + +## Purpose + +This checklist is the release-time record for accessibility verification, sign-off, and unresolved risk. It is intended to be used after the automated scanner run and after manual verification has been completed for the approved release scope. + +Use this document together with: + +1. [ACCESSIBILITY-P0.1-VERIFICATION-PROPOSAL.md](ACCESSIBILITY-P0.1-VERIFICATION-PROPOSAL.md) +2. [ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md](ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md) +3. [ACCESSIBILITY-MANUAL-VERIFICATION-PLAYBOOK.md](ACCESSIBILITY-MANUAL-VERIFICATION-PLAYBOOK.md) +4. [ACCESSIBILITY-SCANNER-TRIAGE-GUIDE.md](ACCESSIBILITY-SCANNER-TRIAGE-GUIDE.md) +5. [ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md](ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md) + +## Release Metadata + +- Release name: +- Release type: patch or minor +- Branch: +- Environment reviewed: +- Release owner: +- Verification owner: +- Date: + +## Automated Verification Checklist + +- [ ] The approved scan profile was used. +- [ ] The approved representative URLs were used. +- [ ] The GitHub Accessibility Scanner run completed successfully. +- [ ] New critical findings were reviewed. +- [ ] New serious findings were reviewed. +- [ ] Moderate and minor findings were reviewed for visibility even if they were not blocking. +- [ ] Workflow or environment failures were separated from true accessibility findings. + +## Manual Verification Checklist + +- [ ] Keyboard-only verification completed for all required representative pages in scope. +- [ ] Focus visibility review completed at 100 percent and 200 percent zoom. +- [ ] NVDA with Firefox checks completed for affected flows. +- [ ] NVDA with Chrome checks completed for affected flows. +- [ ] JAWS with Chrome checks completed for affected Windows-facing flows. +- [ ] JAWS with Edge checks completed for affected Windows-facing flows. +- [ ] VoiceOver with Safari on macOS checks completed for affected flows. +- [ ] VoiceOver with Safari on iOS checks completed when mobile interaction was in scope. +- [ ] TalkBack with Chrome checks completed when mobile forms, navigation, or media behavior changed. + +## Flow Coverage Checklist + +Mark only the flows that were in scope for the release. + +- [ ] Global shell and skip-link behavior reviewed. +- [ ] Search and pager controls reviewed. +- [ ] Status-message behavior reviewed. +- [ ] Select-menu block reviewed. +- [ ] Accordion behavior reviewed. +- [ ] Alphabetical listing reviewed. +- [ ] Photo gallery carousel reviewed. +- [ ] Date picker reviewed. +- [ ] Publication tables reviewed. +- [ ] Marketing Cloud layouts reviewed. +- [ ] Marketing Cloud export route reviewed. +- [ ] Authentication-related flow reviewed. + +## Sign-Off Decision + +- Decision: go, conditional go, or no-go +- Summary of decision: +- Conditions that still must be met: + +## Approvals + +- Engineering owner: +- Verification owner: +- Release owner: +- Product or stakeholder acknowledgment if required: + +## Risk Log + +The following table records unresolved risks, blocked verification, or accepted debt that decision-makers reviewed before release. + +| Risk ID | Representative page or flow | Severity | Description | Mitigation or follow-up | Owner | Release impact | +|---------|-----------------------------|----------|-------------|-------------------------|-------|----------------| +| R1 | | | | | | | +| R2 | | | | | | | +| R3 | | | | | | | + +## Issues And Follow-Up Actions + +- Related GitHub issues: +- Issues opened during verification: +- Issues updated during verification: +- Follow-up work required after release: + +## Notes For Maintainers + +1. A pass is not the absence of scanner output. A pass means the scanner output was triaged and the manual checks required by scope were completed. +2. A conditional go should always include a recorded risk and named owner. +3. A no-go should identify whether the blocker is a new regression, unresolved baseline risk, or missing verification. + +## Recommended Next Step + +Create a copy of this checklist for each release verification window and keep it linked from the release planning notes or board card so accessibility sign-off is visible rather than informal. \ No newline at end of file diff --git a/ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md b/ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md new file mode 100644 index 0000000000..03380ba805 --- /dev/null +++ b/ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md @@ -0,0 +1,80 @@ +# Representative URL Inventory And Environment Map + +## Purpose + +This document turns the representative page matrix into an operational inventory for scanner setup, manual verification, and release planning. + +Because the planning package is documentation-only at this stage, some entries below intentionally use page types, route patterns, or selection rules rather than final live URLs. The goal is to make the inventory actionable now and easy to finalize once the team confirms the scan environment. + +## How To Use This Document + +1. Select the approved environment for the scan run. +2. Replace each placeholder route or selection rule with a final approved live URL. +3. Mark whether the page belongs in the patch profile, minor profile, or both. +4. Use the final URL set to populate the scanner manifest files described in [ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md](ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md). + +## Environment Map + +The table below describes the intended use of each environment in the rollout plan. + +| Environment | Intended use | Suitable for scanner | Branch fidelity | Authentication support | Current planning status | +|-------------|--------------|----------------------|-----------------|------------------------|-------------------------| +| Pull request preview environment | Preferred target for PR validation | Yes | High | Depends on preview platform | Preferred but not yet confirmed | +| Shared staging environment | Fallback target for proof of concept and baseline creation | Yes | Medium | Depends on staging access model | Acceptable fallback | +| Default-branch baseline environment | Stable target for scheduled scans | Yes | Low for PRs, high for default branch drift tracking | Depends on deployment model | Likely useful after rollout | +| Local development environment | Developer reproduction and spot checks | No for the primary scanner plan | High for local code, low for shared verification | Varies | Not the primary scanner target | + +## Representative Inventory + +The table below lists the recommended page types and the role each one plays in the verification model. + +| ID | Page type | Candidate route pattern or selection rule | Primary coverage reason | Patch profile | Minor profile | Authentication needed | Status | +|----|-----------|-------------------------------------------|-------------------------|---------------|---------------|-----------------------|--------| +| R1 | Front page | `/` or the primary site landing page | Global shell, navigation, skip-link behavior | Yes | Yes | No | Needs final live URL | +| R2 | Standard content page | Any published content page using the default main-content shell | Main landmark behavior, standard content flow | Yes | Yes | No | Needs named example | +| R3 | Sidebar or alternate layout page | Any published page with sidebar or alternate layout regions | Layout-region variation and focus continuity | No | Yes | No | Needs named example | +| R4 | Search results page | Site search results page with pager controls | Search submit naming and pager semantics | Yes | Yes | No | Needs named example | +| R5 | Status-message example | Any page that can reliably produce success and error feedback | Live-region urgency and message duplication | Yes | Yes | No | Needs agreed test page | +| R6 | Select-menu page | Any page that embeds the az_select_menu block | Custom widget state, validation, and focus | No unless directly affected | Yes | No | Needs named example | +| R7 | Alphabetical listing page | Page using the Quickstart Alphabetical Listing view | Filter announcements and A to Z focus handoff | No unless directly affected | Yes | No | Needs named example | +| R8 | Photo gallery carousel page | Page using the photo gallery carousel paragraph type | Carousel naming, slide state, keyboard reachability | No unless directly affected | Yes | No | Needs named example | +| R9 | Date picker page | Event page or equivalent page that exposes the calendar picker | Date picker semantics, announcement behavior, focus visibility | No unless directly affected | Yes | No | Needs named example | +| R10 | Publication table page | `/publications` or an equivalent publication table page | Table caption, row and column context | No unless directly affected | Yes | No | Candidate route exists but needs confirmation | +| R11 | Authentication-related page | Approved login or authentication-related flow | Keyboard access, field naming, error recovery | No unless directly affected | Yes where practical | Likely yes | Needs environment decision | +| R12 | Marketing Cloud export route | Approved browser-facing or candidate export route | Export semantics and page-level context | No unless directly affected | Yes | Possibly no | Needs explicit route decision | + +## Patch Profile Recommendation + +The default patch profile should include: + +1. R1 - Front page. +2. R2 - Standard content page. +3. R4 - Search results page. +4. R5 - Status-message example. +5. Every additional representative page directly affected by the release. + +## Minor-Release Profile Recommendation + +The minor-release profile should include the full approved set of representative pages R1 through R12, except where the team explicitly documents that an item is not currently testable in the chosen environment. + +## Page Selection Rules + +Use these rules when choosing the final live URL for each row: + +1. Prefer stable, published examples over temporary content. +2. Prefer examples that reliably reproduce the component or behavior under review. +3. Avoid URLs that depend on one-time editorial state or expiring content when a more stable option exists. +4. If multiple pages expose the same behavior, prefer the one with the simplest surrounding layout unless the surrounding layout is part of the risk. + +## Open Decisions + +The following decisions still need explicit confirmation before the inventory becomes final: + +1. Which environment will provide the live URLs for scanner runs. +2. Which exact page instance should serve as the status-message example. +3. Which authentication-related flow is safe and practical to use as a representative page. +4. Whether the Marketing Cloud export route should be treated as browser-facing for full representative coverage. + +## Recommended Next Step + +Use this document to finalize the first approved URL set, then convert the approved URLs into the patch and minor manifest files described in the Phase 0.2 workflow plan. \ No newline at end of file diff --git a/ACCESSIBILITY-REVIEW-PLAN.md b/ACCESSIBILITY-REVIEW-PLAN.md new file mode 100644 index 0000000000..d1acbb34f3 --- /dev/null +++ b/ACCESSIBILITY-REVIEW-PLAN.md @@ -0,0 +1,229 @@ +# Accessibility Review and WCAG 2.2 AA Remediation Plan for az_quickstart + +## Audit Information + +This document captures a source-level accessibility review of az_quickstart and a prioritized remediation plan for reaching and maintaining WCAG 2.2 AA conformance. + +- Audit date: April 23, 2026 +- Auditor: GitHub Copilot +- Repository scope: custom theme, custom modules, project templates, CI configuration, and accessibility-related frontend assets across az_quickstart +- Review method: targeted source inspection, project-wide pattern searches, and a secondary specialist pass focused on Drupal frontend accessibility risks + +This was a code review, not a rendered-site certification. No browser automation, no screen-reader session, and no manual keyboard walkthrough were executed against a running site during this pass. That means this document identifies confirmed code-level risks and the work required to verify runtime behavior, but it does not prove that no accessibility issues exist. + +For a GitHub-ready execution structure, phased issue set, and product-oriented issue framing, see [ACCESSIBILITY-GITHUB-PROJECT-PLAN.md](ACCESSIBILITY-GITHUB-PROJECT-PLAN.md). + +The live GitHub program artifacts are now available at: + +- [Accessibility Program - az_quickstart project board](https://github.com/orgs/az-digital/projects/285) +- [#5533 - A11Y Program: WCAG 2.2 AA accessibility remediation for az_quickstart](https://github.com/az-digital/az_quickstart/issues/5533) + +## Executive Summary + +az_quickstart is not currently ready for a WCAG 2.2 AA conformance claim. + +The most important problems are systemic rather than isolated. The current codebase has issues in page bypass navigation, accessible names for core controls, dynamic announcements, focus management, carousel behavior, custom widget semantics, and regression prevention. Those problems affect global navigation, search, filtering, carousels, accordion behavior, custom select navigation, the date picker, admin tables, and Marketing Cloud export templates. + +The project also lacks an accessibility regression gate in CI. That is not itself a WCAG failure, but it is the main reason accessibility fixes will not remain fixed unless the team changes how the project is verified. + +The highest-value sequence is: + +1. Fix the global blockers that affect most pages and most users. +2. Repair the custom widgets that currently drift out of sync with assistive technology. +3. Clean up template semantics in tables, exports, and image-driven layouts. +4. Add automated and manual accessibility verification so the project can credibly maintain compliance. + +## Confirmed Findings in Impact Order + +1. The skip link target is not reliably present on standard pages. Severity: serious. Confidence: medium. WCAG: 2.4.1 Bypass Blocks. Evidence: [themes/custom/az_barrio/templates/layout/html.html.twig](themes/custom/az_barrio/templates/layout/html.html.twig#L44), [themes/custom/az_barrio/templates/layout/page.html.twig](themes/custom/az_barrio/templates/layout/page.html.twig#L194). The site-wide skip link points to `#content`, but the standard page template does not define a stable matching main-content target in the reviewed source. Keyboard users can be forced through repeated header and navigation content before they reach primary content. Fix by creating one canonical target on every page, preferably `id="main-content"` on the main landmark with `tabindex="-1"`, and update the skip link to point to that exact element. + +2. The site search submit button is rendered as an icon-only control without an accessible name. Severity: serious. Confidence: high. WCAG: 1.1.1 Non-text Content and 4.1.2 Name, Role, Value. Evidence: [themes/custom/az_barrio/templates/forms/input--search-block-form--submit.html.twig](themes/custom/az_barrio/templates/forms/input--search-block-form--submit.html.twig#L13), [themes/custom/az_barrio/templates/forms/input--search.html.twig](themes/custom/az_barrio/templates/forms/input--search.html.twig#L13). The search input has an accessible name, but the submit control becomes a button that only contains a search icon. Screen-reader and speech-input users can encounter an unnamed action at a core site entry point. Fix by adding visible text or an explicit `aria-label` on the submit button. + +3. The custom select-menu widget exposes invalid and contradictory accessibility state. Severity: serious. Confidence: high. WCAG: 3.3.1 Error Identification and 4.1.2 Name, Role, Value. Evidence: [modules/custom/az_select_menu/src/Plugin/Block/AzSelectMenu.php](modules/custom/az_select_menu/src/Plugin/Block/AzSelectMenu.php#L136), [modules/custom/az_select_menu/src/Plugin/Block/AzSelectMenu.php](modules/custom/az_select_menu/src/Plugin/Block/AzSelectMenu.php#L150), [modules/custom/az_select_menu/js/az-select-menu.js](modules/custom/az_select_menu/js/az-select-menu.js#L68), [modules/custom/az_select_menu/js/az-select-menu.js](modules/custom/az_select_menu/js/az-select-menu.js#L94). The widget uses a popover for error feedback, keeps `aria-invalid="false"`, and sets `aria-disabled="true"` on the select when the empty option is selected without clearly restoring the real state when a valid option is chosen. Users can be told the control is disabled or receive a visual-only error without a programmatic relationship to the field. Fix by rendering persistent inline error text, toggling `aria-invalid`, linking the message with `aria-describedby` or `aria-errormessage`, and removing incorrect disabled state from the select. + +4. The accordion template has broken ARIA relationships. Severity: serious. Confidence: high. WCAG: 1.3.1 Info and Relationships and 4.1.2 Name, Role, Value. Evidence: [modules/custom/az_accordion/templates/az-accordion.html.twig](modules/custom/az_accordion/templates/az-accordion.html.twig#L19), [modules/custom/az_accordion/templates/az-accordion.html.twig](modules/custom/az_accordion/templates/az-accordion.html.twig#L25). Each panel points `aria-labelledby` to its own panel ID instead of the trigger button, and `data-bs-parent` points back to the item rather than the accordion container. That breaks the naming relationship between trigger and region and makes assistive technology output less reliable. Fix by assigning a unique ID to the button, referencing that ID from the panel, and setting `data-bs-parent` to the accordion container. + +5. Hidden Slick slides can permanently lose keyboard access after the a11y patch runs. Severity: serious. Confidence: high. WCAG: 2.1.1 Keyboard and 2.4.3 Focus Order. Evidence: [themes/custom/az_barrio/js/slick-a11y-patch.js](themes/custom/az_barrio/js/slick-a11y-patch.js#L30), [themes/custom/az_barrio/js/slick-a11y-patch.js](themes/custom/az_barrio/js/slick-a11y-patch.js#L34). The patch removes descendants of hidden slides from the tab order, but it does not restore prior focusability when those slides become visible later. Keyboard users can lose access to links and buttons inside carousel content. Fix by storing original tabindex values and recalculating focusability on every slide change. + +6. The photo-gallery carousel does not expose enough structure or state to assistive technology. Severity: serious. Confidence: high. WCAG: 1.3.1 Info and Relationships, 2.4.6 Headings and Labels, and 4.1.2 Name, Role, Value. Evidence: [modules/custom/az_paragraphs/az_paragraphs_photo_gallery/templates/photo-gallery-carousel.html.twig](modules/custom/az_paragraphs/az_paragraphs_photo_gallery/templates/photo-gallery-carousel.html.twig), [modules/custom/az_paragraphs/az_paragraphs_photo_gallery/templates/slider-gallery.html.twig](modules/custom/az_paragraphs/az_paragraphs_photo_gallery/templates/slider-gallery.html.twig). Previous and next controls have basic hidden text, but the carousel itself has no accessible name, slides are not identified as slides, and there is no active-slide announcement. Screen-reader users can move through the widget without reliable orientation. Fix by naming the carousel, giving slides explicit position labels such as "Slide X of Y," and exposing active-slide changes through synchronized state or a polite live region. + +7. The vendored date picker uses `role="application"` and assertive live regions for routine navigation. Severity: serious. Confidence: high. WCAG: 4.1.2 Name, Role, Value and 4.1.3 Status Messages. Evidence: [modules/custom/az_core/lib/vanilla-calendar-pro/index.js](modules/custom/az_core/lib/vanilla-calendar-pro/index.js#L2), [modules/custom/az_core/lib/vanilla-calendar-pro/index.mjs](modules/custom/az_core/lib/vanilla-calendar-pro/index.mjs#L2). The calendar root uses application mode, and the dates, months, and years views announce normal navigation with `aria-live="assertive"`. That can suppress familiar browse-mode behavior and create excessive interruption. Fix by removing `role="application"`, using standard grid or dialog semantics, and moving non-urgent updates to polite announcements. + +8. The alphabetical listing filter updates are silent to assistive technology. Severity: serious. Confidence: high. WCAG: 4.1.3 Status Messages. Evidence: [modules/custom/az_alphabetical_listing/templates/views-view--az-alphabetical-listing.html.twig](modules/custom/az_alphabetical_listing/templates/views-view--az-alphabetical-listing.html.twig#L101), [modules/custom/az_alphabetical_listing/js/alphabetical_listing.js](modules/custom/az_alphabetical_listing/js/alphabetical_listing.js#L114). Search results are hidden and shown dynamically, and the no-results panel toggles visually, but there is no persistent live region communicating the current result state. Screen-reader users may not know that filtering occurred or whether results remain. Fix by adding an always-mounted polite status region that announces result counts and the no-results condition. + +9. The alphabetical listing A to Z jump behavior scrolls visually but does not move focus. Severity: serious. Confidence: high. WCAG: 2.4.3 Focus Order and 2.4.7 Focus Visible. Evidence: [modules/custom/az_alphabetical_listing/js/alphabetical_listing.js](modules/custom/az_alphabetical_listing/js/alphabetical_listing.js#L151). The script intercepts native anchor behavior, animates the scroll, and updates the hash, but leaves focus on the alphabet control. Keyboard and screen-reader users do not land in the destination context after activation. Fix by either allowing native anchor behavior or moving focus to the destination heading after scroll completion. + +10. Routine status messages are announced too aggressively. Severity: serious. Confidence: high. WCAG: 4.1.3 Status Messages. Evidence: [themes/custom/az_barrio/js/toasts.js](themes/custom/az_barrio/js/toasts.js#L41), [themes/custom/az_barrio/js/toasts.js](themes/custom/az_barrio/js/toasts.js#L95). The alert path always uses `role="alert"`, and the toast path always uses `aria-live="assertive"`, even for ordinary status and info messages. This interrupts screen-reader users unnecessarily and makes urgent messages harder to distinguish. Fix by using polite announcements for routine feedback and reserving alerts for urgent failures and warnings. + +11. Pager landmarks are named with an internal ID token instead of a human-readable label. Severity: moderate. Confidence: high. WCAG: 1.3.1 Info and Relationships and 2.4.6 Headings and Labels. Evidence: [themes/custom/az_barrio/templates/navigation/pager.html.twig](themes/custom/az_barrio/templates/navigation/pager.html.twig#L36), [themes/custom/az_barrio/templates/views/views-mini-pager.html.twig](themes/custom/az_barrio/templates/views/views-mini-pager.html.twig#L16). The navigation elements use `aria-label="{{ heading_id }}"`, which names the landmark with an ID token instead of meaningful text. That reduces landmark usability for screen-reader navigation. Fix by changing to `aria-labelledby="{{ heading_id }}"` or a literal readable label such as `Pagination`. + +12. The select-menu CSS removes default focus indication without a robust replacement. Severity: moderate. Confidence: high. WCAG: 1.4.11 Non-text Contrast and 2.4.7 Focus Visible. Evidence: [modules/custom/az_select_menu/css/az-select-menu.css](modules/custom/az_select_menu/css/az-select-menu.css#L45). The control removes the outline and relies on a bottom-border color change that is weaker than a dedicated focus ring. Keyboard users can struggle to locate the focused control. Fix by restoring a visible `:focus-visible` ring with sufficient contrast and preserving a clear control boundary. + +13. The publication type table relies on implicit semantics and has no caption. Severity: serious. Confidence: high. WCAG: 1.3.1 Info and Relationships. Evidence: [modules/custom/az_publication/templates/az-publication-type-listing-table.html.twig](modules/custom/az_publication/templates/az-publication-type-listing-table.html.twig#L19). The table has column headers, but no caption and no row header for the primary label cell. That weakens context for screen-reader users moving across rows and operations. Fix by adding a caption, explicit scopes for column headers where needed, and a row header cell for the publication type label. + +14. Marketing Cloud image-driven layouts hard-code empty alt text on content images. Severity: serious. Confidence: high. WCAG: 1.1.1 Non-text Content. Evidence: [modules/custom/az_marketing_cloud/templates/node--view--az-marketing-cloud--hero-layout.html.twig](modules/custom/az_marketing_cloud/templates/node--view--az-marketing-cloud--hero-layout.html.twig#L81), [modules/custom/az_marketing_cloud/templates/node--view--az-marketing-cloud--30-70-layout.html.twig](modules/custom/az_marketing_cloud/templates/node--view--az-marketing-cloud--30-70-layout.html.twig#L86), [modules/custom/az_marketing_cloud/templates/node--view--az-marketing-cloud--50-50-layout.html.twig](modules/custom/az_marketing_cloud/templates/node--view--az-marketing-cloud--50-50-layout.html.twig#L86), [modules/custom/az_marketing_cloud/templates/node--view--az-marketing-cloud--50-50-layout-image-right.html.twig](modules/custom/az_marketing_cloud/templates/node--view--az-marketing-cloud--50-50-layout-image-right.html.twig#L86), [modules/custom/az_marketing_cloud/templates/node--view--az-marketing-cloud--70-30-layout-image-right.html.twig](modules/custom/az_marketing_cloud/templates/node--view--az-marketing-cloud--70-30-layout-image-right.html.twig#L86). If those images carry real content or context, they are currently hidden from assistive technology. Fix by threading through author-provided media alt text and only using `alt=""` for explicitly decorative assets. + +15. The Marketing Cloud export HTML shell strips document-level semantics. Severity: moderate. Confidence: medium. WCAG: 2.4.2 Page Titled, 2.4.1 Bypass Blocks, and 3.1.1 Language of Page. Evidence: [modules/custom/az_marketing_cloud/templates/html--export--marketing-cloud.html.twig](modules/custom/az_marketing_cloud/templates/html--export--marketing-cloud.html.twig#L1). The HTML template outputs only `page.content`, which means browser-facing export routes can lose the normal document shell and page-level landmarks. If these routes are opened directly, assistive technology users get a degraded navigation model. Fix by either rendering a minimal document shell for browser-facing routes or ensuring these templates are only used as fragments outside normal browser navigation. + +16. The project has no explicit accessibility regression gate. Severity: program risk. Confidence: high. Evidence: [package.json](package.json), [.github/workflows/ci.yml](.github/workflows/ci.yml). The current toolchain covers linting, PHP static analysis, security, and PHPUnit, but no accessibility scanning or keyboard or assistive-technology verification. This is the main reason WCAG defects can re-enter the codebase after remediation. Fix by adding automated page-level accessibility checks and a required manual verification matrix for high-risk interactions. + +## Additional Audit Areas That Still Need Runtime Verification + +The following areas were not proven broken from source alone, but they are high-priority verification targets because they map to WCAG 2.2 AA risk areas or depend on content authors and runtime behavior. + +1. Drag-and-drop and reorder workflows. The project includes draggable ordering flows such as carousel reordering through DraggableViews. Those flows must be checked for WCAG 2.5.7 Dragging Movements and keyboard alternatives. + +2. Authentication and password-management compatibility. CAS and login-related flows should be tested for WCAG 3.3.8 Accessible Authentication - Minimum, including support for paste, password managers, passkeys if available, and recovery flows. + +3. Audio and video content governance. The codebase supports local audio, local video, remote video, and consent-gated embeds. Captions, transcripts, autoplay behavior, and player control accessibility must be verified with real content. + +4. Background-image usage. [modules/custom/az_media/templates/az-responsive-background-image.html.twig](modules/custom/az_media/templates/az-responsive-background-image.html.twig) is safe only when images are decorative. Any meaningful content conveyed through CSS backgrounds will fail non-text alternatives. + +5. Stretched-link patterns in card and ranking components. [modules/custom/az_card/templates/az-card.html.twig](modules/custom/az_card/templates/az-card.html.twig#L46) and similar templates should be checked with a screen reader to confirm link purpose, duplicate-link behavior, and accessible-name outcomes in all editor configurations. + +## Prioritized Remediation Plan + +### Phase 0 - Establish the Accessibility Gate + +This phase should begin immediately and run in parallel with code remediation. It is the only way to turn this review from a one-time cleanup into an ongoing compliance practice. + +1. Add automated accessibility scanning to CI. The recommended baseline is the GitHub Accessibility Scanner against a representative page matrix of live URLs, because the project already uses GitHub Actions and the scanner can surface findings directly in GitHub for maintainers. +2. Define the manual assistive-technology matrix: NVDA with Firefox, NVDA with Chrome, JAWS with Chrome, JAWS with Edge, VoiceOver with Safari on macOS, VoiceOver with Safari on iOS, and TalkBack with Chrome on Android where mobile interaction is important. +3. Add accessibility acceptance criteria to custom widget work. Every widget fix should ship with keyboard, focus, name, state, and announcement checks. +4. Create a regression policy: no merge for new serious or critical accessibility issues on representative pages. + +### Phase 1 - Fix Global Blockers First + +These changes affect the largest number of pages and users. + +1. Repair skip navigation and the main landmark target in the page shell. +2. Give the global search submit button an accessible name. +3. Fix pager landmark naming in both full and mini pagers. +4. Review global message rendering so routine status feedback is polite and urgent alerts stay urgent. + +### Phase 2 - Repair Custom Widgets That Drift Out of Sync With Assistive Technology + +These are the highest-risk component-level issues because they can block keyboard and screen-reader use even when the surrounding page is otherwise sound. + +1. Rebuild the select-menu widget so validation, error messaging, focus styling, and accessibility state are consistent. +2. Correct accordion trigger and panel relationships. +3. Fix Slick slide focus restoration across initialization and slide changes. +4. Upgrade the photo-gallery carousel with a carousel name, slide naming, and state announcement. +5. Replace the date picker's application mode and assertive live-region strategy with standard grid or dialog behavior. +6. Strengthen date-picker focus visibility in light themes. + +### Phase 3 - Fix Dynamic Content, Filtering, and Focus Handoffs + +These items are especially important for screen-reader users and keyboard-only users because the UI changes without a full page reload. + +1. Add a persistent polite results status region to the alphabetical listing. +2. Move focus to the destination section after A to Z navigation or allow native anchor behavior. +3. Audit other AJAX or dynamically updated components for status-message behavior, especially search and filter interfaces. + +### Phase 4 - Correct Content and Template Semantics + +These issues are narrower in scope than the widget problems, but they are still required for WCAG 2.2 AA. + +1. Add caption and row-header semantics to publication tables and any similar data tables. +2. Replace forced decorative alt text in Marketing Cloud layouts with real alt propagation. +3. Decide whether Marketing Cloud export routes are fragment-only or browser-facing, then implement the correct document semantics for that usage. +4. Audit all background-image and decorative-image patterns so meaningful images are never conveyed only through CSS. +5. Verify all author-facing media workflows communicate caption, transcript, and alt-text requirements clearly. + +### Phase 5 - Prove Compliance on Rendered Pages and Lock It In + +Code changes are not enough. This phase turns repaired code into a defensible compliance outcome. + +1. Build a representative test page matrix. At minimum include the front page, a standard content page, a sidebar page, a page using the select menu, an alphabetical listing page, a page with a photo gallery, an event page with the date picker, a publication admin table page, a login or authentication-related page, and a Marketing Cloud export route. +2. Run automated scans against every representative page on every pull request. +3. Run manual keyboard-only checks on every representative page before release. +4. Run screen-reader checks on the high-risk widgets and global flows before release. +5. Track issues by severity and component so regressions are visible over time. + +## Recommended Work Backlog by Team Area + +### Theme and Layout + +1. [themes/custom/az_barrio/templates/layout/html.html.twig](themes/custom/az_barrio/templates/layout/html.html.twig) +2. [themes/custom/az_barrio/templates/layout/page.html.twig](themes/custom/az_barrio/templates/layout/page.html.twig) +3. [themes/custom/az_barrio/templates/forms/input--search-block-form--submit.html.twig](themes/custom/az_barrio/templates/forms/input--search-block-form--submit.html.twig) +4. [themes/custom/az_barrio/templates/navigation/pager.html.twig](themes/custom/az_barrio/templates/navigation/pager.html.twig) +5. [themes/custom/az_barrio/templates/views/views-mini-pager.html.twig](themes/custom/az_barrio/templates/views/views-mini-pager.html.twig) +6. [themes/custom/az_barrio/js/toasts.js](themes/custom/az_barrio/js/toasts.js) +7. [themes/custom/az_barrio/js/slick-a11y-patch.js](themes/custom/az_barrio/js/slick-a11y-patch.js) + +### Custom Widgets + +1. [modules/custom/az_select_menu/src/Plugin/Block/AzSelectMenu.php](modules/custom/az_select_menu/src/Plugin/Block/AzSelectMenu.php) +2. [modules/custom/az_select_menu/js/az-select-menu.js](modules/custom/az_select_menu/js/az-select-menu.js) +3. [modules/custom/az_select_menu/css/az-select-menu.css](modules/custom/az_select_menu/css/az-select-menu.css) +4. [modules/custom/az_accordion/templates/az-accordion.html.twig](modules/custom/az_accordion/templates/az-accordion.html.twig) +5. [modules/custom/az_alphabetical_listing/templates/views-view--az-alphabetical-listing.html.twig](modules/custom/az_alphabetical_listing/templates/views-view--az-alphabetical-listing.html.twig) +6. [modules/custom/az_alphabetical_listing/js/alphabetical_listing.js](modules/custom/az_alphabetical_listing/js/alphabetical_listing.js) +7. [modules/custom/az_paragraphs/az_paragraphs_photo_gallery/templates/photo-gallery-carousel.html.twig](modules/custom/az_paragraphs/az_paragraphs_photo_gallery/templates/photo-gallery-carousel.html.twig) +8. [modules/custom/az_core/lib/vanilla-calendar-pro/index.js](modules/custom/az_core/lib/vanilla-calendar-pro/index.js) +9. [modules/custom/az_core/lib/vanilla-calendar-pro/styles/themes/light.css](modules/custom/az_core/lib/vanilla-calendar-pro/styles/themes/light.css) +10. [modules/custom/az_core/lib/vanilla-calendar-pro/styles/themes/slate-light.css](modules/custom/az_core/lib/vanilla-calendar-pro/styles/themes/slate-light.css) + +### Content Templates and Editorial Outputs + +1. [modules/custom/az_publication/templates/az-publication-type-listing-table.html.twig](modules/custom/az_publication/templates/az-publication-type-listing-table.html.twig) +2. [modules/custom/az_marketing_cloud/templates/html--export--marketing-cloud.html.twig](modules/custom/az_marketing_cloud/templates/html--export--marketing-cloud.html.twig) +3. [modules/custom/az_marketing_cloud/templates/node--view--az-marketing-cloud--hero-layout.html.twig](modules/custom/az_marketing_cloud/templates/node--view--az-marketing-cloud--hero-layout.html.twig) +4. [modules/custom/az_marketing_cloud/templates/node--view--az-marketing-cloud--30-70-layout.html.twig](modules/custom/az_marketing_cloud/templates/node--view--az-marketing-cloud--30-70-layout.html.twig) +5. [modules/custom/az_marketing_cloud/templates/node--view--az-marketing-cloud--50-50-layout.html.twig](modules/custom/az_marketing_cloud/templates/node--view--az-marketing-cloud--50-50-layout.html.twig) +6. [modules/custom/az_marketing_cloud/templates/node--view--az-marketing-cloud--50-50-layout-image-right.html.twig](modules/custom/az_marketing_cloud/templates/node--view--az-marketing-cloud--50-50-layout-image-right.html.twig) +7. [modules/custom/az_marketing_cloud/templates/node--view--az-marketing-cloud--70-30-layout-image-right.html.twig](modules/custom/az_marketing_cloud/templates/node--view--az-marketing-cloud--70-30-layout-image-right.html.twig) +8. [modules/custom/az_media/templates/az-responsive-background-image.html.twig](modules/custom/az_media/templates/az-responsive-background-image.html.twig) + +### Tooling and Quality Gates + +1. [package.json](package.json) +2. [.github/workflows/ci.yml](.github/workflows/ci.yml) + +## Verification Strategy + +The following strategy is required if the team wants to move from source-level remediation to a credible WCAG 2.2 AA sign-off. + +### Automated Checks + +1. Add the GitHub Accessibility Scanner for representative-page scanning against approved live URLs. +2. Establish a brownfield baseline first, then fail pull requests on new serious or critical issues. +3. Track accessibility regressions separately from lint and unit-test failures so they are visible and actionable. +4. Use narrower supplemental checks only where authenticated or hard-to-reach flows cannot be covered by the primary scanner. + +### Manual Checks + +1. Keyboard-only navigation for every representative page. +2. Focus visibility review at 100 percent and 200 percent zoom. +3. NVDA with Firefox and NVDA with Chrome checks for navigation, search, filters, select menu, carousel, date picker, and tables. +4. JAWS with Chrome and JAWS with Edge checks for the same high-risk Windows flows. +5. VoiceOver checks for the same high-risk flows on macOS and iOS. +6. Screen-reader confirmation that status messages are announced once, politely when appropriate, and without duplicate noise. + +### Content Governance Checks + +1. Confirm all editorial image workflows enforce meaningful alt text or explicit decoration. +2. Confirm audio and video workflows require captions, transcripts, and accessible playback controls. +3. Confirm Marketing Cloud export authors understand when email layouts may use decorative images and when they must expose informative alt text. + +## Exit Criteria + +az_quickstart should not be described as WCAG 2.2 AA compliant until all of the following are true. + +1. All Phase 1 and Phase 2 issues are fixed and verified on rendered pages. +2. No serious or critical accessibility issues remain on the representative page matrix. +3. Core flows are usable with keyboard only: global navigation, site search, select menu navigation, alphabetical listing, gallery carousel, date picker, table interaction, and authentication-related forms. +4. Manual checks pass with NVDA, JAWS, and VoiceOver on the defined matrix. +5. Accessibility checks run in CI and block regressions. +6. Editorial guidance exists for alt text, decorative images, captions, transcripts, and background-image usage. + +## Open Questions and Assumptions + +1. The skip-link finding assumes the standard page shell does not receive a runtime-injected `id="content"`. The reviewed source strongly suggests that the target is missing, but this should still be confirmed on a rendered page. +2. The Marketing Cloud export-shell finding assumes the export routes are browser-facing. If they are fragment-only and never directly navigated to, the risk is lower, but the route contract should be explicit. +3. The drag-and-drop and authentication areas were identified as high-priority verification zones because of WCAG 2.2 risk, but they still require runtime testing before they should be classified as failures or passes. + +## Recommended Next Step + +Start with Phase 0 and Phase 1 together. Fixing the global blockers without adding an accessibility gate will create short-term improvement and long-term churn. Adding the gate without fixing the blockers will create noise and stalled pull requests. The best outcome is to do both in the same remediation window. \ No newline at end of file diff --git a/ACCESSIBILITY-SCANNER-TRIAGE-GUIDE.md b/ACCESSIBILITY-SCANNER-TRIAGE-GUIDE.md new file mode 100644 index 0000000000..8d68bf4753 --- /dev/null +++ b/ACCESSIBILITY-SCANNER-TRIAGE-GUIDE.md @@ -0,0 +1,210 @@ +# Accessibility Scanner Triage Guide + +## Purpose + +This guide defines how maintainers should triage results from the GitHub Accessibility Scanner after it is introduced as the primary automated accessibility checker for az_quickstart. + +The goal is to prevent two common failure modes: + +1. Treating every scanner result as an implementation blocker without context. +2. Treating scanner failures as noise and ignoring new regressions. + +## Scope + +This guide applies to: + +1. Pull request scanner runs. +2. Manual workflow dispatch runs. +3. Scheduled scanner runs on the approved representative page matrix. + +It should be used with [ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md](ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md) and [ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md](ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md). + +## First Triage Question + +Always start here: + +Is this a scanner infrastructure problem, an environment problem, an existing baseline finding, or a new accessibility regression? + +Do not start by assuming every failure means the PR introduced a new code problem. + +## Triage Categories + +### Category 1 - Workflow Or Infrastructure Failure + +Examples: + +1. The scanner workflow did not complete. +2. The target URL could not be reached. +3. The token, cache, or workflow input is misconfigured. +4. The environment is down or unstable. + +Action: + +1. Do not convert this directly into a product accessibility finding. +2. Treat it as a workflow or environment issue. +3. Re-run only after the infrastructure problem is understood. +4. Record the interruption in the release sign-off checklist if it affects release readiness. + +### Category 2 - Existing Baseline Debt + +Examples: + +1. A known serious or critical issue appears again after the baseline has already captured it. +2. The result matches previously accepted legacy debt on an approved representative page. + +Action: + +1. Confirm it is really part of the approved baseline. +2. Do not treat it as a new regression. +3. Keep it visible for backlog tracking and release awareness. +4. If it appears outside the approved baseline scope, reclassify it instead of ignoring it. + +### Category 3 - New Regression + +Examples: + +1. A serious or critical finding appears on a representative page and was not present in the baseline. +2. A PR introduces a new issue in naming, landmarks, forms, focus, or status-message behavior. + +Action: + +1. Treat it as a blocking regression if it meets the agreed threshold. +2. Correlate it with the changed files, issue scope, or affected flow. +3. Fix it in the PR or explicitly remove the change from the release. +4. Do not close the triage until the regression is fixed or the release decision is changed. + +### Category 4 - Manual Follow-Up Required + +Examples: + +1. The scanner finds an issue that needs human judgment to confirm impact. +2. The scanner cannot determine whether the automated result reflects actual user-facing breakage. +3. The flow depends on announcement quality, focus handoff, or multi-step interaction. + +Action: + +1. Keep the scanner result visible. +2. Trigger manual verification using [ACCESSIBILITY-MANUAL-VERIFICATION-PLAYBOOK.md](ACCESSIBILITY-MANUAL-VERIFICATION-PLAYBOOK.md). +3. Record the manual outcome before deciding whether to block, defer, or log risk. + +### Category 5 - Candidate False Positive Or Non-Representative Finding + +Examples: + +1. The page did not render as expected. +2. The scanner hit a route or state that is outside the approved representative scope. +3. The issue cannot be reproduced manually. + +Action: + +1. Do not silently dismiss it. +2. Re-check the URL, environment, and scan profile. +3. Confirm whether the finding came from the correct representative page. +4. Record why it was treated as non-blocking if the finding is not actionable. + +## Triage Sequence + +Use the following sequence every time a scanner run produces actionable output. + +1. Confirm the scan profile that ran: patch or minor. +2. Confirm the target environment that was scanned. +3. Confirm the representative URLs that were actually in scope. +4. Separate workflow or environment failures from accessibility findings. +5. Classify each accessibility finding as baseline debt, new regression, manual follow-up, or false-positive candidate. +6. Record the decision in the release sign-off checklist when the result affects release readiness. + +## Blocking Rules + +The initial recommended blocking threshold is: + +1. Block on new critical findings. +2. Block on new serious findings. +3. Record moderate and minor findings without automatically blocking during the first rollout. + +If the team changes the threshold later, update this guide and the Phase 0 planning docs together. + +## What To Do When The Workflow Fails + +If the workflow fails before producing valid scanner results: + +1. Treat it as a workflow failure first. +2. Check whether the live URLs were available. +3. Check whether the profile or environment input was wrong. +4. Check whether the scanner token or permissions failed. +5. Re-run only after the likely cause is understood. + +Do not convert a scanner infrastructure failure into a product accessibility issue unless the failure itself reflects a product problem such as the page being unavailable. + +## What To Do When A Finding Blocks The PR + +1. Confirm it is a new serious or critical finding. +2. Confirm it is on an approved representative page. +3. Correlate it to the code or configuration changes in scope. +4. Decide whether the finding should be fixed in the same PR, backed out from the PR, or moved out of the release. +5. If it cannot be fixed in time, record it explicitly as release risk and treat the PR as not ready under the current policy. + +## When To Open Or Update A GitHub Issue + +Open or update a GitHub issue when: + +1. The finding maps to a real user-facing defect not already tracked. +2. The problem survives triage and manual confirmation. +3. The issue is part of accepted baseline debt that still needs ownership. +4. The same finding continues to recur and needs durable tracking. + +Do not open a new issue when: + +1. The finding is clearly a duplicate of an existing tracked issue. +2. The workflow failed before a valid result existed. +3. The result is a confirmed false positive or environment mismatch. + +## When To Record A Release Risk Instead Of Opening A New Issue + +Use the release sign-off risk log when: + +1. The issue is already tracked elsewhere. +2. The finding is real but the release decision is still pending. +3. The environment prevented full verification. +4. The team needs explicit go or no-go acknowledgement from decision-makers. + +## Baseline Handling Rules + +During the first rollout, baseline debt must stay visible without being confused with new regressions. + +Recommended handling: + +1. Keep the baseline documented and stable. +2. Do not silently expand the baseline after a regression. +3. If a finding appears new because the URL set changed, update the representative inventory before changing the baseline. +4. Revisit baseline scope only through an explicit team decision. + +## Manual Follow-Up Expectations + +Use manual follow-up when a scanner result touches any of these areas: + +1. Skip-link behavior. +2. Search and pager naming. +3. Status-message urgency and duplication. +4. Select-menu state, validation, or focus. +5. Accordion section relationships. +6. Alphabetical listing filter announcements or focus handoff. +7. Gallery carousel naming, slide state, or navigation. +8. Date picker announcement behavior or focus treatment. +9. Publication table context. +10. Marketing Cloud image meaning or export-route semantics. + +## Suggested Triage Record Fields + +For every finding that affects release readiness, record: + +1. Scan profile. +2. Representative page ID or URL. +3. Scanner severity. +4. Triage category. +5. Release action. +6. Linked issue if one exists. +7. Manual follow-up requirement. + +## Recommended Next Step + +Use this guide as the operating companion to the scanner workflow plan. Once the GitHub Accessibility Scanner workflow exists, the first proof-of-concept run should be triaged with this document so the team can refine the rollout before the gate becomes required. \ No newline at end of file diff --git a/ACCESSIBILITY-SENDOUT-BRIEF.md b/ACCESSIBILITY-SENDOUT-BRIEF.md new file mode 100644 index 0000000000..d65c470651 --- /dev/null +++ b/ACCESSIBILITY-SENDOUT-BRIEF.md @@ -0,0 +1,102 @@ +# Accessibility Program Send-Out Brief + +## Purpose + +This document is the single send-out package for the az_quickstart accessibility planning work completed on April 23, 2026. + +Use this when sharing the work with stakeholders so everyone has one place to find: + +1. The live GitHub board. +2. The umbrella issue and phase issues. +3. The detailed planning documents. +4. The Friday meeting materials. +5. The current decision queue. +6. The final send-ready email and one-page handout. + +## Live GitHub Resources + +- Project board: https://github.com/orgs/az-digital/projects/285 +- Umbrella issue: https://github.com/az-digital/az_quickstart/issues/5533 + +### Phase Parent Issues + +- Phase 0: https://github.com/az-digital/az_quickstart/issues/5532 +- Phase 1: https://github.com/az-digital/az_quickstart/issues/5535 +- Phase 2: https://github.com/az-digital/az_quickstart/issues/5531 +- Phase 3: https://github.com/az-digital/az_quickstart/issues/5536 +- Phase 4: https://github.com/az-digital/az_quickstart/issues/5534 + +## Detailed Planning Documents + +These files currently live on the dedicated `docs/accessibility-planning-2026-04-23` planning branch and can be viewed directly in GitHub with the links below. + +- Review plan: https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-REVIEW-PLAN.md +- GitHub execution plan: https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-GITHUB-PROJECT-PLAN.md +- Phase 0.1 verification proposal: https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-P0.1-VERIFICATION-PROPOSAL.md +- Phase 0.2 scanner workflow plan: https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-P0.2-SCANNER-WORKFLOW-PLAN.md +- Manual verification playbook: https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-MANUAL-VERIFICATION-PLAYBOOK.md +- Scanner triage guide: https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-SCANNER-TRIAGE-GUIDE.md +- Release sign-off checklist: https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-RELEASE-SIGNOFF-CHECKLIST.md +- Representative URL inventory and environment map: https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-REPRESENTATIVE-URL-INVENTORY.md +- Friday meeting agenda: https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-FRIDAY-MEETING-AGENDA.md +- Facilitator script: https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-FRIDAY-FACILITATOR-SCRIPT.md +- Project views handoff: https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-PROJECT-VIEWS-HANDOFF.md +- Post-meeting notes template: https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-POST-MEETING-NOTES-TEMPLATE.md +- Live presentation talk track: https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-LIVE-PRESENTATION-TALK-TRACK.md +- Team email draft: https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-PROGRAM-EMAIL-DRAFT.md +- Executive email draft: https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-EXECUTIVE-EMAIL-DRAFT.md +- Final review email: https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-FINAL-REVIEW-EMAIL.md +- One-page Friday handout: https://github.com/az-digital/az_quickstart/blob/docs/accessibility-planning-2026-04-23/ACCESSIBILITY-FRIDAY-HANDOUT.md + +## Friday Decision Queue + +These are the issues currently marked for explicit Friday discussion and remain `Release Target = Undecided` on the project board: + +1. https://github.com/az-digital/az_quickstart/issues/5533 +2. https://github.com/az-digital/az_quickstart/issues/5541 +3. https://github.com/az-digital/az_quickstart/issues/5550 +4. https://github.com/az-digital/az_quickstart/issues/5544 +5. https://github.com/az-digital/az_quickstart/issues/5545 + +## Recommended First-Wave Candidates + +If the Friday decisions are confirmed, these are the most sensible first-wave candidates: + +1. https://github.com/az-digital/az_quickstart/issues/5541 +2. https://github.com/az-digital/az_quickstart/issues/5539 +3. https://github.com/az-digital/az_quickstart/issues/5538 +4. https://github.com/az-digital/az_quickstart/issues/5540 +5. https://github.com/az-digital/az_quickstart/issues/5537 +6. https://github.com/az-digital/az_quickstart/issues/5514 + +## What Was Completed Today + +1. The accessibility review was documented. +2. A phased remediation and verification plan was written. +3. A GitHub program was created with an umbrella issue, phase issues, and child issues. +4. A GitHub Project v2 board was created and populated. +5. The Friday decision queue was narrowed and marked with `needs discussion`. +6. Meeting support materials and send-ready email drafts were prepared. + +## What Has Not Started + +1. No implementation work has started. +2. No new PRs were intentionally opened as part of this planning package. +3. The purpose of this work was planning, prioritization, and visibility only. + +## Should These Markdown Files Be Posted in GitHub? + +Yes. + +The project board itself should remain a program-level dashboard and should not be treated as part of a feature or bug branch. The planning branch exists only to store and review the supporting documentation package. + +Because the documents currently live on a feature branch, they are easy to miss unless people are given direct links. The best low-friction visibility pattern is: + +1. Keep the project board as the top-level entry point. +2. Add a resource index comment on the umbrella issue. +3. Keep the project readme updated with the same resource links. +4. Use direct GitHub blob links in emails and meeting notes so recipients can open the documents in the browser. + +That gives people browser access now without requiring a PR or a merge to `main`. + +For longer-term discoverability, after Friday the best next step would be to move or merge the final planning docs to a more permanent location on the default branch. \ No newline at end of file diff --git a/send.html b/send.html new file mode 100644 index 0000000000..f6334d739f --- /dev/null +++ b/send.html @@ -0,0 +1,82 @@ + + + + + + + az_quickstart Accessibility Review Package + + +
+
+

Accessibility Planning Package

+

az_quickstart WCAG 2.2 AA Review Materials

+

The accessibility effort is now organized as a planning program with a live dashboard, a decision queue, and a focused documentation package ready for team review.

+
+ +
+

Hello everyone,

+

I wanted to share some accessibility planning work I put together for az_quickstart. This has not been widely socialized yet, so I wanted to bring it forward in one place before we decide what should happen next.

+

No implementation work has started. The intent here is to give the team a practical starting point for discussion, and it may make sense to schedule a dedicated review meeting because this package is broader than a normal issue update.

+

The approach is intentionally well targeted. The goal is to start with changes that create immediate, meaningful, and noticeable improvement for users on common journeys, then build from there together. That feels aligned with The Wildcat Way: doing work that makes a real difference.

+
+ +
+

What Is Ready

+
    +
  1. A source-level accessibility review and remediation plan.
    2. +
  2. A live project dashboard and umbrella issue structure.
    3. +
  3. A narrowed Friday decision queue.
    4. +
  4. Meeting materials and send-out documents on a dedicated planning branch.
    5. +
+
+ +
+

Open The Project Board

+

Open The Planning PR

+
+ +
+

Recommended Starting Position

+

These are recommended starting positions for discussion, not pre-made decisions:

+
    +
  1. Use a targeted representative page matrix based on common journeys and the highest-risk widgets.
    2. +
  2. Focus the first wave on navigation, naming, announcements, and reachability where users will notice the difference quickly.
    3. +
  3. Use patch releases for narrow, high-impact fixes on common pages.
    4. +
  4. Keep broader structural rewrites in later phases unless the scope can be narrowed safely.
    5. +
+
+ +
+

Primary Review Links

+ +
+ +
+

Supporting Materials

+ +
+ +
+

The project dashboard remains the standing program surface. The dedicated planning branch exists only to store the review package and meeting materials.

+
+ +
+

Thanks,

+

Jeff

+

This version intentionally avoids layout tables so it copies more cleanly into Outlook while remaining readable in a browser.

+
+
+ + \ No newline at end of file