@cline/ui

Shared visual foundations and reusable React presentation primitives for Cline web products. The package lets teams adopt the same semantic theme and agent chat language without adopting another product's routes, state, or runtime.

The package is configured for public npm releases on its own version and release cycle. Its API is still pre-stable, so consumers should pin an exact version and review compatibility notes when updating. Check availability with npm view @cline/ui version; an E404 means the first release is still pending.

See the adoption primer for complete setup instructions, component examples, boundaries, and release status.

Install

After the initial release is available:

bun add --exact @cline/ui

Use @cline/ui@next only for deliberate previews. Monorepo consumers use "@cline/ui": "workspace:*" instead.

Entry points

SessionStatus uses semantic tone colors by default. Set --cline-ui-session-status-color on the component to override its dot color for a host-specific status palette.

SearchCombobox provides a searchable selector for repository and model lists. Its in-place panel requires ancestors that do not clip overflow.

AgentQuickActions renders prompt shortcuts and reports selection to the host.

AgentAurora fills its nearest positioned ancestor, which must have resolved dimensions.

AgentHeroHeading renders the shared cycling “What would you like to …?” welcome heading and respects reduced-motion preferences.

AgentApprovalCard is controlled presentation; the host owns approval state and submits its callbacks.

The token entry point has no React, Tailwind, font-package, or desktop runtime dependency. Apps provide Schibsted Grotesk and Azeret Mono themselves, which lets each bundler control font loading and asset emission.

tokens.css is the canonical token source; scoped-tokens.css is generated from it. Contributors change tokens.css and run bun run generate:theme; tests and CI reject drift in the scoped output. Consumers may import either public entry point.

Theme usage

For a Tailwind v4 app, import framework and consumer dependencies first:

@import "@fontsource-variable/schibsted-grotesk";
@import "@fontsource/azeret-mono/latin.css";
@import "tailwindcss";
@import "@cline/ui/theme/index.css";

An app that only needs framework-neutral values can import:

@import "@cline/ui/theme/tokens.css";

For an embedded surface, import scoped tokens and optional Markdown styles:

@import "@cline/ui/theme/scoped-tokens.css";
@import "@cline/ui/components/markdown.css";

<section className="cline-ui-theme">
	<div className="cline-markdown">...</div>
</section>

Dark values activate when .dark is on the wrapper or an ancestor.

The theme follows the standard shadcn semantic contract (--background, --foreground, --card, --primary, --border, --ring, charts, and sidebar surfaces) and Tailwind theme names. This means shadcn components and normal Tailwind utilities inherit Cline defaults without custom adapters.

Brand artwork may use the small extension set (--primary-emphasis and the --brand-* palette). Product controls should prefer semantic variables.

Agent-chat usage

Agent-chat consumers must provide React 18.3 or 19. Install React in the consuming application if it is not already present:

bun add react@^19 react-dom@^19

Applications already on React 18.3 can retain that compatible version.

In the application's global CSS, import the component styles after at least the theme tokens:

@import "@cline/ui/theme/tokens.css";
@import "@cline/ui/components/agent-chat.css";

Then import the React components:

import {
	Conversation,
	ConversationContent,
	ConversationEmptyState,
	ConversationScrollButton,
	ConversationViewport,
	Message,
	MessageAction,
	MessageActions,
	MessageContent,
	Reasoning,
	ReasoningContent,
	ReasoningTrigger,
	ToolActivity,
	ToolActivityCode,
	ToolActivityContent,
	ToolActivityDetails,
	ToolActivityTrigger,
} from "@cline/ui/components/agent-chat";

Conversation owns sticky scrolling, Message owns role presentation, Reasoning and ToolActivity provide accessible disclosures, and the smaller action, empty-state, detail, and code primitives fill out common transcript states. Give each conversation a bounded height through an explicit height or a complete flex/min-height chain so its viewport can scroll.

These are presentation primitives, not an agent SDK. Consumers map their own message and tool schemas into the components and retain their own Markdown, transport, approvals, persistence, and product actions.

Storybook

Run the interactive component catalog from the repository root:

bun -F @cline/ui storybook

Then open http://localhost:6006. Build the static catalog with:

bun -F @cline/ui build-storybook

In the repository's agent sandbox, bind to a forwarded host and unused port:

bun -F @cline/ui storybook -- --host 0.0.0.0 --port 3490 --exact-port

The catalog includes the theme foundations and representative agent-chat states in light, dark, desktop, and narrow viewports.

Storybook currently runs from a Cline monorepo checkout. It is not hosted or included in the npm package; deployment can be added once the catalog and ownership model settle.

Layering and compatibility

• Import the Cline theme after Tailwind so its default typography values win.
• Import components/markdown.css after either token entry point.
• Import agent-chat.css after theme tokens.
• Override :root or .dark after package imports for deliberate product variations; do not rename the default semantic contract.
• base.css is optional because it contains opinionated Markdown and global interaction styles.
• Shell layout, routes, provider/session state, and runtime behavior stay with each consumer.
• Contract changes should include a compatibility note, package tests, a Storybook build, and at least one real consumer build.

Releases

The standalone ui-publish.yml workflow validates the package and publishes only after a manual dispatch from main. Production releases use the npm latest tag; deliberate previews use next. UI releases do not trigger the SDK release, GitHub releases, or Slack announcements.

Maintainers use the repository's publish-ui skill for the initial bootstrap and later releases.

The install command above pins the resolved release. Commit the consumer lockfile and update deliberately. The package is ESM and its React components target browser applications. A complete Tailwind theme also requires Tailwind v4 and the two font packages shown above.