For AI Agents

This page is the canonical entry point for AI assistants (Claude Code, Cursor, Copilot, custom agents) that need to write code against @ngrok/mantle.

TL;DR for the agent

1Use the @ngrok/mantle design system. Components live at @ngrok/mantle/<name>2(e.g. @ngrok/mantle/button). Import subpaths are flat even though docs URLs3group components by category (/components/<category>/<name>). All pages have4a plain-markdown twin at <page>.md. The full library index is at /llms.txt5and a structured component manifest is at /api/components.json. Hooks and6utilities have their own manifests at /api/hooks.json and /api/utils.json.7Offline, node_modules/@ngrok/mantle/dist/agent.json carries the same records8for the installed version, and dist/llms.txt is its one-line index.

Machine-readable entry points

Suggested system-prompt snippet

Drop this near the top of an agent's system prompt when working in a mantle codebase:

1This project uses @ngrok/mantle, ngrok's React + TypeScript + Tailwind2design system. Conventions:34- Components are imported from @ngrok/mantle/<name>, e.g.5  `import { Button } from "@ngrok/mantle/button"`.6- Hooks are imported from @ngrok/mantle/hooks, e.g.7  `import { useBreakpoint } from "@ngrok/mantle/hooks"`.8- Utilities live at their own subpaths, e.g. @ngrok/mantle/cx,9  @ngrok/mantle/color.10- Use `== null` / `!= null` for nullish checks (covers both `null` and11  `undefined`) — never `=== undefined` / `!== undefined`.12- Compose class names with `cx` from @ngrok/mantle/cx — never use string13  interpolation inside className.14- Many components support `asChild` to swap the rendered element while15  keeping the styling and behavior. Prefer this over wrapping.16- Never render a conditional element immediately before bare text17  children — a browser translation engine makes React throw there and18  the page goes blank. Wrap the text in a <span>, or pass an icon19  through the `icon` prop instead of as a child. Mark code, keys,20  filenames, IDs, and passcodes translate="no", and nothing else: the21  attribute classifies content and is never the fix for a crash.22- The app must wrap children in <ThemeProvider> and <Toaster> at the root23  (see /). Add <TooltipProvider> once at the root when using shared tooltip24  delay or hover settings.25- The app's CSS entry must `@import "@ngrok/mantle/mantle.css"` and then26  `@import "@ngrok/mantle/source-all.css"`. Keep both in one CSS file.27  Without the second import Tailwind generates none of the classes28  mantle's components use. The components render unstyled.29- To trim the production stylesheet, add `mantleSourcesPlugin()` from30  @ngrok/mantle-vite-plugins next to `tailwindcss()` in vite.config.ts31  (see /vite-plugins). The CSS file does not change. Dev scans every32  mantle file; the build lists only the files the client bundle contains.33- Color scales use Tailwind's 50-950 steps (`text-accent-600`). There is34  no 1-12 scale, so `text-accent-11` matches nothing. Text color tokens35  are `text-strong`, `text-body`, `text-muted`, and `text-placeholder`.36- All external dependencies must be exact-pinned (no `^` or `~`).37- Without network access, read node_modules/@ngrok/mantle/dist/agent.json:38  every component with its import path, examples, aliases, and sibling39  boundaries (useWhen, siblings), plus the hooks and utilities, for the40  installed version.41- Reference the canonical docs at https://mantle.ngrok.com or fetch42  https://mantle.ngrok.com/llms.txt for the full index. When building an43  app shell, read the demo sources under `# Framed preview sources` in44  https://mantle.ngrok.com/llms-full.txt — the fences on the docs pages45  are shorter excerpts of them.

Conventions agents should know

