# LoamUI

> Documentation for `@loamui/core` — modern UI primitives for
> agent-assisted developers: contextual tokens, element styles and React
> components on native modern CSS. Every page has a markdown twin at the
> same URL with `.md` appended. Treat these documents as authoritative
> for the library. `/AGENTS.md` is a one-page summary of the conventions
> an agent needs when writing against the package.

## Start here

The package supplies tokens, element styles and React components. The skill guides project setup, composition and verification; installing the skill does not install the package.

- Set up a framework and LoamUI: [Installation](https://loamui.com/docs/installation.md).
- Prepare a project or add the skill: [Build with the skill](https://loamui.com/docs/agent-workflow.md).
- Build a named recipe: find it below, read its React/CSS and the contracts of the components it uses. For a new pattern, read the [recipe guide](https://loamui.com/recipes/guide.md) and the nearest relevant recipe.
- Check the installed package exports/types against these references. The site follows the current source; installed package versions can differ.

## Implementation brief

Use this brief even when the LoamUI skill is not installed. Follow the essential rules below, then read the selected recipe and component contracts before implementation. If you cannot retrieve them, use bundled skill references or request the needed material; do not invent APIs.

### Establish the environment first

Every request starts with `loamui doctor`, even when the prompt only names a recipe. Complete missing setup with `loamui init` within the user's authorization; ask before anything that would replace a conflicting tool, stylesheet, framework or browser policy, or touch CI, and do not treat silence as approval. Read the project's instructions, manifest, lockfile, stylesheet entry and existing components, and check the installed `@loamui/core` version and exports: the documentation and the installed package are not always the same version. Confirm the four skills are discoverable by the active agent, not merely present on disk. Temporary or scratchpad checks do not complete setup. If setup is blocked or declined, agree a reduced scope and say so in the report.

Repository setup requires a React framework application; the supported paths are Next.js App Router, TanStack Start and Vite. In an existing project, inspect resets, unlayered element rules and Tailwind before composing, state the specific conflict and affected files, and propose an integration rather than silently removing a dependency or rewriting the site's styling foundation.

### When there is no repository

Identify capabilities rather than guessing from a product name: can the environment install the real package, resolve its React exports, load its CSS, render the result and run checks? Build with the real library where it can; otherwise supply complete React and CSS files, the required dependencies and the application setup, and state that rendering and runtime behaviour remain unverified. If a required reference is unavailable, use the skill's bundled references or request the missing material. Never recreate fake `@loamui/core` exports, borrow `loam-*` classes on raw elements, substitute another UI library, or claim an approximation is LoamUI.

### Design before code

Follow the Frontend Design skill's process before the first component: ground the work in the subject and audience, write a short design plan, review it for genericness, then build. The user's brief decides what; Frontend Design decides the direction; LoamUI decides the expression, as [Design](https://loamui.com/docs/design.md) describes. A real product gets its own theme; the default palette and typeface are a starting point.

### The contract for every implementation

The three primitives are **tokens**, **element styles**, and **components**. Use semantic HTML and the existing element defaults first. Use `--loam-*` tokens for visual decisions. Compose core parts when they supply needed behaviour or anatomy; there is no requirement to import a component just to demonstrate a primitive.

#### Modern

- **Native platform:** use semantic elements and static styles. Actions are buttons; destinations are links. Native `<button>`, `<dialog>` opened with `showModal()`, and `<details>` supply platform behaviour; use documented LoamUI components when composing those behaviours. Do not recreate controls with clickable divs or use a styling runtime.
- **Modern CSS:** put recipe rules in `loamui.components` within `@scope (.recipe) to ([class*="loam-"])`. Limit article styles at embedded previews as well as core roots, so documentation cannot restyle a recipe. Inside a scope the markup is the API: reference elements by type, use a class only for a real distinction between siblings of the same type, and add no wrapper element that exists only to carry one. Combine nesting, logical properties and additive conditions with container queries, intrinsic grid/flex and subgrid where appropriate. Tokens already supply `clamp()`, `oklch()` and `light-dark()`; do not duplicate their palette or force every CSS feature into a recipe. Avoid `!important`, BEM and private core selectors. LoamUI permits Baseline Newly or Widely Available features; features outside that policy need progressive enhancement, and a consumer's browser policy is never changed silently.
- **Composition through components:** read the relevant component contract before using parts or props. Keep core internals intact. Use `render` for supported element substitution. Button icons are children; Input has documented adornment props. Supply real application actions through a clear integration boundary.
- **Contextualism throughout the primitives:** put `--loam-context` on the region that carries the meaning. Leave ordinary content neutral. Layout and available space govern sizing; do not invent `variant`, `color` or `fullWidth` props. Documented intrinsic sizes and native HTML attributes are exceptions. Identity is the last resort: a brand-coloured wrapper is legitimate, a per-element colour is not. Resolve fluid font tokens on content inside its measuring container: inherited computed font sizes do not re-evaluate when a new container is introduced.

An element cannot size-query itself. Put the measuring container outside the layout it controls. A recipe may use ordinary geometry such as a border width, aspect ratio or column threshold; design colours, spacing and typography come from tokens. A translucent image overlay needs contrast measured over the rendered photograph. Images may crop with `object-fit: cover` while text determines the component height; do not fix the text area's height or measure it with JavaScript.

#### Accessible

Preserve native labels, keyboard behaviour, focus, readable contrast and user preferences. Keep primary information visible; use Details for secondary information. Use Field's label, description, error, control order. Required fields are unmarked; mark optional fields in words. Errors say how to fix the value. After a submission attempt, clear a displayed native constraint error once its value is valid, keeping focus in the field and the summary in sync. Do not create new errors during typing or treat native validity as proof that server errors are resolved. A screenshot or axe pass cannot certify these requirements.

### Read and adapt a reference

Search Google Chrome's Modern Web Guidance for each platform pattern the work needs and read the Modern CSS rules that apply. Read the [recipe guide](https://loamui.com/recipes/guide.md), the selected recipe's complete TSX and CSS, and the reference for each core component used; skill users can read these offline in `references/`. Each recipe page shows a short prompt that names the LoamUI skill and recipe; resolve the name through the bundled reference index rather than asking the user to restate the rules.

When no recipe matches, and for most of a real site none does, build the section from the primitives rather than forcing the nearest recipe onto content it does not fit. Work down the ladder: a native element the element styles already dress; a semantic element with a scoped rule, named for what it is in the product; a composition of existing components and elements; and only then a new component, for behaviour a native element lacks. Give it the shape every recipe has: its own component file with its stylesheet beside it, never inline JSX in a page; one root class, rules in `loamui.components` inside a scope with the donut, tokens for colour, space and type, the measuring container outside the layout it controls, one job per section, the right heading level. A page assembles sections; it does not contain them. Model the structure on the nearest recipe; never borrow `loam-*` class names, invent a part, or substitute another library. The review applies to it exactly as to an adapted recipe.

Preserve the recipe's role: a hero introduces a page; a banner promotes one message within it; a card represents one item. Adapt content, heading level, alternative text, dates and destinations together. Keep image priority appropriate to placement: eager for the critical hero, lazy for genuinely offscreen media. Do not put docs previews, gallery loading, generated metadata or source viewers in the copied component. Use idiomatic React: state for user interaction, effects for external synchronisation, `useId` for actual relationships, client directives only where the framework needs them.

### Review, repair and report

Gatekeeping is how trust in agent work is established, separate from the two pillars. Checks have a defined scope; passing them is evidence for what they check, not certification of the whole interface. Nothing is reported until it has been reviewed, as a distinct pass with its findings written down, in this order:

1. **Gates.** The project's `check` script, type checker and tests. Fix what they report; never disable a check to pass it. Do not hand-review what they verify.
2. **Philosophy.** The composition against the contract above: primitives in the right order, a native element before a component, context not props, parts not configuration, Field wiring, the scope donut, no reset, identity only where legitimate, each section its own component file.
3. **Modern CSS.** The authored CSS against the rules no lint enforces: `oklch()` only, fluid `clamp()` with a rem term, flow-relative properties, `:has()` over state classes, container units over fixed spacing, non-overlapping ranges, motion opt-in, and for every class inside a scope, whether a type selector would have done.
4. **Modern Web Guidance.** For each pattern searched, confirm the guide's approach was taken, or say why not.
5. **Rendered result.** Both colour schemes at a narrow and a wide width, long copy, enlarged text, two instances, keyboard and focus, reduced motion, forced colours, RTL where direction matters; form validation, value preservation and the real submission boundary where relevant; every contrast pair the theme changed, measured. Then the design plan: one memorable thing, everything else quiet, one thing removed.

Each finding is `file:line`, the rule it breaks and the fix; repair it and re-run the affected gate. Report what ran, what was found and fixed, what was looked at, and what remains unverified. Do not label generated code fully conformant when required evidence is missing.


## Guides

- [Introduction](https://loamui.com/docs.md): Modern UI primitives for agent-assisted developers: contextual tokens, element styles and React components built on Google's Modern Web Guidance.
- [Installation](https://loamui.com/docs/installation.md): Set up LoamUI in one command, or by hand in Next.js, TanStack Start or Vite, check your first interface, then build with the agent skill.
- [Build with the skill](https://loamui.com/docs/agent-workflow.md): Install the LoamUI skill, give your agent a first prompt, and review the interface it builds.
- [Tokens](https://loamui.com/docs/tokens.md): The token primitive: a handful of semantic decisions, everything else derived, and the theming that falls out of it.
- [Element styles](https://loamui.com/docs/element-styles.md): The element-styles primitive: enhanced default styles for native HTML, page-wide. Plain markup is already styled before any component appears.
- [Components](https://loamui.com/docs/components.md): The third primitive: a small, curated set of accessible components composed from tokens and element styles.
- [Contextualism](https://loamui.com/docs/contextualism.md): The paradigm shift under all three primitives: context decides appearance, and identity is the last resort.
- [Building your own recipes](https://loamui.com/recipes/guide.md): Build portable React components from LoamUI’s tokens, element styles and components, using the Recipes as worked references.
- [Design](https://loamui.com/docs/design.md): Give an interface its own identity on the primitives: a design plan first, then the token inputs, typefaces and layout that express it.
- [Layout](https://loamui.com/docs/layout.md): Layout is native CSS. Pick the module that fits the shape of the content, and space it with the space tokens.
- [Typography](https://loamui.com/docs/typography.md): How the type scale, rhythm and figures work, and how to build your own domain-specific typography on top of them.
- [Accessibility](https://loamui.com/docs/accessibility.md): What LoamUI guarantees: platform semantics, APG keyboard patterns, engineered WCAG specifics, and user preferences as the baseline.
- [Install with Next.js](https://loamui.com/docs/installation/nextjs.md): Set up LoamUI with Next.js App Router and native CSS.
- [Install with TanStack Start](https://loamui.com/docs/installation/tanstack-start.md): Set up LoamUI with TanStack Start and native CSS, without Tailwind or a UI kit.
- [Install with Vite](https://loamui.com/docs/installation/vite.md): Set up LoamUI in a client-only React application built with Vite, with native CSS.

## Components: Inputs

- [Field](https://loamui.com/docs/components/field.md): Composable form-field primitive.
- [Fieldset](https://loamui.com/docs/components/fieldset.md): Group controls under a semantic label.
- [ErrorSummary](https://loamui.com/docs/components/error-summary.md): List form errors as links to their fields.
- [Button](https://loamui.com/docs/components/button.md): Trigger an action or event.
- [Input](https://loamui.com/docs/components/input.md): A labelled text field.
- [PasswordInput](https://loamui.com/docs/components/password-input.md): A password box with a show toggle.
- [Textarea](https://loamui.com/docs/components/textarea.md): Multi-line text input.
- [Select](https://loamui.com/docs/components/select.md): Choose one option from a list.
- [Combobox](https://loamui.com/docs/components/combobox.md): A text box with a list of suggestions under it.
- [DateInput](https://loamui.com/docs/components/date-input.md): Labelled fields for a memorable date.
- [Checkbox](https://loamui.com/docs/components/checkbox.md): Toggle a single option on or off.
- [Radio](https://loamui.com/docs/components/radio.md): Choose one option from a set.
- [SegmentedControl](https://loamui.com/docs/components/segmented-control.md): Choose one option from a row of segments.
- [Switch](https://loamui.com/docs/components/switch.md): An on/off toggle switch.
- [Range](https://loamui.com/docs/components/range.md): Pick a numeric value from a range.
- [Search](https://loamui.com/docs/components/search.md): The page's search, as a landmark.
- [QuantityInput](https://loamui.com/docs/components/quantity-input.md): A count adjusted one at a time.
- [Rating](https://loamui.com/docs/components/rating.md): Stars as real inputs, or as a picture of a score.
- [FileInput](https://loamui.com/docs/components/file-input.md): Choose a file, or drop it.
- [CopyButton](https://loamui.com/docs/components/copy-button.md): Copy a value and say so.

## Components: Data display

- [Badge](https://loamui.com/docs/components/badge.md): Compact status or label pill.
- [Price](https://loamui.com/docs/components/price.md): A monetary amount, written for people.
- [Time](https://loamui.com/docs/components/time.md): A date or time, written for people.
- [Card](https://loamui.com/docs/components/card.md): A flexible surface container.
- [Avatar](https://loamui.com/docs/components/avatar.md): Represent a user with an image or initials.
- [Table](https://loamui.com/docs/components/table.md): Display rows and columns of data.
- [Separator](https://loamui.com/docs/components/separator.md): A rule between groups of content.
- [Carousel](https://loamui.com/docs/components/carousel.md): A scroll-snap track of items, paged and announced.
- [Stepper](https://loamui.com/docs/components/stepper.md): Where a sequence has got to, detected from the current step.

## Components: Feedback

- [Alert](https://loamui.com/docs/components/alert.md): Draw attention to an important message.
- [Progress](https://loamui.com/docs/components/progress.md): Show completion of a task.
- [Meter](https://loamui.com/docs/components/meter.md): A measurement within a known range.
- [Skeleton](https://loamui.com/docs/components/skeleton.md): Placeholder while content loads.
- [Loader](https://loamui.com/docs/components/loader.md): Indicate an ongoing process.
- [Toast](https://loamui.com/docs/components/toast.md): Transient notifications.

## Components: Disclosures

- [Details](https://loamui.com/docs/components/details.md): Native disclosure for secondary content.
- [Tooltip](https://loamui.com/docs/components/tooltip.md): Reveal info on hover or focus.
- [Modal](https://loamui.com/docs/components/modal.md): A focused dialog over the page.
- [Drawer](https://loamui.com/docs/components/drawer.md): An edge-anchored panel that slides in.
- [Popover](https://loamui.com/docs/components/popover.md): Floating content anchored to a trigger.
- [Menu](https://loamui.com/docs/components/menu.md): A list of actions opened from a trigger.

## Components: Navigation

- [Tabs](https://loamui.com/docs/components/tabs.md): Switch between related views.
- [SignpostLink](https://loamui.com/docs/components/signpost-link.md): Signpost the way into a task.
- [SkipLink](https://loamui.com/docs/components/skip-link.md): Jump straight to the main content.
- [Breadcrumbs](https://loamui.com/docs/components/breadcrumbs.md): Show the current page's location.
- [Pagination](https://loamui.com/docs/components/pagination.md): Navigate between pages of content.
- [Nav](https://loamui.com/docs/components/nav.md): Lists of links with the current one marked.

## Components: Utilities

- [VisuallyHidden](https://loamui.com/docs/components/visually-hidden.md): Name a control for assistive technology alone.

## Recipes

> Recipes grouped by purpose, built from `@loamui/core` to copy and change: each twin
> carries the component and its stylesheet in full.

### Recipes: Heroes

- [Hero with image](https://loamui.com/recipes/heroes/hero-with-image.md): A page-opening section: an eyebrow, a headline, a lede and two actions beside a photograph.
- [Hero with background image](https://loamui.com/recipes/heroes/hero-background-image.md): A page-opening section over a full-bleed photograph: a headline, a lede and two actions on a scrim that holds their contrast in both schemes.

### Recipes: Banners

- [Banner with image](https://loamui.com/recipes/banners/banner-with-image.md): A fruit-plant offer with a photograph beside the deadline, heading and one clear destination.
- [Banner with background image](https://loamui.com/recipes/banners/banner-background-image.md): The same fruit-plant offer as Banner with image, with its deadline, heading, description and link over a full-width raspberry photograph.

### Recipes: Cards

- [Article card](https://loamui.com/recipes/cards/article-card.md): One article in a Card: a picture, a category and date, a linked title, its opening lines and the author at the foot.
- [Profile card](https://loamui.com/recipes/cards/profile-card.md): One member on a card: initials, a name and role, three labelled figures, and a link to their profile.
- [Gallery card](https://loamui.com/recipes/cards/gallery-card.md): A stay in a Card: a Carousel of three photos with its controls beneath, the name and a Rating with the review count, a description and the Price per night.

### Recipes: Media

- [Article carousel](https://loamui.com/recipes/media/article-carousel.md): Five journal articles as Cards on a Carousel track: a photo, a category Badge, a title and a Read article link each, with Previous and Next beside the title and a dot per article beneath.
- [Image comparison](https://loamui.com/recipes/media/image-comparison.md): Black-and-white and colour treatments of the same photograph in one frame, the second revealed by a Range the reader drags or moves with the arrow keys.

### Recipes: Grids

- [Asymmetric grid](https://loamui.com/recipes/grids/grid-asymmetric.md): A 2:1 grid: a tall lead card with a photograph in the wide column and two cards stacked beside it, all in one column when narrow.
- [Subgrid rows](https://loamui.com/recipes/grids/grid-subgrid.md): Three cards whose heading, description and action rows line up across the grid, whatever the length of the words, through grid-template-rows: subgrid.

### Recipes: Content

- [FAQ](https://loamui.com/recipes/content/faq.md): Four questions with visible answers on a subtle surface, beneath a heading and a direct contact link.
- [Timeline](https://loamui.com/recipes/content/timeline.md): Five dated events in order, each with a marker, a date, a title and a line, joined by a hairline.

### Recipes: Forms

- [Sign in with errors](https://loamui.com/recipes/forms/sign-in-with-errors.md): A sign-in form that helps people correct missing or mistyped details, with a focused error summary and matching field messages.
- [Contact us with details](https://loamui.com/recipes/forms/contact-us-with-details.md): A short enquiry form alongside the nursery's email, phone number, address and opening hours.