Skip to content

docs(readme): colour the badges, rebrand the diagram, delete the fabricated hero - #84

Open
harshuljain13 wants to merge 1 commit into
mainfrom
docs/readme-polish
Open

harshuljain13 wants to merge 1 commit into
mainfrom
docs/readme-polish

Conversation

@harshuljain13

Copy link
Copy Markdown
Collaborator

What changed, and why

Three visual problems β€” one of them a correctness problem wearing visual clothes.

The badges were six identical violet pills

All six were #A685EE. Uniform accent is not restraint; it is the accent spent on everything, which is the same as spending it on nothing β€” the row read as one violet smear. The stack badges now carry each tool's own recognisable colour over the shared Ink label that holds the row together, and the violet is kept for the two that are actually ours:

badge colour
PyPI version #A685EE violet β€” ours
Python #3776AB
LangGraph #1C3C3C
MCP #D97757
OpenTelemetry #425CC7
License #A685EE violet β€” ours

labelColor=0D1317 throughout, so the left half of every pill is Ink.

The diagram was a light-mode block in a dark README

The Mermaid architecture diagram used five pastel fills β€” pale amber, mint, green, slate, blue β€” with nothing to do with the brand. Every node is now Panel #141C22 with Fog text, and only the border carries meaning: the accent on the kernel (which is what the diagram argues for), the code teal on the adapters, dim on what we consume and never reimplement.

Mermaid's own defaults needed fixing too, via an init block: edge labels were rendering as light chips and the arrows were nearly invisible on a dark canvas.

The hero image advertised four things we cannot do

This is the one that matters. branding/hero/image.png sat directly under The problem β€” the first picture a visitor sees β€” and showed Google ADK, OpenAI SDK and CrewAI as engines, with Memory and Guardrails as components. The same README states a few sections later that none of those are built. It also carried the pre-rebuild wordmark, with a glow.

That is precisely the over-claiming agentship verify exists to prevent, and the same defect #63 raised against the website β€” except in the framework's own README. Deleted, and nothing replaces it: the Mermaid diagram immediately below already does that job and is held to the same facts as the prose.

branding/Architecture.png went with it β€” unreferenced by anything, a third wordmark variant, and depicting an ADK sidecar, a vector-store memory layer, eval datasets and LLM-as-judge.

How it was verified

By rendering, not by reading the diff.

  • Every badge URL fetched. All six return an SVG; five have the logo actually embedded (<image present), so no logo slug silently dropped its icon β€” modelcontextprotocol and pypi both resolve. The sixth requests no logo.
  • The diagram rendered with mmdc on both GitHub canvas colours, #0d1117 and #ffffff. That is how two defects were caught that reading the source would not have shown: the cluster titles were colliding with the nodes inside them (long labels wrap and overlap β€” fixed by shortening them), and the edge labels were light chips. Both themes now read correctly; the diagram is a dark card on white in light mode, which is the kit's dark-first intent.
  • No dangling image references β€” the banner resolves on disk, and nothing in the tree still points at either deleted PNG.

Gate, on exit code: make test 0 (950 passed, 26 skipped, 3 xfailed), ruff check . 0, ruff format --check . 0, mkdocs build --strict 0, agentship verify --agents-dir examples 0.

Checklist

  • make test passes locally.
  • ruff check and ruff format --check are clean.
  • agentship verify still exits 0, with no new over-claims.
  • If an engine capability was declared or changed, its conformance cell proves it. β€” none changed.
  • Public surface changes are reflected in docs/capabilities/. β€” none; this is the README and two deleted assets.
  • docs/CHANGELOG.md has an entry under ## [Unreleased].
  • A non-obvious design decision has an ADR in docs/decisions/. β€” none; the badge and palette reasoning is in comments beside the markup.
  • Version numbers untouched.

Anything deliberately left undone

  • I did not restructure "What you get". The brand kit's README template compresses it into a two-column table, and I considered matching that β€” but this repo's version carries the span tree and the Studio progress output as literal code blocks, which are the most concrete things on the page. A table would read tidier and say less.
  • No replacement hero illustration. One could be drawn from tokens/, but a second architecture picture has to be kept in step with the Mermaid one, and the drift between those two is exactly what produced the deleted file. Noted in branding/README.md for whoever wants one later.
  • The adk repo topic and the About text still say ADK and MIT. Settings-only, so I cannot touch them; flagged previously and still outstanding. The About text contradicts GitHub's own Apache-2.0 licence detection on the same page.
  • Badge colours are each vendor's, not verified against a brand guideline per vendor. They are the widely used values (and the shields logo slugs are official), but if any of those projects publishes an exact hex that differs, these should follow it.

…icated hero

Three visual problems, one of them a correctness problem wearing visual clothes.

The six badges were all #A685EE. Uniform accent is not restraint, it is the
accent spent on everything, which is the same as spending it on nothing β€” the
row read as one violet smear. The stack badges now carry each tool's own
recognisable colour (Python blue, LangChain, MCP, OTel) over the shared Ink
label that holds the row together, and the violet is kept for the two that are
actually ours: the version and the licence.

The architecture diagram was five pastel fills β€” amber, mint, green, slate,
blue β€” so a dark-branded README had a bright light-mode block dropped in the
middle of it. Every node is now Panel with Fog text and only the border carries
meaning: the accent on the kernel, which is what the diagram argues for, the
code teal on the adapters, dim on what we consume. Mermaid's defaults needed an
init block too: edge labels were rendering as light chips and the arrows were
nearly invisible against a dark canvas.

And `branding/hero/image.png`, directly under "The problem", showed Google ADK,
OpenAI SDK and CrewAI as engines with Memory and Guardrails as components. The
same README says a few sections later that none of those are built. It is the
exact over-claiming the conformance grid exists to prevent, in the first picture
a visitor sees, carrying the pre-rebuild wordmark with a glow. Deleted, with no
replacement needed: the Mermaid diagram immediately below already does that job
and is held to the same facts as the prose. `branding/Architecture.png` went
with it β€” unreferenced, a third wordmark, and an ADK sidecar, vector-store
memory layer, eval datasets and LLM-as-judge.

Verified by rendering rather than reading. Every badge URL fetched: all six
return SVG, five with the logo actually embedded, so no slug silently dropped
its icon. The diagram was rendered with mmdc on both GitHub canvas colours
(#0d1117 and #ffffff) β€” which is how the cluster titles turned out to be
colliding with the nodes inside them, fixed by shortening them, and how the
light-chip edge labels were caught.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant