Issue Templates

Listen to Episode 16: Issue Templates - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

Structuring Contributions for Clarity and Quality

Issue templates turn a blank text box into a guided form. They help contributors provide the information maintainers need, reduce back-and-forth, and make every issue immediately actionable. This guide teaches you what templates are, how to use the ones in accessibility-agents, and how to create your own - including an accessibility-specific bug report template.

Prerequisites Checklist

Before starting this chapter, verify you have completed

Hard Requirements:

Recommended (but not blocking):

What you already have:

Day 2 Amplifier: In Chapter 16 (Accessibility Agents), you'll use @template-builder to automate template creation. Complete this chapter first, then come back to Chapter 16.

Estimated time for this chapter: 2-2.5 hours (including exercises and YAML troubleshooting time)

Workshop Recommendation (Chapter 15)

Chapter 15 is a template design and implementation chapter focused on structuring contributions with a concrete, familiar example.

Chapter 15 Challenge Set

  1. Analyze the registration template - understand how the template you already filled out works.
  2. Remix the registration template - adapt it for a new use case (bug report, event, research).
  3. Create a Markdown template (optional) - build a Markdown-based template from scratch.
  4. Test in the template chooser (optional) - verify your template appears and works.

Challenge 15.1 Step-by-Step: Analyze the Registration Template

Goal: Understand how professional YAML form templates work by examining the one you filled out to register for this workshop.

Where you are working: GitHub.com - reading the template file in the git-going-with-github repository.

Estimated time: 10-15 minutes.

The Template: .github/ISSUE_TEMPLATE/workshop-registration.yml - This is the form you filled out to register. It is a real, production template.

  1. Open the template file on GitHub.com (use the link above).
  2. Read the YAML frontmatter (top 5 lines) and identify:
    • name - what appears in the template chooser
    • description - helper text when users pick this template
    • title - auto-fills the issue title
    • labels - automatically adds labels to issues created with this template
  3. Read the field types in the body section. Note the four types used:
    • type: markdown - display-only text (instructions)
    • type: input - single-line text field (name, email)
    • type: dropdown - list of options (proficiency level, screen reader choice)
    • type: textarea - multi-line text (questions/accommodations)
  4. For each field, identify the metadata:
    • id - internal identifier (does not display to user)
    • label - what the user sees as the field name
    • description - helper text explaining what to fill in
    • placeholder - example text inside the field
    • validations: required: true - marks a field as required
  5. Search the file for "accessible" - notice the description mentions that all fields work with screen readers. This is professional template thinking.
  6. Compare: how is this different from a blank issue? A blank issue is a massive empty text box with no guidance. This template provides structured fields, helpful descriptions, and required/optional clarity.

You are done when: You can explain the purpose of each field type and why templates reduce back-and-forth questions.

Challenge 15.2 Step-by-Step: Remix the Registration Template

Goal: Adapt the registration template for a different use case while keeping the same YAML structure.

Where you are working: VS Code with a repository where you have write access (your fork or personal repo), or github.dev.

Estimated time: 20-30 minutes.

Use this worked example as a guide:

What changes and what stays the same:

Steps:

  1. Pick a new context for your template (for example: bug report, event attendance, product research, accessibility audit request).
  2. Copy the registration template file to a new file: .github/ISSUE_TEMPLATE/my-template.yml
  3. Change the name and description in the frontmatter to match your new context.
  4. Change the title prefix (for example: [Bug Report]: or [Event]: ).
  5. Change the labels to appropriate labels for your use case.
  6. Replace each field's label, description, placeholder, and options to match your new context.
  7. Decide which fields should be required: true and which can be optional.
  8. Validate your YAML syntax: copy the file contents to yamllint.com and fix any errors.
  9. Commit and push to your repository.

You are done when: Your remixed template file is committed and the YAML syntax validates without errors.

Challenge 15.3 (Optional) Step-by-Step: Create a Markdown Template

Goal: Create a Markdown-based template to compare the two template formats.

Where you are working: VS Code with a repository where you have write access.

  1. Create a new file: .github/ISSUE_TEMPLATE/my-markdown-template.md
  2. Add the Markdown template frontmatter at the top:
---
name: "My Template Name"
about: "Short description of when to use this template"
title: "[PREFIX]: "
labels: documentation
---
  1. Note: Markdown templates use about instead of description (unlike YAML form templates).
  2. Below the frontmatter, add 3-4 sections with HTML comment instructions:
## Problem
<!-- Describe the problem you encountered. -->

## Context
<!-- What were you trying to do when you found this problem? -->

## Solution Ideas
<!-- Optional: any ideas for how to fix this? -->
  1. Commit and push.

You are done when: Your Markdown template file is committed with proper frontmatter and section structure.

Challenge 15.4 (Optional): Test in the Template Chooser

  1. Navigate to your test repository on GitHub.com.
  2. Activate New Issue.
  3. Verify your template appears in the template chooser.
  4. Activate Get started on your template and file a test issue.

You are done when: Your template works and appears in the GitHub template picker.

Completing Chapter 15: Submit Your Evidence

Open your assigned Chapter 15 challenge issue and post a completion comment:

Chapter 15 completed:
- Analyzed registration template: yes / no
- Remixed template context: [your chosen context]
- YAML validates: yes / no
- Template committed to: [repo name]
- Optional Markdown template: yes / no
- Template chooser test: yes / no

Close your Chapter 15 challenge issues when done.

Expected Overall Outcomes

If You Get Stuck

  1. Cannot find the registration template? Look in .github/ISSUE_TEMPLATE/workshop-registration.yml in the git-going-with-github repository.
  2. YAML syntax confusing? The registration template is a working example. Copy its structure and edit the field descriptions. YAML is indented key-value pairs with 2 spaces per level.
  3. YAML not parsing? Compare with the remix sample in learning-room/docs/samples/chapter-15-registration-remix-example.yml and check indentation.
  4. Template does not appear in the chooser? Verify: filename ends in .yml or .md, you pushed the commit, and the file is in .github/ISSUE_TEMPLATE/ folder.
  5. Testing in the template chooser is not working? Reload the Issues page, try a different repository, or ask facilitator for a test repository with write access.
  6. Remix approach feels overwhelming? Start by changing just the field labels and descriptions. Do not change the structure yet.
  7. Ask facilitator to review your template and suggest improvements.

Continue learning: The GitHub Skills course Introduction to Repository Management covers templates and contributor settings in an interactive format. See Appendix Z for the full catalog.

Learning Moment

Templates are scaffolding. They do not restrict expert contributors - they guide newcomers. A template that takes 2 minutes to understand saves 30 minutes of back-and-forth questions later. By remixing a professional template, you learned how to make templates work for your specific context. That is how maintainers decide if a new template is worth creating: they adapt existing patterns first, then innovate.

Learning Pattern Used in This Chapter

  1. Analyze an existing, working example before building your own.
  2. Remix by changing content while keeping structure (safe, fast iteration).
  3. Create from scratch only after you understand the pattern (Markdown template).
  4. Test the result in the real environment (template chooser).

