Site design system

Reference and evidence

The canonical visual reference is the supplied Hub Editorial Studio, inspected on 2026-09-07. Astro imports its framework-independent tokens and local fonts directly; site styles map existing names to those tokens instead of keeping a second palette. Both theme attributes stay synchronized.

The standalone React showcase is reference material, not the site’s runtime or a translated lesson. The Astro site uses native controls and small JavaScript modules. Product logos and the supplied icon-library cover are not repurposed as the curriculum’s identity. Original curriculum illustrations and monochrome diagrams retain their aspect ratios and colors in both themes.

Observed design tokens

The accents identify navigation/card families and decorative rules, not diagram semantics. Every Mermaid diagram retains the repository’s white/ice/gray/black palette and accessible legend. The hero, the film gallery and the footer stay dark in both themes; they share one inverted token scope rather than three hand-written palettes, so their ink, rules and surfaces come from the same tokens as the rest.

The hero watermark uses the original Paula Silva logo at 8% opacity. Its colors and aspect ratio stay intact: no text approximation, rotation or color filter. It is a decorative CSS background, not an interactive element or accessible text.

Mobile browsers retain page zoom and use 44 px navigation targets. Search fields and studio selectors use 16 px text on narrow screens and touch devices. Long source paths wrap inside search results, and dialogs follow the dynamic viewport with contained scrolling; wide tables and code scroll within their own regions instead of widening the page.

Typography and layout

The reference uses Inter for prose and JetBrains Mono for small uppercase labels. Both fonts are bundled locally, with system fallbacks and no third-party font request. Their Inter license and JetBrains Mono license are included.

• Sticky, compact masthead with independent navigation, locale and theme controls.
• Dark introductory hero, strong editorial heading, restrained accent rules.
• Wide but bounded content container; readable article width and generous spacing.
• Square or subtly rounded cards, thin borders and minimal shadow.
• Sidebar navigation for learning documents; on-page table of contents for long guides.
• Responsive grids collapse into a single column without hiding essential content.

Reading text stays at the 16 px body token on narrow screens. Navigation, filters, source actions and learning controls use the 44 px touch-target token. The six section links stay visible down to 1200 px, where the masthead switches to its compact menu; the two longest section titles use short navigation labels so the Spanish and Portuguese bars fit on one row. Code blocks keep space above their first line for the copy control. A learning document uses a wider column than a book measure, because it carries diagrams, tables and code as well as prose; the prose itself keeps a bounded measure inside that column.

Exact spacing outside the inspected reference CSS is an implementation choice, not a claim of pixel-perfect reproduction.

Components

• Three real locale routes: English, Spanish and Brazilian Portuguese.
• Same-document language links, never a switch that always returns to the homepage.
• Search scoped to the selected language, with clearly labeled original-source entries.
• Repository explorer with all source files, code/data previews and original downloads.
• Notices for legacy material, untranslated executable examples and preserved licenses.
• Visible keyboard focus, skip link, layered mobile menu and reduced-motion behavior.
• Card feedback answers hover, keyboard focus and touch; the lift is reserved for a real pointer.
• Search ranks lessons above repository paths and caps the paths so they cannot bury an answer.
• Windows High Contrast keeps every state that colour alone would carry.

Content rules

Design for the first-time learner

The root README and Start here must lead to one runnable first exercise before presenting the complete library. Learning order labels required, optional, advanced and maintainer work. Downloads provides per-lab materials instead of requiring a full checkout.

Every primary lesson should answer: what am I learning, why would I use it, what must already work, where do I run the command, what result should I observe, and how do I recover? The finish must be an evidence checklist, not a marketing claim.

Markdown editorial pattern

• One primary title and a short purpose statement before the details.
• A briefing table for scope, prerequisites, time estimate and expected evidence.
• Semantic headings and links that describe their destination.
• GFM notes, tips and warnings for actual decisions; do not rely on color alone.
• Numbered actions, copyable commands with working-directory context, and checkpoints.
• A concept-specific illustration or diagram with meaningful alternative text.
• Required versus optional execution clearly separated, especially for live services.
• Next-step navigation and a safe reset that protects other projects.

Illustrations explain a concept; they do not substitute for runnable evidence. Historical interface captures must not imply current feature availability. The professional hands-on track stays non-fantasy; stories remain in adventures.

Translate current learning prose, navigation and document metadata. Preserve identifiers, commands, code samples, exact data and URLs so exercises remain reproducible. Historical material and machine-consumed files remain available as original source with a localized notice, not falsely labeled as translated lessons.

No automatic third-party translation, model request, analytics, or credential is required to read the site.

Build and verification

Use Astro’s static build, validated content collections and GitHub Actions publication. Missing translations, broken local links, incomplete source coverage and invalid locale routes are build errors rather than silent English fallbacks.

Verify desktop and mobile navigation, keyboard operation, same-page language switching, localized search, source downloads and Mermaid rendering before publishing.

The publishing guide documents the build, generated files and official Astro/GitHub references. The layout is original; it does not require a third-party theme or client-side application framework.

Interaction and motion

The language selector remains visible in the masthead at every viewport size, and the footer names the three languages in full. Switching language preserves the document, heading fragment and active library filters.

The hero prioritizes the title and learning actions without a side panel. The home page shows the real adventure path: six levels built from the published catalog, each naming its lessons. The adventure catalog repeats that order as bands of covers, and the hands-on index groups its labs the way the lab catalog already groups them, with each card naming its stack. Every lesson opens with a briefing built from its own frontmatter: the capability it teaches, its level, its estimate and its status. The library combines topic filtering, localized search and optional reading marks.

The lesson ending separates marking this page from managing all reading marks. Marking is optional, never blocks the next lesson, and never proves that a lab or test passed. Management is a secondary disclosure with a cancel-first confirmation; reset removes only this site’s reading marks, not evidence checklists or lab files. Storage failures show an unavailable state instead of a zero or a success message, with reload and reset available for recovery. Source and contribution links remain in a separate native disclosure that works without JavaScript.

The homepage offers two illustrated entry points, adventures and professional hands-on labs, before the detailed progression. The full overview remains in a native disclosure rather than repeating the entire introduction. The footer uses a compact maintainer illustration and separates learning links, language choices, credits and font licenses; decorative diagrams do not compete with the lesson.

Entrance animations, one-time section reveals, bounded count transitions, card feedback and a scroll progress indicator add motion without a canvas or animation framework. Reduced-motion preferences disable the effects. Essential content stays readable without JavaScript; native content disclosures still work.

Selected lessons open with a mechanism scene: an original inline SVG that draws the model it teaches in reading order, followed by three short captions. The scene is armed when it scrolls into view and can be replayed; under reduced motion it appears complete and still. The home page carries the same kind of scene for the Ask, Plan, Agent, Review and Evidence loop, including the return path an unresolved gap takes. Long lesson pages carry a session rail that numbers the sections, marks the ones already passed and shows the current position. Every adventure and every lab carries a retrieval check before the section where evidence is recorded: nothing is preselected, the chosen option explains why it holds or fails, and without JavaScript every option and its reason stay readable. The evidence checklist itself can be ticked during the lab; ticks live in that browser only and never stand in for a command that ran. A lesson closes with a card for the next lesson in the path rather than a bare link, and page to page navigation cross-fades where the browser supports it. All of this stops when the reader asks for reduced motion.

Mechanism diagrams initially fit their container, including on narrow screens. Node labels wrap inside padded bounds, and captions stack according to the figure’s width rather than the viewport. An explicit enlarge control reveals the diagram at reading size, with a named, keyboard-focusable horizontal scroll region and localized guidance; fitting it back resets horizontal scrolling. These manual controls still work with reduced motion. Without JavaScript, the complete overview and captions remain visible.

Integrated practice studio

The practice studio is available in all three languages, linked from the homepage, masthead, footer, learning navigation and related lessons. Its tabs use stable fragments, keyboard navigation and readable non-JavaScript fallbacks. Search and the sitemap include the page.

• Workflow: explicit play, pause, single step, playback speed, reset and a review failure that blocks the final evidence stage. Playback pauses on a hidden page or when the learner leaves the workflow tab; nothing plays automatically.
• Context: a bounded selection exercise with missing, over-budget, distracting and focused states. The displayed units are synthetic, not model tokens.
• Verification: three fixed JavaScript fixture checks run in the browser against incomplete or corrected implementations. Changing the implementation invalidates previous results. The module does not evaluate arbitrary code or call a service.

Simulation state is temporary and is never stored as course completion. Reading marks remain separate, explicitly selected browser-local state and synchronize between tabs. No simulation claims that a real agent, terminal or course lab ran.

Image and icon handling

The site’s line icons are small original SVGs with a consistent stroke and decorative semantics; controls retain text or accessible names. Card illustrations are decorative beside their lesson titles. Article images keep their descriptive alternative text, can be enlarged in a keyboard-operable dialog, and retain an original-image link. Closing the dialog restores focus. No image is inverted, stretched or recolored to simulate dark mode.

Selected lessons also carry a contextual visual reference from the supplied collection. Each reference retains its aspect ratio and has a localized description of what to notice. Interface captures are snapshots, not guarantees of current feature or model availability. Benchmark screenshots and stock photography with unverified reuse rights are not promoted into lesson evidence or decorative covers.

The narrow layout exposes learning navigation as a native disclosure instead of removing it. Primary controls use the design system’s minimum touch target. Reduced-motion preferences disable movement without disabling the learning tools.

Adventure covers and animated montages

The 14 adventures use optimized 1456 x 832 WebP covers received from the maintainer, while their original localized SVG concept illustrations remain in native disclosures. The cover inventory records each pairing. Fantasy artwork is limited to the adventure track; hands-on illustrations are unchanged.

The homepage and adventure catalog include 3 silent, 10-second animated montages in a full-width editorial section. Each has a first-frame poster and a localized visual description. Pointer hover or keyboard focus starts a scene without a separate play button; leaving the scene restores the poster. Touch users can tap the image to toggle playback. Only one clip plays at a time.

No video source is loaded before interaction. Page hiding and a switch to reduced motion restore the poster without automatic resumption. With reduced motion, hover and focus remain still and an explicit tap or activation is required. Direct links remain available without JavaScript.

Original JPEGs and MP4s are preserved; optimized covers, silent playback copies and posters are separate assets. The media inventory maps the files, and the video notes describe playback limits. Generated scenes are visual introductions, not UI screenshots or proof that a lab, cloud agent or SDK session ran.