These correlate less than we would like, and the gap is where a lot of otherwise good software fails.

what users actually experience#

Not your service boundaries. Not your consistency model. Not the fact that you handle a partition correctly.

• How many steps to do the common thing.
• Whether it responds instantly or after a spinner.
• Whether an error tells them what to do.
• Whether it does the same thing twice in a row.
• Whether it remembers what they told it last time.

Every one of those is an interface property, and every one is achievable on top of an ugly implementation — or destroyed on top of a beautiful one.

the trade that is usually made backwards#

There is a real tension between internal cleanliness and external simplicity, and it comes up constantly:

• The clean data model exposes three concepts where users think in one.
• The correct API makes the caller specify things they do not care about.
• The properly-separated services mean the UI has to make four calls and handle each failing independently.
• The general solution has eleven configuration options; the specific one would have had zero.

The default resolution is to protect the internals and push the complexity outward, because the internals are what engineers look at and defend in review.

That is backwards. The interface is used far more times than the implementation is read. Complexity at the boundary is multiplied by every user and every call; complexity inside is paid by the people who chose it.

what this looks like in practice#

Collapse concepts at the boundary. If users think of one thing and your model has three, expose one and do the mapping internally. Yes, that is a lossy abstraction and you will occasionally have to break it. That is the correct place to put the pain.

Default everything. Every required parameter is a decision you have forced on someone who has less context than you. Make it optional with a sensible default, and let the people who genuinely need control find the option.

Make the common path one step. Count the actions for the thing 90% of users do 90% of the time. If it is more than two, that is the work.

Absorb the failure. If your architecture means four things can fail independently, the interface should not surface four independent failures. Retry, degrade, or present one coherent state.

Make it fast where they are waiting. A local read, an optimistic update, a cached response. Users cannot tell the difference between "fast because it is well-engineered" and "fast because you cheated" — and neither can anyone else.

the counterweight, honestly#

This is not an argument for shipping a nice facade over a broken system. The internals are what make the interface keep working — under load, at the edges, after a year of changes. Software that is lovely to use and impossible to change dies just as reliably, only slower.

The claim is narrower: when the two genuinely conflict, and they do, the interface should usually win — because it is what the software is for, and because interface decisions are much more expensive to reverse than internal ones. You can rewrite the storage layer. You cannot easily take back a concept you taught a million users.

the test#

Watch someone use your software for the first time without helping them.

Count the moments they hesitate. Each one is a place where your model and theirs diverged, and no amount of internal quality closes that gap.

That exercise is uncomfortable, takes twenty minutes, and consistently produces a better backlog than any amount of architectural discussion.

the anatomy of a good one#

Four parts. Most messages have one.

What happened, specifically.

Not "an error occurred." What failed, in terms the reader can act on.

Why, if you know.

The immediate cause. Not the stack trace — the reason.

What to do next.

The single most valuable part and the most often missing. Even "retry in a few minutes" is infinitely better than nothing.

How to get help.

An error code, a request ID, a link. Something the reader can paste into a support conversation that makes the problem findable.

the transformation#

Error: ECONNREFUSED

versus

Could not connect to the database at db.internal:5432.

The connection was refused, which usually means the database is not
running or a firewall is blocking the port.

Try:
  1. Check the database is running:  systemctl status postgresql
  2. Verify the host and port in config/database.yml
  3. Check network access:           nc -zv db.internal 5432

If this persists, include request ID a1b2c3d4 when reporting.

The second is longer, and length is not the cost people think it is. Nobody has ever complained that an error message told them too much about how to fix their problem.

the rules#

Never blame the user. "Invalid input" is accusatory and unhelpful. "Email address must contain an @ — you entered dom.example.com" is neither.

Echo what they gave you. The single most useful thing a validation message can do is show the value that failed. The user's mental model of what they typed is frequently wrong, and showing it resolves the confusion instantly.

Be specific about which one. "One or more fields are invalid" makes the user hunt. Name the field. Highlight it. If there are several, list all of them — do not make them fix one, submit, and discover the next.

Distinguish the four failure classes, because the correct user action is different for each:

Collapsing these into one generic message means the user cannot tell whether to retry, fix something, or give up.

Include an identifier for the unfixable ones. When it is genuinely your bug, the user cannot fix it and the best thing you can give them is a request ID that appears in your logs. That converts "it's broken" into a support conversation you can actually resolve.

Never expose internals to end users, always expose them to developers. A stack trace on a public error page is an information disclosure. The same trace in a developer tool's console is essential. Know which audience you are writing for.

the developer-facing case#

For errors read by other engineers — library exceptions, CLI failures, API responses — the bar is different and higher.

Say what you expected and what you got.

expected `timeout` to be a positive integer (milliseconds), got: "30s"

Durations must be numeric. Use 30000 instead of "30s".

Point at the source. File, line, and the offending fragment. Compilers have done this well for years and application errors mostly have not.

Link to documentation with an anchor to the specific section, not the homepage.

Give the error a stable identifier so people can search for it. E1042 is searchable in a way that a prose sentence you will reword next release is not.

Rust's compiler errors remain the standard here and the reason is that someone decided error messages were a feature and staffed them accordingly.

the audit worth running#

Grep your codebase for every string that gets shown on a failure. Read them as a list, out of context, the way a user encounters them.

You will find: generic messages, internal jargon, messages that describe the code's state rather than the user's situation, and at least one that says something like "this should never happen."

Fixing them is a day of work and it is the cheapest quality improvement available in most products.

the framing#

Every error message is a conversation with someone having a bad time. You get one sentence, maybe three, to help.

Write them like you will be the one reading them at 2 a.m., because eventually you will be.

You will throw most of it away. That is fine. The value is in what happens while you write it.

what it forces#

A name for the thing. If you cannot name it in one sentence, you do not know what it is. "A library for X" where X is three clauses joined by "and" is three libraries.

A first example that fits on a screen. This is the brutal one. Write the code a new user types first. If it needs eleven lines of setup before anything happens, your API is wrong, and you found out before you built it rather than after.

# if this is your example, stop and redesign
client = Client(config=Config(
    auth=AuthProvider(strategy=Strategy.OAUTH, ...),
    transport=Transport(pool=Pool(size=10), retry=RetryPolicy(...)),
    serializer=JsonSerializer(...),
))
result = client.get_resource(ResourceRequest(id=ResourceId("x")))

# if this is your example, you are probably fine
client = Client(api_key=key)
result = client.get("x")

An explicit list of non-goals. Every project has them and most only discover them in a GitHub issue eighteen months later when someone asks for a feature that would break the design. Writing them down early is the cheapest scope control that exists.

Error cases described in prose. "If the token is expired, X happens." Writing that sentence often reveals that you have not decided what X is, and the decision is much cheaper now.

why it works better than a design doc#

Design documents are written for reviewers. READMEs are written for users. The audience difference changes everything.

A design doc rewards completeness, so it grows sections about alternatives considered and migration strategies and rollout phases, and by page six nobody including the author is thinking about the interface anymore.

A README rewards clarity from the outside. It cannot contain your internal rationale, because users do not care. It can only contain what the thing does and how to use it, which is exactly the part that is expensive to change later.

the internal-service version#

This works for services too, and possibly better.

Write the endpoint documentation before the endpoint. Write the example request and the example response. Write the error codes and what each one means.

Then send it to the team that will consume it — before you build anything. The feedback you get in that thread is worth more than any amount of code review after the fact, because at that point changing the interface is free.

Half the API design mistakes I have watched happen were mistakes that the consuming team would have caught in ninety seconds if anyone had shown them the shape first.

the objection#

"I do not know what it does yet, that is why I am building it."

Sometimes true. Exploratory work where the shape is genuinely unknown should be exploratory, and forcing a README onto it is cargo cult.

But be honest about which mode you are in. Most of the time you do know roughly what it does, and "I will figure out the interface as I go" means "I will discover the interface from whatever was convenient to implement," which is how you end up with a function that takes eleven positional booleans.

the actual test#

When you finish, read the README as if you had never seen the project.

If your reaction is "I do not understand what problem this solves," you have learned something enormously valuable for the cost of twenty minutes and no code.

That is the best exchange rate in software.

the version reset#

Every OS jumps to 26: iOS 26, macOS 26 Tahoe, watchOS 26, tvOS 26, visionOS 26. Year-based, aligned across platforms, matching the model-year convention.

Genuinely good housekeeping. "Requires iOS 17, macOS 14, watchOS 10" was needlessly hard to reason about. Now it is one number.

Liquid Glass#

A system-wide redesign built around translucent, refractive material that reacts to content behind and beneath it. Controls float. Layers have depth. Things bend light.

Reactions split predictably. It is undeniably a strong visual identity and the first genuinely new direction since iOS 7 flattened everything in 2013. It is also, in the first betas, a legibility problem in a lot of contexts — text over a refractive layer over a busy background is exactly the situation typography guidance has warned about for a century.

