Installation
The recommended way to integrate @downcity/ui into a host application
This page covers one job: how to integrate @downcity/ui correctly into a React + Tailwind host app.
Install The Package
npm install @downcity/uiReact Version Requirements
@downcity/ui supports React 18.2 and React 19. Keep react and react-dom on the same major version in the host application.
# React 18
npm install react@^18.2.0 react-dom@^18.2.0
# React 19
npm install react@^19.0.0 react-dom@^19.0.0Import The Styles
@import "tailwindcss";
@import "@downcity/ui/source.css";
@import "@downcity/ui/styles.css";Recommended order:
tailwindcss@downcity/ui/source.css@downcity/ui/styles.css- your host app global CSS
Why Both Entry Points Exist
@downcity/ui/source.css
- Only declares the Tailwind scanning source
- Makes sure the host app includes utilities used inside UI SDK components
- Does not inject tokens or base styles
@downcity/ui/styles.css
- Owns theme variables and the base layer
- Defines semantic tokens such as
background,foreground,popover,border, andring - Makes semantic utility classes work in the host app
Chat styles with a host-owned theme
styles.css includes the shared chat styles. When your application already owns its theme and base styles, load the chat stylesheet independently:
@import "tailwindcss";
@import "@downcity/ui/source.css";
@import "@downcity/ui/chat.css";
/* Load your host theme and component styles here. */
@import "@downcity/ui/markdown.css";chat.css provides input sizing, code blocks, reference capsules, and input-menu surfaces. It does not set global theme tokens or reset the host page. Keep source.css so Tailwind generates utilities used by SDK components. ChatInput uses explicit 24px compact buttons, and its editor consumes the shared writing font and line height with fallbacks.
Markdown Stylesheet
When using MarkdownView, add this import after the base styles:
@import "@downcity/ui/markdown.css";This entry owns Markdown typography and diagram styles. The host supplies semantic theme tokens and outer layout; the component owns fonts, font sizes, line heights, and content spacing, which callers must not override.
Minimal Working Example
import { Button, Card, CardContent, CardHeader, CardTitle, Input, Label } from "@downcity/ui";
export function AgentSettingsCard() {
return (
<Card className="max-w-xl">
<CardHeader>
<CardTitle>Agent Settings</CardTitle>
</CardHeader>
<CardContent className="flex flex-col gap-4">
<div className="flex flex-col gap-2">
<Label htmlFor="agent-name">Agent Name</Label>
<Input id="agent-name" placeholder="research-writer" />
</div>
<div className="flex justify-end">
<Button size="sm">Save</Button>
</div>
</CardContent>
</Card>
);
}Integration Rules
- Use
classNamemainly for layout, width, spacing, and local page adjustments; MarkdownView usesclass_namefor outer layout only - Prefer built-in
variant,size, and composition patterns instead of rebuilding a second visual system - For overlays, follow the primitive composition directly, such as
Dialog + DialogContent + DialogHeader