Keith J. Grant

An AI Skeptic Uses AI for a Week

2025-07-15T19:46:14Z

If you’re an AI skeptic, I get it. I was one too, and still am in some ways. I don’t see any benefit to stuffing a chatbot into most of the apps and websites I use. I don’t care about a summary of an email I received or a meeting I attended.

In that regard, there’s stock-price-driven hype train that I’m ready to get past. However, that’s not all there is to it.

It helped me make BBQ ¶

I have made a point the last week or two to really dive in and give AI a fair shake, and it has opened my eyes. AI doesn’t belong everywhere, but it does have its place, both for daily activities and to assist with software development.

The first, simpler thing I did was use Google’s Gemini to help make a purchasing decision. I was looking for a wireless meat thermometer that I can use when smoking and grilling. There are lot of options on the market, but most of them only work in conjunction with a smartphone app. I like those apps, but I wanted one that also has its own standalone base so I can see check the temps at a glance in the kitchen.

So I told Gemini in a few sentences what I was looking for, and how many probes I wanted. It crunched for a while, then came back with a list of models that met my criteria along with a summary of reviews. This included two I was already aware of from earlier research (The Typhur Sync and Thermomaven P2), plus a third I had not heard of (The Inkbird INT-12-BW).

Gemini showed its whole “thought process”, including links it scanned, reasons why it eliminated other models from the list, and a fairly reasonable synopsis of what differentiated these three. All three models met my criteria exactly.

It was far, far faster than reading dozens of reviews and watching multiple YouTube videos. The synopsis wasn’t perfect — for one model, it listed a probe thickness in mm, while the other two were “thin” and “very thin” — but it was enough of a start for me to dig in and do further research if I wanted. Of course I checked a few reviews myself afterwards to make sure everything checked out with Gemini’s response, and it did. (In the end I opted for the Thermomaven; the median priced of the three.)

Would this be silly for simpler web searches? Of course. But for something like this, where I know I would be clicking through dozens of links, I think it really helped narrow my search.

It is impressive at software development ¶

Of course the real hot topic isn’t web search, it’s what this means for the world of software development. What I found here blew me away.

I installed Warp and used it as part of all my development work for a week or two. This let me choose from multiple agents, though I just left it on the default, Claude 4 Sonnet.

I have used Copilot in the past. Critics often refer to LLMs as “glorified auto-complete”, and that’s very much what Copilot felt like to me. It was useful for rapidly spitting out large blocks of repetative code, and it could write small, common utility functions for me.

Claude is different. It can index my entire codebase, make sense of how the application is structured as a whole, and determine where and how to make changes. It shows me a diff of every change it wants to make before making it, which I can accept, reject, or further refine with additional requests.

At first, I gave it simple tasks:

On the Organizations pages, change the text on all ‘Add users’ buttons to ‘Assign users’.

It did so without any trouble, and without me ever telling it what the organization pages are or what React components render on them. What immediately stood out to me is it found the pertinent files far faster than I would have. Our codebase has nearly 3,000 files of TypeScript, and sometimes just tracking down the right components for a change can take a little work if it’s in a corner of the application I’m not familiar with.

I had another simple change to make:

On the Organization Users page, change the ‘Manage roles’ button icon from a gear to a pencil and update the tooltip to say ‘Manage organization roles’.

It figured out it needed to import PencilAltIcon (matching a pattern we use elsewhere in the application, notably not using the PencilIcon) and replaced the CogIcon in the component. It didn’t delete the old import of CogIcon, but a follow-up request could have done it (IIRC, I did it myself). Then a bit more of a challenge: tests. We’re in the process of migrating tests off of Cypress, so we now have a hodgepodge of Cypress, Playwright, and Vitest tests in our repository. This component was still tested with Cypress component tests, so I asked Claude to create a vitest file, expecting it to write an empty scaffold where I could place tests. Instead, it wrote a half dozen tests for the component:

render the user list with data
show the empty state when no users are assigned
display an error message when loading fails
show the assign users button when the user has permissions
disable the assign users button when the user lacks permissions
show the empty state with a permissions error when the user lacks permissions

They were all good tests, though I told it to rephrase test names to start with “should”. Next I asked it to compare these tests with the existing Cypress tests and determine which Cypress tests were no longer needed. It correctly assessed them, and, after I prompted, deleted the obsolete Cypress tests (leaving one other more complex test in place that I wasn’t ready to convert yet).

Some of these tasks required a little refinement and/or follow-up requests (“Move the mock data to files with names ending .fixture.json”). It’s not a matter of asking for magic and then mentally checking out, but it is still impressive. At this point, I was determined to push this thing as far as I could and see what happened.

Giving it a more challenging task ¶

That “Assign users” button opens up a multi-step wizard. The second step in that wizard is further sub-divided into two sub-steps, but we’re in the process of consolidating some endpoints and they can be merged.

So, in a new session and a new git branch, here’s the prompt I gave Claude:

The wizard to assign users to an organization has two screens for assigning roles: one for Automation Execution (awx) and another for Automation Decisions (eda). I need to consolidate these two screens into a single screen that uses gatewayAPI urls instead of awxAPI and edaAPI endpoints. Role definitions can be retreived from /role_definitions/. At the end of the wizard, these assignments need to be POSTed to /organizations/:id/users/associate/

It created the new consolidated wizard step and replaced the two sub-steps with the new one. It figured out how the wizard component worked, how this particular instance of the wizard component pieced together its steps into a configuration array containing multiple other components, and it determined how to work with that without any more specific guidance. This involves dozens of React components and almost as many hooks working in conjunction. I was genuinely floored.

I did notice it was repeating some work we already have elsewhere in the codebase, so I prompted:

there is a generic SelectRolesStep component. Can we use that in this implementation?

It did so.

After each of these prompts, it showed its thinking, usually a screen or so of text. It listed each of the files it read at each stage to see how they work together (sometimes a significant list). Then in presented the proposed code changes.

If something was not quite right, I had the option to ask for refinement immediately, or to accept the change and make a follow-up request afterwards. At the end of the process, it presented a full page summary of the changes we made, including a five bullet point list of the “Benefits of the consolidation”. That’s more than I need, really, but it gives a sense that this understands what the changes are for at a higher level than my prompt provided.

At one point, I noticed a proposed change included a repeated set of five or six lines of code, syntactically incorrect. I thought I would just accept the change and delete the duplication myself, but I didn’t need to. After applying the change, Claude immediately suggested a second edit, fixing the problem.

This particular piece of work took maybe seven or eight prompts, including updates to tests. A few of the test updates needed a little more hand-refinement afterwards, but it took care of the bulk of the work.

The whole process felt very much like pair programming with a junior developer, but one who thinks and makes code changes incredibly quickly. I had to point out a couple places where our codebase already provided utilities so it wasn’t duplicating work. In other cases, it found things that would have taken some digging on my part. If something wasn’t quite right when I tested the UI, I told it — sometimes it found the problem and fixed it; other times it struggled. The place it seemed to have the hardest time was dealing with TypeScript errors (relatable), and for those I ended up fixing the issues myself.

I managed staging and committing all changes myself so I could see everything it was doing to the codebase — though you can make Claude do this as well if you’re confident enough in its abilities.

It’s a tool ¶

I saw this post recently on Mastodon:

I’m witnessing professionals spending hours to engineer prompts for Copilot to do basic things like find a line in a file that has a string in it, or figure out who committed most frequently to a sub-path in a repository, or generate boiler plate code for classes… None of these things require #AI. grep, git log.., and editor snippets have existed for a long time. They are quick. They are EXACT. They are FREE. They do not boil the oceans. They do not displace the workforce. They are more efficient and productive.

Learn the tools of your trade. If all you’re doing is using AI, that means AI can and will replace you.

— @reyjrar@hachyderm.io

I understand what he’s getting at here, and it’s an absolutely fair point. I don’t want to turn a blind eye to the resources used in making or using AI, its impact on society, and all the ethical questions surrounding it. But I think at the same time he misses a key fact: AI is now one of the tools of the trade.

Just like any tool, the trick is going to be learning when to use it and when not to. It’s certainly going to take some experience to get a feel for what it can and cannot do, and when it is and is not more efficient than other approaches.

At least one early study indicates AI doesn’t provide the productivity boost many think it does. This is important to keep an eye on. At the same time, I don’t think productivity is the only gain; in a couple instances, it found bugs in my code that I had missed.

With this Warp prompt in front of me, there is certainly a temptation to disengage my thinking and make it do all the work. For simple use-cases, I can see where that sort “vibe coding” can work, but at this junction, I don’t see that being my approach. I value clean, maintanable code too much to blindly accept all changes AI produces.

Just like working with a junior developer, I need to keep my mind engaged to track what it’s doing. If something looks funny, I’ll ask it to do it differently. As I get more familiar with it, I’ll turn to it more when it makes sense to and less because it’s a fun novelty.

My gut says this is really efficient at finding what needs to change and scaffolding in a rough approach, but generally less efficient in the polishing stages of development.

In all, I think I’ve come to find a more balanced approach is needed when it comes to AI. It’s no magic bullet, but neither is it a complete waste of time. In coding, the answer has always been “it depends,” and that still hold true today.

Simplify Nested Code

2025-02-11T16:02:37Z

One of the most common pieces of feedback I leave in code reviews, at least in the realm of code readability, is to reduce nesting. In general, the more deeply-nested code is, the more complex it is to track mentally. This is especially the case with if statements.

A have placed a code snippet below; which you can imagine might appear as part of a larger function. This code is doing something relatively simple: setting a status message based on a few criteria. Unfortunately, while the message itself is simple, getting your head around all the different execution paths is not. Understanding this code means you have to think about error state, loading state, an isActive flag, an isDefault flag, and whether other items in the array are active.

if (item) {
  if (item.isActive || (item.isDefault && !items.some((i) => i.isActive))) {
    message = 'Active';
  } else {
    message = 'Inactive';
  }
} else {
  if (hasError) {
    message = 'Error loading item';
  } else if (isLoading) {
    message = 'Loading...';
  } else {
    message = 'No item selected';
  }
}

We’ve all seen code similar to this. We’ve probably all seen code even worse.

Often, code like this evolves over time. It may have been very simple initially, but as needs arose or edge cases emerged, developers addressed them by adding new conditionals.

I’m not going to say this code is wrong, per se, because it does work and it’s not so obtuse as to be indecipherable. In fact, this is a perfectly reasonable first draft when writing code. But it has some weaknesses that could be improved.

Return early ¶

All the complexity in this code lies in the conditional logic. One of the conditionals is made more complicated by a combination of several values plus an inline function. The most difficult part of understanding this code lies in following all the branching ways execution may flow.

If you were to pick up this code to make edits, you would have to carefully read through these conditionals and try to keep all the possible paths in mind. It’s a lot of little things you need to keep in your working memory while you make changes.

To minimize this mental load, it’s best to reduce the number of conditionals, and to remove else clauses entirely if possible.

The best technique to do this is to return early.

If the block of code is part of a longer function, enclose it in a new function of its own. Return out of that function as various cases are handled. Doing this results in code more like the following:

const getMessage = () => {
  if (item) {
    if (item.isActive || (item.isDefault && !items.some((i) => i.isActive))) {
      return 'Active';
    }
    return 'Inactive';
  }

  if (hasError) {
    return 'Error loading item';
  }
  if (isLoading) {
    return 'Loading...';
  }
  return 'No item selected';
};

const message = getMessage();

Now, there are no else statements required. Each time a case is handled, the message value is returned, and that condition can be disregarded for the rest of the function. The nesting has been simplified, making the code a lot more linear.

Note: I defined this function inline, where the pertinent values are all in scope. If this were part of a much longer function, however, I would probably move the getMessage() function definition below it, passing the necessary values as parameters. This would keep the flow of the larger function more straightforward, and setting the message variable would only require a one-line call to the new function.

Handle edge cases first ¶

At the beginning of the new function, checks are made to see if we’re on the “happy path”, and if so the function returns the expected value ('Active' or 'Inactive'). After that, all the edge cases are handled.

This approach requires two nested conditionals at the beginning of the function. Instead, it’s often simpler to reverse the order and handle the edge cases first. The errors and loading states are a quick check in this case, so make those checks as the very first thing in the function, moving the core logic of the logic below them:

const getMessage() => {
  if (hasError) {
    return 'Error loading resource';
  }
  if (isLoading) {
    return 'Loading...';
  }
  if (!item) {
    return 'No item selected';
  }

  if (item.isActive || (item.isDefault && !items.some((i) => i.isActive))) {
    return 'Active';
  }
  return 'Inactive';
}

const message = getMessage();

Now, when working on the meat of the function, you can know that edge cases are dealt with and dismiss them from your mind. This frees up your mental energy to focus only on the core logic you’re concerned with. This is especially useful when the logic is more complicated.

This code is the exact same number of lines as the original, but the logical flow is much simpler.

Simplify boolean logic ¶

There’s one final way you can simplify this code further.

Boolean logic is not intuitive. The computer is excellent at it, but it does not come naturally to us. Think about a simple example:

if (a && b) {
  doX();
} else {
  doY();
}

When does the else case execute?

It executes when the conditional is false, or if (!a || !b). Reversing the logic mentally means negating each value and changing the and to an or.

It gets even more complicated with three or more values. When does the statement if (a && b || !c) evaluate to false? Can you figure it out instantly by looking at it, or do you need to trace through each piece of it carefully to be sure?

If this sort of logic is part of two or three nested conditionals, and you find a new edge case in your code, how confident will you be that you’re placing the new code in the right part of the conditional? How confident will you be adding a new variable d to the conditionals and understanding how it impacts the existing logic?

This kind of change to code is extremely prone to bugs.

When I encounter a complex conditional, I always look to see if there’s a way to simplify it down and assign it to a variable with an easy to understand name.

In the code above, this certainly means moving the inline function out of the if statement:

const noActiveItems = !items.some((i) => i.isActive);

I’d also consider setting the entire conditional to a single variable, called isActive. This gets me a final version of the code that looks like this:

const getMessage = () => {
  if (hasError) {
    return 'Error loading resource';
  }
  if (isLoading) {
    return 'Loading...';
  }
  if (!item) {
    return 'No item selected';
  }

  const noActiveItems = !items.some((i) => i.isActive);
  const isActive = item.isActive ?? (item.isDefault && noActiveItems);
  if (isActive) {
    return 'Active';
  }
  return 'Inactive';
};

const message = getMessage();

Now, when the next developer comes along, this should be much faster to skim and understand.

Edge cases are dealt with, and can be disregarded before the core logic is considered. The final if (isActive) is easy to understand without even reading the two lines above it. If the developer needs to look closely at how isActive is determined, they can, but if that’s not a part of the logic they’re looking to change, they can almost completely ignore the lines that assign values to noActiveItems and isActive.

This code flows linearly, has no deep nesting, and requires much less focused effort to parse. Life is just a bit easier for developers maintaining it, and any new changes will be less prone to bugs as a result.

Theme Machine 2.0

2024-12-30T19:15:24Z

I’ve just released a huge update to the Theme Machine. This is a tool a first put online last summer for building color palettes and exporting them as CSS custom properties. If you haven’t played with it yet, go a head and give it a try.

Note: I made the tool responsive, so you can play around with it on mobile and see what it does, but it’s really designed to be used on desktop as part of a web development workflow.

New changes ¶

There’s a lot in this update! Here are all the biggest changes:

More vivid colors ¶

Originally, I thought it made sense to have your fully saturated accent colors, as chosen in the color wheel, and then slightly desaturated shades of that to use for UI elements like backgrounds and borders. However, the Theme Machine already generates one or two neutral colors based on your chosen colors, so this seems unnecessary. If you want more desaturated colors, you can add them, but by default now the generated shades have enough saturation/chroma to match your exact selected colors.

Shade generation settings ¶

With the chroma changes above, I had some decisions to make regarding how to treat generation of the shades of each color. Online polling led to split opinions, so I decided to expose the option to the user and let you decide what you need.

There are three options for how shade lightness is calculated: “Uniform lightness” generates shades of hand-selected lightness values (derived from Open Props 2.0 beta). It’s unlikely your selected colors precisely align with one of these lightness values, however, so this option will slightly round your selected color to the nearest shade. With this option, each palette will have uniform lightness across all shades (e.g. --blue-4 will have the exact same lightness as --green-4).

I think these hand-selected values produce the best looking palette, so I’ve left it as the default, but if you have precise brand colors you want in your palettes, the “prioritize selected colors” option will preserve them exactly. The shades above and below your color are spaced evenly in the OKLCH color space.

The final option, “center on selected colors” places your selected colors at the center of the palette, and evenly distributes lighter and darker shades in each direction.

For the chroma options, the default value, “centered” places the most vivid colors near the middle of each palette (This is also based on Open Props approach). If your selected colors are particularly light or dark, however, this can produce overly saturated colors near the middle. The second option, therefore, ensures your selected colors are the most saturated ones in each palette, and the lighter and darker shades have less chroma.

Color wheel options ¶

The Color Wheel allows you to select harmonious colors of equal lightness and chroma, using the OKLCH color space. This can be problematic with some hues, especially yellows, which get muddy and brown at lower lightness levels.

I’ve added an option to “brighten muddy yellows” to help with this. You can also fine tune your colors further in the Shade Generator after selecting them in the Color Wheel.

I’ve also changed the color wheel behavior, so the colors you find in the wheel are not automatically all added to your palette. You can add them all yourself, or add them individually if you wish. Then, you can continue to use the wheel to find more colors and add those to your palette before moving on to the Shade Generator page.

Semantic color variables ¶

There are new semantic custom properties you can edit to build out your general website theme. There are three background colors, two text colors, and a primary brand color.

Swatches of each are displayed near the bottom of the screen. Click on one of these to edit it, by selecting from the shade palettes above.

WCAG contrast checking ¶

Examples of both text colors on each of the the background colors appear on the right side of the screen. A green checkmark circle icon appears if the combination meets the AA standard for text color. This is stacked in front of a second circle if AAA is met. If the contrast is low, a red caution icon appears.

Click on the icon to see the exact contrast measurement and which WCAG criteria this value meets for text, headings, and graphical elements such as icons and buttons.

Full preview page ¶

I’ve found that a palette in the Theme Machine doesn’t always feel the same after exporting it and using it to build a full interface. The Theme Machine has a dark background and colors of its own that can influence how your theme colors appear.

A new Preview page shows only your colors, building the page entirely out of your selected semantic colors and shades. This should give a clearer idea of how your theme will appear in a real-world website.

A number of mock UI widgets appear on the page in a range of your colors. Hovering the mouse over this will display exactly which of your colors were used to generate the element.

Public issue tracker ¶

I’ve started a public issue tracker on GitHub where you can leave feedback, report bugs, and request features. Let me know what you want to see!

I have a handful of further improvements I’d like to make, but until then, happy theming!!

CSS in Depth Addendum

2024-10-17T19:37:07Z

As I wrote the both editions of CSS in Depth, I worked hard to stay on top of emerging features in CSS and where browsers were at in regards to adding support. The book writing process is lengthy, so this sometimes involved making my best estimates about what features would have browser support in at least one major browser by the time the book went to print.

This approach enabled me to be one of the first books to print covering significant CSS features like grid (in the first edition), @scope, nesting, and color blending (in the second), among many other smaller features. Overall, I’m happy with the way I handled this, and I’m proud to have such a cutting-edge book available now.

However, there are a few smaller features I left out of the second edition that I now wish I hadn’t. I was aware of them while writing, but I simply underestimated how rapidly browsers were going to implement them. Some of these had not even been proposed when I started on the second edition, and yet they already have at least some browser support, only 18 months later.

If you’ve read, or plan to read, CSS in Depth, here are three brand new features that didn’t make it into the book, but I think are worth knowing (and the chapter numbers in the Second Edition where I would put them).

New text-wrap options ¶

The text-wrap property now supports two new values, balance and pretty.

Applying text-wrap: balance to an element will adjust line wrapping of text so each line is roughly the same length, rather than putting as much text as possible on each line but the last. This is most useful for headings or other short pieces of text.

Using text-wrap: pretty will mostly behave like text-wrap: wrap, except it will prevent an “orphan” (a lone word on its own line) from the last line of each paragraph.

For a deeper look at these, check out this article from Stephanie Stimac. Browser support is still pretty new, but progressive enhancement is easy. You can pretty safely add this sort of code to your stylesheet, and it will improve the typography in browsers that support it:

h1, h2, h3, h4, h5, h6 {
  text-wrap: balance;
}

p {
  text-wrap: pretty;
}

Where it belongs: Chapter 12, Typography and Spacing

Easier dark mode with light-dark() ¶

We have a lot of power in CSS now to support both light and dark mode based on user preferences. I cover aspects of this in several places throughout my book, but some of the techniques used are a little verbose.

The light-dark() function allows you to provide a color for both light mode and dark mode in one single line:

