Getting Started

Areia is a Vanilla TypeScript-first UI kit for Ilha. Start by importing ready-made components, then eject/copy component source later when your product needs deeper customization.

Install

Install Areia in your Ilha project:

npm install areia
# or: bun add areia
# or: pnpm add areia

Some components use optional peer packages. For example, install sonner when using the Sonner/Toaster component:

npm install sonner
# or: bun add sonner
# or: pnpm add sonner

Import a component

Use components directly from areia:

import ilha from "ilha";
import { Button } from "areia";

export default ilha.render(() => (
  <Button variant="primary">Create project</Button>
));

Use JSX or html literals

Areia components are designed for Ilha and can be used with JSX or Ilha's html literal style.

import ilha, { html } from "ilha";
import { Button } from "areia";

// Default JSX syntax
export default ilha.render(() => (
  <div class="flex gap-2">
    <Button variant="primary">Save</Button>
    <Button variant="secondary">Cancel</Button>
  </div>
));

// No-build html template literal
export default ilha.render(
  () => html`
    <div class="flex gap-2">
      ${Button({ variant: "primary", children: "Save" })}
      ${Button({ variant: "secondary", children: "Cancel" })}
    </div>
  `,
);

Add styles

Areia is handcrafted with Tailwind. First, install and configure Tailwind in your app — the Tailwind Vite installation guide is the recommended starting point for Vite-based Ilha projects.

After Tailwind is configured, make sure your app styles are loaded by Ilha. A minimal app stylesheet might look like this:

@import "tailwindcss";
@plugin "areia";

@plugin "areia" registers the full --areia-* token set (light and dark), maps them into Tailwind utilities, adds a dark: variant for .dark roots, and scans Areia's built output in node_modules for class names.

Then add your own utilities and overrides as your app grows.

Theme Areia

Areia components rely on Tailwind utilities backed by --areia-* design tokens. Load the built-in theme with:

@import "tailwindcss";
@plugin "areia";

Or import the bundled entry:

@import "tailwindcss";
@import "areia/tailwind.css";

Override any token in :root or .dark after loading the theme.

Most components use the same token groups: surfaces (background, surface, surface-muted), text (foreground, text-default, text-subtle), borders/focus (border, divider, ring), controls (control-background, control-hover, control-active), and semantic colors (primary, success, warning, destructive, info). Copy the full token set from docs.css when you want complete coverage for every component variant.

Customize later

The recommended flow is progressive:

Import components from areia to move quickly.
Build screens and product flows with the default behavior.
When a component needs custom behavior or markup, copy/eject its source into your app.
Keep using Areia primitives and Tailwind conventions around your customized components.

This keeps the early development loop fast while still giving you ownership of the final UI.