Getting started

Build your first Stardwst interface

Use CSS with native HTML or your own framework. Use the React adapter for components with built-in interaction behavior. Both require the CSS package.

Private workspace required. @stardwst/css and @stardwst/react are private workspace packages. They are not available from the public npm registry.

Private workspace

Set up the local packages

Clone the private repository, then run these commands from its root. Ask a repository administrator for access if needed.

1
Install and build the workspace packages
Use Node.js 26 and pnpm 11.22.0.
```
pnpm install
```
For React apps, build the adapter after installing. Installation alone does not create@stardwst/react/dist/index.mjs.
```
pnpm -C design-system build:react
```
2
Declare the local dependency
For an app in application/core, add these local links to itspackage.json, then rerun pnpm install. Omit@stardwst/react for CSS-only apps.
```
{
  "dependencies": {
    "@stardwst/css": "link:../../design-system/packages/css",
    "@stardwst/react": "link:../../design-system/packages/react"
  }
}
```

CSS

Start with a styled native control

Import the stylesheet once for tokens, scoped base styles, recipes, and themes. Classes provide styles; use native elements or adapter components for keyboard interaction, ARIA states, and focus management.

1. Load the full stylesheet

/* src/app.css */
@import "@stardwst/css/styles.css";

2. Add a design island

<section class="stardwst">
  <button class="button filled" type="button">Save changes</button>
</section>

Keep the island narrow

The .stardwst wrapper is where Stardwst applies its reset, tokens, theme, and recipes. Keep it around the interface you own so host content does not pick up short recipe class names such as .button or .card.

Use tokens only when you own the recipes

tokens.css exports the token contract without the reset, themes, or component recipes. The tokens still live in a .stardwst island. Use this entry point for a custom visual system that still needs Stardwst values.

@import "@stardwst/css/tokens.css";

React

Use React components inside the same island

@stardwst/react has react 19, react-dom 19, and@stardwst/css peer dependencies. Import the stylesheet yourself, then import only the components your feature uses.

import "@stardwst/css/styles.css"
import { Button } from "@stardwst/react"

export const SavePage = () => (
  <main className="stardwst">
    <Button variant="filled">Save changes</Button>
  </main>
)

Find usage examples and APIs in the component reference.

Portals

Keep portalled content in its source context

Portalled content needs its source island's styles even when it renders outside the container.

Render Portal inside the .stardwst island. It creates a new island for the portalled content and keeps its theme classes, custom properties, language, and direction in sync with its own position in the tree. Pass an element assource only when the content should follow a different part of the page.

Portal supplies styling context only. It does not make arbitrary markup act as a menu or a modal dialog. Use the adapter's Menu or Dialog component when you need that interaction contract.

If you use another portal implementation, follow the CSS portal requirements.

import { useState } from "react"
import { Portal } from "@stardwst/react"

export const Status = () => {
  const [open, setOpen] = useState(false)

  return (
    <section className="stardwst">
      <button
        aria-expanded={open}
        className="button outlined"
        onClick={() => setOpen(!open)}
        type="button"
      >
        Show status
      </button>
      {open && (
        <Portal>
          <aside className="card">Build is ready for review.</aside>
        </Portal>
      )}
    </section>
  )
}

Cascade and browser support

Add product-specific styles locally

Stardwst styles are placed in named cascade layers and scoped to the design island. An unlayered rule in your application stylesheet can override a recipe when a local change is needed.

.stardwst .project-summary {
  max-inline-size: 60ch;
}

The stylesheet targets modern evergreen browsers with support for cascade layers and@scope. Check both features against your product's browser requirements. The package does not include an @scope fallback.

Custom properties

Customize through foundation tokens

Set a foundation token on the .stardwst wrapper when one shared choice should apply throughout an interface. This roundness override changes recipes that use the default radius.

.stardwst.project-theme {
  --roundness: var(--roundness__lg);
}

Use a component property only when its CSS recipe documents it. Properties such as--button__background are recipe mappings, while foundation tokens form the shared contract. Read the foundation token guidebefore introducing a new global choice.

Before shipping, check keyboard interaction, themes, and portal context in your app. Follow the accessibility checks.

Install and build the workspace packages

Declare the local dependency

Keep the island narrow

Use tokens only when you own the recipes