Florens Verschelde

Gabarits HTML et CSS simples (édition 2024)

2024-12-10T00:00:00+01:00

Il y a maintenant 16 ans, j’ai créé ces 11 gabarits de mise en page pour la formation Elephorm Apprendre XHTML et CSS. Ils correspondent aux types de mise en page de site web courants à l’époque, compatibles avec Internet Explorer 6. Ils utilisent principalement float et position: absolute, et ne sont pas responsive.

Pourquoi une mise à jour

Depuis, j’ai reçu une moyenne de un (one, uno) courriel par an demandant si une mise à jour utilisant des styles CSS plus modernes était prévue.

L’intérêt d’une mise à jour ne me semblait pas évident, car le design de ces gabarits correspond aux tendances du milieu des années 2000, assez éloignées des mises en page courantes dans les années 2010 et au-delà. Je répondais donc cordialement: cherchez ailleurs.

Cependant, un énième courriel annuel piqua ma curiosité. À quoi pourrait ressembler une mise à jour technique, avec les outils de 2024 et ces designs de 2008? Je me suis alors embarquée dans une réécriture complète.

Le résultat est désormais visible à côté de la version de 2008, conservée comme archive.

À explorer en ligne: Gabarits HTML et CSS simples (version 2024)
Et sur GitHub, avec l’historique des modifications: fvsch/gabarits-html

Comme pour la version de 2008, les feuilles de styles sont abondamment commentées pour expliquer les techniques de mise en page utilisées.

Différences avec la version de 2008

Les couleurs de texte et de fond sont définies dans des variables CSS.
Les styles sont responsive et écrits avec une logique mobile first: on commence par définir la mise en page la plus simple avec les blocs les uns sous les autres (en général adaptée à l’affichage sur petit écran), et on utilise des Media Queries pour définir des surcharges de styles pour les écrans plus larges.
Dans quelques cas, j’ai aussi utilisé des Container Queries, afin d’éviter d’avoir à dupliquer des valeurs précises entre différentes Media Queries.
La plupart des mises en page sont réalisées avec les grilles CSS (display: grid). Ici, comme les principaux conteneurs sont connus à l’avance, j’ai aussi largement utilisé grid-template-areas.
Au lieu de doubler le body avec un conteneur <div id="global">…</div>, l’élément body est utilisé directement pour la mise en page de ses enfants.
Le cas de figure “conteneur sur toute la hauteur du viewport” peut être géré simplement avec min-height: 100dvh.
Le cas de figure “colonnes de même hauteur” était problématique en 2008. On utilisait des effets de trompe-l’oeil avec une image de fond sur un conteneur, répétée en hauteur, pour dessiner les couleurs de fond des colonnes. Ce n’est plus un problème avec les grilles CSS, avec Flexbox, ou même avec display: table (que j’ai souvent utilisé à l’époque d’Internet Explorer 8).

Don’t use stale bots

2023-02-25T06:00:00+01:00

It’s okay for a software project to have a lot of open issues. It’s okay if you’re not able to triage issues, let alone close them. It’s not okay to use stale bots.

What’s a stale bot?

In a bug tracker¹, a stale bot is an automated process that marks an issue as “closed” after a period of inactivity.

If you’re using a piece of software and want to report an issue on a bug tracker, this is how you may end up meeting a stale bot:

You find the bug tracker for the software you’re using, and file a new issue.
Nobody seems to read your report or post any answer. That’s frustrating, but people are busy, and they’re usually not paid to handle your issue.
After a few weeks or a few months, a “bot” account adds a comment on your issue to say that it’s “stale”, and closes the issue or announces that it will be closed soon.

As a user, meeting a stale bot is often a frustrating experience.

Mismatched mindsets

For a user creating an issue in a software project, that issue is strongly related to the software and their experience of the software.

They ran into a bug, or didn’t understand an API. They may be blocked in their work, or will need extra time to find a workaround. And as long as their experience doesn’t improve, the issue remains relevant; it cannot be “stale”.

For a project maintainer, issues are artifacts that are only loosely related to the software.

Issues are often unclear, lack context and steps to reproduce. Just figuring out how the issue relates to the software is a task in and of itself. As time goes by, it becomes very unlikely than whoever opened the issue will come back to reply to requests for information.

For the maintainer, the issue-as-artifact may grow “stale”, hardly actionable in the first place and becoming less so as time goes by. Surely closing that issue automatically makes sense?

Well. Now you have a communication problem.

From your vantage as a maintainer, you are discarding an artifact. From the reporter of the issue, you are deciding against the possibility of fixing or improving the software.

And if bridging this perception gap is hard, automating it — using an impersonal form of one-way communication — will only make it worse.

It might be fine, and indeed useful, to close a vague report where the reporter never replied to requests for information. But when you’re auto-closing issues, you’re also closing issues with good steps to reproduce, screenshots, comments, investigations from users and reduced test cases.

Auto-closing information-rich issues tells users that their efforts — because it does take time and focus to make a good report — are not valued.

Stale bots break your bug tracker

By sweeping dirt under the rug, you have created new UX issues for users of your bug tracker.

If you needed another reason besides users thinking it’s annoying and insulting, take a good look at the bug trackers of projects that auto-close issues after 3, 6 or 12 months.

The list of issues for their GitHub repository may look nice — a few hundred open issues, a few thousand closed issues, good job! — but the actual experience of using that bug tracker is now significantly worse.

First, users can end up on one of your issues from any external source: a link from another repository, a URL in source code, a link in StackOverflow or in a search result page. They may want to know things like:

I am holding the software wrong?
Is it a known limitation or bug?
Was there a recent fix that I could upgrade to?
Any workarounds I could use?

The main signal answering those questions is the bug status. Is it green for “Open” or purple for “Closed”?²

On a repository that closes issues as “stale”, you have to scroll to the bottom of the issue to figure out if “Closed” means “fixed”, “will not fix” or “we’re arbitrarily hiding this issue from the main list”.

Which leads us to our second UX issue: auto-closed issues don’t appear in search results.

Now, when a user tries to report an issue and searches the existing issues, as your contributing guidelines say they should, they will not find that identical issue which was auto-closed³.

This leads to more duplicates in your repo. Now everyone is going to waste time:

Maintainers may redo a lot of the triaging and investigation work that was done 6 months or one year earlier on the auto-closed issue.
Reporters are wasting the time spent reporting an issue, following the many steps in the issue template, making screenshots and reduced test cases.

I’ve seen repos where common problems were reported at least 3 times, with the latest report linking to a “stale” closed issue, itself linking to a previous “stale” issue. What a mess.

Why projects use stale bots

One reason is brand management.

Companies with public bug trackers want to look like they’re on top of bug fixes and feature requests. Open-source projects striving for adoption or looking for sponsorship are aware that some in the software community see a large issue count on GitHub dot com as a marker of a “dead” project.

Stale bots will sweep that dirt under the rug. But while that improves the very first look at a repository,

Meanwhile, large open-source projects like Chromium or Firefox have hundreds of thousands of open bugs in their bugs trackers, and few people bat an eye. Maybe it helps that those projects are not using GitHub⁴.

Here the solution is simple, but hard to make peace with: don’t artificially reduce issue count. If you need to signal that your project is active, there are other ways.

Alternatives to stale bots

Okay, so you agree that stale bots have big downsides. Still, your project got a bunch of users and you are overwhelmed by way too many issues. What else can you do?

Nothing

Accept that large projects will have thousands of open issues. It’s fine.
Triage

Set up a process to qualify issues. The goal is to curate a subset of issues that can actually be worked on.
Project management

Decide what to work on. Have a roadmap, prioritize high impact, do paper-cuts and/or stability projects.

Every step builds on the previous one. You will need people and work for all steps after the first one.

If you have declared triage and project management bankruptcy⁵, auto-closing issues won’t fix that.

If you can’t improve your process, then I suggest you stop at step one. Just don’t use a stale bot.

Bug trackers or issue trackers are websites where users of a piece of software can report issues they’re running into, and often voice suggestions for new features. ↩
Other bug trackers have richer statuses, but we’ll focus on GitHub given that’s where most stale bots are lurking. ↩
Some will suggest that maintainers and users of the software can just remove the is:open search filter that GitHub sets by default. But only a fraction of users will do that. It’s more efficient to not create a problem in the first place. ↩
GitHub might be responsible for half of the idea that a project with many open issues is “dead” or somehow “bad”, thanks to their decision to put counts of open issues and pull requests on every single page of their bug tracker. ↩
Maybe because you’re running an open-source project with not enough funding compared to its user base. ↩

Transparent iframes and dark mode

2022-05-11T12:00:00+02:00

Today we’re talking about how transparent iframes, dark mode, unreadable text and varying levels of browser support are doing my head in. But don’t worry, there’s ~~light mode~~ light at the end of the tunnel.

And just so you know what you’re missing, I workshoped other titles like “Transparent iframes considered darkful” (always wanted to do one of those), “A plague of dark mode iframes” (reference 1) and “Darkmode on the frame of town” (reference 2).

Iframes, transparent by default

I work at StackBlitz, an online IDE for Web stuff, and like many online code editors¹ we typically render two HTML documents:

A top-level document on the stackblitz.com origin, showing a code editor and other tools.
A “preview” document in an iframe, hosted on a different origin (for your own safety), that can be virtually anything that authors of StackBlitz projects generate²: arbitrary HTML and CSS, text/plain HTTP responses, SVG documents, etc.

This is where stuff gets tricky.

By default, iframes are transparent. If you don’t specify a background-color in the embedded document (say, on the html element or on body), the background color from the parent page shows through.

So if the background in the parent document is dark, and the document in the iframe uses browser defaults like black text and a transparent background, you get black text on a dark background and can’t read anything. Whoops.

Because our users were used to web pages with default black text and white backgrounds, the fix was simple: we styled our preview iframes to have a white background.

Most quick demo pages would have black or dark text, resulting in black text on a white background. And more stylish demos would set their own text and background colors, managing color contrast and readability themselves. Problem fixed.

Introducing: color-scheme

A year ago, I tweaked the HTML for all stackblitz.com pages to include a couple meta tags:

<meta name="color-scheme" content="dark">
<meta name="theme-color" content="#2e3138">

These values match the default dark theme (nicknamed “DarkBlitz”) that we use for our editor. When users select the light theme instead in our UI, we then update those meta tags at runtime:

const theme = getTheme(localStorage.currentTheme);
setMetaTag('theme-color', theme.themeColor);
setMetaTag('color-scheme', theme.colorScheme);

(Though it looks like setting the color-scheme property in CSS might be compatible with more browsers, because not all browsers seem to pick up on the meta tag change.)

Why tell browsers about the color scheme used by the page, you ask? Well, quoting MDN:

The color-scheme CSS property allows an element to indicate which color schemes it can comfortably be rendered in. (…) When a user selects one of these color schemes, the operating system makes adjustments to the user interface. This includes form controls, scrollbars, and the used values of CSS system colors.

Our rough goal was to hint to browsers that if they render a scrollbar or a checkbox or a <select> dropdown, we’d appreciate 😘 if they can do that using a theme that is either light or dark (as declared).

How does that relate to iframes? Coming up right now.

Attack of the dark mode iframes

Now, authors using our IDE could also add <meta name="color-scheme" content="dark"> or the equivalent CSS to their pages. Browsers would react by making the page’s text white, and its background dark.

Except in iframes, where the text would be white, but the background would remain transparent. Resulting in, you guessed it, white text on our white background.

That issue was raised with the CSS Working Group, and the resolution was:

If the color scheme of an iframe differs from embedding document, iframe gets an opaque canvas background appropriate to its color scheme.

So the dark mode embedded document, with its <meta name="color-scheme" content="dark"> meta tag, would get a browser style similar to :root { background-color: canvas }, where canvas would be a dark color. White text on dark background, problem solved!

Alas!

Remember that we also have <meta name="color-scheme" content="dark"> in the editor page? So we now have a dark color-scheme in both the embedding document and the embedded document, so the iframe stays transparent. White text on white background again.

Okay, so maybe it was silly to use a white background all along? But remember that all this color-scheme stuff was specified in recent years and implemented in browsers as lately as 2021. For most users and most browsers, we needed that white background, as did CodePen (yup, also setting a white background on their preview iframes) and probably others.

So, what’s the way forward? Do we need to predict what the text color will be and if the iframe will be transparent or not? In our case, we can’t know about what gets rendered in the iframe, so tough luck.

But maybe we don’t need to control or predict that content. We can just say “hey, here’s what we support”, and let the browser handle it? Again, quoting that resolution:

If the color scheme of an iframe differs from embedding document, iframe gets an opaque canvas background appropriate to its color scheme.

So we tell the browser that the embedding document only supports a dark color scheme, and we use a dark background behind the iframe. It could be as simple as:

:root.theme-dark { color-scheme: dark }
:root.theme-light { color-scheme: light }

.preview-iframe {
  /* canvas color depends on the inherited color-scheme */
  background-color: canvas;
}

But if we want to keep a white background for browsers that don’t support color-scheme, it might be safer to do something like:

/* Keep the default white background for backwards compat */
.preview-iframe {
  background-color: white;
}

@supports (color-scheme: dark) {
  :root.theme-dark {
    color-scheme: dark;
  }
  :root.theme-dark .preview-iframe {
    background-color: black;
  }
}

@supports (color-scheme: light) {
  :root.theme-light {
    color-scheme: light;
  }
  :root.theme-light .preview-iframe {
    background-color: white;
  }
}

Would that approach work? Theoretically, yes.

In quick tests in Chrome, it seems to be working well. We might even try it on prod (and roll back if it creates more issues than it solves).

But currently, there are a few browser bugs that might make this solution unreliable:

Firefox doesn’t seem to support adding an opaque background to iframes with mismatched color-scheme values.
There might be some smaller issues in Chrome as well, according to the description in this test case (but I couldn’t reproduce on macOS with dark and light OS modes).

That Firefox issue means that iframes would always be transparent in Firefox. So using a dark background behind the iframe would break any embedded page that specifies neither a background-color nor a color-scheme in Firefox, and that’s most pages. No good.

We’d have to apply that solution to browser that are known to implement that opaque background logic, and since @supports (color-scheme: light) doesn’t test for that, that means doing some UA sniffing. And I really don’t want to do that.

Quick fix: the least bad solution?

This week, we announced a partnership with Cloudflare, who are using StackBlitz to power demos and tutorials of their Wrangler tool for Cloudflare Workers. Many of the demos were returning text/plain responses, which were shown in our preview iframe.

What’s the color-scheme for a document generated for a text/plain response? Well, that’s entirely up to the browser. Chrome is apparently creating a HTML document like this:

<html>
  <head>
    <meta name="color-scheme" content="light dark">
  </head>
  <body>
    <pre style="word-wrap: break-word; white-space: pre-wrap;">Hello World</pre>
  </body>
</html>

It declares that this document supports both light and dark schemes, and the browser resolves that to either light or dark depending on the OS color scheme, not the parent page’s color-scheme (at least in my tests with Chrome 101 on macOS).

So if:

you use a dark mode OS (or browser theme maybe?),
and the default dark theme for the StackBlitz editor,
and the parent page has <meta name="color-scheme" content="dark">,

… then you get a transparent iframe in Chrome, with white text, on our white background. The white background that we can’t change to a dark one, because that would break a bunch of content in Firefox.

So we went for a quick and dirty fix: we removed the color-scheme meta tag on the parent page.

Now Chrome resolves the color schemes to color-scheme: normal for the parent page and color-scheme: dark for the iframe. And since those don’t match, Chrome makes the iframe opaque (white text, dark canvas background).

Meanwhile, Firefox generates a different kind of document for text/plain responses, and that uses a dark theme (when the OS theme is dark) when opened as the top-level document, but not when rendered as a child document in an iframe. So the text is black, the iframe is transparent, and our background is white, and that works, kinda.

I think that the last remaining bug we have is: if the iframed document sets color-scheme: dark and no background-color, we’ll have white text on a white background in Firefox. Not great, but here’s hoping that Firefox implements the opaque iframe logic soon.

Then maybe we can add color-scheme back to our top-level document, and get its purported benefits.

Better fix: white background, local color-scheme!

Alternatively, we might be able to restore our usage of color-scheme for our pages if we declare that the iframe element uses a light scheme.

:root.theme-dark {
  color-scheme: dark;
}

.preview-iframe {
  /* tell browsers to make the iframe opaque
     for documents with color-scheme:dark */
  color-scheme: light;
  background-color: white;
}

That works in Chrome, i.e. when the embedded document has a color-scheme other than dark, then the iframe is opaque. It also seems to match the text of the spec:

In order to preserve expected color contrasts, in the case of embedded documents typically rendered over a transparent canvas (such as provided via an HTML <iframe> element), if the used color scheme of the element and the used color scheme of the embedded document’s root element do not match, then the UA must use an opaque canvas of the Canvas color appropriate to the embedded document’s used color scheme instead of a transparent canvas.

(Emphasis mine.) If “the element” in that paragraph means the element used to embed a document, i.e. our preview <iframe> element here, it looks like we’re following the spec correctly by setting background-color: white; color-scheme: light; on that <iframe> element.

Should it be simpler?

So here we are. I think I mostly figured it out, in big part thanks to Amelia Bellamy-Royds’s generous help. And there’s hope that things will improve in browsers and we’ll be able to use color-scheme again.

But I’m wondering, should we be jumping through those hoops? Can’t we have a way to ask browsers “Hey, could you handle this iframe’s background for me, since you know what’s going on there and I don’t? Thanks, you’re a peach.” Or, conversely, “Look, I want this iframe to be transparent no matter what, and I’m taking on the responsibility here”.

Right now, the opaque iframe background mechanism is something that:

requires expert knowledge to opt in (it’s far from obvious that the answer to “how do I get the browser to set its default background-color for this page in an iframe, like it does when opening the same page in a new tab?” is “use a mismatched color-scheme value on purpose”);
doesn’t have a way to opt out.

Is it good enough as-is, or could that improve? And if we want to improve at least some of these problems, how could we do it?

We should probably document things more, let’s say by updating MDN to add a new section on the iframe page and another one on the color-scheme page?

On top of that, should there be an explicit way to manage iframe transparency, let’s say with a HTML attribute for the <iframe> element or with a CSS property (iframe-transparency: auto | transparent | opaque or something)?

I also like CodePen for quick CSS tests, and I hear that CodeSandbox and GitPod are pretty good too! ↩
Especially since we launched WebContainers, which let you run Node.js code in the browser — so you could have an express server returning any type of HTTP response for that preview iframe. ↩

