Redesign docs site and add theme support

Author: code5717

CHANGELOG.md

@@ -21,6 +21,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `visit_index_expr`: now rejects non-integer index expressions.
 
 ### Changed
+- **Documentation Site Redesign**
+  - Reworked the React/Vite docs frontend under `site/` into a cleaner editorial layout with a warm monochrome token system, flatter panels, and a top-led navigation shell.
+  - Rebuilt the home page around an image-led docs landing composition with a framed code hero, quick-start strip, feature bento, pipeline overview, and structured footer.
+  - Normalized shared docs primitives (`PageHeader`, `SectionPanel`, `MetricTile`, code/table/callout styling) so content pages inherit the same minimalist visual system.
+  - Added light, dark, and system theme support with a header theme toggle and detection for extension-driven dark mode so site styling does not stack awkwardly with tools like Dark Reader.
+
 - **Semantic Coverage Expansion**
   - Unskipped 9 previously skipped semantic tests across `test/test_semantic_generics.py` and `test/test_semantic_control_flow.py`.
   - Converted deferred coverage into active failing tests to track implementation work directly in CI.

site/README.md

@@ -42,6 +42,16 @@ Design tokens and shared interface styles live in:
 
 Primary shared UI primitives live in `site/src/components/`.
 
+The current site direction is:
+
+- warm monochrome, paper-toned surfaces
+- editorial serif display type with a restrained sans body
+- 1px border discipline and flat panels
+- top navigation plus drawer-based full route navigation
+- image-led home page with framed media and minimal motion via reveal-on-scroll
+- built-in `light` / `dark` / `system` theme modes with persistence
+- dark-extension detection to avoid double-dark styling when browser extensions inject their own theme layer
+
 ## Deployment
 
 GitHub Pages deploy runs from `.github/workflows/deploy-docs.yml` when docs-related files change on `main`/`master`.

site/src/components/CodeBlock.tsx

