Aquileo | David Luhr

Aquileo | A 10x engineer isn't what you think

2025-09-05T00:00:00Z

A 10x engineer isn't what you think

If 10x engineers exist, they don't work 10x faster or create 10x the output. Speed and output without quality are waste.

A 10x engineer creates 10x the value with the same resources. They question requirements, cut scope and hone in on what's essential, continuously improve the process, and iterate on their work.

The essential 10%

Lean manufacturing shows that 90% of any process is waste. By identifying the waste and eliminating it, we are left with the 10% of value-adding activities.

Now, this doesn't mean we fill 100% of our capacity with the 10% of value-adding activities at 10x the scale. That likely is impossible and unsustainable.

Instead, we can work more calmly (increased sustainability), with stricter criteria for what we take on (better framing), and enjoy more slack in the system (increased resilience) while using fewer resources (increased efficiency).

Pairing

Pairing is another dimension engineers can scale their impact. Pairing is the most effective form of knowledge sharing and cross-mentorship I've experienced, as two people working on the same project can continuously support, unblock, and mentor each other. This is especially powerful when the pairing partners have different skillsets, as they level their skills over time.

Pairing on work is also faster, more efficient, and higher quality than solo work. Having someone to look up documentation while you work, help troubleshoot issues, keep you unblocked, offer more creative ideas, motivate you to stay focused, and act as a continuous code reviewer is many times more effective than the typical way of working.

So if 10x engineers exist, they likely are pairing.

How to enable 10x engineers

If we understand that the goal is to increase quality and value creation, not just pace or volume, we prioritize creating space instead of simply moving faster or shipping more features.

We should reserve capacity for people to reflect on their work and form novel ideas. They should have time to identify and eliminate waste, which improves quality, increases efficiency, and allows us to focus on more valuable work. This will also naturally lead to an increase in pace and volume while preserving quality and value creation.

We should encourage people to question requirements, including whether a potential project is even worth doing if it's not sufficiently timely and impactful. One of the best outcomes of potential projects is determining that we shouldn't do them at all, as we save 100% of the resources we would have invested, and avoid the risks of diluting our focus and maintenance overhead. We should celebrate and encourage these decisions instead of only incentivizing doing more, new things.

Lastly, when making hiring, resourcing, or process decisions, defer to those doing the work to understand what they need. Often, teams try to hire their way out of bottlenecks, thinking that more people will increase pace and output. In reality, this has diminishing or even negative returns, as it simply scales or exacerbates existing waste and bottlenecks. Instead, by focusing our resources and efforts on the 10% of work that is valuable, we can have much larger impact with the same or even fewer resources, while being happier and more fulfilled along the way.

Aquileo | 10 things I've learned from 10 years of studying lean manufacturing

2025-07-22T00:00:00Z

10 things I've learned from 10 years of studying lean manufacturing

Lateral thinking has proven to be one of the most effective habits I've developed in my career. Over the last 10 years, learning about lean manufacturing has benefited my work in software more than any other topic.

10 years ago, I stumbled across the topic of lean manufacturing. I had recently shifted my career into web design and engineering and was underwhelmed by Scrum and other permutations of Agile. The original intent of Agile seemed clear and focused, but the day-to-day reality of how teams were managing projects and their overall process seemed over-engineered, heavy, and exhausting.

Then I discovered modern lean manufacturing and was drawn to the simplicity and lightness, along with the deep commitment to quality and continuous improvement.

For the last decade, I've independently studied all aspects of lean manufacturing, including the history of the Toyota Production System, the emergence of 2 Second Lean, and all the recent transformations companies have undergone.

There's something so concrete about observing physical processes moving through a factory, learning to identify and address waste, and clearly recognize improvements in quality, efficiency, and most importantly, the happiness of the teams and customers. These learnings have allowed me to spot and correct the much more abstract wastes found in digital work, and address areas of need that no software development methodology even considers.

I want to cover 10 things I've learned that have most impacted my work. I'm going to avoid technical terms, concepts, and theories wherever possible, but would be happy to expand on anything in future posts.

1. Everything is a process

The first mistake many individuals and teams make is to think lessons from another industries or types of companies don't apply. How can learning about physical production lines in a factory help with software development?

The truth is, the industry, product, production steps, etc. are all arbitrary.

What unites all forms of work is: everything is a process.

This realization is critical to understanding that everything, from welding an aluminum frame, to reviewing scientific findings, to designing and engineering a dropdown menu in a web app, is a process that creates or destroys value.

In fact, our job titles are misleading. A designer's job isn't to design user interfaces. Their job is to continuously improve the process of designing user interfaces. Any role should basically be considered to that of a "process engineer."

So, the lessons learned by other industries, even with wildly different contexts and approaches, have underlying, universal truths to learn.

2. There's always a customer

In addition to everything being a process, we need to realize every process has a downstream customer.

Of course, a business serves customers who buy a product. And of course, we want to serve them and produce the best quality and value for our customers.

But, we need to recognize that everything we do always has a customer. Within a team, that customer is usually internal. The customer might be someone in a different role or layer of the organization, and sometimes is yourself, present or future.

If we ask "who is the customer?" with any project or decision, we can be clear on who we're serving and creating value for. This practice completely inverts an org chart. The CEO's customers include everyone in the company. A manager's customers include everyone on the team. An engineer's customers include a pairing partner, a designer, or customer advocate.

And of course, everyone in the company is there to serve the actual customers, first and foremost. But, this is usually top of mind already, and sometimes is used as an excuse for not serving or even sacrificing internal customers, which ironically will also destroy values for external customers.

3. Blame the process, not the person

With processes behind everything we do in service of a customer, how should we respond when someone makes a mistake or we discover waste?

We should blame the process, not the person.

This inverts the typical reflex of assuming a mistake is an individual failing, shortcoming, or skill issue.

Instead, we need to realize that the vast majority of people really just want a challenging, interesting, and rewarding career. We're all just hoping to do a good job, contribute meaningfully, and benefit from the shared success of our work.

Next, we need to recognize that, outside of rare cases of actual sabotage, mistakes are the result of some upstream process, decision, or even standard. Everything from a complete lack of process to a very considered and detailed process has waste and risk of mistakes.

With this in mind, our first thought when something goes wrong is to blame the process. This engages everyone, including the person who made a mistake, in making things better.

Issues no longer become a point of individual blame and shame. They become an opportunity for improvement. The individual who made the mistake is no longer the wrongdoer. It shouldn't reflect on their personal performance. They become the most recent expert in what went wrong, what caused the issue, and how we might prevent it in the future. Their experience is the most valuable information to understand, and their ideas and creative solutions are key to improving. They should be evaluated on their contributions to the improvement.

4. Learn to identify and not tolerate waste

The default mode for many teams is performing routine work without question or reflection. Because everything is a process, and every process has waste, it's critical to learn to identify waste.

The best way to do this is to be sensitive to anything that creates friction, frustration, or struggle, no matter how small. As you work, continuously ask if there's a better way.

In learn manufacturing, there are 8 types of waste:

Transportation: unnecessary movements of products or materials
Inventory: excess raw materials, work in progress (batch processing), or finished goods. Often the root cause of other wastes.
Motion: unnecessary movements of people
Waiting
Overproduction: making more than the next process needs
Overprocessing: unnecessary steps or processing that often lead to transportation waste
Defects: efforts caused by reject, rework, returns
Skills: wasted human genius and potential. The worst of the 8 wastes.

Although these originated from physical manufacturing, they easily map to software development:

Transportation: every code change has to go from commit, to pull request, go through review, get merged to staging, get validated, get rolled out to production, etc.
Inventory: concurrent projects create excessive work in progress, leading to waiting, overproduction, overprocessing, transportation, defects, and more.
Motion: documentation is hard to find. Knowledge and communication are split across many tools and locations. Code is divided across multiple codebases and services. Work is spread across multiple tools, services, and logins.
Waiting: tests, pre-commit hooks, CI/CD actions take too long run. Pull requests are waiting for review. A question or request for help goes unanswered and blocks progress.
Overproduction: ideas are easy to spin up, which exacerbates already stressed engineers. Low-value features and side projects don't have customer demand and dilute the product.
Overprocessing: upfront, high-fidelity design is often unnecessary and thrown away after a feature is built. A proposal goes through several layers of review and formalities.
Defects: bugs, typos, downtime, etc. This is one of the only wastes software teams are actually aware of and sensitive to.
Skills: wasted human genius and potential in any industry is common and equally damaging

Once you notice something wasteful, or even something that simply bugs you, don't accept it. All too often, teams can list tons of things that frustrate them or are clunky, but never get around to doing anything about it. They defer to how things have always been and assume that's how they have to be. Teams can have incredibly high tolerance for tech and process debt, where things that drag down daily work are allowed to persist for years or never get addressed.

5. Stop and fix

So, everything is a process in service of a customer, every process has waste, and we should blame the process instead of the person when finding mistakes, defects, or waste. But what do we do when we find a problem?

We should stop and fix.

Yes, we should immediately stop what we're doing and fix the problem. We should prevent it from occurring again. And, others should stop what they're doing to help.

This sounds absurd and completely inefficient to teams when they first hear it. The thought of halting all output to fix a problem seems to threaten deadlines, burn valuable time and energy, and be wildly disruptive.

The main pushback I've heard is: "we don't have time to do that. We're too busy to stop everything every time a problem comes up."

But, the truth is: you're too busy to fix your problems because you're too busy to fix your problems.

The reason why you're so busy, the reason why there's no slack in the system, the reason why stopping to fix a problem would jeopardize shipping on time, is because you never address the problems that create waste, destroy value, and eat away at your capacity.

To illustrate this, let's talk about Toyota. Toyota assembles tens of thousands of vehicles a week. And anytime a person on the assembly line encounters an issue, they pull a chord that halts production. Everyone around immediately comes to assist the person who pulled the chord to help diagnose and fix the problem.

In just one of their factories with 250 assembly line workers, they do this 16,000 times in 1 week. Each person pulls the chord more than 60 times a week. And this is a company that is world-class in quality and consistency. They got this way by stopping and fixing to ensure defects don't make it past where they originally occurred.

6. Make daily improvements

Like stopping and fixing, this next practice receives the same excuse of "we don't have time to do that." Teams dedicate the first 30 to 60 minutes of their day to fix what bugs them and make small, incremental improvements.

This practice involves something called Daily 3S. 3S stands for "Sweep, Sort, Standardize."

Sweep: clean the work area. This can be physical, digital, or both. As you clean, remove anything unnecessary, make things nice, and look for waste or signs of defects.
Sort: put things back. Reset the work area to the way it should be.
Standardize: make the improvement stick. If something doesn't have a dedicated place, make one. Organize or reorganize things to make them more readily accessible based on what you need in your work.

This practice has immediate benefits for each day of work. It's also a great warm up to get momentum for deep work and deeper problems. And, it's the best way to learn to identify way, try ideas, and engage in creative problem solving.

This daily habit also prevents massive, wasteful refactors, redesigns, etc. in favor of incremental, continual improvements. And, if there isn't time for all the improvements in one morning, then the team only needs to wait 1 day until the next opportunity.

No improvement is too small. Many improvement ideas are quick, rough experiments. But each improvement will spawn many others, including improving an improvement. If it's better than what we have now, it's worth doing.

7. Prioritize improvements

With improvements that can't be made immediately, it's important to prioritize them.

The criteria for prioritizing improvements is:

Safer
Better quality
Simpler
Faster

Most teams jump right to "faster," thinking that will correlate to efficiency. But, faster is the last layer of optimization to make. And, fixating on making something faster can result in speeding up something that shouldn't even exist.

Better quality, simpler, and faster are easy to translate to software development, but safety can be harder to grasp. Safety in software actually has many important qualities:

Security
Privacy
Psychological safety
Accessibility
Ergonomics

Ideally, an improvement benefits safety, quality, simplicity, and speed all at once. But, we should make tradeoffs based on these priorities. If something improves safety, we should be comfortable with it being more complex and slower. Over time, we can make further improvements to capture these other qualities.

Don't get caught up in tracking improvement ideas, just use this ranking to determine which current idea is most important. Individuals can keep their own lists if they like, but maintaining improvement backlogs (like any backlog) is wasteful. People will remember good ideas as they encounter repeated frustrations. Ideas that don't come up again are almost always no longer relevant.

8. Mistake-proof

When we find the source of an issue, mistake, or defect, we should aim to prevent it in the future. This is called mistake-proofing and leads to valuable improvements.

There are lots of examples of mistake-proofing in software development, especially with tooling, validation, and automation. Test-driven development prevents failing code as soon as it arises. Linting errors give realtime feedback, and pre-commit hooks prevent issues from making it to CI/CD checks. Validation on form inputs guards submission.

Practices like code review and QA help identify and correct mistakes before they reach customers, but aren't mistake-proofing. Mistake-proofing makes the mistake impossible in the first place, or at least provides feedback as close to the mistake occurring as possible.

9. Follow one-piece flow

A central misconception many teams have is confusing activity for productivity.

This confusion leads to the wasteful and detrimental practice of having multiple projects in progress for any given team and/or individual.

Concurrent projects create waste through increased overhead, waiting, context switching, miscommunication, and exhaustion. These wastes cause more defects, lead to burnout, and harm both velocity and quality.

To address this, strive for one-piece flow, where each person, team, or even company has a single project at a time, carried through to completion, before taking on a new project.

Like stop and fix, one-piece flow gets a lot of initial pushback. It seems significantly slower than batching work and having multiple projects at once. But the chaos and motion of concurrent projects is an illusion: if you combined the cycle time of each project and summed it up, it will be longer, often significantly, compared to the total duration of completing those projects one at a time.

One-piece flow makes everything easier, especially when performed at a team level. All team members start a project at the same and build shared context as they collectively focus on a single effort. This creates pairing opportunities, eliminates waiting, handoff, and context switching, and makes work more engaging and successful. By pairing on the work together, team members offer each other continuous review, eliminating the need for PR reviews and alleviating QA significantly. This mistake-proofs much of the work, as pairing partners catch a mistake as it occurs. If a larger problem or blocker arises, everyone has shared context to help and is available to offer support.

Not only is one-piece flow faster and higher quality, it increases actual agility. By only starting and finishing one project at a time, the team has more frequent opportunities to propose and select the next project with a completely clean slate, based on the most recent context and experience. When multiple projects are in progress, there is perpetual work and overlapping timelines, which can lock teams into decisions for weeks, months, or even years at time before reflecting on what should come next.

Another way to improve one-piece flow is to work on smaller projects. Aim to reduce scope from multiple weeks, to a single week, to even a day. This increases agility further and often results in more impactful work by focusing on what's essential.

One-piece flow should also be done at each hierarchy of work: from initiative, to project, to task, to step in the process. It's crucial to maintain focus and reduce work-in-progress and context switching at every level.

10. Achieve flow

All of these practices culminate in achieving flow: the ease of work progressing smoothly, swiftly, and successfully from idea to the customer. Flow is an energizing, rewarding, and valuable state of work that leads to a happier team and more capable company.

Flow also involves identifying waste and issues at higher level. Central to this is understanding and spotting bottlenecks. Bottlenecks occur in every process. They're easy to spot with the waste of inventory: simply look for where work is waiting or work-in-progress is piling up more instead of one-piece flow.

Teams can make a damaging mistake when they become aware of bottlenecks. In attempt to get caught up, they try to push the work through the bottleneck faster, often by simply pressuring people to work harder, longer hours. This simply makes the bottleneck worse, as people are over capacity, which harms quality and can lead to complete burnout. It's disrespectful to people, blames them instead of the process, and is also the completely wrong way to resolve a bottleneck.

The first step in actually resolving a bottleneck is leveling production. This means reducing the throughput of all surrounding steps in the process to match the pace of the bottleneck.

For example, if there are a bunch of designs waiting to built, stop designing more features, and stop doing upfront design. Allow engineers to complete the work-in-progress, and when they're ready, start on a new project together with one-piece flow. This guarantees design and engineering will work at a successful pace and prevent future excess inventory.

The bottleneck has been eliminated once the production across stages is running evenly. Often, this will make it obvious that there is another bottleneck elsewhere. Repeat this process until the throughput of the whole system is even. Then, the overall throughput can be increased by making continuous improvements, such as stop and fix, daily 3S, and the other practices explained above, which improve speed and quality together.

So, as you learn to identify waste, identify what isn't flowing, adjust everything else in the process to match, and then make incremental improvements to lift up the whole process together. This will result in a calmer, happier, more efficient, engaging, and successful experience for everyone, while bringing more value than ever to customers.

Wrapping up

I could write an entire book on this, and have often considered doing so. Each of these 10 lessons deserve chapters of their own, and there are dozens of other lessons I haven't covered here. Let me know if you have any questions, what you're struggling with, and if you'd like me to write further on any of these topics.

Aquileo | A deep dive on the UX of number inputs

2025-07-01T00:00:00Z

A deep dive on the UX of number inputs

One of my favorite things about design engineering is how deep the UX considerations can be. I love thinking through and improving every little detail of even an isolated element.

A surprisingly deep topic is the UX of a number input.

You could simply use a default <input type="number"> and be done, but there are many surrounding usability and accessibility considerations to explore.

First off, any interactive element needs an accessible name. So, at the very least, we need the following:

<label for="quantity">Quantity</label>
<input id="quantity" type="number">

Next, we have validation. There are a lot of scenarios to consider here:

Is there a minimum acceptable value?
Is there a maximum acceptable value?
Should we allow decimals or enforce some other step amount?
How should we handle non-numeric or invalid input values?

Luckily, <input type="number"> has native attributes to help with this:

<label for="quantity">Quantity</label>
<input id="quantity" type="number" min="0" max="100" step="0.01">

The step attribute provides further functionality. It not only enforces validation on the input's value, but it changes the increment/decrement amount of the up and down arrow keys, as well as the native "spin" buttons (increment/decrement buttons within the input) that accept clicks.

For example, using step="0.01" would allow any number up to 2 decimal places, but it comes with a usability tradeoff: we can now only increment/decrement by 0.01 at a time. This is great if users need fine-grained control over an input value, but cumbersome if users need to rapidly change the input value by whole values. Using step="any" can help with this, as it reverts the increment/decrement amount to the default of 1, but allows arbitrary decimal values.

The min, max, and step attributes allow us to use the :invalid and :valid pseudo classes to provide visual feedback about the input's state. You may also want to provide feedback to the user of what kind of values are accepted:

<label for="quantity">Quantity</label>
<input id="quantity" type="number" min="0" max="100" step="0.01" aria-describedby="quantity-help-text">

<p id="quantity-help-text">Please provide a value between 0 and 100. Decimal values are allowed.</p>

Enhancing `type="number"`

We can improve the UX of a native number input with some customizations.

Larger increment/decrement amounts

Let's say users often need to adjust the input's value by a large amount. We could increase step to 10, but then users can't increment/decrement by less than 10 with the keyboard of spin buttons. Instead, we could add support for Shift + ArrowUp and Shift + ArrowDown as a larger increment/decrement interaction. We just need to add an event listener for keydown on the input and change the input value by 10.

But, now that we're manually changing the input's value, we're now responsible for enforcing the min and max values. Let's start with the "big" increment use case (Shift + ArrowUp). We have a few scenarios to handle:

Prevent the default behavior of incrementing the input value by 1.
The input's current value is already the max value. Don't do anything.
If we increment the input's value by 10, we would exceed the max. Set the input's value to the max.
If we increment the input's value by 10, we are below the max. Increment the input's value by 10.

And of course, we need to handle the inverse considerations for the min value. Here's some pseudo code of this event handler:

numberInput.addEventListener("keydown", (event) => {
	const currentValue = Number.parseInt(numberInput.value, 10);
	const stepAmount = 10;

	if (event.shiftKey) {
		if (event.key === "ArrowUp") {
			event.preventDefault();

			const maxValue = Number.parseInt(numberInput.getAttribute("max"), 10);

			if (currentValue === maxValue) {
				return;
			}

			if (currentValue + stepAmount > maxValue) {
				numberInput.value = maxValue;

				return;
			}

			numberInput.value = numberInput.value + stepAmount;

			return;
		}

		if (event.key === "ArrowDown") {
			event.preventDefault();

			const minValue = Number.parseInt(numberInput.getAttribute("min"), 10);

			if (currentValue === minValue) {
				return;
			}

			if (currentValue - stepAmount < minValue) {
				numberInput.value = minValue;

				return;
			}

			numberInput.value = numberInput.value - stepAmount;

			return;
		}
	}
});

Using keydown instead of keyup is another UX consideration. Native number inputs respond to keydown, which allows key repeat to quickly change the input value without having to repeatedly press a key. We want to match this behavior with our event listener.

Smaller increment/decrement values

We can also add functionality in the other direction by allowing even finer-grained incrementing and decrementing. We can follow the same approach as above with a dedicated keyboard shortcut, say Control + ArrowUp and Control + ArrowDown, and update the input value by a small amount (0.1, 0.01, etc.).

Having multiple levels of granularity can create a very fluid and efficient interaction pattern for rapidly adjusting a value to a precise target.

Replacing native spin buttons

Native number inputs have "spin" buttons, which are the small increment/decrement buttons nested inside the input.

While these dedicated controls are a nice consideration, they have incredibly small tap targets which are difficult to use. We can replace these with our own increment and decrement buttons.

First, we need to hide the native spin buttons. We can use appearance: textfield to achieve this.

Next, let's provide some dedicated <button> elements:

<label for="quantity">Quantity</label>
<input id="quantity" type="number" min="0" max="100" step="0.01" aria-describedby="quantity-help-text">

<button type="button">Decrease quantity</button>
<button type="button">Increase quantity</button>

Like our Shift + ArrowUp and Shift + ArrowDown event handlers, the click event handler for these buttons needs to respect the min and max values. Luckily, the click event handler fires on keydown for Enter and Space, so holding a key will rapidly change the value.

Lastly, we should consider tab order for these controls. Visually, we may want to have the decrease button, input, and increase button appear in that order. While it's best to have visual order and tab order match, it may create a confusing user experience if the first control to receive focus is a decrease button, and not an input with an accessible name. For that reason, I think it's worth the tradeoff of placing the increment and decrement buttons after the number input in the DOM, and using CSS to change their visual order. This way, the user first tabs into the number input and then proceeds the increment/decrement controls.

The focus order for a custom number input I built for Buffer.com's pricing page goes from the input, to the decrement button, to the increment button.

It could also be argued that these increment/decrement buttons are primarily tap targets and should be excluded from the tab order. In that case, they could use tabindex="-1" so the number input is the only focusable control.

Always working state

If the number input is used in a user-submittable form, it's best to provide visual and text feedback if the input's value is invalid. This allows the user to correct the value to be able to submit the form.

However, if the number input is part of an interactive control for something on the current page, we can improve the user experience by keeping the input in an always valid state.

Natively, <input type="number"> allows the user to type any character, and simply enters an :invalid state if the value is non-numeric and doesn't respect the min, max, and step attributes.

To improve on this, we could prevent invalid key presses from altering the input's value. As a user, this may cause some initial confusion, but can teach the user what is valid input.

We could also immediately correct values outside of our desired range, such as increasing a value that is below our min to the min value. However, this can be a frustrating user experience when editing a field. If our min is 10, the user may want to delete the input value to type 23, but are prevented from doing that if they type 2 on its own. THis forces users to come up with frustrating workarounds, such as temporarily typing 123, moving to the first digit, and deleting 1 to input 23. Preventing this issue becomes its own rabbit hole. Do we debounce the input value before correcting the value? What debounce length is appropriate?

Alternatively, we can correct the input's value on focusout or Enter. This allows the user to input any value, and then corrects the value once focus has left the field or the user has "submitted" the value. If the user increments or decrements the value, we still want to update the interface immediately. But, if the value is invalid, we don't do anything until focusout or Enter and then convert the value to something sensible:

If the value is non-numeric, revert to the default value (or, the last valid value if there isn't a default)
If the value is larger than the max, reduce it to the max
If the value is less than the min, increase it to the min

A custom number input I built for a design tool that converts invalid values into the the last valid number value.

Allowing math expressions

For more advanced web apps, such as a design tool, allowing users to enter math expressions in a number input saves them the effort of opening up a dedicated calculator, keeping them in the flow. This enhancement adds a lot of implementation complexity, but can be a major UX upgrade in situations where math is frequently needed.

Similar to keeping the input in an always working state, we would want to wait for focusout or Enter to evaluate the expression. When we do our validation checks, we also need to parse the input's value to check if it's a valid math expression. If it is, we evaluate the expression (think PEMDAS), then use the resulting value for our remaining checks (enforcing min, max, and step).

The design tool custom number input also accepts math expressions. The expressions are evaluated to produce the number input's value.

When to go beyond `type="number"`

All together, <input type="number"> is a good fit if users need to select or provide a value from a discrete range. But, in some cases, such as a phone number, incrementing and decrementing the value isn't useful or expected behavior.

In this case, we may want to use <input type="text">. This means we'll have complete control over the input's functionality, but we also have to manually handle all validation and functionality.

This includes rolling our own versions of min, max, and step and the resulting validation states.

We also need to use inputmode="numeric" or inputmode="decimal" to bring up the appropriate keyboard on mobile devices, and pattern to enforce input value rules with Regex.

Custom formatting

Whether using type="number" or type="text", it may be helpful to provide automatic formatting, such as adding separators to large values for readability or adding hyphens, spaces, and/or parentheses to common formats such as phone, postal, credit card, or ID numbers.

This can either be done dynamically as the input value changes or on focusout or Enter.

With dynamic formatting, it's important to advance the cursor properly to allow the user to continue typing as expected. Similarly, if the user deletes a character, it may be helpful to automatically remove any adjacent formatting characters. Basically, automatic formatting should be transparent with the typing experience: don't make users move the cursor around automatic formatting characters or be responsible for deleting them.

With formatting on focusout or Enter, the user is allowed to type as expected without interference, and automatic formatting is only applied once they're done. Similar to dynamic formatting, the formatting characters shouldn't affect editing or typing and be purely presentational.

There's probably more to consider

Even with all this in mind, there are probably other UX wrinkles to smooth and enhancements to provide. Much of this is use case dependent, and all of it benefits from testing with a wide variety of users, especially with a variety of assistive technology and devices.

The depth of a single number input shows just how far design engineering can go. It's this level of thoughtfulness and refinement that makes this my favorite kind of work to do.

Aquileo | Tradeoffs with quality, scope, and deadlines

2025-04-02T00:00:00Z

Tradeoffs with quality, scope, and deadlines

Every project involves tradeoffs with quality, scope, and deadlines.

Tradeoffs happen whether you decide or want them to. Strategy is deciding which tradeoffs to make. The default mode for most teams is a lack of strategy with tradeoffs happening to them.

So, we have these 3 interdependent variables of quality, scope, and deadlines.

Teams typically operate in 1 of 2 ways.

1. Fixed deadline, fixed scope, variable quality

With a fixed deadline and fixed scope, the only variable that can give is quality. It goes down.

This is the damage of upfront design and hard deadlines. You've committed to a fixed scope before the build has even kicked off.

As a result, only quality can suffer. Either the current project has immediately worse quality from rushing to make the deadline, or long-term quality suffers as tech debt piles up and the team is burnt out from too much crunch and overwork.

2. Fixed scope, fixed quality, variable deadline

With a fixed scope and fixed quality, the only variable that can give is the deadline. It goes long.

This means that while we have good intentions of only shipping high quality work, we have no predictability of when we'll ship it.

We move slowly, work takes several times longer than expected, the team gets demoralized, and the product becomes stale and irrelevant.

This is the default mode of waterfall companies and is typical of things like government contractors where strict standards and the scope of the work are locked in from the beginning.

But, there's a third way we can operate: Fixed deadline, fixed quality, variable scope.

3. Fixed deadline, fixed quality, variable scope

With a fixed deadline and variable, the only variable that can give is the scope. It gets smaller.

Instead of doing worse work or taking longer than we like, we simply do less, but better.

This smaller amount of work is the most essential and captures the majority of the value. It maintains our quality standards, which respects our customers and protects our reputation. We can always come back and add more to it, but usually, it fully address the problem.

Often, this more focused is even better than the full scope would have been. We've forced ourselves to make tradeoffs, hone in on what's valuable, and cut anything that isn't.

With this approach, we're able to move quickly, have a consistent shipping cadence, produce high quality work we're proud of, and stay motivated and energized.

We now have reliable deadlines that mean something. We've capped the potential downsides of building the wrong thing or making the wrong bet. We've retained all future optionality because we haven't created maintenance or scaling issues.

And, we're now able to have a clear mind to ask what's next and begin the process over again.

Aquileo | Analog productivity

2024-11-18T00:00:00Z

Analog productivity

Lately I've been shifting my day-to-day productivity process to more physical and analog tools.

I still love a digital second brain for personal knowledge management, and it's still the best digital workplace I've experienced.

But, GitJournal, the app I used to sync and edit my second brain on my phone, has had some Git diffing issues for a while now. As a result, I haven't been able to access my second brain on my phone. This has really tanked my use of it, especially for task management.

Open to switching things up, I got a pack of Analog cards by Ugmonk in a recent order and was excited to try a different task management approach.

Physical task management

I've been a fan of Ugmonk for years now. In 2021, we partnered with them to provide the beautiful example product imagery for the Tailwind UI Ecommerce components I built.

After trying my first pack of Analog cards for a week, I really liked the thoughtful design, simplicity, and always-present nature of having my task list visible on my desk instead of tucked behind another window on my screen.

I felt very focused and productive, motivated by checking off each item in front of me. It's ridiculous how filling in an empty circle can be motivating, but I'll take it.

After this trial period, I decided to order the actual Analog starter pack, which comes with 3 refill packs and a walnut card stand. I also went for the matching walnut pen tray for the best pen ever, the uniball Roller 0.5mm. Fight me.

Walnut Analog card stand and matching pen tray.

True, I can make a task list on an index card and skip the walnut accessories. But there's value in having nice objects to look at throughout the work day, and to appreciate good design while crafting things in my own work. I spend at least half of my waking life in my home office, so it's important to me to enjoy my space and only have objects that bring me joy.

Hourglass pomodoro

As part of leaning in to physical productivity tools, I also purchased some hourglasses to do the Pomodoro Technique.

Since a Pomodoro interval is 25 minutes, I ordered 2 hourglasses by Hightide: a 30 minute hourglass and a 5 minute hourglass.

30 and 5 minute clear hourglasses with black sand.

At the start of each interval, I flip both hourglasses over.

The 5 minute hourglass is for my break, which I use to get water, walk around, do some stretches, or do some workout sets with the kettlebell, maces, and olympic rings I have in my office.

When the 5 minute hourglass is done, the remaining 25 minutes of the 30 minute hourglass is for work. When that hourglass is done, I repeat the interval.

I verified these hourglasses are accurate to within a few seconds, which is pretty impressive.

Erasable paper

My design process typically involves physical UI sketches and then immediately jumping into code to design the browser. I like to annotate these UI sketches with notes, questions, and other ideas to get most of my ideas and explorations out before switching to digital tools.

I've used these erasable sheets by Swipies for about 7 years now and they've helped up perfectly. The Staedtler fine point pens allow me to be detailed in my sketches. I'll then take a photo of the sheet to reference later, and erase it using some water.

Erasable paper sheets with dot grid and a fine point felt pen.

I also use these sheets around the house for taking measurements, sketching interior design ideas, and woodworking, so I keep them on a clipboard.

My analog productivity takeaways

This shift has created some nice benefits to my work. I used to do a lot of drawing and oil painting, so returning to more physical thinking engages more of my creative brain. It also adds some nice variety to my fully digital career.

It's worth it to invest in well-designed objects. They make my workspace look nicer, offer mini breaks from screen time, add a more tactile experience to my day, and give my eyes something more interesting to gaze at while thinking. I'm a minimalist, so whatever items I do own should add value to my life and be well made. And, as someone who does woodworking and used to do packaging design, it's nice to have thoughtfully made objects around as inspiration.

After using this setup for the past couple weeks, I'm excited to keep going along this path, and I'll provide updates with any iterations.

Aquileo | Is the best digital workplace just a bunch of Markdown files?

2024-09-02T00:00:00Z

Is the best digital workplace just a bunch of Markdown files?

For over a year, I've been working on a major project with a close collaborator. This project has all the complexities of a full product business, meaning we need to define and prioritize what we work on, document our standards, and capture our day-to-day thinking as we work.

There are endless tools that try to create the perfect digital workplace, with all-in-one tools such as Basecamp or Campsite, or communication-specific tools like Notion, Slack, Paper, etc.

After the past year, we've crafted the best digital workplace I've experienced. It has 3 simple properties:

A bunch of markdown files
Neatly organized in folders
Inside the codebase

This approach is absurd—and it works better than any other tool or remote team I've worked with.

Let's dig into how our folders and files are structured, the benefits of this approach, and the intentional tradeoffs it creates.

Second brain as the workplace

I've been a fan of building a second brain for over 2 years now, and it's transformed how I manage my personal and professional knowledge and productivity. I capture all my thinking, learning, and reference into a simple markdown file and folder structure that has scaled to several thousand notes.

A second brain is organized into top-level folders with the PARA method, which stands for "Projects, Areas, Resources, Archives". This approach organizes notes based on actionabilty: Projects are current efforts with a strict work-in-progress limit, Areas of responsibility are ongoing efforts with standards, Resources are reference not tied to a specific effort, and Archives store any past notes from these top-level folders.

Turns out, the PARA method is well-suited for a digital workplace. Companies have projects, areas (business functions, teams, practices, etc.), resources (documentation, reference, notes, etc.), and archives of past work.

So, we added a root-level _second-brain folder with the PARA structure inside our codebase. This centralized everything we do into a single, version controlled repository.

We also do Shape Up, which is our favorite way to decide what to work on and de-risk potential projects. When I learned about the concept of the Incubator from Fractal Productivity, I knew this was the perfect concept to house Shape Up within our second brain.

Here's a breakdown of our full second brain structure:

00-inbox
- Default home for capturing new notes without worrying about where to put them
  - Perform routine cleaning to keep the inbox tidy
- 00-tasks
  - Unplanned work (seek to keep this to a minimum)
  - Tasks not tied to active projects (day-to-day work)
- 01-improvements
  - A log of any potential improvement ideas, perfect for Daily 3S (more on this in the future)
- 02-scratchpad
  - An outlet for thinking notes and quick/initial ideas to help stay focused on current tasks
  - Informal and no commitment to potential projects or tasks
  - Can create dedicated files for company-wide, team-wide, or per-person use
01-projects
- Used for active projects
- Contains all notes related to active work
- Strict WIP limits (ideally 1 per team)
02-incubator
- Used for Shape up with framing, shaping, and betting stages
- Not a backlog! Potential projects are nothing more than ideas until we bet on them.
- 00-framing
  - Projects that need to be validated for business value and relevant timing
  - Archived if they don't move on to 01-shaping
- 01-shaping
  - Projects that have strategic value but need to be defined and de-risked
  - Archived if they don't move on to 02-betting
- 02-betting
  - Projects that are defined and de-risked but need to be committed to
  - Archived if they aren't bet on
  - Projects we bet on are promoted to 01-projects when they become active work
03-areas
- Areas of responsibility, ongoing efforts, and teams/departments
- Standard operating procedures by area or practice
04-resources
- Research
- Learning notes
- Documentation
- Reference
- Handbook
- Operations
05-archive
- 01-projects
  - Completed projects
- 02-incubator
  - 00-framing
  - 01-shaping
  - 02-betting
  - Projects that didn't make it through Shape Up
  - Helpful to know which stage they were archived
- 03-areas
  - Business functions or practices that are no longer relevant
- 04-resources
  - Resources that are outdated or no longer applicable

Benefits

The many benefits of this approach include simplicity, flexibility, cost, security, transparency, centralization, lightness, clarity, and calmness.

Simplicity

The second brain workplace is just markdown files and folders. Files load instantly and are easy to traverse, search, create, update, move, and delete. Markdown has a simple, readable syntax that is easy to learn. There's no custom engineering, infrastructure, or maintenance required.

With simple files and folders, there's no vendor lock-in. Your digital workplace isn't dependent on other companies surviving. There are no proprietary file formats, unexpected changes in features or functionality, or software rot to deal with.

Flexibility

The simplicity of the second brain structure makes it quite flexible and scalable. It's easy to organize and reorganize files and folders as the organization and work evolve.

For smaller teams, it's best to have the root-level 01-projects represent all projects across the organization, with a global work in progress limit. This helps with transparency and creates a more unified focus for the organization.

For larger teams, it's possible to organize projects by area (team or business function), while still setting work-in-progress (WIP) limits per area.

Because everything is just text in a file, it's easy to create new conventions and patterns (which we'll explore below) without having to depend on a vendor to add requested features.

The format of markdown files and folders offers a lot of individual flexibility, as well. Team members are free to use whatever text editor they like, which can be customized with different themes, shortcuts, extensions, snippets, and more. These customizations can be out of preference, need (accessibility), or both. This second brain digital workplace is adaptive instead of only offering whatever features and options a vendor decides to build.

Cost

This approach can be completely free. All the team needs is a open source text editor, Git, and a version control host such as GitHub or GitLab with free private repositories.

Security

Git with SSH credentials is very secure, especially with 2-factor authentication for the version control host. If this approach works for the software a business runs on, it should work well for the company's digital workplace.

Large companies might have an on-prem or self-hosted version control system, which would make this approach even more secure.

Contrast this with trusting another company to secure and preserve your team's internal communications, which might contain proprietary and sensitive information.

Transparency

Having all communications in a centralized, accessible format makes transparency much more attainable. Communications aren't siloed by varying tools or permissions, and team members can easily peruse information across the team.

If this sounds like a tradeoff, then you likely have a cultural issue of secrecy and distrust.

Centralization

This second brain centralizes all relevant information into a simple digital workplace, which increases access and reduces context switching. This helps eliminate waste by making it obvious where information lives (in one spot) and making information quicker to find.

For teams with a codebase, the second brain is even more powerful when it's embedded directly in the main repository. This creates a direct connection between the communication and thinking of a team with the product being built. It also helps achieve the lean principle of "The answer is where the question is asked" by putting all necessary information in the same place as the work being done.

Lightness, clarity, and calmness

This way of working creates ease and quiet in a team.

It's asynchronous, making fewer demands of individual's attention and time. There are no notifications, alerts, or pings. Everyone can access the information they need, reflect on ideas and proposals, and contribute their considered thoughts.

Tasks

At the most granular level of work, teams manage countless tasks for tracking day-to-day efforts.

With Markdown, it's easy to create task lists that can replicate many of the features of task software with simple text patterns:

Incomplete task: - [ ] Task title
Task with deadline: - [ ] yyyy-mm-dd | Task title
Task assigned to someone: - [ ] @assigneeName (individual or team) | Task title
Task with deadline and assignment: - [ ] yyyy-mm-dd | @assigneeName | Task title
In progress task - [/] Task title
Optional task ~ [ ] Task title

With these text patterns, it's easy to do searches in the second brain to find various types of tasks. These searches can be global or scoped to specific files and folders, which is helpful for excluding archived files. They can even be pinned in tools like VS Code for recurring searches.

Example searches include:

To do (- [ ])
In progress (- [/])
Complete (- [x])
Tasks with dates
Tasks by person or team (@ syntax)

Optional tasks don't appear in these searches by design, because they aren't necessary. But, it's easy to search for them: (~ [ ]).

My experience applying this approach

I've been using this approach for over a year now as I'm building a product with a close collaborator.

It's scaled well across several cycles and projects, many research efforts, countless tasks, and a steady stream of daily ideas, thoughts, and improvements.

Having the digital workplace in the same repo as the code is very natural and eliminates all overhead. You can spend your day in the same tool, reference information with ease, and don't have to manage multiple logins and notification feeds.

This structure also allows for very fluid pairing and contributions. When pairing on work, the driver can stay focused on the task, while the navigator can note future ideas, improvements, and considerations. By practicing the lean principle of "stop and fix", it's also easy to create just-in-time documentation and improve existing notes.

As a big fan of Shape Up, it's felt natural and productive to carry out the full shaping process in the root-level 02-incubator folder, promote active projects to 01-projects, and archive completed work in 05-archives.

For quick coordination and ephemeral communication, we just text each other. This only happens a couple times per week outside of scheduled pairing sessions, where the bulk our work and communication happen. We can easily upgrade this to a tool like Discord or Slack in the future, albeit with very limited use cases.

Tradeoffs

This approach has its tradeoffs, but they are minor. Some are also intentional advantages.

One piece of anticipated pushback is this approach requires everyone to learn Markdown and Git. I'd argue there's a learning curve to any tool, and these skills are much more widely useful and transferable than learning the quirks of a specific workspace tool that won't be around in 5 years or won't be used in a future role. Markdown is easy to learn within a session or two, and while Git can be quite complex, a second brain typically only requires adding files, committing them, and pushing/pulling. I wouldn't encourage using branches or other advanced version control approaches. This can also be a form of skill-leveling across a team, by giving non-developer team members some bridging skills. If the second brain is colocated in the main codebase, this also gives team members the ability to explore and learn how things are being built.

There isn't a way to make fancy content blocks or layouts, such as tables with filters, data plots, Gantt charts, etc. This is fine for me as I prefer lightweight, simple text over complex visuals, and the time invested in crafting the perfect Notion template or a color-coded multi-view database is largely waste.

There's no great way to handle images. We rarely need to include images, so our solution is to just put them in a folder colocated with a note. Text is lighter, more accessible, and editable, so images are often unnecessary.

Internal linking is clunky between notes, especially if relative paths change as files and folders are moved. Wiki links would be great, but would involve more complex tooling. Luckily, linking between notes hasn't been a frequent need.

There isn't a great solution for mobile access. GitJournal for Android is one example that works decently for a second brain, and there are likely equivalents for iOS. But it's probably healthier to not have the workplace accessible from a phone in the first place.

Same-document, real-time collaboration isn't possible. This is solvable by having a designated scribe during calls who is sharing their screen, similar to pairing. Collaboration in general is a solved problem, since Git resolves conflicts and companies can obviously develop massive codebases at scale using the same tools and practices.

As mentioned above, this approach is not well suited for quick coordination and ephemeral communication. That's better handled by a chat tool, and that chat tool's purpose is greatly clarified to only be used for a quick question or reminder. Everything else should live in the second brain.

Lastly, this approach doesn't allow private communication or private personal notes. Direct communication might be better handled by a chat tool, and anything beyond quick coordination should ideally be part of the second brain.

Personal notes can be handled by team members maintaining their own second brain for their role. This is actually how I came up with the idea of using a second brain at a team level, as I've created a second brain for each long-term client engagement and my current full-time role. A personal second brain for my role has been essential for making sense of the chaotic communications that occur across teams in many different workplace tools. Having all communications in a team-wide second brain would greatly reduce the need for personal notes.

It's also possible to create files and folders for specific teams and individuals if the information doesn't need to be private. For example, it might be useful for each team member to have their own scratchpad for in-the-moment thoughts or thinking notes.

Wrapping up

I'm confident there's value in this approach and the past year of using it for a major project only makes me more excited to keep going.

It's strange that this approach would be considered radical because of its simplicity. Most organizations believe they need tons of complexity, almost as evidence of sophistication, and never reflect on what's essential. Most organizations aren't aware of the waste caused by having several heavy, cumbersome, and expensive communication tools as their digital workplace. There is so much time, money, and effort over-invested in these tools that are really just glorified text documents. There's a lot of value in cutting away all the unnecessary and just managing a simple file and folder structure.

I'm interested in hearing your thoughts on this approach, especially if you try it for yourself or your team. Let me know what you think: hello@luhr.co

Aquileo | The next step in my career: joining Buffer as Senior Design Engineer

2024-04-09T00:00:00Z

The next step in my career: joining Buffer as Senior Design Engineer

Over 5 years ago, I created Build UX to provide free, high-quality educational content on building accessible and polished user experiences. And nearly 4 years ago, I started consulting full-time in the summer of 2020. Over these past few years, I've loved the flexibility, interesting problems, and scaled impact of being fully independent.

So, it may come as a surprise that I've chosen to return to full-time employment. But, I have an opportunity that I can't pass up with many of the same benefits I've enjoyed as an independent consultant.

Why I'm stepping away from full-time consulting

The opportunities to guide my clients through technical, process, and cultural transformations have made the past few years the highlight of my career, but running your own consulting business is not without its challenges.

Following the collapse of Silicon Valley Bank early last year, the tech industry was in a reactionary and panicked state. Nearly every consultant and educational content creator I know, including myself, experienced a significant drop in demand through much of last year.

While last year was rewarding in its own way as I explored my potential future product business, it was unpredictable and challenging financially. Luckily, demand started recovering last fall as confidence started returning to the industry, and I was returning back to normal levels of engagement.

At the same time demand started returning, I found the single opportunity that started calling me away from consulting: joining the team at Buffer.

Why I'm joining Buffer

I've followed Buffer for years through their continuous experiments with their way of working and passion for doing what's right. In past leadership positions, I used Buffer as a leading example in transparency with open salaries and equitable pay. In consulting, Buffer has served as a trusted point of reference that teams can and should question assumptions and continuously improve their culture, process, and product, with practices such as 4-day work weeks, embracing side projects, and building for the long-term.

Back in December, I was reading a post and was curious what roles they typically hire for. I saw an opening for a completely new design engineer role, which aligned with my whole career as both a designer and developer. Without hesitation, I decided on the spot to apply with the hope that I could join a team I've admired for years.

I'm not an impulsive person, especially when it comes to my career. But, I can be compelled to move fast and when good opportunities appear, and this was one of them.

Buffer's job openings can be quite competitive: a previous job posting in the same team had around 1,500 applicants just a few months prior. I wasn't even searching for a full-time role. But I knew I wanted to try.

Soon after, I was asked to start interviewing in January. I had several rounds of interviews from January to March, and each step in the process only strengthened my interest in joining. Everyone I spoke to, including the CEO, was incredibly transparent and kind, openly sharing their successes and struggles, their needs and ambitions, and their personal interests and projects.

Throughout the process, I experienced reassuring honesty and genuine support. When I was offered the role in early March, I accepted without hesitation.

What's next?

As a design engineer at Buffer, I bridge design and development and oversee technical strategy for Buffer's marketing website and blog, while also contributing to accessibility and their evolving design system. I also benefit from the cross-mentorship of a larger, senior team, which is something that's difficult to get from consulting.

Now that I'm 3 weeks into this role, I can confidently say that Buffer actually lives up to their values. I've observed people in all areas of the company act without ego, express sincere gratitude and optimism, be fully transparent to inform and empower others, and be open to any suggestions to continuously improve.

Like any long-standing business, Buffer has technical and process debt. But with such a trusting and supportive culture, I've been able to make significant dents in tech debt and propose different ways of working, especially between design and engineering.

Buffer not only supports, but encourages meaningful side projects. People openly share and celebrate everything from hobbies to content creation to even successful businesses outside of Buffer. And, with a 4-day work week, people are able to retain energy and curiosity for things outside of work that make them more fulfilled and productive in the long-term.

For me, this transition has been surprisingly easy. Nearly all of my time as a consultant has been with fully embedded, long-term engagements, so the schedule hasn't been too much of an adjustment. And, with the autonomy of my role, I've been able to start introducing practices such as Daily 3S (sweep, sort, standardize) and pairing that I would bring to my clients.

The 4-day work week and calm way of working has also left me with solid energy and inspiration to continue working on my own projects. I'm planning on reserving my Fridays for creating educational content and continuing to build the product that might become a business at some point.

After going through this change in my career, I feel relieved and grateful to be part of a team that's optimizing for the long-term with a people-first approach to work. And I look forward to the calm, stability, and balance it provides, so I can optimize for the long-term in my own life.

Aquileo | The origins of design engineering

2024-02-26T00:00:00Z

The origins of design engineering

My career for the past 10 years has always combined design and development. I've either been responsible for both design and coding in the same role, or acted as the bridging role between designers and engineers. For me, code is the most effective way to realize designs.

We've never settled on how to classify this work, as evidenced by all the evolving titles over time. Some of my past titles are Senior Web Designer, UX Lead, UX Developer, Lead Developer, etc. During this same time period, industry titles have evolved with Product Designer, UX Designer, Full-Stack Designer, UI Engineer, UX Engineer, etc.

Recently I've come across several posts on design engineering and noticed some convergence in new roles with the title of Design Engineer. The responsibilities of these roles aligns with the work I've done for my whole web career, so I was curious where the title came from.

2019

In January 2019, Chris Coyier wrote a landmark post, The Great Divide, that surveyed the industry and identified the gap between design and engineering. Chris refers to himself as a web craftsman, which I dig.

From what I've found, the earliest resources on design engineering were created by Natalya Shelburne in her fall 2019 Beyond Tellerrand talk, CSS at the intersection.

Some highlights of the talk:

Why tell designers to learn code when we can create tools that serve as bridges between mental models?

Hire people who are good at different things...Enable them to contribute their best way

Roles are arbitrary things we decided

Natalya's website is called Artist-Developer, which is such a great term to encapsulate the dual nature of this work.

2020

In 2020, Natalya Shelburne, Adekunle Oduye, Kim Williams, and Eddie Lou created the Design Engineer Handbook, published by Design Better Co.

Adelkunle Oduye uses the title UX Engineer. Kim Williams has led teams of product designers, UX designers, and UX researchers. And Eddie Lou had UI development and UI engineering roles before forming a design engineering team at Indeed. This is one of the earliest instances I've found of an actual design engineering team at a company.

In October of 2020, Natalya Shelburne discussed design engineering on episode 434 of Shop Talk Show. In this interview, Natalya discusses coming up with the term with Aarron Walter at Design Exchange in Sydney.

2021

In February 2021, Brad Frost coined the term "front-of-the-front-end web development", building on the idea of a "frontend designer" that he wrote about in 2016. Brad has unwaveringly used the title of web designer over the years, which I respect.

A day later, Trys Mudford published a series of blog posts on design engineering:

These posts were followed by a Tweet that summarizes design engineering perfectly:

What I *love* about the name "Design Engineer", is that it's entirely focused on the handshake between those two other roles.

There's no mention of UI, CSS, front-end, design systems, documentation, prototyping, tooling or any 'hard' skills that could be used in the role itself.

@trysmudford

In true design engineering fashion, Trys is a cofounder with James Gilyead of Utopia, which generates fluid type and spacing scales.

James Gilyead is a product designer at Clearleft, the design consultancy co-founded by Jeremy Keith.

Jeremy Keith wrote a post on design engineering in response to Trys' posts soon after. Jeremy Keith describes his work as a web developer, or even more directly, as "making websites".

In September 2021, Jeremy Keith published an episode of the Clearleft podcast on design engineering that featured Tobias Ahlin, Adekunle Oduye, Jon Aizlewood, and Trys Mudford.

Tobias is a design engineer at GitHub and Jon Aizlewood is a design leader. Tobias is another instance of design engineer in a formal role.

2022

In May 2022, Jim Nielsen wrote a post on The Case for Design Engineers. This post links to Jeremy Keith's 2021 post and Jim's post on Declarative Design from April 2022.

The term declarative design really captures the emerging design and engineering opportunities of modern CSS. It builds on the concept of intrinsic web design from Jen Simmons, Andy Bell and Heydon Pickering's work with Every Layout, and Trys Mudford and James Gilyead's work with Utopia.

At this point, design engineering is building on a lot of the most exciting work in the space.

2023

I haven't found as many resources in design engineering that were published in 2023, but I started noticing actual job listings with Design Engineer as the title.

After the industry panic in 2023 with mass layoffs, it's interesting that as companies being hiring again, they are identifying this new role as one to hire for.

2024

When I'm interested in how companies operate, I often poke around their blogs and job listings to get a pulse on their team and direction. We're just a couple months into 2024, and I've already noticed a significant increase in job listings with the title of Design Engineer.

This same month, Jim Nielsen wrote a follow up to his 2022 post: The Case for Design Engineers, Pt. II.

A single quote illustrates the strength of this discipline:

design work with code

The future

It's interesting to trace how early ideas around our roles can spread and eventually shape the titles companies hire for.

2 years after Natalya's Beyond Tellerrand talk, there's an initial surge in content around design engineering, and 2 to 3 years later, noticeably more jobs are using the term.

With CSS continuing to rapidly evolve, we have so many new patterns to explore and refine. Container queries, CSS subgrid, CSS layers, and more are going to push our design opportunities further. It's crucial that we combine design and engineering, or at least eliminate handoff in favor of collaborating, to make the most of these capabilities.

Over the past 10 years, we've had so many different titles, but one thing remains constant: the essential work of bridging design and development. It's uncertain whether design engineering will last as a title, but any momentum that further legitimizes this valuable role is worth supporting.

If I've missed any important people, resources, or milestones in this history, let me know.

If you or your team need help with design engineering and establishing more effective processes, let's talk: hello@luhr.co

Aquileo | Test-driven development as prompt engineering

2024-02-07T00:00:00Z

Test-driven development as prompt engineering

As AI code generator tools gain adoption, Test-Driven Development (TDD) becomes even more essential and a key differentiator for developers.

As Kent Beck said: "90% of my skills just dropped to $0. The leverage for the remaining 10% went up 1000x." I don't think we're anywhere close to 90% currently, but it's likely we'll get there. TDD is going to be a large portion of that remaining 10% that'll become the majority of meaningful work we do as programmers.

I briefly trialed GitHub Copilot in the summer of 2023. While it produced interesting results, I haven't integrated into my daily work. I'll be revisiting this decision periodically. Since then, I've built further experiences working with clients who use these tools and observing videos and posts from the community in general.

Throughout this period, I've observed people being frustrated with the code output of tools like Copilot and ChatGPT, and there are early signs that AI code generators might be lowering code quality at scale.

While these tools can definitely vary in output, I've learned their quality is highly dependent on prompt engineering.

With AI code generator tools like GitHub Copilot, most people leave code comments, wait for generated responses, and are underwhelmed with their choices.

If you use these tools, you'll get the best results by instead following a test-driven development (TDD) workflow.

With TDD, you follow a loop of Red, Green, Refactor: you first write a failing test (Red), then just enough code to make that test pass (Green), then safely improve your code while ensuring it still works (Refactor).

Typically, I only work on one test at a time, but a tradeoff with copilot tools is they benefit from you writing every test you can think of in advance. This helps guide the generated code output address all expected scenarios at once. Otherwise, you'd have to resort to prompting the copilot to iterate the code for each new scenario, which currently doesn't seem as successful.

My preferred copilot workflow is the following:

Write all tests you can think of for a function (Red)
Only use copilot tools for the implementation stage of writing just enough code to make the test pass (Green)
Improve the generated code to meet coding standards and add any other tests that come to mind (Refactor)

This is similar to ping-pong pairing (also known as strict pairing), where one pairing partner writes a test, the other partner writes the code, and then the pair trade roles. Except with copilot tools, you should always be the one writing the tests. It's fine to prompt the tool for additional test ideas, but make sure you are the one setting expectations for how the code should work.

Tests are essential to ensure the code does what you want
Tests are essential to refactoring
- If the copilot output passes the tests, that's a good stopping point
- If you want to refactor the code, you can safely do so with test coverage
It's a great learning mechanism
- I can often state the objective of code, with the function name, inputs, and outputs I'd like to have, but I might deliberate the how too much

It's important for humans to write tests for the behavior that is interesting to our work, and "human judgement is always part of TDD."

Issues with common copilot workflows

The most common workflow I've observed with copilot tools is developers writing code comments that describe the implementation they want. The copilot generates a function, and the developer may make some small tweaks. At best, the developer might then prompt the copilot to generate some tests for the new function.

The first issue of this workflow is waste. Prompting code comments can be quite verbose and require multiple attempts. Plus, these code comments have to be deleted after the code is generated or they add noise to the codebase. Additionally, there may be rework needed to get the code in the desired shape and functionality.

The second and more important issue is bugs with false positives. Even without copilot tools, writing tests after (Test-After Development, or TAD) introduces the risk of only demonstrating what the code currently does. Even if all the tests pass, that means the tests simply describe the current functionality, but they don't prove that the code under test has the desired functionality. By writing tests first, we ensure the generated code meets our needs and accounts for all the scenarios or potential errors that matter to us.

Benefits of TDD as prompt engineering

TDD makes quality suggestions much more likely.

Writing tests first sets expectations for the generated code. It defines:

What the function is called
What it should do (at least for the current case)
What arguments the function accepts (its signature)
What it returns

This gives much more effective guidance for AI as your pairing partner to generate useful code, making it more likely that the generated code will handle the implementation successfully.

After writing tests, it's helpful to evaluate the generated suggestions (using the Ctrl/Cmd + Enter command in VSCode, for example) and pick the one you feel is most likely to pass the tests. This is a good opportunity to make a hypothesis/bet and learn from the results.

Because TDD encourages good design and single responsibility principle for testable functions, copilot tools are more likely to generate more focused, cleaner functions.

Tips

Code comment prompts as code smells

If you have to resort to scaffold code or comments for prompts, you're not writing tests first, probably taking too big a step, doing more than one thing, and working at too high a level of abstraction.