Designing calculator apps

2021-03-16T13:00:00+01:00

Let’s say you want to calculate 35 × 1.2, and you have a pocket calculator. You whip it out, type on the keys, and the result looks like this:

Hm, maybe? That looks a bit strange. How do you know for sure?

With luck, you know that multiplying 35 by a number higher than 1 should give you a result higher than 35, not lower. Also that fractional part smells fishy. That’s definitely wrong.

You could try again, but your confidence is shaken. Is the calculator broken? Probably not. Will you mess up again?

What went wrong? In this case, you made a couple mistakes while inputing the calculation. We can use magic to show you the past:

Here’s what happened: you hit the 8 key instead of the 5 key; and then the ÷ key instead of the × key. You got a result for 38 ÷ 1.2.

To some of us, this is a familiar experience. We’ve lost many points on Math tests because of a momentary lapse of attention, because of finicky calculator keys.

I had a Math teacher who would ban pocket calculators that didn’t show both your input and its result at the same time. If a calculator couldn’t show this:

38 ÷ 1.2
=    31.666666666667

You couldn’t use it. Not in class, not during tests. It’s a recipe for useless mistakes. You need to be able to check your work.

If you give important information to an information system and it disappears as soon as you enter it, you can’t check your work. You can’t catch mistakes.

Some humans have excellent attention and working memory. But we don’t design tools just for the lucky few, do we?

Apple’s Calculator app on macOS imitates an electronic calculator. It uses metaphors from the physical world, such as:

A display showing a single value at a time.
Buttons that represent physical keys.

Optionally, if you know the keyboard shortcut or go looking through the menus, you can show a second window called a “Paper Tape”. It shows a log of your calculations and looks like this:

Another well-loved calculator app on macOS is PCalc. It has a single-value display, “keys”, a separate “paper tape” window, themes if you want it to look like a physical calculator, and 3 memory registers like the best HP and Casio machines out there. Its users sing its praises in Mac App Store reviews.

In 2005, an Australian high school student named Nik Youdale built a small calculator app over the summer. It mimicked the look and features of a pocket calculator. His friend, Zac Cohan, was unimpressed:

I couldn’t understand why it only displayed a single number at a time, and why it wouldn’t evaluate an entire mathematical expression like you’d see written out on paper.

Zac wanted more out of a calculator. A few months later, he got another idea. Instead of copying a traditional calculator, they could copy the page of paper where one writes down calculations, results and notes. Zac asked, What if the calculator was actually part of ‘the page’?

They built an application, Soulver, based on that idea. It’s a paper pad that magically runs your calculations. The current version, Soulver 3, works very much like their first prototype:

Input and output are always visible, and input lines (on the left) can be edited at any time. Soulver also lets you store specific results in variables and reuse them on later lines.

Zac also wanted Soulver to be able to understand natural language, or at least to identify numbers, units, and specific commands within text. He has been steadily improving this feature for 15 years, and in my experience it works quite well.

Soulver is my calculator app of choice on macOS. If you want a similar app for Windows, Android or on the Web, the Soulver FAQ lists a few options. Quotes in this section are from Zac Cohan’s article “The creation of soulver”, which is a great read.

“Skeuomorphism”, the persistence of essential features from old objects as ornamental cues, was a hot topic in the design community in the early 2010s. The design of Apple’s iOS 7 was seen as an about-turn, from apps that mimicked paper and leather to a “flat” minimalist look. Skeuomorphism is dead!

But as we’ve seen with Apple’s Calculator, an app’s visual style can be “flat” while faithfully mimicking a physical counterpart.

At the risk of beating a dead horse, I’ll argue that Soulver’s design is “skeumorphic” as well. It reproduces the experience of writing calculations on paper with a pencil, writing down a result, referencing that result later on, etc. Soulver’s first icon showed a couple sheets of paper, a pencil, and a pocket calculator.

Soulver’s design is superior not because it is less of an imitation, but because Zac’s choice of what to imitate was better. He wanted to focus on the paper and pen experience — saying what you want and writing it down to supplement your working memory. The experience of painstakingly hitting keys on a calculator? That could be automated and abstracted away. In an icon update, the pocket calculator was replaced by a digital display, showing results only.

This design may not work for everyone. The happy users of PCalc love how closely it mimicks the electronic calculators of their youth; the more complex the better! Maybe they have above average working memory. Maybe they loathed having to write down every single step of a calculation in school tests. Maybe they just want to use something they already know.

Finally, the popularity of Soulver, PCalc, and even Apple’s Calculator.app is dwarfed by the number one calculator app out there: Excel. Spreadsheets are the main computer calculators that so many workers reach out to.

In a ghastly whisper, the dead horse’s soul asks: are spreadsheets skeuomorphic too? Probably. They’re designed after accounting ledgers and paper spread-sheets, after all.

RAW Power 3: an affordable digital photo development app for macOS

2021-01-11T13:00:00+01:00

I used to dabble in digital photography, even attended a series of workshops for a year. I’m still amateur level, I think, and haven’t shot much in the past 7 years or so. Still, I have a few thousand pictures, some edited and some not at all, that sit in my archives, and I’d like to edit and publish at least some of those.

Only problem: I didn’t have any photo management and development software I’m comfortable with.

I used to own Lightroom 3 and 4. I still do, but they probably don’t install on current Macs, and Adobe made it hard if not impossible to get a license for the current Lightroom Classic app without paying 20 euros per month. So I’ve been looking for alternatives.

Rounding up photo editors

Here’s a list of what I found:

Capture One, the priciest option for pros (around €500).
DxO PhotoLab, more affordable (€130); I’ve heard some good things.
ON1 Photo Raw (€102), not a good option for my M1 Mac¹.
Exposure X6 (€110), which seems interesting.
Skylum Luminar (€90 standalone, €150 with their new “AI” tools), which was slow when I tried it a few years back but might have improved since.
Darkroom (€88, or a €22/year subscription), seems to integrate with the Apple Photos library and provide a bunch of tools in a nicely designed package ².
Photoscape X (€44), seems marketed for the Instagram crowd but could be powerful anyway.
Picktorial ($5/month subscription).
Apple’s own Photos app (included with macOS), which I tried briefly, but I don’t want to import my photos from my archive folders on external drives and into their Photos Library; I hear the development tools are a bit limited too.

I also got Affinity Photo and Pixelmator Pro, each for around €50. While they can do some RAW development, and have some great features, they’re closer to Photoshop in spirit. So not my cup of tea. They also don’t include a library browser or manager.

There are a few open-source options too, such as Darktable, RawTherapee and LightZone. I didn’t consider them because they tend to have limited macOS support³, a steep learning curve, and questionable usability⁴.

Finally, after reading this review of the Apple ProRAW format, I discovered a small macOS and iOS app called RAW Power. It piqued my interest since it’s cheap (around €30), runs natively on Apple’s new CPUs, and looks similar in spirit to early versions of Lightroom and Aperture.

The RAW Power UI

RAW Power is developed by Nik Bhatt, who worked for years at Apple on the Aperture team. A bunch of user comments call RAW Power a spiritual successor to Aperture, though at this time its feature set seems more limited (with a few exceptions where it’s more up-to-date).

It was originally a development extension for Apple Photos, before gaining a photo library module in version 2 (improved further in version 3), making it usable as a standalone app as well. You can get a trial version on the app’s website, which is fully functional and adds a watermark to exported photos.

Before trying it out, I took an hour to watch this video tutorial series recorded by Nik. I especially liked this one, RAW Power 3 for Mac: Rating and Filtering Workflow. That workflow is not super specific to RAW Power, and could be reproduced in several apps, but sharing this method was a nice touch.

The RAW Power UI looks like this:

The UI can be customized a bit, and includes:

Top: a toolbar that can be customized and rearranged
Left: a library explorer showing folders or Apple Photos albums
Center: the main photo view
Bottom a tab strip
Right: a sidebar which shows either photo metadata or RAW development tools

All those UI components can be hidden or toggled. And if you hide the main photo viewer, the thumbnail strip becomes a bigger thumbnail grid.

This lets you customize your workspace however you want, but sometimes I find that I want to go from one UI configuration to another, and clicking 3 buttons to change things one way and then 3 buttons to change it back is a bit painful.⁵

On the customizing front, you can also reorder and show or hide each of the RAW “adjustments” modules that appear in the Edit sidebar. The interface for that would benefit from some improvements though, since you need to use different menus to add a module, hide a module, and reorder modules; it would be possible to unify all that in a single, more intuitive config view.

Personally, I’m missing a way to quickly show the photo’s metadata when I’m in Edit mode⁶. I have to switch the sidebar from Edit to Info, which takes a good second for some reason, on top of making me lose my place. I’d also love to keep a histogram in Info mode.

The adjustment tools

The adjustment sidebar has a bunch of good tools:

A good histogram with black/white and color clipping highlighting.
White Balance (with a decent Auto option and manual control).
A good Crop tool (I like being able to control the precise pixel size and coordinates, it came in handy working on a photo series where I’m trying to align 20 pictures taken from the same spot!), and a Perspective tool that is maybe less intuitive.
Basics/Tone/Enhance has the usual suspects: exposure, brightness, highlights and shadows, clarity…
Black & White, Channel Mixer, HSL Color.
Curves, Levels, Vignette.
A LUT tool that lets you apply predefined styles, including some film simulation or black and white ones. I wasn’t familiar with the “LUT” term, but apparently LUTs are a kind of color map that pairs each input color to its destination color, and there are a bunch of LUTs available online from different providers, with both free and paid options.

Not sure why Brightness is a “Basics” control but “Exposure” is a “Tone” control. Or why Deepen and Lighten are in “Enhance” and not “Tone”, or why “Sharpen” is in a different category (with a single slider) and not in “Enhance”. So I’ve reordered those modules to put them together.

Things I like about the adjustment sliders in RAW Power:

It’s easy to see which slider you tweaked (used the system highlight color, which is pink in my case) and which uses the default value.
Double-click resets to the default value.
The numbers are text inputs, and can be edited manually for precision.

Some things I don’t like:

Some text inputs require two clicks to get focus. (Nik reached out by email and confirmed that it’s a know issue with a UI component he’s using in the app.)
Some text inputs support the Up and Down keys to increment or decrement the value, and others don’t, depending on the module.
Based on system settings, it decided I want a comma as the decimal separator, and wouldn’t accept input like 1.5 (resetting to the default value instead). I worked around it by changing my system settings, but being more forgiving and handing both dots and commas as decimal separators would be better.
The way out of bounds values are handled (if I input 5 and the maximum is 2.0, please use 2.0 instead of discarding my input).
Slider values are single digit numbers plus two decimals, e.g. 1.00 or -2.54. Most of them go from 0.00 to 1.00, and would be easier to work with if they were shown as integers between 0 and 100 (same precision, but you don’t have to type a decimal separator all the time).

Arguably, I’m finicky. That’s the problem when you use and review software as a UI developer & designer. 😛

Overall I like the tools, they’re rather powerful. There are a few useful presets you can apply, and a couple “Auto Enhance” features which look decent but not quite magical.

One tool which is both powerful and a bit confusing is the RAW Processing adjustment. It shows 9 sliders and a couple options:

The noise controls are part of this first RAW processing pass. I haven’t worked with very noisy images yet, so I’m not sure if they’re good. The Color Noise correction seems to work well.

The “Boost” feature is interesting. It’s set at its maximum by default. If you move it back to 0%, you get a much more washed-out, lifeless picture, like you get in some RAW processing software out of the box (especially in some of the open-source ones, when they’re not set up to apply some default enhancements). Comparing the results at 0%, 50% and 100% Boost, I tend to like what it does.

Boost at 0% and 100%

In the video tutorials, Nik shows how sometimes Boost goes a bit too far, and it’s better to lower it a bit or completely before applying other adjustments (such as highlight recovery). I’ve sometimes moved it down to 90% or 80%, but rarely all the way down.

Another slider I’ve used at times is Black Point, which er makes more or fewer parts of the image black or dark?

Sometimes it looks like there are a few ways to do the same thing, especially when it comes to contrast with: Boost, RAW Contrast, Contrast, Curves and Levels, to name a few. Or micro-contrast with RAW Sharpen, Clarity and Sharpen. It probably takes some time and expertise to learn what works best for you and your images.

I just discovered the RAW Power user manual (50 page PDF), which has more details on how adjustments work. Maybe that’ll clarify what the best approach is for some use cases.

The Curves tool is powerful and lets you set as many points as you want, but it’s hard to move a point just right on the vertical axis, and a little nudge can have an overblown effect. I was a bit more at ease with Lightroom’s four number inputs, which make it easy to create a symmetrical S-curve and control how strong the effect is.

Finally, there are no local adjustment tool: no brushes, no gradients, no repair, etc. While things like machine-learning based local repairs can be done by other software working on an exported TIFF file, it would be great to at least have support for gradient filters, e.g. to handle sky-vs-land exposure.

RAW Power 3.2 added support for Apple’s ProRAW (part of the DNG 1.6 format), which includes precomputed local adjustments from the iPhone’s software as a kind of mask or extra layer (I’m not sure) that you can turn on or off or apply partially. Maybe some of the work done on ProRAW support lays the groundwork for local adjustments? One can dream. 😄

Data portability

In an ideal world, adjustments made to a RAW photo in one app would be understood by another app. Sadly we don’t leave in this world, because RAW development and image correction algorithms are specific to each app, and there’s no standard even for common things such as exposure correction, black and white or color processing, curves, vignette, embedded LUTs, etc.

So development settings done in Lightroom, RAW Power or DxO PhotoLab won’t be interoperable at all. Okay. But can we at least make sure that those development settings are saved reliably?

Lightroom lets you write development settings as “sidecar files”, which use the .xmp extension, or embedded inside DNG files. This comes in handy when syncing files via Dropbox, saving photos on an external drive, or changing computers or operating system.

RAW Power saves development data in Documents/RAW Power, with no option to use sidecar files. This folder may look like this:

If you move or rename a photo, you risk losing the link with this development data, as stated in the help pages:

RAW Power stores its editing and rating / flag information in files stored within its “sandbox”, which is a directory inside your home folder on your disk. RAW Power stores information in the sandbox that lets it connect its data with your original images. Part of the identifier is the file name of your image, and part is the identifier generated by macOS. As a result of this system, RAW Power can connect editing and rating information to your original even if you move the file elsewhere on your disk. However, if you rename it, or move it to another volume, the link is broken.

So if you store photos on a drive, that drive dies and you later get a backup of your photos: sorry, your development data will be lost or not linked to the photos.

Update, Nik Bhatt reached out by email to give more information about this:

While the link can be broken if you move a file to another volume (or restore from a backup), there are two features in the app for reconnecting the edits to the originals. One is called Reconnect and the other is Restore Edits.

I haven’t tried those features yet, but they look like they could handle reconnecting edits to files restored from a backup.

I’d still like to have a way to rename files without losing metadata or having to reconnect metadata to the renamed files. Whether that’s by having sidecar files witch matching filenames alongside the source files, or by having more options for renaming files within Raw Power — or ideally, both.

Nik says he wants to improve file management in future releases, so I’ll keep my eyes on that.

My recommendation

Despite a few pain points and concerns, I find that RAW Power is a capable tool and I’ll probably use it more in the future, while keeping an eye on the pricier competition.

If you liked Lightroom Classic or Aperture, RAW Power might be a good fit for you, provided you can forgive a few issues and missing features.

RAW Power is, as far as I can tell, indie software with a team of one and a low price. It should give you a lot of value for your money.

I heartily recommend giving it a try.

I bought a ON1 Photo Raw 2020 license in a sale last year. It fails to install on my computer. The 2021 version — a somewhat pricy upgrade — is an Intel app that runs too slowly to be comfortable. I might reconsider later if the price and performance are right. ↩
Subjectively and just based on screenshots, Darkroom has the most attractive design. ↩
Darktable tells you “Good Luck :)” if you want to install a macOS version. ↩
That’s not a condemnation of those projects. I understand that open-source side projects made by developers might focus on Linux support and/or powerful features that scratch one’s itch over the years-long design process needed for best-in-class usability. ↩
For browsing and rating I might show the left sidebar, a thumbnail grid with medium thumbnails, and the metadata sidebar. For editing a particular photo, I’d hide the left sidebar, show the main photo view, and either hide the thumbnails or keep them at the smallest size. If I count the clicks needed to go from the first configuration to the other one: that’s 4 clicks. ↩
For instance, I’ve wanted to check data such as the shooting date and hour when tweaking white balance, to make sure the white balance is consistent with the hour and season when I’m going for a realistic look. ↩

Learning XState by refactoring an old project

2021-01-06T17:00:00+01:00

For a while I’ve wanted to learn the XState library, which is presented as a solution to gnarly UI state issues where “what should we show and how should it act?” becomes hard to determine.

Since the best way to learn is to actually build something, I’m thinking I can try to port an old project of mine over to XState, and see how it turns out. Continue reading if you want to follow along!

Why state machines?

I’ve been building a bunch of app or app-like user interfaces with React and other frameworks, and you quickly run into situations where a screen or component’s UI state is represented by a series of variables.

For instance, if a component loads data from a server, you can end up with variables like:

data (undefined, empty Array, or Array with data)
error (undefined or an error object or message)
loading (boolean)

You end up writing conditions like this:

const hasContent =
  !error &&
  !loading &&
  Array.isArray(data) &&
  data.length > 0;

Add a couple more UX or business rules to this UI component, and you’re in trouble. Your code will be littered with complex conditions, and it’s easy to get one of those wrong and end up with subtle bugs where different parts of the UI disagree about what state the application or component is in. So, what’s a poor UI developer to do?

Enter finite-state machines.

As a literature major with no formal computer science training, I’m not quite sure what I’m talking about, but apparently a “finite-state machine” is a programming concept where:

the program has a list of possible states;
it can be in only one state at a time;
and it defines how each state can or cannot transition to other states.

This can be used to describe physical devices like elevators, traffic lights, vending machines and more, and often those devices do run programs that implement a finite-state machine.

Last year I built a tiny click precision game, with zero experience in game development. I used Svelte, and designed the game’s state somewhat naively. Often thinking “I should use an established formalism here” but being pressed for time, I improvised some ad hoc code.

Shortly after that, I heard of XState, a JavaScript library that helps with implementing state machines. And I wondered how would things have worked out if I had used XState. Let’s find out!

How the game currently works

Since this is a refactoring operation, we should review key parts of the current code for click-precision-game. How does it handle the main gameplay state?

Let’s look at the main gameplay in the Playground.svelte component. There’s a lot of logic there. The game follows a linear timeline where each instance of the game is divided in two parts:

A countdown, divided in a few phases (showing “click the green square”, “3”, “2”, “1”).
Then a series of 20 “turns”, each turn divided in 2 phases: the “turn” itself (time when the game’s target is visible and must be clicked), and a “cooldown” (short pause before the next turn).

That information is encoded as a collection of objects:

export const PLAY_PHASES = {
  START: {
    next: "COUNTDOWN_3",
    durationRatio: 1,
    minDuration: 1000,
    countdown: 4,
    showTarget: false,
  },
  COUNTDOWN_3: {
    next: "COUNTDOWN_2",
    durationRatio: 0.5,
    minDuration: 400,
    countdown: 3,
    showTarget: false,
  },
  COUNTDOWN_2: {
    next: "COUNTDOWN_1",
    /* … */
  },
  COUNTDOWN_1: {
    next: "TURN",
    /* … */
  },
  TURN: {
    next: "COOLDOWN",
    /* … */
  },
  COOLDOWN: {
    next: "TURN",
    /* … */
  }
};

When the Playground component is mounted, we’re triggering the first phase:

onMount(() => {
  startPhase("START");
});

And the startPhase function does the heavy lifting. Here it is, partly abridged and annotated:

function startPhase(key) {
  // If we’re just starting a turn
  if (key === "TURN") {
    // increment the turn count
    turns += 1;
    // reset the success/failure state to a neutral value
    turnState = TURN_STATE.INITIAL;
    // place the target at a random position
    targetPosition = getTargetPosition();
  }

  // If ending a turn, we check the component state
  // to see if we have registered a successful click
  // on the target
  if (key === "COOLDOWN") {
    if (turnState === TURN_STATE.SUCCESS) {
      successCount += 1;
    }
  }

  // Get config for this phase
  const phase = PLAY_PHASES[key];
  // update UI
  countdown = phase.countdown;
  showTarget = phase.showTarget;
  // schedule next phase
  timeout = setTimeout(
    () => startPhase(phase.next),
    Math.max(phase.minDuration, phase.durationRatio * $gameSpeed)
  );
}

Note that the countdown and showTarget variables are reactive, and tracked by Svelte. When we update their value, Svelte does its reactivity magic and updates the view. If we were in React land, we could probably use useState and update these state variables with:

const [countdown, setCountdown] = useState();
const [showTarget, setShowTarget] = useState();

const startPhase = (key) => {
  /* … */
  setCountdown(phase.countdown);
  setShowTarget(phase.showTarget);
  /* … */
}

Anyway, that’s how it works right now. Doing a bit of reading on statecharts and this introduction to state machines by David Khourshid on CSS-Tricks, it looks like I was close enough to a hand-rolled finite state machine. Yay me!

Getting comfortable with XState

Originally I wanted to open the XState docs in one tab, my current code on another screen, and just start converting stuff and figuring things out along the way.

Turns out that XState is a bit more complex than I thought. It’s not very hard, but there are a few concepts to learn: machines, services, actions, actors maybe? Is that more than I bargained for?

So, change of plan: before tacking the gameplay state, I want to make sure I’m comfortable with basic usage of XState and how to integrate it in Svelte.

Let’s start with a simpler bit of state then; I picked the main navigation state.

The game has 3 different screens:

"setup" (configures a game’s parameters before starting)
"playing" (plays the game’s main loop)
"results" (shows your points)

We start at the Setup screen:

The information for “which screen should we show?” is stored as a string in a Svelte store (a reactive variable that can be shared between components). It’s defined like this:

import { writable } from "svelte/store";

export const screen = writable("setup");

And in our root component we have a kind of switch statement where we pick which component to render:

<script>
  import { screen } from "../store.js";
  import Setup from "./Setup.svelte";
  /* … */
</script>

