Interaktive Seitenarchitektur

Was macht Interaktive Seitenarchitektur?

Ergebnis

Erstelle eine produktive, öffentlich zugängliche Next.js-Website, deren Inhalt, Erzählung, visuelle Identität und Interaktionsqualität von Bedeutung sind. Dies ist eine universelle Architektur für inhaltsgeführte Websites: Marken- und Marketingseiten, SaaS- und Produktseiten, Launch-Seiten, redaktionelle Eigenschaften, Portfolios, Communities, Konferenzen, dokumentationsähnliche Websites und immersive Präsentationen.

Der Kern ist festgelegt:

• servergerenderte Inhalte;
• schmale Client-Islands;
• validierte Inhaltsverträge;
• geteilte Design- und Bewegungs-Tokens;
• natives Browser-Verhalten;
• SEO und Barrierefreiheit in der Server-Antwort;
• routenbezogene Leistungsbudgets.

Wähle die Module aus, die das Produkt benötigt:

Modul	Verwende, wenn
Sammlung und Detail von Inhalten	Die Website hat Projekte, Artikel, Produkte, Personen, Veranstaltungen oder ähnliche Einträge
Portfolio oder Fallstudien	Die Organisation benötigt Nachweise durch Arbeit
Immersives Archiv	Visuelle Erkundung ist eine primäre Produktoberfläche
Shop	Die Website verkauft digitale oder physische Produkte
CMS-Adapter	Redakteure veröffentlichen unabhängig von Releases
Kontaktformular	Ein E-Mail-Link oder Kalender ist nicht ausreichend

Erzwinge keine optionalen Module auf einer Website, die sie nicht benötigt.

Typische Profile verwenden denselben Kern wieder:

• SaaS oder Produkt: Landing, Angebot, Funktionen, Inhaltssammlung, Docs oder Changelog.
• Marke oder Launch: Kampagnenerzählung, Produktenthüllung, Warteliste, sozialer Beweis.
• Redaktion: Sammlungsindex, Artikeldetail, Autoren, Themen, Suche.
• Community oder Konferenz: Sprecher, Programm, Sessions, Veranstaltungsort, Tickets.
• Portfolio: Projektindex, Falldetail, visuelles Archiv, Kontakt.
• Commerce: Katalog, Produktdetail, Checkout, Download oder Fulfillment.

Vor dem Handeln lesen

• Lies references/architecture-contract.md für jeden Build, jedes Redesign oder jede Architekturänderung.
• Lies references/code-architecture.md bevor du Ordner, Verträge, Services, Adapter oder Server Actions erstellst.
• Lies references/dependency-matrix.md bevor du Abhängigkeiten installierst, upgradest oder entfernst.
• Für eine neue Anwendung folge references/build-playbook.md.
• Für neue Routen, Inhaltstypen, Islands, Archive, Shop-Produkte oder Migrationen folge references/evolve-playbook.md.
• Vor der Abnahme oder Veröffentlichung folge references/quality-gates.md.

Wiederverwendbare Vorlagen befinden sich unter assets/templates/. Starte von ihnen nur, wenn sie mit der gewählten Architektur übereinstimmen. Kopiere nicht blind jede Vorlage.

Unverhandelbare Invarianten

