Skip to content

Commit 6f4a681

Browse files
vishrclaude
vishr
and
claude
committed
docs(spec): design for from-scratch Astro docs rebuild (Terminal direction)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent e41374b commit 6f4a681

2 files changed

Lines changed: 139 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,4 @@ vendor
44
.idea
55
.hugo_build.lock
66

7+
.superpowers/

‎docs/superpowers/specs/2026-06-14-echo-docs-astro-rebuild-design.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# Echo Docs — from-scratch rebuild (Astro, "Terminal" design)
2+
3+
**Date:** 2026-06-14
4+
**Status:** Design — awaiting review
5+
**Repo:** `labstack/echox` (the docs site lives in `website/`)
6+
7+
## 1. Goal
8+
9+
Replace the current Docusaurus docs site with a custom-built, professional docs
10+
platform that matches the quality and feel of `docs.openclaw.ai`, branded for Echo.
11+
The look kept reading as "default/amateur" because it used generic system-sans on a
12+
cool palette; the new design commits to a **monospace, terminal-precise** aesthetic.
13+
14+
## 2. Locked decisions
15+
16+
| Decision | Choice | Why |
17+
|---|---|---|
18+
| Build approach | **Astro** (custom, no docs preset) | Total design control like a hand-build, but routing / MDX / i18n / fast builds / image+font optimization come free; stays free & self-hosted. |
19+
| Design direction | **"Terminal"** | Chosen from 3 directions. Closest to OpenClaw, most "Go developer". |
20+
| Body font | **Fragment Mono** (Google) | Exact font OpenClaw declares; the defining trait. |
21+
| Heading font | **DM Sans** 700/800 | Heavy sans against mono body = OpenClaw's contrast. |
22+
| Palette | Warm near-black `#0d0b0b`, warm grays, **Echo cyan `#00AFD1`→`#4AE1FF`** | Cyan pulled from the Echo logo; warm dark from OpenClaw. |
23+
| Theme | **Dark-first**, light theme also shipped | Matches the chosen aesthetic; light is a polished secondary. |
24+
| Content | **Rewritten fresh** | User chose a clean-slate content pass (new IA + new prose), not a Docusaurus auto-port. |
25+
| Coverage goal | **Full** (all guide/cookbook/middleware/API topics) | Sequenced in phases (§8). |
26+
27+
## 3. Must-have features
28+
29+
1. **Versioning** — separate docs trees for **v4** and **v5** with a version switcher.
30+
2. **i18n** — locale routing + language switcher (en first; zh-Hans/ja/es/fr scaffolded).
31+
3. **Full-text search** — **Pagefind** (static, free, self-hosted; indexes the built site).
32+
4. **Ask Echo (AI)** — ⌘K command palette with streamed answers + cited sources. UI ships
33+
now; wired to a provider (**kapa.ai** OSS tier or self-hosted Inkeep) via a single
34+
integration point — answers are stubbed until a key is supplied.
35+
36+
## 4. Architecture (Astro)
37+
38+
```
39+
website/ # Astro project (replaces Docusaurus)
40+
astro.config.mjs # integrations: mdx, sitemap, pagefind; i18n routing
41+
src/
42+
content/
43+
config.ts # content collections schema (docs)
44+
docs/<version>/<locale>/... # MDX content, e.g. docs/v5/en/core/routing.mdx
45+
components/
46+
Nav.astro Sidebar.astro Toc.astro DocActions.astro
47+
CodeBlock.astro Callout.astro Card.astro VersionSwitcher.astro
48+
LocaleSwitcher.astro AskEcho.tsx Search.astro Hero.astro
49+
layouts/
50+
Base.astro # <head>, fonts, theme bootstrap, nav, footer
51+
DocLayout.astro # sidebar + content + toc + doc actions
52+
pages/
53+
index.astro # homepage (hero + features)
54+
[...slug].astro # docs routes from the content collection
55+
styles/
56+
tokens.css # design tokens (the design system)
57+
global.css
58+
public/ # logo, favicon, og image
59+
```
60+
61+
**Design-for-isolation:** each component has one purpose and a clear prop interface —
62+
`Sidebar` (nav tree in → highlighted list out), `Toc` (headings in → list out),
63+
`AskEcho` (self-contained island), `CodeBlock` (lang + code in → highlighted out). The
64+
content collection is the single source of truth; layouts compose components; pages are
65+
thin. Versioning and i18n are expressed in the content path (`docs/<version>/<locale>/…`)
66+
and resolved by `[...slug].astro`, so no component needs to know about them internally.
67+
68+
## 5. Design system (`tokens.css`)
69+
70+
- **Type:** `--font-body: "Fragment Mono", ui-monospace, …`; `--font-head: "DM Sans", …`;
71+
base 13.5–14px, line-height 1.7; headings 700/800, tracking −0.02em.
72+
- **Color (dark):** bg `#0d0b0b`, surface `#151210`, line `#221e1c`/`#2d2724`,
73+
text `#aaa19d`, heading `#f4f1ef`, muted `#817a76`, accent `#00afd1`/`#4ae1ff`,
74+
accent-soft `rgba(0,175,209,.12)`.
75+
- **Color (light):** warm paper `#faf8f7`, ink `#1a1614`, accent darkened cyan for contrast.
76+
- **Radius** 9–13px; hairline 1px borders; single soft cyan glow top-right; faint grain.
77+
- **Code:** `#0a0908` bg, cyan keywords, warm strings, muted comments (Shiki theme tuned to match).
78+
79+
## 6. Information architecture
80+
81+
- **Top nav:** logo + `v5` version pill, primary links (Guide, Cookbook, Middleware, API),
82+
prominent **Search ⌘K**, locale switcher, GitHub.
83+
- **Sidebar:** sectioned (Getting Started / Core / Guides / …), mono uppercase captions,
84+
cyan active pill with left bar.
85+
- **Doc page:** breadcrumb → H1 → **DocActions** (Ask Echo / Copy / ChatGPT / Claude) →
86+
content (MDX) → right-hand **On this page** TOC. Floating **Ask Echo ⌘K** launcher.
87+
- **Homepage:** split hero (headline + CTAs + `go get` line beside a code terminal window),
88+
stat strip, "Why Echo" feature grid, footer. Hero = **split-with-code** variant; feature
89+
icons = **Phosphor** (consistency). (Both adjustable.)
90+
91+
## 7. Feature design detail
92+
93+
- **Versioning:** content keyed by version dir; default version = latest (v5). Version
94+
switcher rewrites the path to the same page in the other version (fallback to that
95+
version's index if the page doesn't exist). v4 is LTS until 2026-12-31.
96+
- **i18n:** Astro i18n routing; locale dir under each version; `LocaleSwitcher` swaps the
97+
locale segment; untranslated pages fall back to `en`.
98+
- **Search:** Pagefind runs as a post-build step over `dist/`; `Search.astro` mounts the
99+
Pagefind UI behind the ⌘K shortcut (separate from Ask Echo, or unified — see open Qs).
100+
- **Ask Echo:** `AskEcho.tsx` island; ⌘K + floating launcher; streamed answer + sources.
101+
Integration point: `askProvider(query) -> stream` — swap the stub for kapa.ai/Inkeep
102+
with one function + an API key. Answers honor the active locale.
103+
104+
## 8. Implementation phasing (within the full-coverage goal)
105+
106+
- **Phase 1 — Platform + design system + slice.** Astro scaffold, `tokens.css`, Base/Doc
107+
layouts, Nav/Sidebar/Toc/DocActions/CodeBlock/Callout/Card, homepage, and a
108+
representative content slice (Quickstart, Routing w/ code, one nested page). Dark+light.
109+
*This is the first implementation plan.*
110+
- **Phase 2 — Content.** Author the full docs set fresh (Guide, Core, Cookbook,
111+
Middleware, API) as MDX in the collection.
112+
- **Phase 3 — Features.** Versioning (v4/v5), i18n locales, Pagefind search, Ask Echo
113+
provider wiring, deploy pipeline (GitHub/Cloudflare Pages), redirects from old URLs.
114+
115+
## 9. Out of scope (now)
116+
117+
- Live AI backend account/keys (UI + integration point only).
118+
- Full translations (locale scaffolding only; en authored).
119+
- Marketing pages beyond the homepage.
120+
121+
## 10. Risks / notes
122+
123+
- **Content rewrite is the largest cost** — it's a writing effort independent of the
124+
platform; Phase 2 may itself need decomposition by section.
125+
- Old URL structure must be preserved via redirects (Docusaurus had `/guide`, `/cookbook`,
126+
`/middleware` aliases) to avoid breaking inbound links and SEO.
127+
- `onBrokenLinks`-style checking must be re-established in the Astro build.
128+
129+
## 11. Open questions (with my recommended default)
130+
131+
1. Search & Ask Echo — **recommend: one ⌘K** with tabs (Search | Ask Echo); single,
132+
familiar entry point. Alt: two separate launchers.
133+
2. Versioning at launch — **recommend: v5-only first**, add v4 in Phase 3 (don't block the
134+
rebuild on porting v4 content). Alt: both from day one.
135+
3. Deploy target — **recommend: Cloudflare Pages** (fast, Pagefind-friendly) with redirects
136+
from the old paths. Alt: stay on GitHub Pages.
137+
138+
Defaults above are assumed unless you say otherwise.

0 commit comments

Comments
 (0)