@mdo

Working with MDX in Next.js

2024-06-03T00:00:00+00:00

Several weeks ago, I completely redesigned, rewrote, and re-engineered the Pierre Docs. What originally started as a few Notion pages had already turned into a set of low-key static pages on our logged out site, but after a slew of awesome product updates, our very manual setup was severely lacking and we simply needed more docs.

The homepage for the new Pierre Documentation.

I needed an easy way to write and maintain dozens of new pages of documentation. I had just recently redone the Pierre Changelog from a similar manual setup to use MDX and dynamic routes in Next.js, and I wanted to do the same for our docs, too.

Learning new things

There’s a ton about Next.js and React that I didn’t fully know heading into this, so it took me a bit to get up to speed on a few concepts. I’m reiterating them here for my own memory and reference, but at the same time, I want to help others who might be in a similar spot. There’s no shortage of advice and posts out there, but none felt like they explained things in a helpful way for me.

Okay, so here’s a few things I needed to learn or remind myself heading into this project.

Files or folders with brackets in their names like [slug] or [slug].js are dynamic route segments. These allow you to group files and folders of related content while generating routes for your content. In short, you can render any number of MDX pages using this page as a template.
There’s also a special catch-all version of dynamic routes that works across nested folders by prefacing your dynamic segment with .... In my case with the Pierre docs, app/src/docs/[...slug]/page.tsx is the dynamic segment that allows us to render any docs MDX page, no matter the subfolder.
The generateStaticParams function works with dynamic routes to generate each static page. This function is used within those dynamic segments, and when it’s told where to look for say a bunch of MDX files in our app/src/docs/content/ directory, it will loop over those to statically generate each page. Neat!

Now there’s also some stuff I already knew that bears repeating:

MDX is a format that lets you write JSX in your Markdown documents. You can create and extend React components that can be used alongside Markdown content. Super nice for our alerts, buttons, and icons.
Grouping and ordering MDX files still seems like a pain in the ass, and what I mean by that is specifically around generating our docs side navigation. Our best approach here was generate the folders of static pages and use a separate JSON object to order and generate the nav.
There are so many ways to manage MDX, and most of them require the use of plugins to get all the functionality you really want. No issue here, but it’s worth noting that I ended up using next-mdx-remote, some Rehype plugins, and some Remark plugins. All told, it’s been great for me.

Okay with that stuff out of the way, let’s get to the good stuff—how I built the Pierre Docs using MDX and Next.js.

Implementation goals

Right before doing the Pierre docs, I had just redone the Pierre Changelog. The first iteration of it was a single page where individual entries were separate component imports and you’d link to entries with a URL hash.

It looked like this:

<div className={styles.list}>
  <GithubMirror />
  <BranchSummaries />
  <MultiplayerEditor />
  <Mentions />
  <BlendedDiffs />
  ...
</div>

It worked for a bit, but it obviously wouldn’t go anywhere as we grow and ship more. It was already annoying after a handful of posts. What I worked up for the second iteration of the Changelog though was built for a single, flat directory. That wouldn’t suffice here.

Plus, I had some specific goals in mind for what I’d need to build.

Must support dozens of pages
Must support any number of nested directories
Must be easy to contribute to by anyone on the team
Eventually, must be abstracted to easily scale to other content directories

Okay, so with that in mind, I set out to get some help and start building.

Setting up the file structure

Our Next.js app has (what seems to me like) a fairly straightforward setup. For content that doesn’t require signing in, we use some middleware to render our logged out and marketing pages. The rough structure looks a bit like this:

pierre/
├── src/
│   ├── app/
│   │   ├── (authenticated)/
│   │   ├── changelog/
│   │   ├── docs/
│   │   ├── og/
│   │   ├── signin/
│   │   └── ...
│   ├── components/
│   ├── lib/
│   ├── primitives/
│   └── ...
├── next.config.mjs
├── package-lock.json
├── package.json
└── ...

Looking inside the docs folder, here’s what we’re working with:

docs/
├── [...slug]/
│   └── page.tsx
├── components/
├── content/
├── layout.tsx
├── page.module.css
└── page.tsx

The local (to the docs source) content folder is where we put all our MDX files. The page.tsx file is the main component that renders the MDX content, and the [...slug] folder is where we generate all our static pages using those fancy dynamic routes.

You could put your content elsewhere, but in the interest of limiting scope and ensuring easy access, I kept it simple and put it all in Git as local MDX files. Eventually I could see us looking into some external CMS.

Rendering MDX

Now that we have our files in place, we can start figuring out how to render the MDX into static HTML. The [...slug]/page.tsx file is where we fetch and render the local MDX content. We use the generateStaticParams function within to generate our static pages with next-mdx-remote.

// app/src/docs/[...slug]/page.tsx

import fs from "node:fs";
import path from "node:path";

export const runtime = "nodejs";
export const dynamic = "force-static";

const contentSource = "src/app/docs/content";

export function generateStaticParams() {
  // Recursively fetech all files in the content directory
	const targets = fs.readdirSync(path.join(process.cwd(), contentSource), {
		recursive: true,
	});

  // Declare an empty array to store the files
	const files = [];

	for (const target of targets) {
    // If the target is a directory, skip it, otherwise add it to the files array
		if (
			fs
				.lstatSync(
					path.join(process.cwd(), contentSource, target.toString()),
				)
				.isDirectory()
		) {
			continue;
		}

    // Built the files array
		files.push(target);
	}

  // Return the files array with the slug (filename without extension)
	return files.map((file) => ({
		slug: file.toString().replace(".mdx", "").split("/"),
	}));
}

Some more things to note here that I learned along the way:

There are apparently two ways to work with this kind of stuff in Next.js—called runtimes—and that’s using Node or using the edge. Node is what we want since we’re statically rendering this content. The runtime and node related imports are all in support of that. Update: nodejs is the default, so we don’t need to declare this here. Leaving it in for posterity.
Since we want these rendered HTML pages to be static, we can force that behavior in the Next.js app directory by setting dynamic to force-static. Since we’re using generateStaticParams, this is also optional, but it’s always good to be explicit.
Getting that list of targets in the source directory will include sub-directories alongside files, so we need to filter those out. That’s what the isDirectory check handles.

The final piece of that function is to push all the files into an array and return them with the slug. We’ll use this later to help generate the pages by their slug.

Okay, now onto rendering the page! To do that, we need to build a default function for the page.tsx file that takes the information from the magical generateStaticParams function and renders the MDX content.

// Continuing in app/src/docs/[...slug]/page.tsx

// Add new imports
import { useMDXComponents } from "@/mdx-components";
import { compileMDX } from "next-mdx-remote/rsc";
import rehypeHighlight from "rehype-highlight";
import rehypeSlug from "rehype-slug";
import remarkGfm from "remark-gfm";


interface Params {
	params: {
		slug: string[];
	};
}

export default async function DocsPage({ params }: Params) {
	// Read the MDX file from the content source direectory
	const source = fs.readFileSync(
		path.join(process.cwd(), contentSource, params.slug.join("/")) + ".mdx",
		"utf8",
	);

	// MDX accepts a list of React components
	const components = useMDXComponents({});

	// We compile the MDX content with the frontmatter, components, and plugins
	const { content, frontmatter } = await compileMDX({
		source,
		options: {
			mdxOptions: {
				rehypePlugins: [rehypeHighlight, rehypeSlug],
				remarkPlugins: [remarkGfm],
			},
			parseFrontmatter: true,
		},
		components,
	});

	// (Optional) Set some easy variables to assign types, because TypeScript
	const pageTitle = frontmatter.title as string;
	const pageDescription = frontmatter.description as string;

	// Render the page
	return (
		<>
			<h1 className={styles.pageTitle}>{pageTitle}</h1>
			<p>{pageDescription}</p>
			<div className={`${mdStyles.renderedMarkdown} ${styles.docsBody}`}>
				{content}
			</div>
		</>
	);
}

Okay so let’s walk through a few things…

We’re importing a few new things—the useMDXComponents function and a few plugins for our MDX content. We’re also importing the compileMDX function from next-mdx-remote/rsc to render the MDX content.

Here’s a simplified version of the src/mdx-components.ts file:

// src/mdx-components.ts

import type { MDXComponents } from "mdx/types";
import Image, { ImageProps } from "next/image";
// other imports...

export function useMDXComponents(components: MDXComponents): MDXComponents {
	return {
		a: ({ children, href }) => (
			<a href={href} className="styledLink">
				{children}
			</a>
		),
		hr: (props: React.ComponentProps<typeof Divider>) => (
			<Divider
				style=
				{...props}
			/>
		),
		img: (props) => (
			<Image
				style=
				{...(props as ImageProps)}
			/>
		),
		// etc
		...components,
	};
}

If you’re new to using MDX components, this basically let’s you override default HTML elements rendered by MDX and make your own components available to use in .mdx files. For example, in the above snippet we change all default anchor elements to have the class styledLink. We also override the default horizontal rule to use our Divider component.

Back to the rest of the page…

Our components and the MDX plugins that we want are passed to the compileMDX function to render the content. Those are straightforward, so I won’t get into them. We also parse the frontmatter from the MDX file to get the page title and description. We also use fetch a few other things from our page frontmatter—icon, color, OG image, etc—but we won’t get into that here. Lastly, we put it all together at the end in the return to build the page’s HTML.

For the Markdown styling, we have a stylesheet that we made for our file explorer when we added rendered Markdown support. That’s the mdStyles.renderedMarkdown part. There wasn’t much to tweak here either since everything else fell into customizing MDX components.

From here, we have MDX pages that can be dynamically rendered at any level of the source directory, with easy frontmatter access and custom components, plus a set of functions that can be easily extended into other areas of the site.

Sidenav

One bummer about directories of Markdown/MDX has always been building navigation for those pages—seemingly no matter the framework or language. Setting the order, adding icons, controlling states—woof. We could use fs to read from the directory and build a nav ourselves, but how would we order a dynamic set of pages within each sub-directory? Frontmatter could maybe help, but then you’re stuck updating values across multiple pages.

The easiest solution is still building a single config file of sorts for the navigation using JSON or YML. We took that route with the docs pages—here’s a snippet of it.

// src/app/docs/Nav.tsx

export const DocsNav = [
	{
		header: "Getting Started",
		icon: "IconBook",
		color: "purple",
		items: [
			{ href: "/docs/getting-started", label: "Overview" },
			{ href: "/docs/getting-started/new", label: "Create a New Workspace" },
			{
				href: "/docs/getting-started/join",
				label: "Join an Existing Workspace",
			},
			{ href: "/docs/getting-started/import-code", label: "Import Code" },
			{ href: "/docs/getting-started/ssh", label: "Setup SSH" },
		],
	},
	{
		header: "Workspaces",
		icon: "IconBuilding",
		color: "blue",
		items: [
			{ href: "/docs/workspaces", label: "Overview" },
			{ href: "/docs/workspaces/navigation", label: "Navigation" },
			{ href: "/docs/workspaces/members", label: "Members" },
			{ href: "/docs/workspaces/repositories", label: "Repositories" },
			{ href: "/docs/workspaces/notifications", label: "Notifications" },
			{ href: "/docs/workspaces/presence", label: "Presence" },
			{ href: "/docs/workspaces/settings", label: "Settings" },
		],
	},
  // ...
];

Elsewhere, we use that JSON to build our sidebar as its own component that can then be rendered wherever we want in our docs layout. Here’s a look at how we built that with our own components:

import { Colors } from "@/primitives/Color";
import { Column } from "@/primitives/Layout";
import * as Icons from "@/primitives/icons";
import { createElement } from "react";
import { DocsNav } from "./Nav";
import { NavHeader } from "./NavHeader";
import { NavItem } from "./NavItem";

export const DocsMenu = () => {
	return (
		{DocsNav.map((menuItem) => (
			<NavHeader
				key={menuItem.header}
				title={menuItem.header}
				color={menuItem.color as keyof typeof Colors}
				icon={createElement(Icons[menuItem.icon as keyof typeof Icons])}
				items={menuItem.items}
			>
				<Column gap={1} style=>
					{menuItem.items.map((item) => (
						<NavItem href={item.href} key={item.label}>
							{item.label}
						</NavItem>
					))}
				</Column>
			</NavHeader>
		))}
	);
};

We used the same approach overall with our docs homepage, except we created a separate JSON blurb and map since we only wanted to show a subset of pages that we hand-selected. This gave us a bit more flexibility, but it’s also something we could maybe improve down the line as well to avoid the repetition.

Up Next: Abstraction

The last goal for me was to be able to abstract all of this so I can use it elsewhere—like on the Changelog or in the Styleguide I’ve been (very) slowly chipping away at. I’ll save that for another post as I’m still working on that part.

Suffice to say it has also felt relatively straightforward to do and I love that I’m able to get this stuff working elsewhere with ease now.

See you again for the next part!

Shipping Blended Diffs

2024-01-17T00:00:00+00:00

It’s been a whopping five years since I last shipped one of my Shipping blog posts, and boy do I have a good one to come back with. I’ve been working on Pierre for most of the last year and we’ve been shipping some amazing stuff.

Let’s talk about the latest, designing and shipping blended diffs in Pierre!

The final version of blended diffs in Pierre, complete with collapsed deletions, new modifications, and overall lighter design.

Since starting Pierre, we’ve been focused on finding ways to rethink the tools and features we’ve relied on for decades as developers. A few months ago, I decided to do a deep dive into how we can render code changes differently. Just a fun and open-ended exploration in Figma of any and all ideas that came to mind. Most of my Figma files end up looking something like this:

One of six Figma pages. I always make it a goal to generate as many artboards/frames as possible. It’s fun to see the turning point towards blended diffs in the middle of the page.

And since designing diffs and code changes is an area I’ve thought a fair amount about since first shipping split diffs at GitHub back in 2014, I was very excited to dive in.

An early mockup of a file tree table of contents, inline actions on hover, diff options, and more. None of this shipped, but maybe in a future update.

Most of my early explorations like the one above started by adding features to our diffs and reviews, which quickly started to feel like the wrong approach. Instead of adding a bunch of new or improved stuff—which, honestly, we still want to do at some point—what would happen if we started by trying to remove bits and pieces? That’s ultimately what led me to something I started calling blended diffs.

Finding a new style

Blended diffs are an all new diff style that emphasizes a file’s finished state, minimizes deletions, simplifies one-line modifications, and creates more space for context. All in an effort to decrease review time and make code changes more approachable.

The first iteration that added a new ~ indicator and blue “modified” line treatment.

This was the first iteration of a new “modified line” treatment where I treated the 1-line diff as just that, one line with an inline change. Until this point, single line changes show up as two lines of a diff, like this:

- This is the deleted line
+ This is the new line

And this started to really bother me because I spent more time looking at the two lines rather than the one-word inline change. Newer diff tools of course have added inline highlighting to help with this, but it was still the same thing at heart. So I kept pushing.

The first attempt at a blended diff with modifications and a faded deletion.

The very next iteration dropped the notion of a split or stacked diff, instead blending the changes inline with the rest of the file. See what I did there? I was still stuck on all blue here, which I quickly realized wasn’t ideal as it’s unclear if the change was a deletion or an addition. Several iterations later, I landed on a balance of those blue modified indicators and green or red inline treatments.

All one-line modifications have blue line numbers and ~ indicators. One-line additions have a green background, while one-line deletions are indicated with a red vertical bar.

Clicking on the red bar for deletions would toggle a popover to show a regular diff.

This iteration also included the first ideas for inline summaries of deletions and hidden lines. The dream was to show the number of lines and a semantic summary of what was behind that hidden deletion. For example, 2 constants, 1 line break or 1 unused Button function. Originally this was going to be something I planned to push for down the line, but once we got into code, we switched gears on that once we got to building it.

One of the last elements of the new blended diffs was a column left of the line numbers. I really liked the idea of a left-hand column called “the gutter”. The blended diff gutter is a consistent space for context on any line—annotation markers, avatars for comments, and eventually even more. I see this scaling to more custom annotations, like todos or linters, and whatever else we can dream up.

Planning with the team

As the design iterations started feeling better and better, it felt time to get out of Figma and write down my thoughts to better articulate product direction and get some early feedback. Writing about a feature is arguably more powerful and meaningful than just designing it.

Our team likes to spike out our ideas and then gather our thoughts before we fully (or over) commit to something. We built that right into Pierre with branches—you can start writing and getting a review before pushing any code.

Product doc for blended diffs with Figma embed, motivation, goals, and more.

The biggest question sparked by the PRD was how to launch this new diff style—alongside stacked and split, in place of one, or in place of both? Adding a third diff style would be the safest. Replacing one of them would be a little risky. Replacing both would be making a bigger bet. So after some back and forth, we went big.

Blended diffs would replace both existing diff styles—making for less code to maintain, less bloat, and a more opinionated product.

Building it

After getting a clear direction set in stone between design and PRD, we started building. We went back and forth between more rounds in Figma and writing code, a process I really love when working with a product engineer. There’s no better way to fine-tune the details than to ping-pong between design and code, and designer and engineer.

Ian led the charge on building out blended diffs while I provided some frontend support. It ended up being super helpful to be dropping the old diff styles because it was significantly less code to be working around. Our stacked and split diffs naturally shared some code, so adding a third was going to be messy. Making that early bet let us move much faster.

Design-wise, we started with the inline deletion summaries on the left and intersecting the line numbers. This felt too busy once we tried using it, and leading with the number of lines instead of the summary felt like we were burying the lead. We ended up moving the summaries to the right (on desktop) and leading with our AI generated summaries. This has the effect of you noticing a subtle indicator that there’s a deletion, and then you can choose to dig in or not without it taking away too much attention.

Jacob hooked it up so that deleted lines are fed into an AI model to summarize the deletions for us on the fly (and then cached). We experimented with summarizing more parts of the diff, including every line of every file, but that ended up being less accurate and obviously slower and more expensive. We also took some time to fine-tune the spacing and style, ensuring those hidden deletions didn’t interrupt the flow of the lines of code too much.

While we were in there working on the new diff styles, we also took some time out to further minimize deleted files. Now the stuff you don’t need to see as much—like a list of deleted images—can be collapsed to save space, reduce review time, and further improve comprehension.

The same treatment also now applies to very large diffs, like package lockfiles. All minimized and tucked away until you really need to dig in. We really focused in on the idea of comprehension with blended diffs. If we could help people understand what happened faster, and remove the noise, we could make code reviews faster and more enjoyable independent of any other workflow improvements.

Building like this took longer than expected given the holidays, but the extra bake time really helped us hone details around style, interaction, and performance as we continued to use it internally. It also helped a ton that we have super easy and Pierre-native comments for our Vercel branch deploys—the engineers could just screenshot a visual bug for me and it’d show up for me in the branch to fix.

I can’t say it enough times—product designers and product engineers pairing from design to code is absolutely essential to great products. I’m super proud and thankful to be working with this team and building something like Pierre.

A diff canvas

There are like a dozen more ideas we landed on while working on blended diffs, but I don’t want to tip our hat too much before we’re ready. We’re very committed to changing how product engineers work, and diffs are just one piece of that. We truly believe these new diffs are a blank canvas for us to keep building on.

Keep an eye on the Pierre Changelog and join our community Discord to get access to our private alpha.

macOS web apps

2023-10-01T00:00:00+00:00

With the release of macOS Sonoma and Safari 17.0 earlier this week, we can now add web apps to the dock. Here’s a brief rundown of my experience testing them and customizing how Pierre appears when added to the dock.

A look at Pierre’s file explorer when using the new dockable web apps in macOS Sonoma.

Adding to the dock

First, a brief intro how to add to the dock. Click the Share icon and select Add to dock, or choose File > Add to Dock… from the menu bar.

You can configure name, URL, and icon as soon as you create the web app. Additional options can be found in the web app’s Settings.

Name
URL
Icon
Show navigation controls: toggles the back and forward buttons in the title bar
Show color in the title bar: toggles macOS’s default title bar styling to matching the page background-color.

There are also some privacy settings, but that’s not relevant to the discussion around styling obviously.

Web app limitations

Web apps are very slimmed down from Safari proper.

No address bar
Can’t open the web inspector directly, but can open it in Safari and then select the web app from the menu bar (Develop > Computer Name > Web App Name)
Can’t open links in new tabs, but can open links in new windows
Can’t use Safari extensions

And some other notable behavior:

Safari copies cookies to the web app at time of creation, and then keeps them separate after that
Web apps try to keep authentication flows within the app (for example, Google auth for Pierre worked within the web app without issue)
Autofill is available for passwords and more

I’m sure there’s more, so let me know on Twitter/X if you find anything else.

Theme color

Annoyingly, these web apps don’t seem to respect any theme color value. You can see if a site has a theme color in Safari by using the Compact tab layout. Shown here is the Bootstrap homepage with the theme color applied.

Sidebar: nice to see the Open in web app banner for websites after you create them.

Compared to the same page in a new Safari web app, with the Show color in title bar option enabled. Missed opportunity.

The theme-color meta tag has no affect:

<!-- Doesn't work -->
<meta name="theme-color" content="#712cf9">

And configuring theme_color in manifest.json doesn’t work either. Setting background_color does though. Here’s Bootstrap’s current manifest file. Note that the name, icon, and start URL are all pulled from the manifest file, though.

{
  "name": "Bootstrap",
  "short_name": "Bootstrap",
  "icons": [
    {
      "src": "android-chrome-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "android-chrome-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "theme_color": "#7952b3",
  "background_color": "#7952b3",
  "display": "standalone"
}

Checking the Show color in title bar option currently seems to only pull from the <body>’s background-color, which leads to some less than ideal results? Still unclear to me.

Styling

In some situations, you’ll may want to tweak your site’s styling to better fit in with the web app itself. You can scope styles for this with a display-mode media query.

@media (display-mode: minimal-ui) {
  /* ... */
}

All the display-mode values seem to be supported:

fullscreen
standalone (no toolbar on macOS, home screen web app on iOS/iPadOS)
minimal-ui
browser (default)

So far my only real use case for this was to add a border to the top of the site to separate it from the title bar, but that’s not very reliable because there’s no media query or control for detecting the title bar or anything else (unless a user toggling that changes the display mode?). For now I’m sticking with the minimal-ui mode.

Here they are in three super simple examples. Fullscreen and standlone appear to be the same on macOS, but on iOS/iPadOS there’s a difference as mentioned above. minimal-ui seems like the most practical for apps that required page navigation, while standlone seems best for single page apps.

Anything else?

I only played with this for a day or so with Pierre, Bootstrap, and these little test apps. I’m curious what else others have learned thus far, so holler on Twitter/X. I’m also hoping to eventually dive into the notifications and badging more for Pierre and may write up some thoughts around that.

Using Bootstrap in Hugo with npm

2022-05-23T00:00:00+00:00

Up until the latest redesign of the Bootstrap documentation, our blog and Icons sites were including Bootstrap’s compiled CSS and JavaScript via CDN. This worked great overall and gave, but I found myself needing and wanting more granular control over the final production assets. In particular, I wanted the source Sass files, but just the compiled JS for now. Despite using Hugo for years now in Bootstrap’s docs, I’m a complete Hugo newbie, so I had no idea how to actually include Bootstrap with npm in a Hugo project. So I set out to fix that.

The solution I used is straightforward, but I didn’t see many clear and concise answers on it outside some forum threads: use the Hugo mounts system. So, after you create your package.json and npm i bootstrap, you setup your Hugo config to pull from the node_modules directory.

Here’s how it looks in our config.yml for the blog.

module:
  mounts:
    - source:           node_modules/bootstrap/scss
      target:           assets/scss/bootstrap
    - source:           node_modules/bootstrap/dist/js/bootstrap.min.js
      target:           assets/js/bootstrap.min.js

Now we can import Bootstrap’s styles with @import "bootstrap/{filename}"; as we’ve mounted Bootstrap’s source scss directory as part of our regular assets directory in Hugo. Here’s how the start of our stylesheet looks in the blog repo:

// src/assets/scss/style.scss

@import "bootstrap/functions";
@import "bootstrap/variables";
@import "bootstrap/maps";
@import "bootstrap/mixins";
@import "bootstrap/utilities";
@import "bootstrap/root";
@import "bootstrap/reboot";
@import "bootstrap/type";
@import "bootstrap/images";
@import "bootstrap/containers";
@import "bootstrap/grid";
@import "bootstrap/tables";
// @import "bootstrap/forms";
@import "bootstrap/buttons";
@import "bootstrap/transitions";
@import "bootstrap/dropdown";
// @import "bootstrap/button-group";
//
// ...and the rest of the Bootstrap imports

From here, you can use the Sass functions, maps, mixins, mixins, and any component you need. Read the Bootstrap Sass docs for more info. Importing the compiled CSS looks something like this:

{{- $style := resources.Get "scss/style.scss" }}
<link href="{{ $style.Permalink | relURL }}" rel="stylesheet">

On the JavaScript side, things are simpler since we’re just importing Bootstrap’s compiled and bundled JS file.

{{ $bootstrapJs := resources.Get "/js/bootstrap.min.js" }}
<script src="{{ $bootstrapJs.Permalink | relURL }}"></script>

I decided I only really wanted the source Sass files and the compiled JavaScript for now. This way my dependencies and build steps would stay quite simple. To build your own JS bundle, you’d need your own bundler or an ESM shim like es-module-shim. Skipping that saved time and energy in keeping shipping the latest design updates.

Lastly, there’s also the official Hugo module for Bootstrap’s SCSS and JS if you need it. I wanted to know how everything was working, so I went with the solution shown here instead of the module, but you should be good to go with either.

Fun with the dialog element

2022-03-16T00:00:00+00:00

There’s a new element in town and it’s the <dialog>. Support for it just landed in Safari with their newest update (v15.4) across all Apple’s devices. With that update, the <dialog> element is now supported in every evergreen browser. It’s a great step forward for frameworks and libraries looking to make better use of native behaviors, but it’s also not without its limits.

Default styles

Chrome, Safari, and Firefox all render dialogs similarly—black border, black text, white background. They’re all positioned absolutely without a predefined z-index. There’s also no default ::backdrop styling. Check out the CodePen demo.

Only minor differences in the border-width it seems.

When there’s too much content, all dialogs will have an inner scroll. This makes adding a modal header a little annoying as you’ll have to ether add position: sticky, or create some custom components within to handle the scroll.

Functionality

By default, there’s no HTML magic you can use to toggle <dialog> elements—you have to write some JavaScript to open and close them programmatically. However, you can force a <dialog> open with the open attribute, which you can see in action in my previously linked CodePen.

Here’s what else you can do with a <dialog>:

Open regular, absolutely positioned dialogs with the show() method if you don’t want a modal or backdrop
Open modal dialogs with the showModal() method to open fixed position dialogs that block other page interactions
Close dialogs with the close() method
Use Esc to close the dialog without any additional code
Style and animate the ::backdrop pseudo-element
Add a specific autofocus attribute inside the <dialog> to automatically focus on it (otherwise, the first focusable element will be focused)

Unfortunately, because the modal <dialog> backdrop is a pseudo-element, you cannot trigger JavaScript events off it. This makes it impossible to click the backdrop to dismiss the dialog. There’s likely a solution here with non-modal <dialog>s, but I haven’t implemented a smooth solution to this yet.

Regarding dialogs autofocus-ing on the first focusable element, I suggest including a dismiss button near the top. When dialogs are too long and they scroll, it will automatically jump to that focused element. That means if you only have a dismiss button or single action at the bottom of the dialog, your visitors will miss the top portion.

Suggested styling

Dialogs leave a lot to be desired with that default styling, but they are just as style-able as any other element. I put together a CodePen demo that shows some suggested styles and implements easy toggling and closing via JavaScript.

See the Pen Using the <dialog> element by Mark Otto (@emdeoh) on CodePen.

Most dialogs include an inner header element with title and dismiss button, so I’ve implemented the same into my CodePen demo. I’ve also the position: sticky style I mentioned earlier to the dialog header so that when the dialog has an inner scroll, the dialog title and dismiss button are always visible. The dismiss button here also traps that default autofocus. Lastly, the backdrop is styled with a translucent background-color and a quick little fade-in animation.

Lastly, I made it all dark mode friendly with the help of some CSS variables and the prefers-color-scheme media query.

Show and hide

On the JS side, showing and hiding the dialog is easy enough. In my demo, this is accomplished with data attributes:

data-toggle is added to any triggering element and it’s value is the specified target <dialog>
data-close is a boolean attribute that finds the nearest <dialog> to hide

Here’s the complete JS in action.

let toggler = document.querySelectorAll('[data-toggle]')
let closers = document.querySelectorAll('[data-close]')

if (toggler) {
  toggler.forEach(function (element) {
    let target = element.getAttribute("data-toggle")
    let targets = document.querySelectorAll(target)

    element.addEventListener("click", (event) => {
      targets.forEach(function (e) {
        e.showModal()
      })
    })
  })

  closers.forEach(function (element) {
    element.addEventListener("click", (event) => {
      let dialog = element.closest('dialog')
      dialog.close()
    })
  })
}

You can see it all in the demo.

Details element

Before the <dialog> support for Safari dropped this week, I was playing with the <details> element to build dropdowns and modals. It was definitely a fun and worthwhile experiment, and there’s a lot more I want to explore here around keyboard navigation and better modal styling/positioning. For now though, it’s a good comparison to the new <dialog> element and how you can create custom HTML elements.

See the Pen Modals, dropdowns, and more by Mark Otto (@emdeoh) on CodePen.

Check it out on CodePen.

Resources

MDN: The dialog element
Introducing the dialog element (in Safari/Webkit)

Horizontal scrolling nav

2022-03-10T00:00:00+00:00

Continuing with my JavaScript fun, I wanted to do an updated pass on the horizontal navs I’ve previously built for both GitHub Mobile (prior to the current responsive version and native apps) and this Bootstrap dashboard example.

The goal? Build a responsive horizontal navigation with an overflow scroll that automatically scrolls the active nav link into view. The responsive part is that the navigation links scroll horizontally—easy enough, and scales decently well across all viewports. The scrolling part and active link setting is done in JS and, thanks to work on the upcoming redesign of Bootstrap’s docs, relatively straightforward.

Here’s the final demo via CodePen.

See the Pen Scrolling nav by Mark Otto (@emdeoh) on CodePen.

Here’s a look at what’s under the hood. For the HTML, I’m using the barebones: a <nav>, <ul>, and the nav links. The <nav> is what scrolls, while the <ul> holds the links to a single line at all times.

<header>
  <h1>Demo</h1>
  <nav>
    <ul>
      <li><a href="#">Home</a></li>
      <li><a href="#">World</a></li>
      <li><a href="#">Politics</a></li>
      <li><a href="#">Business</a></li>
      <li><a href="#">Opinion</a></li>
      <li><a href="#" class="active">Tech</a></li>
      <li><a href="#">Science</a></li>
      <li><a href="#">Health</a></li>
      <li><a href="#">Sports</a></li>
      <li><a href="#">Arts</a></li>
      <li><a href="#">Books</a></li>
      <li><a href="#">Style</a></li>
      <li><a href="#">Food</a></li>
      <li><a href="#">Travel</a></li>
    </ul>
  </nav>
</header>

The CSS for the <nav> and <ul> get a little clever, though. I set a fixed height (equalling that of the computed link height) and overflow-y on the <nav> to “crop” the links within. But, that doesn’t stop the annoyance of scrollbars appearing on scroll and thus covering up the links. So, among some additional baseline styles, the <ul> has a large padding-bottom value to push any visible scrollbar out of sight. This has it’s own usability concerns—scrollbars show that something can scroll, how much content there is, etc—but there’s no elegant way to address this across all browsers and devices.

nav {
  position: relative;
  z-index: 2;
  height: 2.5rem;
  overflow-y: hidden;
  scroll-behavior: smooth;
}

ul {
  display: flex;
  flex-wrap: nowrap;
  padding-bottom: 1.5rem;
  padding-left: 0;
  margin-block: 0;
  overflow-x: auto;
  list-style: none;
  text-align: center;
  white-space: nowrap;
}

On the JavaScript side, we get started with querying for our selector, check if it exists in the page, and set some variables for the navigation links and active link.

let nav = document.querySelectorAll('nav')

if (nav) {
  let navLinks = document.querySelectorAll('nav a')
  let activeLink = document.querySelector('.active')

  //
}

Our first line of JS then is to immediately (on page load) scroll the active link into view of the containing element. In the CodePen, I set a link that should be offscreen as the .active element so anyone can see the scroll happen on page load. During my work on the Bootstrap docs, I found a helpful JS method for this, scrollIntoView.

let nav = document.querySelectorAll('nav')

if (nav) {
  let navLinks = document.querySelectorAll('nav a')
  let activeLink = document.querySelector('.active')
  activeLink.scrollIntoView({ behavior: "smooth", inline: "center" })

  //
}

The behavior tells the browser how to animate the scroll while inline tells the browser to align the scroll horizontally. (For vertical alignment, if needed, there’s the block parameter.) From here, we need to add an event listener to each nav link to set the .active class and scroll the clicked link into view. This last bit of code could be cleaned up with a scrollIntoView function to de-dupe that line, but it didn’t feel worthwhile at the moment and adds a little more JS.

let nav = document.querySelectorAll('nav')

if (nav) {
  let navLinks = document.querySelectorAll('nav a')
  let activeLink = document.querySelector('.active')
  activeLink.scrollIntoView({ behavior: "smooth", inline: "center" })

  navLinks.forEach( function(link) {
    link.addEventListener("click", (event) => {
      navLinks.forEach( function(link) {
        link.classList.remove('active')
      })
      link.classList.add('active')
      link.scrollIntoView({ behavior: "smooth", inline: "center" })
    })
  })
}

Put it all together, you have a functional side-scrolling, responsive navigation. You may not even need the .active class toggling, but it completes the demo here, so I’ve included it for the sake of completeness.

Toggling classes with JavaScript

2022-03-02T00:00:00+00:00

During my recovery I’ve made it a point to double down on improving my rather limited JavaScript skills. Courses have been helpful, but it seems that no matter the course, I do my best learning by making things myself. So I’ve been tinkering around and trying to build some new projects.

My latest experiment was to build something that allows me to toggle a class on an element with a particular id.

<button type="button" data-toggle-target="#example" data-toggle-class="blue">
  Toggle
</button>

<div id="example">
  This element will have the <code>.blue</code> class toggled on it.
</div>

The gist is that I want to use a <button> to toggle any class I want on another element of my choosing, all using data attributes so that it’s infinitely flexible and functional in any context.

Nothing big, but something I knew I wanted to demo it for the Bootstrap team so we could add a potentially new component in Bootstrap. After seeing what my original demo turned into with that pull request, I realized I had set my sights too low. Instead of toggling classes with a target with only an ID, why not specify targets by classes, attribute, or any other selector? So I rebuilt it to do just that.

Here’s the final demo via CodePen.

See the Pen Toggle anything via data-attribute by Mark Otto (@emdeoh) on CodePen.

Here’s a walk through the JavaScript I wrote.

First, we find all the elements that have the data-toggle-target attribute so we can trigger our JavaScript on them.

let toggler = document.querySelectorAll("[data-toggle-target]")

Second, we add a quick check to see if there are any matching elements with that selector. This way our JavaaScript will only run if there are any elements to actually toggle.

if (toggler) {
  //
}

From there, we use a forEach loop to execute code against every matching instance of our selector from the toggler var. Within that loop, we then access the data attributes so we can use them later.

if (toggler) {
  toggler.forEach(function (element) {
    let target = element.getAttribute("data-toggle-target")
    let targets = document.querySelectorAll(target)
    let toggleClass = element.getAttribute("data-toggle-class")

    //
  }
}

Finally, we add an event listener to eacch toggling element (aka, the button) that toggles the specified class from toggleClass.

let toggler = document.querySelectorAll("[data-toggle-target]")

if (toggler) {
  toggler.forEach(function (element) {
    let target = element.getAttribute("data-toggle-target")
    let targets = document.querySelectorAll(target)
    let toggleClass = element.getAttribute("data-toggle-class")

    element.addEventListener("click", (event) => {
      targets.forEach(function (e) {
        e.classList.toggle(toggleClass)
      })
    })
  })
}

If I had to improve things further, I’d like the trigger to be customizable to click, change (for form elements), hover, and focus. I’d also consider toggling ids and other selectors on the target element. Maybe in another post and experiment.

Diffing Sass maps

2021-09-16T00:00:00+00:00

I’ve been working on some baseline Sass tests for Bootstrap and had the need to diff two different Sass maps—the expected and the actual. Bootstrap provides thousands of default variables and several default Sass maps that are extended and reused under the premise of improved customization. What we’ve run into is some Sass limitations that forced us to make a few architectural changes.

The main problem isn’t the limitation—that once a variable or map has been used, it cannot be modified later—but rather that we weren’t testing for this enough. With that in mind, I set out to try some homegrown tests for how to compare what we expected to happen in our Ssas with what’s actually happening.

This post is a rundown of what I tried out and where I ended up. To start, let’s assume these are our two maps.

// What we want to see
$expected-colors: (
  "primary": "",
  "secondary": "",
  "success": "",
  "info": "",
  "warning": "",
  "danger": "",
  "light": "",
  "dark": "",
  "custom": ""
);

// What we're actually seeing
$colors: (
  "primary": "",
  "secondary": "",
  "success": "",
  "info": "",
  "warning": "",
  "danger": ""
);

Compare via `@debug`

Intitially I just needed to know that two maps—the expected and the actual—matched without any warning or error in the CLI. That’s easy enough with @debug and showing the map keys.

@debug "The following maps should be the same, ending with the custom key.";
@debug map.keys($expected-colors);
@debug map.keys($colors);

Which outputs the following:

Debug: The following maps should be the same, ending with the custom key.
Debug: "primary", "secondary", "success", "info", "warning", "danger", "light", "dark", "custom"
Debug: "primary", "secondary", "success", "info", "warning", "danger"

This is helpful for manually checking if something is looking right, but not the best for proactively flagging an issue mid pull request.

Adding in `@warn`

Making use of @warn—which one could configure to fail a CI build—allows us to compile the entire Sass file and output all the issues to the CLI. @error wouldn’t work for this as it’d stop the compiling at the first error.

Here I setup an actual condtion—these two maps must equal one another. If they don’t, warn me and show me the difference.

@if map.keys($colors) != map.keys($expected-colors) {
  @warn "Keys in $colors don't match expected output.";
  @debug "Expected: " + map.keys($expected-colors);
  @debug "Actual:   " + map.keys($colors);
}

Which outputs the following:

Warning: Keys in $colors don't match expected output.
  test/index.scss 31:3  root stylesheet

Debug: Expected: "primary", "secondary", "success", "info", "warning", "danger", "light", "dark", "custom"
Debug: Actual:   "primary", "secondary", "success", "info", "warning", "danger"

This is great, but I still have to manually make the comparison for what’s different between expected and actual. To improve that, I needed to diff the two maps somehow.

Creating `diff-map`

There’s no built-in map-diff or map.diff feature in Sass, so I wrote a basic function to get me close enough. This diff-map function removes the keys found in both maps and shows me what’s left over in the expected map.

@function diff-map($actual, $expected) {
  $actual-keys: map.keys($actual);
  @each $key in $actual-keys {
    $expected: map.remove($expected, $key);
  }
  @return $expected;
}

@debug diff-map($colors, $expected-colors);

Which outputs the following:

Debug: ("light": "", "dark": "", "custom": "")

Okay, now we’re getting somewhere. This doesn’t account for a situation though in which we have more keys in the output than the expected map.

Improving the function

Next I updated the function to ensure a diff happens in either direction. I added some @if/@else statements to ensure that the larger map (determined via length($map)) has it’s duplicate keys removed and we don’t end up with negative numbers. From there, we use @debug to print the number of remaining keys and list them.

This iteration of the function isn’t the prettiest, but it’s effective. Side note: there’s no real way to get a Sass map’s “name”, just it’s array of keys. Super sad.

@function diff-map($actual, $expected) {
  @if $actual == $expected {
    @debug "Maps have no differences.";
  } @else {
    @if length($actual) > length($expected) {
      $difference: length($actual) - length($expected);
      $keyword: if($difference > 1, "keys", "key");
      @debug "Actual has #{$difference} more #{$keyword} than expected.";
    } @else if length($actual) < length($expected) {
      $difference: length($expected) - length($actual);
      $keyword: if($difference > 1, "keys", "key");
      @debug "Actual has #{$difference} fewer #{$keyword} than expected.";
    }

    $actual-keys: map.keys($actual);
    @each $key in $actual-keys {
      $expected: map.remove($expected, $key);
    }
    @return $expected;
  }
}

@debug diff-map($colors, $expected-colors);

Which outputs the following:

Warning: Keys in $colors don't match expected output.
    test/index.scss 154:3  root stylesheet

test/index.scss:188 Debug: Actual has 3 fewer keys than expected.
test/index.scss:199 Debug: ("light": "", "dark": "", "custom": "")

The debug statements in the CLI tell me that there are three fewer keys than expected and succinctly lists them out.

I’m not done with this yet, but wanted to at least share what I stumbled into. Ideally this function could be improved to also account for more situations in which maps can be compared (e.g., actual and expected have unique keys).

Check it out in this pull request in the Bootstrap repo and let me know what you think!

Learning CSS with utilities

2021-08-10T00:00:00+00:00

One of the premises behind Bootstrap’s utilities is that each property: value pairing is attached to a class named after that pair—.property-value. Because of this pattern, creating and using utilities is an incredibly effective technique for learning CSS.

When I wasn’t as familiar with flexbox, the CSS-Tricks cheat sheet was indispensable, but I still found myself having to go back to it time and time again. Same with CSS Grid.

Originally added in v4 and refined in v5, Bootstrap has flexbox utilities and a flexbox-based grid to use flexbox instead of floats. With the need for a slew of new supporting utilities, I taught myself flexbox by writing out every new class we’d need.

.d-flex { display: flex; }
.flex-row { flex-direction: row; }
.flex-column { flex-direction: column; }
.justify-content-center { justify-content: center; }
.align-items-center { align-items: center; }
// etc

Writing all these out by hand for v4 gave me the muscle memory to remember specific patterns and behaviors for flexbox properties and values. It’s incredibly helpful that learning Bootstrap (and Tailwind, Rebass, Atomic, etc) is very much akin to learning CSS itself. Regardless of the tooling, you have to learn the properties and values, so why not get in the habit of writing them from the start?

Utility driven frontend isn’t going anywhere, and neither is component driven frontend. They ebb and flow, and if you can understand what’s underneath them, you’re in the best position to learn any other tools and languages.

Force pushing to different Git remotes

2021-07-27T00:00:00+00:00

My Git/GitHub workflow has continued to evolve and now makes extensive use of rebasing and squashing instead of merge commits. While this is easy for branches in projects I maintain, it’s more complicated for forks of my projects. In those cases, I need to checkout, rebase, squash, and force push a branch to a different remote with a different branch name.

Once you get your own copy of the fork’s branch locally and you’re ready to force push your rebased and/or squashed changes, here’s how you can push your changes from the terminal:

git push remoteName localBranch:remoteBranch --force

Before you push, you may need to add the fork as a new Git remote:

git remote add remoteName git:https://github.com/user/repo.git

Not familiar with force pushing, or squashing and rebasing? Consider exploring the GitHub rebase docs.

Global CSS options with custom properties

2020-05-20T09:00:00+00:00

I’ve been toying around with some ideas for how to use custom properties (aka CSS variables) for global settings in a project. The idea is to provide control to designers/developers over consistent styles across multiple components. See it in action in this CodePen, or read on for details.

With Sass, this is pretty easy:

// Global option
$enable-shadows: false;

// Mixin that consumes the shadow
@mixin box-shadow($shadow...) {
  @if $enable-shadows {
    box-shadow: $shadow;
  }
}

// Put it to use
.component {
  @include box-shadow(0 .5rem 1rem rgba(0,0,0,.1));
}

By default now, box-shadows won’t be included in your compiled CSS, unless you change $enable-shadows to true. Doing this with custom properties isn’t as difficult as you might think, though.

With custom properties, the logic is quite similar thanks to fallback values. If there’s a global --enable-shadows option present, that will take precedence over the fallback value. To enable the .component’s box-shadow, comment out or remove --enable-shadows.

// Global option
:root {
  --enable-shadows: none;
}

// Put it to use
.component {
  box-shadow: var(--enable-shadows, 0 .5rem 1rem rgba(0,0,0,.1));
}

You can also go about this in another way by specifying a global shadow variable and overriding that at the component level with a utility or a modifier class.

// Global option
:root {
  --component-shadow: 0 .5rem 1rem rgba(0,0,0,.1);
}

// Put it to use
.component {
  box-shadow: var(--component-shadow);
}
.remove-shadow {
  // Because the custom property is within this ruleset,
  // it will only remove the shadow for this class
  --component-shadow: none;
}

And with that, you have some basic control over global options in your CSS without the need for a preprocessor.

Publishing npm packages with dist tags

2020-04-01T00:00:00+00:00

Last month I published the next release of Bootstrap Icons, but I screwed up the distribution tags. Instead of publishing the latest release, I published the next release. That meant my actual latest release wasn’t going to be the version folks get when they updated or installed the package today because next is for upcoming pre-release versions. I’ve screwed this up in the past with Bootstrap proper, too, because I never fully understood them.

Until today, I didn’t even know these things were called distribution (dist) tags. TIL. And today I’m writing it down to remember it for next time.

So how do you use these things or fix problems like this? Turns out npm has you covered with some approachable docs, and you don’t need to release a new version or blow anything up in the process to fix a mistake like this.

npm has dist-tag with some various options to review, add, and remove these tags:

$ npm dist-tag add <pkg>@<version> [<tag>]
$ npm dist-tag rm <pkg> <tag>
$ npm dist-tag ls [<pkg>]

In this case, I had to remove the next dist tag and create a new latest dist tag. It looked like this:

$ npm dist-tag rm bootstrap-icons next
$ npm dist-tag add bootstrap-icons@1.0.0-alpha3 latest

And with that, all was well. If you need a primer on managing alpha or beta releases, check out this Medium article.

Faster rebasing with git reset

2020-03-24T00:00:00+00:00

Lately I’ve been needing to rebase and squash my commits more frequently. I’ve always been averse to doing anything like this because I’ve basically always screwed it up when using the command line. But thanks to this pro-tip I stumbled on, rewriting commits on an existing branch and PR has never been easier.

Rather than do the git rebase -i dance, this approach resets your changes so you can selectively add what you need and write new commits. So much more approachable to me with my Git experience.

Here’s the crux of the tip from the post that uses git reset to uncommit the differences between your feature_branch and master:

# Switch to the master branch and make sure you are up to date.
git checkout master
git fetch # this may be necessary (depending on your git config) to receive updates on origin/master
git pull

# Merge the feature branch into the master branch.
git merge feature_branch

# Reset the master branch to origin's state.
git reset origin/master

# Git now considers all changes as unstaged changes.
# We can add these changes as one commit.
# Adding . will also add untracked files.
git add --all
git commit

From here, add your files and changes in pieces as you like, write new commit messages, and then push your branch. If your branch is already pushed to origin, you may need to force push (git push origin feature_branch --force). Be aware force pushing can have unintended consequences, so test these things out first in a safe environment.

This page is nearly 10 years old and it’s still highly relevant. It also includes details on how to do a proper git rebase for comparison. Hope it’s as helpful to you as it’s been to me with my open source projects and more.

Moving RSS

2020-01-08T00:00:00+00:00

Somehow I never migrated this site’s RSS feed from Feedburner. Well, nearly a decade after it was shut down by Google, I’m finally moving to a new feed that’s been around for years and just never shared.

Please point your readers to https://markdotto.com/atom.xml.

Thanks!

Null variables in Sass

2019-08-30T00:00:00+00:00

Bootstrap is a large and complex frontend library with some powerful functionality and customization built-in. Occasionally though, we get asked to make things even more customizable for folks with more CSS properties and default variables.

This is largely because Bootstrap’s CSS relies on some limited global inheritance of general styles (font, color, line-height, and more), but developers and designers often want to customize things further. So we were typically faced with adding CSS we didn’t need at the outset, and that you might need. This just didn’t seem right for any of us.

Back in January, thanks to one of our maintainers Martijn, we started using null value default variables to combat that bloat while still increasing our level of customization.

Here’s a basic example:

$body-text-align: null !default;

body {
  text-align: $body-text-align; // Won’t compile
}

As you can see, the Sass compiler will ignore the entire property: value; declaration because the value is null. But, if someone customized this before compilation by overriding that default value, the CSS would compile. Here’s an example of how you’d override that default variable.

// First, override `!default` variables
$body-text-align: left;

// Second, import Bootstrap
@import “bootstrap”;

And here’s how it compiles to CSS.

body {
  text-align: left;
}

It’s also worth mentioning that these null values can be used in mixins, too. Check out this old Treehouse article for details.

Historically, more flexibility in our default styles meant more code for everyone, but with null value default variables, we can continue to provide more customization when warranted without knowingly adding bloat to our compiled CSS. I still owe Bootstrap a fresh pass at this to see what we can remove.

Hopefully we can continue to find more techniques for increased customization and smaller file sizes. Please share if you have them!

CSS dark mode

2018-11-05T00:00:00+00:00

Dark mode is finally coming to CSS, and you can start experimenting with it thanks to Safari Technology Preview. With their latest release, the experimental browser includes support for the prefers-color-scheme media query. Variables in CSS are also coming, making dynamic light and dark modes for your visitors easier than ever.

Here’s an abbreviated set of the variables and media query I’ve put to use for my sites.

:root {
  --body-bg: #fafafa;
  --body-color: #555;
  --link-color: #222;
  --link-color-hover: #000;
}
@media (prefers-color-scheme: dark) {
  :root {
    --body-bg: #212529;
    --body-color: #6c757d;
    --link-color: #dee2e6;
    --link-color-hover: #fff;
  }
}

You should use this time to experiment with how you’d adapt your own styles to put the new media query to work. For example, picking the dark colors for my site wasn’t too difficult, but I found screenshots were far too intense for comfortable reading. A quick opacity and transition brings some added comfort while reading at night.

@media (prefers-color-scheme: dark) {
  img {
    opacity: .75;
    transition: opacity .5s ease-in-out;
  }
  img:hover {
    opacity: 1;
  }
}

Shipping system fonts to GitHub.com

2018-02-07T00:00:00+00:00

I’m finally publishing this blog post I drafted over a year ago. It was incomplete when I started to revisit it months ago, but I figured it’s better to share it now than sit on it forever. I’ve called out the additions and edits I made since that original draft. Some details are fuzzy, but the core remains intact.

Last ~~week~~ July, GitHub.com received a slightly updated design featuring more modern fonts. Instead of showing decades old fonts that don’t take advantage of newer, high DPI screens, or dynamic font rendering, we now try to serve the best font possible based on your operating system or device. Awesome!

This posts explains why we made the change, how we coded and tested it, how we shipped the new fonts, and what we’ve done since initially making the move.

Before and after

Before we dive into the why, here’s a quick comparison of GitHub on macOS before and after the font change.

You can really tell this is from well over a year ago given the light header, low contrast, and lack of saturation in all our colors.

And now, with the dark header, color changes, and multiple product ships over a year later.

Compared to the previous figure, there’s clearly a stronger hierarchy and emphasis on key actions.

Why change

Our old font stack wasn’t exactly broken, but it was decades old. That stack featured Arial and Helvetica for Windows and Mac users respectively. Helvetica was created in 1957 when the personal computer was a pipe dream. Arial was created in 1982 and is available on 95% of computers across the web. Millions, if not billions, of web pages currently use this severely dated font stack to serve much younger content to much younger browsers and devices.

As display quality improves, so too must our use of those displays. System fonts like Apple’s San Francisco and Microsoft’s Segoe aim to do just that, taking advantage of retina screens, dynamic kerning, additional font-weights, and improved readability. If operating systems can take advantage of these changes, so too can our CSS.

Speaking of which, the saying goes that the best UI is no UI. With system fonts, page content can feel more like it belongs on your particular computer or device. Pages on my iPhone rendered in San Francisco feel more like a page made just for my iPhone, and I know from experience when I use my Nexus, I feel the same with Roboto there.

What’s changed

While the move to the system font families is quite obvious visually, we (a combination of product designers and web designers before our Design Systems team was formed) shipped a few other changes.

Here’s what’s new:

New fonts in our global font-family for the “system fonts” approach.
Larger base font-size for all pages, moving from 13px to 14px.
Improved type scale with clearer and more consistent heading sizes, weights, and line heights throughout.

Together, these changes have given us a much easier to read site and a stronger, more considered system to build on moving forward.

The stack

The new GitHub font stack has a handful of system fonts, plus some extras as fallback and emoji. Developers love their emoji like anyone else—maybe more.

font-family: -apple-system, BlinkMacSystemFont, "Segoe UI",
 Roboto, Oxygen, Ubuntu, Cantarell, "Fira Sans", "Droid Sans",
 "Helvetica Neue", Arial, sans-serif,
 "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";

This font stack has since been updated and iterated upon:

font-family: -apple-system, BlinkMacSystemFont, "Segoe UI",
 Helvetica, Arial, sans-serif,
 "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";

Here’s the rundown on what was originally included and what’s changed since we made the changes over a year ago:

-apple-system and BlinkMacSystemFont target default fonts in Safari and Chrome on macOS and iOS.
Segoe UI is explicitly named for all browsers on Windows 7+. Friendly side note, our Windows audience is either on Windows 7 or Windows 10—hardly anyone is on 8.x.
~~Roboto is for Android and ChromeOS devices.~~ We ended up removing Roboto because it caused issues in some distros of Linux. We definitely need to revisit it.
As fallback, Helvetica Neue and Arial are included. Fun fact, regular Helvetica is actually aliased to Arial in the Windows registry, so you’ll never get regular Helvetica there anyway.
And lastly, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol ensure that we render the best emoji possible on macOS and Windows.

As you can see, we originally had a few more fonts in there, but after shipping, we heard a ton of feedback from users with browsers, operating systems, and font settings we didn’t anticipate. This included Roboto, Oxygen, Ubuntu, Cantarell, Fira Sans, and Droid Sans. Interestingly enough, Linux users were the most upset at the change given Linux system fonts seem to be rather large and clunky, and their system fonts so inconsistent across distros.

Dealing with Chrome

~~Rather surprisingly, we’re well over a year past this original bug report and Chrome still doesn’t have this issue resolved.~~

Turns out Chrome has fixed this with v64! Huzzah!

Sadly at the time of writing this, Chrome still hasn’t resolved a bug in how they render San Francisco in macOS. You can follow the history of it on the Chromium bug report.

It’s subtle, but it’s definitely noticeable, especially when moving between other macOS apps and Chrome. Rather than utilizing the adaptive kerning of the new Apple font, Chrome applies a generic spacing multiplier across the entire font. This isn’t as noticeable for the SF Display variation of the font (which normally kicks in at 19pt and above), but it is obvious with the SF Text variant for body copy. Note how in the above screenshots the text wraps at different points.

It’s definitely a bummer to see this bug stick around given so many of our website’s visitors are on Chrome. It’s at least somewhat good that Windows Chrome users outnumber the Mac ones, though!

How we did it

Rolling out code changes on GitHub can happen in a handful of ways, but for any sufficiently large project, we use feature flags to help. These flags allow us to enable a change on a per-user, per-team, per-organization, or per-repository basis with ease. It also allows us to “staff ship” something to every GitHub employee—this is how we chose to roll out the system font change.

These feature flags are made accessible in our views, controllers, and more through a small Rails helper. (GitHub is one big Rails app right now in case you were wondering.) In our case, we had the system_fonts feature flag attached to a system_fonts_enabled? method. In practice, this allowed us to conditionally load an additional stylesheet that reset the font-family, provided our font-size and line-height adjustments for the new fonts, and housed any component-level overrides to ensure the font changes didn’t break anything.

<%= stylesheet_bundle “system-fonts” if system_fonts_enabled? %>

Creating that stylesheet and it’s conditional inclusion was the quickest part of the entire project. Once the new font-family was included there, we started browsing pages to see what was broken. That entire workflow really sucks in hindsight, but we don’t do visual diffing at GitHub (no reason why really) and it was the most straightforward path.

As we found things that needed fixing, we put overriding styles in that system-fonts.scss stylesheet with clear comments to explain why the override was needed. Here’s a snippet of what became a ~300 line stylesheet.

body {
  font-size: $body-font-size;
  line-height: $body-line-height;
}

// To ensure text resides vertically right in the middle of our buttons, we bump
// the line-height to 1.6. Otherwise, the button will be an odd-pixel height and
// text will appear to sit too low.
.btn,
.form-control {
  font-size: $body-font-size;
  line-height: 1.6;
}

// Forms need to have their padding match buttons otherwise they're different
// heights when placed inline with one another.
.form-control {
  padding-top: 6px;
  padding-bottom: 6px;
}

// Specificity wars; undo the above override so it doesn't fubar our header search.
.header-search-wrapper,
.header-search-input {
  padding-top: 0;
  padding-bottom: 0;
}

Those code comments were super important early on as this override file was temporary from the get-go. It ensured the work we’d do later to remove this file was as smooth as possible and would ideally even lead to less CSS than when we started.

After we shipped the change and merged it all into master, we had did whole iterate-with-customer-feedback–and–clean-up-the-code dance. We adjusted the font-family and slowly started to move those overrides back to their original rules in our existing stylesheets. This was more problematic for some overrides than others, but in addition to removing the system-fonts.scss file, it led to a good amount of general CSS cleanup.

Before shipping, we staff shipped the font change to all GitHubbers to let it sync in and try to catch as many bugs as we could. We left it in staff mode for two weeks, making additional tweaks here and there before rolling it out to all our users.

One year later

My original draft of this post ended with the above section. Now, over a year later, I can add more context, talk about the iterative updates that went into the typography of GitHub.com, complain once more about this ridiculously old Chrome bug, and hype our Design Systems team.

Near the beginning of 2017, we made a few other design changes to GitHub.com. Within a PR for that, I snuck in one more font change—adding SF Mono to our monospace font stack. It was a subtle change, but a good one for those who could benefit from it. Until the San Francisco fonts, no one on Mac or Windows had a shared sans-serif and monospace font experience. It’s small, and most folks likely don’t care about it, but it was cool to be able to merge that change six months later and complete the picture for macOS system fonts. Maybe we can help Windows and Linux soon!

Several weeks after making the SF Mono change, we also looked into shipping an update to the font stack to clean up some of those browser-specific aliases. We merged the change after some quick testing and assumed everything was going to be spectacular. Thankfully our users are always quick to notice problems and were quick to point out to our Support teams that the new system-ui alias caused issues in WebKit and Blink browsers with non-English languages. We reverted the change back to the previous version and haven’t touched it since.

After our Design Systems team officially formed up earlier this year, they continued to iterate on the code and documentation side of our typography. Making the change to the font stack and their various font-size/line-height pairings was only the beginning. The team stepped up and overhauled all our Sass variables and mixins, and then documented it in our new upcoming style guide. Since making those changes, they’ve also heavily overhauled our CSS toolkit, Primer, to better organize all our CSS, including typography, for easier usage across other properties. As such, we were able to easily put our system fonts in more GitHub web projects, too. Woohoo!

Managing features in Bootstrap

2015-09-28T00:00:00+00:00

Several months ago someone asked me how we manage and develop features in Bootstrap. Overall it’s rather ad hoc, but there are some specific guidelines we follow here and there.

It’s a product

The first thing to keep in mind is that we consider Bootstrap to be a real product. It has features, a development team, releases, and users. It has a mission of sorts—to make web design and development easier for folks. When we add or remove features, we’re attempting to balance that goal with our own experiences and interests, and those of our users.

That mentality governs a lot of how we approach things with Bootstrap. We care a lot about it, we’re impacting real people’s lives, and we’re a small team having fun doing it. Feature wise, we figure out what we could do, and then figure out what we want to do and how best to do it.

In more practical terms, that means we don’t do something unless we believe we can do it well. And we say no to a lot of feature requests—focus and quality means more to us than implementing x, y, or z.

General feature requests

Tracking what to work on mostly happens on GitHub. The Bootstrap issue tracker is our primary means of managing new features and updating existing ones. Anyone can ask us to implement something brand new or to extend an existing feature with an issue or pull request. Those we agree with or would like to get to are left open to implement and assigned a milestone for when to release. Others are commented on, cross referenced, and closed.

Opening an issue or pull request doesn’t inherently mean we will do something though. We’re actually quite selfish about things. We build features we ourselves would like to see in other products and sites. There are tons of components we think make for bad experiences, shitty interactions, or are simply a pain for us to build and maintain (shoutout to datepickers).

A side effect of that has also been that there’s an immensely large community out there doing all the things we can’t or don’t want to do. That’s huge for the folks that need and want those things, and I couldn’t be happier at the impact we’ve had there.

Major releases

During the development of a major release (e.g., the forever upcoming v4), we don’t share much publicly until we’re ready for outside help and testing. This keeps us focused and involves the fewest decision makers as possible—just like any other product.

We track features we want to build and overhaul in the next major release in private. We have two private repositories on GitHub for that—twbs/team and twbs/derpstrap. Our team compiled a list of things we all wanted to see added, removed, or changed in v4 based on the trends we saw in the Bootstrap issues on GitHub. That list become our own master feature issue and have since used it to guide all our v4 work.

Major releases are a chance for us to rewrite everything. We adopted this approach really early on to keep us interested in it over time. When you can experiment, have fun, and try new ideas on a longstanding proejct, it’s obviously more encouraging to continue working on it. So we change things up every now and then. Again, that’s selfish, but much more enjoyable long term.

Development

Regular development (minor and patch releases) happens in our issues and pull requests, either from us or contributors. New features usually end up becoming pull requests before making their way into the project.

Overall our development flow looks like this:

After we figure out what to build, we cut a branch and start adding the CSS, JS, and docs.
Open a pull request and /cc the team and original issue opener.
Include any relevant information, screenshots, and a current state of affairs to tell folks where you’re at in the process.
Once tests pass and the feature is complete, we merge to master.
We make a note in our ship list, an issue we open right after shipping the previous release to serve as a changelog.
When an upcoming version is almost ready to ship, we create the release on GitHub and share it with the world.

Not every feature that sees a PR gets merged though. Sometimes we start to code a change and it just turns out bad. The code could suck, it could be too much code, or the feature could just not align with n number of other things. We’re not shy when it comes to turning down large pull requests—we’ve got the entire project to think about first.

Smaller contributions are also better than larger ones. Once a specific pull request passes a certain point—be it number of lines changed or sheer scope of changes—it’s neary impossible to review properly.

Honestly though, sometimes I skip a lot of those steps. In major releases, I cut a private branch or fork and just get down to it in the development branch. No branches, no pulls—just coding for days. With minor feature releases I sometimes just push right to master as well, but that’s less ideal for history’s sake and should be discouraged.

Simple and focused

In short, we keep things simple and focused. Since Bootstrap is a side gig for most of us, a lightweight and approachable development process is very useful. We love helping folks build awesome stuff by building our own awesome stuff. It involves saying no a lot, and most importantly, thinking of Bootstrap as more than just an open source project.

Nesting in Sass and Less

2015-07-20T00:00:00+00:00

Nesting is supposed to make your CSS easier to read, extend, and maintain. For some situations, it does, but for designing CSS systems at scale, nesting your CSS is almost always a terrible idea. Allow me to explain with some general assumptions and examples.

Assumptions

No matter the build tool or preprocessor, there are a small set of general CSS guidelines I think most folks can agree on:

Less compiled CSS is better.
Less specific CSS is better.
Fewer selectors is better.
Smaller compiled file size is better.
Component-based CSS is better.

Running with that, here are some examples of nesting.

Nesting elements

I find this to be the most common form of nesting and is probably just fine for most sites. It’s not necessarily bad, but nesting like this makes your CSS more specific. It also doesn’t force you to write reusable components, which is what you want for building most apps.

.parent {
  h1 { }
  span { }
  a { }
}

Consider rewriting that code to something like:

.parent-heading { }
.parent-subheading { }
.parent-permalink { }

Those classes have lower specificity, more meaningful selectors, and are component-based.

Nesting classes

Nested classes means you’re heading in the right direction, but are held back by overly specific CSS.

.parent {
  .parent-child { }
  .parent-child2 { }
  .parent-modifier { }
  .parent-modifier2 { }
}

You’ve got a parent element encapsulating all the children classes, but those children classes are already properly scoped as legit classes. Rewrite it just by removing the parent:

.parent-child { }
.parent-child2 { }
.parent-modifier { }
.parent-modifier2 { }

The result is the same number of selectors, but with lower specificity.

Un-nesting with `&`

The un-nesting example is perhaps the most confusing way to nest CSS.

.child {
  .parent & { }
}

When used at the end of a nested selector, the & puts everything to the left of it before the parent selector. So the above example compiles to .parent .child { }. This is confusing in a few ways:

The & puts that selector at the beginning of the top-most parent.
It’s the opposite of how regular nesting works.
It clouds your vision of the compiled CSS.

Rather than go that route, try something like this:

.child { }
.child-modifier { }

The result is a component-based approach with lower specificity and clearer insight into what your compiled CSS will be.

BEM nesting with `&`

Nesting for BEM—or any other flavor CSS architecture—is helpful at first, but comes as a cost.

.block {
  &__element { }
  &--modifier { }
}

While you’re saving a few bytes in your source file by not writing .block each time, you lose out on the ability search for your classes. When you’re debugging something with a browser’s Inspector, you only see the final, compiled class. So, when you need to search your code base for .block__element, you won’t find it. That’s easy enough to get around, but that’s unnecessary cognitive overhead.

Instead, keep it simple and just write it all out:

.block__element { }
.block--modifier { }

Easy to read, easy to search, and with no sacrifice to your compiled CSS.

Nesting pseudo-classes with `&`

Nesting with pseudo-classes feels like the only practical way to nest your CSS.

.btn {
  &:hover,
  &:focus { }

  &:active { }
}

What makes it different from the previous example is that this is all one element and class, just with different states. It’s not multiple half-classes that do different things. That means searching your codebase for it is super easy and more intuitive—just find .btn.

Moreover, and perhaps more helpful, is this makes your code more mixin- and extend-friendly (though the true merits of the latter are up for debate).

Wrapping up

Bottom line? If you’re building pretty simple sites, nest to your heart’s content. However, if you’re building large apps or sites—Twitter, Bootstrap, GitHub, NY Times, etc—avoid it and keep your CSS simple, performant, and easy to parse.

Introducing Primer

2015-03-23T00:00:00+00:00

Primer is GitHub’s internal CSS toolkit. It’s been the base coat for GitHub.com for years now, providing styles for our global typography, layout, tooltips, buttons, and more. Starting today, it’s open source.

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.

Primer is licensed MIT, so you can basically do whatever you like with the source code. We’ll be a little stringent on merging new features to the project for the foreseeable future though. Longer term, we envision having a suite of Primer projects—one repository for each new component. More on that another time though.

For now, head to GitHub to view the source code and read through the docs at http://primercss.io.

Recent projects

2015-01-10T00:00:00+00:00

It’s been awhile since I wrote about any of the recent projects I’ve worked on, so here’s a quick update.

mdoml

What if you could augment HTML5’s current set of elements with your own? Well, as it turns out, you can. mdoml is an experiment in creating custom HTML elements based on today’s most common interface design components.

Read about and try the experiment in the live demo.

Ocean Dark Terminal.app theme

I really love the Ocean color scheme from base16. It’s included in the Spacegray UI theme for Sublime Text and Atom which I use and love. There are a ton of supported apps in the main repository, but not one for Terminal.app.

Download and find out how to use it on GitHub.

GitHub wide

Awhile ago I opened a pull request for GitHub.com to make the site entirely fluid. That is, instead of a fixed center aligned column, the site occupies the entire viewport. For a ton of reasons, we didn’t pursue it any futher than that pull request.

Instead of abandoning the entire thing, I opted to open source the CSS as a custom user style. Head to the repo for details.

Using Sass with Jekyll

2014-09-25T00:00:00+00:00

Updated March 23, 2015: Removed mention of installing Sass gem as Jekyll ships with it’s own converter.

While upgrading my suite of Jekyll themes to utilize the built-in Sass compiler, I found the official docs and example project a bit scattered and incomplete. As such, I decided to put this post together for my own reference down the line. Hopefully it helps you, too.

Assumptions
Install Sass
Create a Sass stylesheet
Link your stylesheet
Using Sass imports
Minification
Hosting on GitHub Pages
Example project

Assumptions

For brevity, this post assumes a couple things:

You have an existing Jekyll project up and running, or know how to start one from scratch.
Your local Jekyll is using version 2.4.0 or better (check in Terminal with jekyll --version).
You have some knowledge of Sass.

Got all that? Awesome, carry on.

Install Sass

Nothing to install here. Jekyll ships with it’s own Sass converter, so you’re good to go.

Wait, Sass or Scss? As far as I know, Jekyll includes support for both .sass and .scss. If you’re unfamiliar with the differences, .sass allows you to omit curly braces. I recommend sticking with .scss—it’s less clever and more approachable.

Create a Sass stylesheet

Create your Sass stylesheet wherever you like. At the top of the file, include a front matter comment, then add your styles after.

---
# Front matter comment to ensure Jekyll properly reads file.
---

// Add your styles here

For the purpose of this post, I’m putting it within a css/ directory. Here’s what my typical Jekyll site’s directory looks like:

jekyll-project/
├── _includes/
├── _layouts/
├── _posts/
└── css/
│   └── styles.scss
├── _config.yml
└── index.html

Assuming that structure, Jekyll will compile your css/styles.scss file into a CSS file at _site/css/styles.css.

Link your stylesheet

Now that we’ve got the CSS being built, the last step is including it in your site’s <head>. Be aware you may need to tweak the path depending on your setup.

<link rel="stylesheet" href="/css/styles.css">

At this point you’re essentially done—this the most basic setup for using Sass with Jekyll. Add you Sass in the source styles.scss file and compile it simply by starting the Jekyll server.

Using Sass imports

Jekyll includes built-in support for using @imports to compile multiple source files into one CSS file. Place your partial .scss files in the default directory, _sass/ and include them in your main Sass stylesheet like so:

---
# Front matter comment to ensure Jekyll properly reads file.
---

// Imports
@import "base";
@import "type";
@import "layout";

You can also change the default _sass/ directory to a custom directory in your _config.yml:

sass:
  sass_dir: _lib

Minification

Enable minification on your compiled CSS by updating your _config.yml to include:

sass:
  style: compressed

Now when Jekyll compiles your Sass, you’ll have no whitespace in your CSS. Be sure to turn this on for production environments if file size is of any concern.

Hosting on GitHub Pages

GitHub Pages has been built with Jekyll in mind—just push your Jekyll site to a branch named gh-pages to get started. It includes support for compiling Sass (and CoffeeScript!) when you push a commit up.

Curious about what dependencies and versions are on GitHub Pages? Check the versions page.

Example project

I’ve turned all this into a super basic example Jekyll project and open sourced it on GitHub. It’s licensed MIT and includes everything mentioned above for setting up Sass with Jekyll.

Enjoy!

Shipping GitHub's split diffs

2014-09-04T00:00:00+00:00

GitHub has been around for over six years, and in all that time there’s only been one mode for diffing code—the unified diff. Until yesterday, that is, when we shipped split diffs. Here’s how they look:

Similar to my post on shipping the new GitHub issues, I wanted to give some background on the how and why of shipping what until this week was our most requested feature.

Timing

For as long as I’ve worked at GitHub, there was an unintentional Hacker News tradition for every major feature we shipped. No matter the ship, we’d most assuredly get a comment like:

Neat. When are they going to do split diffs?

The general sentiment was surely it couldn’t take this long to build split diffs, so why didn’t we just done it already? Well, as it turns out, there were many great reasons why we couldn’t (or wouldn’t). To start:

Many GitHubbers never really used split diffs, so they didn’t see much value in building them into GitHub. I can’t blame anyone for that—either you’ve used and loved them, or you haven’t.
For the last two years, it was actually quite difficult to build. The code for diffs was quite complicated, all our JS depended on super specific HTML, and in general diffs were touchy on performance.
Lastly, and perhaps most importantly, we never just add something for the sake of adding it, especially a feature that impacts so much of our core offering.

Having worked at Twitter for two and a half years before GitHub, I spent much of my time in Reviewboard, a fantastic but ugly and slow code review tool that used split diffs. When I moved on to GitHub, I definitely missed the functionality, and it became one of pie in the sky type of features I wanted to help build.

First prototype

Six months after I joined GitHub, I finally gathered the courage to attempt just that. Much to my surprise at the time, it wasn’t actually too bad to get started. Here’s what I ended up with:

If you’ve ever looked under the hood of a GitHub diff, you’d notice we use <table>s to render them. Each line number and line of code is it’s own table cell. We use data attributes and JavaScript to handle line numbers and diff context expansion (showing more of a diff’s file).

Once I had a better handle on our diff views, and knowing they were <table>-based, I was able to see that the first and biggest step was to duplicate the existing code table cell. Then, I used some CSS-fu to collapse the “empty” cells on either side of the table.

Easy-peasy. Or so I thought.

Prototype ≠ production ready

Ultimately, none of it could ship. For a number of reasons, what I built 18 months ago was in no shape to be the underpinnings of a production-ready feature:

We were increasing the number of elements on the page by at least 33% (three existing cells for unified diffs, four for split).
Within those table cells there used to be a lot more markup. A <span> around every line number, a <pre> around every line of code, etc. That all adds up.
This prototype didn’t take into account how to actually switch between unified and split diffs, or if we’d do that at all.
It didn’t address diff expansion at all, and it turns out that code was completely dependent on the order of line number, line number, code for unified diffs.
It didn’t address code commenting in the slightest. How would comments work—one side, both sides, something else?
How would this impact the soon-to-be shipped prose diffs, which further complicated the diff code?

It just wasn’t going to happen without some serious and dedicated developer help beyond my limited abilities. Once I realized that, I gave up and moved on to other things. No one else really picked it up from there, and I think I have an idea why.

At the time, nothing shipped without a pull request and dedicated developer to push it through. I had a branch, but never opened a pull request for it. Given that, I think folks assumed I’d finish it eventually, and so no one else jumped on it until I did again 18 months later.

Today, the process for proposing and shipping a brand new feature are much better. We have a loose product roadmap, folks in leadership positions, and a better ship list. This new process is part of why split diffs shipped so quickly.

Take two

Fast forward to two months ago. We had just finished putting together a first pass at a more formal roadmap and split diffs were on the list. The exact details of the feature were still up in the air, but it was just enough pressure to kickstart things.

Given I was the last to prototype it, I started in on split diffs once more with a fresh branch. After a couple days I had another working prototype that was rather similar to the first:

This time though, I pushed the branch and opened a pull request. I pinged a couple folks and got a developer assigned to the project. Three weeks, 65 commits, and two contributors later my hacky second prototype turned into a staff shipped feature.

Hell yeah.

Road to shipping

With that initial staff ship, we knew we were on the right track, but we had plenty of work to do before we could ship it to everyone. We had to refactor a lot of code and redesign a few key areas of the site to pull it off.

I redesigned the “Add line comment” button to overlay the line number and code instead of overhanging on the edge, since we needed to go full-width for split diffs and a hanging icon on either side wasn’t going to cut it. It also provided an opportunity to clarify click areas throughout unified and split diffs.

In addition to the refresh of the UI components, the JS for line commenting and diff expansion was completely overhauled so that it’d work the same across split and unified diffs.

We rewrote a ton of code for this, and it was all for the better honestly. On the HTML/CSS side, I refactored the code blobs (static files) and diffs to share more code.

Previously, blobs were two table cells, one for all line numbers and one for all code lines. After the refactor, blobs and diffs were using the same table approach: one row for each line number and code cell.

Figuring out how to break the entire site’s layout on just a handful of pages was a bit of a challenge. For most views it’s as simple as removing a fixed width and adding padding. However, in other areas like the pull request composer above, we needed to do some refactoring to avoid nested fixed widths.

We also conducted several casual user studies to gauge folks’ reactions to the interface, verbiage, performance, and more to verify our gut calls on how to build a “GitHubby split diff” feature. Ultimately the folks we talked to confirmed our own hunches—ship it!—and lined up a ton of next steps for us.

Wrap up

I purposely avoided talking about a few aspects of this project, but hopefully what’s here gives you a good idea of what went into designing, developing, and shipping split diffs.

A number of things were punted so we could ship as fast as possible. To name a few, we still need to polish up the transition from fixed-width to full-width across the site and there are some bugs around composing comments and switching diff modes.

Bottom line? In exactly two months, we went from my pretty shitty pull request to a fully fledged, shipped feature. That’s simply astounding to me given the scope of changes. I’m super proud of this first step and the team. I’m stoked for what’s next.

Shipping the new GitHub Issues

2014-08-04T00:00:00+00:00

We started work on the new GitHub Issues over nine months ago. It was a bit of a crazy ride, but I’m honestly stoked about what we shipped. For the quick low down on what shipped, read the GitHub blog post.

Given the length and scope of the project, I wanted to share more than that blog post and tell the story of how we went from a single pull request to the shipped feature you see today.

Buckle up.

Instead of splitting the article, I figured I’d write until I couldn’t and just give y’all a helpful table of contents.

Why
- Use it to improve it
- Metrics
Logistics
Opening a pull request
Determining features
Iterating
Validating our ideas
Shipping it

Why

Perhaps the most important question is why would we even work on Issues? And what exactly would we do with it? How did we know that it needed the love?

Use it to improve it

We spend most of our time on issues at GitHub. Internally, we use the hell out of Issues for everything. Have a problem with the office? Open an issue. They’re a written record, cheap and fast to create, and searchable. Between our extensive usage internally and the number of folks here contributing to open source projects, we’re some of the most prolific issues users.

Bottom line? There was no one thing that motivated us to do it. We just started to notice some things that could be better, like:

It was starting to feel dated compared to other aspects of the site and enough folks spoke up about it.
The interface was a bit cluttered with nav and filters on the top, right, and left sides.
Searching for issues was an entirely different experience. We didn’t have a dedicated search for issues, so when you searched for a specific one, you left your repo’s issues list and landed on a search results page. From there you couldn’t triage any aspect of the issue until clicking into it.
We were missing a bunch of information on the issues and pull request lists—task list progress, milestone name, build status, etc.
At least two of us wanted to work on it, and we both were excited by the possible outcomes the more we talked about it.

Once we had that kind of feedback shared (you know, if you see something say something), and folks agreed that those were worthy problems to solve, we got to work writing code.

For what it’s worth, this is just about how all product or redesign work goes on the GitHub.com side. Find a problem, propose a solution (usually with code), get feedback, and find a way to ship it. We’re looking into how we can improve this and apply a process or checklist to all great ships, but that’ll take some time.

Metrics

We didn’t spend much time looking at analytics or metrics for Issues before diving in, but we have historical data we can compare against. Throughout the project we tried to optimize our database reads and ensure we didn’t have extra HTML and CSS lying around, but that’s about as far as we got for the front-end performance stuff.

Logistics

Before I get to the good parts, first let me explain a few things about how all this went down logistically as it’s important to have a bit of context for this given our usual shipping speed.

Nine months!?

So, first, why nine months?

We had two large related projects going on at the same time: the issues redesign (internally and hereby called Issues 3) and our conversations redesign.
The conversations redesign took our attention away from Issues 3 after a few weeks. Ultimately it derailed us for around three months while we iterated, shipped, and cleaned up after ourselves.
We had a bit of trouble keeping the two projects separate. We ended up blending some ideas and that also set us back.
We improved a ton of our infrastructure around search and issues performance.
We spent a lot of time trying things out for a week or so between bigger iterations. Our goal was workflow improvements, so we need to work with these ideas more so than other ships.

It was a challenge for all of us—me in particular—at balancing two separate-but-related efforts. Crossing the ~~streams~~ ships meant adding complexity, spinning our wheels, and losing sight of the specific end goal for each ship. I think we did an alright job of realizing that quickly enough and ended up getting a ton of work done.

Who

The Issues 3 core team was essentially three people: two developers and one designer/frontender (me). The extended team included our Ops and database folks, search engineers, and people from support and docs teams. Plus, dozens of others in the company who provided feedback via issues and pull requests throughout.

Working together

We found out really early on that all of us on the core team worked pretty damn well together. We moved fast, broke things, opened tons of pull requests and issues, called each other out on bullshit, propped each other for amazing ideas. Most of it happened fluidly and off the cuff. There was hardly anything formal about it until we were near ship time.

Here are two examples of how most of our work was done.

Issues were opened with specific feedback by one of us (or others across the company), labels added, milestone set, and someone assigned. When we had fixes to deploy, we opened pull requests.

We’d try to be as detailed as possible. We included screenshots, /cc-ed the right folks (e.g., the @github/issues team), and then quickly shipped it. Given the early work on Issues 3 was only team shipped, we could afford to screw things up every now and then because only we would be affected.

There was still a chance of screwing up other things mind you, and I may have done just that a couple times, but we were pretty well shielded.

In issues and pull requests, we’d use task lists whenever possible. Similar to full fledges issues, we’d try our best to be super clear and assignee folks or ask for help when we needed it.

Those issues task lists were especially useful when we got closer to shipping and could use them to do production readiness reviews, check in with the docs team on how their updated screenshots were going, and review last minute tweaks or bug fixes.

Put another way, we used GitHub Issues to build GitHub’s new Issues, and it was pretty damn awesome.

Opening a pull request

Okay, now, back to the product work.

A bunch of us had been talking about updating Issues for a long time, but it didn’t take off until Holman opened the first pull request. (That’s often the case—some ideas just stall out without some code to kick them off.)

The first Issues 3 pull request was opened back in October of last year, and while the aesthetics and layout details changed a lot over time, the core idea never did. This would make search the interface.

The idea itself didn’t feel all that radical, but it did heavily influence the architectures and interface. Under the hood, we leaned into Elastic Search and MySQL to build out the functional tidbits. Today, Elastic Search powers all the custom search queries while MySQL handles the general issue and pull request listing and more.

Interface wise, it’s pretty clear that search was the focus early on. That search bar was huge! Everything you did updated the search bar, and heck some things were (and still are) just easier when you type in the search input. I was honestly hesitant about this, but the team’s excitement kept us moving.

Determining features

That first pull request had it’s own feature set: more search, triage mode (bulk actions), and faster access to issues. Along with that first iteration though came a bunch of spontaneous ideas from within our team as work progressed.

Quite a few of the features we shipped with actually came organically out of that.

Search is obviously the huge feature focus in Issues 3, but the specifics were worked out as we went. We defined the search syntax, added negation searches (like no:label), and more state queries (like is:merged) as we went along.
We found ourselves doing the same simple searches over and over again, so we restored the old quick filters (like Your issues) and added a few more.
Our audit log—the history of changes to titles, assignees, labels, and milestones—went from offhand comment to part of Issues 3 in just a couple weeks.
Notifications on assignee changes went the same way. A few of us were talking about notifications one afternoon and we realized this wasn’t a thing yet. So, we coded it up and made if part of Issues 3.

We had a quite a few things in mind from the start, but just as many important features came naturally out of actively using the thing we were building. While that added extended the time we spent on the project, it was absolutely worth it.

Separately, one thing that’s come up a lot in the last several months has been project management on GitHub. The term project management is rather vague. There’s a multitude of ways in which this could manifest in GitHub, all of them independent of improving our existing issues and search infrastructure and interface. As such, it wasn’t part of this project.

I’m specifically avoiding talking too much about what we didn’t ship as there’s still a good chance we’ll ship those things. I don’t know when, and I don’t know how, but there’s still so much we can do with Issues—a fact I’m sure no one will disagree with.

Iterating

The early months of our work on Issues 3 (after those new conversations shipped) was mostly spent churning out iterations on the interface. While others focused on the underlying code, I fiddled around with the layout, aesthetics, and more. Here are a bunch of those iterations and a few brief notes regarding each.

Earliest iterations

As mentioned earlier, this was the opening screenshot of the issues index page, the work of one engineer just going to town on what a vision for Issues could be. Turns out he was pretty spot on as well.

The design is rather inbox-y with the huge search, buttons for filtering and triaging, and the single line issues list. The reason for that was to add and streamline information to keep it in a single row for more content per page. One line per issue was a bit of a crazy goal and we’d struggle to keep to that as we iterated more.

This screenshot is a bit of a mess as you can tell. It was from one of those interstitial states where the conversations redesign and Issues 3 were becoming confusingly intertwined. The omnipresent search at the top was one (bad) idea we tried to carry over from the issues index to individual issues.

We also tried to have no sidebar on issues with this—you can see the milestone, assignee, and labels at the top of the page. Things got messy, but we were fast and flexible enough to quickly try out and discard ideas.

Once that initial design was merged—it was team shipped, which meant only a few GitHubbers had access to it—I started tweaking the design to explore slightly different directions. Briefly, here’s the what and why:

I minimized the search field because I still didn’t think search would or could be the primary interface for people of all ranges to interact with first.
I condensed the search and filter buttons into one row so you didn’t lose as much vertical real estate.
I tweaked the display of content in the issues list by collapsing labels into dots (revealing the label name on hover via tooltip), giving more weight and contrast to issue titles, and adding more content in a slightly more tabular design.

One of my favorite aspects of this was the arrow to avatar for assignees. To me it read super naturally—issue titled such and such assigned to username. Later it’d cause problems for aligning and wrapping longer content.

The design of that issues list page also mapped to the individual issue again. Things were getting even more mixed up between Issues 3 and the conversation redesign as I streamlined the gray bar and the assignee, milestone, and labels lists into it. Notifications also got moved up from the bottom of the page to a single button on the top right.

The goal here was to present all your actions above the rest of the page content. This way, hierarchically, it reinforced the idea that you were taking action on this page—this issue.

There are some more failed ideas in here from an earlier iteration of the conversations redesign. The state indicator—the thing tells you it’s an issue or pull request, and if it’s open, closed, or merged—was like a big avatar. The opening comment was (literally) unboxed and enlarged to function as a sort of blog post style introduction to the issue or pull request. This never really ended up working out as it brought with it a few annoying differences across how we layout comments and render their Markdown content.

Aesthetics

For a long while most of my changes felt superficial. I played with button styles, orientation of search and filters, and different representations of content within the issues list.

I removed the light gray background to prevent more horizontal stripping of content, something GitHub and tons of other sites seem to struggle with. Other super subtle changes include lightening the comment bubble and count for issues without comments.

More visual changes as I try out lighter button styles to make the page feel less full of administrative cruft. It wouldn’t work out that well for buttons originally, but those styles later resurfaced in our subnav.

I spent far too much time flipping between icon-only buttons and icon-text buttons. At this point I also started to solidify on some of the more basic aspects of the issues list that I stupidly tried out earlier on. For example, I started expanding the labels again to their natural textual state. I also restored the stateful color—green or red for open or closed—to the issue/pull request icons on the left.

Searching vs. filtering

While I struggled with it repeatedly, there was a moment when I suggested we abandon the new search field entirely.

It was starting to annoy me that I had up to three ways to get to things:

Clicking the filter buttons
Searching by hand
Hacking the address bar and using URLs only

It felt odd that we had so many avenues to get to the same content. Eventually though, I’d come to peace with this and realize it was an advantage. Some folks love using buttons for everything, some work faster typing and using keyboard shortcuts, and some love their address bar more than life itself.

Put another way, the more access points, the more we could appeal to different workflows across teams and organizations.

Structure

Throughout our work on issues and conversations, I frequently got care-mad about the intersection of our repository navigation, page headers, section subnav, and our issues filters. I also got fed up with the single-line issues—it just wasn’t working.

So I started screwing around with more subnav-search-filters layouts and the placement of content within the issues list. The subnav moved around from the top right of the page header to the top left of the issues list and more. I think we flipped around and tried out even more ideas, but mostly these were our two “best” options.

The table-header style approach to our filters here was one of my favorite aspects as well. It felt simple, elegant, and functional and came without all the added weight that a series of buttons brings.

We realized for awhile that because we had moved the subnav—previously tabs in the old issues UI—to the page header, we suddenly had more room again. That meant making the search field ginormous again.

But something still didn’t feel right in that layout. The hierarchy felt lost again and it was rather difficult to find relationships between content and quickly find things.

At this point I panicked for nearly an entire day. I gave up everything about the new layout and tried a few ideas to see if a tabbed interface and side column would make more sense again. I don’t know if it’s just because what I tried was absolute shit or if the idea just didn’t make sense, but it felt wrong.

Seeing that it felt wrong again to try the side column and tabs, I starting feeling a lot better about our new direction.

Additional views

While all this work was being poured into the main issues list, we had plenty of other iterations on labels and milestones. Labels in particular are fun to compare before and after:

The original pass was kind of fun and quirky, but not the most practical.

We toned it down and shipped a super basic one-page list of your labels. We wanted to add more sorting and metrics, but time just didn’t allow it. Maybe next time around.

We spent a decent amount of time thinking about how to educate folks about available search queries. Two earlier options include a popover when focusing on search and a set of links at the bottom of the issues list.

Compared to a set of callouts below the content:

We ended up shipping a much more streamlined version of those at the bottom of the issues list. It was easier to work with, easy to ignore by more experienced users, and a fun surprise for those new to the feature.

Settling down

So, I went backwards again to the table header, narrower search button, and a closer subnav for the issues, labels, and milestones links.

Instead of columns like some earlier iterations though, I switched to plain text “buttons” all right aligned above the issues list. Given that they weren’t typical button styles (gradients, box-shadows, etc), it felt lightweight and approachable.

There was a bit more churn around the subnav and issues list:

Added a border around the entire list of issues and the table header
Set the filters (open/closed, labels, etc) against a light gray background for contrast between chrome and content
Tweaked the subnav styles, trying out gray text links, nav pills, and then ultimately a segmented controller style nav
Search styles to clarify the proximity of the quick filters dropdown menu and new issue button

Even with those changes, this was basically the last big iteration we went through before shipping.

Validating our ideas

The thing about working on a single project for so long was how do we know when to stop? I struggled with this a bit. When you’re working for so long on something, you get tunnel vision and don’t want it to end. You keep telling yourself you’ve got time for one more tiny feature or one more UI change.

One day I noticed something though. Whenever I wanted to churn through some Bootstrap issues, I was disabling staff mode and reverting to the old issues interface. As it turns out, I wasn’t able to get any real work done with the current design.

So, that became the test for me. I’d know we were on to something awesome if I could binge close dozens of issues without using the old interface.

For some reason we never really got to do dedicated user research studies on Issues 3. We had plenty of time, but it never solidified. We did have tangential feedback from related studies, our sales team, ourselves, and our peers who we teased with early iterations.

Shipping it

The task of actually shipping Issues 3—after all the design and development was done—is mostly a familiar process to us. There were a few unique aspects for a ship of this size, but overall it went something like this:

We finished off all our product work and shifted gears to the blog post, small bug fixes, etc.
Given we had rewritten and improved much of our infrastructure, we had some basic production readiness reviews with our Ops folks (far too late in the process mind you, but it was better late than never).
We dark-shipped it a couple times to more accurately simulate the changes in performance. (Dark-shipping refers to silently calling a new feature’s functionality in production alongside the existing functionality. This way, you get real metrics on how folks use the service for both versions.)
When we were ready for it to go into “genpop”, we flipped the feature flag and redeployed to our servers.
After watching the graphs in Chat for 10 minutes or so, we decided it was ready to go and merged into master. Boom, it was shipped!
Once we shipped the code, we shipped the blog post and all our documentation updates that our support team had made. Without those last two, the whole ship is a bust as support requests become a shit show rather than what I like to call a coordinated chaos.

That’s greatly simplifying it, but I’m not trying to provide all the technical details. That’s way too much for this post. Suffice to say we had an amazing set of dedicated individuals and teams to help us ensure a quality ship.

Our Support team is always invaluable when it comes to shipping (big) features. They triage incoming feedback, bug reports, and the like so we can more efficiently react and quickly ship follow-up tweaks. I can’t stress enough the importance of that workflow to the success of this project.

Wrapping up

Issues 3 wasn’t without its problems, but we worked our asses off on it for months and the launch has been overwhelmingly successful. I’m sad I don’t have more metrics and user feedback to share, but we simply didn’t collect enough of it throughout the process. Next time, we’ll do even better.

And on that note, here’s to the next :ship:!

GitHub's CSS

2014-07-23T00:00:00+00:00

I’m always interested in the development details of other products, particularly their styleguides and approach to CSS. Given my penchant for the otherwise inane CSS details, I decided to write a bit about GitHub’s CSS.

Given the length, here’s a helpful table of contents.

Quick facts
Preprocessor
Architecture
Linting
Two bundles
Included via Sprockets
Performance
Documentation
Primer
Refactoring

Quick facts

A survey of our current state of CSS shows:

The preprocessor of choice is SCSS.
We have well over 100 individual source stylesheets that we compile before serving it up in production.
That compiled CSS is served via two separate stylesheets to avoid the IE<10 selector limit.
Those two stylesheets weigh in at around 90kb total.
There’s no particular “CSS architecture” in place.
Pixels are the unit of choice, although we do have some ems lying around.
Added 7/24/14: We use Normalize.css and a mix of our own reset styles.

Preprocessor

As mentioned above, we use SCSS. This was a choice made much before my time and I’m a-okay with it (despite Bootstrap currently being written in LESS). Our SCSS is compiled by the Rails asset pipeline with some help from Sprockets (for the time being) for including the files. Read about that a bit farther down.

What about LESS, or Stylus, or …? I don’t think LESS was ever a choice for GitHub, but I can’t really speak to that. We probably wouldn’t switch at this point either as there is no clear benefit.

Why a preprocessor? Our internal framework includes a relatively small set of variables (like font stacks and brand colors) and mixins (mostly for vendor prefixed properties) that make writing code faster and easier.

We don’t currently use Autoprefixer, but we really should as it would basically negate all our existing mixins. Hopefully we’ll implement it soon.

We also don’t currently use source maps, but that’ll be changing soon. (If you don’t know, source maps allow you to see in the Inspector what source SCSS file a particular set of styles are coming from rather than a compiled and minified stylesheet. They’re awesome.)

Added 7/24/14: Other than that, our use of the tools SCSS provides is quite limited. We use color variables, mixins, color functions, math functions, and nesting. We don’t need to iterate over classes, set global options, or anything else really. I enjoy the simplicity this affords.

Architecture

Common CSS architectures include BEM and OOCSS. We lean towards OOCSS, but we have no holistic approach. We do tend to write all our new stuff with a nebulous but basic approach:

Aim for classes over everything else in selectors
Avoid unnecessary nesting
Use (single) dashes in class names
Keep things as short as possible without adding confusion

I’ll write more about my preferred CSS architecture in another post. For now, the above sums up GitHub’s approach, which while not perfect, serves its purpose well enough.

Linting

We didn’t start linting our SCSS until several weeks ago. We had common enough conventions, but everyone’s style and formatting was somewhat unique. Today, every CI build includes basic SCSS linting and will fail if:

You have a class in your CSS but not anywhere in your app/views/ templates.
You are using the same selector multiple times (as they should almost always be combined).
The general formatting rules (nesting limits, line breaks between rulesets, lack of space after :s, etc) are broken.

All in all, these few rules keep our stuff decently tidy. It doesn’t account for discrepancies in commenting styles or general architecture, but that’s the stuff teams need to address themselves with real documentation. It’s something everyone here is open to improving and iterating on.

Two bundles

GitHub.com has two CSS bundles, github and github2. The split was added years ago to solve the problem of Internet Explorer’s 4,095 selectors per file limit. This applies to IE9 and down, and since GitHub requires a minimum of IE9, our split bundle approach must stay.

This is because, as of today, GitHub has around 7,000 selectors across those two files. How’s that compare to other sites?

Bootstrap v3.2.0 has just under 1,900 selectors
Twitter has just under 8,900 selectors
NY Times has just under 2,100 selectors
SoundCloud has under 1,100 selectors (Edit: Previously I reported this at 7,400, which is the old SoundCloud)

These numbers were gathered using cssstats.com. It’s an awesome little tool that looks at your CSS in ways most folks, including myself, usually don’t. We also have graphs for this internally at GitHub and usually use those for our own purposes.

Included via Sprockets

GitHub’s CSS, and JavaScript, is bundled via Sprockets and require. We maintain our two CSS bundles with separate subdirectories within the app/assets/stylesheets directory. Here’s how that looks:

/*
 = require primer/basecoat/normalize
 = require primer/basecoat/base
 = require primer/basecoat/forms
 = require primer/basecoat/type
 = require primer/basecoat/utility
 = require_directory ./shared
 = require_directory ./_plugins
 = require_directory ./graphs
 = require primer-user-content/components/markdown
 = require primer-user-content/components/syntax-pygments
 = require primer/components/buttons
 = require primer/components/navigation
 = require primer/components/behavior
 = require primer/components/alerts
 = require primer/components/tooltips
 = require primer/components/counter
 = require primer-select-menu
 = require octicons

 = require_directory .
*/

We include our dependencies—Primer is our internal framework—and then load the entire directory’s SCSS files in whatever order Sprockets decides to include them (I believe it’s alphabetical). The ease in which we can bundle our stylesheets—by simply writing require_directory .—is awesome, but it also kind of sucks.

The order in which styles get applied matters. It really shouldn’t, but in every design system there are rules and a basic hierarchy of styling. With the Sprockets approach, we sometimes run into specificity problems. This happens because new files can be added to either bundle at any time. Depending on their file name, they appear in different spots in the compiled CSS.

Additionally, using Sprockets means that your SCSS files don’t have immediate and automatic access to your global variables and mixins. That means you have to @import them explicitly at the top of any file that references a variable or mixin.

Given the repetition and occasional specificity headache, we have a pull request open to switch to explicit @imports. The added benefit is clearer insight into our CSS and easier willy-nilly experimentation with our aforementioned bundles. The downside is having to maintain that list, but I like to think of this as an added control to the overall system.

Performance

Added 7/24/14: Bundle sizes and selector count graphs.

Internally we use tons of graphs to monitor how the site and API are doing. We also track a few interesting frontend stats. For example, here’s the size of our two CSS bundles for the last three months:

Similarly, here’s the number of selectors over the last month on our blob (or file) pages. Clearly we still have some work to do there to get those element tag selectors down.

Because we regularly deploy updated CSS, and we deploy dozens of times each day, we’re constantly busting the caches on our decently large CSS files. We haven’t done much in the way of optimizing these file sizes or limiting the cache busting, but we are starting to look into that more closely. It’d be awesome to have a core bundle that hopefully changes very infrequently and secondary bundle that can be more volatile.

Speaking of which, at Twitter we had (I’m unsure if they still have this) two bundles, core and more. core was all the styles needed to keep the time to first tweet number as low as possible. Everything else was in more. Given GitHub’s love of all things fast—here, it’s not shipped until it’s fast—it’s something we plan on looking into. Currently our bundle split is arbitrary.

Generally, selector performance isn’t something we concern ourselves with. We’re aware of bad practices—over-nesting, IDs, elements, etc—but we don’t try to over optimize. The one exception has been diff pages. Due to the extensive markup required in rendering a diff, we avoid attribute selectors like [class^="octicon"]. When used too often, those attribute selectors can (and have) crashed browsers.

For the curious, Jon Rohan, a fellow GitHub design-gineer, has a great talk about GitHub’s CSS performance that covers these problems.

Documentation

Speaking of which, we do an okay job of this, but we’re working on making improvements. We have a publicly accessible CSS styleguide and all our general rules for writing CSS live there, as well as examples of most components. It’s built on KSS, a styleguide generator of sorts, and lives right in the github/github code base.

It’s not perfect, but it helps folks find and use things. It’s also a great way to show new folks how we do things to get them up to speed faster (like me when I joined nearly two years ago).

Primer

I alluded to it earlier, but for folks who don’t know, Primer is our internal framework for common styles and components across our public and internal apps. It includes:

Normalize
Global styles for box-sizing, typography, links, etc
Navigation
Forms
Grid system
Markdown styles
Custom select menu

We use it on GitHub.com, Gist, and several internal apps. As a rule of thumb, if it can or should be used in another app, we consider putting it in Primer.

Most of Primer’s components are documented in our styleguide (e.g., navigation, tooltips, etc). However, we’ve recently been going to town on updating and improving Primer, so lots of things are in flux there. We’ll be updating that soon to include all the things.

And for those about to ask, I’d love to open source parts of Primer, but there’s not much happening on that front in the near future. I’m hopeful though.

Refactoring

We have our fair share of legacy code at GitHub, and that includes our CSS. Unlike a public open source project with strict versioning rules, we burn shit down regularly if it suites us. Finding things to remove tends to happen one of two ways:

Manually finding things that look alike but actually have different HTML and CSS, then combining them.
Running a script that greps for a class in our CSS to see if it exists in our views. (We’ve recently made this part of our CI tests, so we constantly see it now.)

The actual process of refactoring CSS is probably not unique to GitHub. We find shit to remove, burn it down, open a PR, ping the CSS team, and ship it as fast as we can. As to who removes code, anyone can do it. We have tons of great folks adding to GitHub, but we also have just as many nerds looking at what we can remove.

GitHub.com flow

2014-05-02T00:00:00+00:00

The term GitHub flow refers to how one can develop software with GitHub. It’s a process that minimizes friction, enables asynchronous communication (and development), and is decently flexible. For an overview, read Understanding the GitHub Flow on GitHub Guides.

Applying the GitHub flow to development of GitHub.com The Website™ builds on that, and tends to go something like this.

1. Find something to work on

Issues on the github/github repository are the easiest way to find things to do. Anyone can open them, and anyone can comment on them. User and team at mentions are available for pinging folks with bugs, feedback, or questions.

It’s worth mentioning though that we sometimes jump right into code from a meatspace discussion or from a tweet. Twitter is the best way to find out if we have bugs or performance problems in real-time while deploying code.

Bottom line? Get to writing code as soon as possible.

2. Branching

At GitHub, almost every new contribution happens in a branch. What’s in master should always be stable, passing tests, and ready to deploy in an instant. When I figure out what I’m working on, I cut a branch from master and get to work.

My branch naming scheme is sometimes serious and relevant, and usually not useful in the slightest. sidebar_hit_areas and today_we_celebrate_our_independence_day are both branch names that I’ve recently worked on. Both are long gone though.

Great branches really should include accurate names, but most of the time it doesn’t matter because they’re so short lived. Plus, snagging the name of a branch is as easy as copy-pasting from the top of a pull request.

Bottom line? Just cut a branch and write some code.

Not every change happens in a branch. Super small changes can be made right to master should the occasion, or emergency, call for it.

3. Pull requests

Branches are ephemeral. They exist for the sole purpose of creating a pull request. Pull requests are more important than branches for a number of reasons:

Suggested changes are (justifiably so) more likely to be shipped if there’s an available pull request for it.
Branches get deleted, and thus code can be lost. Pull requests are never deleted, only closed or merged.
Pull requests, like issues, are search-able, label-able, milestone-able, and mention-able. Branches? Not so much.
Pull requests can be discussed in the open and linked to.

Pull requests should be created as soon as possible. You should push your code and open a pull request when:

You have changes that are completely finished and just need review before merging.
You have a bunch of things to do and need to use GitHub task lists to outline what’s left.
You have questions and have no idea how to finish a part of your intended changes without pinging coworkers.
You have an idea that you’d like to discuss and test, but might not ever intend to ship.

As a side note, the GitHub.com code base has 50% more pull requests than issues:

For those who asked, to date, the github/github repo has ~10,000 issues and ~15,000 pull requests.
— Mark Otto (@mdo) April 29, 2014

Bottom line? Pull requests are cheap and effective. Create them early and often.

4. Discuss your code

You can define a pull request a few different ways, but first and foremost it’s a discussion around code. Code review. The best code reviews (and thus, pull requests):

Have a limited set of changes
Specifically at mention individuals or teams
Include before and after screenshots, if dealing with visible front-end changes

There’s no harm in creating lots of pull requests for discussion. If you’re concerned about pushing unfinished work, let people know you’re not yet ready for feedback or merging to master. Two easy ways are to preface your pull request title with WIP: or to include a row of :construction: emoji in the opening comment.

Bottom line? Make it as easy as possible for your peers to help you ship your code.

5. Shipping it

When it comes to deploying or shipping your code for GitHub.com, you have a few options:

Branch deploy: deploying your branch temporarily to production in place of master.
Branch lab deploy: deploying your branch to a specific server, which when deployed, gives you a unique URL (e.g., hi_mom.branch.github.com).
Merging to master: merge your branch via the merge form on your pull request. Your branch is merged, tests are run, and master is redeployed with your changes to production.

The best thing to do is use branch lab because you get a real URL you can share with folks around the office. URLs are the best way to drop a link into Campfire to invite folks to view some changes. Also, there’s basically no limit to how many branches can be deployed on branch lab.

When you’re changes have shipped—meaning, they’ve been merged to master—you delete the branch. GitHub will automatically prompt you do to so after merging to ensure your list of branches stays lean.

Bottom line? When you’re ready to ship, test your changes in an isolated branch lab, then merge to master.

Shoutout to Hubot

Hubot is our Campfire bot that literally does (almost) all the things. Find Google images, remember things, run tests, and most importantly, deploy code. When I’m ready to deploy code, I just pop into Campfire and tell Hubot to get to it:

/deploy github/hi_mom to branch-lab

Hubot will automerge master if there are new changes not in my branch yet, run tests again, and then deploy my branch. If my tests fail or haven’t yet finished running, Hubot tells me that right in Campfire.

Dream on

2014-04-07T00:00:00+00:00

This morning I was mentioned in a brief Twitter conversation, and because Jeffrey is the best, I feel obliged to reply.

@brendandawes @elliotjaystocks I'm interested in @mdo's take—from a brilliant designer who also created the bootstrap framework.
— Jeffrey Kalmikoff (@jeffrey) April 7, 2014

I encourage you to read the mentioned post by Elliot Jay Stocks. In it Elliot asks the question, Why have today’s designers stopped dreaming? Between the article and the tweets, there are two topics I’d like to comment on.

Tools

First, Brendan blames—among other unnamed things—frameworks. Consider my interest piqued.

While Elliot directs his post towards the craftsmen—those swinging the tools—Brendan throws the tools themselves under the bus. He’s not alone in that line of thinking. Lots of folks hate on today’s frameworks, design tools, and the like. Usually that dislike comes out of personal preference or limited experience. That doesn’t invalidate anyone else’s use of those tools though, and we’ll all do well to remember that.

Let’s consider another “framework” for a moment—iOS. Is the most important operating system of the last decade to blame for a stagnation in app design and creativity? Some might say so, but have you seen the amazing apps that are being built on iOS? They’re fucking astounding!

Are frameworks the same as a mobile operating system? No, but they serve a familiar role—abstraction of common aesthetics, behaviors, and components with a focus on documentation. As absurd as it might sound, it’s hard not to see at least some similarity between the two.

Are these frameworks and other tools impervious to criticism? Definitely not. (Have you seen the number of issues against Bootstrap? It’s over 13,000!) However, it’s important to acknowledge that amazing things can be done with just about any tool if you have the right mindset.

Bottom line, the tools aren’t (completely) to blame.

Web workers

Second, from the article:

The web right now is a beautiful place. Web design has matured as an industry and the technology now enables us to create whatever we might dream of in HTML, CSS and JavaScript. But it’s clear that laziness amongst designers has never been more rife.

Thousands and thousands of cookie-cutter sites litter the internet, each one drawing just a little too much influence from the last. The blame is not to be laid at the feet of sites that provide actual website templates, but at the feet of professional designers who are churning out ‘bespoke’ sites that might as well be templates.

I dare say what we’re witnessing, and what Elliot and Brendan are referring to, is not laziness. The web design and development community is in a completely different place from when we got started.

We’ve been doing this stuff for 10, 15, or more years now. Those lazy designers you’re seeing? They’re lawyers, stay-at-home dads, bored teenagers, interior decorators, anthropology majors, teachers, and more. And they all just learned HTML and CSS last Tuesday afternoon while we were all eating our burritos and playing video games at work. (Hi, that’s me in case you didn’t realize.)

Today’s web is filled with millions of people who don’t make websites professionally. They make them simply because they want to and the tools are in place so that they can. That’s fucking awesome!

This doesn’t account for everyone though. Are some designers lazy? Yup, and at times I’m definitely one of them. The site Elliot described? It might as well be any number of the example templates that come with Bootstrap. And I’m perfectly okay with that.

Right or wrong

Elliot and Brendan aren’t wrong. There are lazy designers and developers out there, and tools and trends can make it easier for folks to be lazy. At times, I’m one of those lazy designers. Does that make any of us right or wrong? I don’t think so. Can all of us do better? Most assuredly.

Using design trends helps people. We find out what looks good doesn’t always feel good. We find out that some tools don’t always work for every job. We find out that performance and documentation are more important than your own visual preferences. Design trends, frameworks, and the like are, among other things, learning tools. Let’s keep that in mind.

Sing with me

Everything I do in my work at GitHub and on Bootstrap is dedicated to folks who want to make awesome stuff on the Internet. My dream is to help awesome people do awesome shit. Nothing else gets me more stoked out of my mind than that. I get goosebumps thinking about how much the web has changed and how we can continue to shape it just by writing code and sharing our experiences.

Designers didn’t stop dreaming. We just have millions of people dreaming dreams different than our own. Let’s encourage and foster that by enabling these people, and ourselves, to do more—and to do better. And of course, to dream on.

Including CSS in Jekyll

2014-02-28T00:00:00+00:00

Jekyll is a blog aware static-site generator. It’s great for building simple pages like Code Guide or blogs like this one. Lately, I’ve been a big fan of Jekyll’s include functionality.

Now, most folks use _includes for standard partials like a site’s header or footer. Lately though, I’ve been using them to easily include CSS dependencies for fewer page requests.

Say you have three CSS files to include in your Jekyll project. Normally you’d do something like this:

<link rel="stylesheet" href="site.css">
<link rel="stylesheet" href="font-awesome.css">
<link rel="stylesheet" href="syntax.css">

With Jekyll, you can turn that into one file during site generation with includes and YAML front-matter. Here’s an example Gist.

The front-matter tells Jekyll to treat this page as a buildable file rather than simply another asset to copy to the generated _site folder. With that in place, add any _includes you like, and run jekyll serve.

Enjoy!

Introducing Poole

2014-01-02T00:00:00+00:00

Poole is the Jekyll butler. It’s a fully furnished Jekyll setup, designed to be a consistent and flexible starting point for Jekyll projects. It’s available today, and I’m releasing two open source themes with it.

What’s included

Out of the box, Poole is a Jekyll setup that focus on the content first and foremost.

It does so with a limited set of styles and a foundational feature set for any project:

Complete Jekyll setup included (layouts, config, 404, RSS feed, posts, and example page)
Mobile friendly design and development
Easily scalable text and component sizing with rem units in the CSS
Support for a wide gamut of HTML elements
Related posts (time-based, because Jekyll) below each post
Syntax highlighting, courtesy Pygments (the Python-based code snippet highlighter)

Themes

As part of the release of Poole, I’ve created two themes for folks. One, Hyde, has already been available for some time. The second, Lanyon, is brand new today. Each theme includes all the features of Poole, and then some.

Hyde 2

Hyde 1, my first open sourced Jekyll theme, was released in October. Along with the launch of Poole, I’ve redesigned and recoded much of it. Today’s release represents Hyde 2.0. Overall it’s still the same theme, but with many improvements under the hood.

If you’re wondering, Hyde 1.x is available on my GitHub account. However, it’s no longer being actively maintained.

Lanyon

The second theme, Lanyon, is also being launched today.

Lanyon started off as a variation on Hyde to hide the sidebar. Rather than keep the two together, I figured a brand new theme was in order. Thus, Lanyon was born. The best part is the toggleable sidebar is handled all via CSS—no JavaScript is required.

Theme options

Hyde and Lanyon include auto-generated navigation lists with active link highlighting, eight optional color schemes (based on the colors of base16), and reverse layouts (sidebar on the right).

Documentation

Docs for Poole, Hyde, and Lanyon are available in each project’s readme.

The Poole docs include a basic walk-through for setting up Jekyll. Each theme’s readme focuses on only theme-specific features and none of the Jekyll setup process.

Nomenclature

If you’re not familiar with it, The Strange Case of Dr. Jeykll and Mr. Hyde tells the story of a lawyer investigating the connection of two persons, Dr. Henry Jekyll and Mr. Edward Hyde. Chief among the novel’s supporting cast is a man by the name of Mr. Poole, Dr. Jekyll’s loyal butler.

It seemed fitting to name the project after such a man, given all he intends to do—for myself and the rest of you. Plus, it’s a killer naming scheme.

GitHub org

To keep everything neatly organized, everything lives in a new GitHub organization, @poole. It includes Poole, the Poole homepage, and the two themes.

It behooves me to mention that if you have a bug or feature request in any of the Poole-provided files (configs, layouts, poole.css, etc), please open issues in @poole/poole. Anything directly related to the theme (like in hyde.css or lanyon.css), should be addressed in the respective theme’s repository.

Downloads

Snag Poole, Hyde, or Lanyon as you need from each project’s GitHub releases page.

Watch the GitHub repositories to be notified of future downloads, or follow me on Twitter for updates when they become available.

What’s next?

Probably some bug fixes and small feature requests, and soon maybe another simple theme. I plan on looking through my old blog designs for ideas on what to build next. If you have specific ideas, let me know on Twitter.

Introducing Hyde

2013-10-14T00:00:00+00:00

Say hello to Hyde. Hyde is an elegant, open source, mobile first theme for Jekyll, the popular static site generator. It’s super simple, inspired by Medium’s structural design, and is a great starting point for just about any blog.

Check it out on GitHub, or snag a download right away.

Have bugs or feature requests? Open an issue.

CSS and #noparents

2013-10-09T00:00:00+00:00

#noparents is more than an emotionally charged hashtag to express your individuality and independence as an angsty teenager. Turns out it makes a lot of sense when writing CSS, too.

The fuck?

Consider the following snippets of HTML and CSS:

<div class="jumbotron">
  <h1 class="text-danger">Heading</h1>
</div>

.jumbotron h1 {
  color: #333;
}

.text-danger {
  color: #f00;
}

To summarize, we have a .jumbotron h1 that should have red text with the .text-danger utility class. The problem is, due to the specificity (a parent class preceding an open-ended tag) of the first rule, our utility class has no effect. The text will remain dark gray. Shit.

Classes to the rescue

If we modify our approach, we nullify the problem and walk away with some additional benefits.

<div class="jumbotron">
  <h1 class="jumbotron-heading text-danger">Heading</h1>
</div>

.jumbotron-heading {
  color: #333;
}

.text-danger {
  color: #f00;
}

Now, adding the .text-danger class will work as intended. It’s worth noting two things here:

No matter what, this relies on CSS being in the proper order, but that’s always true and out of our control.
Alternate solutions could include using !important or writing overrides to these kind of specific collisions. Both options suck.

Bottom line: removing the parent and using a single class as our selector is the best option, and it pays off.

Dem benefits

So, we wrote more HTML to avoid writing even more CSS. How’s this a win and why does it matter?

To start, we’ve decreased the specificity of our selector. Now, any single class appearing later in our code can take over with ease, just as it does in our updated example. This is how CSS works, and keeping your code to that standard keeps your sanity.
In selectors, classes perform better than elements. Removing that h1 from our CSS rule for the heading helps the browser render the page faster. In many cases this isn’t that helpful, but for larger project (like maybe a CSS framework or web app?) it can make a world of difference.
A series of classes for each component promotes more flexible and durable design systems. The use of .jumbotron and .jumbotron-heading logically groups code, more effectively scopes CSS, and promotes a consistent naming convention.

I’d say those are some solid wins, especially when applied across an entire project.

Applying it

I’ll be the first to say Bootstrap doesn’t do this enough, and it’s to our detriment. Whenever we start work on v4, I’ll be testing this approach. There will inevitably be situations where we need to keep the parents to prevent collisions out of our control (e.g., nav components and dropdowns), but I imagine we can still improve that. We’ll get there in time as we continue to experiment.

Until then kids, remember this: when it comes to CSS specificity, it’s #noparents.

Go Beyond Pixels

2013-05-10T00:00:00+00:00

Next month I’m be heading to Newfoundland for Go Beyond Pixels, a two day design and development event organized by Levin Mejia. I’ll be leading the hackathan on day one and then giving a talk on day two about the future of front-end frameworks and how they’re changing how we do design and development.

I’m excited to be joining an amazing lineup and heading across the continent to hang out with new folks. Look forward to seeing some of you there!

Formatting code on GitHub

2013-04-23T00:00:00+00:00

I see a fair number of issues, pull requests, and comments on GitHub from folks who don’t know how to highlight snippets of code. While this is a problem in it’s own right and we should solve that, I figure I’d drop some knowledge until we figure that other stuff out at GitHub.

Inline code

Inline code is wrapped in backticks—the ``` character.

This is an example of inline ```.

Unlike normal HTML, there is no need to escape angle brackets—GitHub Flavored Markdown does that for you.

Code blocks

Multiple lines of code are easily created by placing three backticks before and after a code block.

```
.element {
  ...
}
```

Language-specific code blocks

You can optional specify a language for proper syntax highlighting on code blocks. Just add the language identifier after the first set of backticks.

```css
.element {
  ...
}
```

The Designer-Developer spectrum

2013-04-22T00:00:00+00:00

I’ve noticed that there are still a few folks who firmly believe designers and developers are two separate types of Web workers. From their perspective, there is no overlap in skills, tools, hobbies, or ambitions, and as such, neither can do any part of the other’s job. That’s an awfully narrow-minded view, and is largely inaccurate.

Designer and developer roles are a spectrum.

You can be all designer, or all developer. You can be mostly designer with some developer, or mostly developer with some designer. Hell, you can even be the golden unicorn of Web workers everywhere if you’re half-n-half (or just both?). Most of the best designers and developers I know are all over this spectrum.

Designers and developers—like any other group of people—shouldn’t be pigeonholed into separate roles. Doing so is damaging to individuals, your company, and the entire industry. Quality products and cultures thrive on employing people with a broad set of skills and at least one specialization. Embrace the sliding spectrum of skills.

I typically think of myself as a designer, but I spend most of my time writing code. Does that make me less of a designer? No, that makes me more knowledgeable about the medium I work on. Any experienced worker from nearly any industry knows how paramount that can be. Know your craft—it’s goal, medium, impact, and end product.

Bottom line? Get talented people together that can have fun and ship awesome shit, and good things will follow. Don’t worry about the labels.

Shoutout to @kneath who I believe originally brought this up at some point, and to that guy on Twitter who prompted this whole thing.

Future Insights Live

2013-04-03T00:00:00+00:00

I’m super excited (and nervous!) to announce that I’m joining an outstanding lineup at Future Insights Live in Las Vegas this month to talk about Bootstrap. In spirit of the conference theme, the title of the talk is Frameworks of Tomorrow, and while that sounds science fiction, there should be a good amount of practical know-off to be had.

Here’s the summary of the talk:

Frameworks have long been an important part of building on the Web. Tools of all shapes and sizes have become common place within our design and development processes, and their prominence shows no sign of slowing down. In fact, we’ll continue to see more and more frameworks in the near future, but perhaps not in the same vein as those of today.

Nearly two years ago, the type of frameworks we use dramatically changed, and they’ll do the same again in the near future. We’ll take a brief look back through not only the evolution of front-end frameworks, but where they may be heading in the next couple years—and how to prepare yourself for them today.

In addition to the talk, I’ll be doing a workshop as well, Building with Bootstrap, about how to best develop with and customize on top of Bootstrap. That will be announced and detailed next week.

Looking forward to seeing a bunch of you nerds there!

Feedback

2013-04-01T00:00:00+00:00

This weekend I set up a new GitHub repo for collecting feedback from you fine folks. I use GitHub every day on account of working there and that whole Bootstrap thing, so it kind of makes sense. I also suck at responding to personal email, especially about the small things. Issues are just easier.

Moreover, issues are public and searchable. This makes my answers infinitely more transparent and hopefully saves you and I time down the line. Email is so inefficient that way.

So, ask a question, leave a comment, or derp with me. Just do it on GitHub.

Make everything an experience

2013-03-20T00:00:00+00:00

There is no such thing as a user experience designer. User experience as a discipline is only kind of a thing in that people generally value good experiences and we should strive to create more of those. Does that deserve it’s own label or job title? Probably not.

Making things into good experiences though, now that’s a thing. We as designers and developers are all just trying to do awesome shit and hoping people find value in it. Good experiences are merely a side effect of creating or doing something people can appreciate. Like calling a cab and watching it drive to you via GPS on your phone. Like buying something online and it arriving the next day.

Like playing music in the office restrooms (as we do at GitHub).

Holy crap (haha) sharing a restroom with other people can be awkward as hell. I obviously have no idea if this is the case for women, but we men are immature and easily perturbed by the restroom activities of other men. Restrooms are cold. People avoid eye contact. No one talks to each other. Every little noise echoes like it’s on a mission of ultimate embarrassment. Not really the stuff great experiences are made of (no matter what your bro tells you about his latest, ahem, victory).

Playing music over speakers is a great way to remove some of that anxiety. It makes people more comfortable, makes the entire process feel less like a silent and mindless ritual, and, most importantly, lessens that whole echo problem. Overall, it feels like a better experience.

Except when you walk up to a urinal and Under Pressure starts playing.

Reintroducing Preboot

2013-02-28T00:00:00+00:00

Before Bootstrap there was Preboot, a collection of LESS variables and mixins originally released in March 2011 under the name Bootstrap.less. Sensing the need for a larger and more comprehensive framework—and not wanting to launch with our internal name—I stole the Bootstrap name from myself and put that code to better use as the groundwork for a much larger vision. To avoid obvious naming issues, I renamed the project and essentially didn’t touch the it for two years.

Today I’m stoked to reintroduce the project with Preboot 2.

Preboot 2 is essentially a backport of all the improvements done in Bootstrap to the original LESS variables and mixins I wrote, with a little extra on top. In the near future, you’ll see some of these once again shared for Bootstrap 3. But enough of that, here are the highlights:

A plethora of useful and customizable variables including grayscale and semantic colors like @black-50 and @brand-success, scaffolding settings like @body-background and @link-color, and typographic shortcuts for font stacks, sizes, headings, and more.
A powerful, semantic, and mobile-first grid system to create your own layouts with ease with just three mixins: .make-row(), .make-column(), and .make-column-offset().
Several vendor-prefix mixins to streamline writing of common CSS3 functions like transitions, gradients, and more.
Several utility mixins for reusing common snippets of code like .clearfix(), .text-truncate(), and more.

Head on over the docs and check it out yourself. Everything is on GitHub, so if you have a feature request or bug to report, just open an issue.

Enjoy!

Improved Terminal hotness

2013-01-13T00:00:00+00:00

A few months ago (!) I wrote about customizing your Terminal prompt. It would seem I had a bug in there that caused some awful wrapping in Terminal, but fret not, there is a solution. Matt Wright was kind enough to hit me up with a fix, so here are the new goods with instructions on how to update.

As you recall, here’s what we’re going for with our new Terminal prompt:

To get us there, open ~/.bash_profile. If you already have a modified prompt, replace the existing similar line with this new snippet. If you don’t have one yet, just add the following snippet:

export PS1='\[\e[0:35m⌘\e[m \e[0:36m\w/\e[m \e[0:33m`git branch 2> /dev/null | grep -e ^* | sed -E  s/^\\\\\*\ \(.+\)$/\(\\\\\1\)\ /`\e[m\]'

Save and restart Terminal. Enjoy!

Terminal hotness

2012-10-18T00:00:00+00:00

The default Terminal prompt is kind of bad—it tells me very little and doesn’t look super fly. After a bit of research, I learned how to customize colors, characters, variables, and show my git branch name.

Here’s what the default Terminal looks like:

ComputerName:~/Directory/Path username $

Plain, and some what informative, but I don’t care about most of this. I know who I am and what computer I’m using, so that can go away. I also don’t need a $ to identify new lines. What I do need is some flavor, the path, and some git info. So I cooked up my own prompt to give me just that. Now, it looks like this:

To use this yourself, open ~/.bash_profile in your favorite editor, and add the following snippet:

export PS1='\e[0:35m⌘\e[m \e[0:36m\w/\e[m \e[0:33m`git branch 2> /dev/null | grep -e ^* | sed -E  s/^\\\\\*\ \(.+\)$/\(\\\\\1\)\ /`\e[m'

Save your changes and restart Terminal. Voilà. Breaking it down some, here’s what’s going on in this snippet, as outlined by this Geek Stuff article:

\e[ starts a new color, while \e[m ends it.
0:35 is the color we’re setting for the ⌘ character. All declared colors take on the format of X:Ym (yes, the m is required).
\w is a variable for outputting the current path. Other available variables include \h for hostname and \u for username.
Lastly, we grep throught the list of branches and output that.

Honestly, I don’t know much about the last part, but it’s a small script I picked up on with a big of Googling and has worked without a hitch so far.

Anywho, that’s it. You can easily swap out the ⌘ special character and change the colors to make it your own. Enjoy!

Don't recreate the platform

2012-10-03T00:00:00+00:00

At Twitter, the Design team is broken down into a number of verticals: corporate, research, mainstream/feature, and platform. The balance of the last two, designing features and designing platforms, represents an important rule of thumb for building on the Web.

Don’t recreate something the platform already provides. This guideline tends to manifest in two areas:

Designing features versus designing reusable components.
Developing new functionality versus utilizing existing functionality provided by the platform.

In the first one, your team has to find balance in building new things within the constraints of a potentially already designed system: your product. Don’t spend time creating new variations on your grids, typography, buttons, navigation, and the like. Instead, spend your time innovating on top of constraints. Focusing on recreating your most common components in every project only undermines your own efforts. Identify those constraints and make them work.

In the second area, the issue is using what the platform gives you or spending time to recreate that existing functionality. Why recreate checkbox functionality when you can simply use checkboxes? In most cases, the former means additional markup, CSS, and JavaScript. In the latter, you get all that behavior for free simply by using native HTML. Now, this doesn’t apply to every situation: sometimes you need to extend existing functionality. In that situation, it becomes an issue of return on investment, and it’s up to your team to make that call.

Don’t let rules cripple the innovation or progress of your team, but try to design within meaningful constraints. Great design is always mindful of striking out on your own and respecting the platform you’re developing on.

GitHub bound!

2012-09-30T00:00:00+00:00

While I announced it on Twitter and Hacker News, I want to top it off with a quick blog post: I’m joining GitHub this October! I’ll be a designer on the Enterprise team, working with a small group of awesome engineers to make GitHub better, faster, and stronger for teams everywhere.

I’ve been a user of GitHub for years, having watched repos to track interesting projects. It was always useful, but I it wasn’t until we released Bootstrap in August 2011 that I really saw its potential. Since then, I’ve used it just about every single day to manage thousands of issues, push code, and more. Beyond the product itself, it’s the people that most attracted me to GitHub. The company is almost entirely developers and designers, and that’s a powerful and inspiring combination.

Lastly, I want to once again reiterate that @fat and I will continue to work on Bootstrap with a 2.1.2 release dropping in the coming weeks. Beyond that, we’re working with @cra at Twitter to move Bootstrap into it’s own organization on GitHub so we can build out a larger team of dedicated contributors to make Bootstrap even better.

I’m stoked to be joining GitHub and couldn’t be more excited about the future of Bootstrap. Thanks everyone who have made both so great.

Take action

2012-08-17T00:00:00+00:00

Today’s guest post on @fat’s blog by @divya is a pertinent one that reflects on the community we work and play in. Her point is best articulated with this line:

By idolising people, I gave up on my opportunity to change the world, learn something exhilaratingly new, call out the wrongs done, and contribute to right some of the wrongs.

And this one, referring to her own successes:

None of these required any particular skill or talent, they are merely results of taking an action.

Keep pushing. Don’t simply do what the rest of us do—do it differently, do it better, do it faster. Take a stance and have an opinion. Don’t be afraid to be wrong. In fact, you should expect to be proved wrong. We learn the most when we take a chance on something and discover our assumptions were incorrect. Taking risks with our own ideas is how we learn to be stay both humble and ambitious. It’s a delicate balance, but one of the most important—you have little to lose and so very much to gain just by being yourself.

So, burn your idols, but most importantly, take action.

GitHub all the things

2012-08-09T00:00:00+00:00

I’ve GitHubbed all the things today—more on that shortly—and while I was doing that, I broke the Internet for a decent amount of folks. I apologize for that and will do my best to ensure it won’t happen again. Here’s some background and an explanation for what happened.

GitHubbing

Previously, my blog used WordPress and was hosted on Media Temple. Everything was version controlled with git already, making things relatively straightforward in case something went wrong, but it was still a pain. Hosting and updating my blog was tedious, having to install WordPress and it’s plugins, pushing code, FTPing in case something broke, and SSHing into my server to pull it down. Not so simple.

Now it’s all GitHub, all the time. This blog is still written in Markdown, but it’s powered by Jekyll and deployed using GitHub Pages. It happens in one fell swoop: just push. Super simple.

Fellow Twit and broheim Dave Gamache also has a nice write-up on using GitHub Pages, so be sure to check that out. His blog setup was the inspiration for this entire endeavor and his support in the process was invaluable.

I broke the Internet

No joke, I messed some stuff up, and again, I apologize for that. Here’s what happened as succinctly and accurately as I can recall.

Early Wednesday morning I created a new GitHub user page using the repo name markdotto.github.com. At this point, all is well.
To make the new GitHub page point to my domain, I added a custom domain. At this point, the shit starts hitting the fan: all my projects are now being pointed to markdotto.com.
As the DNS propagated, the URLs of my Unofficial GitHub Buttons began to change from markdotto.github.com/github-buttons to redirect to markdotto.com/github-buttons, resulting in security errors as the URLs of the iframe were no longer resolving. To make matters worse, once I noticed the problem and attempted to resolve, some of those URLs were still being cached.
At this point I figured out the problem: despite what the GitHub Pages docs say, you cannot use a custom domain on your user page without it affecting your project pages.
To fix all these issues, I have nuked the markdotto.github.com repo and created a new markdotto.github.com/mdo one to point to my personal domain. Alongside that, I bought a new domain and pointed the GitHub Buttons project to that using the same technique.
This change requires everyone using the buttons to update the src on their iframe to begin with http://ghbtns.com/github-btn.html?.

And that brings us to now. Caching might still present security warnings for folks, but there isn’t much I can do about that at this point. From here on out, the core issues should be resolved.

Moving forward

Despite all the hiccups on the GitHub buttons, I did manage to roll out some updates for it tonight:

Retina icons for in the buttons
Changed “Watch” button’s text to “Star” (the type is still going to be watch in the code until the API changes)
Added caret to the count like on GitHub.com
Overhauled CSS better match GitHub.com buttons

Check it out at http://ghbtns.com.

I also pushed some changes to this blog and, after some miscellaneous cleanup on the code, will be propgating them to the Bootstrap blog shortly since it uses the same template. New to the blog are larger tweet buttons on articles (better for mobile), related posts on each post page, and a streamlined homepage for faster loading. More changes to come, so stay tuned.

Simpler

2012-07-11T00:00:00+00:00

Writing about simplicity is difficult. It’s tough to not sound egregiously grandiose or obnoxiously obvious, but sometimes we all need that. And right now, I need that, if only for my own sanity.

Everything needs to be fucking simpler.

This manifests itself in a number of ways, none more apparent to me than in interface and product design. Consider how many successful products you use that focus on one amazing thing: Byword, Dropbox, Rdio, Uber. All these products and their interfaces are the result of paring down an idea to only the most essential. People love this stuff.

We want—need?—fewer, higher quality things in our lives. We crave simpler at every turn. As designers we can provide that.

Comma-separated values in LESS mixins

2012-04-05T00:00:00+00:00

With some CSS3 properties, like box-shadow or text-shadow, it is possible to have a comma-separated list of values for multiple shadows like this:

.element {
  box-shadow: 0 1px 3px #eee, 0 5px 10px #f5f5f5;
}

This works well with regular ol’ CSS, but with CSS3 support being what it is, we sometimes want to use LESS mixins for properties like box-shadow. Given we need various vendor prefixes in our mixin, our example changes to this:

.box-shadow(@shadow) {
  -webkit-box-shadow: @shadow;
     -moz-box-shadow: @shadow;
          box-shadow: @shadow;
}
.element {
  .box-shadow(0 1px 3px #eee, 0 5px 10px #f5f5f5);
}

However, when you use LESS with this approach, the compiler will choke on the unexpected comma between those two shadows. With recent versions of LESS, one might think @arguments is the solution, but that only gets you past the compiling problem. You’ll still end up with a final output that strips that ever important comma between the two shadows. While the most straightforward approach doesn’t work, there are at least two ways of making comma-separated values work in LESS.

The first is to use a local throw-away variable:

.box-shadow(@shadow) {
  -webkit-box-shadow: @shadow;
     -moz-box-shadow: @shadow;
          box-shadow: @shadow;
}
.element {
  @shadow: 0 1px 3px #eee, 0 5px 10px #f5f5f5;
  .box-shadow(@shadow);
}

This works because we’re declaring a value that’s a literal string because it’s a variable and the mixin respects the entire contents of that variable, including the comma. We currently use this method across Bootstrap for it’s simplicity and because we didn’t know of any other options at the time until we discovered this second method.

Your other option is to escape the value when you call the mixin:

.box-shadow(@shadow) {
  -webkit-box-shadow: @shadow;
     -moz-box-shadow: @shadow;
          box-shadow: @shadow;
}
.element {
  .box-shadow(~"0 1px 3px #eee, 0 5px 10px #f5f5f5");
}

This effectively does the same thing as the local variable: it ensures the value passed to the mixin is a string and not a list of options compressed into a single value. The syntax is a still fairly clear, but also more succinct. One potential downside to note is that this method doesn’t enable you to place line-breaks and spaces between values to stack them in your code for improved readability, meaning this wouldn’t compile:

.element {
  .box-shadow(~"0 1px 3px #eee,
                  0 5px 10px #f5f5f5");
}

If that’s your style, you can accomplish this with the local variable method:

.element {
  @shadow: 0 1px 3px #eee,
             0 5px 10px #f5f5f5;
  .box-shadow(@shadow);
}

All in all, it depends on your own style and conventions. Whatever method you opt for, I do recommend being consistent with it throughout entire projects.

It’s worth noting that in the next version of Bootstrap, we’ll be using the second method (escaping when we call the mixin). It’s less code to write and those familiar with LESS shouldn’t be caught off guard by the escaping.

Learnings from open-sourcing Bootstrap

2012-04-02T00:00:00+00:00

Bootstrap wasn’t my first open-source project, but it’s definitely the largest and most successful, largely thanks to Jacob and the community of course. Since open-sourcing Bootstrap seven months ago, I’ve realized a few things about open-source that I’d like share with you all.

Communication is paramount

No matter the success of an open-source project, folks using your hard work begin to depend on you and what you’re doing. Communication becomes more important as the age and use of the project increases. When’s the next release, and what will it include? Does the license allow for X, Y, or Z? What about support for third party plugins like A or B? Questions like this are bound to arise, so you have to be proactive to fight the brunt of it and keep your sanity.

To do that in Bootstrap, we use our GitHub wiki to share a roadmap, license info, a changelog, and even contribution standards. We also use our Twitter account and new blog to post about changes and releases.

People can be jerks

Let’s get this one out of the way, because it doesn’t happen often, but when it does, it sucks in a big way. Just like in real life, some folks can be jerks online. This can be from lack of context on either person’s end, assuming someone’s an idiot, or simply being too aggressive. It sucks, but it can happen. When it does, keep a level head and get past it so you can help all the other awesome folks out there.

People can be fucking awesome

Speaking of awesome, sometimes people can just be fucking awesome. My own personal credo is to “Help awesome people do awesome shit” and I stand by that through and through. To date, Bootstrap is the best way I can help talented folks do their work, and so far it’s been a blast. There are plenty of smart, diligent, and hardworking people out there who just want to help you out or learn from you. Embrace it, learn from it, and pass it on.

Getting complete context on issues is hard

Just like bug reports in a typical web project, getting the complete picture around an issue submitted on GitHub can be difficult. Inability to reproduce a particular bug, difficulty in communicating across languages, dealing with opposite levels of experience, working with different versions of the same codebase, and more are all cases that you might come across on an open-source project.

Figure out a system that works well for you (in many cases, we require a live demo or jsfiddle) and communicate that to your followers. Stick to it and know that sometimes it just takes a bit more time and patience.

It’s all worth it

I hope you come away knowing the positive outweighs the negative in this post because when it comes right down to it, open-sourcing Bootstrap was one of the best things to happen to me personally and professionally. I’ve been able to help thousands of people do their work better and faster—all while helping them learn a bit more as they go. I’ve gotten to work with a lot of awesome people, had a blast doing it, and learned a great deal. Bootstrap has been worth every second I’ve put into it and I hope to keep it up for a long time to come.

TL;DR: Open-source is awesome, sometimes work is hard, be excellent to each other, do what you love, fuck yeah.

Bootstrap 2.0.2 released

2012-03-12T00:00:00+00:00

A new version of Bootstrap is out today with a ton of bug fixes (over 100 closed issues), documentation improvements, and a few new features. Here’s a curated list with some details where appropriate. Download the latest from the Bootstrap docs.

Before we begin, I want to note that you’ll have to upgrade to the LESS 1.3 to compile 2.0.2. For those using LESS.js, download the latest. For those using LESS via npm, run this in your Terminal to update:

sudo npm install less -g

And you should be good to go. Not downloading the latest or running the update means you’ll see LESS spit out some nasty errors and it won’t compile.

Now, let’s check out what’s new.

Documentation updates

All docs pages now have distinct titles, such as Scaffolding · Twitter Bootstrap.
Updated the Apple touch icons (now black on black instead of the blue grid) and fixed the links to them in the docs.
Added new global styles docs section to the Scaffolding page.
- Required use of HTML5 doctype
- Overview of global typographic and links details
- Mention of our embedded CSS reset via Normalize.css
Added version number to the download button on the docs homepage.
Updated progress bars section to simplify how the classes stack and more clearly indicate the available optional classes and styles.
Added a new example, SoundReady.fm, to the homepage
Added various sizes to the docs for button groups

Resolved bugs

Removed all IE7 hacks and floats from .input-prepend and .input-append, however, this requires you to ensure there is no whitespace in your code between .add-on and the input.
In .input-prepend and .input-append, added ability to use add-ons on both sides when you chain the selectors.
Updated lingering .btn-dark reference to .btn-inverse.
Fixed issue with content being cut off in .tab-content for tabbable sections.
Updated .navbar .container to use width: auto; to start and then reset the fixed widths via the #gridSystem mixin (it’s a little dirty, but required to avoid adding another class).
Modal footer buttons are now aligned by their parent via text-align: right; instead of float: right on the button level. This was changed to allow the use of .pull-left and .pull-right to align buttons easily. Double check your button order with this change!
Fixed problem where default striped progress bar was green instead of blue.
Fixed CSS selector used for input and textarea grid sizes to properly apply the CSS (was input > .span* and now is input.span*).

New features

Horizontal dividers support added to nav lists
Added basic version of badges
Added visible/hidden classes for devices
Added support for buttons in input-prepend/append component
Added .navbar-fixed-bottom support
Added .dropup support for dropdown menus to pop them upward instead of downward (this is automatically done for the newly added fixed bottom navbar).
Added mixin for new image replacement technique
Added pause on hover for the carousel
Added tons of new variables for typography, buttons, forms, dropdowns, navbar, and more for the LESS pros out there. These variables have also been reflected on the Customize page.
Added new horizontal description list variation
Added .disabled class support to the pager component (also added a mention of this to the docs)
Added .well-large and .well-small classes for extending the well component

Responsive changes

While not a bug fix or a docs update, I wanted to specially call out this responsive CSS change. We have moved the padding from .container within the <767px layout to body. This ensures a bit more control over containers, rows, and more when setting background colors and such.

New grid mixins

Last, but not least, Jacob has rewritten the grid system mixins to utilize some new features in LESS 1.3. Nothing changes for the compiled CSS, but the LESS we use to generate that code is more succinct and can now fully utilize any number of grid columns when you customize.

For a full issue-by-issue rundown of the release, check out the now closed 2.0.2 milestone on GitHub.

Stop the cascade

2012-03-02T00:00:00+00:00

Cascading styles is at the core of CSS—hell, it’s in the name—but experience has shown that building systems with too many cascading styles can be detrimental. Some times it’s completely necessary to just stop the cascade.

Let’s take the modal of Bootstrap as an example.

<div class="modal">
  <div class="modal-header">
    <h3>Modal title</h3>
  </div>
  <div class="modal-body">
    <h3>Modal subheader</h3>
    <p>Content for the modal, like additional text and forms, goes here.</p>
  </div>
  <div class="modal-footer">
    <button class="btn">Done</button>
  </div>
</div>

Notice how we namespace classes at key levels—each class name begins with modal-as a prefix. Class name prefixing makes our code more durable and easier to maintain, but it also better enables us to scope styles to only the relevant elements.

Consider this snippet of CSS used to style the modal heading:

.modal h3 {
  text-align: center;
}

By using this generic selector, we inadvertently change the styles of the h3 in the .modal-body. We’ve introduced an instance of cascading styles—any h3 throughout the .modal will be center aligned. Therefore, if we wanted the other instances of h3 to be left-aligned, we’d have to override our brand new styles with something like this:

.modal .modal-body h3 {
  text-align: left;
}

It’s worth noting that this example isn’t without its flaws, but that’s the point. With a little more time and thought, one can easily avoid this problem, avoiding extra lines of code and more complications in the overall system. Had we done things differently and altered our selector, our CSS might look like this:

.modal-header h3 {
  text-align: center;
}

By limiting the scope of a selector, we reduce the likelihood that we need additional code down the line by strengthening each component and limiting the effects of their styles. If done right, we can create an entire system of independent and durable, yet still flexible, components. It’s a promising approach I think, but one not to employ with an iron first.

Some CSS should be allowed to cascade. Base typography, links, and the such are prime examples of something not to redeclare over and over again. This would only serve to weigh down a project and make it even more unmanageable. Instead, the goal as always is to strike a balance.

Find ways to isolate components and make them more durable by limiting the scope of their CSS. You’ll discover that components can be more easily rearranged without causing adverse effects and the amount of code necessary will likely decrease.

Designing dropdowns in Bootstrap

2012-02-27T00:00:00+00:00

A recent question on Stack Overflow regarding Bootstrap’s dropdown menus got me thinking I should do a few posts on some of our design decisions. Folks seem curious about certain aesthetics and behavior, and I’d love to shed some light if I can. Beyond explaining existing decisions, I hope these posts can help guide future updates to the docs as well.

To start, let’s talk dropdowns.

Appearance

Before Bootstrap 2 launched, our dropdowns were confined to the topbar (now the navbar) and were thus styled to be white text on black background. This fit with what we do on Twitter.com and helped the topbar feel more complete with the dropdowns as a natural extension of that style. However, we knew we wanted dropdowns to work in a number of components, so we flipped the color scheme back to black on white.

This resulted in improved contrast for the text (especially for typeahead) and made dropdowns work much better for buttons and the like. This gave us a standardized design and cleared up a lot of CSS had we chosen to keep the previous inverted colors. Simpler appearance, simpler codebase.

Behavior

There has always been contention between hover and click events in interaction design. In general I am against using hover as a trigger because things can get messy quickly. The best (worst?) example of this may have been hovercards on Twitter.com from a couple years back. They were great in terms of their content and utility, but not so great in the fact that they seemed to fire without the user intending them to. Inevitably we dropped them and now have a mini profile modal with the latest redesign.

In Bootstrap, we use a mix of both hover and click though–hover for tooltips and popovers, clicks for dropdowns and more. What it really boils down to is user intent. The purpose of a hover state is to indicate something is clickable (underlined text) or to provide some quick information (full URL in a tooltip). The purpose of a click is to actually do something, to take an explicit action. Opening a dropdown is an explicit action and should only happen on click.

Additional notes

It behooves me to mention a few other quick thoughts on our dropdowns:

The aesthetic was derived from menus OS X. They’re super simple, elegant, and scalable.
Prior to open sourcing Bootstrap, the dropdowns were actually fired on hover. We changed this because as soon as your cursor leaves a dropdown, it disappears.
The caret in a dropdown link is the equivalent of underlining a link: it provides some affordance for what will happen when you click this element. Don’t mistake that for providing enough information to pop the dropdown on hover though.
Because we use a click to trigger the dropdown in most implementations, there is no option for a parent link (one of the primary complaints in that Stack Overflow article). Pointing back to OS X and other toolbars, I don’t see this as a huge issue as it promotes our advocacy of using clicks to carry out an action instead of hovers.

And that’s it—dropdowns in Bootstrap explained. Stay tuned for more posts like this in the future. If you’d like me to elaborate on another particular feature of Bootstrap, please hit me up on Twitter or send me an email.

Bootstrap 2.0.1 released

2012-02-17T00:00:00+00:00

After a few weeks of hardcore bugfixing, Jacob and I are happy to finally push out a fairly stable patch to Bootstrap 2 that resolves a bunch of issues. Here are the highlights on what’s new:

Previously the docs called for use of .control-label in the examples, but the CSS didn’t make clear use of it. This class is required for horizontal forms and has been reflected in the CSS.
We’ve tried our best to improve rendering of buttons and icons across all browsers. Some issues remain; Firefox throws an !importanton line-height for inputs, so that’s the big one.
We refined the label component style to move away from uppercase.
Added the black button option, .btn-inverse.
Added a mini button class, .btn-mini.
We had to re-add the protocol, http: to the HTML5 schim because IE7-8 wouldn’t recognize it, dropping some HTML5 support for those browsers and introducing major performance issues.
Resolved some issues with responsive layouts where media queries would overlap at 768px and 980px.
Rearranged Scaffolding docs page to split fixed and fluid grid systems.
Tons of docs updates for typos and language changes.

For a full list of bug fixes in this release, check out the 2.0.1 milestone on GitHub. All in all, we closed over 100 issues with over 150 commits—not bad for a patch release! A big thanks to all who reported bugs and added pull requests, we couldn’t do this without you nerds.

Scope CSS classes with prefixes

2012-02-16T00:00:00+00:00

When building a CSS design system like Bootstrap, it’s important to keep things simple, durable, and flexible. This is no easy task, especially on larger teams and projects where the number of components can become quite high. To help improve this situation in a CSS design system, you might consider using prefixed classes instead of chained classes.

Taking the chained classes approach, your CSS selectors might look something like this for a given set of components:

.success { ... }
.btn.success { .. }
.alert.success { ... }

We have here a global base class, .success, that might house all the commonalities between successful buttons and alerts. Then, at the individual component level, we add on or override as necessary. However, this wide open class and chained approach exposes developers to a number of questions and potential paint points:

What’s that base class stand for?
What elements will be affected at the root level?
How many elements have .success chained onto them?
Can it be extended further to more components?
What if one instance of .success uses green text on a white background while another uses white text on a green background?

And those questions barely scratch the surface. This solution isn’t necessarily bad, but when scale, brevity, and flexibility are your top requirements, it might not be the best idea. A better solution might be using prefixed classes.

Prefixed classes guide developers towards a simpler and more maintainable direction for building an extensive CSS design system. Here’s what we have if we take away the generic base class and scope things per component with prefixes:

.btn-success { ... }
.alert-success { ... }

This way, the base class is at the component level and not the entire system level. In other words, our base classes have become .btn and .alert, not .success. There’s no bleeding of styles or behavior from one component to another here because we treat components in a “successful state” as an idea across the design system. That is to say, we have a shared idea of what “success” looks for buttons and alerts, but the execution is scoped entirely to each independent component. No questions of where common styles are used and no concern of unintended effects, making each component more durable and flexible.

While a very tactical and detail-oriented practice, building components that inherently isolate themselves for improved modularity and customization in a system like Bootstrap makes for better code and a more enjoyable project down the line.

Slides posted from the Twitter Open Source Summit

2012-02-06T00:00:00+00:00

If you didn’t have a chance to make it out to last week’s event, you can view the slides on Speaker Deck from our Bootstrap 2 announcement at Twitter HQ. In our presentation, Jacob and I walked through a brief update and history of Bootstrap, some of the new hotness in v2, and a quick look at the future of the toolkit. Also, be sure to check out the slides from Rob Sayre’s Hogan.js talk and Sean Herron’s NASA & Open Source talk.

Thanks again to all those who made it out, helped test Bootstrap 2, and contributed to the project. We couldn’t do it without you nerds!

Bootstrap 2 ready for testing and feedback

2012-01-24T00:00:00+00:00

Update: Bootstrap 2 is out and ready for you to dive in. Head over to http://getbootstrap.com to check it out!

My fellow nerds, I’m very happy to announce that Bootstrap 2 drops January 31. To ensure we have the very best release possible, we’re opening up the branch and encouraging everyone to jump in and test the new code. We have a lot of new features, rewritten documentation, and use cases to test with the addition of media queries.

This week at Twitter is Hack Week and Jacob and I have dedicated the entire week to working on Bootstrap 2 to get ready for the release. There’s a ton to do, but we’re confident we can get it all done with your help testing and providing feedback on the new hotness.

Here’s how you can help:

Head on over to GitHub and checkout the branch, 2.0-wip. It’s our essentially our master branch right now.
Don’t want to check out any code? We’re hosting the latest version of the docs so you can easily load it up on devices and such for testing. (Please don’t host any other version of the docs for now!)
Load up the new docs in your favorite (or, ideally, your least favorite) browser or device and start testing.
When you find a bug or have feedback, open a new issue on GitHub. Tag it as 2.0-wip right away so we know to prioritize it. Please include as much context and information as possible. If it’s a visual bug, please include a screenshot. If it pertains to javascript, consider including a jsfiddle.
If it’s a code fix you can make yourself, go ahead and submit a pull request to 2.0-wip. Be sure to read the Contributing to Bootstrap wiki page first though for a bit of insight into our code practices. (Unsure how to submit a pull request? Learn more here.)

We’re super close to getting Bootstrap 2 out, but we need your help to make it the best it can be. Any help you can spare would be fantastic and much appreciated.

Thanks in advance, and see you next Tuesday with the finished release!

Bootstrap in A List Apart No. 342

2012-01-17T00:00:00+00:00

Not too long ago I was asked by the A List Apart crew to contribute an article on Bootstrap. After some delays due to the Twitter redesign, the holidays, and some run-ins with the flu, I’m very happy to announce that the article has been published in today’s new edition.

The article, Building Twitter Bootstrap, focuses on the decisions and processes that went into creating Bootstrap. In short, a super small group of developers and I got together to design and build a new internal tool and saw an opportunity to do something more. Through that process, we saw ourselves build something much more substantial than another internal tool. Months later, we ended up with an early version of Bootstrap as a way to document and share common design patterns and assets within the company.

After a year of working on it on nights and weekends, we open-sourced Bootstrap in late August 2010. It’s since become the most popular project on GitHub with over 14,000 watchers and 2,400 forks. There’s a lot more in store for Bootstrap, including v2 launching in the coming weeks, and I couldn’t be more excited about the coming months at Twitter.

Also, a special thanks to Mandy Brown and Krista Stevens as editors for the article. Without Mandy’s incredible ideas and insightfulness, and Krista’s editing and article preparation, the article wouldn’t have happened. It’s been a pleasure working with both and I hope to do so again in the future.

Head on over to A List Apart and give it a read.

New grid system coming to Bootstrap 2

2011-12-16T00:00:00+00:00

Bootstrap 2 brings new responsive features and a large part of that is the grid system at its core. With BS2, we’ll be leaving behind our 16-column overlords and moving to a flexible 12-column grid system. Nothing substantial should change in your use of Bootstrap, but I wanted to share some thoughts about this new (to Bootstrap) approach.

To date, mobile and tablet devices were all virtually ignored. No more–Bootstrap 2 will provide support for mobile devices out of the gate. Responsive features will be available and should provide at least some level of support for all our major components.

By leaving the 16-column grid system behind, we save some headaches and streamline some code. 16-columns required extra CSS for a 3-column layout and we were including an extra 8 columns for those wishing to add 24-column support. No more. We’ve removed the extra CSS and gone to 12-columns, all while retaining the same overall default site width (940px) and adding responsive variations.

Not much changes for those using Bootstrap when we release 2.0. We’ve been using this grid in the our development of 2.0 for several weeks now and are quite fond of it. Just be sure to check your column sizes and test your projects on mobile and tablet devices when you upgrade.

Follow along with Bootstrap 2’s development on GitHub with the 2.0-wip branch.

CSS commenting strategy

2011-12-12T00:00:00+00:00

After a few recent projects, I’ve realized a good commenting strategy is necessary in CSS (and any other language really). After running into problems of our own with mysterious or vague code, I figure I’ll share my general set of quick and flexible guidelines for commenting in CSS.

Here’s what my typical (non-LESS) CSS file looks like:

To start, each file should include a repeated name and short description. While the name here can be the same as the filename (as I’ve indicated), combined with the description, it can help you add clarity for other designers. For instance, if you compile multiple CSS files, these comments can guide you in reading the final file.

Moving along, every major component is broken down into its own section. Not shown above is that each section has two to three lines after it to space things out. Subsections of that component have their own sub headings as well to further break things apart for readability and documentation.

Really though, the last two types of comments are the most important to me. The others are honestly more of a formality and sanity check as searching is just as fast in most cases. These last two are what keep you and your coworkers happy. Take this example of a typical comment and snippet of CSS:

The comment adds no value to anyone because it doesn’t tell you why this code is there in the first place. Here’s what might work a bit better:

While not the greatest example in the world, it illustrates the point. The last type of commenting, inline notes, works well with this as it provides line-by-line justification for properties. Even though some folks might know \9 is an Internet Explorer hack, not everyone does and comments don’t hurt anyone.

CSS, and any code for that matter, is much more legible and maintainable with the right comments. The why’s and inline context matter most for justifying why blocks of code appear in your files in the first place. Most importantly, commenting makes or breaks a team’s ability to quickly execute and update projects. Figure out your own solution, carry it through, and watch your projects become easier to maintain.

Formatting vendor-prefixed CSS

2011-12-06T00:00:00+00:00

I’m a sucker for CSS conventions. Beyond CSS property order, general code formatting, spacing, and commenting are all up for some discipline. To keep things nice and tidy, and to save time in the future, I do my best to streamline my code. Figuring out the right formatting for CSS properties, especially properties like border-radius and box-shadow, is near the top of my list.

Take for instance this block of CSS:

Straightforward enough. We have our vendor prefixes first, ordered by character length (a complex of mine I’m afraid), and ending with the official spec for that property. Great, but we can do better!

Ah, much better! Why? Well, if you’re a fan of code editors like Textmate, Coda, or Sublime Text 2, then you can easily edit multiple lines at a time. In Sublime Text 2—my editor of choice—I just have to hold Option while clicking and dragging to select multiple lines to edit.

With the values lined up, I can not only read my code faster and easier, but I can edit it faster and easier as well. A little bit of guidance on code formatting goes a long way for your own sanity, and those of your peers.

CSS property order

2011-11-29T00:00:00+00:00

CSS property order matters, especially on larger teams with several engineers and designers all contributing code. I know it’s been discussed, but frankly there’s always room for improvement and alternate approaches. In a few projects at Twitter, we added the constraint of consistent CSS property order to make onboarding new folks easier, debugging faster, and expectations of what exactly a block of CSS does that much clearer (without viewing it in the browser).

High level overview

At a high level, here’s our breakdown:

position
display and box model
font, leading, color, text
background and border
CSS3 properties like border-radius and box-shadow
and a handful of other purely visual properties

We hadn’t really seen an approach like this in any other projects we’ve worked on. It mixes the common structural and alphabetical approaches into one in an effort to ensure our property order is logical, scannable, and all-encompassing. We wanted an order that mapped to how we mentally visualized DOM elements and—to an extent—how Webkit’s Inspector presents properties.

Show me!

Getting more specific, here are some blocks of CSS might look with this property order in mind.

Here you can see positioning, box model (height and padding), and visual (background-color, border-bottom and box-shadow) in their proper order. This flows in such a way that you can discern that this is a fixed dark gray bar with a drop shadow–you know exactly what it is you’re dealing with as you read line-by-line.

In this example, we have only box model and visual. Notice that for box model, we have dimensions first with min-height and padding (as that adds to the overall width of an element). For the visual elements, background-color and border come first because those inform you how this element starts to look (e.g., a gray box witha border). border-radius and box-shadow follow that because those are additional visual treatments that add to the base look and feel.

Use what works for your team

This approach seems to work well for us and our teams without adding too much overhead. All you need to do is create a series of rules and stick to them with your team and this because a very successful tactic for organizing and maintaining CSS. No one solution is teh best, so keep that in mind and adjust as you go.

Introducing (Unofficial) GitHub Buttons

2011-11-26T00:00:00+00:00

Today I’m stoked to announce the release of my unofficial GitHub buttons! For months I’ve wanted to provide consistent, easy-to-use links back to my projects’ source and documentation on GitHub. A couple of weeks ago I was finally able to create a decent method of doing just that. Now, I want to share them with everyone and get feedback from the community.

Functionality

For their initial release (and due to lack of time and expertise), functionality is limited to a static link back to your repo and dynamic counts for the number of watchers and forks on any public repo. In the future I’d love to expand on this to support user profiles and—one day—dynamic buttons via oAuth.

How to use

Using these new buttons is as easy as adding an iframe and setting some paramaters in the URL. It’s fast, easy, and pretty lightweight. The best part is that these are hosted on GitHub pages, which means you don’t need to host the code yourself. Just add and go. It also comes with a few options: watch or fork button, count or no count, and default or large size.

The two buttons above are live examples of Bootstrap’s watcher and fork counts. Everything but the size of the iframe is configurable via URL parameters. (This was the easiest and fastest way for me to get this project out the door.)

Get it on GitHub

You can find the source on GitHub. Feel free to download, fork, or watch it from there. If you have any feedback or want to contribute to the project, go ahead and open an issue or submit a pull request.

Coming in Bootstrap 2: Improved documentation

2011-11-21T00:00:00+00:00

Bootstrap 2 is well under way and has lots of awesome new features and improvements baked in already. One of the most exciting things for me (believe it or not) is the updated documentation.

With Bootstrap 2, our goals for improving documenation includes:

Greater visibility into the variations and options for all components in Bootstrap
Less filler and more technical documentation for easier reading and learning
Continued use of live examples right alongside the technical details of how to use any component

We’re still not done with it yet, but we’re making lots of progress. Some of the highlights thus far include splitting the docs into several subpages for faster load time and ease of use while also revamping the homepage to contain nearly all our marketing messaging and key links. The idea is to keep Bootstrap accessible to all by bubbling up the easy stuff first and easing into the more detailed information as necessary.

As always, lots more is planned and if you have feedback, please file an issue on GitHub so we can address it.

Breaking down Bootstrap

2011-11-14T00:00:00+00:00

There are at least two ways to approach organizing an entire system of components like Bootstrap:

Everything in a small set of CSS files for compactness, ease of use in building on shared styles, and fewer requests if used via media queries.
Individual files for nearly every component for greater customization when compiling, making styles easier and more straight forward to find.

Both have their pros and cons, but I’m most anxious in hearing about your preferred methods. For context, here is how Bootstrap’s LESS files are structured today:

bootstrap.less
variables.less
mixins.less
reset.less
scaffolding.less
type.less
tables.less
forms.less
patterns.less

If we were to split things out even more, our files could look like this:

bootstrap.less
variables.less
mixins.less
reset.less
scaffolding.less
grid.less
type.less
tables.less
forms.less
navbar.less
dropdowns.less
tabs-pills.less
breadcrumb.less
buttons.less
alerts.less
pagination.less
modals.less
popovers.less
twipsy.less

While that’s a lot of individual files, it becomes much easier to customize Bootstrap by simply removing import rules from bootstrap.less and recompiling. If Bootstrap were a standalone app, I’d recommend the former, but as it is a customizable toolkit, the latter feels like it could be better. We’re leaning towards the latter with version 2.0–more files, but greater customization for all.

Thoughts? Tweet and let us know.

How to deploy sites via GitHub

2011-11-02T00:00:00+00:00

After one my last posts about GitHub and how it’s saved my ass a number of times, I had a few requests to detail just how I deploy sites with GitHub. So, here we go!

First, some background

I host this site, and a number of others, with Media Temple. My code, however, is verson-controlled with GitHub, where I have a paid account, the $12/month plan. That’s namely for the remote-hosted private repos they provide, but I also use GitHub to contribute to a few repos, watch numerous others, and of course maintain Bootstrap.

Using GitHub for site deployment is pretty straight forward. However, to get started, you need to have a hosting provider that allows SSH access and has git installed. If you don’t have SSH enabled, search your hosting provider’s docs. If you need to install git, a quick Google search reveals some solid enough posts about it.

Now, the how-to

After covering the background details, the rest of this how-to assumes you have a paid GitHub account (for the private repo), SSH access enabled, and git installed on your server. Here’s a quick summary of what we’ll be doing:

Setting up a private GitHub repo
Cloning your repo locally
Add some code
Cloning your repo via SSH
Handling maintenance
Few other tips

Now, let’s get to it!

1. Setup your private GitHub repo

The first step is to create a private repo on GitHub.com. It’s the same as creating any other repo, you just have to check the right option in the setup and you’re golden.

When you create your new repo, just check the option that says “Only the people I specify” for repo access. Now you have a brand new, completely empty, and private repo ready for code.

Note: I prefer a private repo for my personal site as I don’t see any point in anyone viewing those files or contributing to them. Feel free to use a public one, but be warned anyone can browse your stuff.

2. Clone the repo locally

Before we can do anything with our repo, we need to clone it locally and add all our code to it. To do so, just snag the URL of the repo. You’ll find it on your new repo’s page on GitHub.com; it looks like this:

Copy that (manually or via the little clipboard icon) and open up your favorite command line tool (I prefer Terminal). Browse to where you’d like to keep your code locally (on a Mac, I prefer Sites) and we’re ready to clone that repo.

$ cd Sites/
$ git clone [REPO_URL]

If successful, you’ll see something like the following:

$ Initialized empty Git repository in ~/Sites/[REPO_NAME]/.git/
$ Warning: You appear to have cloned an empty repository.

That means you’ve successfully cloned your new repo and that it’s empty–all good things. You know have an empty directory called [REPO_NAME] in your sites directory. Now, let’s add code.

3. Add your code

The key thing about this step isn’t what you add neccesarily, but how you add it. After you paste or move your files into the newly created directory, you have to add, commit, and push your code to GitHub’s remote server. Let’s walk through that step-by-step.

First, add the files so git can track them:

$ git add .

Then, commit them so you can push:

$ git commit -am "[COMMIT_MESSAGE"

And lastly, push all pending changes:

$ git push origin master

Boom, all your files are now pushed to GitHub’s servers and you’re now ready to get your code on your own server.

4. Deploy to your site via SSH

Now that GitHub is tracking your new code, we can connect to your server via command line and pull another copy of it down. To do so, we have to SSH and clone the repo (as we did in Step 2) one more time. I won’t cover how to use SSH here as that’s a bit out of scope, so I’ll use a generic SSH command here:

$ ssh username@website.com

Once connected, navigate to your domain and clone the repo once more, this time right to your server:

$ git clone [REPO_URL]

Once the clone is complete, you have all your files on the server and should be ready to rock! Moving forward, keeping your code up to date is just a matter of working remotely, pushing changes to GitHub, and pulling them down to your server when you’re ready.

Upkeep

As I mentioned above, keeping your site up to date is easy so long as you keep both your local and remote code in sync with git. To do so, repeat Step 3 to push code to GitHub, SSH to your server, then pull the updates like so:

$ ssh username@website.com
$ git pull origin master

Done deal–all your code should be updated.

Mac users: using your .bash_profile

If you’re on a Mac, you can use .bash_profile to setup aliases to make Terminal commands that much easier. To get started, either create or make a new .bashprofile file in home folder. Open it up and add the following:

alias sites='cd ~/sites'
alias mdo='cd ~/Sites/mdo.com'
alias add='git add .'
alias push='git push origin head'
alias pull='git pull'
alias pp='pull && push'
alias st='git status'
alias master='git checkout master'
alias sshmdo='ssh [domain.com@server.com]'
alias editbash='subl ~/.bash_profile'

Save out the file and open a new tab in Terminal and you can use your new aliases. The above aliases allow me to quickly get to my Sites directory, make git commands super fast, and SSH quickly.

Additional resources

Good fucking design advice

2011-10-31T00:00:00+00:00

Believe in your fucking self. Stay up all fucking night. Work outside of your fucking habits. Know when to fucking speak up. Fucking collaborate. Don’t fucking procrastinate. Get over your fucking self. Keep fucking learning. Form follows fucking function. A computer is a Lite-Brite for bad fucking ideas. Find fucking inspiration everywhere. Fucking network. Educate your fucking client. Trust your fucking gut. Ask for fucking help. Make it fucking sustainable. Question fucking everything. Have a fucking concept. Learn to take some fucking criticism. Make me fucking care. Use fucking spell check. Do your fucking research. Sketch more fucking ideas. The problem contains the fucking solution. Think about all the fucking possibilities.

Just bought this poster from Good Fucking Design Advice in black on fucking black. It shall serve as a solid reality check everyday once I get it framed and hung. Love it.

Floored

2011-10-28T00:00:00+00:00

Around the middle of this month, Bootstrap became the fourth most-watched repository on GitHub, passing Homebrew, HTML5 Boilerplate, and many other high quality, awesome repos. I’m floored, humbled, and, more than anything, ecstatic.

Given the reception of Bootstrap, I just wanted to recap a few awesome and staggering stats in light of continued efforts to push out v1.4 as soon as possible and continue to jam on v2:

Over 560,000 visits to the repo alone
Over 8,700 watchers
Over 1,400 forks
Over 400 issues closed
Over 30 contributors

All of that’s huge and is only going to go up as development marches on. Just wanted to say thanks and share some appreciation for all those who have made Bootstrap possible. You guys rock.

Thanks!

Simple GitHub.com userstyle

2011-10-26T00:00:00+00:00

GitHub is awesome, amazing, and wonderful. It’s one of the best things that has ever happened to me as a designer and developer. However, I find myself distracted by the background images and styles of the topbar and struggle to skim boatloads of issues on Bootstrap. So, I added a custom userstyle in Chrome to help me out.

The userstyle

The header and body changes are purely cosmetic changes based on personal preference, but the change to the issues list helps me work a bit more efficiently on Bootstrap. I hide who submitted the issue and when and unbold the issue names. This way I can see more issues at once and get a larger, bird’s eye view.

Updated issues listing

Download on GitHub

Check it out and fork it on GitHub Gists if you like.

If you’re using Google Chrome, I recommend using Stylish to add userstyles. For Safari, I recommend User CSS.

Making Bootstrap responsive

2011-10-21T00:00:00+00:00

With v2.0 of Bootstrap, we’re going to include some of the core tools developers need to make any project responsive: media queries. As we only just began to implement the responsive features, we’d love some feedback on where we stand thus far and what developers (and designers) expect.

The plan

So, after a bit of thought and experimentation, here’s how we’re approaching responsiveness in Bootstrap:

Responsive features should be opt-in, not opt-out. Why opt-in? Well, responsive design isn’t necessary for every project, but it should be available for those who want it. For that reason, we’re thinking of making a separate file for all our responsive code for developers to enable.
Enabling responsiveness should be straightforward and easy for all skill levels. Since we’re considering opt-in for this, we need all skill levels–designers and developers, noobs and pros–to understand how to use it. A separate .less file and compiled stylesheet will both be available.
The responsive features should work for all major platforms and devices (kind of a given, right?). Translation? iOS and Android wherever possible, but not likely Blackberry or Windows. (For full transparency, I’ve had absolutely zero experience with the latter two.)

The feedback?

Three simple guidelines thus far is just a way to get some ideas in place to align our thinking and communicate our goals with the community. That said, we’d love more feedback and know there are plenty of questions out there to consider, including:

What resolutions do we support exactly?
How much functionality should be supported at each level?
Should Internet Explorer be supported in our media queries?

If you’re a developer actively using Bootstrap, I highly encourage you to check out the 2.0-wip branch on GitHub and share your feedback via GitHub issues or Twitter. We’re always looking for more feedback and welcome it at all levels.

Help us refactor forms for Bootstrap 2.0

2011-10-10T00:00:00+00:00

While version 2.0 of Bootstrap is a ways off, we’re still thinking about and (ocassionally) working on some of the new stuff we plan to add with that release in a separate branch, 2.0-wip. To that end, we’re reconsidering our approach to how we use forms and form elements within Bootstrap. And we’d love your feedback on our approach thus far.

(If you’re tracking the development of Bootstrap, I highly encourage you to watch that branch for new activity. Check it out on GitHub.)

Forms in Bootstrap today

In 1.3, form styles are quite generic and wide-reaching. With the “default” styles being a float-left, right-aligned label, we end up having to undo a lot of styles to normalize the form fields. That’s problematic for a few reasons and doesn’t give developers a lot of leeway when building.

What we’re thinking about for v2.0

For 2.0, we’re thinking about namespacing certain styles and types of form to provide a better default state and more included options. When we cut the 2.0 branch, our plan was to include at least four types of form layouts:

Vertical/stacked with left-aligned labels on top of inputs
Horizontal with float-left and right-aligned labels that appear to the side of inputs
Search with a single, super rounded input and one optional button
and, Inline with multiple fields and buttons on one “line”

So why do we need these four options? Well, let’s expand on the descriptions and give you some insight:

Vertical forms give us a better default state because the amount of CSS applied to them is super minimal compared to our current method.
With the base styles simplified, we make it easy to turn any vertical form into a horizontal one just by swapping a class. Same markup overall with just one different class.
Search forms don’t require much extra styling, but making them stand out amongst other generic forms is useful. While type=search is an option, it’s support is limited and styles erratic.
Inline forms are also useful, and while inline fields are technically possible with the vertical forms, this gives us a more durable and scalable option just in case. It’s also needed for inline labels, so there’s that.

And that’s what we have so far from the conceptual side. Hopefully this reduces headaches for creating new and maintaining old forms. To help visualize that, here’s an example of the markup we’re thinking about using for vertical/horizontal forms:

<form class="vertical-form" action="">
  <fieldset class="control-group">
    <label class="control-label" for="element">Label name</label>
    <div class="controls">
      <input type="text" name="element">
    </div>
  </fieldset>
</form>

Here’s how it differs from 1.3 from a technical standpoint:

It’s more semantic. Instead of .clearfix we use .control-group with a fieldset.
Yes, there are more classes here, but that saves us inheritance and performances issues.
It makes your two most common form types, verical and horizontal, completely the same save for a single class on the form.
It namespaces the form styles so they don’t clash with anything else in your markup, an approach that really shines in large systems like Bootstrap.

Hopefully this makes sense from both sides now. The code has more classes, but is infinitely more durable and scalable. We add more options while maintaining existing patterns of stacked and horizontal forms.

Help us out?

Hopefully this all gels with what you’re thinking and doing as a developer. We’d love to hear your feedback on this approach for forms in v2.0 via Twitter, GitHub issues, or mailing list.

Thanks in advance!

Using GitHub for issue tracking

2011-10-01T00:00:00+00:00

Last time I wrote about GitHub, I focused on how awesome it is for rapid and simple web deployment. It’s super simple to use for versioning, hosting, and getting new and updated code to your website. Beyond that, with a recent update to the web interface, it’s been made more awesome as an issue tracking for Bootstrap.

Organizing our issues with Milestones

Without the ability for users and contributors to file issues on GitHub, I’m not sure we would have caught all the bugs, improvements, and feature requests that we did. With well over 200 issues closed on Bootstrap, we weren’t overwhelmed simply because we had the ability to tag each issue and assign them to a milestone.

Setting expectations

The milestone feature is great for two reasons: my own sanity and transparency for everyone else. Each milestone has represents a new release and helps set expectations for others when dates are assigned to them. Setting expectations on an open-source project like Bootstrap is immensely useful for all involved. It shows people that this is a trusted and evolving endeavor; it’s going to be around for awhile.

Driving responsibility

I can’t recall another project that I’ve worked on with such vigor and determination as Bootstrap. Aside from my core work duties at Twitter and writing on this blog, nothing else has made me more happy to keep doing what I do as a web and product designer. Having issues and pull requests filed against Bootstrap from people all over the world is humbling and rewarding. It’s been a blast to talk through ideas, push back on others, and help people solve problems. I love every moment of it.

If you have the chance–even if you’re working in a closed, private repo–give the issue tracking and milestone features of GitHub a go. You’ll be thoroughly impressed and should see a noticeable increase in productivity.

Using iA Writer for Mac

2011-09-26T00:00:00+00:00

For awhile I’ve been writing blog posts just in a plain text or code editor, or even in Pages, but none of those were great options. Either the fonts, colors, or features always got in the way of just busting out content. Enter iA Writer into my life.

iA Writer kicks ass for a few reasons:

After using GitHub for a bit to manage Bootstrap, I’ve gotten accustomed again to using Markdown. Since iA Writer only supports that, and supports it well, I got up and running super quick with the Markdown syntax.
It’s all plain text, which means I can sync everything via Dropbox and have it all backed up and organized. Syncing with Dropbox means no additional service running in the background like Taskpaper requires (my previous, and still awesome, tool of choice).
Fast and simple, just the way I like it. The app purposely lacks features like customizing background, font, text size, and more. Its goal is to get you in and get you writing, and that’s what I’ve done (I’ve written 8 blog posts this weekend already in iA Writer).

And best yet? It’s only $10 and is designed and built by the team at iA, people who know their stuff when it comes to making awesomely designed experiences.

Check it out in the Mac App Store and see for yourself

Good design is constant contact

2011-09-20T00:00:00+00:00

Constant contact between designers and engineers allowed for seamless integration of function and formal response.

Out of all the things I’ve read about Rams, the notion of “constant contact” is by far the most evocative of my day-to-day job as a designer at Twitter.

I work with some of the brightest and most talented engineers in the industry and I can honestly say that without the interactions I’ve had with them, my work would go no where. Good design is constant contact.

The dynamic of a designer-engineer pair is perhaps the most highly valued in design. Constant contact with an engineer provides a different point of view, one essential to how we build and iterate on not just code, but product. A great example of this has been working with @fat on Bootstrap.

Without @fat’s help, we wouldn’t have released it any time close to when we did, we wouldn’t have half the features we do, and we wouldn’t have any javascript plugins, tests, or makefile functionality. Plus, for an engineer, he’s got a great eye for what looks and feels great.

Again, constant contact is incredibly valuable. It leads to faster iteration and innovation and challenges your assumptions as a designer. It’s good design.

Updated site design

2011-09-18T00:00:00+00:00

Decided to give the site a little update by realigning the design. Not much has changed, so here’s the gist:

Streamlined everything by moving to a single column
Sidebar is gone, peep the footer
Open Sans, baby (served via Google Web Fonts)
Updated photo of me to match my avatar elsewhere
Less PHP, JS, HTML, and CSS

And that’s about it. Shed 20 pounds visually and another 10 under the hood. Feels great. Hope you like it!

Welcoming Bootstrap v1.3

2011-09-17T00:00:00+00:00

After a few weeks of intense work, @fat and I are proud to announce the latest version of Bootstrap, 1.3, with a few new features, a boatload of bug fixes, and—best of all—javascript plugins.

New features

Here’s the lowdown on what’s new to Bootstrap 1.3:

Javascript plugins for modals, alerts, dropdowns, scrollspy, tabs, tooltips, and popovers. This is huge—you can now bring Bootstrap to life with interactive design components. They also work with jQuery and Ender.
Massively updated docs, for both the main page and for the new javascript plugins. Yes, I consider this a feature—it’s indispensible for developers and designers. More details below!
Inline labels for marking inline content with key visual flags
Media thumbnails
Breadcrumbs

New and updated docs

Now, about those docs: there is a lot of new stuff. We’ve added more example markup and information on how to use Bootstrap’s code with 1.3 and will continue to do so with every release. To that end, here’s an outline of the big changes to the docs:

Added complete javascript page with detailed docs for how to use
Three complete example pages of using Bootstrap, linked from main docs page with thumbnails
Added section for compiling Less, for guidelines on how to recompile Bootstrap with Less
Added section for customizing grid variables in Less
Added section for code for using pre and code tags
Added section for form field sizes that match grid column sizes

When you’re done here, be sure to checkout those beautiful new Bootstrap docs here.

We got (fixed) issues

Also included in 1.3 is a hefty set of resolved issues from GitHub and other important style changes. Fun fact: to date, we’ve closed over 200 issues on GitHub. That’s huge!

Updated table styles to be just a tad bit more refined
Added new form input sizes based on the Bootstrap grid system (meaning now you can do input.span5 for a 280px-wide input)
Removed :focus states from :active links in Firefox
Fixed unqualified .clearfix that added bottom margin to all containers
Updated .container() mixing to be .fixed-container() to prevent conflicts when compiling
Added focus states (either box-shadow or outline on :focus) to all buttons, links, and inputs
No longer require h3 in topbar, but still support for backwards compatibility

For a complete list of issues fixed in 1.3, view the milestone on GitHub.

Be sure to take a moment and thank your friendly, neighborhood @fat for all the work he’s put into this release. None of the javascript would be here without him and he’s been instrumental in pushing the development of Bootstrap since day one. He’s a boss. Mad props, broheim.

We’ve also created a new Twitter account, @TwBootstrap, for announcements, feature and release teasing, and open-ended discussion. Be sure to follow along for the latest as we continue on with development.

Now, go checkout the latest Bootstrap on GitHub!

Write less Less

2011-09-05T00:00:00+00:00

I’ve written about using LESS before, touting the benefits of accelerating development and simplifying CSS. It seems the more I use it, the more awesome things I have to say about it. It adds many great features to regular CSS like variables, mixins, and nesting, but it’s the latter that that I want to talk about more today.

While I’ve written about using nesting in LESS before, turns out it can encourage good and bad practices as a web developer. Nesting is great, but not if you’re just adding bloat to your code. Take for instance this snippet of LESS:

header {
  ul {
    li {
      a {
        ...
      }
    }
  }
}

When compiled, it looks like this:

header ul li a {
  ...
}

So, what’s the problem? Looks fine at first, right? Well, not so much. You can actually improve this quite a lot by simplifying the nesting, thereby decreasing the amount of code, rendering time, file size, and most importantly specificity. With CSS, I’ve found you need to strike a balance between writing very generic code and writing very durable and modular code. Specificity as a result of nesting has a direct impact on both of those things.

Taking that same LESS code from above and rewriting it to not use unecessary parents in our selectors shows how we can attempt to get closer to achieving that balance.

header {
  ul { ... }
  li { ... }
  a { ... }
}

Of course it depends on your markup and your needs, but this is the gist of what I’m getting at. Ultimately this isn’t a LESS-specific problem; anyone coding CSS can run into this, but with LESS it becomes easier to do unintentionally.

Don’t nest just to nest. Nest to simplify your final, compiled CSS. You’ll save code and headaches later on.

Bootstrap updated

2011-05-30T00:00:00+00:00

It’s been far too quiet around here. As a quick update, I’ve pushed some new changes to Bootstrap to GitHub for all to enjoy. Included are some commits by those in the community (many thanks!) and some other things I’ve been sitting on for quite some time as part of another project (hopefully that will come soon enough).

Here’s the standout new stuff from the latest push:

New gradients with support for direction and IE10 syntax
New helper methods for sizing and quick block-level center alignment
All variables now in camelCase
Opacity added in with some lovely math to support IE
Added offset support for columns (to indent them by a number of columns)
Namespaced font mixins for more context and add new .shorthand mixin

More to come soon! In the mean time, head on over to Github to download or fork Bootstrap.

Fatten up those T's

2011-04-15T00:00:00+00:00

As Naz Hamid pointed out Thursday, the demand for highly focused specialists in the design community is dwindling and our schools are somewhat responsible. While his post focuses on students fresh out of a degree and embracing “the new design,” the principle extends beyond students to the rest of the community.

Generalist specialists—T-shaped people—are the new design hotness.

The concept isn’t revolutionary, nor impossible for anyone to pursue in their career. As creative individuals, we typically have the luxury (curse?) of having interest in the design of just about anything. Clothing, furniture, cars, and hardware are all common interests amongst people in the Web design community. For many of those people, those interests extend to actual skill backed by a decent amount of experience.

For designers on the Web, our skills need to spill into other (previously isolated) verticals. Dedicated graphic designers, visual designers, UX designers, and the like may always find roles down the line, but it seems like the generalist specialists are winning out. That’s where being T-shaped comes in.

As a T-shaped designer one should have experience across the multiple disciplines with a focus or preference for one or two. Being T-shaped means you can shift yourself and provide value at just about any stage or type of project—like sketching, wireframing, visual design, and code. While you can certainly train yourself to be T-shaped, most of us end up this way no matter what through life’s course.

If you’re new to a handful of disciplines as a designer, getting to be a T-shaped designer isn’t hard, but it takes time. To get there, you need to fatten up those T’s by getting your feet wet in things you might not have any experience in.

If you’re a graphic designer, work towards bringing whatever print experience you have to a small single page site. If you’re an interaction designer, start checking out HTML and CSS, and then move on to some basic jQuery. By doing so, you become a much more versatile designer and contributor on any project.

Whatever your speciality is, find something close to it and work at it. You gain a richer understanding of your work and can begin to look at projects from various points of view with relative ease.

So, get out there and fatten up your T by learning something new—you’ll love it, I guarantee it.

Introducing Bootstrap

2011-03-21T00:00:00+00:00

For the last several months, I’ve been developing websites and apps with an awesome tool called LESS. It’s a CSS preprocessor that sits on top of regular ol’ CSS, but provides a ton of extra features like mixins, variables, functions, and operations. The best part? It all comes out as compressed, locally-stored CSS. Hotness, right?

Well, when I started using LESS at Twitter to create Blueprint—a CSS and HTML framework that helps our engineers quickly developer Twittery apps—I realized I needed a starter file of sorts to house all my variables and simple mixins. As time went out, that file grew and has since become the soul of every project I work on, including this very website.

Today, I’m releasing a modified version of that file and it’s called Bootstrap. Bootstrap is a super awesome pack of mixins and variables to be used in conjunction with LESS in any of your web projects. It immediately makes any new design or development project that much easier to start, and also makes older projects easier to maintain.

Looking ahead, I plan on adding more to Bootstrap with additional mixins, variables, and such. I’m also considering making Bootstrap part of several larger projects that I hope to release over the next few months. More on those things to come soon enough!

For now, visit the Bootstrap website to find out more. You can download or fork it at GitHub. Questions, comments, or suggestions? Email me.

One year at Twitter

2011-02-01T00:00:00+00:00

Today marks the one year anniversary of working as a designer at Twitter. The only thing that I can say about it is holy shit. 2010 came and went faster than any other year I can recall. It was full of awesome events, people, and projects, and 2011 is shaping up to be even better.

When I started we had less than 140 employees, the design team was 6 people strong, we were on one floor in our building, had a different CEO, and our Promoted Products were just getting started. Flash forward to today and we have 10 people on the design team intermingled with over 350 employees on two floors, a new CEO, and three types of Promoted Products.

I’m pretty stoked for the next year. I’m looking forward to hunkering down with the rest of the revenue team to continue to iterate on and refine our products, growing the design team, and making Twitter more awesome than it is today.

An update on Less.js & nesting your CSS

2011-01-29T00:00:00+00:00

Awhile back I put together a short comparison of nesting in Less and Sass and how to improve it in both stylesheet languages. Tonight I learned I made a critical mistake in my summary of Less’s nesting features. I have no idea how I missed it, but Dave Gamache shared this with me tonight and I’m still reeling.

Here’s how I thought nesting worked in Less:

div#container {
  a {
    color: @link-color;
  }
  a:hover {
    color: darken(@link-color, 25);
  }
}

Based on the documentation that I read, I saw no way of nesting the :hover selector within the a selector right before. Sass allowed for this, so I was at a loss as to why Less wouldn’t do it as well.

Turns out, I just suck and it is completely possible:

div#container {
  a {
    color: @link-color;
    &:hover {
      color: darken(@link-color, 25);
    }
  }
}

Thanks, Dave! Now, if you’ll excuse me, I have to go rewrite buckets of CSS to fix my nesting :).

Daring Fireball user style now on GitHub

2011-01-11T00:00:00+00:00

Just a heads up that I’ve made my Daring Fireball user style available on GitHub. Head there for the latest and greatest from here on out. Feel free to fork it with any tweaks you might have, too.

Want to use it now? Update your user style rules to include an import rule instead of the full-blown CSS I posted previously. It’s a compressed version of the CSS, with some additional updates, hosted on Github Pages. Just copy and paste the code below and you should be all set!

@import url("http://markdotto.github.com/mdo-df-min.css");

Be sure to read the original blog post I published a week ago that details some of the modifications I’ve made.

(Hat tip to @kneath for pointing out GitHub Pages.)

3D text using just CSS

2011-01-05T00:00:00+00:00

I have no idea if it’s been done before, but I’ve long wanted to put together a quick little demo showing the power of CSS’s text-shadow property. Turns out the latest versions of Chrome, Safari, Firefox, and Opera all render multiple text-shadows on elements, just like box shadows.

So I threw this together: 3D text using nothing but CSS. No extra markup, no :before or :after mess, and no images. Just progressively enhancing CSS to add some flair to your work.

Check out the demo and let me know what you think!

Daring Fireball user style

2011-01-01T00:00:00+00:00

My eyes don’t handle light text on dark backgrounds very well—it physically hurts to even try. I love reading Daring Fireball, but if the name sounds familiar, then you know of the small text, dark background, and low contrast.

Although I read a lot of his posts in Reeder for Mac, I do find myself visiting the full site often. Instead of just whining about it, I figure I’ll whine about it and do something about it. In comes my Daring Fireball user style.

What’s changed

Here’s the rundown on what it does:

white background with dark gray text
bumped up the font-size
eliminated the sidebar’s nav
fixed the ads to the bottom left (no need to hide them, they’re good quality)
resized the main column to 550px
changed out link colors to blue for more contrast
and lastly, miscellaneous spacing changes

Grab a copy

Go ahead and snag a copy for yourself—just copy and paste the CSS below.

/*
  Daring Fireball
  Author: @mdo
  Description: Improves contrast and readability of DF without removing the ads.
*/

* {
  font-family: Helvetica Neue, Helvetica, Arial, sans-serif !important;
}

/* Background change and font-size bump */
body {
  background: #fff !important;
  margin-top: 40px;
  color: #333 !important;
  font-size: 13px !important;
  line-height: 18px !important;
}

/* Links to blue! */
a {
  color: #2276BB !important;
  font-weight: bold;
  border-color: rgba(0,0,0,.2) !important;
}
a:hover {
  background: #eee !important;
}

/* Clean up the text colors and headings */
h1, h2, h3, h4,
.linkedlist p,
.article p,
.article li {
  color: #333 !important;
}
.linkedlist blockquote,
.article blockquote {
  border-left-color: #ccc;
}
.linkedlist blockquote p,
.article blockquote p {
  color: #777 !important;
}
/* Remove top margin from all img elements */
img {
  margin-top: 0;
}
/* Remove left margin on dd */
dl.linkedlist dd {
  margin-left: 0;
}

/* Site Container */
div#Box {
  width: 550px !important;
}

  /* Masthead */
  div#Banner {
    margin: 0 !important;
  }
    /* Modify the logo */
    div#Banner a img {
      background: #333 !important;
      padding-top: 3px;
      padding-right: 5px;
      -webkit-border-radius: 5px;
    }
    /* Hide shirts promo */
    div#BannerPromo {
      display: none;
    }

  /* Nix the sidebar and widen the main column */
  div#Sidebar {
  }
    /* Hide everything in the sidebar but the ads */
    div#Sidebar p,
    div#Sidebar ul {
      display: none;
    }
    div#SidebarTheDeck * {
      border: 0 !important;
      padding: 0;
    }
    /* Move the ads, because ads are revenue and revenue is nice */
    div#SidebarTheDeck {
      position: fixed;
      bottom: 15px;
      left: 20px;
      width: 160px;
      margin: 0;
    }
      div#SidebarTheDeck a {
        border: 0;
      }
      div#SidebarTheDeck img {
        display: block;
        margin-bottom: 5px;
      }
      div#SidebarTheDeck p.ads {
        display: block;
        margin: 0;
        color: #333;
        text-align: left;
      }
      div#SidebarTheDeck img.the_deck_promo {
        margin-top: 0;
      }

  /* Reposition the main column */
  div#Main {
    margin: 50px 0 0 !important;
    width: auto !important;
  }

Not sure how to use it? Check out these extensions for your favorite browsers:

Safari: User CSS
Chrome: Stylish
Firefox: Stylish

Enjoy!

The problem with nesting CSS with Less or Sass

2010-12-18T00:00:00+00:00

I’m a big fan of using http://lesscss.org/ with all my coding projects (be sure to read my other post for more details on it). It saves time by providing me variables, mixins, and of course nesting rules. Sass does the same thing, but for one reason or another I never could get used to it’s syntax. The problem with nesting, and a problem I see in CSS all too often is over-specificity.

Here’s an example of nested rules in Less:

#header {
  background: @darkGray;
  ul#nav {
    background: #fff;
    margin: 0;
    li {
      display: inline;
      a {
        display: inline;
        float: left;
        padding: 5px 10px;
      }
    }
  }
}

It’s a simpler way to write out your CSS, but does it really pay off? That depends on how you look at it. On the one hand, it streamlines your code and provides an easy way to determine the structure of the markup that it styles. On the other hand, it’s way too specific when Less parses it out as regular ol’ CSS.

Here’s that same block, but as parsed as plain CSS:

#header { background: #333; }
#header ul#nav { background: #fff; margin: 0; }
#header ul#nav li { display: inline; }
#header ul#nav li a {display: inline; float: left; padding: 5px 10px; }

