Optimizing GitHub Copilot for Accessibility with Custom Instructions

Guide Topics

 Skip to content

Custom instructions empower you to optimize accessibility by shaping how GitHub Copilot behaves within your organization or repository. Every team has unique accessibility requirements, coding standards, and development practices—custom instructions help ensure GitHub Copilot’s suggestions align with these needs.

Ready to dive in? Let’s look at how to set up custom instructions, followed by some practical Do’s and Don’ts for writing accessibility-focused guidance!

Custom Instructions Setup

Follow these instructions to setup GitHub Copilot custom instructions at each policy level:

  • Organization level setup - organization level instructions cascade to all repositories. This is where your team can define high-level accessibility standards for all projects.
  • Repository level setup - repository level instructions apply only to the specific repository they are defined in. They can be used to override organization-wide standards, handle exceptions, or define requirements unique to that repository.
  • Personal instruction setup - personal custom instructions can be added to customize GitHub Copilot Chat according to your own preferences. These instructions take precedence over other instructions and allow you to guide GitHub Copilot’s responses to best suit your individual needs.

Instruction Do’s 👍

Follow these do’s for writing accessibility-focused GitHub Copilot instructions.

Focus on Team-Specific Workflows, Tools, and Standards

When writing custom instructions, specify the standards, tools, or workflows unique to how your team evaluates accessibility. For example, explicitly stating that your team follows WCAG 2.2 guidance tells GitHub Copilot which version of the standard to reference when reviewing front-end changes:

This application MUST conform to version 2.2 of the Web Content Accessibility Guidelines

If your company’s accessibility goals go beyond legal compliance, use custom instructions to direct GitHub Copilot to apply your preferred or most up-to-date standards (such as the latest version of WCAG).

This level of specificity helps GitHub Copilot operate much like a member of your organization, making its suggestions more relevant and consistently aligned with your accessibility goals.

Reference and Enforce Design System Standards

Provide explicit instructions about which design system GitHub Copilot should reference, and document any updates, deprecations, or caveats directly in your custom instructions. For example:

DeprecatedButton SHOULD NOT be used; instead, use NewAccessibleButton.

Explicit instructions about your design system help ensure your team consistently benefits from the latest improvements. Since design systems evolve over time, some components may become outdated or less accessible. Instruct GitHub Copilot to always use the latest, most accessible components available to avoid accessibility regression.

Use Precise Language Like MUST, MUST NOT, SHOULD or SHOULD NOT

Most language models (LLMs), including GitHub Copilot, respond well to normative language—words like “SHOULD”, “MUST”, or “MAY.” These terms help LLMs recognize and understand your intent by reducing ambiguity and clarifying which rules are mandatory versus optional.

## Instructions for defining keyboard shortcuts 
- Keyboard shortcuts SHOULD NOT override high-priority browser/operating system shortcuts. 
- A keyboard shortcut MUST use no more than 4 simultaneous keys

For many, this approach is familiar, as WCAG guidelines also use normative language to define accessibility success criteria. By mirroring this approach, not only will your custom instructions feel familiar to anyone used to accessibility work, but you will also ensure your instructions are non-ambiguous.

Keep in mind that some situations may require flexibility. While it can be tempting to always use “MUST,” there are likely scenarios where exceptions are necessary and rules may need to be broken.

Use lists to format your instructions

Like normative language, clear and structured lists help LLMs operate consistently. Lists provide guardrails that keep AI (and developers) on track when solving a problem. When writing accessibility-focused instructions, try formatting your requirements as a checklist or list. This helps GitHub Copilot understand the necessary steps and ensures important accessibility criteria are not overlooked.

This checklist's instructions extend standard WCAG for GitHub Copilot coding agent and GitHub Copilot code review. **Follow our internal Accessibility Council's decisions and exceptions for each criterion.**

## Checklist for evaluating 1.3.1 Info and Relationships
- [ ] `role="presentation"` or `role="none"` MUST NOT be applied to semantic elements.
- [ ] Error messages MUST be programmatically associated with inputs.
- [ ] `<h1>` is RECOMMENDED for usability, NOT REQUIRED for compliance.
- [ ] Name-value pairs and taglines MUST NOT use headings; use `<p>`.
- [ ] Legend text visually appearing as a heading MUST be legend, MAY also be heading.

