Hacker News new | past | comments | ask | show | jobs | submit login
Primer – CSS toolkit and guidelines that power GitHub (primercss.io)
256 points by hswolff on Mar 23, 2015 | hide | past | web | favorite | 86 comments

Sometimes I hate web development. Comparing the buttons (http://primercss.io/buttons/) between Chrome and Safari on my Mac, the text is a pixel further up in Chrome and thus looks slightly wonky to me.

Here's a screenshot of the two side-by-side (Chrome left, Safari right), zoomed to 500% in Photoshop with a 1px grid: http://imgur.com/dhZrxFH

This is due to a Chrome bug with how they render Helvetica. We could hack it ourselves, but it's a regression on their end and it'd just be more work for us.

Are you sure it is a bug, and not just a difference in the way the vertical spacing is calculated? Apple changed the way Helvetica's height is calculated in iOS 3.x and for a while had a "legacy font metrics" that were available for their apps, which included MobileSafari until they pulled the trigger in iOS 4.x. I have found every browser and operating system and often different versions of each to calculate these metrics differently, even for a specific given font. I talked to some people at WebKit and on Safari about this, and they absolutely do not consider it a bug.

Yup, see my comment above or below this. I'd find the tweets about it, but blah, Twitter search.

This is great to know - thank you! And keep up the good work.

Did you file a bug?

We got Paul Irish to re-open the bug after they made the change to their font rendering. It is indeed a bug and has been fixed.

Is it just me, or is expecting pixel-perfect identical rendering between different browsers a guaranteed way to set yourself up for disappointment?

If you aren't prepared to put up with differences that slight, perhaps web development isn't the right field for you. (Though I recall back in the day not being able to reliably reproduce film proofs for printing without occasional expensive differences showing up between proofs produced with Quark vs PageMaker... The more things change … )

Text is consistently better in Safari in subtle ways.

It's one of the reasons why I still use it, even though it keeps getting worse with every release (crashing tabs, DNS resolution issues and that dreadful new inspector to name a few). Such a shame, it used to be a great browser.

The real problem here is using vertical paddings.

One solution I've found to getting vertical heights the same across browsers is to use no vertical padding, and large line-heights.

Absolutely no problem with vertical padding—this particular problem is a Chrome bug.

Fair enough, I take it back :)

That being said, I have seen lots of vertical "off-by-one" issues related to trying to combine line-height, vertical-align, and padding.

Hah, yeah, nothing to rebuttal there lol. We're forever facing problems with that kind of stuff.

I use Chrome, and GitHub's button text alignment has always bugged me. I chuckled when I noticed that this CSS framework of theirs has the same issue.

I'm surprised at the lack of semantic meaning in most popular grid frameworks.

Years ago, we moved away from layout with tables because <table><tr> is a horrible way to separate presentation from content but <div class="two-thirds columns"> is just as bad.

What exactly do you mean by "semantic meaning"? Meaning to who? For what purpose?

Classes on elements exist for the purpose of styling via CSS, not for users to see or screen readers to read or googlebots to classify. So if you want your css classes to "mean something" (which is what "being semantic" is), you want them to mean something to the STYLE of your page! Hence, using class="two-thirds columns" is perfectly semantic towards the purpose of visually styling the page.

Did you have some other interpretation of "semantic" that you think should apply instead? Perhaps you mean "the structure of the content"? That's not what classes are for -- that's what the elements themselves are for. Or perhaps you mean for visually-impaired folks to be able to easily navigate the content? That's not what classes are for either -- that's what ARIA roles are for. SEO perhaps? It's possible that google uses class names for this, but that's just black magic voodoo that us mere mortals can have no knowledge about (and even if we did, it could change tomorrow).

Here's the thing about using tables for layout... the table element actually has a defined meaning in HTML... it is for tabular data. The div element however does not imply any meaning (other than "arbitrary division of the page"). So using a div here with the classes that imply meaning to the CSS is quite "semantic" in this case.

"Semantic" in the sense he's complaining about means, roughly, "what the thing is" rather than "how the thing looks". So instead of 'class="one-third column left"' you would write 'class="left-navigation"' or, if you want to be more pure 'class="category-navigation"', which acknowledges that being on the left or right is itself a presentation choice that should be controlled in CSS. Behind the scenes, of course, you can use SASS or similar to apply the styles of left, one-third width, etc, to your semantically-named class, without changing the name "category-navigation" or your markup at all.

