Redesign GitHub Pages UI to match Ollama/LangChain quality

[himanshu231204]

Problem

The current GitHub Pages documentation site (https://openagenthq.github.io/openagent-eval/) uses MkDocs Material with custom CSS, but it doesn't match the polish and professional feel of leading developer tool documentation sites like Ollama (docs.ollama.com) and LangChain (docs.langchain.com). The site needs a visual refresh to:

• Build trust with developers evaluating the tool
• Improve readability and scannability
• Create a more memorable brand impression
• Match the quality expected of a production-ready evaluation framework

Current State

The site currently uses:

• MkDocs Material theme with Indigo primary color
• Custom extra.css with Space Grotesk + Inter fonts
• Hero section with gradient mesh background
• Card-based feature layout
• Basic responsive design

Proposed Design Improvements

1. Typography Refresh

Current: Space Grotesk (headings) + Inter (body)
Proposed: Adopt a more distinctive, modern type stack

• Use Inter or Geist for body (clean, highly legible)
• Use Space Grotesk or Satoshi for headings (geometric, tech-forward)
• Increase heading weight contrast (400 body / 600-700 headings)
• Tighter line-height on headings (1.1-1.2), comfortable on body (1.5-1.6)

2. Color System Refinement

Current: Indigo primary (#3949ab) with amber accent
Proposed: More refined, modern palette

css :root { --oae-brand: #2563eb; --oae-brand-hover: #1d4ed8; --oae-signal: #10b981; --oae-surface: #ffffff; --oae-surface-2: #f8fafc; --oae-border: #e2e8f0; --oae-text: #0f172a; --oae-text-muted: #64748b; }

3. Hero Section Redesign

Inspired by Ollama's minimal hero:

• Remove gradient mesh background (too busy)
• Clean white/light background
• Larger, bolder headline with tighter tracking
• Single CTA button (pill-shaped, high contrast)
• Inline terminal snippet as hero element
• Remove or simplify the hero illustration SVG

4. Navigation Improvements

Inspired by LangChain's structured nav:

• Add top-level navigation tabs (more prominent)
• Improve mobile hamburger menu
• Add breadcrumb navigation on inner pages
• Sticky sidebar on desktop
• Search bar more prominent

5. Card and Component Refinement

• Remove box shadows (use borders only)
• Reduce border-radius (0.5rem instead of 0.75rem)
• Subtle hover state (border color change only)
• More whitespace inside cards
• Consistent icon treatment

6. Code Block Styling

• Dark code blocks with proper syntax highlighting
• Terminal-style blocks with colored prompt markers
• Copy button more subtle
• Better contrast for code text

7. Footer Enhancement

• Multi-column layout (Product, Resources, Community, Legal)
• Social links with icons
• Newsletter signup (optional)
• Copyright and license info

8. Responsive Improvements

• Better mobile typography scaling
• Improved touch targets on mobile
• Stack layout on mobile without losing hierarchy
• Fast load times

Reference Designs

Element	Ollama	LangChain	OpenAgent Eval (Current)
Background	Pure white	White/light gray	White with gradient mesh
Typography	SF Pro Rounded	Inter	Space Grotesk + Inter
Buttons	Pill (9999px)	Rounded (8px)	Rounded (6px)
Shadows	None	Subtle	Medium
Code blocks	Inline pills	Dark blocks	Light blocks
Navigation	Minimal top	Tabs + sidebar	Tabs + sidebar
Hero	Single column	Two-column	Two-column with illustration

Implementation Approach

Phase 1 - Quick wins (1-2 days)

• Update color variables in extra.css
• Refine typography scale and weights
• Remove gradient mesh from hero
• Simplify card shadows

Phase 2 - Component updates (2-3 days)

• Redesign hero section
• Update button styles to pill shape
• Improve code block styling
• Enhance footer

Phase 3 - Polish (1-2 days)

• Mobile responsive testing
• Accessibility audit (contrast, focus states)
• Performance optimization
• Cross-browser testing

Acceptance Criteria

• Site loads in < 2 seconds on 3G
• Passes WCAG AA contrast requirements
• Looks professional on desktop, tablet, and mobile
• Hero section is clean and focused (no gradient mesh)
• Typography is consistent and hierarchical
• Code blocks are easy to read and copy
• Navigation is intuitive and responsive
• Footer provides useful links and context

Additional Notes

• Keep MkDocs Material for now - it is solid and well-maintained
• Focus on CSS-only changes where possible to minimize risk
• Consider using a CSS framework like Tailwind for faster iteration (requires build pipeline changes)
• Could explore migrating to Mintlify (like LangChain) for better docs experience, but that is a larger undertaking

[himanshu231204]

@Nitjsefnie take a look on issue#239

[Nitjsefnie]

Taking this — starting right after the #226 docs wiring lands (both touch mkdocs.yml, so sequencing avoids a conflict). Plan: keep MkDocs Material as the base, overhaul the theme layer — typography scale/rhythm for the Space Grotesk + Inter pair, a proper landing page with hero + feature cards, dark-mode-first palette anchored to the org's black/white mark, cleaner nav/scannability (grouped sections, card grids for tutorials/metrics), and consistent code-block styling. I'll iterate against a locally-built site with real screenshots and bring the result as one PR with before/after captures.

[himanshu231204]

Taking this — starting right after the #226 docs wiring lands (both touch mkdocs.yml, so sequencing avoids a conflict). Plan: keep MkDocs Material as the base, overhaul the theme layer — typography scale/rhythm for the Space Grotesk + Inter pair, a proper landing page with hero + feature cards, dark-mode-first palette anchored to the org's black/white mark, cleaner nav/scannability (grouped sections, card grids for tutorials/metrics), and consistent code-block styling. I'll iterate against a locally-built site with real screenshots and bring the result as one PR with before/after captures.

ok , good to go . waiting for pr