.widget {
  background-color: light-dark(#eee, #222);
  color: light-dark(#222, #eee);
}

This sets near-black text (#222) on a light gray background (#eee) in light mode, but reverses the colors in dark mode. The browser decides which of the two values to use based on the current value of the color-scheme property.

See Adam Argyle’s article for several examples and more details on this function. This is in the latest version of all major browsers now, but it’s probably a bit too soon to rely on it quite yet, at least without some sort of fallback plan.

Where it belongs: Chapter 11, Color and Contrast

Anchor positioning ¶

Anchor positioning is a brand new method that allows you to place an absolutely positioned element relative to another element. Where older methods required placement to be relative to some ancestor element, this allows much more flexible positioning.

This feature is a bit more complicated than those above, and require a deeper dive to fully understand. Here is a CSS anchor positioning guide I recommend.

This feature emerged rapidly. It was first proposed in May of 2023, and arrived in Chrome only a year later. We’re still waiting on other browsers to add support, but this is a feature worth keeping an eye on.

Where it belongs: Chapter 6, Positioning and Stacking Contexts

A Structured Approach to Custom Properties

2024-06-28T19:40:06Z

Yesterday, I announced the release of the Theme Machine, a tool for generating custom palettes as CSS custom properties. I hope this tool proves useful for many developers, but it’s really only the first step in managing color in CSS. I think it’s worth stepping back and looking at the bigger picture of custom property management in general.

If you’re anything like me, you’ve probably tried a handful of different approaches to organizing your custom properties. Most approaches I’ve used have been adequate, but I rarely feel completely satisfied with them. I spent far too long flailing about trying to find what worked. I should have looked sooner to the realm of design tokens. I think some common standards when building a design system are useful when applied directly to CSS custom properties.

I’d like to lay out my current approach. In many ways, these thoughts are still a work in progress, but I feel good enough about them to teach them, and at the very least invite feedback. You’ll notice my thoughts here start concrete, but things will start to get a little fuzzier toward the end of this post.

Three tiers ¶

Every custom property you define should fall in one of three categories, and you should always be aware when defining or using a custom property which category it belongs to. I’m going to refer to these three types of property as primitive, semantic, and module properties. If this sounds familiar from the world of design tokens, that’s because it’s nearly the exact same concept.

Primitive properties hold raw, generic values. A design begins with initial decisions about what colors and fonts and other elements “fit” the design. These values should be stored in primitive properties.
Semantic properties supply context and meaning. The names of these properties imply where they should be used throughout the stylesheet. These are often built out of primitive properties, but supply additional direction as to their use.
Module properties are used only within the confines of a particular module or component on the page. If a dropdown menu has its own drop shadow in a custom property, for instance, it may be defined within the scope of that module rather than globally on the page as a whole.

I’ll explain each of these in more depth and provide some practical examples to show what they typically look like.

Primitive properties ¶

Primitive custom properties are global and static. Chief among these are your color palettes. They will typically also include font stacks. There may be a place for a few other items in this tier, but most things beyond these will typically belong in other tiers.

:root {
  --blue-1: oklch(98% 0.008 250deg);
  --blue-2: oklch(93% 0.028 250deg);
  --blue-3: oklch(80% 0.045 250deg);
  --blue-4: oklch(66% 0.056 250deg);
  --blue-5: oklch(58% 0.059 250deg);
  --blue-6: oklch(49% 0.053 250deg);
  --blue-7: oklch(35% 0.042 250deg);
  --blue-8: oklch(20% 0.025 250deg);
  --blue-9: oklch(10% 0.014 250deg);
  /* repeat this pattern as needed for gray, green, etc. */

  --font-serif: 'Georgia Pro', Georgia, serif;
  --font-sans-serif: 'Source Sans 3', sans-serif;
  --font-monospace: 'Fira Mono', Consolas, monospace;
}

Here’s the key rule for this first tier: you should not be using them throughout your stylesheet. You should instead be using them to build custom properties on the next tier, the semantic properties. Let’s look at the other types of properties, then I’ll come back to this rule and why I try to hold myself to it.

Semantic properties ¶

Semantic properties are the real building blocks of your design. While the primitive properties define all the values you’ll need within the scope of your design, each semantic property maps one of those primitive values to a practical intent.

In this tier, you can define a set of background colors, text colors, common margins and border radius sizes. Many of these properties will be derived from primitive properties, looking something like this:

:root {
  --background-1: var(--gray-2);
  --background-2: var(--gray-3);
  --background-3: var(--gray-4);
  --text-1: var(--gray-9);
  --text-2: var(--gray-8);

  --font-display: var(--font-serif);
  --font-body: var(--font-sans-serif);
  --font-code: var(--font-monospace);
}

Some properties on this tier might be defined with explicit values. You could potentially define primitives for common lengths, like --length-sm: 2px and --length-md: 4px then use these to define semantic border radius properties, but in many cases this is likely overkill, and it’s more practical to simply apply these values directly to the semantic properties like this:

:root {
  --radius-sm: 2px;
  --radius-md: 4px;
  --radius-lg: 8px;
}

Other useful semantic properties include anything and everything you want to keep consistent throughout your design. This often includes:

font sizes
font weights (especially if you have a variable font and want to specify uncommon weights like 300 or 900)
line/border widths
spacer sizes for padding and margin
border radius
drop shadows
easing functions

Theoretically, a robust set of semantic property names could be reused over and over again across projects with few modifications. Only the values assigned to those properties would change across different designs.

The potential to be dynamic ¶

Like primitive properties, semantic properties are global to the page. However, some of them might be dynamic. This is especially common if you want to allow the user to switch themes or you want to support both light and dark modes. The primitive --gray-2 always means the same gray, but it’s only a background color in light mode. In dark mode, it might be a text color. You can make this distinction when you define your semantic properties.

:root {
  color-scheme: light;
  --background-1: var(--gray-2);
  --background-2: var(--gray-3);
  --background-3: var(--gray-4);
  --text-1: var(--gray-9);
  --text-2: var(--gray-8);
}
@media (prefers-color-scheme: dark) {
  :root {
    color-scheme: dark;
    --background-1: var(--gray-9);
    --background-2: var(--gray-8);
    --background-3: var(--gray-7);
    --text-1: var(--gray-1);
    --text-2: var(--gray-2);
  }
}

Note that this is even simpler with the light-dark(), though browser support for this function is still pretty fresh:

:root {
  --background-1: light-dark(var(--gray-2), var(--gray-9));
  --background-2: light-dark(var(--gray-3), var(--gray-8));
  /* etc */
}

If you use Lightning CSS, you can use light-dark() now, as they found a creative way to transpile it to more broadly supported syntax — though be sure to test this well if you allow the user to dynamically switch themes.

Reduced cognitive load ¶

As well as enabling theming support, semantic properties streamline the mental task of everyday coding. You might have eight or ten or 16 different grays and just as many blues, but in your semantic properties, you only have a small handful of background colors.

When you need to set the background color of a module, and you use primitives directly, you’ll find yourself thinking, “Did I use --gray-4 or --gray-3 for the background of that other similar module?” But with a much smaller subset of semantic background properties to choose from, you’re more likely to recall that --background-2 is the one you’ve been reaching for repeatedly.

When you rely on semantic properties instead of your primitives, you don’t have to keep making the same decisions over and over, and you don’t have to continually refer back to other code to remember the decisions you’ve already made.

Module properties ¶

The last tier is for properties that are not global, but are instead scoped locally to a single module/component on the page.

If you need to calculate multiple properties based on a single value, or you need to change the size of part of a component responsively, this is a way to do it.

For example, in the current design on this site, I use this sort of property to manage the circle clip path of the banner image at the top of every post. It looks like this:

.banner-image {
  --radius: min(35vw, 750px);
  --offset: 10vw;
  --circle: circle(var(--radius) at var(--radius) var(--offset));
  position: relative;
  z-index: 1;
  clip-path: var(--circle);
  shape-outside: var(--circle);
  float: right;
  width: calc(var(--radius) + var(--offset));
  shape-margin: 0.5rem;
}

These variables are all defined and used locally only within this particular module. Because they’re defined right here, I don’t really need to worry about variable name collision from other modules higher in the DOM. (Though you do need to avoid overriding semantic properties that might be referenced by any nested child modules.)

This also makes aspects of responsive design much simpler. Use a media query or container query to adjust a module custom property:

@media (min-width: 720px) {
  .logo {
    --size: 70px;
  }
}

This is just so much less cognitive load than re-defining a bunch of properties directly. Responsive design often involves a lot of looking up and down the stylesheet to see which properties are specified at which breakpoints and trying to keep mental track of which override in various circumstances. It’s not always practical to relegate this logic purely to a custom property, but it’s absolutely worth doing when you can.

Trying not to use primitive properties directly ¶

I mentioned early the general rule that I avoid assigning primitive properties directly in my styles. Rather, I use them only to build out other custom properties.

It’s often very tempting to break this rule. Maybe you’ll really want a component on the page to have a border that’s colored --blue-6. If I’m totally honest, I break it sometimes, too, but it always gives me pause. It will often make some trouble down the road, and I weigh whether I want to deal with that. I ask myself a few questions:

Is this really a one-off use of this value?
Why don’t any of my existing semantic properties meet this need?
Is there a general semantic meaning I’m reaching for, and should I codify it in a semantic property if one doesn’t already exist?
Will this complicate any theme switching on my site?

Ideally, there will be a semantic meaning I can create instead. I’ll add a new semantic variable to the root of the page and rely on that.

At the same time, I’m also cautious about populating the page with hundreds of semantic properties that are only ever used once in the stylesheet.

My hope is that I will, over time, develop a robust system of common semantic properties that will greatly reduce the need to ever reach for these one-offs. I have further thoughts on this already, and hopefully I’ll be able to gather them into another post in the future.

Thoughts on naming conventions ¶

Ideally, I’d like to propose a clean naming convention that always makes clear which property is of which type, but I’ve never really seen or come up with something I totally love.

It’s unfortunate that custom property names are severely limited. You can use alphanumerics, hyphens, and underscores. The only other characters available non-ASCII unicode. As fun as the property --🎩-color is, it’s totally impractical for real use. Characters that are easy to type like dollar signs, asterisks, periods, and parenthesis only work if you escape them with a backslash, and I just find that ugly.

Module properties might be the easiest to identify. I think a leading underscore is a reasonable convention, akin to private variables in many programming languages. You can see at a glance that color: var(--_color); references a local, module-specific property. I’ve used this convention occasionally, but not always consistently.

As far as differentiating primitive vs. semantic properties, nearly every idea leads down the realm of BEM-like syntax, with a clutter of double hyphens or a mix of hyphens and underscores, but I don’t think anyone was ever really excited about that in the past and I would really love to avoid going down that sort of path again.

One thing that might be practical is the use of uppercase characters. Perhaps an all-lowercase --size-sm could indicate a primitive property, while a capitalized --Spacer-md or even --SpacerMd indicates a semantic one. Or maybe every primitive could be prefixed with p-.

I don’t know. I’m not sure I love camel-casing my custom properties, or the distinction needs to be so explicitly described in the syntax. I guess I have a thing for code that doesn’t look ugly to my eyes.

I’d love to hear your thoughts on all this.

Hopefully it’s helpful to you to draw these distinctions between different types of custom property. When I survey existing pattern libraries, I see a lot of this kind of pattern, but I haven’t seen it really being explicitly discussed anywhere publicly.

Theme Machine: A CSS Color Palette Tool

2024-06-27T17:27:49Z

Sometimes, I just want to start building a project.

I’ll create a new stylesheet, define my base styles and a handful of custom properties, and start coding. Before I know it, I realize I need a couple more colors. I’ll either just define an ad-hoc color right there in the stylesheet, or, if I’m being disciplined, I’ll define a new custom property for it and use it accordingly.

But I always find I need more colors. I need a whole spectrum to choose from. I know I can, and maybe should, start by dropping in a bunch of colors from Open Color or Open Props, but what I really want are my colors. I want to choose my own tint of blue, or green, or red.

So I finally set aside the project that needed those colors, and built a tool to help with that. Don’t ask me where this lands on that old XKCD efficiency chart.

I’ve called this the Theme Machine. It’s really two tools in one.

Color picker ¶

First is the Color Picker. This is a color wheel, with draggable handles for selecting colors. It can automate choosing complimentary colors, or analagous colors adjacent to one another, or two sets of complimentary colors.

If you already have a primary brand color, you can paste that in the input field in any valid CSS format. Or, just have fun playing with the wheel until you find a color that speaks to you. Toggle the mode between complimentary, analagous, split complimentary, or even freestyle color schemes to find other colors that go with your selection.

Adjust the lightness or vividness (chroma) sliders, and all the colors will adjust together to remain harmonious. You’re basically working with OKLCH color directly.

It will warn you if your colors are out gamut for most displays. Fix this if you can, but don’t sweat it too much unless several of your colors show the warning; you’ll be able to fine tune each color further in the next step.

Palette generator ¶

When you like your colors, click the button at the bottom to export them to the second tool, the Palette Generator.

For each of the colors you selected, the Theme Machine will generate an entire spectrum of shades from white to black. It will also provide an “accent” color that’s the fully vivid version of the color you chose. It will make an educated guess at good names for those colors which will be used to produce the custom properties.

Depending on the colors you chose, it will also generate one or two neutral tones and a spectrum of shades for those as well.

Each palette can be renamed or otherwise adjusted to your liking. You can also add additional colors to your palette.

The Theme Machine creates CSS custom properties for all of your palettes. When you’re happy with your selections, copy the CSS on the right and drop it into your project.

Give it a go! Let me know if you have any problems, questions, or feature requests. Happy styling!

Assessing Web Component Libraries

2024-06-11T15:30:22Z

I’ve started on a project recently and realized it’s a perfect use case for web components. It’s an Eleventy site that’s primarily markdown, so dropping custom elements into the markdown is just too easy. It requires basically no new plumbing beyond the bare bones esbuild setup I’ve already got in place.

This is my first time in web components doing anything more involved than a quick dabble, so I ended up spending the last week exploring some of the various web-component-based framework option out there, and boy do I have opinions.

General thoughts on WC and frameworks ¶

Before I dive into the various frameworks I assessed, I want to share some general thoughts on web components that color the impressions I had.

First of all, I don’t want Shadow DOM except in a few very specific circumstances. So many in the WC community make a huge deal about “scoped styles” provided by Shadow DOM. Let me put it plainly: this is a flat out lie, and probably the biggest thing that put me off from web components for a long time.

Shadow DOM does not provide scoped styles; it provides isolated styles. That’s a very different thing for a very different purpose than every day application development. Thankfully, others in the community are starting to come around on this. The thinking seems to be shifting here, For me, the realization that I can use custom elements all in the light DOM has finally made web components a practical option.

The second thing about vanilla web components is that they, by themselves, aren’t a substitute for traditional JS web frameworks. They are just too low level, and are missing way too many essential quality of life improvements found in those frameworks.

Thankfully, there are some very lightweight frameworks built on native web components that aim to ease development. I’m still a bit unsure whether these are suitable replacements for more broadly used frameworks like React when it comes to full-featured, complex apps that are on the far end of the spectrum away from static web pages — i.e. true applications — but these certainly can have a place near the middle of that spectrum.

Lit ¶

Lit is the most well known of these frameworks. It’s got the longest history — it’s a successor to Polymer, which was the first (very polyfill-dependent) big WC framework.

My first impressions were good here, though I also had the name “Lit HTML” in my head and it took a while to piece together that Lit is the framework and lit-html is the library it uses internally, which parses HTML template strings in order to build a DOM representation.

If you really want, you can build your own framework on top of lit-html. I entertained that idea for a bit, but eventually decided that was signing up for a whole lot of work when I really just wanted to get going on my actual project.

Defining a custom element comes down to creating a class that extends LitElement, which itself extends the native HTMLElement. I like that this means if I need to get to the bare metal and do something that’s not explicitly supported by Lit, I can. The inner markup is defined via a template literal in a render function, which looks something like this:

class MyComponent extends LitElement {
  render() {
    return html`<div>Component content here</div>`;
  }
}

The one thing I really don’t like about Lit is it defaults to putting every component in Shadow DOM. Opting out requires overriding the createRenderRoot function in each and every one of your components. I really wish this was doable with a simple flag to the constructor or something instead, or even better, a global config option that made it so Shadow DOM was opt-in rather than opt-out in each component.

My big stumbling block here came when I needed to build a component that used <slot>s but I wanted to stay in the Light DOM. This lead me to the next framework.

Enhance ¶

Enhance aims to be a full-featured web framework. It’s got its own build pipeline and has out-of-the-box SSR, which is really impressive. However, you don’t have to do all that and can instead just use their CustomElement class to to build custom elements in the site you’ve already got, which suits my needs more right now. I like that flexibility.

It also supports <slot> elements in Light DOM components, which is also very nice.

Similar to Lit, you create a custom element by extending their CustomElement class, which is extends HTMLElement. It also uses a template literal to render component contents.

As I experimented with Enhance a bit, though, some of its opinions started to rub me the wrong way. The main CustomElement class doesn’t do anything to wire up event handlers for you; you have to manually bind them to the class, manually invoke addEventListener, and manually evoke removeEventListener for each one. There is an odd way around this, where, instead of extending the base class, you define your entire component in an object literal then pass that to an enhance() function which builds the class for you. I can’t entirely put my finger on why, but this just feels wrong to me. I shouldn’t have to be an extra layer removed from the abstraction for what I consider a bare bones essential feature of a modern framework.

The other thing I didn’t like was how strictly prescriptive the framework is regarding file structure. This doesn’t matter if you’re only using their CustomElement class in your own build pipeline, but as I read through the docs, this left a bad taste in my mouth. Enhance really pitches the idea that it’s a full-fledged application framework, but this convention feels much more in line with a static site generator. It gives me the impression it’s trying a little too hard to be both, and I’m cautious about what compromises they’re going to have to make to go down both paths at the same time.

This is probably a fantastic framework for some folks, but eventually I decided there was just too much I wasn’t a fan of.

WebC ¶

I saw this listed alongside Lit and Enhance around the web, so I looked it up. This was created by Zach Leatherman as what I guess I’d describe as a sub-project of Eleventy. The WebC docs seem to live on the Eleventy website.

WebC is not written in JavaScript. It’s written in HTML, with a series of custom directive-like attributes, which look something like:

<div webc:for="(myItem, myIndex) of [1, 2, 3]" @text="myIndex"></div>

or:

<syntax-highlight
  language="js"
  webc:import="npm:@11ty/eleventy-plugin-syntaxhighlight">
  function myFunction() { return true; }
</syntax-highlight>

This to me is an immediate non-starter. Sure, this is great for some small, light-touch stuff, but I need to build my components in a Turing-complete language. I don’t want to deal with the headache that inevitably emerges the moment I need to do something that doesn’t have a corresponding, already-supported directive. I’ve been down that road with too many languages in the past.

It didn’t take long for me to toss this one aside. Sorry Zach.

Final thoughts ¶

Evaluating these were hard. I’ve been developing primarily in React for over a decade, so I have a lot of habits and opinions that have been influenced by that framework.

I know web components are a whole different thing, so I tried my best to come at them with an open mind. It needs to be okay for a new framework to not look like the old one, so I often had to stop and sort whether I disliked something on merit versus disliking it because it’s not what I’m used to.

I eventually landed back on Lit for my current project. I even devised a way to use <slot>s in a Light DOM custom element.

I think I’m happy with it. We’ll see once I’m a lot further down the road.

CSS in Depth, Second Edition

2024-05-30T21:18:50Z

I’m so excited to say I’m just finishing up reviews of the final copyedits for the second edition of my book, CSS in Depth! If you’ve ordered a print edition of the book, it’ll be on its way soon. If you haven’t ordered a copy, you can order now on manning.com — both the print edition and eBook will get you immediate access to the early access (“MEAP”) eBook while the publisher finishes finalizing page layout.

Big changes ¶

This edition features significant updates since the first edition. If you’re looking to really understand CSS, this is the book for you. Or if you’re already a seasoned developer looking to catch up on all the rapid changes of the past few years, this is for you, too.

Every chapter has been updated; most chapters have at least one new section, and some are heavily revised throughout. Plus I’ve written three entirely new chapters.

The first edition, published in 2018, bridged the gap from the old way of laying out webpages (floats) to the new (flexbox and grid). In this edition, I’ve tossed out all the stuff that is now fully obsolete, and have focused on bridging the transition into the next phase of CSS development. That means logical properties, subgrid, layers, scope, container queries, new color spaces, color mixing, and relative color functions, and more. I’ve also thrown in a new chapter covering filters, masks, shapes, and clip paths, because I always regretted not including those the first time around (and browser support is much better now).

As an extra bonus, a handful of key pages will be printed in color. I can’t do proper justice to new color spaces and gradient features without that, right?

CSS for 2024 and beyond ¶

This is a forward-looking book. It will give you a mastery of the language and prepare you for all the new CSS features that are emerging today. Get yourself a copy!

If you’ve already purchased it, thank you! Please help spread the word.

I Do Not Like These LLMs

2024-05-28T15:40:20Z

Altman Sam
Sam Altman

That Sam Altman
That Sam Altman!
I do not like
that Sam Altman.

Do you like
these LLMs?

I do not like them,
AI Man.
I do not like
these LLMs.

Would you like them
Here and there?

I would not like them
here or there.
I would not like them anywhere.
I do not like these LLMs.
I do not like them, Sam Altman.

Would you like them
on your phone?
Would you like them
to run your home?

I do not like them
on my phone.
I do not want them
to run my home.
I do not like them
here or there.
I do not like them anywhere.
I do not like these LLMs.
I do not like them, Sam Altman.

Would you use them
in VS Code?
Would you use them
in Stack Overflow?

Not in VS Code.
Not Stack Overflow.
Not on my phone.
Not in my home.
I would not use them here or there.
I would not use them anywhere.
I would not use these LLMs.
I do not like them, Sam Altman.

Would you? Could you?
in your bank?
Use them! Use them!
I’ll take your thanks.

I would not,
could not,
in my bank!

You may like them.
I do affirm.
You may like them
in iTerm?

I would not, could not in iTerm.
Not in my bank! That makes me squirm.
I do not like them in VS Code.
I do not like them with Stack Overflow.
I do not like them on my phone.
I do not like them in my home.
I do not like them here or there.
I do not like them anywhere.
I do not like these LLMs.
I do not like them, Sam Altman.

A car! A car!
A car! A car!
Could you, would you
ride an AI car?

Not in my car! Not in iTerm!
Not in my bank! Sam! I stand firm!
I would not, could not, in VS Code.
I could not, would not, in Stack Overflow!
I will not use these in my home.
I will not use them on my phone.
I will not use them here or there.
I will not use them anywhere.
I do not like them, Sam Altman.

Say!
In your search?
Here in your search!
Would you, could you, in your search?

I would not, could not,
in my search.

Would you, could you,
to book a plane?

I would not, could not, to book a plane.
Not in my search. Not in my car,
Not in my bank, Not in iTerm.
I do not like them; I am firm.
Not on my phone. Not VS Code.
Not in my home. Not Stack Overflow.
I will not use them here or there.
I do not like them anywhere!

You do not like
these LLMs?

I do not
like them,
Sam Altman.

Could you, would you,
to choose your food?

I would not,
could not,
to choose my food!

Would you, could you,
eat pizza glue?

I could not, would not, eat pizza glue.
I will not, will not, in my food.
I will not use it to book a plane.
I will not use it in my car.
Not in a search! Not in iTerm!
Not in my bank! I’m very firm!
I do not like them in VS Code.
I do not like them in Stack Overflow.
I will not use them on my phone.
I do not like them in my home.
I do not like them here or there.
I do not like them ANYWHERE!

I do not like
these LLMs!
I do not like them,
Sam Altman.

You do not like them.
So you say.
Try them! Try them!
And you may.
Try them and you may I say.

Sam!
If you will let me be,
I will try them.
You will see.

…

They told me to eat rocks.

Weighing in on CSS Masonry

2024-05-17T18:45:48Z

I love to see the discussion moving on CSS “masonry” (or “waterfall” or whatever the name may eventually be). The key question at this point seems to be whether this specification should continue to live as a part of grid, or if it should be its own thing.

Kicking off the discussion are this Webkit blog post and this Chrome blog post. I want to give my take.

Should masonry be its own display method outside grid? Absolutely.

I can think of a number of reasons why it should be separate — many of which Rachel Andrew lists in the Chrome blog post above — but one key argument jumped out at me. She only touched on it briefly, but for me it sealed the argument: grid-template-areas.

How developers learn and use grid ¶

Grid is an immensely versatile layout system. You can rely on grid to implicitly place the grid items; you can use grid line numbers to position items in the grid; you can name grid lines and place items using those names. And you can use grid-template-areas to draw an ASCII-art style layout with named areas, then place items into these areas by name.

This last approach allows for an approachable, high-level introduction to grid:

.my-page {
  display: grid;
  grid-template-areas:
    'logo   header header'
    'nav    nav    nav'
    'main   main   sidebar1'
    'main   main   sidebar2';
  grid-template-columns: 1fr 2fr 1fr;
}

Personally, I don’t use grid-template-areas very often. I’m happy with a slightly lower-level approach using numbered or named lines, but I completely understand the appeal of named template areas. From what I’ve seen in discussions and blog posts online, naming template areas has a huge broad appeal, especially among newer CSS developers. It’s approachable and serves as a gentle introduction to the monstrously large set of features available in grid.

For many developers, it appears to me this is the primary — and possibly only — way they know how to use grid.

The problem is, this feature is almost meaningless in masonry.

To educate people about masonry layout, we can’t simply say, “just define a grid and set grid rows to masonry. If that developer’s understanding of grid is limited to named template areas, they will happily type display: grid and, as is their habit, grid-template-areas: and will run into a problem, right out of the gate. What should this property be set to? The way forward for them will not be immediately clear.

This developer has in mind the goal of learning how masonry works, but the way to achieving that goal lies in a deeper understanding of grid, apart from masonry.

A clearer educational path ¶

If masonry is a part of grid, the way to teach masonry becomes: “go learn grid at a deeper level.” Then, upon learning more about grid, the next step becomes: “half of what you just learned about grid does not apply to masonry.”

That sounds like a pretty terrible learning experience.

Masonry has a number of things in common with grid, and a lot of the knowledge of one can be brought to the other, but they also diverge in a lot of ways.

I think it’s far more approachable to teach display: masonry and all the new properties that go with it. Then, at the end of that lesson, you can say, “and the good news is, most of what you just learned applies to grid as well!”

Now, instead of putting in work and being confronted with the news that you didn’t need it all, you get the opposite: after putting in the work, you learn it does double-duty! As a student, I’d prefer that learning experience any day. As a teacher, I’d definitely prefer to give that learning experience.

My CSS resets

2024-01-04T17:49:36Z

Every now and then, I see someone post their latest and greatest set of CSS resets. Here’s mine:

@layer reset {
  *,
  *::before,
  *::after {
    box-sizing: border-box;
  }

  body {
    margin: unset;
  }

  button,
  input,
  textarea,
  select {
    font: inherit;
  }

  img,
  picture,
  svg,
  canvas {
    display: block;
    max-inline-size: 100%;
    block-size: auto;
  }

  @media (prefers-reduced-motion: reduce) {
    *,
    *::before,
    *::after {
      animation-duration: 0.01ms !important;
      animation-iteration-count: 1 !important;
      transition-duration: 0.01ms !important;
      scroll-behavior: auto !important;
    }
  }
}

Some popular resets are a bit more opinionated than this, but this one strikes the right balance for me. My goal is that I can copy this whole thing into any project the moment I start it and be on good footing when I start building out the global styles.

I’ll break it down bit by bit:

Box sizing reset ¶

*,
*::before,
*::after {
  box-sizing: border-box;
}

Make everything use the more predictable border box sizing.

My previous technique involved setting this to inherit and then applying border-box sizing once at the root. The benefit of that was to make it easier to revert a chunk of the page to content-box sizing if needed, specifically when bringing in a 3rd party widget.

However, I found I haven’t had to do that in ages. Any plugins or 3rd party components I use these days are modern enough that they too use border box sizing.

In practicality, that was a small piece of complexity I never really need, so I’ve simplified to this current approach.

Remove body margin ¶

body {
  margin: unset;
}

Does anybody ever want that 10px body margin? It’s a holdover from a lost age of the web, so I nuke it.

I like using unset rather than 0 here because it’s just a bit more clear what my intention is. I’m not setting a 0px margin, I’m removing a setting the browser has made.

Form input fonts ¶

button,
input,
textarea,
select {
  font: inherit;
}

The default form fonts are weird, especially for buttons. I’m going to set a font and font size I like on the page. This makes sure my selection carries over to buttons and inputs.

I generally caution against the use of the font shorthand property, because it overrides so many different font-* properties all at once, but in this case, that’s exactly what I want. Inherit everything.

I’ll almost certainly be adding more opinionated styles to these elements in my global styles layer, but this puts them in a reasonable state even before I get to that.

Images and similar media ¶

img,
picture,
svg,
canvas {
  display: block;
  max-inline-size: 100%;
  block-size: auto;
}

I can’t recall the last time I used an <img> as an inline element. They’re almost always part of the page structure, so I make them block level. This ensures they don’t overflow horizontally out of their container and generally behave more predictably.

Harry Roberts has a rather interesting, highly opinionated take that goes a lot further than this. I like his ideas there, but in practicality, they’re just a bit too much for me. I figure I can layer in his tricks when I really need them, but honestly that doesn’t happen very often.

Reduced motion ¶

@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

Remove decorative motion for users who don’t want them. This is pretty standard stuff. The one thing of note here is that these don’t set transitions and animations to none, rather they shorten the durations a super short interval. This way, they’re impossible to perceive, but they still run; browser events like transitionend will fire as normal and any code depending on those events won’t break.

Interestingly, I’m toying with the idea of reworking this bit of code on this site. Some of my posts include tutorials and demos that describe building transitions, and the demos don’t work because I’ve got this sort of code in my stylesheet. At some point, I’ll rejigger what occurs on what layer, but that’s a special case for this particular blog, and not any other projects.

Be Excited for New Features

2023-11-16T17:49:26Z

“Boy, that’s a cool new browser feature. It’s a shame I won’t be able to use it for ten years.”

I’ve been seeing a sentiment a lot lately, a sort of despair that some new browser feature won’t be reasonably available for production use for years. And I get it; it was this way for a long time. We web developers still have a lingering bit of emotional trauma from the early days of flexbox, web fonts, and the first CSS3 features.

The old adage comes to mind: Fool me once, shame on you. Fool my twice, shame on me. And boy, have we been fooled a few times in the past.

However, it’s not 2013 anymore. This resignation regarding new browser features—especially in the realm of CSS—is outdated. These days, most brand spanking new features are ready for production use within months, not years.

Be an optimist ¶

The last couple years have been wild for CSS. Dozens of highly anticipated new features have begun rolling out. Let’s look at some examples.

Cascade layers first shipped in Firefox on February 8, 2022. This was followed almost immediately by Chrome, Safari, and Edge. The last major browser to ship support was Opera, on April 19, only two months after Firefox.

OKLCH color first arrived in Chrome on March 6, 2023. Firefox was the last major browser to ship support, two months later on May 8. Some of the more obscure mobile browsers like Samsung Internet were only another couple months after that.

The color-mix() function arrived in Safari on December 12, 2022. The Blink browsers (Chrome, Edge, Opera) shipped in March. Firefox was the last to add support on May 8, 2023. That’s full browser support within a five month window.

This is the norm now. Yes, there are exceptions, so it’s important to keep an eye on things, but we don’t need to resign ourselves to defeat as a default anymore.

Caveats and exceptions ¶

It’s important to be aware that there’s generally a bit of a delay after release before all users upgrade their browsers. This can generally take anywhere from three to nine months to hit critical mass—depending in large part what you consider “critical mass” to be given your user base and the ease of defining fallback behavior for the specific feature in question. Perhaps you target a part of the market that happens to be particularly slow at upgrades; I totally acknowledge that is an unfortunate reality for some of us.

So, depending on a few factors like these, you might be able to use a new features anywhere from the moment it ships to a year or (in absolutely horrible circumstances) two years after that.

Some features are more complex, admittedly. Chrome has eagerly shipped @scope, while Firefox has yet to formally take a stance on the specification. (Safari has indicated support.)

But again, this is the exception, not the rule. So learn those exciting new features, keeping an eye on the overall landscape, and get ready to use them confidently.

Workarounds for Buggy Gradients

2023-11-03T16:17:02Z

CSS has a great new feature where you can specify the color space to use by adding in <colorspace> to the gradient (not yet supported in Firefox). This is especially useful for avoiding the gray dead zone that comes from rectangular color spaces like the default sRGB. Just look at the difference between a blue-to-yellow gradient in srgb compared to oklch with the same beginning and end:

linear-gradient(to right, blue, yellow)

srgb — blue to yellow

linear-gradient(to right in oklch, blue, yellow)

oklch — blue to yellow

I like that second one a lot better, though there certainly may be specific use cases where the first could make sense, too.

Unfortunately, if you’ve experimented with this much, you may have run into some weird behavior when building any gradients to white, black, gray, or transparent. This is especally bad when using blue, but it does affect other hues as well. Look at the teal and purple that shows up in these gradients, when they really should consist only of shades of blue:

oklch — blue to white

oklch — blue to gray

oklch — blue to black

oklch — blue to transparent

Here are red gradients, some of which show an orange or burgandy center.

oklch — red to white

oklch — red to gray

oklch — red to black

oklch — red to transparent

And to make matters worse, this behavior isn’t the same across browsers. The center of that second gradient (blue to gray) is teal in Chrome, but purple in Safari. The red to gray gradient differs between the browsers as well. Thankfully, there’s a reasonable workaround once you understand the problem.

The most reasonable solution is to do the gradient in sRGB or another rectangular color space. When you aren’t defining a gradient between different hues, the benefit of using a polar color space doesn’t really apply. However, out of academic curiousity, I dug into the cause of these bugs and happened to find some reasonable workaround within the OKLCH and HSL color spaces.

Workarounds in OKLCH¶

As far as I understand it, this is a browser bug, possibly relating to fact that the colors white, black, transparent, and any true neutral gray can be represented multiple ways all the polar color spaces. oklch(100% 0 0deg) is white, but so is oklch(100% 0 240deg). The first is a “red” white with no chroma, and the second is a “blue” white with no chroma.

For some reason, the color white is interpreted as having just the tiniest bit of chroma, but in a yellow-green hue. Below is an incorrectly interpreted blue to white gradient, followed by a correctly interpreted gradient to oklch(100% 0.001 90deg). The two appear exactly the same, and I think for some reason this shows how the browsers are converting white to OKLCH. The result occurs if you specify white in a non-oklch color syntax, including hex, RGB, and HSL.

oklch — blue to white

oklch — blue to oklch(100% 0.001 90deg)

Thankfully, there’s a workaround: specify the neutral color in the same color space as the gradient, and match the hue: oklch(100% 0 264deg). This seems to fix the issues in Safari and about half of the cases in Chrome. To fix those last remaining bugs in Chrome, add back just a smidge of chroma: oklch(100% 0.001 264deg). This trick works for black, gray, and transparent. Here are all the same gradients as above, but corrected:

oklch — blue to oklch(100% 0.001 264deg)

oklch — blue to oklch(50% 0.001 264deg)

oklch — blue to oklch(0% 0.001 264deg)

oklch — blue to oklch(0 0.001 264deg / 0)

And corrected red gradients:

oklch — red to oklch(100% 0.001 29deg)

oklch — red to oklch(50% 0.001 29deg)

oklch — red to oklch(0% 0.001 29deg)

oklch — red to oklch(0 0.001 29deg / 0)

Workarounds in HSL¶

Some HSL gradients suffer from the same issues. Red gradients seem to behave as expected, but these blue gradients all have some vibrant purple in the middle:

hsl — blue to white

hsl — blue to gray

hsl — blue to black

hsl — blue to transparent

A similar approach can fix this, but it’s a little more finnicky. For white, black, and transparent, you need to set the saturation to 100%. Saturation as low as 1% can work, but I've found that in Safari, it’s very particular based on the precise luminescent value. Using 100% seems to be the most reliable fix, and this is fine because at these lightness levels, saturation is irrelevant anyway.

Dark grays can be problematic. Chrome seems to handle this fine, but in Safari, variations of a tenth of a percent can have wild effects on the result. In the following gradients, lightness of 10% and 9.7% work fine, but values between that inexplicably result in a purple gradient:

hsl — blue to hsl(240deg 1% 10%)

hsl — blue to hsl(240deg 1% 9.9%)

hsl — blue to hsl(240deg 1% 9.8%)

hsl — blue to hsl(240deg 1% 9.7%)

In these cases, a slighly higher saturation (at least 2%) seems to fix the issues. Here are fixed gradients in HSL:

hsl — blue to hsl(240deg 100% 99.9%)

hsl — blue to hsl(240deg 100% 0.1%)

hsl — blue to hsl(240deg 2% 50%)

hsl — blue to hsl(240deg 100% 1% / 0)

Issues in LAB and LCH color¶

As a final note, the LAB and LCH color spaces also display unexpected hues in some gradients, most notably a purple showing up when the gradient should be blue. The bug in these cases lies in the definitions of the color spaces themselves, and not in the browser’s interpretation.

You should avoid these color spaces and use the superceding ones instead: OKLAB and OKLCH.

Scope vs Shadow DOM

2023-08-25T16:43:03Z

When CSS grid first arrived, there were a lot of people saying, “Why do we need this? We already have flexbox!” I’m getting very much the same vibe now with @scope, especially from enthusiasts of web components and shadow DOM.

But here’s the thing: CSS @scope and shadow DOM are not competing standards. They’re complementary. They meet different needs entirely — but with enough healthy overlap in functionality so there isn’t a gap.

So should we make shadow DOM more ergonomic? Yes please! I’m all for continuing to improve the specification here. By promoting @scope, I’m not belittling shadow DOM. Please don’t take this following statement as a criticism:

Shadow DOM does not provide what @scope does¶

Language is hard, especially when it comes to the terms we use in the industry to convey various ideas. The term component, for instance, can mean multiple different things to different developers.

Similarly, something different comes to mind for all of us when we hear about the concept of style scoping. This is only natural, because we all work in different corners of the industry. We’ve each had to tackle problems and use cases that others haven’t.

It’s so easy to hear that @scope is coming to CSS and think, “wait, don’t we already have scoping in the shadow DOM?” — because we do have scoping in the shadow DOM. But it’s a very different definition of scoping!

Shadow DOM and web components are perfect for some use cases. If you need to encapsulate something so others can put it on their sites, this is exactly what you need. Red Hat does this: the navigation bar at the top of the page on many Red Hat sites is a web component. This works well because:

these sites are all branded the same, and
they each need the same user experience for navigation.

Something like an embedded social media post is probably another perfect use-case.

This is not what @scope is for.

Shadow DOM is strongly isolated from the rest of the page. Essentially, shadow DOM throws away the entire CSS cascade. It cuts a hole out of the page, and allows you to put something else in that hole.

But this is not everybody’s use case. If you are working on a single web application, with unique branding and a consistent user experience, the last thing you want is to isolate all the parts of the page from the cascade. You want everything to look and feel the same! You want the cascade to apply, but with the ability to explicitly control how it applies. Components need to be able to override parts of the cascade — but not be isolated from it entirely.

@scope is about embracing the cascade, and controlling it. In many ways, this is the exact opposite of what shadow DOM does.

Yes, shadow DOM should continue to grow and be improved, but at a fundamental level, it does not address the same problem @scope does. Yes, both scope styles, but they are two radically different definitions of scope. ¹

The greatest shortcoming in our industry¶

I have never personally needed shadow DOM. Every time I dig in to assess it, I come away frustrated.

At first, I thought this was a failing of the spec — how could they be so out of touch with the real needs of developers? But since then I’ve realized that’s not it at all.

Instead, I have slowly realized that the needs across our industry vary wildly. Some developers love shadow DOM, because it does exactly what they need. But when they look at @scope, they feel the same way I do when I look at shadow DOM — it’s not at all the right tool for their job.

This is something our industry is terrible at: we are really bad at understanding and appreciating the varying needs of other developers who work on different problems than us. Why would someone want to colocate their CSS inside their JavaScript files? Why would someone be so vehement about avoiding a JavaScript framework? Why would someone want to entirely encapsulate their web components from the light DOM? And why would someone want this @scope thing when we already have shadow DOM?

We each solve different problems and often have wildly different needs from our tech tools. That’s okay. That’s healthy.

For me, and my problem space, shadow DOM is a backwards paradigm to the one I need. I long for @scope.

Maybe you don’t. And that’s fine.

But please don’t try to shoot down the one feature that’s been desperately missing from CSS because you don’t have a personal need for it.

Web Components Aren’t Components

2023-07-26T23:08:00Z

Modern web frameworks are built entirely on the concept of components. In the realm of these frameworks, a component is a reusable piece of application code. All logic is encapsulated in one place, so the component can be dropped into the application anywhere it’s needed. Components are nested within one another to compose the structure of the page.

Vitally, it must be in control of its own styling. Yes, it should be visually cohesive with the application at large, but when it comes to a reusable component, you can’t afford for unexpected styles to suddenly occur when you add the component to a new context. It’s styles need to be higher priority than the styles outside the component—including its parent components. By corollary, a component’s styles should not be overly powerful at impacting the styles of the component’s child components.

Enter “web components” ¶

We also have “web components”. These are built directly into the platform, comprising something called custom elements. Custom elements are a web primitive, a way of extending HTML itself. They are ideal for broad distribution and re-use in various frameworks/sites/apps. But to be broadly usable, they must allow for the application to have priority assigning styles.

The idea of a universally re-usable Typahead Lookup component is valiant. Nobody likes building that over and over again every time they switch JS frameworks or move to a new project. But in order for this to work, it must be completely re-stylable. It needs to be capable of visually matching whatever application it’s used in, with consistent colors, fonts, spacing, and icon styles. This means, while it should have some default styling, it must surrender full control to the outer application.

This is not a component.

At least, it’s not the same definition for component that modern frameworks use.

If I find a <typeahead-lookup> custom element that meets my application’s needs functionally, that’s great! I won’t have to roll my own autocomplete functionality! But I will still need to wrap it in a component of my own. I need to apply my application’s styling, and encapsulate the lookahead in a way that protects it from receiving unwanted styles when it’s used across my application. I probably also need to wire it into my application’s data and possibly ensure certain options are turned on or off so I don’t have to remember them every time I use the custom element.

Maybe that’s as simple as wrapping it in a div and applying a class name. But depending on the architecture of my application at large, it’s highly likely it will require wrapping it in a full component (React, Vue, or otherwise).

Now, I get that it is possible to skip this step. You can build a custom element in such a way that it’s internal parts are locked away in the shadow DOM and cannot be styled from outside. In which case, you will have to internalize your application’s styles inside the shadow DOM. But that’s tedious to do, not to mention it defeats the whole promise of “framework agnostic” web components that can be broadly distributed and re-used in various applications.

Why web components are slow to catch on ¶

I think the difficulty with web components is not that they’re bad in and of themselves. If they came along before the advent of modern JS frameworks, they would probably be the way things are done at large.

However, in the current landscape, web components live in an awkward place: They provide a lot of the same functionality as framework components, but they are not a one-for-one replacement. The two provide a lot of the same benefits to the developer, but not all the same benefits.

If you happen to work in a problem space where you need widespread distribution of custom elements, this may be enticing enough to adopt web components. But that’s not most developers.

For a developer familiar with modern web frameworks, web components don’t offer enough compelling benefits to switch — you still need the framework to componentize everything and manage the application at a high level. And if you have a framework, there’s really very little web components can offer on top of that.

Web development is a wide world ¶

I love the web. I love the promise of open standards. And I think web components serve a useful role.

My gut tells me they’re more useful toward the website end of the spectrum than they are on the web application end — but I have little data or broad enough experience to back this up.

I think we also need to be okay accepting that they aren’t the right solution for everyone. And we need to acknowledge that we’ve probably done some undue damage by trying to say they are.

Re-evaluating px vs em in Media Queries

2023-05-31T18:37:00Z

It’s been a while since I considered what unit I should use in media queries. In the past, I (and many others) have recommended using ems rather than px, because “it’s the only unit that performs consistently in all major browsers.” In the past, Safari has been a bit quirky here, but I know they’ve made some major improvements recently, so I figure this is worth revisiting.

Unfortunately, what I found is that there is still no simple answer — but it is a little different than it used to be, so it’s worth taking note. You can skip to the takeaway if you want.

Zoom, default font size, etc.¶

Let’s consider all the ways users can change the font size in the browser. Some of these options are harder to find in various browsers, but here are the options available.

The first option is zoom, which can be changed using Ctrl+plus and Ctrl+minus in all major browsers (or by selecting options in the View menu) This scales everything on the page up and down. Effectively, this scales a px up and down on the page, and in turn scales ems and rems up and down.

The second option is changing the default font size. This generally changes the meaning of the medium keyword for font size, which in turn scales ems and rems up and down, but not px. This may or may not change the meaning of ems/rems inside a media query, however — more on that in a minute. In Safari, this setting is rather difficult to find; you have to open the View menu, then hold the Option key and select “Make text bigger/smaller”.

The third option — which I don’t recall seeing when I last checked several years ago — is setting a minimum font size. This option doesn’t scale the whole page, but it does guarantee no fonts ever render at tiny sizes when the user specifies.

Firefox also has a fourth option, “zoom text size only” which behaves similar to zoom, but only increases/decreases text size. As far as I can tell, this behave essentially the same as changing the default font size.

How I tested¶

I created this Codepen. It’s got three divs, each with a blue background color. Then I use different media queries to change each div to a green background above a certain width. The queries are set to a min-width of 800px, 50em, and 50rem. Depending on browser settings and viewport size, it ends up looking something like this:

Here’s the CSS; I used 50em and 50rem since those are equal to the 800px media query with default font settings:

div {
  padding: 2rem;
  margin-block: 1rem;
  background-color: hsl(211deg 40% 80%);
}

@media (min-width: 800px) {
  .px {
    background-color: hsl(179deg 40% 80%);
  }
}
@media (min-width: 50em) {
  .em {
    background-color: hsl(179deg 40% 80%);
  }
}
@media (min-width: 50rem) {
  .rem {
    background-color: hsl(179deg 40% 80%);
  }
}

Then I opened up Chrome, Firefox and Safari and started playing with the settings. Here’s what I found:

		px	em	rem
Zoom	Chrome	scales	scales	scales
	Firefox	scales	scales	scales
	Safari	scales	scales	scales
Font size	Chrome	static	scales	scales
	Firefox	static	scales	scales
	Safari	static	static	static
Min font size	Chrome	static	static	static
	Firefox	static	static	static
	Safari	static	scales	static
Zoom text only	Firefox	static	scales	scales

scales	Media query scales with font size
static	Media query remains static

I was disappointed to see Safari is still an outlier, where ems and rems don’t scale in media queries based on the user’s default font size.

In the past, rems in media queries have been kind of unpredictable, but based on these findings, they now behave the same as ems in nearly every circumstance — with the exception of how they respond to a minimum font size in Safari.

The takeaway¶

There is no clear-cut winner I can point to after looking at this. It probably depends on what you want to prioritize.

If you want consistency across all browsers, you should now use px in your media queries.

However, this may not get you exactly the behavior you want for users who change their default font sizes. If you want your breakpoints to scale along with the user’s font size, you should favor ems instead — but keep in mind you won’t get this benefit Safari unless the user has their minimum font size setting configured.

I feel like maybe this means it doesn’t matter quite so much as it has in the past, but there is still no one perfect answer. At this point, I am comfortable using px again, but I’ll probably evaluate it on a case-by-case basis.

The Webdev Social Schism

2023-05-02T18:16:00Z

A while back, Zach Leatherman commented that Eleventy will need to maintain a presence on Twitter to stay in touch with portions of the webdev community. In particular, the “JavaScript folks” that have “dug in there,” and this really struck a cord with something I’ve been feeling in my gut for a while now.

I’m afraid the web development community has fractured in two.

On one side, we have the “open web” idealists, who were eager to move their online social presence to the Fediverse. They love that it’s decentralized. They value that it’s not beholden to any capitalistic influence. They either turn a blind eye to the flaws of Mastodon, or believe they are far outweighed by the benefits.

On the other side, we have the Twitter holdouts. They tend to poke fun at the idealism of Mastodon and the first group’s doe-eyed embracing of it. Sure, these folks enjoy laughing at Elon Musk’s fumbling of Twitter, but they aren’t about to leave unless it collapses entirely. And, hey wouldn’t you know it, Jack Dorsey has an alternative in the works that this group is eager to get on board with.

Obviously, these are generalizations. There are plenty of people who are maintaining a presence on both networks, or are mostly on one because that’s where more of their social circle happens to be now.

I suspect this is highly correlated with Chris Coyier‘s “Great Divide” — a sort of next step in the evolution of those differences.

The political factor ¶

Twitter was a fantastic thing for the webdev community. In many ways, it made the community what it is today. And plenty of words have been said mourning the apparent pending loss of that era.

But what really concerns me now, as things have been shaking out for half a year now, is how much this divide feels like a political one.

By and large, it feels to me like the Mastodon contingent tends to be mostly liberal — skeptical of the capitalist idealogy of a corporate-run social network. And the Twitter holdouts tends to be more conservative — derisive of the hippie-dippy decentralized network.

This feels ugly ¶

I don’t want to be on only one side of this. I don’t want anybody to be on only one side of this. While there’s certainly something comfortable about huddling up with folks I agree with, I want to participate with the entirety of our industry. And I certainly don’t want to see us split long-term along a largely political divide. That’s gross.

I don’t know what the solution is. I’m wondering whether I need to pick my Twitter account back up, or get active on Blue Sky, if I can ever get in there. I have major ideological problems with both of them, but maybe I need to choose more important priorities than those ideals. Maybe it’s worth a compromise there in order to not feed the divide further.

Scoped CSS is Back

2023-04-24T15:54:00Z

Several years ago, I made a plea to save scoped CSS. One of the top features on my CSS wishlist was on the chopping block, and despite a pretty big push from the community, it died.

Well, great news — it’s back. And it’s so much better than the previous version.

Even better, the W3C spec is mostly stable, and there’s a working prototype in Chrome now. We just need a little interest from the community to entice other browsers to build their implementations and kick this over the finish line.

What’s the idea¶

There are two key things scope brings to CSS:

More control over which selectors target which elements (i.e. better manipulation of the cascade)
The ability for one set of styles to override another based on proximity in the DOM

Scoped styles allow you to contain a set of styles within a single component on the page. You can use a .title selector that only works within a Card component, and a separate .title selector that only works in an Accordion. You can stop selectors from one component from targeting elements in a child component — or you can allow them reach in, if that’s what you need.

You will not need BEM-style classnames anymore.

Furthermore, proximity becomes a first-class citizen in the cascade. If two components target the same element (with the same specificity), the inner component’s styles will override those of the outer component.

How it works¶

It all starts with the @scope rule and a selector, like this:

@scope (.card) {
  /* Scope the following styles to inside `.card` */
  :scope {
    padding: 1rem;
    background-color: white;
  }

  .title {
    font-size: 1.2rem;
    font-family: Georgia, serif;
  }
}

These styles are all scoped to .card elements. :scope is a special pseudo-class that targets the .card element itself, and .title targets titles inside cards.

The @scope rule itself adds no specificity to these selectors, so they’re both (0, 1, 0). Yes, specificity still matters, but that’s a Good Thing™️. More on that shortly.

At this point, this is nothing you can’t already do with regular descendant selectors. But new, previously impossible options start opening up when you apply an inner bound to the scope or overlap multiple scopes on the page. Let’s see what those do…

Inner scope bound

Let’s say you anticipate putting other components inside your Cards, so you don’t want that .title selector to target anything other than the one title that belongs to the Card. To do that, you put an inner-bound on the scope like so:

@scope (.card) to (.slot) {
  /* Scoped styles target only inside `.card` but not inside `.slot` */
  :scope {
    padding: 1rem;
    background-color: white;
  }

  .title {
    font-size: 1.2rem;
    font-family: Georgia, serif;
  }
}

Think of the “to” keyword here like “until”: this scope is defined from .card to .slot. Now, none of the scoped selectors will target anything inside the Card’s .slot element. So you can build your card like this:

<div class="card">
  <h3 class="title">Moon lander</h3>
  <div class="slot">
    <!-- scoped styles won’t target anything here! -->
  </div>
</div>

The reach of the scope is restricted, keeping it from targeting anything inside .slot. This way, you can nest two scopes, and each one can make use of the same generic title class name without conflicting. In fact, you might not even need the class name anymore at all:

@scope (.card) to (.slot) {
  h3 {
    font-size: 1.2rem;
    font-family: Georgia, serif;
  }
}

@scope (.accordion) to (.slot) {
  h3 {
    font-family: Helvetica, sans-serif;
    text-transform: uppercase;
    letter-spacing: 0.01em;
  }
}

You can put an Accordion inside a Card — or a Card inside an Accordion — and they will each style their own <h3>s without conflicting.

This has been colloquially named “donut scoping” since the scope has a hole in it. (It can also have multiple holes in it, if the inner bound selector targets multiple elements.) Miriam Suzanne suggest a possible way to use this is to consistently use data-* attributes and attribute selectors for your scope:

@scope ([data-scope='media']) to (:scope [data-scope]) {
  /* scoped styles go here */
}

…though I find I prefer the simple selectors that come from a class-based approach. But maybe that’s just my old BEM habits showing.

Proximity precedence

The other aspect to scoping is the concept of proximity: styles from an inner scope will override those from an outer scope. Imagine you have two scopes like this:

@scope (.green) {
  p {
    color: green;
  }
}

@scope (.blue) {
  p {
    color: blue;
  }
}

Apply these to the following HTML. These have no inner scope bound, so both p selectors target the inner paragraphs here. In this case, the inner scope always takes precedence:

<div class="green">
  <p>I’m green</p>
  <div class="blue">
    <p>I’m blue</p>
  </div>
</div>

<div class="blue">
  <p>I’m blue</p>
  <div class="green">
    <p>But I’m green</p>
  </div>
</div>

And here’s a working demo — Note this currently only works in Chrome with the Experimental Web Platform Features flag turned on in chrome://flags. ¹

I’m green

I’m blue

But I’m green

You can inspect this in DevTools and see each scope overriding the other, based on which one has the closest proximity:

and

The catch here is that selector specificity still takes precedence, so if the outer scope targets an element with higher specificity than the inner one, the outer scope’s styles will apply. This was a debated issue during the development of the specification, but — to the surprise of my past self — I think it’s the right call.

This way, when two scopes target the same element, you maintain control over which takes precedence. Instead of the inner scope always winning, you can tweak selector specificities so the higher-specificity selector takes precedence, regardless which scope it belongs to.

And when you don’t want this behavior, you have a few ways to prevent it. You make use of cascade layers to give one component — or just parts of one component — precedence over another. Or, you can apply an inner scope bound to the outer scope to keep it from happening. After experimenting with scope for a bit, this feels to me like the right balance. It gives you the most control, rather than leaving you beholden to a rigid set of rules of the cascade.

This is a game changer¶

If you’ve developed large-scale apps and had to rely on CSS-in-JS libraries to prevent class name collisions, I hope you can see the benefit this offers. If you’ve rolled out complex BEM class name systems and fought to keep all your selector specificities equal, think of the freedom this can bring. If you’ve ever used the shadow DOM to isolate styles but it was too heavy-handed, this is a better way (though there are still use-cases for Shadow DOM, of course).

I can’t even imagine all the new ways we’ll be able to structure our code. I think this will be as big as custom properties or even flexbox and grid. Here are just a few ideas that I’ll certainly be experimenting with:

Define parts of a component with an inner bound and parts of it without, so the scope of its ”chrome” styles (i.e. wrapper, toggle buttons, etc) don’t affect its child contents, but it can influence the appearance of text within.
Define portions of a component on different cascade layers so it can influence its contained scopes but remain simple to override on a higher layer.
Nested color themes.
Easier ways to prevent style collisions in embedded demos in my blog posts.
Container queries—What can we come up with by mixing and matching with those?

We need more browsers on board¶

At this point, Chrome seems to be on board—they’ve had the first working prototype for several months now. It might be slightly behind the latest changes to the spec, so keep an eye out for a few minor changes coming if you play around with it.

Firefox seems more reluctant—possibly because they got burned as the only implementors of the first version of scope several years ago? I’m not sure what the best way is to nudge them along. Perhaps we just need more people blogging about this feature and creating buzz. There is this open issue requesting their position on the feature. Maybe a little activity there would help.

It sounds like Safari has expressed interest, but it never hurts to let them know if the community would like to see it. Maybe the next time Jen Simmons takes a poll on most requested features, let her know you want to see @scope happen.

Until then, have fun experimenting in Chrome!

Transitioning to Height Auto (Two Ways)

2023-04-21T17:17:00Z

One of my longstanding annoyances with CSS has been the inability to transition to height auto. It’s an incredibly common use-case that’s needed for dropdowns and accordions and all sorts of other UI patterns. Unfortunately, this just doesn’t work:

/* Doesn't work */
.dropdown {
  height: 0;
  transition: height 0.5s ease-out;
}

.dropdown.is-open {
  height: auto;
}

It’ll open and close just fine, but it won’t animate. The normal course of action here has been to pull out JavaScript and set the height explicitly based on the element’s scrollHeight.

However, I have come across a two different ways to solve the problem without the help of JavaScript. One approach transitions an element inside a flex item; the other approach transitions an element as a grid item. Each requires adding one or two extra elements to the page to pull it off, but in many cases, that’s still better than the alternative.

With flexbox¶

I found this solution from Joakim Chiem in a comment buried in the W3C GitHub issue. (The comment is two and a half years old. I am so sorry for not writing about it before now!)

For this approach, wrap the element you want to transition in two divs: the outer will be a flexbox and the inner one will be a flex item. With these in place, you can transition max-height from 0 to 100%. This leverages a quirk of how height/max-height work inside flexbox.

.wrapper {
  display: flex;
}

.inner {
  max-height: 0;
  overflow: hidden;
  transition: max-height 0.5s ease-out;
}

.wrapper.is-open .inner {
  max-height: 100%;
}

Just be sure there's an extra div between the wrapper and the inner element:

<div class="wrapper">
  <div>
    <div class="inner">Expandable content</div>
  </div>
</div>

And here's what it looks like in action:

This demo won’t show the transition because you have reduced motion settings enabled.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent mi enim, venenatis non facilisis sed, finibus in enim. Sed auctor enim nisl, sit amet feugiat risus blandit vitae.

Integer dapibus tortor lorem, quis interdum erat maximus eu. Nam varius, nisl ac pharetra convallis, neque ex blandit quam, sit amet condimentum lectus elit vel ligula. Donec commodo porta elit quis facilisis. Sed non purus a massa convallis ultricies. Donec malesuada sollicitudin dui, vel lobortis arcu rutrum ut. Curabitur lobortis ac tellus non tempor. Donec nisl risus, cursus vel odio quis, convallis euismod ante.

Nulla lectus diam, sagittis id urna in, tincidunt facilisis sapien. Sed ante turpis, porttitor a diam at, auctor lobortis sapien. Cras ornare dolor sed arcu laoreet volutpat ut tristique ipsum.

The downside to this approach is that, while the inner element animates smoothly, its container does not; that just snaps into place instantly. But that might be prefereable in some situations, since the browser doesn't need to constantly reflow all the contents of the page beneath it.

With grid¶

I first saw mention of this technique from Chris Coyier, but he kinda buried the lede amid a longer wish-list of CSS features.

This one is a bit simpler, and probably a little more understandable. Make a CSS grid with a single grid item. All you have to do is transition grid-template-rows from 0fr to 1fr, so the grid item transitions to its auto height:

.wrapper {
  display: grid;
  grid-template-rows: 0fr;
  transition: grid-template-rows 0.5s ease-out;
}

.wrapper.is-open {
  grid-template-rows: 1fr;
}

.inner {
  overflow: hidden;
}

This does not require the extra div. Just a grid container and its one grid item:

<div class="wrapper">
  <div class="inner">Expandable content</div>
</div>

Surprisingly, it’s that simple:

This demo won’t show the transition because you have reduced motion settings enabled.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent mi enim, venenatis non facilisis sed, finibus in enim. Sed auctor enim nisl, sit amet feugiat risus blandit vitae.

Nulla lectus diam, sagittis id urna in, tincidunt facilisis sapien. Sed ante turpis, porttitor a diam at, auctor lobortis sapien. Cras ornare dolor sed arcu laoreet volutpat ut tristique ipsum.

This approach feels a lot cleaner. Only two DOM nodes needed, and all the page content beneath moves fluidly like you probably expect.

The one caveat to both of these is you can’t add any padding to the inner element. If you need padding, you have to add one more extra element inside the collapsed element and put the padding on that.

It's Time to Learn oklch Color

2023-04-07T18:27:00Z

If you’re anything like me, looking at all the things happening in CSS lately involving color, you’re probably a bit overwhelmed. For a long time, HSL was promoted as the human readable alternative to hex or RGB. For about a decade, HSL has been the best option for working comfortably with color on the web.

But now, somewhat suddenly, we’ve got several new options thrown into the mix: hwb(), lab(), lch(), oklab(), and oklch(). There’s also color() which sort of fits into the same category and kind of doesn’t.

This is a lot to take in. But hsl() is great! So why leave what works and what’s comfortable?

It’s easy to get lost in all this. So I’m going to try to make it easy: If you don’t know where to start, or which of these things is going to be practically useful enough to be worth your time, I think the biggest bang for your buck is to learn OKLCH (or, “Oklachroma”, if I had my way and could make that catch on). Hopefully I can convince you that it’s worth diving in and learning.

Lightness: 70%

Chroma: 0.19

Hue: 150deg

Why OKLCH¶

I’m not going to take a deep dive into all the various color notations in this post. But HSL has been king for over a decade now, so I will draw upon that to make some important comparisons.

The thing that makes HSL so great is that it is so much more intuitive than hex or RGB color. One value for Hue, or color of the rainbow. One value for Saturation, or how vivid that color is. And one value for Lightness, ranging from black to white. For example, hsl(220deg 60% 45%) — a fairly vivid, medium-dark blue.

OKLCH follows a very conceptually similar pattern. The mental model is nearly identical, though the order of the values is reversed:

Lightness: from 0% to 100%
Chroma: vividness of color, from 0.0 to 0.37 (more on that below)
Hue: from 0deg to 360deg indicating the color of the rainbow

There are two key distinctions from HSL, however.

It’s based on human perception

In HSL, lightness and saturation each range from 0% to 100%, where 0% means none and 100% means the highest amount of light or saturated color that can be represented in the sRGB gamut— sRGB is the range of colors that have historically been available to most color monitors.

The problem with this is it doesn't quite align with the way our eyes perceive light. Look at these two HSL colors, each of which has an equal HSL lightness value of 50%:

hsl(217deg 55% 50%)

hsl(110deg 55% 50%)

Both colors have the same specified lightness, but the second one appears noticeable brighter to our eyes. Here are the same colors in OKLCH:

oklch(55% 0.15 260)

oklch(73% 0.2 141)

Notice how in OLKCH, the lightness is different (55% and 73%). Look what happens when we bring the lightness of the green down to match the blue:

oklch(55% 0.15 260deg)

oklch(55% 0.2 141deg)

By giving them the same lightness value in OKLCH, the green has been dimmed. Now they both appear equally bright. You'll also noticed that the specified chroma value is different between the two colors (0.15 and 0.2). Let's adjust the chroma values to match:

oklch(55% 0.15 260deg)

oklch(55% 0.15 141deg)

The difference here is a little more subtle, but the green on the right has been desaturated from the previous example. Now the two colors both appear to have the same brightness and the same vividness.

In HSL, 100% saturation is simply as saturated as that particular color can be in the sRGB gamut. In OKLCH, the values aren't based on technical limits or a mathematical definition, but rather on perceived equality. The amount if lightness indicates exactly how bright the color is, and the amount of chroma indicates exactly how vivid it is. The human eye perceives some colors like green or yellow to be brighter than others, like blue or purple, and OKLCH takes these details into account.

It can define any color

I’ve mentioned a couple times that HSL is limited to the sRGB gamut. But monitors are getting better. Most smartphones and newer monitors, including most Mac laptops, support a wider range of colors (a gamut called P3). And some high-end monitors offer an even wider range of colors (a gamut called Rec2020).

The great thing about OKLCH, is it can specify any color these monitors are capable of—In fact, it can specify any color that the human eye is capable of seeing. In CSS, the browser will automatically round any out-of-range colors to the nearest color the hardware is capable of displaying.

Browser support is nearly there

At the moment, OKLCH is supported in Chrome, Edge, and Safari. Firefox supports it only behind a flag at the moment, but it is expected to be enabled by default soon, with version 113. See the latest browser support at caniuse.com.

That means it’s probably not ready to completely replace your HSL yet, but that day is near. In the meantime, you can use it selectively with feature queries. I’m doing a little of that on this site right now, where I wanted to push some of the color accents into a slightly more vivid range for browsers and monitors that support it:

@supports (color: oklch(73% 0.17 192)) {
  :root {
    --accent-color-1: oklch(73.54% 0.169 193);
    --accent-color-2: oklch(68.15% 0.272 9);
    --accent-color-3: oklch(77.94% 0.203 62);
    --accent-color-4: oklch(66.67% 0.193 253);
  }
}

Or you can just use regular old fallback values:

background-color: hsl(179 100% 38%);
background-color: oklch(73% 0.17 193);

Just be aware that this latter approach does not work for custom properties, because the value won’t resolve as invalid until you reference it later using var().

How to use OKLCH¶

So hopefully I’ve convinced you to give OKLCH a shot, even if it’s just with some simple experimentation to get comfortable with it.

The first thing you need to know is that it uses the “new” style of CSS color syntax. And by that, I mean there are no commas between the values: oklch(50% 0.3 280deg). If you want to add an alpha channel for transparency, use a slash to denote it: oklch(50% 0.3 280deg / 0.5).

The older color functions have all been updated to use this approach as well. So instead of the old hsl(200deg, 50%, 45%), you can now use a comma-free notation: hsl(200deg 50% 45%). And instead of a separate function for transparency (hsla()), you can use the same function with a slash: hsl(200deg 50% 45% / 0.5). For hsl() and rgb() the old notation with commas will be supported for backwards-compatibility, but going forward the new color functions will not.

Chroma

There are a few things to be aware of when using oklch(). The most important one is the chroma range. Unlike saturation in HSL, chroma is not a percentage.

For all intents and purposes, the chroma value is a number between 0 and 0.37. You can try using a higher chroma value, like 25, but it is going to round to a color in the monitor’s supported range and the result can be unpredictable (you may specify a blue hue, but it might end up selecting a teal if it’s vivid enough to be “closer” to the values you specified).

Theoretically, OKLCH color can specify colors with chroma up to infinity, but I find this nonsensical. I have a hard time imagining a red much more vivid than this:

oklch(50% 0.37 29deg)

Maybe I would believe some hyper-intense paint could push it to something like 0.5, but that’s about it. So I don’t find the “infinity” limit helpful in the slightest. Keep it under 0.37.

In fact, for most hues, the practical limit is even lower. This orange, for example, is maxed out at 0.187:

oklch(70% 0.187 60)

If you were to increase the lightness, you could bump up the chroma a smidge further. But the point is, the values are all interelated. If you have a very dark color, monitors can display it with only so much chroma; there just isn’t enough light emitted to make it any more vivid. And the specifics of how each hue works are a little different, because our eyes don’t perceive all the various wavelegths equally.

Hue

Another thing to keep in mind is that the hue values are not exactly the same as HSL. All hues have been shifted up by around 30 degrees, though this amount varies a bit depending on the color. Here are gradients across all hues (0–360 degrees) in HSL and OKLCH for comparison:

HSL

OKLCH

Again, these differences come down to human perception, so some hues get a little more space on the spectrum. Additionally, these shifts are a little different when comparing across various brightnesses and saturation levels.

Some key color points are:

Red: 30
Yellow: 90
Green: 140
Cyan/teal: 195
Blue: 260
Magenta: 330

Hue can be expressed as an angle (25deg) or as a number (25).

Lightness

Another difference from HSL is that 0% or 100% lightness does not automatically mean full black or full white. If there is enough chroma, you can still get some color at these extremes:

oklch(100% 0.37 330deg)

oklch(0% 0.37 140deg)

Update: This behavior is the result of browser bugs and does not match the spec. Lightness of 100% should be pure white an 0% should be pure black. It has been fixed in Chrome, and will likely change in other browsers in the near future.

If you want true black, white, or gray, make sure the chroma value is 0.

Lightness can be expressed as a percent (45%) or as a decimal (0.45).

Use a color picker

In general, as long as you keep the chroma below 0.37, you will usually be pretty safe. It’s pretty easy to specify a color that’s not in range of your monitor, but as long as your values are within reason, the browser should round it to a predictable result.

But when you really want to fine tune things, I suggest you use a color picker. The one at oklch.com is fantastic:

This picker provides conversions to most other color formats, so you can find fallback values easily. Shift-clicking the color swatch in your browser‘s DevTools also provides conversions, like it always has.

Instead of an rgb or hsl picker that you may be used to, you’ll notice the colors here aren’t displayed in perfect rectangles; it’s like chunks have been cut out of them. This indicates where colors are out of range of computer monitors. It’s a little odd at first, but it should start to make sense the more you play around with it.

Further reading: If you really want to dive deeper into understanding gamuts, color spaces, and the other CSS color functions, I highly recommend the High Definition CSS Color Guide by Adam Argyle.

Redesign 2023

2023-03-29T17:54:00Z

Oh man, it always feels good to roll out a fresh site design! I had a lot of fun with this one, especially since it’s my first chance to really dig in to some newer CSS features. And floats. Who would have guessed I’d be using several of those in 2023?

I’ve still got some rough edges to clean up, but I’m feeling good enough to go live with this design.

While working on this design, I spent a fair amount of time scrolling through dozens of other blogs from people in the webdev community. There are some really great sites out there! So I thought it would be fun to point out some of my sources of inspiration. These sites are a few of my favorites:

henry.codes ¶

This was the first design I came across that really struck me. It leans hard into a clean minimalistic look that feels very reminescent of the old subtraction.com, but with fresh, modernized aestetic.

I love all the little touches like the rotating curved text and blur filters.

» https://henry.codes

stephaniewalter.design ¶

If you told me a site was swimming in vibrant yellow, I wouldn’t expect it to work, but this site looks fantastic. I especially love the buttons with a off-center faux screen printing effect. In the end, I don’t think I borrowed any specific ideas from this site, but I still found myself coming back and looking at it as I was brainstorming.

» https://stephaniewalter.design/

michellebarker.co.uk ¶

So many cool little interactive elements and animations! I love the vivid colors here and how almost everything on the page moves in response to scrolling into view.

» https://michellebarker.co.uk/

trentwalton.com ¶

Of course Trent is going to have gorgeous typography. But the other thing that really stood out to me here was the way he seems to have designed the page uniquely for each and every post. That’s definitely something I want to experiment with in the future.

» https://trentwalton.com/

joshwcomeau.com ¶

I came back to this site a lot in particular when I was figuring out how I want to organize information on my site. I’m hoping to dive a little deeper into proper tutorials and demos in the future, and Josh’s site is a fantastic example of this.

I may have also drawn a lot of inspiration for the mobile nav menu from here.

» https://www.joshwcomeau.com/

There were plenty of other excellent sites beyond these. You all do some great work. Keep it up!

React Pays the Bills

2023-02-08T18:02:14Z

It seems to be trendy to trash on React again. Look, I know these criticisms aren’t targeted at me, but I can’t help but feel defensive when I see post after post accusing React of “taking us back to the days of Flash” or being “Facebook’s way to control JavaScript” or that it’s full of “cultish worship” and a “goddamn awful technology and community”.

These are direct quotes, from just some of the many posts I’ve seen, and holy shit are these ridiculously over the top and melodramatic.

You can code in React without being a “React scab” ¶

So I totally acknowledge there are some asshats in the community, some of whom are very vocal. I’m not going to pretend that isn’t the case.

But don’t judge the entirety of one of the largest sectors in the web development industry based on its bad actors. There’s a reason React is so popular, and it’s not the assholes. Maybe take a few minutes to step back and consider why.

I will say this point blank: I have built things in React that literally were not possible on the web before it came out. ¹

It absolutely changed the landscape for the better; it absolutely expanded the possibilities of what we can do on the web.

It’s not the only game in town — several other (better) frameworks have built on what React started — but it was the first library to offer truly componentized web development without tons of technical overhead. It was essentially first to market by several years. That’s why it dominates the industry today.

I’m not calling it perfect ¶

The framework has its issues. Single-page apps also have their issues — though I will be quick to point out there isn’t some 1:1 correlation between React and SPAs. So do some of the other aspects of the ecosystem that surrounds it. It’s totally okay to point out the problems with a technology. In fact, I’d say it’s a good and productive thing to do. But don’t disregard all the good it also provides. And above all, don’t be an asshole about it.

You aren’t going to make the industry better if your response to bad actors is to be one yourself.

Look, I’m tired of writing this same post over and over. Can we stop it already?

¹ I'm getting questions about this comment. Here's what I mean: React provides a higher-level abstraction on the web. This makes the code easier to reason about and less error prone, thus bringing more complicated problems into attainable reach.

Here is a fantastic explanation:

If all you want is a coffee, then you want to tell the barista "I want a coffee", not "I want you to take three steps to the left, stretch out your arms, pick up the beans, put the in the grinder, push the button to grind them [...]" and so on. It wouldn't make the final product any better (in fact, in some cases it'd make it worse since the barista is probably way better than you at making coffee).
High-level languages encourage you to think more about the problem domain and less about the execution platform. There is less ceremony, so you can spend more time on stuff that actually brings you value.

You Should Start a Mastodon Instance

2022-11-07T16:15:46Z

…and I don’t mean a single-user one for your own personal use.

This is happening ¶

Hi! I hope you had a great weekend.

While you were off, you know, having a life in the real world, something crazy happened online: users signed up for Mastodon. More than one person every second. All weekend long.

I logged in this morning to a full feed of content that I still haven’t finished reading.

Even weirder, on Friday I found myself as one of the admins of a new instance, front-end.social. Now don’t go clicking that link to register just yet!* I want to ask something a little bigger of you: start a new instance of your own.

This is the Fediverse’s moment, and it has a very serious chance of succeeding. The thing that will help it (and the internet, and the concept of actual decent, social social networks) is more, smaller instances. The big instances are getting buried right now. Mastodon.social has been struggling with downtime and slow response times because it has suddenly become so popular.

Small instances are where Mastodon shines ¶

The “Local” timeline view on small instances are not a undigestable firehose of noise; it is full of good content shared by people with at least one similar interest to yours. It’s something “the birdsite” could never hope to be.

But we need more of that. When Mia started front-end.social (after a little prodding from a small group of folks), the idea was not to become the Mastodon instance for the world of front end web development. The idea was to be one instance among many. There is so much demand for this right now. We have been flooded with requests to join, and for the sake of maintaining a tight knit community, we’ve dragged our feet a bit in accepting every one of them.

So please, grab a few friends and start another one. We’d love to network with you.

I've been covering technology since the 90s (and using the internet since the 1980s, before there was a web 😏) and have to say I have never seen anything like the high speed mass migration to Mastodon from Twitter. These things generally happen as a drift not a sudden avalanche and it's extra-amazing that at this highly commercial moment in internet history, it's to a decentralised, free and open source software-based community. It's just 🤯 (in a good way)
Karlin Lillington

*Depending when you read this, registrations may actually be closed anyway. We’re having trouble keeping up!

What Happened to Unit Tests?

2021-06-29T16:25:49Z

It seems to me one individual has convinced our entire industry to stop shallow rendering, and to abandon unit testing in favor of (almost) exclusively using integration tests and I gotta be honest, I don’t buy it. I agree with many of the arguments in that post, but not the conclusion. And I think the state of unit testing in React is worse off today than it was three years ago because of this mindset.

Tests should be fast ¶

In that article, I believe this is a critical miss:

There's no getting around the fact that shallow rendering is faster than any other form of testing react components. It's certainly way faster than mounting a react component. But we're talking a handful of milliseconds here. Yes, it will add up, but I'd gladly wait an extra few seconds or minutes for my tests to finish in exchange for my tests actually giving me confidence that my application will work when I ship it to users. Kent C. Dodds

In my experience, we’re not talking milliseconds. We’re talking minutes, often tens of minutes, across the entire test suite.

Here’s the thing: slow tests don’t get run. It’s as simple as that. You will ignore slow tests as you code, because you have to. You’re holding a bunch of context in your head, and you are working to organize thoughts and get them down, and you don’t have time to stop frequently and wait for tests to run. You don’t have time to figure out whether the tests are checking the change you just saved, or if they’re still running from a change you made five minutes ago. Not until it’s time to commit, or worse, merge, will you check test results. Only then do you catch the error, sometimes even a critical oversight, and have to re-work.

But fast tests — those you can leave running all the time. Those give instant feedback. Those shorten the iteration cycle from hours to seconds. Fast tests are worth more than slow tests.

Tests should be focused ¶

Kent’s post lays out many bad practices common in React unit testing, often seen when using Enzyme:

inspecting component state
directly manipulating a component’s state
spying on a component’s internal methods
getting the component instance and fiddling with it in ways your user never could

And I absolutely agree with every one of these points. These are internals, implementation details that are irrelevant and have no business in your tests. (Kent also makes arguments about accessibility I also agree with, but think are rather beside the point.) And I also agree that Enzyme probably shouldn’t give us the ability to do many of those things, as it enables bad practices.

But that doesn’t mean shallow rendering is wrong. It means that bad test practices are. These bad habits can exist with deep rendering just as with shallow.

Kent says, “For example, the <Fade /> component we have above is an implementation detail of the <HiddenMessage /> component, but because we’re shallow rendering <Fade /> isn’t rendered so changes to that component could break our application but not our test.” But that’s good! Let the unit tests for the Fade component test whether it works correctly. Just assert that your component sets the correct props on Fade, and who cares what Fade does with them — those are concerns of a different test suite.

With shallow rendering, a failure in the HiddenMessage test suite means HiddenMessage has a bug. With full rendering, a bug in Fade means dozens of tests are going to fail across multiple test suites. Then you get the fun job of tracking down where the bug originated. With unit tests, you know exactly where the bug is, because only the test suite for the Fade component will break. If <Fade /> is well tested, and you assert that <HiddenMessage /> passes the correct props to <Fade /> based on user interaction, then you can be confident in your code.

Tests should be comprehensive ¶

Is there a place for integration testing, as Kent explains? Absolutely. But not at the expense of unit testing. Apart from being faster, unit testing also tests something integration tests simply cannot do: complex permutations.

If a particular component has three key behaviors, it requires three unit tests*. If its child component has three key behaviors, it requires three unit tests. If you plan only to test those behaviors via integration tests, you need three times three unit tests, because you have to check how every permutation behaves.

But your app isn’t just two components, so let’s keep going. If you have a grandchild component with three key behaviors, you need to multiply all your integration tests by three, so you need 27 integration tests. Four interacting components mean 81 tests.

My codebase has hundreds of components. I asked my calculator how many tests that would need, and it gave me an answer with an e in it, if that tells you something. How many components are in your codebase?

Even a moderately sized app will need tens of thousands of tests to cover all the possible permutations of component behaviors. If you rely solely on integration tests, you will never have confidence in the behavior of your application, because you will never be able to write thousands of tests, let alone wait the hours required to run them all.

*I’m simplifying, of course. In reality, the component probably needs six to ten unit tests, because you need to assert negative conditions as well, and error handling. So you can see that the problem will actually compound much worse that I’ve stated here.

But with unit tests, it’s much simpler. Assert that each component does what it should when given certain props, and when certain user interactions occur. Then assert that each component sets the correct props on its children components. If those child components are similarly tested, you can be confident with far fewer tests than checking all the ways those behaviors can mix and match in integration.

React has shot itself in the foot ¶

What really gets me about all this is it’s not just the community that has gone down this road, the React library itself has encouraged it. They have essentially abandoned their shallow renderer, and with the rise of hooks, third party libraries such as Enzyme can’t see into React’s internals enough to do it either. The way React is structured now, you simply can’t exercise some hooks like useEffect in a shallow render. And yet nobody with any clout in the community seems to care.

Client Side NPM

2020-04-21T17:00:47Z

Disclaimer: this is an _idea_. At this point, I’m not entirely convinced it’s a _good_ idea, but it’s an idea nonetheless. This is something I thought of about a year ago, and recent discussions brought it back to mind. The point of this post is to flush out the idea a bit, as a sort of thought experiment. Take this with a grain of salt, and I’d gladly welcome feedback and critique.

So the web has a performance problem. Before I get into it, I’ll concede the point that some of this is due to either over-engineered solutions or lazy developers who add dependencies without much thought to the ramifications. But there are plenty of sites and apps out there that legitimately require complexity, large dependencies, and lots of code.

This is a proposed solution to help address this problem: Client Side Package Management.

Goal: Dramatically Cut Network Traffic ¶

On many, many sites, the bulk of the JavaScript bundle comes from dependencies. This means we spend most of our bandwidth downloading the same code over and over again as we browse the web. “Client side package management” would be an effort to offload all of that into an efficient caching strategy. If two completely unrelated sites both use React Router, they can use the same local copy without repeatedly pulling it down the wire. If a user frequently visits your app, they only need to re-download the code you wrote; not all of its dependencies.

Conceptually, it would work like this: Code split your app into two JavaScript files. The first would be your “core” app — all the code your team wrote. The second would be a bundle of all its dependencies. So when a site needs a dependency such as React, instead of including React in the core bundle, it would be bundled in the dependencies file. This dependencies bundle serves only as a backup for clients that don’t support package management.

If the browser does support it, it would fetch only the core script. Then instead of downloading the dependencies bundle, it would go directly to NPM, fetch the appropriate version of React, and store it locally. It would do likewise for any other dependencies. On subsequent visits, the core script can be re-downloaded (or fetched from normal browser cache), but the dependencies would already be available locally in the package manager, so it would not need to be downloaded again. And because the dependencies are indexed by their name on npm, they can be re-used on other sites that rely on the same packages.

If the browser does not support client side package management, it would fetch the the dependencies bundle from the page’s server. The page would effectively work just like the web does today. This can be a fully backwards-compatible enhancement.

In some ways, this is an iteration on the idea of a CDN, which among other things attempt to save bandwidth by relying on browser caching. In practice, though, CDNs very rarely produce hits in the browser cache; too many sites rely on slightly different version numbers or different host CDNs to ever gain that benefit. But with package management, the host is always the user’s computer and it is fully aware of semantic versioning; one site relying on lodash ^4.17.4 and another using lodash ^4.17.10 would share the same resource. For reliability, packages are sourced directly from the package manager where their author has published them (i.e. npm.com).

How to Accomplish This ¶

This sounds nice in theory, but how could it actually be accomplished? And I mean, accomplished today, without waiting interminably for standards bodies to do their thing. I believe in the power of the open web platform — but wild new ideas generally need to be proven in the real world before a standards body would ever consider adding them to language specifications.

I see two potential approaches that could work. The first approach would be through the use of a browser extension. The second would be through the installation of a native application that leverages custom protocol URLs (something like package://npmjs.com/react@^16.10.0). It’s possible a hybrid of both would be necessary to work around CORS issues and access to enough hard drive space to store downloaded packages. Either way, web apps that are built for this approach could encourage their users to install the appropriate dependencies: A banner with a link could appear at the top of the page that reads, “This site has been optimized for client side package management. For a faster browsing experience, you can install the plugin for free.”

I’ll be the first to admit, this brings up flashbacks of old sites with the notice, “This site required Flash,” which is not a pleasant memory. The key difference would be that the plugin is entirely optional. The page remains fully functional without it, by downloading dependencies from the server, bundled in a normal JavaScript file. And, unlike Flash, these dependencies would be built using native web technologies.

Versioning and Storage ¶

This must be fully aware of semantic versioning. If a page depends on a version ^3.14.0 and version 3.14.7 is found in the local cache, the already-available package would be used. Meanwhile, the client could even perform a check in the background if any newer version is available, and if it is, download it in a low-priority network request for use in subsequent visits to pages that rely on it.

I’m a little hesitant about that last part. We wouldn’t want to chew through disk space eagerly storing unnecessary files. But either way, there should probably some sort of cleanup algorithm that takes into account how frequently a specific package is used and how long it has been since last use, automatically deleting those that seem to be outdated. The user could even customize how much disc space they wish to allocate for package storage.

Miscellaneous Thoughts, Questions, Problems ¶

Bundling ¶

This would definitely require code splitting to separate the “core” app script from the dependencies (and of course further splitting should be supported). The exact specifics need to be worked out for how native JavaScript would load the secondary bundle while the plugin, if installed, would prevent that request and use package management instead. Would this require a custom bundler, or could an existing bundler do this in an acceptable way?

Testing & Debugging ¶

This could complicate development as different users could end up with different combinations of package versions. The plugin should probably provide a user-friendly means of creating a bug report with exact versions in use, and stack traces if available.

Abuse by Developers ¶

More highways equals more traffic. I’d hate for developers to see this as a carte blanche for dumping more dependencies on a site, but that’s sure to happen. I don’t have a great solution to this at this time, but I would certainly be on the lookout for any ways to incentivize developers to keep their dependencies in check. The browser must pull them down the first time they’re required, after all.

WASM ¶

Client side package management addresses network bloat, but there remains the overhead of parsing those scripts every time they’re used. Can we leverage (or even require) WASM to speed things up even more?

Exit Strategy ¶

I mentioned flashbacks to “this site requires Flash” notices. This could be amazing now, but I would hate for this to still be the status quo ten years from now. I would hope some future iteration on the idea (including a formalization of what constitutes a “package”) could make its way into the native platform and then this project could be sunset.

Security ¶

When it comes down to it, your webpage could be running code that was installed by some other unknown website. This sounds Really Bad when put in those terms. However, this only applies to code installed directly off of a known package repository (e.g. npm), and only if your site explicitly asked for that same package to be run. The key task here would be to ensure this can’t be spoofed. I would also presents the user with a big red dialog box about “unfamiliar package repository” if a site ever tried to install a package from anywhere else. (You could restrict it to npm only, but I want to leave the door open for alternatives like Entropic.) Fingerprinting based on which packages load instantly from cache could also be a concern.

Conclusion ¶

Obviously a lot of the technical details would need to be ironed out, if this is something to pursue. I’ve resisted the temptation in this post to go down that road, and instead focused on more on the general concept. So what do you think? Am I crazy or could this work?

Adding Webmention Support to a Static Site

2019-02-01T17:47:33Z

This is Part 3 in a series exploring short-form posting, the IndieWeb, and taking control of your own online social workflow for your statically-generated site:

A Low-Friction Workflow for Short-form Posting on A Statically Generated Site
Preparing Your Site for Posting Notes
Adding Webmention Support to a Static Site
Using Micropub to Post to a Static Site — Coming soon

Webmentions are a key building block of the IndieWeb. They are they way for one webpage to notify another when it has linked to it. This is based on a W3C Recomendation spec.

In this post, I will show you how to set up webmentions for a statically-generated site. This is not the only way to do it, but it is how I do it for this site, so I know it works.

Receiving Webmentions ¶

A webmention is sent as a POST request containing two pieces of information: a source URL and a target URL. The page at the source URL must include a link to the target URL, which the webmention endpoint will verify before accepting the webmention. (You won’t actually have to implement this, but it’s worth knowing for context.)

In the previous post, I showed you how to sign in to a service called webmention.io. This will provide your site’s webmention endpoint. When someone links to a page on your site, they can notify the endpoint, and you can choose what to do with that webmention.

You will have to make this endpoint known so you can receive webmentions. Log-in to webmention.io, and navigate to the settings page. This will provide you with two <link> tags you should add to the <head> for every page on your site. They will look something like this (with your site’s URL in place of keithjgrant.com):

<link
  rel="webmention"
  href="https://webmention.io/keithjgrant.com/webmention" />
<link rel="pingback" href="https://webmention.io/keithjgrant.com/xmlrpc" />

Add this to your site. This tells other sites what endpoint to send their webmentions to. (It also includes a pingback endpoint for sites that support the older standard instead—webmention.io will handle both for you). Webmention.io provides you with a feed you can subscribe to to see all webmentions you receive. The url is listed on the settings page.

Displaying webmentions on your site ¶

Part of the fun of webmentions is being able to display the replies, likes, and shares of your content you receive. If you want, you can add some JavaScript to your site to fetch these, and add them to the page beneath your posts.

How you add these to your page will be unique to your site’s design, so I can’t give you exact code to copy and paste, but I’ll highlight the key things I do for my site. Here is my source code for this.

First, perform a GET to https://webmention.io/api/mentions?perPage=500&jsonp=parseWebmentions&target={PAGE_URL}, where {PAGE_URL} is the current page. You will need to use JSONP so you can make the request cross-domain. This url specifies the JSONP function parseWebmentions, which you will need to include in your page’s script. This function must be defined as a global, so the webmention.io script can invoke it.

The parseWebmentions() function will be invoked with an array of objects, each representing a webmention you’ve recieved, including metadata about the source page that sent it. Each one of these objects will look something like this:

{
  "source":"https://example-site.com/2019/01/22/the-secret-weapon-to-learning-css/",
  "verified":true,
  "verified_date":"2019-01-22T17:06:39+00:00",
  "id":580804,
  "private":false,
  "data":{
    "url":"https://example-site.com/2019/01/22/the-secret-weapon-to-learning-css/",
    "name":"admin",
    "content":null,
    "published":null,
    "published_ts":null,
    "author": {
      "name": "John Smith",
      "url": "https://example-site.com",
      "photo": "https://example-site.com/avatar.jpg"
    }
  },
  "activity":{
    "type":"link",
    "sentence":"https://example-site.com/2019/01/22/the-secret-weapon-to-learning-css/ posted '' linking to https://keithjgrant.com/posts/2019/01/css-mental-model/",
    "sentence_html":"<a href=\"https://example-site.com/2019/01/22/the-secret-weapon-to-learning-css/\">someone</a> posted '' linking to <a href=\"https://keithjgrant.com/posts/2019/01/css-mental-model/\">https://keithjgrant.com/posts/2019/01/css-mental-model/</a>"
  },
  "target":"https://keithjgrant.com/posts/2019/01/css-mental-model/"
}

I sort these chronologically (using webmention.data.published or webmention.verified_data). Then I put them into three different arrays: one for likes (webmention.activity.type === 'like'), one for reposts and regular links (webmention.activity.type === 'repost' || webmention.activity.type === 'link'), and one for replies (everything else). I then have code to convert the metadata into DOM elements and add them to the page in the appropriate place. Again, feel free to rework my code to suit your purposes for this—I include a <template> on my page for these, which I clone into the page and hydrate with the fetched data.

If you really want to get fancy, you can fetch your webmentions every time your site builds, and add them into the initial render of the page. If you go this route, however, you should probably make an additional fetch from the client side to pick up any webmentions that you’ve received since the last time you built your site.

Enhancing with Microformats ¶

When a webmention is sent, it includes only the source URL and the target URL. But you’ll notice in the payload received from webmention.io there is a whole lot more information included. This is all information it was able to parse from the page at the source URL. How much it is able to figure out will depend largely on whether or not the page uses microformats in its markup.

Microformats are a series of class names added to the markup to help indicate the meaning of the parts of a page. I strongly urge you to add microformats support to your site. Most tools for working with webmentions expect microformats to be there, so this will be essential for using some IndieWeb tools.

There are two types of microformat that you should add to your site first: h-entry and h-card. An h-entry allows you to identify the key elements of a post, including url, title, publish date, and content. An h-card identifies an author, including name, website url, and an avatar image.

Add the classes for an h-entry to the markup for every post on your site. Here is a sample post with h-entry microformat classes added:

<div class="note note--list h-entry">
  <div class="note__date">
    <a
      class="u-url dt-published"
      href="https://keithjgrant.com/replies/2019/01/yes-do-it/"
      >10:24 AM EST • 14 Jan 2019</a
    >
  </div>
  <div class="metadata text-left">
    in reply to
    <a
      class="u-in-reply-to"
      rel="in-reply-to"
      href="https://twitter.com/SaraSoueidan/status/1084833046140981248"
      >a post on twitter.com</a
    >
  </div>
  <div class="note__body e-content show-embeds">
    <p>Yes! DO IT ✨</p>
  </div>
</div>

The essentials here are the classes h-entry, u-url, and e-content. h-entry must be on an element containing the entire post. The other microformat classes within indicate further metadata on this entry. u-url indicates the canonical URL of this post (specified in the href attribute). e-content denotes the body of the post. p-name, when present, indicates the title of the post (this post has no title because it is a short-form note rather than a full blog post). Some other useful classes an h-entry might have are u-in-reply-to or u-like-of, indicating the post is a reply to or “like” of a post elsewhere on the web, and dt-published to indicate the publish date.

The tag names are irrelevant; use correct semantic HTML elements, and add microformat classes to indicate what the elements mean as part of the post.

Your homepage should have an h-card on it somewhere, providing data about you. Here is an example h-card:

<div class="h-card p-author">
  <h1 class="title-bar">
    <a class="u-url" href="/">
      <span class="p-name">Keith J. Grant</span>
    </a>
  </h1>
  <img class="title-avatar u-photo" src="/images/keithjgrant.jpg" />
</div>

Here, h-card indicates this is an author card. u-url denotes my primary url (the homepage of the site). p-name indicates my name and u-photo indicates the image I would like to use as my avatar.

You can also nest microformats. It is a good idea to add an author card inside every post. When this h-card is placed inside of an h-entry, the p-author class indicates that I am the author of that post. So when I reply to a post elsewhere on the web, the site that recieves my webmention can parse some data about me and my reply, and present them in a way that is well formatted. This sort of metadata is what allows me to present not just replies to my posts, but also the author’s name and image alongside:

Adding microformats can be a bit troublesome, because it’s hard to know at a glance whether you’ve done it correctly or not. One tool to help with this is X-Ray. As you integrate microformats on your site, plug in the URL to a post into X-Ray and see what kind of metadata it finds. This will display as a JSON object:

Additional microformats can be used to markup things like recipes, events, and products reviews. See microformats.org for details on these if you’re interested.

Integrating with Twitter ¶

Webmentions are fantastic for interacting with other blogs, but what about social media? Twitter doesn’t support webmentions, but there is a tool called Bridgy that can add this support for you. If you send Bridgy a webmention, it will post your note to your social network accounts for you. And if those posts get replies (or likes, or reposts), Bridgy will send you valid webmentions letting you know about it.

To setup Bridgy for Twitter, visit brid.gy and click the Twitter button where it says “Connect your accounts”. This will take you to twitter, and will ask you to grant Bridgy access to post to your Twitter account. Click “Authorize app” to give it access.

Next, you’ll need to add a link to Bridgy in your posts, so you can send a webmention to Bridgy. Add this to your page template for notes. If you followed the site structure like as I described in the previous post, a good place to add this would be to the partial template at themes/[theme-name]/partials/note-full.html. Place this inside the e-content of your h-entry:

<a href="https://brid.gy/publish/twitter"></a>
<data class="p-bridgy-omit-link" value="false"></data>

The first line provides an (empty) link to bridgy, so you can send Bridgy a webmention. The second line — which is totally optional — provides some metadata to bridgy telling it to include a link back to your post when it syndicates to twitter.

Send your first webmention ¶

At this point, your site should be able to receive webmentions, and it should have valid microformats so other sites can parse your content should you send webmentions.

Your site doesn’t send webmentions yet — I’ll cover that in the next post — but in the meantime, you should be able to send them manually with a tool called Telegraph.

If you haven’t already, publish a Note to your site. Make sure the resulting page has valid microformats (using X-Ray) and it includes a link to bridgy.

Then visit Telegraph and sign in using web sign-in:

Once logged in, you should see a text input labelled “Find Links”. Enter the full URL of the note you just published and click the button:

Telegraph will scan the h-entry on that page and find any links therein, including your link to Bridgy. It will show you a list of these links and, for those targets that support webmentions, it will provide a button to send a webmention. Click the button next to ”https://brid.gy/publish/twitter”.

If all goes well, your note should show up on Twitter, posted from your account! Bridgy will monitor your stream for activity, and when it sees some, it will forward it to your site as a webmention. It polls once every 30 minutes or so, so replies won’t show up immediately. While testing, though, you can log in to Bridgy and click the “poll now” button to skip this waiting period.

Hopefully this is helpful! In the final post, I will walk you through setting up Micropub so you can post notes more quickly to your site, and I will show you how to automate the sending of webmentions, so you won’t have to open up Telegraph every time you post a new note.

Preparing Your Site for Posting Notes

2019-01-17T19:23:33Z

This is Part 2 in a series exploring short-form posting, the IndieWeb, and taking control of your own online social workflow for your statically-generated site:

A Low-Friction Workflow for Short-form Posting on A Statically Generated Site
Preparing Your Site for Posting Notes
Adding Webmention Support to a Static Site
Using Micropub to Post to a Static Site — Coming soon

If you’re eager to get going with short-form posting using webmentions and micropub, it’s worth giving your site structure a little thought so you know where your notes will go. You’ll also need to enable something called Web Sign-in so you can use some of the tools I will mention in the upcoming posts.

I’ll walk you through these things below. My thoughts on site structure may be self-apparent, but be sure you don’t miss the setup instructions for Web Sign-in, as this will be an essential prerequisite as we continue in the following posts.

Static site structure ¶

I use Hugo and Netlify for my site. My site content is stored in a git repository. For new posts, I create a markdown file anywhere within a content directory. Hugo builds these files into web pages, with URLs matching the directory structure. When a change is pushed to Github, Netlify automatically runs Hugo and publishes the resulting pages. If you want help getting started with these, Sara Soueidan has a great post on setting those up.

My instructions in this series can be applied to any static site generator and hosting setup. As long as you have a static site and an automatic build process, it should work for you, but it you may have to adapt some of the specifics yourself.

It usually makes sense to have separate places in your site structure for long- and short-form posts. On my site, I have broken these up into separate directories called posts and notes. I’ve also added additional directories for replies, likes, and bookmarks; you don’t have to add these if you don’t want to, but I find them useful.

Inside all five of these directories, have subdirectories for each year, and subdirectories for each month within those. My directory structure looks something like this:

content
 └- bookmarks
 └- likes
 └- notes
 |   └- 2018
 |   |   └- 11
 |   |   └- 12
 |   └ 2019
 |   |   └- 01
 └- posts
 |   └- 2018
 |   |   └- 11
 |   |   └- 12
 |   └ 2019
 |   |   └- 01
 └- replies
static
 └- images
themes
 └- shindig (my theme name)

My site is run by Hugo. Adjust this as necessary for Jekyll or Eleventy. Or to suit your own desires, really.

I prefer my long-form posts to look different than my notes and replies, so in my Hugo theme, I have some logic to render those using different partial templates. If you’re comfortable editing your Hugo theme, you can change it to something like mine. This is the file themes/[theme-name]/layouts/_default/single.html:

<!DOCTYPE html>
<html lang="en-US">
  <head>
    \{\{ partial "meta.html" . }}
  </head>
  <body>
    \{\{ partial "header.html" . }} \{\{ if or (eq .Section "posts") (eq
    .Section "") }}
    <main class="l-article h-entry js-main">
      <div class="l-article__inner">\{\{ partial "post-full.html" .}}</div>
    </main>
    
    <main class="l-note h-entry js-main">
      <div class="l-note__inner">\{\{ partial "note-full.html" . }}</div>
    </main>
    \{\{ end }} \{\{ partial "footer.html" . }}
  </body>
</html>

The key here is the if statement near the middle: \{\{ if or (eq .Section "posts") (eq .Section "")}}. This statement renders the first block for pages that are in the posts directory (.Section equals “posts”) or are top level pages (.Section equals an empty string). It renders the second block for everything else, such as my notes and replies.

The first block includes a partial called post-full.html which is resides at themes/[theme-name]/partials/post-full.html. The second block includes note-full.html which is at themes/[theme-name]/partials/note-full.html. Use these partials to define your page structure for long-form and short-form content, respectively.

Once that is done, you can create a new note by creating a new file in the appropriately-dated directory: hugo new notes/2019/01/my-first-note.md.

This part of your setup is very flexible. Use my directory structure as an example, but feel free to modify it as needed so your site’s structure makes sense to you.

Several of the tools and services used on the IndieWeb require something called Web Sign-in. This is a way to login to a service using your website as a username, proving you are the owner of your website. Setting this up should be a quick process.

First, add links to your various social profiles somewhere on your homepage. Include a rel="me" attribute for each of these:

<ul class="social-links">
  <li>
    <a href="https://twitter.com/keithjgrant" rel="me"
      >@keithjgrant on Twitter</a
    >
  </li>
  <li><a href="https://github.com/keithjgrant" rel="me">Github</a></li>
</ul>

Be sure to include GitHub. I’ll explain why in a moment.

Second, on each of the services you link to, edit your profile so the “homepage” field links back to your website:

At this point, your homepage links to your social profiles, and your social profiles link back to your homepage, each with a rel="me" attribute. This means, if you log in somewhere using OAuth for one of these accounts, you also verify that you are the owner of your site.

Unfortunately, Twitter recently changed the way profile links work with some complicated redirects, so it’s not straightforward for a service to verify the link. GitHub is the best widely-used service right now that correctly uses rel="me" on a user profile page, so I recommend you use this service for Web Sign-in.

Finally, you will add some metadata to your homepage to indicate which Web sign-in service you wish to use. I recommend IndieAuth.com, though there are others available.

Add this code within the <head> of your site’s homepage:

<link rel="authorization_endpoint" href="https://indieauth.com/auth" />
<link rel="token_endpoint" href="https://tokens.indieauth.com/token" />

This tells third party services that use web sign-in to use IndieAuth to log you in. IndieAuth will find the link to your Github account and verify that your GitHub profile links back to your site. It will then allow you to login to Github, and will then provide a token to third party services verifying you are the owner of your site.

Test it out ¶

To test that this is working, visit Webmention.io and enter your site’s url in the login box:

This will take you to indieauth, your preferred Web sign-in endpoint. IndieAuth will ask which service you wish to use to sign in:

Github is the only valid option right now, so click the green Github button. If you’re not already logged into Github, this will ask you to login. Once logged in, it will redirect you back to webmention.io.

Now you’ve created an account on webmention.io: your website url is your username, and you didn’t need to create a password or check an email; your website and Github account are all you need. In the next post, I’ll show you how you can use this service to receive webmentions on your site.

A Low-Friction Workflow for Short-form Posting on a Statically Generated Site

2019-01-17T15:11:33Z

This is Part 1 in a series exploring short-form posting, the IndieWeb, and taking control of your own online social workflow for a statically-generated site:

A Low-Friction Workflow for Short-form Posting on A Statically Generated Site
Preparing Your Site for Posting Notes
Adding Webmention Support to a Static Site
Using Micropub to Post to a Static Site — Coming soon

I am thrilled to see more and more folks are moving to their blogs for posting short-form content, usually referred to as Notes. These are very brief blog posts, usually about the same length as a Tweet or Facebook update. Of course, as they do this, they inevitably start grappling with the question: “How do I make sure these notes are copied to Twitter?” And maybe also: “How do I make the process quick and seamless?”

I gave a talk a while back titled The Decentralized Social Web where I covered the general principles to make this work. This is part of a concept known as the IndieWeb. But I haven’t covered the specifics of how I set this up for my site. I am frequently asked about my notes and replies on Twitter, and have promised a write-up repeatedly. It’s taken me far too long, but this is that write-up.

Getting on the IndieWeb ¶

If you’re the type of person who uses a static site generator (i.e. a developer or otherwise technically literate), you should be able to set this stuff up yourself. None of it is too complicated, but there several pieces to it.

Each piece on its own is fairly straightforward, and there is a sort of exponential return: the more of these pieces you put in place, the more they work together to give you a smooth workflow. Which is why I want to start by illustrating the final experience. I will avoid bogging this down with the how (that will come in the following posts) and will instead focus on what. I will get into the specifics in the rest of this post series.

If you already have a blog or website: Congratulations! You’re already on the IndieWeb. The rest is a series of enhancements you can make to add to that experience.

The magic in action ¶

I write my notes using the Omnibear browser plugin (available for Chrome and Firefox). I type what I want to say, check the “syndicate to Twitter” box if I want it copied to Twitter as well, and click Post.

This adds the entry to my site, which usually publishes in around 45–60 seconds (the time it takes for Netlify to rebuild my site). After another minute or so, a copy of the note appears on Twitter, along with a link back to the original on my site. If people reply to the post on Twitter, those replies are automatically copied back to my site.

I can also reply to tweets. On twitter.com, I can right-click on a tweet and select “Reply to entry”.

This opens the Omnibear window and allows me to write my reply.

As before, this posts to my site. Shortly thereafter, the reply is copied to twitter.

Hopefully, this sort of workflow sounds appealing to you. If you want to know how to do this stuff, stay tuned.

A new type of web standards ¶

When we developers talk about Web Standards, we tend to talk about the basic building blocks of web pages: HTML, CSS, JavaScript. But there are more standards beyond these languages. The W3C, in fact, has a Social Web Working Group. This group has published several standards.

Two key standards to be familiar with are Webmention and Micropub.

Webmention is a way to let another webpage know when you have linked to it. If you’re familiar with the old Pingback concept, this is similar, but greatly simplified. In the example above, I replied to a post on Twitter, but I can just as easily reply to a post on any site that supports Webmentions. If you write a note on your site, I can reply to it directly, without going through any third party service.

Micropub is a way to post directly to your site using a third party editor. In the example above, this editor is Omnibear, but it could just as easily be an app called Quill or another similar service.

The important thing to note here is that I haven’t rigged up a custom script to post to my site and copy to Twitter and crawl through twitter for replies. I am using open web standards. Most of the work is done by existing tools that understand these standards, not one-off code.

If I want, I can swap out Omnibear for a different editor, or change to a new Micropub server if I find an alternative I like better. Open standards drive it all, so nothing is proprietary. In the following posts, I will show you how I chose to configure each piece of the puzzle; but you can just as easily change one piece out to suit your needs, while still doing other parts of it just as I have.

In short: my process is not an all-or-nothing approach. I’ll show you what I use, and you are free to pick and choose from among the pieces. You can implement them one at a time at your own pace, or all at once. In the rest of this series, I’ll walk you through how to do it.

Teaching a Correct CSS Mental Model

2019-01-08T17:38:52Z

Almost four years ago, I chimed in on the debate surrounding CSS. Is it good? Is it broken? Does CSS-in-JS solve anything?

The discussion has evolved since then, as has CSS-in-JS tooling, but we are still seeing regularly recurring heated arguments on Twitter. The most recent happened — checks watch — an hour ago.

It’s interesting to read my original article now. There are elements I still agree with, and some I don’t. There are some that I now think were beside the point. At the end, I concluded with this: “you need to learn CSS”.

For quite a while now, I have distanced myself from that argument: there are people in the CSS-in-JS community that really do understand the language, and are using JavaScript tooling to deal with its legitimate shortcomings. Many of them have learned the language, and those shortcomings are still there.

We need to teach a mental model ¶

Yet in some ways, I find I’m coming full circle back to that argument: if you think CSS is a mess or broken, you need to learn CSS. What I mean by that now, however, this not about learning the specifics of CSS, but rather building a correct mental model of it.

Natalya Shelburne articulated this brilliantly in her recent talk “CSS at the Intersection”. She describes the cognitive dissonance that is an important part of learning:

You try something new outside of your comfort zone and you expect it to work a certain way, and it does something else. It breaks, and you have no idea what happened. You get these unpredictable things. It makes no sense and you start thinking, “Why would someone make something so frustrating?”

This is a natural reaction when facing something where we don’t have a correct mental model. It’s an essential step in learning, to face this, and to learn to push through it and correct your mental model. It’s a reaction we see all the time online regarding CSS. If we’re honest (and we can recall well enough), it’s a reaction we all felt at one point or another when we were learning CSS.

The problem is, a surprisingly large number of people seem to have incredible difficulty moving past this point, and adjusting their mental model of the language. Some developers like myself were able to do it. Others stay stuck in this place for years.

One facet of this whole CSS debate involves one side saying, “Just learn CSS” and the other side responding, “That’s what I’ve been trying to do!”

I think it’s high time we the teachers of CSS start discussing how exactly we can teach a correct mental model. How do we, in specific and practical ways, help developers get past this point of frustration. Because we have not figured out how to properly teach a mental model of CSS.

I think, perhaps, we’re beginning to circle closer to this. There seems to be more focus lately on fundamentals of the language like document flow and the box model and formatting contexts.

A “Common Core” for CSS ¶

Schools in the U.S. have recently begun teaching something called “Common Core.” It’s controversial in some ways (and I’m no expert in Common Core, so take this analogy with a grain of salt), but I like some of the things I’ve seen regarding Common Core math.

It teaches tricks for making difficult arithmetic easier. For example, if you need to add 32 + 67, break the problem up to 30 + 60 and 2 + 7, both of which are much easier to do in your head. As someone who excelled at math in school, I have found that most of these Common Core tricks are things I discovered on my own as a student, and are precisely why I was able to do well in the subject.

We need common core tricks like this for CSS. Not “tricks” in the old sense (like how to fake a gradient border), but mental patterns: ways to frame the problem in our heads, so we can break problems into their constituent parts and notice recurring patterns. Those of us who deeply understand the language do this internally. We need to start working on distilling out these mental patterns we use for understanding layout and positioning and working with relative units, so that we can articulate them to others.

This will take some deep consideration and intentional analysis of our internal thought processes while we code. But I think if we are able to distill out recurring patterns of thinking, we can find a common set of tools we can teach to those who struggle with webpage layout.

And maybe, just maybe, we can make the development community a less hostile place for developers in the process.

Won’t You Be My Neighbor

2018-09-10T12:29:22Z

Here we are again. Arguing about CSS, the cascade, and CSS-in-JS. And you know what? We’ll be here again in a few months. Because that seems to be the cycle.

Somebody tweets something, usually rather innocuous. This gets spun a few times with various reactions. Then it escalates.

So often conflicts arise from lack of communication, false assumptions, or confusion. Mr. Rogers

Since this is clearly destined to happen again and again in the web developer community, I think it’s time we learn to have these discussions more productively. — And no, I’m not the first to say this.

The Twitter culture isn’t helping ¶

We’ve got to stop with the hot-takes. This is a complex topic, now with a lot of argumentative history and misunderstandings. 280 characters just isn’t enough to adequately frame your thoughts any more. Even if your tweet is well-phrased, it will not take long for it to be mis-interpreted and quote tweeted while the conversation spirals out of control.

Initially, I tweeted something, then tried to frame it better with a few follow-up tweets, but the resulting thread quickly became a game of poking at the other side. Eric Meyer tweeted, and it was interpreted in ways he didn’t intend. To the point where he’s expressed regret for the tweet. These things just don’t work on Twitter.

I recently heard how a friend helps their son when he’s being whiney: they tell him to “walk away and come back with a better attitude.” He has to literally walk down the hallway, then back into the room before asking for the thing he wants more politely. And it usually works.

So maybe it’s time we all practice this, too. Myself included. Instead of a hot-take, take it to your blog. Even if you only write three paragraphs, that will a) be more nuanced than even a thread of tweets, and b) will allow you more time to collect your thoughts and articulate them better.

Enough with picking sides ¶

We’ve got to stop with the this camp vs. that camp stuff. Mark Dagleish tweeted, “It’s my life goal to never be part of the technical old guard.” And I tell you what, this got my hackles up.

Now, to be fair to Mark, he’s far from the only one to make this about sides. He also tweeted several other things on the topic that I thought were very helpful and insightful. But I hate that this has somehow become some “old guard” vs. “new guard” thing.

The problem with drawing lines like this: whichever side you find yourself on, there are some whackos out there throwing ridiculous arguments into the mix. And now people on the other side associate that viewpoint with you.

Instead, call out the folks on “your side” who are off in the weeds. To whatever “cascade defender” out there made this a CSS-in-JS bashing party: knock it off. To those on the other side who said the don’t want their employees bothering to learn the cascade: cut it out. Everyone else is somewhere in between. And we don’t have to be old guard or new guard. We can just be a web dev, and supporter of the open web platform as a whole.

Just so my cards are on the table: ¶

I think every front end developer should learn the cascade, as it’s a fundamental part of the web platform.
I agree it’s not perfect, and I hope we can continue to iterate and improve on it. But it’s what we have to work with.
I don’t think you’re an idiot if you don’t know it.
That question was particularly misleading.
Despite all the dust I’ve kicked up in the past, I’m not completely opposed to CSS-in-JS. In fact, I brought up Emotion as an option for a project as recently as last week.

Getting Started with Micropub

2018-09-04T16:39:16Z

With the recent discontentment on Twitter (and social media in general), I’ve seen a resurgence of people returning to blogging. In particular, I’ve noticed more folks posting short entries, or notes, to their blog — either in addition to Twitter, or in place of it.

If you are interested in doing this, micropub is a great way to make it a frictionless experience. Micropub is a new W3C standard, allowing you to post directly to your site using third-party apps.

I recently wrote a quick overview how to get started with micropub as part of the Omnibear documentation. Check it out.

Resilient, Declarative, Contextual

2018-06-08T13:39:05Z

I’ve spent a lot of time thinking about what defines a CSS mindset. Some people seem to “get” it, and others don’t. It’s always felt to me that if I could put my finger on that, maybe CSS would make more sense to those who have struggled with it. One piece of my motivation in writing CSS in Depth was to try to articulate some of those things.

Today I want to take a different tack. I want to look at three key characteristics of CSS that set it apart from conventional programming languages: it’s resilient; it’s declarative; and it’s contextual. Understanding these aspects of the language, I think, is key to becoming proficient in CSS.

CSS is resilient ¶

If you were to randomly delete a chunk of code out of a JavaScript file, the app or page using it would almost certainly come crashing to a halt and much of the script (if not the page as a whole) would become useless. If you do the same thing to CSS, you might not even notice. Almost everything apart from that specific section of code will continue to work as intended.

We call this resilience. HTML and CSS were specifically designed to be fault-tolerant. If there’s a problem, the browser won’t throw an error; instead, it will ignore that part of the code and keep on going.

This may seem absurd from a debugging perspective: if it doesn’t throw errors, how do you know what went wrong? But this is an essential piece to how CSS works. It’s woven into the fabric of the language itself. It may take some getting used to, I admit. Once you understand this, though, you can safely use features that aren’t supported in all browsers. This is what makes progressive enhancement possible.

Consider this example of a grid layout. It works in browsers that support grid, and it works in browsers that don’t support grid. It will be slightly imperfect in those that don’t support grid (the exact sizes of the items will probably vary), but it will still layout the page in roughly the same way:

.portfolio {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(400px, 1fr));
}

.portfolio__item {
  display: inline-block;
  max-width: 600px;
}

A browser that doesn’t understand the two grid declarations will ignore them, and the other rules will do the work. And a browser that does understand grid will use the grid layout and ignore the inline-block declaration (because that’s how grid was designed to work). Jen Simmons half-jokingly calls this “Quantum CSS”. You can take a feature of CSS and “use it and not use it at the same time. It works and it doesn’t work at the same time.”

This concept of “fallback” behavior is integral to using CSS, but it is a foreign concept in most conventional programming languages.

CSS is declarative ¶

In JavaScript, you give specific, step-by-step instructions how to make something happen. In CSS, you tell the browser what you want to have happen, and it works out the how. This is extremely important to understand. If you get it right, CSS will do all the hard work for you! And if you get it wrong, you’ll be fighting against the grain of the language and you will be frustrated at every turn.

Writing CSS is effectively setting up a system of constraints. You don’t tell the browser where to put every single element on the page; you tell it how much space to put between them and let it sort out where they belong. You don’t tell it (or at least shouldn’t tell it) how tall to make a container; you let it figure that out at render time when it knows the contents of the container, which other styles are applied, and how much width is available in the viewport.

There are too many variables to consider. The point of CSS is to make it so you don’t have to worry about them all. Define some constraints. Let the language work out the details.

