Every screen has floors. We don’t usually say it out loud, but we feel it. Some information sits on the ground, foundational, the place you keep returning to. Some belongs upstairs, out of the way until you reach for it. And some floats above everything, a quick alert you glance at and forget.

For a long time I treated information hierarchy as a styling job. Bigger here, dimmer there, more contrast on the thing that matters. A few years ago I started treating it as a spatial one instead, and gave it a single rule: the higher you go, the less information and the less navigation each floor carries.

That rule changed how the whole system felt to use.

The ground floor

This is where people live. In a building it’s the lobby, the shop floor, the kitchen. In an app it’s no different.

The ground floor gets the full screen. Primary tasks, multiple things happening at once, navigation back and forth. It’s the place you return to between everything else, so it earns the most room and most of your design thinking.

Getting this floor right is about generosity. Give it space. Don’t crowd it with things that belong upstairs.

The first floor

The first floor is quieter. You go up there for one reason and you do one thing.

I think of it as offloading. When a ground floor interaction starts to accumulate secondary detail, you send that detail up. The first floor handles it in a single, focused task. It can still use the full screen, but it holds only what’s needed, and navigation goes one way: back down.

There’s something clarifying about that constraint. Whenever I found myself wanting to link sideways between first floor screens, it was almost always a sign I’d sent something up there that belonged on the ground. The floors become diagnostic. The structure tells you when you’ve put something in the wrong place.

The second floor

This is where I had to resist the urge to do too much.

The second floor is for high-level signals only. A status, a notification, a quick number. It takes up roughly a fifth of the screen. It doesn’t navigate and it doesn’t ask anything of you. It tells you something and closes, returning you to where you were.

I kept wanting to add a button. A link. Just one tap to act from here. Every time I did, I was collapsing the floor, asking the second to do the work of the first. The constraint is the whole point.

The research under the rule

This isn’t only a feeling. Two well-documented principles sit underneath it.

The first is Hick’s Law: the time it takes to make a decision grows with the number and complexity of the choices in front of you. That’s the navigation half of the rule. Fewer ways to move on the upper floors means fewer decisions, so the higher you climb, the less there is to weigh up.

The second is cognitive load: the mental effort it takes to understand and use an interface. Every element a person has to process costs something, whether they act on it or not. Thinning the information as you go up isn’t decoration. It’s how you keep the upper floors from quietly taxing someone who only came up to check one thing.

Neither idea is mine. Jon Yablonski has a clear write-up of both at lawsofux.com, and Nielsen Norman Group has written for years about reducing cognitive load. The floors are just a way to put those principles somewhere you can stand.

Practical approaches

You can apply these approaches to help map out and use the different floors for your work.

Why floors work

What surprised me was how much people relaxed once the floors were consistent.

I think it comes down to orientation. When everything can be anywhere, you stay slightly braced, scanning, deciding where to look. When the system has a clear vertical logic, you build a kind of spatial memory for it. You know roughly where you are and what this height of the building is allowed to do. You stop thinking about where to look, and you didn’t have to be told.

The floors don’t make a screen simpler. There’s the same amount of work to do. What they do is make it legible, so attention has somewhere to rest and somewhere to go.

I’m still sitting with how far the metaphor stretches. Whether it holds on small screens, whether it scales to dense, data-heavy tools, whether all interfaces are navigated spatially even when we pretend they aren’t. But every time I get the floors right, the same thing happens. The product stops feeling busy, and starts feeling like a building someone already knows their way around.

The higher the floor, the less it holds was originally published in UX Planet on Medium, where people are continuing the conversation by highlighting and responding to this story.

There is a moment, after something finally works, when I realise I can no longer fully explain it. The feature runs. The buttons do what they should. But if you sat me at a whiteboard and asked me to draw how it all fits together, I would hesitate. The thing exists, and somehow it has already outgrown my memory of it.

This happens more now than it used to. I build faster than I did a year ago, because AI writes a lot of the code with me. That part is real and I lean on it every day. But speed has a quiet side effect. You can arrive at a working system you never fully held in your head.

Working is not the same as understood

A diff is a strange thing to rely on. It tells you what changed, line by line, but it says almost nothing about how the system behaves. You can read every function in a file and still not see the shape of it. What calls what. Where the data flows. Which step quietly runs in the background. What happens when one piece fails.

Code is precise and almost illegible at the same time. It is the most accurate description of a system that exists, and also the hardest one to reason about out loud. That gap, between something being correct and something being understandable, is where most of the confusion in a team actually lives.

For years the only way to close that gap was slow. Someone senior would sit down for an afternoon, trace the code by hand, and turn it into a diagram. By the time they finished, the code had usually moved on, and the diagram was already a little untrue.

Asking the code to explain itself

A while ago I started doing something simple. After the agent built a feature, I asked it to explain the feature back to me. Not as more code. As a map.

I pointed it at one file, a set of Next.js server actions sitting behind a submission detail page, and asked it to draw the architecture from what was actually there. What came back was not a summary. It was a document I could read in a minute and trust.

A high-level flow, drawn in plain boxes, from the client component down through the server action and out to the database. A section on security that made the quiet decisions loud: which queries ran under the user’s session and row-level security, which ran with elevated service-role access, where the service key must never travel. A data flow for each action, step by step. The early exit paths, drawn as a small decision tree. An error handling table that listed every failure point and what the user would see at each one.

None of that was new information. It was all in the code already. But I had never seen it in one place, in language I could hold.

What the map showed

The interesting part is what becomes visible once the shape is on the page.

High-Level Flow

┌─────────────────────────────────────────────────────────────────┐
│              Client Component (check-again-dialog.tsx)          │
│  • User confirms "Check again" in global confirm dialog         │
│  • Calls checkAgainSubmission(submission_id)                    │
└─────────────────┬───────────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                    actions.ts ('use server')                    │
│  • createServer() — SSR Supabase client (user session + RLS)    │
│  • deleteSubmission — hard-delete owned row                     │
│  • checkAgainSubmission — clone row + allowance + side effects  │
└─────────────────┬───────────────────────────────────────────────┘
                  │
        ┌─────────┴─────────┐
        ▼                   ▼
