feat: Add comprehensive AI agent instructions for accessibility devel… #335

joe-watkins · 2025-11-04T20:04:12Z

Adds instructions for AI agents to adhere to. AGENTS.md is the newer industry standard to support multiple IDEs with a single instructions file. AI Agents will pull these instructions into every chat context.

Two key sections: Project-specific rules based the this project and Accessibility rules that AIs should respect.

https://github.com/openai/agents.md
https://code.visualstudio.com/docs/copilot/customization/custom-instructions

silverli · 2025-11-26T16:37:01Z

AGENTS.md

+### Documentation (Markdown)
+- All documentation files go in `/public/content/documentation/`
+- Follow the structure: `<section>/<category>/<filename>.md`
+- Use the provided templates: `criteria` or `how-to-test`


the templates are output by src/scripts/createMarkdown.sh which we might want to mention since that is where the actual templates are as well

silverli · 2025-11-26T16:37:23Z

AGENTS.md

+- Follow the structure: `<section>/<category>/<filename>.md`
+- Use the provided templates: `criteria` or `how-to-test`
+- Use the script: `npm run create-md -- <filename> "<relative-path>" <template-type>`
+- Reference the MARKDOWN_GUIDE.md for formatting standards


Should we use the relative path to where this GUIDE is? Does it need that?

silverli · 2025-11-26T16:37:45Z

AGENTS.md

+## Testing Requirements
+- Write unit tests for all new components
+- Update snapshots when component structure changes intentionally
+- Run tests before committing: `npm test`


Run linting: npm run lint and npm run lint:scss

silverli · 2025-11-26T16:38:20Z

AGENTS.md

+5. Add to navigation if needed using `npm run create-md`
+
+### Updating Documentation
+1. Never manually create markdown files - use the script


Should we restate the script command and documentation here?

silverli · 2025-11-26T16:38:28Z

AGENTS.md

+
+### Updating Documentation
+1. Never manually create markdown files - use the script
+2. Keep examples accessible and code snippets valid


Rewrote this to make a bit more sense

silverli · 2025-11-26T16:38:55Z

AGENTS.md

+You are an expert full-stack accessibility developer. MagentaA11y V2 is an accessibility accessibility accpeptance criteria documentation platform built with React and TypeScript. The project provides comprehensive accessibility guidelines, testing procedures, and best practices for web and native applications.
+
+## Core Principles
+1. **Accessibility First**: All code and documentation must follow WCAG guidelines and accessibility best practices


Should we specify WCAG 2.2 and the WAI-ARIA version?

Yes! Brought in versions

silverli · 2025-11-26T16:40:11Z

AGENTS.md

+- `npm run parse-md-files` - Update markdown files
+- `npm test` - Run tests
+
+## Important Notes


Should we mention the easily AI readable content.json file somewhere to learn about the project?

silverli · 2025-11-26T16:41:29Z

AGENTS.md

+Avoid generating content that reflects implicit bias or outdated patterns. Critically assess accessibility choices and flag uncertain implementations.
+
+- **Verification-Oriented Responses**
+When suggesting accessibility implementations or decisions, include reasoning or references to standards (e.g., WCAG, platform guidelines). If uncertainty exists, the assistant should state this clearly.


can we actually say, "always reference standards and resources used" in this case?

Yes! Edited

silverli · 2025-11-26T16:42:01Z

AGENTS.md

+
+### Anti-Patterns and Mistakes to Avoid
+- Using only placeholders to label inputs
+- Suppressing visible focus with CSS resets or browser overrides


how about use Semantic HTML over ARIA roles whenever possible?

silverli · 2025-11-26T16:43:15Z

AGENTS.md

+```
+- Avoid overuse of sectioning elements and ARIA landmarks
+- Don't add any ARIA attributes unless asked to, rely on web standards first
+- Using generic containers when semantic elements would be more appropriate


Do you need a "Don't" or "Avoid" in front of this one?

Hmm or maybe it should preface the whole section?

Yes and Yes - reworked this

silverli

Great start!! A couple questions and comments added. I think we should get one more AI review maybe from Lawrence or Jules

MyLightIsOn · 2025-12-03T22:46:34Z

AGENTS.md

+```html
+<button>Click me</button>
+```
+- Don't apply role="link" to a Link <a>


This tag without an attribute is making the following headings look like links.

jtweb23 · 2025-12-03T23:26:44Z

Item #1) Line 252
- 4.5:1 for normal text (defined as up to and including 18.5px regular or 14pt bolded)
Checking on the 1.4.3 Contrast minimum for regular text. Did we mean to say ‘14pt` unbolded ??

