Collection / Notes

Ideas in progress.

Working material that becomes clearer through revision, use, and connection.

Status: seedling/Type: fleeting

A writing waterway

I am considering “writing waterway” as another name for this site. The image starts with drops, which can gather into streams, join into rivers, and reach an ocean. It gives me a way to describe small observations becoming connected writing, while leaving room for ideas that stay local or evaporate.

A possible shape

  • Drops are individual observations, questions, or fragments. A log entry could hold one.
  • Streams connect a few drops around an idea. A developing note could do that work.
  • Rivers bring several streams together into a longer argument or explanation. Articles could sit here.
  • The ocean is the wider body of connected writing, including the work of other people that my thinking joins.

Maps could help readers follow a waterway, see where streams meet, and choose a direction. These are working associations. I have not decided to rename the site’s sections.

Water already appears in writing about blogging and knowledge. These are useful comparisons, though none of the pieces below sets out this exact drops-to-ocean structure.

  • Mike Caulfield’s The Garden and the Stream contrasts the chronological stream with a garden of connected, revisable ideas. That creates a useful challenge for my metaphor. I want a waterway where readers can trace connections and return upstream, without everything disappearing into a feed.
  • Robin Sloan’s Stock and flow describes short updates as flow and durable work as stock. He argues for using both. His distinction helps me ask whether a drop can contribute to something that remains useful after the day it was written.
  • Tom Critchlow’s Building a digital garden uses streams for Twitter, campfires for blogging, and gardens for deeper thinking. He also draws on Sloan’s stock-and-flow idea. His categories describe different spaces for writing, while I am considering how pieces of writing join together.
  • Maggie Appleton’s A Brief History & Ethos of the Digital Garden traces the garden metaphor and explains its emphasis on connected ideas and ongoing revision. Her discussion of streams builds on Caulfield. It is a useful check that a new name still leaves room for those habits.

A quick search did not surface an established blogging framework called “writing waterway.” That is a limited finding, and I am not claiming the phrase or the broader water analogy is original.

What I need to test

A waterway suggests movement and connection, but a drop does not have to reach the ocean. An idea can evaporate when I lose interest or find that it does not hold up. It can also stay in a local water cycle, returning as a question or a small note that helps with one part of my work. Neither path needs to produce a larger article to be useful.

That makes the metaphor less linear. Some ideas join a wider conversation. Others circulate close to where they began, or return later in a different form. Revision should still be possible anywhere in the system.

For now, I will keep this as a possible framing alongside why I am building a digital garden. The next test is whether drops, streams, and rivers make the site easier for a new reader to understand.

Read note →
Status: budding/Type: permanent

Design tokens are the styling layer

The old default was to choose a colour while building a component. It felt efficient on the first screen and became expensive by the twentieth, because the choices scattered. Six slightly different greys appear, nobody can say which one is correct, and a rebrand turns into a hunt through every file that ever touched a shade.

Design tokens fix that by moving the decision out of the component and into a named layer. A token is a value with a job. Ground, surface, text, muted text, heading, link, border, accent. The component asks for a role and never learns the hex.

Three layers, one direction

The pattern that holds up is three layers with a strict direction of travel.

The bottom layer is the raw palette. Petrol is #093558, mist is #DCE5F5, graphite runs from #0B0C0F to #F5F6F7. These are facts about the brand and they almost never change.

The middle layer is semantic. --ground points at a graphite step. --heading points at petrol. --link points at the action indigo. This is where the site’s intent lives.

The top layer is usage. Components and utilities read the semantic names. Nothing above layer two is allowed to contain a raw value.

The discipline is that changes travel upward only. A rebrand edits the palette. A redesign edits the semantics. A component edit never touches either, which is what keeps a component honest about what it needs.

Custom properties are the delivery mechanism

CSS custom properties are what make the middle layer switchable at runtime. They inherit, they can be overridden on a subtree, and a single class on the root can swap every value underneath it.

That is what a dark mode should be. Same token names, different values, one class on the html element. A second set of names for night mode, like --color-text-dark, is the tell that a system is about to fork.

Tailwind v4 makes it native

The version of this site’s stylesheet runs Tailwind v4, where configuration is CSS and the @theme block turns tokens into utilities. --color-link becomes text-link. --color-hairline becomes border-hairline. The design system and the utility names are the same object, which removes the usual mapping file nobody updates.

There is a second trick worth keeping. Tailwind ships palettes named gray, slate, blue, indigo. Re-pointing those names at brand ramps inside @theme changes every existing utility at once. The lightest step stays lightest, the darkest stays darkest, so text-gray-900 and its dark:bg-slate-800 neighbour both keep their meaning while wearing brand colour. That is how I moved forty components onto a new palette in one afternoon without opening forty files.

Use that trick deliberately. Re-pointing a stock palette is a migration tool, and the semantic names are where the design should end up living.

What a token system buys you

