OhNine's first-run screen went through three full rewrites before I let it ship
Version one explained the tool, version two explained nothing, version three explained one thing
The rule that finally worked: a first-run screen earns the right to say exactly one sentence
Every RAXXO tool now gets the same one-sentence test before its onboarding ships
Version One: The Screen That Explained Everything
OhNine is a menu bar app that watches Claude usage limits and tells you before you run out, not after. It sounds simple to describe in one sentence, which is exactly why the first onboarding screen I built for it was not one sentence. It was five.
I wrote a paragraph that explained what the menu bar icon meant, what the color states represented, how the refresh interval worked, where the settings lived, and why I had built the tool in the first place. I was proud of that paragraph. It was accurate. Every claim in it was true and useful, and if someone read the whole thing carefully they would understand OhNine better than almost any other user.
Nobody read the whole thing carefully. I watched three people install the app and open it for the first time, and every one of them glanced at the screen, clicked past it, and then asked me a question the screen had already answered. That is the exact failure mode of an onboarding screen that tries to cover everything: it succeeds at being complete and fails at being read. A first-run screen is not documentation. It is the one moment you have someone's full attention before they decide, in about four seconds, whether the tool is worth the second click.
I had built the same trap I fell into with an early Git Dojo tutorial screen: explain thoroughly, assume thoroughness equals clarity. It does not. Thoroughness is for the help page a user visits on purpose, after the tool has already earned enough trust to be worth reading about. A first-run screen has not earned that yet. It has to earn it in the moment, with less text, not more.
Looking back at that first version now, the mistake is obvious in a way it never is while you are writing it. I was writing for myself, for the version of me who had spent real time thinking through every edge case of what the colors should mean and how often the check should run. That version of me wanted every decision justified on the screen, as if the person opening the app for the first time needed to be convinced the design was sound before they were allowed to use it. Nobody opening a menu bar app for the first time wants to be convinced of anything. They want to know, in the time it takes to glance at a phone notification, whether this is worth their attention.
Version Two: The Screen That Explained Nothing
The overcorrection came fast, the way overcorrections do. If explaining everything failed, I decided, explain almost nothing. Version two of the OhNine onboarding screen was a single line of muted gray text under the app icon, something like "menu bar usage tracking, click the icon to begin," and a single button labeled Continue.
This tested even worse than version one, just in a different way. Where the first screen buried the useful information in noise, the second screen simply did not have the useful information. People clicked Continue, found the menu bar icon, clicked it, and had no idea what the colors meant or why the number in the dropdown mattered. One person assumed the icon was just a static status light and never opened the dropdown at all, which meant the entire point of the tool, the early warning before a limit hit, never reached them. I had solved the wrong problem. The issue was never length by itself. It was that I had not decided what the one thing worth saying actually was, so I either said everything or said nothing, and both were guesses.
This is the part of building a tool alone that is easy to get wrong quietly. There is no one in the next desk to say "I read that and I still don't get it" in real time. I had to manufacture that feedback myself, by watching real people open the app cold and saying nothing while they did it. The two failed versions were not wasted, exactly. Version one taught me that completeness is not clarity. Version two taught me that brevity without a clear priority is not clarity either. I needed both less text and a sharper idea of which sentence actually mattered.
Version Three: The One Sentence That Stuck
The third version of the onboarding screen has exactly one sentence: "OhNine watches your Claude usage and tells you before you hit the wall, not after." Below it, one line of secondary text pointing at the menu bar icon, and nothing else. No settings walkthrough, no color legend, no explanation of the refresh interval. All of that moved to a help view reachable from the menu, available the moment someone actually wants it, invisible until then.
That one sentence works because it answers the only question a first-run screen actually needs to answer: why should I keep this open. Everything else, the color meanings, the interval, the settings, answers a question that only matters after someone has already decided the tool is worth keeping around. Front-loading those answers onto the first screen does not help the user get there faster. It makes the one sentence that matters compete for attention with four that do not.
I tested version three the same way I tested the first two, by watching someone open the app for the first time and saying nothing. The difference was immediate. Every person read the sentence, looked at the menu bar, found the icon, and started using the tool without a single follow-up question about what it did. They still had questions later, about the color states and the refresh timing, and those questions were fine. They were the right questions to ask once the tool had already proven its one claim.
The Rule I Apply to Every RAXXO Tool Now
Out of that process I built a test I now run before any RAXXO tool ships its first-run screen: write the one sentence the screen is allowed to say, before writing the screen. Not a list of features. Not the reasoning behind the design. One sentence, the kind you would say out loud to a friend if they asked what the tool does and you had four seconds to answer before they walked away.
If I cannot compress the tool down to one sentence that actually explains its value, that is a signal about the tool, not just the screen. Statusline Builder passed this test easily: it builds a statusline without you touching config syntax. Git Dojo passed it too: it teaches Git the way a terminal actually works, not the way a slide deck explains it. When a tool resists being compressed to one sentence, I have usually found a real problem with how I am describing it, sometimes with what I actually built.
The test is also cheap, which is why I keep using it. It costs nothing but honesty. Before a first-run screen gets written, I write the sentence on its own, away from the design file, and read it back the way a stranger would. If it needs a second sentence to make sense, the first sentence was not doing its job. If it needs a qualifier, an "although" or a "but keep in mind," I have not actually found the one true claim yet, I have found a compromise between two claims, and a first-run screen has no room for a compromise.
The test also changed how I think about the design system that ties five RAXXO tools together. A shared visual language only pays off if every tool under it is also making the same promise about attention: say the one true thing first, let the rest wait. Consistency in color and type means little if one tool's first screen respects a user's four seconds and another one does not.
None of this shows up in a screenshot or a feature list. It shows up in whether someone who has never seen the tool before understands, without asking, what to do next. That is a harder thing to design for than it sounds, and I did not get there by being clever. I got there by shipping two wrong versions, watching real people struggle with both, and being honest enough with myself to admit that the fix was not more polish. It was less text and one sharper idea about what the text was for.
Bottom Line
Three rewrites for one screen sounds like a lot of effort for something a user glances at once and never sees again. That is exactly why it deserves the effort. A first-run screen is the only screen in a tool's entire life that is guaranteed to get looked at by someone who has decided nothing yet, who has not built any trust in the product, who owes it nothing. Every other screen in the app gets read by someone who already chose to be there. The onboarding screen has to do the choosing.
The lesson generalized past OhNine. Every RAXXO tool I have shipped since goes through the same one-sentence test before its first-run screen gets written, and every one has been better for it, not because the sentence is clever, but because writing it forces me to know what the tool is actually for before I ask anyone else to figure it out.
Top comments (0)