Markup written this way is, imo, indeed more readable, maintainable, and less likely to change. Whether you agree with that or not, that's the meaning of "semantic" in CSS arguments.

The argument here is similar to the argument for writing declarative code, or, in OO, for ensuring that your objects, and their names, match natural domain concepts. The rates of change of such concepts are generally much slower than the rates of change of their concrete manifestations in views.

I respectfully / slightly disagree. The "thing" we're referring to here is a div whose sole purpose is for the grid layout.

The way I see it, that thing is a boundary for the grid. In fact, I bet if you narrow your screen, that "thing" changes the way it looks entirely and is no longer a "column" but rather stacks above or below its counterparts within the same grid "row". If you used the class "left-navigation", to me that's describing how it looks even more than saying it's a "grid column" (because the navigation won't be on the "left" on narrow screens)!

Of course your example of class="category-navigation" does not suffer from this problem, but again my point is that sure it's more "pure" from the perspective of describing the element's place in the overall structure of the page, but this is not the purpose of the 'class' attribute! The HTML5 elements are for structuring the content... but classes are hooks for styling the content. As long as the styles themselves are not intermingled within the HTML, I think it's no more or less "semantic" to use words that imply meaning to the css versus the content itself.

Finally, in my experience building tons and tons of CMS-based sites over the years, the "meaning" of the content that exists in a particular location of the page changes a lot more frequently than the visual layout of the page. So I'd argue that it's more likely (in my experience, for the kinds of sites I tend to build) that using "column" as a class name will keep its intended meaning for much longer than using something like "category-navigation" (because one day someone in marketing is going to want to put a CTA button or more social links in that spot that you originally intended to be for "category navigation").

class="two-thirds columns" enforces a strong coupling between the HTML and how it is presented.

To change how wide a column is, you change its class. To change how wide an image is, you go into the CSS. To change how wide a column's border is, you go to the CSS. Doesn't changing the class seem a little out of place?

In theoretical terms, the class is semantically the category to which the component belongs. a <section class="cart"> is perfectly reasonable, whereas <div class="two-thirds columns"> is not. The <div> and it's children are not tied to the notion of how wide the div is. The fact that a section has class "cart" is important in understanding it's children.

I don't see how class="two-thirds columns" enforces coupling any stronger than using a different class name... what if that div only exists for the purposes of the grid layout? As long as the styles themselves are in CSS, how is it any different? I mean, of course if you just arbitrarily named the class with gibberish, that's no good -- but the point I'm trying to make is that the CSS classes exist to impart meaning to the designer (or the developer), not the end-user and not the screen readers and not search engine crawlers... so "two-thirds columns" is perfectly semantic because it is giving meaning to that div whose entire purpose in life is to be a two-thirds column in wide-screen view :)

I totally understand your point, and I'm kind of being obtuse for the sake of argument... but I do think the term "semantic" is thrown around without people really thinking about "semantic for whom" or "towards what purpose".

> what if that div only exists for the purposes of the grid layout?

Those things aren't supposed to exist. HTML is supposed to look like:

    <div class="blogpost><h1> ...
    <div id="mainmenu"> ...
We never got enough power in CSS to actually do that, and current frameworks are a return to the table based layout of the 90s where structure of the layout (not structure of the content) is stored in the HTML.

If semantic in terms of HTML is ever thrown around meaning anything but description of the content, it is used wrong.

The question about "semantic for what purpose" is moot when talking about HTML. It is semantic towards what information the content conveys.

"Semantic HTML is the use of HTML markup to reinforce the semantics, or meaning, of the information in webpages rather than merely to define its presentation or look."


The question of whether that is feasible to do with current technology is completely different, but it is too late to try and redefine semantic HTML.

Okay, let's say instead of calling those classes "columns", we instead call them "item". (I do this with my own "semantic grids" -- instead of "row" and "column", I use the terms "group" and "item", because on narrow screens the columns aren't actually columns). It seems to me that I could use a div to group content together in this way and it then is used to describe the structure of the content (which things are grouped together).

Everything is so loosey-goosey with HTML. HTML5 sectioning elements are a huge clusterfuck, no browsers utilize the document outline and screen readers primarily rely on ARIA roles. Google uses black magic to figure out what documents mean... so the "html can only contain information that defines the content" ship has sailed. You need to have divs in your html to achieve certain layouts. As long as those divs need to be there to serve that purpose, why not use class names that are related to the purpose you're using them for?

