Mastering Astryx / lesson 1 of 13

Introduction, Setup & Architecture

Get started with Astryx: installation, Next.js setup, CSS layer imports, client provider boundaries, and the first stub of our Kanban board.

Transcript

00:00 To get started with the Astryx design library from Meta, we’re going to create a new next application here. We’re going to call it My-Astryx-App. We’re going to be running TypeScript, the app router, source directory, no Tailwind, and no ESLint. That’s set up.

00:18 So we’re going to CD into our project. We’re going to install these libraries, the @astryxdesign/core library. That’s the entire design system. The theme neutral, it’s just a theme that’s available to us. Hero icons, because they use it, so I’m going to use it. And then style X, which is a CSS in JavaScript library. Okay, that’s set up.

00:41 So we’re going to open up Zed. And first thing I’m going to do is I’m going to kill these agent files. We don’t need them. I’m going to jump into our source app. We also don’t need this page modules file. Here in our global CSS, we’re going to kill everything. We’re just going to bring in these core CSS elements from AstryxDesign. So we’ve got a reset, Astryx, and then we’ve got our theme neutral theme.css. We’re going to jump into our layout.

01:11 We’re going to kill everything that’s there. We’re going to drop in a very generic root layout component here. There’s nothing Astryx specific. I am going to need to create this provider’s component. So I’ll do that now. Okay, that’s going to be used client. Now we’re bringing in just a type from React node, but also our theme component from core. And then the neutral theme from theme neutral. It’s important that you have this built bit here. You do need the pre-compiled version. We’re going to export a function called providers. And that’s just going to take in children to be a type of React node. And we’re going to return a theme. Inside of that, we’ll have our children. And on this theme, we’ll have an attribute of theme. And we’ll say, sorry, neutral theme. And then we’re going to have mode. And that’s going to be equal to system for now. So that’s your light, dark, or system mode. So we’re going to save that. And now if we jump over to our layout, our little error is gone.

02:25 Now our primary component is going to live in this components directory. And it’s going to be called Kanbanboard.tsx. So there is a demo UI in the Astryx library in their documentation. It’s very similar to this, the Kanban board. But it’s all in one file. And it doesn’t really touch on a lot of the features available to you in Astryx. So we’re going to rebuild that UI with a whole bunch of added features. And we’re going to build it out very modularly.

03:00 Okay, so this is going to be used client. And we’re bringing in card from Astryx design core slash card. And then heading and text from text. So there is a CLI tool that will tell you where all these things are. But you do end up having to call the very specific component file for the component that you’re looking for. And here we’re going to export a default function called Kanbanboard. And that’s pretty close. We’re going to have a card. We’re going to give it a padding of four. So you’re going to see a lot of these types of props that represent design tokens throughout this course. So padding is one of them. We’ll be diving more into that stuff later. On heading, we can go level two. So it’s like an H2. And on text, we’re going to say color is secondary. Again, another design token. Very similar to other things you might have used. So rather than primary, this is secondary. There’s also an accent and all of that good stuff. Okay. We’re going to save that.

04:11 And then the last thing we’re going to do is jump over to our page TSX. We’re going to kill everything that’s there. And we’re just going to drop in our Kanban board. And we’re going to render that. So let’s see if our application is working. So we’re going to npm run dev. That should be on localhost 3000. And there’s our Kanban board. So we’ve got a nice, very simple little shell. In the next lesson, we’re going to use a bunch of primitives to start making this more of a layout. We’ll touch on layouts and headers and sections. And more interestingly, H stacks and V stacks and things of that nature.

Welcome to Mastering Astryx! Astryx is a modern, open-source design system built on top of StyleX. It combines zero-runtime performance with a fully customizable, type-safe suite of React primitives.

In this lesson, we will set up an Astryx project using Next.js, configure CSS import layers, wrap the app in client providers — including a theme provider with light/dark support — and create the first stub of the Kanban board we will build together across this entire course.

The Course Build: One App, Built in Place

This course has a simple philosophy: we build the actual Kanban app, not throwaway demos. From this lesson on, page.tsx stays untouched — it simply renders KanbanBoard, and every lesson grows the board itself (or one of its components). No more overwriting page.tsx with a one-off demo page.

By the end of the course, your project will look like this:

src/
└── app/
    ├── globals.css                  # CSS layer imports
    ├── layout.tsx                   # Root layout (written once)
    ├── page.tsx                     # <KanbanBoard /> (written once)
    ├── providers.tsx                # Theme + i18n providers + usePreferences()
    ├── messages.ts                  # en/fr translation catalogs
    ├── types.ts                     # Domain contracts
    ├── data.ts                      # Column configs, priorities, initial items
    ├── styles.ts                    # Centralized StyleX stylesheet
    ├── hooks/
    │   └── useKanbanDrag.ts         # Drag-and-drop interaction hook
    └── components/
        ├── BoardCardBody.tsx        # Work item presentation
        ├── BoardCard.tsx            # Interactive card shell
        ├── BoardColumn.tsx          # Column shell & empty state
        ├── BoardToolbar.tsx         # Top bar: sprint, actions, theme & language toggles
        ├── FloatingCard.tsx         # Fixed drag overlay clone
        └── KanbanBoard.tsx          # The board — grows every lesson