Instead, write tests for each operation, which will prompt the generated code to first create more testable helper functions that are largely one liners.

Have a pair programming mindset

Working with AI is like being the navigator in pair programming. I found the constant code suggestions to be quite distracting at first, but when I started thinking of it as another form of pairing, I reframed the suggestions as immediate feedback about my role as navigator and using tests as prompts.

Speed and scale are dangerous priorities

AI code generator tools are an accelerator, but accelerating isn't always desirable. Going faster doesn't mean anything if it's in the wrong direction. Going in the right direction, then going faster, is a true advantage.

Speed and scale in isolation create waste, not value. In the world of lean manufacturing, the ranked criteria for any improvement is:

Safer
Better quality
Simpler
Faster

The post "Safety, Accuracy, Efficiency, Then Scale" offers a related perspective focused on product teams.

My experience working with TDD, with or without AI code generators, is that it results in much, much greater speed and scalability over time. This is thanks to fewer bugs, less manual debugging, better documented/simpler code, and improved system design.

So, if copilot tools are appealing for their speed gains, the best way to leverage these gains is by incorporating TDD.

TDD is even more important as AI code generators gain adoption

As more and more teams start using AI code generators to churn out variable code quality, following Test-Driven Development will be a real competitive advantage.

In programming, typing isn't the bottleneck. Thinking is. Thinking about the tests ("what" the code should do) is far more important than thinking about the implementation code ("how" the code should do it). Without tests, we're handing off too much responsibility for copilot tools to determine both "what" and "how".

Prompt engineering is shaping, and TDD is prompt engineering. Without tests, we're not actually capturing or asserting our thinking for what generated code should do. We're just taking suggestions as our code quality, long-term productivity, and maintainability suffer at scale.

If you or your team need help implementing test-driven development and want to achieve meaningful speed and scale, let's talk: hello@luhr.co

Aquileo | Build-free type annotations with JSDoc and TypeScript

2024-01-25T00:00:00Z

Build-free type annotations with JSDoc and TypeScript

I've used TypeScript in various client projects, but sometimes got bogged down with migrating to .ts files and the tooling. After Svelte switched to using JSDoc with TypeScript in the spring of last year, it caught my attention and motivated me to try it out in my own projects.

My solo projects are entirely in vanilla JS. I like the simplicity, direct learning with exposure to browser APIs and web standards, and adaptability it gives me so I can help clients in various frameworks with better fundamental skills.

One of my favorite benefits of working this way is a build-free setup with no production dependencies and normal .js files. As a result, the build setup and file extension for TypeScript have been a deal breaker for my personal work. If your project already has a build step, then just using TypeScript can be great. But in my work, using JSDoc with TypeScript unlocked all the value of type annotations without the unwanted overhead.

Using JSDoc

On it's own, JSDoc is a documentation generator for JavaScript that uses comments to describe your code with various tags that use the @ syntax.

The tags we're most interested in for type annotations are @type, @typedef, @property, @params, and @returns.

For example, when creating a new element and assigning it to a variable, we can document the @type as HTMLElement:

/** @type {HTMLElement} */
const headingElement = document.createElement("h1");

Or, we can document a function's signature with its parameter and return types using the @param and @returns tags:

/**
 * @param {Node} node
 * @returns {String}
 */
function getNodeName(node) {
	return node.nodeName.toLowerCase();
}

Occasionally, it's necessary to cast a type so it respects a function's signature and expected types, such as specifying an Event type as a KeyboardEvent. This can be done with the inline comment syntax, @type tag, and wrapping the expression you want to cast in parentheses:

addEventListener("keydown", (event) => {
	handleKeydown(/** @type {KeyboardEvent} */ (event));
});

The last thing I commonly do is create a custom type definition for objects that are used between functions. This uses the @typedef and @property tags to document the structure of an object. Here's an example of creating a custom type for menu option objects that contain properties for a display name, action, and keyboard shortcut:

/**
 * @typedef {Object} Option
 * @property {String} displayName
 * @property {String} action
 * @property {String} [shortcut=""]
 */

This example also demonstrates the optional syntax using square brackets and an optional default value with the equals sign.

With this type definition, we can use this custom type elsewhere in our annotations:

/**
 * @param {Option} option
 * ...
 */

The main pushback I find with JSDoc that leads to "Just use TypeScript!" responses is the syntax is too verbose. I personally don't mind the syntax. It's simple, readable, and with snippets takes little effort to author.

Most JSDoc examples include a description in the first line of the comment, but these add little value if you have well named, readable code. In fact, I treat descriptions much like code comments in general: an anti-pattern that indicates there are code quality issues. There are rare exceptions, such as explaining why something obscure is needed due to a browser bug, but my standard is to omit descriptions.

VSCode has strong support for JSDoc, including default snippets for both the multi-line and single line comments, which start with a forward slash and two asterisks: /**. You can expand multi-line comments with the Enter key, and VSCode will do a decent job of filling out the parameter and return types for you. You can expand single-line comments with the Tab key, but VSCode can't infer the tags or types in this case.

As a standalone tool, JSDoc provides a lot of value with standardized documentation throughout a codebase. However, it's just static documentation and doesn't provide any feedback while coding. For that, we'll add TypeScript into the mix for continuous type checking.

Using JSDoc with TypeScript

The first thing we need to do to leverage TypeScript is install it as a dev dependency:

npm i typescript -D

Next, we need a configuration file, such as jsconfig.json, with our desired settings:

{
	"compilerOptions": {
		"allowJs": true,
		"checkJs": true,
		"strict": true,
		"noEmit": true
	},
	"include": ["src"]
}

With TypeScript set up, it'll immediately provide syntax highlighting for any type issues. If you don't already have type annotations, you'll find red squiggles throughout your codebase. If you have existing type annotations that are inaccurate or function calls that aren't respecting the proper types, these will be surfaced as well.

This continuously reinforces standards to annotate your code, helps prevent accidental type coercion, and makes your code more resilient by accounting for edge cases from unexpected types.

These edge cases often go completely unaccounted for and create bugs that are hard to track down or replicate. Test-Driven Development (TDD) helps reduce these bugs, but these types of tests are lower value, tedious to write, and difficult to exhaustively predict for every function and variable.

How I use tests and type annotations together

As an example, let's enforce proper types in a getNodeName function:

function getNodeName(node) {
	return node.nodeName.toLowerCase();
}

With tests, we should assert the function throws an error if the type of node passed into the function is not Node. We should also test that the returned value is a string:

describe("getNodeName", () => {
	it("throws an error if the provided node is not a type of Node") {
		expect(() => {
			getNodeName("string");
		}).to.throw(Error, "node has incorrect type of [object String]");
	}

	it("returns the node name as a string") {
		expect(() => {
			const testDivElement = document.createElement("div");
			const returnValue = getNodeName(testDivElement);

			expect(typeof returnValue).to.equal("string");
		})
	}
});

To make these tests pass, we'll need to improve our function:

function getNodeName(node) {
	if (!node.nodeName) {
		throw new Error(
			`node has incorrect type of ${Object.prototype.toString.call(
				node
			)}`
		);
	}

	return node.nodeName.toLowerCase();
}

I can be persuaded that even with type checking, these tests are valuable. But I write tests to get continuous feedback about the code I'm writing. JSDoc with TypeScript provide that feedback, so I'm personally comfortable skipping these types of tests in my own projects. This is a decision I might revisit in the future.

So instead, or in addition to these tests, we can add type annotations to our function:

/**
 * @param {Node} node
 * @returns {String}
 */
function getNodeName(node) {
	if (!node.nodeName) {
		throw new Error(
			`Cannot get node name of "${node}" with incorrect type of ${Object.prototype.toString.call(
				node
			)}`
		);
	}

	return node.nodeName.toLowerCase();
}

To finish our function, it's still important to assert our function guards against null or undefined values. Let's write a test for that:

describe("getNodeName", () => {
	it("throws an error if no node is provided") {
		expect(() => {
			getNodeName();
		}).to.throw(Error, "node is undefined");
	}

	/* ... */
});

And we add the guard to our function:

/**
 * @param {Node} node
 * @returns {String}
 */
function getNodeName(node) {
	if (!node) {
		throw new Error("node is undefined")
	}

	/* ... */
}

A helpful snippet for type guards

One of the more common ways TypeScript makes code more resilient is in preventing null or undefined values from being operated on in subsequent steps.

I typically handle this with if statements that act as type guards. Here's an example of two type guards to prevent null and undefined values from causing errors later in the function:

/**
 * @returns {String}
 */
