UI kit

zidane-ui is the design system behind the desktop app and this site, plus the app's chat components: session list, transcript and composer. The chat components read a ChatHost, an object of readable stores and optional actions. A fixture, an in-page agent, your server or zidane-server can be the host.

The design system works without the chat layer. The chat layer works without zidane-ui/adapters. Every import is listed in Entry points.

Install#

npm install zidane-ui react react-dom motion
npm install zidane   # for every area except appearance, plus the adapters and the server helpers

Without zidane you can use the design system (zidane-ui, zidane-ui/code/editor, the highlight and patch-parse workers, zidane-ui/labels, zidane-ui/uno), the appearance area, and the headless and testing entries of files and terminal. Markdown (react-markdown, remark-gfm) and the composer editor (Tiptap) are regular dependencies.

Styling#

Pick one of the two routes below. Do not use both.

Prebuilt CSS#

Use this route when your app does not run UnoCSS. Import one stylesheet once: zidane-ui/core.css for the design system alone, zidane-ui/styles.css for everything (chat, setup wizard, editor, terminal). It holds every utility class and icon that those components use, then the kit styles. If your page has no reset, import the reset first. Without one, native button and list styles show through.

import 'zidane-ui/reset.css'
import 'zidane-ui/core.css' // or 'zidane-ui/styles.css'

The prebuilt files sit in the cascade layers zidane-ui.reset, zidane-ui.utilities and zidane-ui.kit, so your own unlayered CSS overrides the kit without a specificity fight. They only carry the utilities the kit uses: to put token classes in your own markup, take the UnoCSS route or use the --zg-* variables.

UnoCSS#

Add the preset, scan the kit's files and import the kit stylesheet after the Uno utilities. Your markup can then use token classes (bg-zg-raised, text-zg-muted). crispPhosphor draws regular Phosphor icons with their bold outline, so they stay crisp at the kit's 10 to 14px.

// uno.config.ts
import { crispPhosphor, presetZidane } from 'zidane-ui/uno'
import { defineConfig, presetIcons, presetUno } from 'unocss'

export default defineConfig({
  content: { filesystem: ['src/**/*.{ts,tsx}', 'node_modules/zidane-ui/dist/**/*.js'] },
  presets: [presetIcons({ collections: { ph: () => import('@iconify-json/ph/icons.json').then(i => crispPhosphor(i.default)) } }), presetUno({ dark: { dark: '.dark' } }), presetZidane()],
})

/* your stylesheet, after the Uno utilities */
@import 'zidane-ui/styles/index.css';
/* or, to put the kit in a layer of its own: */
@import 'zidane-ui/styles/index.css' layer(zidane-ui);

Components paint from --zg-* CSS variables with dark defaults, so they render before you set a theme.

Extension icons#

Extensions name their icons as data (icon: { gui: 'i-ph-rocket' }), so no stylesheet built ahead of time has them all. Call watchRuntimeIcons once at startup, on either route. It adds the rule of each i-ph-* class the page shows without one, from the same Phosphor set. The set loads the first time an icon is missing, in a chunk of its own.

import { watchRuntimeIcons } from 'zidane-ui'
import { crispPhosphor } from 'zidane-ui/uno'

watchRuntimeIcons({ loadPhosphor: () => import('@iconify-json/ph/icons.json').then(m => crispPhosphor(m.default)) })

Build your own agent UI#

The example below puts a sidebar, a transcript, question cards and a composer on one host. This fixture host echoes every prompt. You can swap in a real host without a change to the components.

import 'zidane-ui/styles.css'
import { ChatProvider, HostComposer, HostInteractions, HostTranscript, SessionList } from 'zidane-ui/chat'
import { createFixtureHost } from 'zidane-ui/chat/testing'
import { useState } from 'react'

const host = createFixtureHost(
  { sessions: [{ id: 's1', title: 'First session', status: 'idle', createdAt: Date.now(), updatedAt: Date.now() }] },
  { reply: prompt => [{ kind: 'markdown', text: `You said: ${prompt}` }] },
)

export function App() {
  const [id, setId] = useState('s1')
  return (
    <ChatProvider host={host}>
      <div style={{ display: 'grid', gridTemplateColumns: '260px 1fr', height: '100vh' }}>
        <SessionList activeId={id} onSelect={setId} search />
        <main style={{ display: 'flex', flexDirection: 'column', gap: 12, padding: 16, minWidth: 0 }}>
          <div style={{ flex: 1, overflowY: 'auto' }}><HostTranscript sessionId={id} /></div>
          <HostInteractions sessionId={id} />
          <HostComposer sessionId={id} attachments />
        </main>
      </div>
    </ChatProvider>
  )
}

The inline styles are there because the prebuilt stylesheet holds only the kit's own classes. With UnoCSS, use utility classes.

Pick a host#

A host runs the agent behind the components. Every host returns a ChatHost, so switching hosts leaves the components unchanged.

Connecting a host sets up each one and lists their limits. Server clients compares a browser with other zidane-server clients.

What a host offers#

To write your own host, implement ChatHost. Only transcript(id) is required. Each optional member that you leave out hides its control:

Entry points#

dist/ has one module per source file. Only the CSS has side effects, so bundlers keep only what you import. No module has 'use client'. If you use React Server Components, import the kit from your own client component.

Labels#

Every rendered string comes from one dictionary. Override chat strings with ChatProvider's labels prop and design-system strings (Copy, Confirm, Cancel, Close) with LabelsProvider. Function labels take their values as arguments, so translations control word order. A prop passed to a component wins over the dictionary.

import type { ChatHost } from 'zidane-ui/chat/headless'
import type { ReactNode } from 'react'
import { ChatProvider } from 'zidane-ui/chat'
import { LabelsProvider } from 'zidane-ui/labels'

export function French({ host, children }: { host: ChatHost, children: ReactNode }) {
  return (
    <LabelsProvider labels={{ confirm: 'Confirmer', cancel: 'Annuler', close: 'Fermer' }}>
      <ChatProvider
        host={host}
        labels={{
          newSession: 'Nouvelle session',
          searchSessions: 'Rechercher',
          noMatches: query => `Aucune session ne correspond à « ${query} »`,
          composerPlaceholder: 'Écrivez à l’agent…',
        }}
      >
        {children}
      </ChatProvider>
    </LabelsProvider>
  )
}

Full lists: DEFAULT_LABELS (zidane-ui/labels) and DEFAULT_CHAT_LABELS (zidane-ui/chat/headless).

Next#