Keep this tree in mind — every lesson maps to a file or two in it.

Setup Steps

1. Initialize Next.js Application

Create a new Next.js project with TypeScript and the App Router enabled:

npx create-next-app@latest my-astryx-app --typescript --app --src-dir --no-tailwind --no-eslint
cd my-astryx-app

2. Install Dependencies

Install @astryxdesign/core, @astryxdesign/theme-neutral, @heroicons/react, and @stylexjs/stylex:

npm install @astryxdesign/core @astryxdesign/theme-neutral @heroicons/react @stylexjs/stylex

@astryxdesign/core is the design system itself. @astryxdesign/theme-neutral is the theme package we will use (light and dark token sets included). @heroicons/react provides the icons Astryx components render. @stylexjs/stylex is the styling engine — we write our first stylex.create styles in lesson 4.

3. Configure CSS Layer Imports

Open the generated src/app/globals.css file and replace its contents with the reset, component base styles, and theme variables in the exact required order:

@import '@astryxdesign/core/reset.css';
@import '@astryxdesign/core/astryx.css';
@import '@astryxdesign/theme-neutral/theme.css';

The CSS import order is critical for CSS layer precedence:

reset.css: Baseline resets (@layer reset)
astryx.css: All component styles (@layer astryx-base)
theme.css: Theme token overrides (@layer astryx-theme)

Import globals.css inside your root layout and mount the client Providers boundary:

import './globals.css';
import { Providers } from './providers';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

4. Create the Client Providers Boundary

Interactive state — themes, locale — runs on the client in Next.js App Router, so the provider boundary must be marked 'use client'. From day one we wrap the app in Astryx’s <Theme> provider so light/dark token resolution is in place before we ever toggle it (lesson 5 adds the toggle button):

'use client';

import type { ReactNode } from 'react';
import { Theme } from '@astryxdesign/core';
import { neutralTheme } from '@astryxdesign/theme-neutral/built';

export function Providers({ children }: { children: ReactNode }) {
  return (
    <Theme theme={neutralTheme} mode="system">
      {children}
    </Theme>
  );
}

<Theme theme={neutralTheme}> activates the neutral theme’s token set.
mode="system" (the default) follows the OS color scheme — light or dark — automatically.
We import neutralTheme from @astryxdesign/theme-neutral/built because globals.css already loads the pre-compiled theme.css. The /built subpath pairs with that CSS and skips runtime style injection (the correct setup for Next.js SSR). The plain @astryxdesign/theme-neutral import injects styles at runtime instead — pick one and stay consistent with how the CSS is loaded.

5. Create the Kanban Board Stub

Create the folder src/app/components/ and a first stub of the board. It will be replaced by the real shell in lesson 2 — but the file location is permanent:

'use client';

import { Card } from '@astryxdesign/core/Card';
import { Heading, Text } from '@astryxdesign/core/Text';

export default function KanbanBoard() {
  return (
    <Card padding={4}>
      <Heading level={2}>Sprint Board</Heading>
      <Text color="secondary">
        The Kanban board is under construction — we will build it together
        over the coming lessons.
      </Text>
    </Card>
  );
}

KanbanBoard declares 'use client' because it will own interactive state later. That makes it the App Router client boundary — the page itself can stay a server component.

6. Mount the Board in `page.tsx` (Written Once)

Replace the generated page with a single render of the board:

import KanbanBoard from './components/KanbanBoard';

export default function Page() {
  return <KanbanBoard />;
}

Note: no 'use client' here. page.tsx stays a server component; KanbanBoard is the client boundary. We will never touch page.tsx again.

7. Clean Up Boilerplate

create-next-app leaves scaffolding we don’t need. Delete:

rm src/app/page.module.css

page.tsx, globals.css, and layout.tsx are already replaced above. The rest of src/app/ (favicon, etc.) can stay.

See It in Action

Run the dev server:

npm run dev

Open http://localhost:3000 — you should see a card titled Sprint Board with supporting secondary text, centered on the default page. If it renders with correct spacing and typography, your Astryx baseline is live.

What You Built

A Next.js + Astryx project with the correct CSS layer import order.
A client Providers boundary with the <Theme> provider already active (mode="system" — flip your OS to dark and the page re-themes instantly).
A KanbanBoard stub mounted in page.tsx, which you will never rewrite again.

In the next lesson, we will shape that stub into the real board shell using Astryx layout primitives.

Share this post on:

Layout & Spatial Composition