How to Connect AI-Generated Frontends to a Design System with Astryx: React Components, Themes, and Acceptance Constraints

Generating one page with AI is easy; making the second and third pages retain the right colors, spacing, component states, accessibility attributes, and interaction boundaries is harder. Astryx is Meta’s open-source React design system. The official repository describes it as Beta, with 150+ accessible components, themes, dark mode, templates, and a CLI, and supports theme overrides through CSS custom properties. Official repository

The purpose of connecting Astryx to an Agent is not to let the model design freely. It is to make people and agents use the same components and documentation.

Decide whether it fits first

It is usually a fit when:

• A React project already has several back-office pages and AI-generated UI is drifting.
• The team needs consistent buttons, forms, dialogs, empty states, and dark mode.
• Agents should compose existing components instead of writing CSS from scratch.
• You can validate and version-lock a Beta dependency in isolation.

If the project is not React or already has a mature internal library, do not refactor just for a trend. Move practices such as component-first work, token-first work, and screenshot acceptance into the existing system instead.

Installation and a minimal theme

The official example uses:

1
2

npm install @astryxdesign/core @astryxdesign/theme-neutral
npm install -D @astryxdesign/cli

Verify build, style loading, and dark mode in an isolated branch or small page before expanding to the application entry point. Do not let an Agent replace global styles, the route shell, or existing token files.

A theme should express brand constraints, not let every page override itself. Record the colors, radii, typography, and spacing that may change in project rules so the Agent knows what to reuse rather than merely being told to “make it look premium.”

Start with a small page, not the application shell

Start on one route, such as settings, a filter sidebar, or a data-detail card. List its current typography, spacing, color tokens, interaction states, and components, then have the Agent rebuild one area with Astryx. Keep routing, data requests, permission checks, and the global style entry unchanged; the design system owns components and themes, not business migration.

Use a fixed local sequence: install dependencies and start the dev server; inspect light and dark modes; use Tab through forms, dialogs, and buttons; narrow the window to mobile width; then run existing tests or the build. Record issues with that component instead of discovering token overrides, CSS precedence, or focus conflicts after many pages have migrated.

Once the small page is stable, make it a reference implementation: record permitted packages, theme entry, component import style, and global files that must not change. Later Agent tasks should point to this reference rather than rediscovering conventions.

Project-level constraints for an Agent

Put rules like these in AGENTS.md, CLAUDE.md, or a Skill:

1
2
3
4
5

- 新页面优先使用 @astryxdesign 现有组件；新增自定义组件前先说明原因。
- 不新增全局 CSS reset，不修改既有主题 token。
- 所有表单字段必须有可见 label、错误态和禁用态。
- 完成后提供桌面和窄屏截图，并列出新增组件与交互状态。
- 不以截图相似为唯一验收；保留键盘操作和语义结构。

That is more actionable than “build a dashboard with the design system.” It gives the Agent prohibited changes, a reuse path, and deliverables, and lets reviewers spot whether the component library was bypassed.

Put inputs, outputs, and prohibitions in the task

A real task should state page scope, usable data, editable files, and required screenshots. For example: change only src/features/orders/FilterPanel.tsx; reuse existing query parameters; add no dependency, route, or change to theme.ts; provide desktop and narrow screenshots and list Button, Select, and Dialog states. This prevents an Agent from changing global reset, state management, or the API layer just to reach a visual result.

For a complex component, ask first for a structural draft: which sections exist, which Astryx component each maps to, and which loading/error/empty states are needed. Approve the structure before code. If the design exceeds the library, adjust the design or name an owner for the new component rather than inserting disposable CSS.

Use four acceptance layers to reduce UI drift

Visual consistency is not pixel copying. What must stay stable is accessible semantics, state machines, theme source, and maintainable component boundaries.

A repeatable acceptance process

Before merging, inspect the diff for global styles that bypass the library, hard-coded brand colors, and unrelated files. In the browser verify normal data, loading, empty data, and API failure; for forms also test required, format-error, disabled, and submitting states. Screenshots of only the normal state hide most regressions.

Finally complete a key flow with the keyboard: Tab order should make sense, focus must enter and leave Dialog, error messages must associate with fields, and color contrast must remain sufficient. Put these checks in the PR template so Agent-generated pages receive the same standard.

Common mistakes

1. Treating Beta as a reason to rewrite the site: lock a version and validate upgrade cost in one domain first.
2. Letting the Agent edit component internals: prefer composition and theme overrides; export or take over source only when necessary.
3. Writing one-off CSS per page: the system becomes only a package name and cannot constrain future Agents.
4. Accepting screenshots without interaction checks: screenshots do not reveal tab order, error feedback, or disabled buttons.

Summary

Astryx can establish a shared frontend language for people and Agents. Validate components, theme, and acceptance on a few pages first, then record the rules in project files; do not turn a new design system into another unmaintained abstraction.