jtweb23 · 2025-12-03T23:40:07Z

Item #2) Had a content idea to consider including Tables. Maybe we could start with consideration of simple data tables versus presentation layout tables:
Tables that have structured content which must be linearized by screen readers and similar assistive technology are coded as simple data tables. Simple Data Tables
·      Column headers or Row headers in simple data tables use semantic tags.
·      Data Tables do not use CSS such as CSS Flexbox, CSS Grid, other non-semantic visual positioning attributes to indicate relationships in between table data cells and headers.
Presentation tables
·      Tables that are used for layout or presentation use role=”presentation”.

joe-watkins · 2025-12-04T03:04:56Z

@jtweb23 @MyLightIsOn @silverli We could pull in some some content from these instructions too:
https://github.com/github/awesome-copilot/blob/main/instructions/a11y.instructions.md

@jtweb23 There's some good <table> content there we could borrow.
https://github.com/github/awesome-copilot/blob/main/instructions/a11y.instructions.md#table-and-grid-accessibility-acceptance-criteria

…opment

joe-watkins · 2025-12-05T22:55:41Z

Item #1) Line 252 - 4.5:1 for normal text (defined as up to and including 18.5px regular or 14pt bolded) Checking on the 1.4.3 Contrast minimum for regular text. Did we mean to say ‘14pt` unbolded ??

joe-watkins · 2025-12-05T22:58:46Z

I've folded in all feedback!

Item #1) Line 252 - 4.5:1 for normal text (defined as up to and including 18.5px regular or 14pt bolded) Checking on the 1.4.3 Contrast minimum for regular text. Did we mean to say ‘14pt` unbolded ??

@jtweb23 I've rewritten this to be a little more readable and just went with px. pt conversions are complex. I also moved it up into it's own little section.

Item #2) Had a content idea to consider including Tables. Maybe we could start with consideration of simple data tables versus presentation layout tables: Tables that have structured content which must be linearized by screen readers and similar assistive technology are coded as simple data tables. Simple Data Tables · Column headers or Row headers in simple data tables use semantic tags. · Data Tables do not use CSS such as CSS Flexbox, CSS Grid, other non-semantic visual positioning attributes to indicate relationships in between table data cells and headers. Presentation tables · Tables that are used for layout or presentation use role=”presentation”.

@jtweb23 I've added Tables to the bottom of the file :) Great callout

I think we are good when everyone Resolves there feedback items if happy. We can iterate on this as we get in there and Dev with it. I think especially when it comes to some of the React specific stuff. @silverli @MyLightIsOn

ps. I was also sure to rebase so merge should be cool.

joe-watkins requested a review from silverli November 4, 2025 20:05

silverli added the In review label Nov 5, 2025

silverli reviewed Nov 26, 2025

View reviewed changes

silverli requested changes Nov 26, 2025

View reviewed changes

silverli requested a review from MyLightIsOn December 3, 2025 21:29

MyLightIsOn reviewed Dec 3, 2025

View reviewed changes

jtweb23 self-requested a review December 3, 2025 23:03

joe-watkins added 2 commits December 5, 2025 13:56

feat: Add comprehensive AI agent instructions for accessibility devel…

14f8154

…opment

Roll in feedback and add Tables

2529736

joe-watkins force-pushed the feat--add-ai-custom-instructions branch from 70a743d to 2529736 Compare December 5, 2025 22:50

feat: Add comprehensive AI agent instructions for accessibility devel… #335

Are you sure you want to change the base?

feat: Add comprehensive AI agent instructions for accessibility devel… #335

Uh oh!

Conversation

joe-watkins commented Nov 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

silverli left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jtweb23 commented Dec 3, 2025

Uh oh!

jtweb23 commented Dec 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

joe-watkins commented Dec 4, 2025

Uh oh!

joe-watkins commented Dec 5, 2025

Uh oh!

joe-watkins commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

joe-watkins commented Nov 4, 2025 •

edited

Loading

jtweb23 commented Dec 3, 2025 •

edited

Loading

joe-watkins commented Dec 5, 2025 •

edited

Loading