Astro

Astro

Dev server runs locally via bun run dev. Default Astro port is 4321, but multi-app workspaces (this repo has Presence + Voice + Partner forks) shift each to its own port — check astro.config.mjs for the active project, or ss -tlnp | grep 432 to find what's already running. Always use Bun — never npm or pnpm.

References are organised by shape. Simple, single-concept areas (file structure overview, assets, images) live as single files under Areas/. Low-frequency or cross-cutting areas that still belong to the Astro skill also live under Areas/ as subfolders with an entry linker_<Topic>.md — currently Areas/Language_Modes/, Areas/Hidden_Feartures/, and Areas/CI_CD/. Primary subsystems that agents open often, or that grew into broad implementation domains, get promoted to a top-level folder with an entry linker_<Topic>.md — currently Fonts/, Styles/, Design/, Niches/, Scripts/, Data/, Utils/, Content/, SEO/, Blog/, Legal/, and Debug_Validation/. Operational how-tos live under Tasks/. Operator-facing deliverables and service runbooks live under Services/, currently AI image prompt briefs and self-hosted MapLibre map handoffs. Canonical files to copy verbatim into projects (configs, schema bases, recipe code) live under Templates/ — the relevant Areas/ or per-topic doc explains the WHY and points at the template by relative path. When a new subsystem needs documenting, decide which shape fits and place it accordingly.

File naming convention — pick the right reader before opening

Docs in this skill are written for one of three readers, and the filename signals which. Open the file that matches your job. Reading the wrong-audience file wastes context on background you do not need (or, worse, makes you act on architecture trivia when you were just trying to ship a feature).

_Pipeline is reserved strictly for actual build/render pipeline internals. Architecture and debug docs use descriptive filenames and are surfaced by the relevant linker_*.md. When you find a file that mixes audiences, split it (one was image_Pipeline.md, now split into image.md + image_Pipeline.md) — don't leave the tangle for the next reader.

Areas — per-subsystem deep dives