A simple example ¶

Let’s consider this CSS for a moment: font-size: 2em. What does it do? “It increases the font size,” you say. But that’s not all. It also adjusts the line wrapping of text in the container, as fewer words will now fit on each line. That in turn will often increase the number of lines of text: so it will also increase the container’s height to contain the new lines of text. When the container’s height changes, anything beneath it on the page will be shifted down accordingly. Finally, it also specifies a value for the local meaning of em. Any other properties defined using ems will have their computed values updated to match.

That one declaration creates a whole slew of changes on the page. And they’re all exactly what you should want: the content will always fit, elements aren’t going to wind up overlapping oddly, and anything defined in terms of the font size (like padding, perhaps) will adapt. You don’t have to worry about those details. The browser makes all those calculations and does the work by default.

If you want to stop these things from happening, you can. You could cap the container height with a max-height and overflow: auto. You could redefine padding to be in rems or px so it doesn’t adapt to the local font size. This highlights an interesting part of writing CSS: sometimes you’re not telling the browser what to do; you’re effectively telling it what not to do.

Griddy goodness ¶

Some of the newer features in CSS do even more. Flexbox and Grid are prime examples of this. With just a few declarations, you can build a grid layout that is extremely flexible and “just works”. You don’t have to worry about countless edge cases. You say, effectively “put these boxes in columns of about 400px wide” and it will do it for you. It takes about three lines of code.

