Installation

Create a framework application, install @loamui/core, and load its stylesheet. The stylesheet supplies tokens, element styles and component styles; no provider is needed. Then add the skill and describe what you want to build.

@loamui/core is available on npm. Installing the agent skill does not install the library.

Quick start

Create your application with your framework's own tool, then set up LoamUI in it with one command:

pnpm dlx loamui@latest init

npx loamui@latest init

yarn dlx loamui@latest init

bunx loamui@latest init

init installs @loamui/core, links the stylesheet for the installed version, writes the layer order, adds Stylelint, Oxlint and Oxfmt with the composition checker, their scripts and one check that runs them all, writes a LoamUI section into AGENTS.md so your agent knows the setup and the checks, and installs the LoamUI skill and its companions for your agent. It only adds; nothing you have is replaced, and running it again changes nothing. --dry-run shows the plan first.

Starting from nothing? create runs the framework's own scaffolder and then init: create-next-app by default, @tanstack/cli with --framework tanstack-start, or create vite with --framework vite. Each framework guide shows its command; for any other framework, use its scaffolder and then init.

pnpm dlx loamui@latest create

npx loamui@latest create

yarn dlx loamui@latest create

bunx loamui@latest create

To see what is missing in a project, or to check it in CI:

pnpm dlx loamui@latest doctor

npx loamui@latest doctor

yarn dlx loamui@latest doctor

bunx loamui@latest doctor

Before wiring the cascade, init checks for CSS that would silently override LoamUI's element styles. Tailwind 4 is resolved with one combined layer order; Tailwind 3, another design system or a reset package hold the cascade steps back until you decide. Open your agent in the project afterwards, confirm loamui is listed among its skills, and describe what to build.

The guides below are the same setup by hand, for when you want to see what init does.

1. Choose your framework

Use a working framework application before adding LoamUI. These guides cover a fresh project, the package and the stylesheet setup:

• Next.js App Router — routing, server rendering and React Server Components.
• TanStack Start — a full-stack React framework with routing, server rendering and server functions.
• Vite — a client-only React application with no routing or server rendering.

The beta setup uses LoamUI as the styling foundation, without Tailwind or another global reset. React recommends starting new applications with a framework.

Already have a project? Check its framework, React version, CSS imports and resets first. Tailwind's presence in a manifest alone does not prove a conflict: inspect Preflight, utility classes and global rules that affect the interface. LoamUI keeps every rule inside @layer loamui.*, so an unlayered reset overrides its element styles. With Tailwind 3, Preflight is unlayered: disable it and keep Tailwind for utilities, or scope LoamUI to a subtree. With Tailwind 4, whose layers are real cascade layers, declare one combined order before any other stylesheet: @layer theme, base, loamui.tokens, loamui.elements, loamui.components, components, utilities;. Follow the existing-project workflow before changing shared styles or dependencies.

Stylesheet delivery

The core stylesheet uses modern CSS that the tested Next.js and TanStack Start bundlers cannot parse, so both framework guides load it through a stylesheet link and the browser receives the CSS unchanged. Do not also import @loamui/core/styles.css through JavaScript or CSS.

The link points at the published package on the npm CDN, pinned to the version you installed: https://cdn.jsdelivr.net/npm/@loamui/core@0.2.0/dist/styles.css. The URL is immutable, so a later release never changes a deployed application; update the package and the link together, which init does. The link needs network access and must be allowed by your site's Content Security Policy. To serve the stylesheet yourself, run init or create with --stylesheet local: it copies the installed stylesheet to public/loamui-core.css, links /loamui-core.css, and doctor checks the copy against the installed version. By hand, copy node_modules/@loamui/core/dist/styles.css into your public assets and link that instead, keeping the layer order below. Do not alter core CSS to get a build to pass.

2. Check the foundation

After completing your framework guide, confirm the application builds and the LoamUI styles load. You can use this small interface to check the foundation.

"use client";
import { Checkbox, Field, Input } from "@loamui/core";import "./welcome.css";
export default function Welcome() {  return (    <main className="welcome">      <h1>Welcome to LoamUI</h1>      <p>Native HTML and components share the same foundation.</p>      <Field.Root>        <Field.Label>Your name</Field.Label>        <Input name="name" autoComplete="name" />      </Field.Root>      <Field.Item>        <Field.Label>          <Checkbox /> Send me product updates        </Field.Label>      </Field.Item>    </main>  );}

@layer loamui.components {  @scope (.welcome) to ([class*="loam-"]) {    :scope {      display: block grid;      gap: var(--loam-space-l);      max-inline-size: var(--loam-measure);      padding: var(--loam-space-xl);    }  }}

3. Build with the skill

Once the application builds and the foundation works, you are ready to create your own interface. The next guide shows you how to install the skill, give your agent a first prompt, and review the result.

Next: Build with the skill.