Accessibility

This page is for anyone who uses instruction.md with a keyboard, a screen reader, a right-to-left language, or settings that make the screen easier to read. It says what works today, what doesn't yet, and how to write instructions that everyone on your team can use.

Use the editor with a keyboard

You can write, find your way and publish in the editor without a mouse.

  • Tab moves through the account menu, the side bar, the text and the panels. The place that has the focus is always outlined.
  • The command palette finds any command by name. Press Ctrl+K (on a Mac, ⌘K), type a few letters, such as "publish", and press Enter.
  • Go to an instruction by name opens another instruction. Press Ctrl+P (on a Mac, ⌘P).
  • Dialogs keep the focus inside them while they are open. Esc closes a dialog and puts the focus back where it was.
  • Lists, such as History, move with the arrow keys.
  • A row's menu in the side bar opens with Shift+F10 or the menu key, as a right-click would. In the text, Shift+F10 opens the menu for the words you selected.
  • Buttons say their keys. A button with a shortcut gives its key in its name, so you learn the keys as you go.

The editor's own list of every key opens with Ctrl+/ or ? (on a Mac, ⌘/ or ?), or ? when you aren't typing in the text. Keyboard shortcuts and the command palette has the whole list, and what to do when a key does nothing.

Use a screen reader

The editor's buttons, menus, dialogs, tabs and switches are built from parts that tell a screen reader what each one is, what it is called and whether it is on.

Messages that appear on their own are read out too. These include a short note after an action, such as a saved checkpoint, and new lines in the assistant's panel and in an agent's conversation.

Two ways of working help with a screen reader:

  • The Markdown shows the instruction as plain text, line by line. Use it when Preview, which draws the instruction like a page, is harder to follow. Open it with Show Markdown, or with Content when Developer mode is on. Find your way around the editor says how to switch.
  • The assistant can be asked in your own words, typed or spoken, to find, explain or change part of an instruction. See The assistant.

The sign-in pages, the docs and these Learn pages have a Skip to content link as the first stop of the keyboard.

Use a right-to-left language

The editor and the sign-in pages are in English, Ukrainian, French, Spanish and Arabic. The docs and Learn have their menus in the same five languages, but most of their pages are in English for now. In Arabic, the whole page reads from right to left: the side bar, the menus and the panels change sides.

To choose the editor's language, open Your account ▸ Appearance and pick a Language, or Same as my browser. The language of the editor never changes the words of your instructions. In Preview, each paragraph of an instruction runs the way its own words run: a paragraph in Arabic or Hebrew reads from right to left, whatever language the editor is in.

Themes, contrast and motion

  • Dark or light. Open Your account ▸ Appearance and choose a Theme: System, Light or Dark. The docs and Learn pages have their own theme buttons at the foot of each page.
  • Readable brand colours. In Your account ▸ Appearance, a Colour is refused when the words on its buttons would be hard to read. The editor then says how far it falls short: button words need a contrast of at least 4.5 to 1 with their background, on hover and when pressed too.
  • Contrast settings. When your computer uses a high-contrast or forced-colours theme, as Windows can, the editor's parts keep their outlines and stay visible.
  • Less motion. When your computer is set to reduce motion, the editor's menus, panels and lists stop sliding and fading.
  • Bigger text. Your browser's zoom makes the editor and these pages larger.
  • A quieter screen. Type in Your account ▸ Appearance switches the editor's typeface. In the status bar, View turns on Monospace text and Line numbers, or hides the side bar.

Captions and transcripts

These pages have no videos yet. When a guide gets one, the video won't replace the words: the page writes out the same steps, so you can follow it without watching. We add captions to each video we make, and the player shows them when they are there.

Write instructions everyone can use

An instruction is read by people as well as by agents. The same habits help both.

  • Give every picture words. A picture, a video or a sound file in an instruction has an alt line that says what it shows. People who can't see it hear those words, and the agent reads them too. A drawing has a Title (what the drawing shows) for the same reason. See Add diagrams, drawings and media.
  • Give a video or a sound file a transcript. Its transcript line is the address of the words spoken in it.
  • Name each figure. A flowchart's first line is its name, and Preview uses it as the figure's label. Say what the figure shows.
  • Use headings in order. Start sections with headings, and don't skip a level. A screen reader lists the headings, and Contents shows them, so people can jump to the part they need.
  • Don't rely on colour alone. Say "the red button" and also "Delete".
  • Keep rules short. One rule per line, in plain words, is easier to hear, to translate and to follow.

The editor doesn't ask for alt text, so check it yourself before you publish: in Preview, each picture, video and sound card shows its alt text, or "Image not loaded here" when it has none.

Known gaps

We check the site and the editor with an automated test against the web's accessibility guidelines (WCAG 2.1, level AA), in the light and the dark theme, and we test the editor with the keyboard alone. An automated test doesn't find every problem. These are the gaps we know about:

  • Drawing needs a pointer. The drawing pad's tools have letter keys, but drawing itself needs a mouse, a pen or a finger. Write a flowchart in text instead: a screen reader reads it, and it can be made with the keyboard alone.
  • Other websites' sign-in pages. When your organization signs you in with its own provider, that provider's pages are its own, not ours.
  • Translations. Some pages are in English in every language until they are translated. They say so at the top.

Report a problem

If something in instruction.md is hard or impossible for you to use, tell us. Send us a request and choose Something else. Say which page, what you were trying to do, and what you use, such as a screen reader, a voice control program or a magnifier. We answer accessibility requests like any other support request, and we fix what we can.

Questions

Can I use the editor with a keyboard only or a screen reader?

Yes, apart from drawing, which needs a mouse, a pen or a finger. The rest of the editor can be reached with the keyboard, and the command palette finds any command by name. Its buttons, menus and dialogs tell a screen reader what they are. See Use the editor with a keyboard and Use a screen reader.

Does the editor work in Arabic?

Yes. The editor and the sign-in pages are in Arabic, and the whole page reads from right to left. Choose it in Your account ▸ Appearance. See Use a right-to-left language.

Can I make the editor dark, or easier to read?

Yes. Choose a Theme in Your account ▸ Appearance, and use your browser's zoom for bigger text. The editor follows your computer's settings for high contrast and reduced motion. See Themes, contrast and motion.

Does the agent see my pictures?

No. It receives the picture's address and your alt text. Put what the agent must know in the alt text or in the rule itself. See Add diagrams, drawings and media.

Last checked against the product:

Was this page helpful? Report a problem