ClaudeDo/docs/superpowers/specs/2026-06-04-marketing-website-design.md

ClaudeDo distribution website — design

Date: 2026-06-04 Status: Approved (design), ready for implementation planning Repo: new standalone repo claudedo-web (not part of the ClaudeDo app solution) Domain: claudedo.kuns.dev (Coolify on the user's VPS)

Purpose

Give friends a public place to download ClaudeDo and learn what it does, without sending them to the Gitea repo — so the source repo can be made more private. The site also fronts the app's self-updater so the Gitea URL is never exposed in the app or on the page.

Goals / non-goals

Goals

• Public, no-auth landing page at claudedo.kuns.dev that matches the app's visual identity.
• A primary download (installer .exe) plus the portable .zip and checksums.
• A release proxy that (a) feeds the page the current version and (b) serves the app's self-updater the same JSON shape Gitea returns, with download URLs rewritten to route through claudedo.kuns.dev — hiding Gitea entirely.

Non-goals

• No docs site / getting-started page (the app ships an installer that handles setup).
• No changelog page (release notes already live on Gitea releases).
• No auth, accounts, analytics, or CMS.
• No CI/PR tooling for this repo beyond what Coolify needs to deploy.

Access & distribution decisions

• Access: fully public. No password/login. Relies on the unadvertised URL.
• Download source: build-time fetch of the latest Gitea release for the displayed version; actual download links route through the proxy and resolve the latest asset at request time (so a stale page still downloads the current build).
• Self-updater proxy: in scope for v1 (not deferred).

Tech stack

• Nuxt 3 (Vue 3) — single framework, single repo, single Coolify deploy.
• Nitro server routes for the release proxy + asset streaming.
• No DB, no auth, no secrets (the releases/ClaudeDo repo is public).
• Fonts: Inter Tight (display/body) + JetBrains Mono (mono), self-hosted or via Google Fonts. Design tokens ported from docs/UI Rewrite/design_handoff_claudedo/Tokens.axaml and styles.css (moss/sage/peat palette, dark-first, 14px island radius, grain texture).

Concept: "the page IS the app"

The landing page is a faithful, in-browser rendering of the ClaudeDo desktop — the window chrome + the three islands — rather than a conventional marketing page. This is the chosen direction (over a cinematic single-window scroll and a worklog feed).

Layout — three islands on the app "desktop"

Desktop background = the app's layered moss gradients + 3px grain overlay. A centered app window (titlebar + body) holds a 3-column island grid:

1. Lists island (left) — repurposed as page nav.

   • Header "Lists" + a decorative search box (Ctrl K kbd chip).
   • "Pages" group: Overview · Features (6) · How it works · Screenshots (3) · Download, each with a colored swatch dot; active item gets the accent left-bar.
   • Footer styled like the app's user footer: avatar, "For friends", claudedo.kuns.dev.

2. Tasks island (middle) — features rendered as task cards.

   • Header: date eyebrow, big title (the hero line "Queue the work. Claude does it."), a running · review badge, eye/gear icon buttons, and a subtitle.
   • A decorative "Add a task…" row.
   • Six feature cards (circle check — done cards filled; title; a status chip done/running/waiting for review; a star). The features:
     1. Isolated worktrees
     2. The task queue
     3. Review & merge
     4. Live session log
     5. Per-list & per-task config
     6. Self-updating
   • A "Ready" group with the final "↓ Download ClaudeDo" card.

3. Detail island (right) — faithful to the reworked Task-Detail island.

   • Source of truth for the detail visuals: docs/superpowers/specs/2026-06-04-task-detail-redesign-design.md (the app's in-progress rework). The website's detail pane must track that design.
   • Three-zone stack:
     • Task header — mono id (#F01…), title, trash/gear action icons.
     • DETAILS bar — DETAILS eyebrow + Edit / copy / ⋯, then a markdown body (headings, paragraphs, inline code, ordered/unordered lists) describing the feature.
     • WorkConsole docked at the bottom — traffic-light dots, · N turns · +x −y, tabs Output / Actions / Session, and a Created … footer.
   • Per-feature mapping:
     • Feature panels: markdown writeup in DETAILS + a short relevant Output log.
     • "Review & merge": opens on the Actions tab with Merge target + Open Diff / Approve & merge.
     • Download: DETAILS shows requirements (.NET 8 Desktop Runtime, Claude CLI, Git); the Actions tab holds the install controls, with Merge target repurposed as a Build selector and buttons ↓ Download installer / Portable .zip / checksums.txt.

4. Statusbar (bottom) — ● Online · claudedo.kuns.dev · private build.

Interaction

• Clicking a task card selects it (accent bar + card highlight) and swaps the active detail panel; the WorkConsole tabs are clickable within a panel.
• All panels are server-rendered and present in the DOM, toggled by class — the page is fully readable and downloadable without JavaScript (progressive enhancement). Vue handles the selection state on the client.

Responsive

• ≤ ~1100px: drop the Detail island; show Lists + Tasks.
• ≤ ~780px: single column — the Tasks list; tapping a feature pushes to a full-screen Detail view (mirrors the app's narrow-window behavior) with a back affordance.

Server: release proxy (Nitro)

The app's ReleaseClient (src/ClaudeDo.Releases/ReleaseClient.cs) calls {apiBase}/releases/latest and reads tag_name, name, and assets[].browser_download_url; DownloadAsync GETs an asset URL directly.

• GET /api/releases/latest — fetches https://git.kuns.dev/api/v1/repos/releases/ClaudeDo/releases/latest, returns the same JSON shape, but every assets[].browser_download_url is rewritten from the Gitea URL to https://claudedo.kuns.dev/api/download/<encoded-asset-path>. Cached briefly (e.g. 5 min) server-side.
• GET /api/download/[...path] — reconstructs the Gitea asset URL from the path and streams the binary back (no redirect to Gitea, so the URL stays hidden). Sets appropriate Content-Type/Content-Disposition.
• server/utils/gitea.ts — shared base URL (GITEA_API, REPO from env), fetch helper, and the URL-rewrite/asset-path round-trip.
• The page's download buttons point at the same /api/download/... routes (with a stable "latest installer" path), so links never go stale between deploys.

App-side coordinating change (separate, in the ClaudeDo repo)

Point ReleaseClient's apiBase at https://claudedo.kuns.dev/api instead of the Gitea default (one-line DI change where ReleaseClient/UpdateCheckService are constructed). Tracked as a follow-up; not part of the claudedo-web repo. The proxy path (/api/releases/latest) is chosen to match the existing {apiBase}/releases/latest call so the parser is untouched.

Content / assets

• Screenshots (provided): main 3-column view (hero), diff review modal, worktrees panel. Stored in public/screenshots/. Placeholders sized for them until dropped in.
• Copy: hero "Queue the work. Claude does it."; six feature writeups as above (final wording during implementation).

Error handling

• Build-time release fetch fails: render the page with a last-known/placeholder version label; download buttons still work because they resolve via the runtime proxy route.
• Proxy /api/releases/latest upstream failure: return a 502/null-equivalent the way Gitea would on miss; the app's UpdateCheckService already treats null/exception as CheckFailed and degrades gracefully.
• /api/download upstream failure: surface a 502; the button shows an error state.
• No retries beyond a single upstream attempt for v1 (low traffic, friends-only).

Testing

• Vitest unit tests for server/utils/gitea.ts: URL rewrite (Gitea → proxy) and the asset-path round-trip (proxy path → Gitea URL), and release-JSON shape preservation.
• A light component smoke test that the page renders the islands and the download controls without JS errors.
• No real-network/Gitea calls in tests — mock the upstream fetch.

Deployment (Coolify)

• Dockerfile: node:20-alpine build → nuxt build → run .output/server/index.mjs.
• Coolify app bound to claudedo.kuns.dev with TLS via its reverse proxy.
• Env: GITEA_API (default https://git.kuns.dev/api/v1), REPO (releases/ClaudeDo), PUBLIC_BASE_URL (https://claudedo.kuns.dev) for URL rewriting.
• Deploy on push to main; re-deploy (or a periodic rebuild) refreshes the displayed version. No PR/CI tooling beyond Coolify's build.

Open risk

• The reworked Detail island in the app is still in flux. The website's detail pane must be kept in sync with 2026-06-04-task-detail-redesign-design.md; expect a visual-polish pass once that rework lands.

Repo layout

claudedo-web/
├── nuxt.config.ts
├── app.vue
├── pages/index.vue              # the one landing page
├── components/
│   ├── AppWindow.vue            # window chrome + statusbar
│   ├── ListsIsland.vue          # page nav
│   ├── TasksIsland.vue          # feature cards + download card
│   ├── DetailIsland.vue         # three-zone detail (header / DETAILS md / WorkConsole)
│   ├── WorkConsole.vue          # tabs: Output / Actions / Session
│   └── content/                 # per-feature markdown/blurbs + download panel
├── server/
│   ├── api/releases/latest.get.ts
│   ├── api/download/[...path].get.ts
│   └── utils/gitea.ts
├── assets/css/tokens.css        # palette + type ported from Tokens.axaml/styles.css
├── public/screenshots/          # 3 PNGs
└── Dockerfile