• File structure: thin src/ overview — the three code locations (src/Scripts/ for pipeline, src/Utils/ for leaf layer, root Code/ for manual CLI tooling), the leaf-layer rule, root Code/ deep-dive, improved_Camel_Snake naming, English-first folder naming, numeric-prefix rules, high-level "where does a new file go?" routing table, add/rename checklists. Use for cross-cutting naming questions or as the entry point that routes to Scripts and Utils. The Scripts and Utils deep-dives live in their own folders.
• Assets: src/Assets/{Imgs,Fonts}/ folder layout, page/section subfolders under Imgs/, the three image-loading patterns (direct import, import.meta.glob, MDX), where local-font files live on disk, and rename/move checklist including the OG manifest path gotcha. Use when adding images or fonts (file placement), importing them into pages/components/MDX, or restructuring the assets tree.
• Images (usage): when to reach for <Picture> vs <Image>, the picture policy by surface (blog prose → Post_Img; design heroes → Hero_Picture; blog covers → Blog_Cover_Picture; blog index thumbnails → Blog_Row_Thumbnail_Picture; cards/thumbnails/portraits; galleries with separate preview vs lightbox; wide editorial panels), the Partner picture audit listing current picture surfaces with their policy verdict, the AVIF + WebP format choice, the four-knob loading playbook (loading / decoding / fetchpriority / preload) with the LCP-critical extra steps, and the common-mistakes list. Use when adding images that need to be fast on mobile, fixing LCP regressions, or deciding whether a raw <Picture> call needs explicit widths / sizes. Complements assets.md (which covers file layout) and the Fonts area (which covers font preload).
• Image pipeline (internals): the build-time machinery — how <Picture> expands to <picture> + <source> + <img>, the image.breakpoints config and the source-capping behaviour that justifies oversampling, the layout: "constrained" + responsiveStyles: false rationale (Tailwind fights Astro's inline styles), and the content-hashed cache under .astro/. Open this only when modifying breakpoints, debugging an unexpected emit, or porting the pattern to a new project. For author-facing usage open image.md instead.
• AI image prompt: write copy/paste-ready image prompt briefs under Scratch/Img_Prompts/; do not assume the agent is generating the image directly. Contains the universal content rules for every AI-generated source image — no faces of any living creature, no photo-like real-people/real-premises imagery, and the allowed-when-faceless catalogue — plus prompt-block structure, negative-prompt text, aspect-ratio guidance, and a complete Markdown example. Per-project flavor stays in Project_Manag/Docs/Brand/imagery_Brief_*.md. Use when preparing AI image prompts for the operator to paste into an image-generation tool.
• Maps: self-hosted MapLibre vector-map workflow — local/private tenant vs public tenant, tile/glyph/sprite/style ownership, tile-schema compatibility, visual style iteration, JSON export, and map-server handoff templates. Use when adding or changing a map surface, freezing a local style into hosted JSON, or coordinating CORS/static-asset requirements with the map-server operator.
• Icons: Lucide-only policy, @lucid/* Vite alias wiring (tsconfig + astro.config), Lucid_<Name> component naming, sizing via Tailwind size-*, currentColor + text-* coloring, custom-SVG home at src/Icons/<Category>/ and the two-rule explanation (src/ vs public/ gates SVGO; Icons/ specifically is org convention, not SVGO requirement), inline <svg> exemption for data-driven geometry, SVGO config recipe, and the org-wide arrow convention (arrow-right internal / arrow-up-right external / chevron-down expand). Use when adding any icon, deciding where a custom SVG belongs, or wiring SVGO into a new project.
• Page routes: the src/pages/ side of routing — [lang]/ prefix idiom, the two framework-mandatory index.astro files (root /, lang-root /{lang}/) and why every other route uses a self-naming bracket file, English-named files with URL leaves read from mdx_Info.slug per language (never German file names like kontakt.astro), the bracket-file-plus-bracket-folder pattern for list + item routes ([blog].astro next to [blog]/[post_Slug].astro), the dispatcher-over-fan-out rule with [legal_page].astro and [static_page].astro as worked examples, the getStaticPaths and href-resolver helper tables (build_Per_Lang_Index_Paths, build_Per_Lang_Slug_Paths, resolve_Top_Level_Page_Path, resolve_Top_Level_Entry_Path, build_Path), the sitemap resolver in page_File.ts honoring both bracket-file and bracket+index layouts, plus add/rename checklists. Use when adding a new top-level route, restructuring an existing one, or debugging a sitemap-resolver miss. Pairs with Slugs and IDs, which covers the content side of the same routing equation.

Language Modes — single-lang vs multi-lang project shape

• Language modes overview: entry point for every question where behavior changes based on langs_Config.supported_Langs.length. Routes to affected surfaces, multi-lang mode, and single-lang mode.
• Affected surfaces: the cross-surface checklist for language-mode changes — mandatory inputs, bare root, routing, content tree, SEO head, sitemap, lastmod, language switchers, and JSON-LD review items.
• Multi-lang mode: every real public page lives under /<lang>/; bare / is a deployment diagnostic with noindex,nofollow and server redirect ownership.
• Single-lang mode: bare / is the real public landing page; hreflang and language switchers hide; /<main_Lang>/ is redundant and excluded from the sitemap.

Fonts — own folder (grew past one cohesive file)

• Fonts overview: entry point for every font question. Routes to Bootstrap (project-setup view — the slot=category convention (Modern=sans, Elegant=serif, Precise=mono), the three real edit points, dependency map showing five consumers of font_Config.js, what auto-inherits at runtime vs. bakes at build with the Mermaid caveat, single-bundled-font and multi-font playbooks, project audit checklist), Setup (Astro Fonts API config, providers, cssVariable convention, variable chain, Tailwind preference, preload strategy, weights gotcha, checklists), Reader Settings (runtime size/spacing/font panel on blog — the data-rs-* button protocol, persistence, the inline-style-on-article.prose swap mechanism, accessibility), CJK rendering (negative-tracking ban, weight ceilings for OG, b_Cjk detection), and Performance & Debugging (what <Font /> emits in HTML, DevTools verification, build output, cache invalidation, lever ranking). Use as the routing layer for any font work; the per-topic files do the heavy lifting.

Styles — CSS organisation (own folder, grew past one cohesive file)

• Styles overview: entry point for every CSS question. Owns the Tailwind-vs-CSS rule (Tailwind by default for element-local styling; CSS when it earns its keep as reusable primitives, CSS-only behavior, source-of-truth control, reduced duplication, motion handling, or cross-component chrome). Routes to folder_Structure (two-folder Base/ + Pages// split, snake_Case + PascalCase naming, the entry-chain mechanics, the page-scoping pattern with worked examples from Partner), tokens (base semantic vars in theme.css, dependent color roles in derived_Color_Vars.css, @theme inline exports, [data-theme="dark"], name-reserved tokens, full catalogue, pre-paint theme-attribute script, why oklch is mandatory), and layers_And_Breakpoints (@layer base / components / unlayered discipline, @custom-variant breakpoint conventions, three operational checklists for adding / renaming / lifting a stylesheet). Use as the routing layer for any Styles work; the per-topic files do the heavy lifting.

Design — visual and interaction rules (own folder, grew past one cohesive file)

• Design overview: entry point for premium visual-discipline questions. The editorial layer that governs which token to reach for in markup, separate from Styles which owns the token system and the Tailwind-vs-CSS implementation rule. Routes to colors (cardinal never-raw-colors rule, monochromatic-default rule, three-tier text hierarchy, full role-token reference, contrast traps), typography roles (display-vs-functional font strategy without prescribing universal serif/sans), CTAs (primary-action scarcity, secondary action hierarchy, focus-ring color), surfaces (derived section roles, section rhythm, card/grid limits, borders), interactions (.surface-hover, compact menu/icon chrome primitives, hover/focus/current/selected/disabled/open-state semantics), radius (three allowed steps plus pill, why only three, why the larger tokens exist but aren't for page work), links (three underline patterns — inline border-b, active nav text-decoration, active filter with --primary — plus the no-underline editorial arrow-link pattern and breadcrumb exception), icons (Lucide usage, arrow semantics, no text glyph arrows, icon sizing/color/hover behavior), motion (mandatory prefers-reduced-motion global override, flat-by-default elevation rule, transition discipline of 150–250ms / ease in-out / one property, scroll-driven-animation pattern with fallback, explicit anti-patterns), and audit checklist. Use as the routing layer for general premium design work. Dentist-specific rules and commercial dentist tiers live under Niches, not Design.

Niches — domain-specific design guidance

• Niches overview: domain-specific guidance that is reusable within a niche but not universal across Astro projects. It routes to Dentist register, typography, and dentist commercial-tier notes, and explains the boundary: conceptual domain rules here, actual brand values in project docs and token files, copyable code only in Templates.

Scripts — pipeline/infrastructure code (own folder, six purpose subfolders)

• Scripts overview: entry point for every Scripts question. The six purpose folders with their runtimes (build vs browser vs separate process), the leaf-layer rule, the Code/ (root manual tooling) vs src/Scripts/Build/ (Astro build pipeline) distinction, naming, decision table, add/rename checklist. Use as the entry point for any pipeline / build / browser-boot work, and as the principle source when bootstrapping a new repo's Scripts layer.
• Astro_Frontmatter: build-time helpers called from inside .astro frontmatter — routing factories, lang providers, OG image naming, per-page data collectors. Internal Common/ + per-page subfolder pattern, Astro_Config/ for files imported by astro.config.mjs. Use when adding a build-time helper used by page templates.
• Build: plugins/integrations wired into astro.config.mjs and ec.config.mjs — remark/rehype plugins, TextMate grammars for Expressive Code, standalone integrations (HTML minifier, meta-tag fixer). Use when adding a Markdown transform, syntax highlight grammar, or build-time post-processor.
• Browser_Client: client-side hydrated JS organized by English page name (Header/, Blog/, Contact/, Common/). Three wiring patterns (eager import, <script src>, lazy await import()), internal relative imports for portable feature folders. Use when adding any code that runs in the user's browser.
• Content_Schemas: flat folder of Zod schemas — one per content collection plus shared schema_Seo.ts. Imported by src/content.config.ts. Naming, composition with the shared SEO schema, the numeric-suffix exception for ID-ranged collections. Use when adding or modifying a content collection's frontmatter shape.
• Multi_Lang_Txts: translation tables keyed by lang code, page/section/feature subfolder split, Shared/route_Txt.ts for structural route labels, assert_Translation.ts for build-time coverage validation. The crucial distinction from Utils/Common/ language metadata (strings shown to users vs. facts about languages). Use when adding UI labels, route labels, page copy, or tooltips in multiple languages.
• OG_Images (usage): the in-repo OG manifest builder — what lives in src/Scripts/OG_Images/, which project inputs live in src/Data/Og_Img/, the WebP output format, explicit split-icon config, how to wire generate_Og_Manifest() into astro.config.mjs, why the worker is external (heavy and isolated), what does NOT belong here (the <meta og:image> tag, font registration, static cards), naming conventions, and the add/rename checklist. Use when designing a new OG card template, configuring or troubleshooting a new project's OG generation, or coordinating an output-format change with the external renderer.
• OG_Images pipeline (internals): the build-time machinery — which Astro hooks fire and in what order (astro:config:setup → injectRoute for the virtual /og_Manifest.json route → build → astro:build:done moves the JSON to Cache/Og_Gen/), the manifest payload shape (meta + tasks) and what each field carries, how font roles flow from font_Config.js through og_Font_Roles into font variant payloads, and how find_Astro_Cached_Font resolves files by globbing .astro/fonts/ for {cssVariable}-{weight}-{style}-{subset}-{contenthash}.woff2. Open only when modifying manifest_Integration.js / worker_Mn.js, adding fields to the manifest payload (a contract change with the external renderer), or debugging a build that emits an empty or malformed manifest.

Data — infrastructure constants (own folder, grew past one cohesive file)

• Data overview: entry point for any infrastructure-constants question. src/Data/ holds values that change when the project's shape changes (new language, new domain, new OG contract, new dev tool) — modified by project engineers, not by feature contributors. Routes to Common (language config + BCP codes + site domain + analytics IDs + preview/demo metadata, the derived-helpers-stay-in-Data exception, the "no functions" rule), Og_Img (OG template catalogue, output config, reusable asset roles, explicit split-icon choices, theme contract), and Dev (dev-only feature-flag pattern, the audit-boundary reason for a separate Dev/ subfolder, the "all false before production" discipline, when NOT to use a dev flag — real feature flags belong in env vars, per-user toggles in settings, per-tenant toggles in customer-config repos). Includes the Data-vs-Utils mutability rule and a "Customer / tenant state" section that explicitly routes out to the project's customer-config flow (multi-tenant state does not live in src/Data/). Use as the routing layer for any Data work; the per-topic files do the heavy lifting.

Utils — leaf-layer code (own folder, has its own subfolder structure)

• Utils overview: what src/Utils/ is for (leaf-layer code — shared data + pure helpers, imported by pages, components, layouts, and Scripts; never imports back), the leaf-layer rule (Utils is the bottom of the import graph), the two kinds of content (data files vs. pure helpers), subfolder convention (Common/ always; <Feature>/ per-project), naming, decision table, add/rename checklist. Use as the entry point for any Utils question, and as the principle source when bootstrapping a new repo's Utils layer.
• Common/: what site-wide content belongs in Utils/Common/ (language metadata, owner contact, locale detection) vs. what does NOT (translation strings → Scripts/Multi_Lang_Txts/, page-specific data, DOM-touching code), file-pattern recommendations, honest note on Jav_Web's historical helper.js junk-drawer. Use when adding a site-wide constant or pure cross-cutting helper.
• Feature subfolders: when to lift a helper into Utils/<Feature>/ (the three thresholds — two callers in one feature, too-narrow for Common, multiple related helpers), Jav's Blog/ as a clean worked example, Jav's Overview/ as an honest counter-example of what NOT to copy, sub-subfolder rules, naming. Use when a feature accumulates shared helpers and you're deciding whether to promote them.

Content — content-collection conventions (own folder, org-standard pattern + two project choices)

• Content overview: entry point for any content-collection question. What Astro Content Collections solve, the three folders that cooperate (src/Content/ for files, src/Scripts/Content_Schemas/ for schemas, src/content.config.ts for registration), the org-standard pattern (flat <lang>/ siblings + path-based ID + per-language slug: field), the two remaining per-project choices (folder naming, asset co-location), the prior-question file Content vs Config vs Labels for choosing between MDX / Data/Common / Multi_Lang_Txts with an explicit gray-zone section, and a section pointing at the four Content/Templates/ copy-paste artifacts. Use as the entry point and as the principle source when bootstrapping a new repo's content layer.
• Folder structure: src/Content/<Collection>/ layout, the numeric-prefix-vs-plain-name decision with the project-count threshold for choosing, NNNN_ entry-filename prefix for sort order, Post_Assets/ co-location pattern and the glob-safety trade-off. Use when adding a collection folder or restructuring an existing one.
• Multilingual organization: the org-standard flat-language-siblings pattern ({en,de,es,fr,zh}/ under each collection), why Caddy at the proxy layer makes Astro folder asymmetry unnecessary, the loader configuration, routing via path-split + frontmatter slug, adding translations, and a short legacy carve-out for Jav_Web's 000_Landing_Page (the only collection still on en/ + translation/<lang>/ post the 2026-05-18 migration). Use when bootstrapping a multilingual project or migrating any remaining pre-migration collections.
• Slugs and IDs: the ID-vs-URL-slug distinction, the standard path-based generateId + frontmatter slug: per language pattern, the translation_key concept (filename stem as stable cross-lang identifier), the URL-slug kebab-case regex, cross-language sister-entry lookup by filename match, the extension for URLs whose middle segments also localize (per-language structural-segment map + build_Per_Lang_Slug_Paths helper — Jav_Web's implementation in route_Slugs.ts / per_Lang_Slug.ts), and the landing-page legacy carve-out with migration steps. Use when designing a multilingual project's URLs, adding a collection with multi-segment localized paths, or migrating an inherited pre-migration collection.
• Adding a new collection: end-to-end workflow checklist — apply the standard pattern, make the two per-project choices (folder naming, asset co-location), write the schema in Scripts/Content_Schemas/, register in content.config.ts, create the folder + first entry, wire to a page template via getStaticPaths, add translations, verify the build. Use as the operational playbook when introducing or removing a collection.
• Schema patterns: six reusable Zod schema field patterns Partner has converged on — status enum for draft/published workflow, the image() helper and its function-form schema: ({ image }) => footgun, cross-references via translation_key (filename, not slug) for cross-language stable links, sort_key override for non-default ordering (German umlauts, display-vs-sort name), surface/variant enum for one-template-many-looks, embedded structured frontmatter (FAQ + JSON-LD, sources/bibliography) for content that powers multiple consumers. Use when designing a new collection's schema or when an existing schema feels repetitive — these patterns let you stop re-inventing.

SEO — discoverability and structured data (own folder, grew past one cohesive file)

• SEO overview: entry point for every SEO question. The six surfaces that compose SEO and the boundary against adjacent areas (OG image generation lives in Scripts/og_Images.md; the schema_Seo.ts Zod is documented in Scripts/content_Schemas.md with a copy-paste template at Templates/seo_Schema.ts; per-language metadata lives in Data/Common). Routes to head_Tags (the full <head> block — title, description, OG with width/height/type/alt + locale:alternate, Twitter card, canonical, hreflang with two emission modes for translated-slug vs parallel-slug pages, x-default, sitemap link, theme-color light+dark, SVG+ICO favicon — plus the Layout prop contract and the strict head-order rules), JSON-LD (the per-type-builder pattern, the shared identity builder that keeps Person/Organization in sync across every schema, the og_Type dispatcher, the extra_Schemas escape hatch, a catalogue of which schema fits which page kind, per-type reference for Article/Profile/Website/Breadcrumb/FAQPage and domain schemas like LocalBusiness/MedicalProcedure, validation workflow, anti-patterns), and sitemap_And_Robots (@astrojs/sitemap integration with filter + i18n options, static vs dynamic robots.txt with the multi-language Disallow case that justifies dynamic). Includes bare-/ handling by mode: multi-lang root diagnostic vs single-lang public landing. Includes a six-step bootstrap order for standing up SEO on a new project. Use as the routing layer for any SEO work; the per-topic files do the heavy lifting.

Blog — long-form prose pages (own folder, grew past one cohesive file)

• Blog overview: entry point for every blog-implementation question. The cohesive subsystem around Post_Layout.astro and its supporting cast, plus a strict boundary against adjacent areas (reader-settings panel → Fonts/reader_Settings.md; Article + Breadcrumb + FAQPage JSON-LD → SEO/json_Ld.md; frontmatter schema → Content/schema_Patterns.md + Scripts/content_Schemas.md; OG image generation → Scripts/og_Images.md; browser scripts under Browser_Client/Blog/ → Scripts/browser_Client.md). Routes to MDX_Components/ (component map, Post_Img, links/cards, structured blocks, code/tables), post_Covers, toc_And_Chrome, markdown_Pipeline, diagrams, charts, and typography. Includes an eight-step bootstrap order for standing up a blog on a new project. Use as the routing layer for any blog work; the per-topic files do the heavy lifting.

Legal — public legal/demo compliance references (own folder)

• Legal overview: entry point for Astro legal-page implementation references. Routes first by legal layer: real public-site operator pages, fictional demo/sample pages, and final client delivery pages. Covers persistent real-operator links, German dentist-preview legal pages, final client Impressum intake, §5 DDG as the federal Impressum baseline, state/chamber follow-up checks, source registers, and implementation footguns used when editing or auditing legal MDX/content. This is not legal advice; it is the technical/source checklist agents use before changing legal pages.

CI/CD — deployment pipeline (low-frequency area folder)

• CI/CD overview: working CI/CD skill area for deploying an Astro repo via Woodpecker CI to a Linux server behind Caddy. The pipeline shape is the same across every Astro repo we ship — install → build → og_images → compress → deploy — what varies per project is the deploy target, the repo path on the agent machine, and whether the Forgejo/Woodpecker trigger path is already active. Route platform questions to .agents/skills/ci-cd/Platform/ for shared Forgejo/Woodpecker service checks, API discovery, and secrets. Route application questions to .agents/skills/ci-cd/Application/ for repo integration, repo trigger checks/setup, active deploy use, rollback, and verification. Architecture remains the explanation for local backend, external scripts, skip_clone: true, release naming, atomic symlink swap, and footguns.

Debug / Validation — cross-cutting error patterns (own folder)

• Debug/Validation overview: entry point for catching errors early and hard. The org does not use interface Props {} — ArkType replaces it with runtime validation that actually crashes. Routes to props_Validation (the full ArkType pattern — ark_Type import, props_Schema, props_Result, explicit instanceof ark_Type.errors check, naming conventions, when to apply, the deliberate-crash test technique). Use when adding props to any Astro component or layout, or when a confusing downstream crash needs tracing back to its real source.

Hidden Features — fallback and rarely-seen user surfaces (low-frequency area folder)

• Hidden Features overview: entry point for user-facing fallback surfaces that normal navigation does not expose but that still need production quality. Currently routes to Custom 404 pages, covering Astro route files, multilingual copy placement, noindex/sitemap exclusion, Caddy handle_errors, localized error bodies, expected failure modes, and a copyable Caddy template.

Tasks — operational how-tos

• Browser navigation: playwright-cli usage, dev-server discovery, where to store screenshots in Scratch/. Use when the task requires opening a page in a browser, taking screenshots, or running visual diffs.
• Accessibility audit — use the audit_Jav skill instead. Lives outside this skill because it has its own CLI surface.

Templates — canonical files to copy verbatim

Real source files an agent can drop directly into a project. Each template has its WHY documented in the corresponding Areas/ or per-topic doc — the template file is the artifact, the doc is the rationale. Templates are the source of truth: if a project needs to deviate, update the template first (with reasoning in the file header), then copy out.

• Templates/svgo_Config.ts — SVGO configuration for Astro's experimental.svgo. Copy to src/Scripts/Astro_Frontmatter/Astro_Config/svgo_Config.ts. Rationale and per-plugin reasoning in Icons § SVGO config.
• Templates/seo_Schema.ts — Zod seo_Schema composed into every content collection's frontmatter (title, description, and required og_Img). Copy to src/Scripts/Content_Schemas/schema_Seo.ts. Rationale and composition pattern in Content_Schemas; how the consumed fields surface in <head> is in SEO § head tags.
• Templates/og_Img_Schema.ts — Zod og_Img_Schema for generated OG image copy, optional template_Override, and optional image source for deliberately image-led cards. Copy to src/Scripts/Content_Schemas/schema_Og_Img.ts when a project uses the Data/Og_Img OG pipeline.