function getMenuActiveDescendantId() {
	/** @type {HTMLElement|null} */
	const docMenu = document.querySelector("#menu");
	if (!docMenu) {
		throw new Error("docMenu is null");
	}

	/** @type {String|undefined} */
	const activeDescendantId = docMenu.getAttribute("aria-activedescendant");
	if (!activeDescendantId) {
		throw new Error("activeDescendantId is undefined);
	}

	return activeDescendantId;
}

To make repeatedly typing this easier, I have a simple VSCode snippet that I invoke with nil followed by the Tab key:

"Throw error if null": {
	"prefix": "nil",
	"body": ["if (!$1) {", "  throw new Error(\"$1 is $2\");", "}"]
}

Wrapping up

I've been using JSDoc with TypeScript for months now and feel it's the perfect balance for my personal work. The nice thing is these skills are transferable to using TypeScript directly by simply adapting the syntax, making my transition to client work seamless.

I'm really excited for the native type annotations proposal which is currently Stage 1. I hope we end up with a nice syntax similar to the optional types I use in Python or in GDScript (a Python-like language used in the Godot open source video game engine).

If you implement JSDoc with TypeScript, be sure to reference the JSDoc documentation and especially the TypeScript JSDoc reference, which I find even more useful.

Aquileo | Vision Pro, rabbit r1, LAMs, and accessibility

2024-01-19T00:00:00Z

Vision Pro, rabbit r1, LAMs, and accessibility

Today Apple released a video guided tour of the Vision Pro which gave a larger preview of the spatial user interfaces and how people will interact with them.

A little over a week ago, rabbit announced r1, a "personalized operating system" and companion device that primarily uses voice controls.

Both of these devices are interesting from an accessibility perspective. On one hand, they could provide new opportunities for people with limited mobility. On the other, the way they display UIs and handle user interactions makes me concerned that they will encourage bad practices that harm accessibility over time.

Concerns with spatial computing and the Apple Vision Pro

Back in June, I privately noted accessibility concerns with the initial announcement of the Apple Vision Pro and the Meet Safari for spatial computing video.

With today's video guided tour, I noticed the same issues and wanted to further detail them.

Text color contrast ratio

Like many Apple user interfaces, the text color contrast ratio is very low in menus, titles, and overlay text.

In the guided tour, there's white title text on top of the image grid with no defensive design considerations for how the text will appear on top of photos with bright content. As a result, the example text in the guided tour has a failing contrast ratio of 1.47:1. The lowest possible ratio is 1:1 with two identical colors, so this is a substantial readability issue. It needs to be at least 4.5:1 to meet the WCAG 2.1 AA standard.

The white overlay text on the image grid has 1.47:1 contrast.

For UI elements with a background, the frosted glass effect of a semi-transparent background with background blur similarly compromises on contrast. Even for buttons with more opaque backgrounds, the contrast ratio I measured was only around 2.16:1.

Native app UIs like Mail and Safari have similar issues. The highest contrast ratio I measured was 4.18:1, which only meets the AA standard for large text. All other instances of text had failing color contrast ratios.

The Mail app in Apple Vision Pro has insufficient color contrast across the UI.

"Cursor" hover indicators

The Apple Vision Pro uses eye tracking to determine hover on interactive elements, and hand/finger gestures to determine click, drag, and swipe interactions.

When an interactive element has hover from the user's gaze, it's indicated with a very, very subtle change in brightness, sometimes paired with a similarly subtle scaling. These changes are so slight that even though I have perfect vision with contact lenses, I have a hard time telling the difference.

When the user looks at different photos in the photo app, the brightness difference between hover and default states is almost imperceptible as it moves between photos.

The before and after comparison of hover moving from one image to another is almost imperceptible.

This issue carries over to interacting with the web. In the June WWDC video demonstrating Safari for spatial computing, the hover indicator for links is incredibly difficult to see, with a contrast ratio of 1.09:1.

On a page will multiple card links, the hover indicator on the center link has incredibly low color contrast.

In the home view, app icons receive the same subtle increase in brightness and a slight scaling on hover.

Hover on app icons in the home view are also very difficult to differentiate.

In menus, the indicator is more noticeable, but it unfortunately matches the active/selected state.

Menu items share hover and selected state styling.

There's an argument that because hover is always where the user is currently looking, there's no ambiguity about where hover is, so it's preferable that it's subtle to not interfere with elements that users are looking at.

While this is true for interactive elements, the hover indicator is so subtle that it's very difficult to determine what elements are actually interactive. This is a particularly bad issue for the web, where each website has unique design, and determining what is or isn't a link through vision alone is nearly impossible due to the prevalence of ambiguous UI design.

Interactive regions in Safari for spatial computing

Safari for spatial computing maps pinch and pointer finger gestures to touch events with a coarse pointer and no hover. This helps clarify why vision tracking is essentially a cursor that hovers elements instead of focusing them.

Indirect pinch gestures correspond to pointerdown, pointermove, and pointerup touch events.

Safari for spatial computing has clear criteria for determining which elements are interactive and should provide the (very subtle) hover indicator when the user looks at them:

Buttons, links, and menus
Elements with the equivalent ARIA roles
Input fields and form elements
Elements with CSS cursor: pointer;

The first and third criteria are sensible, as semantic HTML should determine interactivity. I'm not sure what they mean by "menus" separately from "Elements with the equivalent ARIA roles", as we have no native menu elements in HTML.

I'm concerned with "Elements with the equivalent ARIA roles" that aren't buttons, links, or input fields, as well as "Elements with CSS cursor: pointer;.

Both these criteria enable interaction for elements that may not actually be accessible for keyboard and assistive technology users. The presence of an ARIA role on an element has no guarantee that it will properly announce its function or even handle mouse and keyboard click events. The same goes for using cursor: pointer;, which is completely presentational.

Developers can opt out of these hover indicators with pointer-events: none;, which does affect interactivity and feels asymmetric. The hover indicators are shaped with border-radius, which matches how outline now behaves.

This criteria fully supports a <div> with a click event listener, which is worrying.

I understand that Apple wants Safari for spatial computing to be as resilient as possible with the unpredictable web, but supporting bad practices can only encourage lacking accessibility. Developers are already prone to use "it works for me" as an excuse, and now an incredibly expensive device will only reinforce that flawed logic further.

This isn't specific to spatial computing, but the code used in the June WWDC video demo shows other bad practices, such as wrapping <li> with <a> to change the appearance of the hover indicator, and referring to each link as a "button". Here's some of the code for the example navigation:

<nav id="sidebar">
	<ul>
		<a href="home.html"><li>home</li></a>
		<a href="index.html" class="selected"><li>teas</li></a>
		<!-- ... -->
	</ul>
</nav>

First off, anything but <li> as a direct child of <ul>/<ol> isn't valid HTML. Second, there's no need to wrap the list items in <a> elements to change the visual appearance of a hover indicator. Simply size and style the link as desired and it'll automatically have a matching size and border radius on hover. Lastly, as a real nitpick, don't hard-code text casing in HTML to achieve visual design. Use the text-transform property.

I point these indirectly related issues out because this is supposed to be an instructional video for a developer conference on how to properly build websites for spatial computing. Having such fundamental mistakes from such a large authority as Apple should be concerning.

What you should do to provide a universal experience

Despite Safari for spatial computing accommodating fake interactive elements that simply have ARIA roles and cursor: pointer;, you should still always stick with semantic interactive elements, such as <a>, <button>, <detail>/<summary>, <input>, <select>, and <textarea>. Valid, semantic HTML remains crucial to accessibility.

To properly support all users, we need to provide accessible focus indicators (with outline) for keyboard and assistive technology users, hover for mouse users with the :hover pseudo selector, and hover indicators with cursor: pointer; for Safari for spatial computing users.

Luckily, all of these indicators inherit border-radius, including outline in recent browser versions.

Interestingly, using cursor: pointer; on interactive elements such as buttons and input fields has always been a source of debate. Some argue that adding it is inconsistent with native apps that have a cursor: default; appearance when hovering interactive elements. Since Apple is now encouraging/requiring cursor: pointer; for all interactive elements, I guess this is a sensible default for all buttons, links, and input fields.

Lastly, sufficient tap targets (44 by 44 pixels) are still universally helpful to accommodate interaction in all forms.

And now, let's talk about rabbit r1 and LAMs

A little over a week ago, a new company called rabbit announced r1, a companion device they claim allows users to accomplish complex tasks on the web by speaking naturally.

The rabbit r1 device, designed by Teenage Engineering.

The rabbit r1 announcement video discusses a specific type of AI called LAMs, or Large Action Models, which they've trained to accomplish tasks based on language input using user interfaces.

From my understanding, they've trained models to visually parse UIs to identify interactive elements and carry out actions. The example images from this model have red borders around every text and interactive element, such as (icon) buttons, links, and other controls.

rabbit LAMs visually identify text and interactive elements with red borders in both native app and website UIs.

It's unclear what goes into this identification. My guess is it's purely visual, as it spans native apps and websites, making it difficult to consider the underlying code. But, it would be possible to also parse native code and HTML to better parse UI elements.

Similar to Vision Pro, an over-reliance on visual parsing might make for a more resilient and adaptive tool for interacting with the unpredictable web, but accommodation also allows for us to let our accessibility standards slip further.

If devices like r1 become successful and prevalent, then companies might optimizing for visual presentation over accessibility even more than we do now. This could create further gaps in accessibility and strengthen the confusion between visual design and semantics.

The announcement video had several magic edits when demonstrating the device actually carrying out a task, so it's still completely unproven.

If it does actually work, then it could be an interesting new opportunity for users with disabilities, with LAMs having potential for enhancing assistive technology.

Nonetheless, this device and the underlying technology will need to prove itself valuable and reliable before I put any weight into the claims or get excited about future possibilities.

Can we have a unified model of understanding UIs?

We these emerging vision-based technologies, I wish we could lean more heavily on proper, semantic code and the accessibility tree to determine, well, semantics and interaction. Finding <div> elements with click handlers is easier than finding correct heading levels, and I'm worried this is only going to get worse.

Accessibility and valid HTML are shockingly bad across the majority of websites. While this emerging wave of devices might open up access by adapting to inaccessible code with lacking semantics, they might also further encourage teams to ignore accessibility, prioritize visual presentation over everything, and buy into the delusion that if it works for me, it works for everyone.

Aquileo | 2023 year in review

2023-12-28T00:00:00Z

2023 year in review

2023 was a year of challenges, deep learning, experimentation, patience, and self-reliance.

Career

My work this year had a very different balance compared to previous years. Due to the economy, I invested about 75% of my time on personal projects and 25% on client work.

Consulting

This year was a rough one for consulting due to the collapse of Silicon Valley Bank in March that sent ripples of panic throughout our industry. Demand for client work evaporated as companies of all sizes reacted with fear of a looming wider collapse. As many people were affected by layoffs, I felt fortunate to have my own business, even if revenue took a substantial hit.

So, faced with fewer prospects, I invested my time in creating educational content, refining my way of working, going deep on interesting problems, and exploring a new product I'd like to launch in the future.

I've noticed confidence and momentum in the industry are picking up again lately, so demand for consulting is returning to normal. I've already started booking out 2024, with the spring filling up quick. If you or your team need help with accessible design and development, test-driven development, Shape Up, or process improvements, feel free to reach out: hello@luhr.co

Educational content

I started the year off with recording a course called Accessibility-first design for LinkedIn Learning. It was a great experience to record onsite at the LinkedIn Learning offices in Santa Barbara, California, and enjoy the warm January weather as an escape from the snow.

The script writing process for the course got me in a solid writing habit and the video format pushed me to be clearer and more concise in my teaching. Both of these experiences have continued to improve my educational content.

The course launched in April and now has over 12,000 students with a 4.9/5 rating. I'm happy with how the course turned out and glad so many people want to create more accessible design for everyone. A goal of my career is making accessibility-first the default way to build great products, so this was a solid step in that direction.

Now that I've created a formal course, I'm open to making more courses in the future. I've long considered doing this independently, which I might explore again at some point, but creating a course for Frontend Masters on a topic such as test-driven accessibility would be a fantastic fit.

Outside of course content, I blogged fairly consistently this year with 12 posts. I wrote a series on my custom second brain setup, which continues to be one of most valuable investments in my career and personal life. This year, I highlighted over 1,200 articles on design, development, and accessibility, and my second brain setup scaled perfectly for capturing those highlights and referencing them easily when working or creating new content.

I also wrote the first post in what will likely become a series on accessibility with All about accessible headings. I'd like to write posts in this series about accessible links, buttons, landmark regions, etc. that cover all the considerations of foundational accessibility.

I have dozens and dozens of post ideas, so I expect to keep the blogging pace going, if not accelerate it.

In addition to blog content, I picked my Build UX YouTube channel back up with 3 new videos towards the end of the year. I found I really enjoyed writing a post, then using that post as a rough outline for a video, and then publishing them together as complimentary resources. With so many blog post ideas kicking around, I hope to get a rhythm of videos out alongside new posts.

To wrap up educational content for the year, I wrote an article for the 2023 HTMHell Advent Calendar called Test-driven HTML and accessibility. This article teaches the approach to testing that I've developed throughout this year and transformed how I work. This topic is something I plan on expanding a ton in 2024, as I'm confident it will provide a lot of value for improving and protecting accessibility.

Learning

As client work was lighter than usual, I was able to dedicate most of my time to self-directed learning and building.

The bulk of my learning was with test-driven development (TDD), which I was able to incorporate fully in both my personal and client work.

TDD has been the most valuable practice of my development career. It gives so much clarity, confidence, quality, and resiliency to coding. It eliminates nearly 100% of the waste with manual debugging and has made me a substantially better developer. It's also been an incredibly powerful learning tool, even as I've dived into unfamiliar codebases, libraries, problems, and languages.

In April, I attended a small workshop from James Shore on Nullables, which is his technique for testing production code without hitting external systems. This approach eliminates the need for integration tests and mocks, which are slow and unreliable. Instead, you can turn off communication with the outside world and unit test functionality throughout the codebase.

The workshop was a bit of a stretch for my skills at the time. But a few months later, my main client was struggling with a problem that was the perfect candidate for this approach. With nullables in place, we were able to confidently unit test all of the functionality we were working on with tests that ran predictably and instantaneously. We even replaced existing clunky integration tests and reduced the test suite run time from several minutes down to a few hundred milliseconds.

The last frontier for testing that I wanted to solve was testing HTML and accessibility. James Shore kindly shared his past experiences using tools like Karma and Test'em, but these projects were now aging and I couldn't get them running in my projects.

Luckily, right as Karma was officially deprecated, I came across Web Test Runner, which is a tool that runs JavaScript tests in the browser instead of in Node. This makes it possible to run tests in all the major browser engines (Chromium, WebKit, and Firefox) simultaneously in the background with every change. Most importantly, it means that tests have access to the real DOM and actual user interaction events. I cover this in depth in my Test-driven HTML and accessibility article, but in short I've been able to unit test everything I build, from logic, to integrations, to rendered DOM, to accessibility, all with a lightweight setup that has scaled perfectly to many hundreds of tests running at once.

Product

The reason why I was writing many hundreds of tests is I started exploring a product that I'd like to sell in the future. I'm not ready to discuss what the product is just yet, but I am excited for the value, quality, accessibility, and efficiency it'll bring to designers and developers alike.

This project was the central driver of my learning and will continue to inspire relevant educational content to share what I've found.

It quickly became the largest codebase I've built on my own and was a good proving ground for the level of polish I know is possible if teams prioritize the right things. While I've needed to continuously refine the codebase as it scales, having tests in place made this a calm and steady practice.

This experience was really clarifying for my career. I now am inspired to continue building this product on the side, and if I can one day focus on it full-time, I'd be thrilled and terrified to take on that challenge. While I could make a bet on it full-time, I'd rather come at it from a place of security and patience to do what's best in the long term.

Working rhythm

As I worked on my own projects throughout the year, I organically discovered and refined what is now my ideal working rhythm.

At a higher level, I used each month as a Shape Up cycle, with the first 3 weeks focused on product work, and the last week acting as a cooldown focused on creating content and framing/shaping work for the next month.

This larger rhythm feels like the perfect balance of making meaningful progress on features and learning that is substantial and fresh enough to share in a blog post and video. While I didn't directly tie each month's post and video to what I was working on, I'd like to do this in the future. When I'm ready to announce the product I'm working on, I'll still use that last week for creating educational content, but it can use the product as a concrete example if needed. I feel providing value routinely will be more effective than any actual marketing.

At a daily level, I found similar balance. My ideal workday is now the following:

8:00 AM to 9:30 AM: deep work
9:30 AM to 10:30 AM: break/shallow work
10:30 to 12:00 PM: deep work
12:00 PM to 1:00 PM: lunch
1:00 PM to 2:00 PM: deep work
2:00 PM onward: go live my life

This schedule guarantees 4 hours of deep work, which is far above what most full-time roles can achieve. I find 90 minutes is the longest deep work block I can sustain without diminishing returns, and having hour-long breaks between blocks keeps me fresh, gives an outlet for less important work, and lets my brain subconsciously process important problems.

While I designed and refined this schedule for my solo product work, I found it works perfectly with clients as well. Each deep work block is perfect for pairing/mobbing sessions, and the 8:00 AM to 2:00 PM PST schedule has a lot of overlap with my clients in the EST timezone 3 hours ahead.

Personal

I love mountain biking, and this year I finally got into the habit of routinely volunteering to do trail work in our local trail system. It was a ton of fun learning about trail design, which has many parallels to software design, particularly when it comes to accessibility in the form of adaptive riding. It was also super rewarding to make major improvements to trails I love, and then immediately enjoy the improvements by riding as a group.

I made several new friends as part of this group and now have great people to ride with. We even did a mountain bike camping trip in the summer to check out other trail systems in the Alsea and Black Rock areas of Oregon which was one of the highlights of my year.

Outside of mountain biking, I started making wood fire pizzas routinely and was able to hone my Neapolitan dough skills. I had a ton of fun experimenting with different toppings, learning how to shape and stretch dough quickly, and growing ingredients in our garden. Everything always turns out great, and worst case, you just make a calzone if the dough isn't cooperating.

Lastly, I continued my Japanese learning habit with a 450 day streak. I studied in Kyoto, Japan in 2012 but lost much of my conversational skills and Kanji in the decade since. Last year, I got back into studying routinely, and I'm happy to have my speaking and reading coming back strong.

Wrapping up

Although this year didn't go according to plan, I feel I made the most of the time I had to evolve as a developer, improve my work and way of working, and lay the foundations for a future business.

While I'm looking forward to having more predictability and stability again, I now have new skills, resilience, and calm that will make this year of unsurety worth it in the long run.

Aquileo | New article: Test-driven HTML and accessibility

2023-12-21T00:00:00Z

New article: Test-driven HTML and accessibility

I wrote a new article for the 2023 HTMHell Advent Calendar called Test-driven HTML and accessibility.

I've been wanting to share my new approach to unit testing JavaScript and I'm really happy with how this article turned out.

For most of this year, I've been exploring the full potential of Test-Driven Development (TDD) in my work and found a tool called Web Test Runner that allows me to run unit tests directly in the browser. This makes testing HTML and user interaction in the DOM possible, which opens up a whole new way to do accessibility testing.

Learn more about this setup with helpful examples: Test-driven HTML and accessibility

While you're there, check out all the other great articles for the HTMHell Advent Calendar!

Here are some of my favorites so far:

Aquileo | Build UX is 5 years old

2023-11-29T00:00:00Z

Build UX is 5 years old

Andy Bell posted that his company is 5 today and that reminded me that Build UX, my YouTube channel and now consulting company, is also 5 years old.

I rarely take time to reflect on my past work, so this milestone snuck up on me.

How it started

5 years ago, I was mentoring a couple people who wanted to get into frontend development. I strongly believe in applied learning, so I found interesting designs on Dribbble, recreated them in an emerging design tool called Figma (heard of it?) that I started using in 2017, and coached them how to build a responsive website with professional HTML and CSS.

The people I was mentoring took to the process and produced really high quality projects while quickly learning important fundamentals of frontend development. After wrapping up this round of mentoring, I thought it'd be valuable to share this approach more widely with my dual design and development background.

I started making videos on Build UX to demonstrate my process of turning visual designs into resilient websites with semantic HTML, scalable CSS, and accessibility. That new design tool, Figma, was starting to gain adoption, so I began making tutorials on creating "responsive" components and breaking designs into hierarchical components with Atomic design.

How it went

When you create content, you demonstrate your approach, thinking, and experience.

This is very effective for learners, but creating free educational content has also lead to nearly every career opportunity I've had in the last 5 years. This includes conference talks and workshops, articles for other publications, a LinkedIn Learning course, job offers, and consulting and coaching clients.

Similar to Andy, I was fully booked through the pandemic with long-term clients, and continue to get organic inquiries without ever searching for clients.

Where it's going

After transitioning into consulting full-time in 2020, I haven't created videos consistently. But this year I've roughly settled into a rhythm of a monthly video and companion blog post that I'd like to continue. I've been creating more focused videos to solve specific accessible design and development problems, and I also want to teach my latest approaches to TDD, JavaScript, and accessibility testing.

I love the freedom and impact I have as an independent consultant with long-term clients. I can act as an embedded team member, directly coach, solve problems, and contribute work, and have the flexibility to dig deep into research projects or create larger educational content. If you're interested in working together on accessible design and development, reach out: hello@luhr.co

There's one more destination on my horizon that I'd like to explore in the next 5 years: starting a product business. I'm not ready to share details yet, but over the past 2 years I've been increasingly investing time in building something I'm confident will provide a ton of value to designers and developers alike.

Thank you for watching my videos, reading my posts, hiring me to solve meaningful problems, and supporting me over these past 5 years. I'm excited to keep Build UX going strong.

Aquileo | All about accessible headings

2023-09-12T00:00:00Z

All about accessible headings

Watch the companion video to this post on YouTube

What is a heading?

A heading is text that describes a section of content.

In HTML, we have 6 heading elements (<h1>, <h2>, <h3>, <h4>, <h5>, <h6>) to create different heading levels. This allows us to create a hierarchical outline to structure our content.

Heading, header, title

It's important to always refer to these elements as headings. Don't confuse it with the term "header". In HTML, a <header> element is a landmark region that semantically groups introductory content, such as the top navigation, search, and settings of a website. Similarly, don't confuse it with the term "title". In HTML, the <title> element provides meta information about the page that is used in the browser's tab, and appears in search results. Unrelated, there's also the title attribute, which is a poorly supported HTML attribute that provides a tooltip on mouse hover, and is inconsistently announced by different assistive technology.

Why are headings useful?

Headings allow people to understand the structure of content and quickly identify relevant information.

For sighted users, headings are often styled distinctly from other text to allow people to visually scan a page and jump between areas of interest.

For assistive technology users, headings provide an overview of the webpage and even allow for quick navigation, such as navigating with the tree structure of all headings, moving to the previous or next heading, or moving to the previous or next heading of a specific heading level.

Like good accessibility in general, in addition to helping people, proper heading structure is also good for SEO. Headings allow search engine crawlers to understand the structure of a page, and search engines reward good heading use.

What makes for a good heading?

A good heading, like all good copywriting, should be descriptive, clear, and concise. It should also be unique, at least within the current section of content, to help users identify different chunks of information.

It's best to not overuse headings, especially with more granular content, as this dilutes their usefulness. If content can be grouped thematically, then it would benefit from a heading. If a piece of information or data needs a label, then a heading is likely too much, and other semantic HTML, such as the description list (dl) might be a better fit.

Myth: `<hgroup>` adds semantic content to headings

HTML 5 over ambitiously introduced the <hgroup> element, which was intended to associate a heading with one or more paragraphs to act as supplemental heading information:

<hgroup>
	<h2>Pricing</h2>
	<p>Plans that scale with your rapidly growing business</p>
</hgroup>

However, no assistive technology communicates any additional semantics with <hgroup>, so the heading and paragraph are treated normally. As a result, it's best to ignore this element.

What are heading levels?

Headings should be hierarchical, with different heading levels (1 to 6) to structure the relationship of content. The hierarchy of headings should be intuitive and consistent across similar sections.

How should we use heading levels?

Heading levels should create a logical outline for content that communicates the relationship of different sections, much like an indented bullet list.

Although HTML offers 6 levels of headings, try to create content that doesn't require more than 3 or 4. Content that repeatedly requires more than 3 heading levels probably means the content is too complex and can be edited or broken into distinct pages.

Rule: don't use headings for visual styling

As with all accessibility, visual styling and semantics are not the same, and should be treated separately.

Browsers have default CSS styles that provide a bold font weight for headings and a typographic scale that decreases font size from <h1> (the largest) to <h6> elements (the smallest).

As a result, some developers mistakenly choose the heading level based on the font-size they want instead of the appropriate level based on the content's structure.

Similarly, some developers mistakenly turn normal, paragraph text into a heading to make it bold instead of using the font-weight property in CSS.

Don't use headings for visual styling. Use headings to describe sections of content, use other text HTML elements (<p>, <li>, <dt>, <dd>, etc.) for non-heading text, and use CSS to achieve font size and font weight.

Rule: use a single, unique `<h1>` per page

Pages should have at least one heading, and every page's heading outline should begin with a single, unique heading that clearly and succinctly identifies the main focus of that page.

This <h1> heading should be unique to that page and shouldn't be used as the <h1> on any other page for the site.

Using more than one <h1> for a page creates an illogical structure, like a book having more than one title on the front cover.

Myth: the HTML outline algorithm

The HTML 5 spec included the HTML outline algorithm, which promised to automatically handle heading levels based on the nested structure of landmark region elements, such as <main>, <article>, <aside>, and <section>.

With this approach, developers would use <h1> elements for the first heading in each nested section, and the structure of the landmark elements would inform the proper heading level semantics. If you implement this structure in HTML, the default browser CSS styles will actually modify the font-size of <h1> elements that mimics the different headings levels.

Browser default styles of h1 elements with cascading font-sizes in nested sections

However, the HTML outline algorithm was never implemented in assistive technology. This approach of using <h1> elements in each section results in a flat outline with multiple level-one headings, which is confusing and not very useful.

In 2018, the W3C and WHATWG "retired" HTML 5 and introduced the HTML living standard. With the living standard, we no longer have version numbers for HTML, and the HTML outline algorithm is not advised.

Instead, use <h1> to <h6> to create a logical outline for content. These heading levels can be used regardless of the structure of landmark region elements, but pair nicely with well-structured landmarks.

Rule: don't skip heading levels

A heading should not be more than 1 level deeper than the previous heading.

If the previous heading is <h3>, then the following heading can be <h2> (a new section unrelated to the previous heading), <h3> (a new section as a sibling to the previous heading), or <h4> (a new section within the previous heading). It can't be <h1>, because there should only be one <h1> as the first heading of the page, and it can't be <h5> or <h6>, because that would skip a heading level.

A good heading outline

Applying these rules together results in a logical heading outline that's similar to an indented list:

<h1>...</h1>
  <h2>...</h2>
    <h3>...</h3>
  <h2>...</h2>
  <h2>...</h2>
    <h3>...</h3>
      <h4>...</h4>
    <h3>...</h3>
  <h2>...</h2>

Headings and landmarks

While the HTML outline algorithm was never really a thing, headings and landmarks provide rich semantics when used together. Landmark region elements, such as <main>, <article>, <aside>, and <section>, benefit from dedicated headings.

In fact, the <section> element, has no semantic value as a landmark unless it has an accessible name. This is achieved with the aria-labelledby attribute, which points to the id attribute of a heading:

<section aria-labelledby="features-section-heading">
	<h2 id="features-section-heading">Features</h2>
</section>

With this approach, the overall HTML structure of a page utilizes landmark elements and headings working together:

<header>
	<nav>
		<!-- ... -->
	</nav>
</header>

<main>
	<h1>Example, Inc.</h1>

	<section aria-labelledby="features-section-heading">
		<h2 id="features-section-heading">Features</h2>

		<!-- ... -->
	</section>

	<section aria-labelledby="plans-section-heading">
		<h2 id="plans-section-heading">Plans</h2>

		<h3>Starter</h3>
		<!-- ... -->

		<h3>Growth</h3>
		<!-- ... -->
	</section>
</main>

Accessibility-first headings

An accessibility-first workflow incorporates accessibility from the start of any project and preserves it across content design, visual design, and development.

It's useful to determine and note heading levels directly in content documents.

If you're authoring content in Markdown, this is easily achieved with # for <h1>, ## for <h2>, ### for <h3>, and so on.

In Google Docs, it's possible to style text as "Heading 1" to "Heading 6" using the dropdown menu, or keyboard shortcuts (Ctrl/Cmd + Alt/Opt + 1 for <h1>). It's still a good idea to note what the heading level is with Markdown's # approach to make it clear and convenient to implement in code.

If you're authoring content directly in HTML (as I recommend), then there's no need to separately document heading levels. Getting content into the browser as soon as possible without any styling allows us to evaluate the structure and accessibility of the page early on, and provides a working baseline that we protect throughout the rest of the project.

With raw HTML in the browser, we can then incorporate visual design. Again, it's critical to separate semantics from visual styling. This is why noting heading levels when creating content or working directly in HTML is so important. It frees the visual design to style typography however is needed, whether it's heading or paragraph text. If a heading ultimately isn't going to be visually shown in the final design, it's already in place and can be accessibly hidden using CSS.

With this process, you are much more likely to have well-structured, accessible headings in any design and UI.

Solutions to common design patterns

Beyond heading levels being misused to achieve a particular font-size, I typically find issues with headings in some common design patterns. Luckily, there are easy solutions that allow us to achieve the visual design of these patterns while providing accessible headings.

Eyebrow text followed by large text

This design pattern appears a lot in marketing sites, especially sections describing different app or service features. The eyebrow text is small, brief text that appears before larger, more descriptive or narrative text.

Feature sections on Stripe's homepage incorrectly use h2 for eyebrow text followed by h1 for narrative text in stead of h2 for eyebrow text and a paragraph for narrative text.

I often find this incorrect HTML structure:

<div>
	<p>Pricing</p>
	<h2>Plans that scale with your rapidly growing business</h2>

	<!-- ... -->
</div>

To fix this, we can simply make the eyebrow text the heading, and the larger text a paragraph. We can also enhance this chunk of content with a landmark section:

<section aria-labelledby="pricing-section-heading">
	<h2 id="pricing-section-heading">Pricing</h2>
	<p>Plans that scale with your rapidly growing business</p>

	<!-- ... -->
</section>

Lack of (hidden) headings

Sometimes visual designs don't accommodate headings in particular visual regions, or an accurate heading feels too formal compared to more narrative, marketing-oriented text. This seems to be common with missing <h1> headings on pages that only show sub-sections or have a marketing tagline that doesn't do a good job of describing the site or page as a whole.

In this case, it's best to add headings to properly describe the site, page, or section as needed.

While I recommend visually shown headings whenever possible, this can introduce design challenges that might discourage fixing the issue of missing headings. As a start, at least improve the heading outline with accessible, visually hidden headings while exploring better long-term solutions.

Stripe's homepage incorrectly uses narrative text as the h1 instead of a visually hidden h1 with the text "Stripe".

Home link is `<h1>`

Sometimes I come across top navigation that uses a <h1> element in the home page link.

<header>
	<nav>
		<h1>
			<a href="/">Example, Inc.</a>
		</h1>

		<ul>
			<li>
				<a href="/pricing">Pricing</a>
			</li>
			<li>
				<a href="/about">About</a>
			</li>
		</ul>
	</nav>
</header>

<main>
	<!-- -->
</main>

This results in a few issues:

The <h1> isn't located near the main content that it describes
The <h1> is the same across every page
The <h1> of the website/brand name is only relevant for the home page

To correct this, the top navigation should simply contain links. On the home page, a <h1> with the website/brand name should be included in the <main> section. On other pages, the <h1> should provide a descriptive heading for that particular page.

<header>
	<nav>
		<ul>
			<li>
				<a href="/">Example, Inc.</a>
			</li>
			<li>
				<a href="/pricing">Pricing</a>
			</li>
			<li>
				<a href="/about">About</a>
			</li>
		</ul>
	</nav>
</header>

<main>
	<h1>Example, Inc.</h1>

	<!-- -->
</main>

Linked headings

Headings and links often go together for lists of articles or to provide anchor links within a page. However, people can make the mistake of wrapping the heading in a link.

<a href="/a-year-in-review">
	<h2>A year in review</h2>
</a>

Instead, the heading should contain the link:

<h2>
	<a href="/a-year-in-review">A year in review</a>
</h2>

Evaluating the heading outline

There are helpful tools and manual testing approaches to evaluate the heading outline whether you're improving an existing project or working on a new project.

The WAVE browser extension by WebAIM provides a helpful heading outline and annotates any headings directly on the page. It also flags incorrect heading usage and potential headings.

With these findings, it's helpful to created a bulleted list of the heading outline to share with others and demonstrate whether the current structure makes sense.

It's also valuable to review headings with a screen reader. You can evaluate the page's heading structure and experience if the wording is distinct and understandable.

In NVDA on Windows, use the Elements List with Insert + F5 to get all headings on a page and review their tree order or jump between headings. You can also use the H key to jump to the next heading and Shift + H to jump to the previous heading.

In VoiceOver on MacOS, use Rotor Mode with Control + Option + U to get a similar list of all headings.

Summary

Don't confuse "heading" with "header" or "title"
Write clear, concise, descriptive headings
Only include a single <h1> per page, that's unique to that page
Use heading levels to create a logical heading outline
- Plan heading levels early on and test the heading outline throughout a project
Don't skip heading levels
Aim for less complex content that doesn't require all 6 heading levels
Don't use headings to achieve visual styling

Aquileo | All the ways to render a WebC component with 11ty

2023-07-11T00:00:00Z

All the ways to render a WebC component with 11ty

Watch the companion video to this post on YouTube

One of my favorite features of WebC is the variety of rendering options it provides. This allows full control to use WebC for HTML templating, custom elements, or web components (with or without the shadow DOM).

All of these rendering options offer some major benefits:

Explicit control over the final output for clean markup
Write HTML freely in components. There are no strange limitations, like Fragments in React to render multiple top-level elements.
Slots (with the <slot> element and slot attribute), including named slots, which alleviate the need for attributes (props) and offer even more control over the final output
Advanced templating with webc:if, webc:elseif, webc:else, and webc:for
Components can nest other components. WebC layouts are just components, so layouts can be nested as well.

Which rendering option to use

Each rendering option has different tradeoffs, so it can be difficult to know which to use for different situations.

Do you want basic HTML templating?

Simple HTML templating
Replace an element with the component's markup

Do you want scoped styles?

Overloading an HTML element
Scoped styles without using a custom element tag
Custom element

Do you want JavaScript?

Dynamic content with JavaScript render functions (server-side)
Custom element (server-side and global client-side)
Web component (client-side)

I prefer the least-powerful options based on my needs, and prioritize options that don't output a custom element tag. Custom element tags wrap around the component's internal markup, which can make layout and semantics more challenging in certain situations. This is somewhat alleviated with display: contents;, but I avoid it when possible.

Option 1: Simple HTML templating (the default)

The most common use case for components is HTML templating to reuse chunks of markup across a site, also known as partials or includes.

By default, WebC with 11ty allows you to write any markup you want in a component, use the component's custom element tag in your page, and it'll simply render the markup inside the component without the custom element tag.

In my-component.webc

<h2>Hello from the component</h2>

In page.webc

<my-component></my-component>

Rendered output at /page

<h2>Hello from the component</h2>

Benefits
- Reuse markup
- Doesn't render a custom element tag
Limitations
- Can't use scoped styles
- Can't use JavaScript

Option 2: Replace an element with the component's markup

This works identically to the default behavior, but allows you to replace any HTML element with a WebC component, without using the custom element tag.

This approach is required when rendering WebC components in the <head> element, since custom elements aren't allowed inside <head>.

Read 11ty's WebC documentation on <head> components

In my-component.webc

<h2>Hello from the component</h2>

In page.webc

<div webc:is="my-component"></div>

Rendered output at /page

<h2>Hello from the component</h2>

Benefits
- Reuse markup
- Works in the <head> element
- Doesn't output a custom element tag
Limitations
- Can't use scoped styles
- Can't use JavaScript

Option 3: Overloading an HTML element

The custom element spec requires a hyphen in custom element names to avoid conflicts with native HTML elements. However, WebC intentionally allows for naming conflict to make "overloading" native HTML elements possible.

When a WebC component has the same name as a native HTML element, the component will replace any instance of that element.

This makes enhancements to native elements possible, such as always including an alt attribute on an <img> that defaults to an empty string.

This approach also allows for scoped styles without outputting a custom element tag. Using <style webc:scoped> in the .webc file will tie all styles to the component. 11ty and WebC do this by creating a hashed CSS class name that's added to the component's root-level element, such as <div class="weljrwcay">.

With scoped styles, it's possible to select the root-level element with the :host pseudo-selector. This follows the shadow DOM standard for selection a shadow root host, but in the case of WebC, it can be used for any scoped styles, regardless of creating an actual Web Component with a shadow DOM.

11ty will automatically aggregate any styles (scoped or global) it finds in WebC components. All that's needed is to include the CSS bundle in the base layout file:

<style @raw="getBundle('css')" webc:keep></style>

In footer.webc

<h2>Heading with red text color</h2>

<style webc:scoped>
	h2 {
		color: red;
	}
</style>

In page.webc

<h2>Heading with normal text color</h2>

<footer></footer>

Rendered output at /page

<h2>Heading with normal text color</h2>

<footer>
	<h2>Heading with red text color</h2>
</footer>

Benefits
- Enhance native elements
- Can use scoped styles
- Doesn't output a custom element tag
Limitations
- Must commit to overriding every instance of a native element
- Can't use JavaScript

Option 4: Scoped styles without outputting a custom element tag

If you don't want to overload an HTML element but still want scoped styles, you can override the component's custom element tag with a native HTML element of your choice.

This is useful for creating variations of a common semantic element, such as <header> elements, without having a custom element tag getting in the way.

This approach makes use of the webc:root="override" attribute, which will replace the custom element tag.

In my-component.webc

<header webc:root="override">
	<p>Hello from the component</p>
</header>

<style webc:scoped>
	p {
		color: red;
	}
</style>

In page.webc

<my-component></my-component>

Rendered output at /page

<header>
	<p>Hello from the component</p>
</header>

Benefits
- Don't have to commit to overloading a native element
- Can use scoped styles
- Doesn't output a custom element tag
Limitations
- Can't use JavaScript

Option 5: Dynamic content with JavaScript render functions

Many components require more dynamic content, such as accessing data from 11ty's data cascade or adding timestamps.

This is achieved with JavaScript render functions, which run server JavaScript in a component. JavaScript render functions can be the entire component, or used within a component's markup just for the dynamic portions.

All it requires is a <script> tag in the .webc file with the webc:type="js" attribute. This render function outputs the last line of code, which is usually a template string of HTML.

Because this is server JavaScript, there won't be any JS bundling or client-side functionality.

In my-component.webc

<script webc:type="js">
	const currentDate = new Date();

	`<h2>Hello from ${currentDate.getFullYear()}</h2>`;
</script>

In page.webc

<my-component></my-component>

Rendered output at /page

<h2>Hello from 2023</h2>

Benefits
- Can use server-side JavaScript
- Allows access to 11ty's data cascade
- Allows for more advanced templating, such as looping and variables
- Doesn't output a custom element tag
Limitations
- No client-side functionality
- Can't add styles (global or scoped) within a render function
- Have to author HTML in a template string (no syntax highlighting, autocomplete, linting, etc.)

Option 6: Custom element

By default, WebC will output the custom element tag any time there are scoped styles or JavaScript in a component.

Custom elements are mainly useful for advanced templating with webc:if, webc:elseif, webc:else, and webc:for that rely on JavaScript. Similar to JavaScript render functions, 11ty will run server JavaScript in a custom element component and statically render the output.

Because 11ty will bundle any styles and JavaScript it finds in WebC components, it's possible to add global client-JavaScript in a custom element component by simply including a <script> tag. But, this can be hard to maintain, so I wouldn't recommend it.

Custom element tags need to have a hyphenated name to avoid naming collision with native HTML elements, unless you're intentionally overloading an HTML element. Browsers handle custom element tags as a generic element, similar to a <div>.

Similar to styles, 11ty will automatically aggregate any client-side JavaScript it finds across WebC files into a bundle. If your .webc file includes any (global) client-side JavaScript, be sure to source the bundle in your base layout file:

<script type="module" @raw="getBundle('js')" webc:keep></script>

In my-component.webc

<h2>Hello from the component</h2>

In page.webc

<my-component></my-component>

Rendered output at /page

<my-component>
	<h2>Hello from the component</h2>
</my-component>

Benefits
- Allows for more advanced templating while authoring normal HTML
- Can use server-side or global client-side JavaScript
- Can use scoped styles
Limitations
- There are better options for scoped styles without outputting a custom element tag
- Custom element tags may introduce some challenges with layout and semantics
- Can't use scoped client-side JavaScript

Option 7: Web component

At last, we arrive at a full-on Web Component, with all its powers and quirks. I only reach for Web Components if I need client-side interactivity and functionality.

As with any client-side JavaScript, it's best to consider progressive enhancement in case JavaScript doesn't load or is disabled.

Additionally, WebC works with the 11ty is-land plugin for hydrating Web Components after the page has loaded. This layers interactivity on top of the statically-rendered content.

Because Web Components depend on client-side JavaScript, we need to source the JS bundle in our base layout file, if we haven't already:

	<script type="module" @raw="getBundle('js')" webc:keep></script>

The type="module" is technically only needed if a WebC component is an actual Web Component, but I always include it so I can freely upgrade any component to a full Web Component.

In my-component.webc

<button type="button">Log to the console</button>

<script>
	window.customElements.define("my-component", class extends HTMLElement {
		connectedCallback() {
			const button = this.querySelector(":scope button");

			button.addEventListener("click", () => {
				console.log("Hello from the component");
			});
		}
	});
</script>

In page.webc

<my-component></my-component>

Rendered output at /page

<!-- Logs "Hello from the component" to the console on click -->
<button type="button">Log to the console</button>

Benefits
- Full Web Component spec
- Light or Shadow DOM
- Can use scoped styles
- Can use scoped client-side JavaScript
Limitations
- Custom element tags may introduce some challenges with layout and semantics
- Need to think through progressive enhancement and hydration

Summary

These options can be overwhelming, but they provide complete control over the output from WebC components, which is a major win for styling, semantics, and accessibility. I find that WebC results in writing less code and create cleaner output than any framework I've used.

Resources

The official WebC documentation by 11ty details all the features, many of which I couldn't cover in this post.

Shout out to 11ty & WebC by W. Evan Sheehan has great articles that dig into the nuances and capabilities of WebC with helpful examples.

Aquileo | Prompt engineering is shaping

2023-05-16T00:00:00Z

Prompt engineering is shaping

Prompt engineering is an emerging practice of creating the most effective prompts to get valuable responses from AI tools like ChatGPT or GitHub Copilot.

Most people will ask ChatGPT a simple, single question and may be underwhelmed by the quality of the response. But, people are finding that there is wide variability in the depth and quality of responses based on the structure and quality of the prompt.

While this practice will continuously shift and evolve alongside each new AI model or version, the early emerging techniques are noticeably more effective and even a little surprising.

Better prompts provide a lot of detail to set context, considerations, constraints, expected format, and more.

A successful prompt might include the following:

Tell the AI their role, who they are, and/or what perspective they should adopt
The desired outcome, goal, or solution
Constraints and details
Request the AI to ask questions before responding, and ask if the prompt makes sense
Define the expected output, such as "step-by-step instructions"

An example of a higher quality prompt is:

You are an experienced game developer with expertise in the Godot 4 game engine. You are creating a new racing game with realistic vehicle physics and handling, including independent suspension, manual shifting, tire condition, and surfaces with different friction materials. While there will be different car models with different engine parameters, the player will not be able to tune the vehicle. Your task is to create the core vehicle game object. The vehicle is a central focus of the game, so the implementation should be robust. First, provide step-by-step instructions of how you will approach this task. Once the instructions are finalized, you will next provide the corresponding code in GDScript. Please ask any questions you may have before generating a response. Does that sound alright?

Note the frame-setting and depth of the prompt, and how it sets up the AI as a partner in the process. I've found requesting the AI to ask clarifying questions is particularly effective, as it will do a fair bit of discovery to further understand the job to be done and constrain the response.

Essentially, this is a form of shaping, the practice of defining and de-risking potential solutions.

Shaping was popularized by the book Shape Up, and the output of the shaping process is a pitch document with the following:

Problem — The raw idea, a use case, or something we’ve seen that motivates us to work on this
Appetite — How much time we want to spend and how that constrains the solution
Solution — The core elements we came up with, presented in a form that’s easy for people to immediately understand
Rabbit holes — Details about the solution worth calling out to avoid problems
No-gos — Anything specifically excluded from the concept: functionality or use cases we intentionally aren’t covering to fit the appetite or make the problem tractable

Effective prompt engineering (and answering questions from the AI) should cover all the areas of a defined pitch. It's important to note that the solution in a pitch is high-level but well defined, and the AI is tasked with carrying out the specific implementation.

Sometimes, it's unclear what potential solutions may even exist, especially when learning a new skill or topic. In this case, it's valuable to engage the AI as a partner in the shaping process itself, by crafting a prompt that establishes the problem space, the desired outcome, what in-scope, out-of-scope, and so forth.

As I started learning about prompt engineering, I was surprised that the biggest improvements seem to come from humanizing the AI, such as telling them who they are, requesting that they ask for clarification, or asking if they understand.

With decades of figuring out how to write cold, unnatural prompts for search engines, it's new but more intuitive to be able to write prompts that are closer to having a normal conversation. And, there will be more alignment with the shaping work I do with my clients and the prompt engineering I do with AI, which will push my shaping skills further.

The main quality of effective prompt engineering is engaging AI as a pairing partner or mentor in the process. By treating AI as a collaborator, not as something we merely delegate to, it produces more value.

If an artificial intelligence benefits from this treatment, then surely we can do better to engage individual contributors as equals with mutual respect and involvement in shaping our work.

Aquileo | My Custom Second Brain Setup Part 4: Limitations as Strengths

2023-04-26T00:00:00Z

My custom second brain setup, part 4: Limitations as strengths

The main limitations (and strengths) of my second brain setup come from Markdown and Git:

There's no great way to handle images, which can be useful for design inspiration (user interfaces, home interior design, etc.). Luckily I rarely need them for notes or reference, so I usually just transcribe the information in text for things like diagrams and visual explanations. If I do need them, I co-locate images in the same folder as the related note, and can preview them in VSCode or with the file explorer.

I don't have a solution for linking between Markdown files. Sometimes I'll just create a link in Markdown with the file name and path, which I'll use to simply search for the file using the command palette in VSCode or the file tree. Having backlinks like Obsidian, Roam, or Dendron offer would be cool, but I'm not sure I want to invest in making custom tooling or finding an extension for this.

My second brain setup doesn't allow for any sharing or collaboration. For me, that's fine and intentional as this is a private workspace for all areas of my life, and I can use other collaboration tools as needed.

Exporting and migrating Markdown files from Readwise and converting voice notes isn't automatic and introduces friction in the CODE workflow. It's not ideal, but I rarely have an urgent need for specific highlights I haven't imported yet that disrupts my work.

Valuable constraints

These limitations are mildly inconvenient, but I'm continuously refining my setup and have full control over it. In fact, I find these limitations worthwhile and even beneficial, as they allow me to keep my setup simple, lightweight, and flexible. Everything is about tradeoffs, and this setup provides immense value to me without requiring much overhead or complexity.

I'm guessing my current setup offers 95% of what I could ever want in my second brain. In fact, the only improvements I have or currently plan to make involve simple adjustments to the folder structures and how I scope/limit my work in progress.

Recap

Here's a final overview of my custom second brain setup.

Workflow:

Capture highlights and notes from source material (eBooks, articles, videos, podcasts)
Organize with PARA method using folders and files
Distill using Markdown syntax for progressive summarization
Express with new writing and notes for creating other content

Tools:

Kindle (eBook highlights and notes)
Readwise Reader (article highlights and notes)
Readwise (export highlights and notes to Markdown)
VSCode (creating and editing notes)
Git Journal (creating and editing notes on mobile)
Git (version control)
Version control and automatic file backup services (use multiple for redundancy, privacy, and security)

Costs:

Readwise and Readwise Reader: $99/year
Cloud storage for file backups: $49/year
Everything else is free and open-source
This setup saves me countless hours per year, while an hour of consulting covers the annual costs

Second brain resources

There's a growing personal knowledge management community that's focused on building a second brain.

Here are some resources I've gotten a lot of value from:

Building a Second Brain: An Overview article by Tiago Forte (creator of the concept)
Building a Second Brain book by Tiago Forte
The PARA Method: The Simple System for Organizing Your Digital Life in Seconds by Tiago Forte
Fractal Productivity series by Dennis Nehrenheim M.Sc. (interesting ideas that build on top of PARA)

Aquileo | My Custom Second Brain Setup Part 3: Minimalist Productivity

2023-04-24T00:00:00Z

My custom second brain setup, part 3: Minimalist productivity

The real strength of a second brain comes down to a simple folder structure that has done more for my productivity than any app or user interface I've used.

The PARA method structures all the information in a second brain in order of actionability.

As a review, my second brain is just a collection of Markdown files that use Git for version control. These files are structured with folders that follow the PARA (Projects, Areas, Resources, Archive) method:

00-inbox
- Default for new notes to be processed later
- scratchpad.md file for random thoughts and reminders
- Day-to-day tasks that don't relate to a specific project
01-projects
- Active projects across work and personal life (try to limit to a max of 7)
02-areas
- Ongoing areas of interest or processes with a standard to maintain
03-resources
- Reference information that's not tied to an ongoing area of effort
04-archive
- Information that's no longer relevant or actionable, but can always be promoted again if it's useful

My Projects folder represents any current work across my professional and personal life. I try to limit work in progress to an absolute max of 7 projects at once, with 3 or 4 as a more manageable amount.

Projects have all the relevant notes, resources, and tasks in once place to achieve a specific outcome by a particular date. For example, when writing the scripts for my course on LinkedIn Learning, Accessibility-First Design, I was able to reference all the years of my previous work and learnings without having to do much new research as I wrote. This greatly accelerated my writing process by focusing my time on simply curating my already-established thoughts and recommendations instead of starting with a blank script for each topic.

On a day-to-day basis, all other notes go into Areas if they represent topics of ongoing interest (writing, wellbeing, home, travel, etc.) or Resources if the are just useful reference (recipes, bookmarks, learning notes, instructions, etc.).

Anything that's no longer relevant gets demoted to the Archive folder. Life and work seem to have some seasonality to them. Occasionally, archived notes become relevant again and I can easily drag some notes back into a more actionable folder.

Tasks

Tasks primarily come out of project scopes and are the most granular and actionable information in a second brain. I either add tasks inline inside of notes where relevant, or can create a dedicated tasks.md file in a project folder with headings for each project scope.

There are also tons of loose tasks that come up in day-to-day life that aren't tied to a specific project (scheduling an appointment, quick things I need to do around the house, etc.). I simply add these to a tasks.md file in my 00-inbox folder.

I don't use a separate task manager, and instead leverage Markdown and VSCode to track incomplete tasks from across my entire second brain.

In any file, I can add a simple Markdown task:

- [ ] Task name
- [x] Completed task name

If the task has a deadline, as most tasks should, I created this convention:

- [ ] YYYY-MM-DD | Task name

Sometimes a task is a nice-to-have, so I mark it as optional with a tilde (~):

~ [ ]

Because tasks can appear anywhere, I do a global search in VSCode for the following string: - [ ]. This finds all incomplete tasks across all files. It's intentional that optional tasks with ~ [ ] don't appear in this search. I only want to see those when I actively reviewing other information in a project, but the whole point is I'm not committed to them and comfortable never completing them.

Use Ctrl/Cmd + Shift + F to do a global search in VSCode with the string - [ ]

I take this one step further and use the "Open in editor" button to create a dedicated tab, which I pin so I can reference it any point.

Use the "Open in editor" button to create a dedicated search tab

This pinned tab shows tasks across all files that represent the work I need to do in every area of my life. From this pinned tab, I can quickly jump into to read the surrounding context or update tasks as needed.

The pinned search results tab shows tasks across all files

If you want to only view tasks at a certain hierarchy, or for a specific project, it's easy to limit the search to a particular folder to create a more focused task list.

Routine review

It's useful to routinely review the 00-inbox folder to process and organize lose notes into their respective areas, clean up the scratchpad.md file, and get an overview of my work in progress. Review may also involve manually exporting Kindle and Readwise Reader highlights and notes into Markdown files, which I then organize into my second brain as needed. Sometimes, I'll also refine the organization of some folders, and move items into the Archive as needed, but usually this happens in my day-to-day work with my second brain.

While some people have a formal cadence of weekly or monthly reviews, I embrace a just-in-time approach and simply do it whenever it comes to mind or bugs me. This works and hasn't resulted in too much batch processing.

Calm

This very straightforward setup requires very little thinking to use and creates very little friction when creating new notes or getting ideas out of my head.

I've found I hold on to fewer recurring worries or reminders in my working memory, and can trust that any task, obligation, or interesting idea is accounted for in my second brain.

I've never been one to have more than a few browser tabs open at once and my capture and organize workflow provides an immediate destination for any interesting articles I want to read later. I find myself needing very few bookmarks since they no longer act as a reading list, and I've actually migrated any remaining browser bookmarks into simple notes in my Resources folder by topic.

This second brain setup also means I also have very few tools and logins to manage, which adds to the calm and reduces context switching. I don't have to maintain my productivity system across multiple sites or apps, so my folder and file structure account for everything holistically.

This simplicity and calm make me feel less overwhelmed, more effective, and more creative than ever.

Keeping it minimal

I feel most productive with simple processes and the lightest tools possible.

While in the past I've used task management systems like Asana and created robust dashboards in tools like Notion, the flashy appearance of functionality came with increased overhead that did little to change my actual output. Having all my tasks embedded in the context of all my other knowledge and work in progress is both convenient and easy to survey at a high level.

It feels ridiculous that I put so much thought into some files and folders, but this absurdly simple setup has done more for me than any other tool I've tried.

In the final post in this series, I'll cover the limitations of my custom second brain that are actually some of its main strengths.

Next: part 4: Limitations as strengths.

Aquileo | My custom second brain setup, part 2: How it works

2023-04-21T00:00:00Z

My custom second brain setup, part 2: How it works

To explain how my custom second brain setup works, I'm going to break down the tools I use for each of the steps in the CODE (Capture, Organize, Distill, Express) workflow.

Brace yourself: the core of my setup is so simple and minimal that you might be disappointed. This simplicity is absolutely intentional and the result of very careful consideration and continuous improvement.

Tools for Capture

Articles

I use Readwise Reader to save articles, subscribe to RSS feeds, and add highlights and notes. Readwise (the main app) provides a convenient Markdown export that provides all the highlights and notes since the last export.

Books

I primarily read eBooks using a Kindle. Even though I enjoy reading paper books more, eBooks are so much more efficient for highlighting and capturing notes. I also use Readwise to export my Kindle highlights into Markdown.

When I do want to make notes or highlights in paper books, I'll read at my computer and transcribe any interesting text as I'm reading. This isn't the most ergonomic workflow, as books rarely stay open when I set them down to type, and transcription is tedious and slower than eBook highlights, so I don't really like this workflow. However, it's necessary for books that are only available in print. I may build a compact bookstand that can accommodate books of any size and holds the pages open. Handheld scanners with a pen form factor are a thing, but I don't know how well these work. That could be a viable solution, though.

Videos, podcasts, audiobooks, and other sources

For video and audio content, there's no efficient way (that I'm aware of) to capture snippets of audio as a "highlight" or auto-transcribe a selected portion. It'd be interesting if there are solutions to this, but I don't mind keeping things more manual and low-tech. This little bit of friction is actually a positive, as only the best information feels worth the effort to capture.