{#if $screen === "setup"}
  <Setup />
{:else if $screen === "playing"}
  <Playground />
{:else if $screen === "results"}
  <Results />
{/if}

To navigate between screens, we change the store’s value:

function startPlaying() {
  $screen = "playing";
}

Note: we’re using the dollar syntax, $screen, to access the value of the screen store in a reactive way (read more in the Svelte docs).

Converting this to XState is probably overkill, but using XState we can enforce a few rules:

Restrict the state to known values (e.g. make it impossible to set the current screen to "whoops" if that’s not a known state).
Specify relationships between states, e.g. only the "playing" state can go to the "results" state.

Let’s create a basic XState machine to keep track of the current screen:

// src/state/screen.js
import { Machine } from "xstate";

const screenMachine = Machine({
  id: "screen",
  initial: "setup",
  states: {
    setup: {},
    playing: {},
    results: {}
  }
});

Right now our 3 states have no rules or features attached, but we’ll flesh them out later.

Now if I’m understanding correctly, a XState “machine” is a static set of rules, but it is itself stateless: it doesn’t have a current state or a state history. To hold a “current value”, we need a XState “service”:

// src/state/screen.js
import { interpret, Machine } from "xstate";

const screenMachine = Machine({
  id: "screen",
  initial: "setup",
  states: {
    setup: {},
    playing: {},
    results: {}
  }
});

const screenService = interpret(screenMachine);
export default screenService;

This feels a bit like a class-vs-instance thing. We have a kind of blueprint (a class, or a machine in this case) which is used to create a structure that holds data or state (instance/service). Not sure if that makes sense, this is just how it looks to me. 😅

Let’s update our top component to use the screenService instead of the screen Svelte store:

<script>
  import screenService from "../state/screen.js";
  import Setup from "./Setup.svelte";
  /* … */
</script>

{#if screenService.state.matches("setup")}
  <Setup />
{:else if screenService.state.matches("playing")}
  <Playground />
{:else if screenService.state.matches("results")}
  <Results />
{/if}

This looks good to me, but alas! it fails. We get a blank screen. What’s going on in the Console?

Warning: Attempted to read state from uninitialized service 'screen'. Make sure the service is started first.

Indeed, when we run console.log(screenService.state), that’s undefined! Looks like we have to start the service to make it go to its initial state ("setup"):

const screenService = interpret(screenMachine);
screenService.start();

That works! I’m seeing the Setup screen, and if I change the initial value in stateMachine and reload the page I can see the Playground or Results components — though Results are broken, because the result data is missing.

So we have a navigation state. Now we need some navigation actions, i.e. a way to go from one state to the other.

XState handles that with events, which are defined on the machine. It looks like, by convention, state names are lowercase and event names are uppercase, so we’ll follow that.

const screenMachine = Machine({
  id: "screen",
  initial: "setup",
  states: {
    setup: {
      on: {
        START_PLAYING: "playing"
      }
    },
    playing: {
      on: {
        SHOW_RESULTS: "results",
        SHOW_SETUP: "setup"
      }
    },
    results: {
      on: {
        SHOW_SETUP: "setup"
      }
    }
  }
});

With that setup:

to start playing, we must be on the "setup" state and send a "START_PLAYING" event;
the "playing" state can go to the "results" state or to the "setup" state (e.g. if the user wants to interrupt a game);
the "results" state can only go back to the "setup" state, to start a new game.

And we could add events to handle more features. For instance, if we want to add a “Try Again” button on the results screen that starts a new game with the same parameters, we can add: PLAY_AGAIN: "playing".

We send events with the service’s send method. Let’s start with the Setup page. It listens to the form’s "submit" event and navigates, so we’ll update that:

<!-- src/components/Setup.svelte -->
<script>
  import screenService from "../state/screen.js";

  function onSubmit(event) {
    event.preventDefault();
    screenService.send("START_PLAYING");
  }
</script>

<form on:submit={onSubmit}>
  <!-- … -->
</form>

And… it doesn’t work.

Nothing in the Console. Hmm, how else can we debug what’s happening? We have two options:

add a bunch of console.logs;
use the Redux DevTools browser extension and tell XState to send it state information.

Looking closer, once we call send("START_PLAYING"), here is what happens:

The event is dispatched correctly on the screenService.
The screenService’s state changes to "playing".
But nothing in Game.svelte reacts to this change.

We need to make Svelte aware of changes in the screenService!

Thankfully, XState’s docs have a recipe for using XState with Svelte, which shows two solutions. My favorite is to treat the XState service as a Svelte store, which is possible because a XState service has a subscribe method that fulfills Svelte’s “store contract”.

In short, that means we can use $screenService as a reactive version of screenService.state. Our code becomes:

<script>
  import screenService from "../state/screen.js";
  /* … */
</script>

{#if $screenService.matches("setup")}
  <Setup />
{:else if $screenService.matches("playing")}
  <Playground />
{:else if $screenService.matches("results")}
  <Results />
{/if}

And with that, navigating between screens finally works!

Tackling the main game loop

Okay, that wasn’t super simple and there was a bit of a learning curve, but we finally know how to make a basic state machine with XState. Should we create one for the PLAY_PHASES structure we described earlier? As a reminder, it looked like this:

export const PLAY_PHASES = {
  START: {
    next: "COUNTDOWN_3"
  },
  COUNTDOWN_3: {
    next: "COUNTDOWN_2"
  },
  COUNTDOWN_2: {
    next: "COUNTDOWN_1"
  },
  COUNTDOWN_1: {
    next: "TURN"
  },
  TURN: {
    next: "COOLDOWN"
  },
  COOLDOWN: {
    next: "TURN"
  }
};

The first-level keys are our states, and we have just one event, "next", telling us what the next state should be.

As a XState machine, this could look like:

const playMachine = Machine({
  id: "play",
  initial: "start",
  states: {
    start: {
      on: { NEXT: "countdown_3" }
    },
    countdown_3: {
      on: { NEXT: "countdown_2" }
    },
    countdown_2: {
      on: { NEXT: "countdown_1" }
    },
    countdown_1: {
      on: { NEXT: "turn" }
    },
    turn: {
      on: { NEXT: "cooldown" }
    },
    cooldown: {
      on: { NEXT: "turn" }
    }
  }
});

While working on the XState refactor for this article, I realized that the 4 first states (from "start" to "countdown_1) represent a single countdown animation with 4 “stages”. To simplify the state logic a bit, I decided to turn those states into a single “countdown” state, and moved the animation logic to a CSS animation in the Countdown component. This simplifies our machine:

const playMachine = Machine({
  id: "play",
  initial: "countdown",
  states: {
    countdown: {
      on: { NEXT: "turn" }
    },
    turn: {
      on: { NEXT: "cooldown" }
    },
    cooldown: {
      on: { NEXT: "turn" }
    }
  }
});

Another problem to solve: how do we start this playMachine at the right time in our app’s life?

One solution would be to create and start a new playService every time that the Playground component is mounted.

Another option is to merge our screenMachine and our playMachine in one hierarchical state machine. The states from our playMachine can be children of the playing state.

(You don’t need to have a single machine for your whole app’s state. It’s perfectly okay to have several machines for several features or screens. But since the game loop only exists in the "playing" screen, a single hierarchical machine makes sense here.)

Our merged machine will handle most of the game’s state, so let’s call it gameMachine:

// src/state/game.js
import { interpret, Machine } from "xstate";

const gameMachine = Machine({
  id: "game",
  initial: "setup",
  states: {
    setup: {
      on: {
        START_PLAYING: "playing",
      }
    },
    playing: {
      on: {
        SHOW_RESULTS: "results",
        SHOW_SETUP: "setup"
      },
      initial: "countdown",
      states: {
        countdown: {
          on: { NEXT: "turn" }
        },
        turn: {
          on: { NEXT: "cooldown" }
        },
        cooldown: {
          on: { NEXT: "turn" }
        }
      }
    },
    results: {
      on: {
        SHOW_SETUP: "setup"
      }
    }
  }
});

const gameService = interpret(gameMachine);
gameService.start();

export default gameService;

This machine can be visualized using XState’s interactive visualizer:

If you try clicking on the event names in the visualization, you’ll see that:

We start at the setup state.
We can go to the playing state, which starts at its playing.countdown state.
In the playing state, we can go to playing.turn, then to playing.cooldown, then to playing.turn again, and we stay there in a loop.
We can go from the playing state forward to the results state, or back to setup.

Pretty good. Now, in the Playground component we need to react to changes in the game state to:

show or hide the countdown;
show the square target with a new position, and increment the turn count;
hide the square target.

Most of that logic happens in the startPhase function we described earlier. Our previous logic relied on calling startPhase recursively, with a delay. Schematically, it looked like:

import { onMount } from "svelte";
import { PLAY_PHASES } from "./constants.js";

onMount(() => {
  startPhase("countdown");
});

function startPhase(key) {
  // 1. Perform side effects (update the UI):
  // …
  // 2. Set a timer for the next phase:
  const nextKey = PLAY_PHASES[key].next;
  const duration = PLAY_PHASES[key].duration;
  setTimeout(() => {
    startPhase(nextKey);
  }, duration);
}

With our state machine, we’re going to split this in two:

We’re going to call startPhase every time the gameService’s state changes. For that, we need to subscribe to updates.
At the end of a game phase (in our setTimeout function), we’re going to send a "NEXT" event instead of calling startPhase directly.

import { onMount, onDestroy } from "svelte";
import gameService from "../state/game.js";
import { gamePhaseDurations } from "../state/setup.js";

// Listen to state transitions
onMount(() => {
  gameService.onTransition(startPhase);
});
onDestroy(() => {
  gameService.off(startPhase);
});

function startPhase(state) {
  // state.value looks like: {playing: "countdown"}
  const key = state.value.playing;
  // 1. Perform side effects (update the UI):
  // …
  // 2. Set a timer for the next phase:
  const duration = $gamePhaseDurations[key];
  setTimeout(() => {
    gameService.send("NEXT");
  }, duration);
}

And we’re done!

The actual logic is a bit more complex — it handles things like counting turns and points, sending a send("SHOW_RESULTS") event after 20 turns, etc. — but this is a good representation of how the state machine powers the game loop.

My impressions of XState

I found XState to be more complex than I had anticipated. Granted I knew next to nothing about state machines and statecharts. But the learning curve was a bit steep, I think, for two reasons:

There’s a bit of jargon to wrap your head around.
XState has a lot of features, and it’s easy to get lost asking yourself if one feature is essential for your use case or not, or that other feature, or maybe this one…

At first I tried diving in for a couple hours, writing some code, expecting to know my way around the concepts and library in that time-frame. That didn’t work at all.

So I took a step back, actually read some of the docs, watched a couple videos and read some articles, before diving back in with a smaller scope: porting the navigation state.

After that, porting the main game loop to XState was still a lot of work, but mostly because my own UI logic had a lot of parts to account for, and changing some of its state management meant I had a lot of loose ends to reconnect.

Me trying to make Playground.svelte work again.

While I initially wanted to spend 1–2 days learning XState, I ended up spending close to a week learning and refactoring, and then 2–3 days writing this post (I’m a slow writer).

There were a few more things I wanted to try, but had to drop for lack of time:

Statecharts can have “extended state”, called “Context” in XState. It looks like it would make sense to store the points and turn count in the gameService’s context.
With the turn count stored in the gameService, the branching logic for going to the next turn or ending the game could be part of the state machine as well (instead of the Playground component’s state and the startPhase function). Probably using Guarded Transitions.
I tried putting the playing phase duration config on the state machine, using state meta data, but it was awkward and created other issues for that use case.

Would I use XState on a new project? Definitely. Being able to reason about an app, screen or feature’s state by reading a statechart definition is invaluable, and the visualizations are a nice touch. And while I haven’t used most of the advanced features, reading up on them makes me confident that I could handle complex use cases.

A word of caution though: when bringing XState to a team project, I’d factor in the learning curve for everyone involved. It’s probably worth doing some basic training, at least.

Laptop fundraiser: complete!

2020-11-12T09:00:00+01:00

A couple months ago I asked if people wanted to gift me money to buy a laptop, and besides a tweet or two I haven’t written an update on what happened. It went super well!

In a couple days we were around 85% of the €1350 goal, and a few days later we were at 100%.

I’m super thankful to everyone who contributed financially, and to everyone who had nice words about my work on Firefox DevTools. Special thanks to Harald Kirschner, your compliments make me blush and I’m definitely putting you up as a reference on my CV!

Another special thanks goes out to Jan Odvarko, who asked Mozilla if they had a used laptop lying around. Turns out they did! So in September I got a package from Mozilla Paris with a 15″ 2017 Macbook Pro. Thanks a bunch folks!

We also got a second cat, pictured above. Quad-paw 4.1 Megafloof cuddler, very little memory. (Not a replacement for first cat.)

So what am I doing with the money? I’m still buying a laptop, as intended. Because I’m finishing my current contract and returning the work computers we’ve been using at home since this summer, we’ll need a second computer.

The 2017 MBP is great, but its keyboard has Sticky Key Syndrome, so for now it can only be used for real work as a desktop (with an external keyboard); there’s a repair program for the butterfly keyboards, but so far it’s been impossible to get an appointment where I live due to the pandemic.

I also wanted something more portable, and hesitated a bit: cheaper Windows or Linux ultrabook, Chromebook, Surface, iPad, Macbook Air maybe? In the end, I followed the news about Apple’s upcoming ARM laptops, and decided to get a new Macbook Air with the M1 chip.

I’m not much of an Apple fan¹, but I’m kinda excited about this one. I’m going to try to use it as a work computer and see how it goes, while we try to use the larger MBP for family needs². It’s probably not the most sensible configuration, but I felt like trying that!

I tend to think that all operating systems are terrible and computers were a mistake, but macOS or decent Linux/Gnome configs are the least frustrating options for me. ↩
Watching horror movies in bed. ↩

A quick look at privacy-focused analytics for small sites

2020-09-25T00:00:00+02:00

What’s the point of analytics?

This blog has been analytics-free since 2013. Before that I used Google Analytics, then removed it as Google became too pervasive for my taste. I wasn’t looking at stats much, anyway.

Was I getting sweet sweet views? Once in a while I’d get an email with comments or questions, and some of my articles would get shared a few times on Twitter; At times I’ve used Twitter’s search to check if an article was getting traction.

Perhaps that is vain. But if I’m going to spend whole days writing and editing, I need something to feed into my brain’s reward system. It’s a bit out of whack, my brain. Needs a gentle push on the regular.

So I ended up looking at analytics tools that:

Are privacy-conscious, and don’t feed information to Google, Amazon, Microsoft or Palantir.
Tell me which pages are the most visited, because it can feel nice, and it tells me which old articles may benefit from updates.
Are cheap enough.

A lot of paid analytics services have an entry price for monthly pageviews below a 10k limit. I’ll be looking at the price above that as well, because historically my site has been slightly above that limit (though it’s probably lower than that now).

GDPR and Do Not Track

Cookie banners are an ugly and tacky distraction, and I’d rather have zero analytics data than put one up.

I’m hoping that if a service that doesn’t use user ids — not storing IP addresses, no fingerprinting, no cookies or localStorage, etc. — then it doesn’t count as tracking or as requiring user consent.

Sounds reasonable to me, but don’t take it as legal advice that it’s okay to do that; especially on sites with user accounts or user data entry or payments.

One thing I’m not sure about: the DNT (Do Not Track) HTTP header. Should I disable analytics for every visitor with DNT: 1? If the analytics is private and minimal enough, does it count as “tracking”? I’m tempted to ignore it, as long as I’m using a private enough analytics service. But maybe that’s dropping the ball on a commitment to privacy and respecting user intent?

I was wondering if some browsers where sending a DNT: 1 header by default. Looks like virtually no browser is doing that. You’re most likely to get this header from Firefox users, if they set their Tracking Protection level to “Strict” (not the default level). Brave has a fairly hidden preference. Safari doesn’t support DNT at all; I think they removed support at some point, citing inefficiency and a fingerprinting risk.

A random collection of tools

Not a review. I haven’t tried most of these.

Server logs

The received wisdom is that server logs are not reliable since, unlike client-side analytics, they record a lot of bot requests. (There’s nothing special about client-side analytics that filters out bots, but the majority of bots don’t run full browsers to make HTTP requests, because it costs a lot more to do that.)

Still, it was interesting to see Netlify take a stab at building analytics out of server logs, and maybe they got it right enough to be useful. If you’re on Netlify and can pay $9/month, do check it out.

Matomo (formerly known as Piwik)

The big, old, PHP-and-MySQL open source alternative to Google Analytics. Available as a paid hosted service too, but at a price point too steep for hobbyists (€19/month). Does a lot out of the box, and has plugins for more.

Looks like an option, and my web host has an instance already set up. But maybe not simple or minimal enough? It looks like they have a lot of settings or steps to follow to increase user privacy or avoid having to show a cookie consent banner.

Fathom

Best known of the handful of small analytics tools that cropped up recently, Fathom starts at $14/month. Looks nice. I’m a bit concerned that the first item on their Features page is “Bypass ad-blockers”.

Looks like the open-source version, was set aside when the Fathom team focused on building a commercial offer.

Simple Analytics

Privacy focused, built by a 2 person team, starts at $19/month. They do have instructions for bypassing ad-blockers, looks like a common request. They’re European based and do seem to focus on GDPR compliance though; their What We Collect page is a good read.

They seem to have nice features, plus a public roadmap. Overall Simple Analytics tries to balance a strong privacy focus with catering to businesses and marketeers’s needs.

Plausible

Initially built by a developer who wasn’t convinced by Fathom or Simple Analytics — though while they built Plausible it’s likely that those tools improved too. Now a two-person team.

I like that it focuses on bloggers and freelancers as a target market, and its pricing might be the most accessible yet: $12/month for 100k pageviews, and yearly billing gets you a nice 33% discount. Roughly half the price of the competition.

Plausible is also fully open-source (unlike Fathom), but its hosting requirements are a bit complex; this will probably rule out self-hosting for single users, but could be interesting for companies.

Friendly Analytics

Stylized as “🙂 Friendly”. Launched in March 2020, hosted in Switzerland, GDPR-compliant, etc. Looks like they’re based on Matomo, but with customs settings and maybe a custom UI? Not cheap: starts at €9/month, but for very few page views (5k max), so you’ll probably need the €19/month plan instead.

They’re an “Open Startup” and publish detailed revenue numbers on their blog. Could make for some interesting reading.

Metrical

Another 2-person team, this time from Italy. Does not track visits for users with a Do Not Track header. Currently free while in beta, and pricing is announced at $7/month or $50/year (for a 50k monthly pageviews limit).

I read about Metrical in this comparative review of Fathom, Simple Analytics and Metrical.

Goatcounter

An open-source, self-hostable analytics package written in Go (requires a SQLite or PostgreSQL database). Also available as a hosted service, with a generous free tier that should cover most small sites; when using the free tier, the developer recommends donating money to help the service stay up.

The app’s design is maybe a bit less appealing than others, but it has a nice “early Basecamp” vibe if that’s your thing. Goatcounter chooses to ignore DNT headers.

Umami

An open-source project built in 30 days by Mike Cao, Umami is a simple, self-hosted analytics app. The project was announced less than a month ago, but it has seen steady releases since then.

If you’re comfortable installing and running a Node.js app with a MySQL or PostgreSQL database, it could be a fun option.

Ackee

Another open-source, self-hostable project. Version 2.0 was published last month and requires the latest Node.js (Node 14) and a MongoDB database.

I tried the demo quickly, and it looks really good but I didn’t find it as usable as Umami (for example).

Shynet

A Python-based open-source project (self-hosted, requires a PostgreSQL database). Looks pretty good. Their recommandation:

Shynet isn’t for everyone. It’s great for personal projects and small to medium size websites, but hasn’t been tested with ultra-high traffic sites. It also requires a fair amount of technical know-how to deploy and maintain, so if you need a one-click solution, you’re best served with other tools.

Though that is probably true of all the new-ish, self-hosted solutions listed here.

Offen

An open-source web app that you need to deploy yourself (binary executable plus a database, SQLite by default). Offen has a different take on user privacy than all other services and software listed here:

Your site’s visitors must opt in to analytics.
Visitors can access the data that Offen collected about them, and can delete it.

End users get a view similar to what you get as a site administrator, but with only their own visits and pageviews in the data set. Try it out by visiting offen.dev, accepting tracking, then looking for the “Try as user” link.

What I’m picking

I’ve only had broad impressions of the different services and software packages so far. For a small business, I might go with Plausible or Simple Analytics. For this small blog, plans around $15–20/month are excessive, but Metrical and maybe Plausible might work.

I’m also considering giving Umami a try. It should run on my current web host, at no extra cost.

Update: I’ve been using Umami for three years now, and I like it.

A DevTools Retrospective: Or, Fund Me Maybe

2020-08-20T00:00:00+02:00

My 5 year old laptop won’t start up anymore. Plus my stupid son ate through the charger cable.

So my laptop died a few months ago and I’ve made do with my work computer instead, but recently I’ve considered buying a new one to not depend on work equipment.

In the past 2 years, I’ve also spent a lot of my time — including time off from my day job — to work on Firefox DevTools as a volunteer contributor. As my involvement in this project is coming to a close, I’ve been looking back and thinking: what if I got a small something out of it, beyond a bit experience, as a thank you?

So I’ve decided: I am asking you, kind reader, to consider chipping in to help me pay for a new laptop. I’m targeting something like a Macbook Air (€1200 with VAT) or the cheapest Macbook Pro (€1500), or a similar laptop with Windows or Linux. I’ve set up a Ko-fi page with a €1350 goal, and you can give anything you want, if you appreciate the work I did.

To be clear, I’m not in any financial hardship. I could buy a laptop without help, but I’ll appreciate it if I can cover most or some of the cost this way. Read on if you want more context on why I’m asking for contributions.

What did I do as a contributor?

I started contributing to Firefox DevTools in Spring 2018, initially to work on small UI details and land CSS fixes for the Inspector, Console or Network Monitor. Over two years I have:

Helped dozens of volunteers, Outreachy candidates and Google Summer of Code candidates get started with the DevTools codebase (usually over Bugzilla and Slack). I’ve also led or participated in code reviews.
Fixed 106 bugs of various sizes (from a few hours to week-long efforts).
Participated in many UX discussions to provide feedback and ideas.
Led a few design projects, including an icon refresh (shipped) and a redesign of the Settings page (accepted but not implemented).

One example: if you’re using Firefox DevTools on Linux, your experience may have improved overnight thanks to this simple CSS patch that fixed a lot of issues with font sizes and icon alignments; it took just a few lines of code, but days of investigation and tests!

I’ve worked remotely with Victoria Wang, Patrick Brosset, Nicolas Chevobbe, Harald Kirschner, Micah Tigley, Jason Laster, David Walsh, Yura Zenevich and many others.

I also participated in three Mozilla All Hands weeks, which were fun! (But they were also work, somewhat tiring, and it did require me to use up my job’s paid time off.¹)

On the visible side, here are some of the design-y work I’ve done. Click through to to see full-size images.

An overview of design documents I’ve worked on in my Figma “DevTools” project. It’s mostly icon work and small mock-ups to explain ideas.

A redesign of the DevTools tab icons, made to follow the 2017 Photon Design System guidelines. This was my most visible user-facing work.

I’ve worked on a redesign of the DevTools settings page, to break it up in more readable chunks. You can try out the HTML prototype (but do try it in Firefox, since it uses CSS Logical Properties not supported by Chrome and Safari at this time), and check out the repository.

Why am I asking for money?

Because I felt like it! 😁

Just to make it clear, I don’t think I’m entitled to money here. Nobody has to give me anything! (As a side note, if I was trying to crowd-fund payment for the time worked on DevTools, at 1-2 days a week for something like 18 months straight, that goal would be much higher than $1.5k.)

Asking for money now might sound strange, especially since I didn’t start contributing to DevTools with money in mind. I wanted to scratch some itches, and I was excited about having patches I wrote improving a UI used by hundreds of thousands. And I also wanted to help out so that we don’t end up in a Chrome monoculture for good.

But after 6-12 months of doing good work, I ended up thinking: I like the work and it seems to be useful, let’s get paid for it and do it full time!

Sadly I’m pretty bad at advocating for myself, and I never actually applied for a role. I did reach out to a few team members, but what I heard was that there was no budget for more people, beyond maybe short-term contracts (not an option for me at the time).

Then in the last year it became clear that Mozilla management didn’t see DevTools as a vital investment, and in 2020 reorgs and layoffs have strongly impacted DevTools.

So that was it. Combined with some frustrations about not being able to do or land some work on my side because I could not secure reviews or other help², I mentally called it quits.

What prompted me to ask random people for money was this tweet:

If you're worried about the future of #Firefox, #Gecko, #MDN and other projects from #Mozilla there's one way you can help: contribute.

I always hang out in our #Introduction channel, so if you feel like coding and want to help just ping me.

—@gabrielesvelto

I have some feelings about that.

We’re talking about doing free work here. If you want those projects to succeed, are worried they might not, and want to make an impact, that could mean a lot of free work. Is that work going to lead to significant financial loss? Maybe to burnout or an increased risk of burnout, if doing that work on top of a day job? Maybe a mix of both?

Meanwhile, this work is adding value to projects and products (especially Gecko and Firefox) that Mozilla Corporation derives money from. That money funds big compensations for the C-Suite, and salaries for engineers that surpass anything I ever earned in my own career³. That’s true for many other contributors too, of course, and is part of a wider criticism of open-source.

(And maybe talking about this just after the layoffs is ill-timed, but the layoffs are the reason why people are calling for a surge of contributions.)

Finally, as I replied on Twitter, if you want people to work for free you should provide some incentives, including psychological ones. For large projects like Gecko or Firefox, the technical complexity, specific processes and bureaucracy⁴ mean it’s hard to just “scratch an itch” and see results quickly. Instead, one incentive can be to ship fixes and features to tens of thousands or millions of users — an appeal that smaller projects can’t provide.

But to be able to do that and not waste your time, you will need support from the core team. So you need that team to not be fired, cut in half or otherwise scaled down. And you will need some confidence that once your efforts pane out and your work is ready to ship to users, the product will not have been discontinued (ahem, Firefox OS). And if we cannot guarantee that, because strategic decisions lie in the hands of unaccountable corporate management, should we really call for people to provide free work?

So I was thinking about all that, all those mixed feelings about open-source, and I ended up at: you know what, fuck it, I want some money too. My friends and family always tell me I’m super bad at valuing myself and asking for money, promotions or raises — so maybe I should break that cycle.

I’m asking for money. A symbolic amount, really, compared to the work I did, but still an amount that I can use for something practical.

If it works out, great, and if it doesn’t… eh. 🤷‍♀️

Update: the response to this has been super positive, and we made the goal in 4 days! I wrote this follow-up post, it has a cat picture too.

Mozilla shoulders all other costs of inviting volunteer to the Mozilla All Hands, including plane tickets, hotel rooms, catering, and expense stipends. I don’t have exact numbers, but the total cost for inviting a single volunteer three times is probably in the $10–15k range? ↩
For example, for the Settings page implementation, I was motivated to do a lot of the work but would have required mentorship or timely help. One developer also had ongoing work on that panel that he could share with me, but he was moved from the DevTools team to the Firefox for Android project. ↩
To be clear, I don’t have any issue with current or former Mozilla employees, especially the great people I’ve been lucky to work with. My point is that when taking a step back and looking at Mozilla or company-sponsored open-source projects in general, some people are getting compensated and others not, and maybe it should give us pause. ↩
It seems largely similar in Chromium or WebKit; it comes from the scope and reach of the project, not from Mozilla or Google being particularly bad at it. ↩

PHP code typing with Kirby CMS

2020-08-12T00:00:00+02:00

As I was updating this site and writing my previous post on Kirby CMS, I sometimes struggled to get good code autocompletion.

Kirby 3 is built with PHP 7 and uses type annotations extensively, but this often won’t be reflected in an IDE. This post explores why, and what workarounds you can use.

Why you might want completions

Unlike CMSes like WordPress and Drupal which come with default themes that generate HTML code for you out of the box, Kirby uses a very hands-off approach to building web pages. You can start from scratch and write your own PHP controllers and templates to render what you want, using Kirby’s PHP API.

That’s great if you want to build something bespoke. But it also means that you’re going to spend a lot of time looking at the reference documentation. Before you know it, you’re juggling between your code editor and 15 open documentation tabs.

That’s where code completion — sometimes called “intellisense” — helps. It lets you be a bit lazy and access a lot of that reference information directly in your code editor, as you type.

Ideally, when your editor sees a PHP variable like $page in a Kirby template, it should known that $page is an instance of the Kirby\Cms\Page class. And it should offer code completions and suggestions from that class. No need to check the docs!

Sadly, this doesn’t work out of the box with Kirby, in a few common situations.

Runtime magic

Kirby tries to be approchable for people who are not pro developers or PHP programmers. Its creator, Bastian Allgeier, is a designer and developer, and wants to cater to a wider audience of designers, webmasters, tinkerers, etc. So Kirby tries to do some magic things like:

Load templates (and controllers, if any) by file name. Follow the convention, and your code will run[^2].
Automatically inject variables in your templates and in your controllers.

This means that the template for a page of type 'article' can be named site/templates/article.php and be as simple as:

<h1><?= $page->title() ?></h1>
<?= $page->text() ?>

The downside of this approach is that your code editor has no information about this $page variable. It cannot know if it’s a string, a number, or an object (and what kind of object). Your editor might even warn you that this variable was never defined, and highlight it as an error!

Kirby controllers use a different kind of magic. Controllers are defined as functions returned by a script, such as site/controllers/article.php:

<?php
return function ($page, $site) {
  // Inject two new variables, $content and $articles,
  // in the 'article' template
  return [
    'content' => $page->text()->markdown(),
    'articles' => $site->find('blog')->children()
  ];
}

See the $page and $site parameters in the function? Kirby will look at the function’s parameter names and automatically provide an instance of the current page for a parameter named $page, of the Site object for a parameter named $site, etc.

This lets us ask for a few built-in objects in any order we want, for example:

return function ($site, $kirby, $page) { … }

But again, the downside is that this is magic happening deep inside Kirby’s own code, and your IDE will have no idea what those variables are. No code completion for you!

Adding type hints and annotations

I’ve found a couple solution to this problem.

For controllers, since we’re using function parameters to “request” specific objects, we can add type declarations using PHP’s syntax:

<?php // site/controllers/article.php
use Kirby\Cms\App;
use Kirby\Cms\Page;
use Kirby\Cms\Site;

return function (Site $site, App $kirby, Page $page) {
  …
}

Note that for backward compatibility with Kirby 2, Kirby 3 provides shorter class aliases, including Kirby (for Kirby\Cms\App), Page and Site. Personally, I like using the longer, more explicit class names.

Now, let’s talk about templates. Templates will receive variables defined by Kirby (like the $page and $kirby objects), and any other variable you return in a controller.

Sadly there is no way in PHP to declare “hey I know that this $page variable exists in this context, and I’m going to tell you what it is”. Unlike in TypeScript where you could write something like:

declare var page: Page;

The good news is, there is a widely supported way to declare variable types in PHP, using the PHPDoc @var tag:

<?php // site/templates/article.php

/** @var Kirby\Cms\Page $page */

<h1><?= $page->title() ?></h1>
<?= $page->text() ?>

PHPDoc comments are not a native PHP feature, so declaring a type this way won’t affect how your code runs at all. But most code editors and IDEs with good PHP support will understand this special comment syntax, and will read it as “there is a variable $page in the current scope, and it’s an instance of the Kirby\Cms\Page class”.

And if you have created a Page Model for this template, you can declare the type using the page model’s class name, for example:

<?php // site/models/article.php

class ArticlePage extends Kirby\Cms\Page {
  public function getArticleBody(): string {
    if ($this->content()->body()->isNotEmpty()) {
      return $this->content()->body()->markdown();
    }
    return '';
  }
}

<?php // site/templates/article.php

/** @var ArticlePage $page */

<h1><?= $page->title() ?></h1>
<?= $page->getArticleBody() ?>

Making sure your editor has good PHP support

Finally, if you want to see code completions in your editor or IDE of choice, type annotations may not be enough. You also need an editor or IDE with good PHP support!

Personally, I use PhpStorm when writing more than a couple lines of PHP, because it just works. The downside is that it’s paid software, and not cheap.

I’ve also tried using Visual Studio Code with the PHP Intelephense extension. It works well, but do follow the “Quick Start” steps in the extension’s page.

There are a few other options, such as NetBeans, but I haven’t tried them out.

Where should you put logic code in Kirby CMS?

2020-06-01T12:00:00+02:00

This blog has been running on Kirby CMS for 6 years. And I’ve been migrating it from Kirby 2 to Kirby 3, which is taking a bit of work.

I like to do a bunch of custom things with my site’s structure and content, so instead of relying on “the Kirby way” I’m implementing a bunch of stuff myself.

That means writing PHP code that queries and manipulates data — often called “logic” code by programmers — and I’ve struggled a bit with understanding where I can put this code in the project.

Logic in templates? Sure.

One thing I like about Kirby is that it’s powerful and doesn’t require you to jump through hooks. So if you want to put all your logic in a template file, you can!

In the following example, we’re querying all the child pages of the current page, keeping the “Published” ones and sorting them by date, then listing the latest 20 pages.

<?php // site/templates/blog.php
$posts = $page->children()
  ->filterBy('isPublished', true)
  ->orderBy('date', 'desc')
  ->limit(20);
?>

<h1><?= $page->title() ?></h1>
<ul>
<?php foreach($posts as $item): ?>
  <li><?= $item->title() ?></li>
<?php endforeach; ?>
</ul>

(This template would be used for any page which has the 'blog' content type, meaning its content file is something like content/my-page/blog.txt. See “Creating pages” in the Kirby documentation for more information.)

Or in controllers, maybe?

Putting logic in template is great for people just getting started with Kirby, or people who may not be professional programmers. But if you want to separate your logic from the template, you can move it to a controller function:

<?php // site/controllers/blog.php

return function ($page) {
  $posts = $page->children()
    ->filterBy('isPublished', true)
    ->orderBy('date', 'desc')
    ->limit(20);
  return ['posts' => $posts];
};

But what if you want to share some logic between different templates, controllers or page types? It would be awesome if you could call something like $page->getPublishedChildren(), from anywhere.

Kirby offers two ways to do that:

Creating a page method

Page methods apply to all $page objects, regardless of page type. They’re a slightly older technique in Kirby, and in Kirby 3 you need to declare a plugin to add page methods:

<?php // site/plugins/my-plugin/index.php

Kirby::plugin('me/my-plugin', [
  'pageMethods' => [
    'getPublishedChildren' => function() {
      return $this->children()
        ->filterBy('isPublished', true)
        ->orderBy('date', 'desc')
        ->limit(20);
    }
  ]
]);

There are a few downsides to page methods:

Having to register a plugin is a bit awkward.
If you’re using PHP types and intellisense in your editor, your editor has no way to know that $this in your page method is an instance of Kirby’s Page class. That means you don’t get code completions and validation in your editor.

Creating a page model

The newer option is to use page models, which are defined as PHP classes extending Kirby’s Page class.

<?php // site/models/blog.php

class BlogPage extends Page {
  public function getPublishedChildren() {
    return $this->children()
      ->filterBy('isPublished', true)
      ->orderBy('date', 'desc')
      ->limit(20);
  }
}

This looks a little bit cleaner to me, mainly because we avoid creating a plugin. And since we’re extending the Page class, now our code editors will know what methods the $this object has¹.

And reading the Kirby documentation, and especially the Guide, it looks like Page Models are the preferred mechanism for adding functionality to page objects.

But they have one big downside: they only apply to a given page type, the 'blog' page type in this example. If you try to use $page->getPublishedChildren() on a page with a different type, you get an error.

Are we forced to use Page Methods in a plugin to share functionality between pages? Well, maybe not.

Creating a default page model

Our page models already inherit from Kirby’s Page class. What if we added one more class to that hierarchy?

Let’s start by moving our method to a new class, which we’ll call DefaultPage. Ideally we should pick a name that doesn’t match a page type (meaning we don’t have pages with a content file named default.txt).

<?php // site/models/default.php

class DefaultPage extends Page {
  public function getPublishedChildren() {
    /* ... */
  }
}

Then we can create a class for our 'blog' page type, which extends DefaultPage:

<?php // site/models/blog.php
require_once 'default.php';

class BlogPage extends DefaultPage {
  // Add methods specific to the 'blog' type
}

Note that we have to require default.php explicitly to load the DefaultPage class, because Kirby won’t load it automatically since it doesn’t match a real page type.

If we add a new page type, we can create an empty page model that inherits from DefaultPage, and it will inherit the same shared methods.

<?php // site/models/article.php
require_once 'default.php';

class ArticlePage extends DefaultPage {}

Fair warning: this means that to fully emulate a global “page method”, we have to create a page model for every single page type we have!

If that’s too verbose, your options are:

Going back to using the page method technique;
Upvoting this feature request.

Happy coding!

At least if we’re using a code editor with good support for PHP, like PhpStorm; in my experience VS Code was too limited out of the box, and I couldn’t figure out which plugins to try to improve that. ↩

A short history of body copy sizes on the Web

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

It’s hard to pick a font size that is just right, especially as you try to adapt to different screens and scenarios. Looking at the recent history of how we got here can give us some perspective.

When I started working on Web stuff around 2005, there were two extremely popular font styles for body copy:

10px Verdana;
11px Arial.

Those two styles appeared on maybe 90 percent of professionally built sites, to be seen by users on IE5, IE5.5 and IE6 on Windows XP and earlier versions. They also looked similar, thanks to heavy font hinting, lack of font smoothing or sub-pixel rendering, and the fact that Verdana has a bigger x-height so 10px Verdana was roughly equal to 11px Arial, only with slightly wider letters.

Ten and 11 pixels may seem puny today, but in the early 2000s that was deemed readable for two reasons:

the 800×600 and 1024×768 screens of the late 1990s and early 2000s had biggish pixels, so the result was on the small side but not as small as it might look today;
designers and their clients were accustomed to 9, 10 and 11 point sizes for body copy in print (books, magazines, leaflets…), and the prospect of using bigger values felt like shouting at readers.

With relatively little experience of the Web as an autonomous medium, graphic designers and marketing departments relied on previous knowledge — from e.g. QuarkXPress and Microsoft Word. “How do I translate this point size, which works in my leaflet or magazine ad, to a HTML size?”

Of course, there is no way to reliably translate typographic points to pixels, because pixels don’t have a universal physical size. Screens have different pixel-per-inch ratios. The original Macintosh had a 72ppi screen (or perhaps 68ppi?¹). Twenty years later, in 2004, screens in the 80–90ppi range were common. A few years laters, pixels had gotten a bit smaller, and screens were often in the 90–120ppi range, while most iPhones had a 160ppi resolution². Despite the popular misconception, and even before the Retina transition started, the Web’s resolution was not 72ppi; it never was a single thing.

However, we don’t need to work out the exact points-per-inch resolution of every device to make sensible design choices. Trying things out should always trump dpi, ppi, Retina, or even pixel counts.

In November 2006, iA’s Oliver Reichenstein ran a simple experiment: he compared a magazine’s body copy at arms’ length and a typical site’s body copy at a common, eye-to-desktop-screen distance. The website’s text looked much smaller. Oliver argued for setting the body copy to the browser’s default, or 100%, which by convention is 16px in common browsers. In 2006, and even a few years later, it was a revolutionary proposition. Web designers and clients thought it was extreme. Five years later, we still had to fight for the death of 11px body copy (example, in French).

Text that is too small takes more time to read. Users may have to lean towards the screen, hold mobile devices closer, squint, or just concentrate more. As designers and developers, we strive to not ask for such extra effort from people who use or read our work.

On average, online text got bigger — at least in nominal pixel sizes — in the late 2000s and early 2010s. The exact reasons why are anyone’s guess, so here’s mine:

the medium’s matured, thanks to arguments such as the one spelled out by Oliver Reichenstein;
text in the 10–12px range looked tiny on the iPhone and other early smartphones (resolutions in the 150–200ppi range).

I remember web designers and developers leading the way with blogs, professional news sites and the occasional client project set in “bigger” sizes in the 14–18px range. This evolution seeped into generalist news sites, one high-profile redesign after the other; nowadays, theguardian.com has 1.0625rem (17px) text with 1.5 line-height, nytimes.com used 17px font-size and 26px line-height circa 2017, and in 2019 it went up to 20px font-size and 30px line-height on wide screens; body copy in the 18–21 pixel range is common (Medium, bostonglobe.com, newyorker.com, liberation.fr…).

Those numbers only mark a point in time. Back in 2003, 12px Arial might have been a generously big, very readable option for that majority of users on 800×600 screens with font smoothing turned off. The feeling that the browser’s default font-size was too big, which was very present when Oliver’s article was published in 2006, was partly a cultural thing, but it had some technical reasons as well. Likewise, we’ve started to feel that 16px is rather small for all but the smaller screens, again for a combination of reasons.

Then there is the very big body copy trend. In April 2012, influential web designer Jeffrey Zeldman redesigned his site with 24px Georgia body copy (and 32px for the opening paragraph of each post). Many fellow designers were puzzled, and some complained that the design was hard to read or reported having to zoom out on laptops or desktop computers to be able to read comfortably. Still, that design lasts today. Other designers have used similar sizes, e.g. Trent Walton stated his preference for 20–24px text (or 125–150%).

The most recent example of that trend is Jeremy Keith’s Resilient Web Design online book. Jeremy uses a CSS lock³ to vary the font size depending on viewport width, between two boundaries: 100% and 250%. At 320px, you get (with default browser settings) a 16px font size. At 1600px, you get 40px text. Obviously this is a design choice, and I recon that — similar to what Trent Walton described — the intended effect for laptop and desktop use is that readers lean back and read with their faces away from the screen rather than leaning towards it. It’s a design that invites taking your time instead of skimming through the text.

While that design makes for a good reading experience on smaller screens (especially smartphones and tablets, in my tests), I find it difficult on larger screens. The main issues I have with it are:

Seeing very few lines of text at a time. For instance, 10 lines of text on a 13 inch laptop. I have some level of attention deficiency when reading, and this setup removes a lot of visual context when I try to scroll and read; I generally try to fight the attention deficiency by selecting every other paragraph I’m reading, but when the design only shows one or two paragraphs at a time, that doesn’t help.
Each line of text is physically wide, requiring the reader’s eyes to span a wider angle than usual. This could have two undesired effects: readers might end up doing more fixations to read the same line of text (e.g. 3–5 instead of 2–4); and in more extreme examples, the wider eye movements could cause eye strain or fatigue.

Let’s say someone is seating in a sofa with a laptop on their lap, and currently reading an article. And let’s suppose that for this person in this setting with their own preferences and current level of fatigue etc., there exists an ideal font size for reading whatever text they’re reading. For instance, it could be 22px.

The reading process involves saccades and fixations. On each fixation (which can span a quarter of a second), they are only seeing a small portion of text in focus:

Look, I’m no scientist, so I’m hoping that’s actually representative of the real thing but take it with a spoonful of salt okay?

Now if the same text was quite bigger, but the other parameters (like the eye–screen distance) didn’t change, I’m guessing the result would look like this:

With the focus area staying the same size, and bigger text, I suspect that the eye can discern fewer letters correctly on each fixation. This is why my hypothesis is that for really big text (like Resilient Web Design’s 250% body copy on wider screens), readers will need to use more eye fixations to read the same text, and might lose in reading speed and experience fatigue sooner. I don’t have the skills needed to test this hypothesis, but I’d be wary of the very big text trend.

Personally, I favor more limited tweaks in font size. I like starting with a 100% basis for small screens, bump it for large phones or tablets (say, 110% or 115%), and maybe go up to 125% on laptops and larger screens. Then I tweak those values depending on the font I’m using, the look I’m going for, and what I’ve seen in testing on a variety of devices.

I’m also sad that we’re somehow chasing after device makers, operating system and browser developers, and trying to tweak font sizes every other year to adapt to what is out there in the market. The very concept of raising font size a bit depending on the screen width should raise eyebrows. Isn’t it the device’s job to make sure that font-size: 100% is readable?

In theory, CSS pixels should match a “reference pixel” defined as an angle of vision:

The reference pixel is the visual angle of one pixel on a device with a pixel density of 96dpi and a distance from the reader of an arm’s length. For a nominal arm’s length of 28 inches, the visual angle is therefore about 0.0213 degrees. For reading at arm’s length, 1px thus corresponds to about 0.26 mm (1/96 inch).

But this rule can only be followed if hardware makers, operating system and browser developers all collaborate towards that goal, which is rare enough. Especially since hardware vendors are more interested in selling screens optimized for video resolutions (“1080p”, “4K”), even when it makes the whole UI awkwardly small.

In theory again, browser makers should be able to change the 16px default font size to adapt to modern devices. But too much existing content relies on this default size not ever changing.

And so, we guess; we test; we tweak.

Whether technically correct or an approximation (my own calculations show a resolution of 68dpi), the “72dpi” resolution allowed designers to easily transpose point sizes to pixel sizes. Since there are 72 typographic points in an inch, at 72dpi each pixel is exactly one point. ↩
Retina displays didn’t change the “system point per inch” resolution, instead each system point was mapped to a 2×2 square of physical pixels. Since the CSS px unit works similarly as system points on those devices, and doubling the physical pixel resolution did not impact the size of HTML text, I skipped talking about resolutions measured in physical pixels (e.g. 320ppi) altogether. ↩
A Responsive Web Design technique that lets you transition smoothly between two property values when the screen gets smaller or bigger technique. First implemented in CSS by Mike Riethmuller, and developed further by Tim Brown. See The math of CSS locks for details. ↩

Et tu cliques cliques cliques, à côté du bouton ♫

2019-12-24T00:00:00+01:00

Que ce soit à la souris ou sur un écran tactile, un pourcentage de nos clics tombera à côté de la cible, voire sur le bouton voisin. C’est un peu frustrant, mais n’est-ce pas une fatalité ? Regardons ça de plus près.

Par exemple, vous avez forcément croisé la fameuse pop-up d’inscription à une indispensable newsletter :

Bien planquée dans le coin supérieur droit, une petite croix : le bouton de fermeture. Alors on se dépêche, vite on clique, et rien. Quoi ? Zoomons un peu pour voir ce qu’il se passe.

Dans sa grande bonté, le/la designer a dessiné une icone de 8 pixels de côté. Puis, lors du développement, l’intégrateur ou la développeuse ne s’est pas posé de question et a utilisé une image de 8 pixels de côté également, sans réserver un espace cliquable plus grand.

Et maintenant, troisième étape de notre histoire, l’utilisateur·trice clique à côté. Alors on réessaye, parce qu’on n’a toujours pas l’intention de s’inscrire à cette newsletter. En se méfiant, après ce premier échec et un début de frustration.

À la souris, il faut ralentir considérablement et amener le pointeur bien au dessus de l’icone, et surveiller si la flèche se transforme en main ou si un autre changement visuel signale que là, c’est bon, on peut y aller. Ensuite, on clique, mais attention : le mouvement ou la vibration du clic peuvent déplacer le pointeur de quelques pixels.
Sur un écran tactile, on prendra son doigt le plus fin et approchera l’écran presque orthogonalement pour essayer de « cliquer » le plus précisément possible. Il est rare qu’un effet visuel vienne indiquer clairement quelle partie de la pulpe du doigt a réellement touché l’écran, et s’il y en avait un il serait de toute façon masqué par notre doigt. Alors il faudra peut-être trois, cinq ou 10 essais pour fermer cette satané pop-up.

Et ça, c’est dans dans des conditions favorables : sans handicap, sans tendinite, et sans tenter d’utiliser un site important en marchant dans la rue avec un smartphone à la main.

Alors que tout ça aurait pu être beaucoup plus simple avec un bouton adapté :

Pourquoi c’est pas facile de cliquer un petit bouton ?

Et par opposition, pourquoi agrandir la zone cliquable d’un bouton faciliterait la vie des utilisateurs·trices ?

C’est le moment « pour marcher il faut mettre un pied d’vant l’autre » de cet article, mais restez avec moi, ça va bien se passer.

Première raison : pour utiliser un bouton, un lien ou tout élément interactif d’une interface, il faut déjà le trouver. Intuitivement, on comprend qu’un élément trop petit sera difficile à identifier dans une interface car peu visible.

Vous connaissez l’expression « chercher une aiguille dans une botte de foin » ? À votre avis, si une botte de foin contient une aiguille, un parapluie et un lampadaire IKEA de 2 mètres, lequel de ces objets sera le plus simple à trouver en premier ? Et en deuxième ?

Bien sûr la taille n’est pas le seul critère, d’autres rentrent en ligne de compte :

La forme. Une forme conventionnelle sera identifiée plus vite et plus souvent. Par exemple : le manche recourbé d’un parapluie cane, le texte souligné d’un lien, l’aspect surélevé d’un bouton-poussoir.
L’emplacement. La position dans la page (à un endroit attendu ou moins conventionnel), et la position par rapport à d’autres éléments (voir la loi de proximité dans la Psychologie de la forme).
Le contraste des éléments graphiques entre eux et avec leur environnement (Understanding Success Criterion 1.4.11: Non-text Contrast).

Ces critères participent à ce que le psychologue James J. Gibson a nommé l’affordance d’un objet, sujet très large et passionnant, mais que je vous propose de laisser de côté pour revenir à nos boutons.

Mettons que vous ayez aperçu et identifié le bouton de fermeture de cette satanée pop-up. Deuxième étape : il faut maintenant l’activer. Pour ça, il faut l’atteindre, et ça c’est un vrai petit voyage :

Avec une souris ou un pavé tactile, il faut déplacer le pointeur entre sa position actuelle et la position de la cible.
Sur un écran tactile, de smartphone par exemple, il faut déplacer un doigt vers la cible sans toucher l’écran, par exemple déplacer un pouce de sa position de repos vers le bouton.

Dans les deux cas, c’est un mouvement qui comprend une phase d’accélération et une phase de décélération. Et parfois, on s’arrête trop vite ou trop tard, un peu comme en voiture ou à vélo.

En ergonomie des interfaces humain-machine (IHM), on retrouve cette problématique dans la loi de Fitts. Dans les années 1950, en étudiant entre autres les cockpits d’avion de l’armée américaine, Paul Fitts estime que le temps moyen nécessaire pour atteindre physiquement une cible (par exemple un bouton ou un levier) dépend de deux paramètres : 1. la distance de la cible et 2. la taille de la cible.

(Pour plus de détail, on pourra lire cette explication très intéressante en anglais de la formule proposée par Fitts et son application aux interfaces informatiques.)

En gros, les cibles éloignées et les petites cibles demandent plus de temps. Les petites cibles éloignées étant les plus exigeantes.

Cela s’explique en partie par un phénomène connu dans l’expérience humaine et en sciences cognitives : le compromis entre la vitesse d’exécution et la précision (The speed-accuracy tradeoff: history, physiology, methodology, and behavior). Par exemple, si je veux appuyer rapidement sur un bouton sur un écran tactile, je ne vais pas prendre le temps de regarder le mouvement de mon doigt pour obtenir une information qui me permet de corriger ou optimiser mon mouvement : je risque donc de perdre en précision.

En tant que designers et développeurs·euses d’interfaces, nous pouvons faire deux suppositions :

Nos utilisateurs et utilisatrices seront souvent pressées ou distraites, et ne manipuleront pas nos interfaces délicatement et patiemment comme s’il s’agissait de fragiles nouveaux-nés.
En cas d’« erreur » de manipulation, par exemple un clic enregistré à côté d’un bouton voire sur le bouton voisin, nos utilisateurs et utilisatrices ne comprendront pas les raisons techniques et ergonomiques précises de l’erreur, et pourront percevoir l’interface comme buguée (ça m’a emmené ailleurs que prévu, j’ai dû cliquer plusieurs fois pour que ça marche, etc.), lente (j’ai dû cliquer plusieurs fois avant que ça ne finisse par réagir, ça « lague »), et plus généralement comme frustrante voire hostile.

En conséquence, notre boulot est de réduire autant que possible le nombre d’erreurs, et pour ça la loi de Fitts nous apprend que nous pouvons jouer sur la distance et sur la taille des éléments interactifs.

Petit problème : pour la distance, c’est compliqué. Elle est rarement fixe et prévisible, nous ne connaissons pas l’état du défilement de la page, la position de départ du curseur, etc. Sur smartphone, il existe des usages courants comme l’utilisation du pouce et une position de repos vers le bas de l’écran, mais même certaines distances courtes peuvent être difficiles d’accès (car il faut tordre la main ou le poignet). Donc pragmatiquement, on peut considérer qu’on a toujours une chance importante de se retrouver dans un cas difficile.

Il nous reste donc une variable majeure pour faciliter la vie des utilisatrices et utilisateurs : agrandissons-donc ces fichus boutons !

Okay mais tout le monde sait ça hein, c’est la base !

Malheureusement cette question n’est pas si connue que ça, car nous tombons tous et toutes quotidiennement sur des interfaces qui ne respectent pas ce principe. Et pas seulement sur des sites perso ou amateurs. Voici quelques exemples.

Sur Inc. (publication de Mansueto Ventures qui publie également le magazine Fast Company), les boutons de l’en-tête ont une taille cliquable minuscule (deuxième ligne, en vert). Ma proposition de correction (troisième ligne, en rose) utilise une taille minimum de 36 × 36 pixels. Idéalement il faudrait prévoir plus grand encore, et pour cela mieux répartir les boutons entre la gauche et la droite.

Mais peut-être que du côté de la presse en ligne on ne sait pas coder, alors que chez les vrais développeurs si, on sait ? Faut voir, parce que chez GitHub ce n’est pas ça non plus :

Les boutons de l’en-tête se limitent à la surface de l’icone, et cliquer à côté est excessivement aisé. La hauteur du champ de recherche pourrait être augmentée, et principaux liens du menu sont plutôt corrects sauf le lien “Marketplace” au milieu de la liste. Enfin, le texte des liens ou l’icone de profil touche le bord gauche du bouton, ce qui reste risqué : un peu de padding ne ferait pas de mal.

Peut-être que ça se passe mieux dans les entreprises spécialisées en design ? Hmm, pas toujours. On ne va pas prendre d’exemple sur le site d’Adobe, ce serait cruel. Mais si on regarde du côté d’Invision, il y a du bon et du moins bon :

Chez Invision, lorsqu’un bouton est visuellement grand, sa zone cliquable est grande également (logique…). Par contre dans l’en-tête, la plupart des liens se limitent à la surface du texte. Mention spéciale pour le petit triangle à côté de “Design Community” : il suffit de cliquer un pixel plus à droite pour cliquer dans le vide.

Un autre problème courant, qu’on peut voir dans les colonnes du pied de page, c’est l’utilisation de line-height pour espacer les éléments d’un menu. Un line-height important donne une bonne hauteur cliquable, mais dès que le texte passe sur deux ligne c’est la catastrophe. À votre avis, dans les cinq lignes de texte suivantes, combien y a-t-il de liens ?

Invision For

Startups

Pricing

Students &

Teachers

Mon conseil : combinez un line-height raisonnable (par exemple line-height: 1.5) et du padding pour obtenir une hauteur de bouton correcte, et testez avec du texte sur plusieurs lignes. Et si ça « casse » le design, parlez-en aux designers !

Autre écueil : attention à ne pas suggérer visuellement une surface cliquable, avec des couleurs de fond, des bordures, des décorations visuelles ou des effets au survol… tout en implémentant une zone cliquable plus petite. Vous invitez vos utilisateurs·trices à cliquer dans le vide !

Sur la page d’accueil de Google Design, les catégories principales montrent une bordure au survol, qui suggère une zone cliquable très large. Malheureusement, ce n’est pas le cas, et les liens ont une surface beaucoup plus réduite.

Les tailles de bouton recommandées pour les interfaces tactiles

Une taille de bouton suffisante, c’est quoi au juste ? Ça va dépendre en partie du public (certaines interfaces « expertes » ont une forte densité d’information et des contrôles plus petits que la moyenne), mais aussi du support.

Sur mobile, on peut suivre les recommandations d’Apple pour iOS et de Google pour Android, qui sont assez proches.

Les Human Interface Guidelines d’iOS recommandent une zone réactive de 44 pixels de côté minimum, et déconseillent les boutons trop rapprochés. Source : General Layout Considerations, © Apple.

Les recommandations Material Foundation de Google spécifient des zones réactives de 48 pixels de côté minimum, avec au moins 8 pixels entre les boutons. Source : Material Design: Spacing methods, © Google.

Un exemple intéressant dans cette dernière illustration : en (3), le bouton utilise un style standard de Material Design avec une hauteur de 36 pixels. Mais la zone tactile doit toujours faire au moins 48 pixels de haut, alors que faire ?

Sur certaines plateformes, on peut rendre la zone tactile d’un élément plus grande que l’élément lui-même. Par exemple, avec React Native on pourra utiliser la propriété hitSlop de certains composants.

<Button hitSlop={{ top: 6, bottom: 6, left: 0, right: 0 }}></Button>

Sur le Web, c’est plus compliqué. Deux solutions :

Utiliser un élément <a> ou <button> transparent avec du padding, et placer un <span> stylé comme un bouton à l’intérieur.
Utiliser un pseudo-élément positionné en absolu pour élargir la zone cliquable.

.my-button {
  position: relative;
}

.my-button::after {
  content: "";
  position: absolute;
  top: -6px;
  bottom: -6px;
  left: 0;
  right: 0;
}

Apparté sur les unités de mesure : iOS utilise des « points système », notés pt ; Android des “device points” notés dp ; et sur le Web on travaille en « pixels CSS », notés px. Ces trois unités sont équivalentes dans la plupart des cas, et peuvent correspondre à des quantités variables de pixels physiques (suivant la densité de l’écran et la configuration du système d’exploitation).

Les tailles de bouton pour les interfaces à la souris

Sur des interfaces qui ont été conçues principalement pour la souris, les boutons sont généralement plus petits. Par exemple sur macOS, les boutons des barres d’outils font 22 pixels de haut, et les Human Interface Guidelines pour macOS ne recommandent pas de taille minimum.

Material Design ~~recommande~~ recommandait encore récemment une taille minimum de 24 pixels pour les boutons dans les interfaces à la souris. On notera que dans ces deux exemples on pourrait facilement agrandir les zones cliquables sans modifier le design visuel. Source : Material Design: Spacing methods, © Google.

Personnellement, je trouve la recommandation de Material Design un peu faible, et préfère utiliser des zones cliquables de 30, 40 pixels ou plus. De plus, il devient compliqué de savoir si une interface sera utilisée à la souris, sur un écran tactile (en particulier avec les grandes tablettes et les ordinateurs portables tactiles), pour ne parler que des cas les plus courants ! Donc la pertinence de recommandations pour les interfaces à la souris est, à mon sens, de plus en plus contestable.

Mise à jour : les designers de Google semblent d’accord, et viennent de mettre à jour la documentation de Material Design pile au moment où nous publions cet article ! La nouvelle recommandation, à la page « Accessibilité », suggère des zones cliquables de 44 pixels de côté minimum pour les interfaces à la souris ou au stylet.

Même à la souris et sans handicap ou difficulté motrice, une cible de 24 pixels peut être difficile à atteindre, par exemple si on est un peu pressé.

Pour l’illustrer, voici un petit jeu de précision. Le but de ce jeu est de cliquer une vingtaine de cibles carrées de 24 pixels, toutes affichées exactement une seconde. Sachant que le temps de réaction humain moyen est de 250 millisecondes, cela laisse 750 millisecondes pour déplacer le pointeur et cliquer.

Je vous propose une première partie en gardant les paramètres par défaut, et on se retrouve juste après. Prêt·e ?

Alors, comment ça s’est passé ? Si vous avez obtenu un score de moins de 90, comment pouvez-vous l’améliorer (donc diminuer le taux d’erreurs) ? Vous avez trois leviers :

Augmenter la taille de la cible. Ne serait-ce qu’en montant à 32 pixels, la différence devrait être sensible.
Diminuer la taille du conteneur, et donc les distances à parcourir.
Augmenter le temps de jeu, pour être moins pressé·e.

N’hésitez pas à faire quelques essais. Et si jamais vous en tiriez quelques enseignements pour les interfaces que vous designez ou développez, ce serait bien sûr parfaitement fortuit. Bonnes parties, et joyeux Noël !

P.S. : le code du jeu est open-source et on peut le retrouver sur cette page.

Interview sur Alsacréations

2019-12-03T00:00:00+01:00

J’ai donné une petite interview pour le site alsacreations.com, un site communautaire autour des technologies web créé par Raphaël Goetter et Rodolphe Rimelé et auquel j’ai beaucoup participé il y a une dizaine d’années.

Il y a deux questions qui m’ont particulièrement intéressé, et je me permets de recopier mes réponses ici pour mémoire.

Alsacréations: Comment envisages-tu le futur de CSS ou de l’intégration en général ? (on pense notamment à CSS-in-JS)

Pour les CSS dans le JavaScript, c’est plus un symptôme de ce qu’il se passe depuis quelques années. Je n’ai rien contre ces outils, moi ça ne me gêne pas d’utiliser styled-components ou CSS Blocks, pas plus que Sass ou d’autres. Mais ça fait partie d’une tendance générale à empiler des couches techniques les unes par dessus les autres, qui correspond mieux aux schémas mentaux des développeurs·euses «classiques» que des intégrateurs·trices.

On se retrouve avec des projets où pour participer sur les styles ou l’accessibilité il faut pouvoir utiliser Git mais aussi Docker, maitriser JavaScript et React, configurer webpack, et écrire les styles dans une syntaxe JavaScript ou en pseudo-CSS. C’est quand même beaucoup d’obstacles pour des gens qui connaissent peu ces outils mais ont une expertise sur le HTML et l’accessibilité, le CSS, les navigateurs web, etc. Je parle régulièrement avec des gens qui faisaient de l’intégration web principalement ou en plus d’autres missions, et qui se sont rabattus sur du design ou de la gestion de projet car l’environnement technique devenait trop «pour et par les devs».

Je ne sais pas comment ça va évoluer, mais en tout cas je m’intéresse à tout ce qui tire un peu dans le sens inverse : permettre à des designers et/ou intégrateurs·trices de produire des choses sans être bloqué par plein de couches techniques. Peut-être une simplification des frameworks JS pour que le JS s’efface autant que possible, comme dans Svelte ? Est-ce qu’il faut forcément coder, ou bien est-ce que la manipulation directe comme dans Webflow ne fonctionnerait pas mieux au final ? Est-ce qu’on peut mélanger code et manipulation directe, pour bosser ensemble avec plusieurs profils ?

Alsacréations: Si tu avais à former un·e débutant·e en HTML et CSS, sur quels thèmes insisterais-tu particulièrement ?

Pour moi le plus important serait de rattacher HTML et CSS à un objectif plus large. Quand j’ai fait de la formation il y a 10 ans, j’avais une approche très linéaire, HTML et sémantique d’abord puis CSS ensuite, etc. Avec le recul je trouve ça un peu formel et pas très motivant.

Avec des débutant·e·s en développement web voire en développement tout court, j’insisterais sur l’idée de créer quelque chose. Dans ce cadre, HTML et CSS ne sont que deux outils sur cinq ou 6. On peut bosser sur plein de sujets : de l’animation, des ébauches d’application multimédia (par exemple une application pour générer des sons ou de la musique), une galerie de photos, mettre en page un poème ou une tablature de guitare, etc. L’important serait de publier le résultat (par exemple sur GitHub Pages, Netlify, ou en codant directement sur Glitch) et le partager à quelques personnes : voilà ce que j’ai fait.

Avec un public de développeurs·euses qui a déjà une formation initiale en développement “backend” mais très peu d’expérience en UI, le risque principal c’est le découragement car CSS est un domaine à part. Les compétences déjà acquises en Java, PHP, Python ou SQL ne se transfèrent pas vraiment à l’apprentissage de CSS (Miriam Suzanne, Why Is CSS So Weird?). Et si on n’a pas anticipé ce problème, on peut se retrouver en pleine dissonance cognitive (Natalya Shelburne, CSS at the Intersection) et abandonner.

Du coup, s’il faut se familiariser avec un nouveau domaine et une culture de design et d’ergonomie, pourquoi ne pas enseigner directement ces concepts de design, en utilisant CSS comme un exercice d’application ? Et enseigner directement des bases d’accessibilité, en utilisant HTML pour la mise en application ? En somme, viser un résultat plutôt qu’enseigner un langage.

Static site generators

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

I’ve been looking for a decent static site generator to build a simple, 10-page-or-so documentation site, and I’m failing. Here are some notes on my journey, to serve as a warning sign to future travellers, and thoughts on what static site generators could do better.

What is a static site generator, really?

I’d like to try and describe static site generators as if we hadn’t encountered this class of software yet. Please do not skip this section, even if you already (think you) know the answer.

Static site generators (SSG) are a class of software programs that help with creating websites. They’re often written by developers — professionals or hobbyists — to power their own small website or blog, and as such they tend to have a limited feature set.

SSG are close parents to scripts: short programs (a few hundred lines of code), which can be used from a command prompt to achieve specific tasks. They’re often built as a hobby by one developer, sometimes getting help from a few others months or years later. They almost never offer a graphical user interface.

One core principle of those scripts is that they work with a source collection of plain text files (aka “content”), process those files to transform them to the HTML format, and wrap them in more HTML. This is often called a “build” step. Before running the build command, you would have a file tree that looks like this:

My Cool Website
└── content
    ├── 2018-09-07-cool-blog-post.txt
    └── 2018-10-01-other-blog-post.txt

And after typing some text to run a command in a “terminal” or “command prompt” application, you would get something like:

My Cool Website
├── content
│   ├── 2018-09-07-cool-blog-post.txt
│   └── 2018-10-01-other-blog-post.txt
└── output
    ├── cool-blog-post.html
    ├── index.html
    ├── other-blog-post.html
    └── rss.xml

With that setup, you get a simple blog with one HTML page for each blog post, an index (or home) page that lists published posts, and a RSS feed. You can write your own styles if you know CSS, or — with some SSG, but not all — use a “theme” or an example project as a starting point.

Users of static site generators do this work on their own computer, and after the “output” folder has been generated they are expected to know how to put those files online to publish them. This can require software such as a FTP client, or more complex setups involving one or two additional command line tools.

There are hundreds of static site generators, with many listed on StaticGen.com. Some of the most popular ones are Jekyll, Hugo and Hexo.

When it comes to editing features, there are not many to speak of. Users are expected to know what formats like HTML and Markdown are, how to prepare images themselves (in Photoshop, Gimp or similar software), how to insert images inside a page’s content by using code that may look like this:

![My cat at 4 months](./sniffles-4months.jpg)

Or even something more complex:

![My cat at 4 months]({{< imgproc sniffles-4months.jpg Resize "600x" />}})

At this point we must recognize that static site generators are tools made by developers for developers. They require a ton of previous knowledge: HTML, Markdown, command line interfaces, FTP or some other way to publish HTML files online, and of course you would need some kind of web hosting to put those files. Users will also need to dive into technical documentation for their tool of choice when they want to customize their site’s pages, work in “templates”, learn a templating language, and probably write some CSS.

The most popular static site generator, Jekyll, may have the best documentation pages of the lot. And yet, it still puts a bunch of technical language front-and-center, on the project’s home page:

Jekyll’s core message, “Get up and running in seconds”

This is developer-talk, because static site generators are tools made by developers for themselves and their peers.

On the other hand, “content management” software such as WordPress, Drupal or my personal favorite, Kirby, target a dual audience: content editors (who write and manage content), and developers (who set up the CMS and implement the site’s design and features).

I’m making this point because, if we own up to who our software’s audience is, then we can consider what we can do for that audience and hopefully design less terrible software.

A developer’s idea of elegance

I sometimes talk with developers who praise static site generators as simple, which is hogwash. I’ve seen a few projects where content editors were handed off a site based on a SSG (especially in startups where devs may dominate the conversation), and could not manage any change without a lot of training and assistance. Nothing simple about that.

What those developers probably mean is that they find static site generators elegant. A programmer thinks that a solution is elegant when it uses their current knowledge to achieve something with:

few steps,
no repetition, and
not too much indirection.

Static site generators are an elegant solution for developers because:

It rests on our previous knowledge of: file and code formats, the command line, the plain-files-and-scripts philosophy, git and ssh or scp and other deployment strategies, etc.
Using this base knowledge, it offers solutions to boring, repetitive tasks. For example, Markdown syntax lets us avoid repeating <p>…</p> tags in our content; templates let us avoid tasks like manually repeating HTML structure and updating menus and content lists.
Finally, using the filesystem to store content lets us work in a single place (avoiding database software and languages, which would be overkill for limited datasets).

I’m all for elegant solutions that fit my mindset (aka just “elegant solutions”), and I’ve used static site generators in the past, including Pelican, Hyde, Jekyll and Metalsmith.

Here’s the thing, though: it’s been a terrible experience. It turns out that static site generators are terrible at handling content. Which is too bad, because that’s one of their very few features to begin with.

Static site generators are elegant on principle, but are not designed to deal with content more complex than a handful of pages and a list of blog posts. And I’m not talking about the speed of building hundreds of pages or more (Jekyll is notoriously slow, Hugo is fast), but the sheer ability to use content however you want.

Static site generators are bad at content

Let’s back up a bit. Most static site generators were built — or at least are advertised — as alternatives to database-driven CMS software. We’ve already shown that they may only be a valid alternative for developers and technical users with a lot of prior knowledge. But they are missing another core capability of CMS software.

In your average PHP or Python CMS, as in many Web frameworks, querying content from a relational database is always possible (and more or less straightforward). Linked objects and/or hierarchical content structures are built in features. Building home pages, landing pages, lists, modular pages, product pages with many sections, etc., out of content hierarchies or relations is standard practice; CMS software that was too limited to do that either evolved or was replaced by their competition.

When I’ve used static site generators in the past ten years, there were a few pain points like lacking documentation and strange and incompatible conventions. But the nail in the coffin was always that it’s either impossible or way too hard to build a single page from several pieces of content.

Recently, I’ve looked at static site generators again, because I wanted to convert Kaliop’s Frontend Style Guide, originally built with Kirby CMS, to something that could be built to static HTML in fewer steps by developers (e.g. npm install && npm run build).

This site is made of a handful of long “chapter” pages, with a top-level table of contents which lists all chapters and their sections:

For easier content management and reordering of sections, I had broken each chapter into different section files, so that the index page is generated from three levels of content. Looking at the “General Rules” branch only, the content hierarchy looks like:

2.0
└─ general
   ├─ 1-readme
   ├─ 2-editorconfig
   ├─ 3-dry
   └─ 4-clean

When generating the full table of contents, I expect to be able to write (in pseudo-code):

for chapter in page.children:
    print chapter.title
    for section in chapter.children:
        print section.title

Similarly, when generating a chapter page, I expect that I can easily print the full chapter content:

for section in page.children:
    print section.title
    print section.content

Actual templates would be a bit more complex, since we need to wrap this content in HTML tags, and maybe pass it to template partials or components. But retrieving content from a hierarchy of local files should be straightforward.

I haven’t found a single static site generator that handles this use case gracefully. Instead, after reviewing the documentation of three dozens tools (listed on StaticGen), and actively trying to build my use case with a handful of them, I’ve seen a range of limitations and awkward workarounds:

Sometimes it’s just not possible to work with content hierarchies and partial content. (Most JavaScript static site generators fall into that category.)
Or you have to write some configuration code that populates “Collections” ahead of build time. (Too indirect, and breaks if you change your information architecture a bit. We need something a bit closer to direct manipulation!)
Finally, a short list of tools allow listing a page’s children or “resources”, but have bugs when dealing with more than one level (Gutenberg) or impose arbitrary restrictions on what page “types” can list different types of content (Hugo).

When you can list content from children, grandchildren or other locations, it’s often not possible to process this content as Markdown or access its metadata.

A few words of warning about Hugo

The Hugo static site generator, praised by many for its speed, is more capable than most. There are surely many good things to say about Hugo, but in the spirit of warning folks about the terribleness of software: I wouldn’t recommend it for anyone who wants a smooth learning experience.

For one thing, it requires learning about way too many specific concepts: Sections, Lists, Taxonomies, Page Bundles, Leaf Bundles, Template lookup order, and the perfectly unintuitive differences between a index.md page and a _index.md page. (Or are those Sections, or Bundles? Is one a Section and the other a Page? Are Sections and Bundles “pages” too? I have no idea.)

I particularly dislike the way Hugo matches a page to a dozen possible template files or more — taking a page from Drupal’s book of idiosyncratic awfulness. Now, I understand that this is meant to make it possible to use different “themes”, and at worst your pages will still render with the theme’s layouts/_default/list.html or layouts/_default/single.html templates. But if you want to write your own HTML and CSS, the template lookup stuff is a nuisance (much like it is in the Drupal world when you want any kind of control over the HTML output).

On top of the complexity of Hugo’s design, its documentation is often subpar. For instance, the “Content Management > Page Resources” page does not explain much about, well, content, or content management. I expected a description showing content examples (some markdown or a file structure maybe), then information about how to use it in templates and other contexts. Instead, it’s a kind of API documentation listing “Properties” and “Methods”.

The second issue is that while Hugo builds pages fast, it often builds the wrong thing fast. For instance, if I rename a index.md file to _index.md, I need to run the hugo command two or three times to get it to render with the correct template. Using hugo server seems even less reliable.

Hugo is also unhelpful when a source Markdown file doesn’t render anything (there is no log or warning) or outputs a cryptic <pre></pre>. This doesn’t help the learning curve.

That being said, I heard that Hugo is an interesting choice if you’re building hundreds or thousands of pages (because it builds these pages really quickly), in which case it might be worth spending a couple weeks learning to use it.

What could we do differently?

There are thousands of static site generators out there (counting a bunch of scripts with 5 stars on GitHub) because thousands of developers looked at existing solutions and said “eh, I’ll just build my own”.

As a thought experiment, here are the core topics I would look at if I wanted to build my own tool from scratch.

1. Content naming conventions

Conventions for naming content files are necessary to allow users to create content files quickly and get predictable results. Those conventions must be short, clearly defined, clearly explained (you need great docs here), and intuitive (when possible, follow existing conventions rather than roll your own).

Major issues to solve regarding source content:

What will translate to a web page?
What will be ignored?
How may users control the transformations that are applied to content (processing of Markdown or other formats, templates, image transformations)? Should this be defined in the content or elsewhere?
How do you generate alternative views for the same page, e.g. a HTML page and a RSS or Atom feed?
How can you generate category and tag pages? More generally, how do you generate any limited set of pages based on querying information from other content, without having to manually create a new (probably empty) content file?

Some of those concerns can be addressed in templates or in configuration or other code, but there’s value in using elegant conventions to let users directly manipulate or tweak content to get a desired result.

2. Give feedback on content-to-output mapping

The generator should provide, by default, feedback on which files are picked up, which are ignored, and why. When a file is picked up and processed in some way, it should say so too.

To surface this information efficiently, the generator may need to come with a GUI (a web UI could work). I would be looking at tools like Fractal for inspiration.

3. More code should happen in templates

Most generators use restrictive template engines, and feed a restricted context (aka a set of data and functions) to those templates. This seems to come from a misguided need to keep templates “simple”, “logic-less”, and other kinds of baloney. Look, in a big MVC application built by people with different roles and technical knowledge, it might be useful to have your very responsible backend developers write controllers and let designers or frontend developers write HTML in a sandbox. Well, that’s a questionable approach too.

Anyway, as we said we’re making a tool for technically-minded people, and should give them power to actually do stuff. And since we’re talking about websites built ahead-of-time, the risks of logic in templates don’t apply as much.

Another consequence of restricted templates is that SSG documentation will then tell you to work in a third place: not in content, not in templates, but in “config code”. This is a problem because A) it’s probably one place too many and B) it’s often unclear at what time this config code is running or how often: once for every page generation or template run, or just once at the start of a build?

So, do more work in templates. We’re making somewhat simple websites here, it’s going to be okay. It’s cool if you can refactor your code to avoid duplication or separate concerns or whatever, but this shouldn’t be a requirement; users will only jump through hoops if they’re working on a big enough project to justify it.

4. A full content API

There should be a full content traversal API, which could be modelled after Kirby’s API (itself inspired by jQuery). Other sources of inspiration:

Globbing, e.g. find('posts/*.md').
DOM traversal (there’s no reason why your content tree cannot be a tree of nodes).

One concern with offering a full content API in templates is that if you run a template for a thousand pages, and do the same work (including querying the filesystem) every time, you’re going to have performance issues. I have a few possible optimizations in mind (fragmenting content queries and memoization), but I’ll admit that as a UI developer this is not my forte.

On top of traversing and retrieving content, templates should be able to transform formats (Markdown to HTML, parsing JSON and maybe YAML) and process images.

5. Markdown plus front-matter is too limiting

Originating in simple blog engines, static site generators treat pages as a single content chunk (often in Markdown) with some metadata sprinkled on top. If you need several long chunks of content (say, a product short description, long description, technical specs, and a list of vendors), you’re out of luck.

Theoretically, you can put any kind of text content in YAML “front-matter”, but editing that content without breaking the YAML syntax is a pain.

One workaround is using separate files in the same folder or in subfolder, than use the content API to retrieve them. Each such “resource” can have a body and metadata.

Kirby does things a bit differently (though it’s always possible to use a page’s files or child pages too), using a custom format with arbitrary fields:

Title: My Title
----
Date: 2018-12-25
----
Desc: Short description for list views and SEO.
----
Body:
## A field contains arbitrary text
So we can use a field value and parse it as Markdown or whatever.
…
----
Notes: …
----
References: …

Other sources of inspiration:

Vue single-file components, and, well, XML
Inside the page’s body: shortcodes (WordPress, Hugo), Web Components, Vue components (Vuepress)
Separators using HTML comment syntax, like

I’m not sure what would be the “best” solution, but it should be possible to unlock more power without completely breaking with convention.

6. No theming system

A theming infrastructure imposes a lot of technical restrictions and indirection, such as template lookup orders (see: Hugo), having to specify a handful of default template names (Hugo, again), and having to specify strange content conventions for mapping content to those default template names (still Hugo). Frankly, if a user really wants a template inheritance and theme inheritance mechanism, they’ll probably bite the bullet and work with WordPress or Drupal.

In the lightweight CMS world, having a theming system is the main reason why Grav is less straightforward than Kirby (which inspired it): themes and plugins rely on metadata in pages, so you have to put detailed config-as-metadata in every page to enable and configure theme and plugin features, which often feels like randomly pressing buttons and hoping to get a result.

Styling buttons, the right way

2018-05-09T00:00:00+02:00

If you’re building a website or a web app, you probably have buttons. And maybe links that look like buttons? Anyway, it’s important to get them right.

In this tutorial we’ll create basic styles for <a> and <button> elements, and a custom .btn CSS component. You will find a demo page for each step of the process.

Demo	Section
Step 1	Resetting `<button>` styles
Step 2	Writing a “button” CSS component
Step 3	Styling hover and active states
Step 4	Managing focus styles

Resetting `<button>` styles

As a rule, 99.9% of the clickable things in your website or app should be either <a> or <button> elements. If you’re not sure what element to use in a given situation:

If it goes to a different URL or changes most of the page’s content, use a link (<a href="some_url">…</a>).
Otherwise, use a generic button (<button type="button">…</button>).

Using the correct element has a few advantages: it’s SEO-friendly (especially for links!), it works well with keyboard navigation, and it improves accessibility for all users.

In spite of this, developers rarely use the <button> element. All over the Web, we can see a lot of buttons that trigger JavaScript actions, and on closer inspection it turns out they’re coded with <div>, <span> or <a>.

Why is the <button> element so underused?

Knowledge: many developers don’t know about it (learning HTML’s 100+ elements takes a little while).
Styling: <button> comes with complex default styles, which can make it hard to achieve a custom look.

Thankfully, the styling part can be fixed!

/**
 * Reset button styles
 * It takes a little bit of work to achieve a “blank slate” look.
 */
button {
  padding: 0;
  border: none;
  font: inherit;
  color: inherit;
  background-color: transparent;
  /*
    Show a hand cursor on mouse-over instead of the default arrow cursor.
    (Some argue that we should keep the default arrow cursor for buttons, to be consistent with how desktop operating systems treat buttons.)
  */
  cursor: pointer;
}

We end up with buttons that look like regular text.

The downside of this approach is that now we have to style all our buttons, or users won’t recognize them.

If we want to avoid that, another option is to use this style as a mixin (with Sass or another preprocessor) and apply it selectively:

@mixin button-reset {
  padding: 0;
  border: none;
  font: inherit;
  color: inherit;
  background-color: transparent;
  cursor: pointer;
}

.my-custom-button {
  @include button-reset;
  padding: 10px;
  background-color: skyblue;
}

<button type="button">
  I use default browser styles
</button>

<button type="button" class="my-custom-button">
  And I’m using custom styles instead
</button>

Writing a “button” CSS component

Now that we’ve removed default styles, let’s define our own button styles. This is what we’d like to do:

a “button” style that can be applied to both links or buttons;
we want to apply it selectively, because we’ll have other link and button styles in our pages.

This calls for a CSS component. A CSS component is a style or collection of styles which we can apply using classes, often on top of a few different types of HTML elements. You may be familiar with this concept from CSS frameworks like Bootstrap or Foundation.

We’ll call this component .btn — like Bootstrap does, but we’ll restrict ourselves to a single color and size, to keep things simple.

.btn {
  /* default for <button>, but useful for <a> */
  display: inline-block;
  text-align: center;
  text-decoration: none;

  /* create a small space when buttons wrap on 2 lines */
  margin: 2px 0;

  /* invisible border (will be colored on mouse-over) */
  border: solid 2px transparent;
  border-radius: 0.4em;

  /* size comes from text & padding (no width/height) */
  padding: 0.5em 1em;

  /* make sure colors have enough contrast! */
  color: #ffffff;
  background-color: #9555af;
}

Here is what our button component looks like:

You may be wondering why contrast is such a big deal. That second line of buttons looks nice; who doesn’t like a pastel look?

Simply put: with good contrast, you can reach more users. Some of your users have imperfect vision. Or bad screens that make washed out colors hard to differentiate. Others may be looking at your site on their phone, in broad daylight. You can check your contrast ratios here, and read more about the UX of text contrast here.

Styling hover and active states

It’s cool that your button looks nice, but… users are going to interact with it, and they will need visual feedback when the button’s state changes.

Browsers come with default styles for states like “hover” (mouse pointer is hovering the element) and “active” (the element is being pressed); and by resetting button styles we’ve removed some of those. We would also like to have styles for mouse-over, and overall we want styles that are visible and match our design.

Let’s start with a style for the :active state:

/* Old-school "push button" effect on clic + color tweak */
.btn:active {
  transform: translateY(1px);
  filter: saturate(150%);
}

We could change the button’s colors when clicked, but I want to reserve this effect for our mouse-over styles:

/* Swap colors on mouse-over */
.btn:hover {
  color: #9555af;
  border-color: currentColor;
  background-color: white;
}

Here’s our result — try out the active and hover styles. In the next section, we’ll deal with focus styles.

Managing focus styles

What are focus styles?

Users of your websites or web apps can use a keyboard or some other input software or device (gamepads, speech input software, head pointers, motion tracking or eye tracking, single switch entry devices, etc.) to navigate the page. Those methods will move the current “focus” from one element to the next, so that the user may activate an interactive element or type in a focused text field.

Even if you primarily use a mouse or trackpad, you might still be using the Tab key when using a web form, to jump from one form field to the next. Even your mouse users are keyboard users some of the time.

To serve all users, we need the currently focused element to be clearly visible. Thankfully, browsers do it by default:

Historically, browsers like Internet Explorer and older versions of Firefox had a very subtle focus style: a thin dotted outline. This led to the recommandation to add your own custom and more accessible focus style.
In recent years, Chrome, Edge, Firefox and other browsers ship with a default focus style that uses a double outline with two colors, which is more often accessible on varied backgrounds.

If you’re not sure what to do, you can keep the browser’s default style. But if you do want to customize it, read on.

Custom focus styles

Let’s define a custom focus style with the aptly-named :focus pseudo-class. We’d like this style to follow accessibility guidelines, including:

When a user interface component has keyboard focus, the focus indicator:

Encloses the visual presentation of the user interface component;

Has a contrast ratio of at least 3:1 between its pixels in the focused and unfocused states;

Has a contrast ratio of at least 3:1 against adjacent colors.

So we basically need a kind of outline or border, and it should be contrasted enough against part of the element itself and its environment, which can be a bit hard to always achieve. For instance, if you have a button with a gray border on a white page, and you just want to change the border’s color when that button is focused, picking a color can be tricky:

.btn {
  border: solid 1px gray;
}

.btn:focus {
  /* hide the browser's default outline, because we're showing our own focus styles */
  outline-color: transparent;

  /* ❌ blue is contrasted enough with the white background (8.51:1), but not contrasted enough with the border's initial gray color (2.42:1) */
  border-color: blue;

  /* ✅ black is different enough from both white (21:1) and gray (5.92:1) */
  border-color: black;
}

And when you’re not sure what the surrounding background color is going to be, it can be even harder to ensure your focus styles have good contrast every time.

To make our focus styles always perceptible, we can try creating a double-outline effect like the default focus style of Chrome and Firefox. Because the outline property only accepts a single outline, we’ll have to use a combination of outline and box-shadow to achieve the same effect.

.btn:focus {
  /* paint a 2px white pseudo-outline using box-shadow */
  box-shadow: 0 0 0 2px #fff;
  /* then paint a 2px dark pink outline and offset it to reveal one or two pixels of the pseudo-outline */
  outline: solid 2px #d59;
  outline-offset: 1px;
}

That works pretty well. And since we are setting a custom outline value, we don’t have to do anything like outline-color: transparent or outline: none to override the default outline style.

Sticky focus styles

There is one tricky issue left. When you click a link or button, two states will apply:

:active;
:focus.

The :active state stops as soon as you stop pressing the mouse button or trackpad. But in most browsers, clicking an interactive element gives it focus, so the :focus style applies until the user clicks somewhere else on the page.

This has been a headache for many web designers and developers for almost two decades. I cannot count the number of clients who have told me “when I click here, there is a strange border around the button, please remove it!”

Even if you know that this strange border helps make their site accessible, convincing a client to leave it be can be an uphill battle! (And if you don’t know, sadly you’ll find plenty of blogs, forum posts and StackOverflow answers telling you to “just use outline: none” and call it a day.)

Thanksfully there is a better way, implemented in all browsers in recent years: the :focus-visible pseudo-class.

How it works in a nutshell: for buttons and links, browsers will set the :focus-visible state on an element after a keyboard or keyboard-like interaction, but not after a click.

We can replace :focus with :focus-visible to fix our issue with focus styles sticking around after a click:

.btn:focus-visible {
  /* paint a 2px white pseudo-outline using box-shadow */
  box-shadow: 0 0 0 2px #fff;
  /* then paint a 2px dark pink outline and offset it to reveal one or two pixels of the pseudo-outline */
  outline: solid 2px #d59;
  outline-offset: 1px;
}

Note that Web browsers have recently moved to use :focus-visible for their own default focus styles. In that case, we don’t need to do anything about default focus styles, because our custom :focus-visible style will override them.

And if some browsers are showing focus styles on :focus instead of :focus-visible, we can use this style to make sure that only our custom focus styles would show up, and only on :focus-visible:

/* disable the default outline on a focused element which doesn’t have the :focus-visible state (e.g. a button after a mouse click) */
.btn:focus:not(:focus-visible) {
  outline-color: transparent;
}

And with that, here is our our final result:

Go ahead and look at the final code to review everything we’ve seen in this tutorial.

Command line tips

2018-05-03T00:00:00+02:00

I’d like to share a few command line things I’ve learned in the past years.

The command what?
You need help (and tldr is great)
Bash keyboard shortcuts
MacOS: install Homebrew and GNU coreutils
How big is this directory?
How to not delete everything

The command what?

I’m talking about the command prompt found in macOS when using the built-in “Terminal” application, or on Windows when you install something like Git Bash. It’s a text-based interface where you type commands to navigate in folders, create or delete files, and much more. If you’re curious and want to get started, this tutorial is pretty good for learning from scratch.

In the next sections, examples will look like this:

# This line is a comment
$ command parameter --option

The dollar character ($) indicates a command that you can type. You should not type this character, only what comes after it.

You need help (and `tldr` is great)

Sometimes you remember the name of a command, but how should you use it? What arguments and options does it take?

Most operating systems will come with documentation files called “man pages” (man is for manual). For example if I want to be reminded how the cd (change directory) command works, I could type man cd and press the Enter key, and I would get this:

That’s great, but those doc pages are long often hard to read. Can I get a summary?

One option is to use the command’s built-in help, if it exists. For example you can call mycommand --help. But some commands don’t have a help option, some use -help (single hyphen), some use -h, some use mycommand help (no hyphen), it’s a mess!

My solution is to use the tldr command. It’s an open-source documentation project for common commands, which shows very short usage examples. It looks like this:

You can use it online, but it’s quicker to use it straight from the command line. You will need to have Node.js and npm installed to use it, though, so it’s only useful if you’re using those tools already.

Installation looks like this:

# Install with npm
$ npm install --global tldr
...

# Time to use your new powers!
$ tldr rm

Bash keyboard shortcuts

When you’re using a Terminal or command prompt on Linux or macOS, you’re probably using the Bash program. (On Windows, you can install Git Bash to use that instead of cmd.exe.)

Bash is, among other things, the program that allows you to write commands an see their output.

One thing really frustrating with Bash and terminals in general is that you can’t just click around to move the input cursor, like you would in a code editor. If you’re like me, you probably spent a lot of time using the left and right arrows to move the cursor in a line of text.

So here are a few keyboard shortcuts that can help:

Up: fill the command prompt with the last command; useful if you need to correct it. Use “Up” several times to go back in history.
Ctrl + Left and Ctrl + Right (or Alt + Left|Right on macOS): move the cursor by a full word.
Ctrl + A: move the cursor to the start of the line.
Ctrl + E: move the cursor to the end of the line.
Ctrl + K: delete all characters to the right.
Ctrl + U: delete all characters to the left.

MacOS: install Homebrew and GNU coreutils

If you’re going to work on the command line often on macOS, it’s probably a good idea to install Homebrew, which will help you install more command-line tools.

Once you’ve installed Homebrew, I recommend using GNU Core Utilities, which contains the GNU version of tools like ls or rm. Compared to the similar tools that come with macOS, they’re often a bit more usable.

# Install coreutils, then follow the instructions
# to use them instead of macOS’s built-in ones
$ brew install coreutils

How big is this directory?

I’ve had trouble remembering how to check how big a directory is. For the past 15 years, I would have to switch to a graphical file explorer to do that.

Sometimes I would find this command:

# Show the size of everything in current directory
$ du -sh *

But I would never manage to remember it. Then it hit me that it sounds a bit like “douche”, so if you need something to help you memorize it, you’re welcome.

Here’s another trick for listing folders sorted by size. This only works on Linux, or on macOS if you’re using GNU Core Utilities:

How to not delete everything

When you want to delete a directory which contains a lot of files, you’re probably going to use rm -rf. It might look like this:

$ rm -rf some/path

But if you mess up the path part, you can end up deleting the wrong folder. For instance, maybe you wanted to delete a bunch of old log files:

$ sudo rm -rf /var/log/some-program/old-logs/*

But when you types, you pressed Enter by mistake, and the resulting command is now:

$ sudo rm -rf /

Shit.

There’s one way to make this kind of human error less likely: write the -rf part last:

$ sudo rm /var/log/some-program/old-logs/* -rf

If you hit Enter by mistake, the command will be:

$ sudo rm /
rm: cannot remove '/': Is a directory

Phew.

This is a good habit to get into:

Write rm then the directory’s path.
Check the path, does it look okay?
If it’s okay, write -rf at the end.

The main issue here is that on Linux this will work perfectly, because the GNU version of rm can take options at the beginning or at the end. But on macOS, the BSD version of rm will tell you that -rf is not a file. My workaround for this is installing GNU coreutils with Homebrew.

Gradient fills for SVG icons

2018-03-26T00:00:00+02:00

In my 2016 article How to work with SVG icons, I concluded the “Advanced” section with this warning: sorry, gradient fills won’t work.

I was mostly referring to code like fill: linear-gradient(red, blue) which does not work because fill is from SVG which has its own gradient system, and linear-gradient is from CSS and made mostly for backgrounds. The two don’t mix well.

I knew we could probably use SVG’s <linearGradient/> element but hadn’t really tried it. Then a few months later I did try it, and it worked!, but I forgot to blog about it. So, how can we do this thing?

Putting gradients in your HTML

The most reliable technique I found was to add a SVG element in your HTML page (at the start or end of the <body>, for instance). It should define a <linearGradient/>:

<svg style="width:0;height:0;position:absolute;" aria-hidden="true" focusable="false">
  <linearGradient id="my-cool-gradient" x2="1" y2="1">
    <stop offset="0%" stop-color="#447799" />
    <stop offset="50%" stop-color="#224488" />
    <stop offset="100%" stop-color="#112266" />
  </linearGradient>
</svg>

This element should not be hidden with display:none, because some browsers will just ignore the gradient if we do that. Making it zero pixels high seems to work.

You can then use this gradient on your SVG icon:

<svg class="icon" fill="url(#my-cool-gradient) #447799;" aria-hidden="true" focusable="false">
  <use xlink:href="#symbol-id"></use>
</svg>

Or in your CSS:

.icon {
  /* gradient and fallback color */
  fill: url(#my-cool-gradient) #447799;
}

These two icons should be using a turquoise-to-dark-blue gradient.
Credits: Leaf by Gabriele Malaspina and Carpet by Ben Davis

Note that you cannot customize the gradient on a per-icon basis. If you want different gradients, you will need to create different SVG gradient definitions in you HTML.

Changing gradient colors with CSS variables

If we want to set our gradient colors from CSS, we could do it using CSS variables. We’re going to write our gradient definitions using CSS custom properties (var(--my-custom-property)).

<svg aria-hidden="true" focusable="false" style="width:0;height:0;position:absolute;">
  <linearGradient id="gradient-horizontal">
    <stop offset="0%" stop-color="var(--color-stop-1)" />
    <stop offset="50%" stop-color="var(--color-stop-2)" />
    <stop offset="100%" stop-color="var(--color-stop-3)" />
  </linearGradient>
  <linearGradient id="gradient-vertical" x2="0" y2="1">
    <stop offset="0%" stop-color="var(--color-stop-1)" />
    <stop offset="50%" stop-color="var(--color-stop-2)" />
    <stop offset="100%" stop-color="var(--color-stop-3)" />
  </linearGradient>
</svg>

Now we can set — and, if need be, change — those colors in our CSS:

#gradient-horizontal {
  --color-stop-1: #a770ef;
  --color-stop-2: #cf8bf3;
  --color-stop-3: #fdb99b;
}
#gradient-vertical {
  --color-stop-1: #00c3ff;
  --color-stop-2: #77e190;
  --color-stop-3: #ffff1c;
}

And, finally, use them as icon fills:

.icon-hgradient {
  fill: url(#gradient-horizontal) gray;
  /* We could use it as a stroke fill too:
  stroke: url(#gradient-horizontal) gray; */
}
.icon-vgradient {
  fill: url(#gradient-vertical) gray;
}

Here’s the result (in browser supporting CSS Custom Properties):

Testing icons with SVG gradient fills and CSS variables

The gradient fill is painted for each path of the icon. To avoid color mismatches (like the junction between the leaf and the stem), it might be useful to merge all or most paths in the icon’s source SVG.

Using gradients in external files

This technique works in Firefox, and used to work in Edge (confirmed in Edge 14 and 15, regressed in Edge 16 and Insider Preview). In the following test:

Both icons are fetched from an external sprite: sprite.svg.
The first icon uses a gradient from this HTML page, and the second one from sprite.svg.

.icon-sprite-gradient {
  fill: url(sprite.svg#my-warm-gradient) red;
}

Non-supporting browsers (Chrome, Safari, latest Edge…) should show a red fallback fill for the second icon.

Using gradients in CSS as data URLs

What if I told you that you could define your gradients in SVG, but put the SVG in your CSS as data URLs? Okay now I’m just being silly. But it works! At least it works in Firefox :P

/* Notice the `id="grad"` in the SVG URL and how we’re using it at the end. Note that the `#` in hexadecimal colors must be escaped as `%23`. */
.icon-gradient-url {
  fill: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg'><linearGradient id='grad'><stop offset='0%' stop-color='%23ff00cc'/><stop offset='100%' stop-color='%23333399'/></linearGradient></svg>#grad") purple;
}

/* Same SVG, in base64 */
.icon-gradient-base64 {
  fill: url("data:image/svg+xml;base64,PHN2...zdmc+#grad") purple;
}

See how we reference the gradient’s id with #grad at the end of the URL? Only Firefox seems to understand this syntax. Eh, too bad.

Trying to show a magenta to purple gradient. Non-supporting browsers (Chrome, Safari, Edge…) should show a purple fallback fill.

Let’s recap

Yes you can have gradient fills!
But you need to include SVG gradients in your HTML
Colors can be hardcoded in the SVG gradient (in HTML), or set in CSS (using CSS variables)
All icons using a given gradient will use the same colors, you can’t override on a specific color like this:

.icon-gradient-override {
  /* This works, as shown before */
  fill: url(#gradient-horizontal) gray;
  /* But this will do nothing… */
  --color-stop-1: white;
  --color-stop-2: gray;
  --color-stop-3: black;
}

If you need a lot of different gradient fills, this technique might not work for you. Creating 10 or 20 different SVG gradients in your HTML is not practical. But for simpler use cases, this should work in all current browsers (including IE11 if we avoid CSS variables).

A few wishes for privacy settings in Firefox

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

Update: as I was writing this post, Mozilla was already working on privacy features and settings. Firefox’s Tracking Protection was released in 2018 and enabled by default for all users in 2019.

Firefox could do more to limit online tracking. Recently with the Quantum effort, Mozilla rebranded Firefox along three attributes: speed, customization and privacy. Yet the browser’s defaults allow most tracking techniques by default, for the sake of compatibility with existing websites.

About tracking

Most web browsers leak a lot of user data by default. For instance:

They allow third-party services (which a website almost always uses, e.g. Google Analytics, Facebook Connect, and ad providers) to track users’ activity across many websites, using third-party and first-party cookies.
They allow sites to know where a user is coming from (with the Referer HTTP header).
Through JavaScript, they give access to a lot of information on the browser itself, the operating system I’m using, my time zone, how many processor cores I have, and some of my preferences (e.g. whether I allow cookies, which languages I prefer reading). This and other technical information can be used to identify you uniquely across the web, a practice dubbed “fingerprinting”.

I’m probably forgetting a few things. Try the EFF’s Panopticlick tool to get an idea of how resistant your browser is to tracking and fingerprinting.

Most users don’t realize how much random companies they never deal with (such as ad networks) and other companies they do deal with (such as Google and Facebook) manage to know about them.

I’ve had a few friends and relatives asking how to remove a virus from their browser… where by “a virus” they meant “many sites I visit show me the same ads that seem to know too much about me, so a virus must be spying everything I do and inject ads in my computer”. After explaining a bit, I cleaned their cookies and installed uBlock Origin for them.

Why browsers don’t do more

Of course all the technical features I mentioned are not provided for tracking users, they are simply abused that way. But why won’t browsers stop this abuse? Why even load scripts — executable code with access to a bunch of information and features! — from other domains, why enable cookies for third-parties, etc.

In short: since it was possible before, most sites rely on these loose permissions now, and would break if they were tightened.

There are still opportunities for tightening these features and preventing at least some of the massive tracking going on, but different browser vendors have different priorities:

Chrome has a good focus on security but is all-in on tracking, because spying on users is Google’s business model.
Firefox is in a strange position because their brand is about independence and privacy but ultimately the bulk of their money comes from ad-and-tracking companies: Google, Yahoo and perhaps one of their competitors in the future. Also if a website stops working in Firefox then users are likely to blame Firefox for the breakage (and not the website for their invasive tracking techniques), and jump ship to Chrome.
Upstarts like Brave target a niche of tech-savvy privacy-conscious users, which want an on-by-default ad blocker, so they have some breathing room here. Also they’re based on Chromium so that limits other kinds of breakage (e.g. all the “Chrome only” web apps launching these days, from Google and others), which buys them some goodwill.
Safari enjoys a monopolistic position on iOS (since other browsers on iOS must use WebKit for rendering pages), and has good usage numbers on macOS, so they can get away with off-by-default third-party cookies and more recent things such as Intelligent Tracking Protection.

What Mozilla is doing

Note: I’m not an employee and not a big contributor to Mozilla projects. The information in this section comes from reading updates on Mozilla blogs and Twitter accounts.

Back to Firefox. While I wish Mozilla would have their Tracking Protection feature on by default, I understand that it can be a hard sell: many Firefox users would not be aware of that feature or what its advantages are, and they would resent the occasional site breakage.

Which is why Mozilla is experimenting with such features in Private Browsing Mode only: in this mode, users can expect things to maybe break, and are warned about it.

In Private Browsing windows, Tracking Protection is on by default, and Mozilla is working on shortening the Referer HTTP header for third-party domains so that sites can only know which site you’re coming from and not which specific page (or worse, what private information the URL contained, in some bad cases).

Mozilla is also researching how often privacy-centric restrictions break websites; basically they’re trying to figure out what they can do without losing a bunch of users.

Firefox Focus is another attempt at privacy-by-default, launched as a separate product (and sub-brand).

Privacy settings should be simpler

Currently, a more private setup in Firefox requires:

Activating Tracking Protection for all sites in the “Privacy” page of the browser preferences. This setting is also way down in the page.
Tweaking some settings in the “Privacy” page, some being a bit painful to get right (blocking third-party cookies or restricting cookies to the current section only).
If you’re feeling even more adventurous, there are a bunch of settings to tweak in about:config, for HTTP Referer and more.

This should be simpler, and more palatable to most users.

My wish would be for Mozilla to design a combo of privacy features which users could activate in one click. And because nothing is ever new, in spirit it would be somewhat close to what Microsoft did with Internet Explorer’s security levels:

I don’t have fond memories of this setting because, as a developer, it meant that a client’s IE6 or IE7 would sometimes block all scripting. But in retrospect I do find that it had some merits as a preference, if not always in the specific technical choices that were made.

Two, maybe three levels of protection could be offered:

Default (current behavior, which should not stop Mozilla from upgrading its privacy by blocking third-party cookies and maybe offering something similar to Safari’s Intelligent Tracking Protection…)
More Private (enables Tracking Protection, disables third-party cookies altogether or limits them to the current session, and maybe adds some other technical restrictions such as truncating Referer and fingerprinting resistance.)
Private Browsing Only (same as #2, with some added technical restrictions and all browsing is in Private Browsing Mode)

That’s a very rough idea and maybe these specific profiles don’t make sense. But I think it’s an idea worth pursuing, to offer better privacy defaults and options to all users.

What’s more, this setting should not be hidden in the “Privacy” settings page, but should be near the top of the “General” settings page or at the top of the “Privacy” page at worst. It should also come with an onboarding campaign to explain the trade-offs of each mode and offer a chance to switch modes right there. Finally, there might be ways to reflect this setting — and maybe offer a chance to switch — on each tab, in the navigation bar or on the New Tab page itself.

I have no idea if the rambling post can be of any help achieving better privacy by default in Firefox or any browser, but here it is anyway. Thanks for reading.

Printing background colors with CSS and SVG

2018-01-24T00:00:00+01:00

A client’s site had a white SVG logo on top of a color background.

<header style="background:black">
  <img src="https://fvsch.com/articles/css-print-background/white-logo.svg"
       alt="The site’s name">
</header>

When working on the print styles, we had a problem: browsers would disable background colors and print the logo white on white. And in this case we could not change the logo image or use a filter: invert(100%) on it.

We could have used the non-standard -webkit-print-color-adjust CSS property, but what about other browsers?

Faking a background with SVG

By default, browsers will print content images. We can inject one in our page and display it as a kind of background, in 3 steps:

Use a pseudo-element (::before or ::after) and an image URL in the content property.
For a solid color, we can make a simple SVG image, which works well as a data-URL.
Finally, we use absolute positioning to place this pseudo-element in the background.

header {
  position: relative;
}
header > * {
  position: relative;
  z-index: 2;
}
header::before {
  position: absolute;
  z-index: 1;
  top: 0;
  bottom: 0;
  left: 0;
  right: 0;
  overflow: hidden;
  /*
    In the URL, change the background to your own color.
    Warning: the `#` character must be escaped as %23,
    for example: `background:%23FFFF00` (yellow).
  */
  content: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 10 10' style='background:YOUR_COLOR_HERE' />");
}

Here is a fully working example in an iframe. You can test it by using your browser’s Print Preview on this page, or on the example page directly.

As noted, it’s a nice trick but don’t overuse it: you could cost your users a lot of money in printer ink.

Browser support

Works on all modern desktop browsers (tested in Edge 14–16, Firefox 58–60, Chrome 61–63, Safari 11)
Not tested on mobile browsers
Does not work in IE11

Three things to watch out for

The pseudo-element and the image are two separate entities. While the pseudo-element will cover its parent, the image will take the full width, and its height will depend on its aspect ratio. This means that the image will overflow its container, and we have to hide it with overflow:hidden.
In this example, we use a square image (viewBox='0 0 10 10'); if you need a taller image, use a rectangle one (for example viewBox='0 0 10 50').
Making sure that your url(…) is a valid data-URL can be tricky. In practice there is not a lot to escape, but if you are using double quotes to wrap your URL you will need single quotes for the XML attributes, and vice-versa. The # character identifies a fragment in URLs, so you will need to escape it using percent-encoding (%23).