kobar-project/kobar/kobar-ui-ux-designer

KoBar UI Guide (remastered design system)

Visual rules: KoBar now uses the Canlı visual language. Colours, shapes, type, icons, the bar's tiles and the

card/panel patterns are defined in the Canlı design guide; where this guide and

that one disagree on a visual rule, Canlı wins. The structural rules below (windows, state, hit-testing, i18n,

layers, primitives) still apply.

This file documents the KoBar design system for agents writing host UI in src/. The source of truth is the design tokens in src/index.css and the primitives in src/ui/. It documents the current system; it is not binding on plugin authors. Plugin authors follow for-agents/kobar-plugin-developer/SKILL.md. Anything marked LEGACY below exists only so v1 plugins keep working; never use it in new host code.

1. Character

Native-calm: a quiet shell, with colour only for state, selection, focus and the single primary action. No glow, no gradients, no grow-on-hover, no decorative animation. Light and dark schemes both exist; never assume dark. Corners are modest (6 / 8 / 12 / 16 px), not "as round as possible".

2. Windows and where state lives

KoBar renders host UI in three windows. Know which one you are in before you read state or add an interaction.

3. Root attributes (set on :root, do not set them in components)

Components never branch on these; the tokens change underneath them. In JS, use isMacPlatform() / getDocumentPlatform() from src/platform.ts when behaviour (not styling) depends on the platform.

4. Tokens and utilities

Use semantic utilities. Never use raw palette utilities (bg-slate-800, text-white, bg-blue-500) for structure.

Colour rules:

• ESLint forbids `#hex` and `rgb(`/`rgba(` inside any JSX `className` (string or template literal, including

conditionals; eslint.config.js, error level). If you need a colour, use a token utility or bg-[var(--kb-...)].

• The accent never paints backgrounds of large areas; it marks selection, focus and the one primary action.
• On a translucent shell, accent is never the only signal for state; add an icon, fill or text. Cards with text stay solid.
• Never use pure black text. Use text-fg-1.
• Contrast: text 4.5:1, controls/indicators 3:1. If you add a colour, compute it.

5. Typography

• System font stack via tokens (--kb-font, --kb-font-display, --kb-font-mono); Segoe UI Variable on Windows, SF Pro on

macOS (the darwin block reorders the stack). The body default is already set; do not apply font-display or a font family.

• Roles: caption 11/16, body 13/20, body-strong 13/20 weight 600 (buttons, row titles, section headers in sentence case, text-fg-2), subtitle 15/22 (panel title), title 20/28, display 28/36 (note title only).
• No uppercase, wide-tracked micro labels (text-[10px] uppercase tracking-wider is gone).
• LEGACY: Space Grotesk stays only as an @font-face alias for v1 plugins. Host code never uses it.

6. Icons

• Material Symbols Outlined, loaded locally (variable font, default wght 300, opsz 20).
• Use <Icon>; sizes 16 / 20 / 24 only. Active/selected state uses filled (FILL axis 1), not a different icon.
• Icon names are part of the plugin contract; the family does not change. Do not add SVG icon libraries.
• Decorative icons are hidden from assistive tech automatically; give label only if the icon alone carries meaning.

<Icon name="settings" size={20} />
<Icon name="star" filled size={16} />
<Icon name="warning" size={20} label={t('status.warning')} />

7. Primitives (import { ... } from '../ui' / src/ui/index.ts)

All primitives use only --kb-* tokens and already apply no-drag-region, pointer-events-auto, the focus ring and reduced-motion handling. Do not re-add those classes on top. Primitives contain no i18n: pass translated strings.

Pick the primitive first; hand-written <button className=...> is the exception.

Examples:

// Primary + secondary action, with an icon and a loading state
<Button variant="primary" icon="add" loading={saving} onClick={save}>{t('save')}</Button>
<Button variant="secondary" onClick={close}>{t('cancel')}</Button>
// Icon-only button: label is mandatory; pressed = toggle state
<IconButton icon="push_pin" label={t('pinToggle')} pressed={pinned} onClick={togglePin} />
// Setting row with a Toggle; hideLabel because the row already shows the title
<ListItem
  title={t('settingsSound')}
  description={t('settingsSoundHint')}
  trailing={<Toggle checked={sound} onChange={setSound} label={t('settingsSound')} hideLabel />}
/>
// Form fields
<TextField label={t('noteTitle')} value={title} onChange={(e) => setTitle(e.target.value)} error={err} />
<Select label={t('settingsEdge')} value={edge} onChange={(e) => setEdge(e.target.value)}
        options={[{ value: 'left', label: t('edgeLeft') }, { value: 'right', label: t('edgeRight') }]} />
// Tabs / Segmented are controlled
<Segmented items={[{ value: 'a', label: t('optionA') }, { value: 'b', label: t('optionB'), icon: 'list' }]} value={v} onChange={setV} />
// Menu with a destructive item
<Menu
  aria-label={t('noteMenu')}
  trigger={<IconButton icon="more_vert" label={t('more')} />}
  items={[
    { id: 'rename', label: t('rename'), onSelect: rename },
    { type: 'separator' },
    { id: 'delete', label: t('delete'), danger: true, onSelect: askDelete },
  ]}
/>
// Destructive confirmation (every string from src/i18n/locales/*.json via t)
<ConfirmDialog open={open} danger title={t('deleteConfirmMsg')} confirmLabel={t('delete')}
               cancelLabel={t('cancel')} onConfirm={doDelete} onCancel={() => setOpen(false)} />
// Toasts: the main window mounts <ToastRegion> once; call from anywhere in that window
toast.success(t('noteSaved'), { action: { label: t('undo'), onClick: undo } });
// Container and empty state
<Surface level="surface" elevation="e1" radius="md" className="p-4">...</Surface>
<EmptyState icon="inbox" title={t('pluginsNone')} action={<Button onClick={browse}>{t('pluginsBrowse')}</Button>} />