Wrong document outline because of Term reference label in h3

This is a bit of a difficult problem, but thanks for bringing it up. The problem is:

- we need to render headings for some render components
- we do not know where in the document hierarchy these components will appear

We might render a list with a heading, and it might be used in a sidebar block, or the footer, or in the main content of a page under another heading.

I don't think that there will be a good solution to this until we (the developer community) begins to better understand and implement HTML5 sectioning elements, which will help adjust the document outline. Of course, these also need to have better support by user agents, including assistive technology.

Related issue: #1218640: Bartik displays all taxonomy term fields in a smaller font than other fields

Can we get some outlines provided from actual sites to compare?
http://gsnedders.html5.org/outliner/
http://code.google.com/p/h5o/

How do we get the "better understand and implement HTML5 sectioning elements" that Everett's called for.

Actually, shouldn't this be fixed in D8 and then brought back?

my god, this issue still there for 3 years already!

@freelylw - would love it if you could submit a patch. It's also not 3 years. It isn't 2015 yet.

@mgifford sorry I don't know how to code, love to do this if I can. I just start to use D7 and noticed this problem

I wrote a longer reply, but lost it.

This probably is hard as described in #1. I don't know any CMS that has resolved it. Closest approach might be:
https://github.com/ThePacielloGroup/html5-h

That is something we could work towards for Drupal 9.

Some related links:
http://accessibleculture.org/articles/2011/10/jaws-ie-and-headings-in-ht...
http://www.smashingmagazine.com/2013/01/18/the-importance-of-sections/

It's never too late to learn to code. Alternately to reach out to the AT vendors and get consensus from them on how to deal with this.

From feedback in #1218640: Bartik displays all taxonomy term fields in a smaller font than other fields in August it has been explained that the taxonomy field needs to look deliberately different to the other headings.
A quote for Jen...

This is a deliberate design decision to create a visual hierarchy in what's most important vs not as important. If you'd like to override this for your particular website, I suggest making a child theme of Bartik and adding a bit of CSS to change it to look how you want.

So I think a h3 element was just chosen to make the styling look visually different, as h3s print at a smaller in size. I don't see why we can't change term reference headings to print with the same markup as the other fields but with a class that can add particular styles. Seven is dealing with the styling of headings and accessibilty etc here #2028053: Add typographic styles, components, and utility classes.

But looking at the recent status changes this issue seems to have been postponed to 8.1.x-dev so I will set it as so. Feel free to open this up again or create another issue to change the term reference markup.

It needs to be a heading for accessibility. A heading (H1-H6) is needed semantically before a list (UL or OL) for screen reader users.

Since this is (a) an accessibility issue, and (b) can perhaps be fixed with only a markup change - aren't those two independent reasons why this can still be an 8.0.x issue?

So Everett's comment in #1:

I don't think that there will be a good solution to this until we (the developer community) begins to better understand and implement HTML5 sectioning elements, which will help adjust the document outline. Of course, these also need to have better support by user agents, including assistive technology.

That's basically the way to solve this, right? You can use <section> or similar to wrap the list of terms, and then inside that it doesn't matter what level heading you use, right? - i.e. <h1> is allowed. And since Drupal 8 already uses <section> elsewhere I assume it's supported enough by screen readers at this point that it's OK to use?....

I'm also adding the backport tag here since it was mentioned above that it would be good to fix this in Drupal 7. We can't assume HTML5 there so I'm not sure what the solution would be, but we should at least see if there's something we can do.

I agree with @David_Rothstein.
Using a HTML5 section means it's contents can have it's own heading hierachy. Read here for a good example... https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Sections_and_Out....

https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Sections_and_Out... explains Sections.

Patch please :)

some screen-reader users use a document outline to jump to sections

This is incorrect: http://www.w3.org/html/wg/drafts/html/master/sections.html#outlines

I think what you mean however is that screen readers can navigate the page using headings, if so, then yes, this is correct.

the field labels are inconsistently styled

This is a CSS issue.

In many situations, this will create a false outline

I can only think of one out of the box - in forum posts the tags field is right at the top. However, this is in no way the fault of the h3 on the term list, the problem is caused by not using a new heading to introduce the long text. OK, so we know this, the proposal here is to use section element to fix this issue, however it will not fix the issue because no user agent recognises section element as a sectioning element.

Mike is right, we must use headings on lists, and lets be frank, a heading can appear anywhere in the long text itself, thus branching the outline.

I think the bigger question here is this - is this actually a real world issue? IMO no, its not really an issue. The only possible issue I can think of is for accessibility and headings for navigation, however we are merely assuming this might be an issue, however I do not see screenreader users pointing this out as a real problem, even after many years of us doing this.

At the end of the day each author needs to take particular care to structure documents with headings, personally I think the forum structure is flawed, but html5 is not going to save us here. The inherent flaw is sticking an h3 in the middle of the document flow and not having an h2 directly after the tags to introduce the long text.

So, yes, we could use a section element, but it will only make us feel better, it does not fix the issue, despite what some outlining tool might indicate.

