w3c/tr-design

CSS used by W3C specs (this repo is not about the w3.org/TR index page)

W3C Technical Reports Design Project

This project is available on GitHub.

The purpose of this project is to maintain and improve the style sheets for current and future technical reports published by the W3C.

New style sheets are adoped once a year (see below). The project goal for 2015 is outstanding maintenance: to clean up, consolidate, and update the styles without significantly altering the visual look and feel. (Future releases may significantly alter the visual design, but we probably want to overhaul the markup first, and that waits until after the new publication system is sorted out.)

Contributing

If you're familiar with GitHub then contributing is simple: just fork and make pull requests. Absolutely everyone is welcome (and even encouraged) to contribute to improve the design of W3C specifications. Bugfixes, code cleanup, and simple improvements will be unilaterally approved by the Design Point Person. For more significant changes to the visual styles, discussion on [email protected] is encouraged to get feedback and consensus. (Think of it as a design critique.)

Do not commit directly to any of the common branches (gh-pages and 2016 at the time of writing) unless you are the Design Point Person for the project. Instead, fork the desired branch and submit a pull request.

Guidelines for a proper design

1. Ensure the security and privacy of the individuals reading the document;
2. Ensure proper access by everyone regardless of disability;
3. Consider the different languages, scripts, and cultures from around the world;
4. Ensure that individuals can read properly the normative and non-normative parts of the document when scripting is disabled or not available;
5. Consider the impact of the design on the W3C publication ecosystem: publication tools, authoring tools, editors
6. Ensure that the W3C Brand and general W3C website integration are respected, per the W3C Communications Team;
7. Consider the Web user agent compatibility risks (past, present, and future) and the long term maintenance.
8. Use valid CSS and follow CSS best practices.
9. Ensure that the document can be printed beautifully.

Discussions happen through issues, pull requests, and on [email protected].

Release Process

Principles

For the purpose of this project, there are two guiding principles to guarantee efficiency and progressive design:

1. W3C MUST NOT change the design of technical reports already published.
2. W3C MAY adopt a new design for technical reports only once per year, on the 1st of January.

Process for approving a new design

For any given year:

1. No general proposals for a new design can be made after September 30.
2. No final design can be proposed after October 31. This is intended to ensure a minimum of one month for wide review of the final design before formal adoption.
3. The deadline to obtain W3C Director approval for the final design is November 30. No substantive changes can be made to the final design after approval. This is intended to guarantee a minimum of one month advanced notice for the W3C publication ecosystem (publication tools, authoring tools, editors).
4. The W3C Webmaster must deploy the new style sheets and associated assets no later than December 1st, if approved by the W3C Director.
5. The new design becomes effective on January 1st of the following year for a 12 months duration.

The dates above are deadlines but the earlier the better, especially when considering the schedule of the W3C TPAC meeting.

One Design Point Person per year is in charge of managing general proposals, producing and proposing the final design, ensuring wide reviews, addressing issues and pull requests, and obtaining the W3C Director approval. Only the Design Point Person — and, occasionally, W3C staff — should commit to the common branches of the project. This individual must engage with the Web Community at large and is appointed by the W3C Director.

NOTE: For 2015, the Design Point Person is @fantasai.

If the W3C Director cannot approve a new design within a given year, the design of the current year remains effective for the following year.

The W3C Director MAY delegate responsibility (generally to other individuals in the W3C Team) for his role described in this document.

Bug Fixing

Bug fixing MAY happen on a continuous basis for all style sheets. Published styles are include in releases/ for maintenance purposes.

Branches

At any point in time, branch gh-pages is used for work on next year's TR design, until the first candidate release is branched out from it. From that moment on, gh-pages becomes the development branch for the following cycle.

Branches with years in their names (eg, 2016) are used exclusively for bug-fixing candidate releases for that specific year. Commits to gh-pages will not be propagated to yearly branches.

Considerations

1. There are no backward compatibility issues since we never change the design of documents already published and the new design MAY NOT accommodate the large set of documents published in the past by W3C anyway.
2. Unique design among all W3C /TR documents is no longer guaranteed. Two W3C specifications published in two different years MAY look completely different. While design consistency from year to year is NOT required, it should be kept in mind and balanced to avoid confusing the Web community.
3. A new design does NOT have to address all possible future refinements before being adopted, such as taking into account all possible future user preferences and how to display all future combinations of those.
4. As a side note, Proposed Recommendations published after the 15th of October should easily allow the W3C Advisory Committee to visualize the document using the new design of the following year. Note however that such new design may be tweaked until November 30 or rejected by the Director.