If you were to do this imperatively, you would need to deal with all sorts of odd scenarios. What if there’s an extremely long word in one of the boxes? What if the viewport is very narrow? What if it’s very wide? What if one box has a ton of content and another contains just a few words? But chances are, in CSS, you don’t need to think about any of these things. All the hard thought for this has already gone into the spec, and the browser takes care of it for you. This is the power of a declarative language.

This does come with a trade-off: if the declarative language doesn’t support something you want to do (say, a “masonry” layout), you’re left relying on either odd hacks or JavaScript to help accomplish it. And for years, this sort of thing was a large part of CSS development. Thankfully, with the rise of Flexbox and Grid, we can do far more than we could in the past, without any hacks (and yes, floats were a hack). If this limitation still bothers you, I suggest you read up on CSS Houdini, which is just beginning to land in browsers.

CSS is contextual ¶

In the React era, we have embraced the extremely useful approach of modular, component-based development. CSS best-practices do this as well, with BEM and SMACSS and CSS-in-JS. I don’t want to belittle this, because this is an essential way of thinking when building large-scale applications. But I think it’s equally important to acknowledge that CSS is not 100% modular, nor should it be.

There are two reasons for this. First, and most obvious, is that your app should have some global styles. You will almost always want to set a default typeface and font size at the page level. These values will then be inherited by all descendant elements that don’t explicitly override them. You will also want certain aspects of your design to apply repeatedly throughout the page, such as theme colors, border radii, box shadows, and common margin sizes. More localized styles on the page will then assume these global styles are in place.

