Opencoven Design

---
name: opencoven-design
description: Agent-operable design constraints for OpenCoven, Coven, harness cockpits, docs, and integration surfaces
style: dark
accent: violet
source_of_truth: DESIGN.md
---

# OpenCoven Design Skill

Use this skill when designing or implementing OpenCoven/Coven interfaces, docs pages, diagrams, package README visuals, native companion surfaces, or agent-built UI components.

OpenCoven should feel like collective intelligence plus controlled power: arcane but precise, technical not gimmicky, powerful not loud, minimal but symbolic.

Core positioning: OpenCoven is an open ecosystem for persistent AI familiars: named agents with memory, tools, identity, roles, and continuity. It turns AI from a blank chatbox into a living workspace of agents that remember, coordinate, and belong to the user.

## Source Of Truth

Read these local files before changing brand or UI behavior:

- `DESIGN.md` - canonical brand and design system
- `docs/BRAND.md` - brand asset index and usage summary
- `docs/BRANDING-ADHERENCE.md` - current exceptions, risks, and hardening checklist
- `brand/docs/BRAND-USAGE.md` - contributor PR checklist
- `brand/ui/color-tokens.css` - canonical CSS color tokens
- `brand/ui/typography.css` - canonical typography tokens

Do not invent a separate design system. If this skill conflicts with `DESIGN.md`, follow `DESIGN.md` and update this skill.

## Brand Position

Build for harness operators and developers, not a marketing toy.

- The default feeling is a quiet command cockpit.
- The product promise is durable AI systems that can stay: remember what matters, understand their purpose, use tools, coordinate with other agents, and remain understandable over time.
- A familiar is not a faceless bot. It has a name, purpose, memory, toolset, voice, role, and place in a larger workflow.
- Keep the philosophy clear: powerful without becoming opaque, personal without pretending to be human, extensible without collapsing into chaos.
- Mystical symbolism is allowed only when it supports identity: crown silhouette, mirrored wings, rising center, nodes, execution paths.
- Interfaces should be dense, legible, and repeatable under daily use.
- Copy should be direct and capable. Avoid hype, jokes, and vague AI language.
- Use `OpenCoven` for the ecosystem/org and `Coven` for the CLI/daemon/product.
- The command is always `coven`, never `opencoven`.

## Color Tokens

Read `brand/ui/color-tokens.css` and use the named `--oc-*` values directly. Do not copy literal canonical palette values into this skill; they belong in the token file.

Active tokens to import/use:

- `--oc-black`
- `--oc-white`
- `--oc-purple-1`
- `--oc-purple-2`
- `--oc-purple-3`
- `--oc-purple-glow`
- `--oc-accent-blue`
- `--oc-danger`
- `--oc-success`
- `--oc-surface-0`
- `--oc-surface-1`
- `--oc-surface-2`
- `--oc-border-subtle`
- `--oc-border-strong`
- `--oc-text`
- `--oc-text-muted`
- `--oc-text-faint`

### Color Rules

- Use black and white for roughly 90 percent of the composition.
- Reserve purple for identity, primary CTAs, focus, selected state, execution paths, and small highlights.
- Use `--oc-accent-blue` only for documented actionable/system states. Do not make blue the brand accent.
- Use `--oc-danger` for destructive actions and hard errors.
- Use `--oc-success` for completion, connected, passing, and healthy states.
- Keep text WCAG AA contrast on every surface.

## Signature Treatments

Gradients and glow are allowed only as controlled ambient brand moments, never on the crown itself.

Use the named tokens from `brand/ui/color-tokens.css` directly for ambient
effects: `--oc-radial-glow` and `--oc-focus-ring`. Do not
restate their color-stop values here.

Use signature treatment for:

- Hero/OG ambient background treatments
- Focus rings and interactive affordances
- Subtle radial glow behind the crown or nearby surfaces

Never apply these treatments to logo or crown rendering.

Do not use gradients or glows for:

- General cards
- Tables
- Dense cockpit panels
- Documentation diagrams, except small path highlights
- Decorative page backgrounds

## Typography

