feat: add accessibility docs

src/content/guides/accessibility.mdx

@@ -8,17 +8,88 @@ meta:
   category: Editor
 ---
 
-We strive to make Tiptap accessible to everyone. From our current understanding, that’s what needs to be done:
+import { CodeDemo } from '@/components/CodeDemo'
+
+We strive to make Tiptap accessible to everyone. But this is at odds with the fact that we are a headless editor. We don’t provide an interface, so it’s up to you to make sure that the editor is accessible. Here are some guidelines to help you with that.
+
+## Demo of an accessible editor
+
+<CodeDemo src="https://deploy-preview-5809--tiptap-embed.netlify.app/preview/Examples/Accessibility" />
+
+## Guidelines
+
+Here are a non-exhaustive list of guidelines to make your editor accessible:
+
+### Keyboard accessibility
+
+Make sure that all editor features are accessible via the keyboard. This includes navigating the editor, selecting text, menus, and using all editor features.
+If you look at the demo above, you can see that you can navigate the editor with the keyboard by:
+
+- `Tab` to focus within the editor
+- `Alt + F10` to focus the editor's toolbar
+  - Arrow keys to navigate the toolbar
+  - `Enter` to select a menu item
+  - `Tab` or `Esc` to navigate back the editor content
+- `Shift + Arrow keys` to select text
+  - `Tab` to navigate to the text selection menu
+  - `Enter` to select a menu item
+  - `Tab` or `Esc` to navigate back to the editor content
+- `Enter` to create a new paragraph
+  - `Tab` to navigate to the insert content menu
+    - Arrow keys to navigate the toolbar
+    - `Enter` to select a menu item, inserting the content
+    - `Tab` or `Esc` to navigate back to the editor content
+- All other editor keyboard shortcuts as described in the [keyboard shortcuts](/editor/core-concepts/keyboard-shortcuts)
+
+### Semantic markup & Aria Roles
+
+All of the default Tiptap extensions produce semantic markup. This means that the editor produces HTML that is easy to understand for screen readers.
+
+To help screen readers even more, your editor & menus should provide appropriate Aria roles. Some examples are:
+
+- The editor should have the `role="textbox"`
+- The toolbar should have the `role="toolbar"`
+- The menu should have the `role="menu"`
+- The menu items should have the `role="menuitem"`
 
 ### Interface
 
-An interface needs to have well-defined contrasts, big enough click areas, semantic markup, must be keyboard accessible and well documented. Currently, we don’t provide an interface, so for now that’s totally up to you.
+An interface needs to have well-defined contrasts, big enough click areas. Currently, we don’t provide an interface, so for now that’s totally up to you.
+
+### Gotchas
+
+We've found a few gotchas, when implementing accessibility, that you should be aware of:
+
+#### VoiceOver concatenates words across block elements
+
+When using VoiceOver on macOS, it is important to be aware that it may concatenate words across block elements. This can lead to unexpected reading experiences for users relying on screen readers.
+
+For example, consider the following HTML structure:
+
+```html
+<h1>Heading</h1>
+<p>Paragraph</p>
+```
+
+VoiceOver would read this as "HeadingParagraph" instead of "Heading Paragraph" (notice the space). To fix this, you can add a zero-width space after each block element:
 
-But no worries, we’ll provide an interface soon and take accessibility into account early on.
+```css
+.tiptap {
+  h1::after,
+  h2::after,
+  h3::after,
+  h4::after,
+  h5::after,
+  h6::after,
+  p::after {
+    content: '\200B';
+  }
+}
+```
 
-### Output
+#### Keyboard traps
 
-The editor needs to produce semantic markup, must be keyboard accessible and well documented. The Tiptap content is well structured so that’s a good foundation already. That said, we can add support and encourage the usage of additional attributes, for example the Alt-attribute for images.
+A keyboard trap is a situation where a user can’t navigate away from a certain element using the keyboard. This can be a problem if you have a modal or a menu that can be opened with the keyboard. Make sure that the user can always navigate away from these elements.
 
 ### Writing assistance (optional)