diff --git a/site/README.md b/site/README.md index 97f0d93..2d8262b 100644 --- a/site/README.md +++ b/site/README.md @@ -41,12 +41,17 @@ production HTTP headers. Deployment is a separate operation. ## Design -The approved minimal documentation layout uses a 240px navigation rail, a reading -column, and a 180px outline. Native disclosures replace the rail below 900px and -the outline below 1200px. Article prose uses Inter Variable at 17px and 1.65 line -height. Literal code uses JetBrains Mono at 15px and 1.6 line height without -ligatures. Both fonts are pinned dependencies, copied locally with their -licenses. Only the prose font is preloaded. +The shared documentation shell uses a 240px navigation rail, a reading column, +and a 180px outline. Native disclosures replace the rail below 900px and the +outline below 1200px. The landing page (`index`) adds a brand-first full-bleed +hero before that shell: large **A7** mark, one lede, Get started / Tour CTAs, and +a full-width code sample. Safe-area insets, short-height orientation compaction, and +fold / dual-segment spanning rules live in `src/tailwind.css`. + +Article prose uses Inter Variable at 17px and 1.65 line height. Literal code +uses JetBrains Mono at 15px and 1.6 line height without ligatures. Both fonts +are pinned dependencies, copied locally with their licenses. Only the prose +font is preloaded. Light and dark tokens live in `src/tailwind.css`. The initial theme follows the system; explicit preferences apply before paint and persist when storage is diff --git a/site/docs/research-decisions.md b/site/docs/research-decisions.md index b31ff16..c9feeef 100644 --- a/site/docs/research-decisions.md +++ b/site/docs/research-decisions.md @@ -6,7 +6,9 @@ Reviewed 2026-09-19. These decisions implement the user's approved option 2 plan Use a persistent documentation rail, a readable article column, and an optional page outline. Collapse navigation into native disclosures on smaller screens so it works without JavaScript. Separate the guided tour from exhaustive language reference. This applies the distinction between learning and information retrieval in [Diátaxis](https://diataxis.fr/). -No option 2 concept image was located by the initial repository filename search. The written approved plan is the design authority. Existing screenshots under `docs/audits/2026-09-19/browser/` record the previous site, not acceptance of this rebuild. Do not claim a pixel comparison against an unavailable reference. +The 2026-11 landing + responsive pass keeps that IA. The home route adds a brand-first hero (large A7, one sentence, two CTAs, full-bleed code visual) before the shared shell. Responsive hardening covers safe-area insets, short-height orientations, local overflow for tables and code, and progressive fold / viewport-segment dual-pane rules. Fold hardware coverage is only as strong as the CSS APIs the browser exposes; record simulations separately from device claims. + +No option 2 concept image was located by the initial repository filename search. The written approved plan is the design authority for the docs shell. The Project store brief `site-responsive-redesign.md` (approach 3) is the authority for the landing and fold/responsive additions. Existing screenshots under `docs/audits/2026-09-19/browser/` record the previous site, not acceptance of this rebuild. Do not claim a pixel comparison against an unavailable reference. ## Typography diff --git a/site/public/docs/index.md b/site/public/docs/index.md index b01c573..5aca235 100644 --- a/site/public/docs/index.md +++ b/site/public/docs/index.md @@ -6,11 +6,10 @@ summary: An experimental systems language that compiles to Zig and native progra order: 0 --- -# A7 documentation +# A7 -A7 is an experimental, statically typed systems language. Its Python compiler -checks `.a7` source and emits a single Zig file. Zig 0.17.1 builds the native -program. Start below, then read the tour or the language reference. +A7 checks `.a7` source in Python, emits one Zig file, and builds a native program +with Zig 0.17.1. Start below, then read the tour or the language reference. ## Start in two minutes diff --git a/site/public/docs/manifest.json b/site/public/docs/manifest.json index c57f5ce..686a8ac 100644 --- a/site/public/docs/manifest.json +++ b/site/public/docs/manifest.json @@ -2,7 +2,7 @@ "schemaVersion": 1, "sourceRevision": { "kind": "documentation-sha256", - "value": "eb7189210095e32a41842c28da6d205770570dcbeda5d106094c47ea587d26dd" + "value": "37e9a5b449debb1d260b3cd415d31b797ecfcfdb60376e4c6626530c3b532dd6" }, "qualification": "Documentation content digest, not a compiler verification result. Evidence links identify the source authority.", "pages": [ @@ -16,8 +16,8 @@ "sections": [ { "level": 1, - "id": "a7-documentation", - "text": "A7 documentation" + "id": "a7", + "text": "A7" }, { "level": 2, diff --git a/site/public/llms-full.txt b/site/public/llms-full.txt index 4cff57f..3407ada 100644 --- a/site/public/llms-full.txt +++ b/site/public/llms-full.txt @@ -2,11 +2,10 @@ Source: https://code5717.github.io/a7-py/docs/index.md -# A7 documentation +# A7 -A7 is an experimental, statically typed systems language. Its Python compiler -checks `.a7` source and emits a single Zig file. Zig 0.17.1 builds the native -program. Start below, then read the tour or the language reference. +A7 checks `.a7` source in Python, emits one Zig file, and builds a native program +with Zig 0.17.1. Start below, then read the tour or the language reference. ## Start in two minutes diff --git a/site/scripts/build.ts b/site/scripts/build.ts index f5d8406..13e2ce6 100644 --- a/site/scripts/build.ts +++ b/site/scripts/build.ts @@ -28,6 +28,37 @@ function navigation(active: string) { .join("")}`, ).join(""); } +function topbar() { + return `
A7 DocumentationExperimental
GitHub
`; +} +function searchDialog() { + return `

