CSS Code style: do not use display: contents

I propose to add a new CSS Code style recommendation on our HTML and CSS codestyle page:

Avoid using display: contents.

The support [3] of this value is not complete and changes wildly depending on browser versions.
As explained in [1], ‘display: contents’ could be a liability for accessibility in xwiki.

AFAIK, this value is useful especially in combination with display: grid to have all the children in the grid even though they are wrapped in semantically relevant parents [4]. In some cases, using display: contents would just make the parent disappear from the accessibility tree [2] and defeat the purpose of having a semantic HTML structure.

So far in xwiki-platform, we don’t use CSS display: grid (we use bootstrap grid instead) and we don’t use display: contents. I think it’s still necessary to write down this recommendation in order to avoid making a major accessibility regression without noticing it.

Note: As of now, using display: contents will not systematically trigger a failure in our WCAG automated tests.


  1. display: contents considered harmful – Eric Bailey
  2. Display: Contents Is Not a CSS Reset — Adrian Roselli
  3. "display: contents" | Can I use... Support tables for HTML5, CSS3, etc
  4. More accessible markup with display: contents | hidde.blog – this article is not perfect, I recommend to take it with a grain of salt. It lacks some actual tests of the functionalities, see the comments made about it in [1].

+1, sounds good, in particular if we aren’t using it yet. Would be good to have an automated test for it, though.



+1 Thanks



Was going to say the same thing, we need a test or just writing it down will not be enough :wink:

EDIT: we use GitHub - validator/validator: Nu Html Checker – Helps you catch problems in your HTML/CSS/SVG but idk if it could be configured with some custom rules. If not, we’ll need to decide how to check for custom CSS rules. That could be done with other frameworks.

+1 otherwise

1 Like

It doesn’t seem like the Nu HTML Checker accepts custom rules as options.
Seems like something like StyleLint (MIT license) would be more appropriate to test such css code style. Stylelint looks very extendable and active :slight_smile:

Sounds good. We need to find how to integrate that into our maven build.

I updated the code style page.

Keeping note of this discussion about Stylelint :+1:

1 Like