Getting Started

Installation

Install, import, and configure Aster DS in modern web applications using npm or direct browser distributions.

Before you start

Aster is plain HTML, CSS, and browser JavaScript, so no framework is required. You need npm, pnpm, or yarn for a package install, or nothing at all for the CDN option below. It targets current browsers because it relies on modern CSS, such as color-mix() and :has().

1. Install using npm

Install the official Aster DS package from the npm registry:

Terminal

npm install aster-ds

Or with your preferred package manager:

Terminal

# pnpm
pnpm add aster-ds

# yarn
yarn add aster-ds

2. Import CSS Stylesheets

Import Aster's compiled stylesheets in your application's entrypoint or layout:

JavaScript / CSS Entry

// All-in-one stylesheet (tokens + components)
import 'aster-ds/aster.css';

Or import tokens and components separately:

JavaScript / CSS Entry

import 'aster-ds/tokens.css';
import 'aster-ds/components.css';

3. Typography Web Fonts

Include the 4 canonical Google Fonts in your document's <head>:

HTML <head>

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Bebas+Neue&family=Manrope:wght@400;500;600;700&family=Merriweather:ital,wght@0,300;0,400;0,700;1,300&family=Space+Mono:ital,wght@0,400;0,700;1,400&display=swap" rel="stylesheet">

4. Initialize Behaviors

Aster components feature zero runtime framework dependencies. Initialize delegated behaviors (dialog focus trap, ripple effects, drawer dismiss) once on mount:

Client Entry

import { initAsterComponents } from 'aster-ds';

// Initialize interactive behaviors across the document tree
initAsterComponents(document);

5. Use a CDN instead

For a quick prototype with no build step, load Aster directly. Pin the version so updates can't change your page unexpectedly.

HTML

<link rel="stylesheet" href="https://unpkg.com/aster-ds@0.2.0/dist/css/aster.css">
<script type="module">
  import { initAsterComponents } from 'https://unpkg.com/aster-ds@0.2.0/dist/js/aster.js';
  initAsterComponents();
</script>

6. Check it works

Add a button. If it looks like a dark or white pill and reacts when hovered, the stylesheet is loading.

Problem	Likely cause
Components have no styling	The stylesheet isn't imported, or only `components.css` is loaded without `tokens.css`.
Fonts look wrong	The web fonts in step 3 aren't loaded.
Dialogs, tabs, or menus don't respond	`initAsterComponents()` wasn't called.
Dark mode doesn't apply	Set `data-theme="dark"` on the `html` element.
The Select menu looks plain	That browser doesn't support `appearance: base-select`, so it shows its native menu. It still works.