Search documentation

↑ ↓ NavigateEnter OpenEsc Close

`; +} +function shell( + doc: Doc, + articleInner: string, + outline: string, + neighbors: string, + options: { mainTag: "main" | "div"; mainClass?: string } = { + mainTag: "main", + }, +) { + const tag = options.mainTag; + const cls = options.mainClass ? ` class="${options.mainClass}"` : ""; + const mainOpen = + tag === "main" + ? `
` + : ``; + const mainClose = tag === "main" ? "
" : ""; + const article = `
${e(doc.group)}Read Markdown
+
On this page
+
${articleInner}
+ +
`; + return `
+${mainOpen}${article}${mainClose} +
`; +} function page(doc: Doc) { const outline = doc.headings .filter((h) => h.level === 2) @@ -38,6 +69,7 @@ function page(doc: Doc) { d ? `${label === "Previous" ? icon("left") : ""}${label}${label === "Next" ? icon("right") : ""}${e(d.nav)}` : ""; + const neighbors = `${neighbor(docs[i - 1], "Previous")}${neighbor(docs[i + 1], "Next")}`; let articleHtml = doc.html; for (const id of doc.aliases) { const target = @@ -47,26 +79,57 @@ function page(doc: Doc) { `$1`, ); } - return ` - + const head = ` + ${e(doc.title)}${doc.slug === "index" ? "" : " · A7"} - - -
A7 DocumentationExperimental
GitHub
-
-
+`; + if (doc.slug === "index") { + const match = articleHtml.match(/^]*)>([\s\S]*?)<\/h1>\s*/); + if (!match) throw new Error("expected leading H1 in article HTML"); + const headingText = match[2]; + const body = articleHtml.slice(match[0].length); + const headingId = doc.headings[0].id; + const hero = `
+ +
+
+

Experimental systems language

+

${headingText}

+

${e(doc.summary)}

+

Get startedTour

+
+
-
-

Search documentation

↑ ↓ NavigateEnter OpenEsc Close

+main :: fn() { + io.println("Hello, World!") +}
+ + +`; + return `${head} + +${topbar()} +
+${hero} +${shell(doc, body, outline, neighbors, { + mainTag: "div", + mainClass: "landing-docs", +})} +
+${searchDialog()} +`; + } + return `${head} + +${topbar()} +${shell(doc, articleHtml, outline, neighbors)} +${searchDialog()} `; } await rm(DIST, { recursive: true, force: true }); diff --git a/site/src/site.js b/site/src/site.js index 65b0c54..9df50d6 100644 --- a/site/src/site.js +++ b/site/src/site.js @@ -1,10 +1,16 @@ const navigation = document.querySelector(".navigation"); const mobileNavigation = matchMedia("(max-width: 899px)"); +const foldNavigation = matchMedia( + "(spanning: single-fold-vertical), (horizontal-viewport-segments: 2)", +); function adaptNavigation() { - if (navigation) navigation.open = !mobileNavigation.matches; + if (!navigation) return; + // Dual-pane fold layouts keep the rail open even when the CSS width is mid-range. + navigation.open = foldNavigation.matches || !mobileNavigation.matches; } adaptNavigation(); mobileNavigation.addEventListener("change", adaptNavigation); +foldNavigation.addEventListener("change", adaptNavigation); const base = "/a7-py"; const known = [ "start", diff --git a/site/src/tailwind.css b/site/src/tailwind.css index e1c8371..c3a840e 100644 --- a/site/src/tailwind.css +++ b/site/src/tailwind.css @@ -58,9 +58,11 @@ } html { scroll-padding-top: 6rem; + overflow-x: clip; } body { overflow-wrap: anywhere; + overflow-x: clip; margin: 0; background: var(--bg); color: var(--text); @@ -123,7 +125,9 @@ button:hover { display: flex; align-items: center; justify-content: space-between; - padding: 0 2rem; + padding: max(0rem, env(safe-area-inset-top, 0px)) + max(2rem, env(safe-area-inset-right, 0px)) 0 + max(2rem, env(safe-area-inset-left, 0px)); gap: 1rem; background: var(--bg); position: sticky; @@ -168,7 +172,10 @@ kbd { display: grid; grid-template-columns: 15rem minmax(0, 1fr) 11.25rem; gap: 3rem; - padding: 0 2rem; + padding: 0 max(2rem, env(safe-area-inset-right, 0px)) + max(0rem, env(safe-area-inset-bottom, 0px)) + max(2rem, env(safe-area-inset-left, 0px)); + min-width: 0; } .sidebar { font-size: 0.9375rem; @@ -218,7 +225,8 @@ kbd { background: var(--selected); font-weight: 600; } -.shell main { +.shell main, +.shell .landing-docs { min-width: 0; padding: 3rem 0 2rem; } @@ -511,10 +519,16 @@ dialog { border: 1px solid var(--line); border-radius: 0.5rem; box-shadow: 0 24px 80px #0003; - width: min(42rem, calc(100% - 2rem)); - max-height: 85dvh; + width: min( + 42rem, + calc(100% - 2rem - env(safe-area-inset-left, 0px) - env(safe-area-inset-right, 0px)) + ); + max-height: calc( + 85dvh - env(safe-area-inset-top, 0px) - env(safe-area-inset-bottom, 0px) + ); padding: 1.5rem; - margin: 8vh auto; + margin: max(8vh, env(safe-area-inset-top, 0px)) auto + max(1rem, env(safe-area-inset-bottom, 0px)); overflow: auto; } dialog::backdrop { @@ -706,7 +720,9 @@ pre, } .topbar { position: relative; - padding: 1rem; + padding: max(1rem, env(safe-area-inset-top, 0px)) + max(1rem, env(safe-area-inset-right, 0px)) 1rem + max(1rem, env(safe-area-inset-left, 0px)); height: auto; flex-wrap: wrap; } @@ -722,7 +738,9 @@ pre, } .shell { display: block; - padding: 0 1.5rem; + padding: 0 max(1.5rem, env(safe-area-inset-right, 0px)) + max(0rem, env(safe-area-inset-bottom, 0px)) + max(1.5rem, env(safe-area-inset-left, 0px)); } .sidebar { padding: 0; @@ -737,8 +755,8 @@ pre, } .navigation > summary { display: list-item; - min-height: 2rem; - padding: 0.25rem 0; + min-height: 2.75rem; + padding: 0.5rem 0; } .navigation:not([open]) > nav { display: none; @@ -750,7 +768,8 @@ pre, min-height: 2.75rem; padding: 0.625rem 0.75rem; } - .shell main { + .shell main, + .shell .landing-docs { padding-top: 2rem; } .prose h1 { @@ -765,7 +784,9 @@ pre, } @media (max-width: 399px) { .shell { - padding: 0 1rem; + padding: 0 max(1rem, env(safe-area-inset-right, 0px)) + max(0rem, env(safe-area-inset-bottom, 0px)) + max(1rem, env(safe-area-inset-left, 0px)); } .topbar { gap: 0.75rem; @@ -777,6 +798,9 @@ pre, } .tools a { padding: 0.25rem; + min-height: 2.75rem; + display: inline-flex; + align-items: center; } pre { padding: 1rem; @@ -791,6 +815,25 @@ pre, align-items: start; } } +@media (orientation: landscape) and (max-height: 500px) { + .topbar { + position: relative; + height: auto; + padding-top: max(0.5rem, env(safe-area-inset-top, 0px)); + padding-bottom: 0.5rem; + } + .navigation { + position: static; + max-height: none; + } + .page-outline nav { + position: static; + max-height: none; + } + html { + scroll-padding-top: 1rem; + } +} @media print { .topbar, .sidebar, @@ -799,14 +842,17 @@ pre, .tools, .pager, footer, - .copy { + .copy, + .landing-hero-plane, + .landing-ctas { display: none !important; } .shell { display: block; padding: 0; } - .shell main { + .shell main, + .shell .landing-docs { padding: 0; } pre { @@ -961,16 +1007,6 @@ footer a:hover { text-decoration: underline; text-underline-offset: 0.2em; } -body[data-slug="index"] .prose h1 { - font-size: clamp(2.5rem, 5vw, 3.25rem); - letter-spacing: -0.04em; - max-width: 20ch; -} -body[data-slug="index"] .prose > h1 + p { - font-size: 1.25rem; - line-height: 1.6; - max-width: 58ch; -} @media (prefers-reduced-motion: reduce) { *, *::before, @@ -980,3 +1016,268 @@ body[data-slug="index"] .prose > h1 + p { scroll-behavior: auto !important; } } + +/* Landing hero: brand-first first viewport */ +.landing-hero { + position: relative; + isolation: isolate; + overflow: clip; + min-height: min(72dvh, 44rem); + display: flex; + align-items: stretch; + border-bottom: 1px solid var(--line); + color: var(--text); +} +.landing-hero-plane { + position: absolute; + inset: 0; + z-index: -1; + background: + radial-gradient( + 120% 80% at 12% 0%, + color-mix(in srgb, var(--link) 16%, transparent), + transparent 55% + ), + radial-gradient( + 90% 70% at 88% 20%, + color-mix(in srgb, var(--muted) 18%, transparent), + transparent 50% + ), + linear-gradient( + 165deg, + color-mix(in srgb, var(--surface) 88%, var(--bg)) 0%, + var(--bg) 48%, + color-mix(in srgb, var(--surface) 70%, var(--bg)) 100% + ); +} +.landing-hero-plane::after { + content: ""; + position: absolute; + inset: 0; + opacity: 0.35; + background-image: repeating-linear-gradient( + -12deg, + transparent 0, + transparent 11px, + color-mix(in srgb, var(--line) 55%, transparent) 11px, + color-mix(in srgb, var(--line) 55%, transparent) 12px + ); + mask-image: linear-gradient(180deg, #000 20%, transparent 92%); +} +.landing-hero-grid { + width: min(100rem, 100%); + margin: 0 auto; + display: grid; + grid-template-columns: minmax(0, 1.05fr) minmax(0, 0.95fr); + gap: clamp(1.5rem, 4vw, 4rem); + align-items: center; + padding: clamp(2rem, 5vw, 4.5rem) max(2rem, env(safe-area-inset-right, 0px)) + clamp(2rem, 5vw, 4rem) max(2rem, env(safe-area-inset-left, 0px)); + min-width: 0; +} +.landing-eyebrow { + margin: 0 0 1rem; + font-size: 0.8125rem; + font-weight: 650; + letter-spacing: 0.08em; + text-transform: uppercase; + color: var(--muted); +} +.landing-copy h1 { + margin: 0; + font-size: clamp(3.5rem, 12vw, 7rem); + font-weight: 750; + line-height: 0.92; + letter-spacing: -0.055em; + max-width: 8ch; +} +.landing-lede { + margin: 1.25rem 0 0; + font-size: clamp(1.125rem, 2.2vw, 1.375rem); + line-height: 1.55; + color: var(--muted); + max-width: 34ch; +} +.landing-ctas { + display: flex; + flex-wrap: wrap; + gap: 0.75rem; + margin: 2rem 0 0; +} +.landing-cta { + display: inline-flex; + align-items: center; + justify-content: center; + min-height: 2.75rem; + padding: 0.65rem 1.25rem; + border-radius: 0.25rem; + text-decoration: none; + font-weight: 600; + background: #a12a2a; + color: #fff; + border: 1px solid #8e2424; +} +.landing-cta:hover { + text-decoration: none; + filter: brightness(0.95); +} +.landing-cta-secondary { + background: transparent; + color: var(--text); + border-color: var(--muted); +} +.landing-cta-secondary:hover { + background: var(--surface); + filter: none; +} +.landing-visual { + min-width: 0; + align-self: stretch; + display: flex; +} +.landing-code { + flex: 1; + margin: 0; + min-width: 0; + max-width: 100%; + overflow: auto; + border: 1px solid var(--line); + background: color-mix(in srgb, var(--bg) 70%, var(--surface)); + padding: clamp(1.25rem, 3vw, 2rem); + font-size: clamp(0.875rem, 1.6vw, 1.05rem); + line-height: 1.65; + box-shadow: 0 18px 50px color-mix(in srgb, #000 12%, transparent); +} +body[data-slug="index"] .shell { + padding-top: 0.5rem; +} +body[data-slug="index"] .landing-docs .prose > p:first-child { + font-size: 1.125rem; + color: var(--muted); + max-width: 58ch; +} +@media (max-width: 899px) { + .landing-hero { + min-height: 0; + } + .landing-hero-grid { + grid-template-columns: minmax(0, 1fr); + padding: 2rem max(1.5rem, env(safe-area-inset-right, 0px)) 2.5rem + max(1.5rem, env(safe-area-inset-left, 0px)); + } + .landing-visual { + min-height: 14rem; + } +} +@media (max-width: 399px) { + .landing-hero-grid { + padding-inline: max(1rem, env(safe-area-inset-left, 0px)) + max(1rem, env(safe-area-inset-right, 0px)); + } + .landing-copy h1 { + font-size: clamp(3rem, 18vw, 4.25rem); + } +} +@media (orientation: landscape) and (max-height: 500px) { + .landing-hero { + min-height: 0; + } + .landing-hero-grid { + grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); + padding-block: 1.25rem; + gap: 1.25rem; + } + .landing-copy h1 { + font-size: clamp(2.5rem, 8vw, 4rem); + } + .landing-ctas { + margin-top: 1rem; + } +} + +/* Dual-screen / fold spanning: prefer nav | article across segments */ +@media (spanning: single-fold-vertical) { + .shell { + display: grid; + grid-template-columns: env(fold-left, 15rem) env(fold-right, minmax(0, 1fr)); + column-gap: env(fold-width, 3rem); + max-width: none; + } + .page-outline { + display: none; + } + .mobile-outline { + display: block; + } + .sidebar { + border-right: 0; + padding-right: 0; + } + .navigation { + position: sticky; + top: 4.5rem; + max-height: calc(100dvh - 4.5rem); + overflow: auto; + } + .navigation > summary { + display: none; + } + .navigation:not([open]) > nav { + display: block; + } +} +@media (spanning: single-fold-horizontal) { + .landing-hero { + min-height: env(fold-top, 40dvh); + } + .shell { + padding-top: 1rem; + } +} +@supports (width: env(viewport-segment-width 0 0)) { + @media (horizontal-viewport-segments: 2) { + .shell { + display: grid; + grid-template-columns: + env(viewport-segment-width 0 0) + env(viewport-segment-width 1 0); + column-gap: calc( + env(viewport-segment-left 1 0) - env(viewport-segment-right 0 0) + ); + max-width: none; + padding-left: env(viewport-segment-left 0 0); + padding-right: calc(100vw - env(viewport-segment-right 1 0)); + } + .page-outline { + display: none; + } + .mobile-outline { + display: block; + } + body[data-slug="index"] .landing-hero-grid { + grid-template-columns: + env(viewport-segment-width 0 0) + env(viewport-segment-width 1 0); + column-gap: calc( + env(viewport-segment-left 1 0) - env(viewport-segment-right 0 0) + ); + max-width: none; + width: 100%; + padding-left: env(viewport-segment-left 0 0); + padding-right: calc(100vw - env(viewport-segment-right 1 0)); + } + } +} + +.table-wrap, +.code-block, +.landing-code, +pre { + max-width: 100%; +} +.table-wrap { + -webkit-overflow-scrolling: touch; +} +.prose table { + max-width: none; +}