1. Behalte Seitenkomposition und primären Inhalt standardmäßig in Server-Komponenten.
2. Setze use client auf das kleinste lebensfähige Blatt. Animiniere servergerenderte Kinder nach Möglichkeit durch Client-Wrapper.
3. Behandle TypeScript-Datenverträge als die einzige Quelle der Wahrheit für jede Inhaltseinheit, Metadatensatz, Galerie und Sitemap-Eintrag.
4. Gib jeder Overlay-Interaktion eine echte Route, die ohne Client-Status, JavaScript oder Hash funktioniert.
5. Verwende zuerst natives HTML-Verhalten: Links, Buttons, Formulare, <dialog>, Fokus-Management und Browser-Verlauf.
6. Halte Geheimnisse in server-only Modulen. Nur öffentliche Identifikatoren dürfen NEXT_PUBLIC_* verwenden.
7. Wenn Commerce existiert, behalte Preise, Berechtigungsentscheidungen, Zahlungsbestätigung und geschützte Downloads auf dem Server.
8. Respektiere prefers-reduced-motion, Tastaturnavigation, sichtbaren Fokus, semantische Überschriften und Lesbarkeit ohne Skript.
9. Halte Inhalte für eine Route aus dem anfänglichen Client-Bundle einer anderen Route fern. Übergebe kleine Zusammenfassungen vom Server, wenn eine Client-Shell einen Zähler oder ein Label benötigt.
10. Verwende einen modularen Monolithen mit dünnen Routenadaptern, eigenen Feature-Modulen, expliziten Ports und einer einzigen Kompositionsgrenze.
11. Bevorzuge stabile Abhängigkeiten. Starte keine neue Produktions-App mit einem Canary-React-Build.

Standard-Stack

Verwende die exakt validierten Versionen in der Abhängigkeitsmatrix, es sei denn, die Website hat einen dokumentierten Grund, davon abzuweichen.

• Node 26 LTS-Familie und pnpm.
• Next.js App Router, React, React DOM, TypeScript.
• Tailwind CSS 4 für Tokens, Reset und Utility-Layout.
• CSS Module für routen- oder komponentenspezifische Komposition.
• Motion for React Orchestrierung und Gesten.
• Natives Dialog, Canvas, SVG, CSS und Web Animations API für Interaktionen, wo sie ausreichen.
• Lucide Icons einzeln importiert.
• Zod für Inhalts- und externe Eingabegrenzen.
• Vercel für Deployment, Analytik und Bildauslieferung.
• Stripe Embedded Checkout und Server Actions, wenn Commerce erforderlich ist.

Arbeitssequenz

1. Inventarisiere die öffentlichen Oberflächen: Landing Pages, Inhaltsindizes, Detailseiten, Conversion-Pfade, rechtliche Seiten, Suche, Archiv und Commerce.
2. Friere das Routenmanifest und die Client-Boundary-Karte vor der Implementierung ein.
3. Weise Feature-Besitzer, Ports, Routenadapter und externe Adapter zu, bevor du Dateien erstellst.
4. Modelliere Inhaltseinheiten und benötigte Medien, bevor du Abschnitte baust.
5. Etabliere globale Tokens, Typografie, Abstände, Zustände, Reduced-Motion-Verhalten und Bildkonventionen.
6. Baue die Server-Shell, Navigation, Routen-Fallbacks und SEO-Metadaten.
7. Füge Client-Islands einzeln hinzu. Dokumentiere, warum jedes Client-seitig sein muss.
8. Baue Overlays mit nativem Dialog und URL-Status. Füge gleichzeitig die kanonische Seitenroute hinzu.
9. Füge komplexe Visuals hinzu, nachdem ihre Daten, Fallback, Reduced-Motion-Verhalten und Leistungsgrenzen definiert sind.
10. Füge CMS, Commerce, Konten oder Persistenz nur hinzu, wenn das Betriebsmodell sie erfordert.
11. Führe die Architekturgrenzenprüfung, das strukturelle Audit, fokussierte Tests, Qualitätsgates und die Produktionsvorschau-Abnahme durch.
12. Berichte implementiertes Verhalten, überprüfte Nachweise und nicht verifizierte Einschränkungen getrennt.

Entscheidungsregeln

