docs(site): make the docs site feel like part of Docker, and explain what Docker Agent is

[dgageot]

Bring the docs site in line with Docker's official design system and rewrite the homepage so first-time visitors can answer "what is this and why should I care?" in under 30 seconds.

No application/runtime code is touched — every change is in docs/.

Re-opened from #2792 against an internal branch (the original PR was on a fork, so the cross-fork CI gate skipped). The full review history (37 incremental commits + the back-and-forth that produced this) is in #2792.

---

Commits

#	Commit	Change
1	0f122af2a	ci: drop the dead Docs Preview workflow — the workflow could never deploy a preview (cross-fork gate + github-pages environment locked to main). Removed rather than left as a permanent red FAILURE on every docs/** PR.
2	7aae80c1e	docs(site): rebrand to docker.com / docs.docker.com style — see breakdown below.

The second commit's message lists every sub-change. A summary follows.

---

What's in the rebrand commit

Branding

• Fonts switched to Roboto Flex (sans, the variable-axis font docs.docker.com self-hosts) and Roboto Mono (mono).
• Color tokens introduced as a structured palette derived from the official brand kit (Docker-Logos-1.zip):
  • --blue-100..700 anchored on Ocean Blue #2560FF
  • --navy-900..600 anchored on Deep Blue #00153C
  • --gray-100..900 lifted verbatim from docs.docker.com
• Dark theme matches docs.docker.com: neutral charcoal page bg #10151B, sidebar/cards #1E2129, body text #C8CFDA, headings white, links #4B83F1. Brand navy is reserved for the hero, primary button and info-callout dark backgrounds.
• Light theme also calibrated to docs.docker.com: page+sidebar+main on #E7EAEF (gray-100), cards on white, headings #1F242D, body copy #3F4750.
• Moby mark — replaced the hand-authored whale (which was missing the eight containers on its back) with the actual docker-mark-ocean-blue.svg from the brand kit, plus a white variant.
• Callouts — redesigned in docs.docker.com style: rounded panel, filled circular icon badge, bg colors that match admonition-note / tip / warning.
• Header — wordmark + Moby mark, left-aligned at the page padding edge so it doesn't drift on wide monitors.
• Sidebar — value tagline at the top, nav links at 16px / weight 400, pure white text in dark mode for higher contrast.
• Right-column TOC — restyled like docs.docker.com:
  • "Edit this page" link (pencil icon, points at GitHub's web editor; URL resolved at build time via <meta name="docs-edit-url"> and {{ page.path }})
  • "Table of contents" heading at 1.05rem weight 500
  • Links at .875rem, gray-600 / gray-100, with a 2px gray-300 left-border + weight 500 on the active entry
  • Built programmatically with createElement + textContent so heading text can never be reinterpreted as HTML (CodeQL hardening — see below)
• Ecosystem footer — three-column footer linking to Docker Desktop, Hub, Scout, Build Cloud, docs.docker.com, the agent catalog, the blog, status, terms and privacy.
• Page chrome — light-theme code blocks honor the theme, footer moved out of <main> (ARIA correctness), skip-link target gets scroll-margin-top so keyboard users land below the header.

Messaging

• Hero leads with the docker-run analogy:

  Docker Agent is to AI agents what docker run is to containers.
  Define an agent in a YAML file, run it with one command, share it through any OCI registry — the same workflow you already use for images.

• Demo GIF moved above the fold.
• 30-second elevator panel — what it is / what it isn't / who it's for / what you get.
• Without / With Docker Agent code comparison: ~30 lines of Python + Anthropic glue vs. 8 lines of YAML + docker agent run.
• "Why" rows — abstract copy replaced with concrete pain → fix pairs.
• Use cases — 4-card row (coding / ops / data / custom workflows) linking to the most relevant follow-up page.
• How it works — SVG flow diagram; uses hard-coded gray-600 (#566581) for text (a neutral mid-grey that reads on both light #E7EAEF and dark #10151B page backgrounds) because currentColor does not inherit through <img src="…svg">.
• Glossary box explaining Agent / Tool / MCP / A2A / TUI / OCI inline.
• Ecosystem tiles — cross-links to Docker Hub (agent catalog), Desktop, Model Runner, Scout.
• Icon set — emoji icons replaced with Lucide-style line icons in tinted Docker-Blue squares.
• STYLE.md — codifies "Docker Agent" (prose) vs docker agent (CLI) naming, voice, glossary.
• Bulk callout edit — across 56 content pages, the leading ℹ️ / 💡 / ⚠️ emoji on <div class="callout-title"> was stripped (the new icon-badge already provides one).

Meta

• <title> and meta description tightened for SEO; og:site_name and Twitter card metadata added.

Review feedback addressed

Reviewer finding	Resolution
🔴 HIGH — how-it-works.svg uses currentColor but is embedded as <img>, making labels invisible on the dark page bg	Fixed: SVG now hard-codes #566581 (gray-600) for text/strokes — readable on both #E7EAEF light and #10151B dark page backgrounds
🟡 MEDIUM — docker-bar.html had nested role="navigation" landmarks	N/A: the corporate top bar (and docker-bar.html) was reverted earlier in the same PR; no nested-landmark issue remains
🔴 CodeQL — DOM text reinterpreted as HTML in js/app.js:78 (heading text interpolated into aside.innerHTML via template literal)	Fixed: buildTOC() rewritten to use document.createElement + textContent, eliminating the XSS class entirely

---

Try it locally

cd docs
bundle install        # needs Ruby ≥ 3.0
bundle exec jekyll serve

Or, with Docker:

docker run --rm \
  -v "$PWD/docs:/srv/jekyll" \
  -v docker-agent-docs-bundle:/usr/local/bundle \
  -w /srv/jekyll \
  -p 4000:4000 \
  ruby:3.3 \
  bash -c "bundle install && bundle exec jekyll serve --host 0.0.0.0 --baseurl ''"

(There is no automated PR-preview deploy — see commit 1's message for why.)

Validation

• ✅ task lint — 0 issues
• ✅ task test — green on CI (build-and-test: SUCCESS); two example-loader tests fail locally because Docker Model Runner isn't enabled on this machine, unrelated to this PR
• ✅ CodeQL — all three jobs (Go / JS-TS / actions) green
• ✅ Built locally with Ruby 3.3 + Jekyll, served clean at http://localhost:4000/

Closes #2792.

[dgageot]

Docs Preview now runs on this PR (the fork-gate from #2792 is gone), but it fails at the deploy step:

Branch refs/pull/2793/merge is not allowed to deploy to github-pages due to environment protection rules.
The deployment was rejected or didn't satisfy other protection rules.

Cause: the github-pages environment on docker/docker-agent has a custom branch policy that only allows deployments from main. The Docs Preview workflow tries to push from a PR branch, which the environment rejects — so the preview can never deploy from any PR, fork or internal.

Options:

1. Adjust the environment so PR-preview branches are allowed (e.g. add a docs/** or gh-readonly-queue/** branch policy, or remove the github-pages environment from the preview job and just push to gh-pages). This is a project-wide config change worth doing separately.
2. Maintainer bypasses the protection on the failed deployment (admins can, per can_admins_bypass: true) just to see the preview for this PR.
3. Build locally with cd docs && bundle install && bundle exec jekyll serve (Ruby ≥ 3.0).

I deliberately didn't change the environment configuration as part of this PR — that's a separate concern from the docs-branding work. Happy to open a tiny follow-up PR that splits the deploy out of the github-pages environment if reviewers want.

[dgageot]

Dropped the Docs Preview workflow in b8ed4eebd since it could never deploy successfully (cross-fork gate + github-pages environment locked to main). The dead red FAILURE check on docs/** PRs is gone now.

If we want PR previews back, the right fix is a separate follow-up that either widens the github-pages environment branch policy or moves the deploy to a different destination (Cloudflare Pages, Netlify, plain gh-pages push without an environment, etc.).

[docker-agent]

Assessment: 🔴 CRITICAL

This PR does excellent work rebranding the docs site to match Docker's design system. However, one critical rendering bug would make the new architecture diagram invisible to most visitors on the default dark theme.

Summary of findings:

• 🔴 HIGH (1): how-it-works.svg uses currentColor for all text labels, but is embedded as <img src="...">. Per the SVG spec, currentColor does not inherit from the host page in this context — it resolves to black, making all labels invisible against the dark navy background.
• 🟡 MEDIUM (1): docker-bar.html creates two nested role="navigation" landmarks (outer <div role="navigation"> wrapping inner <nav>), which confuses screen reader navigation.

[docker-agent]

[HIGH] currentColor in how-it-works.svg resolves to black when embedded via <img> — text labels invisible on dark theme

The SVG's comment says it "uses currentColor where practical so it picks up the surrounding text colour," but this only works for inline SVG (<svg> directly in HTML). When an SVG is loaded as an external image via <img src="...">, it is processed as an independent document in its own rendering context — the host page's CSS color is not inherited. Per the CSS/SVG specs, currentColor in this context resolves to the SVG's initial computed color, which is black (#000000).

All text labels in the diagram use fill="currentColor":

• agent.yaml / your config (lines 24–25)
• Model, LLM call (lines 48–49)
• Tools, fs / shell / MCP (lines 54–55)
• Sub-agents, delegation (lines 60–61)
• repeats until task is done (line 68)
• Stream, to TUI / API (lines 77–78)

The site defaults to a dark navy background (#0D1B2E). Black text on a dark navy background is functionally invisible, making the architecture diagram unreadable for the majority of visitors.

Fix: Replace fill="currentColor" with explicit hex colors that work on the dark background (e.g., fill="#E8ECF2" for the dark theme, or use a <style> block with @media (prefers-color-scheme) queries inside the SVG, or embed the SVG inline in the template).

[docker-agent]

[MEDIUM] Duplicate role="navigation" landmark: outer <div> wraps inner <nav>

The outer <div> carries an explicit role="navigation" with aria-label="Docker corporate links", but it also wraps an inner <nav class="docker-bar-links"> — which has an implicit role="navigation" landmark per the HTML spec. This creates two nested navigation landmarks in the accessibility tree:

1. <div role="navigation" aria-label="Docker corporate links"> → named landmark
2. <nav class="docker-bar-links"> → unnamed navigation landmark (child of Telemetry #1)

Screen reader users navigating by landmarks would encounter both, with the inner one unlabeled, causing confusion. WCAG 2.1 success criterion 1.3.1 (Info and Relationships) is affected.

Fix: Either use <nav aria-label="Docker corporate links"> as the outer element (removing the inner <nav>), or remove role="navigation" from the outer <div>:

<!-- Option A: single <nav> -->
<nav class="docker-bar" aria-label="Docker corporate links">
  <div class="docker-bar-inner">
    <a class="docker-bar-brand" ...>...</a>
    <ul class="docker-bar-links">
      <li><a href="...">Desktop</a></li>
      ...
    </ul>
  </div>
</nav>

[dgageot]

Squashed the 37 incremental commits into two atomic ones, per request:

#	Commit	Change
1	df21b520c	ci: drop the dead Docs Preview workflow
2	c4316845e	docs(site): rebrand to docker.com / docs.docker.com style

Verified the squash is byte-identical to the previous tip:

$ git diff <new-tip>..<old-tip> | wc -l
0

The full review history is preserved in #2792 and on the tag-style ref backup/pre-squash-1778688351 if anyone wants to walk through the individual changes.

[dgageot]

Rebased on origin/main and addressed all review feedback in the squashed docs commit (7aae80c1e):

Finding	Resolution
🔴 HIGH — how-it-works.svg uses currentColor while embedded as <img>, so labels render black on the dark page bg	The SVG now hard-codes #566581 (docs.docker.com's gray-600) for text/strokes — a neutral mid-grey that reads on both #E7EAEF light and #10151B dark page backgrounds
🟡 MEDIUM — docker-bar.html nested role="navigation" landmarks	N/A — the corporate top bar (and docker-bar.html) was already reverted earlier in this PR, so no nested-landmark issue remains in the current state
🔴 CodeQL HIGH — js/app.js:78 interpolated ${h.textContent} into an innerHTML assignment	buildTOC() rewritten to use document.createElement + textContent — eliminates the XSS class entirely. CodeQL: ✅

All checks now pass:

• ✅ ci / build-and-test
• ✅ ci / lint
• ✅ ci / license-check
• ✅ ci / build-image
• ✅ CodeQL / Analyze (go)
• ✅ CodeQL / Analyze (javascript-typescript)
• ✅ CodeQL / Analyze (actions)
• ✅ Local task lint — 0 issues

Local task test shows two pre-existing example-loader failures (dmr.yaml, unload_on_switch.yaml) because Docker Model Runner isn't enabled on this Mac. They pass on CI \u2014 build-and-test: SUCCESS \u2014 and aren't introduced by this PR.