This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ before writing any code. Heed deprecation notices.

Astryx v0.2.0 · 154 components CLI: run every command as npx astryx <cmd> (shown below as astryx ...).

SETUP (once, in your app entry e.g. main.tsx) — without these, components render unstyled: import "@astryxdesign/core/reset.css"; import "@astryxdesign/core/astryx.css";

WORKFLOW — discover, don't guess. Before writing UI:

astryx build "<idea>" — START HERE: returns a kit (closest [page] + [block]s + [component]s). No args = full playbook.
astryx template <name> [--skeleton] — scaffold the [page]/[block]s it named, or study their layout. Templates are reference code.
astryx component <Name> — props + examples for every component you use.

RULES:

No
— components do all layout/spacing. Full page → AppShell; sidebar nav → SideNav.
Frame first: pick the shell (AppShell / Layout+LayoutPanel) and budget regions in px BEFORE writing content (astryx docs layout).
Dense data = rows (Table, List/Item) edge-to-edge — never Card-wrapped list items. Card = dashboard widgets, galleries, settings groups only.
Status → StatusDot/Token; Badge only for counts and enumerated states, never decoration.
Custom styling: component props first; else Tailwind utilities backed by tokens (bg-surface, text-primary, rounded-lg) via tailwind-theme.css. No raw hex/px.
Tokens for every value (astryx docs tokens). Brand/accent via astryx theme — never override --color-* in :root.
SELF-CHECK before you finish: re-read the file and replace any style={{…}}, raw
/ layout, imported .css/@apply, or hardcoded/arbitrary value (e.g. bg-[#fff], p-[13px]) with the component or a token-backed utility. If unsure a component/prop exists, run astryx component <Name> / astryx search "<thing>"; don't hand-roll CSS.

MORE CLI: search "" find any component / hook / doc / template / block component --list 154 components by category template --list page + block recipes docs color, elevation, icons, illustrations, internationalization, layout, migration, motion, principles, shape, spacing, styling, theme, tokens, typography swizzle eject component source for deep customization upgrade --apply run after any @astryxdesign/core bump

Loyaly Merchant Dashboard — project rules

Toolchain

Node 22 is required (.nvmrc → 22.23.1). The astryx CLI hard-fails on Node 20. nvm use before running any npx astryx command or npm run theme:build.
Dev server runs on port 3100 (lytsup-site owns 3000).

Theme

All design values live in src/theme/loyalyTheme.ts. Edit that, then run npm run theme:build, then commit the generated src/theme/loyaly.{css,js,d.ts,variants.d.ts}.
theme:build is deliberately NOT wired to prebuild — it would break npm run build on Node 20.
Import the theme from @/theme, never @/theme/loyaly directly. @/theme re-attaches the Lucide icon registry, which astryx theme build cannot serialise (icons are React components). Skipping it silently degrades every <Icon> to Astryx's default glyph set.
globals.css imports ../theme/loyaly.css, NOT @astryxdesign/theme-neutral/theme.css. Astryx theme CSS is @scope-gated on the theme name, so neutral's rules match nothing under [data-astryx-theme="loyaly"].

The monochrome rule

Gray is the accent. The only colour permitted is semantic: success, warning, error.

Astryx's categorical hues (blue/cyan/teal/purple/pink/orange) are aliased to gray in aliasHueToGray(). green/red/yellow deliberately keep hue — Banner's semantic statuses resolve through those hue tokens.
Some neutral-theme component styles hardcode colour instead of reading a token (badge variant:info, progressbar variant:accent). Those need an explicit components override; aliasHueToGray() cannot reach them.
/tokens (dev-only route) is the audit page. After any theme change, load it and run the chromatic sweep in the browser console — it should report 0 non-semantic colour nodes.

Known upstream issues (Astryx 0.2.0)

useEntryAnimation breaks SSR hydration. Its source assumes 'use client' modules never run on the server; in the App Router they do. Any FieldStatus (i.e. TextInput/TextArea status={...}) present at initial paint renders without the slide-down class on the server and with it on the client → an unpatchable class mismatch. Setting status on blur/submit (the normal path) is unaffected. Don't server-render a field that already has a status.
Component keys in defineTheme({components}) are inconsistently cased: text-input but progressbar. The CLI warns on unknown keys — treat any ⚠ Unknown component from theme:build as an error, it means the override silently did nothing.

Conventions

Follow the Astryx rules above: no raw <div> for layout, no hardcoded hex/px, component props first then token-backed Tailwind utilities.
src/lib/icons.ts is the single icon map. Only the 26 semantic names resolve via <Icon icon="search"/>; everything else is <Icon icon={ICONS.stores}/>. Never import a lucide icon directly into a feature file.

5.5 KiB Raw Blame History