┌───────────────────┐ ┌───────────────────────────────────────────┐
│  User-scoped      │ │  Service-role query helpers                │
│  PostgREST (RLS)  │ │  • checkSubmissionAllowance (RPC)          │
│  submissions      │ │  • insertResubmission                      │
│  delete / select  │ │  • addTimelineEntryServiceRole             │
└───────────────────┘ │  • notifyAdminsNewSubmission               │
                      │  • notifyUserSubmissionConfirmed           │
                      └───────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────────────┐
│              revalidatePath("/user/submissions")                │
│  • Refreshes submissions list cache after mutation              │
└─────────────────────────────────────────────────────────────────┘

Reading the map, I could see things that were invisible while scrolling through functions. Side effects that fire and forget, so a failed notification never rolls back the main write. A monthly allowance check sitting as a gate before anything gets created. A race condition where two requests pass the same gate and a database trigger has to catch the second one. You do not notice these things in a stream of code. You notice them when the flow is drawn.

The code already knew all of this. The map was just how it finally said it to me.

A thing other people can stand in front of

Then I asked for one more step. Turn the map into a board the team can open and edit.

The same process now generates a FigJam diagram from the document, links it back into the markdown, and leaves you with something a designer, a new engineer, or a product manager can move around together. Not a screenshot that goes stale. A living picture of how the thing works, drawn from the code as it actually is. You can open one of these boards here: figma.com/board/dzA7QebkACODLNPK0n8P5u.

I keep coming back to a prototype I built years ago for Transport for London. What changed the room was not my argument. It was that people could stand in front of something real instead of imagining it from a slide. A good architecture map does a smaller version of the same thing. It moves a system out of one person’s head and onto a surface everyone can point at.

When legibility gets cheap

What stays with me is not the diagram. It is how short the path has become.

Producing a clear, accurate map of a system used to be expensive enough that we mostly didn’t do it. We let the understanding live in one or two people and hoped they stayed. Now the cost of drawing that map has dropped close to zero, and it comes straight from the code rather than from someone’s fading memory of it.

I think that quietly changes things. A team can bring someone new up to speed in an afternoon. A designer can finally see the system they are designing for. A group can argue about the right thing, because the shape is on the screen instead of trapped in a single mind.

I turned this into a small Cursor skill called /arch-flow. Point it at a file and it reads the code and draws the map. Ask, and it turns that map into a FigJam board you can share. It is free and open source: github.com/hferello/ai/tree/main/arch-flow.

What I find valuable about AI is not only that it writes the code with me. It writes the code, and it can turn around and explain that code back, clearly enough that other people understand it too. I’m still working out how far that second thing goes. But every time I open one of these maps and see the shape of something I built and couldn’t quite hold, it feels like progress.

The map underneath the code was originally published in Bootcamp on Medium, where people are continuing the conversation by highlighting and responding to this story.

I love AI coding agents. I use them constantly. But there’s a problem nobody talks about enough.

They forget what you’re building.

Every new chat, every new session — the slate is blank. Your agent doesn’t know the product. It doesn’t know the boundaries. It doesn’t know what you’ve already decided.

So you repeat yourself. Again. And again.

Or worse — you don’t. And the agent confidently builds the wrong thing.

I got tired of that. So I built a fix.

Smart tools. Zero memory.

Here’s what happens without product context.

You ask an agent to add a feature. It does. But it also adds three things you never asked for. It picks a library you’d never use. It ignores a constraint you forgot to mention.

The agent isn’t dumb. It’s uninformed.

It’s like hiring a brilliant contractor but never handing them the blueprint. They’ll build something. It just won’t be what you wanted.

One file. Bunch of questions.

I built a Cursor skill called /context. It writes a single file — docs/context.md — that gives every AI agent in your project the context it needs.

No setup wizards. No complex configs. Just a conversation.

Type /context and the agent walks you through bunch of questions. One at a time.

After each answer, the file updates on disk. If your session crashes halfway through, just run /context again. It picks up where you left off.

Not sure? Say “you tell me.”

This is my favourite part.

Don’t know the answer to a question? Just say “you tell me.” The agent researches your codebase and proposes an answer. You confirm it, tweak it, or reject it.

Don’t care about a question? Say “skip.” That section won’t appear in the doc at all.

No filler. No fluff. No guessing.

It pushes back. On purpose.

I didn’t want a polite transcription bot. I wanted a thinking partner.

List ten must-haves and it says: “That’s ten. Pick three you’d ship without the others.”

Give a vague pitch and it says: “I can’t picture it yet — give me a concrete example.”

Describe a feature instead of an outcome and it says: “That’s something it does — but what does the user actually get?”

This isn’t rudeness. It’s rigour. A tight context doc is worth ten sloppy ones.

The red team

After all nine questions, the skill does something unexpected. It turns on you.

Not maliciously. Constructively.

It re-reads the whole document as a critic. It checks for contradictions, hidden complexity, and scope creep. Then it goes deeper — challenging assumptions and suggesting simpler alternatives.

Things like: “Is this must-have actually three features in a trenchcoat?”

Or: “You’re anchored on one approach. Have you considered this instead?”

Clear issues get fixed on the spot. Judgment calls come back to you as questions. It’s the week-two realisation — compressed into five minutes.

What the output looks like

Here’s a real example from a receipt-tracking app for freelancers:

# Product Context

> **One-liner:** Snap a receipt, auto-categorise the deduction,
> export at tax time.

## Mission
Help solo freelancers stop losing track of expenses
so tax time isn't a scramble.

## Must-Haves
1. Snap/upload receipt → auto-extract vendor, amount, date
2. Assign a tax category (meals, travel, supplies, etc.)
3. Export year-end summary as CSV

## Out of Scope
- Invoicing or billing
- Multi-user / team accounts
- Tax filing or tax advice