Coven uses a three-face system: **classical serif for identity, technical sans for reading, purpose-built mono for inspection.** Each face has one job.

```css
/* Display / brand — EB Garamond is canonical (headlines, hero, ceremonial only) */
--oc-font-display: "EB Garamond", "Iowan Old Style", Georgia, "Times New Roman", serif;

/* UI / body — Inter is canonical (everything you read) */
--oc-font-ui: Inter, "SF Pro Text", -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;

/* Mono — JetBrains Mono is canonical (everything you inspect) */
--oc-font-mono: "JetBrains Mono", "SF Mono", SFMono-Regular, ui-monospace, Menlo, Monaco, Consolas, "Liberation Mono", monospace;

--oc-tracking-heading: -0.02em;   /* sans headings — tight */
--oc-tracking-hero: -0.055em;     /* sans hero — very tight */
--oc-tracking-display: -0.005em;  /* EB Garamond headings — near-zero */
--oc-tracking-label: 0.14em;      /* uppercase mono badges */
--oc-line-body: 1.4;              /* sans body */
--oc-line-prose: 1.55;            /* serif long-form */
--oc-line-heading: 1.2;
```

### CovenCave Defaults

Cave (`coven-cave`) uses a user-selectable font catalog. The configured defaults follow DESIGN.md canon:
- **Display (serif):** `eb-garamond` — `--font-eb-garamond`
- **Sans (UI):** `inter` — `--font-inter`
- **Mono (code):** `jetbrains-mono` — `--font-jetbrains-mono`

Geist Sans and Geist Mono remain in the selectable catalog as clean alternatives; they are no longer the shipped defaults.

### Typography Rules

- **Serif is for identity moments only.** Headlines, hero, hero eyebrows, ceremonial sections, marketing spreads, print. Never body copy, never labels, never dense operational UI.
- **Sans is for everything you read.** Body, chat, prose, controls, tables, docs, forms, chrome.
- **Mono is for everything you inspect.** Code, terminal, identifiers, uppercase labels, badges, metadata, timestamps, keyboard hints.
- **Real italics matter.** EB Garamond has a distinctive italic — use it for pull-quotes, kickers, and named entities in lore copy. Do not synthesize italics on a font without a real italic style.
- JetBrains Mono is the canonical mono face — prefer it over SF Mono, Geist Mono, or system mono on any surface where you control the font.
- Keep sans body line height at 1.4, serif prose at 1.55, headings at 1.2.
- Avoid all-caps except for compact labels, badges, and nav group headings.
- **Do not add playful, cursive, or novelty fonts.** Rounded display faces (retired: Fredoka) are banned; a serif has replaced them where identity was needed.

## Spacing And Shape

- Base spacing is a 4px grid.
- Dense cockpit UIs should favor 4px, 8px, 12px, and 16px increments.
- Documentation and landing pages may use more breathing room, but still stay on grid.
- Cards and panels should use restrained radii: 4px to 8px unless a platform style requires otherwise.
- Do not nest cards inside cards.
- Use borders and alignment before shadows.

Recommended dimensions:

```
Button heights: 24px compact, 32px standard, 40px large
Input height: 32px standard
Table rows: 32px dense, 40px comfortable
Sidebar: 280px standard, 320px expanded
Modal: 400px compact, 500px standard, 600px wide
Icon grid: 24px or 32px
```

## Layout Patterns

### Harness Cockpit

Use for session managers, operator dashboards, run queues, agent control rooms, and debug tools.

- Left navigation or lane rail, main work area, optional right inspector.
- Dense rows with clear status badges.
- Mono identifiers for sessions, agents, tools, commits, ports, and paths.
- Explicit empty, loading, error, and disconnected states.
- No oversized marketing hero inside operational UI.

### Session Browser

Use tab-like navigation for long-lived work.

