Astryx Web Integration

Archived: 2026-11-07 · roadmap-id: web-design-system

Why

Projects generated from web-tanstackstart are mostly written by AI coding agents, including weak models (Codex + deepseek-flash). Left alone, they lay pages out from scratch and stack components without a plan; the first such Web (TheFoolAI lean-flowkit) has to be redesigned. An audit and three spikes on 2026-11-06 (thefoolai PRD dp-web-design-system §1, W1–W11) found:

• The agents that built lean-flowkit never ran astryx build; every page was assembled from component APIs.
• Astryx's own page templates cannot be used as-is in this template. Each one brings its own shell (AppShell, a local Theme with its own appearance state), viewport media queries, icon packages the template does not have (@heroicons/react, lucide-react), and 30–170 hard-coded English strings. A weak model has to rewrite most of the page, which is how pages end up arbitrary.
• Astryx 0.7.5 has no mobile-first page template. Intents such as "step-by-step practice session on mobile" fall back to shell-top-nav. Mobile is a primary surface for these Webs.

Astryx integrations can add page templates, replace built-in ones, ship searchable docs, and append agent guidance to AGENTS.md. A spike on 0.7.5 confirmed all four work from a local package.

Non-goals

• Wiring the package into web-tanstackstart, the page:new entry, and provenance checks (change web-tanstackstart-page-from-template).
• The design-direction skill, the DESIGN.md contract, and the design gate (change web-tanstackstart-design-direction).
• Moving TemplateShell, PageShell, and the other layout primitives into the package as components. Deferred until a shell change has to reach projects that already exist.
• Detail-page and mobile task-flow (practice session) archetypes. Deferred until a project needs them.
• Custom themes. Projects use Astryx built-in themes plus a brand palette generated per project.
• The web-tanstackstart-kids template.