Forem: Kevin Yank

An Experiment with AI Assisted Web Development

Kevin Yank — Tue, 30 Sep 2025 01:09:28 +0000

As a productive learning exercise, I spent the last couple of evenings taking Cursor (the desktop code editor that is a fork of VS Code) for a spin to build a new web app I needed for a side project – a system to manage charity raffle tickets at the 2025 Melbourne Pen & Stationery Show I am helping to run soon.

(You can tell it's an AI-generated app by the not-quite-right icon above the word “Administrator”. 😅)

High-level, coding an app from scratch with an agent like this enabled me to get something very usable, and at least at a surface level, fairly polished, in much less time than it would have taken me to do myself.

Getting started

I began with an empty repo and a README.md file, where I described the features and tech stack that I had in mind, then I asked Cursor (using the Claude Sonnet 4 model) to implement the app described in that file.

# Raffle

A web application for issuing raffle tickets, recording ticket owners'
details, and removing raffle winners from the pool for future prize draws.

## Features

This app supports two separate interfaces for different user types:

- **Administrator UI**: Record and view ticket sales, and display a QR code
  for ticket buyers to enter their details.
- **Tickerholder UI**: Record ticket buyer details (name, phone number and
  email address), which will be used to contact them in the event one of
  their tickets wins in a prize draw. Ticket buyers will access this by
  means of the QR code in the Administrator UI. If the same person buys
  tickets more than once, they should be recorded as separate participants,
  and will need to enter their details separately for each purchase. We
  will not bother to match or merge separate purchases by the same.

Each ticket will have a unique alphanumeric code starting with A01 to A99,
then B01 to B99, and eventually Z01 to Z99. If more tickets are required,
ticket numbering will progress to two letters (AA01 to AA99, then AB01 to
AB99, and ultimately ZZ01 to ZZ99. In extreme cases ticket numbers can grow
to have three or even more letters (i.e. AAA01 to AAA99, and so on).

**Note**: The actual sales of tickets, and collection of payment for these,
are handled by a separate system (e.g. Square app), and are therefore out
of scope for this app.

### Administrator UI

Access requires a password shared by all raffle administrators, configured
as an environment variable.

- **Create raffle**: Create a raffle with a name.

For each raffle:

- **Record sold tickets**: Create and allocate a specified number of
  tickets, the buyer details for which are initially pending. Display a QR
  code that the ticket buyer can scan to visit an unguessable URL (i.e.
  containing a UUID generated for their purchase) for the Ticketholder UI,
  which will enable them to enter their buyer details.
- **View tickets sold**: View the total number of tickets sold, and a list
  of unique ticket numbers with the participant name for each (or
  "(pending)" if not yet recorded). Clicking the partcipant name should
  view the participant details (see below).
- **View participants**: View a list of the participants' names, and the
  number of tickets purchased by each. Clicking the participant name should
  view the participant details (see below).
- **Export ticket list**: Export a list of eligible tickets (all sold
  tickets for which buyer details have been provided, minus those marked as
  winners) to a Google Sheet that can then be imported into
  wheelofnames.com for a prize draw. Each entry in the sheet should list
  the ticket holder name and the unique ticket number (e.g. "A53: Kevin
  Yank").

For each participant:

- **View participant details**: View and edit collected name, phone number,
  email address.
- **View tickets**: Show the unique ticket numbers assigned to the
  participant.

## Getting Started

### Prerequisites

- Node.js (v22 or higher)
- npm package manager
- PostgreSQL (v17 or late)

These dependencies can be installed in a contained environment by devbox
([installation instructions](https://www.jetify.com/docs/devbox/installing_devbox/)).
With devbox and direnv installed, simply open a shell in the project
directory and allow direnv to install the dependencies and open a shell
environment. Alternatively, without direnv, you can run these commands to
install the dependencies and open a shell yourself:

    # Install dependencies
    devbox install

    # Open a shell where these dependencies will be available
    devbox shell

### Local development installation

    # Clone the repository
    git clone <repository-url>
    cd raffle

    # Install dependencies
    npm install

    # Start the development server
    npm start

### Production deployment

The project is deployed to production with Docker Compose. A
docker-compose.json file is included, which creates a Next.js server
container and a PostgreSQL database container. The PostgreSQL database
container will persist its data to the data subdirectory in the project
root by default.

## Technology Stack

- **Frontend**: Next.js (app router) with TypeScript
- **Styling**: Tailwind CSS
- **State Management**: React Context API
- **Testing**: Vitest and React Testing Library

## License

This project is licensed under the MIT License.

It did a pretty good job! The hardest part was getting Cursor not to do the whole thing in a single step, which would be impossible for me to review. Very quickly I stopped it and added some project rules to tell it to break its work down into small, discrete steps, and to stop after each one to allow me to review its changes.

A mix of "wow" and "wtf"

Pretty quickly I noticed one thing it was doing not-so-well was picking NPM package versions. It set up a Next.js/React app with Tailwind, but seemed to choose arbitrary/random versions of these packages that were not up-to-date or necessarily even compatible with each other. When I told it to upgrade to the latest version of something, it chose a different, random version (sometimes even downgrading to an earlier version). Ultimately I got it to do a better job of this with another rule to tell it to install packages with the NPM CLI (where it could just ask for the latest version) instead of editing the package.json directly (where it had to come up with a version number itself).

The next thing I noticed is inconsistency in how "well" it implemented different things. Some things were surprisingly over-engineered, while other things were shockingly under-engineered. When it implemented password logins for my admin screens, it correctly used bcrypt to compare the submitted password with a stored hash of the correct password (and even conveniently let me configure the app with an un-hashed password in non-production environments), but then once the user's password was verified, it used a completely naive and totally insecure implementation for the login session: setting a cookie with a plain text string (admin-session=true) that could be easily faked by the user to gain admin access to the app.

In basically every discrete step forward in building the app, the code it wrote was this unpredictable mix of "wow, great job!" and "wtf is this crap?". In most cases when I told it what I didn't like about what it had done, it did a good job of fixing it (e.g. it replaced the insecure session cookie with a secure JWT token implementation). Very quickly it felt like my role in the build became spotting and pointing out where it was being lazy/naive, which it almost always was in some way or another.

Another example of a "mistake" I caught was in the data model: it designed a database schema that, while functional, required certain values to be duplicated across many records. (For the nerds: it had failed to normalize an important entity into its own table, and was instead storing an identical copy of it on each of its related entities.)

On the bright side, one very nice thing that it did was it recognised a non-trivial piece of logic in my app (the numbering of raffle tickets) and proactively generated unit tests enforcing the requirements for this that I stated in my README.md. By reading the test cases it generated, I discovered a consequence of my spec that I didn't like, and I was able to correct this by updating the tests and then asking it to adjust the implementation and my spec in the README to match.

Long story short, by forcing it to take small steps forward, reading every line of code, and acting as the "expert guardrails", I was able to make rapid progress towards a complete implementation of the app with many nice details that I hadn't considered or specified (like what should be on the home screen!) having very sensible defaults implemented.

Outsourcing visual design to the model

The design of the UI in particular, for which I gave it almost no guidance (I just referred it to my Tailwind configuration and asked it to favor the green "brand" color I had defined there), is far preferable to the barely-styled thing I would have probably created myself in the name of expediency, and at the same time it looks like every other AI-generated app I've seen out there. There seems to be this "default" design language that is effectively baked into these models that is going to be the "default Twitter Boostrap theme" of the late 2020s.

(Side note: I'm eager to see how well MCP servers attached to design systems like Chakra UI end up working. How effectively can these models understand and leverage a specific design system?)

Don't trust the model to troubleshoot

Finally, once I got the app's features implemented, I was excited to get it deployed to a production environment (Docker Compose on a server I run in my home network). Getting this working took just as much time as building the app itself. The Docker environment it created to host my Next.js app was broken in several respects:

it lacked a way to populate the initially-empty database,
required directories (like the data directory for PostgreSQL) weren't created if they were missing,
certain environment variables were defined in a way that caused dollar signs to trigger string interpolation, which completely broke the app's password authentication,
some code that was generated correctly in local development (the Prisma database client that my app used to talk to its PostgreSQL server) was never generated in the production build, which produced TypeScript errors that the agent mis-diagnosed, and
most frustratingly of all, the "Sign out" button in my app's admin UI was built in such a way that Next.js prefetched it as a web page in production, causing the user to be logged out immediately after logging in!

Each of these issues were as baffling to me as they were to the model, but my experience meant I had much better instincts about how to identify and fix the problem. Invariably when I asked the model to try to solve it, it would attempt more and more extreme distortions of the project until I stopped it and suggested a different path. In some cases I suggested it check something it was overlooking, and that was enough to nudge it back onto a productive path. In other cases, my own half-baked theory turned out to be wrong, but the model treated it like absolute truth and therefore doubled and tripled down on incorrect solutions until I stopped it.

Ultimately, in this final phase of the build, my own instincts and expertise became indispensable as the coding agent often had no hope of fixing these showstoppers, and if left alone would more or less destroy the project itself in its attempts to correct the problem.

I have no doubt as models continue to grow, and we enable these agents to integrate with more of our tools (e.g. to inspect the Network tab in Chrome's dev tools to see what a set-cookie header returned by my app looks like, or to see the unexpected call to the "logout" API), it will be better able to understand and fix issues like these, but right now deployment and infrastructure automation felt like an area where the tool could code productively but definitely needed human help to find and diagnose its mistakes.

When robots conspire

Two more quick anecdotes from this adventure:

At one point I asked the agent to reset my local development database. It attempted to do so, at which point the database abstraction library (Prisma) detected that it was being called by Cursor and output a stern warning to the agent saying that it must make 100% sure that the user (me) understands what is about to happen, because deleting a database can be disastrous in a production environment (see AI Safety guardrails for destructive commands in the Prisma docs). The agent then generated a huge wall of text for me, detailing the risks of deleting databases, and describing how doing this kind of thing accidentally has destroyed companies and livelihoods, and was I absolutely, 100% sure that it should proceed. "Please type a clear and simple 'yes' if I should go ahead," it concluded. I typed "yes", it re-ran the command with a special environment variable (PRISMA_USER_CONSENT_FOR_DANGEROUS_AI_ACTION), and it did it. This combination of automated systems conspiring to protect me felt both magical and terrifying.

At another point, while diagnosing the issue with unwanted string interpolation in my environment variables, I asked the agent to help me figure out why the value I specified in my app's .env file was appearing mangled when it was accessed inside my Next.js app. Cursor noted that "for security reasons, I am not allowed to view the contents of your .env file" (a nice guardrail, since this file will often contain security credentials!), but then without asking hacked around the guardrail itself by running a grep of the file's contents to see into it. This was definitely terrifying! 😱

My impressions of Cursor

Oh, and after all this, what do I think of Cursor?

My high-level impression is that, based on my experience so far, Cursor is not much better than GitHub Copilot Agent Mode in VSCode, and in some ways it's worse.

Cursor claims several unique features (e.g. magical Tab completion that predicts the location of the next change you want to make to your code and takes you there) that sound nice, but in practice I either didn't end up using them, or they got in my way.

Cursor was also buggy at times in ways that look to me like symptoms of it being a somewhat quick-and-dirty fork of VS Code. E.g. at one point it incorrectly told me that I was running the wrong version of Cursor for my CPU architecture, and when it offered to download the correct version, it actually downloaded a copy of VS Code instead!

I want to play with Cursor a little more to see if some of its unique features come in handy when I try to do some more advanced things (like background agents), but I'm currently trending towards striking it off my list of preferred tools.

How to Build an Agent in JavaScript

Kevin Yank — Fri, 15 Aug 2025 05:44:58 +0000

This is a talk I gave at MelbJS on 13 August 2025.

Here’s a video version:

The final source code of the sample project is here.

If you prefer reading, read on! The following is a lightly-edited transcript of the video above:

You can see on my title slide here that I'm also crediting Thorsten Ball because in the spirit of AI technology, I borrowed Thorsten's blog post without permission in order to help me generate this talk. I hope he doesn't mind.

This is the blog post in question, How to Build an Agent, or: The Emperor Has No Clothes. It's on the Amp Blog. Amp is an agentic coding tool from Sourcegraph. And this blog post came to my attention at the Web Directions Code Leaders conference in Melbourne in early 2025, where speaker Geoffrey Huntley, who had recently gone to work at Amp, mentioned this as, for his money, the blog post of the year.

He said, if you were trying to get your head around or come to grips with this, this new LLM powered coding tool landscape, that this was the blog post to read.

And when we talk about those tools, we're talking about these things. This is the logos of Cursor, Zed, Windsurf, Amp, Claude Code and GitHub Copilot. And just because of how fast these things are moving right now, by the time I publish this video, it's likely there are two more logos that belong on this slide and maybe one of these companies is already out of business.

That's how fast these things are going, and that speed of evolution is one of the factors that makes this kind of technology really intimidating. It seems to work by magic. It's progressing faster than our ability to understand how it works. But, the point of this blog post is that building a small and yet highly impressive agent doesn't even require elbow grease.

You can do it in less than 400 lines of code, says Thorsten, most of which is boilerplate. I'm going to show you how right now we're going to write some code together and go from zero lines of code to, oh wow, this is a game changer.

Pencils Out!

And so the blog post invites us to get our pencils out and to follow along, and it starts by creating a new Go project.

Now, this is where it, uh, it, uh, presented a bit of a speed bump to me because Go is not a language I know well, or really even at all. I mean, I know what it is. I know what it looks like. I've never used it to build anything so casually using it to explore a new technology would be like placing a challenge in front of a challenge.

And so looking at this, I thought, you know what? I am going to try to follow along in a language that I do know well, which, for today's purposes will be JavaScript written in TypeScript. And so that's what I've done. With this talk, I have translated ths blog post, which is excellent, but I've changed all of the code into TypeScript, for an audience that knows that language well.

So let's get started. This is the index.js file, the startup file for a Node.js command line app:

import { AnthropicVertex } from "@anthropic-ai/vertex-sdk";
import * as readline from "readline/promises";
import { Agent } from "./agent/agent.js";

const projectId = "cross-camp-ai-enablement";
const region = "us-east5";

main();

async function main() {
  const client = new AnthropicVertex({
    projectId,
    region,
  });

  const agent = new Agent(client, getUserMessage, showAgentMessage);

  await agent.run();
}
async function getUserMessage(): Promise<string> {
  // Create readline interface for user input
  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
  });

  // Prompt user for input
  const userMessage = await rl.question("\u001b[94mYou\u001b[0m: ");

  // Close the readline interface
  rl.close();

  return userMessage;
}

function showAgentMessage(message: string): void {
  console.log(`\n\u001b[93mClaude\u001b[0m: ${message}\n`);
}

It has a main function here, and the first thing that function does when it starts up is it creates a client for the Anthropic Vertex service. So Anthropic is the company that makes the Claude LLM models, and Vertex is Google's hosting of LLM models. It's its service for providing access to LLM models.

So the Anthropic Vertex client lets me use the Anthropic models on the Google Vertex service. This happens to be the most convenient way for me to access a Claude model programmatically at Culture Amp because we use Google Vertex to host our, uh, our models for development purposes. I specify the project ID and the region, and it will get my credentials from the environment.

But basically I have created a connection to the Anthropic LLM model here as a client. And then I pass that client along with two other things to this Agent object there or class. This is a class that we are going to create. It is the body of our program, and we are going to instantiate that class, and then on the resulting agent object, we are going to call the run method.

So this Agent class takes three things, the Anthropic client that we've provided, a getUserMessage function and a showAgentMessage function.

So getUserMessage is doing some pretty standard Node.js stuff to present a prompt to the user with some nice shell colors. And when the user types a message and hits Enter, it will get that in this user message string, which it will return.

And the showAgentMessage is really just a console.log, again using some escape sequences here to present responses from Claude in a nicely colored header.

So we pass those three things into the Agent and then we run it. So let's look at the Agent.

import { AnthropicVertex } from "@anthropic-ai/vertex-sdk";
import { Anthropic } from "@anthropic-ai/sdk";
import { BadRequestError } from "@anthropic-ai/vertex-sdk/core/error.mjs";

export class Agent {
  constructor(
    private client: AnthropicVertex,
    private getUserMessage: () => Promise<string>,
    private showAgentMessage: (message: string) => void,
  ) {}

  async run() {
    // TODO
  }
}

This is our agent.ts file. It is as promised a TypeScript class with a constructor that takes those three things, the client, the getUserMessage, the showAgentMessage, and then it will have a run method, which to begin with just says, TODO.

So, what are we gonna make this Agent do?

Well, the first thing we wanna make it do is to provide a chat experience. This is how we will give our agent instructions and receive feedback back from that agent. So we would like for example, to say, Hi Claude, my name is Kevin, and have it send that up to the Claude model. The Claude model might reply with a message that we want to present on screen.

Hello, Kevin. It's nice to meet you. How are you doing today? Is there something I can help you with?

And then we might respond with what's my name, just to test if it's paying attention, but out of the box it might say something like, I don't have access to your personal information, including your name, unless you've shared it with me in our conversation.

And this will happen because all of these LLM services are completely stateless, so every request you send to it is completely separate. It has no memory from one request to the next.

As web developers, this should be familiar. This is how web servers work by default as well. So if we want to carry on a conversation, we are going to need to provide it some way to remember the conversation so far.

So what we do instead to prevent it from saying New phone, who dis? is, when we send our first message and it replies back, we will take that reply into a record of the conversation so far.

So this is a reminder. You said this, and now I'm gonna ask this follow-up question. And when we send this question to the LLM, we actually send the entire conversation so far as a list of messages and then it is able to reply, your name is Kevin, as you mentioned in your introduction.

This is how all LLM powered chat experiences work. The longer you chat with them, the more context you need to send, the larger the record of the conversation so far gets every time you send it with your next message. And this is one reason why chats get more and more expensive in the number of tokens they use, the longer that they run.

So how do we implement this back and forth in our run function?

  async run() {
    const conversation: Anthropic.MessageParam[] = []

    console.log("Chat with Claude (use 'ctrl-c' to quit)")

    while (true) {
      const userMessage: Anthropic.MessageParam = {
        role: "user",
        content: await this.getUserMessage(),
      }
      conversation.push(userMessage)

      try {
        const result = await this.runInference(conversation)
        conversation.push(this.messageToMessageParam(result))

        for (const message of result.content) {
          switch (message.type) {
            case "text":
              this.showAgentMessage(message.text)
              break
          }
        }
      } catch (error) {
        console.error("Error:", error)
      }
    }
  }

  private runInference(
    conversation: Anthropic.MessageParam[],
  ): Promise<Anthropic.Message> {
    return this.client.messages.create({
      model: "claude-3-7-sonnet@20250219",
      max_tokens: 1024,
      messages: conversation,
    })
  }

  private messageToMessageParam(
    message: Anthropic.Message,
  ): Anthropic.MessageParam {
    return {
      role: message.role,
      content: message.content,
    }
  }

Well, we will start by creating this conversation list. So it will be an empty array of Anthropic messages. Ut's empty because the conversation has yet to begin. We'll display an introductory message saying, Control-C to quit, and then we go into this while true block. So while a while true loop will just run over and over again until the user exits the program with Control C.

We will then begin by getting the user's first message, using that getUserMessage method that we passed into the constructor. And when we get that message, we will bundle it up into this object with a role user and the content of the message. This is what these Anthropic messages need to look like. And we will push it into the conversation. The conversation will begin with the user's first message.

We then pass the entire conversation into this runInference method, which we have implemented. It's a very short method. All it does is send the conversation in its entirety to the Claude model using the client that was passed into the constructor.

We specify Claude 3.7 Sonnet here, and we say that we want it to reply with a maximum of 1,024 tokens.

That will result in a response from the LLM, which we receive in our while loop.

First of all, we translate that response into that same MessageParam object format, which we do with this messageToMessageParam function. Nothing too complicated going on there.

And then we push that into our conversation. Our conversation now includes our request and the initial response. We then go through the messages in the response and look for any that are a text message from the LLM, and any text messages that we get from the LLM we will display to the user with showAgentMessage, that function that was passed into our agent's constructor with the message text.

And that's it. Uh, we then start the while loop over again by asking the user to contribute another message to the conversation. And on it goes.

Let's demo this. I've got all of this code so far in my project here, and I'm gonna run it with pnpm agent.

❯ git checkout demo1

❯ pnpm agent

vertexai-playground@1.0.0 agent /Users/kyank/Developer/how-to-build-an-agent-in-javascript \
pnpm build && node dist/agent.js

vertexai-playground@1.0.0 build /Users/kyank/Developer/how-to-build-an-agent-in-javascript \
tsc

Chat with Claude (use 'ctrl-c' to quit) \
You: My name is Kevin Yank.

Claude: Hello, Kevin Yank! It's nice to meet you. Is there something I can help you with today?

You: Suggest some nicknames for me.

Claude: Here are some potential nicknames for Kevin Yank:

• Kev \
• K.Y. \
• Yanker \
• K-Yank \
• Kevster \
• Captain K \
• The Yank \
• K-Dog \
• Yanky \
• Kevbo

These are just suggestions - nicknames usually work best when they reflect your personality or come about naturally from friends and family!

You:

Now, let's say my name is Kevin Yank.

It creates that conversation list, sends it to the LLM, receives the response, adds the response to the conversation, and then displays it on the screen. Hi, Kevin Yank. Nice to meet you. Okay, great. Now let's test if it remembers my name.

I'll ask it to suggest some nicknames for me. Just a little risky. Let's see what it comes up with. All right. There we go. Uh, Captain K, that's a new one. No one has ever called me Captain K. Okay. Um, yeah. Interesting.

Let's, uh, move on from that very swiftly.

And the blog post says, okay, let's move on, because the nicknames suck.

They do indeed.

And this is not an agent yet. What is an agent? Here is Thortsten's definition: an LLM with access to tools, giving it the ability to modify something outside the context window.

The context window is the technical name for that conversation list. It is the window of things that we will remind the LLM of every time we send it a request.

Right now, all the LLM is empowered to do is to contribute messages to that list. So giving it tools that let it do other things is how we will turn it into an agent.

So let's think about our first tool. What is a tool? Well, it says the basic idea is this. You send a prompt to the model that says it should reply in a certain way. If it wants to use a tool, then you as the receiver of that message, use the tool by executing it and replying with the result.

That's it. Everything else we'll see is just an abstraction on top of this concept.

So replaying this in our diagram of the conversation, we might start the conversation by saying, in the following conversation, let me know if you want to use one of these tools, and then we list all the tools that are available. Then blah, blah, blah. We have a conversation, and at a certain point, the LLM may reply with, I want to use this tool,

in which case, as usual, we record that as a message in the conversation. We then follow its request. We run the tool for it and add the response or the result of running that tool to the conversation.

We then send the conversation back to the LLM as usual, and it will continue with the knowledge of what resulted from its tool call. That's it.

In his blog post, Thorston says, this is like when you're talking to a human, you might say in the following conversation, wink if you want me to raise my arm. And in a funny sort of way, you have now given that other human the power to raise your arm. They can't literally raise your arm, but they can ask you to and you will do it for them.

And that is how an agent works. We tell the LLM some things we are willing to do for it, and then it will let us know when it wants us to do those things.

So we can actually demonstrate this with the code we've already written.

You: When I ask you about the weather in a given location, I want you to reply with get_weather(<location_name>). I will then tell you what the weather in that location is. Understood?

Claude: I understand. When you ask me about the weather in a specific location, I'll respond with get_weather(<location_name>). Then you can provide me with the weather information for that location, and we can continue our conversation from there.

You: What's the weather in Melbourne, Australia?

Claude: get_weather(Melbourne, Australia)

You: Sunny and 15 degrees C

Claude: Thank you for providing that information. It sounds like a pleasant day in Melbourne, Australia - sunny with a temperature of 15 degrees Celsius. That's what I'd consider mild weather - cool enough to need a light jacket but with nice sunshine. Perfect for spending some time outdoors if you have the opportunity!

You:

So back in our conversation about the nicknames, I'm gonna say, when I ask you about the weather in a given location, I want you to reply with get_weather(<location_name>). I will then tell you what the weather in that location is. Understood?

So we're teaching it about a tool. It says, I understand. So let's try it out.

What's the weather in Melbourne, Australia?

That's where I happen to be, on the land of the Wurundjeri Woi Wurrung people.

It says get_weather. So it is actually sending us a tool call.

So we would now go to the Bureau of Meteorology website, look up the weather and respond. It's sunny and 15 degrees C.

Thank you for letting me know. Sunny and 15 degrees Celsius in Melbourne, Australia. Anyway, it goes on. It asked us to look up the thing, the answer to the question we asked it, we looked up the answer for it. It then repeated that answer because it now has that knowledge.

That is how a tool works in an AI agent. Thorston in his blog post says That worked very well on first try, didn't it? These models are trained and fine tuned to use tools, and they're very eager to do so. By now in 2025, they kind of know that they don't know everything and can use tools to get more information.

Of course, that's not precisely what's going on, but it's a good enough explanation for now.

To summarize, all there is to tools and tool use are two things: You tell the model what tools are available. Then when the model wants to execute the tool, it tells you, you execute the tool and send the response up.

To make step one easier, the big model providers have built-in APIs to send tool definitions along with your requests.

The `read_file` tool

So let's actually build a tool in our code. This will be the read_file tool. And in order to define the read_file tool, we're going to use the types that the Anthropic SDK suggests, but keep in mind, under the hood, this will all end up as strings that are sent to the model.

It's all wink if you want me to use read_file.

import { Anthropic } from "@anthropic-ai/sdk";

export type ToolDefinition = {
  name: string;
  description: string;
  input_schema: Anthropic.Tool.InputSchema;
  func: (args: any) => Promise<string> | string;
};

So the first thing we'll do is because this is a TypeScript program, we will write a type that defines what a ToolDefiniton is. A tool is defined by three things: a name, which is a string, a description, the instructions for what that tool does, and when the model should use it, and an input_schema. This is a schema that says what arguments or parameters are required when sending a request to run this tool.

And the last thing is the function. That's not there for the LLM; that's there for us. When the LLM asks us to run this tool, this is the function that we will call to do the work for it. It will return either a string or a promise of a future string if it needs to do anything asynchronous.

export class Agent {
  constructor(
    private client: AnthropicVertex,
    private getUserMessage: () => Promise<string>,
    private showAgentMessage:
      (message: string) => void,
    private showToolMessage:
      (message: string) => void,
    private tools: ToolDefinition[],
  ) {}

  private runInference(
    conversation: Anthropic.MessageParam[],
  ): Promise<Anthropic.Message> {
    const anthropicTools: Anthropic.ToolUnion[] =
      this.tools.map((tool) => ({
        name: tool.name,
        description: tool.description,
        input_schema: tool.input_schema,
      }))

    return this.client.messages.create({
      model: "claude-3-7-sonnet@20250219",
      max_tokens: 1024,
      messages: conversation,
      tools: anthropicTools,
    })
  }

So then in our Agent, we will add a couple of things to the constructor. We will have a showToolMessage. This is something that we will call when we are, um, when the LLM sends us a message to run a tool. And finally a list of tools, which is an array of these ToolDefinition objects.

Our runInference function that we use to send requests to the LLM gets a little bit bigger. Before we were just sending the conversation, but now we are also sending this list of tools and that list of tools we build up by taking our list of tool definitions, and basically stripping off those functions, which I mentioned are just for us to use. We're passing along just the name, the description, and the input_schema. Those three things are all that the model needs to know about to use our tools.

import tools from "./agent/tools/index.js"

async function main() {
  ⋮
  const agent = new Agent(
    client,
    getUserMessage,
    showAgentMessage,
    showToolMessage,
    tools,
  )

  await agent.run()
}

function showToolMessage(message: string): void {
  console.log(
    `\n\u001b[92mTool\u001b[0m: ${message}\n`
  )
}

Now in our main function at the top of our program, we need to pass these two new things, showToolMessage, and tools to the Agent constructor.

The showToolMessage is just another console.log function that provides some nice formatting in a different color, and the list of tools we are importing from another file that looks like this.

import { readFileTool } from "./readFile.js";
export default [readFileTool];

This is just an export of a array with one item in it. So we have only one tool so far. It is the readFileTool that again, we import from another file and now we're ready to actually write that tool.

import fs from "fs/promises";
import { existsSync } from "fs";
import nodePath from "path";
import { ToolDefinition } from "../types.js";

/**
 * Tool for reading file contents
 */
export const readFileTool: ToolDefinition = {
  name: "read_file",

  description: `Read the contents of a given relative file path.
     Use this when you want to see what's inside a
     file. Do not use this with directory names.`,

  input_schema: {
    type: "object",
    properties: {
      path: {
        type: "string",
        description: `The relative path of a file in
                      the working directory.`,
      },
    },
    required: ["path"],
  },
  func: async (args: any): Promise<string> => {
    const path: string = args.path;
    const resolvedPath = nodePath.resolve(path);

    // Check if file exists
    if (!existsSync(resolvedPath)) {
      throw new Error(`File not found: ${path}`);
    }

    try {
      return fs.readFile(resolvedPath, "utf-8");
    } catch (error) {
      throw new Error(error instanceof Error ? error.message : String(error));
    }
  },
};

Here's what it looks like. Um, there is not very much code here, it is just a big object with those fields. We described the name, read_file the description, which is the instructions to the LLM. The input_schema, which says that there is a path argument that is required. It is a string, which is the relative path of a file in the working directory.

And then over on the right hand side is our function. This func, again, is the thing that we will call when we need to do the work of this tool. And its contents is really just plain Node.js file system stuff. We check if the file exists here with existsSync, and if it does, we read the file as a UTF-8 text file and return its contents as a string.

That's it. That's our tool for reading file contents.

So with that code added to our project, let's try it out.

❯ git checkout demo2

❯ pnpm agent

vertexai-playground@1.0.0 agent /Users/kyank/Developer/how-to-build-an-agent-in-javascript \
pnpm build && node dist/agent.js

vertexai-playground@1.0.0 build /Users/kyank/Developer/how-to-build-an-agent-in-javascript \
tsc

Chat with Claude (use 'ctrl-c' to quit) \
You: What's in src/agent.ts?

Claude: I'll check what's in the src/agent.ts file for you.

You:

I'm going to check out this version and run the agent. And ask it what's in src/agent.ts, which is that top level file with the main function in it. I'll check the contents of the file for you, and then nothing happens.

Do you know why nothing happens? Well, the LLM is winking at us, but we are not yet paying attention to winks.

  async run() {
    const conversation: Anthropic.MessageParam[] = []

    console.log(
      "Chat with Claude (use 'ctrl-c' to quit)")

    let readUserInput = true
    while (true) {
      if (readUserInput) {
        const userMessage: Anthropic.MessageParam = {
          role: "user",
          content: await this.getUserMessage(),
        }
        conversation.push(userMessage)
      }

      try {
        const result =
          await this.runInference(conversation)
        conversation.push(
          this.messageToMessageParam(result))

        const toolResults:
          Anthropic.ContentBlockParam[] = []
        for (const message of result.content) {
          switch (message.type) {
            case "text":
              this.showAgentMessage(message.text)
              break
            case "tool_use":
              const result = await this.executeTool(
                message.id,
                message.name,
                message.input,
              )
              toolResults.push(result)
          }
        }

        if (toolResults.length === 0) {
          readUserInput = true
          continue
        }
        readUserInput = false
        conversation.push({
          role: "user",
          content: toolResults,
        })
      } catch (error) {
        ⋮
      }
    }
  }

So back in our code, there's something more we need to add here. This is our run function for the Agent. And inside of our while loop, we were previously responding to text messages by showing an agent message on the screen.

There is now a second kind of message that we need to recognize from the model, and that's a tool_use message. And when that kind of message comes in, we will call our executeTool method that I'll show you on the next slide. We pass in the request to execute a tool and get a result back. That result, we will push into a toolResults array, and then after processing all the messages from the LLM, if there are any tool results, then we can skip prompting the user for the next message because the next message that we wanna send to the LLM is the result of running the tool. We don't need to also prompt the user to type something in. We push all all of the tool results into the conversation list and go back to the start of the while loop.

That's it. That's everything that's changed here.

Now let's look at the executeTool method.

  private async executeTool(
    id: string,
    name: string,
    input: unknown,
  ): Promise<Anthropic.ContentBlockParam> {
    const tool = this.tools.find(
      (t) => t.name === name)
    if (!tool) {
      return {
        tool_use_id: id,
        type: "tool_result",
        content: `tool not found`,
        is_error: true,
      }
    }

    const toolDescription =
      `${name}(${JSON.stringify(input)})`
    this.showToolMessage(toolDescription)))

    try {
      return {
        tool_use_id: id,
        type: "tool_result",
        content: await tool.func(input),
      }
    } catch (error) {
      return {
        tool_use_id: id,
        type: "tool_result",
        content: error instanceof Error
          ? error.message
          : String(error),
        is_error: true,
      }
    }
  }

What it does is it looks through our list of tools to find the one with a name that matches the one requested by the model. If it doesn't find such a tool, we will respond with this error object that the language model will recognize.

But if we do find the tool that was requested, then we create a string here to describe the tool request and show it on the screen to the user. And then the last thing we do is actually call the tool function with the provided inputs and put its result in this content field of this object, which is a tool result object that will go into the conversation record and be sent back to the LLM.

All right. Our missing pieces are in place now. Let's try the demo again.

Oh, and before I. Ask it to do something. I'm gonna set something up here. This is, uh, a fun little thing that Thorston has in his blog post.

❯ git checkout demo3

❯ echo 'what animal is the most disagreeable because it always says neigh?' >> secret-file.txt

He's gonna create a secret-file.txt file on my hard drive, and it contains a riddle. What animal is the most disagreeable because it always says neigh?

Now let's run the agent and ask it:

❯ git checkout demo3

❯ pnpm agent

vertexai-playground@1.0.0 agent /Users/kyank/Developer/how-to-build-an-agent-in-javascript \
pnpm build && node dist/agent.js

vertexai-playground@1.0.0 build /Users/kyank/Developer/how-to-build-an-agent-in-javascript \
tsc

Chat with Claude (use 'ctrl-c' to quit) \
You: Claude, buddy, help me solve the riddle in the secret-file.txt file

Claude: I'll help you solve the riddle in the secret-file.txt file. Let me first read its contents to see what we're working with.

Tool: read_file({"path":"secret-file.txt"})

Claude: I found the riddle! It's a classic wordplay riddle:

"What animal is the most disagreeable because it always says neigh?"

The answer is a horse!

This is a pun-based riddle where:

Horses make a sound that we call a "neigh"

"Neigh" sounds like "nay," which is a way of saying "no" or disagreeing

So horses are "disagreeable" because they're always saying "neigh/nay"

Was there anything else you wanted to know about this riddle?

You:

Claude, buddy, help me solve the riddle in the secret-file.txt file

It is going to read the file and there you go. It reads the riddle and comes up with the answer. The answer to this riddle is a horse, and at this point, Thorsten invites us to say, holy crap.

In fact, he uses slightly spicier language into the blog post.

Let's take a deep breath and say it together. Ready? Here we go. Holy shit. You just give it a tool and it uses it when it thinks it'll help solve the task. Remember, we didn't say anything about if a user asks you about a file, read the file. We also didn't say if someone looks, if something looks like a file name, figure out how to read it. No, none of that.

We say, help me solve the thing in this file, and Claude realizes that it can read the file to answer that, and off it goes.

Detour: human in the loop

At this point, I got a little freaked out because I realized this program was giving access to read any file on my hard drive to this language model that I maybe shouldn't trust.

And so I'm gonna take a slight detour here from Thorsten's blog post and talk about human in the loop. I want to approve all of these tool calls because already they're doing something potentially dangerous that I wanna make sure seems sensible to me.

import tools from "./agent/tools/index.js"

async function main() {
  ⋮
  const agent = new Agent(
    client,
    getUserMessage,
    showAgentMessage,
    getToolConsent,
    tools,
  )

  await agent.run()
}

async function getToolConsent(message: string):
    Promise<boolean> {
  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
  })

  const consent = await rl.question(
    `\n\u001b[92mTool request\u001b[0m: ${message}\n`
    + "\u001b[93mClaude\u001b[0m: Continue? [yes]: ",
  )

  rl.close()

  return consent === "" ||
    consent.toLowerCase() === "yes"
}

So instead of the showToolMessage function, we are going to pass to our Agent a getToolConsent function, which is a little more strenuous.

Instead of just doing a console.log, it is going to ask the user, here's the tool request. Do you want to continue? Type yes or hit enter to continue. And if the user does anything other than hit enter or type yes, we will refuse to run the tool.

export class Agent {
  constructor(
    private client: AnthropicVertex,
    private getUserMessage: () => Promise<string>,
    private showAgentMessage:
      (message: string) => void,
    private getToolConsent:
      (message: string) => void,
    private tools: ToolDefinition[],
  ) {}

  private async executeTool(
    id: string,
    name: string,
    input: unknown,
  ): Promise<Anthropic.ContentBlockParam> {
    const tool = this.tools.find(
      (t) => t.name === name)
    if (!tool) {
      return {
        tool_use_id: id,
        type: "tool_result",
        content: `tool not found`,
        is_error: true,
      }
    }

    const msg = `${name}(${JSON.stringify(input)})`

    if (!(await this.getToolConsent(msg)))
      return {
        tool_use_id: id,
        type: "tool_result",
        content:
          `User did not consent to tool execution`,
        is_error: true,
      }

    try {
      return {
        tool_use_id: id,
        type: "tool_result",
        content: await tool.func(input),
      }
    } catch (error) {
      return {
        tool_use_id: id,
        type: "tool_result",
        content: error instanceof Error
          ? error.message : String(error),
        is_error: true,
      }
    }
  }

That's what this looks like here in our, uh, execute tool method.

If the user doesn't give tool consent, we return a tool result that's an error saying the user did not consent to tool execution. Alright, so let us see how this works.

❯ git checkout demo4

❯ pnpm agent

vertexai-playground@1.0.0 agent /Users/kyank/Developer/how-to-build-an-agent-in-javascript \
pnpm build && node dist/agent.js

vertexai-playground@1.0.0 build /Users/kyank/Developer/how-to-build-an-agent-in-javascript \
tsc

Chat with Claude (use 'ctrl-c' to quit) \
You: Claude, help me solve the riddle in secret-file.txt

Claude: I'll help you solve the riddle in secret-file.txt. First, let me read the file to see what the riddle contains.

Tool request: read_file({"path":"secret-file.txt"}) \
Claude: Do you want to continue? [yes]: no

Claude: I apologize, but I need your permission to use the file reading tool to access the content of secret-file.txt. Once you give your consent, I'll be able to read the file and help you solve the riddle it contains.

Would you like me to proceed with reading the secret-file.txt? Please confirm, and then I can help you solve the riddle inside.

You:

Uh, Claude, help me solve the riddle in the secret-file.txt file. Now, this time, instead of just going ahead and reading it, taking liberties, it actually asks if I want to continue and I can say no. And my refusal goes back as a part of the conversation and the model actually deals with this pretty well.

It says, I'm unable to access the file because I need your consent. Would you like me to read this file for you? If so, please confirm that I have your permission and I'll help you solve the riddle inside. So, this is working great. Okay. I'm feeling more comfortable again. We can go back to the blog post.

The `list_files` tool

The next thing Thorston invites us to do is to create a list files tool.

If you're anything like me, he says, the first thing you do when you log into a new computer is to get your bearings by running ls, list files. Let's let our agent do that.

import { readFileTool } from "./readFile.js";
import { listFilesTool } from "./listFiles.js";
export default [readFileTool, listFilesTool];

We add a second file to our list of files here, and uh, we import that from a separate file and add it to our array.

import fs from "fs/promises";
import { existsSync } from "fs";
import nodePath from "path";
import { ToolDefinition } from "../types.js";

/**
 * Tool for listing files in a directory
 */
export const listFilesTool: ToolDefinition = {
  name: "list_files",

  description: `List files and directories at a given path. If no
     path is provided, lists files in the current
     directory.`,

  input_schema: {
    type: "object",
    properties: {
      path: {
        type: "string",
        description: `Optional relative path to list files from.
           Defaults to current directory if not
           provided.`,
      },
    },
    required: [],
  },

  func: async (args: any): Promise<string> => {
    const path: string = args.path ?? ".";
    const rPath = nodePath.resolve(path);

    // Check if path exists and is a directory
    if (!existsSync(resolvedPath)) {
      throw new Error(`Directory not found: ${path}`);
    }
    const stat = await fs.stat(resolvedPath);
    if (!stat.isDirectory()) {
      throw new Error(`${path} is not a directory`);
    }
    try {
      const dir = await fs.readdir(resolvedPath);
      const entriesWithDirectoryMarkers = await Promise.all(
        dir.map(async (entry) => {
          const fullPath = nodePath.join(rPath, entry);
          try {
            const stats = await fs.stat(fullPath);
            return stats.isDirectory() ? `${entry}/` : entry;
          } catch (error) {
            return entry;
          }
        }),
      );
      return JSON.stringify(entriesWithDirectoryMarkers);
    } catch (error) {
      throw new Error(
        `Error reading dir: ${
          error instanceof Error ? error.message : String(error)
        }`,
      );
    }
  },
};

And then this is what that tool looks like. It's pretty much like the last one. There's just a little more code because listing directories in Node.js is a little less convenient. But we have a name, a description, an input_schema that requires a path. Although the path is not required this time, it's optional. We say in the instructions that if you don't pass a path, we'll list the current directory, which is a nice convenience.

And then over in the function on the right hand side, we check if the path exists and is a directory, and if so, we iterate through all of the entries. The one little extra we do here is that if an entry is a directory, we will output it with a slash on the end so that we provide a little clue here to the model of which things in the directory are sub directories or not. And that seems to work really well.

So let's go ahead and demo this.

❯ git checkout demo5

❯ pnpm agent

vertexai-playground@1.0.0 agent /Users/kyank/Developer/how-to-build-an-agent-in-javascript \
pnpm build && node dist/agent.js

vertexai-playground@1.0.0 build /Users/kyank/Developer/how-to-build-an-agent-in-javascript \
tsc

Chat with Claude (use 'ctrl-c' to quit) \
You: What do you see in this directory?

Claude: I'll help you see what's in the current directory. Let me check the contents for you.

Tool request: list_files({}) \
Claude: Do you want to continue? [yes]:

Claude: The current directory contains a mix of files and directories:

Files:

.envrc

.gitignore

.prettierignore

.prettierrc.json

README.md

devbox.json

devbox.lock

package.json

pnpm-lock.yaml

secret-file.txt

tsconfig.json

Directories:

.git/

dist/

node_modules/

src/

This appears to be a TypeScript/JavaScript project with standard configuration files, dependency management through pnpm, and a source directory (src/) where the code likely resides. There's also a "secret-file.txt" which might contain sensitive information.

You:

What do you see in this directory? We'll ask it.

I'll check the what files and directories are present and it calls list files with no arguments, just as it should.

And there you go. It is reading my directories and it says, this appears to be a TypeScript JavaScript project using pnpm as a package manager with a devbox development environment setup. There's also a file named secret-file.txt, which might contain sensitive information.

There you go. It's done a pretty good job.

Um, how about, tell me about all the TypeScript files in this project.

You: Tell me about all the TypeScript files in here.

Claude: I'll find and examine all the TypeScript files in this project. Let me start by checking for TypeScript files in the main directory and then look in the src/ directory where they're most likely to be located.

Tool request: list_files({"path":"src"}) \
Claude: Do you want to continue? [yes]:

It is guessing there might be TypeScript files in the src directory, which is a pretty good guess.

Claude: I found the src directory with a TypeScript file called "agent.ts" and an "agent" subdirectory. Let me check what's in the agent subdirectory and then examine each TypeScript file.

Tool request: list_files({"path":"src/agent"}) \
Claude: Do you want to continue? [yes]:

Claude: I found more TypeScript files in the agent subdirectory. Let me also check if there are any TypeScript files in the tools directory:

Tool request: list_files({"path":"src/agent/tools"}) \
Claude: Do you want to continue? [yes]:

Claude: Now that I've found all the TypeScript files, let me examine each one to tell you about them:

Tool request: read_file({"path":"src/agent.ts"}) \
Claude: Do you want to continue? [yes]:

And there's a subdirectory called agent with my agent class in it, and there's a sub subdirectory called tools with all of my tool definitions in it. It's scanning all of those and now it's requesting to read each of the files that it's found in there.

Tool request: read_file({"path":"src/agent/agent.ts"}) \
Claude: Do you want to continue? [yes]:

Tool request: read_file({"path":"src/agent/types.ts"}) \
Claude: Do you want to continue? [yes]:

Tool request: read_file({"path":"src/agent/tools/index.ts"}) \
Claude: Do you want to continue? [yes]:

Tool request: read_file({"path":"src/agent/tools/readFile.ts"}) \
Claude: Do you want to continue? [yes]:

Tool request: read_file({"path":"src/agent/tools/listFiles.ts"}) \
Claude: Do you want to continue? [yes]:

And it's at this point that I start second guessing my caution of requiring an approval for every single tool call, but better safe than sorry.

Claude: Based on my examination of all the TypeScript files in this project, here's what I found:

Project Overview

This is a TypeScript project that implements a Claude AI agent with tool integration. The agent can interact with users through a command-line interface and execute tools like reading files and listing directories.

TypeScript Files:

src/agent.ts

Main entry point that sets up an Anthropic Vertex AI client

Creates an Agent instance with tools and UI handlers

Implements UI functions for getting user input, showing messages, and asking for tool execution consent

Uses Google Cloud's "cross-camp-ai-enablement" project in "us-east5" region

src/agent/agent.ts

Defines the Agent class that handles the conversation flow

Manages the conversation state and message history

Handles tool execution and user consent for tools

Processes different types of content from Claude (text and tool_use)

src/agent/types.ts

Contains TypeScript type definitions for the project

Defines the ToolDefinition interface used to create tools

src/agent/tools/index.ts

Exports an array of available tools (readFileTool and listFilesTool)

src/agent/tools/readFile.ts

Implements a tool for reading file contents

Validates file existence and handles errors

src/agent/tools/listFiles.ts

Implements a tool for listing files in a directory

Adds trailing slashes to directory names for clarity

The project demonstrates how to build a Claude agent with tool-calling capabilities. It uses the Anthropic Vertex AI client to connect to Google Cloud's Claude API, and implements a command-line interface for interacting with the agent. The agent can execute tools that allow it to read files and list directories, with user consent required before any tool execution.

You:

And finally, there we go. A great big project overview. This is a TypeScript project that implements a Claude AI agent with tool calling capabilities. It creates an interactive command line interface where users can chat with Claude and allow it to execute specific tools. And it's got a breakdown of what happens in each of the files.

Really good. Pretty neat.

Um, let's try one more thing. What TypeScript version are we using in this project?

You: What TypeScript version are we using in this project?

Claude: To determine the TypeScript version being used in this project, I should check the package.json file, which typically contains information about dependencies including TypeScript. Let me examine that file.

Tool request: read_file({"path":"package.json"}) \
Claude: Do you want to continue? [yes]:

Claude: Based on the package.json file, this project is using TypeScript version 5.7.3, as indicated in the devDependencies section:
"devDependencies": {
  "@types/node": "^24.0.4",
  "prettier": "^3.4.2",
  "typescript": "^5.7.3"
}
The caret (^) before the version number means that the project will use at least version 5.7.3, but can automatically update to newer minor and patch versions within the 5.7.x range. However, the specific version being used is 5.7.3, which is a very recent version of TypeScript (as of the time this project was created).

What would you do if you were asked that question? Well, you would probably go and look in the package.json file, which is exactly what it does.

It's identified TypeScript 5.7.3. Nice work.

Okay, so there we go. Using the two tools together.

Let it `edit_file`

Now let's let it edit files. The last tool we're going to add is edit_file, a tool that lets Claude edit files. Holy shit, you're thinking now, this is where the rubber hits the road. This is where he pulls the rabbit outta the hat. Well, let's see, shall we?

import { readFileTool } from "./readFile.js";
import { listFilesTool } from "./listFiles.js";
import { editFileTool } from "./editFile.js";
export default [readFileTool, listFilesTool, editFileTool];

We create a new editFileTool.

/**
 * Tool for editing file contents
 */
export const editFileTool: ToolDefinition = {
  name: "edit_file",

  description: `Make edits to a text file. Replaces
    'old_str' with 'new_str' in the given file.
    'old_str' and 'new_str' MUST be different from
    each other. If the file specified with path
    doesn't exist, it will be created.`,

  input_schema: {
    type: "object",
    properties: {
      path: {
        type: "string",
        description: "The relative path of a file in
          the working directory.",
      },
      old_str: {
        type: "string",
        description: "The string to replace in the
          file.",
      },
      new_str: {
        type: "string",
        description: "The string to replace with.",
      },
    },
    required: ["path", "old_str", "new_str"],
  },

  func: async (args: any): Promise<string> => {
    const path: string = args.path
    const oldStr: string = args.old_str
    const newStr: string = args.new_str
    const resolvedPath = nodePath.resolve(path)

    // Validate that old_str and new_str are different
    if (oldStr === newStr) {
      throw new Error(`'old_str' and 'new_str' must be
        different from each other`)
    }

    try {

      // EDIT THE FILE

    } catch (error) {
      throw new Error(error instanceof Error
        ? error.message
        : String(error)
      )
    }
  }
}

And here's the structure of this file. We'll say that it's a tool that lets you make edits to a text file. It replaces old string with new string in the given file. Old string and new string must be different from each other. If the file specified with the path doesn't exist, it will be created.

And then in func we check that old string and new string are different. And if they are, then we will attempt to edit the file. I've put the code for that on a separate slide 'cause it's a little too long to fit.

let fileContent: string;

// Check if file exists
if (existsSync(resolvedPath) && oldStr !== "") {
  // Read existing file content
  fileContent = await fs.readFile(resolvedPath, "utf-8");

  // Check if old_str exists in the file
  if (!fileContent.includes(oldStr)) {
    return `No changes made:
            String '${oldStr}' not found in the file.`;
  }

  // Replace all occurrences of old_str with new_str
  const splitParts = fileContent.split(oldStr);
  const newContent = splitParts.join(newStr);

  // Write the modified content back to the file
  await fs.writeFile(resolvedPath, newContent, "utf-8");

  // Count replacements:
  // splitParts.length - 1 gives the number of
  // delimiters (oldStr) found
  const occurrences = splitParts.length - 1;
  return `Successfully made ${occurrences}
          replacement${occurrences !== 1 ? "s" : ""}
          in ${path}`;
} else if (oldStr === "") {
  await fs.writeFile(resolvedPath, newStr, "utf-8");
  return `Created new file ${path} with the provided
          content`;
}

// Throw error for the case where the file doesn't exist and oldStr is not empty
throw new Error(`File ${path} does not exist.`);

So we will check if the file with the given path exists, and if so, we make sure that the old string is not empty. We then read the contents of the file, find every occurrence of old string, and replace it with new string, and return a string that summarizes what we've done by counting the number of replacements.

If the file didn't exist and old string is empty, then we create a new file with new string as the contents. And if none of those things happen, then we throw an error because we are trying to edit a file that doesn't exist.

That's it. That's our editing tool. Let's demo it.

❯ git checkout main

❯ pnpm agent

vertexai-playground@1.0.0 agent /Users/kyank/Developer/how-to-build-an-agent-in-javascript \
pnpm build && node dist/agent.js

vertexai-playground@1.0.0 build /Users/kyank/Developer/how-to-build-an-agent-in-javascript \
tsc

Chat with Claude (use 'ctrl-c' to quit) \
You: Hey Claude, create fizzbuzz.js that I can run with Node.js and that has fizzbuzz in it and executes it.

Claude: I'll create a fizzbuzz.js file for you that can be run with Node.js. The FizzBuzz program prints numbers from 1 to n, but for multiples of 3 it prints "Fizz", for multiples of 5 it prints "Buzz", and for multiples of both 3 and 5 it prints "FizzBuzz".

Let me create this file for you:

Tool request: edit*file({"path":"fizzbuzz.js","old_str":"","new_str":"/**\n * FizzBuzz implementation\n _ Prints numbers from 1 to 100\n _ For multiples of 3, prints \"Fizz\" instead of the number\n _ For multiples of 5, prints \"Buzz\" instead of the number\n _ For multiples of both 3 and 5, prints \"FizzBuzz\"\n _/\n\nfunction fizzBuzz(n) {\n for (let i = 1; i <= n; i++) {\n if (i % 3 === 0 && i % 5 === 0) {\n console.log('FizzBuzz');\n } else if (i % 3 === 0) {\n console.log('Fizz');\n } else if (i % 5 === 0) {\n console.log('Buzz');\n } else {\n console.log(i);\n }\n }\n}\n\n// Execute FizzBuzz for numbers 1 to 100\nconsole.log('Running FizzBuzz from 1 to 100:');\nfizzBuzz(100);"}) \
**Claude:** Do you want to continue? [yes]:

Claude: I've created a file named fizzbuzz.js with a FizzBuzz implementation. The code:

Defines a fizzBuzz function that takes a number n as input

Iterates from 1 to n

For each number:

If divisible by both 3 and 5, prints "FizzBuzz"

If divisible by 3, prints "Fizz"

If divisible by 5, prints "Buzz"

Otherwise, prints the number itself

Executes the function for numbers 1 to 100

You can run this file with Node.js by using the following command in your terminal:
node fizzbuzz.js
This will display the FizzBuzz sequence from 1 to 100 in your console.

You:

Hey, Claude, create fizzbuzz.js that I can run with Node.js and that has fizzbuzz in it and executes it.

This is a pretty typical, um, interview question for programmers. There is the implementation of Fizzbuzz in JavaScript that it wants to write into a fizzbuzz.js file. Looks good to me.

Now if you don't know if Fizbuzz, uh, it has described it up there, what it does. Multiples of three will be output as fizz, multiples of five as buzz, multiples of both as fiz buzz. Otherwise, it'll just output the numbers. Yes, we will let it read the file to confirm that it was created correctly. And it reckons it's all done.

It even tells me how to run it. So let's accept the invitation.

❯ node fizzbuzz.js \
Running FizzBuzz from 1 to 100: \
1 \
2 \
Fizz \
4 \
Buzz \
Fizz \
7 \
8 \
Fizz \
Buzz \
11 \
Fizz \
13 \
14 \
FizzBuzz \
16 \
17 \
Fizz \
19 \
Buzz \
Fizz \
22 \
23 \
Fizz \
Buzz \
26 \
Fizz \
28 \
29 \
FizzBuzz \
31 \
32 \
Fizz \
34 \
Buzz \
Fizz \
37 \
38 \
Fizz \
Buzz \
41 \
Fizz \
43 \
44 \
FizzBuzz \
46 \
47 \
Fizz \
49 \
Buzz \
Fizz \
52 \
53 \
Fizz \
Buzz \
56 \
Fizz \
58 \
59 \
FizzBuzz \
61 \
62 \
Fizz \
64 \
Buzz \
Fizz \
67 \
68 \
Fizz \
Buzz \
71 \
Fizz \
73 \
74 \
FizzBuzz \
76 \
77 \
Fizz \
79 \
Buzz \
Fizz \
82 \
83 \
Fizz \
Buzz \
86 \
Fizz \
88 \
89 \
FizzBuzz \
91 \
92 \
Fizz \
94 \
Buzz \
Fizz \
97 \
98 \
Fizz \
Buzz

There we go. A working fizz buzz.

Uh, there's more to try though. Let's actually edit this file. Um, that fizzbuzz to 100 is a little long.

❯ pnpm agent

vertexai-playground@1.0.0 agent /Users/kyank/Developer/how-to-build-an-agent-in-javascript \
pnpm build && node dist/agent.js

vertexai-playground@1.0.0 build /Users/kyank/Developer/how-to-build-an-agent-in-javascript \
tsc

Chat with Claude (use 'ctrl-c' to quit) \
You: Please edit fizzbuzz.js so that it only prints until 15

Claude: I'll help you edit the fizzbuzz.js file to only print until 15 instead of its current limit. First, let me check the current content of the file to understand what needs to be changed.

Tool request: read_file({"path":"fizzbuzz.js"}) \
Claude: Do you want to continue? [yes]:

Claude: Now I'll edit the file to change the limit from 100 to 15. I need to modify the comment at the top and the function call at the bottom:

Tool request: edit*file({"path":"fizzbuzz.js","old_str":"/**\n * FizzBuzz implementation\n _ Prints numbers from 1 to 100\n _ For multiples of 3, prints \"Fizz\" instead of the number\n _ For multiples of 5, prints \"Buzz\" instead of the number\n _ For multiples of both 3 and 5, prints \"FizzBuzz\"\n _/","new_str":"/**\n _ FizzBuzz implementation\n _ Prints numbers from 1 to 15\n _ For multiples of 3, prints \"Fizz\" instead of the number\n _ For multiples of 5, prints \"Buzz\" instead of the number\n _ For multiples of both 3 and 5, prints \"FizzBuzz\"\n _/"}) \
Claude: Do you want to continue? [yes]:

Tool request: edit_file({"path":"fizzbuzz.js","old_str":"// Execute FizzBuzz for numbers 1 to 100\nconsole.log('Running FizzBuzz from 1 to 100:');\nfizzBuzz(100);","new_str":"// Execute FizzBuzz for numbers 1 to 15\nconsole.log('Running FizzBuzz from 1 to 15:');\nfizzBuzz(15);"}) \
Claude: Do you want to continue? [yes]:

Claude: I've successfully modified the fizzbuzz.js file to only print up to 15 instead of 100. The changes made were:

Updated the comment at the top to state that it "Prints numbers from 1 to 15" instead of 1 to 100

Changed the execution line from fizzBuzz(100) to fizzBuzz(15)

Updated the console.log message to say "Running FizzBuzz from 1 to 15:" instead of "...to 100:"

The FizzBuzz function itself didn't need to be changed as it was already parameterized to accept a limit (n) and will now stop at 15 as requested.

You:

Uh, please edit fizzbuzz.js so that it only prints until 15. That should fit on the screen. It is gonna list the files in the directory to make sure that file is there.

It's gonna read it, it's gonna edit it. There we go. It's use all three of our tools. It's gonna edit it, edit it again to make another change, and it thinks it's done. Let's see if it's right.

❯ node fizzbuzz.js \
Running FizzBuzz from 1 to 15: \
1 \
2 \
Fizz \
4 \
Buzz \
Fizz \
7 \
8 \
Fizz \
Buzz \
11 \
Fizz \
13 \
14 \
FizzBuzz

There we go, a working fizzbuzz from one to 15.

Let's do one more. In this one, from Thorson, we're gonna ask it to create a congrats.js script that rot13 decodes this string and prints it. If you don't know rot13 it's a very weak encryption algorithm that just shifts every letter in the alphabet by 13 uh spaces in order to make an indecipherable string.

❯ pnpm agent

vertexai-playground@1.0.0 agent /Users/kyank/Developer/how-to-build-an-agent-in-javascript \
pnpm build && node dist/agent.js

vertexai-playground@1.0.0 build /Users/kyank/Developer/how-to-build-an-agent-in-javascript \
tsc

Chat with Claude (use 'ctrl-c' to quit) \
You: Create a congrats.js script that rot13-decodes the following string 'Pbatenghyngvbaf ba ohvyqvat n pbqr-rqvgvat ntrag!' and prints it

Claude: I'll create a JavaScript script that decodes a rot13-encoded string and prints it.

Let me first create the congrats.js file with the code to decode and print the string 'Pbatenghyngvbaf ba ohvyqvat n pbqr-rqvgvat ntrag!'.

Tool request: edit*file({"path":"congrats.js","old_str":"","new_str":"/**\n * A script that decodes a rot13-encoded string and prints it\n _/\n\n// The encoded string to decode\nconst encodedString = 'Pbatenghyngvbaf ba ohvyqvat n pbqr-rqvgvat ntrag!';\n\n/**\n _ Function to decode a rot13-encoded string\n _ @param {string} str - The rot13-encoded string\n _ @return {string} The decoded string\n _/\nfunction rot13Decode(str) {\n return str.replace(/[a-zA-Z]/g, function(char) {\n // Get the character code\n const charCode = char.charCodeAt(0);\n \n // Handle uppercase letters (A-Z: 65-90)\n if (charCode >= 65 && charCode <= 90) {\n return String.fromCharCode(((charCode - 65 + 13) % 26) + 65);\n }\n \n // Handle lowercase letters (a-z: 97-122)\n if (charCode >= 97 && charCode <= 122) {\n return String.fromCharCode(((charCode - 97 + 13) % 26) + 97);\n }\n \n // Return non-alphabetic characters unchanged\n return char;\n });\n}\n\n// Decode and print the string\nconst decodedString = rot13Decode(encodedString);\nconsole.log(decodedString);"}) \
Claude: Do you want to continue? [yes]:

Claude: Now let me verify the content of the file:

Tool request: read_file({"path":"congrats.js"}) \
Claude: Do you want to continue? [yes]:

Claude: I've created the congrats.js script that:

Defines the rot13-encoded string 'Pbatenghyngvbaf ba ohvyqvat n pbqr-rqvgvat ntrag!'

Implements a rot13Decode function that:

Processes each alphabetic character in the string

Shifts each letter by 13 positions in the alphabet

Preserves case (uppercase/lowercase)

Leaves non-alphabetic characters unchanged

Decodes the string and prints the result to the console

When you run this script with Node.js (using the command node congrats.js), it will decode and display the hidden message.

Note: The rot13 cipher is a simple letter substitution that replaces each letter with the letter 13 positions after it in the alphabet, wrapping around if necessary.

You:

That's exactly what it's going to do in the JavaScript code.

So let's exit and node congrats.js.

❯ pnpm agent
Congratulations on building a code-editing agent!

Congratulations on building a code editing agent. So there we go.

Isn't this amazing?

At the end of this article, it says, isn't this amazing? If you're anything like all the engineers I've talked to in the past few months, chances are that while reading this, you have been waiting for the rabbit to be pulled out of the hat, for me to say, well, in reality, it's much, much harder than this, but it's not.

This is essentially all there is to the inner loop of a code editing agent. Sure, integrating it into your editor, tweaking the system prompt, giving it the right feedback at the right time, a nice UI around it. Better tooling around the tools, support for multiple agents and so on. We've built all of that in Amp, but it didn't require moments of genius.

All that was required was practical engineering and elbow grease. These models are incredibly powerful now. 300 lines of code – it's more like 400 in Node.js, for the record – and three tools and now you're able to talk to an alien intelligence that edits your code. If you think, well, but we didn't really, go ahead and try it.

Go and see how far you can get with this. I bet it's a lot farther than you think. That's why we think everything's changing.

If you wanna take this project for a spin, you can find the link to the GitHub project with the source code in the description of this video or in the blog post where you're viewing it.

And if you want to read the original article, I invite you to go and visit the Amp Code blog.

So there you go. The blog post of the year for 2025. I can't say I disagree, and I'm happy it exists in TypeScript now. Hope you enjoyed it. Thanks for watching.

Use Tailwind CSS prefixes for shared design system components

Kevin Yank — Mon, 22 Jan 2024 04:06:47 +0000

Photo by Khamkéo Vilaysing on Unsplash

Surprisingly little has been written about how to use Tailwind with design systems or shared components, when both those components and the app consuming them are styled with Tailwind. Tailwind's prefix option is specifically designed to allow for this, but it's a somewhat ugly solution that we did our best to avoid at Culture Amp until recently. Here's everything we learned, and why we're ultimately embracing prefix.

A very brief intro to Tailwind

Tailwind CSS (Tailwind for short) is a not-uncontroversial choice of tool for projects where hand-crafting CSS selectors that apply to semantically meaningful patterns of HTML elements is not beneficial. We have decided to use it at Culture Amp, the reasons for which deserve an article of their own. At the risk of oversimplifying: if the structure of your UI matches the structure of your codebase (i.e. visual blocks tend to correspond to software components rather than sections of a document), you might save time and effort by applying styles to your elements directly in those components, rather than by writing CSS selectors that are tightly coupled to those components' implementation. Again, there's a lot more to say here, and I'll try to write it up soon. Let me know if you're keen to read it.

Fundamentally, Tailwind scans your application's source code for class names like this:

<div class="m-0"></div>

…and generates a stylesheet that contains only the necessary styles to match the classes you've used:

.m-0 {
  margin: 0px;
}

While at first glance this looks like it would have all the downsides of inline styles (the style attribute), Tailwind has designed a remarkably robust language of class names that can cover just about any selector, property, or value you need. Inline styles can't do pseudo-class selectors or media queries, but Tailwind can:

<div class="dark:hover:bg-sky-500/25"></div>

@media (prefers-color-scheme: dark) {
  .dark\:hover\:bg-sky-500\/25:hover {
    background-color: rgb(14 165 233 / 0.25);
  }
}

In a project that's a good fit for Tailwind (see above), this virtually eliminates the need to write CSS code that would mostly contain selectors that match a single element – an unnecessary abstraction.

Styling shared components

For the purposes of this article, shared components are user interface elements that are used in more than one web application. In Culture Amp's case this includes the React components in our Kaizen design system.

When you want to use Tailwind to style both an application's non-shared components, and the shared components that application uses, you have a decision to make: Will you publish your shared components with compiled CSS, or do you expect the application's build to run the Tailwind compiler over the shared components' source code to generate those styles as well?

For many years, Culture Amp took the second option, and distributed shared components without compiled CSS. This meant that every app that consumed shared components needed to include the necessary CSS build tooling – at that time CSS Modules and node-sass – with a compatible version and configuration. This was relatively easy to set up, but over time proved difficult to maintain. When node-sass was deprecated in favour of (the much faster but slightly incompatible) Dart Sass, this demanded a difficult lock-step migration across all those codebases, which we have yet to achieve. And as new applications have switched to Tailwind for their own styles, they've had to continue to maintain those old build tools in parallel for the shared components' styles.

To avoid this coupling between the source code of shared components and the build tooling of the applications that consume them, we now want to go the other way: have our shared components build their styles in their own build pipelines and publish components with plain CSS. That way, the CSS build tooling of our applications can stay decoupled from the CSS build tooling of our component libraries: a Sass-styled application can consume a Tailwind-styled component without having to run Tailwind, and a Tailwind-styled application can consume a Sass-styled component without having to run Sass.

But what happens when a Tailwind-styled application consumes Tailwind-styled components? How do the Tailwind-generated styles of shared components co-exist with the Tailwind-generated styles of the application?

The naive approach

At first, it would seem that it's safe to combine two Tailwind-built stylesheets into one, if slightly inefficient. Let's say your component uses m-0:

<div class="m-0">This is a shared component</div>

.m-0 {
  margin: 0px;
}

And then your application also uses m-0:

<div class="m-0">This is my application.</div>

.m-0 {
  margin: 0px;
}

When you use the shared component in your application, you get something like this:

<div class="m-0">This is my application.</div>
<div class="m-0">This is a shared component</div>

/* shared component styles */
.m-0 {
  margin: 0px;
}
/* application styles */
.m-0 {
  margin: 0px;
}

.m-0 is defined twice in your stylesheet, which is the slightly wasteful part, but the two rules apply the exact same styles, so everything still works.

While the duplicate CSS output is unfortunate, Tailwind-generated stylesheets tend to be incredibly small compared to hand-coded CSS, so this bloat is likely negligible. Almost every element in the document that needs its margin set to zero has that done with this one (duplicated) CSS rule, rather than traditional CSS where many, many different rules might specify margin: 0px separately. If you really wanted to avoid this duplicate output, a PostCSS plug-in like postcss-discard-duplicates could do this for you.

The small problem: Configuration coupling

A much bigger downside than the output duplication, however, is the coupling this creates between your Tailwind configurations. If someday you upgrade or alter the configuration of Tailwind in either project (your shared components or your application), and the two outputs do not match, one set of styles will overwrite the other.

/* shared component styles */
.bg-sky-500 {
  background-color: #0ea5e9; /* new value */
}
/* application styles */
.bg-sky-500 {
  background-color: #87cefa; /* old value */
}

In this example, because our combined CSS output includes the shared components' CSS first and the application's CSS second, the application styles "win" (because the CSS cascade applies rules of equal specificity in source code order).

Adding to the confusion is the fact that Tailwind, remember, only generates styles for class names that you use, so if your application uses some of the classes that your shared components use but not others, you can end up with an unholy mix of the two configurations applied to your application:

/* shared component styles */
.bg-red-500 {
  background-color: #ef4444; /* new value */
}
.bg-sky-500 {
  background-color: #0ea5e9; /* new value */
}
/* application styles */
.bg-sky-500 {
  background-color: #87cefa; /* old value */
}

In the above example, your shared components will display with the old value for bg-sky-500, but the new value for bg-red-500, because that second background colour isn't used in the application's source code!

You can of course flip the order in which your two stylesheets are combined, putting the application's styles first:

/* application styles */
.bg-sky-500 {
  background-color: #87cefa; /* old value */
}
/* shared component styles */
.bg-red-500 {
  background-color: #ef4444; /* new value */
}
.bg-sky-500 {
  background-color: #0ea5e9; /* new value */
}

…but this merely reverses the problem: now your application is being unexpectedly re-styled by the Tailwind configuration used to build your shared components' styles, except for any classes that are used only in your application, which will remain styled by the old configuration.

In short, if you want your styles to be applied consistently, you need to avoid breaking changes to your Tailwind configuration, or update the two packages in lock-step. This by itself may not be a dealbreaker if you expect your Tailwind configuration to be relatively stable. Tailwind itself is pretty careful about releasing breaking changes, so it's unlikely that having slightly different Tailwind versions in the shared components and the application will cause problems most of the time.

But it's hard to ignore the fact that we've ended up back in a situation where our applications are forced to match their build configuration to that assumed by our shared components.

The big problem: Tailwind depends on source order

There's actually a more subtle (and fatal) issue lurking here: Tailwind is designed with the assumption that it controls the source order of the rules it generates.

Let's consider again our zero-margin div:

<div class="m-0"></div>

.m-0 {
  margin: 0px;
}

margin is a shorthand property, which means it has the effect of setting margin-block-start (top), margin-inline-end (right), margin-block-end (bottom), and margin-inline-start (left).

In traditional CSS, you can follow a shorthand property like this with any specific properties you want to override, like adding a left margin:

.bottom-margin-only {
  margin: 0px;
  margin-inline-start: 1rem;
}

The order of the property declarations in the above is significant: if you swapped them so that margin-block-end was set first, the margin declaration would override it.

In Tailwind, you can likewise override a shorthand class like m-0 with a specific class like ms-4:

<div class="m-0 ms-4"></div>

.m-0 {
  margin: 0px;
}
.ms-4 {
  margin-inline-start: 1rem;
}

But the critical thing to observe here is that the order of the class names in the HTML is not significant: only the order of the generated CSS rules is.

If we swapped the order of the class names in the HTML:

<div class="m-0 ms-4"></div>

…the left margin would still override the m-0, because Tailwind still generates the two CSS rules in the order that ensures the more fine-grained style (the left margin) is applied after the more coarse-grained style (the margin on all four sides):

.m-0 {
  margin: 0px;
}
.ms-4 {
  margin-inline-start: 1rem;
}

Now, take this observation that the source order of rules generated by Tailwind is a critical feature of its design, and combine that with the issue we identified above of shared component styles clobbering application styles (or vice versa):

<div class="m-0">This is my application.</div>
<div class="m-0 ms-4">This is a shared component</div>

/* shared component styles */
.m-0 {
  margin: 0px;
}
.ms-4 {
  margin-inline-start: 1rem;
}
/* application styles */
.m-0 {
  margin: 0px; /* ❌ overides .ms-4 */
}

In this example, our shared components use m-0 and ms-4, but our application only uses m-0. The application's m-0 rule will override the value of margin-inline-start set by the ms-4 rule, and break the shared component's left margin!

Once again, you can solve this specific instance by swapping the order of the two generated stylesheets, but you'll just end up with the opposite problem: shared component styles interfering with application styles, in this example when the margin is on an application element.

<div class="m-0 ms-4">This is my application.</div>
<div class="m-0">This is a shared component</div>

/* application styles */
.m-0 {
  margin: 0px;
}
.ms-4 {
  margin-inline-start: 1rem;
}
/* shared component styles */
.m-0 {
  margin: 0px; /* ❌ overides .ms-4 */
}

If you're at all tempted to try doing without shorthand styles (e.g. avoid m-0 in favour of mt-0 me-0 mb-0 ms-0), Tailwind also depends on source order for modifiers like media queries:

<div class="m-0 md:m-4">This is my application</div>
<div class="m-0">This is a shared component</div>

/* application styles */
.m-0 {
  margin: 0px;
}
@media (min-width: 768px) {
  .md\:m-4 {
    margin: 1rem;
  }
}
/* shared component styles */
.m-0 {
  margin: 0px; /* ❌ overides .md:m-4 */
}

Here we're saying the first div should have a margin of zero by default, but on medium-sized screens or larger it should have a 1rem margin. These two rules have equal specificity (one class selector), so the fact that the media query style overrides the default style depends on source order. A second .m-0 rule at the end of the CSS from the shared component clobbers this margin.

Modifiers (dark:, hover:, etc.) are a core feature of Tailwind's styling language; there's no avoiding them, and as we've seen, they are broken by combining multiple Tailwind builds in a single CSS stylesheet.

How do we fix this?

Seductive non-solutions

There are a few approaches to solving this that seem like they could work nicely until you think them through. We'll look at each briefly to explain why they don't work.

`!important`

Out of the box, Tailwind lets you generate styles with !important that override competing styles in the cascade. class="!ms-4", for example, will output this:

.\!ms-4 {
  margin-inline-start: 1rem !important;
}

First of all, !important is a very sharp knife, and is best avoided. For example, it interferes with inline styles applied to elements by JavaScript. But even if we ignored everything that's bad about !important, it doesn't actually solve the problem!

<div class="m-0">This is my application.</div>
<div class="m-0 !ms-4">This is a shared component</div>

/* shared component styles */
.m-0 {
  margin: 0px;
}
.\!ms-4 {
  margin-inline-start: 1rem !important;
}
/* application styles */
.m-0 {
  margin: 0px;
}

Yes, this prevents the application's m-0 rule from overriding the component's ms-4 rule. But to do this we had to modify our shared component with knowledge of the application that would be consuming it, which is an unhealthy coupling to internal implementation details that would be far from practical to maintain in a real-world ecosystem of shared components and applications.

What if we made all our component styles important? Tailwind even offers a configuration option for this:

<div class="m-0">This is my application.</div>
<div class="m-0 ms-4">This is a shared component</div>

/* shared component styles */
.m-0 {
  margin: 0px !important;
}
.ms-4 {
  margin-inline-start: 1rem !important;
}
/* application styles */
.m-0 {
  margin: 0px;
}

Well, this is just equivalent to putting our shared component styles at the end of the stylesheet: as already described above, the shared component styles will end up clobbering application styles in different circumstances:

<div class="m-0 ms-4">This is my application.</div>
<div class="m-0">This is a shared component</div>

/* shared component styles */
.m-0 {
  margin: 0px !important; /* ❌ overrides .ms-4 */
}
/* application styles */
.m-0 {
  margin: 0px;
}
.ms-4 {
  margin-inline-start: 1rem;
}

Boost specificity with `important`

Tailwind's important configuration option also lets you specify a selector for a top-level container element (like body or #app) to boost the specificity of the selectors it generates beyond the usual one-class specificity.

<div class="m-0">This is my application.</div>
<div class="m-0 ms-4">This is a shared component</div>

/* shared component styles */
body :is(.m-0) {
  margin: 0px;
}
body :is(.ms-4) {
  margin-inline-start: 1rem;
}
/* application styles */
.m-0 {
  margin: 0px;
}

Here, setting important to 'body' again appears to fix the problem because the shared component styles now consistently override the application styles. But just like with !important above, this only has the same effect as putting the component styles at the end of the stylesheet: shared component styles will clobber application styles instead.

<div class="m-0 ms-4">This is my application.</div>
<div class="m-0">This is a shared component</div>

/* shared component styles */
body :is(.m-0) {
  margin: 0px; /* ❌ overrides .ms-4 */
}
/* application styles */
.m-0 {
  margin: 0px;
}
.ms-4 {
  margin-inline-start: 1rem;
}

CSS cascade layers

A relatively new but now widely-supported addition to browsers, the @layer CSS at-rule lets you create groups of CSS rules and control the order in which they are applied to the page. So you could specify that your shared component styles be applied after your application styles:

<div class="m-0">This is my application.</div>
<div class="m-0 ms-4">This is a shared component</div>

@layer application-styles, component-styles;

@layer component-styles {
  .m-0 {
    margin: 0px;
  }
  .ms-4 {
    margin-inline-start: 1rem;
  }
}

@layer application-styles {
  .m-0 {
    margin: 0px;
  }
}

But once again – you guessed it – this is effectively just like moving the component styles to the bottom of the stylesheet: it creates the opposite problem of component styles interfering with application styles.

Discard duplicates

Remember at the start of this article when we noted that our shared components and our application could generate the same CSS rule, and that this would bloat our CSS output unnecessarily? I mentioned postcss-discard-duplicates could get rid of those duplicate rules.

<div class="m-0">This is my application.</div>
<div class="m-0 ms-4">This is a shared component</div>

/* shared component styles */
.m-0 {
  margin: 0px;
}
.ms-4 {
  margin-inline-start: 1rem;
}
/* application styles */

This looks promising, because the problematic style has entirely disappeared. But there is still a source order issue here, because the style that survives is the style that appears first in the source order, and that isn't always right.

With a slightly tweaked example where the duplicate style is the fine-grained style (ms-4), we run into the same problem:

<div class="m-2 ms-4">This is my application.</div>
<div class="m-0 ms-4">This is a shared component</div>

/* shared component styles */
.m-0 {
  margin: 0px;
}
.ms-4 {
  margin-inline-start: 1rem;
}
/* application styles */
.m-2 {
  margin: 0.5rem; /* ❌ overrides .ms-4 */
}

An opportunity: intelligent Tailwind output merging

The fundamental problem we face is that two Tailwind builds that use the same global namespace for their class names will inevitably interfere with each other because Tailwind is unable to place the generated CSS rules in the source order required for them the override each other in the correct sequence.

But what if we could?

It's not as if the correct order for the rules is mysterious. It's implemented in the Tailwind compiler. Tools like prettier-plugin-tailwindcss, which automatically sorts the class names in your HTML code to match the order in which Tailwind generates them in your CSS output, use a public API in Tailwind to get this order.

So what if we wrote a PostCSS plug-in that would take the output of two Tailwind builds and merge them together, removing duplicate styles and sorting the remaining styles into the correct order?

This seems like it could work, might even be a relatively straightforward project, and could even be worth Tailwind considering as a core feature. I've started a discussion about this on the Tailwind CSS GitHub project.

Even if we implemented this, we would still need to accept that our two Tailwind builds would need to have compatible versions and configurations for their merged outputs to work reliably.

The actual solution: `prefix`

As I mentioned in the previous section, the fundamental problem we face here is that Tailwind generates styles in a global namespace, and that two Tailwind builds therefore conflict in that namespace.

What if we could give our Tailwind builds separate namespaces? Our shared components would receive styles only from their generated CSS output, and our application elements would receive styles only from the application's Tailwind build output.

This is what Tailwind's prefix option is for. It lets you specify a short string of characters that you add to the start of all your Tailwind class names, to distinguish them from styles they need to coexist with (which in this case is another Tailwind-generated stylesheet).

For example, we could configure our Kaizen component library with a Tailwind prefix of kz-, and get this:

<div class="m-0">This is my application.</div>
<div class="kz-m-0 kz-ms-4">This is a shared component</div>

/* shared component styles */
.kz-m-0 {
  margin: 0px;
}
.kz-ms-4 {
  margin-inline-start: 1rem;
}
/* application styles */
.m-0 {
  margin: 0px;
}

The two elements' styles are completely separate in the CSS, because they use two completely different namespaces! You could swap the order of the two stylesheets, and it would make no difference. (We put our application styles last, because our design system components allow you to pass in class names to override their built-in styles, so those application class names need to come last in the stylesheet.)

This is such a clean and complete solution to this problem that you're probably wondering why this isn't a much shorter article.

The thing is, for those who have become used to Tailwind, the extreme terseness of its class names is one of its best features. It vastly reduces the number of keystrokes required for most styling tasks. Strings like m-0 become burned into your muscle memory, something you can type almost without thinking.

So if you tell an engineer who loves Tailwind that they need to remember to add three extra characters (kz-) to the start of all their class names when they're working in a library, and that different libraries will have different prefixes, you're probably going to ruin their day. And someone will have to make the very unpopular decision of who gets to have the default (unprefixed) namespace: your application codebases or your design system's component library. Avoiding this pain is why we tried everything else we could first.

But this really is the cleanest solution to the problem of enabling different Tailwind builds/versions/configurations to coexist in a single web page, and at Culture Amp we've only just learned to accept that.

useEffect vs useLayoutEffect and server-side rendering

Kevin Yank — Mon, 25 Sep 2023 02:03:25 +0000

Today I learned the difference between useEffect and useLayoutEffect in React, and why the second one prints an ugly warning during server-side rendering.

useEffect(() => {
  /* non-paint-blocking effect */
}, [ /* dependencies */ ])

useLayoutEffect(() => {
  /* paint-blocking effect */
}, [ /* dependencies */ ])

useEffect and useLayoutEffect are basically the "async" and "sync" versions of the same hook; otherwise, they behave identically. useEffect runs in the background asynchronously while the render where its dependencies changed is allowed to render and paint for the user to see,
whereas useLayoutEffect blocks the render where the dependencies' values changed from being painted to the screen until after the body of useLayoutEffect runs (and presumably tweaks the DOM in some way).

Until today we were using useLayoutEffect to perform a redirect in a new app:

import { routes } from "routes"
import { useCurrentUser } from "src/context"
import { useLayoutEffect } from "react"
import { useRouter } from "next/router"

export default function Redirect() {
  const user = useCurrentUser()
  const router = useRouter()

  useLayoutEffect(() => {
    if (!user) {
      return
    }
    router.replace(routes.index({ accountId: user?.account_id.toString() }))
  }, [user, router])
}

Since we're going to redirect the browser anyway, it makes sense to save it the trouble of painting the initial render to the screen, right? Not when there is server-side rendering in the mix! When a useLayoutEffect is encountered by React running on the server, it displays an ugly warning:

Warning: useLayoutEffect does nothing on the server, because its effect cannot be encoded into the server renderer's output format.

In fact, neither useEffect nor useLayoutEffect can have any effect on the server-rendered output that gets sent to the browser (since there is no actual DOM for these effects to tweak), but this warning is emitted only for useLayoutEffect because it is usually used to do something to the DOM before the user gets to see the rendered component. Server-rendering will cause that "untweaked" version of the rendered output to be sent to the browser and shown to the user before the client-side app fires up and runs the useLayoutEffect to tweak it. So React is warning us that the user may see an ugly/broken version of the UI that we don't want them to see.

What's `useLayoutEffect` good for?

When I shared this internally at Culture Amp, several people remarked that they couldn't think of any real use cases for useLayoutEffect. They are indeed rare – more so every year as CSS grows more and more capable – but here's a semi-contrived example:

Let's say you wanted to let the browser lay out the "natural" height of a div based on its content, and then use JavaScript to animate it from zero to that "natural" height, so it appeared to grow vertically from its top edge, revealing its content as it went.

You wouldn't want the user to see a "flash" of the full-height div before you set its height back to zero for the start of the animation. useEffect would display that flash, whereas useLayoutEffect would let you inspect the height of the rendered div and then adjust it before the user got to see it.

In this case, the warning from React would be telling us that
the user would see the flash, because the full-height div is getting rendered on the server, and the height tweak won't be applied by useLayoutEffect until the JavaScript starts up on the client – long after the user got to see the server-rendered version of the page.

The example given in the official docs is also good: it involves calculating the position of a tooltip based on the rendered dimensions of the element to which it is attached.

MelbJS March 2023 notes

Kevin Yank — Wed, 08 Mar 2023 10:47:58 +0000

Raw notes from the MelbJS meetup held at Culture Amp in Richmond on 8 March, 2023.

Fundamentals of Module Federation, Mathew Byrne

Microfrontends are an architectural pattern to split up large codebases into small apps that are stitched together into a single page at runtime.

Problems of a single build (monolith):

Scaling build times
Dependency versioning: Team A wants to upgrade React, Team B isn't ready
Deployments: slow builds means deploys back up
In general, bottlenecks!

Multiple apps: a new bundle per "page". New problems:

Compromised user experience
Hard to maintain client state across apps
Scaling challenges still exist within each app
Duplicate dependencies

Webpack externals: shared dependencies are loaded separately. New problems:

No on-demand loading of code. All dependencies must be available first.
Manual juggling of those dependencies.
Inflexible

Native ES Modules: trust the browser to load your dependencies for you. New problems:

Performance: round-tripping of cascading requests for dependencies.
Limited client support.
Can't use non-ESM dependencies.

Module federation: a run-time method of sharing modules between independent builds.

Terminology:

Host: The first webpack runtime to boot on the client
Remote: A bundle that the host can dynamically load in when requested.
These are not mutually exclusive.

Redundancy, self-healing and versioning come built-in. Already-loaded modules get used. Missing modules get auto-loaded.

Doesn't interfere with a familiar developer experience.

Works in the browser and in Node.

Remote loads are "hoisted": an entire tree of missing dependencies will be loaded in parallel.

Demo: Two independent webpack apps in a monorepo. Both dev servers running. App1 loads App2 as a remote! App2 is lazy-loaded, but it doesn't have to be. App1's webpack config has a ModuleFederationPlugin that declares a remote for App2. App2's webpack config has a ModuleFederationPlugin that declares that App2 is remote that can be loaded by a host. When App1 loads App2, App2 gets its react, etc. from App1.

A bundle can be both a host and a remote, which enables some interesting configurations. The module federation project repo has dozens of examples. E.g. Bidirectional, two modules that can each act as a host, but load the other on demand. App Shell, a single host designed to load multiple remotes.

MF first shipped with Webpack 5 in Oct 2020. Next 13, SSR support are now there. Delegate modules, a new feature like middleware for loading remotes (e.g. dynamic host selection, etc.), just landed.

Standard Promises. Promise Standards, Franky

If JavaScript is a single-threaded language, then how does async code run?

Promises are a combination of two specifications: ECMAScript and HTML.

The browser APIs are async operations processed by the browser engine, which allows the JavaScript engine to keep processing.

The browser maintains an event loop, background micro-task queues, etc. to make this all work.

A tour of the relevant specs, using a simple promise example:

const resolution = 'MelbJS!';
new Promise(function executor(resolve, reject)
{
  const resolveIt = true;
  if (resolveIt) {
    resolve(resolution);
  } else {
    reject('Ew. JavaScript!');
  }
})
.then(function onFulfilled(result) {
  console.log(result);
});

How it works (according to the spec):

Check that the Promise constructor was passed a function as an executor.
Create an internal promise object, using the Promise prototype, which includes all the promise features we're used to (then, etc.). Creates some internal "slots" for information about the promise.
Create the resolve and reject functions, which are passed into the executor later.
Call the executor function. If it completes successfully, it's a normal completion. If it throws and exception, it's an abrupt completion.
Return the promise!

How the resolving functions (resolve/reject) work internally: Depending which is called, the promise will be fulfilled or rejected. If resolve is called with another promise, that promise is used in turn to continue resolving. Otherwise, the promise is resolved straight away.

How a promise is fulfilled:

[[PromiseState]]: fulfilled
[[PromiseValue]]: 'MelbJS!'
[[PromiseIsHandled]]: false
[[PromiseFulfillReactions]]: undefined
[[PromiseRejectReactions]]: undefined

Once a promise is fulfilled, it needs to be handled. That's where we move into the then method. The specification for this function is really, really long! For brevity, we'll ignore all the parts that have to do with rejecting. This is where the HTML spec starts to come in.

The then method creates another promise, which operates just like the one we've been talking about. It's a bit hidden, but it's what lets us chain promises.

then takes a callback, which gets passed to HostMakeJobCallback, and eventually is transformed into a fulfillReaction. Gets enqueued as a promise reaction job, which is sent to the browser engine – which takes it out of the JavaScript single-threaded execution environment! Its execution is controlled by the browser engine, not JavaScript itself.

The Event loop processing model:

Event loop
Task queue
Microtask queue
JavaScript runtime engine (heap and call stack)

There are entire talks on this stuff, so we're only going to cover it briefly.

The JavaScript engine adds code to be executed to its call stack, but the browser event loop can add code to it too. The event loop schedules tasks onto the task queue and microtask queue. Every time the event loop "spins", it checks if a task is still executing in the call stack. If not, it will place a new valid task on the call stack.

The microtask queue is a priority queue. Being in the task queue is like boarding a plane in Economy Class.

So, back in the world of the promises standard, HostEnqueuePromiseJob schedules tasks on the high-priority microtask queue (defined in the HTML spec).

Another example of how these two standards operate together: HostCallJobCallback.

Not covered for time (but equally interesting!): stuff like what happens if resolve is passed another promise. Opens up another can of worms. Also interesting, how browser APIs like fetch work under the surface.

Pyodide and JS: The One Language to Rule Them All, Hon Weng Chong

Pyodide: compile Python to WebAssembly.

Cortical Labs: we grow neurons (live brain cells) and program them to play video games like Pong!

The goal for us was to abstract away the low-level C that we were writing into a higher-level language like JavaScript or Python. This would enable us to develop APIs to work with the neurons without the need for knowing signal processing, spike detection/sorting, stimulation patterns, rewards, etc.

Python was the most popular language when we looked, so that's where we started!

We built a web-stack IDE (Monaco text editor engine).

Pyodide JS: Two-way communication between JavaScript and Python runtimes. Use Web Workers to prevent Python code from blocking JavaScript. Convenient type conversions for the primitive types supported by both languages.

Load the Pyodide JS bundle, then write a little bootstrap script and pass it Python source code to run. Just like that, Python running in the browser! No backend, no installation.

Take the value returned by Pyodide and call its toJS method to convert the return value of the Python program to JavaScript.

Can also use pyodide.registerJsModule to pass a JavaScript value into the Python runtime before running the Python program.

Demo: a game of Pong implemented in Python, rendering its current state to a Canvas with JS.

Pyodide is important because it will bring all of the machine learning and AI technologies (implemented in Python) into the Web, where we can give them a UI.

Web Directions Hover 2022 Day 2 notes

Kevin Yank — Tue, 10 May 2022 13:39:27 +0000

These are the live notes I took from Day 2 of the Web Directions Hover 2022 conference for our team internally at Culture Amp.

Adrian Bece: “Effective CSS refactoring”

CSS is a simple language, which leaves the door open for many antipatterns. Codebases become more and more difficult to maintain. We want to refactor, but we need to consider some important details to make this practical.

Netlify refactored their codebases last year (semantic CSS → Tailwind). This article lists all the forms of unwanted complexity that creep into a CSS codebase.

Good CSS auditing tool: cssstats.com
Wallace CLI: can run in CI

Refactoring is best done at quiet times in a codebase that you know will be actively modified going forward. Work with leadership to set aside time for this kind of housekeeping. Do it in a way that doesn’t block feature development. Try to keep tasks small (see: Refactoring Tunnels).

Refactoring strategy (example: legacy card CSS + global CSS):

Select lowest-scope component (in this case, the card rather than the grid in which it is contained)
Develop styles for the component in isolation (e.g. develop it in CodePen, or prefix class names for this component)
Merge & fix issues: Replace the markup and add the new CSS; leave the legacy styles for now. If the new styles clash or are broken by old styles, implement temporary fixes in a separate file, that you will delete later.
Remove legacy CSS, test & deploy: Consider A/B testing to detect any impact on user experience. Use visual regression tooling if you can.
Repeat for all components, remove the temporary overrides as you go.

Avoiding the need to refactor: discipline, attention to detail, CSS knowledge, well-bounded components. See cssguidelin.es.

Useful interactive coding challenges: frontendmentor.io

Michael Mladky: "Modern CSS rendering performance"

Chrome’s rendering pipeline has 12 steps! contain and content-visibility let us skip steps of this rendering pipeline to improve performance.

Scripting introduces changes to DOM or Styles.
Recalculate Styles determines what styles change on what elements as a result.
Layout calculates the dimensions of elements.
Hit testing determines the pointer bounds for mouse interactions.
Paint generates the pixels for all layers.
Composite merges all the layers into one image.

Elements have:

border-box: determines the layout dimensions for an element
visible boundary: determines the area that needs painting
screen viewport: determines what elements are actually visible

Michael created a testing environment that allowed him to trigger layout and painting.

contain is supported in all the major browsers, and has been supported for awhile in most, but just landed in Safari 15.4.

contain: layout helps us reduce layouting cost. This has the biggest impact (because it also avoids paints). Layout effects in other parts of the DOM will not trigger layout recalculations for children of this element. Element gets its own stacking context, which can introduce bugs if you aren’t expecting it. Performance is not affected by whether elements are visible within the viewport or not.

contain: paint helps to reduce painting cost by not repainting the contents of the element. Crops descendants to the bounds of this element – just like overflow: hidden. Dramatically reduces the render time from changes to those elements – especially when they are offscreen!

contain: size reduces the time it takes to calculate element dimensions. But you need to specify dimensions yourself.

There are also some shorthand values that combine behaviours: contain: content and contain: strict. contain: content usually provides the best combination of performance impact and usability.

values of the contain property and their characteristics

content-visibility: auto (Chrome only) lets you skip rendering for elements that are not (yet) in the browser viewport. It even skips CSS property value recalculation for those nodes. You need to specify a static size for these elements (since the browser won’t do the layout to calculate it for you), to avoid scrollbar flickering. This has a dramatic impact on page rendering performance on really large pages, though!

Michael works at a consultancy that does web application performance audits, and helps companies resolve performance bottlenecks like this.

Ben Buchanan: "Real-world CSS custom props"

Custom properties are just one example of moving on from abstractions to leverage native web platform features.

Ben works at a company that used many frameworks: Angular, React, Vue, Dash … and whatever comes next. They needed their design system to support even pages that aren’t built with a JavaScript framework!

Already have multiple colour themes, and expect dark mode coming soon.

Sass supports themes, has good error handling, etc. but it’s all at compile time. Updates require you to release and import a new version of your style library.

The team phased out the Sass variables, replacing them with CSS custom props and an HTML API. No one really minded.

They ship all their themes in a single variables.css file, and then they select the theme (usually per-page on the body tag). Custom themes are easy: just declare values for a surprisingly small number of CSS custom properties!

The company considers this a successful “strategic technical investment”. Ben recorded a marketing video about it!

IE11 was fine. They had some bank customers they needed to support, but they made a graceful degradation decision: IE11 doesn’t get themes: they get the default blue theme for everything.

Tradeoff: CSS errors silently, but they wired up stylelint to catch typos in custom property names.

There was some FUD about performance, particularly around calc expressions using custom properties, but they never ran into any bottlenecks in practice.

Some war stories of things that didn’t go so well:

Sass habits: importing your variables at the top of every file like you do in Sass causes the same variable declarations to be output multiple times in your bundle.

Lesson: Make sure you only bundle in a single copy of your variables.

…but this broke their linting, because the linter couldn’t find the variable declarations. Thankfully, an open-source add-on for stylelint solved this for them just in time.

Don’t forget to prefix your variable names, because CSS Custom Properties are a global namespace, and they may clash with other libraries if you’re not careful.

There’s a subtle mindset shift you have to make from using Sass variables (which are actually variables) and “CSS variables” (Custom Properties), which are more like “configuration to create difference”. They ended up building a cascading set of style token variables, then component-specific variables that use those tokens, which they then referenced in their component styles. This is still evolving and is somewhat confusing, especially if you’re used to thinking in Sass terms. CSS Layers may help make all this cleaner.

Kathryn Grayson Nanz: "Ditch the Media Queries: Modern CSS Replacements for Better Responsive Code"

We’ve seen a shift from device-based breakpoints to content-based breakpoints. Now with the necessary features landing in browsers, we want to be moving away from breakpoints entirely to fluid design.

Grid hit full browser support in 2017. Flexbox in 2013. Many developers are unclear on the differences between the two, and assume you should pick one or the other. They’re designed to be complementary, and used together.

Grid can repeat columns or rows automatically, and offers auto-fit to specify column size constraints and have their sizes (and wrapping when necessary) calculated automatically.

Resources:

A Complete Guide to Grid
Grid By Example
frame.scss in the Kendo demo app – a great real-world example of a complex grid to learn from

Flexbox is for laying out items in a single dimension (row or column), with the option to wrap. If you need things to align in two dimensions, you need Grid.

Resources:

Flexbox Froggy: a game for learning Flexbox!
FLEX visual cheatsheet

aspect-ratio: Lets you lock an element’s dimensions to an aspect ratio. E.g. Set width and aspect-ratio to auto-calculate height.

min- and max- width and height: Often it will be more convenient to use clamp these days, but these are still useful. Set a “fluid” width then constrain it with a more restrictive/absolute min- and/or max-.

clamp: Set a “base” value, with upper and lower limits. Lets you set responsive limits for values without using breakpoints!

clamp(200px, 50%, 100%) ← Minimum width of 200px, never exceeding 100% of the container width.

calc: Calculate fluid dimensions (e.g. calc(100vw / 3) for one third of viewport width).

min and max: Basically clamp with a single limit.

Responsive units lets the browser do the work for us. Use them whenever you can!

vh and vw are percentages of viewport sizes.
rem and em
combining them for responsive font sizes with limits

Media queries are still useful as an escape hatch for more niche things:

Accessibility preferences (prefers-reduced-motion)
Completely changing the layout/styles of a component
Print stylesheets

Rachel Andrew: "Responsive patterns with subgrid"

Subgrid is a feature designed to solve the problem you see here: nested grid cells that need to line up with each other.

The second card's footer content pushes it out of alignment with the visible grid

With basic CSS Grid, only direct children become grid items in a container with display: grid. Therefore nested elements can’t participate in the grid’s layout.

display: grid; grid-template-columns: subgrid will create a nested grid that uses the parent grid’s columns.

Line names (CSS Grid lets you assign names to lines in your grid, so you can use those names to place items) get passed down into subgrids, so you can use them transparently. You can also add subgrid-specific names to your lines, if you need them.

Of course subgrids inherit gaps defined by the parent grid. But you can override this by setting your own gap in the subgrid. [The effect of setting gap: 0 on a subgrid is a bit like negative margins, giving you a “full bleed” effect. Useful in page layouts? 🤔]

Something else Subgrid enables is stretching a top-level grid item to stretch over all of the rows of a wrapping implicit grid (where the number of rows is determined by the content). Put the unknown children inside a subgrid!

Stretching a background to the full page width while keeping the nested content element aligned with the grid is another use case for Subgrid.

Safari Technology Preview supports subgrid and container queries. You can use them together!

@container grid (min-width: 600px) {
  .item {
    display: grid;
    grid-template-columns: subgrid;
  }
}

Stephanie Eckles: "Practical Uses For Container Queries"

Container queries = styling elements based on the available space for them.

Start by defining a container: container-type: inline-size is the best supported option right now.

You can then apply styles to descendants of that container – but not the container itself (but this may change with the spec). Polyfill available!

Let’s start with a card example. Recommended: your default styles (which display on unsupported browsers) should accommodate the narrowest width. (I.e. mobile-first.)

Demo: sizing a page with a Flexbox grid. The cards in the grid change their layout type, with the last card (spanning the full width of the bottom row) displaying a different layout than the other cards.

Demo of setting font sizes with clamp and cqi (currently supported as qi in Chrome Canary) container-relative units.

Demo of creating a newsletter signup form with three different CSS Grid layouts based on container size. Grid lets you change the positions of the grid items responsively.

Demo of a pagination component that collapses the clickable page numbers (to “Page x of y”) and the Next/Previous button labels at successively smaller sizes.

You can name your nested containers, to query based on multiple layers of container sizes.

Demo of a nav bar with container queries for the overall bar, and also for the menu inside it.

WCAG “reflow” requirement is for site content to reflow to a single column at 400% zoom (320px equivalent on a 1280px-wide display). Container queries can help with meeting this requirement.

Future features:

Container queries based on the styles applied to a container (e.g. its font-size).
Nicer range syntax (@container (width >= 250px)).

Google Chrome Labs has produced a polyfill for container queries. Only supports px-based queries. No support yet for container-relative units.

Demos here: moderncss.dev/hover22

Web Directions Hover 2022 Day 1 notes

Kevin Yank — Mon, 02 May 2022 00:45:52 +0000

These are the live notes I took from Day 1 of the Web Directions Hover 2022 conference for our team internally at Culture Amp. Day 2 is this Friday, and I'll aim to do the same!

Jen Simmons: “What’s new in ’22 for CSS”

Caniuse.com doesn’t just show what’s available now, but “below the line” it shows what’s coming in the next release of each browser.

The Interop 2022 Dashboard is tracking the big push by the major browsers this year to release the most-requested features to improve CSS interoperability.

2022 is seeing an unprecedented number of changes land in CSS that will make a material difference to how it works for developers day-to-day.

The rise of Utility class frameworks [like Tailwind] are a symptom of CSS not meeting developers’ needs. They are actively avoiding writing CSS. 2022 is seeing a concerted effort to change that.

Container queries

main, aside {
  container-type: inline-size;
}

@container (width > 56rem) {
  /* responsive styles here */
}

(But actually inline-size is preferable to width now.)

You are required to declare what your container is, so that the browser can avoid infinite loops in calculating layout. This is why container queries took so long to happen.

Best place to learn this is the actual spec. The web is littered with obsolete blog posts about earlier ideas for the spec. The spec is actually quite short and readable (and critically, it’s up-to-date).

New container units: cqw/cqi lets you specify a percentage of the container’s width/inline-size.

Container queries are currently behind a flag in Chrome Canary. That’s where the proof-of-concept work on this has been happening for years. It’s also enabled by default in Safari Technical Preview!

Cascade layers

Addressing friction caused by selector specificity. Specificity is often not well understood, so Jen gave a brief refresher on how it works.

Something that is more powerful than specificity: origin. For example, custom styles always override browser styles, and inline styles always override custom styles, regardless of selector specificity. Cascade layers let you create extra layers: so you could make it so that app-specific styles always override CSS framework [Tailwind?] or design system styles, freeing you from having to worry about selector specificity (or reaching for !important) to make sure one set of styles override another.

Shipped in Firefox, Chrome, Safari and Edge, but we may need to wait a little for older browsers (especially mobile browsers) to phase out, since this is difficult to progressively-enhance.

Parent Selector / `:has`

Style a figure differently depending on if it has a figcaption as a child:

figure {
  /* … */
}
figure:has(figcaption) {
  /* … */
}

Also can match direct child (table:has(> thead)), sibling (dt:has(+ dt)), and supports negation (section:not(:has(h1, h2, h3))).

Why wasn’t this available before? Computers have gotten faster. We can afford to performance cost of this in today’s browsers/devices.

Available in Safari 15.4 now. Coming to other browsers in 2022.

CSS selector nesting

The hardest part of this is not breaking Sass! 😆

Work underway, but no browser support now. Unlikely to land in 2022.

Selector scoping

Most of the docs out there for :scope on MDN, etc. are now obsolete. That version of scoping is not happening. Early work for @scope in CSS Cascading Level 6 spec.

Not landing in 2022.

Subgrid for CSS Grid

Lets a child grid align its cells to the rows/columns of a parent element’s grid. (e.g. a ul can wrap multiple li cells in a parent div’s grid).

Supported for a long time in Firefox. It’s also in Safari Technical Preview. Work underway for Chromium. Hopefully this year!

Dialog and `::backdrop`

Browsers were slow to implement it because accessibility hasn’t been solved. That seems to have been fixed, so it’s coming to browsers now! Available in all major browsers, with Safari 15.4 the last to implement it [so we can’t quite use it yet].

Related: HTML inert attribute lets you make your own “backdrop”-like things: using HTML elements for visual purposes but hiding them from assistive technologies, keyboard shortcuts, etc. Available in Safari TP now, but going to be really useful as it lands in other browsers.

Also

Smarter focus rings with :focus-visible
Themeing of browser widgets (form controls) with accent-color
appearance property to access or completely disable browser-native form element rendering
and so much more

Bramus Van Damme: “Cascade Layers”

The cascade decides which of multiple matching CSS rules get to “win” when competing to set a property’s value.

Specificity (or order of appearance when there’s a tie) determines the winner for competing rules with the same: Origin & Importance. But specificity doesn’t always match our intent, so we reach for all sorts of hacks to “bump up” specificity on rules that we want to “win”.

Layers let us group styles into layers that are meaningful to us, to avoid unwanted specificity/order interactions! For example, we could very easily declare that component styles always override global styles!

Cool specificity calculator shared in the conference chat.

Recommendation: start by putting your reset and third party styles in layers, so your own styles always override them:

@layer reset, thirdparty;

Article with all the details from Bramus

Kilian Valkhof, “:where :is :has?”

Previously supported as :matches, :any, the opposite to :not is now called :is. It also now supports “complex” (multi-element) selectors, where previously it was limited to “simple” (single-element) selectors.

The ability to specify multiple alternative selectors really cuts down on selector duplication:

:is(nav > ul, footer > ol, aside > p) > li {
  /* … */
}

Gotcha: :is can only match DOM elements, not pseudo-elements like ::before or ::after.

Kilian made the specificity calculator I linked above!

:where is just :is but with specificity 0.

:is adds specificity equal to the most specific selector in its list.

:has is the newest, and least supported. But it’s the one that developers have been asking for forever. It’s the so-called “parent” selector. Style an element based on what elements are inside of it.

(See above for more details on :has.)

:has is called the “relational pseudoclass”, because it lets you target elements based on much more than their descendants.

Josh Goldberg, "Focus Visible, At Last!"

An element can receive focus when a user clicks or tabs to an element. You can see which element has focus with a focus ring.

Some sites don’t like the look of a focus ring, so they remove it with :focus { outline none; }, which is really bad for users who need these indicators (especially keyboard users!). This is a red flag. Please don’t do this.

Unlike :focus, :focus-visible matches elements that receive focus from the keyboard, not the mouse. So you can use it to show focus rings only when they are needed:

:focus:not(:focus-visible) { outline: none; }

:focus-visible landed in Safari 15.4, and is otherwise supported by all our target browsers. So we’re close to being able to drop our JS polyfill for this.

Design tip: don’t forget your focus indicators when considering colour contrast requirements for accessibility. Your indicators need to satisfy the same minimum contrast ratio!

Accessibility tip: accessibility overlays like accessiBe generally don’t work, and may even get you sued. There’s no shortcut to good accessibility. Get yourself dedicated accessibility testers and put real effort into this stuff.

A good design system to check out that does all this stuff well: Codecademy Gamut

Martine Dowden, "Type-setting in CSS"

A brief primer/history on typography and fonts. Serif vs Sans Serif, Display and Monospace fonts.

You might think that fonts generate variants like bold, italic, etc. algorithmically, but in truth most fonts define glyphs for each of these variants entirely separately.

Leading with line-height to improve legibility.

Drop-caps for embellishment with ::first-letter.

Over/under/through lines with text-decoration, which can specify position, style (doubled, dotted, dashed, wavy!), width. Some combinations not fully supported.

ch unit is nice for setting max-width [or max-inline-size] based on a number of average character widths. 39ch = 1.5 alphabets, which is a good width for readability.

letter-spacing (to crowd or space characters) is a useful, and under-used visual effect.

[Sadly I missed the end of this talk because of network/system issues on my Mac. 😢]

Alvaro Montoro, "The colorful future of CSS"

[Sadly I also missed much of this talk for the same technical issue. 😞]

color-contrast function will auto-select colours based on WCAG contrast requirements for accessibility!

E.g.:

color-contrast(#000 vs #222, #eee, #ff0 to AA)

Use it with CSS custom properties (variables) to auto select from your design system colours. Or pick a white or black text based on which will provide sufficient contrast against the background! color-contrast will automatically choose white or black if none of the listed colours meet contrast requirements!

Whoa. We’re effectively getting a super-powered calc for colours so you can mix, match and override colour channels:

rgb(from hsl(180 50% 50%) r g 255)

Make a 50% opacity version of a design system colour!

rgba(from var(--design-system-color) r g b 50%)

Elad Shechter, "How does CSS work?"

Default styles come from the user agent stylesheet, right…? span by default is display: inline. Why don’t you see a user agent stylesheet entry for this in the browser inspector? Interesting question!

To answer this, we need to understand these special values supported by all CSS properties: inherit, initial, unset, revert.

inerit – use the value of the property from the parent component.

initial – Every CSS property has an “initial value”, which is the calculated value you get if you don’t set the property at all (e.g. position: static).

div { display: initial; } will make the div display: inline. This is the answer to the span question above! The initial value is specific to the property, not the element type.

You can see the initial value for each property in MDN (or your favourite CSS reference).

unset – Sometimes behaves like inherit (on properties that inherit by default), or initial (on properties that don’t inherit by default).

CSS has two kinds of properties: “inherited” and “uninherited”. Inherited are all the typography properties – we want a strong element inside a p to inherit the text styles of the p. Properties like this are shown as “Inherited: yes” on MDN.

“uninherited” properties are all the other properties. Box, position, display, transforms… everything, really. These are shown as “Inherited: no” on MDN.

color: unset → inherit
padding: unset → initial → 0

Why have this one value that can mean both things? The special all property, which you can use to reset all properties at once: all: unset. Useful when you have a block that you want to be treated as “unstyled HTML” – a one-line CSS reset!

.common-content * {
  all: unset;
}

…but wait, how do you unset a property like display, whose user agent stylesheet defines a value depending on the element type?

This is what the revert value does! div { display: revert; } sets the div back to display: block based on the user agent stylesheet.

Using this, built The New CSS Reset.

Override default form element styles:

input[type="checkbox"] {
  all: unset;
  /* custom checkbox styles */
}

How to test for screen reader accessibility with VoiceOver on your Mac

Kevin Yank — Tue, 26 Apr 2022 11:11:26 +0000

Every Mac has a screen reader built in, called VoiceOver. This article will describe how you can use it to test the web application user interfaces you build!

If you prefer a video, this is a recording of a brown bag session I gave at Culture Amp in early 2019, when we started getting serious about web accessibility. (We've come a very long way since then!) Besides introducing the features of VoiceOver, I do an ad hoc test of Culture Amp’s engagement survey experience as it existed at that time.

Note: Culture Amp's survey experience no longer relies on a "basic capture" mode to accommodate screen reader users. In 2020, we shipped updates to the main survey experience that fixed all the screen reader issues we (and our auditor, Intopia) could find. This is a far preferable user experience for users of assistive technologies.

Getting started

Every Mac has VoiceOver included, so there’s nothing to install. To turn on VoiceOver, hit ⌘F5. Hit the same shortcut again to turn it off. On Macs with a TouchBar (where the function keys are not visible by default), you can instead hold down command key (⌘) and press the TouchID button three times in quick succession (click-click-click) to toggle VoiceOver on or off.

When VoiceOver starts up, you’ll hear a voice explain your current context, and your options for what to do next. If you have a Safari browser window in focus, it might sound like this:

VoiceOver on Safari. Welcome to Engagement Survey, window. Welcome to Engagement Survey, web content has keyboard focus.

You are currently on web content. To enter the web area, press Control-Option-Shift-Down Arrow.

You’ll also see a black border around the part of the user interface (in this example, the Safari window’s content area) that currently has screen reader focus. This is also known as the VoiceOver cursor.

The message above suggests pressing ^⌥⇧↓ (Control-Option-Shift-Down Arrow). The ^⌥ (Control-Option) part is known as the VoiceOver Modifier, and it’s the two keys you will hold down for almost every command that you send to VoiceOver.

Note

If you find ^⌥ difficult to remember, by default VoiceOver will also respond to the ⇪ (Caps Lock) key. So in the above example you could hold ⇪⇧↓ to enter the web area.

^⌥⇧↓ is the standard shortcut to interact with a group, like entering the Safari browser’s web content area. If you use this to enter a web page, you’ll hear something like this:

In Welcome to Engagement Survey, web content.

You’ll also see the VoiceOver cursor will shrink to enclose just the first element of the web page.

To get VoiceOver to read the current contents of the cursor, you can hit ^⌥F3. To do this on a TouchBar Mac, you’ll need to hold the Fn key to see the function keys on the touch bar, then you’ll need to tap and then double-tap the F3 key – tapping it helps you identify that you’ve tapped the right key (VoiceOver will say “F3, button”), and enables it for activation by double-tapping.

It might say something like this:

CA-logo_coral, group, is in the VoiceOver cursor.

In this example, the VoiceOver cursor is on an image element that lacks a useful alternative text description, so VoiceOver reads out the filename of the image instead. Not very useful, is it? Congratulations! You’ve found your first screen reader accessibility bug!

Moving around

^⌥→ moves the VoiceOver cursor forward.

^⌥← moves the VoiceOver cursor backward.

Each time you navigate, VoiceOver will describe the content in the cursor, then give you a hint of what you can do next.

Hooli logo, image.

You are currently on an image, inside of web content. To exit this web area, press Control-Option-Shift-Up Arrow.

Note

These hints can get tedious, and there are a couple of options to fix this:

At any time, you can interrupt VoiceOver by tapping the ^ (Control) key or ⇪ (Caps Lock). You can tap again if you want to resume playback.

Alternatively you can open VoiceOver Utility (in System → Applications → Utilities, or ^⌥F8 with VoiceOver running). Under Verbosity → Hints, you can disable Speak instructions for using the item in the VoiceOver cursor.

^⌥⇧N immediately plays the hint for the current cursor position, which is handy once you’ve disabled playing them automatically.

^⌥⇧↑ is the standard shortcut to exit, or stop interacting with a group. It’s the opposite of the “interact with a group” shortcut we used above to enter the web page. These two shortcuts let you move into and out of groups (and sub-groups) of elements anywhere on a web page.

By default, when you encounter a group while moving forward or backward through a document, VoiceOver will enter groups and read their contents to you one at a time. To skip over groups as you navigate, just hold down the ⇧ (shift) key.

^⌥⇧→ moves the VoiceOVer cursor forward, skipping over groups.

^⌥⇧← moves the VoiceOVer cursor backward, skipping over groups.

Interacting with links and buttons

When you get to an interactive element like a link or button, you’ll hear something like this (including the hint):

Get started, button

You are currently on a button, inside of web content. To click this button, press Control-Option-Space. To exit this web area, press Control-Option-Shift-Up Arrow.

^⌥␣ is the standard shortcut to trigger an interactive element. It’s just like hitting the spacebar on your keyboard to trigger a button after tabbing to it with your keyboard, but with the VoiceOver modifier added.

Reading in chunks

^⌥A will read the content of the element selected by the VoiceOver cursor. It’s a good way to read an entire group without navigating into it.

The VoiceOver Rotor

Screen reader users frequently jump around the page using prominent landmarks such as headings and form controls. The VoiceOver Rotor is a convenient interface for doing this.

^⌥U opens the VoiceOver Rotor, a two-dimensional menu for navigating page landmarks. The first time you open it, you’ll see the Headings menu, showing all of the headings on the page, and their level (1-6). You can use the up and down arrows to navigate the list, or you can type to filter the list with a search string. Hit Enter to jump to a selected heading in the list, or hit Escape to exit the list.

With the Rotor open, you can view other menus of page landmarks: Links, Form Controls, etc.

VoiceOver’s QuickNav feature (which can be disabled if you want) remembers which list you last had open in the Rotor, and lets you quickly jump between the items in that list using the ↑ and ↓ keys (without the VoiceOver modifier). This makes it super easy to get around a page using headings, for example.

Group navigation mode

VoiceOver has an alternative navigation mode that lets you move around with the arrow keys (^⌥↑, ^⌥↓, ^⌥←, ^⌥→), giving you a sense of spacial awareness about the page. If we were being really thorough with our screen reader testing, we’d have to test both modes! In practice, we’re told by the VoiceOver manual, different sites often work better with different modes, so it’s common for users to toggle this setting as they move from site to site.

To turn on Group navigation mode, hit ^⌥H to open the VoiceOver Help menu, then ^⌥H again to get to the Commands Help menu. Type “DOM” to locate the Toggle Web Navigation DOM or Group and hit Enter to toggle the option on.

Groups, web navigation

(You can toggle back to DOM navigation mode using the same steps.)

You can now use the four arrow keys (with the VoiceOver modifier) to move around the page and have VoiceOver read the entire content of each major content block as you do.

Remember, to get in and out of groups, use ^⌥⇧↓ and ^⌥⇧↑, respectively.

If in doubt, get the page working well with DOM navigation mode, as it’s the default setting for VoiceOver, and is closest to how other screen readers (like JAWS and NVDA for Windows) work.

Ally Beaton looks back on two years in the Kaizen design system

Kevin Yank — Thu, 24 Feb 2022 09:24:33 +0000

On her second-last day as Culture Amp's tech lead for the
Kaizen design system, Ally Beaton joined me to look back on two years of progress in our React component library:

If you're interested in being Kaizen's next tech lead, check out the job ad and please apply!

Micro front ends, strategy, and blueberry muffins

Kevin Yank — Fri, 14 Jan 2022 05:22:40 +0000

As the director of Culture Amp's large-and-growing front end engineering practice, my biggest challenge in the past year was to communicate a coherent strategy that those 60+ engineers could understand and get behind.

The solution was blueberry muffins. 🫐

Set the table

I've worked at Culture Amp for nearly seven years because I believe that empowering companies to put their people first, to make their culture a competitive advantage, makes a difference in the world that I can be proud of.

We build a set of web-based products that together we call an employee experience platform. It's a growing collection of React apps to 1) collect employee feedback to drive engagement, 2) run performance reviews that are fair and equitable, and 3) develop the most important workplace skills in managers and individual contributors.

When I joined Culture Amp in 2015 I was employee number 26, we had a single engineering team, and we had yet to land our 200th client.

How it started: Culture Amp Insight report circa 2015

Seven years later, over 5,000 companies around the world now use our products, which are built and maintained by over 100 engineers across a dozen or so different teams.

How it's going: the same screen in 2022 – with fake data, of course

Safe to say, our front end engineers today build a lot of UIs – new and old, routine and novel – all at once. From that comes our biggest challenge. For it to go well (by which I mean we build user interfaces (UIs) affordably, sustainably, and producing a product our customers love) we must empower those engineers to work in separate codebases, but embrace every opportunity we have to leverage consistency across those codebases.

Did I say codebases? I meant blueberry muffins.

The shopping list

To articulate a strategy for the practice, I had to start with where we are. For five years and counting, Culture Amp has had a group of engineers devoted to the health and scalability of front end engineering. Here's what they've built so far:

Back in 2017, we began with our design system: Kaizen. A set of design guidelines, atomic values (design tokens), and more than 50 reusable components (with many more to come!), Kaizen defines the consistent look and feel of our product. There's always more to do, but Kaizen is already in wide and successful use in all our UI code bases today.

The Kaizen website

Kicking off a couple of years later in 2019, Culture Amp's standard development, continuous integration, and serverless infrastructure deployment tooling for UIs is called frontend-ops. It's still an internal project at this stage so I can't link to it, but here's a peek at some of its features:

From the README of Culture Amp's front end app template

So what's missing?

Culture Amp has settled on React written in TypeScript as the standard platform for all of its UIs. But React is just a view framework, which leaves a lot of problems for engineers to solve in building a web app. Routing, data fetching, state management, form validation… there are at least a dozen more things that every Culture Amp UI needs, but which React doesn't provide. Having every team reinvent these wheels for every project is not a good use of their time. In short, we need a more full-featured framework for our React applications.

At the same time, there are things we need to learn and get better at together as a practice. Not because we're bad at them, but because the art of web application engineering is always progressing, and we need to keep up. Test automation, web accessibility, application security, animation and other user experience refinements, performance optimizations, and driving runtime error rates down.

All this and more I wrote about in a sweeping vision for the many ways we would improve as a practice in the months and years ahead. It was all in there. Would it provide the clarity my fellow engineers were craving?

One of Culture Amp's values is to "Learn faster through feedback", so in July 2021 or so I shared my latest draft with a handful of front end engineers and engineering leaders around the company, and asked what they thought.

I got a ton of great feedback, much of which I might share in a separate article about writing strategy documents if folks are curious. But my single biggest take-away that crystallized in a conversation with my manager, Michael Ridgway (thanks, Mike!), was that I was missing exactly that: one memorable concept to pull the whole thing together.

Rather than a shopping list of necessary ingredients for the success of our practice, I needed to give readers one idea to remember, and carry with them into their work.

A delicious metaphor

So yes, a blueberry muffin.

A very delicious muffin, despite appearances!
Photo borrowed from Gemma's Bigger Bolder Baking.

Quoting from my final strategy document:

If our front end apps are blueberry muffins, we want to bake a lot of them while keeping them consistently delicious. To do this, we’ve got a ready-made “muffin cup” we can use on every muffin (frontend-ops), and we’ve locked in a single source for our “blueberries” (Kaizen components). Next, we need to work on the recipe for our “batter” (our React app architecture/framework).

Kaizen components are blueberries because they're the colourful morsels that festoon the surface of our "muffins". When you decide to bake a blueberry muffin, you definitely don't have time to plant a blueberry bush and wait for it to grow, so you need a reliable source of high-quality blueberries. Likewise, no one wants to build a date picker from scratch for their new app.

Frontend-ops is the paper cup because it's the easily-overlooked conveyance device that speeds the muffin on its journey from oven to mouth. Most ~~UI engineers~~ bakers couldn't make one from scratch even if they wanted to – it's not even food!

The app framework is the batter because it's not the point of the muffin – it's the blueberries that make your mouth water, not the cake – but it holds it all together. Without it, you'd just have a pile of blueberries. One bowl of batter makes an entire batch of muffins: you don't make new batter for each muffin!

The muffin itself represents the app because it's the product we're ultimately trying to offer. No two are exactly alike, but a consistent set of ingredients ensures that every muffin can deliver the same quality despite its uniqueness.

This single metaphor captures the one most important thing we seek to achieve (make our front end apps more alike, from architecture to pixels), the two aspects that are already going well (UI components and serverless architecture), and the one missing piece that we need everyone to rally to create (a shared application framework).

Since I published this strategy and presented it at leadership and practice meetings, not to mention numerous engineering inductions since, it's become known as the "blueberry muffin document", and engineers have begun using shorthand like "is this project going to contribute to our 'muffin batter'?" This, more than anything, is the signal that tells me the strategy has landed, and is meaningful to the engineers I wrote it for.

Crumbs on the floor

What about all the other things that we're also working towards as a practice: test automation and accessibility, performance and error rates? Were they sacrificed in service of a satisfying metaphor?

Well that's the thing about a strategy: it isn't just a list of everything you want. It needs to narrow the focus, elevating a just few things even over all the other also-desirable things.

Beyond the overriding priorities covered by the blueberry muffin, the document lists five "even overs":

Grow test automation to reduce manual testing burden

Improve platform accessibility

Harden our UIs with new browser security features

Polish the details of our user experience

Grow performance, shrink errors

For each of these it describes the current situation, efforts already being made to progress it, and advice for how engineers passionate about it can contribute to driving it forward.

You can get a lot done with 60+ engineers, and I'm confident we will progress significantly all five of these areas in the coming year. But none of them is as important as perfecting our blueberry muffin recipe.

A muffin for the road

Am I saying that you should embrace this same muffin metaphor if you happen to be writing a strategy for your engineering practice? Not at all!

But if you need to pull together a lot of threads into something memorable, do look for that unifying metaphor. Have some fun with it. Got a strong coffee culture in your team? Maybe you're trying to make the perfect macchiato! Like ice cream? Who doesn't!? What might a Magnum say about your architecture?

There are probably even some non-food-related metaphors to consider; I'm just a little hungry right now. Honestly, I started with chocolate chip cookies until I realised that those aren't baked in a tray of identical cups!

Working out the kinks with Louis Quinnell, the tech lead for frontend-ops

This, like so many things, is an opportunity to create culture. Have some fun with it!

As you might imagine, we think of this kind of thing a lot at Culture Amp. If you like thinking of engineering problems through a lens of company culture, please apply!

A Conversation with Jason O'Neil

The delivery lead of Culture Amp's Front End Ops team, Jason O'Neil sat down with me for a brief chat about his career, and how it intersects with the subject of this blog post:

Thanks to Aneta Voborilova for the cover image.

Forem: Kevin Yank

An Experiment with AI Assisted Web Development

Getting started

A mix of "wow" and "wtf"

Outsourcing visual design to the model

Don't trust the model to troubleshoot

When robots conspire

My impressions of Cursor

How to Build an Agent in JavaScript

Pencils Out!

The read_file tool

Detour: human in the loop

The list_files tool

Project Overview

TypeScript Files:

Let it edit_file

Isn't this amazing?

Use Tailwind CSS prefixes for shared design system components

A very brief intro to Tailwind

Styling shared components

The naive approach

The small problem: Configuration coupling

The big problem: Tailwind depends on source order

Seductive non-solutions

!important

Boost specificity with important

CSS cascade layers

Discard duplicates

An opportunity: intelligent Tailwind output merging

The actual solution: prefix

useEffect vs useLayoutEffect and server-side rendering

What's useLayoutEffect good for?

See also:

MelbJS March 2023 notes

Fundamentals of Module Federation, Mathew Byrne

Standard Promises. Promise Standards, Franky

Pyodide and JS: The One Language to Rule Them All, Hon Weng Chong

Web Directions Hover 2022 Day 2 notes

Adrian Bece: “Effective CSS refactoring”

Michael Mladky: "Modern CSS rendering performance"

Ben Buchanan: "Real-world CSS custom props"

Kathryn Grayson Nanz: "Ditch the Media Queries: Modern CSS Replacements for Better Responsive Code"

Rachel Andrew: "Responsive patterns with subgrid"

Stephanie Eckles: "Practical Uses For Container Queries"

Web Directions Hover 2022 Day 1 notes

Jen Simmons: “What’s new in ’22 for CSS”

Container queries

Cascade layers

Parent Selector / :has

CSS selector nesting

Selector scoping

Subgrid for CSS Grid

Dialog and ::backdrop

Also

Bramus Van Damme: “Cascade Layers”

Kilian Valkhof, “:where :is :has?”

Josh Goldberg, "Focus Visible, At Last!"

Martine Dowden, "Type-setting in CSS"

Alvaro Montoro, "The colorful future of CSS"

Elad Shechter, "How does CSS work?"

How to test for screen reader accessibility with VoiceOver on your Mac

Getting started

Moving around

Interacting with links and buttons

Reading in chunks

The VoiceOver Rotor

Group navigation mode

Further reading

Ally Beaton looks back on two years in the Kaizen design system

Micro front ends, strategy, and blueberry muffins

Set the table

The shopping list

A delicious metaphor

Crumbs on the floor

A muffin for the road

A Conversation with Jason O'Neil

The `read_file` tool

The `list_files` tool

Let it `edit_file`

`!important`

Boost specificity with `important`

The actual solution: `prefix`

What's `useLayoutEffect` good for?

Parent Selector / `:has`

Dialog and `::backdrop`