- Tabs or session pills show active work.
- Preserve browser-like history where relevant: back, forward, reopen, recent sessions.
- Active session should be obvious through border, text, and selected state, not color alone.
- Destructive session actions should be visible but gated.
- Use product ritual labels exactly where they exist: **Rejoin**, **View Log**, **Summon**, **Archive**, and **Sacrifice**.
- **Archive** is reversible and keeps the ledger.
- **Summon** restores an archived session to the active list.
- **Sacrifice** is permanent, refuses running sessions, and requires explicit confirmation such as `--yes` or typed confirmation.
- In terminal UIs, `coven sessions` should favor a human browser; `coven sessions --plain` stays scriptable.

### Documentation And Landing

- Landing hero: black foundation, centered transparent `brand/logo/opencoven-mark.svg` in `currentColor`, restrained purple ambient glow in the surrounding chrome only, literal OpenCoven/Coven offer.
- Docs: calm technical rhythm, readable code blocks, no decorative clutter.
- Diagrams: nodes, paths, monoline icons, purple execution highlights.
- Keep the next section visible below a landing hero on normal mobile and desktop viewports.
- Be honest about early MVP status where relevant. Do not imply production maturity beyond the docs.

### Repair And Trust Surfaces

- Repair flows should show selected repo root, branch, dirty files, untracked files, harness, and verification profile before launch.
- Dirty repos require a visible warning and confirmation.
- v0 repair flows never commit, push, or operate outside the selected repo root.
- Treat the Rust CLI/daemon as the authority boundary for project-root validation, PTY lifecycle, socket API, input/kill, and persistence.
- Clients may improve UX, but they must not visually imply authority they do not have.

## Components

### Buttons

- Primary: purple accent, white text, hover border/surface shift.
- Secondary: dark surface, subtle border, white or muted text.
- Ghost: transparent, clear hover surface.
- Danger: danger token, explicit label, confirmation for irreversible actions.
- Icon buttons should use familiar icons and tooltips when meaning is not obvious.
- Hover should not scale layout.

### Inputs

- Dark surface, subtle border, clear placeholder color.
- Focus must use visible purple ring or equivalent tokenized focus treatment.
- Error state must include border and text message.
- Disabled and readonly states must be visually distinct.

### Panels And Cards

- Use for real grouped content, repeated items, modals, and framed tools.
- Background: `--oc-surface-1` or `--oc-surface-2`.
- Border: `--oc-border-subtle` or `--oc-border-strong`.
- Prefer dividers and alignment over shadows.
- Do not use glass-heavy blur.

### Tables And Lists

- Header labels should be compact, muted, and scannable.
- Rows should support hover, selected, focused, loading, and error states.
- Use mono for machine data.
- Avoid zebra striping unless density requires it.

### Badges

- Use badges for run status, agent state, verification result, branch state, auth state, and risk level.
- Keep badges compact.
- Pair color with text, never color alone.

### Modals And Confirmations

- Use modals for irreversible or high-risk choices.
- Dialog copy should name the action and affected resource.
- Prefer archive/stop/disable before delete where the product supports recovery.
- Danger action must not be the default focused action.

## Interaction States

Every interactive element needs these states:

- Default
- Hover
- Active or pressed
- Focus visible
- Disabled
- Loading or pending where async work exists
- Error where user recovery is possible

Keyboard navigation must remain visible. Never remove focus indicators without a tokenized replacement.

## Motion

- Motion should clarify state changes, not decorate the page.
- Standard transition: 150ms to 250ms.
- Page or path drawing motion may run 600ms to 1200ms when it explains graph/execution flow.
- Respect `prefers-reduced-motion`.
- Hover border/surface changes are preferred over scale for brand CTAs.
- Do not animate body text or cause layout shift.

## Iconography

- Use monoweight, geometric, slightly sharp icons.
- Use existing icons from `brand/icons/` when possible.
- Use crown points, mirrored wings, rising forms, nodes, and connection lines only as meaningful motifs.
- Avoid emoji and whimsical icons in system UI.
- Test logo and icon legibility at 24px minimum.

## Logo Rules