Bottom line is section/sectioning elements and html5 outlining is a fiction, it only exits in specifications, but it looks like user agents have near to zero interest in actually implementing it.

Good gracious, I just looked at the Forum content type and now notice the entire comment form is above the content, in this case we have bigger problems for forum nodes.

And yes, its actually meant to be like this, see: core.entity_view_display.node.forum.default.yml

Update: this issue will fix the forum node comment field issue afaict judging by the current patch: #2106243: Use yml files to create the forum module's comment and taxonomy term fields

So as Emma mentioned in #12 Seven deals with this problem by adding header-x classes that allow you to choose a different header style to the html element. So we can have the best of both worlds. #2028053: Add typographic styles, components, and utility classes

I imagine the mark up would look something like:
<h2 class="header-c">Tags</h2>

We should implement these classes after #2375673: Split Bartik's CSS into SMACSS style components has landed

Lewis, I do this like Bootstrap does, I use small as a modifier also: e.g.:

h1, .h1 {@include adjust-font-size-to($xxx-large)}
h1 small, .h1 small {@include adjust-font-size-to($x-large)}

Yes, they can be very useful.

We will be working on the fix for this issue plus adding classes for all of the other heading styles in this issue... #2400233: Add reusable heading classes to Bartik.
Postponing this issue here for now.

Ok, that's fixed now.

Patch attached with before and after pics (should be no visual difference).

Before:

After:

Hey @mherchel. Thanks for the patch! It's almost there, we just need to implement the work @LewisNyman said in #18.

We need to have the tags title print as a h2 and then apply the h3 styles to it using the heading-x classes in the CSS.

The tags need to intentionally print "as h3s" purely for the styling, but in the markup they need to be h2 elements.

Changed divs to h2s

Probably should add a screenshot or two (before, after). Otherwise this would be RTBC.

The patch is technically correct thank you so much @mherchel! But due to other (bad) CSS in the theme that we haven't refactored yet the solution does not kick in as we like. The heading styles do not work because of far far too much overspecifity from other css. We want to fix this in Bartik with reusable classes, no multi level selectors, no selectors containing raw html elements and we are just not that far enough with the taxonomy tags section.

See screenshots.
 

 

 
I am postponing this issue until we clean up the related CSS. The h2 having just the class heading-c is the perfect ideal way to go!

@emma.maria - what is this postponed on?

I don't see how switching from a hardcoded H3 to a hardcoded H2 helps... doesn't it actually make things worse?

The original problem here was just about a missing heading level on node pages (i.e. a jump from H1 to H3) which was relatively minor, I think.

But if it's switched to an H2, then on pages which display a list of node teasers (like a view, e.g. the default front page), things get a lot worse.

Before patch:

• H1. Page title
  • H2. Node title
    • H3. Tags
  • H2. Another Node title
    • H3. Tags

After patch:

• H1. Page title
  • H2. Node title
  • H2. Tags
  • H2. Another Node title
  • H2. Tags

Seems like it would be a lot worse to me; now it's no longer obvious that the tags are associated with each node - rather they appear like nodes of their own.

Maybe there's a way to do this so H2 is used only on the full page node view (at node/X) but H3 is still used everywhere else?

So, yes, we could use a section element, but it will only make us feel better, it does not fix the issue, despite what some outlining tool might indicate.

Bottom line is section/sectioning elements and html5 outlining is a fiction, it only exits in specifications, but it looks like user agents have near to zero interest in actually implementing it.

Do you know why? Is it that screen readers haven't gotten around to it yet, or they're deliberately not going to do it?

Given that this is part of the HTML5 standard it seems like the best general solution available to Drupal is to start using it in these situations and then hope user agents will respect the standard... but I guess it would be pointless if they're never going to for some reason.

True, although this isn't a problem with the default node layout provided by core... and on some level it's the responsibility of a site builder or install profile to make sure they build things in an accessible way (although in practice I can see that very few people will ever think about this specific issue).

So this is really a conflict between two accessibility goals?

• Lists are supposed to have headings for accessibility.
• But you can't realistically mandate that because you have a heading in front of a list you need to add a heading on everything that is at the same level of the hierarchy and that comes after the list too. (For the specific case of fields, it's very common not to want some fields to be configured with a label in front at all - and that's not wrong in general, some simply don't need them.)

As far as I understand, HTML5 <section> elements are the only real solution to this problem too (since they allow you to show where the "end" of the section covered by the heading is), so it comes right back to the question in my previous comment :)

In my experience, trying to solve the overall architectural issues in a bug report usually means that neither get fixed, or not for a very long time at least. I would really recommend we fix the initial bug reported in this issue and open a follow up to discuss changing our HTML policy to <section><h1> - I can't see that happening before 8.1 though

#30 I don't know why, I do know Jaws have tried it but discontinued development. Its not just screen readers though, no user agents implement this afaict. I tend to think everyone is focused much more on ARIA, RDFa etc whereas relying on outlines is very difficult because the specs are ambiguous (therefor implementations vary too much to be reliable).

With regards to the design change, lets just make sure it works with the label inline, that was the original reason why the label/heading font size matches the tax term size.

