Getting Started

Anvil2 AI Kit provides guidance, patterns, and components for building agentic product experiences. Carto is the visual theme AI Kit uses to give agentic surfaces a consistent identity across web and mobile. Use this guide to understand when to use AI Kit, how it relates to the rest of Anvil2, and how to get started.

What is “agentic”?

An agentic experience uses AI to act on your behalf, not just to advise you. Four things define it:

Context: the system understands what’s relevant.
Reasoning: it makes thoughtful, adaptive decisions.
Conversation: it explains what it’s doing.
Action: it takes meaningful steps for you, not just suggestions you have to act on yourself.

Compare that to non-agentic AI, which stays advisory: it surfaces insights and recommendations, but a person still has to do the work.

Overview

AI Kit is part of Anvil2. It extends the Anvil2 ecosystem with design guidance and building blocks for agentic experiences, including chat, generative UI, panels, action surfaces, and agent-mediated flows. Carto provides the visual layer for AI Kit through its typography, iconography, semantic tokens, component tokens, and component styling. Core Anvil2 continues to support standard product surfaces, while AI Kit applies Carto to agentic surfaces within AgentOS.

When do I use AI Kit?

Use AI Kit when building an agentic surface within AgentOS. Do not apply the Carto theme to an entire screen solely because it contains an AI-powered feature. When an agentic element appears within a core Anvil2 surface, use the defined integration patterns for that element instead of applying AI Kit components or the Carto theme to the surrounding product UI.

How does AI Kit relate to Anvil2?

AI Kit belongs to the Anvil2 design system and specializes it for agentic product experiences. Use core Anvil2 components and guidance for standard product UI. Use AI Kit when a surface requires agentic interaction patterns, AI-specific components, or the Carto visual treatment. The Carto theme gives agentic surfaces a distinct visual identity while keeping their implementation within the Anvil2 ecosystem.

Beyond the Carto theme, AI Kit uses agent-friendly APIs to improve consistency. Its components favor prop-driven interfaces over compositions of subcomponents, limit reliance on open-ended children props, and use a tighter token system to keep web and mobile libraries aligned automatically. Over time, these API improvements will be incorporated into the core Anvil2 library.

How is this different from Atlas v1?

Atlas v1 was the previous iteration of ServiceTitan’s agentic chat experience. It was built with ext-atlas, Anvil2’s extended Atlas component library, and focused on chat-based interactions. Atlas today uses AI Kit and the Carto theme to support agentic experiences beyond chat. ext-atlas supports existing Atlas v1 integrations and is deprecated for new Atlas experiences.

How do I start?

Design assets

Get familiar with what’s covered above: when to use AI Kit, how it relates to Anvil2, and how Carto styles agentic surfaces.
Explore the component libraries in Figma:
Explore the AI Kit component Storybook.
Have questions on agentic patterns? Ask in #support-agentic-design. Have questions about components or implementation? Ask in #ask-designsystem. Since the system and its conventions are still forming, a quick check-in helps you avoid rework as things solidify.

Engineering assets

Use @servicetitan/carto-react-kit to implement AI Kit experiences on the web. It provides chat shells, prompts, artifacts, supporting primitives, and the Carto theme through a consistent React API. Peer requirements: react@>=18 <20, react-dom@>=18 <20.

Storybook

AI Kit component Storybook

Explore API documentation and interactive component examples.

AI Kit API documentation will move to this site soon.

Install

pnpm add @servicetitan/carto-react-kit

Or with npm:

npm install --save @servicetitan/carto-react-kit

Styles

Import the CSS bundle once at your application entry point so vanilla-extract styles load:

import "@servicetitan/carto-react-kit/styles.css";

Theme

Wrap your AI Kit tree in CartoTheme so Carto design tokens inherit to every descendant, including components rendered inside MFE shadow roots:

import { CartoTheme } from "@servicetitan/carto-react-kit";

export function Root({ children }) {
  return <CartoTheme appearance="auto">{children}</CartoTheme>;
}

Overlays from React Aria (Tooltip, Popover, Menu, Modal, Toast) portal into a sibling inside the theme wrapper rather than document.body, so token context stays intact.

Fonts

AgentOS pairs Sofia Pro for headers with Inter for body copy. This differs from the existing setup in Web, which pairs Sofia Pro with Nunito Sans. Prefetch Inter in your document <head> for the fastest first paint. The kit also injects this link at module load as a safety net.

<link rel="preconnect" href="https://fonts.googleapis.com" crossorigin />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  rel="stylesheet"
  href="https://fonts.googleapis.com/css?family=Inter:400,400i,500,500i,700,700i&display=optional"
/>

Sofia Pro requires no additional setup: the kit reuses the same Sofia Pro already loaded by your host application, the same font Web relies on for headers.

Quick start

import { Button, CartoTheme, Text } from "@servicetitan/carto-react-kit";
import { IconPencil } from "@servicetitan/carto-react-kit/icons";
import "@servicetitan/carto-react-kit/styles.css";

export function App() {
  return (
    <CartoTheme>
      <Text variant="headline" size="regular" text="AI Kit" />
      <Button label="Edit" icon={<IconPencil />} onPress={() => {}} />
    </CartoTheme>
  );
}

Icons

AI Kit uses Lucide icons (lucide-react) along with a small number of custom Carto SVGs. Import icons from the kit subpath, not directly from lucide-react:

import { IconPencil, IconPlus } from "@servicetitan/carto-react-kit/icons";

The icon allowlist is owned by VizD and curated inside the kit. Consumers cannot extend it from outside.

Internationalization

CartoIntlProvider is optional. Without it, components render English. Mount it inside CartoTheme to switch locale or override strings without colliding with your app’s react-intl context:

import { CartoTheme, CartoIntlProvider } from "@servicetitan/carto-react-kit";

export function Root({ children }) {
  return (
    <CartoTheme appearance="auto">
      <CartoIntlProvider locale="fr-FR">{children}</CartoIntlProvider>
    </CartoTheme>
  );
}

Resources

AI Kit overview

Learn what AI Kit covers and how its documentation is organized.

Terminology

Explore core terms used across AI experiences and ServiceTitan.

Visual Foundations

Explore the visual foundations of AI Kit and the Carto theme.

Components

Browse reusable AI Kit building blocks.

AI UX

Read guidance for agentic product experiences.

​What is “agentic”?

​Overview

​When do I use AI Kit?

​How does AI Kit relate to Anvil2?

​How is this different from Atlas v1?

​How do I start?

​Design assets

​Engineering assets

​Storybook

AI Kit component Storybook

​Install

​Styles

​Theme

​Fonts

​Quick start

​Icons

​Internationalization

​Resources

AI Kit overview

Terminology

Visual Foundations

Components

AI UX

What is “agentic”?

Overview

When do I use AI Kit?

How does AI Kit relate to Anvil2?

How is this different from Atlas v1?

How do I start?

Design assets

Engineering assets

Storybook

Install

Styles

Theme

Fonts

Quick start

Icons

Internationalization

Resources