Skip to content

Commit 83e48c7

Browse files
committed
feat: add visual reference library pages
1 parent bc84ebd commit 83e48c7

7 files changed

Lines changed: 463 additions & 180 deletions

File tree

site/astro.config.mjs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ export default defineConfig({
6464
{
6565
label: 'Project Status',
6666
items: [
67+
{ label: 'Visual References', slug: 'project/visual-references' },
6768
{ label: 'Visual Atlas', slug: 'project/visual-atlas' },
6869
{ label: 'Changelog', slug: 'project/changelog' },
6970
{ label: 'Missing Features', slug: 'project/missing-features' },
Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8" />
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
6+
<title>A7 Examples Reference</title>
7+
<link rel="preconnect" href="https://fonts.googleapis.com">
8+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
9+
<link href="https://fonts.googleapis.com/css2?family=Instrument+Serif&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
10+
<style>
11+
:root {
12+
--bg:#fff8f5; --surface:#fff; --surface2:#fff1eb; --text:#2a1f1b; --text-dim:#7a665e;
13+
--border:rgba(82,44,31,.14); --accent:#b24d1f; --mint:#1d8860; --amber:#b57713; --rose:#b33b5e;
14+
--font:'Instrument Serif',serif; --mono:'IBM Plex Mono',ui-monospace,monospace;
15+
}
16+
@media (prefers-color-scheme: dark) {
17+
:root {
18+
--bg:#1b1210; --surface:#261a17; --surface2:#30221e; --text:#f7e7df; --text-dim:#c8a99d;
19+
--border:rgba(243,205,187,.2); --accent:#ff9a6f; --mint:#72d7b1; --amber:#ffc781; --rose:#ff9fbd;
20+
}
21+
}
22+
*{box-sizing:border-box} body{margin:0;padding:36px;background:
23+
radial-gradient(920px 360px at 12% -10%, rgba(178,77,31,.18), transparent 58%),
24+
radial-gradient(780px 340px at 90% 0%, rgba(29,136,96,.16), transparent 56%),var(--bg);
25+
color:var(--text);font-family:var(--font)}
26+
.wrap{max-width:1050px;margin:0 auto}
27+
h1{margin:0;font-size:clamp(2rem,4vw,3rem);line-height:1.02;letter-spacing:-.01em}
28+
.sub{margin:.6rem 0 1.4rem;color:var(--text-dim);font-family:var(--mono);font-size:12px}
29+
.stats{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:10px;margin:0 0 12px}
30+
.stat{border:1px solid var(--border);border-radius:12px;background:var(--surface);padding:11px 12px}
31+
.stat strong{display:block;font-size:1.24rem;line-height:1.1;margin-bottom:2px}
32+
.stat span{font-family:var(--mono);font-size:10px;letter-spacing:.12em;text-transform:uppercase;color:var(--text-dim)}
33+
.table-wrap{border:1px solid var(--border);border-radius:14px;overflow:hidden;background:var(--surface)}
34+
.table-scroll{overflow:auto}
35+
table{width:100%;border-collapse:collapse;font-size:13px;min-width:820px}
36+
th{position:sticky;top:0;background:var(--surface2);text-align:left;padding:12px 13px;border-bottom:2px solid var(--border);font-family:var(--mono);font-size:10px;letter-spacing:.12em;text-transform:uppercase;color:var(--text-dim)}
37+
td{padding:12px 13px;border-bottom:1px solid var(--border);vertical-align:top}
38+
tbody tr:nth-child(even){background:rgba(178,77,31,.06)}
39+
tbody tr:hover{background:rgba(29,136,96,.09)}
40+
.status{display:inline-flex;align-items:center;gap:6px;border:1px solid transparent;border-radius:999px;padding:3px 8px;font-family:var(--mono);font-size:10px;letter-spacing:.08em;text-transform:uppercase;white-space:nowrap}
41+
.done{color:var(--mint);background:color-mix(in srgb,var(--mint) 14%, transparent 86%);border-color:color-mix(in srgb,var(--mint) 32%, transparent 68%)}
42+
.study{color:var(--amber);background:color-mix(in srgb,var(--amber) 16%, transparent 84%);border-color:color-mix(in srgb,var(--amber) 32%, transparent 68%)}
43+
.advanced{color:var(--rose);background:color-mix(in srgb,var(--rose) 14%, transparent 86%);border-color:color-mix(in srgb,var(--rose) 32%, transparent 68%)}
44+
code{font-family:var(--mono);font-size:11px;background:rgba(178,77,31,.1);padding:1px 5px;border-radius:4px}
45+
@media (max-width:860px){body{padding:22px}.stats{grid-template-columns:repeat(2,minmax(0,1fr))}}
46+
</style>
47+
</head>
48+
<body>
49+
<div class="wrap">
50+
<h1>A7 Examples Reference</h1>
51+
<p class="sub">Topic map + progression guidance for all runnable examples.</p>
52+
<div class="stats">
53+
<div class="stat"><strong>36</strong><span>Total Files</span></div>
54+
<div class="stat"><strong>5</strong><span>Learning Tracks</span></div>
55+
<div class="stat"><strong>14</strong><span>Core Syntax Files</span></div>
56+
<div class="stat"><strong>8</strong><span>Larger Programs</span></div>
57+
</div>
58+
<div class="table-wrap"><div class="table-scroll">
59+
<table aria-label="A7 example reference matrix">
60+
<thead><tr><th>Track</th><th>Goal</th><th>Start Files</th><th>Deep Files</th><th>Readiness</th></tr></thead>
61+
<tbody>
62+
<tr>
63+
<td>Fundamentals</td>
64+
<td>Syntax, declarations, operators, literals</td>
65+
<td><code>001_hello</code>, <code>002_var</code>, <code>004_func</code></td>
66+
<td><code>015_types</code>, <code>019_literals</code>, <code>020_operators</code></td>
67+
<td><span class="status done">Core</span></td>
68+
</tr>
69+
<tr>
70+
<td>Control Flow</td>
71+
<td>Branching, loops, match, defer behavior</td>
72+
<td><code>005_for_loop</code>, <code>006_if</code>, <code>007_while</code></td>
73+
<td><code>008_switch</code>, <code>021_control_flow</code>, <code>024_defer</code></td>
74+
<td><span class="status done">Core</span></td>
75+
</tr>
76+
<tr>
77+
<td>Data + Memory</td>
78+
<td>Structs, enums, unions, arrays, pointers</td>
79+
<td><code>009_struct</code>, <code>010_enum</code>, <code>012_arrays</code></td>
80+
<td><code>013_pointers</code>, <code>016_unions</code>, <code>035_matrix</code></td>
81+
<td><span class="status study">Intermediate</span></td>
82+
</tr>
83+
<tr>
84+
<td>Abstractions</td>
85+
<td>Generics, methods, function pointers, callbacks</td>
86+
<td><code>014_generics</code>, <code>017_methods</code></td>
87+
<td><code>022_function_pointers</code>, <code>027_callbacks</code></td>
88+
<td><span class="status study">Intermediate</span></td>
89+
</tr>
90+
<tr>
91+
<td>Programs</td>
92+
<td>Multi-step examples and complete workflows</td>
93+
<td><code>029_sorting</code>, <code>030_calculator</code></td>
94+
<td><code>031_number_guessing</code>, <code>033_fibonacci</code>, <code>034_string_utils</code></td>
95+
<td><span class="status advanced">Advanced</span></td>
96+
</tr>
97+
</tbody>
98+
</table>
99+
</div></div>
100+
</div>
101+
</body>
102+
</html>
Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8" />
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
6+
<title>A7 Language Map</title>
7+
<link rel="preconnect" href="https://fonts.googleapis.com">
8+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
9+
<link href="https://fonts.googleapis.com/css2?family=Chakra+Petch:wght@500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
10+
<style>
11+
:root {
12+
--bg:#f6faff;--surface:#fff;--surface2:#eef4ff;--text:#1b2737;--text-dim:#62758c;
13+
--border:rgba(24,58,95,.14);--accent:#2a62b2;--green:#1d8a67;--orange:#ba7518;--purple:#7b56c8;
14+
--font:'Chakra Petch',system-ui,sans-serif;--mono:'IBM Plex Mono',ui-monospace,monospace;
15+
}
16+
@media (prefers-color-scheme: dark){
17+
:root{--bg:#101723;--surface:#172131;--surface2:#202d42;--text:#eaf1ff;--text-dim:#9fb1ca;--border:rgba(184,208,240,.2);--accent:#8bb7ff;--green:#7adfb8;--orange:#ffc685;--purple:#c7b2f3}
18+
}
19+
*{box-sizing:border-box}body{margin:0;padding:36px;background:radial-gradient(900px 340px at 14% -8%, rgba(42,98,178,.2), transparent 58%),radial-gradient(840px 360px at 90% 2%, rgba(29,138,103,.16), transparent 54%),var(--bg);color:var(--text);font-family:var(--font)}
20+
.wrap{max-width:1080px;margin:0 auto}
21+
h1{margin:0;font-size:clamp(2rem,4vw,3rem);line-height:1.02;letter-spacing:-.01em}
22+
.sub{margin:.6rem 0 1.3rem;color:var(--text-dim);font-family:var(--mono);font-size:12px}
23+
.grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:12px}
24+
.card{border:1px solid var(--border);border-radius:12px;background:var(--surface);padding:14px}
25+
.label{font-family:var(--mono);font-size:10px;letter-spacing:.13em;text-transform:uppercase;color:var(--text-dim);margin-bottom:8px}
26+
.title{font-size:1.18rem;line-height:1.2;margin:0 0 8px}
27+
.desc{margin:0;color:var(--text-dim);line-height:1.55}
28+
ul{margin:.55rem 0 0;padding-left:14px} li{margin:.22rem 0;color:var(--text-dim)}
29+
@media (max-width:900px){body{padding:22px}.grid{grid-template-columns:1fr}}
30+
</style>
31+
</head>
32+
<body>
33+
<div class="wrap">
34+
<h1>A7 Language Map</h1>
35+
<p class="sub">Visual breakdown of core language guide domains and where they connect in the docs.</p>
36+
<div class="grid">
37+
<article class="card"><div class="label">Types</div><h2 class="title">Type System Core</h2><p class="desc">Primitives, composites, aliases, references, and pointer semantics define the shared foundation for all expressions.</p><ul><li><code>language/types</code></li><li><code>language/declarations-and-expressions</code></li></ul></article>
38+
<article class="card"><div class="label">Execution</div><h2 class="title">Control + Functions</h2><p class="desc">Control flow rules combine with function declarations, method patterns, and return-path semantics.</p><ul><li><code>language/control-flow</code></li><li><code>language/functions</code></li></ul></article>
39+
<article class="card"><div class="label">Abstractions</div><h2 class="title">Generics + Modules</h2><p class="desc">Generic constraints and module boundaries shape reuse, API design, and compile-time specialization.</p><ul><li><code>language/generics</code></li><li><code>language/modules-and-visibility</code></li></ul></article>
40+
<article class="card"><div class="label">Runtime</div><h2 class="title">Memory + Builtins</h2><p class="desc">Heap lifecycle, defer behavior, and intrinsic operator/builtin semantics govern runtime safety and performance.</p><ul><li><code>language/memory-management</code></li><li><code>language/builtins-and-operators</code></li></ul></article>
41+
<article class="card"><div class="label">Formalism</div><h2 class="title">Grammar + Diagnostics</h2><p class="desc">Grammar summary and diagnostics pages provide quick parse-level and error-model grounding during implementation.</p><ul><li><code>language/grammar-summary</code></li><li><code>language/diagnostics-and-limits</code></li></ul></article>
42+
<article class="card"><div class="label">Bridge</div><h2 class="title">Examples + Pipeline</h2><p class="desc">Examples validate language behavior through pipeline stages and generated backend output expectations.</p><ul><li><code>examples/by-topic</code></li><li><code>compiler/pipeline-overview</code></li></ul></article>
43+
</div>
44+
</div>
45+
</body>
46+
</html>
Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8" />
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
6+
<title>A7 Pipeline Reference</title>
7+
<link rel="preconnect" href="https://fonts.googleapis.com">
8+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
9+
<link href="https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:wght@500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
10+
<style>
11+
:root {
12+
--bg:#f1fcf8; --surface:#ffffff; --surface2:#e8faf3; --text:#17342b; --text-dim:#4f7b6e;
13+
--border:rgba(12,63,50,.14); --accent:#0f7b66; --accent-dim:rgba(15,123,102,.12);
14+
--blue:#196baf; --amber:#ba7318; --rose:#b2425e;
15+
--font:'Bricolage Grotesque',system-ui,sans-serif; --mono:'IBM Plex Mono',ui-monospace,monospace;
16+
}
17+
@media (prefers-color-scheme: dark) {
18+
:root {
19+
--bg:#0f1d1a; --surface:#152824; --surface2:#1a312c; --text:#e8f7f1; --text-dim:#9bc6b7;
20+
--border:rgba(186,230,214,.2); --accent:#65d0b2; --accent-dim:rgba(101,208,178,.16);
21+
--blue:#82c8ff; --amber:#ffcd8d; --rose:#f3a0b5;
22+
}
23+
}
24+
*{box-sizing:border-box} body{margin:0;padding:36px;background:
25+
radial-gradient(900px 360px at 10% -8%, var(--accent-dim), transparent 60%),
26+
radial-gradient(860px 360px at 92% 0%, rgba(186,115,24,.16), transparent 58%), var(--bg);
27+
color:var(--text); font-family:var(--font);}
28+
.wrap{max-width:1100px;margin:0 auto}
29+
h1{margin:0;font-size:clamp(2rem,4vw,3.1rem);line-height:1.03;letter-spacing:-.02em}
30+
.sub{margin:.65rem 0 1.4rem;color:var(--text-dim);font-family:var(--mono);font-size:12px}
31+
.panel{background:var(--surface);border:1px solid var(--border);border-radius:14px;padding:16px}
32+
.legend{display:flex;gap:12px;flex-wrap:wrap;margin:0 0 10px}
33+
.legend span{font-family:var(--mono);font-size:11px;color:var(--text-dim);display:flex;align-items:center;gap:6px}
34+
.dot{width:10px;height:10px;border-radius:999px;display:inline-block}
35+
.dot-a{background:var(--accent)} .dot-b{background:var(--blue)} .dot-c{background:var(--amber)} .dot-d{background:var(--rose)}
36+
.mermaid-wrap{position:relative;border:1px solid var(--border);border-radius:12px;background:var(--surface2);padding:30px 18px;overflow:auto}
37+
.mermaid-wrap .mermaid{display:flex;justify-content:center;transition:transform .2s ease;transform-origin:top center;min-width:680px}
38+
.zoom{position:absolute;top:8px;right:8px;display:flex;gap:2px;padding:2px;background:var(--surface);border:1px solid var(--border);border-radius:8px;z-index:8}
39+
.zoom button{width:28px;height:28px;border:0;border-radius:6px;background:transparent;color:var(--text-dim);font-family:var(--mono);cursor:pointer}
40+
.zoom button:hover{background:var(--accent-dim);color:var(--text)}
41+
.mermaid-wrap.is-zoomed{cursor:grab}.mermaid-wrap.is-panning{cursor:grabbing;user-select:none}
42+
.mermaid .nodeLabel{font-family:var(--font)!important;font-size:15px!important;color:var(--text)!important}
43+
.mermaid .edgeLabel{font-family:var(--mono)!important;font-size:12px!important;color:var(--text-dim)!important}
44+
.mermaid .edgeLabel rect{fill:var(--bg)!important}
45+
</style>
46+
</head>
47+
<body>
48+
<div class="wrap">
49+
<h1>A7 Pipeline Reference</h1>
50+
<p class="sub">Compiler stage map with semantic passes and output artifacts.</p>
51+
<section class="panel">
52+
<div class="legend">
53+
<span><i class="dot dot-a"></i>Frontend parsing</span>
54+
<span><i class="dot dot-b"></i>Semantic analysis</span>
55+
<span><i class="dot dot-c"></i>Preprocess/codegen</span>
56+
<span><i class="dot dot-d"></i>Artifacts</span>
57+
</div>
58+
<div class="mermaid-wrap" id="m1">
59+
<div class="zoom"><button data-z="in">+</button><button data-z="out"></button><button data-z="reset"></button></div>
60+
<pre class="mermaid">
61+
graph LR
62+
SRC["source .a7"] --> TOK["tokenizer"] --> PAR["parser"] --> AST["AST"]
63+
AST --> NR["name resolution"] --> TC["type checker"] --> SV["semantic validator"]
64+
SV --> AP["AST preprocessor"] --> ZIG["zig backend"]
65+
ZIG --> OUT[".zig output"]
66+
AP -. doc mode .-> DOC["markdown report"]
67+
TOK -. mode .-> MT["tokens output"]
68+
PAR -. mode .-> MA["AST output"]
69+
SV -. mode .-> MS["semantic report"]
70+
71+
classDef a fill:#0f7b6624,stroke:#0f7b66,stroke-width:1.5px
72+
classDef b fill:#196baf24,stroke:#196baf,stroke-width:1.5px
73+
classDef c fill:#ba731824,stroke:#ba7318,stroke-width:1.5px
74+
classDef d fill:#b2425e24,stroke:#b2425e,stroke-width:1.5px
75+
76+
class SRC,TOK,PAR,AST a
77+
class NR,TC,SV b
78+
class AP,ZIG c
79+
class OUT,DOC,MT,MA,MS d
80+
</pre>
81+
</div>
82+
</section>
83+
</div>
84+
<script type="module">
85+
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
86+
import elkLayouts from 'https://cdn.jsdelivr.net/npm/@mermaid-js/layout-elk/dist/mermaid-layout-elk.esm.min.mjs';
87+
mermaid.registerLayoutLoaders(elkLayouts);
88+
const dark = window.matchMedia('(prefers-color-scheme: dark)').matches;
89+
mermaid.initialize({ startOnLoad:true, theme:'base', layout:'elk', look:'classic', themeVariables:{
90+
primaryColor: dark ? '#1a312c' : '#e8faf3', primaryBorderColor: dark ? '#65d0b2' : '#0f7b66', primaryTextColor: dark ? '#e8f7f1' : '#17342b',
91+
secondaryColor: dark ? '#1d2f43' : '#e7f2ff', secondaryBorderColor: dark ? '#82c8ff' : '#196baf', secondaryTextColor: dark ? '#e8f7f1' : '#17342b',
92+
tertiaryColor: dark ? '#362b1f' : '#fff2df', tertiaryBorderColor: dark ? '#ffcd8d' : '#ba7318', tertiaryTextColor: dark ? '#e8f7f1' : '#17342b',
93+
lineColor: dark ? '#89b7a9' : '#4f7b6e', fontSize:'15px', fontFamily:'Bricolage Grotesque'
94+
}});
95+
const wrap=document.getElementById('m1'); const mer=wrap.querySelector('.mermaid'); const zoom=wrap.querySelector('.zoom');
96+
let s=1, p=false, sx=0, sy=0, sl=0, st=0;
97+
const apply=()=>{mer.style.transform=`scale(${s})`; wrap.classList.toggle('is-zoomed', s>1.01)};
98+
zoom.addEventListener('click',(e)=>{const b=e.target.closest('button'); if(!b)return; const z=b.dataset.z; if(z==='in')s=Math.min(3,s+.14); if(z==='out')s=Math.max(.7,s-.14); if(z==='reset')s=1; apply();});
99+
wrap.addEventListener('wheel',(e)=>{if(!(e.ctrlKey||e.metaKey))return; e.preventDefault(); s += e.deltaY<0?.08:-.08; s=Math.max(.7,Math.min(3,s)); apply();},{passive:false});
100+
wrap.addEventListener('mousedown',(e)=>{if(s<=1.01||e.button!==0)return; p=true; wrap.classList.add('is-panning'); sx=e.pageX-wrap.offsetLeft; sy=e.pageY-wrap.offsetTop; sl=wrap.scrollLeft; st=wrap.scrollTop;});
101+
window.addEventListener('mouseup',()=>{p=false; wrap.classList.remove('is-panning');});
102+
wrap.addEventListener('mousemove',(e)=>{if(!p)return; e.preventDefault(); const x=e.pageX-wrap.offsetLeft; const y=e.pageY-wrap.offsetTop; wrap.scrollLeft=sl-(x-sx); wrap.scrollTop=st-(y-sy);});
103+
apply();
104+
</script>
105+
</body>
106+
</html>

site/src/content/docs/project/visual-atlas.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ description: Interactive visual overview of docs architecture, pipeline flow, an
88
The visual documentation atlas is available as a self-contained interactive page:
99

1010
- [Open A7 Docs Atlas](/a7-py/visuals/a7-docs-atlas.html)
11+
- [Browse all visual references](/project/visual-references/)
1112

1213
## What it includes
1314

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: Visual References
3+
description: Curated visual docs pages for architecture, pipeline, examples, and language map.
4+
---
5+
6+
These semi-static visual pages complement the written docs with quick orientation views.
7+
8+
## Library
9+
10+
- [A7 Docs Atlas](/a7-py/visuals/a7-docs-atlas.html)
11+
- [A7 Pipeline Reference](/a7-py/visuals/a7-pipeline-reference.html)
12+
- [A7 Examples Reference](/a7-py/visuals/a7-examples-reference.html)
13+
- [A7 Language Map](/a7-py/visuals/a7-language-map.html)
14+
15+
## Recommended usage
16+
17+
1. Start with Docs Atlas for the full overview.
18+
2. Use Pipeline Reference during compiler-stage debugging.
19+
3. Use Examples Reference to choose learning paths.
20+
4. Use Language Map when editing spec/guide pages.

0 commit comments

Comments
 (0)