Apple will iterate through the beta cycle. They always do. Contrast will be raised, blur will be increased, and the shipping version will be about 70% of the demo. That is the normal arc and knowing it saves you from having the argument twice.

For developers: if you use standard controls you get it for free. If you built custom UI, budget real time. Custom navigation bars and tab bars in particular are going to need work.

Foundation Models framework#

Here is the actual news. Apple exposes the on-device model to third-party apps via a Swift API, with guided generation, tool calling, and streaming.

import FoundationModels

@Generable
struct Recipe {
    @Guide(description: "Dish name") var name: String
    @Guide(.count(3...8)) var ingredients: [String]
    var minutes: Int
}

let session = LanguageModelSession()
let recipe = try await session.respond(to: "A quick pasta dish", generating: Recipe.self)

That @Generable macro is the good part. You define a Swift type, the framework constrains decoding so the output is guaranteed to parse into it. No JSON parsing, no retry loop for malformed output, no schema drift between your prompt and your struct. Type safety all the way through.

And it costs nothing per call. No API key, no rate limit, no network, no privacy review. For a small on-device model that is enough for summarization, classification, extraction, and simple generation, that changes the calculus for a huge number of app features that were previously not worth a server bill.

The model is small — roughly 3B parameters — and you should not expect frontier behavior. Expect a good small model that is free and private, and design features that fit that envelope.

Containerization#

A framework for running Linux containers on macOS with each container in its own lightweight VM, open source, with sub-second start times. Docker Desktop on macOS has been a performance complaint for a decade. This is Apple's answer and it is architecturally cleaner: per-container VMs rather than one shared Linux VM.

Xcode 26#

Model integration in the editor with support for multiple providers including Claude, plus a new coding assistant experience. Apple shipping first-party support for a competitor's model inside its own IDE is notable — it means they have concluded the model layer is a component, not a differentiator.

the read#

Consumer-facing, this was a design conference. Developer-facing, it was the conference where Apple's local-first AI strategy finally produced something you can build on.

The strategy is coherent: small models on device, free and private, with the big stuff handled elsewhere. It is not going to win benchmark comparisons and it was never trying to.

Six and a half billion dollars for a design team and an idea is a lot of money, and it is worth taking the underlying thesis seriously even if you think the price is absurd.

the thesis#

The smartphone is optimized for an interaction model that AI makes obsolete.

A phone is a rectangle of apps. You unlock it, find the app, navigate its hierarchy, and perform a task. That design solved the problem of "how do I access many different services on a small screen," and it solved it well enough that the form factor has been essentially static for fifteen years.

If the interaction model becomes "state your intent, the system figures out which services to use," then most of the phone's design — the grid, the navigation, the visual hierarchy — is scaffolding for a problem that no longer exists. What you need instead is something always available, ambient, primarily audio, with a screen only when a screen is genuinely the right modality.

That is a coherent thesis. It is also the thesis behind two products that failed badly and publicly in 2024: the Humane Ai Pin and the Rabbit R1.

why those failed and whether this is different#

The Ai Pin and R1 failed for the same three reasons:

1. The models were not good enough. Both shipped in early 2024, before reliable tool use, before good latency, before models that could handle ambiguity gracefully. The demos were staged; the products were not ready.
2. The hardware was bad. Thermal problems, terrible battery life, laser projection nobody could read in daylight.
3. They competed with a phone that was in the same pocket. Any task the device could not do, the phone could. That is a brutal comparison to survive.

Reason one has changed a lot in eighteen months and will change more by 2026. Reason two is precisely what you buy Jony Ive's team for. Reason three has not changed at all and is, I think, the actual problem.

the part that is genuinely hard#

A dedicated AI device has to be better than a phone at something to justify existing. The candidates:

• Always-on context. A device that sees and hears what you do all day has context a phone does not. That is also the most invasive product concept in consumer electronics history, and the social norms around it do not exist.
• Zero-friction capture. Say something, it is recorded, transcribed, actioned. Genuinely better than unlocking a phone. Also achievable by a watch or earbuds, which people already wear.
• Not being a phone. There is a real and growing market for devices that do not have a feed. That market is not obviously large enough for a $6.5B bet.

the strategic read#

OpenAI's dependence on Apple and Google for distribution is a structural risk. Every ChatGPT interaction on a phone happens on an operating system built by a competitor who can change the rules. Owning hardware is the only permanent solution to that, and it is worth a lot to not be a tenant.

Whether it is worth this much, executed by a team that has never shipped hardware at this company, on a two-year timeline, in a category with a hundred percent failure rate so far — that is a different question.

I would not bet against Ive on the object. I would bet against the category on the timeline.