diff --git a/.github/workflows/deploy-homepage.yml b/.github/workflows/deploy-homepage.yml new file mode 100644 index 0000000..eb61d5e --- /dev/null +++ b/.github/workflows/deploy-homepage.yml @@ -0,0 +1,55 @@ +name: Deploy Homepage + +on: + push: + branches: [main] + paths: + - 'homepage/**' + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: pnpm/action-setup@v4 + with: + version: 10 + + - uses: actions/setup-node@v4 + with: + node-version: 22 + cache: pnpm + cache-dependency-path: homepage/pnpm-lock.yaml + + - name: Install dependencies + working-directory: homepage + run: pnpm install + + - name: Build + working-directory: homepage + run: pnpm build + + - uses: actions/upload-pages-artifact@v3 + with: + path: homepage/dist + + deploy: + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - id: deployment + uses: actions/deploy-pages@v4 diff --git a/README.md b/README.md index 3629cb7..6323e9f 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ Quick Start License: MIT Claude Code Plugin + Homepage

diff --git a/docs/plans/2026-03-15-homepage-design.md b/docs/plans/2026-03-15-homepage-design.md new file mode 100644 index 0000000..573adb7 --- /dev/null +++ b/docs/plans/2026-03-15-homepage-design.md @@ -0,0 +1,83 @@ +# Understand Anything — Project Homepage Design + +**Date**: 2026-03-15 +**Goal**: Attract new users to the Understand Anything Claude Code plugin +**Approach**: "The Reveal" — cinematic scroll-driven single-page site + +## Tech Stack + +- **Astro** (static site generator, zero JS framework overhead) +- **Self-hosted fonts** (no Google Fonts CDN dependency — works in China) +- **CSS** with variables matching dashboard theme +- **Vanilla JS** for `IntersectionObserver` scroll animations +- **GitHub Actions** for CI/CD to `gh-pages` branch + +## Source & Deployment + +- Source: `homepage/` directory on `main` branch +- Build output: deployed to `gh-pages` branch via GitHub Actions +- URL: `lum1104.github.io/Understand-Anything` + +## Page Structure (scroll order) + +### 1. Nav Bar +Minimal floating nav. Logo/wordmark left, GitHub star button + "Get Started" CTA right. Transparent, becomes solid on scroll. + +### 2. Hero (full viewport) +- Headline: **"Understand Any Codebase"** +- Subheadline: "Turn 200,000 lines of code into an interactive knowledge graph you can explore, search, and learn from — powered by multi-agent AI analysis." +- CTA: "Get Started" (gold button, scrolls to install section) +- Secondary: "View on GitHub" (text link) +- Background: `hero.jpg` with dark gradient overlay + +### 3. Dashboard Showcase +- Label: "See your codebase come alive" +- `overview.png` in a stylized browser frame with gold glow shadow +- Fade-in on scroll + +### 4. Feature Cards (3 columns) +Staggered fade-in animation: +1. **Interactive Knowledge Graph** — "Visualize files, functions, and dependencies as an explorable graph with smart layout." +2. **Plain-English Summaries** — "Every node explained in language anyone can understand — from junior devs to product managers." +3. **Guided Tours** — "AI-generated walkthroughs that teach you the codebase step by step." + +### 5. Install CTA +- Headline: "Get started in 30 seconds" +- Code block: + ``` + /plugin marketplace add Lum1104/Understand-Anything + /plugin install understand-anything + /understand + ``` +- "Works with Claude Code" note + +### 6. Footer +- "Understand Anything" wordmark +- GitHub link, license +- "Built as a Claude Code plugin" + +## Visual Design System + +### Colors (matching dashboard) +| Token | Value | Usage | +|-------|-------|-------| +| `--bg` | `#0a0a0a` | Page background | +| `--surface` | `#141414` | Card backgrounds | +| `--border` | `#1a1a1a` | Borders, dividers | +| `--accent` | `#d4a574` | Gold/amber primary accent | +| `--text` | `#e8e2d8` | Primary text (warm white) | +| `--text-muted` | `#8a8578` | Secondary text | + +### Typography (self-hosted, with fallbacks) +- **Headings**: DM Serif Display → Georgia, "Times New Roman", serif +- **Body**: Inter → -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif +- **Code**: JetBrains Mono → "SF Mono", "Cascadia Code", "Fira Code", monospace +- Hero headline: ~4rem serif with subtle text-shadow glow + +### Effects +- Gold glow on dashboard screenshot frame (`box-shadow` with gold at low opacity) +- Subtle noise texture overlay (SVG, matching dashboard) +- Scroll-triggered fade+slide-up animations (CSS `@keyframes` + `IntersectionObserver`) +- CTA button: gold background with hover glow pulse +- Cards: glass-morphism with `backdrop-filter: blur` +- Responsive: 768px (tablet), 480px (mobile) diff --git a/docs/plans/2026-03-15-homepage-implementation.md b/docs/plans/2026-03-15-homepage-implementation.md new file mode 100644 index 0000000..5be2639 --- /dev/null +++ b/docs/plans/2026-03-15-homepage-implementation.md @@ -0,0 +1,1238 @@ +# Homepage Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Build a cinematic, scroll-driven project homepage for Understand Anything using Astro, deployed to GitHub Pages via `gh-pages` branch. + +**Architecture:** Astro SSG project in `homepage/` on main. Self-hosted fonts (DM Serif Display, Inter, JetBrains Mono) with robust fallbacks. Pure CSS animations triggered by `IntersectionObserver`. GitHub Actions workflow builds and deploys to `gh-pages` on push. + +**Tech Stack:** Astro 5, CSS custom properties, vanilla JS, GitHub Actions + +**Design doc:** `docs/plans/2026-03-15-homepage-design.md` + +--- + +### Task 1: Scaffold Astro Project + +**Files:** +- Create: `homepage/package.json` +- Create: `homepage/astro.config.mjs` +- Create: `homepage/tsconfig.json` +- Create: `homepage/src/pages/index.astro` (placeholder) +- Create: `homepage/src/layouts/Layout.astro` (placeholder) +- Create: `homepage/public/.gitkeep` + +**Step 1: Initialize Astro project** + +```bash +cd /Users/yuxianglin/Desktop/opensource/Understand-Anything +mkdir -p homepage +cd homepage +pnpm create astro@latest . -- --template minimal --no-install --no-git --typescript strict +``` + +If the interactive prompt blocks, create files manually instead. + +**Step 2: Configure Astro for GitHub Pages** + +Edit `homepage/astro.config.mjs`: + +```js +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + site: 'https://lum1104.github.io', + base: '/Understand-Anything', +}); +``` + +**Step 3: Verify the project builds** + +```bash +cd /Users/yuxianglin/Desktop/opensource/Understand-Anything/homepage +pnpm install +pnpm build +``` + +Expected: Build succeeds, `dist/` directory created. + +**Step 4: Commit** + +```bash +git add homepage/ +git commit -m "feat(homepage): scaffold Astro project with GitHub Pages config" +``` + +--- + +### Task 2: Self-Host Fonts & Base CSS + +**Files:** +- Create: `homepage/public/fonts/DMSerifDisplay-Regular.woff2` +- Create: `homepage/public/fonts/Inter-Regular.woff2` +- Create: `homepage/public/fonts/Inter-SemiBold.woff2` +- Create: `homepage/public/fonts/JetBrainsMono-Regular.woff2` +- Create: `homepage/src/styles/global.css` + +**Step 1: Download font files** + +Download the WOFF2 files from Google Fonts API (or fontsource). Place them in `homepage/public/fonts/`. Required files: +- DM Serif Display Regular (woff2) +- Inter Regular + SemiBold (woff2) +- JetBrains Mono Regular (woff2) + +Use curl to download from fontsource CDN or Google Fonts CSS API. Example: + +```bash +mkdir -p homepage/public/fonts +# Download from fontsource (reliable CDN) +curl -L "https://cdn.jsdelivr.net/fontsource/fonts/dm-serif-display@latest/latin-400-normal.woff2" -o homepage/public/fonts/DMSerifDisplay-Regular.woff2 +curl -L "https://cdn.jsdelivr.net/fontsource/fonts/inter@latest/latin-400-normal.woff2" -o homepage/public/fonts/Inter-Regular.woff2 +curl -L "https://cdn.jsdelivr.net/fontsource/fonts/inter@latest/latin-600-normal.woff2" -o homepage/public/fonts/Inter-SemiBold.woff2 +curl -L "https://cdn.jsdelivr.net/fontsource/fonts/jetbrains-mono@latest/latin-400-normal.woff2" -o homepage/public/fonts/JetBrainsMono-Regular.woff2 +``` + +If download fails, try alternative URLs or use `npx fontsource` to install locally. + +**Step 2: Create global CSS with design tokens and font-face declarations** + +Create `homepage/src/styles/global.css`: + +```css +/* Font declarations — self-hosted, no external CDN dependency */ +@font-face { + font-family: 'DM Serif Display'; + src: url('/Understand-Anything/fonts/DMSerifDisplay-Regular.woff2') format('woff2'); + font-weight: 400; + font-style: normal; + font-display: swap; +} + +@font-face { + font-family: 'Inter'; + src: url('/Understand-Anything/fonts/Inter-Regular.woff2') format('woff2'); + font-weight: 400; + font-style: normal; + font-display: swap; +} + +@font-face { + font-family: 'Inter'; + src: url('/Understand-Anything/fonts/Inter-SemiBold.woff2') format('woff2'); + font-weight: 600; + font-style: normal; + font-display: swap; +} + +@font-face { + font-family: 'JetBrains Mono'; + src: url('/Understand-Anything/fonts/JetBrainsMono-Regular.woff2') format('woff2'); + font-weight: 400; + font-style: normal; + font-display: swap; +} + +/* Design tokens */ +:root { + --bg: #0a0a0a; + --surface: #141414; + --border: #1a1a1a; + --accent: #d4a574; + --accent-glow: rgba(212, 165, 116, 0.15); + --text: #e8e2d8; + --text-muted: #8a8578; + + --font-heading: 'DM Serif Display', Georgia, 'Times New Roman', serif; + --font-body: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; + --font-code: 'JetBrains Mono', 'SF Mono', 'Cascadia Code', 'Fira Code', monospace; +} + +/* Reset & base */ +*, *::before, *::after { + margin: 0; + padding: 0; + box-sizing: border-box; +} + +html { + scroll-behavior: smooth; +} + +body { + font-family: var(--font-body); + background-color: var(--bg); + color: var(--text); + line-height: 1.6; + -webkit-font-smoothing: antialiased; + overflow-x: hidden; +} + +/* Noise texture overlay */ +body::before { + content: ''; + position: fixed; + inset: 0; + pointer-events: none; + z-index: 9999; + opacity: 0.03; + background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='noise'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23noise)'/%3E%3C/svg%3E"); +} + +/* Scroll-reveal animation */ +@keyframes fadeSlideUp { + from { + opacity: 0; + transform: translateY(30px); + } + to { + opacity: 1; + transform: translateY(0); + } +} + +.reveal { + opacity: 0; +} + +.reveal.visible { + animation: fadeSlideUp 0.8s ease-out forwards; +} + +/* Stagger delays for feature cards */ +.reveal-delay-1 { animation-delay: 0.1s; } +.reveal-delay-2 { animation-delay: 0.25s; } +.reveal-delay-3 { animation-delay: 0.4s; } + +a { + color: var(--accent); + text-decoration: none; +} + +a:hover { + text-decoration: underline; +} +``` + +**Step 3: Import global CSS in Layout** + +Update `homepage/src/layouts/Layout.astro`: + +```astro +--- +interface Props { + title: string; +} + +const { title } = Astro.props; +--- + + + + + + + + + {title} + + + + + + + +``` + +**Step 4: Build and verify fonts load** + +```bash +cd /Users/yuxianglin/Desktop/opensource/Understand-Anything/homepage +pnpm build +``` + +Expected: Build succeeds. Check `dist/fonts/` contains the woff2 files. + +**Step 5: Commit** + +```bash +git add homepage/public/fonts/ homepage/src/styles/global.css homepage/src/layouts/Layout.astro +git commit -m "feat(homepage): add self-hosted fonts and design token CSS" +``` + +--- + +### Task 3: Nav Bar Component + +**Files:** +- Create: `homepage/src/components/Nav.astro` + +**Step 1: Create the nav component** + +Create `homepage/src/components/Nav.astro`: + +```astro +--- +const githubUrl = 'https://github.com/Lum1104/Understand-Anything'; +--- + +

+ + + + +``` + +**Step 2: Add Nav to index.astro (temporary test)** + +Update `homepage/src/pages/index.astro`: + +```astro +--- +import Layout from '../layouts/Layout.astro'; +import Nav from '../components/Nav.astro'; +--- + + +