· 6 min read
We installed Meta's agent-ready design system. Rule one for agents: no div
Astryx 0.7.16 writes 409 words of rules into your AGENTS.md, links a skill into your home folder on request, and charges 115 KB for one button. We measured all of it.
Written with the help of AI, reviewed and added to by Kevin Bos.
The first rule Meta’s design system gives an AI agent is to stop writing <div>. It arrives in your repository as part of a 409-word block that one command adds to AGENTS.md:
$ astryx init
[ok] AI agent docs installed -> AGENTS.md, GEMINI.md
[…]
files added in the project by init:
> ./AGENTS.md
> ./GEMINI.md
--- ./AGENTS.md: 35 lines, 409 words, 2773 bytes
The block opens its rules with “No <div>”, followed by “components handle all layout and spacing”. It ends with a self-check: re-read the file and replace any raw <div> or <span>, any hardcoded hex colour or pixel value. The README of the same project lists as its first principle “Guidance over enforcement”.
409 wordsof instructions Astryx adds to your AGENTS.md, for every agent that opens the projectOur run in the sandbox, Astryx 0.7.16, 18 November 2026
Why we looked
Astryx gained 8,700 stars in the week to 18 November and stands at 30,365. Meta describes it as “an open source design system that’s fully customizable and agent ready”. The README says it grew inside Meta for eight years and powers more than 13,000 apps. It is in beta, MIT licensed, and built on React 19.
“Agent ready” is the part nobody can check from a README. So we installed it in a container and measured three things: what it writes to disk, how much an agent has to read, and what a user downloads.
What “agent ready” writes to your disk
Installing the packages wrote nothing outside node_modules. The agent text appears only when you run init, and there are two levels.
The second level is the one to know about before you type it. init --user sets up the whole computer:
$ astryx init --user
[ok] Wrote ~/.agents/skills/astryx/SKILL.md
[…]
[ok] Linked ~/.claude/skills/astryx
[…]
> ./.claude
> ./.claude/skills
> ./.claude/skills/astryx
Our sandbox home folder had no .claude folder. The command created one and linked the skill into it. The skill is 283 words and tells any agent on the machine that Astryx exists, when to use it, and to run npm i -g @astryxdesign/cli if the command is missing. The source of init adds that a CLI installed for the computer “refreshes the file in the background after each upgrade”. We did not test that part.
We wrote two days ago that a skill is a dependency nobody reviews. This is the well-behaved version of that: a named command, a printed receipt, a hash in the file, and an undo. We ran the undo:
$ astryx init --user --remove-agents
[ok] Removed ~/.agents/skills/astryx/SKILL.md
[ok] Removed ~/.claude/skills/astryx
The skill and the link were gone. Two empty folders and a settings file stayed behind, with "install": false so it does not come back. In the project, init --remove-agents deleted both files it had created.
What an agent has to read
Astryx does not ask the agent to read node_modules. It gives it a CLI, and the skill says so in as many words: read astryx component <Name>, “not the package’s files”.
- AGENTS.md block, read every session
- 409 words
- List of all 174 components
- 714 words
- Button, props only
- 630 words
- Button, dense format
- 1,269 words
- Button, full docs
- 1,498 words
Reading every component’s docs one by one came to 127,706 words for 174 components, an average of 734. That number is the argument for the CLI: nobody loads it all, and an agent that reads only what it uses stays in the low thousands. The --dense flag is described as token-efficient. On Button it saved 229 of 1,498 words.
What one Button costs your users
The README promises “no build plugin, no styling library to adopt”: you import pre-built CSS. We bundled a page with one Button using esbuild 0.28.2 and compared it with the same page using a plain <button>:
none.jsx bundle: 223471 bytes, gzip 69037 bytes
one.jsx bundle: 416111 bytes, gzip 133084 bytes
sub.jsx bundle: 414516 bytes, gzip 132232 bytes
ten.jsx bundle: 588993 bytes, gzip 184919 bytes
node_modules/@astryxdesign/core/dist/astryx.css: 292182 bytes, gzip 42973 bytes
| JavaScript, gzip | CSS, gzip | |
|---|---|---|
React and a plain <button> |
69.0 KB | 0 |
| One Astryx Button | 133.1 KB | 50.8 KB |
| Button, imported from its own path | 132.2 KB | 50.8 KB |
| Button plus four more components | 184.9 KB | 50.8 KB |
One Button adds 64 KB of JavaScript. Importing it from @astryxdesign/core/Button instead of the package root saved 852 bytes, so the weight is in what Button itself pulls in. The CSS is the stylesheet for all components (43.0 KB), the reset (3.8 KB) and the theme (4.0 KB), whether you use one component or all 174.
For an internal tool that is a fair price for 174 accessible components. For a public landing page it is 115 KB before the first word of content. Astryx also ships a build package for compiling StyleX from source, which may shrink the CSS. We did not test it.
Does the agent part work?
Here Meta deserves credit, because it publishes its own answer and the answer is not flattering. The team runs nightly “vibe tests”: the same prompts given to fresh agents with Astryx, with shadcn and Tailwind, and with plain HTML. Their write-up shows a good night, 98 for Astryx against 95 for the shadcn baseline, and a bad one where Astryx scored 2 on correctness because agents invented imports and prop names. Then it says: “Across our full ledger the baseline actually wins the plurality of nights”.
A newer evaluation in the repository is stricter: a deterministic grader in a real browser, no LLM judge, intervals on every pass rate. It notes one asymmetry itself. The agent is given the project’s AGENTS.md if the library’s setup wrote one, and the README says: “Today only astryx init writes one.” So the Astryx arm gets 409 words of coaching and the shadcn arm gets none. That is a fair test of the product as shipped, and it means a win measures the instructions as much as the components.
We ran no agent ourselves. These are the vendor’s numbers.
What we would do
We would try Astryx for an admin interface or an internal tool, where 174 consistent components matter and 115 KB does not. We would not put it on a marketing site.
We would run astryx init and then read the diff of AGENTS.md in the pull request, as we would for any dependency that writes instructions for our agents. The block is managed: by the project’s own documentation it is “written, refreshed, and removed whatever ignore rules or generated markers say”. We would not run init --user on a shared development machine without telling the people who use it.
What would change this: published pass rates from the stricter evaluation, with and without the AGENTS.md block.
Limits of this test
One version (0.7.16), one clean container, npm on Node 22.23.5. We measured files, words and bytes, and did not build an interface with an agent. Bundles were made with esbuild’s defaults for a minified production build and no StyleX compiler; a real app with Vite or Next.js will differ. Word counts are wc -w on the CLI’s text output, which is not the same as tokens.
Sources
- meta/astryx
- Astryx blog: Vibe Test, how we make decisions in Astryx
- Astryx CLI: documentation of init, in the source
- Astryx vibe eval: how the comparison with shadcn/ui is run
- GitHub Trending, weekly, 18 November 2026
- AI agents
- design systems
- React
- frontend