UI SDK Development

This page is for developers using @downcity/ui to build real screens.

Integration Rules

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

If you import styles.css without source.css, the host app may miss the Tailwind utilities used inside UI SDK components.

Component Selection Guide

Actions

• Button
• Toggle
• ToggleGroup
• Badge

Forms

• Input
• Textarea
• Checkbox
• Label

Containers

• Card
• Tabs
• Separator
• Skeleton

Overlays

• Dialog
• Sheet
• DropdownMenu
• Popover
• Tooltip
• Toaster

Common Screen Patterns

Settings Panel

import { Button, Card, CardContent, CardHeader, CardTitle, Input, Label, Separator } from "@downcity/ui";

export function ModelSettingsPanel() {
  return (
    <Card className="max-w-2xl">
      <CardHeader>
        <CardTitle>Model Settings</CardTitle>
      </CardHeader>
      <CardContent className="flex flex-col gap-4">
        <div className="flex flex-col gap-2">
          <Label htmlFor="provider">Provider</Label>
          <Input id="provider" placeholder="openai" />
        </div>
        <Separator />
        <div className="flex justify-end">
          <Button size="sm">Save</Button>
        </div>
      </CardContent>
    </Card>
  );
}

Toolbar

• Button
• Toggle
• Tooltip
• DropdownMenu

Modal Editing

• Dialog
• DialogHeader
• DialogTitle
• DialogDescription
• DialogFooter

If the content is larger, prefer Sheet instead of forcing everything into Dialog.

Host App Conventions

If a screen needs to talk to the downcity main package, do not import internal main-package source files from a component. See Host Integration.

className should mostly handle

• width
• layout
• spacing
• local page-level adjustments

Avoid

• rebuilding a second color system at the page layer
• redefining buttons per business screen
• overriding primitive semantics with business-specific wrappers

Recommended Reading

• UI SDK
• Components
• UI SDK Modules
• Host Integration