Walnut Guide to Accessibility Compliance

Overview

Walnut demos are built from two distinct layers: the Walnut software layer, which adds interactivity, guides, annotations, playlists, and publishing controls, and the input layer, which includes captured assets from your source platform as well as static and media content such as images, MP4s, GIFs, and embedded documents (for example, Google Docs) used within demos and playlists. Because each layer behaves differently, accessibility considerations apply differently across the demo experience.

This guide outlines how accessibility works in Walnut, what is supported today, and which tools and best practices you can use to enhance accessibility across demos, guides, and playlist experiences

In this guide:

• How Walnut Demos Are Structured
• Input Layer & WCAG Compliance
• The Walnut Software Layer & WCAG Considerations
• Accessibility Enhancements Built into Walnut:
• Accessibility Optimization Checklist for Walnut Demos
• Accessibility Scope & Responsibilities

How Walnut Demos Are Structured

Walnut demos are composed of two core layers, each with distinct behavior and accessibility considerations.

The Walnut Software Layer

The software layer consists of all interactive elements added by Walnut, including the Editor, Library, guides and annotations, links, navigation, global styling, and template settings.

Each layer carries its own accessibility characteristics and limitations.

Input Layer (Captured Assets & Media Content)

The input layer includes the content that Walnut displays, which can be either:

• Captured Assets (Source HTML/CSS) — The static HTML and CSS of your product or platform captured using the Walnut Chrome Extension.
• Screens Library Templates (Static Images) — Image-based screens uploaded to the Screens Library and used within demos or guides.
• Uploaded Media & Documents — Static files such as PDFs, MP4 videos, and embedded documents (for example, Google Docs) used as supporting or informational content within demos, guides, or playlists.

Each input type has different accessibility characteristics and limitations, and accessibility considerations should be evaluated based on the format and source of the content.

Input Layer & WCAG Compliance

Captured Assets (Source HTML/CSS)

Accessibility compliance for captured screens (the source HTML/CSS of your product’s UI) reflects the accessibility of the source application as implemented. Walnut displays this content as captured and does not independently assess, modify, or certify its accessibility.

• Walnut does not automatically modify, enhance, or apply accessibility logic to captured HTML or CSS.
• WCAG adherence for captured UI is inherited directly from the system being captured. If the original product’s markup is inaccessible or incomplete, the captured version may also be inaccessible.
• The Walnut Chrome Extension captures the source application’s existing HTML semantics, including structural markup and ARIA attributes, as they exist at the time of capture.

Screens Library Templates & Uploaded Media

Static content uploaded via Screens Library templates or included in demos and playlists as uploaded media (for example, images, MP4 videos, GIFs, PDFs, or embedded documents such as Google Docs) does not contain underlying HTML semantics managed by Walnut.

As a result:

• Text within static images is not readable by screen readers.
• Text, colors, and contrast within images cannot be modified using Walnut styling tools or Global CSS.
• Keyboard navigation and focus behavior do not apply to image- or media-based content in the same way as captured HTML.

Accessibility considerations for static assets and uploaded media must be addressed at creation time, prior to uploading the content to Walnut. Where appropriate, these assets should be supplemented with text-based guides, annotations, captions, transcripts, or audio narration to support accessible demo experiences.

The Walnut Software Layer & WCAG Considerations

Walnut demos are delivered through the Walnut software layer, which introduces interactivity on top of captured or static content. This layer uses a multi-layered architecture based on nested <iframe> elements.

• Each captured screen is rendered inside an <iframe>. 
• Guided demos and multi-screen experiences may include multiple nested <iframe> layers.

Because assistive technologies interpret nested <iframe> elements differently depending on the browser, screen reader, and operating system, accessibility behavior may vary. This can affect areas such as focus management, reading order, and how content within frames is announced.

Walnut also provides features within the software layer that can help improve usability and visual accessibility, including guides, annotations, text styling controls, translations, and global CSS. These tools can support accessibility-minded design but are not explicitly designed to provide full WCAG compliance, and Walnut is not fully WCAG-compliant at this time.

Accessibility enhancements and potential WCAG alignment remain under ongoing evaluation and development.

Accessibility Enhancements Built into Walnut

• Keyboard Navigation for Guided Demos
• Text-to-Speech for Annotation Content
• Guide Translations
• Post-Capture Content Editing & Styling Controls
• Global CSS Styling

Keyboard Navigation for Guided Demos

For linear guided demos with annotations, demo viewers can move forward and backward using keyboard navigation (for example, arrow keys). This can support users who prefer or rely on keyboard-based interaction.

Pro Tip:
Inform viewers that keyboard navigation is available, such as in an introductory guide step or on-screen instruction.

Text-to-Speech for Annotation Content

Use text-to-speech to generate and embed spoken audio for annotation text. This helps make instructional content more accessible for users who benefit from auditory guidance.

Learn more: 

• Adding Text-to-Speech Audio to Guide Steps

Guide Translations

Reach global audiences with ease using Guide Translations. Localize text-based guide and annotation content into multiple languages so viewers can experience your demos in the language that works best for them.

Learn more: 

• Guide Translations

Post-Capture Content Editing & Styling Controls

Walnut provides post-capture editing and styling controls that allow teams to refine captured content and guide annotations after capture. These controls can help improve readability, consistency, and visual accessibility without recapturing screens.

Using Walnut’s built-in HTML and text-style editors, you can make targeted updates to captured assets, including:

• Adjusting headings and text structure
• Improving readability and semantic hierarchy
• Making minor accessibility-oriented refinements where possible

In addition, Walnut provides content controls for text size, text color, and background color across both captured content and guide annotations. Using these styling controls, you can:

• Increase text size for improved readability
• Adjust text color and background color for stronger contrast
• Align text size and color contrast with WCAG AA or AAA readability and contrast guidelines where applicable

Learn more:

• Create Demos – Part 4: Editing Captured Content
• Edit the Background Color of Any Element
• AI Mode is Here: And It’s Changing Everything 🤖

Global CSS Styling

Apply custom global CSS via Template Settings > Custom Code > Global CSS.

Global CSS provides centralized control over the styling and layout of captured HTML content, enabling organizations to apply accessibility-focused enhancements consistently and at scale.

Common enhancements include:

• Increasing base font sizes and line height to improve readability
• Improving color contrast for text and UI elements within captured screens
• Enhancing visible focus states for interactive elements to support keyboard navigation
• Adjusting spacing and layout to support clearer hierarchy and readability

Global CSS is best suited for organizations that require consistent accessibility standards and visual governance across captured demo content. While Global CSS can improve presentation and usability, it does not change the underlying accessibility semantics of the source application.

Optimizing Walnut Demos for Mobile and Smaller Screens

Optimizing Walnut demos for mobile devices and smaller screens is an important part of creating accessible, usable demo experiences. Viewers on mobile or tablet devices may rely on touch interaction, smaller viewports, or system-level accessibility settings such as zoom, text scaling, or screen readers.

Walnut provides several tools and settings that help ensure demos remain readable, navigable, and usable across a wide range of screen sizes.

Key Considerations for Mobile Accessibility

• Content density: Smaller screens benefit from simplified layouts and concise guide steps to reduce cognitive load.
• Readable text: Ensure text remains legible without requiring excessive zooming.
• Tap targets: Interactive elements should be easy to tap without precision gestures.
• Guide placement: Make sure annotations and guides do not obscure critical UI elements on smaller screens.

Walnut Features That Support Mobile Optimization

• View on Mobile: Enables a mobile-optimized split-screen experience when demos are viewed on devices under the mobile breakpoint.
• Screen Display Settings: Use Proportional Fit, Fixed Width, or Fixed Size to control how captured screens scale within smaller containers.
• Preset Screen Sizes: Capture and design demos using common mobile and tablet resolutions to better reflect real-world viewing conditions.
• Responsive embeds: When embedding demos, ensure the parent container resizes appropriately on smaller screens.

Accessibility Best Practices for Mobile Demos

