Guidelines for your ai tool

Accessibility

Ai tools reach for some design choices by default that make a site harder, or impossible, for some people to use. Each guideline below asks for the accessible version.

The Web Content Accessibility Guidelines (WCAG) can sound like a pass-or-fail checklist. Each requirement is testable, but how you meet it is still a design decision. WCAG sets the minimum contrast, not your colors. It requires a focus outline you can see, not what the outline looks like. My studio's copper measures 3.6 to 1 on our cream background, under the minimum for body text, so the brand has a deeper copper, at 5.1 to 1, for text. Same brand, a choice made inside the guidelines.

Some of the guidelines below go past the minimum on purpose, and each one says where and why. The reason is the same every time: your ai tool has to get it right without you watching, so these pick the version that's easiest to get right and easiest to check.

1. Gradient text, and text on gradients or frosted glass

   When the background changes under the letters, part of the text can be readable while another part isn't. Text needs a contrast ratio of at least 4.5 to 1 against what's behind it (WCAG 1.4.3).

   Ask forPut text on a solid color. No gradient text. If text has to sit on a gradient, photo, or frosted glass, every letter needs at least 4.5 to 1 contrast against the lightest part behind it.

   Where this goes past WCAG: WCAG doesn't ban gradient text. It asks for enough contrast everywhere the text sits. But a contrast checker can't measure a color that keeps changing, so you can't easily prove gradient text passes. A solid color you can check in seconds.

2. Pale text

   Small badges, light gray subtitles, and placeholder text are often too faint to read for people with low vision, or for anyone on a phone in the sun (WCAG 1.4.3).

   Ask forEvery piece of text, including badges, gray secondary text, and placeholders, is at least 4.5 to 1 against its background, or 3 to 1 for large text. No thin or light font weights for body text.

   Where this goes past WCAG: WCAG doesn't set a font weight. It notes that thin letters are harder to read at lower contrast, and a light weight can pass the number and still be hard to read, so this asks for regular weight or heavier.

3. Animations that never stop

   A logo strip that scrolls forever makes the rest of the page hard to read for some people. Anything that moves on its own for more than five seconds needs a way to pause it (WCAG 2.2.2).

   Ask forNothing loops forever. Anything that moves on its own stops within five seconds or has a visible pause button.

   Where this goes past WCAG: WCAG accepts endless motion if there's a way to pause it. A pause button is one more control the tool has to build, label, and make work with a keyboard. Motion that stops on its own needs no control at all, so it's the version the guideline leads with.

4. A missing focus outline

   People who use a keyboard press Tab to move through a page. When the outline is removed and nothing replaces it, they can't tell where they are (WCAG 2.4.7).

   Ask forNever remove the focus outline without a replacement. Every link, button, and form field shows a clearly visible outline when someone reaches it with the Tab key.

   Where this goes past WCAG: At Level AA, WCAG asks only that focus be visible; a faint outline can technically pass. "Clearly visible" leans toward WCAG's stricter Focus Appearance criterion (AAA), which sets a size and contrast for the outline. How it looks is yours: thickness, color, and offset can all match your brand.

5. Buttons that are only an icon

   A screen reader can't describe a picture of three lines, so it says "button" and nothing else (WCAG 1.1.1).

   Ask forEvery button or link that shows only an icon gets a text name that says what it does, like "Open menu." Icons that are only decoration get hidden from screen readers.

## Accessibility

Everything you build meets WCAG 2.2 Level AA. In particular:

1. Put text on a solid color. No gradient text. If text has to sit on a gradient, photo, or frosted glass, every letter needs at least 4.5 to 1 contrast against the lightest part behind it.
2. Every piece of text, including badges, gray secondary text, and placeholders, is at least 4.5 to 1 against its background, or 3 to 1 for large text (24 px, or about 19 px bold). No thin or light font weights for body text.
3. Nothing loops forever. Anything that moves on its own stops within five seconds or has a visible pause button.
4. Never remove the focus outline without a replacement. Every link, button, and form field shows a clearly visible outline when someone reaches it with the Tab key.
5. Every button or link that shows only an icon gets a text name that says what it does, like "Open menu." Icons that are only decoration get hidden from screen readers.

Whenever you add or change colors, list any text and background pair under these minimums and fix it.

The copied block also ends with one line WCAG doesn't have: it asks your tool to list any text and background pair that falls short whenever it changes colors, so the tool checks its own work before you do.

Guidelines make these problems less likely; they don't guarantee them gone. Check the result with a free tool like WAVE or WebAIM's Contrast Checker, and press Tab through the page yourself.

Brand

If you don't give your ai tool a brand, it picks one for you. When I asked Gemini for a landing page for a booking app, it chose dark slate, a bright green, and a gradient headline. Nobody asked for those. They were its defaults.

