Add classes to style h2 tags like an h1 tag

[loganmccaul]

Currently, the heading tags (h1 ... h6) are being used to style a page to be visually correct without regard to html structure, causing a situation where the html structure is broken.

h1. Page Title
  h2. Missing
    h3. Missing
      h4. h2 styled as h4
h1. h2 styled as h1
h1. h2 styled as h1
  h2. h3 styled as h2

If new classes, such as bx--heading--1, were added a h2 tag could be style like an h1 tag, but remain an h2 element allowing for proper HTML structure.

h1. Page Title
  h2. .bx--heading--4
  h2. .bx--heading--1
  h2. .bx--heading--1
    h3. .bx--heading--2

[hellobrian]

Notes from Logan about Headings

Spoke with @loganmccaul offline to get a better sense of the problem he's raising.

(Paraphrasing here. Correct me if I'm wrong)

FEDs like Logan are at odds with the following:

• maintaining accessibility
• implementing design comps
• using carbon-components type scale for headings

☝️ None of these really match up and in Logan's case, for him to do his work is more complicated than strictly following Carbon Design System vs Design Comps vs Accessibility.

According WebAIM on Semantic Structure,

Pages should be structured in a hierarchical manner...

• (<h1>) being the most important (usually page titles or main content heading),
• (<h2> - usually major section headings),
• (<h3>) - sub-sections of the <h2>, and so on.

For users who rely on screen readers, these heading tags are going to create a navigational hierarchy that will help them navigate the UI they're using.

Also, see W3 on Headings.

Example from Bluemix

There should only be one h1 on a page.
This is already included in the main header labeled "IBM Bluemix"

Since Carbon Design System says h1 tags should look a specific way, the h1 for Bluemix as a product needs to use overriding CSS.

TL;DR: Here's what I think we should do:

• We should allocate time to updating content on the website to explain the proper usage of heading tags by documenting the important parts of these a11y docs.
• Provide the .bx--heading classes proposed by @loganmccaul

[aagonzales]

Yes, we should definitely talk about this. I don't think I'm quite understanding all the problems and requirements just from this issue. To be honest I don't really understand how heading tags work or should properly work, especially across pages/areas of the product.

Since Carbon Design System says h1 tags should look a specific way

We did a smart default in-case no hierarchy is applied but from a system standpoint we do not define global h1s or any other headers.

Carbon specifically doesn't define a heading scale because the hierarchy of each page/section could be different. A designer should be picking from the carbon typescale to define their own heading tags/scale.

Also cc: @iangfleming since he helped with the type scale and defaults

[hellobrian]

I can set up a meeting with all of us. It was helpful for me to hear from Logan in-person about why this issue was raised originally.

We did a smart default in-case no hierarchy is applied but from a system standpoint we do not define global h1s or any other headers.

Yes, I believe this is the same reasoning @iangfleming settled on when we helped to define the typescale.
But, I think we can make it a little easier for FEDs to apply our typescale styles to different heading elements.

For example, we have our h1 style:

  h1 {
    @include reset;
    @include font-size('32');
    @include line-height('heading');
    @include letter-spacing;
  }

There isn't really an easy way for the user to reuse this style without doing one of the following:

• copy and paste the CSS for h1
• use an <h1> element but this breaks accessibility for Bluemix

I think the solution is to offer a CSS class like @loganmccaul originally suggested.
And we can do that very easily.

 h1,
 .bx--heading--1 {
   @include reset;
   @include font-size('32');
   @include line-height('heading');
   @include letter-spacing;
 }

Providing a class lets users use the class in their HTML or SCSS to reliably use our h1 styles on the text element that needs it.

<h2 class="bx--heading-1">I look like an h1 but I'm really an h2</h2>