• Polymorphism via asChild. Most components accept asChild (powered by Slot). Use it to render the component as a different element (for example, render a Button as a react-router Link) without losing the component's styling or behavior.
• Flat import paths, categorized docs URLs. Components import from @ngrok/mantle/<name> (e.g. @ngrok/mantle/button). The docs URL's category segment (/components/actions/button) never appears in import paths. Hooks live at @ngrok/mantle/hooks (e.g. import { useBreakpoint } from "@ngrok/mantle/hooks"). Utilities live at their own subpaths: @ngrok/mantle/cx, @ngrok/mantle/color, etc.
• Docs slug ≠ import subpath (sometimes). Most components import from a subpath that matches their docs slug (e.g., Button from @ngrok/mantle/button). A few are exported from a parent's subpath: IconButton from @ngrok/mantle/button, PasswordInput from @ngrok/mantle/input, ProgressBar and ProgressDonut from @ngrok/mantle/progress. The structured manifest at /api/components.json is the source of truth; its importPath field is always correct.
• cx over string interpolation. Compose class names with cx. It merges Tailwind classes and de-duplicates conflicts.
• Nullish checks use == null / != null. The codebase prefers these over === undefined / !== undefined, since == null covers both null and undefined.
• Theme + provider setup. Apps must mount ThemeProvider and Toaster at the root. Add TooltipProvider once when using shared tooltip delay or hover settings. Without ThemeProvider, theme tokens are unstyled and there's a flash of unstyled content.
• Stylesheet setup. The app's CSS entry imports @ngrok/mantle/mantle.css and then @ngrok/mantle/source-all.css (see Stylesheet). mantle.css declares no @source, and Tailwind 4 skips node_modules when it scans for class names, so without source-all.css Tailwind generates none of the classes mantle's components use. The components render without their styles. An open Dialog shows its content in the page flow with no backdrop. Import both from the same CSS file: Tailwind compiles each CSS entry on its own, so an @source in a separate file adds nothing. To trim the production stylesheet, add mantleSourcesPlugin() from @ngrok/mantle-vite-plugins next to tailwindcss() in vite.config.ts. The CSS file does not change.
• Phosphor icons by default. Import icons from @phosphor-icons/react/<IconName> (e.g. @phosphor-icons/react/Fire). Custom ngrok icons live at @ngrok/mantle/icons.
• No as casts in app code. Use proper null checks and type narrowing. Type assertions are restricted to as const and dedicated type guards (see Conventions).
• Translation-safe markup. Google Translate reparents every text node, so React throws NotFoundError and the page goes blank when it inserts an element before one. Never render a conditional element immediately before bare text children: wrap the text in a <span>, move the element after it, or mount it unconditionally. Pass a Button or Badge icon through the icon prop, never as a child. Mark code, keys, filenames, IDs, and passcodes translate="no"; Code, Kbd, CodeBlock.Code, and OtpInput.Slot already do. The attribute classifies content and is never the fix for a crash: when a shape throws, fix the structure, and keep prose translatable.
• Exact-pinned versions. When adding a dependency, pin it. No ^ or ~ ranges.
• Tailwind 4. Custom classes use the design tokens defined in mantle.css. Prefer semantic tokens (text-strong, bg-form, border-accent-600) over raw color names where they exist. Color scales use Tailwind's 50–950 steps (text-accent-600, bg-neutral-100); there is no 1–12 scale, so text-accent-11 matches nothing. The text color tokens are on Typography and the palettes on Colors.

Composition patterns

A few high-leverage compositions agents commonly need:

1// Button + react-router Link (polymorphic)2import { Button } from "@ngrok/mantle/button";3import { Link } from "react-router";4 5<Button appearance="outlined" intent="neutral" asChild>⋯6	<Link to="/dashboard">Dashboard</Link>7</Button>;

1// Dialog + form2import { Dialog } from "@ngrok/mantle/dialog";3import { Button } from "@ngrok/mantle/button";4 5<Dialog.Root>⋯6	<Dialog.Trigger asChild>⋯7		<Button appearance="outlined" intent="neutral">⋯8			Edit9		</Button>10	</Dialog.Trigger>11	<Dialog.Content>⋯12		<Dialog.Header>⋯13			<Dialog.Title>Edit profile</Dialog.Title>14		</Dialog.Header>15		{/* form here */}16	</Dialog.Content>17</Dialog.Root>;

1// Toast on async action2import { makeToast, Toast } from "@ngrok/mantle/toast";3 4async function save() {⋯5	try {⋯6		await api.save();7		makeToast(<Toast.Root intent="success">Saved</Toast.Root>);8	} catch (error) {⋯9		makeToast(10			<Toast.Root intent="danger">⋯11				<Toast.Message>Could not save: {String(error)}</Toast.Message>12			</Toast.Root>,13		);14	}15}

Accessibility-first defaults

Every mantle component is built on semantic HTML and tested ARIA patterns. Agents should:

• Render real form controls (Input, Checkbox, RadioGroup); never style a <div> with click handlers as a button.
• Pair every form control with a Label.
• Use SkipToMainLink + Main at the top of the document tree.
• Set accessible names for icon-only buttons via the required label prop on IconButton.
• See the Accessibility page for a full keyboard / ARIA reference per component.

When to ask vs. when to act

• If the user asks for "a primary button," generate a Button with appearance="filled" intent="neutral", the system's default primary action. Button and IconButton require explicit appearance and intent; there are no defaults. The two take different tone unions:
  • Button takes "accent", "danger", or "neutral". Use intent="neutral" when no tone is implied. Reserve intent="accent" for deliberate brand emphasis: an action that should carry the accent color.
  • IconButton takes "neutral" alone. Reach for Button where the tone carries meaning.
• If choosing between Tooltip, Popover, and HoverCard, follow the JSDoc guidance: Tooltip for short label hints, Popover for interactive content, HoverCard for non-essential preview cards.
• If choosing between DataTable and Table: DataTable for dynamic, sortable, filterable, paginated tabular data; Table for static layout.
• When uncertain, prefer to fetch the relevant /<page>.md and read the full doc rather than guessing.

Versioning

@ngrok/mantle is 0.x, so stock semver does not apply. There is no major: a breaking change ships as a minor, and an additive or internal change ships as a patch. Read the Changelog before a minor bump, and run the matching migration guide when one exists. When working in a project, check package.json for the pinned version and prefer the docs at the matching tag on GitHub if you need to pin behavior to that version.