This is very different from table-based layouts. The <table> element does have a defined meaning! But div's do not... so using divs and styling them with CSS achieves proper separation of concerns. The label you use to describe them only has meaning to you (the designer/developer).

> You need to have divs in your html to achieve certain layouts.

I'm not saying that semantic HTML is working today. But just because it isn't working doesn't mean we should start calling what is working for semantic HTML.

Reminds me of @hsivonen's wonderful "HOWTO Spot a Wannabe Web Standards Advocate": https://hsivonen.fi/wannabe/

Edit: Curious why this is being downvoted. Is humor (intelligent humor in this case IMO) really that frowned upon at HN? Or did someone think I was calling the parent commenter a "Wannabe Web Standards Advocate"? (I certainly wasn't. Quite the opposite.)

Nicolas Gallagher wrote a pretty thorough rebuttal to this popular idea (at least popular in comment sections, as you note none of the frameworks that have taken the web by storm recently pay any attention to it).



"When you choose to author HTML and CSS in a way that seeks to reduce the amount of time you spend writing and editing CSS, it involves accepting that you must instead spend more time changing HTML classes on elements if you want to change their styles. This turns out to be fairly practical, both for front-end and back-end developers – anyone can rearrange pre-built “lego blocks”; it turns out that no one can perform CSS-alchemy."

I share your frustration, but a general purpose css framework can't really avoid using this approach to support layout. What possible alternative semantic classes could they use that would provide the level of flexibility they're catering for?

It's very doable, but Sass or similar is necessary.

For example: http://neat.bourbon.io/

This is just absurd:

    div#alpha {
      @include span-columns(1);

    div#beta {
      @include span-columns(11);

    div#gamma {
      @include span-columns(2);

How is this any better than col-xs-2, col-xs-4, etc.? I see absolutely no reason to obsess over semantic markup anymore. We all have work to do and grid frameworks help us actually get things done.

In this way the HTML is static and when you have to change a presentation detail (like the width of the columns) you just have to edit the CSS - as it's meant to be.

Until you have a ton of automated tests. Then a markup (class) change breaks all the selectors used in the tests - not fun. I prefer to abstract the styling so I don't have to fix the tests if the styling needs to change.

An HTML element can have both a class and an ID or multiple classes. Your tests should not have any knowledge of your framework's classes.

So your saying that tests should always rely only on the id attribute? Tell me how you target elements that have id attributes auto-generated by a framework either on the front end, Ember for instance, or the back end?

It's a nice idea, but falls over pretty spectacularly in the real world when you have a complicated web application.

Read my comment again. You can select elements using whatever CSS/XPATH selectors you want. Whether those elements have additional presentational CSS classes on them is completely irrelevant since the selectors will still work.

Thanks for the link. I know that Bootstrap can be used in a similar way (in theory, I haven't tried it myself) but this just seems much lighter and focused on that specific use-case rather than "also you can use it like this" in Bootstrap.

AFAIK you shouldn't get this problem if you use the sass/less sources of these frameworks directly.

But I didn't find any good tutorials on this.

Also, I don't know how this should change the html-elements needed by stuff like the bootstrap components.

No tutorial needed.

1. Create your HTML using only semantics. If you're tempting to create a class called, say, "column" or "left-container", stop yourself. If you have multiple items that will be presented the same way, give them the same class. For a shopping site, for example, a class might be "product".

2. Use a CSS preprocessor to inherit non-semantic classes from your framework of choice into the classes you created in step 1. You might use the framework's classes as they are or modify them a little.

(didn't down-vote)

This may work for simple cases. But what about stuff like the Bootstrap components, which consist of many HTML-elements?

You have two options.

A. You can compose components the same way Bootstrap does, but using semantic classes. For example, if Bootstrap is using "thumbnail-container", you could call your class "product-thumb-container". Because of the way HTML works, container classes are often necessary, and they can be semantic. Think about a legal document: at the end of them, you have appendices. An appendix is like a container: it's factored into the overall structure, but it also has a semantic value. You can't move an appendix somewhere else and still call it an appendix.

B. You can use only the parts of Bootstrap that you want, so you could leave components out altogether. As mentioned above, this might be a better option for a larger project with fine-grained, custom designs.

If you're going this route, then you wouldn't use Bootstrap. You'd dreg up your own semantic/non-semantic styles from scratch.

This works really well on projects that have a dedicated design team.

This sounds interesting, but I definitely need a tutorial for step 2.

Just look up the syntax for extending classes for the preprocessor of your choice. This is such an important part of the preprocessors that it'll usually be on the landing page for the documentation (sometimes above the fold).

I'd recommend SCSS if you're just getting started.

I got tired of using CSS frameworks where classes are used to define widths. Now, I much prefer frameworks that support semantic style like Susy.


If you use SCSS or LESS, you can inherit the widths into semantic classes. So Bootstrap can be as semantic as you want it to be.

Just be sure to use @include and not @extend, otherwise you'll wind up blowing through your allowed selector ration and wind up wonky css bugs that you will never be able to resolve without re-writing everything.

Its not as bad because table had another meaning that was being abused because there was nothing else. That's not the case for grids. Also grids are presentation, not semantic.

Agree, I really like this one http://semantic.gs/

> Primer is the basecoat...

That's an interesting confusion within the analogy.

"Primer is the primer" is accurate but unclear. I wonder if most people even know what primer is, especially considering most paints are now supposedly "self-priming".

They seem to have missed the opportunity for a great pun here.

@mdo is one of the maintainers. Is this a spiritual successor to Bootstrap?

From the blog post: "Primer isn’t another large front-end framework, though. It’s rather limited in functionality and isn’t intended to replace something like Bootstrap. It will always be GitHub’s internal toolkit first, designed to help build GitHubby things. That said, we love to share."

That was kinda my take away, too. It's pretty minimalist overall.

It looks to be pretty tied to git terms:


Indeed. From the announcement blog post: "It will always be GitHub’s internal toolkit first, designed to help build GitHubby things. That said, we love to share." [1]

[1]: http://markdotto.com/2015/03/23/introducing-primer/

I like it, as it's much more semantically oriented than Bootstrap. But why do the buttons still need the "BTN class?

mdo mentions this in his recent talk: http://jqueryuk.com/2015/videos.php?s=mdo-ular-css

tl;dr; It makes for cleaner grep results.

Without having watched the video, that sounds like a weak justification at best. I'm sure best practises could be ignored in many scenarios with the effect of slightly more greppable source, but that would normally be counterproductive. I guess we need better command-line search tools, really, ones that understand the structure of the file they're inspecting beyond a line-by-line representation.

That is one of the reasons—you can view the slides also at https://speakerdeck.com/mdo/at-mdo-ular-css if you don't want to watch the video.

I like to use prefixes and base classes. It's faster for browsers to paint, leads to fewer rules overall, reduces selectors, and helps prevent unnecessary overrides.

My aesthetic senses have always led me to a preference for button {} over .btn {}, class="foo bar" over class="foo-bar", etc. But I realise I'm in the minority and I need to get pragmatic. The slides have convinced me to check out the video tomorrow, which will be a start.

codeguide.co also looks well worth checking out. At the risk of derailing the conversation further, what's the reason for leaving a trailing slash out of self-closing elements? I recognise it's optional, but including it gives you the option of XML-parsing your HTML; is there a non-aesthetic advantage?

I think the "Pixels vs ems" was a bit short. Anyone?http://primercss.io/guidelines/

Yeah, I thought rems were the new thing?

All of GitHub is basically in pixels, save for our Markdown styles—for easy modification across devices, we use `em`s. It'd be a huge project to update that to `rem`s anytime soon.

If you'd make it from scratch today, what technique would you use? html {font-size:62.5% } with REM?

Set an HTML font-size—likely 16px—and use body { font-size: 1rem; }. Allows for easy media query scaling of type.

why would i want a css toolkit from a site that can't even show usable scroll bars in a text area?

it is simply impossible to see diffs with slightly longer lines without scrolling all the way to the bottom of the page, away from the line you want to read, so you can reach the horizontal scroll bar.


hold middle mouse button, drag

Say what?

i take you don't use github for code review...

I loved the tooltips implementation. I'd like to grab just that.

What did you love? I was checking it and the text seems strangely positioned on OSX.

Love this. What other companies have released their CSS/HTML guidelines?

I much prefer to read guidelines like this, than using a full framework.

It's not down to the code style level, but Atlassian has the Atlassian Design Guidelines (ADG) and Atlassian UI (AUI).

ADG is the general patterns and UX stuff, AUI is a UI library which covers both CSS and JS components and implements the patterns in the ADG.

ADG: https://design.atlassian.com/latest/ AUI: https://docs.atlassian.com/aui/latest/

I'm looking forward to seeing their GFM styles... that's probably the most compelling to me.

Why do I have to put 3 divs in order to make work the grid?

How else would you do it (assuming you wanted to use floats)?

Terrific and very useful.

This just seems kinda boring - visually and technically. Do we really need another CSS toolkit with an almost replicated feature set.

Every year, I think github is going to somehow release a long awaited product that blows me away with all the talent they have. Every year, I'm surprised at how little they change, and how all the opportunities that seem obvious slip to the wayside.

Might be boring to you, but it isn't to us. This is (part of) our job :).

When I stopped to think about it, there was honestly no reason to not open source Primer. If the goal of open source is the share and learn and improve, then what does it matter what we release? Especially as open source?

Not to piss on the pie BUT: The GitHub CSS breaks when one sets a minimum font-size (as required for high DPI screens). Heck every web page based on bootstrap or most "modern" CSS frameworks breaks the same way.

How about you "CSS experts" get your shit together and start respecting the fucking standard. Assuming being able to force a font size (other than relative) is UNPORTABLE. It always has been and (hopefully) it WILL ALWAYS BE. I am NO GOD DAMN DESIGNER. I just know CSS because its fucking 2015. I knew this bug since fucking 2010. Only because I fucking PLAYED WITH CSS.

Why is that the GitHub (successful company, right?) CSS team makes mistakes I stopped making when I was in high school and CSS based layouts were a new thing?

Now wait for it: "But minimum font size is not a default setting in any browser. You're less than 1% of out userbase. We don't care."

/end unforgivable vulgar rant. No harm intended. Consider it comedy. But seriously: CSS people are so wrong right now. I should be the pope of web design and I don't even care about it.

mdo: It's not your fault. I am barking at the wrong tree. In fact there are more pressing issues I have that GitHub ignores. It just vulcanoed out of me. If you have any influence in the CSS scene, please try to address this common mistake.

Would you mind elaborating on what you mean by minimum font-size? You've got me curious.

At first glance I'd assume the idea is that a browser can choose to ignore author stylesheet font sizes if they are smaller than a certain size, ensuring text is always a minimum size of say, 16px. This is in contrast to approaches that vary the text size consistently -- either by scaling text alone to larger, constant sizes, or by using a "zoom" property. I can imagine that without JavaScript, a minimum font size would be harder to support and still maintain compatibility. This is why for most retina screen use cases, scaling is employed instead of font-size changes.

Getting back to minimum font size, I assume the point is that we shouldn't use em or rem to base our designs solely on font sizes, but instead on a combination of those and percentage-based units. Also, I imagine all layouts must "flow" to accommodate larger font sizes. Really, the biggest issue is that every browser and device supports "zoom" for text in different ways -- look at Android, for example -- and it's hard enough accommodating screen readers and multiple platforms to then take into account how browsers can change the page. To some extent, it's like complaining that your websites don't fit on my 800x600 CRT unless I make the text really tiny. Yes, it's a legitimate complaint, but maybe there's another browser out there or extension that can handle it -- e.g. "Readability" or Safari and how it can pull body text from a page. Or the ability to "zoom in" on sections of a page, e.g. with a magnifier.

It's a common(?) browser setting. E.g. in Firefox go to "Preferences > Content > Font & Colors / Advanced". It's useful for preventing websites from forcing font sizes that are too small for your display (e.g. in my case a 14" Full-HD panel).

Ideally no website would (1) change the base font size or (2) set fonts below 0.8em of base font size. Unless it intentionally wants unreadable text.

Alternatively I believe there are some high dpi related settings coming into the browsers to adjust the global "pixel size". That would "solve" the problem but really we shouldn't have been in this situation in the first place. Setting a pixel font size is just a stupid idea, obviously.

Sorry for the rant, you're completely right.

With this, the updated rankings are in:

new JavaScript frameworks this month: 24

new CSS frameworks this month: 21

Will front-end developers be able to catch up to JavaScript's score or is it going to be the third month in row JavaScript gets more frameworks out there than CSS? With less than 10 days left on the clock, avid front-enders will have to give everything they have to release at least 3 more frameworks. And as you know, unless it is a MAJOR update according to the semver standard, current framework updates don't count!

.satire {}

The number of frameworks of any kind has no bearing on the willingness of more people to share their knowledge and experience with the open source community. I'd write 10 more CSS frameworks if it helped just one more person make something they loved on the web.

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact