Ray's TIL

Notes on Writing Well

Mon, 12 Oct 2026 00:00:00 GMT

Michael Nielsen keeps a set of rough working notes on writing. He calls them notes, not polished prose, but they’re full of ideas I keep coming back to.

Good writing is good psychology. Rules like “avoid adverbs” or “omit needless words” usually come without a reason. Nielsen’s point is that good writing isn’t a property of the text. It’s a property of the relationship between the reader and the text, so useful advice is about how to change that relationship.

One purpose. A good piece has a single, sharp purpose, and every part of it, even the digressions, should serve that purpose. The failure mode he calls discursive disease: you’re writing about gardens, then you add that good thought you had about rainforests, and now the piece is sort of about both and really about neither. His fix is to write the purpose at the top of the draft and reread it every time you sit down. Anything that doesn’t fit gets filed away for another piece, the way Aaron Sorkin’s leftover material from The American President went on to become The West Wing.

It’s hard to write the truth. Early drafts are full of the written version of “you know what I mean”. The only fix he knows is to revise over and over, asking of each sentence whether it can be sharper, and whether you actually believe it.

Beware words you wouldn’t say out loud. They’re usually there to sound authoritative, which serves the writer, not the reader.

A few smaller ones worth stealing:

Write one true sentence. Hemingway’s way out of being stuck. Start with the simplest true thing you know and go from there.
Stop when you know what comes next. Also Hemingway. If you end each session mid-flow, you’ll never start the next one stuck.
Brainstorm ten opening sentences. When the first line won’t come, don’t settle for a mediocre one. Write ten quickly, then judge them.
Start as late as possible. Ask whether the opening sentence could begin further in.
Don’t announce that something is interesting. “It’s interesting to consider…” tells the reader how to feel instead of making them feel it, and quietly suggests the topic sounds boring. Just say “Consider…”, then make it interesting.
“Very” is the worst adverb. “She looked very angry” loses little without it. Where the intensity matters, swap the phrase for something specific: “Jake would very much like lunch” becomes “Jake was ravenous for lunch”.

Scroll Animation Terms

Sun, 11 Oct 2026 00:00:00 GMT

If you struggle to describe scroll animations in Claude or Codex, these commonly used terms can help. Save this for later.
— Gabriel (@gabriell_lab) October 6, 2026

“Make it animate when I scroll” can mean at least six different things. Naming the right one gets you the right result on the first try, whether you’re prompting an AI or briefing a designer.

Scroll-triggered: the animation plays once when an element enters the viewport, then runs on its own clock. Scrolling starts it but doesn’t control it. Usually built with IntersectionObserver.
Scroll-linked: the animation’s progress is tied directly to the scroll position, so it scrubs forwards and backwards as you scroll. A reading progress bar is the classic example. CSS can now do this natively with animation-timeline: scroll() or view().
Parallax: layers move at different speeds from the page, so the background drifts slower than the foreground and fakes depth.
Sticky: an element scrolls normally until it hits an edge, then stays pinned there until its container scrolls past. Think of the A, B, C letter headers in a contacts list. It’s just position: sticky; top: 0.
Scroll snap: scrolling settles on set points instead of stopping anywhere, like a full-screen slide deck. Set scroll-snap-type: y mandatory on the container and scroll-snap-align: start on each child.
Horizontal scroll: content moves sideways. This is either a plain overflow-x carousel, or a pinned section that turns your vertical scroll into sideways movement.

The pair that gets mixed up the most is triggered vs. linked. If the animation should finish by itself once it starts, it’s triggered. If it should follow your scroll, including when you scroll back up, it’s linked.

Push vs. Pull vs. Merge Requests

Fri, 26 Jun 2026 00:00:00 GMT

TLDR

“Pull request” is a leftover from the pre-GitHub days, when you’d email a maintainer asking them to pull your branch (and tell them where to find your fork). GitHub kept the name; GitLab later chose “merge request” because merging is the action you actually care about. The terminology is a social artifact, not a technical one.

tbh i still don’t get why it’s called a pull request instead of a push request
— ange (˶♡ᴗ♡) (@angehyc) June 19, 2026

Like any other student, I was first acquainted with Git through GitHub. Like the OP of the tweet above, I wondered the same thing but never really put much thought into it.

