Skip to content

chore(branding): apply the brand kit to the repo, docs site and Studio - #80

Merged
harshuljain13 merged 1 commit into
mainfrom
chore/apply-brand-kit
Oct 15, 2026
Merged

harshuljain13 merged 1 commit into
mainfrom
chore/apply-brand-kit

Conversation

@harshuljain13

Copy link
Copy Markdown
Collaborator

What changed, and why

The project had two visual identities and nothing said which was current. branding/ carried a logo set from before the rebuild, the README pointed at branding/banners/github-readme-banner@3x.png, the docs site was Material's stock teal with its fonts fetched from Google on every page load, and Studio's tab icon was a placeholder — a blue circle with a white triangle in it. Anyone reaching for "the logo" had to guess which directory held the real one.

The AgentShip brand kit is now vendored under branding/ (logo, banner, fonts, tokens), and the superseded logos/, icons/, favicons/ and banners/ directories are deleted, so there is no second identity left to pick up by mistake. branding/README.md records which file belongs where, the clearspace and accent rules, and the licensing.

The docs site serves the mark, the favicon, the brand palette and self-hosted Bricolage Grotesque / Instrument Sans / JetBrains Mono, with font: false so Material does not also pull its own. The kit ships a dark scheme only; this site deliberately keeps a reader-preference toggle, so I filled in the light half from the kit's documented light tokens rather than dropping the toggle. In light mode the accent becomes #6A47C2 — #A685EE measures 2.9:1 as text on Paper, under AA.

Studio's palette maps onto the kit's six greys in order (Ink, Panel, Harbor, Line, Line-strong, Outline) and it draws the real mark. It stays a single no-build file, so it carries the token values inline rather than importing tokens/tokens.css; there is a comment saying so, because that duplication is deliberate and would otherwise look like drift.

/docs and /redoc are rebuilt by hand for one reason: both hard-code FastAPI's own favicon, so a tab of AgentShip API documentation was branded as somebody else's project. Same URLs, same Swagger and ReDoc assets, served against a new public GET /favicon.svg.

Two documentation claims were wrong, and the branding pass is what surfaced them:

  • The README listed voice under "not built yet" in one paragraph and as shipped in another. Voice has been released since 0.0.3.
  • Its Status section, and the top of docs/RELEASING.md, told readers to pin agentship-sdk==0.0.2 as "the latest on PyPI" and said the next release would be 0.0.3. Anyone following either would have pinned two releases behind.

The fonts are not ours. They are redistributed under the SIL OFL 1.1 with each licence file kept beside them, as the OFL requires, and the README now notes that Apache 2.0 grants no rights in the AgentShip name or logo (section 6).

How it was verified

The gate, run bare and checked on exit code rather than output:

make test 0 — 950 passed, 26 skipped, 3 xfailed
ruff check . 0
ruff format --check . 0 — 333 files
mkdocs build --strict 0
agentship verify --agents-dir examples 0 — grid 11/11, 0 over-claims

Beyond the suite, what I actually drove:

  • The service, through a TestClient. /docs, /redoc, /favicon.svg, /studio, /openapi.json and /healthz all answer 200 (and / still 307s). /favicon.svg returns image/svg+xml with Cache-Control: public, max-age=604800, and its body contains A685EE — it is the brand mark, not a stale file. Both doc pages contain /favicon.svg in their markup. /studio and /favicon.svg are both absent from the OpenAPI schema, which is the property test_studio.py already guards for Studio.
  • The built docs HTML, not the config. site/*.html references assets/agentship-mark-on-dark.svg, assets/favicon.svg, stylesheets/agentship.css and assets/fonts/fonts.css, and grep -c "fonts.gstatic\|fonts.googleapis" returns 0 — the Google Fonts request is genuinely gone, not just overridden.
  • Contrast, computed rather than eyeballed, for the values the kit does not define: Studio's third text step is 6.2:1 on Ink dark and 4.9:1 on Paper light, and the accent carries 6.3:1 against Ink and 5.4:1 against Fog.
  • Dangling references: grep across the tree for branding/logos, branding/icons, branding/favicons and branding/banners returns nothing, and both image paths the README uses resolve on disk.

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. — no capability changed.
  • Public surface changes are reflected in docs/capabilities/. — the new route is GET /favicon.svg, browser chrome rather than contract, and deliberately out of the schema. See below.
  • docs/CHANGELOG.md has an entry under ## [Unreleased]. — the section did not exist yet, since 0.0.4 was just cut; this PR adds it.
  • A non-obvious design decision has an ADR in docs/decisions/. — see below.
  • Version numbers untouched.

Anything deliberately left undone

  • No ADR, and no capability page. Nothing here changes a capability or a seam. The two decisions a reader might question — keeping the docs light/dark toggle when the kit is dark-only, and inlining token values into Studio instead of importing them — are both commented where they live. Say the word if you would rather one of them were an ADR.
  • GET /favicon.svg is public and out of the schema, matching /studio's rationale: it is chrome, not contract, and the bytes are identical for every caller, so it carries no tenant data. It is added to _DEFAULT_PUBLIC_PATHS; a favicon that 401s renders as a broken icon on /docs and /studio alike. No test asserts the route yet — I drove it by hand, as above.
  • Two things only a human can do. The GitHub social preview has to be uploaded through Settings → Social preview (branding/banner/github-social-preview.png); it cannot be set from code. And the kit flagged that the repo About text may still say MIT while LICENSE and every pyproject.toml say Apache-2.0 — worth checking while you are in Settings.
  • docs/RELEASING.md still uses 0.0.3 in its worked examples (git tag v0.0.3, git checkout -b hotfix/0.0.4 v0.0.3), which reads oddly now that the same file correctly says the next release is 0.0.5. I fixed the factual status claim but did not rewrite a release procedure's examples as part of a branding PR — happy to do it separately.
  • Studio ships no font files. It names the brand faces and falls back to system-ui, exactly as it already did for Inter, rather than adding ~200 KB of woff2 to the agentship-service wheel. That was a deliberate call; the alternative is a one-line change if you want it.

@harshuljain13
harshuljain13 requested a review from Parv17k October 14, 2026 11:28
@harshuljain13 harshuljain13 self-assigned this Oct 14, 2026
@harshuljain13 harshuljain13 added the documentation Improvements or additions to documentation label Oct 14, 2026
@harshuljain13 harshuljain13 added this to the 0.1.0 milestone Oct 14, 2026
The project had two visual identities and nothing said which was current.
`branding/` carried a logo set from before the rebuild, the README pointed at
`branding/banners/github-readme-banner@3x.png`, the docs site was Material's
stock teal with its fonts fetched from Google on every page load, and Studio's
tab icon was a placeholder: a blue circle with a white triangle in it. Anyone
reaching for "the logo" had to guess.

The AgentShip brand kit is now vendored under `branding/` — logo, banner, fonts
and tokens — and the superseded `logos/`, `icons/`, `favicons/` and `banners/`
directories are deleted, so there is no second identity left to pick up by
mistake. `branding/README.md` records which file belongs where, the clearspace
and accent rules, and the licensing.

The docs site serves the mark, the favicon, the brand palette and self-hosted
Bricolage Grotesque / Instrument Sans / JetBrains Mono, with `font: false` so
Material does not also pull its own — the built HTML now makes no request to
Google. The kit ships a dark scheme only; this site deliberately keeps a
reader-preference toggle, so the light half is filled in from the kit's
documented light tokens, where the accent becomes `#6A47C2` because `#A685EE`
does not carry enough contrast as text on a light ground.

Studio's palette maps onto the kit's six greys in order and it draws the real
mark rather than the placeholder. It stays a single no-build file, so it carries
the token values inline instead of importing `tokens/tokens.css`.

`/docs` and `/redoc` are rebuilt by hand for one reason: both hard-code
FastAPI's own favicon, so a tab of AgentShip API documentation was branded as
somebody else's project. Same URLs, same Swagger and ReDoc assets, served
against a new public `GET /favicon.svg`.

Two documentation claims were wrong and are fixed here because the branding pass
is what surfaced them. The README listed voice under "not built yet" in one
paragraph and as shipped in another — voice has been released since `0.0.3`. Its
Status section, and the top of `docs/RELEASING.md`, told readers to pin
`agentship-sdk==0.0.2` as "the latest on PyPI" and said the next release would
be `0.0.3`; anyone following either would have pinned two releases behind.

The fonts are not ours. They are redistributed under the SIL Open Font License
1.1 with each licence file kept beside them, as the OFL requires, and the README
now notes that Apache 2.0 grants no rights in the AgentShip name or logo.
@harshuljain13
harshuljain13 merged commit e0456a9 into main Oct 15, 2026
4 checks passed
@harshuljain13 harshuljain13 added type:chore Build, CI, dependencies, release plumbing area:service REST, SSE, WebSocket, auth, Studio and removed documentation Improvements or additions to documentation labels Oct 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:service REST, SSE, WebSocket, auth, Studio type:chore Build, CI, dependencies, release plumbing

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant