This is intentional, that is "ToC" is a large thin font, lots of padding, and a sectional line divider. All other levels of subheader are dark, bold, and get gradually smaller.

I do think the weight and blackness of the subheadings can overwhelm headings a bit, for instance on the Changelog:

My eye is drawn to "2015" and "2014" much more than "Past Changes".

I don't find it confusing, but I did assume it wasn't intentional when I hit it while typing up that document.

It is a usability issue though. See for yourself: https://www.dropbox.com/s/qa2oexmuc7sobty/Screenshot%202015-04-27%2014.58.52.png?dl=0

(Here "Fix" is a subheading, "Unable to clone" is a heading.)

Either there needs to be more padding before the level 1 headings, or the relative sizes of headings and subheadings could be adjusted. Ideally the subheadings should be less bold.

Can't you choose to use a smaller header in that case? The main concern with this ticket is it's asking to change all of Remarkup, for all installs, when possible other possibilities exist. @epriestley has a more reasonable issue to fix (the section/header) view.

I think our use cases are pretty much the same, the documents are just laid out a bit differently.

@chad: It's ugly bordering on unusable in all of Remarkup, for all installs. So yes.

@gvanrossum that's a little insulting, don't you think? I'd prefer to remain productive in this conversation.

Well I felt insulted by your quick "that's a feature / there's a workaround" response. We'd have to update hundreds of wiki pages to address this. Surely there's some CSS in a central place we can tweak?

See T4213 for discussion of themes/skinning, and an explanation of why we don't expose CSS/HTML as an API.

You can tweak these rules in phui-fontkit.css (for the specialized <h1 /> tags) and remarkup.css (for standard headers), but making adjustments to the CSS or HTML requires maintaining local patches.

Haha, no, sorry, not intended and an honest response. We built the current styles around all our documentation and how those pages are laid out. We of course maybe organized this documentation in a different way then other companies may. I took more of the "Section - Header - Copy - Subheader - Copy" approach. That is, we don't generally expect a large first level header, copy, then new section.

I think the example @epriestley showed is easily resolvable, and sound like it might resolve your case as well, though I don't feel it will have the same impact. We'll likely increase space on the sections and darken that font a level, and reduce the header colors a level.

Current Changelog page Evan mentioned:

I pulled up the CSS console and swapped the font-weight and color of h2 and h3:

Then added some more padding above the h2 (that is, main) headings:

Personally, I think the second screenshot is good enough. The extra padding doesn't do too much for my eyes.

Guido: Does that work for you?
Chad: Is this a change that you would be open to considering making globally?

@jhurwitz Evan is right that the colors in our Remarkup headers are incorrect, that is they use a straight black instead of our bluetext palette. They may predate that color scheme, or be an oversight. The intention around the design of the sections is one of a soft-transition, like chapters in a book, use of large fonts, white space, soft lines. Then inside each "chapter" you get individual levels of headers. I still prefer to keep that direction and correct the colors since I find it lends to readability more.

Got it. Thanks for that explanation.

Do you have a quick mock and/or verbal description of what this section of the Changelog would look like once it correctly uses the new color palette? I don't have a good mental model of what the color scheme you're describing looks like.

Is there a task to track fixing this oversight (ie, switching Remarkup headers to use the new color palette)? If not, can we create one?

(As for the future of this task, let's discuss after doing the above. It's possible that changing palettes removes the confusion, and would allow us to close this task as a duplicate of the new-color-palette-task. Or maybe not, but we can't tell until the above questions are answered.)

@jhurwitz: both #2 and #3 are a big improvement. Others: I don't have enough context, I'll let you all sort this out from here.

Thanks @chad for the fast fix! The spacing and color look much better now.

What's the plan regarding font-weight for remarkup headers and subheaders? Is F387173 the desired font-weight, or is that planned to change in the future?

There are no firm plans for additional immediate changes. Long term, I'd like to introduce Semi-bold 600 as the "Heading" style, but adding another font file increases page weight, so I don't know when we'd pursue this. I do really like Source Sans Pro, and we've added both extended fonts and italics, and the response has been positive.

http://www.google.com/fonts#UsePlace:use/Collection:Source+Sans+Pro

As far as I can tell from looking at the CSS console, here is the status quo:

• Remarkup headers (==) get styled as <h2>s. We currently display these in Source Sans Pro, normal (400) weight.
• Remarkup subheaders (--) get styled as <h3>s. We currently display these in Source Sans Pro, bold (700) weight.

Even without introducing a new weight (the semi-bold 600), I think we can improve this right now by swapping the weights -- make h2 weight 700, and make h3 weight 400. (Then, if you introduce weight 600 in the future, you may want to change some of these.)

Does this sound like a good idea to you, @chad? Or is there a good reason (that I'm currently missing) for subheaders being more heavily-weighted than headers right now?

(I am not a CSS expert, and I fully recognize the possibility that I'm seeing headers in a different font family than you are because my browser/OS has different fonts installed. But what I am seeing is what I described above.)

There a number of reasons we pursued this direction, mostly it is grounded a few top level philosophies.

• The entire page of content must be light, easy to read, and flow visually with little impact. (Nothing should feel too eye-grabby.)
• "Sections" of content (which you call headers) should be dramatic, approachable, and visually distinctive. They should feel like mini-pages with-in the entire document (click on a link in the ToC).
• Page layout should approximate an old-school outline visually.

Flow-wise, it's important from the design perspective to look at how people use Phriction, that is how will they find what they want, and how can we make it faster. Try to sit in the users seat so to speak. Roughly, we're looking here at two common workflows. either the user is flat out reading the entire page (see point 1) or the user is reading just one section (see point 2) based on the ToC. For the third point, I just used an old school outline to provide the basis for how the page as a whole should flow.

Mostly, the concern I'd have with making sections heavy and subheaders light is that it changes the visual flow of the page. Right now there is a light, airy, feel between sections. If you're reading the whole page, you get to take a break and re-orient yourself before the next section. You're not hit over the head with it. We've decided that while this top level header is important, it's not hit you over the head important. They just need to be findable when looked for, this is the intent.

I also understand this might not be what you want from the design, or fit with how your team is using Phriction. I can only design with an intent for "vanilla Phabricator". We're going to likely just swap 700-bold for 600-semi-bold and see how that feels for documents. Beyond that, like @epriestley mentioned, you'll have to maintain local patches / CSS if you have more specific needs.

Also, if there are more 'top-level' Phriction needs, we'd be interested in hearing about those. We are interested in moving into more of a CMS direction, but we'd want to understand actual needs/use before exploring.

Thanks @chad! I just tested your changes on a local install, and I think the content looks much better now.

I don't understand - previous version looked OK, but this... Now docs in our Phriction look awesome and cool :-)