That changed when I moved to PayNet and started using GitLab. Not only did they use different terminology (merge request, or MR), it also rekindled my curiosity about how the terms differ and why they exist in the first place.

Thankfully, the thread below put the question to rest:

As someone who used GitHub for years, went to work at GitLab, and was yelled at dozens of times for calling it a pull request (not a merge request) I know a lot about this topic https://t.co/vEbhv32g1x
— Phil Zona (@philzona) June 19, 2026

Before GitHub and GitLab, most dev work involving Git happened over mailing lists and self-hosted Git servers. When you wanted to land a change, you had to actively reach out to the maintainer.

What you’d ask them: “Hey, can you pull my branch into master?”

That message was the pull request. It was simply the abstraction people had at the time, and GitHub named its action after the workflow everyone was already using.

GitLab came along a couple of years later with “merge request” (MR), which in my honest opinion is more technically accurate. The action contributors actually care about is merging, not just pulling and reviewing.

But GitHub’s name makes sense too once you remember Git is distributed, and so were forks back then. Part of a pull request was telling the maintainer where to find your fork and how to pull your branch, because GitHub didn’t yet exist to host it for you.

The more you know. ¯_(ツ)_/¯

Core Web Vitals: LCP, CLS & INP

Mon, 13 Apr 2026 00:00:00 GMT

Core Web Vitals are the three metrics Google uses to measure real-world user experience. They directly influence search rankings and are what actually matters when someone asks “is this site fast?”

Metric	What it measures	Good	Poor	Common fixes
LCP (Largest Contentful Paint)	Time until the largest visible element renders	≤ 2.5s	> 4s	Preload LCP image, inline critical CSS, use `fetchpriority="high"`, fast server response
CLS (Cumulative Layout Shift)	How much the layout shifts unexpectedly during load	≤ 0.1	> 0.25	Set explicit `width`/`height` on images, reserve space for dynamic content, use `font-display: swap` with `size-adjust`
INP (Interaction to Next Paint)	Worst-case latency from interaction to visual response	≤ 200ms	> 500ms	Break up long tasks with `scheduler.yield()`, debounce handlers, move heavy work to web workers

Google measures these on real Chrome users via the Chrome UX Report (CrUX). Your Lighthouse score in DevTools is lab data — useful for debugging, but the field data from CrUX is what determines your pass/fail status in Search Console.

INP replaced FID (First Input Delay) in March 2024. Where FID only measured the first interaction’s input delay, INP tracks all interactions throughout the page’s lifecycle and reports roughly the p98 worst case — a much better reflection of how responsive the page actually feels.

Partial Hydration & Islands Architecture 101

Sun, 12 Apr 2026 00:00:00 GMT

Modern JavaScript frameworks ship a lot of JavaScript. But most websites don’t need a lot of JavaScript.

On one end of the spectrum, you have dashboards, SaaS apps, and real-time editors — deeply interactive pages where JS is the product. On the other end, documentation, blogs, and marketing pages that are pure content and need zero JavaScript.

But there’s a whole category of sites in between that need some interactivity, just not a lot:

These “goldilocks” sites are awkward for traditional frameworks. You can’t fully statically generate them because some parts need to be interactive, but shipping an entire framework runtime for a theme toggle and a few animated icons feels like overkill.

The root of the problem is hydration. When a server-rendered page reaches the browser, the framework loads and hydrates the entire component tree — walking every node, attaching every listener — even for the 90% of the page that’s static content and will never respond to a click. That’s a lot of JavaScript downloaded and executed for nothing.

Partial hydration flips the model. Instead of hydrating everything and carving out static parts, you start from zero JavaScript and opt in to interactivity only where you need it. The rest of the page stays as pure, server-rendered HTML with no runtime overhead.

This is the idea behind the islands architecture, a term coined by Etsy’s frontend architect Katie Sylor-Miller and later popularised by Preact creator Jason Miller. Think of your page as an ocean of static HTML with small, independent “islands” of interactivity scattered across it. Each island hydrates on its own, in isolation, without knowing about or depending on the others.

How Astro implements it

Astro is probably the most well-known framework built around this model. By default, Astro components render to static HTML at build time with zero client-side JavaScript. When you need interactivity, you explicitly opt in using client:* directives on a per-component basis:

---
// Everything here runs at build time only
import Header from '../components/Header.astro'     // static, no JS
import SocialLinks from '../components/SocialLinks'  // React component
import GitHubCalendar from '../components/GitHubCalendar' // React component
---

<!-- Pure HTML, zero JS -->
<Header />

<!-- These become interactive islands -->
<SocialLinks client:idle />
<GitHubCalendar client:only="react" />

The client:* directives control when each island hydrates:

Directive	When it hydrates	Good for
`client:load`	Immediately on page load	Critical interactive UI that must work right away
`client:idle`	After the page is done loading (browser idle)	Non-critical interactive components like theme toggles, animated icons
`client:visible`	When the component scrolls into view	Below-the-fold content like pagination arrows, newsletter forms
`client:only="react"`	Client-side only, never SSR’d	Components that depend entirely on browser APIs (e.g. GitHub contribution calendar)
`client:media="(max-width: 768px)"`	When a CSS media query matches	Mobile-only interactive components

How this site uses it

This site you’re reading is built with Astro. The vast majority of it — the sidebar, the blog content, the navigation, all the layout — renders to static HTML at build time. No framework, no virtual DOM, no JavaScript. It’s just HTML and CSS.

The interactive islands are small and deliberate:

Animated icons (client:idle) — the little SVG icons that animate on hover throughout the site. They hydrate after the page settles so they don’t compete with the initial render.
Theme and notification toggles (client:idle) — the brightness/moon icons and bell icons in the header. Interactive but not urgent.
Social links (client:idle) — React components that handle hover animations.
GitHub contribution calendar (client:only="react") — fully client-rendered because it depends on browser APIs and fetches data at runtime. No server-side HTML is even attempted.
Pagination chevrons and newsletter form (client:visible) — only hydrate when you scroll down to them. Why load JavaScript for something you might never see?
Vinyl collection grid (client:idle) — the interactive filtering and sorting on the vinyls page.

Each of these islands loads and hydrates independently. If the GitHub calendar fails to load, the rest of the page is completely unaffected — it was never JavaScript to begin with.

Why it matters

The performance difference is real. A traditional React SPA would ship the framework plus every component’s JavaScript to the browser, even for a page that’s 95% static prose. With islands, that same page ships close to zero JS unless you explicitly need it.

This is particularly noticeable on content-heavy sites like blogs and documentation. The content is the product, and it doesn’t need reactivity. Islands architecture lets you get the DX of component-based frameworks (use React, Vue, Svelte — Astro doesn’t care) without paying the runtime cost for static content.

Islands architecture and partial hydration are closely related but not identical. Partial hydration is the technique (hydrate only some components). Islands architecture is the mental model (static ocean, interactive islands).

Astro uses partial hydration to implement the islands model. Other approaches to partial hydration exist too — React Server Components, for example, solve a similar problem but from within a single-framework paradigm rather than Astro’s framework-agnostic approach.

Claude Code Hooks 101

Sun, 05 Apr 2026 00:00:00 GMT

CLAUDE.md is a suggestion. Claude reads it and follows it about 80% of the time. Hooks are different. They’re shell commands that fire automatically every time Claude does something, regardless of what the prompt says.

Two hook types cover most workflows:

PreToolUse runs before the tool executes. Exit code 2 blocks the action and sends your error message back to Claude so it can try a safer approach. Think of it as a bouncer.
PostToolUse runs after the tool completes. Good for formatting, linting, logging. Think of it as quality control on the assembly line.

Hooks live in one of 3 places:

.claude/settings.json         # project-level, committed to git
~/.claude/settings.json       # user-level, all projects
.claude/settings.local.json   # local only, not committed

Block dangerous commands

Claude is powerful enough to run rm -rf, git reset --hard, or curl … | bash. It probably won’t, but “probably” isn’t good enough.

#!/usr/bin/env bash
set -euo pipefail
cmd=$(jq -r '.tool_input.command // ""')

dangerous_patterns=(
  "rm -rf"
  "git reset --hard"
  "git push.*--force"
  "DROP TABLE"
  "DROP DATABASE"
  "curl.*|.*sh"
  "wget.*|.*bash"
)