• Verwende CSS-Übergänge für Hover, Fokus, Drücken, Enthüllen, Laufband und einfache Zustandsänderungen.
• Verwende Motion für koordinierte Varianten, Layout-Übergänge, Drag, Präsenz und scroll-verknüpfte Orchestrierung.
• Verwende Canvas oder WebGL nur, wenn das visuelle Element nicht zuverlässig mit DOM, SVG und CSS ausgedrückt werden kann. Füge Sichtbarkeitspause, DPR-Grenzen, Bereinigung, Reduced-Motion-Verhalten und einen statischen Fallback hinzu.
• Behalte Inhaltssammlungen servergerendert. Sende nur Zähler, Labels oder ausgewählte Einträge an eine Client-Overlay-Shell.
• Verwende ein natives <dialog> für Vorschauen und Blätter, wenn derselbe Inhalt auch eine kanonische Seite hat. Verwende eine dedizierte Route für tiefe, lange oder unabhängig verlinkte Inhalte.
• Verwende validierten Code-Inhalt für ein kleines Team, das mit der App ausliefert. Führe ein CMS hinter einem Repository-Adapter ein, wenn Redakteure unabhängiges Veröffentlichen benötigen.
• Verwende eine zustandslose Stripe-Sitzung, wenn der Shop nur sofortigen Kauf und Download benötigt. Füge eine Datenbank und verifizierte Webhooks hinzu, wenn das Produkt Berechtigungen, Rückerstattungen, Konten, Bestellhistorie oder Wiederholungen benötigt.
• Füge Radix, shadcn oder eine andere Komponentenbibliothek erst hinzu, nachdem du das Primitive identifiziert hast, das sie besitzt. Native Elemente und site-eigene Primitive sind die Basislinie.
• Behandle Portfolios, Archive und Shops als Module. Sie verwenden die Kernverträge für Inhalt, Route, Stil, Bewegung und Sicherheit wieder.

Erforderliche Build-Artefakte

Erstelle und pflege diese Site-weiten Artefakte:

• docs/architecture.md: Routenkarte, Client-Grenzen, Inhaltsbesitzer, externe Dienste und Leistungsbudgets.
• src/features/*/domain und src/features/*/application: validierte Verträge und Fähigkeiten.
• src/platform/*: externe Adapter und die server-only Kompositionswurzel.
• src/shared/*: bewährte, feature-übergreifende Verträge und Design-Primitive.
• src/components/*: Server-Komposition und Client-Islands mit expliziten Namen.
• src/app/*: Seiten, Layouts, Metadaten, Sitemap, Robots und Routen-Handler.
• .env.example: Namen und Zweck, niemals echte Geheimnisse.
• Tests für Inhaltsvalidierung, Client-Zustandsmaschinen, Server Actions und kritische Browser-Reisen.
• Eine Release-Checkliste mit Vorschau-, Browser-, Barrierefreiheits-, Leistungs-, SEO- und bedingten Commerce-Nachweisen.

Strukturelles Audit

Führe die Architekturgrenzenprüfung und das gebündelte Audit nach dem Gerüstbau und vor der Veröffentlichung durch:

pnpm arch:check
node scripts/audit_site.mjs --root /path/to/app

Verwende --strict in CI, wenn Warnungen fehlschlagen sollen. Das Skript prüft Abhängigkeitspräsenz, Routen- und Inhaltsstruktur, Client/Server-Geheimnisrisiken, Dialog- und Bewegungsabsicherungen, Tests, SEO-Dateien und Source-Map-Exposition. Es ergänzt Tests, ersetzt sie aber nicht.

Abschlussvertrag

Ein Build ist nur dann vollständig, wenn:

• die Routen- und Grenzkarte mit der Implementierung übereinstimmt;
• der Abhängigkeitsgraph azyklisch ist und arch:check besteht;
• Routen öffentliche APIs von Features verwenden und die Kompositionswurzel die Verkabelung besitzt;
• die App ohne Canary- oder Peer-Dependency-Überraschungen erstellt;
• kritischer Inhalt im Server-HTML erscheint;
• Overlays, Menüs und Tastaturpfade funktionieren und den Fokus wiederherstellen;
• Reduced-Motion- und No-Script-Fallbacks verifiziert sind;
• Metadaten, Sitemap, Robots, kanonische URLs und soziale Bilder vorhanden sind;
• anfängliche Route JS- und Bild-Payloads innerhalb der dokumentierten Budgets bleiben;
• Commerce, falls vorhanden, servereigene Preise, serverseitige Bestätigung und geschützte Downloads verwendet;
• Vorschau- und Produktionsnachweise getrennt aufgezeichnet werden.