@@ -10,11 +10,16 @@ export default function CodeBlock({ code, lang, title }: CodeBlockProps) {
   const html = useHighlight(code, lang)
 
   return (
-    <figure className="code-shell">
+    <figure className="code-shell" data-reveal>
       {(title || lang) && (
         <figcaption className="code-head">
-          <span>{title || lang}</span>
-          {lang && <span className="doc-chip">{lang}</span>}
+          <span className="code-head-dots" aria-hidden="true">
+            <span />
+            <span />
+            <span />
+          </span>
+          <span className="code-head-title">{title || lang}</span>
+          <span className="code-head-meta">{lang ? 'A7' : ''}</span>
         </figcaption>
       )}
       {html ? (

site/src/components/Layout.tsx

@@ -1,9 +1,26 @@
 import { useEffect, useState } from 'react'
-import { Outlet } from 'react-router-dom'
+import { NavLink, Outlet, useLocation } from 'react-router-dom'
 import Sidebar from './Sidebar'
+import { useTheme } from '../hooks/useTheme'
+
+type PrimaryNavItem =
+  | { kind: 'route'; to: string; label: string; end?: boolean }
+  | { kind: 'link'; href: string; label: string }
+
+const PRIMARY_NAV: PrimaryNavItem[] = [
+  { kind: 'route', to: '/', label: 'Docs', end: true },
+  { kind: 'route', to: '/start', label: 'Guide' },
+  { kind: 'route', to: '/language', label: 'Reference' },
+  { kind: 'route', to: '/examples', label: 'Examples' },
+  { kind: 'route', to: '/testing', label: 'Playground' },
+  { kind: 'route', to: '/changelog', label: 'Blog' },
+  { kind: 'link', href: 'https://github.com/Airbus5717/a7-py', label: 'GitHub ↗' },
+]
 
 export default function Layout() {
   const [sidebarOpen, setSidebarOpen] = useState(false)
+  const { pathname } = useLocation()
+  const { preference, resolvedTheme, darkExtensionActive, cycleTheme } = useTheme()
 
   useEffect(() => {
     if (!sidebarOpen) {
@@ -26,6 +43,34 @@ export default function Layout() {
     }
   }, [sidebarOpen])
 
+  useEffect(() => {
+    document.documentElement.classList.add('reveal-ready')
+
+    const elements = Array.from(document.querySelectorAll<HTMLElement>('[data-reveal]'))
+    const observer = new IntersectionObserver(
+      (entries) => {
+        entries.forEach((entry) => {
+          if (entry.isIntersecting) {
+            entry.target.classList.add('is-visible')
+            observer.unobserve(entry.target)
+          }
+        })
+      },
+      {
+        threshold: 0.14,
+        rootMargin: '0px 0px -8% 0px',
+      },
+    )
+
+    elements.forEach((element, index) => {
+      element.classList.remove('is-visible')
+      element.style.setProperty('--reveal-delay', `${(index % 6) * 80}ms`)
+      observer.observe(element)
+    })
+
+    return () => observer.disconnect()
+  }, [pathname])
+
   return (
     <div className="app-shell">
       <a className="skip-link" href="#main-content">
@@ -34,11 +79,97 @@ export default function Layout() {
 
       {sidebarOpen && <div className="mobile-overlay" onClick={() => setSidebarOpen(false)} />}
 
-      <aside className={`app-sidebar${sidebarOpen ? ' open' : ''}`}>
+      <aside className={`app-sidebar${sidebarOpen ? ' open' : ''}`} aria-hidden={!sidebarOpen}>
         <Sidebar onClose={() => setSidebarOpen(false)} />
       </aside>
 
       <div className="app-main">
+        <header className="site-header">
+          <div className="site-header-inner">
+            <NavLink to="/" className="site-brand">
+              <span className="site-brand-mark">A7</span>
+            </NavLink>
+
+            <nav className="site-nav" aria-label="Primary">
+              {PRIMARY_NAV.map((item) => (
+                item.kind === 'route' ? (
+                  <NavLink
+                    key={item.to}
+                    to={item.to}
+                    end={item.end}
+                    className={({ isActive }) => `site-nav-link${isActive ? ' active' : ''}`}
+                  >
+                    {item.label}
+                  </NavLink>
+                ) : (
+                  <a
+                    key={item.href}
+                    className="site-nav-link"
+                    href={item.href}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                  >
+                    {item.label}
+                  </a>
+                )
+              ))}
+            </nav>
+
+            <div className="site-header-tools">
+              <button type="button" className="site-search" aria-label="Search documentation">
+                <span className="site-search-label">
+                  <svg width="14" height="14" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.8}>
+                    <circle cx="11" cy="11" r="6.5" />
+                    <path strokeLinecap="round" d="M16 16l4 4" />
+                  </svg>
+                  Search docs
+                </span>
+                <span className="site-search-kbd">/</span>
+              </button>
+
+              <button
+                type="button"
+                onClick={cycleTheme}
+                className="theme-toggle"
+                aria-label={`Theme: ${preference}. Click to cycle theme mode.`}
+                title={darkExtensionActive ? 'Dark extension detected. Site theme will avoid double-dark styling.' : undefined}
+              >
+                <span className="theme-toggle-icon" aria-hidden="true">
+                  {resolvedTheme === 'dark' ? (
+                    <svg width="16" height="16" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.8}>
+                      <path strokeLinecap="round" strokeLinejoin="round" d="M21 12.8A9 9 0 1111.2 3a7 7 0 009.8 9.8z" />
+                    </svg>
+                  ) : preference === 'system' ? (
+                    <svg width="16" height="16" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.8}>
+                      <rect x="3.5" y="4.5" width="17" height="12" rx="2" />
+                      <path strokeLinecap="round" d="M8 19.5h8M12 16.5v3" />
+                    </svg>
+                  ) : (
+                    <svg width="16" height="16" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.8}>
+                      <circle cx="12" cy="12" r="4.5" />
+                      <path strokeLinecap="round" d="M12 2.5v2.5M12 19v2.5M21.5 12H19M5 12H2.5M18.7 5.3l-1.8 1.8M7.1 16.9l-1.8 1.8M18.7 18.7l-1.8-1.8M7.1 7.1L5.3 5.3" />
+                    </svg>
+                  )}
+                </span>
+                <span className="theme-toggle-label">{preference}</span>
+                {darkExtensionActive ? <span className="theme-toggle-badge">ext</span> : null}
+              </button>
+
+              <button
+                type="button"
+                onClick={() => setSidebarOpen(true)}
+                className="site-menu-button"
+                aria-label="Open site navigation"
+              >
+                <svg width="18" height="18" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.8}>
+                  <path strokeLinecap="round" strokeLinejoin="round" d="M4 7h16M4 12h16M4 17h16" />
+                </svg>
+                <span className="site-menu-button-text">Menu</span>
+              </button>
+            </div>
+          </div>
+        </header>
+
         <header className="mobile-header">
           <div className="mobile-header-row">
             <button
@@ -60,14 +191,16 @@ export default function Layout() {
           <Outlet />
         </main>
 
-        <footer className="app-footer">
-          <div className="app-footer-inner">
-            A7 Programming Language ·{' '}
-            <a href="https://github.com/Airbus5717/a7-py" target="_blank" rel="noopener noreferrer">
-              GitHub
-            </a>
-          </div>
-        </footer>
+        {pathname !== '/' ? (
+          <footer className="app-footer">
+            <div className="app-footer-inner">
+              <span>A7 Programming Language</span>
+              <a href="https://github.com/Airbus5717/a7-py" target="_blank" rel="noopener noreferrer">
+                GitHub
+              </a>
+            </div>
+          </footer>
+        ) : null}
       </div>
     </div>
   )

site/src/components/MetricTile.tsx

@@ -6,7 +6,7 @@ interface MetricTileProps {
 
 export default function MetricTile({ label, value, note }: MetricTileProps) {
   return (
-    <div className="metric-tile">
+    <div className="metric-tile" data-reveal>
       <p className="metric-label">{label}</p>
       <p className="metric-value">{value}</p>
       {note ? <p className="metric-note">{note}</p> : null}

site/src/components/PageHeader.tsx

@@ -9,11 +9,13 @@ interface PageHeaderProps {
 
 export default function PageHeader({ title, summary, eyebrow, actions }: PageHeaderProps) {
   return (
-    <header className="page-header">
-      {eyebrow && <span className="page-header-eyebrow">{eyebrow}</span>}
-      <h1 className="page-header-title">{title}</h1>
-      <p className="page-header-summary">{summary}</p>
-      {actions ? <div style={{ marginTop: 'var(--space-3)' }}>{actions}</div> : null}
+    <header className="page-header" data-reveal>
+      <div className="page-header-copy">
+        {eyebrow && <span className="page-header-eyebrow">{eyebrow}</span>}
+        <h1 className="page-header-title">{title}</h1>
+        <p className="page-header-summary">{summary}</p>
+      </div>
+      {actions ? <div className="page-header-actions">{actions}</div> : null}
     </header>
   )
 }

site/src/components/SectionPanel.tsx

@@ -9,7 +9,7 @@ interface SectionPanelProps {
 
 export default function SectionPanel({ title, subtitle, children, className = '' }: SectionPanelProps) {
   return (
-    <section className={`section-panel ${className}`.trim()}>
+    <section className={`section-panel ${className}`.trim()} data-reveal>
       {title && <h2 className="section-title">{title}</h2>}
       {subtitle && <p className="section-subtitle">{subtitle}</p>}
       {children}

site/src/hooks/useTheme.ts

@@ -0,0 +1,112 @@
+import { useEffect, useMemo, useState } from 'react'
+
+export type ThemePreference = 'system' | 'light' | 'dark'
+type ResolvedTheme = 'light' | 'dark' | 'extension-dark'
+
+const STORAGE_KEY = 'a7-docs-theme'
+
+function readStoredPreference(): ThemePreference {
+  if (typeof window === 'undefined') {
+    return 'system'
+  }
+
+  const stored = window.localStorage.getItem(STORAGE_KEY)
+  return stored === 'light' || stored === 'dark' || stored === 'system' ? stored : 'system'
+}
+
+function hasDarkExtensionActive() {
+  const html = document.documentElement
+  const body = document.body
+
+  if (
+    html.hasAttribute('data-darkreader-mode')
+    || html.hasAttribute('data-darkreader-scheme')
+    || html.classList.contains('darkreader')
+    || body?.classList.contains('darkreader')
+  ) {
+    return true
+  }
+
+  return Boolean(
+    document.querySelector(
+      'style.darkreader, link.darkreader, meta[name="darkreader"], style[data-darkreader], style[id*="dark-reader"]',
+    ),
+  )
+}
+
+export function useTheme() {
+  const [preference, setPreference] = useState<ThemePreference>(() => readStoredPreference())
+  const [prefersDark, setPrefersDark] = useState(false)
+  const [darkExtensionActive, setDarkExtensionActive] = useState(false)
+
+  useEffect(() => {
+    const media = window.matchMedia('(prefers-color-scheme: dark)')
+    const updatePreference = () => setPrefersDark(media.matches)
+
+    updatePreference()
+    media.addEventListener('change', updatePreference)
+
+    return () => media.removeEventListener('change', updatePreference)
+  }, [])
+
+  useEffect(() => {
+    const updateExtensionState = () => setDarkExtensionActive(hasDarkExtensionActive())
+
+    updateExtensionState()
+
+    const observer = new MutationObserver(updateExtensionState)
+    observer.observe(document.documentElement, { attributes: true, childList: true, subtree: true })
+
+    return () => observer.disconnect()
+  }, [])
+
+  const resolvedTheme = useMemo<ResolvedTheme>(() => {
+    if (darkExtensionActive) {
+      return 'extension-dark'
+    }
+
+    if (preference === 'dark') {
+      return 'dark'
+    }
+
+    if (preference === 'light') {
+      return 'light'
+    }
+
+    return prefersDark ? 'dark' : 'light'
+  }, [darkExtensionActive, preference, prefersDark])
+
+  useEffect(() => {
+    window.localStorage.setItem(STORAGE_KEY, preference)
+  }, [preference])
+
+  useEffect(() => {
+    const root = document.documentElement
+    root.dataset.themePreference = preference
+    root.dataset.theme = resolvedTheme === 'dark' ? 'dark' : 'light'
+    root.dataset.darkExtensionActive = darkExtensionActive ? 'true' : 'false'
+    root.style.colorScheme = resolvedTheme === 'dark' ? 'dark' : 'light'
+  }, [darkExtensionActive, preference, resolvedTheme])
+
+  const cycleTheme = () => {
+    setPreference((current) => {
+      if (current === 'system') {
+        return 'light'
+      }
+
+      if (current === 'light') {
+        return 'dark'
+      }
+
+      return 'system'
+    })
+  }
+
+  return {
+    preference,
+    resolvedTheme,
+    darkExtensionActive,
+    setPreference,
+    cycleTheme,
+  }
+}