Cheetah / Cheetah documentation

Component layers and styling

The @cheetah/ui source is organized by how much of the reader's task a component owns. Moving up the stack saves application code but also adopts more Cheetah-specific data loading, refresh, and navigation behavior. Moving down gives the product more control but requires it to assemble the experience.

Read the package as three component layers

The root export also supplies DiagnosticsClient, diagnostic response types, theme support, URL helpers, and three hooks. useDiagnosticsApi() keeps one client instance for an API base. useAutoRefresh() avoids overlapping refreshes, pauses while the document is hidden, and refreshes when the page becomes visible again. useTagDiscovery() counts tags and assigns deterministic colors from the current theme.

Exact component props belong to the emitted TypeScript declarations. A handwritten catalogue would drift quickly and would hide the more important choice: whether the host wants one rendered record, one investigation workflow, or a complete dashboard.

The package is source-consumed

The package metadata contains "private": true. Cheetah's maintained dashboards resolve @cheetah/ui directly to cheetahUI/packages/components/src through their Vite configuration. Their Tailwind configuration scans that source directory so utility classes used by the components are present in the generated dashboard CSS.

The component project can build ESM JavaScript and TypeScript declarations into dist, but that does not make it a supported external package. The repository does not establish public registry publication, a standalone stylesheet, or a public Tailwind preset. Do not infer an npm install workflow from the package name.

Within a maintained dashboard or another deliberately owned source integration, imports use the single root boundary:

import {
  ThemeProvider,
  HistoryStream,
  MessageCard,
  type HistoryMessage,
} from '@cheetah/ui';

Avoid source-subpath imports in application code. The package exposes only its root and can change its implementation directories without preserving those paths.

Theme values are not the complete stylesheet

ThemeProvider creates a wrapper and supplies the main Cheetah colors as CSS custom properties. Components combine those variables with Tailwind-style utility classes for layout, spacing, typography, borders, visibility, and responsive behavior.

Providing a theme therefore changes color values; it does not supply the missing utilities. A product that deliberately embeds the source must provide a compatible utility build or restyle the components. Rendering without that step may leave the data present but the hierarchy, spacing, responsive behavior, or interaction states wrong.

This is a packaging boundary, not a suggestion to copy the maintained dashboard's entire build configuration into every product. A future public component package would need a deliberately versioned distribution and styling contract.

Domain components receive records, not authority

A MessageCard receives one normalized HistoryMessage. A ClientInfoCard receives one ConnectionSnapshot. Rendering either object does not query the server or authorize an action. The product decides where the record came from and who may see it.

Some components expose callbacks for navigation or local state. Those callbacks do not prescribe a router. A host may open a side panel, update a URL, or select another composite. The component does not silently turn that navigation into a Cheetah command.

The one explicit write-capable component is ActionDispatcher. Keep it behind the separate control boundary described in Diagnostics client and composites.