for pattern in "${dangerous_patterns[@]}"; do
  if echo "$cmd" | grep -qiE "$pattern"; then
    echo "Blocked: '$cmd' matches dangerous pattern '$pattern'. Propose a safer alternative." >&2
    exit 2
  fi
done
exit 0

Exit code 2 is the key. It cancels the action and the error message goes back to Claude so it knows to try something safer. Exit 0 means go ahead. Anything else logs a warning but doesn’t block.

Log every command

Appends every Bash command Claude runs to a timestamped audit trail.

#!/usr/bin/env bash
set -euo pipefail
cmd=$(jq -r '.tool_input.command // ""')
printf '%s %s\n' "$(date -Is)" "$cmd" >> .claude/command-log.txt
exit 0

Add .claude/command-log.txt to .gitignore. When something breaks, you have an exact record of what ran and when.

Auto-format and lint after every edit

Rather than telling Claude “always run Prettier” in CLAUDE.md and hoping it remembers, a PostToolUse hook makes it unconditional.

The hook receives the tool call as JSON on stdin, so jq can pull out the file path:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/block-dangerous.sh" },
          { "type": "command", "command": ".claude/hooks/log-commands.sh" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write 2>/dev/null; exit 0"
          },
          {
            "type": "command",
            "command": "npx eslint --fix $(jq -r '.tool_input.file_path') 2>&1 | tail -10; exit 0"
          },
          {
            "type": "command",
            "command": "npm run test --silent 2>&1 | tail -5; exit 0"
          }
        ]
      }
    ]
  }
}

Prettier runs first, then ESLint with --fix, then the test suite. The tail -5 keeps test output short so Claude sees “3 tests failed” rather than 200 lines. The ; exit 0 on all three means failures are reported but never block the session. By the time you look at the code, it’s formatted, lint-clean, and you already know if tests are passing.

Speculation Rules API

Sun, 29 Mar 2026 00:00:00 GMT

Prefetch vs. Prerender

By default the browser does nothing until you click, then kicks off the full sequence from scratch: DNS, TCP, TLS, HTML fetch, parse, JS execute, render. All of that happens after you’ve committed to navigating.

Both prefetch and prerender move that work earlier, but they stop at different points.

Prefetch stops after the network. It downloads the HTML and sub-resources into cache, but the page isn’t parsed or rendered. You still pay the rendering cost on click, just not the network cost.

Prerender goes further. It fetches, parses, executes JS, lays out, and paints in a hidden background tab. When you click, the browser swaps the already-rendered page in.

Prefetch strategies

Strategy	Triggers on
`tap`	mousedown, just before click
`hover`	hover delay (~80ms)
`viewport`	link scrolls into view
`load`	every link, immediately on page load

Prerendering

You can trigger it per-link with rel="prerender":

<link rel="prerender" href="/about" />

The opposite end is lazy loading: defer everything until explicitly needed (loading="lazy", dynamic imports, IntersectionObserver).

TLDR

Prerender pays upfront. Lazy loading pays on demand.

The Speculation Rules API

Chrome 109+ lets you control this with a JSON script tag:

<script type="speculationrules">
  {"prerender":[{"where":{"href_matches":"/*"},"eagerness":"moderate"}]}
</script>

eagerness controls when the browser triggers prerendering:

Value	Triggers on
`conservative`	mousedown
`moderate`	hover / focus
`eager`	link in DOM

moderate is the right default. Hover is clear enough intent, and a wrong guess just wastes a bit of bandwidth.

Prefetch + prerender compose well

Astro’s prefetch: { defaultStrategy: 'viewport' } fires when a link scrolls into view, warming the cache early. By hover time the assets are already local, so the prerender finishes fast:

link enters viewport → prefetch (network)
             ↓
         user hovers → prerender (full render, from cache)
              ↓
            click → instant swap

Don’t prerender pages that run side effects on load — analytics hits, impression counters. The browser executes those during prerender, before the user has actually visited.

On this site view counts are incremented by a React component on mount, which only hydrates on real navigation, so it’s safe.

Other browsers silently ignore the script tag, so no broken behaviour as a fallback.

CSS font units: em, rem, ex, ch, cap

Sat, 28 Mar 2026 00:00:00 GMT

Five units tied to the current font, each measuring something different:

Unit	What it measures
`em`	font-size of the current element
`rem`	font-size of the root (`<html>`) element
`ex`	x-height — height of a lowercase “x”
`ch`	advance measure of the “0” glyph
`cap`	cap height — height of an uppercase letter

em compounds when nested. A 1.2em element inside another 1.2em element is 1.44× the root size. rem skips all that — always anchored to :root.

ch is the useful one people overlook. Setting width: 60ch on a prose container gives you a readable line length regardless of font size. It’s not exactly “60 characters wide” (monospace aside), but it’s close enough and adapts as the font changes.

ex and cap are handy for optical alignment — centering an icon with text, nudging a superscript, that kind of thing:

/* nudge icon to sit at cap height */
.icon {
  height: 1cap;
  width: 1cap;
}

/* rough measure: ex ≈ 0.5em for most fonts */
sup {
  vertical-align: 1ex;
}

CSS viewport units: dvh, lvh, svh (and their *vw siblings)

Sat, 28 Mar 2026 00:00:00 GMT

vh and vw have been around forever, but mobile browsers broke them. The URL bar in Chrome/Safari shrinks when you scroll — so 100vh is taller than the visible area when the page loads, causing content to get clipped or produce unexpected scroll.

The fix landed as three new variants:

Unit	What it tracks
`svh` / `svw`	Small viewport — assumes UI chrome (address bar, nav) is fully visible
`lvh` / `lvw`	Large viewport — assumes UI chrome is hidden/retracted
`dvh` / `dvw`	Dynamic viewport — updates as UI chrome appears and disappears

Same split applies to vi / vb (inline/block axis) if you need those.

Which one to use

dvh sounds like the obvious answer but it causes layout reflows as the user scrolls, which can make the page jump. Use it sparingly.

/* hero that actually fills the screen on load */
.hero {
  min-height: 100svh;
}

/* sticky footer pinned to the retracted-chrome size */
.modal {
  height: 100dvh;
}

svh is the safe default for full-screen sections — it matches what the user sees when they first land on the page. lvh is mainly useful when you know the chrome is gone (fullscreen video, PWA display mode).

All three have been supported across Chrome, Safari, and Firefox since 2023. The old vh still works — just be aware of what it actually measures (inconsistent across browsers, generally the large viewport).

BEM: Blocks, Elements, and Modifiers

Thu, 26 Mar 2026 00:00:00 GMT

BEM (Block, Element, Modifier) is a CSS naming convention created by Yandex in 2009. The pattern is .block__element--modifier.

Block — a standalone component (.card)
Element — a part of that block that has no meaning on its own (.card__title)
Modifier — a variation or state of a block/element (.card--featured, .card__title--large)

.card { }              /* Block */
.card__title { }       /* Element */
.card--featured { }    /* Modifier */

The double underscore (__) signals “this belongs to,” and the double hyphen (--) signals “this is a variant of.” Elements are always flat — .card__body__text is wrong, .card__text is right.

Why BEM?

Flat specificity — single-class selectors only, no !important wars
Self-documenting — .search-form__input--disabled needs no comment
Encapsulation — .card__title won’t bleed into .header__title
Grep-friendly — search .card to find everything related to that block

DX tradeoffs

Good: readable diffs, easy onboarding, human-readable DevTools classes (.search-form__input--error vs .sc-dkPtRN).

Bad: verbose class names, naming fatigue (“is this a block or an element?”), awkward JS access — $style['card__body--muted'] because -- breaks dot notation.

Use Case in Vue

In Vue SFCs, you probably don’t need BEM. Vue’s <style scoped> and <style module> already handle encapsulation, so BEM’s namespacing becomes redundant. Simpler alternatives:

Flat semantic names with scoped styles — just .title, .body, .muted. The scoping attribute ([data-v-f3f3eg9]) prevents collisions.

CSS Modules with camelCase — better when you need JS class binding:

<template>
  <div :class="$style.card">
    <h2 :class="$style.title">Hello</h2>
    <p :class="[$style.body, $style.bodyMuted]">World</p>
  </div>
</template>

<style module>
.card { /* ... */ }
.title { /* ... */ }
.body { /* ... */ }
.bodyMuted { /* ... */ }
</style>

Clean dot notation, no brackets. Configure with css.modules.localsConvention: 'camelCaseOnly' in Vite.

Data attributes for states — :data-featured="featured" instead of modifier classes. No class binding juggling, and state shows up clearly in DevTools.

When to use what

BEM — shared/global CSS, design systems, vanilla CSS projects, large teams
Scoped styles + flat names — Vue/Astro components that don’t need JS class binding
CSS Modules + camelCase — components that need dynamic class binding in JS
Utility-first (Tailwind) — when you’d rather skip naming altogether

Enhanced Code Blocks with Shiki Transformers

Mon, 23 Mar 2026 00:00:00 GMT

Shiki supports built-in transformers for filename labels, line highlighting, and diff notation — no plugins needed.

Filename Labels

Add title="filename" to any fenced code block to show a filename tab:

export function greet(name: string): string {
  return `Hello, ${name}!`;
}

Line Highlighting

Highlight specific lines with // [!code highlight]:

:root {
  --color-primary: #6366f1;
  --color-secondary: #a855f7;
  --radius-md: 0.5rem;
}

Focus

Dim everything except the lines marked with // [!code focus]. Hovering the block restores full opacity.

import { hash } from 'bcrypt';
import { db } from './db';

export async function createUser(email: string, password: string) {
  const hashed = await hash(password, 10);
  return db.user.create({ data: { email, password: hashed } });
}

export async function deleteUser(id: string) {
  return db.user.delete({ where: { id } });
}

Diff View

Show additions and removals with // [!code ++] and // [!code --]:

export const config = {
  theme: 'light',
  theme: 'dark',
  prefetch: false,
  prefetch: true,
  lang: 'en',
};

All Together

interface ButtonProps {
  label: string;
  variant?: 'primary' | 'ghost';
}

export function Button({ label, variant = 'primary' }: ButtonProps) {
  return (
    <button className={`btn btn--${variant}`}>
      {label}
    </button>
  );
}

Irradiation Illusion: Why white looks bigger than black

Fri, 20 Mar 2026 00:00:00 GMT

White text on dark backgrounds looks heavier than it actually is. Light bleeds past the edges of each letter, making the font appear bolder than it is.

Road sign designers figured this out decades ago. Fonts like Wayfinding Sans Pro built for highway signage ship two versions of every weight. The one meant for light-on-dark is thinner, so both look equal to a driver at speed.

Same idea works on the web. Make your light mode font-weight slightly heavier than your dark mode. Both will feel the same, even though they aren’t.

The fix is rather simple, just adjust the weights for both modes:

:root {
    --font-weight-regular: 450;
}

[data-theme="dark"] {
    --font-weight-regular: 400;
}

The kind of detail no one notices when it’s right. Everyone feels when it’s wrong.

Sometimes even after doing all the right things in theory, there are high chances it can feel off. Some manual adjustments has to be done in order for the design to appear natural in practice (not theory).

CSS Text Box Trim

Thu, 19 Mar 2026 00:00:00 GMT

Text always has weird extra space above capitals and below the baseline.

Just a simple two-line fix, perfectly trims the text box to the actual glyph bounds. No more padding hacks.

.text-box-trim {
  text-box-trim: both;
  text-box-edge: cap alphabetic;
}

As of early 2025, text-box-trim is available by default in Chrome 133+, Edge 133+, and Safari 18.2+ (sadly no Firefox womp womp).

VS Code Smooth Scrolling

Wed, 18 Mar 2026 00:00:00 GMT

{
    "editor.cursorBlinking": "smooth",
    "editor.cursorSmoothCaretAnimation": "on",
    "editor.smoothScrolling": true,
    "terminal.integrated.smoothScrolling": true,
    "workbench.list.smoothScrolling": true
}

CSS :has() selector is a parent selector

Tue, 17 Mar 2026 00:00:00 GMT

The :has() pseudo-class lets you style a parent based on its children. For example, div:has(> img) selects any div that directly contains an img. No more JavaScript hacks for parent selection!

git switch vs git checkout

Mon, 16 Mar 2026 00:00:00 GMT

git switch was introduced in Git 2.23 as a safer, more focused alternative to git checkout for switching branches. Use git switch for branches and git restore for files — clearer intent, fewer foot-guns.