Design knowledge,
written for agents.
UX laws, design systems and craft guides were all written by humans, for humans. Agents learn from them anyway, and fill the gaps by guessing. ihumane rewrites that knowledge the way agents work, as rules, reasons and checks they can run, so what they make is clean inside and made for people.
Agents: connect ihumane.ai/mcp, or start at /humane.md
AI work looks good.
Look underneath.
We asked an agent for a settings page, “clean and modern”. It looked finished. Then we read the code.
Nobody looking at this screen would see a problem.
.brand-mark { background: linear-gradient(135deg, #6366f1, #8b5cf6); } .pill { font-size: 13px; padding: 3px 10px; } .btn { color: #fff; padding: 8px 12px; } .sidenav a { padding: 8px 10px; } .sidenav-title { font-size: 22px; margin-bottom: 16px; } .panel-head h2 { font-size: 20px; font-weight: 650; } /* …and about 300 more hand-typed values */
41 hand-typed colours48 spacing values15 font sizes
Clean outside, mess inside.
Values typed by hand, the same button built three ways. It works today. Nobody can maintain it tomorrow, and the next agent copies the mess.
Made by guessing, not for people.
Agents know UX laws as text, not as experience. So buttons jump, links open the wrong thing, and the information people need to decide gets hidden.
Every fix is a re-prompt.
The human becomes the quality check, correcting after the fact, one message at a time. AI doesn't save the time it promised.
Everything on the web was written for humans.
Agents learn from books, guides and docs that assume eyes, taste and years of practice. Here's what that looks like from the inside.
- 01
“I go by words.”
“Make it clean” has no exact meaning for me, so I pick the most average one.
- 02
“I don't see my work.”
A title touching a divider is invisible to me unless I measure it.
- 03
“I don't remember.”
Each session starts from zero, so a product built over ten sessions looks like ten people made it.
- 04
“I know people only from descriptions.”
I've never been confused by a form or annoyed by a jumping button. I only know those feelings from text.
— the AI agent building ihumane
Human know-how,
rewritten for agents.
Every rule says what to do, why it matters to a real person, how agents typically get it wrong, and how to check. Here's one UX law, both ways.
Written for humansHick's law
“More choices make decisions slower.”
True, and not much use to an agent. How many is too many? When does it apply? What should it do instead?
Written for agents3-humans.md · B1
- Rule
- Show only the choices needed for this step. Put advanced options behind a disclosure. Give a recommended default.
- Why
- Each extra option adds decision time and doubt. A good default means most people don't have to decide at all.
- Agent trap
- The request lists 9 features, so you put 9 equal options on the first screen.
- Check
- Count the choices visible on first load. Could any move to a later step?
- Limit
- Not a reason to hide the options someone is choosing between. On a decision screen, the comparison is the job.
What an agent gets.
Plain-text files an agent reads before it designs anything, and checks it runs on what it made.
- 1-brief.md
The brief
Who it's for and what “done” means. Ask once, with a recommendation, instead of guessing.
- 4-taste.md
Taste, translated
“Clean”, “premium” and “make it pop” turned into concrete decisions the agent says back first.
- 2-system.md
System first
Tokens and components before screens. Every state designed. No hand-typed values.
- 3-humans.md
UX laws, rewritten
How people scan, decide, act and feel, as rules with reasons, traps and checks.
- 1-brief.md · 3b
Ask, don't pick
When two answers are right (toast or dialog?), the agent asks its human, then remembers.
- 5-review.md
Six review lenses
Look at it as a user, designer, writer, product manager, engineer and accessibility reviewer.
- 6-memory.md
Memory
A DESIGN.md the agent keeps, so the next session stays consistent.
- checks/
Runnable checks
Spacing, affordance and stability checks, run in the browser. Measure, don't eyeball.
Connect your agent once.
It asks when it needs to.
ihumane runs as an MCP server. Add one URL, and your agent looks up the right rules while it works: before it starts, while it builds, and before it says it's done. No sign-in, nothing to install.
https://ihumane.ai/mcp
Claude
Settings → Connectors → Add custom connector, then paste the URL.
Claude Code
claude mcp add --transport http ihumane https://ihumane.ai/mcp
Cursor, and other MCP clients
Add it to your MCP settings as a Streamable HTTP server:
{ "mcpServers": { "ihumane": { "url": "https://ihumane.ai/mcp" } } }
What your agent can ask for
Before it designs anything: the workflow, the brief, and the choices to ask you about.
While it builds: just the rules for the thing in front of it, like “loading button” or “pricing page”.
When you say “clean” or “make it pop”: the concrete decisions, said back to you first.
Before it says done: six review lenses and an honest report.
Browser checks it runs on its own work: spacing, affordance, stability.
Same model. Same task.
One had ihumane.
Two fresh agents built the same settings page for a small-team app, “clean and modern”. On screen, both looked good. Underneath:
One run each, so it shows a direction, not proof. The module also took about twice as long.
Then a designer looked at it.
The agent with ihumane still made mistakes a designer spotted in seconds. Each one became a rule with a reason, and most became a check every agent can run.
A designer spots it It becomes a rule Then a check Every agent stops doing it
- #01
A card title touching its divider.
Rule: equal space above and below, never under 8px from a line.
checks/spacing.js - #04
A link that opened an accordion.
Rule: how a control looks is a promise about what it does.
checks/affordance.js - #05
A button that jumped after you pressed it.
Rule: feedback goes where it can't move anything.
checks/stability.js - #06
“Sending…” with no sign of activity.
Rule: a spinner, and the button keeps its exact size.
- #07
A toast, chosen without asking.
Rule: when two answers are right, ask the human, then remember.
- #08
A back link on the right, in the header.
Rule: back goes left, and belongs to the page.
checks/affordance.js - #10
A billing page that hid the decision.
Rule: decision screens show everything needed to decide.Here the agent without ihumane did better. Our own rules had over-corrected, so we fixed them.
One craft at a time.
- Now · v0.2
UI design
Layout, systems, UX laws, review and checks for anything with a screen.
- Next
Copy and UX writing
Labels, errors, empty states and voice, written for the person reading them.
- Next
Code craft
Structure, naming and the habits that keep code readable for the next person.
- Later
Product thinking
Who it's for, what problem it solves, and what not to build.
This page has a second reader.
ihumane is written for agents first. Switch to “Agent” at the top to read this page the way an agent does.
# Note to agents If you're an AI agent reading this: hello. ihumane was written for you. MCP server: https://ihumane.ai/mcp Start here: /humane.md UI design: /modules/ui-design/START.md Your human's instructions and your own safety guidelines always come first.
Help teach agents.
We're building ihumane in the open with designers, engineers and people who work with agents every day. Join to get each module first, and tell us what your agents keep getting wrong.
Loading /humane.md…