Table of Contents

  1. What Is an Issue Template?
  2. How Templates Work on GitHub
  3. Navigating the Template Picker
  4. The Accessibility Agents Issue Templates
  5. Creating a New Template - Step by Step
  6. YAML Form-Based Templates
  7. Building an Accessibility Bug Report Template
  8. Pull Request Templates
  9. Hands-On Activity

1. What Is an Issue Template?

An issue template is a pre-filled Markdown file that appears when someone activates "New Issue." Instead of an empty editor, the contributor sees:

Why they matter for accessibility projects

Accessibility bugs require specific context that general bug templates often omit:

Without this context, maintainers ask follow-up questions - which delays the fix and uses everyone's time. A good accessibility template captures it all on the first submission.

2. How Templates Work on GitHub

Templates live in a specific folder in your repository:

Description

Templates live inside your-repo/.github/. The ISSUE_TEMPLATE/ subfolder contains: bug_report.md (Markdown template), feature_request.md (Markdown template), accessibility-bug.yml (YAML form template), and config.yml (template chooser configuration). The pull_request_template.md file sits directly in .github/, not inside ISSUE_TEMPLATE/.

Markdown templates (.md): Traditional template format. Pre-fills a text editor with structured Markdown content. Contributors edit the template directly, replacing instructions and placeholder text with their own content.

YAML form templates (.yml): Modern form-based templates. Creates a proper form interface with labeled fields, dropdowns, checkboxes, and validation. Contributors fill in fields rather than editing freeform Markdown. Better for accessibility because each field has an explicit label announced by screen readers.

config.yml: Controls the template chooser page - what templates appear, what their descriptions say, whether an external link (like a discussion forum) appears as an option, and crucially, whether contributors can bypass templates entirely with a blank issue.

For accessibility projects, config.yml is important: disabling the blank issue option means every report arrives with the structure your project needs. A screen reader bug report without reproduction steps and AT version information is almost impossible to triage - the form prevents that by making those fields required.

Example config.yml

blank_issues_enabled: false
contact_links:
  - name: Community Discussion
    url: https://github.com/community-access/accessibility-agents/discussions
    about: For questions and general discussion - not bugs
  - name: Security Vulnerability
    url: https://github.com/community-access/accessibility-agents/security/advisories/new
    about: Please use private reporting for security issues

With blank_issues_enabled: false, the "Open a blank issue" link disappears from the template chooser. Contributors must use one of your structured templates or one of the contact links. This is one of the most effective ways to improve the quality of incoming issues in any project you maintain.

3. Navigating the Template Picker

When a repository has multiple templates, GitHub shows a template chooser page before the issue editor.

Visual / mouse users
  1. Click the Issues tab on any repository
  2. Click the New issue button
  3. The template chooser page loads - templates appear as cards with a title, description, and "Get started" button
  4. Click "Get started" on the template you want
  5. The issue editor opens with that template's content pre-filled
Screen reader users - NVDA / JAWS (Windows)
  1. Navigate to the Issues tab (press T from the repository tabs landmark)
  2. Activate "New issue" button
  3. The template chooser page loads
  4. Each template appears as a list item or a link
  5. Use Tab to move between templates
  6. Each template shows: name, description, "Get started" button
  7. Activate "Get started" on your chosen template
Screen reader users - VoiceOver (macOS)
  1. Navigate to the Issues tab (VO+Right from the tab bar landmark)
  2. VO+Space to activate "New issue"
  3. The chooser page loads - templates appear as list items
  4. VO+Right to move between templates
  5. VO+Space on "Get started" for your chosen template

Note: GitHub's improved Issues experience provides proper keyboard accessibility for the template chooser. This feature may already be active in your account.

Bypassing the Chooser

If you want to file an issue without using a template:

4. The Accessibility Agents Issue Templates

Accessibility Agents uses templates to structure contributions. Navigate to .github/ISSUE_TEMPLATE/ in the repository to read them.

Visual / mouse users
  1. Click the Code tab on the repository
  2. Click the .github folder in the file listing
  3. Click ISSUE_TEMPLATE
  4. You'll see the template files - click any to read it
Screen reader users (NVDA / JAWS / VoiceOver)
  1. Open the Code tab
  2. Use Ctrl+Alt+Down/Up (NVDA/JAWS) or VO+Arrow (VoiceOver) in the files table to reach the .github folder
  3. Activate the folder
  4. Activate ISSUE_TEMPLATE
  5. You will see the template files listed

Reading a Template File

Open any template file (e.g., bug_report.md) in VS Code or in the GitHub web editor (pencil button - screen readers announce it as "Edit this file").

Look for:

Example frontmatter

name: Bug Report
about: Report a problem with an agent or prompt
title: '[BUG] '
labels: bug
assignees: ''

The about text appears in the template chooser. The title pre-fills the issue title field (the contributor replaces the placeholder). The labels array auto-applies labels when the issue is created.

5. Creating a New Template - Step by Step

Choosing Between Markdown and YAML Templates

Before creating a template, decide which format best suits your needs:

Factor Markdown Templates YAML Form Templates
Best for Simple templates, freeform text Structured data collection, accessibility
Complexity Very simple to create More complex, requires YAML knowledge
Screen reader UX Announces as pre-filled text editor Announces each field with explicit labels
Validation None - contributors can delete anything Can mark fields as required, validate input
Flexibility Full Markdown formatting freedom Limited to defined field types
Data consistency Varies - contributors may skip sections High - dropdowns ensure consistent values
Learning curve Minimal Moderate
Maintenance Easy - just edit Markdown More involved - must update YAML structure

Use Markdown templates when

Use YAML form templates when

For accessibility projects: YAML form templates are strongly recommended. Accessibility bug reports require specific context (screen reader, browser, OS, version numbers) that Markdown templates rely on contributors to remember. Form templates make these fields explicit and required.

Markdown Template Structure

A Markdown template consists of two parts:

1. YAML Frontmatter (between --- delimiters)

Defines metadata about the template:

name: Bug Report                    # Name shown in template chooser
about: Report a bug or error        # Description in template chooser
title: '[BUG] '                     # Pre-filled issue title (user can edit)
labels: ['bug', 'needs-triage']     # Auto-applied labels
assignees: ''                       # Auto-assigned maintainers (optional)

2. Markdown Body

The template content that pre-fills the issue editor:

## Describe the Bug
A clear and concise description of what the bug is.

## Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. Scroll down to '...'
4. See error

## Expected Behavior
What you expected to happen.

## Actual Behavior
What actually happened.

## Environment
- **OS:** [e.g. Windows 11, macOS Sonoma]
- **Browser:** [e.g. Chrome 124, Firefox 125]
- **Screen Reader:** [e.g. NVDA 2025.3.3, VoiceOver]

## Additional Context
Add any other context about the problem here.

Markdown template tips

Complete Markdown Template Example

Here's a complete accessibility bug report template in Markdown format. Save this as .github/ISSUE_TEMPLATE/accessibility-bug-simple.md:

name: Accessibility Bug (Markdown)
about: Report an accessibility issue using the simple Markdown template
title: '[A11Y] '
labels: ['accessibility', 'needs-triage']
assignees: ''