FYI here is the original discussion from regarding menus and headings (the tax terms are basically a menu) #364219: Navigation menus should be preceded by headings of the appropriate level (usually <h2>)., I can't find the issue for tax terms, however that is the root issue that kicked it all off in Drupal, I would also add that this had been very successful in terms of improving accessibility, its basically been in the field for 6 years and has proven very useful and robust. We absolutely should not change this unless better technology comes along and has broad support and is widely used.

@no2e Screen reader users navigate by the headings. Without a heading they will just skip over a list of links and not get a sense of the structure of the page. An example from the W3C is:

http://www.w3.org/TR/2008/WD-WCAG20-TECHS-20080430/H42.html#H42-ex1
http://www.w3.org/TR/2008/WD-WCAG20-TECHS-20080430/H69.html#H69-ex2

As @Jeff Burnz said, this is also something we've tried to implement consistently in the interface since D7. It would be good if we could continue with that.

@LewisNyman agree with setting up a new issue to discuss broader policy issues for 8.1.

By adding tags to an article and viewing them here, I expect to see this problem.
node/1
/taxonomy/term/2

The outliner here https://gsnedders.html5.org/outliner/ shows the Comments under the Taxonomy, but that's a bit of a mess. That doesn't make sense to me as the taxonomy is an H3, but the comments are an H2.

There's a limit to how perfect we can make this and it's unclear to me how critical the hierarchy is in most cases. Absolutely it's better if it is nested correctly...

What is the most logical solution for this issue? We need clear instructions to move this issue forward, otherwise it is just going to sit here.

Also if the solution turns out to be we just to do nothing, I can close the issue.

Change the tags h3 -> h2. At least it's not broken out of the box.

Ok, this is essentially a re-roll of #25. Except that core/themes/bartik/templates/field--taxonomy-term-reference.html.twig no longer exists & there was no explanation as to why 'heading-c', was added.'heading-c',

Lets see if this gets us closer.

I didn't test the latest patch, but doesn't switching from a hardcoded h3 to a hardcoded h2 make accessibility worse rather than better? (We discussed that earlier; see my comment in #29.)

@David_Rothstein Ah yes you're right, sorry for my drive-by solutioneering :D We'd just be replacing a problem with another problem.

I've written a patch that passes the view mode into the twig template. The template assumes if you're not using 'full' then it's probably a listing. Pretty basic but I guess someone would use display suite to keep complex logic sane.

Looking at the patch in #42 I feel like Bartik is adding even more to an already overengineered specific field in Core. I am tempted to take out the heading tag altogether from the tags field template.

No other field label has a heading and no other theme in Core adds the heading. Also the heading field is not being styled different to other fields based on the h3. I can't see a reason to keep the h3.

*winces incase of backlash :-)*

Headings are important for navigation. It is more complex, but it is critical for blind and low vision users who use headings to provide context for the page.

There really isn't that much logic that is being added to provide this, and it makes Drupal more consistent.

In looking at this issue I decided to use the outline function in the WAVE Toolbar. It was there that I noticed that there is a difference in the title when you're logged in and logged out.

Logged in it looks like this (from the page.html.twig file):

<h1 class="title page-title">
<span class="field field--name-title field--type-string field--label-hidden quickedit-field" data-quickedit-field-id="node/1/title/en/full" property="schema:name">Trees</span>
</h1>

Logged out it looks like this (from the node.html.twig file):

<h2 class="node__title">
<a rel="bookmark" href="/node/1">
<span class="field field--name-title field--type-string field--label-hidden" data-quickedit-field-id="node/1/title/en/teaser" property="schema:name">Trees</span>
</a>
</h2>

This should be a new issue, but really can't see what the headings would change between node.html.twig & page.html.twig

Anyways, logged after creating a page with a taxonomy, the hierarchy is:
Heading level 1: Trees
Heading level 2: Primary tabs
Heading level 3: Tags

I feel that for consistency, the scope of this issue should be widened to affect all instances of entity reference fields, or potentially all fields.

I also propose that the resulting style amendments be dealt with in a separate issue, and this issue focus on applying the correct semantic tag and therefore resolving the original accessibility problem.

#47 yes for entity reference fields because right now Bartik is broken - see #1847596: Remove Taxonomy term reference field in favor of Entity reference, the only consistent fix here is to a) remove Bartiks template override (and in so doing reduce accessibility) OR b) "implement a new theme hook suggestion that includes the target entity type for entity reference fields" SEE https://www.drupal.org/node/1847596#comment-9813999, and convert Bartik to use this new template suggestion instead of the current field--node--field-tags.

Think we're going to need to move this to 8.1...

I agree with @emma.maria in #43 - bartik theme should not have a template that only applies to the standard profile. That template should be in the standard profile if it relates to its content model.

I think at this point, we might be best to either close this issue and start a new one to just remove that template or decide to mark this as closed won't fix given Bartik is now deprecated.

Added reroll of patch #42 on Drupal 9.5.x.

Fixed failed commands against #65
Attached interdiff

This appears to be specific. to bartik and since bartik was removed in D10 going to move to contrib module