The example outlined above gives GitHub Copilot a clear checklist to follow when evaluating UI against WCAG success criteria 1.3.1. By structuring requirements as a checklist, you help GitHub Copilot implement your organization’s standard practices.

Instruction Don’ts 👎

Follow these don’ts for writing accessibility-focused GitHub Copilot instructions.

Don’t Paste an Entire Set of Guidelines

LLMs are trained on broad data from across the internet and are already aware of standards like WCAG. Simply copying and pasting WCAG guidelines into your instructions often isn’t very helpful.

(omitted for brevity, don’t paste guidelines in full)

Instead of providing lengthy guideline text, focus on crafting concise, actionable instructions that address your team’s specific accessibility needs. For example, highlight unique practices your team follows or specify which success criteria is top priority. These examples provide net-new information to GitHub Copilot and help GitHub Copilot generate code that aligns with your intent.

Note: Several GitHub Copilot products allow you to configure which LLM is used. Each LLM has a specific cutoff date indicating the most recent data included in its training. For details on data coverage and training periods, see the documentation provided by the LLM’s vendor.

By default, GitHub Copilot does not access external links in custom instructions.

You MUST use https://www.w3.org/WAI/standards-guidelines/wcag/ to evaluate accessibility.

This limitation is a deliberate security feature designed to protect user privacy. As a result, adding links into custom instructions is generally ineffective. Additionally, the content behind links can change unexpectedly over time.

Instead, directly write the relevant instructions or guidance into your custom instructions to ensure clarity and safety. However, if you use information from an external source, it’s still good practice to include the link as a reference for human readers; this won’t negatively affect GitHub Copilot.

Don’t Reference Information in Other Private Repositories

When writing instructions, avoid referencing private repositories unless the instructions are explicitly stored within the repo. GitHub Copilot cannot access private repositories content unless the content is available within the repo it is running in.

Ensure you follow our accessibility guidance written in the some-org/private-accessibility repo.

Additional Considerations

Finally, it’s important to mention a few methods for writing instructions that should be approached with caution.

Role-Based Prompting

Role-based prompting is a concept where you assign a persona or set a scene for GitHub Copilot to help it respond in a particular way. For example, you might use a prompt like:

As the lead accessibility expert on your team, your teammates lean on you for accessibility guidance and WCAG best practices. Your primary focus is ensuring that all UI is accessible by default, relying on standards like semantic HTML before using ARIA attributes or less common solutions.

In custom instructions, you can use language such as “you are an __” to give GitHub Copilot a specific persona, or “you are talking to a __” to help GitHub Copilot understand its audience and adjust the level of explanation or verbosity accordingly.

This type of instruction writing or prompting can be very beneficial as it gives GitHub Copilot a lot of useful context and helps tailor its responses to match your team’s needs and expectations. However, by setting up a specific role for GitHub Copilot to follow, you may also introduce bias into how it responds. Almost any persona or role can carry certain assumptions, especially since AI is trained on a wide variety of data. Be careful and review any roles you introduce into your prompt. Try to be specific about skills and responsibilities, stay neutral, and focus on professional functional language.

Verbosity

When it comes to verbosity, custom instructions should be concise, clear, and focused. Although there isn’t a strict character limit, overly lengthy instructions can reduce the precision and performance of AI models. In some situations, you may want to include more detailed instructions—hence the lack of a character limit—but it’s important to consider whether the details you add truly provide value.

Avoid the temptation to include every possible accessibility guideline; instead, concentrate on summarizing the most important rules and actionable practices. Clear and targeted instructions help GitHub Copilot generate more effective and relevant suggestions for your team.

Share with the Community

Writing effective custom instructions requires experimentation and iteration. Consider contributing your results to the github/awesome-copilot repository so others can benefit from your experience.

Note: Before sharing your custom instructions publicly, carefully review them to ensure they do not contain any sensitive or confidential information.

Resources

Contributors

Special thanks to @kendallgassner (author) and @mlama007.

Please share questions or comments on the accessibility community discussion page.

Accessibility Documentation