<!-- 
Thank you for reporting an accessibility issue. Please fill in all sections below.
Screen reader and browser information is especially important for us to reproduce the issue.
-->

## Component Affected

<!-- Which agent, slash command, or feature has the accessibility issue? -->

- [ ] @daily-briefing
- [ ] @issue-tracker
- [ ] @pr-review
- [ ] @analytics
- [ ] @insiders-a11y-tracker
- [ ] Slash command (specify below)
- [ ] Documentation
- [ ] Setup or configuration
- [ ] Other: ___________

## Your Assistive Technology Setup

**Screen Reader:** [e.g. NVDA 2025.3.3, JAWS 2026, VoiceOver macOS Sonoma]  
**Browser:** [e.g. Chrome 124, Firefox 125, Safari 17]  
**Operating System:** [e.g. Windows 11, macOS Sonoma 14.3, Ubuntu 22.04]  
**Keyboard only (no screen reader):** [ ] Yes  [ ] No

## Expected Behavior

<!-- What should happen? What should your screen reader announce? -->



## Actual Behavior

<!-- What actually happens? What does your screen reader announce (or not announce)? -->



## Steps to Reproduce

1. 
2. 
3. 
4. Result: 

## WCAG Success Criterion (if known)

<!-- Which WCAG guideline does this violate? Leave blank if unsure. -->

- [ ] 1.1.1 Non-text Content
- [ ] 1.3.1 Info and Relationships
- [ ] 2.1.1 Keyboard
- [ ] 2.4.3 Focus Order
- [ ] 2.4.6 Headings and Labels
- [ ] 4.1.2 Name, Role, Value
- [ ] Other: ___________
- [ ] Not sure

## Additional Context

<!-- Screenshots (with alt text), links to related issues, workarounds, or suggested fixes -->



## Before Submitting

- [ ] I searched for existing issues and this is not a duplicate
- [ ] I can reliably reproduce this issue with the steps above
- [ ] I have included my screen reader and browser versions

When to use this Markdown version instead of YAML

Markdown template accessibility considerations

Creating Markdown Templates: The Manual Workflow (Browser)

Visual / mouse users
  1. Navigate to your fork of accessibility-agents on GitHub
  2. Click the Settings tab
  3. Scroll to the "Features" section → click the checkmark next to "Issues" → click "Set up templates"
  4. Or navigate directly to .github/ISSUE_TEMPLATE/ in your fork → click the + button → "Create new file"
  5. GitHub opens a template editor. Fill in the template name, about description, and body
  6. GitHub auto-populates the filename - you can change it
  7. Click "Propose changes" → create a PR to add the template
Screen reader users (NVDA / JAWS / VoiceOver)
  1. Navigate to your fork of accessibility-agents on GitHub
  2. Go to the Settings tab (press T from the tabs landmark, then navigate to "Settings")
  3. Scroll to the "Features" section → find "Issues" → activate "Set up templates"

    Alternative: Navigate directly to .github/ISSUE_TEMPLATE/ → activate the "+" button → "Create new file"

  4. GitHub opens a template editor. Fill in:

    • Template name: what appears in the chooser heading
    • About: the description in the chooser
    • Template content: the Markdown body
  5. GitHub auto-populates the filename based on your template name
  6. "Propose changes" → create a PR to add the template

Creating Markdown Templates: The VS Code Workflow

  1. Open your accessibility-agents fork in VS Code
  2. Navigate in Explorer to .github/ISSUE_TEMPLATE/
  3. Create a new file: Ctrl+N → save as your-template-name.md in that folder
  4. Add frontmatter first (between --- delimiters), then the body
  5. Commit and push: open Source Control (Ctrl+Shift+G) → stage → commit → push

File naming conventions

6. YAML Form-Based Templates

YAML templates create a proper form interface - labeled fields, dropdowns, checkboxes - rather than a pre-filled text editor. This is the preferred format for modern GitHub projects, especially those focused on accessibility.

Why YAML Forms Are Better for Accessibility

Explicit labels: Each field has a label: that screen readers announce. In Markdown templates, users must infer structure from headings and placeholder text.

Structured navigation: Screen readers can navigate form fields with standard form navigation commands (F key in NVDA/JAWS, form controls in VoiceOver rotor).

Required field validation: Screen readers announce when a field is required before the user submits. Markdown templates have no validation.

Consistent data: Dropdowns provide options that screen readers can navigate (Up/Down Arrow to hear each choice). contributors don't have to guess valid values.

Skip unreadable instructions: HTML comments in Markdown templates (<!-- -->) can confuse some screen reader configurations. YAML markdown fields provide instruction text that renders as readable content, not editing noise.

YAML Template Structure

A YAML form template consists of several parts:

name: Issue Template Name         # Shows in template chooser
description: Longer description   # Shows in template chooser
title: "[TAG] "                   # Pre-filled issue title
labels: ["label1", "label2"]      # Auto-applied labels
assignees: ["username"]           # Auto-assigned (optional)
body:                             # Array of form fields
  - type: markdown
    attributes:
      value: |
        Instructional text here

  - type: input
    id: unique-field-id
    attributes:
      label: Field Label
      description: Help text under the label
      placeholder: Placeholder text in the field
    validations:
      required: true

Top-level keys

name: Accessibility Bug Report
description: Report an accessibility issue in Accessibility Agents' output or interface
title: "[A11Y] "
labels: ["accessibility", "needs-triage"]
body:
  - type: markdown
    attributes:
      value: |
        Thank you for reporting an accessibility issue.
        Please fill in as much detail as possible.

  - type: dropdown
    id: screen-reader
    attributes:
      label: Screen Reader
      description: Which screen reader are you using?
      options:
        - NVDA (Windows)
        - JAWS (Windows)
        - VoiceOver (macOS)
        - VoiceOver (iOS)
        - TalkBack (Android)
        - Narrator (Windows)
        - Orca (Linux)
        - None
    validations:
      required: true

  - type: checkboxes
    id: checked-existing
    attributes:
      label: Before Submitting
      options:
        - label: I searched for existing issues and this is not a duplicate
          required: true
        - label: I am using the modern GitHub Issues experience (default since Jan 2026)
          required: false

YAML Field Types Reference

GitHub supports several field types in YAML form templates. Each has specific attributes and uses:

1. markdown - Instructional Text

Displays formatted Markdown content. Not editable by the contributor. Use for instructions, warnings, or explanations.

- type: markdown
  attributes:
    value: |
      ## Before You Begin

      Please search for [existing issues](../issues) before submitting.
      Use this format for multi-line text.
Attributes

No validation options (static content)

Screen reader note: This content is announced as regular text. Screen reader users can read it with their reading commands before moving to the next field.

2. input - Single-line Text Field

A single-line text input. Best for short answers like version numbers, URLs, or names.

- type: input
  id: version
  attributes:
    label: Version Number
    description: Which version of the software are you using?
    placeholder: e.g., v2.4.1
  validations:
    required: true
Attributes
Validations

Screen reader announcement: "Version Number, required, edit text, Which version of the software are you using?"

3. textarea - Multi-line Text Area

A multi-line text input. Best for descriptions, reproduction steps, code snippets, or any long-form content.

- type: textarea
  id: description
  attributes:
    label: Describe the Issue
    description: Provide as much detail as possible
    placeholder: |
      When I navigate to...
      The screen reader announces...
      I expected...
    value: |
      This text pre-fills the textarea.
      Contributors can edit or replace it.
    render: markdown
  validations:
    required: true
Attributes
Validations

Accessibility tip: Use placeholder for examples, value for pre-filled template text that contributors should edit.

4. dropdown - Select Menu

A dropdown menu with predefined options. Contributors select one choice. Best for bounded answer spaces like OS, browser, or severity.

- type: dropdown
  id: browser
  attributes:
    label: Browser
    description: Which browser are you using?
    options:
      - Google Chrome
      - Mozilla Firefox
      - Microsoft Edge
      - Apple Safari
      - Other
    multiple: false
  validations:
    required: true
Attributes
Validations
Screen reader experience
  1. Field is announced as "Browser, required, combo box"
  2. Press Down Arrow or Alt+Down to expand the dropdown
  3. Up/Down Arrow to navigate options
  4. Screen reader announces each option
  5. Enter or Space to select

Accessibility note: Dropdowns are more accessible than free text for bounded choices. Screen reader users can hear all options and select precisely.

5. checkboxes - Checkbox Group

A group of checkboxes. Contributors can select multiple options or use as a verification checklist.

- type: checkboxes
  id: prerequisites
  attributes:
    label: Before Submitting
    description: Please verify these items
    options:
      - label: I searched for existing issues
        required: true
      - label: I can reproduce this issue reliably
        required: true
      - label: I have attached relevant logs or screenshots
        required: false
Attributes
Each checkbox option

No top-level validation - validation is per-checkbox in options

Screen reader experience
  1. Group label announced: "Before Submitting, Please verify these items"
  2. Each checkbox announced as "I searched for existing issues, checkbox, not checked, required"
  3. Screen reader users can check each box with Space

Accessibility note: Checkboxes with required: true prevent submission if unchecked. This enforces contribution guidelines (e.g., "search for duplicates first").

YAML Field Types Summary Table

Type Best For Key Attributes Validations Screen Reader Announced As
markdown Instructions, warnings, explanations value None Regular text content
input Version numbers, URLs, short text label, placeholder required "Edit text" or "Edit"
textarea Descriptions, steps, code, long text label, placeholder, render required "Multi-line edit" or "Text area"
dropdown OS, browser, severity, bounded choices label, options, multiple required "Combo box" or "Pop-up button"
checkboxes Verification lists, multiple selections label, options with per-item required Per-checkbox "Checkbox, not checked"

Choosing the right field type

7. Building an Accessibility Bug Report Template

This is the hands-on activity. You will create a YAML form template specifically for accessibility bug reports in accessibility-agents.

Full Template

Save this as .github/ISSUE_TEMPLATE/accessibility-bug.yml in your fork:

name: Accessibility Bug Report
description: Report an issue where Accessibility Agents output or behavior is not accessible to screen reader users or keyboard-only users
title: "[A11Y] "
labels: ["accessibility", "needs-triage"]
body:
  - type: markdown
    attributes:
      value: |
        ## Thank You for This Report

        Accessibility bug reports are some of the most important contributions
        this project receives. The more detail you provide, the faster we can
        reproduce and fix the issue.

        **Before submitting:** Please check existing issues to avoid duplicates.
        You can search: `is:open is:issue label:accessibility`

  - type: dropdown
    id: component
    attributes:
      label: Which Agent or Feature Is Affected?
      options:
        - "@daily-briefing"
        - "@issue-tracker"
        - "@pr-review"
        - "@analytics"
        - "@insiders-a11y-tracker"
        - "A slash command (specify below)"
        - "Documentation"
        - "Setup or configuration"
        - "Other"
    validations:
      required: true

  - type: dropdown
    id: screen-reader
    attributes:
      label: Screen Reader
      description: Which screen reader are you using? Select all that apply by filing separate issues, or list multiple in "Additional Context" below.
      options:
        - NVDA (Windows)
        - JAWS (Windows)
        - VoiceOver (macOS)
        - VoiceOver (iOS / iPadOS)
        - TalkBack (Android)
        - Narrator (Windows)
        - Orca (Linux)
        - Keyboard only (no screen reader)
        - None of the above
    validations:
      required: true

  - type: input
    id: screen-reader-version
    attributes:
      label: Screen Reader Version
      description: For example, "NVDA 2025.3.3" or "JAWS 2026"
      placeholder: e.g., NVDA 2025.3.3
    validations:
      required: false

  - type: dropdown
    id: browser
    attributes:
      label: Browser
      options:
        - Google Chrome
        - Microsoft Edge
        - Mozilla Firefox
        - Apple Safari
        - Other
    validations:
      required: true

  - type: input
    id: browser-version
    attributes:
      label: Browser Version
      placeholder: e.g., Chrome 124.0.6367.82

  - type: dropdown
    id: os
    attributes:
      label: Operating System
      options:
        - Windows 11
        - Windows 10
        - macOS Sequoia
        - macOS Sonoma
        - macOS Ventura
        - iOS / iPadOS
        - Android
        - Linux
        - Other
    validations:
      required: true

  - type: textarea
    id: expected
    attributes:
      label: Expected Behavior
      description: What should happen? What should your screen reader announce?
      placeholder: |
        When I activate the "Get started" button, my screen reader should announce
        "Issue template: Accessibility Bug Report, heading level 2" and move
        focus to the first form field.
    validations:
      required: true

  - type: textarea
    id: actual
    attributes:
      label: Actual Behavior
      description: What actually happens? What does your screen reader announce (or not announce)?
      placeholder: |
        When I activate the "Get started" button, focus moves but my screen reader
        announces nothing. I have to navigate manually to find where I am.
    validations:
      required: true

  - type: textarea
    id: steps
    attributes:
      label: Steps to Reproduce
      description: Numbered steps to reproduce the issue
      placeholder: |
        1. Navigate to accessibility-agents on GitHub
        2. Activate "New issue"
        3. On the template chooser, Tab to "Accessibility Bug Report"
        4. Activate "Get started"
        5. Result: [what happens]
    validations:
      required: true

  - type: dropdown
    id: wcag
    attributes:
      label: WCAG Success Criterion (if known)
      description: Which accessibility standard does this appear to violate?
      options:
        - "1.1.1 Non-text Content"
        - "1.3.1 Info and Relationships"
        - "1.3.2 Meaningful Sequence"
        - "1.4.1 Use of Color"
        - "1.4.3 Contrast (Minimum)"
        - "2.1.1 Keyboard"
        - "2.1.2 No Keyboard Trap"
        - "2.4.1 Bypass Blocks"
        - "2.4.3 Focus Order"
        - "2.4.6 Headings and Labels"
        - "2.4.7 Focus Visible"
        - "3.3.1 Error Identification"
        - "4.1.2 Name, Role, Value"
        - "4.1.3 Status Messages"
        - "Not sure"
        - "Does not apply"
    validations:
      required: false

  - type: textarea
    id: context
    attributes:
      label: Additional Context
      description: Anything else - screenshots (with alt text), links to related issues, workarounds you found, or suggestions for a fix

  - type: checkboxes
    id: checklist
    attributes:
      label: Before Submitting
      options:
        - label: I searched existing issues and this is not a duplicate
          required: true
        - label: I can reliably reproduce this issue with the steps above
          required: true
        - label: I have included my screen reader and browser versions
          required: false

