AI DevOps Framework Brand Guidelines

Source: DESIGN.md

Status: generated handoff artifact for issue #24834. Regenerate after any DESIGN.md change.

Token Summary

version: alpha
name: AI DevOps Framework
description: Developer-first automation interface using GitHub-dark surfaces, blue focus, green operational success, compact cards, and system typography.
colors:
  primary: "#58a6ff"
  secondary: "#8b949e"
  tertiary: "#238636"
  neutral: "#0d1117"
  background: "#0d1117"
  surface: "#161b22"
  surface-raised: "#21262d"
  on-surface: "#c9d1d9"
  on-primary: "#0d1117"
  on-tertiary: "#ffffff"
  outline: "#30363d"
  muted: "#6e7681"
  success: "#3fb950"
  warning: "#fbbf24"
  error: "#da3633"
  error-hover: "#f85149"
typography:
  headline-display:
    fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif"
    fontSize: 32px
    fontWeight: 700
    lineHeight: 1.15
    letterSpacing: -0.02em
  headline-lg:
    fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif"
    fontSize: 24px
    fontWeight: 700
    lineHeight: 1.2
  headline-md:
    fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif"
    fontSize: 18px
    fontWeight: 600
    lineHeight: 1.3
  body-lg:
    fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif"
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.55
  body-md:
    fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif"
    fontSize: 14px
    fontWeight: 400
    lineHeight: 1.5
  body-sm:
    fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif"
    fontSize: 12px
    fontWeight: 400
    lineHeight: 1.45
  label-md:
    fontFamily: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif"
    fontSize: 12px
    fontWeight: 600
    lineHeight: 1.2
rounded:
  none: 0px
  sm: 4px
  md: 6px
  lg: 8px
  xl: 12px
  full: 9999px
spacing:
  unit: 4px
  xs: 4px
  sm: 8px
  md: 12px
  lg: 16px
  xl: 20px
  gutter: 16px
  margin: 20px
components:
  dashboard-page:
    backgroundColor: "{colors.neutral}"
    textColor: "{colors.on-surface}"
    typography: "{typography.body-md}"
    padding: 20px
  card:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.on-surface}"
    typography: "{typography.body-md}"
    rounded: "{rounded.lg}"
    padding: 16px
  card-hover:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.on-surface}"
    rounded: "{rounded.lg}"
  input-default:
    backgroundColor: "{colors.background}"
    textColor: "{colors.on-surface}"
    typography: "{typography.body-md}"
    rounded: "{rounded.md}"
    padding: 8px
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    typography: "{typography.body-md}"
    rounded: "{rounded.md}"
    padding: 8px
  button-primary-hover:
    backgroundColor: "#2ea043"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.md}"
  button-secondary:
    backgroundColor: "{colors.surface-raised}"
    textColor: "{colors.on-surface}"
    typography: "{typography.label-md}"
    rounded: "{rounded.md}"
    padding: 6px
  button-secondary-hover:
    backgroundColor: "{colors.outline}"
    textColor: "{colors.on-surface}"
    rounded: "{rounded.md}"
  button-danger:
    backgroundColor: "{colors.error}"
    textColor: "{colors.on-tertiary}"
    typography: "{typography.label-md}"
    rounded: "{rounded.md}"
    padding: 6px
  button-danger-hover:
    backgroundColor: "{colors.error-hover}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.md}"
  badge-success:
    backgroundColor: "{colors.success}"
    textColor: "{colors.on-primary}"
    typography: "{typography.label-md}"
    rounded: "{rounded.full}"
    padding: 4px
  badge-warning:
    backgroundColor: "{colors.warning}"
    textColor: "{colors.on-primary}"
    typography: "{typography.label-md}"
    rounded: "{rounded.full}"
    padding: 4px
  badge-neutral:
    backgroundColor: "{colors.muted}"
    textColor: "{colors.on-tertiary}"
    typography: "{typography.label-md}"
    rounded: "{rounded.full}"
    padding: 4px
  badge-error:
    backgroundColor: "{colors.error}"
    textColor: "{colors.on-tertiary}"
    typography: "{typography.label-md}"
    rounded: "{rounded.full}"
    padding: 4px

Design System: AI DevOps Framework

Overview

AI DevOps is a developer-operations framework and OpenCode plugin. Its interface language should feel like a reliable engineering console: dark by default, compact, status-led, and evidence-oriented. The current implemented UI evidence is the MCP Server Dashboard in .opencode/server/mcp-dashboard.ts, which uses GitHub-dark colours, compact cards, system fonts, blue focus/highlight states, green primary actions, red destructive actions, and 4px/8px spacing increments.

Design goals:

• Keep operational state obvious: running, stopped, error, authenticated, last update, and command actions should scan quickly.
• Preserve developer trust with native system typography, code-friendly contrast, visible borders, and restrained motion.
• Use compact density for dashboards and sidebars, but keep controls at least 44px high when touch use is plausible.
• Prefer semantic tokens over one-off values so generated reports, OpenCode UI surfaces, and dashboard screens stay consistent.

Colors

The canonical palette is derived from the dashboard CSS in .opencode/server/mcp-dashboard.ts:

Contrast rules:

• Use #c9d1d9 or white text on #0d1117, #161b22, #21262d, #238636, and #da3633.
• Do not use muted text below 12px; pair #6e7681 only with non-critical metadata.
• Blue #58a6ff is an accent, not the primary CTA colour; reserve CTA fill for green #238636 unless the action is navigation/focus.

Typography

Use native system UI fonts for app and dashboard surfaces:

font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;

Scale:

• Display: 32px / 700 / 1.15 for handoff covers and major report titles.
• Large heading: 24px / 700 / 1.2 for page-level headings.
• Medium heading: 18px / 600 / 1.3 for card titles; matches the dashboard .card-title size.
• Body: 14px / 400 / 1.5 for dashboard controls and normal UI copy.
• Small: 12px / 400-600 for badges, metadata, helper text, and compact buttons.

Code snippets and command examples may use SFMono-Regular, Consolas, Liberation Mono, Menlo, or monospace, but the primary interface remains system sans.

Layout

Use a compact 4px base with an 8px rhythm:

• Page padding: 20px on dashboard-like pages.
• Grid gap: 16px; dashboard cards use repeat(auto-fill, minmax(300px, 1fr)).
• Panel/card padding: 16px.
• Form/control horizontal rhythm: 8px or 12px gaps.
• Sidebar width: 420px default, 320px minimum, 640px maximum from .opencode/ui/chat-sidebar/constants.ts.
• Message and panel content should use a readable max width near 600px when not in a dashboard grid.

Keep dashboard layouts responsive through fluid grids rather than fixed breakpoints. On narrow screens, cards stack to a single column and action rows may wrap.

Elevation & Depth

Depth is border-led rather than shadow-led:

• Use 1px solid #30363d for card, auth bar, input, and button boundaries.
• Use #161b22 panels over #0d1117 page background.
• Use #21262d for secondary action surfaces.
• Hover depth changes border or fill colour, not position.
• Reserve heavy shadows for generated browser/PDF report previews, not operational dashboards.

Shapes

Radius is compact and functional:

• 4px for code chips and very small inline elements.
• 6px for inputs and buttons.
• 8px for cards, panels, and auth bars.
• 12px for larger generated report containers.
• Full radius for status badges and pills.

Avoid large rounded marketing cards in operational screens unless the surface is a report preview or handoff artifact.

Components

Core component rules:

• Page shell: #0d1117 background, #c9d1d9 text, 20px padding, system font.
• Cards: #161b22 background, #30363d border, 8px radius, 16px padding. Hover changes border to #58a6ff.
• Inputs: #0d1117 background, #30363d border, #c9d1d9 text, 6px radius, 8px 12px padding.
• Primary buttons: green #238636 fill with white text; hover #2ea043.
• Secondary buttons: #21262d fill, #30363d border, #c9d1d9 text; hover #30363d.
• Danger buttons: red #da3633 fill and border; hover #f85149.
• Status badges: 4px 8px padding, full pill radius, 12px/500 type. Running is green, stopped/unknown is muted grey, error is red.
• Metadata: use #8b949e at 12px; use #6e7681 only for lowest-emphasis timestamps.
• Focus: keyboard focus should use blue #58a6ff outline or border with at least 2px visible affordance.

Do's and Don'ts

Do:

• Use semantic tokens from this file before adding new hex values.
• Keep dashboards compact, structured, and border-defined.
• Use green for safe primary operations and red only for destructive/error states.
• Preserve high contrast and readable 12px+ metadata.
• Keep generated reports and brand handoffs free of private local paths, secrets, raw transcripts, and unrelated repo names.

Don't:

• Add light-only UI surfaces without a matching dark-mode treatment.
• Use blue filled CTAs when green better communicates an operational action.
• Hide error state in colour alone; pair colour with text labels.
• Introduce decorative gradients, glassmorphism, or heavy shadows into operational tooling.
• Use skeleton placeholder brand values in UI or generated guidelines.

Responsive Behaviour

• Dashboard grids should use auto-fit/auto-fill patterns and collapse to one column below the card minimum width.
• Chat sidebars keep the 320px-640px clamp and default to 420px.
• Button rows may wrap; primary and destructive actions remain visually distinct when wrapped.
• Generated report handoffs should print cleanly to A4, US Letter, and 16:9 slides without clipped tables.
• Maintain keyboard and screen-reader access for every control; existing ARIA labels in .opencode/ui/chat-sidebar/constants.ts are the naming pattern.

Agent Prompt Guide

When implementing AI DevOps UI:

1. Read DESIGN.md before changing any dashboard, sidebar, generated report, or browser-facing interface.

2. Reuse the token names and values in the YAML front matter. If a new state is needed, add a semantic token and explain the evidence source.

3. Match the GitHub-dark operational console style: dark background, raised dark cards, blue focus/highlight, green safe action, red danger/error.

4. Verify contrast for new text/background pairs and keep focus indicators visible.

5. Regenerate brand guideline artifacts after changing this file with aidevops design guidelines . --pdf.

Handoff QA

• [x] Generated from project-root DESIGN.md.
• [x] Uses observed UI values from .opencode/server/mcp-dashboard.ts and .opencode/ui/chat-sidebar/constants.ts.
• [x] Contains no secrets, raw transcripts, private local paths, or unrelated repo names.
• [x] HTML and PDF exports are generated from this Markdown handoff.