From 3d4109ba9d9dcadd47da616e24e2757a1409c39c Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 4 Nov 2025 22:07:20 +0000 Subject: [PATCH 1/4] docs: add accessibility and keyboard shortcuts documentation - Add comprehensive accessibility documentation page under Getting Started - Document all keyboard shortcuts - Document WCAG 2.1 AA color contrast enforcement - Include troubleshooting section for common issues - Add page to Getting Started navigation in docs.yml Co-Authored-By: Chris McDonnell --- fern/products/docs/docs.yml | 2 + .../pages/getting-started/accessibility.mdx | 104 ++++++++++++++++++ 2 files changed, 106 insertions(+) create mode 100644 fern/products/docs/pages/getting-started/accessibility.mdx diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index 49b103847..bab13f5da 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -9,6 +9,8 @@ navigation: path: ./pages/getting-started/quickstart.mdx - page: Project structure path: ./pages/getting-started/project-structure.mdx + - page: Accessibility and keyboard shortcuts + path: ./pages/getting-started/accessibility.mdx - link: Customer showcase href: https://buildwithfern.com/showcase#docs-customers.alldocs-features - changelog: ./pages/changelog diff --git a/fern/products/docs/pages/getting-started/accessibility.mdx b/fern/products/docs/pages/getting-started/accessibility.mdx new file mode 100644 index 000000000..0a47a4dbf --- /dev/null +++ b/fern/products/docs/pages/getting-started/accessibility.mdx @@ -0,0 +1,104 @@ +--- +title: "Accessibility and keyboard shortcuts" +subtitle: "Navigate and use Fern docs with keyboard shortcuts and accessibility features" +description: "Learn about keyboard shortcuts and accessibility features in Fern documentation, including navigation shortcuts, search commands, and WCAG 2.1 AA color contrast enforcement." +--- + +Fern docs are designed to be accessible and keyboard-friendly, supporting navigation and interaction without requiring a mouse. This page outlines the keyboard shortcuts and accessibility features available in Fern documentation. + +## Keyboard shortcuts + +### Page navigation + +Navigate between previous and next pages in your documentation using keyboard shortcuts: + +- **Command + ← / →** (macOS) or **Alt + ← / →** (Windows/Linux): Navigate to the previous or next page + - Note: Some browsers may intercept these shortcuts for back/forward history navigation + +### Search + +Open the search dialog to quickly find content in your documentation: + +- **Command + K** (macOS) or **Ctrl + K** (Windows/Linux): Open search dialog +- **/** (forward slash): Open search dialog when focus is not in a text input field + - Note: The `/` shortcut won't work when typing in an input field, textarea, or contenteditable element + +Once the search dialog is open: +- **Arrow keys**: Navigate between search results +- **Enter**: Select a search result +- **Escape**: Close the search dialog + +### Ask AI panel + +Toggle the Ask AI side panel for AI-powered search assistance: + +- **Command + /** (macOS) or **Ctrl + /** (Windows/Linux): Toggle Ask AI panel + - Note: This is different from the single `/` key which opens the regular search dialog + +### API playground + +Control the API playground/explorer when available: + +- **Ctrl + `** (backtick): Toggle API playground/explorer +- **Escape**: Close the API playground when it's open + +### Browser shortcuts + +Standard browser keyboard shortcuts also work in Fern docs: + +- **Command + ↑ / ↓** (macOS) or **Ctrl + ↑ / ↓** (Windows/Linux): Scroll to top or bottom of page (browser-native behavior) + +## Accessibility features + +### Interactive elements + +All interactive elements in Fern docs are keyboard accessible: + +- **Enter** or **Space**: Activate buttons and expandable sections +- **Tab**: Move focus between interactive elements +- **Shift + Tab**: Move focus backward between interactive elements + +### Dialogs and panels + +Dialogs and panels in Fern docs are designed for keyboard accessibility: + +- **Escape**: Close open dialogs, panels, and the API playground +- Focus is trapped within open dialogs to prevent navigation outside the dialog +- The search dialog supports full keyboard navigation with arrow keys + +### Color contrast + +Fern automatically enforces WCAG 2.1 AA color contrast ratios to ensure text and interactive elements are readable for all users, including those with visual impairments. + +When you configure colors in your `docs.yml` file, Fern validates and adjusts accent colors to meet accessibility standards: + +- **Minimum contrast ratio**: 4.5:1 (WCAG AA standard for normal text) +- **Enhanced contrast ratio**: 7:1 (WCAG AAA standard when feasible) +- **UI elements**: 3:1 minimum contrast ratio for graphics and user interface components + +If your configured accent color doesn't meet the minimum contrast ratio against your background color, Fern will: + +1. Display a warning during `fern check` validation +2. Automatically adjust the accent color at runtime to meet WCAG AA standards +3. Attempt to further adjust toward WCAG AAA (7:1) when possible + +This ensures your documentation remains accessible regardless of your color choices, while still respecting your brand colors as closely as possible. + +## Troubleshooting + +### Keyboard shortcuts not working + +If keyboard shortcuts aren't working as expected: + +- **Browser conflicts**: Some browsers use the same shortcuts for their own features (e.g., Command + ← / → for history navigation). Try using the alternative shortcuts where available. +- **Operating system conflicts**: Your OS may intercept certain keyboard combinations. Check your system keyboard settings if shortcuts aren't responding. +- **Focus in input fields**: The `/` shortcut for search won't work when typing in a text field. Use **Command/Ctrl + K** instead, which works from anywhere. +- **Extension conflicts**: Browser extensions may override keyboard shortcuts. Try disabling extensions if you experience issues. + +### Screen reader support + +Fern docs use semantic HTML and ARIA attributes to support screen readers. If you encounter accessibility issues with screen readers or other assistive technologies, please report them to the Fern team. + +## Feedback + +If you have suggestions for additional accessibility features or encounter any accessibility issues, please reach out to the Fern team through the [Slack community](https://buildwithfern.com/slack) or contact support. From 2c709a46f2de4f97441a0b891871f627b2d03d08 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 4 Nov 2025 22:11:58 +0000 Subject: [PATCH 2/4] docs: address Vale linting feedback - Define WCAG acronym on first use (Web Content Accessibility Guidelines) - Remove adverb "quickly" from search section - Change "is not" to "isn't" for consistency Co-Authored-By: Chris McDonnell --- fern/products/docs/pages/getting-started/accessibility.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/fern/products/docs/pages/getting-started/accessibility.mdx b/fern/products/docs/pages/getting-started/accessibility.mdx index 0a47a4dbf..b944d1998 100644 --- a/fern/products/docs/pages/getting-started/accessibility.mdx +++ b/fern/products/docs/pages/getting-started/accessibility.mdx @@ -1,7 +1,7 @@ --- title: "Accessibility and keyboard shortcuts" subtitle: "Navigate and use Fern docs with keyboard shortcuts and accessibility features" -description: "Learn about keyboard shortcuts and accessibility features in Fern documentation, including navigation shortcuts, search commands, and WCAG 2.1 AA color contrast enforcement." +description: "Learn about keyboard shortcuts and accessibility features in Fern documentation, including navigation shortcuts, search commands, and Web Content Accessibility Guidelines (WCAG) 2.1 AA color contrast enforcement." --- Fern docs are designed to be accessible and keyboard-friendly, supporting navigation and interaction without requiring a mouse. This page outlines the keyboard shortcuts and accessibility features available in Fern documentation. @@ -17,10 +17,10 @@ Navigate between previous and next pages in your documentation using keyboard sh ### Search -Open the search dialog to quickly find content in your documentation: +Open the search dialog to find content in your documentation: - **Command + K** (macOS) or **Ctrl + K** (Windows/Linux): Open search dialog -- **/** (forward slash): Open search dialog when focus is not in a text input field +- **/** (forward slash): Open search dialog when focus isn't in a text input field - Note: The `/` shortcut won't work when typing in an input field, textarea, or contenteditable element Once the search dialog is open: From d32e5e946db14f4e5a5d7c47bacf89e214f5f050 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Tue, 4 Nov 2025 18:15:36 -0500 Subject: [PATCH 3/4] separate into overview and shortcuts page, make more concise --- fern/products/docs/docs.yml | 9 +- .../accessibility/keyboard-shortcuts.mdx | 59 ++++++++++ .../docs/pages/accessibility/overview.mdx | 35 ++++++ .../pages/getting-started/accessibility.mdx | 104 ------------------ 4 files changed, 101 insertions(+), 106 deletions(-) create mode 100644 fern/products/docs/pages/accessibility/keyboard-shortcuts.mdx create mode 100644 fern/products/docs/pages/accessibility/overview.mdx delete mode 100644 fern/products/docs/pages/getting-started/accessibility.mdx diff --git a/fern/products/docs/docs.yml b/fern/products/docs/docs.yml index bab13f5da..4e17e4fc9 100644 --- a/fern/products/docs/docs.yml +++ b/fern/products/docs/docs.yml @@ -9,8 +9,6 @@ navigation: path: ./pages/getting-started/quickstart.mdx - page: Project structure path: ./pages/getting-started/project-structure.mdx - - page: Accessibility and keyboard shortcuts - path: ./pages/getting-started/accessibility.mdx - link: Customer showcase href: https://buildwithfern.com/showcase#docs-customers.alldocs-features - changelog: ./pages/changelog @@ -164,6 +162,13 @@ navigation: path: ./pages/customization/user-feedback.mdx - page: Custom CSS & JS path: ./pages/component-library/custom-components/custom-css-js.mdx + - section: Accessibility + collapsed: true + contents: + - page: Overview + path: ./pages/accessibility/overview.mdx + - page: Keyboard shortcuts + path: ./pages/accessibility/keyboard-shortcuts.mdx - section: API references collapsed: true contents: diff --git a/fern/products/docs/pages/accessibility/keyboard-shortcuts.mdx b/fern/products/docs/pages/accessibility/keyboard-shortcuts.mdx new file mode 100644 index 000000000..94e3ba622 --- /dev/null +++ b/fern/products/docs/pages/accessibility/keyboard-shortcuts.mdx @@ -0,0 +1,59 @@ +--- +title: "Keyboard shortcuts" +description: "Learn about keyboard shortcuts in Fern documentation, including navigation shortcuts, search commands, Ask AI panel controls, and API playground shortcuts." +--- + +Fern docs include built-in keyboard shortcuts for navigation, search, and interactive features. + +## Interactive elements + +| Action | Shortcut | +|--------|----------| +| Move focus between interactive elements | `Tab` | +| Move focus backward between interactive elements | `Shift` + `Tab` | +| Activate [buttons](/learn/docs/writing-content/components/button) and [expandable sections](/learn/docs/writing-content/components/accordions) | `Enter` or `Space` | +| Close open dialogs, panels, and the API playground | `Escape` | +| Toggle Ask AI panel | `Command` + `/` (macOS)
`Ctrl` + `/` (Windows/Linux) | +| Toggle API playground/explorer | `Ctrl` + `` ` `` | + + +The `Command`/`Ctrl` + `/` shortcut is different from the single `/` key which opens the regular [search dialog](#search). + + +## Navigation + +| Action | Shortcut | +|--------|----------| +| Navigate to the previous or next page | `Command` + `← / →` (macOS)
`Alt` + `← / →` (Windows/Linux) | +| Scroll to top or bottom of page | `Command` + `↑ / ↓` (macOS)
`Ctrl` + `↑ / ↓` (Windows/Linux) | + + +Some browsers may intercept these shortcuts for back/forward history navigation. + + +## Search + +| Action | Shortcut | +|--------|----------| +| Open search dialog | `Command` + `K` (macOS)
`Ctrl` + `K` (Windows/Linux) | +| Open search dialog when focus isn't in a text input field | `/` (forward slash) | + + +The `/` shortcut won't work when typing in an input field, `textarea`, or `contenteditable` element. + + +Within the search dialog: + +| Action | Shortcut | +|--------|----------| +| Navigate between search results | `Arrow keys` | +| Select a search result | `Enter` | + +## Troubleshooting + +If keyboard shortcuts aren't working: + +- **Browser conflicts**: Some browsers use the same shortcuts for their own features (e.g., `Command` + `← / →` for history navigation). +- **Operating system conflicts**: Your OS may intercept certain keyboard combinations. Check your system keyboard settings. +- **Focus in input fields**: The `/` shortcut won't work when typing in a text field. Use `Command`/`Ctrl` + `K` instead. +- **Extension conflicts**: Browser extensions may override keyboard shortcuts. Try disabling extensions. \ No newline at end of file diff --git a/fern/products/docs/pages/accessibility/overview.mdx b/fern/products/docs/pages/accessibility/overview.mdx new file mode 100644 index 000000000..556e7535f --- /dev/null +++ b/fern/products/docs/pages/accessibility/overview.mdx @@ -0,0 +1,35 @@ +--- +title: "Overview" +description: "Discover the accessibility features in Fern documentation, including keyboard navigation, Web Content Accessibility Guidelines (WCAG) 2.1 AA color contrast enforcement, and screen reader support." +--- + +Fern docs use semantic HTML and ARIA attributes to support screen readers and keyboard navigation. + + + Reach out to support@buildwithfern.com to report accessibility issues or suggest improvements. + + +## Keyboard navigation + +All interactive elements support keyboard navigation using `Tab`, `Enter`, and `Space` keys. See [keyboard shortcuts](/learn/docs/accessibility/keyboard-shortcuts#interactive-elements) for the complete list. + +## Dialogs and panels + +Dialogs and panels in Fern docs are designed for [keyboard accessibility](/learn/docs/accessibility/keyboard-shortcuts#interactive-elements). Focus is trapped within open dialogs to prevent navigation outside the dialog, and the search dialog supports full keyboard navigation with arrow keys. + +## Color contrast + +Fern automatically enforces [WCAG 2.1 AA](https://www.w3.org/WAI/WCAG21/quickref/#contrast-minimum) color contrast ratios to ensure text and interactive elements are readable for all users: + +- **Normal text**: 4.5:1 minimum ([WCAG AA](https://www.w3.org/WAI/WCAG21/quickref/#contrast-minimum)) +- **UI elements**: 3:1 minimum +- **Enhanced**: 7:1 when feasible ([WCAG AAA](https://www.w3.org/WAI/WCAG21/quickref/#contrast-enhanced)) + +When you [configure colors in your `docs.yml` file](/learn/docs/configuration/what-is-docs-yml#colors-configuration), Fern validates accent colors. If your accent color doesn't meet the minimum contrast ratio against your background color, Fern will: + +1. Display a warning during `fern check` validation +2. Automatically adjust the accent color at runtime to meet WCAG AA standards +3. Attempt to further adjust toward WCAG AAA (7:1) when possible + + + diff --git a/fern/products/docs/pages/getting-started/accessibility.mdx b/fern/products/docs/pages/getting-started/accessibility.mdx deleted file mode 100644 index b944d1998..000000000 --- a/fern/products/docs/pages/getting-started/accessibility.mdx +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: "Accessibility and keyboard shortcuts" -subtitle: "Navigate and use Fern docs with keyboard shortcuts and accessibility features" -description: "Learn about keyboard shortcuts and accessibility features in Fern documentation, including navigation shortcuts, search commands, and Web Content Accessibility Guidelines (WCAG) 2.1 AA color contrast enforcement." ---- - -Fern docs are designed to be accessible and keyboard-friendly, supporting navigation and interaction without requiring a mouse. This page outlines the keyboard shortcuts and accessibility features available in Fern documentation. - -## Keyboard shortcuts - -### Page navigation - -Navigate between previous and next pages in your documentation using keyboard shortcuts: - -- **Command + ← / →** (macOS) or **Alt + ← / →** (Windows/Linux): Navigate to the previous or next page - - Note: Some browsers may intercept these shortcuts for back/forward history navigation - -### Search - -Open the search dialog to find content in your documentation: - -- **Command + K** (macOS) or **Ctrl + K** (Windows/Linux): Open search dialog -- **/** (forward slash): Open search dialog when focus isn't in a text input field - - Note: The `/` shortcut won't work when typing in an input field, textarea, or contenteditable element - -Once the search dialog is open: -- **Arrow keys**: Navigate between search results -- **Enter**: Select a search result -- **Escape**: Close the search dialog - -### Ask AI panel - -Toggle the Ask AI side panel for AI-powered search assistance: - -- **Command + /** (macOS) or **Ctrl + /** (Windows/Linux): Toggle Ask AI panel - - Note: This is different from the single `/` key which opens the regular search dialog - -### API playground - -Control the API playground/explorer when available: - -- **Ctrl + `** (backtick): Toggle API playground/explorer -- **Escape**: Close the API playground when it's open - -### Browser shortcuts - -Standard browser keyboard shortcuts also work in Fern docs: - -- **Command + ↑ / ↓** (macOS) or **Ctrl + ↑ / ↓** (Windows/Linux): Scroll to top or bottom of page (browser-native behavior) - -## Accessibility features - -### Interactive elements - -All interactive elements in Fern docs are keyboard accessible: - -- **Enter** or **Space**: Activate buttons and expandable sections -- **Tab**: Move focus between interactive elements -- **Shift + Tab**: Move focus backward between interactive elements - -### Dialogs and panels - -Dialogs and panels in Fern docs are designed for keyboard accessibility: - -- **Escape**: Close open dialogs, panels, and the API playground -- Focus is trapped within open dialogs to prevent navigation outside the dialog -- The search dialog supports full keyboard navigation with arrow keys - -### Color contrast - -Fern automatically enforces WCAG 2.1 AA color contrast ratios to ensure text and interactive elements are readable for all users, including those with visual impairments. - -When you configure colors in your `docs.yml` file, Fern validates and adjusts accent colors to meet accessibility standards: - -- **Minimum contrast ratio**: 4.5:1 (WCAG AA standard for normal text) -- **Enhanced contrast ratio**: 7:1 (WCAG AAA standard when feasible) -- **UI elements**: 3:1 minimum contrast ratio for graphics and user interface components - -If your configured accent color doesn't meet the minimum contrast ratio against your background color, Fern will: - -1. Display a warning during `fern check` validation -2. Automatically adjust the accent color at runtime to meet WCAG AA standards -3. Attempt to further adjust toward WCAG AAA (7:1) when possible - -This ensures your documentation remains accessible regardless of your color choices, while still respecting your brand colors as closely as possible. - -## Troubleshooting - -### Keyboard shortcuts not working - -If keyboard shortcuts aren't working as expected: - -- **Browser conflicts**: Some browsers use the same shortcuts for their own features (e.g., Command + ← / → for history navigation). Try using the alternative shortcuts where available. -- **Operating system conflicts**: Your OS may intercept certain keyboard combinations. Check your system keyboard settings if shortcuts aren't responding. -- **Focus in input fields**: The `/` shortcut for search won't work when typing in a text field. Use **Command/Ctrl + K** instead, which works from anywhere. -- **Extension conflicts**: Browser extensions may override keyboard shortcuts. Try disabling extensions if you experience issues. - -### Screen reader support - -Fern docs use semantic HTML and ARIA attributes to support screen readers. If you encounter accessibility issues with screen readers or other assistive technologies, please report them to the Fern team. - -## Feedback - -If you have suggestions for additional accessibility features or encounter any accessibility issues, please reach out to the Fern team through the [Slack community](https://buildwithfern.com/slack) or contact support. From 5696bba1289d374ac53f41e9e30e387e19eb2850 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Tue, 4 Nov 2025 18:16:44 -0500 Subject: [PATCH 4/4] add link, fix vale --- .vale/styles/FernStyles/Acronyms.yml | 2 ++ fern/products/docs/pages/accessibility/overview.mdx | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.vale/styles/FernStyles/Acronyms.yml b/.vale/styles/FernStyles/Acronyms.yml index 578f1b6f2..6cca1813e 100644 --- a/.vale/styles/FernStyles/Acronyms.yml +++ b/.vale/styles/FernStyles/Acronyms.yml @@ -89,3 +89,5 @@ exceptions: - RPG - MIME - PNG + - AAA + - ARIA diff --git a/fern/products/docs/pages/accessibility/overview.mdx b/fern/products/docs/pages/accessibility/overview.mdx index 556e7535f..ecd142303 100644 --- a/fern/products/docs/pages/accessibility/overview.mdx +++ b/fern/products/docs/pages/accessibility/overview.mdx @@ -3,7 +3,7 @@ title: "Overview" description: "Discover the accessibility features in Fern documentation, including keyboard navigation, Web Content Accessibility Guidelines (WCAG) 2.1 AA color contrast enforcement, and screen reader support." --- -Fern docs use semantic HTML and ARIA attributes to support screen readers and keyboard navigation. +Fern docs use semantic HTML and [ARIA attributes](https://www.w3.org/WAI/standards-guidelines/aria/) to support screen readers and keyboard navigation. Reach out to support@buildwithfern.com to report accessibility issues or suggest improvements.