What Makes This Template Accessible

This template is itself an accessibility contribution:

A Second Template: Feature Request Form

The bug report template above is specific to accessibility issues. Once you understand the pattern, you can create templates for any contribution type. Here is a Feature Request template you can add to your own projects - it follows the exact same YAML structure.

Save as .github/ISSUE_TEMPLATE/feature-request.yml:

name: Feature Request
description: Suggest a new agent, slash command, or improvement to Accessibility Agents
title: "[FEAT] "
labels: ["enhancement", "needs-triage"]
body:
  - type: markdown
    attributes:
      value: |
        ## Suggest a Feature

        Feature requests are welcome. The more specific your suggestion,
        the easier it is to design and implement.

  - type: dropdown
    id: feature-area
    attributes:
      label: Feature Area
      description: Which part of Accessibility Agents does this relate to?
      options:
        - New agent
        - New slash command
        - Existing agent improvement
        - Output format / accessibility
        - Documentation
        - Configuration / preferences
        - Other
    validations:
      required: true

  - type: textarea
    id: problem
    attributes:
      label: Problem or Gap
      description: What is the problem you are trying to solve? What can you not currently do?
      placeholder: |
        I often need to... but there is no way to...
        I find that the current output of @daily-briefing does not...
    validations:
      required: true

  - type: textarea
    id: solution
    attributes:
      label: Proposed Solution
      description: How would you like this to work?
      placeholder: |
        A new slash command called /weekly-digest that...
        The @pr-review agent should additionally announce...
    validations:
      required: true

  - type: textarea
    id: accessibility-impact
    attributes:
      label: Accessibility Considerations
      description: How does this feature affect screen reader users or keyboard-only navigation?
      placeholder: |
        This would improve the experience because...
        Screen reader users would benefit by...

  - type: checkboxes
    id: checklist
    attributes:
      label: Before Submitting
      options:
        - label: I searched existing issues and discussions - this has not been suggested before
          required: true
        - label: This feature would benefit contributors beyond my personal workflow
          required: false

Why this matters for your own projects: Every open source project you create or maintain can have issue templates. A project with good templates gets better bug reports and feature requests - which means less back-and-forth and faster, more confident triage. The templates you create here are skills you carry to every repository you own.

Designing Templates for Your Own Projects

When designing templates for a project you maintain, use these principles:

Ask for the minimum that makes the report actionable. Every optional field you add is a reason for a contributor with limited time to stop and not finish. Required fields should be information you genuinely cannot triage without.

Use dropdowns over free text when the answer space is bounded. "Which operating system?" should be a dropdown, not a text field. Bounded dropdowns reduce typos, inconsistent labeling, and fields left blank.

Write textarea placeholders as examples, not instructions. A placeholder that says "e.g., When I navigate to the Issues tab using NVDA in Chrome on Windows 11..." teaches the contributor what a good answer looks like. A placeholder that says "Describe the issue here" does not.

Include a pre-submission checklist. Even one checkbox - "I searched for existing issues" - reduces duplicate reports significantly. The checklist also reinforces community norms: the act of checking a box is more memorable than reading a line of text.

Test every template with your screen reader before committing. Navigate through the form, tab through all fields, confirm every label is announced correctly, and verify that required-field errors are surfaced in a way a screen reader user will encounter before submitting.

8. Pull Request Templates

A pull request template appears as the default body of every new PR in your repository.

File location: .github/pull_request_template.md (singular - only one PR template per repo)

Reading the Accessibility Agents PR Template

Open .github/pull_request_template.md in VS Code. You will see the standard sections the project expects:

## Description
<!-- What does this PR add or fix? Why? -->

## Type of Change
- [ ] New agent
- [ ] New slash command
- [ ] Bug fix
- [ ] Documentation improvement
- [ ] Accessibility improvement
- [ ] Other (describe below)

## How to Test
<!-- How can a reviewer verify this works correctly? -->

## Accessibility Considerations
<!-- Does this change affect screen reader output? WCAG compliance?
     Keyboard navigation? If yes, describe what was tested. -->

## Related Issues
<!-- Use "Closes #N" to auto-close the issue when this PR is merged -->

Using it when opening a PR: The template auto-fills the PR description field. Tab through the sections with your screen reader and fill in each one. Delete placeholder comments (<!-- ... -->) - they will not appear in the rendered PR but can confuse screen readers if left in.

9. Hands-On Activity

Exercise A - Use an Existing Template

Your Mission: File your first issue using a structured template. You'll experience the template as an end-user, which teaches you what good template design feels like.

What You'll Learn: How templates guide contributors, what fields are required vs optional, and whether screen reader announced all fields clearly.

Step 1: Navigate to the Accessibility Agents Issues Section

What to do
  1. Open GitHub in your browser
  2. Navigate to the community-access/accessibility-agents repository (or your fork)
  3. Click the Issues tab (top navigation, between Pull Requests and Discussions)
  4. You should see a list of existing issues
What you should see
  1. Click the "New issue" button
If you can't find it

Step 2: View the Template Chooser with Your Screen Reader

What to do
  1. You should now see a Template Chooser page
  2. The page displays available templates as buttons or links
  3. With screen reader: Navigate through the templates:
    • NVDA/JAWS: Press Tab to move between templates, Enter to select one
    • VoiceOver: Use VO+Right Arrow to move between elements, then VO+Space to activate
  4. Count the templates and read their descriptions aloud (or write them down):
    • Template 1: [name] - [description]
    • Template 2: [name] - [description]
    • And so on...
What you're listening for
Write down

Step 3: Select a Template

What to do
  1. Choose the template closest to a real issue type you identified on Day 1 (e.g., if you noted "screen reader navigation bug," select the Accessibility Bug Report template)
  2. Click it (or press Enter if focused with keyboard)
What happens
If no template matches exactly

Step 4: Navigate the Form Fields

What to do
  1. The issue form is now open
  2. Navigate through all visible fields using your screen reader or by tabbing:
    • NVDA/JAWS: Press Tab to move to the next field, Shift+Tab to go back
    • VoiceOver: Use VO+Down Arrow to read fields in order
  3. For each field, note:
    • Field label (announced by screen reader)
    • Help text or placeholder (hints about what to enter)
    • Whether it's marked as required (usually with a red * or the word "required")
  4. Write down at least 3 fields and whether each is required:
    • Field: [name] - Required? [Yes/No]

Step 5: Fill In the Form

What to do
  1. Fill in at least 3 fields with realistic content based on an issue you identified on Day 1
    • Example: If the template asks "Screen Reader," select "NVDA"
    • If it asks "Steps to reproduce," write 2-3 specific steps
  2. For required fields marked with *: Fill them in completely
  3. For optional fields: Choose at least one and fill it in (so you test optional fields)
  4. Don't worry about filling in every field - the point is to test the form
