Improve docs site design and language review

Author: code5717

.github/workflows/deploy-docs.yml

@@ -48,6 +48,10 @@ jobs:
             npm install --no-audit --no-fund
           fi
 
+      - name: Lint docs
+        working-directory: site
+        run: npm run lint -- --max-warnings=0
+
       - name: Build docs
         working-directory: site
         run: npm run build

.gitignore

@@ -18,5 +18,7 @@ examples/*.zig
 # Local agent configs/instructions
 .agents/
 .claude/
+.hermes/
+skills-lock.json
 AGENTS.md
 CLAUDE.md

CHANGELOG.md

@@ -26,6 +26,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - 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.
+  - Revised the dark theme into a quieter terminal-brutalist direction, replaced remote placeholder imagery with a local generated hero asset, made the header search control functional, reduced marketing copy, and removed fake testimonial content.
+  - Tightened example-card wrapping, search dialog semantics, shared scroll locking, and responsive home-section padding so compact layouts do not collide with panel borders.
+  - Added a documentation 404 route and social preview metadata for a cleaner fallback and share surface.
 
 - **Semantic Coverage Expansion**
   - Unskipped 9 previously skipped semantic tests across `test/test_semantic_generics.py` and `test/test_semantic_control_flow.py`.

LANGUAGE_SPEC_REVIEW.md

@@ -24,7 +24,9 @@ npm run preview
 
 ```bash
 cd site
-npm run lint
+npm run lint -- --max-warnings=0
+npm run typecheck
+npm run build
 ```
 
 Repository-level docs style checks:
@@ -44,14 +46,27 @@ Primary shared UI primitives live in `site/src/components/`.
 
 The current site direction is:
 
-- warm monochrome, paper-toned surfaces
+- minimal terminal-brutalist dark mode with graphite surfaces, amber action color, and restrained cyan focus/info accents
 - 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
+- image-led home page and social preview assets from `site/public/` plus source assets in `site/src/assets/`
+- concise, product-like copy with no fake testimonials
+- keyboard-accessible docs search overlay from the header search button and `/` shortcut
 - 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
 
+## Adding a Docs Page
+
+When adding or renaming a page, update these pieces together:
+
+- route registration in `site/src/App.tsx`
+- primary/sidebar navigation and `PAGE_META` in `site/src/content/navigation.ts`
+- section search entries for important anchors
+- footer links if the page is a major docs group
+- route-specific content with `SectionPanel` titles for stable anchors
+- `npm run lint -- --max-warnings=0`, `npm run typecheck`, and `npm run build`
+
 ## Deployment
 
 GitHub Pages deploy runs from `.github/workflows/deploy-docs.yml` when docs-related files change on `main`/`master`.

site/README.md

@@ -4,8 +4,25 @@
     <meta charset="UTF-8" />
     <link rel="icon" type="image/svg+xml" href="/a7-py/favicon.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="darkreader-lock" />
+    <meta name="color-scheme" content="light dark" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Instrument+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;600;700&family=Newsreader:opsz,wght@6..72,400;6..72,500;6..72,600&display=swap" rel="stylesheet" />
+    <link rel="canonical" href="https://airbus5717.github.io/a7-py/" />
     <title>A7 Programming Language</title>
     <meta name="description" content="A7 is a statically-typed, procedural language with array programming capabilities, generics, and manual memory management. Compiles to Zig." />
+    <meta property="og:title" content="A7 Programming Language" />
+    <meta property="og:description" content="A small systems language with explicit control flow, clear diagnostics, and direct compiler output." />
+    <meta property="og:type" content="website" />
+    <meta property="og:url" content="https://airbus5717.github.io/a7-py/" />
+    <meta property="og:site_name" content="A7 Docs" />
+    <meta property="og:locale" content="en_US" />
+    <meta property="og:image" content="https://airbus5717.github.io/a7-py/a7-terminal-hero.png" />
+    <meta name="twitter:card" content="summary_large_image" />
+    <meta name="twitter:title" content="A7 Programming Language" />
+    <meta name="twitter:description" content="A small systems language with explicit control flow, clear diagnostics, and direct compiler output." />
+    <meta name="twitter:image" content="https://airbus5717.github.io/a7-py/a7-terminal-hero.png" />
   </head>
   <body>
     <div id="root"></div>

site/index.html

@@ -7,6 +7,8 @@
     "dev": "vite",
     "build": "tsc -b && vite build",
     "lint": "eslint .",
+    "typecheck": "tsc -b --pretty false",
+    "check": "npm run lint -- --max-warnings=0 && npm run typecheck && npm run build",
     "preview": "vite preview"
   },
   "dependencies": {

site/package.json

@@ -1,16 +1,20 @@
-<!DOCTYPE html>
-<html>
+<!doctype html>
+<html lang="en">
   <head>
-    <meta charset="utf-8">
+    <meta charset="utf-8" />
     <title>A7 Docs</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
     <script>
-      // SPA redirect for GitHub Pages
-      // Redirects 404s back to index.html with the path as a query param
-      var path = window.location.pathname;
-      window.location.replace(
-        window.location.origin + '/a7-py/' + '?p=' + encodeURIComponent(path)
-      );
+      ;(function () {
+        var base = '/a7-py'
+        var path = window.location.pathname
+        var route = path.indexOf(base) === 0 ? path.slice(base.length) : path
+        route = route.replace(/\/index\.html$/, '') || '/'
+        window.location.replace(base + '/#' + route + window.location.search + window.location.hash)
+      })()
     </script>
   </head>
-  <body></body>
+  <body>
+    <p><a href="/a7-py/#/">Open A7 docs</a></p>
+  </body>
 </html>

site/public/404.html

@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://airbus5717.github.io/a7-py/sitemap.xml