dotCMS / dotCMS/core

Block Editor: no visual indicator that a block carries (or is missing) accessibility metadata

Open
#36,050 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

dotCMS: Block Editor Team : Scout Type : Task
Dominant language
Java
Stars
970
Forks
486
Avg merge
3d 33m
Merged PRs (30d)
170

Description

Description

Several Block Editor blocks let authors set accessibility metadata, but the editor gives no visual feedback that the metadata was set — and no signal when an important a11y attribute is missing. The values are persisted correctly in the ProseMirror JSON (dotCMS stores the JSON, not rendered HTML), but from the editing surface they are effectively a write-only field set: the author cannot see, confirm, or be nudged to fix them.

This was originally filed for tables only; the same problem applies across block types:

Block A11y metadata it can carry Current editor feedback
Table caption, aria-label, aria-labelledby None — caption never renders; aria attrs invisible
Link aria-label, title None — no marker that a link has an aria-label/title
Image (dotImage) alt, title None — no indication alt text is set, and no warning when alt is empty (the most common a11y defect)
Video (dotVideo) title / aria-label (and missing captions/tracks) None

Net effect: a block can carry (or be missing) accessibility metadata with zero visible hint in the editor. Authors can't confirm what they entered, and nothing flags a missing-but-important attribute like image alt text.

Scope note: this ticket is about surfacing a11y metadata (indicators / rendered elements / "missing" nudges) on the editing surface. Systematic validation of content against accessibility guidelines (WCAG / Section 508, parity with the TinyMCE AChecker) is a separate, larger capability tracked in #36255.

Original detail — the table case (representative)

The new Block Editor's Table properties popover (table_edit toolbar button) sets caption, aria-label, and aria-labelledby on the table node:

  • Caption is never rendered. The table is configured resizable: true, so it uses prosemirror-tables' TableView NodeView, which renders <colgroup><tbody>… and never a <caption>. The caption attribute on DotTable also has renderHTML: () => ({}). After the author types a caption and clicks Apply, nothing visibly changes — the value sits silently in the JSON.
  • aria-label / aria-labelledby are invisible by nature (a11y attributes on <table>), so the author has no indication the table carries them.

Found while reviewing PR #36042 (part of #35980 Block Editor bug hunting). Pre-existing, not a regression introduced by that PR.

https://github.com/user-attachments/assets/68596862-60ca-4c9e-a87c-987f2d8cd314

Table Without Accessibility
Image
Table With Accessibility
Image

Acceptance Criteria

General (all block types that carry a11y metadata):

  • When a block has a11y metadata set (caption, aria-label, aria-labelledby, alt, title), the editor shows a clear visual indicator that the metadata exists (rendered element where natural, otherwise a small badge/marker on the block).
  • When a block is missing an important a11y attribute (primary case: an image with no alt text), the editor shows a non-blocking indicator so the author is nudged to add it. (Indication only — full rule-based validation is #36255.)
  • Indicators stay in sync as the author sets / changes / clears the values via the relevant popover (table properties, link popover, image properties).
  • All values round-trip correctly in the ProseMirror JSON and, where a render-to-HTML path is used (getHTML() / headless SDK), are emitted on the correct element (e.g. <caption>, alt=, aria-label=) rather than dropped.
  • No regression to table column resizing, cell selection, the cell-handle popovers, link/image editing, or any existing block behavior.

Per block:

  • Table — non-empty caption renders as a visible <caption> inside the editor; aria-label/aria-labelledby presence is indicated.
  • Linkaria-label/title presence is indicated (e.g. on the inline link or its edit popover).
  • Imagealt/title presence is indicated; missing alt is flagged.
  • Videotitle/aria-label presence is indicated.

Priority

Low

Additional Context

Relevant files (core-web):

  • libs/new-block-editor/src/lib/editor/extensions/table-extensions.tsDotTable; caption attribute currently renderHTML: () => ({}), no NodeView emits <caption>.
  • libs/new-block-editor/src/lib/editor/extensions/editor-extensions.ts — table configured resizable: true (activates prosemirror TableView).
  • libs/new-block-editor/src/lib/editor/components/table-properties-popover/table-properties-popover.component.ts — sets table caption / aria-label / aria-labelledby.
  • libs/new-block-editor/src/lib/editor/extensions/link.extension.tsDotLink, carries aria-label + title.
  • libs/new-block-editor/src/lib/editor/components/link-popover/link-popover.component.ts — link aria-label / title editing.
  • libs/new-block-editor/src/lib/editor/extensions/nodes/image.extension.ts + image-properties popover — alt / title.
  • libs/new-block-editor/src/lib/editor/extensions/nodes/video.extension.ts — video metadata.

Related: PR #36042, issue #35980; accessibility validator spike #36255; Block Editor parity epic #35262.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the listed table-extensions.ts and editor-extensions.ts files to understand DotTable and the resizable TableView, then inspect the table, link, and image popovers alongside the link, image, and video extensions. Trace how metadata changes are stored and rendered, including the table caption path. Done means indicators stay synchronized for all listed metadata, missing image alt is flagged, and values round-trip without regressions to editing behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
accessibility, frontend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.