astryx-max

name

astryx-max

description

Build production-grade sites with the Astryx design system (@astryxdesign/*) that don't look AI-generated. Use this whenever the user wants to build, scaffold, design, or improve a real website, landing page, dashboard, or app UI with Astryx — or says "astryx max", "make this astryx site look designed / not like AI slop", "push astryx further", or is unhappy with a generic Astryx build. This skill grounds the model on the full Astryx CLI capability manifest so it uses real components and flags instead of guessing, then runs a screenshot → critique → fix loop in a headless browser to catch the alignment, hierarchy, and palette problems that make agent-built sites look generated. Prefer this over building an Astryx site freehand — the manifest grounding and visual loop are the whole point.

Astryx Max

Astryx out of the box builds correct but generic sites: it leans on bare templates, reaches for the default blue/black palette, and can't see that a card wrapped to a new line or a product row isn't centered — because a text-only agent never looks at the rendered page. The result reads as "AI-built."

This skill fixes both problems. First it grounds the model on everything the Astryx CLI can actually do, so it composes from real components instead of guessing. Then it looks at the running site and iterates — the same thing a designer does when they open the browser and go "hm, that's off." Grounding + eyes is the whole idea.

When you're done, the site should

• use real Astryx components pulled via the CLI (not hand-rolled markup),
• pass a visual review (aligned grids, deliberate depth/spacing, clear hierarchy), and
• avoid the AI-slop tells in references/slop-patterns.md.

The workflow

Work through these in order. Steps 4–6 are a loop — that's where the quality comes from, so don't skip straight to "done" after the first build.

1. Ground on the manifest (do this first, always)

The single most important step. Run:

npx astryx doctor          # confirm setup is sane; fix failures it reports
npx astryx manifest --json > .astryx/manifest.json

manifest --json emits the full CLI capability map (~25KB: every command, flag, and option). Read it. This is what lets you use commands and flags you'd otherwise never know existed — the difference between "I'll guess at a template" and "I know search, component, template, build, swizzle, layout exist and what each takes." If .astryx/manifest.json already exists and npx astryx --version matches the version inside it, reuse it; only regenerate when the CLI version changed.

2. Discover what already exists

Don't rebuild from scratch — Astryx ships 150+ components and page templates. For the thing the user asked for, query the library:

npx astryx build "<the user's idea>"   # composition kit for a page idea
npx astryx search "<keyword>"          # ranked components/hooks/docs/templates
npx astryx component <Name>            # props + usage for a specific component
npx astryx template                    # list page/block templates

Start from the closest template or composition kit, then adapt. Pull component docs with component <Name> before using one so you get props right.

3. Build, following the design rules

Compose the page from real components. Before you write layout code, read references/design-rules.md — it encodes the specific failures that make Astryx builds look generic (card wrapping, uncentered rows, default palette) as positive rules to build by. Wire a non-default theme; don't accept the blue/black reach.

Next.js note: if astryx init offers a template, put it in app/ not pages/ (see the project/global CLAUDE.md astryx gotcha). Plain Vite/React has no such concern.

4. Render it — actually look

Start the dev server, then drive a headless browser to see the page. The chrome-devtools MCP tools are ideal (they may be deferred — load them with ToolSearch first: navigate_page, take_screenshot, take_snapshot, list_console_messages). claude-in-chrome works too.

navigate_page  → http://localhost:<port>
take_screenshot (full page, and again at a mobile width via resize/emulate)
list_console_messages  → any errors mean the build is broken, fix before judging looks

A screenshot is not optional polish — it's the only way to catch problems that are invisible in source (wrapping, misalignment, weak contrast, cramped spacing). Text-only, you will ship these.

5. Critique against the rubric

Grade the screenshot with references/review-rubric.md and run it through references/slop-patterns.md. Be a harsh reviewer: name concrete defects with locations ("the third pricing card wraps below the row at desktop width"), not vibes. If it looks like a textbook generated SaaS page, say so and why.

6. Fix and loop

Apply fixes for what you found, re-render (step 4), re-critique (step 5). Repeat until the rubric passes clean or you hit 3 rounds — whichever comes first. Diminishing returns after ~3; if it's still failing then, surface the remaining issues to the user rather than looping forever.

7. Verify

Final pass of the checks in references/review-rubric.md (§Evals): no console errors, non-default palette in use, headings form a real hierarchy, layout holds at mobile width. Then report what you built, which components you used, and anything you couldn't resolve.

Reference files

• references/design-rules.md — how to build so it doesn't look generic (read before step 3).
• references/slop-patterns.md — the enumerated "AI slop" tells to detect and eliminate (used in steps 5–6). Extend it: when the user says something still looks AI-made, add that pattern here so the skill gets smarter over time.
• references/review-rubric.md — the screenshot grading rubric + the final eval checklist (steps 5 and 7).