A rebrand touches one file. A reviewer can answer why a heading is that colour without opening a component. A new page inherits the current design instead of approximating it. And the whole layer becomes checkable, because the values resolve to something a machine can read. I ran a contrast sweep over every text element after the reskin and it found two real problems a visual pass had missed.

Where tokens do not help

Tokens cannot invent a palette that is not there. The brand blue ramp carries three usable blues, and four homepage cards wanted four hues. Forcing four produced a grey that read as disabled and a petrol that looked wrong beside its neighbours. The fix was a design decision, one chip treatment for all four, not a token.

Names also decay. --color-blue-500 describes a value and will lie after the next rebrand. --color-link describes a job and stays true. If a token’s name mentions a colour, it belongs in the palette layer and nowhere above it.

The test

A practical way to judge any styling setup, tokens or otherwise. Try to change the look of one thing across the whole site. If that means one edit, the system works. If it means a search, the system is still a collection of components that happen to share a file.

Read note →
Status: budding/Type: permanent

Wikilinks, markdown links, and router links are three different things

Writing a digital garden across an Astro site, Foam, and Obsidian means living with three link systems that look similar but resolve differently.

A wikilink, [[like-this]], is resolved by name against a whole vault. Obsidian and Foam both support it, but it has no meaning to a plain Markdown renderer or to GitHub, so a file full of wikilinks stops being readable outside those two tools.

A relative markdown link, [text](../log/entry.md), is resolved as a file path from the current file’s location. This is what a standard Markdown renderer, GitHub, VS Code, Foam, and Obsidian (when wikilinks are turned off) all agree on. It is the most portable option, which is why this garden uses it in the source files.

A router link, /log/entry, is resolved by Astro against the site’s routes, not against the filesystem. It is what the rendered HTML needs, but it means nothing to an editor trying to “go to file,” because no file exists at that literal path.

The remark plugin described in the log entry about this decision exists to convert the middle form into the last one: write relative markdown links for the sake of the editors, and let the build produce router links for the sake of the site. The source stays portable; only the compiled output is Astro-specific.

One consequence worth remembering: this conversion only understands links that point inside src/data/<collection>. A link to something outside the content collections, or a genuine external URL, should stay exactly as written.

Read note →
Status: budding/Type: permanent

Workspace Prettier and Astro plugin resolution

The red formatter indicator in VS Code was not reporting a formatting problem in the note. The project-local CLI passed the file with npx prettier --check, but the Prettier extension logged this error:

Cannot find package 'prettier-plugin-astro' imported from /noop.js

The important distinction was between two Prettier installations. AstroWind includes prettier and prettier-plugin-astro as development dependencies so the command line, CI, and every developer can use the same versions. VS Code also bundles its own Prettier as part of the esbenp.prettier-vscode extension. In this case the extension was loading the bundled copy while reading the project configuration, so the plugin could not be resolved from the project dependency tree.

Prettier 3 also removed automatic plugin searching. That is why .prettierrc.mjs explicitly lists prettier-plugin-astro and manually assigns the astro parser for .astro files. Removing the plugin would hide the error for some files but would make the project formatter unable to understand Astro syntax.

The durable fix is to point VS Code at ./node_modules/prettier and use the Prettier extension for both Astro and Markdown files. Markdown does not need the Astro plugin because Prettier supports Markdown natively. It still uses the project’s shared options, while .astro files additionally use the Astro parser and plugin.

This keeps editor formatting aligned with npm run check:prettier and avoids relying on whatever Prettier version happens to be bundled with the editor extension.

Read note →
Status: budding/Type: permanent

An Astro site is a small system

I am treating this Astro site as a small system rather than a collection of pages. The visible pages matter, but they are the surface. Underneath them are a content model, a set of routes, a publishing rhythm, and a few decisions about what should stay simple.

The content collections give the system its vocabulary. A log entry records a moment. A note gives a useful idea enough room to develop. An article makes a longer argument and names the sources that shaped it. A map helps a reader move between those pieces without needing to understand the folder structure first.

That separation is practical. It lets me choose the right size for a thought instead of forcing every idea to become an article. It also makes the site easier to maintain, because the schema describes what each type is for while the pages focus on making the content readable.

The next test is whether the structure continues to help after the novelty of setup wears off. If adding a piece of writing feels heavier than writing the piece, the system needs to become simpler.

Read note →
Status: seedling/Type: permanent

What a note is for

A note is where I give an idea enough room to become useful. It is longer than a log, but it does not need to be a finished argument. I use notes to make a distinction, capture a lesson, respond to something I have read, or preserve a question that deserves another visit.

The stage matters because ideas have different jobs. A seedling is an invitation to keep looking. A budding note has a shape and a few connections. An evergreen note has earned its place through revision and reuse. None of those labels is a judgment of quality. They simply tell me how much attention an idea has received.

A good note should be understandable when I return to it later. It should say what I think, what changed my mind, and where the next question might lead.

Read note →