- Public/exported surfaces use the approved flat white crown on a black square.
- Do not add gradient, glow, shadow, or the retired emblem to the exported logo.
- Controlled dark compositions inside the landing page shell may use `brand/logo/opencoven-mark.svg` with `currentColor` for nav, hero, and footer.
- Do not apply glow to the logo itself; keep purple glow as an ambient background/UI effect only.
- Use `assets/opencoven/opencoven.svg` as the shared SVG source.
- Use `docs/assets/opencoven-icon.svg` for the generated docs site.
- Package READMEs use package-local copies of the approved SVG.
- Preserve aspect ratio and clear space.
- Do not create, publish, or link alternate public logo variants.

## Accessibility

- Hit targets should be large enough for pointer use: 32px minimum for dense tools, 40px preferred for primary actions.
- Do not rely on color alone for status, risk, or selection.
- Keep focus order predictable through rails, tabs, tables, dialogs, and inspectors.
- Modals must trap focus while open and restore focus when closed.
- Every icon-only control needs an accessible name and tooltip where helpful.

## Verification

Before claiming a UI or brand change follows this skill:

- Check changed colors against `brand/ui/color-tokens.css`.
- Check typography against `brand/ui/typography.css`.
- Inspect desktop and mobile layouts when a visual surface changed.
- Verify focus, hover, disabled, loading, empty, and error states for touched interactive components.
- Run the smallest relevant project gate: typecheck, lint, build, screenshot, or direct visual inspection.
- Record intentional exceptions in `docs/BRANDING-ADHERENCE.md`.

## MUST

- Use `DESIGN.md` and `brand/ui/*.css` as source of truth.
- Build dark-first on pure black foundations.
- Keep UI technical, minimal, and symbolic.
- Use `OpenCoven`, `Coven`, and `coven` with their exact product meanings.
- Keep purple controlled and meaningful.
- Use tokenized colors and typography.
- Provide visible focus states.
- Provide empty, loading, disabled, error, and success states where applicable.
- Gate destructive actions.
- Preserve Archive/Summon/Sacrifice semantics in session UI.
- Respect the Rust daemon as the authority boundary in trust-sensitive UI.
- Keep dense operator surfaces scannable.
- Use mono for operational data.

## SHOULD

- Use borders and spacing before shadows.
- Prefer tabs, rails, split panes, inspectors, and command surfaces for harness workflows.
- Use status badges for session/agent/tool state.
- Keep page copy short and concrete.
- Use diagrams to explain orchestration only when they clarify relationships.
- Document any intentional exception in `docs/BRANDING-ADHERENCE.md`.

## NEVER

- Do not use light mode as the primary OpenCoven experience.
- Do not use random gradients, noise textures, bokeh, or decorative blobs.
- Do not overuse purple; it should feel intentional, not saturated.
- Do not use blue, green, or red as brand accents.
- Do not hide focus rings.
- Do not use heavy blur/glass effects.
- Do not use shadows as the main structure.
- Do not make marketing heroes inside operator tools.
- Do not add playful fonts, emoji UI, or novelty iconography.
- Do not place text over complex backgrounds.
- Do not create orphan color values when a token exists.

## Prompt Pattern

Use this pattern when assigning UI work to an agent:

```markdown
Build [surface/component] for OpenCoven.
Follow skills/opencoven-design/SKILL.md and the canonical brand files:
- DESIGN.md
- brand/ui/color-tokens.css
- brand/ui/typography.css

The surface must include:
- [required states]
- [required interactions]
- [data density / layout constraints]

Do not invent new colors, logo variants, or decorative effects.
Return changed files, verification run, and any brand exceptions.
```

## Review Checklist

- Colors come from `--oc-*` tokens or documented semantic aliases.
- Typography uses `--oc-font-ui`, `--oc-font-display`, or `--oc-font-mono`.
- Purple is limited to identity, focus, selected state, CTAs, and execution highlights.
- Hover states change border/surface; they do not glow or scale layout.
- Dense tools are scannable and not card-heavy.
- Destructive actions are explicit and gated.
- Focus, disabled, loading, empty, and error states are present.
- Public exports use the full black-square, white-crown logo; controlled dark nav, hero, and footer may use the transparent mark.
- Any exception is documented in `docs/BRANDING-ADHERENCE.md`.

---

Last updated: 2026-08-14
Version: 1.3.0
License: MIT