I usually watch educational videos on my computer, so I just add notes directly in my second brain as needed.

I'm usually not at my computer when listening to podcasts, so I just pause and make a note to re-listen to the podcast when I'm at my computer. Or better yet, find a transcript that I can save and highlight as if it's an article (going through Readwise Reader and then Readwise for exporting to Markdown). If you have a podcast, please provide transcripts! They're essential for accessibility and benefit anyone who wants to make notes or highlights.

Audiobooks have similar limitations, but I'll usually just get the eBook version if I like the audiobook, and re-read it while making highlights and notes (going through my Kindle and then Readwise for exporting to Markdown).

Voice notes

I use the built-in Recorder app on Android to capture voice notes that auto-generate fairly accurate transcriptions. While this is handy for dictating ideas while I'm driving, for example, it requires some manual migration, and the transcripts aren't as succinct as my written notes or highlights, so they usually require more reworking and trimming to be useful.

Tools for Organize

My second brain: just files and folders

My second brain is just a collection of Markdown files that use Git for version control. These files are structured with folders that follow the PARA (Projects, Areas, Resources, Archive) method:

00-inbox
- Default for new notes to be processed later
- tasks.md for loose, day-to-day tasks not tied to any project
- scratchpad.md for capturing random thoughts that can be organized and refined later
- shopping-list.md for groceries or anything I need to buy in town
01-projects
- Active projects across work and personal life (try to limit to a max of 7)
02-areas
- Ongoing areas of interest or processes with a standard to maintain
03-resources
- Reference information that's not tied to an ongoing area of effort
04-archive
- Information that's no longer relevant or actionable, but can always be promoted again if it's useful

Version control and syncing

With Git for version control, I can easily back up and sync my second brain across many devices. I have full flexibility of using any combination of local storage, automatic file backups, GitHub, GitLab, etc. for safe keeping and redundancy.

I also find the security of version control services like GitHub and GitLab to be much more robust and dependable than self-rolled solutions from productivity apps.

Editing notes on the computer

Because my second brain is just a simple version-controlled folder structure, I can use the same tools I use for coding, which really speeds up my productivity.

For me, that's VSCode with a VIM plugin for efficient editing and searching.

Whenever I'm using my computer, I always have an instance of VSCode with my second brain open and at the ready. No logins needed.

At the Markdown file level, I use standard Markdown syntax, with the occasional table. The only custom thing I do is simple frontmatter in each file with created and modified dates:

---
created: YYYY-MM-DD
modified: YYYY-MM-DD
---

This is easy to add with a Markdown snippet I created in VSCode that I invoke with /top and autocomplete:

In markdown.code-snippets:

"Markdown frontmatter": {
	"prefix": "/top",
	"body": [
		"---",
		"created: $1",
		"modified: $1",
		"---",
		"",
		"# $0"
	],
	"description": "Default frontmatter"
},

Editing notes on mobile

I edit notes on mobile using the Git Journal app.

I configured Git Journal to name all new files to YYYY-MM-DD-HH-SS.md by default. Traversing folders in Git Journal isn't the easiest, so by default it stores all new notes in the 00-inbox folder, which I can organize later when I'm working on a computer.

Git Journal automatically adds and updates the created and modified timestamps in frontmatter for each file, which matches my manual process.

Git Journal works well overall. Managing folders and files is a little clunky, so I organize them later when I'm at my computer. It does have a custom toolbar with some WYSIWYG options, but I'd really like to have dedicated indent/outdent buttons.

Tools for Distill

Progressive summarization is an efficient way to distill highlights and notes down to the most interesting and impactful information. It's an iterative process that involves 3 passes of using text formatting to highlight certain text with increasing levels of emphasis.

In an app like Evernote or Notion, this may involve the following passes:

First pass: bold the most important text
Second pass: underline the most important bolded text
Third pass: highlight (add a background color to) the most important underlined and bolded text

The result of this third pass is often less than 10% of the original highlights and notes. Since highlights are often 10% or less of the original source information, the output of progressive summarization is the most essential 1% of ideas that offer the majority of value.

Since all my notes are authored in Markdown, I can use its simple syntax for progressive summarization:

First pass: italicize with * (*idea to highlight*)
Second pass: bold with ** (**idea to highlight**)
Third pass: bold and italicize with *** (***idea to highlight***)

This syntax is easy to type, and just so happens to visually indicate the level of importance with 1, 2, or 3 asterisks (*), even when viewing Markdown as plain text.

Tools for Express

The main channels I use to express new ideas and content are my personal blog and my YouTube channel, with some very light posting to social media.

My personal site uses 11ty with Markdown for posts, so I draft all posts in my second brain and copy them into my site's codebase when I'm ready to publish. All I need to do for publishing is add some frontmatter for meta information (title and description), sprinkle in some WebC components if needed, and a published date. Then, I simply commit it up to trigger a new build. It's critical that this process requires only a couple minutes of work to go from finished draft to published post.

For other channels, my second brain has substantially accelerated my learning and creative output with so much valuable information and thoughts to build upon. I can quickly search my notes for ideas across a topic, rework them as an outline for a video or as a quick social post, and then create the final content.

Alongside authoring written content in Markdown, I've experimented with dictating blog post drafts using Recorder for Android or Otter.ai, but this has been less efficient for me. Exporting text from these tools and manually formatting into more structured Markdown content is tedious. And, although I largely have aligned my speaking voice and writing voice over the last few years, my off-the-cuff dictating isn't as well structured and sequenced as my writing, so it requires a lot more editing to get from initial draft to finished post.

I can probably improve on this with more detailed outlines before dictating content, but I'm more likely just to just write directly. I might refocus my dictating experiments into recording podcast episodes or YouTube videos in the future instead.

All together

Here are all the tools that compose my second brain setup:

Kindle (eBook highlights and notes)
Readwise Reader (article highlights and notes)
Readwise (export highlights and notes to Markdown)
VSCode (creating and editing notes)
Recorder (Android app for voice recording)
Git Journal (creating and editing notes on mobile)
Git (version control)
Git repository hosting and automatic file backup services (use multiple for redundancy, privacy, and security)

At its core, my second brain really is just a collection of Markdown files in folders, with my text editor (VSCode) as the primary tool. A key attribute of this setup is I can use any text editor to edit and maintain my second brain, and I can store it anywhere. I can structure everything to suit my needs, and any conventions are purely of my own choosing. For me, this simplicity offers pretty much everything I could want.

In the remaining posts in this series, I'll cover my minimal productivity process using my custom second brain setup, and then wrap things up by covering the limitations of my setup that are actually some of its main strengths.

Next: part 3: Minimalist productivity.

Aquileo | My custom second brain setup, part 1: Why go custom?

2023-04-19T00:00:00Z

My custom second brain setup, part 1: Why go custom?

Building a second brain last year had the biggest impact on my productivity, learning, and organization in my entire career. It led to many of the successes I covered in my 2022 year in review and provided incredible value in my work, self development, and creative output.

What is a second brain?

A second brain is a productivity system that gives focus, structure, and actionability to all the information we encounter in our lives.

It acts as a central store for all areas of your professional and personal life. By getting all information out of your head, you can keep your "working memory" clean, which is calming and leads to clearer thinking.

A second brain follows the CODE (Capture, Organize, Distill, Express) workflow:

Capture
- Highlight or take notes on the most relevant, interesting, and impactful information from source materials (articles, books, videos, podcasts, etc.)
- Write down any ideas or tasks as you think of them to get them out of your head
Organize
- Structure this information based on actionability
Distill
- Use progressive summarization to refine highlights and notes down to the essential details and most novel ideas
Express
- Recombine existing ideas and generate new ones to create meaningful work

My second brain setup needs to account for this full process with as little complexity and overhead as possible.

Most people build their second brain using a productivity/knowledge management app like Evernote, Notion, Obsidian, or Roam, sometimes with multiple layers of other services and integrations that support a complex CODE workflow.

With so many great options, some of which are completely free, why build a custom setup?

Past pains and lock-in

I've been burnt by lost data. A few years ago, a collection I maintained with over 15 years of my past writing vanished suddenly from my Google Drive. This happened without a trace, not even appearing in my file history or trash, and could not be recovered. That was a deeply painful experience that discouraged me from writing much at all for nearly 2 years.

I've also lost a lot of time migrating between tools repeatedly due to pricing and plans changing suddenly, companies going out of business or being acquired, and other stressful experiences.

I first drafted my second brain in 2021 using Notion and quickly felt locked in. I was also frustrated by how long the app took to load, poor offline support, and block limits as the pricing structure changed. When I migrated off Notion to my custom setup, the process was tedious. Even going from Notion's flavor of Markdown to standard Markdown required a fair bit of manual conversion and per-file review.

These apps work for many people and not everyone needs to build a custom second brain. Lock-in happens to varying degrees with any paid service. For some people, those tradeoffs are totally worth it. Sometimes a level of lock-in provides even provides convenience within an ecosystem, but it's not a good fit for me.

Requirements

My second brain needed to have the following qualities:

Quick and easy to access
Simple
Efficient
Lightweight
Secure
Easy to maintain
Independent of specific companies or services
Flexible
Fully works offline
Convenient editing and syncing across my devices

Existing options

I'm not interested in Evernote, and moved away from Notion.

Obsidian and Roam are other interesting options that have free plans. They offer intricate relational graphs, backlinks, and other power features are probably great for abstract thinkers, but the interfaces and interactions are definitely more complex as well. They both have mobile apps, which is a plus, but I'm hesitant about long-term lock-in.

If I had to pick an existing tool, I'd probably go with Dendron. It's an impressive open-source project that adds knowledge management features directly into VSCode. Some features even match Obsidian and Roam, such as the relational graphs that connect topics across notes. These features are more complex than what I need, but seem pretty optional. The main downside of Dendron is the lock-in with VSCode and lack of mobile editing. I use VSCode, but have considered using VIM directly in the terminal. So VSCode may not always be my editor, and I need a way to edit my second brain from my phone.

After evaluating all the existing options, I was craving more flexibility, efficiency, and simplicity than what was available.

Time to go custom

Often people build custom tools to have features that don't exist, or to support nuanced, intricate workflows. In my case, I actually wanted the opposite: strip out as much complexity, overhead, and outsourcing as possible so I can enjoy a simple, focused, portable second brain setup.

In the next post in this series, I'll detail the tools I use for each of the Capture, Organize, Distill, and Express steps of the CODE workflow. In following posts, I'll then cover my minimal productivity process using my custom second brain setup, and wrap things up by covering the limitations of my setup that are actually some of its main strengths.

Next: part 2: How it works.

Aquileo | My new course: Accessibility-First Design

2023-04-17T00:00:00Z

My new course: Accessibility-First Design

My new course, Accessibility-First Design, launched recently on LinkedIn Learning!

Accessibility doesn't compromise design. Instead, it's at the core of successful content and visual design.

This concise course provides tons of tactical skills across content design, visual design, and accessibility testing to make more successful digital products. While it's focused on design, I consider all product work to be a form of design, and every topic has bridging context to development.

I love when my educational content opens up wider conversation. If you take the course, let me know if you have any questions or feedback!

Core concept: accessibility-first

As the title reflects, this course focuses on an accessibility-first approach to product design.

Accessibility-first is a term I introduced in my work over the past year that's analogous to mobile-first design.

With mobile-first design, we design for smaller viewports to ensure that the user experience, content, and visual design are all thoughtfully crafted without compromise when there's less space to work with. This makes for a more focused, resilient, and cohesive experience for all users across all screen sizes.

With accessibility-first design, we design with accessibility in mind from the start as a core principle of our work. This spans content design, visual design, and development, with accessibility testing throughout the product development process to ensure we keep our work in an always-working, accessible state. Prioritizing accessibility improves the user experience for everyone.

Core concept: just-in-time Design

Just-in-time design is another approach and term I've introduced in my work over the past year. Even the most "Agile" teams often perform upfront design before beginning development, which leads to a lot of rework and waste in the process. Questions, constraints, and even opportunities arise later in the process, which requires repeated design changes or compromises.

With just-in-time design, teams do visual design in parallel with development. Specifically, by waiting for initial content and functionality to be implemented in the browser, teams can start with a working, accessible, unstyled version of their product. This verifies that the overall functionality, content structure, and accessibility are in place and will be protected as the product evolves.

At this point, just enough visual design is layered in to bring polish, branding, and delight to the user experience, but it's built on a working, de-risked foundation.

This is a radical approach, but I've implemented it in my consulting work with my clients' teams with a lot of success. The end result is a more better product across accessibility, user experience, performance, content design, and visual design, while also saving significant time and energy.

Behind the scenes

It's surprising how much work and distillation goes into creating just a 1 hour 24 minute course.

LinkedIn Learning first reached out in August of last year to ask if I would like to pitch a course. The course pitch process involved writing a course summary and an outline with learning objectives for each topic. It was interesting to outline the course from a user benefit perspective, and forced me to think about actionability and outcomes for every topic.

My course was greenlit in late September, so I kicked off production in October with a flurry of script writing. With the volume of production work ahead of me, I really depended on time blocking my calendar to guarantee I had consistent hours every week to stay on schedule.

Typically, I just have a simple bulleted list when I record educational content. Writing polished scripts that I would follow word-for-word was a new experience, and forced me to really unify my writing and speaking voices.

Although I do a lot of writing in my career, this also pushed me to produce writing consistently, on-demand, at scale. By mid-November, I finalized scripts for 26 videos with 13,500 words.

From there, the sole focus was creating visual assets. Across each of the 26 videos, I created an ID for every distinct idea that would benefit from a dedicated visual. This created an inventory of over 350 slides I needed to design.

First, I conducted an audit of all the unique user interface situations I cover in the course. This created a checklist for me to build a realistic design system in Figma that had a generic fictional brand, cohesive look, and all the statefulness of an interactive and accessible product. A number of these components also needed both good and bad versions to cover common mistakes.

This work was a form of just-in-time design. Because the visual design was driven by the script writing, I was able to design exactly what was needed and create a ton of efficiencies. I was surprised that just 10 distinct user interface patterns had enough accessibility considerations, states, and common mistakes to support hundreds of slides.

With my component warehouse in place, I worked fairly quickly and linearly through the slides. Most of the slides I designed could be adapted for related topics in other videos, so progress accelerated with each chapter I completed.

Working around the holidays and surges in client work, I finalized the slides in mid-January just before traveling to LinkedIn Learning to record onsite.

As someone who records a lot of content at home, the scale and resources of the recording process at LinkedIn Learning really impressed me. Their studio had dozens of soundproof booths with dedicated halves and equipment for producers and instructors to collaborate.

My soundbooth and entire universe for a couple days.

The studio has dozens of soundbooths for recording many courses in parallel.

An accidental homage to HAL-9000.

The campus also had dedicated sets and studios for on-camera content and photoshoots, and the scale of the whole operation made it clear how LinkedIn Learning can put out multiple new courses weekly.

After a couple days recording onsite, the course went into post-production and launched in late March!

Reflecting on my experience

This experience made me realize how courses are a strong form of progressive summarization. This course summarizes years of my career and learning, hundreds of hours of production work with thousands of words of writing and hundreds of dedicated visual assets, and distills it all down into less than 90 minutes.

I typically create longer, deep-dive content that could dig into a single technique for 90 minutes, so this format of intensely focused, shorter videos was a good stretch exercise for me.

The production process also created a productive habit in my writing. Since working on the course, I've carried this momentum forward into this year. Writing comes much more easily now, even at scheduled times, and I've found myself wanting to get back into creating video content again after a couple years of being focused on client work.

Feel free to check out Accessibility-First Design on LinkedIn Learning. I hope it provides value for anyone who works on digital products. Let me know your thoughts!

Aquileo | Betting on WebC

2023-02-27T00:00:00Z

Betting on WebC

WebC is a new tool by Eleventy that is one of the most exciting developments in a long time.

WebC as a standalone tool generates markup for custom elements and Web Components, which unlocks server-rendering for Web Components and brings many quality-of-life features while following web standards.

As someone who most enjoys working in good old HTML, CSS, and vanilla JS, this is a dream. I've used plenty of frontend frameworks throughout my career, but I've always been frustrated by the complexity, bloat, and damage to the user experience they cause. WebC has the potential to become my go-to approach for building websites.

WebC as a plugin for Eleventy allows for single-file components and tons of new templating and rendering possibilities. It can be used for layouts, pages, and components, meaning Eleventy sites can now be built entirely with WebC without other templating languages such as Nunjucks or Liquid.

In fact, I recently rebuilt this website using WebC instead of Nunjucks, and the authoring experience was so empowering, simple, and fun. I'm using WebC for layouts (including nested layouts), pages, and components that have fully replaced Nunjucks partials/includes.

Enhancing Web Components

Web Components have a strong future, but the main arguments against them have been server-side rendering and the ergonomics. WebC solves this, allowing for progressive enhancement, while also providing rendering flexibility, simple CSS scoping, critical CSS and JS bundling, and more.

Probably my favorite benefit of WebC with Eleventy is the default behavior of simply rendering an HTML-only partial. You simply write markup in a .webc file, and the custom element tag will be replaced with the markup when rendered. This is the main use case for HTML templating, and keeps the DOM clean and simple. I'll dig into and compare all the rendering options WebC offers in a future post, as there are so many useful options available.

As with all projects by Eleventy, performance and web standards are top of mind with WebC. An Eleventy site with WebC won't ship any client-side JavaScript, unless you intentionally author it in a component. Even if you add scoped CSS to a component, WebC will render it with a custom element tag, but there's no JavaScript needed. This is a major win for performance, web standards, and simplicity.

Future potential

WebC unlocks a lot of possibilities for static sites using Eleventy and I'm interested in what's now possible for even more interaction-heavy experiences. I have an ambitious personal project in the works, so I'm going to take things as far as I can with WebC and Eleventy, sharing my learnings and ideas along the way.

Because WebC addresses the limitations of Web Components, I'm optimistic that it can be used to build robust web apps and can gain strong adoption in the community.

I don't care about tech trends, but it'd be great to have a project that's committed web standards and progressive enhancement grow in use to improve the web for everyone.

Learn more about WebC

WebC Eleventy documentation
Interactive Progressively-enhanced Web Components with WebC (Eleventy YouTube)
Crash Course in Eleventy’s new WebC Plugin (Eleventy YouTube)
11ty & WebC. This site of useful recipes taught me a lot about how WebC works and all the different rendering options it offers.

Aquileo | 2022 year in review

2023-02-25T00:00:00Z

2022 year in review

2022 was the best year of my career so far, and one of the best in my personal life.

Career

I moved away from full-time employment in the summer of 2020 to be fully independent, and I'm enjoying this phase of my career more than ever. 2022 was a year of focus, and I really overcame lingering burnout that had crept into my life from the previous couple years.

Consulting

Independent consulting work was very successful, rewarding, and dependable. My goal was to keep my time and attention focused, so I turned down several consulting and full-time opportunities.

I started 2022 fully booked for the year with my main client, who was incredible to work with throughout the entire year, and I'm rolling into 2023 with the whole year booked with them again.

While I originally began working with this client in November 2021 to improve their product's accessibility, our work together has since evolved to include pretty much all aspects of the product and business.

I was able to work with the team to drastically simplify and redesign the marketing site and product, introduce lean manufacturing principles to improve an intense data workflow at the core of the business, and transition the team from Scrum to Shape Up with much success.

Working with this team has led to many learning opportunities for me. I learned how to code in Python, build a parser from scratch, do web scraping and data transformations at scale, and really embraced Test-Driven Development (TDD).

Coaching

In addition to consulting, I took on a new design coaching client who is a solo entrepreneur and a freelancer. While I've done a lot of mentorship in past roles, this was a great experience to focus more on formal coaching, provide advice, and provoke new solutions with less focus on teaching.

While I don't really have the capacity to scale coaching as an offering, I enjoyed the recurring sessions we had for a few months, and it was rewarding to see my client really level up in design skills, UX, and accessibility.

Teaching

I wanted to keep my total obligations to a minimum in 2022, so I turned down multiple speaking and course opportunities for most of the year.

In the fall of 2022, however, I was contacted by LinkedIn Learning to basically create any course I wanted. After careful consideration, I felt this opportunity was a good fit and came at the right time, so I kicked off production on a new course on accessible design that is slated for spring 2023.

Although I've been gradually working on a large-scale accessibility course for a couple years, it's always had to fall back in priority to paid consulting work. Having a short-term deadline with a more focused scope was the right level of commitment and led to a very productive few months.

I wrote over 13,000 words for the video scripts between October and November, and spent December and January creating designs for dozens of UI examples and over 300 slides. In late January 2023, I went to LinkedIn Learning's offices to record the course, and it's now in post-production.

Learning

As I mentioned with consulting work, I had an opportunity to pick up several new skills in 2022. I've grown to really enjoy working with Python as my second programming language after JavaScript, and it's been quicker to pick up additional languages, such as C# for game development (more on that in the future).

Since I started my career in visual design, my development experience has always been heavily focused on the frontend. In 2022, I got a lot of experience working with APIs and asynchronous code and getting more familiar with backend development which has helped round out my understanding and made me a better developer.

My favorite project of the year was building a custom tokenizer and recursive descent parser (RDP) in both JavaScript and Python to parse a custom syntax for my main client. I followed a TDD workflow to write maybe the most polished code of my career.

TDD has always been interesting to me, but it didn't quite click until this past year. While I'm still learning how to best test integrations (particularly with James Shore's nullables technique), it's been confidence-inspiring to code in an always-working state, while improving my understanding of how things work.

Lastly, I finally made the switch to Vim for text editing. Like TDD, I've dabbled with Vim for a while, but didn't fully commit. In the middle of 2022, I tried it again and felt right at home. While I'm still not the most efficient at horizontal movements and more advanced text replacements, most tasks have become muscle memory and really improved the ergonomics of writing and coding.

Side projects

As part of my focus for the year, my side projects played less of a role in 2022.

After collaborating weekly with a past colleague on a major product idea for the past 2 years, we decided to wind the project down in mid-2022 to focus on individual interests.

I haven't created content for Build UX in about a year and a half, as I was staving off long-term burnout. My burnout wasn't specific to content creation, but something had to give. Recently I've been feeling more inspired to create more videos and free educational content, so it's possible this will play more of a role again in 2023.

Although I didn't make formal progress on my larger accessibility course in 2022, creating the smaller course for LinkedIn Learning proved to myself how much I could cover on the topic in the future. This course has definitely been de-prioritized in favor of bringing in consulting income and I'm not sure when or if it'll be my main focus.

Personal life

My personal life in 2022 was defined by investing in long-term improvements and simplifying things as much as possible. Overcoming lingering burnout was a huge relief, and I feel like I'm more organized and productive than ever.

The biggest transformation to my organization, learning, and personal growth has been my second brain. Throughout 2022, I really increased my non-fiction book and article reading, with tens of thousands of highlights feeding into several hundred notes.

I created several hundred more notes from courses, educational videos, and both professional and creative writing. Building a second brain has really changed the way I work and learn by structuring all my thoughts and interests and giving me a central reference to any important information I need in my career and personal life.

Alongside this, I can't understate how helpful therapy has been for my personal growth and self awareness. I wish therapy was accessible for everyone as a standard wellness practice. I'm glad therapy is being de-stigmatized as something everyone can benefit from, even if you don't feel you're unwell or in crisis.

Personal learning

On a lighter note, I really progressed in my mountain biking skills and fitness in 2022. My technique, strength, and cardio were better than ever, and I felt more comfortable on black diamond and pro rating trails as I pushed myself to ride more challenging lines, bigger jumps, and longer sessions.

I also returned to learning Japanese after many years. I studied Japanese throughout college and studied at Doshisha University in Kyoto through the Department of State's Critical Languages Scholarship in 2012. I traveled to Japan in 2016 and 2017, and while a lot of things came back to me after a few days of immersion, my overall speaking skills have really taken a hit. But, I'm now on a 150+ day streak of studying Japanese again, and I feel a lot of my previous knowledge returning. I've been fortunate to have a friend to practice with each week, and it's good to be learning something not directly tied to my professional work.

Going into 2023

I don't place much emphasis on New Year's and I'm not a fan of making specific goals or resolutions. Instead, I try to continuously adjust my values and guiding principles to shift my habits and energy in the direction I want.

For 2023, I would like to continue keeping my professional work focused with just my main client, and saying "no" to other opportunities as the default. I'm fortunate to have 2023 already fully booked, and I'm feeling energized with my work more than ever.

I've been getting a lot of ideas for educational content lately, so that will likely play more of a role again this year.

I'm at an inflection point with two side projects that have some real long-term potential, and I know I will need to choose just one to dedicate my time and learning to. It's going to be a difficult call, but I've over-extended myself enough times to know that it's necessary.

In my personal life, I'm excited to keep investing in my personal growth and organization. 2022 very much felt like laying the foundations for future improvements.

I'll hopefully be traveling to Japan in September, which is really motivating me to take my Japanese learning further. I'm also hoping to do a mountain bike race or two, as I miss the personal challenge I used to get from motocross and desert racing when I was younger.

I feel incredibly fortunate to be where I'm at, and more motivated than ever to make the most of it.

Aquileo | Freelancing, consulting, and coaching

2022-06-03T00:00:00Z

Freelancing, consulting, and coaching

I recently took on a new client that I've been coaching in design, and it got me thinking about how the terminology of freelancing, consulting, and coaching really does define the engagement and working relationship.

Freelance work is often relegated to production with a set scope and deadline. Whether it's true, being a freelancer seems to have the connotation of someone who is assigned well-defined projects that might have smaller scope or quick turnaround. A freelancer might bill hourly, by the word or deliverable, or have a retainer for consistent production targets. If there's an opportunity for value-based pricing, it's usually for projects that again are well-defined with a known deadline.

In my career, defining myself as a freelancer felt like I was limited by unfair client expectations that I could/should only work this way, which led to lots of price negotiating and clients looking for a discount. If I had wider recommendations around processes or an area I wasn't explicitly assigned to, they weren't really welcomed or treated seriously.

The working relationship as a consultant or coach feels very different. Both these roles have the connotation of outside expertise, a fresh perspective, of someone you bring in to help with hard problems, illuminate opportunities and inefficiencies, and give guidance on how to progress.

This leads to one of my favorite quotes:

We give added trust to claims made by external sources.

Actually, I just wrote that. But by framing it as a quote, it seems more objectively and universally true, which proves my point.

What sets apart consulting from coaching in my experience is the level of embeddedness. When I consult for my clients, I strive to basically be a member of the team, and often contribute directly in addition to evaluating, teaching, and advising. With coaching, I'm a bit more removed, asking questions and providing feedback with check-ins or while talking through challenges and recent work. Coaching sessions definitely can involve pairing on things, but it's usually a lighter touch or with the coach acting purely as the navigator.

Consulting and coaching also open the engagement up to high level observations and recommendations about how the work is being done, or if there are opportunities in areas beyond the original focus. I might begin working with a client primarily focused on accessibility, but this can naturally lead to further visual design and performance implications or have wider learnings with how the team is structured and collaborating.

These types of engagements are also better suited for a retainer model or value-based pricing (often at a higher amount), with more flexible scopes and an ongoing timeline.

The connotation of expertise with consulting and coaching is definitely a benefit, but it needs to be handled carefully. The main advantage is clients seek and value your insights and observations, which leads to a much more successful working relationship compared to an engagement where I'm supposed to hand over deliverables without question. This allows me to contribute much more business value, which deserves a higher rate.

There is a risk to this perception, however. Because clients assume consultants have outside expertise, that sometimes means they don't believe there is internal expertise. One of my objectives in working with clients is to ensure that everyone, both leaders and individual contributors, recognize, respect, and praise the expertise across all roles in the team. There may be cultural or process issues that are inhibiting this, but I can use the trust placed in me as a consultant to surface and resolve them.

All this said, it's strange how much these terms define the working relationship, limit or open opportunities, and even affect how much you can charge for the work. As much as I feel that titles and roles are largely superficial and unnecessary, they do really affect the perceived value of our work. Shifting my focus to consulting and coaching over time really did change the dynamics with better work, pay, and impact.

So, if you're a freelancer with clients who don't allow you to bring your full potential, maybe try calling yourself a consultant to switch it up. You work for yourself, so it's not like you need permission.

Aquileo | David Luhr

Aquileo | A 10x engineer isn't what you think

A 10x engineer isn't what you think

The essential 10%

Pairing

How to enable 10x engineers

Aquileo | 10 things I've learned from 10 years of studying lean manufacturing

10 things I've learned from 10 years of studying lean manufacturing

1. Everything is a process

2. There's always a customer

3. Blame the process, not the person

4. Learn to identify and not tolerate waste

5. Stop and fix

6. Make daily improvements

7. Prioritize improvements

8. Mistake-proof

9. Follow one-piece flow

10. Achieve flow

Wrapping up

Aquileo | A deep dive on the UX of number inputs

A deep dive on the UX of number inputs

Enhancing type="number"

Larger increment/decrement amounts

Smaller increment/decrement values

Replacing native spin buttons

Always working state

Allowing math expressions

When to go beyond type="number"

Custom formatting

There's probably more to consider

Aquileo | Tradeoffs with quality, scope, and deadlines

Tradeoffs with quality, scope, and deadlines

1. Fixed deadline, fixed scope, variable quality

2. Fixed scope, fixed quality, variable deadline

3. Fixed deadline, fixed quality, variable scope

Aquileo | Analog productivity

Analog productivity

Physical task management

Hourglass pomodoro

Erasable paper

My analog productivity takeaways

Aquileo | Is the best digital workplace just a bunch of Markdown files?

Is the best digital workplace just a bunch of Markdown files?

Second brain as the workplace

Benefits

Simplicity

Flexibility

Cost

Security

Transparency

Centralization

Lightness, clarity, and calmness

Tasks

My experience applying this approach

Tradeoffs

Wrapping up

Aquileo | The next step in my career: joining Buffer as Senior Design Engineer

The next step in my career: joining Buffer as Senior Design Engineer

Why I'm stepping away from full-time consulting

Why I'm joining Buffer

What's next?

Aquileo | The origins of design engineering

The origins of design engineering

2019

2020

2021

2022

2023

2024

The future

Aquileo | Test-driven development as prompt engineering

Test-driven development as prompt engineering

Issues with common copilot workflows

Benefits of TDD as prompt engineering

Tips

Code comment prompts as code smells

Have a pair programming mindset

Speed and scale are dangerous priorities

TDD is even more important as AI code generators gain adoption

Aquileo | Build-free type annotations with JSDoc and TypeScript

Enhancing `type="number"`

When to go beyond `type="number"`

Myth: `<hgroup>` adds semantic content to headings

Rule: use a single, unique `<h1>` per page

Home link is `<h1>`