Improve table and videos accessibility in BlockNote

[Ovgodd]

Improve table accessibility in BlockNote and table-related videos

Feature Request

Hello, I am opening a discussion regarding the accessibility of tables in BlockNote and the table-related videos audited in Docs.

Audited document:
https://docs.numerique.gouv.fr/docs/0d998bef-1b69-47ce-bd18-83d4d849c734/

Is your feature request related to a problem or unsupported use case? Please describe.

Several accessibility issues were identified around tables.

BlockNote tables

On the BlockNote side, the generated tables are not fully accessible for screen reader users.

The interface allows users to define row and column headers, and the generated markup uses <th> elements. However, these headers are not explicitly associated with the related cells.

There is currently no scope attribute, no unique id / headers relationship, and no clear rowheader or columnheader semantics.

Because of this, screen readers may not be able to reliably announce whether a header is related to a row or a column.

The same issue also applies to merged cells, where the relationship with the related headers is not clearly exposed.

Another issue is that the interface does not currently allow users to add an accessible title to a table.

A table title should be exposed through one of these techniques:

<caption>Table title</caption>

or through title, aria-label, or aria-labelledby.

Table-related videos

In the audit, some videos explaining table features were also reviewed.

For example, the video “Ajouter des colonnes et des lignes” shows how to add rows and columns using the mouse, but there is no text transcript explaining the same action for blind or visually impaired users.

The videos are also preceded by a title, but there is no additional context explaining the goal of the video before the user watches it.

Delete a table block

In the “Delete a table” block, the visual context explains how to delete a table with the mouse.

However, the keyboard workflow is different and is not clearly explained.

Table colors

Some colors used inside tables do not provide enough contrast.

Ratio 3.53 — #E03E3E on #DDEDEA
Ratio 4.26 — #E03E3E on #FFFFFF

Describe the solution you'd like

Improve the accessibility of table-related content and table editing features.

Expected improvements for BlockNote tables:

• allow users to define an accessible table title;
• expose the table title correctly in the generated markup;
• correctly associate table cells with their row and column headers;
• use scope="col" and scope="row" for simple tables when possible;
• use id and headers for more complex tables when needed;
• ensure merged cells keep a clear relationship with their related headers.

For simple tables, header relationships can usually be exposed with scope.

<table>
  <caption>Project members</caption>
  <thead>
    <tr>
      <th scope="col">Name</th>
      <th scope="col">Role</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row">Alice</th>
      <td>Designer</td>
    </tr>
  </tbody>
</table>

For more complex tables, especially with merged cells, id and headers may be needed.

<th id="q1">Q1</th>
<th id="north">North</th>
<td headers="north q1">120</td>

Expected improvements for table-related guidance and videos:

• explain keyboard workflows when an action is demonstrated with the mouse;
• add a short introduction before each video explaining its purpose;
• provide a text transcript for videos that demonstrate table interactions;
• ensure transcripts explain both mouse and keyboard workflows when they are different;
• improve color contrast inside tables.

Discovery, Documentation, Adoption, Migration Strategy

This should be reviewed in two parts:

1. BlockNote table output and table editing features.
2. Table-related videos and guidance in the audited Docs document.

The goal is to make table creation, editing, and reading usable for keyboard and screen reader users.

This discussion can be split into smaller implementation tasks if needed:

• accessible table title support;
• row and column header associations;
• merged cells accessibility;
• delete table keyboard instructions;
• table color contrast;
• video context before playback;
• video transcript for table interactions.