# Lathe — guide for coding agents

This project uses Lathe (https://latheui.dev), a React component library installed as source with
the shadcn CLI. Stack: React 19, Tailwind CSS v4, TypeScript, Motion, Radix.

## Finding components

- Index of every component with one-line descriptions: https://latheui.dev/llms.txt
- Props, states, keyboard and accessibility for every component in one file: https://latheui.dev/llms-full.txt
- One component as Markdown, before you use it: https://latheui.dev/md/<name>
- Registry manifest (free items): https://latheui.dev/r/registry.json

## Installing

- Every item: `npx shadcn@latest add @latheui/<name>`. The project needs the registry once: `npx latheui init`, or `npx latheui init --key <key>` with Lathe Pro (see https://latheui.dev/docs/pro).
- Free items also install with no setup from their full address: `npx shadcn@latest add https://latheui.dev/r/<name>.json`
- Components land in `components/ui/`, assemblies in `components/`, shared files in `lib/` and `hooks/`.
- Before writing a new component, check whether Lathe already has one. Install it instead of hand-rolling.

## Prefer assemblies over raw parts

When a page matches an assembly, start from the assembly and replace its sample data, rather
than composing cards and inputs by hand:

- Activity Replay (`activity-replay`, Pro): Inspect recorded application snapshots, play through ordered events, pin a comparison baseline, and jump to any checkpoint.
- Command Preview (`command-preview`, Pro): Find an action, edit its parameters, inspect proposed changes, then execute with cancellation, retry and optional undo.
- Conflict Resolver (`conflict-resolver`, Pro): Resolve field-level differences between local and incoming changes, inspect the merged result, and save with retry.
- Dashboard (`dashboard`, Pro): A workspace that fits your product. Three navigation layouts, a responsive grid, and composable cards with gentle motion. Try every arrangement in the expanded playground.
- Delivery Details (`delivery-details`, Pro): A compact checkout step for contact, address and delivery method, with saving, confirmation and retry states.
- FAQ Section (`faq-section`): Questions and answers beside a heading, with a search that filters as you type and a closing line for anything else.
- Import Workbench (`import-workbench`, Pro): Bring in CSV data, map columns, preview transformations, correct invalid cells and import only after validation passes.
- Metrics Dashboard (`metrics-dashboard`, Pro): A dense analytics view: four headline numbers that double as tabs, one chart you can inspect and compare against the previous period, and ranked lists of top pages and sources.
- Notification Inbox (`notification-inbox`, Pro): Grouped updates with unread filtering, individual and batch read actions, undo and a preferences slot.
- Order Summary (`order-summary`, Pro): The step before payment: a promo code chip, discount and tax lines, a rolling total and a stateful pay button.
- Pricing Table (`pricing-table`, Pro): Three plans side by side with a monthly and yearly switch. Prices roll to their new values when the billing period changes.
- Review Contact Sheet (`review-contact-sheet`, Pro): Select assets, compare aligned images, annotate a single image, approve or reject selections, and export a review with comments.
- Scenario Workbench (`scenario-workbench`, Pro): Adjust model assumptions, pin a baseline, and compare calculated metrics and projection data in a chart and table.
- Sign In (`sign-in`): A sign-in panel that also creates accounts, with provider buttons, validation and progress states. The preview sends nothing anywhere.
- Stat Tiles (`stat-tiles`, Pro): A row of headline numbers, each with its trend line and change, that roll to new values when the range changes.
- Testimonial Wall (`testimonial-wall`, Pro): A heading over rows of quotes that drift past in opposite directions and slow down under the pointer.
- Upload Manager (`upload-manager`, Pro): A file queue with raster previews, per-file progress, cancellation, retry and application-owned upload transport.

## Conventions

- `className` styles the root element and is merged last. Do not wrap components just to add spacing.
- Stateful components work controlled or uncontrolled: `value` / `defaultValue` / `onValueChange`, or `open` / `defaultOpen` / `onOpenChange`.
- Variants and sizes are string unions named `variant` and `size`. Use one primary button per view.
- Every part has a `data-slot` attribute for styling from a parent.
- Colors come from the shadcn CSS variables (`bg-background`, `text-muted-foreground`, `border-border`, `ring`). Do not hard-code colors.
- Motion uses the shared springs in `lib/motion.ts` and already respects reduced motion. Do not add new animation libraries.
- Keep loading, empty and error states. Every component documents them; wire them to real data instead of removing them.
- Assemblies that ship sample data accept it as props (for example `items` or `plans`). Pass the project's data instead of editing the samples.