Generated brand handoff

# AI DevOps Framework Brand Guidelines

Canonical source: `DESIGN.md`. Generated for browser review and PDF handoff.

# 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`:

Token | Value | Use
--- | --- | ---
`background` / `neutral` | `#0d1117` | Page background, input background, code wells
`surface` | `#161b22` | Cards, authentication bar, raised panels
`surface-raised` | `#21262d` | Secondary buttons and low-emphasis controls
`outline` | `#30363d` | Borders, dividers, hover fills
`on-surface` | `#c9d1d9` | Primary text on dark surfaces
`secondary` | `#8b949e` | Body metadata, helper copy, inactive labels
`muted` | `#6e7681` | Lowest-emphasis timestamps and stopped/unknown badges
`primary` | `#58a6ff` | Headings, focus, hover border, selected highlights
`tertiary` | `#238636` | Primary action and running status
`success` | `#3fb950` | Authenticated/success text
`warning` | `#fbbf24` | Warnings and cautionary evidence badges
`error` | `#da3633` | Error status and destructive actions
`error-hover` | `#f85149` | Error text and danger hover

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.