Large content sections feel spaced too much.

[michaelblyons]

I mostly feel this in the rendered ReadMe on Packages, but I think it's maybe applicable to the About page, too.

IMO things like p, h1-h6, ul, ol, pre, etc. should have no padding, and margin like 0.6em 0, except headings should be a little farther from the section above: 0.7em 0 0.5em.

[michaelblyons]

Also, nested ul and ol should have minimal vertical margin to let the <li> versus <li><p> margins to appear as desired from the Markdown author.

[braver]

The documents are set up on a vertical rhythm or grid. This pattern underpins all elements on all pages and ensures it's comfortable to read and everything stays in balance. Typically after moving various aspects of the design around for a while, balance tends to get lots making everything feel messy. Bringing it back to this grid restores order. Whether that's achieved via paddings and/or margins is besides the point. The approach I've taken here is a well known and easily understood way of building that kind of structure into a document to make it feel cohesive.

Maybe it's perhaps a bit more spacious than your average site. But that's a matter of taste. One person says there should be less space, someone else says there should be more. That's why design doesn't happen in committees. There is no right or wrong. But doing it right needs some system to keep things together, and takes time and effort beyond adding or removing a few em here or there.

Also, nested ul and ol should have minimal vertical margin to let the <li> versus <li><p> margins to appear as desired from the Markdown author.

I'm sorry, I don't know what you mean. There is a p, and then perhaps a ul, and then another p. They're spaced so that the next paragraph after the list lands exactly on the next line in the grid. I don't know what else the Markdown author may have desired, the markup does not express anything else. And the readme's here tend to look a lot like they do on Github anyway. If I look at the docs site, or docs at sublime-text.com, paragraphs and lists are also very evenly spaced. Perhaps not to a strict grid like we have here, but again: there is no right or wrong, this site just follows the design principles of this site.

So, I'm probably a bit defensive about this. But someone needs to be, you can't design without having opinions. We can deal with feedback and adjust. But if we're talking about these details of the design a comprehensive redesign needs to be proposed that can be evaluated and discussed, and a cohesive approach should be taken to these things. Because changing the foundations of the design can be done, but should not be done lightly. 90% is text and changing the typography changes everything.

In a very practical way I would also wait and see what plans SublimeHQ has with all of this. If the site moves under their umbrella it might make sense to match more of their existing design language. Not sure what their involvement will look like.

[michaelblyons]

I'm sorry, I don't know what you mean. There is a p, and then perhaps a ul, and then another p. […] I don't know what else the Markdown author may have desired, the markup does not express anything else.

This part, at least, is easy to explain:

- A
- B
    - C
- D

makes

<ul>
  <li>A</li>
  <li>B
    <ul>
      <li>C</li>
    </ul>
  </li>
  <li>D</li>
</ul>

whereas

- A

- B

    - C

- D

makes

<ul>
  <li><p>A</p></li>
  <li><p>B</p>
    <ul>
      <li><p>C</p></li>
    </ul>
  </li>
  <li><p>D</p></li>
</ul>

Leaving the margin for nested ul means that these two lists are indistinguishable:

- A
- B
    - C
- D

break

- A
- B

    - C

- D

<ul>
  <li>A</li>
  <li>B
    <ul>
      <li>C</li>
    </ul>
  </li>
  <li>D</li>
</ul>

<p>break</p>

<ul>
  <li>A</li>
  <li>B
    <ul>
      <li><p>C</p></li>
    </ul>
  </li>
  <li>D</li>
</ul>

[michaelblyons]

On your larger point, I dispute the virtue of the vertical grid. It makes sense to me for invariant font size and a requirement that all lines take the same height. In, say, the text editor we both use, a line is empty or it is not. The lined-notebook screenshot you have is cute, but it's not my preference in their absence.

I don't have design language to counter with, but I have a substantially different aesthetic taste. I want margins to collapse, leaving the largest one as controlling among any pair of vertical block elements. I want headers more tightly coupled to their following text than their leading text, and everything else should have cohesive block spacing: large enough to readily identify and small enough to minimize eye movement.

It's fine to disagree. I'm not offended, and I'm glad you have opinions!

[braver]

Thanks for explaining the paragraphs inside lists. I must say I hadn't considered those (don't see them often in the wild).

I'm also fine with the disagreement... I can definitely see your perspective. That's also a way to do it. What we have here is perhaps a little crude and simple, but that's also an aesthetic choice. It's on purpose.

Problem is what to do with the disagreement. At some point someone has to make the design work holistically across the entire project. Since, at this point, that someone is me, I'm likely to weigh my tastes and interests in working with various design techniques a little bit more than anyone else's 😄 In a very practical sense overthrowing the typography isn't high on my list of things to work on in this project.

... And on a certain level, that's what a user stylesheet are for. This thing is still part of the open web in a real way, and if you feel it must be one way or another, do it. Some browsers still have built-in support, others can use a plugin.

[kaste]

How did you produce your rhythm pic? I get

with the snippet in typography.css

EDIT: You're allowed to move that around (background-position-y). Got it!

[kaste]

What @michaelblyons referred to was mainly the README. E.g.

Here the header seems to stick more to the previous section than the following section (which there are the headings for).

GitHub:

[braver]

Hm, in some cases it also starts to drift from the grid, that's not great. It's not a big deal if blocks are offset somewhat, as long as internally they adhere to some grid (doesn't even need to be the same as the main grid), and eventually everything lines up again.

That last one (Task Format, File Organization) is a good example of where things can be improved for sure. It's acceptable if headings are slightly off the grid to be closer to their following block than the preceding block, as long as altogether everything locks back into that grid.

That's cool, I can take a stab at perfecting that a bit. There are a few other places where I think some nip-n-tuck work is in order.

🫡 Task accepted, I'm on the case.

[kaste]

You can take a look at 3b4ab7f too

New

Old