feat(cli): help agents discover the right template, blocks & components from a plain-English idea

[josephfarina]

🎯 Why this exists

Part of a broader push to make Astryx the easiest design system for AI agents to build real UIs with — one-shot, no escape hatches, no broken renders. We're vibe-testing the full agent journey (install → init → discover → compose → build → typecheck → render) and fixing every friction point it surfaces, so an agent given a one-line prompt lands a correct, fully-styled, type-safe page using only design-system components.

Summary

• Adds astryx build — the page-building front door:
  • build "<idea>" returns a composition kit: the closest page template, the blocks that cover parts, and components to fill gaps, plus a one-line Compose: suggestion.
  • build with no args prints the how-to-build playbook.
• Reworks the shared search ranking so oblique natural-language queries work: query tokenization + stopwords, a synonym/intent map, light stemming, and page-template keyword enrichment (derived components + category). search still exposes the same engine as a flat universal lookup.

Why

In vibe-testing, agents using the published CLI never used search (0/20) and never discovered the 517-block library. A composition-oriented build front door + better ranking got agents to discover and compose from pages and blocks.

Test plan

• npx vitest run packages/cli (search + api tests green)
• astryx build "pricing page" returns a kit incl. the RadioList — Pricing Tier block
• astryx build prints the playbook
• astryx search "data table with filters" returns relevant results (was "no results")

Made with Cursor

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
astryx	Ignored		Jun 25, 2026 5:49pm

[github-actions]

🚀 Vercel Preview Deployment

Status	✅ Deployed
Preview	Open Preview
Commit	c5c1146
Inspect	Vercel Dashboard
Workflow	View Logs

No authentication required — anyone with the link can view the preview.

[github-actions]

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

🧪 Sandbox Preview

View Sandbox for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

No new or modified components detected.

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@astryxdesign/core	N/A	4.6KB	0B

Accessibility Audit

Status: No accessibility violations detected.

---

_{Generated by PR Enrichment workflow | Storybook | Sandbox | View full report}

[cixzhang]

Pretty neat. Can you share the vibe test comparison with this strategy?

[josephfarina]

Vibe-test comparison (before → after this strategy)

@cixzhang — here's the before/after. I re-ran the vibe test on 10 stratified, colloquial prompts (the way people actually describe pages), comparing the pre-PR main (merge-base 96874876) against this branch's build + reworked ranking. Same prompts, same models, same getting-started flow — the only variable is the CLI.

1. Discovery recall (deterministic — no agent involved)

Running the raw query through the CLI: old search vs new build.

Colloquial prompt	BEFORE astryx search	AFTER astryx build
"portfolio page … chart of value over time and top holdings"	❌ No results	✅ dashboard-portfolio (direct)
"product page … photos to flip through, collapsible sections"	❌ No results	✅ product-gallery + product-detail
"shop page with products as cards, photo name description price"	❌ No results	✅ product-gallery (direct)
"table page for an ops team, search/filters, action toolbar"	❌ No results	⚠️ surfaces table-page (ranked 3rd)
"settings in a popup with a side menu inside the dialog"	❌ No results	✅ settings-dialog (direct)
"preferences where the left nav swaps the section, edit in place"	❌ No results	✅ settings-sidebar (direct)
"form page with a hero header and the form in a card, two columns"	❌ No results	⚠️ surfaces form-two-column (ranked 3rd)
"board where we drag task cards between todo / doing / done"	❌ No results	✅ correctly "no exact match → compose", + Card blocks
"pricing page, 3 plans, middle one recommended"	❌ No results	✅ correctly "no exact → compose", + RadioList — Pricing Tier block
"invoice page, line items, totals, pay/download"	❌ No results	✅ detail-page (direct)

Before: 0/10 returned anything. After: 10/10 surface a relevant template (8/10 as the top pick) plus the blocks to compose it. The old ranking simply doesn't match how people phrase UI ideas; the new build front-door + ranking does.

2. Agent runs (10 before / 10 after, one-shot)

Both sets build green (these are capable models that work around gaps), so the signal is in how they get there:

• Before: search returns nothing for the obvious phrase → every agent falls back to scanning template --list to find the template by eye. Discovery is a manual hunt.
• After: agents run build "<idea>" and get the page template + frame + blocks + foundation directly, then scaffold. Discovery is one step.

The before-runs also surfaced two frictions the sibling PRs address (called out so the picture is complete, not attributed to this PR): the docs Quick Start omitting the required reset.css/astryx.css import → unstyled renders (build-first docs PR), and StyleX-in-templates throwing at runtime → blank page on a green build (portable-templates PR).

Honest caveats

• 2/10 after-cases (table-page, form-two-column) surface the right template but rank a sibling higher — ranking still has room to improve.
• This comparison isolates discovery. It does not claim a render-success delta: agent-authored xstyle can still white-screen in a plain Vite app, which is a separate follow-up.

Method

10 stratified prompts; before = PRs' merge-base on main in an isolated worktree; after = this stack. Full per-run write-ups and the harness are in the vibe-test workspace.