A brand guide is one page that says your colors, your fonts, and how you sound. Your tool reads it every time, next to the accessibility guidelines above. Decide brand and accessibility together: every text color in the guide sits beside the background it goes on and the contrast ratio you measured. My studio's copper measures 3.6 to 1 on our cream background, too low for body text, so the guide keeps a deeper copper, at 5.1 to 1, for text. The brand stayed the same. The text color changed.

# Brand guide: [your product]

## Rules for your ai tool
- Use only the colors in this guide. Don't add new ones.
- Put text only on the pairs listed under "Text on background."
- Headings use [heading font]. Body text uses [body font] at 16 px or larger.
- Write in the voice described under "Voice."
- If you need a color, font, or pairing that isn't here, ask me instead of inventing one.

## What it is
- What it does, in one sentence: [ ]
- Who it's for: [ ]
- Three words for how it should feel: [ ], [ ], [ ]

## Colors
| Name | Hex | Used for |
|---|---|---|
| Primary | #______ | buttons and links |
| Background | #______ | the page |
| Surface | #______ | cards and panels |
| Text | #______ | body text |
| Muted text | #______ | captions and secondary text |

## Text on background
Measure each pair with a contrast checker. Body text needs at least 4.5 to 1. Large text (24 px, or about 19 px bold) and the edges of buttons and form fields need at least 3 to 1.
| Text color | Background | Ratio | OK for |
|---|---|---|---|
| Text | Background | __ to 1 | |
| Muted text | Background | __ to 1 | |
| Text on buttons | Primary | __ to 1 | |
| Primary | Background | __ to 1 | |
Never pair: [any pair under 3 to 1]

## Type
- Headings: [font]
- Body: [font], 16 px or larger, regular weight or heavier

## Voice
- Sounds like: [ ], [ ], [ ]
- Phrases we use: [ ]
- Phrases we never use: [ ]
- One sentence in our voice: [ ]

## Optional
- Logo: [where the files live, and the space to keep around it]
- Images and icons: [style]
- Motion: [none, or what moves and for how long]

Interview me to fill in the brand guide below. Ask one question at a time, and wait for my answer before the next.

- Start with what the product does, who it's for, and how it should feel. Ask what I already have, like a logo, colors, or a site, before suggesting anything.
- Only suggest colors after that, and explain why each one fits what I told you.
- For every pair in "Text on background," give the contrast ratio and say what it's OK for. Flag any pair under 4.5 to 1 for body text, and offer a darker or lighter version of the same color that passes.
- For the voice, ask me for two or three things I've written myself, and describe the voice from those. Don't invent one.
- Don't make up facts about my business.

When we're done, give me the finished guide as markdown.

[paste the brand guide here]

Save the finished guide where your tool reads standing context, next to the accessibility guidelines. If you use Claude Code, my free designer plugin has a brand-kit skill that does the same interview inside your project.

Tools to check your site

Guidelines make problems less likely. Checking is how you find the ones that got through. These are free, and you don't need to be a developer to run them.

Automated checkers

Each one scans a page and lists what it can measure. Run more than one; they don't all use the same rules.

• axe DevTools, from DequeA browser extension. Its rules, called axe-core, also run inside other tools, including Lighthouse.
• Lighthouse, built into ChromeOpen Chrome's developer tools and run a Lighthouse report. Its accessibility audits run axe-core rules (Lighthouse source), and the score only counts what it tested (how it scores). When it agrees with axe, that's one opinion, not two.
• ARC Toolkit, from TPGiA panel in Chrome's developer tools with its own rule set, so it can catch things axe doesn't.
• WAVE, from WebAIMDraws icons right on the page, so you can see where each problem is without reading code. The easiest place to start.
• WebAIM's Contrast CheckerPaste two colors and get the ratio. Use it for anything the scanners skip, like text on a gradient.

Screen readers

• VoiceOver, built into every MacPress Command-F5 to turn it on and off (Apple's guide). Listen to your page from the top: does it say what someone needs to hear, in an order that makes sense?
• NVDA, free for WindowsA free screen reader for Windows.

What no checker can tell you

Automated tools only catch part of the problem. When the UK Government Digital Service planted 142 barriers on a test page and ran 13 tools, the best found 40% of them and the worst 13% (GDS, last updated 2018). Deque, which makes axe, reports its automated tests find 57% of issues by volume (Deque, 2021). The two measure different things, and either way a person has to check the rest. Do these by hand:

• Press Tab through the whole page. Can you always see where you are, and reach everything?
• Watch for anything that moves on its own for more than five seconds, and look for a way to pause it.
• Open the page on a phone. Is anything missing, like a menu or a login link?
• Turn on a screen reader and listen. Icons, emoji, and images can come out as noise or as nothing.
• Measure any text on a gradient or a photo by hand; scanners usually skip it.