Visual Style Reference

Defines the exact visual language used across magi and melchior. Apply these patterns consistently. Every file. Every context.

Core rule: decoration frames content. Every element must make output easier to parse, not harder. When in doubt, use less.

---

Color Palette

CLI output only. Not applicable to committed source files.

Role	ANSI Code	Hex	Use
Primary	\033[38;5;214m	#ffaf00	Amber — panel borders, section headers
Bright	\033[38;5;220m	#ffd700	Yellow-amber — emphasis, prompts
Dim	\033[38;5;172m	#c86000	Dark orange — secondary text
Success	\033[38;5;82m	#5fd700	Green — confirmations, valid state
Error	\033[38;5;196m	#ff2222	Red — failures, blocking errors
Muted	\033[38;5;240m	#585858	Dark gray — hints, defaults
Text	—	#c8b89a	Warm off-white — body text (web only)
Bold	\033[1m	—	Combine with a color code
Reset	\033[0m	—	Always reset after coloring

---

Plain Text Patterns

Apply to: .env.example, casc.yml, docker-compose.yml, Dockerfile, *.groovy, Jenkinsfile, build.gradle.

Line width target: 72 characters total (including the comment prefix). Trailing dashes fill each pattern to that width.

---

Pattern 1 — Section Header

Used for major sections: config blocks, pipeline stages, top-level code divisions.

# /─[ SECTION TITLE ]──────────────────────────────────────────────────

// /─[ SECTION TITLE ]─────────────────────────────────────────────────

Rules:

• Title in ALL CAPS
• Open-ended right side — the content below is the body of this section
• Trailing ─ fills the line to 72 characters total

.env.example example:

# /─[ CORE JENKINS ]───────────────────────────────────────────────────
JENKINS_ADMIN_PASSWORD=        # required — emergency break-glass access
JENKINS_URL=                   # required — public URL (Cloudflare tunnel output)

Groovy example:

// /─[ INDICATOR FILE DETECTION ]───────────────────────────────────────
def indicators = [
    'Dockerfile.ci', 'package.json', 'pom.xml'
]

---

Pattern 2 — Block Header

Used at the top of source files only: *.groovy, Jenkinsfile, build.gradle. Provides a framed description of the file's purpose.

// /─[ Name ]───────────────────────────────────────────────────────────
// >  One-line description of what this file does.
// >  Second line if needed — two lines max.
// \────────────────────────────────────────────────────────────────────

Rules:

• Name in camelCase or Title Case matching the actual file/step name
• Description lines use imperative mood, complete sentences
• Bottom border uses \ + ─ aligned to header width
• File-level only — do not use inside functions or methods

Example:

// /─[ detectAgent ]────────────────────────────────────────────────────
// >  Infers the Jenkins agent label from workspace indicator files.
// >  Falls back to JENKINS_DEFAULT_AGENT env var, then hard-fails.
// \────────────────────────────────────────────────────────────────────

---

Pattern 3 — Subsection Divider

Groups related items within a section.

# >> label ──────────────────────────────────────────────────────────

Rules:

• Label in lowercase
• Fills to 72 characters total
• Only use inside an established section, never at the top level

Example:

# /─[ ARTIFACT STORAGE ]───────────────────────────────────────────────
# >> local (default) ─────────────────────────────────────────────────
ARTIFACT_STORE_TYPE=local

# >> remote backends ──────────────────────────────────────────────────
# ARTIFACT_STORE_TYPE=s3
# ARTIFACT_STORE_URL=
# ARTIFACT_STORE_CREDENTIALS=

---

Pattern 4 — Annotations

Inline markers for notes and warnings. Use sparingly — if every line has one, none of them matter.

# ▸ non-obvious context or constraint worth calling out
# ▲ WARNING: destructive or irreversible operations only

Required/optional field markers (.env.example only):

VAR_NAME=               # required — one-line description
VAR_NAME=default_value  # optional — one-line description

---

Markdown Patterns

Apply to all .md files rendered by MkDocs or GitHub.

The amber/orange palette comes from the MkDocs Material theme — not from raw ASCII art. Work with the renderer, not against it. ASCII decoration belongs inside code blocks, showing what terminal output actually looks like, not as raw markdown structure.

---

Section Structure

Use standard markdown headers. The theme provides the visual hierarchy.

## Major Section

### Subsection

#### Detail (use sparingly — three levels is almost always enough)

---

Callouts

Use Material admonitions. Not hand-rolled ASCII boxes.

!!! note "Optional title"
    Content here. Renders as an amber-bordered panel in the Material theme.

!!! warning "Title"
    For destructive operations, irreversible steps, or important caveats.

!!! tip "Title"
    For shortcuts, best practices, or things that save time.

---

Terminal Output in Docs

Show real CLI output in fenced sh blocks. This is where the panel aesthetic appears in documentation — as accurate examples of what the terminal looks like, not as decoration.

```sh
┌─[ CONFIGURATION WIZARD ]───────────────────────────────────────────
  Jenkins admin password  ████████████
  Public URL              https://jenkins.example.com
  Cloudflare token        [set]
  GitHub App ID           12345
  ▸ Configuration written to .env
```

---

Horizontal Rules

Use --- to separate major content blocks when section headers alone are not enough. Do not use them between every section — only where there is a genuine content break.

---

CLI Output Patterns

Apply to: setup wizard and any scripts that produce terminal output.

---

Panel Header

AMBER = '\033[38;5;214m'
BOLD  = '\033[1m'
RESET = '\033[0m'

def panel(title: str, width: int = 72) -> str:
    dashes = '─' * (width - len(title) - 6)
    return f"{AMBER}┌─[ {BOLD}{title}{RESET}{AMBER} ]{dashes}{RESET}"

Renders as:

┌─[ JENKINS CORE ]───────────────────────────────────────────────────

---

Step Indicator

Used when the wizard has multiple stages. Format: [ current / total ]─[ title ].

┌─[ 2 / 7 ]─[ CLOUDFLARE TUNNEL ]───────────────────────────────────

---

Status Lines

  ▸ Jenkins URL        https://jenkins.example.com
  ▸ Admin password     [set]
  ✓ Configuration valid
  ✗ GitHub App ID      not set

• ▸ — field label and value
• ✓ — success / valid state
• ✗ — missing or invalid (shown in red)

---

Manual Action Pause

Used when the wizard must wait for a browser action (GitHub App creation, etc.). The wizard pauses here and resumes when the user presses Enter.

  ▲ ACTION REQUIRED
  ─────────────────────────────────────────────────────────────────
  Complete this step in your browser, then return here and press Enter.

  [Enter to continue]

---

What Not to Do

• ASCII box art that fills the terminal with structure but contains no useful content
• Decoration on every single line — patterns lose meaning when they're everywhere
• Mixed styles — pick one variant per file type and stick to it
• Right-side borders on section headers — they don't add information and break at narrow terminals
• Using these patterns in rendered markdown as raw text — they look wrong outside a monospace terminal