pyRPCPRs #137 and #138 rebuilt the website’s visual system: new brand assets, a redesigned landing page, unified light/dark theming, and, the part engineers actually notice , one syntax palette shared by every code block on the site. This is a retrospective on why a docs site deserved that much attention.
The problem: three code renderers, three palettes
The site renders Python and TypeScript in three places, marketing page, docs content, interactive playground, and each had accumulated its own highlighting setup. The same @rpc.query decorator could be green in docs and amber in the playground. For a product whose entire pitch is one source of truth, that inconsistency was a contradiction in the first five seconds.
The fix is boring and correct: shared Shiki theme definitions consumed by all three surfaces, with paired light/dark token mappings so switching themes never changes semantics, only luminance.
Theming as tokens, not pages
Alongside the palette work, the app migrated to fumadocs 16.12’s token names and a better-auth-style light/dark system: semantic variables (--fd-background, --fd-muted-foreground and friends) instead of per-component hex codes. Two consequences:
- New pages are correct by default. A blog post written today picks up both themes without a single dark-mode media query.
- The demo/playground matched for free. Editor chrome now uses the same tokens; the sandbox stopped looking like an embedded third-party widget.
Landing page: subtraction
The redesign removed more than it added, wave backgrounds, decorative gradients, redundant hero copy. What stayed: the wordmark, one honest sentence about what pyRPC does, the install command, and the demo GIF. Developer tools earn trust by being legible, not by being decorated.
The meta-lesson
Docs sites rot when they are treated as content plus CSS. Treating them as a product with its own design system, tokens, themes, shared syntax definitions, means every future page inherits quality instead of re-deciding it. The site should feel like it was generated from the same discipline as the library, because it was.