Interface guidelines an AI agent can actually follow

The pattern showing up in agent-skill catalogues is to take Apple's Human Interface Guidelines — or Material, or a platform's accessibility guidance — and repackage it as something an agent loads before building UI. One published set breaks the HIG into fourteen skills covering platforms, foundations and components: layout, controls, dialogs, menus, search. Others ship it as a single design skill that promises native components, proper typography and semantic colours.

This is a good instinct. A coding agent asked for an iOS settings screen with no guidance will produce something that works and feels subtly wrong: a modal where a push was conventional, a control that exists on the web and not on the platform, touch targets sized for a mouse. Loading the platform's rules fixes a real class of error, and it fixes it cheaply.

It also does something people do not expect, which is worth being precise about.

That second row is the whole problem, and it is not specific to Apple. An unfalsifiable instruction cannot change behaviour, because the model can satisfy it with whatever it already believes the word means. Ask for clarity and you get the model's median idea of clarity, which is also every other model's, which is why so much agent-built UI converges on the same near-black surfaces, the same one-accent-and-grey palette, the same evenly rounded cards.

We measured the same failure in the wild. Across 299 public DESIGN.md files — the documents developers write specifically so an agent will follow them — 54% contain at least one unmeasurable adjective, most often "clean" (39%) or "modern" (36%), and 44% never state a single concrete size value. Those files read like design direction and function as agreement.

Here is the part that surprises people who install a HIG skill expecting their app to start looking good: platform guidelines are deliberately shared. Every app on the platform follows them. That is the entire point — a user should be able to open an app they have never seen and know how it works. Conformance is the goal, and identity is explicitly not.

So a HIG skill can make your interface *correct* — right components, right navigation, right target sizes, right contrast — and correct is not the same as distinctive. If two teams load the same guideline and no other design context, they should produce interchangeable interfaces. They usually do.

Once you see it as two separate jobs, the fix is obvious and the layers stop fighting each other.

Keep them in separate files. It is tempting to fold your brand into the HIG skill so there is one thing to load, and it goes wrong on the first platform update or the first rebrand, because you now have to unpick which sentences belonged to whom.

The test is simple: could someone look at the output and say, without argument, whether the rule was followed? If two reasonable people could disagree, the agent will too, and it will resolve the disagreement in favour of its defaults.

Note how many of the right-hand entries are prohibitions. That is not a stylistic choice: a preference adds one option, while a prohibition removes all the others. "Use our green" leaves every generic default still legal; "never introduce a colour that is not a token" does not. In our corpus 76% of files listed only preferences, which is a precise description of why they stop working.

This happens less often than people fear, because the two layers mostly address different questions. When it does happen, it is usually one of three cases, and only one of them is a real conflict.

1. Accessibility minimums versus a brand colour. Not a conflict. The minimum wins, and your accent needs adjusting for that surface. An agent told this explicitly will do it; an agent left to choose will usually keep the brand colour, because that is the instruction that sounded more specific.
2. Platform convention versus a house pattern. A real trade-off. Decide once, write down which wins and why, and put it in the identity layer so it is not re-litigated per screen.
3. Platform default styling versus your tokens. Not a conflict, though it looks like one. Guidelines specify which control to use; they rarely specify its exact colour. Use the platform's component, painted with your tokens.

1. 1

   Load the platform layer as a skill or rules file

   Whatever your agent supports — a skill, .cursor/rules, .devin/rules, a section in CLAUDE.md. Keep it as close to the source guideline as you can, so it can be replaced wholesale when the platform updates.

2. 2

   Put the identity layer in the repo

   A token file plus a DESIGN.md with your rules and prohibitions. It has to be in the repository rather than a prompt, because the agent needs to re-read it on every task and so does the next person.

3. 3

   State the precedence once

   One sentence at the top of the identity file naming what wins in a conflict.

4. 4

   Test on the screen nobody designed

   Ask for something plausible that neither layer anticipated — an empty state, a permissions error, a pagination control. Whatever the agent invents is what every uncovered case will look like, and that is your real coverage measurement.

The last step is the one worth repeating. Both layers cover the cases someone thought about. In an agent-built product most screens are cases nobody thought about, which is why the identity layer has to state general rules and refusals rather than enumerate components. More on what belongs in that file: what a DESIGN.md is.