This is a bit of an oversimplification, but it’s easy to see what’s going on here. You can easily rewrite that CSS to be less specific, but just as effective. CSS is most effective when it is just specific enough, but doesn’t overdo it.

Here’s that parsed CSS again, but without the inheritance from nesting:

#header { background: #333; }
#header ul { background: #fff; margin: 0; }
#header li { display: inline; }
#header a {display: inline; float: left; padding: 5px 10px; }

The problem with this is again one of over-specificity and speed. Browsers read CSS right to left, and the most specific you get, the longer it takes for the browsers to parse your CSS. This isn’t an issue on most sights as the difference is in milliseconds, but for certain circumstances, I can see it being problematic.

Either way, nesting without prefacing selectors with it’s parent rule would be outstanding. Nesting is primarily saves on time and readability, so shouldn’t that be reflected in the output of Less and Sass? Perhaps in future iterations.

WebKit placeholder text color

2010-08-30T00:00:00+00:00

<input type="text" id="phone" placeholder="xxx-xxx-xxxx">

::-webkit-input-placeholder {
  color: #ccc;
}

Anthony Short shows us how to change the placeholder text for input fields in WebKit browsers.

About the new design

2010-08-25T00:00:00+00:00

The other day I quickly coded a new design for this here website. The idea behind it is simple: provide some base structure, but ultimately let the content drive the design of the site. To share what’s under the hood, I wanted to share a little more about that idea and what’s powering this site.

