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/ui

React 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.0

Import The Styles

@import "tailwindcss";
@import "@downcity/ui/source.css";
@import "@downcity/ui/styles.css";

Recommended order:

  1. tailwindcss
  2. @downcity/ui/source.css
  3. @downcity/ui/styles.css
  4. 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, and ring
  • 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 className mainly for layout, width, spacing, and local page adjustments; MarkdownView uses class_name for 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

Next Reading