The Guess Dressed Up As A Plan

Every proposal has a line you're not sure about yet.

Maybe it's how many components a mobile app needs before anyone's designed it. Maybe it's whether the client's team can carry the system forward once you're gone, or whether that team ends up being one person or four. You don't have the answer, and the deadline for sending the proposal isn't waiting around for you to get one.

So you do what most people do here — you pick a number. Forty hours, twelve components, two training sessions, and you keep going. It's a guess dressed up as a plan, and it holds up fine. Until it doesn't.

We've all sent proposals like that early in our careers, more than we'd like to admit. The estimate looked clean, the client signed it, and a few weeks into the engagement the gap we'd skipped over showed back up. Except this time it came with the client's expectations attached, not just ours.

What we do differently now: we write the gap down instead of skipping past it.

A recent proposal had a scope question sitting right in the middle of it: nobody knew how much of the system a still-undesigned mobile app would need. We could have picked a number, built in some padding, and called it settled. Instead, the line read something closer to: mobile scope is an open question, pending one more conversation with the design lead. Plain, on the page, next to the parts we were sure of.

That one line did more work than a padded estimate ever would have. It told the client we'd looked at the scope closely enough to know exactly where it thinned out. It gave us something concrete to ask about on the next call, instead of a guess we'd have to defend later if it turned out wrong. And it kept the rest of the estimate honest, because every number sitting next to that flagged line was one we'd stand behind.

There are a few things that help when a gap like this is staring back at you:

1. Write it where the estimate lives, not in a separate notes doc nobody opens again: Right in the proposal, next to the number it affects, so the client sees it in context instead of finding out later.
2. Turn it into a question, not a decision: "Mobile scope: TBD" leaves everyone guessing at what you meant. "Mobile scope: pending confirmation on which flows need support" gives the client something they can actually answer.
3. Say what happens once you know: A flagged gap should come with a note about how the answer moves the estimate, up or down. Clients don't mind uncertainty. What they mind is a surprise invoice.

None of this makes a proposal look less finished — it makes it look like someone read the brief closely enough to spot the edges before anyone had to ask.

If you've got a scope gap you're staring down right now, or a habit that's helped your team name what you don't know, we'd love to hear how you handle it.

📬 From the inbox

This week's question came from a reader thinking through what's left for design system reference sites to do:

That three-part model still describes most of what's happening: A design source of truth, A code source of truth, and a reference site. But there's something bigger happening underneath that — we think the reference site itself is starting to split into two. One layer stays human-readable and explains the why. The other is structured and queryable, built for a model to read directly. We've sat with teams wrestling with exactly this split firsthand, unsure whether the fix belonged in the site or somewhere underneath it.

You can see the shape of that second layer already in what documentation teams are choosing to build. Carbon didn't redesign their site for this — they shipped a separate MCP server that lets a model pull component details and tokens directly, bypassing the page entirely. They left the site alone and built something separate, because the gap between how a model reads a page and how a person does isn't something you can write your way out of.

Mintlify, which builds documentation infrastructure for a lot of teams, reports that close to half the traffic hitting docs sites now comes from agents, not people. When that much of your audience isn't reading a page the way it was designed to be read, a structured second version of the same information stops being an experiment and starts looking like infrastructure.

The era itself isn't over. But what's probably over — for anyone starting today, is treating a monument-scale site as the finish line — Carbon, Polaris, and Primer keep their scale because of what they already built over a decade, not because that's still the right target to aim for from zero.

The three names you picked deserve a closer look individually, too: grouping them under "big sites" hides how differently each one earns its keep, and I’m not sure that any of it comes down to PR.

Shopify has a third-party app store, and that's the actual reason Polaris exists. Outside developers rely on it to build apps that feel native inside Shopify's admin. Take the site down, and Shopify loses something closer to a revenue channel than a brand exercise.

GitHub built Primer for itself first, but outside projects have adopted it wholesale since, OpenProject among them. That's ecosystem work happening outside GitHub's own walls, not image management.

Then there's Carbon, maybe the clearest case of all three. IBM's own team has written about coordinating thousands of its own globally distributed teams, with no other shared point of contact between them, plus external adopters on top of that. At that scale, the public site is one of the only shared coordination points those teams have.

Three sites, three different jobs.

There's a third bucket alongside PR, too: whether a site is coordinating an audience too distributed to reach any other way, external developers on a platform, or internal teams so large and disconnected they might as well be external. Recruiting still matters too, Brad Frost has talked for years about people who cite a company's public style guide as the reason they applied, but we think that's the secondary reason these three specifically survive. Coordinating a distributed audience looks closer to the primary one.

If you're deciding what to build for a system that isn't Carbon-scale, start with the structured, model-readable layer: semantic tokens, a real description on every component. That's the part getting queried right now, regardless of whether a polished site exists yet. Build the human-facing site after, sized to the audience you actually need to coordinate.

Thanks for reading, and see you next week! 👋 💛
– Murphy

📣 Incase you missed it

Katie's running her first cohort of our brand new course Figma, Beyond the Basics — For Brand & Marketing Creatives in August. It's built for anyone who came up in the Adobe suite and still feels like Figma is a translation exercise, rather than second nature. 

Over the week you'll learn how a file is actually built, get comfortable with auto layout, components, and variants, and set up styles you can reuse instead of rebuilding from scratch every time. There's a ton of tips and tricks along the way too, and you'll walk away with a real brand style guide published as a library. We’re so excited!