Spec Styling Effort

Requirements & Feedback

Christoph Päper

Loretta Guarino Reid

Speaking of all the contrast issues, can we please ensure that the new style meets WCAG 2.0 AA? I haven't yet done an analysis, but this should be a requirement.

Martin J. Dürst

1) As many others have said, don't force me to read with a fixed width. There are definitely legibility issues with too wide (or too small, for that matter) columns, but they depend on many different variables (e.g. reading habits, familiarity with the matter, complexity of the text, whether the language or script is 'native' or not,…). And they may be overridden by other issues (side-by-side comparisons, efficient use of paper (or screen real-estate; not everybody has big screens). For print, a single decision has to be made. There is NO need for such a decision for the Web, so please don't force it on us. [Side comment: I'm involved in a large updating project for the Web site of my university. I tried hard to get them to do a 'fluid' design that would work well on a large variety of devices. Unfortunately, it was a lost cause; run-of-the-mill Web 'professionals' still think in paper despite more than 20 years of the Web. Please let at least W3C provide some good examples, rather than stay stuck in the paper age.]

2) It seems nobody noticed, but please use the full brightness gammut of the display device. I don't understand why displaying body text in dark gray (#2f2f2f) would make the text any more readable, in particular when there is lots of ambient light. To me the whole thing looks like the ink was running out. Headings,… are even lighter (#4f4f4f).

3) That then would allow to make the examples a bit darker, too. It's good to use a somewhat lighter tone for the examples, that automatically enforces the message that they are not normative parts of the spec, but as they are currently, I get tired reading them.

4) The bold font in the examples is way too bold in Safari. For whatever reason, it looks much less bold (and better) in all four other browsers I checked.

5) The light blue color for the links is too light (see above) and therefore not very readable, too eye-catching to detract from reading the text, and too 'cute' for a spec. Most of these points also apply in the other cases where light blue is used.

6) Good typography is a lot about messaging. The new style, to me at least, seems to aim for a message of high quality, but is too much slanted towards high quality poetry and not enough towards high quality engineering. I wonder to what extent messages such as “this is about precision” or “I'm the spec, you aren't going to mess with me” were part of the (maybe implicit) design brief for the redesign? With the current design, it may be easier to catch the eye of a Web designer, but do we think that this design is appropriate for specs e.g. about Web Services?

Robin Berjon

  • I won't repeat what others have already said, except to say that I agree on wider layout and better contrast.
  • I like the overall new ToC layout. I would recommend testing it out with at least two-three extra depth levels since those do indeed occur once in a while. I also think that sections at the end that have no number should be lettered as appendices.
  • It is confusing to have the same colour for <code> and links — I actually tried to click on a code piece.
  • Issues text should definitely not be light grey — issues are important! As they stand, I find them hard to read and I'm (relatively) young with 20/20 eyesight. It would be good to test the style with issue titles as some specs use them (e.g. “Issue 1: Light grey unicorns are hard to spot in the winter”). I like the issue floating as an aside, maybe that should be the default, with an option to expand?
  • It would be good to try out a style similar to that of issues but for Notes. Some specs also use a related style for Best Practices.
  • I find the first code example really hard to read. I think that they should be called out more clearly with an “Example” header (not in light grey and light grey lines), followed by an optional example title. A lot of specifications nowadays also use syntax highlighting — it would certainly be useful to have a common style for those (I can provide examples).
  • In the same vein, a style for figures (which may be numbered and may have a ToF as an appendix) that is somehow consistent with the style for examples probably makes sense.
  • I would expect a clickable link on the W3C logo at the top left.
  • It would be good to test the style for <dfn> in text body and not just in property definition tables. A lot of specs also have specific styles for links to definitions.
  • A lot of specs now use highlighting, links, etc. for WebIDL snippets. That would be good to have some agreement on as well. Yes, I know that it's a lot of style :) This is just an example, and it does not necessarily carry consensus, but for IDL segments themselves you can look at any API spec that uses ReSpec (which is a large number of them). An example is http://www.w3.org/TR/contacts-api/. It does not necessarily exercise all the styles — I could probably construct a document that does.

Dave Raggett on contrast


The light blue color used for links is in my opinion too low a contrast against the white page background, and some people (myself included) will find the links hard to read. You may want to look at the WAI authoring accessibility guidelines for recommendations on colors and contrasts.

Richard Ishida on content width

Please don't force me to work with a fixed width of text - please make it a % of the window width so that I can widen by stretching the window if I want.

Although I do normally like a narrowish column for on-screen reading, there are circumstances where I want to see more content at a time, and I'd like to be able to do that by controlling, myself, how much of the content i see. Stretching the window allows me to do that.

The same goes for situations where I may want to compare multiple windows on a screen - the fixed width of this column loses information on the right side if I make my window too narrow.

Richard Ishida on Print

In addition, please provide an option to print specs without such narrow columns. This is to save on paper. I often print out specs to review them for i18n issues. It already takes up a lot of paper, and if this fixed column width is forced on me for printing, I will probably use up twice as much.

Karl Dubost

  • Adjustable line width for very small screen would be nice (Mediaqueries maybe)
  • “i like 100% width… then i resize my browser width to a decent size for me” (colleague comment)
  • Property table hard to read at the bottom. Need better style. The values seem to be floating.
  • Guidelines for schematic graphs would be a nice touch to add, so there is consistency between specs
  • Use of same color for links and code is a bit confusing.
  • I would add more space in between paragraphs but that might be me only :) difficult to breathe.

Daniel Glazman on body width

In the body of Vincent's spec, I suppose one given element, let's say #main, has a fixed size through a width or max-width property. Something like

 #main {
   max-width: 50em;

Just tweak that to

 #main:target {
   max-width: 50em;

and your document can have two different renderings for the regular URL without fragment id and the one with #main fragment id.

 index.html      will be viweport-wide
 index.html#main will be 50em-wide
ideas/spec-styling.txt · Last modified: 2014/12/09 15:48 (external edit)
Recent changes RSS feed Valid XHTML 1.0 Valid CSS Driven by DokuWiki