## Success Criteria
- Receipt-in-hand to expense-logged in under 10 seconds
- 80%+ OCR extractions need zero correction
- One freelancer uses it a full quarter
  without reverting to spreadsheets

Short. Specific. Actionable. Every section is something an agent can actually use to make better decisions.

The rule that ties it together

The context doc is half the system. The other half is a project rule.

You install a small .cursor/rules/context.mdc file into each repo. It tells every agent: read docs/context.md before doing anything significant.

Three things follow from that. Agents ship must-haves and push back on out-of-scope requests. If your request contradicts the doc, the agent flags it: “The context doc says X. You’re asking for Y. Which wins?” And if there’s no context doc and the work is big, it suggests running /context first.

The rule lives in the repo, not in your global config. It travels with the code. Everyone on the team gets the same guardrails.

Install it in 30 seconds

Install the skill (once per machine). Open a terminal in Cursor and run:

git clone --depth 1 https://github.com/hferello/ai.git /tmp/cursor-skill \
  && bash /tmp/cursor-skill/context/install.sh \
  && rm -rf /tmp/cursor-skill

Restart Cursor.

Install the project rule (once per repo). From your project, run:

bash /path/to/context/install-project-rule.sh .

Commit .cursor/rules/context.mdc so the whole team gets it.

Then open Agent chat, type /context, and start answering.

Why this matters

AI agents can build almost anything now. The catch: they still don’t know what they’re building unless you tell them. Every. Single. Time.

That’s the gap /context fills.

One conversation. One file. Every agent in every session stays aligned.

No more repeating yourself. No more rogue features. No more “wait, that’s not what I wanted.”

Just clarity. In five minutes.

The skill is open source. Grab it, try it, break it, make it better.

GitHub: github.com/hferello/ai

There’s a moment in an emergency when the world narrows.

