OpenCoven UI

OpenCoven UI is the modular component library, block library, specimen app, and shadcn registry for OpenCoven agent surfaces.

The package and registry share one TypeScript source tree. The specimen app imports the same public modules consumers receive, so documentation cannot quietly drift back into copied HTML.

Foundation

Decision	Value
Component base	Base UI for new interactive primitives
shadcn style	base-nova
Scaffold seed	Zinc
Brand semantics	OpenCoven web profile 1.0.0
Action	Coven Violet #8e3dff dark / #7a22ee light
Presence	#b991ff dark / #5e2a8a light
Density	default and explicit compact variants
Language	Strict TypeScript
Styling	Tailwind CSS 4 and CSS custom properties
Icons	Lucide
Distribution	@opencoven/ui package and shadcn registry

Zinc supplies scaffold structure only. Colors, display/reading/mono font roles, and the 4/8/12/16/24/32/48/64/96px spacing scale map to the pinned canonical brand profile. Fonts use its local/system fallback stacks; no font files or third-party font requests are bundled. Components consume semantic tokens such as background, card, presence, success, and the canonical tool-read/tool-write/tool-exec/tool-net mappings.

Workspace

.
├── apps/specimens/              React/Vite component library and six-scene lab
├── packages/ui/
│   └── src/
│       ├── components/ui/       Base UI and native primitives
│       ├── components/          Coven composed components
│       ├── blocks/              Reusable operational surfaces
│       ├── lib/                 Shared utilities
│       └── styles/              Semantic tokens and themes
├── registry/                    Categorized registry source fragments
├── public/r/                    Generated shadcn artifacts
├── registry.json               Generated root registry
└── docs/migration/              Legacy audit and migration evidence

Develop

pnpm install
pnpm dev

The specimen app opens at http://127.0.0.1:5173/. Its assembled lab is at http://127.0.0.1:5173/lab.

The catalog retains the original index.html proportions: a 248px component sidebar, flexible main column, and 216px context rail within a 1680px shell. Main gutters follow the original clamp(24px, 5vw, 72px). Below 1281px the context rail disappears and the sidebar becomes 232px; at 880px and below, a native grouped picker replaces the sidebar. All 16 component and block links share the rendered catalog's inventory and search results. Hash links support direct navigation, while the selected entry follows page scrolling.

Library and Lab use one fixed compact layout, without density controls or density labels. Public component density props remain available to consumers.

The library presents one specimen per row, with bounded live surfaces, responsive block layouts, and a compact installation strip. It keeps live previews above syntax-highlighted install commands, imports, and full component source, with copy controls and explicit clipboard-failure feedback. The shared code renderer supports Bash, TypeScript/TSX, and CSS. Each specimen has Preview/Source tabs in a fixed-size preview area, so opening source does not change the card or page height. Preview or Escape returns to the same component state; source scrolls inside that area. Supported states live in a separate, always-visible footer rather than a tab. The Lab fits the viewport and offers six scenes through tabs, previous/next controls, and touch swipes. Only the active scene scrolls when space is limited or text is enlarged; the page and navigation stay fixed. Demo actions are local and do not send agent requests.

The monochrome crown/lotus mark in public/opencoven-mark.svg is vendored unchanged from OpenCoven/brand's web/assets/mark.svg, pinned to commit 798e2f5f2f1a69f5d156ccc0a9aafc4f7da55fc8.

Consume the package

pnpm add @opencoven/ui

Import the theme once, then import named modules:

import "@opencoven/ui/globals.css";
import { Composer, ToolClassBadge } from "@opencoven/ui";

Component and block subpaths are also exported:

import { ModeSwitch } from "@opencoven/ui/components/mode-switch";
import { RunRail } from "@opencoven/ui/blocks/run-rail";

Consume the registry

After the generated registry is deployed at ui.opencoven.ai, add the namespace to components.json:

{
  "registries": {
    "@opencoven": "https://ui.opencoven.ai/r/{name}.json"
  }
}

Then install source you own:

pnpm dlx shadcn@latest add @opencoven/button
pnpm dlx shadcn@latest add @opencoven/composer

pnpm check runs deploy:check, which asserts every generated registry item is published byte-identical in the deploy output and that the SPA rewrite does not capture /r/*. After a deploy, pnpm live:check fetches every item from the deployed origin and confirms a missing item returns 404 rather than the app shell:

pnpm live:check                      # defaults to registry.json homepage
pnpm live:check https://preview-url  # or a specific deployment

To test the registry before deployment:

pnpm registry:build
python3 -m http.server 4321 -d public/r
pnpm dlx shadcn@latest add http://127.0.0.1:4321/composer.json

registry.json is composed from categorized fragments. shadcn build then creates public/r, and a deterministic normalization pass converts package imports to standard consumer aliases. Do not hand-edit either generated surface.

Components and blocks

The initial migration includes:

• Base UI primitives: Button, Tabs, Tooltip, and Dropdown Menu.
• Native primitives: Input, Textarea, Badge, Progress, Separator, and Card.
• Composer components: Mode Switch, Send Control, Completion Palette, and Attachment Chip.
• Operational components: Metric Display, Status Indicator, Plan Row, Activity Item, Resource Row, Tool Mix, Failure Surface, Context Meter, Budget Pill, Search Field, Empty State, and Error State.
• Blocks: Composer, Run Rail, Transcript Turn, and Session Header.

Composer accepts an optional tools slot for supporting controls and supports Ctrl/Cmd+Enter to send a non-empty draft while idle. Run Rail accepts optional plan and resources arrays using the public Plan Row and Resource Row props; omit them to retain the metrics/activity/limits composition. Send Control only displays its options action when onOpenOptions is supplied.

No Radix implementation existed to retain. No React Aria dependency was added; the current component set does not require its collection or internationalization architecture.

Quality gates

pnpm check

This runs formatting, linting, strict type checking, unit and interaction tests, automated accessibility checks, architecture/design contract checks, official registry validation and builds, generated-artifact freshness, clean-consumer registry installation, package and specimen production builds, and package export checks.

CI runs the same command on every pull request and push to main.

The Visual review workflow also runs scripts/visual-review.mjs and scripts/mobile-quality-review.mjs against the production app. It publishes individual specimens and Lab scenes, contact sheets, and browser measurements. Coverage includes every specimen's source overlay, real keyboard/mouse and clipboard flows, touch navigation, theme persistence, forced colors, RTL, narrow screens, and 200% text.

Legacy migration

index.html and Components.dc.html remain as parity references. They are not the package or deployed specimen source. Their complete component, token, interaction, accessibility, responsive, and motion mapping lives in docs/migration/legacy-to-modern.md.

Do not remove them until a later visual parity receipt covers all 12 legacy component pages, four blocks, five assembled scenes, both schemes, both densities, keyboard behavior, and 390px layout.

Contribution rules

1. Add reusable behavior to packages/ui; never implement a private specimen substitute.
2. New interactive primitives use Base UI unless an architecture decision records a concrete constraint.
3. Keep color semantic: greys structure the interface, and color communicates presence, status, or tool class.
4. Use the 4/8/12/16px radius scale and shared density tokens.
5. Comparable numbers use the numeric utility.
6. Keep one filled action per surface.
7. Pair every colored state with text, shape, weight, or iconography.
8. Preserve complete feedback under prefers-reduced-motion.
9. Add registry metadata and tests with every public component.
10. Run pnpm check before opening a pull request.