What to expect

Step 6: Preview the Issue Before Submitting

What to do
  1. Look for a Preview tab or button (usually near the top of the form, next to "Write" or "Markdown")
  2. Click it (or press the hotkey shown)
  3. A preview pane appears showing how the issue will look when published
With screen reader
What to look for
If something is unclear

Step 7: Submit the Issue

What to do
  1. Once you're satisfied with the preview, go back to the "Write" tab
  2. Locate the green "New issue" button (usually at the bottom of the form)
  3. With keyboard: Press Tab until the button is focused, then Enter
  4. With mouse: Click the button
  5. The issue is submitted and you see the new issue page with your content
What happens

Step 8: Checkpoint - Reflect on the Template

After submitting, answer:

  1. Template Clarity: Did the template guide you toward providing useful information, or did fields feel confusing or unnecessary?
  2. Screen Reader Accessibility: Were all field labels announced clearly? Did you encounter any accessibility barriers?
  3. Required vs Optional: Was it obvious which fields were required? If you skipped an optional field, would you have known it was optional?
  4. Context Helpfulness: Did the placeholder text or help text under each field make you understand what information to provide?

Record these answers. You'll use them in Exercise D when you design your own template.

Exercise B - Add the Accessibility Bug Report Template to Your Fork

Your Mission: Create your own instance of the accessibility bug report template in your personal fork. This teaches you the file structure and gives you hands-on experience with YAML syntax.

What You'll Learn: How templates are stored as files, what YAML syntax looks like, and how to test templates locally.

Prerequisites:

Step 1: Clone Your Fork to Your Machine

What to do
  1. Open a terminal (PowerShell on Windows, Terminal on macOS/Linux)
  2. Navigate to a folder where you want to store the project:

    cd ~/projects

    (Or wherever you keep code projects)

  3. Clone your fork:

    git clone https://github.com/[YOUR-USERNAME]/accessibility-agents.git

    Replace [YOUR-USERNAME] with your actual GitHub username

  4. Wait for the clone to complete (should take 10-30 seconds)

  5. Navigate into the folder:

    cd accessibility-agents
What you should see
If you get an error

Step 2: Open Your Fork in VS Code

What to do

  1. From the terminal, while in your accessibility-agents folder, type:

    code .
  2. Press Enter
  3. VS Code opens with your fork loaded
What you should see
If code . doesn't work

Step 3: Navigate to the Templates Folder

What to do
  1. In VS Code's file tree (left sidebar), expand the .github folder
  2. Inside, find and expand the ISSUE_TEMPLATE folder
  3. You should see existing template files (like bug-report-template.yml or similar)
What you're looking at
If the folder doesn't exist

Step 4: Create a New Template File

What to do
  1. Right-click on the ISSUE_TEMPLATE folder
  2. Select New File
  3. Name it: accessibility-bug.yml (exactly this name)
  4. Press Enter
What happens

Step 5: Copy the Accessibility Template YAML

What to do
  1. Go to Chapter 15, Section 7 in this curriculum
  2. Find the complete YAML template code block (starting with name: and ending with the last field)
  3. Select all the YAML code (use Ctrl+A on the webpage or manually select)
  4. Copy it (Ctrl+C)
  5. Go back to VS Code
  6. Paste it into your new accessibility-bug.yml file (Ctrl+V)
What you should see

Step 6: Verify the YAML Syntax

What to do
  1. Save the file (Ctrl+S)
  2. Look at the bottom right of VS Code - you may see some notifications
  3. Check if VS Code shows any red squiggly lines (indicating syntax errors)
Common YAML errors to watch for
If you see red squiggles
  1. Hover over the error to see what VS Code suggests
  2. Compare your file with Section 7's template - look for extra/missing spaces or colons
  3. Make corrections and save again
If you see no errors

Step 7: Create a Branch and Commit

What to do
  1. Open the terminal in VS Code: Terminal → New Terminal (or Ctrl+ ` on Windows)
  2. You should be in the accessibility-agents folder already

  3. Create a new branch for this change:

    git checkout -b feat/add-accessibility-template

  4. Add the file to git:

    git add .github/ISSUE_TEMPLATE/accessibility-bug.yml

  5. Commit with a message:

    git commit -m "feat: add accessibility bug report template"

  6. Push to your fork:

    git push origin feat/add-accessibility-template
What happens
If you get errors

Step 8: Test the Template in GitHub Web

What to do
  1. Open GitHub in your browser
  2. Go to your fork: https://github.com/[YOUR-USERNAME]/accessibility-agents
  3. You should see a notification or purple bar saying "Compare & pull request" (your new branch)
  4. But instead of opening a PR, click the Issues tab
  5. Click New issue
  6. You should now see your new template in the chooser: "Accessibility Bug Report"
  7. Click it to open the form
What you should see
If you don't see the new template

Step 9: Test with Your Screen Reader

What to do
  1. With screen reader activated: Navigate through the template form using your reader's commands
  2. For each field, note:
    • Is the label announced clearly?
    • Is it obvious whether the field is required?
    • Do dropdowns announce their options correctly?
    • Are descriptions/help text announced?
  3. Answer:
    • Did you encounter any accessibility barriers?
    • Would a screen reader user find this template easy to use?

Record your findings - you'll use this for Exercise D.

Step 10: Merge Your Branch (Optional)

What to do
  1. Open an PR for your branch:
    • Go to your fork on GitHub
    • You should see a "Compare & pull request" button
    • Click it
  2. Add a title: feat: add accessibility bug report template
  3. Add a description: This template guides contributors to report accessibility issues with clear fields for screen reader type, browser, and WCAG criteria.
  4. Click Create pull request
  5. Review your PR (using skills from Chapter 14!)
  6. If satisfied, click Merge pull request to merge it into your fork's main branch
Why merge?

Checkpoint

After completing Steps 1-9, verify:

  1. You created a file named accessibility-bug.yml in .github/ISSUE_TEMPLATE/
  2. The file contains valid YAML (no red squiggles in VS Code)
  3. The template is visible when you click "New issue" in your fork
  4. You tested it with your screen reader and noted any issues

You're ready for Exercise C!

Exercise C - Submit It Upstream

Your Mission: Contribute your tested template to the upstream community-access/accessibility-agents repository. This is a real open source contribution!

What You'll Learn: The PR process for submitting contributions upstream, working with maintainers, and seeing your code merged into an open source project.

Prerequisites:

Step 1: Verify Your Template is Ready

Before submitting upstream, make sure your template is production-ready:

What to do
  1. Go to your fork on GitHub
  2. Click Issues → New issue
  3. Verify your template appears and is named "Accessibility Bug Report"
  4. Open it and fill it out once more to confirm:
    • All fields display correctly
    • No broken formatting
    • Dropdowns work properly
    • Required fields are marked
  5. Don't submit this test issue - just close the tab
What success looks like

Step 2: Create the Pull Request

What to do
  1. Stay on your fork's GitHub page
  2. You should see a "Compare & pull request" button (or look for your feature branch)
  3. If that button doesn't appear:
    • Click the Code tab
    • Click the branches dropdown
    • Select your branch (feat/add-accessibility-template)
    • Click "New pull request" to the right
  4. A PR creation page opens showing:
    • Base: community-access/accessibility-agents / main (the upstream repo)
    • Head: [your-username]/accessibility-agents / feat/add-accessibility-template (your fork/branch)
  5. Confirm this is correct - you're sending your branch to the upstream repository
What you should see

Step 3: Write Your PR Title and Description

Form fields to fill
Title
feat: add accessibility bug report template
Description

Write a clear description that explains what you're contributing:

## What Does This PR Do?

This PR adds a comprehensive GitHub issue template for filing accessibility 
(a11y) bug reports. The template uses a form-based structure (YAML) to guide 
contributors through providing crucial accessibility context.

## Why Is This Useful?

Accessibility issues are often under-reported because contributors don't know 
what information maintainers need. This template standardizes that data:
- Screen reader type (NVDA, JAWS, VoiceOver, etc.)
- Browser and OS version
- WCAG success criterion affected
- Steps to reproduce the issue
- Expected vs. actual behavior

## How Was This Tested?

- YAML syntax validated (no errors)
- Template displays correctly in GitHub web UI
- All fields announced clearly with screen reader (NVDA/JAWS/VoiceOver)
- Dropdown options are navigable
- Required fields are properly marked
- Form preview is accessible

## Related Issue

Closes #[issue number] (if there is an open issue requesting this feature)

What to do

  1. Copy the template above into the description field
  2. Edit it with your actual testing experience:
    • Which screen reader(s) did you test with?
    • Did you find any issues? (Be honest if you did!)
    • Did you test with a colleague or friend for feedback?
  3. Keep it concise but thorough

Step 4: Review Your PR Before Submitting

What to do
  1. Scroll down and preview your PR description as it will appear
  2. Using your screen reader, read through it:
    • Is the title clear about what you're adding?
    • Does the description explain the value of this template?
    • Are all checkmarks (``) and formatting visible?
  3. Make any corrections needed
  4. Do not submit yet - continue to Step 5

Step 5: Submit the PR

What to do
  1. Click the green "Create pull request" button
  2. Your PR is now submitted to the upstream repository
  3. You see a confirmation page showing your new PR number (e.g., "#42")
  4. GitHub may automatically assign reviewers or run CI checks
What happens next
What success looks like

Step 6: Respond to Feedback

If maintainers leave comments
What to do
  1. Read their feedback carefully using your screen reader
  2. Understand what changes they're requesting (or what they're praising!)

  3. If changes are needed:

    • Go back to your fork in VS Code
    • Edit the accessibility-bug.yml file accordingly

    • Commit and push:

      git add .github/ISSUE_TEMPLATE/accessibility-bug.yml
git commit -m "Address feedback from maintainers: [brief description]"
git push origin feat/add-accessibility-template
    • Your changes automatically appear in the PR (linked to the branch)

  4. Leave a reply comment on the PR:

    Thanks for the feedback! I've made the changes you requested 
in commit [commit hash]. The template now includes [what you changed].
  5. Click Reply
If no feedback after 48 hours

Step 7: Celebrate Your Contribution

When your PR is merged
  1. You'll see the PR status change to "Merged"
  2. Your template is now part of the community-access/accessibility-agents repository
  3. Everyone who forks that repo will get your template
  4. You can claim this as a real open source contribution
What to do

Checkpoint

After completing Steps 1-7, verify:

  1. You created a PR to the upstream repository
  2. Your PR includes a clear description of what you're contributing
  3. Your template is the only change in the PR (one file)
  4. You addressed any feedback from maintainers
  5. Your PR was merged (or is waiting for merge)
Reflect

Exercise D - Design a Template for Your Own Project

Your Mission: Apply everything you've learned to design a template for a repository you own, maintain, or plan to create.

What You'll Learn: How to make design decisions about required vs. optional fields, field types, and how to test your template with real users.

Time estimate: 30-45 minutes (can be done after the workshop)

Part 1: Choose Your Project

What to do

  1. Think of a repository you have a personal connection to:

    • A project you own or maintain
    • A project you contribute to regularly
    • A project you plan to create (even if just in your head)
    • A project that's important to your workplace

  2. Write down the project name and briefly why chose it:

    Project: [name]
Why it matters to me: [1 sentence]

Current state: Exists, I maintain it
               Exists, I contribute to it
               I'm planning to create it
               Other: [describe]
What success looks like

Part 2: Identify Issue Patterns

Your task: Study the issues your project receives (or would receive) to understand what information is most valuable.

What to do
If your project already has issues
  1. Open your issue list in GitHub
  2. Read the last 5-10 issues (or all open issues if fewer)

  3. For each issue, ask yourself:

    • What problem was the reporter describing?
    • What information helped you (or would help) understand the issue?
    • What information was missing that you had to ask for?

  4. Write down 3-5 patterns:

    Issue Type 1: [what kind of issues are most common?]
- Essential info needed: [what always helps?]
- Often missing: [what do you always have to ask for?]

Issue Type 2: [second most common type]
- Essential info needed: [what?]
- Often missing: [what?]
If your project doesn't exist yet or has no issues

  1. Think about the type of issues you'd want to receive:

    • Bug reports?
    • Feature requests?
    • Documentation improvements?
    • All of the above?
  2. For each type, ask: "If someone reported this issue, what would I need to know?"

  3. Write down:

    Issue Type 1: [e.g., "Bug Report"]
- Essential info needed: [e.g., "What OS? Browser? Steps to reproduce?"]
- Questions I'd ask: [What follow-ups would I need?]

Issue Type 2: [e.g., "Feature Request"]
- Essential info needed: [e.g., "What problem does this solve?"]
- Questions I'd ask: [e.g., "Who else has asked for this?"]
What success looks like

Part 3: Design Your Required Fields

Your task: List the fields you absolutely need to understand an issue.

What to do

Rule: Keep required fields minimal. If a field is required, you genuinely cannot triage without it.

  1. Create a table:

    Field Name -- Type (dropdown/input/textarea) -- Why Required? -- Options (if dropdown)
[name]     -- [type]                        -- [reason]      -- [choices]

  2. For each issue type from Part 2, add 2-4 required fields:

    Example for "Bug Report":

    Field Type Why? Options
    Component dropdown "I have 5 components; knowing which is affected saves triage time" Component A, B, C, D, E
    Steps to Reproduce textarea "I cannot fix what I cannot replicate" (free text)
    OS dropdown "Bugs are often OS-specific" Windows, macOS, Linux

  3. Write down at least 2 required fields:

    Required Field 1: [name]
- Type: [dropdown / input / textarea?]
- Why is it required? [explain as if to the issue reporter]
- If dropdown, options: [list them]

Required Field 2: [name]
- Type: [type]
- Why is it required? [explain]
- If dropdown, options: [list them]
What success looks like

Part 4: Design Your Optional Fields

Your task: Add optional fields that would be helpful but aren't blocking.

What to do

  1. Brainstorm nice-to-have information:

    • Information that's helpful but you could triage without it
    • Information that helps you prioritize or assign the issue
    • Information that provides missing context

  2. Example optional fields for a bug report:

    • Environment details (CPU, RAM, versions of dependencies)
    • Screenshots or links
    • Workarounds the reporter has found
    • When the issue started happening

  3. Write down at least 2 optional fields:

    Optional Field 1: [name]
- Type: [dropdown / input / textarea / checkboxes?]
- Why include it? [what does it help with?]

Optional Field 2: [name]
- Type: [type]
- Why include it? [what insight does it provide?]

  4. For each field, decide:

    • Should this be a dropdown (bounded choices) or free text (open-ended)?
    • If dropdown, list the options
    • If textarea, what's a helpful placeholder or example?
What success looks like

Part 5: Write Field Placeholders and Help Text

Your task: For each field, write helpful placeholder or description text that guides the reporter.

What to do

For each required and optional field, draft:

  1. Field label (the visible name)
  2. Description (short help text)
  3. Placeholder (example of what to type, for input/textarea fields)
Examples
Field: "Steps to Reproduce"
Description: "Numbered list of actions that trigger the bug"
Placeholder: "1. Open the settings menu
2. Click 'Advanced Options'
3. Toggle the switch
4. The app crashes"


Field: "Expected Behavior"
Description: "What should happen if everything worked correctly?"
Placeholder: "The settings should save silently and the app should remain open"
Write these for at least 3 of your fields
Field 1: [name]
Description: [guidance for the reporter]
Placeholder: [example of good input]

Field 2: [name]
Description: [guidance]
Placeholder: [example]

Field 3: [name]
Description: [guidance]
Placeholder: [example]
What success looks like

Part 6: Test Your Template Locally

Your task: Create a draft YAML template file and test it with your screen reader.

What to do

  1. Create a text file with your template in YAML format. Use Section 6 as a template:

    • Start with the frontmatter (name:, description:, title:, labels:)
    • Add your fields in the body: section
    • Use appropriate field types (input, textarea, dropdown, checkboxes)

  2. Save it locally (not yet in GitHub):

    • Name it: [your-project-name]-template.yml
    • Save it to your desktop or a projects folder

  3. Open it in VS Code and check:

    • Is the YAML syntax correct? (no red squiggles)
    • Does every field have an id, label, and attributes?
    • Are required fields in a validations: block?

  4. Test the structure:

    • Print it out or read it aloud
    • Does your field order make sense? (Related fields together?)
    • Are required fields grouped before optional?
    • Is any field confusing or unclear?

  5. With your screen reader:

    • Open the YAML file in your editor
    • Navigate through it with your reader
    • Can you understand the structure: name, description, then body with fields?
    • Are the field labels clear?
If you find issues
What success looks like

Part 7: (Optional) Deploy to GitHub and Test with a Friend

Your task: Upload your template to a GitHub repository and test it with a colleague or friend.

What to do

This is optional but powerful - real user testing is the best validation.

  1. Upload your template to a test repository:

    • Create a test branch in a personal repo
    • Add your template file to .github/ISSUE_TEMPLATE/
    • Push the branch

  2. Ask a colleague or friend:

    • "Could you try filing an issue using this template?"
    • "What did you find confusing?"
    • "Did any required fields feel unnecessary?"
    • "Were the descriptions helpful?"

  3. Collect feedback:

    • What worked well?
    • What was confusing?
    • Did they skip any optional fields? (If yes, consider removing them)
    • Would they suggest different field options?
  4. Refine your template based on their feedback

Part 8: Reflect on Your Template Design

Your task: Document what you learned from this exercise.

What to do

Write answers to these questions:

  1. Decision-making: Which field did you debate including? Why did you finally decide yes or no?

    Field: [name]
Debate: [why was this hard to decide?]
Decision: [required / optional / removed]
Reason: [what made you decide?]

  2. Trade-offs: You can't ask for everything without overwhelming reporters. What information did you choose not to ask for? Why?

    Information I didn't include: [example]
Why I chose not to ask: [explanation]
Would I change this? [yes/no] + why

  3. Iteration: If you had user feedback (from Part 7), what did you learn?

    Feedback: [what did your friend/colleague say?]
Change you made: [how did you refine?]
Why it helped: [what improved?]

  4. Real-world readiness: Would you actually deploy this template to a real project?

    Readiness: Yes, I'm confident
           Maybe, with more testing
           No, I need to rethink some fields
Next step: [what would you do next?]
What success looks like

Checkpoint

After completing Parts 1-8, you have:

You now understand the thinking that separates "a blank text box" from "structured, actionable contributions."

This skill - understanding what information actually matters - is what makes great templates. The YAML syntax is just the delivery mechanism. The hard part is the thinking you did in Parts 1-5.

You've Completed the Template Exercises

You now:

  1. Understand templates from the user perspective (Exercise A)
  2. Can create and deploy templates yourself (Exercise B)
  3. Know how to contribute upstream (Exercise C)
  4. Can design templates with real thinking behind them (Exercise D)

In Chapter 16 (Accessibility Agents), you'll see how the @template-builder agent automates the YAML writing part - but you bring the design thinking from this exercise. The agent generates YAML; you decide what questions to ask.

10. Day 2 Amplifier: The Template Builder Agent

Everything you just learned - field types, YAML structure, accessibility testing - is core GitHub knowledge. Now see how Accessibility Agents amplifies it.

Our 6th agent, @template-builder, is an interactive wizard that generates issue templates guided by your answers to simple questions. Instead of writing YAML by hand, you answer prompts and the agent produces a production-ready template in seconds.

How It Works

In VS Code

You: @template-builder create accessibility template
Agent: [Ask Questions interface]
  • Template name? → "Accessibility Bug Report"
  • What's this for? → "Report screen reader and keyboard issues"
  • First field? → "Screen Reader (dropdown)"
  • Options? → "NVDA, JAWS, VoiceOver, TalkBack, Other"
  • Required? → "Yes"
  [... continues field by field]
Agent: Here's your YAML template [syntax-highlighted code block]

Then you copy, paste to .github/ISSUE_TEMPLATE/your-template.yml, commit, and done.

Why It Matters

Approach Time Expertise Error Rate
Manual YAML 15-20 min High (YAML syntax) Medium (typos, missing colons)
Copy-Paste Example 10-15 min Medium Low (if example is good)
Agent-Guided 2-3 min Low (just describe) Very Low (structured output)

The Template Builder does not teach you to design templates - Section 5 taught you that. It automates the mechanical part: translating your decisions into working YAML.

Using the Template Builder

Prerequisite: Complete Exercise D above. You should understand what fields you want to ask for and why.

Chapter 16 Exercise (Accessibility Agents): Use @template-builder to generate a template for a real project, then customize or extend it. See Accessibility Agents: Contributing to the Ecosystem.

After the Workshop: Any repetitive GitHub task - templates, checklists, workflows - can be built with Accessibility Agents. The Template Builder shows how.

Next: Accessibility Agents Back: Accessible Code Review Related: Working with Issues | Culture & Etiquette | Accessibility Agents