Not metaphorically. Literally. Your peripheral vision contracts. Sounds flatten into background noise. The only thing that exists is the thing directly in front of you. Psychologists call it perceptual narrowing. The psychologist [J. A. Easterbrook described the mechanism back in 1959](https://doi.org/10.1037/h0047707): as emotional arousal rises, the range of cues we can take in shrinks. Your brain, under threat, stops processing what it deems unnecessary and concentrates everything on survival.

I think about this a lot when I’m designing screens.

f22 — everything in focus

A camera lens at f22 keeps everything in focus. The foreground, the background, the blurry figure at the edge of the frame. Every element competing equally for your attention.

Most apps are designed at f22.

Hence a wealth of information creates a poverty of attention
 — Herbert Simon, 1971

Every button visible. Every option available. Every notification badge clamouring for a glance. There’s a kind of democratic logic to it, an idea that giving users everything means giving them control. But control and cognitive load aren’t the same thing. One is a feeling. The other is a measurable weight.

When I worked on an Australian Police Service app, we were designing for over 11k officers across a state the size of Western Europe. The brief was straightforward: make them more efficient. But the deeper we went into the research, the more the real question came into focus.

What does it cost someone to use a bad interface at the wrong moment?

Two officers, one screen

We did field research. Clipboards in hand, watching officers work. Not in a lab, but in the actual conditions of their days.

What became obvious quickly was that the same officer, the same person, the same hands and eyes and brain, was a different user depending on where they stood. At a desk finishing a report, they were calm, methodical, patient with complexity. In the field, mid-incident, moving or in a vehicle, their stress was elevated and their tolerance for visual noise had collapsed.

The interface didn’t know any of this. It presented itself the same way regardless.

This felt like a design failure. Not a feature gap. A philosophical one.

f2.8 — the aperture shifts

A camera at f2.8 does something beautiful and strange. It pulls one thing into sharp relief and lets everything else dissolve. The background doesn’t disappear, it just stops asking for your attention.

It implies withdrawal from some things in order to deal effectively with others.
 — William James, The Principles of Psychology, 1890

We built this into the UX stress model. As an officer’s stress increased, the interface contracted. Non-essential elements receded. Choices narrowed. The screen stopped being a dashboard and started being a torch.

The metaphor came from photography but the logic is neurological. When the brain is under load, every additional decision has a cost. Hick’s Law tells us that the time to make a decision increases with the number of options. But that’s in a neutral state. Under stress, the relationship isn’t linear. It compounds. The Yerkes-Dodson law, first described in 1908, gives that curve its shape: performance climbs with arousal up to a point, then falls away, and the more complex the task, the sooner the fall begins.

George Miller wrote in 1956 that the human mind can hold roughly seven items in working memory, plus or minus two. That was in a quiet room with a willing participant and no stakes. Put a person in a car responding to a call and that number shrinks considerably. A 2016 meta-analysis of acute stress and executive function found the same thing in the lab: across fifty-one studies, stress reliably impaired working memory.

Don Norman has spent a career making the same point from the design side. Negative affect “focuses the mind,” he writes, and under threat that focus collapses into “narrow, tunnel vision.” His conclusion for anyone building tools for those moments is blunt: they “are best served by designs that emphasise function and minimise irrelevancies.” A torch, not a dashboard.

What we don’t design for

Here’s what bothers me, the thing I keep coming back to.

Most UX design is optimised for a calm user. The personas we build, the testing we run, the environments we simulate. Someone seated, unhurried, with full cognitive resources available.

We design the f22 version of an interface and then we wonder why it breaks down under pressure.

Stress isn’t an edge case. It’s a condition of use. A parent navigating a hospital app with a sick child in their arms. A driver trying to follow directions in an unfamiliar city at night. A person rereading the same sentence in a financial document because they’re scared of what it says.

These aren’t unusual users. They’re all of us, on a bad day, when the stakes are real.

Practical methods to shift between different stresses

Stopping down the aperture comes down to a handful of concrete moves, each one a different degree of pulling something out of focus.

1. Desaturate the unimportant: Drain the colour from elements that aren’t central to the task, so the eye has less to catch on as it scans the interface.

2. Reduce the opacity of the secondary: Fade back elements that support the task without driving it, so they settle a layer beneath the thing in focus. Present enough to find, quiet enough to ignore.

3. Remove the nice-to-have entirely: Anything that lives in the optional category can go when stress is high. The most reliable way to lower cognitive load is to have less on the screen in the first place.

4. Blur what falls outside the task: Let elements that don’t belong to the current workflow soften into the background. They still exist, they just stop asking for attention.

5. Move into its own layer: A modal or a separate screen takes a secondary task out of sight, so the user can stay with the one that matters. A full-screen step usually beats a partial one, because it removes the surrounding noise instead of competing with it. The only context worth preserving is the kind that isn’t obvious, like where a deep link dropped someone.

6. Shift things visibly, with motion: When you move an element elsewhere, animate the change so the user sees it hasn’t vanished, only relocated, and can be reached again when they need it.

What the camera knows

A photographer chooses their aperture deliberately. Wide open for intimacy. Stopped down for clarity. The choice shapes what the viewer sees and what they’re allowed to let go.

We don’t talk much about interface design in those terms. About what we’re choosing to keep in focus and what we’re allowing to blur. About the responsibility that comes with putting something in front of a person who is already carrying more than they can hold.

I’m not sure we’ve fully reckoned with that yet. The tools exist. The research is there. Miller, Kahneman, the whole field of cognitive load theory stretching back decades.

Something else is missing. An acknowledgement, maybe, that the person holding the screen is not always fine.

That sometimes they’re at f2.8 whether we planned for it or not.

References

Perceptual narrowing under arousal. Easterbrook, J. A. (1959). The effect of emotion on cue utilisation and the organization of behaviour. Psychological Review, 66(3), 183–201. https://doi.org/10.1037/h0047707

Attention as selective withdrawal. James, W. (1890). The Principles of Psychology, Vol. 1, Ch. 11, p. 404. http://www.yorku.ca/pclassic/James/Principles/prin11.htm

The attention economy. Simon, H. A. (1971). Designing organizations for an information-rich world. In M. Greenberger (Ed.), Computers, Communication, and the Public Interest (pp. 37–72). Johns Hopkins Press.

Arousal and performance, the inverted-U. Yerkes, R. M., & Dodson, J. D. (1908). The relation of strength of stimulus to rapidity of habit-formation. Journal of Comparative Neurology and Psychology, 18, 459–482. Overview: https://en.wikipedia.org/wiki/Yerkes-Dodson_law

Decision time and the number of choices. Hick, W. E. (1952) and Hyman, R. (1953), together the Hick-Hyman Law. Plain-language summary: https://lawsofux.com/hicks-law/

The limits of working memory. Miller, G. A. (1956). The Magical Number Seven, Plus or Minus Two. Psychological Review, 63(2), 81–97. Summary: https://lawsofux.com/millers-law/

Stress impairing working memory. Shields, G. S., Sazma, M. A., & Yonelinas, A. P. (2016). The effects of acute stress on core executive functions: a meta-analysis and comparison with cortisol. Neuroscience & Biobehavioral Reviews, 68, 651–668. https://pmc.ncbi.nlm.nih.gov/articles/PMC5003767/

Cognitive load. Sweller, J. (1988). Cognitive load during problem solving. Cognitive Science, 12(2), 257–285. For the design application: Nielsen Norman Group, “Minimize Cognitive Load to Maximize Usability.” https://www.nngroup.com/articles/minimize-cognitive-load/

Affect, focus, and tunnel vision. Norman, D. A. (2002). Emotion & design: attractive things work better. Interactions, 9(4), 36–42. https://jnd.org/emotion-design-attractive-things-work-better/

Attention as a finite resource. Kahneman, D. (1973). Attention and Effort. Prentice-Hall.

Designing for the Wrong User was originally published in UX Planet on Medium, where people are continuing the conversation by highlighting and responding to this story.

There’s a question I kept coming back to while designing. Not philosophically. Practically. When someone on the team asks why the spacing is 24 and not 20, what do you say?

“It felt right” is honest, but it doesn’t travel. It doesn’t survive a handoff, a new hire, a design system that has to outlast the person who made it.

I started building a number system to try to answer that question. Not for anyone else, at first. Just to see if I could make something where the answer was always there.

The first was 8

Before anything else, there was a base unit. 8.

It has practical advantages that are easy to explain. It multiplies cleanly. It scales perfectly across iOS and Android, including the edge cases like Android’s @0.75 and @1.5 displays. Icons built on an 8pt grid don’t break when the resolution changes.

It made sense to use this as the starting point for everything that followed.

Typographic ratios

The first library was typographic. A number system built around the classical type scale, sizes that have been used in print, on screens, in every medium type has ever lived in.

What I noticed is that the sizes didn’t need justifying. They arrived already related to each other, the way notes in a musical scale are. There’s a prearranged harmony to them, accumulated over centuries of people working out what the eye finds natural.

Starting from a scale with that kind of history means you’re not making decisions from scratch. You’re inheriting hundreds of years of visual reasoning.

That felt worth understanding better.

Single-root scaling

The second library came from a different direction. I wanted to understand what it would look like if every value in a design system, spacing, typography, layout, was derived from a single root.

From the base of 8, each step in the scale is roughly 1.618 times the last. That ratio, φ, gave me a single multiplier to derive every value from one root. Whether the ratio itself matters less than I expected is part of what I’m still sitting with. What I was actually after wasn’t beauty by formula. It was traceability. Values that connect back to something, rather than values that connect back to nothing.

The number system gives you horizontal and vertical rhythms too. All text flows along a baseline derived from the same logic. The grid follows. Icons follow. Everything moves from the same root.

Base 10

The third library went the other direction entirely.

Base-10 spacing. Multiples of ten, with mid-steps for finer control. 10, 15, 20, 25, 30. Values that are easy to hold in your head and easier to apply consistently across a team.

There’s no Fibonacci here, no golden ratio. The logic is just legibility. Sometimes a designer needs to move quickly, or hand something off to someone who doesn’t want to think about ratios. Sometimes the math is just clarity.

It belongs in the same family as the others because it answers the same question. Where does this value come from? Here the answer is: somewhere everyone can follow.

Colour was the missing piece

Most design systems treat colour scales as a separate problem. You pick some percentages, you generate a palette, and you call it done. The logic that governs spacing doesn’t touch colour at all.

That disconnection bothered me more the longer I worked on it.

I wanted to know what happens when you apply the same proportional thinking to colour directly. HSB colour, specifically, hue, saturation, brightness, because it’s the model that maps most naturally to how we actually think about colour. Hue is the position on the colour wheel. Saturation is how much colour is injected into white. Brightness is how much the lightbulb is turned on. It’s intuitive in a way that RGB, which describes what a screen is doing, is not.

I started working through the idea in a conversation with Claude. At some point, the concept was fully formed in the exchange. The logic, the maths, the expected output. It just didn’t exist as anything I could point to yet.

So I asked it to turn the conversation into a working HTML page. Brought it into Cursor to finish the job. Pushed it to GitHub.

One sitting. From a thought I could only describe to people, to a tool with a URL anyone could open and use.

Names instead of numbers

I didn’t stop at Figma. The same three token sets are available as an npm package. Install them, import a single CSS file, and the values are in your project.

The spacing scale uses names instead of numbers. gap-section, p-loose, m-apart. Because the relationship between elements matters more than the pixel value. The number follows from the ratio. The name follows from the intent.

Each library compiles into three files. Raw primitives. A semantic layer with dark mode. And responsive breakpoints that adjust type and grid automatically across desktop, tablet, and mobile. It works with Tailwind v4 or as plain CSS variables.

The question that outlasts you

The thing these libraries share isn’t a visual style or a set of rules. It’s a way of asking a question before you make a decision.

Where does this value come from?

What I’ve found, working through each one, is that the question gets easier to answer the more the values are connected. Not because you stop making judgement calls, you still do, but because the judgement calls are fewer and more considered.

The specific foundation matters less than I thought it would. Fibonacci, base-10, a classical type scale. What they share is that they’re all answerable. Someone new to the project can ask why the spacing is 24 and not 20, and the answer is there waiting for them. It doesn’t depend on the person who chose it still being in the room.

I’m still not sure whether full proportional consistency across a system produces something that actually feels better to use, or just satisfies a kind of theoretical tidiness. I haven’t resolved that yet. It’s part of why I keep building.

Grab them free from Figma Community:

• Typographic ratio — Design library by Hal
• Golden ratio — Design library by Hal
• Base-10 ratio — Design library by Hal

NPM package:
https://github.com/hferello/design-libraries-npm

Design library site:
https://hferello.github.io/design-libraries/

Most spacing scales start with a list. 4, 8, 16, 32. Or 10, 20, 30. Chosen because they divided cleanly, or because someone else used them, or because they just felt right. I’ve built plenty of those scales myself. They worked. But I could never quite explain why the gap was 24 and not 20.

“It looks balanced” is true. It’s also useless.

What I was actually describing

I’ve been building a set of design token libraries, each one grounded in a different proportional system. The idea is that every value in a design system should trace back to something, so when someone asks “why is the spacing 24 and not 20?” the answer is already there.

When I got to spacing, I assumed it would be the easy part. Each system produces a clean sequence with its own logic underneath. Plug in the formula, get the values, done.

What I found instead was that the numbers were almost beside the point.

Every spacing decision is a decision about relationship. When I place two elements flush against each other, I’m saying: these are one thing.

When I pull them apart by a small breath, I’m saying: these belong together, but they’re distinct.

Keep going and eventually the message changes completely. These exist in different contexts. These are unrelated. A large gap doesn’t just mean more space. It means something different.

I kept adjusting values by a pixel or two, trying to get something to “feel right”, and what I was really doing was trying to get the sentence right. The gap was saying something, and I couldn’t rest until it matched what I meant.

I’d always had a sense for proximity. But it took building my own system to stop reaching for pixel values and start designing in relationships.

The scale built itself

Once I saw it that way, the spacing system stopped feeling like a list of numbers and started feeling like a vocabulary. Each step is a word with a meaning: flush, tightly paired, loose group but breathing room, new section, unrelated, structural separation.

The sequence isn’t just about quantity. It’s about what you’re communicating at each level. And when you name it that way, the next value isn’t arbitrary. It follows from what you’re trying to say.

The numbers are still there, grounded in a proportional system so they scale consistently across devices and contexts. But they’re downstream of the meaning. Not the other way around.

The question underneath the question

I’ve been thinking about why this took me so long to name.

There’s something about how the eye parses the world that we rarely talk about in design. We do it with music all the time. A rest between two notes isn’t silence. It’s tension, or release, or the space where meaning lands. Shorten the rest and the phrase rushes. Lengthen it and the notes become separate thoughts. The gap is doing as much work as the sound.

Spacing on a screen works the same way. Gestalt psychology calls it the law of proximity. Elements that are close together get perceived as belonging together. We do this automatically, without thinking, before we’ve read a single word on the page. It’s one of the primary signals the brain uses to understand structure.

So when you place two elements with 4px between them, you’re not making a layout decision. You’re making a cognitive one. You’re telling someone’s brain: these are related. When you use 64px, you’re saying: these are not.

I keep coming back to that. The pixel value is a means. The relationship is the message.

I’ve always been drawn to the moment an idea stops being abstract and becomes something physical. A sketch on paper. A prototype you can click through. A tool someone else can open and use. There’s a shift that happens in that transition, something changes in how you understand your own thinking when it exists outside your head.

The idea

I’ve been building a mathematical design library in Figma where every value is proportionally connected to the next. Spacing, typography, layout. All of it derived from a value (e.g. 1.618 or φ), the same proportional logic found in nature, architecture, and music. If we trust these proportions for the Parthenon and for musical harmony, why not for the systems that power our digital interfaces?

But I kept hitting a wall with colour. Most design systems treat colour scales as a separate concern. You pick a brand colour, then generate tints and shades using percentage-based formulas. Lighter by 10%, darker by 20%. The numbers are arbitrary. They work visually, but they’re disconnected from the proportional logic governing everything else.

I wanted to know what happens when you apply φ to colour directly.

Thinking out loud

I started working through the idea in a conversation with Claude. HSB (Hue, Saturation, Brightness) felt like the right colour model because it maps most naturally to how we perceive colour. Hue is the colour itself. Saturation is its intensity. Brightness is how much light it carries.

The question was simple: what if saturation stepped down by φ from a base colour? Take #FF0000, pure red, at full saturation. Divide by 1.618 at each step. You get 100 → 61.8 → 38.2 → 23.6 → 14.6 → 9.0 → 5.6 → 3.4 → 2.1.

At some point during the conversation, I realised the idea was already fully formed in our exchange. The logic, the maths, the expected output. It just didn’t exist as anything I could point to yet.

Making it real

So I asked Claude to turn our conversation into an HTML page where I could plug in any mathematical formula across the three HSB channels. That single request gave me a working tool. Not a mockup or a wireframe, but a functional colour scale generator.

I brought it into Cursor and used Sonnet and Composer agents to finish the job. Light/dark mode. Better typography. Cleaner file separation. The kind of detail work that turns a rough prototype into something you’d actually want to share.

The whole thing is now a GitHub page. Pick a base colour, write a formula for each channel, and generate a scale. There are presets to get you started, three different views, and export options for hex, CSS variables, Figma tokens, and JSON.

Try it here: hferello.github.io/colour-scale

The distance between thinking and making

What stays with me about this experience is not the tool itself. It’s how short the path was from having the idea to holding the finished thing.

I’ve had versions of this concept in my head for a while. Mathematical colour scales, φ applied to every channel of HSB. But it lived as a thought, something I could describe to people but couldn’t show them. In one sitting, through conversation alone, it became something physical. Something with a URL. Something someone else can open, use, and build on.

I think this is what changes when the cost of making things drops close to zero. The ideas that used to sit in notebooks and voice memos and half-finished Figma files start becoming real. Not because the technology is impressive, but because the gap between “I think this could work” and “here, try it” gets small enough that you actually cross it.

For me, this small tool is one piece of a bigger question I keep coming back to. If mathematical proportion governs the structures we find beautiful in nature, what happens when we let those same proportions govern every layer of a design system? Not just spacing and type, but colour, motion, opacity, everything.

I don’t have the full answer yet. But now I have a tool to keep exploring, and that feels like progress.

From idea to something you can hold was originally published in Bootcamp on Medium, where people are continuing the conversation by highlighting and responding to this story.

I’m a designer who codes a bit. I’ve dabbled in PHP, HTML, and CSS over the years, but always at a beginner level. Nothing that would prepare you for building a full-stack platform from scratch.

And yet, that’s exactly what I did. I spent 6 months building Play Hopper; a platform that connects families with local playgroup organisers for children’s activities. A real product, with real users, real payments, and real edge cases.

But here’s the thing that surprised me the most. The skills that carried me through this weren’t the ones I learned along the way. They were the ones I already had.

System thinking → Data modelling

When I sat down to design the database schema for Play Hopper, I expected it to feel completely foreign.It didn’t. It felt exactly like designing a complex information architecture.

I needed to model a world where organisers create events, events generate sessions, sessions accept bookings, bookings belong to adults who have children, children have age ranges that determine eligibility, and sessions have capacity limits that differ depending on whether you’re counting adults only or adults plus children. There are waitlists that promote automatically, voluntary “give my spot away” flows, and bookings that can be cancelled, refunded, or converted from waitlist entries. Each with its own financial implications.

Sound familiar? If you’ve ever designed a complex IA. The kind where you’re mapping out content types, taxonomies, relationships, and states across a large-scale product. You’ve done this before! You’ve just never called it “data modelling.”

Entities are content types. Relationships are the lines between them. States are the statuses that change how the UI renders. The thinking is identical; you just express it differently. Instead of a sitemap, you write a schema. Instead of a content model in a spreadsheet, you write it in TypeScript with Drizzle ORM.

But the cognitive work, the part that actually matters, is the same.

Edge case obsession → Error handling

If there’s one thing designers are trained to do, it’s obsess over states. Not just the “happy path”, but the empty states, the error states, the loading states, the partial states, the “something went wrong but we don’t want the user to panic” states. We sketch them. We prototype them. We argue about them in design reviews.

It turns out, engineering needs the exact same obsession.

What happens when two parents try to book the last spot in a session at the same time?

One succeeds. The other needs to land on a waitlist — seamlessly, without a confusing error message.

And if the first parent cancels? The waitlisted parent should get promoted automatically, notified via email, and the booking should be flagged as a waitlist conversion for the organiser’s analytics.

That’s not just code. That’s experience design for a system you can’t see.

The same thinking popped up everywhere:

1. What if a Stripe webhook is delayed?
   I built a checkout session verification function as a safety net, with a delay mechanism to give webhooks time to process before falling back to manual verification.
2. What if a user opens a magic link in a different browser?
   I refactored the authentication flow to use token first, with a legacy fallback, so the login works regardless.
3. What if an organiser needs sessions that don’t follow a recurring pattern?
   I added a “custom” frequency option, letting them manually manage sessions outside of automatic generation.

Every single one of these started as the same question designers ask every day: ”But what happens when…?”

User flows → System flows

Before I wrote a single line of booking logic, I mapped the entire booking process as a user journey. Step by step. Screen by screen. Decision by decision.

What does the parent see first? How do they select a session? What happens if the session is full? What if the event is free versus paid? What if there’s a late booking fee? What if the child’s age doesn’t match the event’s eligibility criteria? What does the confirmation look like? What email do they receive?

I mapped all of this out as a flow; the way designers do.

And when it came time to implement? The user journey became the engineering spec. Each step in the flow became a function. Each decision point became a conditional. Each screen became a component. The flow I’d already designed told me exactly what to build and in what order.

This pattern repeated across the entire platform:

Organiser onboarding flow

From signup to profile creation to event setup to going live, this was a user journey before it was a series of database mutations and action server calls.

The account deletion flow

Requiring confirmation, notifying affected users, soft-deleting records, and cleaning up storage. It was designed as a careful off-boarding experience before it became a cascade of database operations.

The user journey is the system architecture. Designers just don’t always realise that’s what they’re producing.

What “designing with AI” actually means

There’s a conversation happening right now about designers and AI. Most of it focuses on the surface: swap Figma for an AI prototype tool, generate mockups faster, use AI to write copy.

That’s fine. But it misses the point.

The real opportunity isn’t about replacing one design tool with another. It’s about going deeper into the system. And when you understand the system well enough, you start making decisions that no AI tool can make for you.

Optimise how data loads

I implemented lazy-loaded charts with React Suspense, replaced <img> tags with Next.js <Image> for automatic optimisation, and built tab-based session navigation with URL state management so users can bookmark specific views. These aren’t designer decisions or engineer decisions. They’re experience decisions that require understanding both sides.

Choreograph interactions that genuinely delight

Waitlists: When a waitlisted parent gets promoted to a confirmed booking, the UI transition matters. When a booking card shifts to “cancelled,” the grayscale styling communicates status before the user reads a single word. These are design decisions made at the system level.

Make architectural decisions with intention

Capacity count mode: a real architectural decision where a UX insight (“some organisers count capacity by adults only, others count adults and children together”) became a single schema field that cascades through the entire platform: booking validation, waitlist logic, search results, map pins, event forms, and analytics.

Observation → architectural choice → system adapts.

This is what it actually means to design with AI as your collaborator.

Not delegating the thinking, but elevating it. You use AI to handle implementation velocity while you focus on the decisions that shape the experience: the data model, the edge cases, the flows, the architecture.

The evidence is in the details

If you want to know whether design thinking translates to engineering quality, look at the details:

Inclusivity

Full ARIA support, semantic <fieldset> and <legend> forms, keyboard-navigable autocomplete. This wasn’t an afterthought. Accessibility is a design discipline, so it was designed in from the start.

Invisible design

Google Calendar integration needed automatic create, update, and delete across sessions. Manual sync for missing events. Connection status management. Race condition fixes. It’s a complex system integration, but the design question was simple:

How should an organiser’s calendar stay in sync with their sessions without them thinking about it?

Building trust

With environment-aware rules, bot detection on signup and login forms, token-based authentication with cross-browser fallback. Security as a design constraint, not an engineering bolt-on.

Hundreds of edge cases handled. A platform that went from zero to production with one person. A designer. Making every decision.

Designers have always been systems thinkers

The gap between design and engineering isn’t as wide as our industry pretends. The cognitive skills are remarkably similar.

The difference is syntax, not thinking.

System thinking, edge case obsession, user flow mapping; these aren’t skills that become irrelevant once you open a code editor. They’re the hardest skills in the entire process. Knowing what to build, why to build it, and what happens when things go wrong; that’s the hard part.

And designers are already trained for it.

AI is accelerating this convergence. When AI handles more of the syntax; the boilerplate, the configuration, the “how do I do X in framework Y” questions.

What’s left is the thinking.
The architecture.
The decisions.
The empathy for the person on the other side of the screen.

Designers have always been systems thinkers. We just have new systems to design.

Design thinking is the AI superpower was originally published in Bootcamp on Medium, where people are continuing the conversation by highlighting and responding to this story.

It feel like a magic using coding agents to build something. Getting started with a simple prompt “make me this” can seem like the right way to build, scrappy now, fix later.

Generally, when you look at how successful teams operate, they structure their work: discover the problem, understand their users, what are the goals, what is out of scope, etc.

All these decisions help build value for the user.

Keeping track of a feature can become trickier though: break it into tasks, design this, conversation there, decisions get made on the fly, edge cases surface. The original intent can get lost somewhere between the brief and the pull request.

It’s no different with coding agents, but they lose context of what they’re supposed to be doing, but much quicker.

Agents build first. Think never.

AI coding agents make this worse.

Give an agent a prompt and it starts producing immediately. Components. Logic. Layouts. Full speed, no questions. It doesn’t ask who the feature is for. It doesn’t consider what happens when something breaks. It doesn’t check whether what you asked for is actually what you need.

What good teams do differently

The best teams I’ve worked with do one thing before anyone writes a line of code. Someone slows everything down and asks the uncomfortable questions.

Not in a doc that lives in Notion. Not in a ticket nobody reads. Right there, before the work starts:

• What problem does this actually solve?
• Who is it for?
• What does success look like?
• What are we explicitly not building?
• What breaks if we get this wrong?

That conversation shapes everything that follows. Skip it and you’re building on assumptions.

So I built that conversation into the tool

I created a small open-source add-on for Cursor called /feature. Run /feature "checkout-flow" and it doesn't start building. It starts asking.

One at a time. You can answer, skip, or push back on any of them

The point isn’t to fill out a form. It’s to make sure the agent and you actually understand what’s being built before a single line of code is written.

Download it

The thinking lives in the files

Once the questions are answered, /feature creates a set of files directly inside your project under features/<task-name>/:

• task_plan.md — the work broken into phases, with status tracking
• findings.md — research and discoveries along the way
• progress.md — a session log so nothing falls through the cracks
• documentation.md — what was built and how it works
• prd.md — the full requirements, built from your answers

These aren’t planning documents that live outside the work. They live inside the project. They travel with the code. They’re as much a part of the feature as the components themselves.

It criticises itself

After the files are created, the agent switches roles and starts reviewing.

It re-reads everything with one goal: find the problems before the build does.

• Do the goals, user stories, and requirements actually align?
• Are there edge cases implied by the stories but not listed anywhere?
• Did scope quietly grow beyond the original brief?
• For UI work: missing error states, empty states, accessibility gaps?

But it goes further than a checklist. It challenges the thinking behind the plan.

“Is this must-have actually three features pretending to be one?”

“You’re anchored on one approach — have you considered this simpler alternative?”

“What is this assuming about the user that might not be true?”

Clear issues get fixed on the spot. Judgment calls get surfaced with context and a recommendation. It’s the feature review you’d normally do on day three.

Why this matters for product teams

We think in flows, states, and outcomes. We see the whole picture from the start.

But hand an idea to an AI, or sometimes even to a team, and the nuance evaporates. The feel gets lost. The why gets lost. What comes back is something that technically works but misses the point entirely.

/feature doesn't fix that completely. But it forces the conversation that usually gets skipped. And it keeps a record of that conversation inside the project.

The plan isn’t separate from the feature. It is the feature.

Try it

Open source, free, one-line install:

git clone --depth 1 https://github.com/hferello/ai.git /tmp/cursor-feature-skill && bash /tmp/cursor-feature-skill/feature/install.sh && rm -rf /tmp/cursor-feature-skill

Restart Cursor, type /feature "your-task", and see what happens when an AI agent plans before it builds.

Check it out on Github: https://github.com/hferello/ai/tree/main/feature

Inspiration

The workflow and “plan with living docs” idea for this skill take their cue from planning-with-files (Othman Adi). Thank you 🙏

Build in Features, Not Plans. was originally published in Bootcamp on Medium, where people are continuing the conversation by highlighting and responding to this story.

The queue to the rollercoaster — before Aston

When we first found that my wife, Jodie, was pregnant, I felt a sense of calm and imagined the many moments we’ll have together as a family. She sat me down, and it felt like a therapy session at the time “Hal I think I’m pregnant”. It was hard to express my emotions. Finding out painted a variety of different feelings and questions. Will I be able to help? Can we financially have a baby? Will I be a good enough dad? What does it mean for our relationship?

In my heart, I knew I was ready to be a dad, though. Somewhere in there, I thought, “Yeah, this is the right time”. As the days went by, I was able to process it and become more and more excited. :excited:

Organising life before the chaos

My prepping mind went into gear, and I read several blog posts about how we can best prepare and understand what to expect. While the baby was still inside and we had time, I decided to organise the next 12 months into a Trello board. My wife loved this as she was able to ask the right questions to doctors and midwives and ensure we’re on the right(ish) track.

Flat floor

We also used this time to get our place clean and as tidy as possible. Keeping Aston’s stuff nearby when we needed it. We also decided to change him on the floor as it would give us more time to interact with him.

The many little things

A baby’s skin is more transparent during the first few months, and so it becomes easier to do scans of all the different organs and bones. We saw Aston yawn, stretch, and roll. :loveit: My connection with him grew so much at this point.

Unwinding before Baby — the Babymoon

We decided to go on a three-week holiday around the Great Ocean Road before Aston came into the world. One, we are digital nomads at heart. We love being in different places and exploring different cultures and spaces. Two, our mobility will be greatly limited with a newborn to a small radius around our local area (more than we realised, as we initially thought we would be fine travelling with a baby). This was a great way for us to get out of the routine of being at home and it gave my wife, Jodie, a chance to exercise along beautiful coastal walks.

💺 Getting onto the rollercoaster — birth

By far the craziest experience I’ve ever been through. So many things to bring, so many things to think about. Jodie’s early labour was very long, over 30 hours. At the time, we were watching the men’s final for the Australian Open. Jodie slipped out before the last game. Again, she sat me down like a therapy session and said “Hal I think I’m going into labour soon.” As time passed, things got more serious, we drove to the hospital and Jodie’s water broke in the car. It felt like a rom-com scene, well, in my head, I’m not sure Jodie thought it was in any way comical… She decided to have a water birth and I’ll save you from all the details, but it was like the movie “Everywhere everything all at once”, at least for me it did. Luckily, Jodie didn’t have any complications, and they were at home the next day. The 15-min drive home from the hospital was the longest drive of my life! I was probably doing 15kph the whole way there 😅 🐌

🎢 Riding the rollercoaster — after Aston

My life was forever changed when I first held Aston in my arms. The first week was fantastic; he was asleep for most of it. We thought this would be a breeze! Then came the second week, when he started learning to cry. We realised ohhhhh this is what it’s really like. Sleepless nights, nappy changes, and learning the ropes of caring for a fragile little life can be overwhelming, but these moments were also filled with love and bonding that created a strong foundation for our family.

Innate self-development

I loved seeing how Aston naturally developed things he needed to do during each milestone, like learning to make eye contact, holding his head up, holding things and smiling at us. For the first six weeks before he smiled felt so much harder. When that first smile came, oh wow, we were over the moon. It’s like your manager giving you great feedback! His self-development reminded me of a book by Carl Sagon called the Dragons of Eden, which explains how the human brain works and how it’s structured. I started to embrace the learning curve of parenthood by adapting and constantly growing alongside Aston. It also meant recognising that there’s no perfect parent and that it’s okay to make mistakes. I saw early on that it was important to learn from him and strive to be the best parent I can be.

Easing into life

We were cautious new parents during the first few weeks. A 10-min walk is all we could manage at the beginning. We slowly started to get out for longer and longer trips over the next couple of months. Each time he had more exciting things to see. We even managed a two-hour drive to stay a night in the Blue Mountains. They became unforgettable moments that filled our hearts.

Learning to keep all my plates spinning

Being a parent comes with many challenges. Balancing work, family, and personal growth can sometimes seem difficult. Finding ways to maintain a healthy balance is essential by prioritising quality time with Aston, setting boundaries at work, and carving out time for self-care. With this approach, I hope to be better equipped to handle the challenges I might face on this rollercoaster.

Copy and paste

Children naturally copy their closest humans — usually their parents! This means I play a vital part in shaping his values, beliefs, and attitudes. I’ve always believed in demonstrating qualities like kindness, patience, and resilience, and I have been taught these lessons many times in my life. I hope I can pass these essential life lessons on to Aston. My actions, whether big or small, might have a lasting impact on his life, so I promise to strive to be the best role model I can be.