• Test demos on both iOS and Android devices where possible.
• Validate navigation using touch as well as keyboard navigation on tablets with keyboards.
• Ensure key instructions are available through text-based guides or audio narration, especially when UI elements become compressed.
• Combine mobile optimization with Guide Translations and Text-to-Speech to support global and diverse audiences.

Learn More:

For a detailed walkthrough of mobile layouts, screen sizing, and responsive best practices, see:

The Complete Guide to Mobile-Friendly Demos
Build responsive, mobile-ready demos using preset screen sizes, View on Mobile, and layout best practices for clarity, readability, and usability across devices.

Accessibility Optimization Checklist for Walnut Demos

Use this checklist as a quick reference when creating or reviewing Walnut demos for accessibility.

• Verify Source Application Accessibility
  • Confirm your captured product UI follows internal or WCAG-aligned accessibility standards.
  • Review key flows in the original application with screen readers and keyboard-only navigation before capture.
  • Note that the Walnut Chrome Extension captures the source application’s existing semantic structure, including HTML semantics and ARIA attributes. Any accessibility behavior present (or missing) in the source application will be reflected in the captured experience.
• Configure Guided Demos for Keyboard Navigation
  • Use linear guided demos where possible to simplify navigation.
  • Test forward/back keyboard navigation to ensure steps progress as expected.
  • Inform demo viewers that keyboard navigation is available (for example, via an intro guide step or on-screen instruction).
• Optimize Annotation Content
  • Use concise, clear annotation text with simple sentence structure.
  • Increase annotation font size for key instructions or dense text.
  • Ensure annotation text and buttons meet WCAG AA/AAA contrast ratios, including sufficient contrast between text and its background, where possible.
• Add Text-to-Speech Where Helpful
  • Generate audio narration for critical guide steps or complex instructions.
  • Confirm that audio playback controls are easy to locate and use.
• Use Guide Translations
  • Localize guides and annotations into supported languages for your core audiences.
  • Spot-check translations for clarity and terminology consistency.
• Refine Captured HTML (When Needed)
  • Use Walnut’s HTML editor to adjust headings or structure where safe to do so.
  • Avoid large structural HTML rewrites that may break the captured experience.
• Apply Global CSS Enhancements
  • Increase base font sizes for body text and key labels.
  • Improve color contrast across text, buttons, and links.
  • Add or enhance visible focus states for clickable elements.
  • Adjust spacing and layout to improve readability across devices.
• Optimize for Mobile and Smaller Screens
  • Enable the mobile optimization setting for guided or hybrid demos.
  • Ensure demos remain usable and readable on mobile devices and smaller viewports.
  • Test demos on mobile and tablet screen sizes, including both portrait and landscape orientations.
  • Ensure text remains legible without excessive zooming and that interactive elements are easy to tap. Validate mobile behavior with View on Mobile and appropriate screen display settings (Proportional Fit, Fixed Width, or Fixed Size).
• Test Across Browsers and Assistive Tools
  • Preview demos in at least two major browsers (for example, Chrome and Edge).
  • Test keyboard navigation from start to finish.
  • Spot-check behavior with a screen reader, paying attention to iframe transitions and focus.
• Document Known Limitations
  • Capture any constraints (for example, nested iframes and screen reader variability) in internal documentation.
  • Share these notes with stakeholders to align expectations.

Accessibility Scope & Responsibilities

Walnut does not currently provide fully WCAG-compliant demos end to end. Core accessibility of captured screens follows the accessibility of the original source application, while Walnut provides tools that can help improve readability, multilingual support, and usability through guides, styling controls, and global CSS applied to captured HTML.

Because Walnut demos rely on nested <iframe> architecture and a combination of captured content, static assets, and guided overlays, accessibility behavior may vary depending on the viewer’s browser, operating system, and assistive technology. Accessibility outcomes are influenced both by the accessibility of the source application and how content is structured and presented within the demo.

Teams should evaluate Walnut demos end to end, including captured screens, static assets, and guide experiences, as part of their overall accessibility review.