Skip to content

brand: VitePress docs site theme alignment to new dark palette #528

@Axelj00

Description

@Axelj00

Problem

The VitePress docs site at `https://clawterm.github.io/clawterm/docs/\` still ships the default VitePress theme — light/dark auto-switching, generic blue primary color, default sans typography. It does not match the new ClawTerm visual system shipped in #523:

  • Dark scale (`#050607` / `#0B0D0E` / `#111315`)
  • Command Green `#7CFF4F` accent for active state
  • JetBrains Mono everywhere

The landing page at `/clawterm/` was rebuilt in #526 to the new system, but as soon as a user clicks into "Installation" or "Architecture" they hit a docs site that looks like a completely different product.

Current state

`docs/.vitepress/config.ts` defines navigation + sidebar but no `themeConfig` color overrides and no `docs/.vitepress/theme/` directory exists.

```
docs/.vitepress/
├── config.ts ← nav + sidebar only
└── dist/ ← generated, not tracked
```

The deploy workflow `.github/workflows/docs.yml` already builds + deploys via `gh-pages` so any theme changes will land on the next push to `main` that touches `docs/**`.

Proposal

Add a VitePress theme override at `docs/.vitepress/theme/index.ts` that imports the default theme and adds a small `custom.css` overriding the relevant CSS variables:

```css
:root,
.dark {
--vp-c-bg: #050607;
--vp-c-bg-alt: #0B0D0E;
--vp-c-bg-soft: #111315;
--vp-c-bg-elv: #111315;
--vp-c-divider: #22262A;
--vp-c-text-1: rgba(244, 244, 245, 0.9);
--vp-c-text-2: rgba(244, 244, 245, 0.55);
--vp-c-brand-1: #7CFF4F;
--vp-c-brand-2: #8FFF6A;
--vp-c-brand-3: #7CFF4F;
--vp-c-brand-soft: rgba(124, 255, 79, 0.12);
--vp-font-family-base: "JetBrains Mono Variable", "JetBrains Mono", "SFMono-Regular", ui-monospace, monospace;
--vp-font-family-mono: "JetBrains Mono Variable", "JetBrains Mono", "SFMono-Regular", ui-monospace, monospace;
}
```

Force-dark only (light mode shouldn't exist for this brand) — `appearance: 'force-dark'` in `config.ts` will hide the theme toggle in the navbar.

Also: pull the docs-site favicon set from `docs/` (we have the new ones) by referencing them via `head` config in `vitepress`.

Acceptance

  • Visiting any page under `/clawterm/docs/` renders the new dark palette + green accent + JetBrains Mono typography.
  • Theme toggle no longer offered (force-dark).
  • Site favicon matches the new mark.
  • No regressions to search, sidebar nav, or local dev (`npm run docs:dev`).

Out of scope

  • Rewriting individual docs pages — only the chrome / theme changes here.
  • Custom layout components.

Related

Metadata

Metadata

Assignees

No one assigned

    Labels

    designVisual design and UXdocsDocumentationpriority: mediumImportant but not urgent

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions