DEV Community

Cover image for The VS Code Terminal Can't Do Accessibility, So I Built a Reading Mode Around It
Ali Alp
Ali Alp

Posted on

The VS Code Terminal Can't Do Accessibility, So I Built a Reading Mode Around It

Most of what I read in a workday is not code anymore. It is prose: agent replies scrolling past in a terminal, Markdown docs, review notes. The terminal is the worst place in VS Code to read prose. One monospace font, one line height, no paragraphs, every line the same weight.

I started with three reading modes for web pages. Each one is a CSS class on <html>:

  • Dyslexia: Atkinson Hyperlegible, wider letter, word and line spacing, lines of about 68 characters, a cream background, italics shown as bold.
  • Autism: no motion, muted colours, links always underlined.
  • ADHD: the block under the pointer stays sharp and everything else dims to 70%, bold terms get a highlighter, and a thin bar shows reading progress.

I wanted the same thing in VS Code. The result is Reading Modes. This post covers why the terminal needed a workaround, two ways I almost broke people's settings, and what changed when I took the modes to the browser.

Three surfaces, three styling systems

In a web page the modes stack for free, because they are just classes. VS Code has no single equivalent. Each surface is styled by something different:

Surface What styles it What the extension does
Editor settings and decorations per-language settings for Markdown and plain text, ADHD dimming via decorations
Markdown preview a webview fed by markdown-it a markdown-it plugin plus a contributed stylesheet
Terminal the xterm.js cell grid spacing and cursor settings only, full styles in a reader panel

The terminal is a grid

The integrated terminal renders a grid of cells. Every cell has the same width, and one font and one line height apply to the whole terminal. A proportional font like Atkinson Hyperlegible breaks that grid, and with it every table and TUI. There is also no way to dim a paragraph, because the terminal has no idea what a paragraph is.

So the terminal only gets what it can take. Dyslexia mode widens terminal.integrated.letterSpacing and lineHeight. Autism mode turns off cursor blinking and smooth scrolling. The real styling happens somewhere else: press Ctrl+Alt+R in the terminal and its text opens in a webview panel, rendered as Markdown with the same CSS as the web version.

Reading a terminal without an API

The stable extension API cannot read a terminal's buffer. There are proposed APIs for it, but an extension that uses proposed APIs cannot be published to the Marketplace. What does exist are three built-in commands: select all, copy selection, clear selection. So the capture goes through the clipboard:

const before = await vscode.env.clipboard.readText();
const sentinel = `reading-modes-capture-${Math.random().toString(36).slice(2)}`;
terminal.show(true); // make it the active terminal without stealing focus
await vscode.env.clipboard.writeText(sentinel);
try {
  await vscode.commands.executeCommand("workbench.action.terminal.selectAll");
  for (let i = 0; i < 10; i++) {
    await vscode.commands.executeCommand("workbench.action.terminal.copySelection");
    const text = await vscode.env.clipboard.readText();
    if (text !== sentinel) return text;
    await wait(50);
  }
  throw new Error("Could not copy the terminal text (the terminal may be empty).");
} finally {
  await vscode.commands.executeCommand("workbench.action.terminal.clearSelection");
  await vscode.env.clipboard.writeText(before);
}
Enter fullscreen mode Exit fullscreen mode

Each line is there for a reason:

  • copySelection only runs when the "text selected" context key is set, and that key flips a moment after selectAll returns. Hence the retry loop.
  • The sentinel tells "the copy has not happened yet" apart from "the terminal holds the same text as the clipboard". Without it a failed copy would quietly show you your old clipboard as if it were the terminal.
  • The user's clipboard goes back afterwards. Only text can be restored, so an image on the clipboard is lost. The README says so.
  • Captures run one at a time. Press refresh twice quickly and two overlapping captures would each save the other's sentinel as "your clipboard", then restore that.

The panel renders the text with markdown-it and html: false, so terminal output cannot inject markup. A nice side effect: hard-wrapped terminal lines join back into paragraphs, which is exactly what the ADHD focus effect needs.

Changing someone's settings is a promise

The editor and terminal parts work by writing to the user's settings. That means the extension has to give back exactly what was there when a mode turns off. My first version kept one record of the original values in globalState. A review of that code found two ways it breaks for good.

Two windows. Every open window reacts to the same mode change. Window A saves your font and sets the mode's font. Window B has not seen A's record yet, finds the mode's font in your settings, and saves it as your original. Turn the mode off and the "original" that comes back is the mode's font.

A failed write. If any write fails halfway, say because settings.json has a syntax error, the earlier writes have happened but the record was never stored. On the next run the settings already hold the mode values, so those get saved as originals. Same stuck state.

The fix is a few rules, each one small:

for (const [id, o] of wanted) {
  if (saved.get(id)) continue;              // already ours: leave it, the user may have edited it
  const current = store.get(o.key, o.lang);
  if (same(current, o.value)) continue;     // another window did it, or it was already that
  await saved.set(id, { had: current !== undefined, original: current, applied: o.value });
  await store.set(o.key, o.lang, o.value);  // saved first, then written
}
Enter fullscreen mode Exit fullscreen mode
  • One storage key per setting, written before that setting is touched.
  • A setting that already holds the mode's value, with no saved original, is never recorded.
  • On the way back, the original is restored only if the setting still holds what the mode applied. If you changed it by hand while the mode was on, your change wins.
  • The keys are registered with setKeysForSync, so Settings Sync carries them next to the settings they belong to.

The sync logic lives in a file with no vscode import, so it runs under node --test against a fake settings store. The tests are named after the bugs: "a second window never records the mode's value as the original", "a failed write keeps the originals of settings already changed".

The Markdown preview needs a nudge

The built-in preview accepts markdown-it plugins through "markdown.markdownItPlugins": true. The plugin pushes a core rule that wraps the document in <div class="rm m-dyslexia m-adhd">, and a contributed stylesheet does the rest.

One trap: the preview caches rendered output and only re-renders on its own when markdown.* or editor.* settings change. An extension's own setting does not count, so toggling a mode looked broken until the extension called markdown.preview.refresh itself.

ADHD mode in the editor

In Markdown and plain-text files, a text decoration with opacity: 0.7 covers everything except the blank-line-separated block around the cursor. Move the cursor and the focus moves with it. Code files are left alone.

What it cannot do

  • The editor uses Atkinson Hyperlegible only if it is installed on your system. An extension can ship a font for a webview, not for the editor. Otherwise it falls back to Verdana.
  • Turn the modes off before uninstalling. The uninstall hook runs without the settings API, so it cannot restore anything.
  • High-contrast themes keep their own colours. Only spacing, font and motion change.

The same modes in the browser

Most of the prose I read outside the editor is on web pages, so the repository now also holds a browser extension for Chrome, Firefox and Safari. It is plain JavaScript. The only build step copies three files into place: the font, Mozilla Readability, and the same modes.css the VS Code reader panel uses.

One manifest, three browsers

Manifest V3 is nearly the same everywhere, except for the background script. Chrome wants a service worker, Firefox and Safari want background scripts. Listing both works, because each browser ignores the key it does not use:

"background": {
  "service_worker": "background.js",
  "scripts": ["background.js"],
  "type": "module"
}
Enter fullscreen mode Exit fullscreen mode

That needs Chrome 121 or Firefox 121 and later. The rest is const ext = globalThis.browser ?? globalThis.chrome, plus optional chaining for the context menus and keyboard shortcuts that Firefox for Android does not have.

A web page is not a reader panel

In the reader panel I own the markup. On a web page I do not, so the modes are lighter there, and several rules needed a second version:

  • Dyslexia mode uses the WCAG 1.4.12 text spacing values: line height 1.5, letter spacing 0.12em, word spacing 0.16em. Pages are supposed to survive those without breaking. There is no cream background and no 68-character line, because those would fight the site's layout. Code blocks keep their spacing.
  • The font goes on text elements, not on *. Setting it on everything also replaced icon fonts, and every icon turned into a letter.
  • The first version stopped motion with animation: none. Content that fades in from opacity: 0 then stayed invisible, because the animation that would have shown it never ran. Now animations get a duration of .001ms: they finish at once, and the events at their end still fire.
  • Autism mode is one filter: saturate(.7) on the root element. A filter on any other element breaks position: fixed for everything inside it. It also runs in the top frame only, or a page inside a frame would be desaturated twice.
  • Plenty of sites set <html>'s className from their own scripts, which wipes the mode classes. A MutationObserver puts them back.

The reader view

Alt+Shift+R opens the selection, or the page's main article as found by Mozilla Readability, in a tab styled by modes.css. The page's HTML is untrusted and the reader is a privileged extension page, so the HTML goes through DOMParser first: scripts, frames, forms and SVG are dropped, a short list of attributes is kept, and links and images must be http or https.

Two bugs came from the reader itself. Readability wraps the article in nested divs, and the ADHD focus rule (.rm.m-adhd:hover > *) only dims direct children, so nothing dimmed until the reader unwrapped them. And pressing "Read this page" on the reader tab itself failed, because an extension cannot inject scripts into its own pages. It can see its own tabs' URLs without the tabs permission, though, so the extension now checks the URL first.

The documents live in the browser's session storage and are gone when it closes. Nothing leaves the browser.

Store review

Chrome flags an extension whose content script matches <all_urls> for an in-depth review, and suggests activeTab instead. But activeTab only grants access to the current tab after a click, so the modes would reset on every page load. For an extension whose job is to restyle every page you read, the broad match is the point. The cost is a slower review.

Try it

code --install-extension alialp.reading-modes
Enter fullscreen mode Exit fullscreen mode

Click the eye in the status bar to pick modes, then press Ctrl+Alt+R in a terminal.

For the browser, build the extension and load the browser/ folder as an unpacked extension in Chrome (chrome://extensions, Developer mode) or as a temporary add-on in Firefox (about:debugging):

git clone https://github.com/alicommit-malp/reading-modes
cd reading-modes && npm install && npm run build:browser
Enter fullscreen mode Exit fullscreen mode

The source is on GitHub, MIT licensed.

If you use one of these modes, I would like to know what is missing. The defaults are a starting point, and I am sure they are not right for everyone.

Top comments (0)