What failed#

Comments in code blocks measured 3.28:1 in light mode and 3.85:1 in dark, against a floor of 4.5:1. Light-mode numbers measured between 4.08 and 4.32:1 depending on the palette.

comment  light  #8a8a92  3.28:1  ->  #727278  4.60:1
comment  dark   #71717d  3.85:1  ->  #7e7e89  4.60:1
number   light  #b06a1f  4.08:1  ->  #a4631d  4.60:1

Why hand calculation goes wrong#

Relative luminance is not lightness, and the green channel carries 72% of it. Two colours that look equally dark can differ by a factor of two once weighted, which is exactly the error that puts a grey at 3.3:1 while it reads as comfortably mid-tone.

Measure against the real surface#

Code sits on --surface, not on the page background. A comment grey measured against white clears the floor; the same grey measured against the code block it actually sits in does not. Sample the rendered page, not the palette.

What the pipeline already does#

Concatenation, minification, fingerprinting and subresource integrity are all built in:

{{ $css := slice
     (resources.Get "css/tokens.css")
     (resources.Get "css/base.css")
   | resources.Concat "css/site.css" | minify | fingerprint "sha512" }}
<link rel="stylesheet" href="{{ $css.RelPermalink }}" integrity="{{ $css.Data.Integrity }}">

That is the whole build. No lockfile, no node_modules, nothing to audit.

What you give up#

Autoprefixing, and the ability to use a framework that assumes a bundler. Custom properties and modern CSS cover most of what a preprocessor was for, and the browsers that needed the prefixes are gone.

What you gain#

A build that still works in two years. The failure modes of a Hugo-only build are Hugo’s, and there is exactly one binary to upgrade.

Measure comes first#

Northlight sets prose at 68 characters. Below about 45 the eye reverses too often and the rhythm breaks; past about 80 it loses the start of the next line on the return sweep. The range is wide, and 68 sits where a 17px face with generous leading stays comfortable on a laptop without stranding a column of whitespace beside it.

The measure is set in ch units rather than pixels, so it follows the font size instead of fighting it.

Leading follows measure#

Longer lines need more leading. At 68 characters, 1.75 keeps the lines distinct without opening gaps that break the paragraph into stripes.

The two settings are one setting. Changing the measure without changing the leading is how a layout ends up technically correct and unpleasant to read.

Scale, and how little of it you need#

Six sizes cover a blog: a page title, two heading levels, a lede, body, and meta. Anything more and the steps stop being distinguishable, which defeats the point of having them.

• Page title, fluid between 30 and 46px
• Section heading at 26px
• Subsection at 20px
• Lede at 19px, body at 17px
• Meta at 13.5px

A third level, so the next one does not skip#

The scale runs without gaps for the same reason the measure does: skipping a level is a hole in the document outline, and the outline is how a screen reader navigates.

A fourth level, for completeness#

It exists, it appears in the table of contents, and it is styled — but four levels of heading in one post usually means the post wanted to be two posts.

Its cover has no text in it, and that is the point. The covers elsewhere on this site have their title baked into the artwork, which is the right choice for a card but the wrong one here: an overlay treatment would then show the title twice. Artwork for these styles should carry no words.

The image is still never cropped. The box keeps the exact 1200×630 ratio and the fit is contain, so the whole cover is visible and the header sits over a scrim on top of it.

Its cover has no text in it, and that is the point. The covers elsewhere on this site have their title baked into the artwork, which is the right choice for a card but the wrong one here: an overlay treatment would then show the title twice. Artwork for these styles should carry no words.

The image is still never cropped. The box keeps the exact 1200×630 ratio and the fit is contain, so the whole cover is visible and the header sits over a scrim on top of it.

A second-level heading#

Body copy sets the measure at 68ch. Here is an external link and some inline code in a sentence.

A third-level heading#

• A list item
• Another one, with code inside it
• A third

A blockquote. Used sparingly, and styled with the accent wash rather than a grey box.

Code, in the languages that matter#

Seven languages, because those are the seven the reference blog uses. Every one of them has to be legible in both colour modes, comments included.

apiVersion: v1
kind: ConfigMap
metadata:
  name: example
  namespace: default
data:
  # Comments must clear 4.5:1 against the code background
  replicas: 3
  key: "value"
  enabled: true

# A comment, which must stay legible in both colour modes
find . -name '*.md' -mtime -7 | sort -u | head -20
export COUNT="$(grep -c . < list.txt)"

FROM alpine:3.20
RUN apk add --no-cache ca-certificates
COPY --chown=1000:1000 . /srv
EXPOSE 8080

A fence can name the file it came from, which renders a bar above the code:

server {
    listen       443 ssl;
    server_name  example.com;

    # Cache immutable assets for a year
    location ~* \.(css|js|woff2)$ {
        expires    1y;
        add_header Cache-Control "public, immutable";
    }
}

resource "aws_s3_bucket" "assets" {
  bucket = "example-assets"
  tags = {
    Environment = "production"
    Managed     = true
  }
}

prometheus.scrape "default" {
  targets    = discovery.kubernetes.pods.targets
  forward_to = [prometheus.remote_write.default.receiver]
}

NAME                     READY   STATUS    RESTARTS   AGE
northlight-7d9f8c6b-x2k  1/1     Running   0          14d

Line numbers and a highlighted line are configured per fence rather than globally, so both need styling even though the reference blog uses neither:

1
2
3
4
5

metadata:
  name: example
  namespace: highlighted
  labels:
    app: northlight

A table#

Wide tables scroll inside their own container rather than pushing the page sideways.

Raw HTML#

The site config enables unsafe HTML, so posts may contain markup like this:

Fourth level#

A third level, so the fourth does not skip one#

A heading level may not be skipped: an h2 followed by an h4 reads to a screen reader as a missing section, and this page is the theme’s own integration test, so it should not demonstrate the mistake.

This is an h4#

It should render, and it should appear in the table of contents, which is configured for levels 2 through 4.

Unused surface is not free#

Every shortcode is a template to maintain, a name to document, and a behaviour someone will eventually depend on. Shipping forty-five of them to cover the handful a given site might want is a trade that only looks good before the maintenance starts.

What replaces them#

Markdown, and render hooks for the cases where markdown alone is not enough. A hook applies automatically to content that is already written, which is the opposite of a shortcode: nothing has to be sprinkled through the posts to switch it on.

The distinction that matters is portability. A shortcode is theme-specific syntax, so content written with it only renders correctly inside this theme. A render hook enriches standard markdown, so the same file renders fine anywhere — just plainer.

Admonitions#

Callouts use GitHub’s alert syntax rather than a shortcode, for exactly that reason:

Images#

The image hook does the unglamorous work. Every local image ships with its intrinsic width and height, so the article never reflows as pictures arrive, and it generates a srcset — the prose column is 44.2rem wide, so serving a 2400px screenshot at full size costs a reader roughly three times the bytes they can actually use.

A markdown title becomes the caption, as on the diagram above.

What changes between the modes#

Dark sits on #0b0b0e rather than #000000, and text drops to #f2f2f5 rather than #ffffff. Both decisions reduce the contrast between the extremes from punishing to comfortable without going anywhere near the AA floor.

The accent swaps roles#

Each palette carries two tones. The readable one carries text and links; the soft one carries fills, hover borders and washes, where contrast rules do not apply. Between light and dark the two swap places, which is the only reason a genuine pastel can be the primary colour of a theme at all.

A pastel used as link text on white fails contrast every time. Used as a fill behind dark text, the same colour is fine. The trick is never asking one tone to do both.