Form Before Function

That phrase feels like a cop-out, but it sums things up nicely. So far, photos and a few text and code heavy posts are all that’s here. That could easily change and I wanted to remain flexible as to not feel constrained by whatever elaborate design I could come up with.

I don’t know exactly what I want out of this site yet, only that I want to blog, share photos, talk about some code, and share thoughts on links.

Under the Hood

Because it’s what I’m familiar with, I opted to use WordPress once again. Coupled with the awesome plugin support and flexibility of WordPress as a CMS, it was a no-brainer for me. Here’s a look at what I’m using with WordPress to power this site.

Categories, Not Custom Posts

Just a quick note to begin here: WordPress 3.x allows for custom post types. I’ve used them before, but decided to avoid them this time around and instead keep things simple to start. As I said, I want the form of this blog to come as naturally as possible.

To customize how each category’s post shows up, I threw in some conditionals for the loop:

<?php if ( have_posts() ) while ( have_posts() ) : the_post(); ?>
  <?php if (in_category('photos')) { ?>
    <figure>
      <?php the_content(); ?>
      <figcaption>
        **<?php the_title(); ?>**
        <?php echo get_post_meta($post->ID, 'caption', true) ?>
      </figcaption>
    </figure>
  <?php } elseif (in_category('quotes')) { ?>
    <blockquote>
      <?php the_concept(); ?>
      <cite><?php the_excerpt(); ?></cite>
    </blockquote>
  <?php } else { ?>
    <?php echo tweetbutton(); ?>
    <h1><?php the_title(); ?>;</h1>
    <span class="date"><?php the_time('l, F jS, Y') ?></span>
    <?php the_content(); ?>
  <?php } ?>
  <hr />
<?php endwhile; ?>

Plugin: WP Tweet Button

To encourage sharing of the articles I (will) write, I’ve added the Twitter Tweet button via this handy plugin. It gives you a few options, including: automagically adding it to posts, custom recommendations per post, and more.

Check it out if you haven’t yet. I did try some other plugins but they all sucked. This one seemed best.

Plugin: Disable WPAutoP

I can’t begin to tell you just how frustrating WordPress’s automatic p tags are. They wrap anything and everything, which makes for some funky styling if you’re not careful enough (e.g., images get wrapped and can leave funky spacing if floated). Install this bad boy and kiss those rogue p tags good-bye.

CSS with Less.js

I talked about this before, but I’ll mention it here again. Less.js, a Javascript implementation of Less CSS (previously done via Ruby) that gives you powerful add-ons to CSS. Use it to add variables, create mixins for shorthanding long or complicated pieces of code, perform math, and more. It’s really handy.

Plus, even though it compiles the CSS in the head of your page, it stores it in a HTML5 local database. Hot.

Chili: A jQuery Syntax Highlighter

Not sure if there is a better one out there, but it seemed solid to me after a quick tour around Google. I’ve love some suggestions for alternatives; my only complaint is it’s ugly default styling. Will definitely need to dive in and change that up more in the future.

PaintbrushJS: Javascript Image Modification

I use PaintbrushJS to modify that beautiful mug of mine on your left. It’s damned awesome; you can modify images with sepia, noise, tint, and even blur filters. All on the fly with javascript and some awesome use of canvas. It’s developed by Dave Shea (@mezzoblue) and is just getting started. Not practical in my implementation, no, but still cool :).

Beanstalk for Low Maintenance SVN

I’m a fan of version control—if by version control you mean just one master branch of all my code so that I can quickly revert my mistakes and checkout new copies should my server get hacked or otherwise fubared. Nice to have and these guys do all the leg work; I just import my base files and they take it from there.

Also, an added bonus of using SVN was the need for using SSH to checkout my code on my server. Handle to know; I need to pick up more stuff like this.

And that’s it! I’ll keep adding features and posting about them as I go though.

Like CSS3? Use LESS.js

2010-08-23T00:00:00+00:00

I’ve been using Less.js in just about every project I can lately and I love it. I don’t go wild about it though; I’d rather preserve the readability and structure of regular ol’ CSS. That said, I do want to make more complex things easier.

But wait, why use it? Well, for a few reasons really, but most importantly to add variables for repeated values like colors and to simplify the usage of CSS3 values that have vendor prefixes.

So here are a few examples of how I use Less.js. Check them out and feel free to use them in your own code.

