Version: 1.7 Date: 2026-03-13 Status: Phase 1 Implemented Author: Sephyi + Claude Opus 4.6
Revision history
| Version | Date | Summary |
|---|---|---|
| 1.7 | 2026-03-13 | Nav scroll-aware transparency (FR-025), proper 404 pre-rendering (DR-002), JetBrains Mono preload hint (PR-004) |
| 1.6 | 2026-03-13 | Mobile menu island (FR-025), TOC scroll-spy highlighting (FR-015), search a11y keyboard nav (FR-013), skip-to-content + CSP + semantic landmarks (UX-001/SR-002), robots.txt + sitemap.xml + canonical URLs (DR-002), architecture tree update |
| 1.5 | 2026-03-13 | Fix nested <pre> in docs code blocks (build.rs strips syntect wrapper), unified code block styling (#2b303b background), View Transitions API for cross-document navigation, link prefetching on hover, redesigned sticky doc sidebar, copy-to-clipboard buttons on docs code blocks via code-block-wrapper in build.rs, confirm ScrollObserver WASM island fully replaced by inline script (Claude) |
| 1.4 | 2026-03-13 | Replace ScrollObserver island with inline script in app.rs shell (FR-023 rewrite), copy buttons on landing page install section (FR-006/FR-014), remove nonexistent asset links from HTML shell, architecture file tree update |
| 1.3 | 2026-03-13 | Tailwind v4 CSS-first migration, ScrollObserver island (FR-023 complete), CSS hash resolution, architecture updates |
| 1.2 | 2026-03-13 | Fix stale wget reference in FR-030 (now Rust prerender binary), document bin-target requirement in FR-031, add CLAUDE.md |
| 1.1 | 2026-03-13 | Phase 1 implemented — all FRs built, Leptos 0.8 (was 0.7+), cross-platform Rust prerender binary, web-sys non-optional for island compatibility |
| 1.0 | 2026-03-13 | Initial PRD — landing page, documentation wiki, Leptos architecture, bee-themed design system, GitHub Pages deployment |
"The website that makes you want to try the CLI."
CommitBee Web is the official website for CommitBee, serving as both a cinematic landing experience and the canonical documentation wiki. Built entirely in Rust with Leptos, it demonstrates the same engineering philosophy as the CLI itself: semantic understanding, correctness, and craftsmanship.
The site tells the story of how CommitBee understands code through scroll-driven visual storytelling, then provides deep, searchable documentation for developers who are ready to dive in. The warm, organic bee-themed design creates a unique identity in the developer tools space.
- Cinematic first — The landing page is a visual experience, not a wall of text
- Content as code — Documentation lives as markdown in the repo, rendered at build time
- Rust all the way — Frontend, backend, build tooling — all Rust via Leptos
- Zero runtime cost — Pre-rendered static HTML with surgical WASM hydration for interactive islands only
- Accessible by default — Dark/light mode, reduced motion, semantic HTML, keyboard navigation
| Category | Examples | CommitBee Web Advantage |
|---|---|---|
| CLI tool docs sites | mdBook, Docusaurus, VitePress | Full-stack Rust, cinematic landing, not just docs |
| Dev tool landing pages | Linear, Vercel, Stripe | Warm bee identity vs. generic tech aesthetic |
| Rust WASM sites | Leptos examples, Yew demos | Production-quality design, not a framework demo |
- Scroll-driven pipeline walkthrough — No competing CLI tool visually demonstrates its internals
- Bee-themed design system — Distinctive warm amber palette, hexagonal motifs, immediately recognizable
- Full-stack Rust — Landing page, docs wiki, build pipeline — all one language
- Docs from markdown — Single source of truth between repo and website, zero content drift
| Component | Technology | Purpose |
|---|---|---|
| Framework | Leptos 0.8 (islands) | SSR with surgical WASM hydration |
| Server | Axum | Build-time HTML rendering (not deployed) |
| Build tool | cargo-leptos | Parallel server/client compilation |
| Styling | Tailwind CSS v4 | CSS-first config (@theme tokens, no JS config) with dark mode, @view-transition for cross-document navigation |
| Markdown | pulldown-cmark | Build-time markdown to HTML |
| Syntax highlighting | syntect | Rust-native, bee-themed color scheme |
| Task runner | mise | Dev/build/content task orchestration |
| CI/CD | GitHub Actions | Build, pre-render, deploy |
| Hosting | GitHub Pages | Static HTML + WASM + CSS |
The site uses Leptos islands architecture with static pre-rendering:
build.rsprocesses all markdown content into static Rust data at compile timecargo-leptoscompiles the Axum server (native) and client WASM (islands only) in parallel- In CI, the server runs locally and all routes are pre-rendered to static HTML via the Rust
prerenderbinary - The static HTML + WASM bundle + CSS deploys to GitHub Pages
- Islands hydrate client-side only for interactive elements
The Axum server exists solely as a build-time rendering tool. In production, everything is static files served from GitHub Pages.
commitbee-web/
├── src/
│ ├── main.rs # Axum server entry
│ ├── bin/
│ │ └── prerender.rs # Cross-platform static HTML pre-renderer
│ ├── lib.rs # Leptos app root + hydrate entry
│ ├── app.rs # Router + HTML shell (includes inline scroll-reveal + link prefetch scripts)
│ ├── pages/
│ │ ├── landing.rs # Hero + all landing sections
│ │ ├── docs.rs # Doc page renderer
│ │ └── not_found.rs # 404 page
│ ├── components/
│ │ ├── nav.rs # Sticky navigation header
│ │ ├── footer.rs # Site footer
│ │ ├── theme_toggle.rs # Dark/light mode island
│ │ ├── pipeline_demo.rs # Animated pipeline walkthrough island
│ │ ├── code_block.rs # Syntax-highlighted code with copy island
│ │ ├── doc_search.rs # Fuzzy search island (Cmd+K, arrow nav)
│ │ ├── doc_sidebar.rs # Docs sidebar navigation
│ │ ├── doc_toc.rs # Right-side table of contents
│ │ ├── mobile_menu.rs # Slide-out mobile navigation island
│ │ ├── scroll_reveal.rs # Scroll animation wrapper (SSR)
│ │ └── toc_highlighter.rs # Scroll-spy TOC highlighting island
│ └── content/
│ └── loader.rs # Build-time markdown loader + frontmatter
├── content/
│ └── docs/ # Markdown source files with YAML frontmatter
├── style/
│ ├── tailwind.css # Tailwind v4 CSS-first config (@theme tokens, @source, @custom-variant, @view-transition)
│ └── animations.css # Scroll-reveal + pipeline animation keyframes
├── public/
│ ├── fonts/ # Inter + JetBrains Mono (self-hosted)
│ └── images/ # OG images, favicon, bee assets
├── build.rs # Markdown processing pipeline
├── mise.toml # Task orchestration
├── Cargo.toml
└── .github/
└── workflows/
└── deploy.yml # Build + pre-render + deploy
build.rs cargo-leptos
| |
+- Walk content/docs/*.md +- Compile server (native)
+- Parse YAML frontmatter +- Compile client WASM (islands only)
+- Markdown -> HTML (pulldown-cmark) +- Process Tailwind CSS
+- Syntax highlight (syntect) +- wasm-opt optimization
+- Extract heading tree for TOC
+- Build search index
+- Generate $OUT_DIR/content_generated.rs
CI pre-render (cross-platform Rust binary, zero shell deps):
+- Build release binary + WASM bundle
+- Start Axum server locally (background)
+- Pre-render all known routes via HTTP/1.0 GET -> static HTML
+- Add 404.html for GitHub Pages SPA fallback
+- Deploy dist/ to GitHub Pages
| Crate | Purpose |
|---|---|
leptos 0.8 (features: islands) |
Framework with islands architecture |
leptos_meta |
<title>, <meta>, OG tags per page |
leptos_router |
Client-side routing |
leptos_axum |
Axum integration for SSR |
axum |
HTTP server (build-time only) |
tokio |
Async runtime |
pulldown-cmark |
Markdown to HTML |
syntect |
Syntax highlighting |
serde + serde_yaml |
Frontmatter parsing |
tower-http |
Static file serving, compression |
wasm-bindgen + web-sys |
Browser API access (localStorage, Clipboard) — non-optional because #[island] macro does not cfg-gate the body. IntersectionObserver is now handled by inline script, not WASM. |
Fullscreen hero with tagline "The commit message generator that actually understands your code." Animated honeycomb motif in background (CSS clip-path or SVG pattern, gentle pulse animation). Terminal mockup showing commitbee producing a commit message. Two CTAs: "Get Started" (scrolls to install) and "See How It Works" (scrolls to pipeline). Terminal fades and scales down on scroll.
Split view layout: left side shows raw git diff dump, right side shows a vague commit message from a typical tool. Headline: "Every other tool just pipes your diff to an LLM and hopes for the best." Scroll triggers visual transformation where raw diff morphs into structured semantic context.
Pre-baked animated walkthrough of commitbee's 7-stage pipeline using a real example diff. Each stage appears as a card that slides in on scroll:
- Git Service — staged files appear
- Tree-sitter — symbols highlighted in code
- Splitter — files visually group into clusters
- Context Builder — evidence flags appear, budget meter fills
- LLM — streaming text animation of commit message generation
- Validator — checkmarks appear next to each of the 7 rules
- Sanitizer — final clean commit message appears
Implemented as an #[island] component with play/pause and step-through controls. All animation data is pre-baked, not computed live.
Three feature cards with hexagonal accent borders:
- Tree-sitter Semantic Analysis — "It reads your code, not just your diffs"
- Commit Splitting — "It detects mixed concerns and splits them"
- 25-Pattern Secret Scanning — "It catches leaked credentials before they reach any LLM"
Each card has a mini-animation showing the feature in action.
Stylized comparison of commitbee vs. the field on key features. Layered card design (not a flat table). CommitBee column accented with amber glow. Features compared: tree-sitter AST, commit splitting, secret scanning, token budget, streaming, local LLM, cloud providers, git hooks.
Terminal-style code blocks with copy-to-clipboard buttons. Shows cargo install commitbee, brew install sephyi/tap/commitbee, and the zero-config first-run experience. Animated terminal showing the first-run flow. Copy buttons implemented on all install section terminal blocks using .copy-btn pattern with data-code attributes, activated by a CodeBlockActivator island on the landing page.
Visual transition where landing page aesthetic gradually shifts into documentation layout. Cards linking to key doc sections: Getting Started, Configuration, Providers, Architecture. Smooth visual transition into docs navigation.
GitHub repo, crates.io, license links. "Made with Rust" badge. Subtle honeycomb pattern background.
Renders markdown content as HTML with sidebar navigation and table of contents. Three-column layout on desktop: left sidebar (doc tree), main content (~75ch max-width), right sidebar (page TOC). Responsive: sidebar becomes slide-out drawer on mobile, TOC collapses.
Markdown files in content/docs/ with YAML frontmatter (title, order, section, description). Processed at build time by build.rs:
- Walk directory, parse frontmatter
- Convert markdown to HTML via
pulldown-cmark - Apply syntax highlighting via
syntect—build.rsstrips syntect's outer<pre>wrapper to avoid nested<pre>tags, wrapping the result in a unified<div class="code-block-wrapper">with a consistent dark background (#2b303b) shared between the header bar and code body - Wrap each code block in a
code-block-wrapperdiv that includes a language label header and a copy-to-clipboard button (activated client-side via inline script) - Extract heading tree for TOC generation
- Build search index (title + headings + first 200 words per page)
- Generate Rust module with doc tree as
conststatics in$OUT_DIR
Left sidebar with collapsible section tree. Current page highlighted with amber accent. Sticky positioning on desktop (sticky top-20) with thin custom scrollbar and refined typography hierarchy (section headers uppercase, page links with hover/active states). Slide-out drawer on mobile. Prev/next links at bottom of each page based on ordering. Breadcrumbs: Docs > Section > Page.
Section structure:
| Section | Pages |
|---|---|
| Basics | Getting Started, How It Works |
| Usage | Commands & Flags, Configuration, LLM Providers, Commit Splitting |
| Internals | Validation Pipeline, Security & Safety, Supported Languages |
| Integration | Git Hooks, Troubleshooting |
| Reference | Architecture |
Client-side fuzzy search over pre-built search index. Cmd+K / Ctrl+K keyboard shortcut to open search overlay. Searches titles, headings, and content excerpts. Results ranked by relevance. Implemented as an #[island] component. Search index emitted as a separate JSON file by build.rs, loaded lazily when the search modal opens (not baked into WASM to keep bundle small). Fuzzy matching via sublime_fuzzy or equivalent compiled into the search island. Keyboard accessibility: ArrowUp/ArrowDown cycles through results with visual highlight, Enter navigates to the selected result, Escape closes the modal. Body scroll is locked while the modal is open. The search input receives auto-focus with a short delay for DOM rendering.
Syntax-highlighted code blocks via syntect (rendered at build time). Copy-to-clipboard button on each block. Language label displayed. Bee-themed syntax color scheme for both light and dark modes. Copy-to-clipboard implemented on both docs pages and landing page install section terminal blocks using .copy-btn with data-code attributes. Docs code blocks are wrapped at build time by build.rs in a code-block-wrapper div containing a header bar (language label + copy button) and the code body, sharing a unified dark background (#2b303b). The build pipeline strips syntect's outer <pre> wrapper to prevent nested <pre> elements, applying the background color to the wrapper div instead. CSS overrides ensure consistent styling regardless of Tailwind dark mode state.
Right sidebar (desktop only) auto-generated from page headings. Highlights current section on scroll via IntersectionObserver. Smooth-scrolls to heading on click. Scroll-spy highlighting is implemented as a separate TocHighlighter #[island] (rather than converting DocToc itself, since its &'static heading props are not serializable for island deserialization). The island uses a -70% bottom margin observer to trigger headings when they reach the top portion of the viewport, tracking visible heading IDs in a HashSet and highlighting the first visible heading in document order with text-honey font-medium border-l-2 border-honey styling.
Warm amber/honey color tokens:
Light mode: --honey (#F59E0B), --honey-light (#FCD34D), --honey-dark (#D97706), --nectar (#FFFBEB), --comb (#78716C), --bark (#1C1917), --pollen (#FEF3C7), --surface (#FFFFFF), --surface-raised (#FAFAF9).
Dark mode: --honey (#FBBF24), --nectar (#1C1917), --comb (#A8A29E), --bark (#FAFAF9), --pollen (#292524), --surface (#0C0A09), --surface-raised (#1C1917).
Auto-detects prefers-color-scheme by default. Manual toggle via #[island] component in navigation bar. User preference persisted to localStorage. Implemented with Tailwind dark: variants. Smooth transition between modes.
Inter for headings and body text. JetBrains Mono for code. Self-hosted fonts in public/fonts/ (no external font dependencies).
Scroll reveal is handled by an inline <script> in the HTML shell (src/app.rs), not a WASM island. The previous ScrollObserver #[island] approach was replaced because it blocked SSR content — all .reveal elements remained invisible until WASM hydrated, defeating the purpose of pre-rendering.
The inline script implementation:
- Above-fold elements are revealed synchronously via
getBoundingClientRect()viewport check (no transition delay, content visible on first paint) - Below-fold elements are animated via
IntersectionObserveras they scroll into view - SPA route changes are handled by a
MutationObserverthat re-scans for new.revealelements - No-JS fallback: a
<noscript><style>block makes all.revealcontent visible without JavaScript
Supports .reveal, .reveal-left, .reveal-right, .reveal-scale classes, adding .visible on intersection. CSS animation-timeline: scroll() remains as progressive enhancement for Chromium browsers. Motion style: fade-up and slide-in, smooth and organic. Respects prefers-reduced-motion — all animations disabled when set.
src/components/scroll_observer.rs has been deleted. The file tree no longer includes it.
Subtle hex grid pattern in hero background. Feature card borders with hex-inspired angled corners (hints, not literal hexagons). Section dividers use gentle honeycomb wave instead of straight lines. Restrained — enhances the theme without distracting from content.
Fixed navigation bar at top of page. Shows commitbee logo/name, primary nav links (Home, Docs, GitHub). On docs pages, adds search bar. Transparent background at hero, glassmorphism background after scroll — implemented via a passive scroll listener inline script that toggles a .scrolled CSS class on #site-nav, with @custom-variant scrolled (&.scrolled) in Tailwind v4 driving the transition. Mobile: MobileMenu #[island] replaces the original non-functional hamburger button with a full slide-out navigation panel. Features backdrop overlay, slide-in-right CSS animation with prefers-reduced-motion override, Escape key dismissal, and close-on-click behavior for all navigation links (Home, Docs, GitHub, crates.io).
GitHub Actions workflow triggered on push to development branch:
cargo leptos build --release- Start Axum server locally in background
- Pre-render all routes to static HTML via cross-platform Rust binary (
src/bin/prerender.rs) - Add
404.htmlfor GitHub Pages SPA fallback - Deploy
dist/to GitHub Pages viaactions/deploy-pages
mise.toml with tasks: dev (cargo leptos watch), build (cargo leptos build --release), content (validate markdown frontmatter and links), prerender (pre-render all routes to static HTML via Rust binary), fmt (cargo fmt), check (clippy for both SSR and WASM). Note: bin-target = "commitbee-web" is required in [package.metadata.leptos] because the [[bin]] entry for the prerender binary creates a second binary target that confuses cargo-leptos.
leptos_router for navigation between pages without full reloads. URL structure: / (landing), /docs/:slug (doc pages). Fallback route for 404. Cross-document navigation uses the View Transitions API (@view-transition { navigation: auto; } in CSS) for smoother page transitions in supporting browsers. Link prefetching is enabled via an inline script that creates <link rel="prefetch"> elements on pointerenter events, preloading target pages before the user clicks for near-instant navigation.
No API keys, credentials, or secrets in the codebase. The site is entirely static with no server-side secrets needed.
Self-hosted fonts and assets only. No external script dependencies. No third-party analytics or tracking by default. Content-Security-Policy headers via <meta> tag in HTML shell. Only favicon.svg is referenced (no apple-touch-icon or favicon.ico links — those files do not exist in public/images/).
cargo audit in CI. Minimize dependency tree. Pin WASM toolchain versions.
Target: < 1.5s on 3G connection. Pre-rendered HTML ensures content is visible before WASM loads. Critical CSS inlined or loaded with high priority.
Islands-only WASM: target < 200KB gzipped. Only interactive components compiled to WASM. Static content is pure HTML with zero JS overhead.
Target: > 95 on all four Lighthouse categories (Performance, Accessibility, Best Practices, SEO) for both landing page and doc pages.
Self-hosted fonts with font-display: swap. Preload critical font weights. System font stack as fallback. Inter-Variable.woff2 and JetBrainsMono-Regular.woff2 are both declared as <link rel="preload" as="font"> in the HTML shell, preventing render-blocking font fetches and eliminating layout shift on code blocks.
OG images and assets served in modern formats (WebP with fallback). Lazy loading for below-the-fold images.
WCAG 2.1 AA compliance. Semantic HTML throughout. Keyboard navigation for all interactive elements. Focus indicators on all interactive elements. Screen reader compatible navigation and content structure. prefers-reduced-motion respected for all animations. Skip-to-content link (<a href="#main-content">) is visually hidden by default, visible on focus with honey accent styling. Landing page uses <main id="main-content"> semantic landmark; docs pages use id="main-content" on the content container.
Three breakpoints: mobile (< 768px), tablet (768-1024px), desktop (> 1024px). Doc sidebar collapses to drawer on mobile. TOC hidden on mobile and tablet. Landing page sections stack vertically on mobile with simplified animations.
Automatic detection of system preference. Manual override with persistent toggle. No flash of wrong theme on page load (theme applied before first paint via inline script or server-rendered class).
Sticky top nav visible at all times. Doc sidebar shows full page tree with current page highlighted. Breadcrumbs on doc pages for orientation. Prev/next links for sequential reading. Cmd+K / Ctrl+K search shortcut discoverable via nav hint.
All markdown files parse without errors. Frontmatter validates against schema. No broken internal links between doc pages. Search index generates successfully.
Leptos component tests for interactive islands (theme toggle, search, code copy). Verify hydration works correctly after pre-rendering.
Lighthouse CI checks on every PR. Screenshot comparison for landing page and key doc pages (optional, Phase 2).
axe-core or equivalent automated accessibility checks in CI. Verify keyboard navigation flow. Verify screen reader landmarks.
Test on: Chrome (latest), Firefox (latest), Safari (latest). WASM hydration must work on all three. CSS scroll-timeline fallback verified on Firefox/Safari.
Static HTML + WASM + CSS + assets deployed to gh-pages branch. Custom domain support via CNAME file in public/.
All routes pre-rendered at build time. Route list auto-generated by build.rs into a routes.txt manifest (doc slugs from content pipeline + landing page + /not-found). A cross-platform Rust binary (src/bin/prerender.rs) starts the Axum server locally, iterates the manifest, and fetches each route via HTTP/1.0 GET to path/index.html (e.g., docs/getting-started/index.html). Zero shell dependencies — works on Linux, macOS, and Windows. 404.html is generated from the pre-rendered /not-found route (dist/not-found/index.html), which renders the actual NotFound component with bee-themed 404 page — not the landing page. Falls back to index.html if the /not-found render fails. /not-found is excluded from sitemap.xml. The prerender phase also generates robots.txt (with sitemap reference) and sitemap.xml (from the routes manifest with priority scoring). Base URL is configurable via SITE_BASE_URL env var, defaulting to https://commitbee.dev. Canonical <link rel="canonical"> tags are rendered per-page in the landing and docs page components.
Hashed asset filenames for long-term caching. HTML files served with short cache TTL for quick content updates. WASM bundle and CSS fingerprinted.
| Phase | Version | Status | Focus |
|---|---|---|---|
| 1 | v1.0 | Implemented | Landing page, docs wiki, design system, deployment pipeline |
| 2 | v1.1 | Future | i18n support, visual regression tests, enhanced pipeline demo |
| 3 | v2.0 | Future | WASM playground (run commitbee internals in browser), blog/changelog |
| Metric | Target | Measurement |
|---|---|---|
| Lighthouse Performance | > 95 | CI Lighthouse audit |
| Lighthouse Accessibility | > 95 | CI Lighthouse audit |
| WASM bundle size | < 200KB gzipped | CI artifact size |
| First Contentful Paint | < 1.5s (3G) | Lighthouse |
| Build time | < 5 minutes | GitHub Actions duration |
| Doc page count | >= 12 (all DOCS.md sections) | Build output |
| Broken links | 0 | Build-time validation |
- WASM playground — No live compilation of commitbee internals in the browser for v1. Pipeline demo uses pre-baked animation.
- Blog / changelog — Not in scope for v1. Documentation wiki only.
- User accounts — Static site with no server-side state or authentication.
- Analytics dashboard — No built-in analytics. Optional privacy-respecting analytics (e.g., Plausible) can be added later.
- Comments / discussion — Use GitHub Discussions for community interaction.
- i18n content translation — English only for v1. Architecture supports future locale directories.
- Server-side runtime — No persistent server. Everything pre-rendered to static files.
See docs/superpowers/specs/2026-03-13-commitbee-web-design.md for the full design specification including:
- Detailed color palette with hex values for both light and dark modes
- Typography specifications
- Hexagonal motif guidelines
- Scroll animation specifications
- Component inventory
Documentation content is derived from the commitbee repository's DOCS.md, split into individual markdown files:
| Doc Page | Source Section |
|---|---|
| getting-started.md | DOCS.md: Getting Started |
| how-it-works.md | DOCS.md: How It Works |
| configuration.md | DOCS.md: Configuration |
| commands-and-flags.md | DOCS.md: Commands & Flags |
| llm-providers.md | DOCS.md: LLM Providers |
| commit-splitting.md | DOCS.md: Commit Splitting |
| validation-pipeline.md | DOCS.md: The Validation Pipeline |
| security-and-safety.md | DOCS.md: Security & Safety |
| git-hooks.md | DOCS.md: Git Hook Integration |
| supported-languages.md | DOCS.md: Supported Languages |
| troubleshooting.md | DOCS.md: Troubleshooting |
| architecture.md | DOCS.md: Architecture Deep Dive |