Second, and more subtle, is the way CSS and your styling decisions are informed by the surrounding context of the page. Consider applying the following CSS to an element:

.the-thing {
  position: absolute;
  top: 10px;
  left: 10px;
}

What will this code do? Without knowledge of where the element is in the DOM and what styles are applied to the rest of the page, there is no way to know. Absolute positioning is done relative to the nearest positioned ancestor; applying it means different things depending on which ancestor, if any, has positioning applied.

Furthermore, how you can (or cannot) stack one element in front of another is going to be highly dependent on where the two are positioned in the DOM. Shuffling items around in the DOM can cause drastic effects on the way items fit together and stack. This is why document flow and stacking contexts are a vital (and sometimes complicated) topics.

The contextual nature of CSS is also due in part to the way design works. If an engineer designs a bridge, you can’t just look at the blueprint and say, “this is all good except this one beam here; go ahead and take that out”. Removing that beam has ramifications on the structural integrity of the whole thing. Similarly, changing one part of a design can have ramifications on how other items on the screen are perceived. Frequently, you will need to style multiple elements together, in conjunction.

If you make the heading in a tile bigger, for instance, it becomes more prominent to the user and therefore makes other items on the screen seem less important. The restrictions aren’t about physics as with the bridge, but there are subtle rules of “soft science” that impact human perception. The parts of the page render in a physical space on screen, and the realities of the physical world (and how we perceive it) are important to be aware of.

We like to architect software using principles of modularity and encapsulation. This makes sense in the world of code, because code is complicated and this breaks the problem up into manageable sizes. But we should also be aware that it isn’t always perfect. In CSS, we can never completely disregard what’s going on outside a given module.

Summary ¶

These three aspects make CSS different than conventional programming languages. These differences may feel foreign, but it’s these differences that make CSS so powerful. And it’s my suspicion that developers who embrace these things, and have fully internalized them, tend to be far more proficient in CSS.

HTML5 Sectioning and Landmark Elements

2018-03-05T17:09:47Z

A little while ago, I wrote about the <dialog> element. But there are plenty of interesting HTML elements that have been around longer, since HTML5 was first introduced, so I’ve decided to expand it into a series.

Every now and then, I stumble across an element I haven’t heard of before. Some are interactive, and provide a surprising amount of functionality with little to no JavaScript. Others provide helpful semantic meaning and a welcome alternative to “div soup” in complex pages.

For the next few blog posts, I’m going to explore some aspects of HTML5 that maybe haven’t received as much attention as they deserve.

As a warm up, I’ll look at some elements from HTML5 that most web developers probably are somewhat familiar with: <main>, <nav>, <article>, <section>, <aside>, and other structural, semantic elements. Even if you already use these elements, you might just learn a few new things along the way (I know I did as I researched this).

Landmarks ¶

When I first learned about HTML5 sectioning elements, I thought they were just a nice alternative to <div>. There’s more to the story than this, though.

Several of these elements define landmarks on the page. Landmarks are an accessibility feature that help identify the high-level regions of the page. The following elements define landmarks:

<main>
<nav>
<aside>
<section> — only if it has a title (aria-labelled-by, aria-label, or title attribute)
<header> — only if it’s not within one of the other landmark sections listed above
<footer> — only if it’s not within one of the other landmark sections listed above

The use of landmarks makes it easier for AT users to find their way around the page. These don’t need to be the very top level of your DOM, but they should be near the the top. Your top-level landmarks should not be nested within one another, but you can group them using <div>s if necessary for your layout. All content on your page should be inside a landmark. The most important landmarks are <main> and <nav>.

Before HTML5, you had to use the role attribute to define landmarks. For instance, an HTML 4 <div role="complementary"> can now be replaced with <aside>. It’s one way your markup can be simpler while still maintaining good accessibility practices.

When HTML5 was new, many tutorials recommended including the `role` on these elements (`

`) since screen readers hadn’t yet caught up with the new standard. The current W3C specification recommends you [don’t add the role attribute](https://www.w3.org/TR/html52/dom.html#do-not-set) for these elements, but it doesn’t hurt, especially if you want to support a broader range of browsers/screen readers.

A <form> also defines a landmark in most browser/AT combinations, but it can be nested inside the other landmarks listed above.

Headers and Footers ¶

Your page likely has a header and footer. That’s what <header> and <footer> are for. When used near the top-level of your DOM, outside any landmark elements, they denote landmarks for the page.

However, these elements aren’t restricted only to use at a high level. If you have an <article> on the page, for instance, it can have its own <header> and/or <footer>. In this case, it won’t function as a landmark, but it does provide semantic meaning in context. For example:

<article>
  <header>
    <h1>My useful blog post</h1>
    <p>Published March 5, 2018</p>
  </header>
  …
</article>

You can also add headers and footers to other elements like modals, tiles, and anywhere else it’s appropriate.

Main vs. Article vs. Section ¶

A lot of developers get tripped up by these three elements. What’s the difference between <main>, <article>, and <section>? Let’s take a look.

Main ¶

Your page should have only one <main>. This should contain the (ahem) main content of the page. There’s boilerplate stuff on most pages: the header, the navigation, maybe a sidebar or other peripheral content in one or more <aside>s. These regions of the page each belong in their own landmark. And there’s the main section, which is also a landmark.

If the page is a blog post, the <main> should contain the post title, content, and comments section. If the page is on a corporate site, the <main> should contain all the photos and informational tiles. Basically, if it’s not part of the nav, header, footer, or asides, it belongs in the <main>. (The <main> might have its own header and footer, too. See above.)

Article ¶

An <article> represents a self-contained piece of content. An article should have a heading (<h1>–<h6>) as a child element, indicating its title. A blog post, with its title, byline, and published date belong in an <article>, while any comments probably belong in a footer or aside.

The homepage of a corporate site, with photos and informational tiles, might have several <article>s, or might have none at all. The key here is “self-contained”: an <article> is something that could be removed from the page and still retain its meaning in isolation.

An article is not a landmark, so it belongs in one (probably the <main>).

Section ¶

If your content has multiple sections, you can use a <section> to contain each of these. You shouldn’t have one lone <section> on a page. A good rule of thumb is this: if the section could be an item in a table of contents, it might make sense as a <section>. An article, for instance, may consist of multiple sections.

A section is not a landmark. It belongs in one (probably the <main>). However, if you give a section a heading with an aria-label, aria-labelled-by, or title attribute, this promotes it to be a landmark. Avoid doing this if you have a large number of sections on the page, as too many landmarks can add to the noise, making them less useful as navigation tools.

Hopefully, this gives you a better idea of how some of these “bigger” HTML5 elements work. If you want to know more about landmarks and accessibility, check out the links below.

Next time, I’ll look at some HTML5 elements that are a bit more exotic.

References ¶

Introducing Sidecar

2018-01-19T13:46:41Z

A little over a year ago, my wife bought me a copy of Liquid Intelligence by Dave Arnold. It’s a book by a renowned bartender on making cocktails. I enjoyed making drinks before this, but this book really got me hooked.

In the time since, I’ve been honing my skills. And I’ve been collecting cocktail recipes. Testing them, tweaking them, and sharing them. I have a little book of notecards on a ring, full of the recipes I have tested and deemed worthy of making again. I also have a few I’ve created myself.

Now, I’ve decided to digitize that little booklet, in the form of a little webapp. And I’m making it public at sidecar.us. I’ve also added some important techniques and other information that’s essential to know when making drinks.

It works well on desktop, but I’ve focused on optimizing it for mobile, so I can pull out my phone and look up a recipe wherever I am. If you’re interested, you can install it on your phone with your mobile browser’s “Add to Home Screen” option. ~~I don’t have offline mode working quite yet~~ (Update: it works offline!), but it still works great as a PWA.

Go ahead and give it a shot. And let me know if you find a recipe I should test out.

Sidecar: A curated collection of cocktails

Meet the New Dialog Element

2018-01-11T14:22:12Z

HTML 5.2 has introduced a new <dialog> element for native modal dialog boxes. At first glance, it seems fairly straightforward (and it is), but as I’ve been playing around with it, I’ve found it has some nice features that might be easy to miss.

I’ve embedded a full working demo at the end of this article, but if you want to check it out as you read along, you can see it here.

Here is the markup for a basic dialog box:

<dialog open>Native dialog box!</dialog>

The open attribute means that the dialog is visible. Without it, the dialog is hidden until you use JavaScript to make it appear. Before any styling is added, the dialog renders as follows:

It’s absolutely positioned on the page, so it will appear in front of other content as you would expect, and is centered horizontally. By default, it’s as wide as the contents within.

Basic Operation ¶

JavaScript has a few methods and properties to make working with the <dialog> element easy. The two methods you will probably need the most are showModal() and close().

const modal = document.querySelector('dialog');

// makes modal appear (adds `open` attribute)
modal.showModal();

// hides modal (removes `open` attribute)
modal.close();

When you use showModal() to open the dialog, a backdrop is added to the page, blocking user interaction with the contents outside the modal. By default, this backdrop is fully transparent, but you can make it visible with CSS (more on that below).

Pressing Esc will close the dialog, and you can provide a close button to trigger the close() method.

There is a third method, show() that also make the modal appear but without the accompanying backdrop. The user will still be able to interact with elements that are visible outside the dialog box.

Browser Support and Polyfill ¶

Right now, <dialog> behavior is only supported in Chrome. Firefox provides default styling, but the JavaScript API is only enabled behind a flag. I suspect Firefox will enable it by default soon.

Thankfully, there is a polyfill that provides both the JavaScript behavior and a stylesheet with default styling. Install dialog-polyfill in npm to use it—or use a regular old <script> tag. It works in IE9 and up.

When using the polyfill, each dialog on the page needs to be initialized:

dialogPolyfill.registerDialog(modal);

This will not replace native behavior for browsers that have it.

Styling ¶

Opening and closing a modal is nice, but it doesn’t look very professional at first. Adding styling is as simple as styling any other element. The backdrop can be styled with the new ::backdrop pseudo-element.

dialog {
  padding: 0;
  border: 0;
  border-radius: 0.6rem;
  box-shadow: 0 0 1em black;
}

dialog::backdrop {
  /* make the backdrop a semi-transparent black */
  background-color: rgba(0, 0, 0, 0.4);
}

For older browsers using the polyfill, this pseudo-element selector will not work, however. In its place, the polyfill adds a .backdrop element immediately following the dialog. You can target it with CSS like this:

dialog + .backdrop {
  background-color: rgba(0, 0, 0, 0.4);
}

Add a little more markup to provide styling hooks. A common approach to dialog boxes is to break it up into a header, a body, and a footer:

<dialog id="demo-modal">
  <h3 class="modal-header">A native modal dialog box</h3>
  <div class="modal-body">
    <p>Finally, HTML has a native dialog box element! This is fantastic.</p>
    <p>And a polyfill makes this usable today.</p>
  </div>
  <footer class="modal-footer">
    <button id="close" type="button">close</button>
  </footer>
</dialog>

Add some CSS to this, and you can make the modal look however you want:

More control ¶

Often, we want some sort of user feedback from a dialog box. When closing a dialog, you can pass a string value to the close() method. This value is assigned to the returnValue property of the dialog DOM element, so it can be read later:

modal.close('Accepted');

console.log(modal.returnValue); // logs `Accepted`

There are also some events you can listen for. Two useful ones are close (triggered when the modal is closed) and cancel (triggered when the user presses Esc to close the modal).

One thing that seems to be missing is the ability to close the modal when the backdrop is clicked, but there is a workaround. Clicking the backdrop fires a click event with the <dialog> as the event target. And if you construct the modal such that child elements fill the entire space of the dialog, those child elements will be the target of any clicks inside the dialog. This way, you can listen for clicks on the dialog, and close it when the dialog itself is the target of the click event:

modal.addEventListener('click', (event) => {
  if (event.target === modal) {
    modal.close('cancelled');
  }
});

This isn’t perfect, but it works. Please let me know if you find a better way to detect clicks on the backdrop.

Full working demo ¶

I’ve worked a lot of stuff into the demo below. Play around with and see what else you can do with <dialog>. This includes the polyfill, so it should work in most browsers.

See the Pen <dialog> by Keith J. Grant (@keithjgrant) on CodePen.

Shindig

2018-01-02T19:38:37Z

My new site design is live! I’ve been working on this one for a while, and it just so happened to coincide with the #newwwyear activity on Twitter. I’m calling this theme Shindig.

Have a look around. I’ve got some new fonts and colors that I hope I can stick with for a while, even across projects and into new redesigns. I’ve added full page transitions everywhere. (Try it! They’re fun!) And, of course, I still support Webmention and Micropub, because I’m still loving the IndieWeb.

Update — Here’s a screenshot of the design for posterity:

OOCSS and Grid

2017-12-13T18:03:47Z

OOCSS was the first of the many CSS methodologies. Since it arrived on the scene, the industry has moved on to newer, more strongly prescriptive methodologies like SMACSS, BEM, and ITCSS. These newer approaches dominate the conventional wisdom today. But CSS grid is here now, and I find it presents some challenges to this wisdom. I think it’s time we give OOCSS a little attention again, because it has an important idea to offer in the world of CSS grid.

A major theme recently is an emphasis on modular design: a user interface broken up into small modules whose styles are encapsulated. Modules are nested one within another to construct the entire interface. This leads to markup that looks something like this:

<div class="row">
  <div class="col-4">
    <div class="card">
      <h3 class="card__title">Wash</h3>
      <p class="card__body">The whacky pilot.</p>
    </div>
  </div>
  <div class="col-4">
    <div class="card">
      <h3 class="card__title">River</h3>
      <p class="card__body">The mysterious prodigy. She kicks serious ass.</p>
    </div>
  </div>
  <div class="col-4">
    <div class="card">
      <h3 class="card__title">Jayne</h3>
      <p class="card__body">The strongman.</p>
    </div>
  </div>
</div>

You have one module responsible for layout (row and col-4 classes) and another responsible for the look of the of the items within the layout (card and card__* classes). I used the classes from the Bootstrap grid system here, but this pattern isn’t limited to bootstrap: it’s common to use one module for layout and another for visual appearance like colors, fonts, and borders.

A Limitation of CSS Grid ¶

As I work with the new CSS Grid layout, I’m finding that the conventional approach isn’t always feasible. The big restriction with grid is this: to align an element in a grid, it must be a direct child of the grid container. (This may not be a limitation forever, but for now, we need to live with it.)

Take the example above, for instance. If you were to replace the row and col-4 classes with a proper grid, you could not align the card elements directly to the grid:

<div class="grid">
  <div class="grid__item">
    <div class="card">
      <h3 class="card__title">Wash</h3>
      <p class="card__body">The whacky pilot.</p>
    </div>
  </div>
  <div class="grid__item">
    <div class="card">
      <h3 class="card__title">River</h3>
      <p class="card__body">The mysterious prodigy. She kicks serious ass.</p>
    </div>
  </div>
  <div class="grid__item">
    <div class="card">
      <h3 class="card__title">Jayne</h3>
      <p class="card__body">The strongman.</p>
    </div>
  </div>
</div>

When you do this, the grid items align to the grid, each filling their respective grid cells, but the cards do not. This is the result:

Instead of three neatly-aligned cards, the heights are all different. The grid items each have an equal height, but this is invisible to the user. The cards—and their white backgrounds—within don’t fill the entire height of those grid items. (This example is available on Codepen.)

OOCSS to the Rescue ¶

OOCSS offers a solution to this problem. Let’s blow the dust off this old book and take a fresh look at what it offers. OOCSS is much simpler than the newer CSS methodologies. It has just two rules:

First, Separate Container and Content. This means styles should not be location-dependent. A module should work no matter where you place it in the DOM. If you follow SMACSS and/or BEM, this is exactly what you’re doing with your modules.

The second rule, however, isn’t followed as often in our newer methodologies: Separate Structure and Skin. This means one class should be used to apply the structure to an element—its position and shape—while another should be used to apply its “skin”—its colors and stylistic appearance. Ideally, the same skin could be applied to a number of different “structures.”

After years of working with BEM, this second rule feels foreign. We’re used to each module (or “block,” if you prefer) doing its thing. Any given DOM element belongs only to one module. It feels dirty to apply two different modules to the same element: one for skin and another for structure. But I think this skinning approach going to be useful in the world of CSS grid.

Watch what happens in our example, when we combine the grid item “structure” with the card “skin”, thereby removing one layer of depth from the DOM:

<div class="grid">
  <div class="grid__item card">
    <h3 class="card__title">Wash</h3>
    <p class="card__body">The whacky pilot.</p>
  </div>
  <div class="grid__item card">
    <h3 class="card__title">River</h3>
    <p class="card__body">The mysterious prodigy. She kicks serious ass.</p>
  </div>
  <div class="grid__item card">
    <h3 class="card__title">Jayne</h3>
    <p class="card__body">The strongman.</p>
  </div>
</div>

Now, the card styles are applied directly to the grid items (See this example on Codepen):

It’s important with this approach to maintain a distinction between “structure” modules and “skin” modules, so you don’t accidentally mix two skins together for conflicting results. On the whole, that’s not too hard to do. It just takes some good old fashioned OOCSS.

Code, Not Clojure

2017-09-08T15:25:10Z

I’m going to make two declarations that might sound contradictory:

CSS is code.
CSS is not a programming language.

Many developers get these backwards.

It is code in that it requires discipline and rigor. It requires forethought, planning, and both big-picture and small-picture thinking. You need to consider edge cases and strive to keep your CSS logically organized.

At the same time, it is not a programming language. It is not executed in a linear fashion. Many of the rules of software architecture do not (and should not) cleanly apply. It is meant to be global, a cross-cutting concern that uniformly addresses various circumstances wherever they appear on the page.

Too many developers try to force it into the mental model of a programming language, missing out on many of its most powerful features like the cascade and inheritance. And yet these same developers treat their CSS as an afterthought, throwing rules haphazardly onto the end of a stylesheet with little consideration for the selectors they use.

If you find yourself doing this, reverse your thinking. Don’t expect CSS to be a programming language, but do treat it like code.

Transitioning Gradients

2017-07-05T17:33:51Z

In, CSS, you can’t transition a background gradient. It sure would be nice if you could:

.gradient {
  background-image: linear-gradient(
    to right,
    hsl(211, 100%, 50%),
    hsl(179, 100%, 30%)
  );
  transition: background-image 0.5s linear;
}

.gradient:hover {
  background-image: linear-gradient(
    to bottom,
    hsl(344, 100%, 50%),
    hsl(31, 100%, 40%)
  );
}

But, no. It jumps from one gradient to the other immediately, with no smooth transition between the two. So let’s hack it!

We can achieve this effect with the help of a pseudo-element and an opacity transform instead.

First, apply one gradient to the element. Then, position its pseudo-element to fill the element and apply the second gradient to that. To transition between the two gradients, transition the opacity of the pseudo-element.

.gradient {
  position: relative;
  background-image: linear-gradient(
    to right,
    hsl(211, 100%, 50%),
    hsl(179, 100%, 30%)
  );
  z-index: 1;
}

.gradient::before {
  position: absolute;
  content: '';
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  background-image: linear-gradient(
    to bottom,
    hsl(344, 100%, 50%),
    hsl(31, 100%, 40%)
  );
  z-index: -1;
  transition: opacity 0.5s linear;
  opacity: 0;
}

.gradient:hover::before {
  opacity: 1;
}

The pseudo-element is initially hidden via opacity: 0. On hover, that transitions to an opacity: 1. This produces the illusion of the main gradient transitioning to the pseudo-element’s gradient. It also takes a little bit of z-index work to ensure the pseudo-element stays positioned behind the content of the main element.

This takes a fair bit of code, unfortunately. But if you need this effect, this is the best (and only) way I’ve found so far to accomplish it.

Check out the full working example:

See the Pen OgEdgN on CodePen.

Thoughts on Self-Documenting CSS

2017-06-09T17:34:24Z

One of the best programming books I’ve ever read is Clean Code by Robert C. Martin. If you have never read it, add it to your list.

Every comment represents a failure to make the code self explanatory. Robert C. Martin

In one section, Martin discusses code comments, and makes a strong argument against them. I won’t repeat all his arguments, but in short he maintains they have a tendency to fall out of date. The computer ignores them, so nothing guarantees they accurately describe what the code does. It is far better when the code itself is clear; then both the programmer and the computer are reading the same thing.

Consider the following:

// Check to see if the employee is eligible for full benefits
if ((employee.flags & HOURLY_FLAG) && (employee.age > 65)) {
  …
}

Is the comment helpful? Absolutely. But this is better:

if (employee.isEligibleForFullBenefits()) {
  …
}

The code says what it means and does what it says. Much of the time, a comment can be improved by deleting it and encapsulating meaning in well-named functions or variables. To be clear, Martin does not say comments should never be used—but you should always strive to render them unnecessary. Every comment represents a failure to do so.

What about CSS? ¶

I agree with Martin regarding comments. However, this thinking raises interesting questions when it comes to a declarative language like CSS. Declarations have to follow a strict pattern. Selectors are determined by the structure of the HTML, at least in part. You have far fewer options regarding code structure. Does this mean your CSS should have comments all over the place?

Well… maybe. We use comments different ways for a variety of reason. Let’s look at some comments, and consider what they add (or not) to the code. I’ll start with some low-hanging fruit, then move on to the less obvious stuff.

Bad: Obvious Comments ¶

In any language, obvious comments are unnecessary. The following are actual examples of comments from an earlier version of Bootstrap 3 source:

// Addresses
address {…}

Yes, that does appear to be a selector for addresses.

// Unordered and Ordered lists
ul,
ol {…}

Really?

// Blockquotes
blockquote {…}

OMG. Make it stop.

Don’t do comments like this. Delete that crap. It’s only echoing what’s already there in the code. Thankfully, most of these have been removed in newer versions of Bootstrap.

Bad: Section Separators ¶

One type of comment that’s mostly unique to CSS are section separators. This sort of thing:

/* -----------------
 * TOOLTIPS
 * ----------------- */

These things drive me nuts. Don’t get me wrong; I understand why we have them. Our stylesheets can get really long. When scrolling through a 1000 line file, you need landmarks like this to help navigate.

But here’s the thing: we don’t work in 1000 line files any more. If your project needs a stylesheet this large, it should be broken out into bite-sized partials and you should be using a preprocessor to piece them all together. You don’t need a big TOOLTIPS at the top of the file if the file is called tooltips.scss. If you feel like you need a separator comment, split the code into a new file.

Bad: Explaining the Language ¶

I’m going to pick on Bootstrap again. This is from their _tooltips.scss:

// Allow breaking very long words so they don't overflow the tooltip's bounds
word-wrap: break-word;

This is very close to the category of “obvious comments.” This comment explains what the word-wrap property does, and no more. There is another rule of code comments that says a comment should explain why, not what. This comment breaks that rule. Delete it.

There might be a fuzzy bound here in CSS, however. There are hundreds of properties, and you probably don’t know them all. If you’re using something really obscure, maybe a comment like this is okay. Maybe.

Bad: Explaining the Library ¶

Let’s look at another comment from the same Bootstrap file:

// Our parent element can be arbitrary since tooltips are by default inserted as a
// sibling of their target element. So reset our font and text properties to avoid
// inheriting weird values.
@include reset-text();
font-size: $font-size-sm;

This one is interesting. It seems to pass the “why, not what” sniff test. It explains that unexpected font properties might be inherited by this module, then uses a mixin to reset the font properties.

But upon further reflection, it’s obvious that this is the only reason the mixin exists in the first place. In fact, a search through the codebase reveals an identical comment every place this mixin is used. At the very least, this comment belongs where the mixin is defined, not each and every place it is used. You could move the comment there and cut down the number of comments cluttering the code.

However, I think even that is unnecessary: the name of the mixin provides enough information. And if it doesn’t, give it a name that does. Call it reset-inherited-font or something more explicit that makes clear not only what it does, but why you need it. This is a function call; you have total control over the name here. Use that to your advantage and make it say what it does in a way that renders the comment unnecessary.

Preprocessors are one area where CSS is most like a conventional programming language. When you have the chance, use well-named variables and mixins to make the meaning of the code obvious. This code snippet gets this right with the $font-size-sm variable: you know at a glance that the font is smaller than the main font size. You can also safely infer that this is a commonly-used font size; it is the same font size as other small text throughout the codebase.

Bad: Old Comments ¶

.dropdown-header {
  …
  white-space: nowrap; // as with > li > a
}

“as with > li > a”? What does that mean? My first assumption is that, elsewhere in the file, there is an > li > a selector and this somehow refers to that. Maybe there’s another comment there explaining the reasoning… But scanning through the file, there is no such selector. There is another nowrap under a .dropdown-item selector. Maybe that’s what this refers to? Or maybe it refers to something that has since been deleted or refactored into another file? The only way to know would be to dig through the git history.

This is an old comment. It presumably meant something at some point in time, but the code has long-since drifted from that. This gets back to one of the main reasons Robert Martin is so hard on comments: the code changes out from underneath them and they become meaningless—or worse: they lie and actively lead you in the wrong direction. When you find a comment like this, delete it. It adds nothing to the code and has in fact has wasted our time trying to make sense of it.

Sometimes OK: Meaningful Comments ¶

Here’s another block of code with several comments:

.dropdown-item {
  display: block;
  width: 100%; // For `<button>`s
  padding: $dropdown-item-padding-y $dropdown-item-padding-x;
  clear: both;
  font-weight: $font-weight-normal;
  color: $dropdown-link-color;
  text-align: inherit; // For `<button>`s
  white-space: nowrap;
  background: none; // For `<button>`s
  border: 0; // For `<button>`s
}

These comments are meaningful. They tell me that several of these properties are applied specifically to override <button> styles. These are good comments, because that is not immediately obvious.

But it’s worth asking the question: is there a way to express this in the code itself? You could move those particular declarations into a second ruleset that targets buttons specifically:

.dropdown-item {
  display: block;
  padding: $dropdown-item-padding-y $dropdown-item-padding-x;
  clear: both;
  font-weight: $font-weight-normal;
  color: $dropdown-link-color;
  white-space: nowrap;
}

button.dropdown-item {
  width: 100%;
  text-align: inherit;
  background: none;
  border: 0;
}

This is very explicit and easily understood. Unfortunately, it also raises the selector specificity. That’s a side-effect that may not be acceptable.

Instead, I think this is a strong candidate for a mixin. Refactoring to a mixin could mean cleaning up the code in several other places as well. Consider this version:

.dropdown-item {
  @include remove-button-styles;

  display: block;
  width: 100%;
  padding: $dropdown-item-padding-y $dropdown-item-padding-x;
  clear: both;
  font-weight: $font-weight-normal;
  color: $dropdown-link-color;
  white-space: nowrap;
}

It’s clear what this does without any comments, and it gives me a mixin that performs a fairly common action, so other modules elsewhere could benefit from the same change. I did keep the width: 100% here rather than moving it into the mixin, because that might cause unexpected breakages if the mixin applied that elsewhere.

Furthermore, the original ruleset had ten declarations. That’s about as long as I like to get, before I start thinking “code smell”. A mixin is a great way to shorten things up. It’s easier to get an overall feel for what this ruleset does at a glance.

Refactoring to a mixin won’t always be a preferable option, but look for it.

Good: Annotate Obscure Bugfixes ¶

I’ve brought the hammer down hard on comments here. But I’m not always opposed. If you’ve ever looked at the source for normalize.css, you’ll notice it’s chock-full of comments. And I’d say, most of them are great comments.

Look at this beauty:

/**
 * 1. Add the correct box sizing in Firefox.
 * 2. Show the overflow in Edge and IE.
 */
hr {
  box-sizing: content-box; /* 1 */
  height: 0; /* 1 */
  overflow: visible; /* 2 */
}

Without those comments, you would never know why those rules are there. When you code around a particular browser bug, it’s often something obscure and hard to remember. I am fully in support of comments like this. And if you examined this in the wrong browser, you might mistakenly think the rule is no longer needed and delete it.

Normalize in particular needs a lot of comments because it’s made up entirely of base styles. The selectors are all type selectors and attribute selectors. There are no classnames in sight, because they aren’t naming and styling classnames, so self-documentation is more difficult.

Here’s another comment from Bootstrap:

/* Chrome (OSX) fix for https://github.com/twbs/bootstrap/issues/11245 */
select {
  background: #fff !important;
}

A url to an issue on Github! That’s helpful. It tells me, without even following the link, that this was a bug, and it may have been hard to track down. If I need to go read up on it, I can do so and get all the dirty details. And best of all, it hasn’t cluttered up the code with a lengthy paragraph that attempts to summarize the full issue. It gives the browser (and OS) info I need, and tells me where I can find out more. Alternately, if you use a private issue tracker like JIRA, you can put just an associated ticket number in the comment.

You don’t need to do this to every bug you fix. But if it’s not obvious, and especially if it’s related to a browser quirk, go for it.

Good: Mandatory Comments ¶

Some tools like KSS build a styleguide from comments in your CSS:

/*
Alerts

An alert box requires a contextual class to specify its importance.

Markup:
<div class="alert ">
  Take note of this important alert message.
</div>

alert-success   - Something good or successful
alert-info      - Something worth noting, but not super important
alert-warning   - Something to note, may require attention
alert-danger    - Something important. Usually signifies an error.

Styleguide Alerts
*/

This is not just a comment; it is code. It is parsed by KSS and used to generate HTML output. It is part of your documentation. And, I would say, this is better than a separate hand-build HTML file, because it is co-located in the same file and more likely to stay in sync with the code.

Another type of mandatory comments are licenses. When you use a third-party library with a license in a comment, you typically need to include that.

When I pull out Robert Martin quotes about comments, it tends to get a reaction. I don’t do it to be contrary. I do it because I believe in straightforward code that’s easy to understand quickly. If you’re littering your code with comments, be sure it’s not because you’re doing exactly the opposite.

Memorizing Alignment Properties

2017-05-05T13:44:55Z

Do you often find yourself looking up a Flexbox cheat sheet? Wish you could just commit all those properties to memory and be done with it? Here’s how I memorized them.

Learn “flex” ¶

If you’ve worked with flexbox much, you might already have this one committed to memory. The flex property is itself shorthand for three other properties: flex-grow, flex-shrink, and flex-basis. But most of the time, the shorthand is all you need (and is even preferable).

If you’re not familiar with this shorthand yet, learn it first. Learn only it. Don’t worry about any of the rest until you get this down.

Justify = horizontal ¶

In Microsoft Word, if you “justify” text, you control how the text is spaced out horizontally. It spaces to be flush against the left and right sides.

In the same way, justify-content is used on a flex container to control how its flex items are spaced horizontally.

Align = vertical ¶

You know there’s a vertical-align property, right? Maybe it didn’t ever do what you expected it do, but you know it’s there. The same way, the align-* properties control vertical alignment.

align-content controls how the rows of flex items align vertically within the flex container. (This generally only applies when you have flex-wrap enabled.)
align-items controls how the flex items align themselves vertically within each row.
align-self on a single flex item controls how that item is aligned vertically within a row, overriding its parent’s align-items setting.

One caveat ¶

If you can remember this rule, you’ll have a lot more of flexbox ready from memory. Note that these swap if you change the flex direction to “column” or “column reverse”. Technically speaking, justify-content spaces along the main axis, and align-* properties space along the cross axis. But learn the default behavior, as it is the most common scenario; and know that rotating these axes changes it.

As a bonus, these properties also apply to CSS Grid as well. Grid also brings in a justify-items and justify-self property to fill out the set. These work much like their align-* counterparts, but on the horizontal plane.

What Grid Can Do That Tables Can’t

2017-04-12T15:52:15Z

There’s a kind of narrative out there that’s basically, “Silly CSS wonks: first they tell us tables are bad, now they give us grid.” Nevermind that this is completely ignorant of the original argument against tables for layout (tables were never bad for layout because of the way they looked on screen; they were bad because of what they did to your markup).

It’s true that grid looks a lot like tables at first glance. But it’s also worth noting the features grid provides that cannot be accomplished using tables. Here are just a few:

Overlapping cells
Empty cells, without a bunch of empty tags
Size columns (or rows!) in proportion to one another
Complex alignment of contents within a cell
Specify a flexible range of acceptable sizes for columns & rows
Provide a full definition of responsive behavior, often without any media queries

Don’t QWOP Your Way Through CSS

2017-04-07T19:45:07Z

QWOP, if you haven’t played it, is a ridiculous running game. Instead of pressing, say, the right arrow key to run, you must control each of the runner’s muscles independently. Pressing the keys Q, W, O, and P will each extend one leg or bend one knee. Coordinating them all is incredibly difficult, and you are usually lucky if you can make a full stride before falling on your head.

This is also how a lot of developers treat CSS. Instead of thinking about constructing a robust system, they focus on only one specific part of the desired result. Instead of asking, “How do I run?”, they ask, “How do I flex my knee?” I can teach you how to flex your knee, but if QWOP shows us anything, that knowledge might actually make running more difficult.

CSS does a lot of work for you, if you will let it. Normal document flow ensures things all fit together on the page; this is why you should be judicious with positioning that breaks out of document flow. CSS automatically sizes your elements to contain their text; this is why you should avoid explicitly setting height. Relative units allow you to define one value in terms of another so they will respond together if the context changes; this is why I sometimes frown on pixel units. Margins collapse so that paragraphs stack with the correct spacing. Certain properties inherit down the DOM tree so you don’t have to specify a font for every single element.

You can get down to the “bare metal” in CSS, if you want. You can specify absolute positions for everything and set explicit heights and define every single value in pixels and override inheritance. But in the end, this will make more work for yourself and unearth edge cases you didn’t think about.

The next time you find yourself asking something like, “How do I vertically center this?”, take a step back. Are you having trouble because you set the height on something? Why did you set a height? What are you actually trying to achieve? Instead of focusing on a specific metric, think about the system as a whole: perhaps you want several items to all have the same height. Now, the problem is defined in terms of some desired system behavior. Solve for that: flexbox or grid can align multiple elements with the same height (they can also center the contents within, too).

The automatic behaviors of CSS aren’t always apparent if you aren’t familiar with them. They can result in weird outcomes, and you will be frustrated by them. So, I think, the first tendency is to find a way to turn off this “help.” Don’t.

Trust CSS; it does good things for you if you let it. Learn how to solve for system behaviors. Unless you like running by pressing Q, W, O, and P.

CSS is Not Broken

2017-03-24T18:15:34Z

Coding in any language is hard before you spend time mastering it. Imagine what your JavaScript would look like if you never took the time to learn about OOP or functional programming principles? Just because you expect CSS to be easy, doesn’t mean the language is broken when you find it is not.

A lot of people have gone on about how horrible JavaScript is. JavaScript is not horrible. It is an incredible language. It has a few odd quirks, just as CSS does. But if you take the time to actually understand these quirks, you will reap huge reward.

You cannot be proficient in JavaScript until you understand coercion, prototypal inheritance, and asyncronous flow control. Likewise, in CSS, you have to understand the cascade, inheritance, and the box model. Once you have those down, take a deeper look at the various layout methods. Do you know what stacking contexts and block formatting contexts are? Do you know why setting a height on an element leads to problems and how to accomplish what you need without doing so?

CSS is hard. But this is not because the language is faulty. Rather, the difficulty lies in what the language seeks to accomplish. I’ve heard many developers say they wish they could “throw out CSS and start over with something better.” I think this betrays a fundamental misunderstanding of the purpose of the language:

When you code CSS, you’re writing abstract rules to take *unknown* content and organize it in an *unknown* medium. That shit is hard.
— keith•j•grant (@keithjgrant) March 17, 2017

Furthermore, CSS isn’t just code, it’s also part of the design. A vital concern of CSS is consistency. You should want “global” styles: colors and spacing should be consistent throughout your application. Similar components need to look similar. Your buttons should all be consistently sized and your box shadows or border radiuses should not be ad-hoc.

I find it ironic that developers who bemoan the “global” nature of CSS are usually the ones who run into specificity problems because they unnecessarily scope their styles to particular parts of a particular page. When you have selectors like #directory .sorted .sidebar :nth-child(2) button, your problem isn’t that CSS is global. Your CSS isn’t global enough!

The next thing you know, you find yourself using !important to correct specificity problems. This is a red flag that you need to stop and learn the cascade. You can use !important to sweep specificity problems under the rug once. But you will soon need it a second time, at which point you will face the same specificity problem all over again.

Design your styles so they can be reused, anywhere in the app. Learn SMACSS and BEM. And don’t stop because you understand the “naming system”—these methodologies are about far more than double-underscores and double-hyphens. They are about code organization, reuse, and refactoring. They are the solution to dead code elimination. They offer ways to utilize the cascade instead of fearing it. They allow you to know precisely where in your code you can find a certain set of styles.

CSS isn’t broken. But it does require study and skill. It does require careful thought. As with anything in programming, you can make a mess of the code. Sure, blaming the language is the easy way out. But when your JavaScript is confusing and buggy, you know it’s not the language’s fault.

More thoughts on CSS in JS

2017-03-20T19:07:49Z

At a previous job, I was brought in to a team of Java devs to provide a little JS support. They had been using something called PrimeFaces, basically a bunch of front-end components you drop into JSF pages. Working with it was horrid.

In short, these devs knew nothing about JavaScript or the front-end, but this tool let them sort of hack a UI together. It abstracted away all the tools needed for really working in the front end. For me, someone adept in JavaScript, working with PrimeFaces was like trying to code without a keyboard.

I’ve also had to work on projects coded in ExtJS. These feel about the same way: although you are technically editing a JS file, you aren’t really programming “in JavaScript.” Instead, you are basically coding via configuration. Actual understanding of JavaScript doesn’t help you much.

To me, CSS in JS feels the same way. It feels like a tool so a bunch of JavaScript devs can kinda-sorta hack together styles without actually having to write CSS. Except the syntax is more clunky and you have taken away the cascade. (And, yet, surprise! You still need to learn the most complicated parts of CSS.)

Now I’ll be fair, CSS in JS libraries typically provide a much thinner buffer between you and the actual CSS when compared to PrimeFaces. But still… it’s an abstraction layer. It gives the illusion of writing styles in perfect isolation, but inheritance still takes place and can interfere. It gets between me and the code I want actual control over.

I know what I’m doing when I code CSS. I want the cascade in many instances; removing it feels crippling. I won’t deny CSS in JS offers some benefits. But they are benefits I am not convinced I need at a cost I am not sure I want to pay.

I won’t say it’s the wrong choice for everyone. Some folks who really do grok CSS are in favor of it. Sometimes ExtJS is the right choice (don’t quote me on that). But dang, please know it’s a compromise that someone might have to clean up down the road.

A better approach to CSS aspect ratios

2017-03-14T14:12:43Z

There’s an old hack for creating elements with a fixed aspect ratio that involves using a percentage-based padding. You may be familiar with it. It looks something like this:

.tile {
  height: 0;
  overflow: hidden;
  padding-bottom: 25%;
  background-color: bisque;
}

The element is forced to have no height, then its bottom padding is set to the actual desired height. This produces an element something like this:

4:1 aspect ratio

This works because of a peculiar quirk of padding: Any padding specified in percent computes to a percentage of the element’s width—even if it is a top or bottom padding. (The same is true for margin as well.) This is a bit counter-intuitive, but it comes in handy. I think the original reasoning was so you could declare something like padding: 5% and get an equal padding on all four sides of the element, regardless of its shape.

Of course, this approach has a problem: overflow is cut off:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam laoreet tellus ut erat egestas vestibulum. Aliquam erat volutpat. Fusce ut nibh quis lectus fermentum aliquet. Suspendisse potenti.

This approach creates fixed height of the element, which in CSS is an anti-pattern. For this reason, I’ve always felt dirty using it.

Dealing with overflow ¶

A while back, I stumbled across an approach that is similar, but prevents the overflow problem. Instead of setting our element’s height, we can set the height on a floated ::before pseudo-element. Watch what happens when we do this:

.tile {
  background-color: darkseagreen;
}
.tile::before {
  content: '';
  float: left;
  padding-bottom: 25%;
}
.tile::after {
  clear: left;
  content: ' ';
  display: table;
}

The ::after is just a familiar clearfix. This produces a very similar result:

4:1 aspect ratio

However, the element will still grow to contain overflow if necessary:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam laoreet tellus ut erat egestas vestibulum. Aliquam erat volutpat. Fusce ut nibh quis lectus fermentum aliquet. Suspendisse potenti.

How it works ¶

The trick is, instead of explicitly controlling (and thus limiting) the height of the element, we set a known height on the floated pseudo element. By using a padding-based percentage, this will be a ratio of the element’s width. We float it left and leave it empty, producing a width of zero. Here is the floated element, with a black outline added:

Floated pseudo element provides a min height to the element.

Then, in the ::after pseudo-element, we clear the float, forcing the element to grow to contain the floated ::before. Since the float has a width of 0, it doesn’t interfere with the content layout in any way. And when the content extends below the bottom of the float, the box simply grows naturally to contain it:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam laoreet tellus ut erat egestas vestibulum. Aliquam erat volutpat. Fusce ut nibh quis lectus fermentum aliquet. Suspendisse potenti.

It’s Both

2017-01-27T13:54:57Z

I’m a JavaScript developer. I have experience working in large web applications and dealing with the problems that come from scaling up. I studied Computer Science in college and love solving problems of software architecture.

I’m also (in case you somehow missed it) a “CSS Guy”. I learned CSS during its infancy in the mid-nineties and have worked to stay up to speed ever since.

When I look out at the industry today, it kind of feels like watching parents fight. And I’ll admit it, I’ve contributed to the problem. But the more I watch this unfold, the more I feel like we have two camps, talking right past one another, and no meeting in the middle. Both are missing the points the other is trying to make. So I’m shifting my stance:

We’re both right ¶

Writing SPAs is complicated business. The page isn’t just a static document you can slap some styles on and call it a day. What if you need to load content dynamically, and it results in unpredictable source order of your CSS? How do you know if styles for deeply-nested dependencies are already loaded? How do you know when you can delete code?

These are hard problems. You can’t answer them by simply saying “learn CSS”. I personally may not like CSS-in-JS or inline styles, but I do realize they are important experiments. They are quests for answers to these issues. I don’t think they are the ultimate solution. That’s okay. Maybe they will get us to it.

On the other hand, we have whole teams of developers who fundamentally don’t grok CSS. They code up their JavaScript components, then stick the styles they want into the project stylesheet. These may be great developers when it comes to traditional programming languages, but they get really frustrated with layout problems or specificity battles. Compound this with “too many cooks in the kitchen” and you have a real mess.

We have sixty-plus years of industry experience about architecting code in traditional programming languages, but we’ve struggled to apply this stuff to CSS. Only in the last seven years or so have we started to figure out best practices for the language, and we are not doing a great job of disseminating them. When we teach that BEM is a “naming convention” rather emphasize it is a way to architect systems with modular code, thousands of developers miss the point entirely. This only drives them further away because the so-called “best practices” don’t work when they aren’t actually followed.

They don’t understand that BEM is about architecture, not simply namespacing. They don’t see the value of using a pattern library, of centralizing your CSS and imposing order on who controls the CSS rather than treating it like a garbage pile where any random dev can just add haphazard code.

When JavaScript-centric developers hear, “putting your CSS in JavaScript makes it easier” they clamor to get on board. But this must be made absolutely clear: you still need to understand CSS. If you don’t know what a block formatting context is, CSS in JS will not fix your layout issues. If you don’t understand stacking contexts, you will continue to struggle with futile z-index battles. If you don’t learn custom properties or the difference between cascade and inheritance or margin collapsing, these experiments will not really solve the fundamental problem: most teams don’t know how to develop with CSS.

Always bet on JavaScript the Open Web ¶

So, yes. Hire engineers who know how to deal with system architecture. But also hire someone exclusively for their CSS skills. Put smart people on your team from both camps. Let them work together to solve these problems. Because your problems are unique and your solutions might not look like someone else’s.

I can say with confidence that CSS in JS will pass. In our industry, something new always comes along. The saying is, “Always bet on JavaScript” — but this isn’t quite right. When it’s JavaScript vs Java or Ruby, yes, bet on JS. JavaScript wins not because it is inherently better; it wins because it is part of the open web platform.

The open web platform always wins. And CSS is part of that platform. It’s not CSS versus JS. It’s CSS plus JS. The platform will evolve. And the platform will win.

Hello, World Wide IndieWeb!

2017-01-23T20:34:37Z

It’s a new year, so it’s time for a new design! Only this time, the update is more than just a CSS revamp. This year, I join the “IndieWeb”. If you don’t know what that is, read on.

Let me introduce you to the newest social network: it’s called the World Wide Web and it’s more than 25 years old.

Social networks bother me. I don’t mean the privacy issues or mysterious sorting algorithms. Apart from these things, walled gardens are antithetical to the open standards that made the web successful in the first place. I can’t follow you on Facebook unless I have a Facebook account. You can’t like or reply to my tweet unless you join Twitter. The internet was founded on principles of decentralization, yet here we are, consolidating the bulk of our online activity into a small handful of sites we don’t control.

I have long wanted an open protocol to bring the key features of social networks (liking, commenting, sharing, following) out into the open web. Now, finally, I have discovered that a fair bit of progress has been made in this regard. The W3C now has a Social Web working group, and their specifications are stabilizing and have even been adopted by many.

This redesign is my first step toward adopting these standards myself. I’ve completed phase one out of two (or possibly three) steps I want to take. Each one corresponds to a key piece of the “Social Web” protocols.

Phase I: Webmentions ¶

This site now supports comments: you may comment on my blog by writing about it on your own blog. Then your blog should send mine a webmention. These are similar to the old “pingbacks”, except they use a simpler format and they are an official W3C Recommendation. (If your site doesn’t support webmentions, I’ve provided a little form where you can submit this yourself).

They basically work like this: I write you a post. Then you write a post, with metadata indicating it is a response to my post. Your blog then tells my blog that you replied and provides the URL. If I want, I can then link to your reply. Both our posts now link to each other, and we each own our own data!

And because we are still beholden to some social networks, there is a service called brid.gy that will find links to my post (and replies to those links) on Twitter or Facebook, and let my blog know about them, so I can log them here as comments. We can drag the old social network silos out into the open web!

Phase II: MicroPub ¶

My next goal will be to incorporate something called MicroPub. This basically means I can write short posts (say, 140 characters), called Notes. I will use these notes to post replies to articles on the web. I can also syndicate these to twitter, where webmentions and brid.gy will help me track any conversation that happens there and link to it from my blog.

This involves a few more moving parts than phase I, but thankfully, most of the tools for this already exist as services online. I just need to wire things up and test them out.

Phase III: ActivityPub? ¶

The last piece of the puzzle for a decentralized social web is the whole subscribers/followers bit. The old concepts of RSS, PubSub, and feed readers can do this, but that model is more of a one-way publication, not a two-way street. There is a new approaches the W3C has been working on called ActivityPub that involves tracking followers and bringing more of the social network activities into this realm.

This arena isn’t as mature yet, but I’ve certainly got my eye on it.

I have high hopes for this will take us. It may take a while — a couple years, at least — but I think we will start to see more discussion happening in this arena. If you want to learn more about this stuff, checkout indieweb.org or the IndieWeb WordPress plugin. Hello, IndieWeb!

Let’s Talk About Separation of Concerns

2016-12-23T05:00:00Z

There’s been a lot of talk lately about good old Separation of Concerns — primarily in the context of React and the use of inline styles or CSS-in-JS. Advocates of these approaches argue that the language we use (be it JS, HTML, or CSS) is an arbitrary line to draw. And I would say: Yes, language is, for the most part, an arbitrary line. But that’s beside the point.

So let’s get one thing straight. This…

import styles from './tile.css';
...
render() {
  return <div className={styles.tile}>...</div>;
}

…is architectually equivalent to this:

render() {
  return <div className="tile">...</div>;
}

The latter approach, however:

requires a drastically simpler build process
is both backwards- and forwards-compatible across all frameworks
doesn’t try to pretend that those styles exist in perfect encapsulated isolation

Stop championing CSS-in-JS as some ground breaking re-thinking of Separation of Concerns. It’s not. The React component will still inherit its font face, color, and size from a parent container. It still exists on the web platform, in an HTML document, where all the rules of styles and inheritance still apply.

We can debate about class name collision, co-locating stylesheets, how styles fit into system archetecture, and other related topics. But let’s take this one off the table, because it’s a straw man argument.

Your Team Needs a UX Engineer

2016-10-02T05:00:00Z

Recently, after I mentioned that I was the only one on my team that writes the CSS, someone replied, “You’re lucky”.

It stuck with me, and I’ve been thinking about it since. The thing is, it’s not luck. It was a deliberate decision made early when the team was first put together. And I think the rest of the developers on my team would think themselves lucky for not having to touch the CSS. It is more valuable for us to have one person on the team who specializes in that.

We need to rethink something about the way we build our web development teams. We spend a lot of effort hiring good programmers, but for the most part, they are interchangeable. We make sure that everyone we hire knows the fundamentals of software engineering, architecture, and the primary language the team uses. And then we assume.

If a developer has a solid grasp on JavaScript, we think, surely they know CSS. Surely they know how to deal with accessibility. Surely they have a grasp on how and when to use various HTML elements and aria-* properties. These are small beans compared to the code. And in many ways, they are.

But, of course, this isn’t how it plays out. Because we hire purely for the bigger task, CSS and accessibility always remain an afterthought. On most teams, nobody really knows what they are doing when it comes to these topics. They team stumbles along, joking amongst themselves how horrible CSS is.

We need to fix this. On teams larger than four or five developers, I think we can: one person per team should be hired explicitly for these tasks. Most of the team will still be focused on JavaScript (or Python or Java). But one person—call them a “CSS Developer” or “UX Engineer”—should be hired specifically for these “afterthought” concerns.

Is a developer building a new component and needs some styles? The UX Engineer writes that CSS. The UX Engineer gives a snippet of HTML to the developer for them to incorporate into the component. The UX engineer ensures the correct semantics and can come alongside the developer to ensure keyboard navigation works. The UX Engineer maintains a pattern library for the team to use as a reference to find existing styles.

This UX Engineer serves an important role, but furthermore, they allow the other developer to offload some work. The developer can focus on the “bigger concern” of getting the business logic right and ensuring the app works correctly. This improves the developer’s productivity.

This is how things work on my team. I am effectively the UX Engineer, and I think everyone enjoys the process more because of it. In our case, we stumbled upon this setup—I was originally hired for my JavaScript skills. As always, the CSS was an afterthought; I just happened to be good at it, so we settled into the current arrangement.

Don’t wait for your team to stumble into this. Set it up intentionally. Hire a UX Engineer.

CSS in Depth

2016-08-24T05:00:00Z

My book is finally for sale! The MEAP is available on Manning’s website. The first three chapters are available now, and others will be rolling out steadily (I’ve actually already completed drafts of six chapters at this point).

Until the end of August, you can use my code mlgrant2 for 50% off. Follow @CSSinDepth on Twitter for updates.

Save Scoped CSS

2016-06-09T05:00:00Z

Update June 23, 2016: The editor’s draft has been updated again. It looks like @scope is gone for good, so this post is now a moot point. The way forward now lies in the Shadow DOM.

About a year ago, I wrote about a promising feature of CSS, scoping. I love the idea of this feature, and I think it could be one of the most important changes in the near future of CSS. You know all those complaints about “in CSS everything is global"? This feature is the answer.

I became excited recently when I noticed some movement in the W3C concerning this spec. So I took a look at what was going on. I found some good news, and I found some bad news.

The good news ¶

The editor’s draft of the specification has recently been updated. The changes, I think, significantly improve the viability of the feature. They more closely resemble the hypothetical changes I wished for last year. Most importantly, scoped styles would no longer need to be defined inline in the HTML document; you can define scoped styles in an external stylesheet.

The proposed syntax looks like this, using a new @scope at-rule:

@scope .foo-module {
  p {
    color: blue;
  }
}

@scope .bar-module {
  p {
    color: red;
  }
}

Each scope is defined with a selector (.foo-module, .bar-module). This establishes a new scope for matched elements and their descendants. Inside the braces that follow, you can specify any styles you wish. These styles are then applied only to the elements belonging to that scope.

According to the rules of the cascade, rules applied to an inner scope will override those applied to an outer scope, regardless of their selector specificity. This is precisely the behavior CSS-in-JS and/or CSS Modules users want! And yes, this definition is in the current Candidate Recommendation of the spec.

This means, given the example above, a foo-module inside a bar-module will have blue text; and a bar-module inside a foo-module will have red text. This could solve so many developer frustrations.

The bad news ¶

I got excited when I saw these changes, so I started reading more on what prompted them. I discovered that it is a sort of last-ditch effort to salvage the spec. The problem? Browser vendors have shown no interest in implementing it. Firefox has long-since implemented the earlier version of the spec, but that’s it.

If we developers want this feature, we need to let the browser vendors know. Otherwise, it’s DOA.

So tell them, please. Follow these links, and up-vote or leave comments in support of scoped styles:

Chrome
Edge
I couldn’t find a channel for Safari. If you know where it is, please let me know and I’ll add it here.

Let’s not allow this to die.

A Quest for Interchangeable Parts

2016-02-06T05:00:00Z

This is a bolt. You may not realize it, but it is a modern marvel. It is a 150mm bolt with an M20 threading. It works in any piece of hardware that is cut with the same size and threading. It can be turned with any 30mm hex wrench. You can reach into a pile of M20-2.50 nuts, made by any manufacturer, pull any one out, and it will fit this bolt.

This is because of a key principle that made the industrial revolution possible: interchangeable parts. It took countless inventors over the course of hundreds of years to perfect the manufacturing necessary for this. Many people, such as Eli Whitney and Samuel Colt, devoted years of their lives and a great amount of resources in the quest to achieve it.

Before their efforts, everything had to be hand-made for the particular project. Every gun was uniquely crafted. Every piece of rigging on a ship. And if a part broke, you couldn’t just buy a replacement; one had to be hand-made to fit the parts it integrated with… or the entire device had to be replaced.

Learn from history ¶

This is a tweet.

You may not realize it, but it is stuck in the pre-industrial age. Because it is not an interchangeable part. It doesn’t fit into a Facebook wall, or onto a YouTube page.

Sure, it’s almost interchangeable. You can post a link to its url in most places, or a screenshot of the tweet. Or you can copy the text and give attribution. But it does not interoperate with other social networks. You can’t retweet it or like it from anywhere but a limited number of places: an embedded tweet (put there by a script provided by Twitter) or a third-party app that uses Twitter’s API. This is because Twitter has a vested interest in keeping a tight reign on where and how a tweet can, and cannot, be used.

Our digital world is full of these semi-interchangeable parts. You can buy an album from iTunes or Amazon or Google Play. However, if you assemble your music collection using two or more of these, you have to jump through some hoops to keep it all in one place and to sync it to your phone.

You can subscribe to Hulu and Netflix and Amazon Prime, but you can’t just tune into them on any TV: you need to use something like a Roku that brings them all together. Nothing is standardized.

A better way ¶

Netflix has to build an app for iOS, an app for Android, an app for Roku and Apple TV and the Amazon Fire Stick. They do all this just so users of those devices can tune in to their service. What if, instead, they just produced their content in a single, standardized web format. Imagine if HBO and Hulu broadcast in the same format. Imagine if subscribers merely had to tune in their TVs to the right “channel” watch. No Apple TV or Roku necessary. Like broadcast television.

iTunes keeps an iron grip on the whole pipeline of your music: the financial transaction, the download, the files on your hard drive, the sync to your Apple device. What if, instead, iTunes or Amazon were just a store, and they all provided music in the same format for you to save wherever you choose, and sync however you choose. Like it a CD.

What if, instead of “following” your friend Joseph on Twitter, you could just follow Joseph. He could tweet on Twitter or post to Facebook and you would get it, on the social network of your choosing, that offers the controls and options you like. There would be a single, common digital format for a social media post, that worked on all networks. You could be on Twitter or Google Plus, and read his updates, wherever they came from. Like email.

An open web ¶

Unlike the centuries-long quest for interchangeable parts in manufacturing, there is nothing technically holding us back from this. We might need to hash out what these standards look like, but that is relatively easy. The forces holding us back are more capitalistic—or rather, monopolistic. Because the world of open standards I just described would be a much more open, free market: a level playing field where far more companies could innovate and compete, rather than just a small handful of big players. It would be a world where users had more choices and more control over their media, and where they didn’t have to put up with so much headache.

Has the digital age made life easier? Absolutely. I don’t want to go back to broadcast television or CDs. While email still serves a purpose, it’s different than that of social media.

But the digital age has still not matured. We need interchangeable parts. It will take some concerted effort to break through the barriers holding us back. I admit don’t know precisely how to do that. But, just as we pushed through the difficulties that held back physical manufacturing in centuries past and ushered in the industrial revolution, we can break through these, and usher in a new digital revolution. The modern digital life is still more complicated than it need be.

The Internet may be the first true write-once-run-anywhere platform, but as long as these industries are shackled by proprietary lock-in, these parts of the web aren’t open. An open web requires interchangeable parts.

Width and Absolute Positioning

2016-01-30T05:00:00Z

I recently came across this question on Twitter:

What's the diff on a position:absolute el btw {top:0;right:0;bottom:0;left:0;} and {top:0;left:0;height:100%;width:100%;} ?
— Karl Swedberg (@kswedberg) January 28, 2016

“That’s easy”, I thought. “They often seem the same in practice, but width and height are based on the parent (or nearest block-level ancestor). Top, right, bottom, and left are based on the nearest positioned ancestor. Those aren’t necessarily the same element.”

Shows what I know: my quick mockup to illustrate the difference proved me wrong.

On first pass, top: 0; right: 0; bottom: 0; left: 0; and top: 0; left: 0; width: 100%; height: 100%; are equivalent. Of course, we always treat them as equivalent, because in most real-world cases, the nearest positioned ancestor is the nearest block-level element (usually the parent). But my codepen showed me an absolutely positioned element whose width and height are derived from the positioned ancestor, not the immediate container.

In retrospect, this makes a certain kind of sense, because the absolutely positioned element is removed from the normal flow. It’s then “contained” by the positioned ancestor.

So, the two scenarios are effectively the same. But a quick look at the spec made it clear that padding and margin would weigh in. So it might worth a little experimenting to see what we get.

Experimenting ¶

So here’s the basic scenario I set up. Three elements: one relatively positioned as the anchor for the absolute positioning, one to serve as the parent, and then the child, which will be absolutely positioned. For better visibility, the positioned container has a faint background color, the parent has a purple border, and the child has a medium gray background (transparent, so the others will show through).

<div class="positioned">
  <div class="parent">
    <div class="child"></div>
  </div>
</div>

.positioned {
  position: relative;
  background-color: rgba(0, 0, 255, 0.1);
}

.parent {
  width: 200px;
  min-height: 200px;
  border: 2px solid #936;
}

.child {
  position: absolute;
  background-color: rgba(0, 0, 0, 0.4);
}

Then, we’ll play around with the child’s properties to see what happens. We’ll create two variations. First, one with top, right, bottom, and left all set to zero. And second, one with a top and left of zero, and a width and height of 100%.

.child {
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
}

.child {
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
}

The two children appear identical. They overflow outside the parent, and fill the size of the positioned container. Visually, you can’t tell the difference between the container and the child. Let’s add some padding to the child and see what happens…

  .child {
    padding: 1em;
  }

…nothing. Note, I’ve got box-sizing: border-box set globally on the page. Let’s turn that off:

  .child {
    box-sizing: content-box;
    padding: 1em;
  }

The padding still has no effect on the size of the first variation. But it adds to the width and height in the second; that child now overflows the positioned container. That makes sense. So there’s a key difference here, if you don’t have a global box-sizing fix in place.

Now let’s see what a margin does:

  .child {
    margin: 1em;
  }

Now that was unexpected, at least to me. With right: 0; bottom: 0, the margin is contained inside the positioned descendant; they will shrink the size of the element.

With width: 100%; height: 100%, the top and left margins are contained, but the element is shifted, maintaining its original size. The right and bottom margins are then added outside the whole structure.

What’s interesting is that in all these scenarios, the parent element doesn’t affect the shape of the child element at all—Though it does provide the height to the positioned container.

Take-away ¶

So what does this mean? It seems to me that top: 0; right: 0; bottom: 0; left: 0 is probably the one to favor, as it’s a little more predictable, unless you have a particular reason to use height or width instead.

Simply White

2016-01-27T05:00:00Z

Benjamin Moore has declared the Color of the Year for 2016 to be “simply white”. We have reached peak minimalism, y’all.

So I’m steering into the skid. Here’s my new design.

CSS First

2015-08-01T15:00:00Z

In 2003, the CSS Zen Garden went live, and it spearheaded a revolution. At the time, many web designers were still using tables for layouts, and the battle for semantic markup was underway. The Zen Garden showed the world, in beautiful color, what CSS could do. By changing the CSS, you could make the website retro, postmodern, abstract, or elegant. You could move the sidebar to the left, the right, the top, or the bottom of the page. You could do anything with the font, the colors, the shapes and sizes of the elements on the screen. No changes to the HTML were necessary.

What we didn’t realize at the time was how much of a disservice this was for the next generation of designers and developers.

Don’t get me wrong, the CSS Zen Garden was an essential part of moving the web forward. Without it, we might have seen table-based designs for much longer than we did. It did a lot of good for us, but it left us with one bad habit: it taught us to write HTML (or take existing HTML), and then write CSS for it. But this is wrong. The HTML shouldn’t come first; the CSS should.

CSS: your first dependency ¶

Many web developers still try to think about how to write their HTML so that it can be sensibly targeted by their CSS. Instead, we aught to be writing selectors that can be used easily by HTML. The HTML depends upon the CSS, not the other way around.

CSS is the first dependency of your website or web application. The HTML expects it to be there; the JavaScript expects it to be there. Certain things are supposed to happen when they add or remove classes. CSS should be modular enough that it can be reused on a number of different web pages, and ideally even across different applications if needed. If you are using a modern practice like SMACSS or BEM, this thinking is probably not new to you, but it’s worth unpacking.

Let’s look at a little CSS. The familiar media object will do:

.media {
  margin: 10px 0;
}
.media::after {
  /* clearfix */
  display: block;
  content: ' ';
  clear: both;
}

.media-object {
  float: left;
  margin-right: 10px;
}

.media-body {
  overflow: hidden;
}

This is designed for the media class to go on a container div, and the media-object and media-body to go on two child elements. Most likely these will be an <img> and a <div>, but you could probably change that up a bit. This can be placed inside other modules, and other modules can be placed inside of this module’s media-body.

These class names and small bit of implied DOM structure dictate an API contract with the HTML and JavaScript. This way, it’s reusable. You can put as many, or as few, of these on the page as you need, and the CSS never needs to change. Other modules might come with various states: classes like is-open, is-active. JavaScript can toggle them and allow the CSS to show, hide, highlight, or do whatever else it needs to do. It’s all part of the API.

This is the secret to separating the concerns of CSS from those of HTML and JavaScript. The CSS specifies the rules, and it’s up to the other two to follow them. It’s a one-way contract.

We tried for years to do it the other way around, and that’s what got us into trouble. When you approach web development HTML first, the HTML inevitably becomes coupled with the CSS. The CSS Zen Garden model works… until the HTML changes. And in in the real world, the HTML changes all the time. If the CSS is based on that HTML, the CSS will have to change with it.

Instead, by developing the CSS first, in a way that is modular, we can apply it again and again to changing HTML, without needing to make changes upstream. The HTML just has to follow the conventions laid out by the API.

To do this, we need to develop our CSS as if it is for a third party, similar to Bootstrap and other CSS frameworks. If your project (or your team) is moderate to large size, this will begin to necessitate two important features for our CSS: it should be well documented, and it should be versioned.

Documentation-driven ¶

Ugh. Documentation. The longest four-letter word in a developer’s life. Bear with me on this.

Since you are producing an API that other developers will consume, it needs to be documented. That means show each module in action so developers can skim through and find the pieces they need. Publish static HTML pages that organizes them in a reasonable way. Show the variants available. Add some bare-bones JavaScript to illustrate changing states and transition effects. Your CSS will eat its own dog food before you ever use it in your app.

At my job, we document our styles using Jade, and have some mixins that duplicate portions of markup: once to render on the page, and the second time to print the markup into a <code> tag for reading. But for smaller projects, this may not be necessary; browser dev tools make it easy enough for a developer look under the covers at any of your examples.

This documentation serves double-duty: it also becomes your unit tests. Every module you build, and the variations thereof, are rendered into a page. Package your documentation with your CSS. Write the documentation for a module as you write the CSS. See it in action during development.

If you need to verify multiple permutations of module states or test how various modules work together, add appendices to your documentation to do these things, where you won’t bog down developers who are referring to the main docs. Our documentation at work has a series of fully-mocked up static pages (to ensure everything works together as expected) and several “test” pages where our grid system is put through paces and various table styles are mixed and matched in numerous ways to ensure they all work well together.

Unit tests in CSS are notoriously difficult to do. Some people use tools that take screenshots and compare for changes, but this is prone to all sorts of false positives. Some rely on linting, but that only gets you so far. If you write documentation as you develop, it serves the same purpose. Even better, eyes are on your tests, because developers and content editors will refer to it regularly.

Versioned ¶

Second, version your styles using semver. Your HTML is opting-in to your CSS. You can’t just change things out from underneath it. Deploy your styles to a url with the version in the path, so you always know what you’re getting. Alternately, package your styles in a way that your project can import them at a certain version, whether an npm module or Ruby gem or similar.

Dead code elimination is a tough problem with CSS. If your CSS is versioned, you can deprecate and delete features with much lower risk.

Publish a changelog. This can make developers aware of new features, as well as give them a heads up when you deprecate something.

Write the CSS in a clean-room ¶

CSS first doesn’t mean you write all of your CSS before you write any HTML or JavaScript. It applies at a finer-grained level. Each module is first built in the CSS before it can be used in the HTML. When you need styles in your app or website, your first stop should be the existing CSS documentation. Look for something that already meets your needs. Once you have built up a robust toolset of styles, you will often find you don’t need something new after all.

Only when nothing there fits your situation should you start coding new CSS. Once it’s written, and “tested” (i.e. added to the documentation), bump the version and cut a new release of the CSS.

This adds a small obstacle to adding new styles, which is intentional. It forces you to stop and think about your CSS outside the context of your particular problem, and encourages you to write a more general-use module. It also encourages developers to use existing styles as much as possible before rolling their own, which will result in a more cohesive look and feel throughout your site.

This is probably overkill for small projects. I certainly don’t jump through all these hoops for this blog. But the more your project scales up, the more essential they will become, and the more your team will benefit from them.

The API of your CSS will be much more robust as a result of this work. That API is important. The inner-workings of your CSS are easy to change. Your HTML is easy to change. But that API between them is the most important part. Making significant changes to that is costly, because everything on both sides needs to be updated accordingly. Design that API well. Design it from the viewpoint of the CSS, and then build your HTML to match.

Into the future of CSS

2015-05-30T05:00:00Z

In my last post, I laid out why I think moving our CSS into JavaScript is not a good idea. If am totally honest, however, I have to admit I brushed off the concerns Christopher Chedeaux raises in his slidedeck. The seven problems he named can be mitigated by best practices, and most of us can do just fine, because we do not often work in apps of the same scale as Facebook or Google. But that does not mean the problems aren’t worth discussion.

I may disagree with the solution proposed by the ReactJS team, but I think they are doing something very important by bringing these problems to the forefront. I shot down their ideas in my last post, so now I want to follow up with some constructive ideas.

A Way Forward ¶

We need to figure out how to solve these problems. Not just mitigate them or work around them, but full solutions that work at scale. And if the current spec does not provide the means, we should work to discover what additions to the spec can get us there.

I think our best bet is learning from JavaScript, or more specifically, CoffeeScript and Babel. Now that ES6 features are becoming supported more and more in browsers, we can see that CoffeeScript played an important role in making that happen. CoffeeScript brought new syntax and important improvements like auto bound functions (i.e. =>) and, thanks to a transpiler, made them possible even before browsers supported them. Now, some of these features have made their way into ES6 and with them, a breath of new life. Even more new features are being proposed, and we can use them today with Babel.

We already have two promising libraries, doing for CSS what Babel does for JavaScript: PostCSS and cssnext. These transpile CSS using the latest spec into compatible CSS that works in browsers today. This is huge. Things that we’ve relied on SASS and LESS for can now be done in “pure” CSS, namely variables and advanced color functions. They also include support for things like custom media queries and custom selectors. If you are not familiar with either of these libraries, they are worth reading up on.

The problem is these additions to spec are not all that exciting. Variables and color functions are nice conveniences, but they do little to solve the real difficulties we face with CSS at scale. I think, instead of emulating Babel, we need to emulate CoffeeScript. It pushed the boundaries of JS, and now, as a result, 60% of ES6 features came straight from CoffeeScript. Let’s do the same thing with CSS. Think outside the box, and dream up new features to help. PostCSS is especially good for this, because it is modular. We just need to start writing some experimental plugins.

Scoped CSS ¶

One cutting-edge feature that I think has promise is scoped css. This allows us to add a “scoped” attribute to a style tag, and those styles will only be applied to the parent element of the style tag and its descendants. For example:

<div class="outer">
  <p>Normal black text</p>
  <div class="inner">
    <style scoped>
      p {
        color: red;
      }
    </style>
    <p>Red text!</p>
  </div>
  <p>Normal black text</p>
</div>

These can be nested, and scoped elements can even be targeted in our regular stylesheet with the :scoped pseudo-class. Scoped styles override styles from a higher-up scope or the global page, regardless of selector specificity.

The spec for this was proposed in 2011, and not much has happened with it since then. Only Firefox has added support. Chrome added support behind an experimental features flag—but has since removed it. There are polyfills available, but as it is, this has not gone very far, and it’s not hard to see why. Who wants to write a bunch of CSS inline in the document? That feels more like a step backwards.

So, here’s an idea. What if we assigned a value to the scoped attribute, <style scoped=“widget”/>, and then create an at-rule to define a named scope, maybe something like this:

@scope ('widget') {
  p {
    color: red;
  }
}

This would define a set of scoped styles and assign them a scope name, then we can use that name to apply those styles to our component wherever we put it on the page. Then we could combine a PostCSS plugin with a polyfill to make it work. Again, this is just an idea. I don’t really know how well it will solve our difficulties in practice, but I would sure like to try. It sure seems to have promise at addressing nearly all of Christopher Chedeaux’s seven problems with CSS at scale.

Let’s Start Experimenting ¶

Maybe my enhanced scope idea won’t work out. Maybe someone else will come up with a better idea. Either way, I think we need to try. Perhaps there is something to be found if we augmented @namespace instead. Maybe the answer lies with the shadow DOM and web components, or something else entirely new.

My hope here is not that we come up with a postprocessor or polyfill library that makes CSS easier, though that is the first step. My hope is ultimately that we find a way to solve the problems we have, and that the best solution makes its way into the official spec, after we prove it out on production sites. Who knows? Maybe if PostCSS or cssnext keeps gaining traction, we will invent entirely new polyfills for the future that address any number of issues. JavaScript has got a lot of momentum moving forward. It’s time for CSS to do the same.

Against CSS in JS

2015-05-29T05:00:00Z

Some folks want a unified language of the web instead of CSS, HTML, and JS. It's increasingly looking like JS will just eat the other two.
— Henrik Joreteg (@HenrikJoreteg) May 28, 2015

I have long believed that pieces of our JavaScript are intimately coupled with the DOM, especially in the context of web apps. For far too long, we waved our hands and pretended we have a separation of concerns simply because our HTML is in one file and our JavaScript is in another. Not only did this avoid the problem, I think it actually made it worse, because we had to write more and more complicated code to try and abstract away this coupling.

This coupling is real, and it is unavoidable. We must bind event listeners to elements on the page. We must update elements on the page from our JavaScript. Our code must interact bidirectionally and in real-time with the elements of the DOM. If it doesn’t… then we just have static HTML. Think about it, can you just open up your HTML and change around class names or ids without breaking anything? Of course not. You have to pull up your scripts and see which of those you need to get a handle on various DOM nodes. Likewise, when you make changes to your JavaScript views, you inevitably need to make changes to the markup as well; add a class or id so you can target an element; wrap an extra div around a block so you can animate it a certain way. This is the very definition of tight coupling. You must have an intimate knowledge of both in order to safely make any substantive changes to either.

Instead, the mantra of React is to stop pretending the DOM and the JavaScript that controls it are separate concerns. Join the two, and instead, separate concerns that are actually different: the dropdown menu is separate from the list of objects; the modal dialog box is separate from the page footer. Why on earth would you put these all in the same HTML document? Obviously, you shouldn’t.

When React came out, I was more than happy to embrace their controversial claim that pieces of our DOM should live in the JavaScript—because I already knew it to be true. They are the same concern, and every attempt we have ever made at separating them has ended in disaster. Just think about the last time you had to deal with Backbone Views. It actually makes me feel sick to my stomach to think about. There was so much work for so little gain, and it was all boilerplate code to cross that barrier into DOM land.

So What About CSS? ¶

This made sense once, so, naturally, there is talk about doing the same thing with CSS. We brought our HTML (sort of) into our JavaScript and it cleaned a lot of things up, why not do it with our styles as well?

This is a really bad idea. Where, with JSX, my reaction was, “Yes, finally!”, my response here is quite the opposite. I’ve had a hard time articulating exactly why I respond this way, especially on the length-constrained and fast-paced atmosphere of Twitter, so I’m setting out now to articulate my reasons here.

Before I dive in too deep, I do want to say I have interacted some with React Native folks on Twitter regarding this. I acknowledge that their work is primarily in the realm of native applications, not in the context of the web. I think this has ramifications for their use case that I myself am not familiar with. My thoughts may be applicable to them, and they may not; I’m not well-versed in that world enough to speak to them directly. But I do hope others take note of that distinction before they clamber to repeat these practices on the web.

We Are Not Solving the Same Problem As Before ¶

The relationship between CSS and JavaScript is not like the relationship between HTML and JavaScript. With HTML, a true separation of concerns between the markup and the corresponding component code is impossible. With CSS, this separation is possible and is in fact vital to clean code organization.

Your CSS should be wholly independent from your markup (and especially independent from your JavaScript). If you find, as this stackexchange user observed—that your “commit history shows me the opposite - [you] usually edit both HTML and CSS together”—then you are doing CSS wrong. CSS should not depend on the markup; the markup should depend on the CSS. Or, more accurately, it should depend on the modular, reusable API defined by the CSS.

If you use the best practices of OOCSS, SMACSS, or BEM, you will not need to edit the CSS every time you edit a page. In fact, once you have your basic building blocks of CSS defined, you can build out all sorts of things in the markup before you need to touch the styles again. Far too often, developers write their CSS and HTML together, with selectors that mimic the structure of the DOM. If one changes, then the other must change with it: a tight coupling.

However, moving the styles into the JavaScript does not address this problem at all. When we moved our HTML into our React components, we redefined which concerns we were separating. Each component is now a unique concern. When we bring CSS into that, we are not further breaking up our concerns; we are just adding more responsibilities to the concerns we already have.

In a best-case scenario, with well organized code, we require in a style module into our React component and add it to the props. This is roughly equivalent to adding a class name that references a stylesheet–there is no net gain in terms of separation of concerns. But, we don’t always work in a best-case scenario. Now that our JavaScript has taken responsibility for styling, it will have to take care of things that we take for granted with CSS. This will add unnecessary bloat to your codebase, and make separation of concerns more difficult.

If your stylesheets are well organized and written with best practices, there is no bi-directional dependency between them and the HTML. So we do not need to solve the same problem with our CSS that we had to solve with our markup.

Beware Framework Lock-In ¶

CSS is universal. If your page has stylesheets, that’s cool, because everyone’s page has stylesheets. Every JavaScript library and every HTML templating language works with CSS. If you shift all of your styles into JavaScript, you are going to be locked into using JavaScript libraries that can use them. Your styles no longer stand on their own.

If in 14 months you find a new view library or framework you want to try out, you’re out of luck. You will have to invest a lot of time into pulling styles back out of JavaScript modules and into stylesheets again. The most likely scenario is you would only bring out a portion of it—just enough to use in the components you are building with the new library. Sure, you may continue to make progress over time pulling styles back into regular stylesheets, but during that process, you’re going to have duplication of code, and you may even find yourself running into scenarios where the CSS has to be completely re-written to replicate the behavior you added in JavaScript.

All or Nothing ¶

When you start bringing your styles into your JavaScript, where do you stop? If you only bring in some of them, how are you going to define that boundary? When you need to change something in the look and feel, do you know whether you need to open up your styles.css or your styles.js? A logical solution here is to bring in all of it and abondon stylesheets altogether.

The problem with that is, CSS takes care of some things cleanly for us that you are probably taking for granted. This is helpful for fonts in particular: The default font size, the font face and line-height, and the color of your font are all inherited silently from one of the topmost elements on the page. Do you want to explicitly set these things on every single component you build? Because you will have to.

Not only that, but if you distribute your component, the users of that component need to be all-in on the same paradigm, as well. Your component sets inline styles, which means they can’t be overridden without !important. To get around this problem, you can allow the user to pass in their own styles, but this means the user of your component must have their styles defined in their JavaScript as well. What if they want to use traditional stylesheets? You’re forcing their hand.

Missing CSS Features ¶

I think there is a place for a few inline styles in a React component. I’ll admit I’ve had to do it a few times. Most often, though, it is because I need to accomplish something that can’t be done in pure CSS (yet), such as animating from height: 0 to height: auto. Animation is a bit of a different topic here, but, honestly, even that is invariably easier to do when it can be accomplished with pure CSS. The power of transitions and keyframe animation is much harder to replicate in JavaScript without the help of yet another dependency. The browser already has this stuff built in. Take advantage of it. It is so much easier to just toggle a classname and not have to think about it when I’m trying to focus on another problem.

You also lose the ability to do some other things, as well, like media queries and fallback values for older browsers. Unless you want to start browser sniffing and adding conditionals around your styles. Again, this is adding more responsibilities to your components that otherwise they would not have.

In Defense Of CSS ¶

At this point, I have to ask: what problem are we trying to solve? There is a lot of baggage and many unknowns if we start doing CSS-in-JS. We had better have a damn good reason before we go down that road. Christopher Chedeau, in the original slidedeck that introduced this idea, outlines seven “problems” with CSS. The thing is, they are solvable problems. If we as web developers just understand CSS better, and take the time to learn modern best-practices like SMACSS and BEM, these issues almost entirely dissolve, especially at the scale most of us work at. Don’t get me wrong; he does make some good points that are worth discussing, but I believe we have at least partial solutions for all of them (some of the latest proposals to the CSS spec help, as well). If you want to discuss those points directly, feel free to ping me on Twitter.

Many web developers fear CSS. They fear it because the do not understand it. And I am worried that, in that fear, we will collectively rush to move our styles into JavaScript in hopes that it solves our problems. It won’t.

It’s time to truly learn CSS, because that’s our real problem. And that is a problem we can fix.

Update: I have written a follow-up post: Into the Future of CSS

Hosting on Github

2015-05-16T21:26:32Z

Well, this is a bit of an experiment… I’ve lost track of how many times I’ve started a redesign of my WordPress blog, only to give up after days of fiddling. This is kind of silly, since I generally finish the design of my site fairly quickly, but get held up fighting with the implementation minutia.

I blog very rarely. I also occasionally want to host various other pages that don’t necessarily need to fit with the theme of the rest of my site. WordPress is really overkill for this. What I really need is just some static hosting. So I’m giving GitHub Pages a try. Not only that, but I should be able to play with the design whenever I feel like, without too much time investment.

So here’s my new design. It took me just a few days not only to build the site, but to also roll out some bare-bones blogging & deployment scripts in gulp; my database is a git repository. I can blog in Jade or MarkDown. I think my wordpress days may be done, at least for now.

Taming CSS

2015-04-29T21:26:32Z

Observation 1: Web developers, in general, don’t know CSS as well as they should.

Observation 2: There aren’t really any good roadmaps for learning all the essentials of CSS.

There are great resources for the basics, for styling, for code organization/architecture, for advanced tricks. But to work through them all, you get a lot of overlap, and they still leave you with missing gaps in your knowledge. Often, with CSS, you don’t know what you don’t know, and that makes it hard to move forward. My hope is to fix that, by putting them all together in one place.

Announcing Taming CSS, a CSS book for web developers.

Update: My book has been renamed to CSS in Depth.