// This is a comment
/* This is also a comment */
div.container {
  ...
}

Comments: Less.js brings a small add-on for me, but for some reason I love it.

// Colors
@linkColor: #4bb14b;
@darkGray: #333;
@lightGray: #7f7d79;

Colors as variables: Hex values can be a real headache, especially if you change them often. Use variables instead to save yourself the pain.

a:hover {
  color: darken(@linkColor, 10);
}
// Additional functions: darken, saturate, desaturate,
    and greyscale

Functions: One of my new favorite features is functions in Less.js. I use them on my link hovers. More info

// Declare border-radius for everyone (yay!)
.borderRadius (@radius: 5px) {
  border-radius: @radius;
  -khtml-border-radius: @radius;
  -moz-border-radius: @radius;
  -webkit-border-radius: @radius;
}
.boxShadow (@shadow: 0 1px 3px rgba(0,0,0,.25)) {
  box-shadow: @shadow;
  -moz-box-shadow: @shadow;
  -webkit-box-shadow: @shadow;
}
div.container {
  background: #fff;
  padding: 30px;
  margin: 0 auto;
  .borderRadius(6px);
  .boxShadow(0 1px 3px rgba(0,0,0,.5));
}

CSS3 mixins: With Less.js, you can use what’s called mixins—partials for your CSS.

Have a suggestion? Talk to me on Twitter or shoot me an email.

@mdo

Working with MDX in Next.js

Learning new things

Implementation goals

Setting up the file structure

Rendering MDX

Sidenav

Up Next: Abstraction

Shipping Blended Diffs

Finding a new style

Planning with the team

Building it

A diff canvas

macOS web apps

Adding to the dock

Web app limitations

Theme color

Styling

Anything else?

Using Bootstrap in Hugo with npm

Fun with the dialog element

Default styles

Functionality

Suggested styling

Show and hide

Details element

Resources

Horizontal scrolling nav

Toggling classes with JavaScript

Diffing Sass maps

Compare via @debug

Adding in @warn

Creating diff-map

Improving the function

Learning CSS with utilities

Force pushing to different Git remotes

Global CSS options with custom properties

Publishing npm packages with dist tags

Faster rebasing with git reset

Moving RSS

Null variables in Sass

CSS dark mode

Shipping system fonts to GitHub.com

Before and after

Why change

What’s changed

The stack

Dealing with Chrome

How we did it

One year later

Managing features in Bootstrap

It’s a product

General feature requests

Major releases

Development

Simple and focused

Nesting in Sass and Less

Assumptions

Nesting elements

Nesting classes

Un-nesting with &

BEM nesting with &

Nesting pseudo-classes with &

Wrapping up

Introducing Primer

Recent projects

mdoml

Ocean Dark Terminal.app theme

GitHub wide

Using Sass with Jekyll

Table of contents

Assumptions

Install Sass

Create a Sass stylesheet

Link your stylesheet

Using Sass imports

Minification

Hosting on GitHub Pages

Example project

Shipping GitHub's split diffs

Compare via `@debug`

Adding in `@warn`

Creating `diff-map`

Un-nesting with `&`

BEM nesting with `&`

Nesting pseudo-classes with `&`