tr-design's Issues

Sticky TOC on the left with clickable doc links...

Like the getting started doc for bootstrap and many others. Just scroll down a little and you will see what I mean...

http://getbootstrap.com/getting-started/#migration

They put it on the right side, but either is fine, IMHO. For long docs it is great to be able to see the TOC as a hierarchy tree with a marker of some sort showing the current position.

Thanks :-)

Mobile-friendly Styles / Restrict the Style of <pre> and Tables

This is relevant to #10

Not sure if it's a general problem for all the mobiles, but the font-size in our specs is always too small to read on my phone (Safari 08, iPhone 5s). Here's a screenshot from /TR/animation-timing:

It's even more problematic when the style of the pre elements haven't been carefully chosen (screenshot from /TR/resource-timing):

My suggestion'd be:

• Slightly reduce the margin of the document (less white space in this case, on the contrary to #13 )
• Adjust(increase) the font-size of the titles, the subtitles and the body;
• Restrict the Style of pre elements and Tables, though it isn't easy...

Minification and long-caching

It would not be a bad idea to have the entry point sheets just be shells that import other styles. Those other styles are to be minified, given a name based on a hash of the content, and set to have eternal caching.

Add skip to TOC/skip to content links

As a visual keyboard user (on a large screen) the TOC is the first thing I see, yet the keyboard navigation doesn’t bring me to the TOC. Provide jump links to the TOC as the first thing in the site helps. That jump link should be invisible by default but visible on :focus.

(Relates to #39.)

On mobile, code font is smaller than text font

https://webbluetoothcg.github.io/web-bluetooth/#device-discovery (A bikeshed spec), when rendered on Android Chrome, looks like:

Instead, the code font should be approximately the same size as the paragraph text.

Use different icons/glyphs for the show/hide toc and back to top links

The show hide toc arrow left/right has an unclear function when looking at it for the first time. I would prefer the abbreviation TOC for it.

The back to top arrow is very thin, it could take a thicker arrow to make the purpose really clear.

top navigation arrow misplaced?

http://w3c.github.io/hr-time/
does have the top navigation arrow appearing before the spec title, instead of the bottom left corner. CSS issue?

What is the backwards compatibility story?

If we plan for the styles to be backwards compatible in perpetuity, we need a strategy if the design is going to evolve more than a little bit.

We know from experience that updating styles on unsuspecting drafts will break things, and there are too many to check.

One option is that when new, larger changes are made they are keyed off a special class that drafts must use in order to opt into the new style. (I think this is my preferred approach.)

Another option is to have releases (hopefully not too often) and major ones can break things but are opted into.

Sheep appearing beneath the copyright statement

See the image (taken from http://www.w3.org/TR/2015/WD-international-specs-20151020/ with the stylesheet link pointing to the new style sheet)

addEventListener on MediaQueryList?

In fixup.js, I noticed:

  var sidebarMedia = window.matchMedia('screen and (min-width: 78em)');
  if (sidebarMedia.addEventListener) {
   ...
  } else if (sidebarMedia.addListener) {
   ...
  }

According to caniuse.com, matchMedia() only became available in IE10, which probably means that sidebarMedia.addListener will never run (because IE was supporting addEventListener() properly by then). Maybe that second if statement could be removed?

Make it easier to point to github/bugzilla for comments please

I like to see a way to point people to github/bugzilla as the preferred location for comments on the document that blends with the information on mailing lists.

It should be possible to produce EPUB format from our TR documents

I think that, at long term, we should be able to routinely produce EPUB formats for our documents as an offline/download format (to replace the PDF versions that many TR documents offer).

This should not affect CSS styling; EPUB can handle those without problems. However, if (local) Javascript is used for the documents, we should check whether they are acceptable for EPUB (on long term, that should not be a problem either, but there may be limitation on short term.

Where it may require extra consideration is when a TR document consists of several files (typical for large specs like HTML5 or SVG). In that case a separate navigation file (table of content) should be made available, because it is not necessarily obvious how to generate those automatically from, say, respec sources. In general, the documents should be such that it should be easy to generate such EPUB via, say, a respec module; this may affect the structure of the document (adding some info to links to make the targets local for an EPUB file, etc.)

Images constrained to be blocks?

I applied the new styling to
http://www.w3.org/TR/2015/WD-clreq-20150730/#h-examples_of_zhuyin_annotations

Previously the four images in the figures were displayed side by side, which helps significantly in comparing the various figures. Here is a snap:

Now the images are shown as blocks, which spoils the intended effect.

Why are the images forced to be block items?

Note also, btw, that the positioning of the list item counter now is rather confusing compared to the original.

make wider space to the right

just raising this to ensure that it wasn't forgotten...

The initial proposal had the main text block centred horizontally in the window.

During TPAC we agreed that there would be a fixed distance margin on the right of the main text block, and that if the window size was increased horizontally the max-width would therefore produce a variable and potentially much larger margin to the right, so as to better accommodate wide tables, diagrams, etc.

Allow for "bleeds" on wide content?

This may be related to issue #24, but I am not entirely sure that one fully cover it.

The new design has restricted the default width of the text significantly. This creates issues with documents that were prepared under the old style; their transition to the new style may become fairly difficult and time consuming. The difficulty comes with content like large tables or diagrams that try to make use of the full width of a window and which cannot simply be shrunk without loosing readability. Just two examples, both from an upcoming Rec related to CSV on the Web (typically on data table, thus...):

• large diagram
• large table (please push the button down in the section labelled as "show detailed table annotations" to see them all)

I have made some local experimentation with these by simply exchanging the style file reference, and the result are fairly bad. The way I see it the only viable approach today would require a significant editorial re-engineering to make the examples and/or the diagrams usable. (This is a real drag at this stage of the process.) I am not sure whether there is a way to alleviate this. (E.g., is it possible to allow some 'bleed' of these content into the wide margin on the right? Not nice, but may be necessary... Or switch "off" the large margins for the document through a specific class.)

Cc: @plehegar @r12a @gkellogg @JeniT @6a6d74

Avoid picture for vertical side-bar

The "W3C Recommendation" text on the blue side is added as a (blurry) image. I don't see why this needs to be a picture.

In CSS you can do this with just text.. see for example on https://w3id.org/bundle/

I did that as:

    <div class="status"><div><span>W3C Specification</span></div></div>

and

.status {
    position: fixed;
    left: 0em;
    top: 0em;
    text-align: right;
    vertical-align: middle;
    /* Square version of the inside span. Slightly larger */
    width: 24em;
    height: 24em;
    /* Don't steal focus! */
    z-index: -1;
    /* For mobile browsers who overlap */
    opacity: 0.6;
    /* Enable for debugging
    background: #abc;
     */

    /** From http://stackoverflow.com/questions/1080792/how-to-draw-vertical-text-with-css-cross-browser */

    -webkit-transform: rotate(-90deg);
    -moz-transform: rotate(-90deg);
    -ms-transform: rotate(-90deg);
    -o-transform: rotate(-90deg);
    transform: rotate(-90deg);
    /* also accepts left, right, top, bottom coordinates; not
    * required, but a good idea for styling */
    -webkit-transform-origin: 50% 50%;
    -moz-transform-origin: 50% 50%;
    -ms-transform-origin: 50% 50%;
    -o-transform-origin: 50% 50%;
    transform-origin: 50% 50%;

    /* Should be unset in IE9+ I think. */
    filter: "progid:DXImageTransform.Microsoft.BasicImage(rotation=3)";
}

/* The actual status box */
 .status div {
    display: block;
    background: green;
    color: white;
    width: 23em;
    padding-top: 0.3em;
    padding-left: 0em;
    padding-right: 5em;
    padding-bottom: 0.3em;
    /* Enable for debugging
    border: red thin solid;
     */
}

/* And text inside, don't confuse fonts as it breaks em above */
.status div span {
    font-family: "Tauri";
    font-size: larger;
}

(Feel free to use the above)

More white space please

I'd like (much) more white space before h2 and h3, so that it's easier to spot where sections start and end, and read the titles. (Extra space not necessarily needed in the SOD area.)

A bit more keyboard love

As a user, I would like to be able to, from the first page load on Desktop, be able to skip to the sidebar and back (skip links). I would also like to be able to see the funny arrow-thing at the bottom left of the page, but when I'm tabbing I'm almost always on a link and the URL the browser displays is just larger than the arrow (so if the arrow were either a bit bigger or moved up a bit from the bottom, it could be seen). I also have to discover what these arrows do as they're kinda mystery-meat-- unless the title that is supplied to mouse users could be added on focus?
arrow-thingie:focus:after { display: whatever; content: attr(title); //and some styles to put it in a useful place}

And as someone using either IE or any of the Blink browsers, I would like clicking a link in the sidebar to bring not only my visual focus but also my keyboard focus to the destination. Due to long-standing bugs that seem unlikely to be addressed soon, could the devs consider adding tabindex="-1" to the link destinations, which allows focus to go to the right place in these browsers? I've unfortunately been using this hack for years myself, but it doesn't seem I'll be removing them anytime soon, and offers functionality to users who maybe cannot choose to switch UAs while viewing these pages.

prevent the page from scrolling horizontally on narrow screens

Right now, if you go to http://fantasai.inkedblade.net/style/design/w3c-restyle/2016/sample on a small screen (any brand phone with any OS & browser), the page scrolls sideways, horizontally back and forth, while you are trying to read and trying to scrolling vertically. This makes reading the document very hard, especially since these are long documents.

You can replicate this on a traditional computer by making the browser window very narrow.

Why are the horizontal scroll bars appearing? Because some of the content is too wide — especially the tables.

The solution is to make the tables stay inside the available space, and not let them scroll-jack the whole page.

This code solves most of the problem:

table {
  display: block;
  overflow-x: auto;
}

Now, we were having a long conversation about this on Twitter, and I saw people complaining that then you have to scroll sideways to see the whole table. Yes, that's true. And likely not ideal, but you'd have to scroll sideways to see the whole table anyway. To me, the addition of this code does not make the experience of seeing the table worse. It does make the experience of seeing everything else much better. In fact, imo, no one will look at the tables without this code, because no one will scroll down far enough to get to the tables.

If you disagree, please at least first test this on a touch screen smart phone of your choice. http://fantasai.inkedblade.net/style/design/w3c-restyle/2016/sample
In fact, test both — with and without this change — and see what it's like on a touch screen. Trying to guess what the experience is like from imaging it is unlikely to produce good information for making a decision. No less than 9 people complained on Twitter about this experience. It was by far, the number one bug report.

If this simple solution doesn't provide a nice-enough table experience, then a second-level improvement would be to find a better solution for the tables. Fantasai has pointed out that there are many kinds of tables, with many different data structures. Any solution needs to be universal and independent of knowing what the content in the table is.

A web search for "responsive tables" will provide a plethora of options. Some require a consistent and known data structure, so those are out. Doing quick search this morning I found:
http://exisweb.net/responsive-table-plugins-and-patterns
https://css-tricks.com/responsive-data-tables/
https://github.com/filamentgroup/tablesaw

My recommendation is to add table { display: block; overflow-x: auto; } as a first step. Then if time and energy allows, look into a more complex option for making the tables responsive.

BTW, this solution will have no affect on tables or other content when the screen is wider. It only affects whether the table alone gets a horizontal scroll bar or the whole page gets one.

/cc @fantasai @patrickkettner

Should the use of !important be forbidden

Since the pubrules checker checks that the W3C stylesheets are mentioned last in the list of stylesheets of a document, a lot of documents are making use of !important...

Should this be prevented by policy? I mean, there won't be any good reason to use it once the TR design is always cool and modern...

Regarding enforcing this rule, I know people will say that we simply cannot because it's easy to manipulate CSS with JS, but I would argue that this is true for pretty much everything in a document so at this point we ask people to be reasonable. Without going that far, it means Specberus would need to check inline CSS (<style> tag and style attributes) as well as external CSS files.

Make the W3C logo an absolute url

Right now it's a relative url "logos/w3c-white.svg" which means that it doesn't load for Bikeshedded specs that directly embed the stylesheet, unless I manually change it every time. ^_^ Mind making it absolute so I can just do copy/paste of the TR stylesheet into Bikeshed whenever things update?

Reduce the line spacing in the TOC

I think that a smaller line spacing in the TOC helps to
[1] make the structure of the document easier to see
[2] makes it easier to find items
[3] makes the TOC more compact which helps get a better overview of the document by fitting more into the space available

Compare the following screen snaps, before and after applying the new styling:

I think the former is more useable.

In addition, the positioning of the numbering in the new style is inconsistent, with the fourth-level numbering drifting to the right.

respec related conflicts with examples?

Consider the image below. It is a document generated through respec, using the standard 'example' class. When generated through respec, (see the original) there is only one vertical line on the left, when replacing base with the new version we get two.

/Cc: @halindrome @plehegar

should responsive design be a requirement?

Horizontal scrolling

In Firefox nightly the sample scrolls a little horizontally.

Larger back to top and show/hide sidebar buttons

Those buttons are extremely hard to hit on mobile (iPhone 6s Plus) and are only 22⨉22px large. The recommended size is 44⨉44px, so that is a quarter of the space they should have.

allow the user to control whether the toc jumps to the left

while it's generally useful to have the toc automatically jump to the left as the window widens, from time to time it can be annoying – for example, when stretching the window to see a large table, when i'm just about at the right width and suddenly i have to repeat the process (if my screen allows).

if there were some button in the toc area that can be used to hide the toc when displayed to the right, i think this may be sufficient.

Process questions for the transition to the new style

I'm somewhat concerned that there appears to be only one demo document for the new styling, and that that document only contains a subset of the features likely to need support under the new style (eg. no wide tables or diagrams per issue #27 ).

I wonder how many editors are actually trying the new styling against their documents to provide us with the necessary beta testing feedback before the big switch, and worry that all kinds of issues may surface AFTER the switch has been flicked. Such issues will need immediate attention to avoid confusion and the avoid impacting deadlines for some of the documents in question. Is there provision for that?

I suggest that we test the new styling against a wider range of specs (especially non-CSS specs!), and put up additional demos.

What could really help time-constrained editors to test against their specs would be to add a switch to respec and bikeshed (it would need to be within the next few days) that would allow the editor to quickly generate their document in the new style to check for errors. (Even if we don't do that this year, and i think we should, we ought to consider it for future years.)

Unofficial style missing in new set of styles

This is a request to add "w3c-unofficial.css" to the 2016 styles directory.

ReSpec's logic for selecting between the new and old styles is fairly simple (and would like to keep it so) - so it would be great to not have to special case for unofficial specs (by having to drop out to ../ from the 2016 dir).

Potential compat issue with Phantomjs 2.1

I'm seeing this getting dumped from ReSpec's tests when running Jasmin on Phantomjs 2.1:

TypeError: undefined is not a constructor (evaluating 'toggle.matches(':hover')')

  https://www.w3.org/scripts/TR/2016/fixup.js:42 in toggleSidebar
  https://www.w3.org/scripts/TR/2016/fixup.js:88
TypeError: null is not an object (evaluating 'head.offsetTop')

I think the main problem is assuming that:

    var head = document.querySelector('.head');

will always always return an element.

Do we need namespacing?

The classes used in these styles apply to many documents that also have their own styles. Adding new classes could easily clash. Should we introduce w3c- prefixes for ours?

Propdef tables no longer have a width limit on their TH elements

The stylesheet no longer has any special handling for <th> elements in propdef tables, which means that they look really dumb now with both columns being 50% wide and the th being centered.

Looking back at CSSWG's default.css, it looks like the necessary rule was, for some bizarre reason, nestled right in the middle of the .proptable styles, which were rightfully deleted.

We just need this back:

    .propdef th {
        font-style: italic;
        font-weight: normal;
        text-align: left;
        width: 3em;
    }

Since this actually is needed by all the *def types, I guess this is actually a generic table.def th rule that needs to be restored.

Effect of github.io on the display of the new style?

I was looking at:

https://w3c.github.io/csvw/html-note/index.html

The strange situation is that

• Looking that file with Chrome, Firefox, or Safari (on a MacOS) the styling is clearly incomplete; the 'Editors draft' banner is missing, and the margins of the page are also not set
• Looking at the same file through localhost on my machine, I see the new TR style appearing (with TOC on the left)

I wonder whether this is a CORS like issue or something specific to github. Or possibly respec (that file is done via respec).

But, taking into account that it has become the practice to refer to the github.io file as the "editor's draft" in the header of our publications, this should be taken care of...

/Cc: @gkellogg @halindrome @marcoscaceres

Blue line under W3C logo

When applying the new style to
http://www.w3.org/TR/2015/WD-international-specs-20151020/
and other docs, i see a blue line under the W3C logo at the top right of the doc.

Will that be automatically fixed for the new style?

move the toc higher

one of my main bugbears with the current TR style is the position of the toc. If i'm deep in the document, i often want to visit a different section via the toc. Getting to the top of the doc is easy in desktop environments - it can be a bit of a pain on my iPad (i may be missing something there).

but the main thing is that when you reach the top of the page you then have to carefully scroll down a bit to find the toc. That's the annoying bit.

Can we not move the toc so that it's almost at the top of the page? Maybe put it in a separate column alongside the SOTD stuff?

Figure too large?

I have a figure in my files, with the following markup

      <figure id="pwp_figure">
        <img src="figures/pwp.svg" alt="...">
        <figcaption>...</figcaption>
      </figure>

with no extra setting for figures. The SVG file does not have explicit width, only a viewport, ie, a pure 'rescaling' figure. The 1st attached screenshot shows that the figure occupies the full width of the page (using latest release of FF on Mac OS). Replacing the svg with png shows that the full width of the png file is used.

I also tried to explicitly set the width of the figure to 50rem. Using inline style I get what is shown on the 2nd screen shot.

(The respec uses the base.css in /2016/01/)

Styles for Unofficial Drafts not included

For some reason http://www.w3.org/StyleSheets/TR/w3c-unofficial is not included in this repository. Is that intentional?

Accessibility concerns

I've noticed a few issues:

• Keyboard navigation:
  • In Chrome, all links to "named" anchors are broken. For example, "clicking" on the "Jump to Table Of Content" link and then hitting the tab key puts the focus back on that link rather than focusing onto an element of the TOC. That's an old Chrome bug that can be "fixed" by adding tabindex="-1" to the "named" anchor (i.e. <nav id="toc" tabindex="-1">).
  • The visual layout does not really match source order as the TOC shows to the left of div.head (as in "before the header") even though it comes after it in the markup. This may be confusing to some users (i.e. sighted keyboard users). Also, it seems that for SR users best practice is to deliver the same experience across the board—meaning if sighted users perceive the TOC as being before the "header" then SR users should perceive that as well.
• The TOC "nav" may be better positioned at the top left of the viewport rather than its bottom because those links could go unnoticed on large screens.
• The "Pop Out Sidebar" link could be hidden from screen-reader users as its purpose is purely visual.
• I'd not wrap the "jump links" inside a nav element as only sections that consist of major navigation blocks are appropriate for the nav element.

In my opinion, pages like these are very difficult to navigate for keyboard users. Not only because the visual sequence is different than the natural tab order but also because once a user selects a jump link within the TOC and reaches that section by tabbing out—it is very laborious to reach back to the TOC. This is why I believe the use of accesskey may help here.

Regarding the jump links themselves, I think the second item (the one that toggles the TOC) should be a button instead of a link. And I'd not rely on title to convey the text, I'd rather hide the arrows from SR users and give them plain text (visually-hidden). Then you can display that text on mouseover rather than using pseudo-elements.

So instead of this:

<nav id="toc-nav">
  <a id="toc-jump" href="#toc">
    <abbr title="Jump to Table of Contents">↑</abbr>
  </a>
  <a id="toc-toggle" class="toc-toggle" href="#toc">
    <abbr title="Pop Out Sidebar">→</abbr>
  </a>
</nav>

I'd go with something like this:

<div id="toc-nav">
  <a id="toc-jump" href="#toc">
    <b class="visually-hidden">Jump to Table of Contents</b>
    <b aria-hidden="true">↑</b>
  </a>
  <button id="toc-toggle" class="toc-toggle">
    <b class="visually-hidden">Pop Out Sidebar</b>
    <b aria-hidden="true">→</b>
  </button>
</div>

or this if we think the toggle button is of no use to SR users:

<div id="toc-nav">
  <a id="toc-jump" href="#toc">
    <b class="visually-hidden">Jump to Table of Contents</b>
    <b aria-hidden="true">↑</b>
  </a>
  <button id="toc-toggle" class="toc-toggle" aria-hidden="true">
    <b class="visually-hidden">Pop Out Sidebar</b>
    <b>→</b>
  </button>
</div>

As a side note, "Collapse Sidebar" may not be the right wording here as the element does not collapse per se; to the contrary, it goes back into flow. I'm not sure that word helps create the proper mental model for how that TOC behaves.

Minor possible additions for paged media

I have recently implemented a service (primarily aimed at documents produced by respec) to convert TR documents to EPUB3. In doing so, and having looked at the output in some of the EPUB readers I have access. This resulted in some minor additions to the styling of the document. These are as follows:

h2 {
    page-break-before: always;
    page-break-inside: avoid;
    page-break-after: avoid;
  }

  div.head h2 {
    page-break-before: auto;
    page-break-inside: avoid;
    page-break-after: avoid;
  }

  figure {
    page-break-inside: avoid;
  }

  h3, h4, h5 {
    page-break-after: avoid;
  }

  dl dt {
    page-break-after: avoid;
  }

  dl dd {
    page-break-before: avoid;
  }

  div.example, div.note, pre.idl, .warning, table.parameters, table.exceptions {
    page-break-inside: avoid;
  }

  p {
    orphans: 4;
    widows: 2;
  }

I realize that some of these are part of the new CSS, but others are not. I think we could consider adding these to the core CSS, thereby avoiding processors like mine having to repeat them.

Note that some of the class selectors may be respec specific. Although the converter seems to work with documents produced by bikeshed, too, I must admit I did not go through all the bikeshed class names to find the corresponding ones, if any.

Strange numbering of sections

The very odd numbering of sections shown in section 2 the picture occurs on Firefox, Chrome, Safari and Edge. It's not only the toc – the numbering is the same in the body of the text. Is it anything to do with the style sheet?

Should there be a style guide, or guidelines in general?

Does this need some form of style guide that people follow when adding to the styles? Can we just start organic?

Hi-res and SVG images

A number of the images we use look really bad at higher resolutions.

Please don't uppercase note markers

https://webbluetoothcg.github.io/web-bluetooth/#bluetoothgattservice has a note whose header is "BluetoothGATTService attributes", which references a BluetoothGATTService type. That's being rendered as "BLUETOOTHGATTSERVICE ATTRIBUTES", which isn't the name of the type.

Better line widths please, and useful marginalia

I'd like to see line width that expands with the window, but doesn't fill the window width. (See related issues elsewhere.) Large images, tables, etc should fill the page width, where needed.

Use of the margin for side notes, diagrams, etc.

How is this documented?

Notably in how it interacts with the structures used in reports.

Space needed between h1 header and w3c logo

See the image (taken from http://www.w3.org/TR/2015/WD-international-specs-20151020/ with the stylesheet link pointing to the new style sheet)

Timeline and Considerations

As someone who normally uses whatever stylesheet I am given, I was concerned to see that the Proposed Rec that transitions in the fall "should easily allow the W3C Advisory Committee to visualize the document using the new design of the following year". When will there be test stylesheets for us to test for the upcoming year? I assume they will be available earlier because the deadline for the direction decision will be Nov 30 and the webmaster will deploy them on Dec 1 (making him/her work weekends?) . However, there is no mention of a schedule to provide stylesheets for people transitioning to PR in the fall who want the AC to visualize the final look.

Use fractional rem rather than em for "pre, code, a.property"

The rule that sets font-size to 0.9em in base.css for "pre, code, a.property" means that a <a> element in a <code> element in a <pre> element gets that rule applied 3 times, which makes it tiny and breaks space indentation between a <code>foo</code> and a <code><a>bar</a></code> — among other things, this makes WebIDL code managed by ReSpec look disaligned.

Using rem instead of em should fix this.

position shifts when the toc appears/disappears on the left

A disagreeable phenomenon: if I start with, eg, a narrow screen (and the TOC is not on the left), then enlarge it (and the TOC appears on the left) then the position on the main text disappears. See the two screenshots below: whereas I am at section 2.3.2 on the narrow screen here:

After enlarging the 'focus' goes to section 2.2.2:

The same happens when moving to a narrow screen from large.

I sort of understand what happens as far as the browser is concerned, and I am not sure something can be done without some JS support (again:-(, but maybe somebody has a clever idea...

Using dated version is not great

Can I kindly ask that we refrain from using a year (e.g., "2016") for the directory that holds the redesigns? Using years is known to be problematic (the W3C in particular should know this, as it has a long legacy of using dated URLs poorly). Instead, please tag versions using git and please just use two directories:

That is, if a resource is stable:
https://www.w3.org/StyleSheets/TR/

Otherwise, it's experimental and should go here:
https://www.w3.org/StyleSheets/TR/experimental/

Having dated versions makes a huge mess for tools like ReSpec because it means we need to unnecessarily maintain a list of all the possible different experimental versions year over year. Which is a maintenance burden.

If a user wants to opt into "experimental", then they can just set a flag in ReSpec's conf. However, right now, we are having to special case an useExperimentalStyles options using either a boolean or a year.

If we keep using a year, we are going to make "useExperimentalStyles" just default to
new Date().getFullYear() and hope for the best ... which would be sad.