Websites entwickeln

Best Practices für ADDXION Marketing-Sites — Astro, Neon Consumer, SEO, Architektur.

Für wen gilt das

Consumer	Repo	Stack
addxion.com	addxion-com	Astro 5, Bun, Neon, CF Pages
süper	süper	Next.js, Neon, CF (öffentliche Surfaces: Login)
addxion.ai	addxion-ai	TanStack Start (öffentliche Surfaces: Guest/Login)
Externe Referenz	improdent	Astro 6, Tailwind Plus, statisches Hosting (nicht ADDXION-Standard)

Ökosystem-Grenzen: Repo Boundaries. Nach Package-Änderungen: Docs-Sync.

Repo-Setup

Geschwister-Repos:

GitHub/
  addxion-neon/
  addxion-docs/
  addxion-com/

"@addxion/neon": "file:../addxion-neon/packages/neon",
"@addxion/components": "file:../addxion-neon/packages/components"

Consumer nutzen @addxion/neon, nicht @addxion/core (interne Engine).

cd addxion-com
bun install
bun run dev    # :4123 — Marketing; /docs/* proxied zu addxion-docs :4321

CSS-Schichten

Details: CSS Architecture.

Datei	Inhalt
`brand.css`	Marken-Tokens (`ink`, `cream`, `electric`, Fonts) — SSOT in addxion-com
`site.css`	`tailwindcss` + Inter + `brand.css` + Marketing-Komponenten (`.btn`, `.wrapper`)
`cp-page.css`	Optional: Produktseiten-Layout (CallPilot, Automation) — analog süper-Kurse-Layer
`neon.css`	`@import "@addxion/neon/styles"` — nur wenn Neon-Primitives mit `tw:` gebraucht werden

Marketing-Layout importiert nur site.css. neon.css nicht global laden, wenn die Seite unpräfixiertes Tailwind nutzt.

Typografie

SSOT: Typografie — Font-Stack und Type Scale.

Fonts

Keine Google Fonts CDN. Inter self-hosted:

@import "@addxion/neon/fonts/inter.css";

System-Schrift (SF Pro) zuerst, Inter als Fallback. Stack und Scale-Tokens in Consumer-brand.css setzen, nicht in addxion-neon.

Scale (Marketing)

Größen/Tracking nach improdent-Metriken; Familie bleibt ADDXION-Stack (--font-display: var(--font-sans)).

Surface	Rolle	Token / Muster
Hero-Headline	Display	`--text-display`, tracking `-0.04em`, weight `400`
Section-Titel	Heading	`--text-heading` / `--text-heading-lg`, tracking `-0.03em`, weight `400`
Fließtext	Body	`--text-body` (`1rem` / `1.75rem`), optional `--text-body-lg`
Eyebrow / Meta	UI	`text-sm`, `font-semibold` oder `font-medium`

Consumer: addxion-com; öffentliche Surfaces von addxion-ai (Guest/Login). App-interne PageHeader-Titel nutzen --text-title (UI), nicht Display.

Komponenten-Architektur

Bei wenigen Seiten reicht eine flache Struktur (pages/ + components/). Ab etwa 3–4 Seiten lohnt sich die Schichtung aus improdent:

src/pages/*.astro          → dünn: Meta, Layout, Route-Komponente
src/components/routes/     → AppShell + Page-Entry (React)
src/components/content/    → Section-Zusammenstellung
src/components/shell/      → Header, Footer, wiederkehrendes Chrome
src/lib/*.ts               → statische Daten (Produkte, Team, Jobs)

Regel: Astro-Seiten bleiben kurz. Wiederkehrende Logik und Daten gehören in lib/ oder Shell-Komponenten, nicht in jede Page kopiert.

addxion-com hat aktuell 2 Marketing-Pages — Refactor auf routes/content/shell ist optional, das Muster gilt für Wachstum.

Marketing Header vs. App PageHeader

Chrome	Package	Inhalt	Mount
Marketing Header	`@addxion/components` (`MarketingHeader`)	Logo, öffentliche Nav, CTAs	nur öffentliche Layouts
App PageHeader	`@addxion/shell`	Seitentitel, Command, App-Tabs	Auth-App, geschützte Routen

Shared-Struktur in @addxion/components/react/MarketingHeader (Sticky, Backdrop, Desktop-Nav, Mobile-Drawer). Inhalt und Marke bleiben im Consumer: dünner SiteHeader-Wrapper mit Logo, Nav-Array, Actions und Brand-Klassen.

import { MarketingHeader } from '@addxion/components/react'

Referenz-Consumer:

Repo	Wrapper	Mount
addxion-com	`src/components/shell/SiteHeader.tsx`	`Header.astro` (`client:load`)
addxion-ai	`src/components/marketing/site-header.tsx`	`_guest/route.tsx`
süper	`src/components/layout/SiteHeader.tsx`	`(super)/login/layout.tsx`

Nicht in _auth, (protected) oder anderen App-Layouts mounten — dort bleibt @addxion/shell PageHeader. Keine Marken-Tokens (cream, ink, …) im Package; Brand-Klassen nur im Wrapper.

Hydration

React-Inseln gezielt hydratisieren:

Directive	Einsatz
`client:load`	Above-the-fold: Header, Hero, AppShell
`client:visible`	Below-the-fold: Carousels, Stats, Feature-Grids
`client:idle`	Unterseiten, Legal, wenig interaktive Bereiche

Nicht alles mit client:load — das erhöht initiales JS unnötig.

SEO und Metadaten

Zentrale Site-Konfiguration in src/lib/site.ts:

export function getSiteUrl(): string {
  const raw = import.meta.env.PUBLIC_SITE_URL ?? 'https://addxion.com'
  return String(raw).replace(/\/$/, '')
}

Export	Zweck
`getSiteUrl()`	Canonical-Basis; `PUBLIC_SITE_URL` für Preview/Staging
`siteName`	OG `site_name`, JSON-LD
`siteDescriptionDefault`	Fallback-Meta
`siteDefaultOgImagePath`	`/og.png`
`getStructuredDataJsonLd(siteUrl)`	`@graph`: WebSite + Organization

Sitemap und Robots

Programmatische Endpunkte statt statischer Dateien:

src/pages/sitemap.xml.ts — explizite URL-Liste mit changefreq / priority
src/pages/robots.txt.ts — Sitemap: ${getSiteUrl()}/sitemap.xml

Keine /docs/* URLs in der Marketing-Sitemap. Plattform-Docs laufen über separates CF Pages-Projekt (addxion-docs).

Neue Marketing-Seite → URL in Sitemap eintragen.

Layout

Layout.astro bezieht Defaults aus site.ts:

Canonical, OG, Twitter Cards
<script type="application/ld+json"> mit getStructuredDataJsonLd()
Domänenspezifische Schemas (z. B. Dentist, JobPosting) nur beim jeweiligen Consumer ergänzen

Weitere SEO-Regeln

404: robots="noindex, follow" (kein Index, Links folgen)
Fixe Navigation: scroll-padding-top in site.css für Anker-Sprünge unter sticky Header

View Transitions und Third-Party

addxion-com nutzt ClientRouter (Astro View Transitions). Das ist für Marketing ohne schwere Embeds in Ordnung.

Bei Drittanbieter-Widgets (Reviews, CMP, Chat) kann SPA-Navigation Probleme machen: Widgets bleiben nach Zurück-Navigation leer bis Hard-Reload. Dann entweder:

Full-Page-Navigation ohne ClientRouter, oder
Lifecycle-Bridge (astro:before-swap) für betroffene Embeds

Referenz: improdent verzichtet bewusst auf ClientRouter wegen Elfsight.

LLM-Index

Datei	Repo	Inhalt
`public/llms.txt`	addxion-com	Marketing-Index, Produktlinks, Verweis auf Docs
`public/llms-full.txt`	addxion-com	Volltext nur Marketing-Seiten
`public/llms.txt`	addxion-docs	Plattform-Docs-Index

Bei neuer Marketing-Seite: llms.txt und ggf. llms-full.txt in addxion-com. Bei neuer Plattform-Doc: addxion-docs llms.txt und Starlight-Content.

Details: Documentation as Code.

Copy und Schreibstil

Documentation as Code: keine KI-Floskeln, kein Gedankenstrich-Spam.

Zusätzlich (aus improdent AGENTS.md):

Keine Bindestriche in Fließtext — umformulieren zu fließendem Satz
Externe Quellen (Templates, Kits) ans eigene Design System anpassen, nicht 1:1 übernehmen
Produktnamen: Neon, AI — ohne „ADDXION®“-Präfix im Produktnamen

AI-ready Neon-UI

Für UI mit Neon-Primitives: AI-ready Neon.

Kurz:

MCP @addxion/mcp in .cursor/mcp.json (cwd: ../addxion-neon)
Vor Implementierung: list_rules, get_component
tw: Prefix, semantische Tokens, Brand nur in brand.css
bun run check (neon), bun run build (com)

Deploy

Consumer	Hosting	Besonderheit
addxion.com	Cloudflare Pages	`functions/_middleware.ts` proxied `/docs/*` → addxion-docs
süper	Cloudflare Pages	Eigener Consumer, eigene `brand.css`
improdent	Statisch / FTP	Referenz für SEO-Muster, nicht ADDXION-Deploy-Standard

addxion-com: bun run deploy. Docs separat: cd addxion-docs && bun run deploy.

Checkliste: neue Marketing-Seite

src/pages/<slug>.astro anlegen
Meta (title, description) — Defaults aus site.ts nutzen
URL in sitemap.xml.ts eintragen
public/llms.txt aktualisieren
Bei Bedarf llms-full.txt ergänzen
bun run build in addxion-com

Truths

ID	Wahrheit
T-PKG-NEON	Consumer-Einstieg: @addxion/neon, nicht @addxion/core
T-NEON-BRAND	Markenwerte in Consumer brand.css
T-BRAND-STRATEGY	Markenstrategie nur in addxion-docs `/docs/branding/`
T-REPO-BOUNDARY	Klare Repo-Verantwortung pro Inhaltstyp

Für Agents

Scope: Marketing-Websites — addxion.com, süper, Neon-Consumer.

Referenz: addxion-com; @addxion/neon als Design-Einstieg
brand.css pro Consumer für Markenwerte und Type-Scale-Tokens
Typografie: Hero → Display, Section → Heading, Body base/7 — Typografie
Copy und Positionierung an Branding ausrichten
Nach Package-Änderung: Docs-Sync