feat: redesign documentation site with animated logo and improved UX (#7)

* feat: redesign documentation site with animated logo and improved UX

Major documentation overhaul:

• Simplified navigation from 23 pages to 7 essential pages
• OAuth-first approach with bearer tokens as fallback option
• Clean red theme matching logo design
• Responsive theme switching (light/dark mode)

New animated logo mascot:
• Eyes look left, right, center with subtle nose rotation
• Natural blinking animation with proper easing
• 12-second cycle for subtle easter egg effect
• Positioned correctly in hero layout

Enhanced user experience:
• Custom theme toggle (sun/moon icons vs dropdown)
• Improved color contrast in both themes
• Proper syntax highlighting and formatting
• Fixed all configuration examples to match implementation

Technical improvements:
• Added Prettier formatting with Astro plugin
• Created reusable components (CustomHero, AnimatedLogo, ThemeSelect)
• Proper component override structure
• CSS custom properties for consistent theming

Removed overcomplicated structure and fixed content accuracy to match actual Go implementation.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* add Makefile with convenience commands for docs

* docs: update CLAUDE.md with documentation site guidelines

Add comprehensive section covering:
- Design philosophy and visual guidelines
- Technical implementation details
- Animation specifications
- Color management and theming
- Content guidelines and common issues
- Deployment process

Includes specific guidance on the animated mascot, proper color usage,
and troubleshooting for future documentation work.

---------

Co-authored-by: Claude <[email protected]>

Author: dgellow

CLAUDE.md

@@ -196,9 +196,110 @@ staticcheck ./...
 
 # Run locally
 ./mcp-front -config config.json
+
+# Documentation site (from root)
+make doc         # Start dev server
+make format      # Format docs with Prettier
+make build       # Build static site
 ```
 
-## Communication & Design Philosophy
+## Documentation Site Guidelines
+
+### Design Philosophy
+
+The documentation site follows terse, to-the-point prose style (like early Stripe or Stainless docs):
+- No bullet lists or tables in content
+- Conversational yet technical tone
+- Developer-to-developer communication
+- OAuth-first approach with bearer tokens as collapsible fallback
+
+### Visual Design
+
+- **Theme**: Clean red (#FF6B6B) matching logo, with softer red (#FF9999) for dark mode
+- **Logo**: Animated mascot that looks left/right/center with nose rotation and natural blinking
+- **Navigation**: Simplified from 23 pages to 7 essential pages
+- **Components**: Custom hero, theme switcher, and animated logo components
+
+### Technical Implementation
+
+**Structure** (docs-site/):
+```
+src/
+├── components/
+│   ├── AnimatedLogo.astro       # Mascot with eye movement and blinking
+│   ├── CustomHero.astro         # Hero layout with logo positioning
+│   └── CustomThemeSelect.astro  # Sun/moon toggle vs dropdown
+├── assets/
+│   ├── logo.svg                 # Dark mode version (lighter strokes)
+│   └── logo-light.svg           # Light mode version (darker strokes)
+└── styles/custom.css            # Theme variables and animations
+```
+
+**Key Features**:
+- Starlight theme with custom components and CSS overrides
+- Proper light/dark mode with automatic logo switching
+- 12-second animation cycle for subtle mascot behavior
+- Mobile-responsive design (needs work)
+
+### Animation Details
+
+The animated logo creates a face-like character:
+- **Eyes**: Left/right translation (1px) with synchronized movement
+- **Nose**: Subtle rotation (-1deg/+1deg) following eye direction  
+- **Blinking**: Vertical scale (scaleY 0.1) with step-like timing for natural effect
+- **Timing**: 12-second cycle for easter egg discovery, not attention-grabbing
+
+### Color Management
+
+**CSS Custom Properties**:
+```css
+:root {
+  --sl-color-accent: #FF6B6B;  /* Light mode */
+}
+
+[data-theme='dark'] {
+  --sl-color-accent: #FF6B6B;  /* Buttons */
+  --sl-color-text-accent: #333333;  /* Text on red backgrounds */
+}
+```
+
+**Specific Overrides**:
+- GitHub icon: White in dark mode
+- Sidebar selection: Readable contrast
+- Anchor links: Light gray in dark mode
+- Content links: Red in dark mode
+- TOC current section: Red highlight
+
+### Content Guidelines
+
+**Configuration Examples**:
+- Always use `{"$env": "VAR"}` syntax, never bash `$VAR`
+- Match actual Go implementation exactly
+- Use realistic service names (e.g., "linear" not "database")
+- Include all required fields (version, transportType, etc.)
+
+**Writing Style**:
+- Flowing prose, not lists
+- Explain the "why" not just "how"  
+- Assume developer audience
+- Keep it concise but complete
+
+### Common Issues
+
+1. **Theme switching breaks**: Check CSS variable inheritance
+2. **Logo not animating**: Ensure component is properly imported and classes match
+3. **Colors wrong in dark mode**: Verify `[data-theme='dark']` selectors
+4. **Build failures**: Usually missing imports or malformed frontmatter
+5. **Content not updating**: Astro dev server cache, restart required
+
+### Deployment
+
+- Uses GitHub Pages with workflow in `.github/workflows/`
+- Build artifacts in `docs-site/dist/`
+- Base path: `/mcp-front` for GitHub Pages
+- Prettier formatting enforced
+
+Remember: The mascot is an easter egg, not a distraction. Subtle movements create personality without being annoying.
 
 ### Understanding Sam's Standards
 

Makefile

@@ -0,0 +1,12 @@
+doc:
+	cd docs-site && npm run dev
+
+format:
+	go fmt ./...
+	cd docs-site && npm run format
+
+build:
+	go build -o mcp-front ./cmd/mcp-front
+	cd docs-site && npm run build
+
+.PHONY: doc format build

docs-site/.prettierrc

@@ -0,0 +1,23 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 80,
+  "plugins": ["prettier-plugin-astro"],
+  "overrides": [
+    {
+      "files": "*.astro",
+      "options": {
+        "parser": "astro"
+      }
+    },
+    {
+      "files": ["*.md", "*.mdx"],
+      "options": {
+        "proseWrap": "preserve",
+        "printWidth": 100
+      }
+    }
+  ]
+}

docs-site/astro.config.mjs

@@ -12,67 +12,30 @@ export default defineConfig({
 			description: 'OAuth 2.1 authenticated proxy for Model Context Protocol servers',
 			logo: {
 				alt: 'MCP Front Logo',
-				src: './src/assets/logo.svg',
+				light: './src/assets/logo-light.svg',
+				dark: './src/assets/logo.svg',
 			},
 			social: [
 				{ icon: 'github', label: 'GitHub', href: 'https://github.com/dgellow/mcp-front' },
 			],
 			sidebar: [
+				{ label: 'Introduction', slug: 'index' },
+				{ label: 'Quickstart', slug: 'quickstart' },
 				{
-					label: 'Start Here',
+					label: 'Examples',
 					items: [
-						{ label: 'Introduction', slug: 'index' },
-						{ label: 'Getting Started', slug: 'getting-started' },
-						{ label: 'Architecture', slug: 'architecture' },
-					],
-				},
-				{
-					label: 'Configuration',
-					items: [
-						{ label: 'Overview', slug: 'config/overview' },
-						{ label: 'Bearer Token Auth', slug: 'config/bearer-token' },
-						{ label: 'OAuth 2.1 Auth', slug: 'config/oauth' },
-						{ label: 'MCP Servers', slug: 'config/mcp-servers' },
-						{ label: 'Environment Variables', slug: 'config/environment' },
-					],
-				},
-				{
-					label: 'Deployment',
-					items: [
-						{ label: 'Docker', slug: 'deployment/docker' },
-						{ label: 'Docker Compose', slug: 'deployment/docker-compose' },
-						{ label: 'Google Cloud Run', slug: 'deployment/cloud-run' },
-						{ label: 'Production Setup', slug: 'deployment/production' },
-					],
-				},
-				{
-					label: 'OAuth Guide',
-					items: [
-						{ label: 'OAuth 2.1 Overview', slug: 'oauth/overview' },
-						{ label: 'Google Workspace Setup', slug: 'oauth/google-workspace' },
-						{ label: 'Firestore Configuration', slug: 'oauth/firestore' },
-						{ label: 'Security Best Practices', slug: 'oauth/security' },
-					],
-				},
-				{
-					label: 'API Reference',
-					items: [
-						{ label: 'Endpoints', slug: 'api/endpoints' },
-						{ label: 'Authentication', slug: 'api/authentication' },
-						{ label: 'SSE Protocol', slug: 'api/sse-protocol' },
-					],
-				},
-				{
-					label: 'Development',
-					items: [
-							{ label: 'Testing', slug: 'dev/testing' },
-						{ label: 'Architecture Decisions', slug: 'dev/architecture-decisions' },
+						{ label: 'Bearer Token', slug: 'examples/bearer-token' },
+						{ label: 'OAuth with Google', slug: 'examples/oauth-google' },
+						{ label: 'Deploy to Cloud Run', slug: 'examples/cloud-run' },
 					],
 				},
+				{ label: 'Configuration', slug: 'configuration' },
+				{ label: 'API Reference', slug: 'api-reference' },
 			],
 			customCss: ['./src/styles/custom.css'],
 			components: {
 				Header: './src/components/CustomHeader.astro',
+				ThemeSelect: './src/components/CustomThemeSelect.astro',
 			},
 		}),
 	],

docs-site/package-lock.json

@@ -9,14 +9,18 @@
     "build": "astro build",
     "preview": "astro preview",
     "astro": "astro",
-    "deploy": "npm run build && gh-pages -d dist"
+    "deploy": "npm run build && gh-pages -d dist",
+    "format": "prettier --write \"src/**/*.{astro,md,mdx,js,ts,json}\"",
+    "format:check": "prettier --check \"src/**/*.{astro,md,mdx,js,ts,json}\""
   },
   "dependencies": {
     "@astrojs/starlight": "^0.34.3",
     "astro": "^5.6.1",
     "sharp": "^0.32.5"
   },
   "devDependencies": {
-    "gh-pages": "^6.0.0"
+    "gh-pages": "^6.0.0",
+    "prettier": "^3.3.3",
+    "prettier-plugin-astro": "^0.14.1"
   }
 }