Kuratierte Dokumentation von NotionKit Web: Schnellstart, Struktur, Konventionen, Sektionen, Hero-Wahl, Branding, i18n, Blog, Kontaktformular, Tests und Update-Rezept.

Schnellstart

NotionKit Web ist ein GitHub-Template („Use this template“), kein npm-Paket. Die Foundation NotionKit kommt per npm und wird nie lokal editiert.

bashnpm create astro -- --template JUNGHERZ/NotionKit-Web my-site
cd my-site && npm install
npm run dev        # http://localhost:4321/demo/  (base aus astro.config.mjs)
npm run build      # statisch nach dist/
npm test           # Mirror-Check, Farb-Guard, Playwright

Zehn Schritte zur eigenen Site

Template ableiten, npm install. Ordner site/ löschen (Produktseite von NotionKit Web) und den Assemble-Step in .github/workflows/deploy.yml entfernen (markiert „NotionKit-Web only“). SKILL.md behalten.
astro.config.mjs: base auf '/<repo>' setzen – oder für eine Custom Domain entfernen, site setzen, public/CNAME anlegen.
src/data/site.ts: Name, Titel, Beschreibung, Repo-URL, headerBadges, Sprachen.
Hero wählen: HeroProduct (App-Panel), HeroDocs (Suche + Baum) oder HeroEditorial (typographisch) – Import in src/pages/index.astro tauschen.
Copy je Sektion in src/components/ ersetzen (grep „Atlas“); Nav-Einträge stehen einmal im Header und rendern Desktop + Mobile.
Inhalte: src/content/docs/ und src/content/blog/ ersetzen, Bereiche in src/data/docs.ts.
public/favicon.svg ersetzen und npm run build:assets (PNG-Icons + og.png aus scripts/assets/og-demo.html).
Marke in src/styles/brand.css (Token-Overrides, kommentierte Themes) – nie in notionkit.css oder site.css.
Impressum/Datenschutz mit echten Inhalten füllen.
Push auf main – GitHub Actions testet, baut und deployt (einmalig: Settings → Pages → Source „GitHub Actions“).

Struktur

textsrc/data/site.ts            Konstanten, languages, headerBadges, contactForm, href()
src/data/docs.ts            Doku-Bereiche und UI-Labels je Sprache
src/styles/site.css         Web-Layer (.nkw-*), nur --nk-* Farben
src/styles/brand.css        Eure Marke (Token-Overrides)
src/styles/generated/       No-JS-Dark-Spiegel (generiert, committed)
src/layouts/                BaseLayout, DocsLayout
src/components/             Sektionen (Copy darin), en/ = Sprachzweig
src/content/docs|blog/      Markdown je Sprache
src/pages/                  index, docs, blog, impressum, datenschutz, 404, rss, robots, llms + en/
scripts/                    build-dark-mirror, check-no-hex, build-assets
tests/smoke.spec.ts         Smoke-Suite (CI-Gate)

Konventionen

Eigene Klassen tragen das Präfix .nkw- und nutzen ausschließlich --nk-*-Tokens. Keine Farbliterale in src/ (Guard: npm run check:colors). --nkw-*-Properties nur für Nicht-Farben (Font, Breiten).
Kein Scoped CSS in .astro-Dateien – alles global in site.css.
Theme: data-theme auf <html>, Bootstrap-Script vor dem ersten Paint; ohne JS greift der generierte prefers-color-scheme-Spiegel.
Links immer über href() aus site.ts (base-sicher, Trailing Slash). Nackte #anker brechen auf Unterseiten.
Fluide Layouts, genau ein Breakpoint bei 860px, keine Geräte-Mockups. Visualisierungen werden aus nk-*-Komponenten gebaut, nie gescreenshottet.
Accessibility: prefers-reduced-motion deaktiviert Reveal/Animationen, Fokus-Ringe aus --nk-accent, dekorative Demo-UI ist aria-hidden.

Sektionen

Komponente	Zweck	Hinweis
SiteHeader / SiteFooter	Sticky Header mit Nav, Badges, Sprach-Pill, Theme-Toggle, Mobile-Menü; Footer-Spalten	Von BaseLayout gerendert, je Sprachzweig
HeroProduct	Headline + CTAs + App-Panel	Default. Panel = reines Foundation-Markup
HeroDocs	Suche + Seitenbaum-Vorschau	Titel-Filter ohne Dependency
HeroEditorial	Rein typographisch	Gradient-Wort per `<Highlight gradient>`
LogoCloud	Graue Logo-Reihe	Slot für eigene SVGs, `aria-hidden`
FeatureGrid / Bento	Feature-Karten, Bento mit Media-Slots	Media = gebaute nk-Mini-UIs
Steps	Prozess-Schritte ohne JS	Mit CodeWindow je Schritt
CodeWindow	Code-Block mit Copy-Button	Props: code, lang, title, copyLabel
StatsRow	Kennzahlen auf `nk-stats`	Opt-in
Pricing / Testimonials / FAQ	Preise, Zitate, FAQ mit JSON-LD	Opt-in; FAQ = `details.nk-toggle`
Cta / Contact	Abschluss-Band, Kontaktformular	Provider über `contactForm`
Decor	Punktraster, Linien, Dithering	Opt-in, Slot-Positionierung
DocsTree / SectionNav / DocsPager	Docs-Navigation	Von DocsLayout genutzt

Hero wählen und App-Panel befüllen

Das App-Panel (src/components/hero/AppPanel.astro) ist ein Browser-Rahmen (.nkw-appframe), in dem ausschließlich Foundation-Klassen stehen: Sidebar mit Seitenbaum, Topbar mit Breadcrumb, Seite mit Datenbank als Tabelle oder Board. Kein .nk-app (100vh), keine feste Höhe – nur max-height mit Fade. Ein Smoke-Test prüft, dass im Panel-Body keine .nkw-*-Klassen stehen. Zum Befüllen: Zeilen im rows-Array und Labels im labels-Objekt ändern; für ein Board view="board" setzen.

Stil-Leitlinie: Highlight-Pill (Default) oder Gradient-Wort (Opt-in) in der Headline, Announcement-Pill darüber, CTA-Gruppe Primary + Ghost, optional Serif-Typo über --nkw-font-display in brand.css. Muster-Ebene: notion.com (Pill, Panel, Logo-Cloud), twenty.com (Serif, Browser-Rahmen, Badges), chatprd.ai (Announcement, Gradient, Stats). Nichts kopieren.

Branding

css:root { --nk-accent: #2f8f5b; }
[data-theme="dark"] { --nk-accent: #5cbf87; }
@media (prefers-color-scheme: dark) {
  :root:not([data-theme]) { --nk-accent: #5cbf87; }   /* No-JS-Pfad */
}
:root { --nkw-font-display: ui-serif, Georgia, serif; } /* Serif-Headlines */

Nur in brand.css. Der dritte Block ist nötig, weil ohne JavaScript kein data-theme gesetzt wird und der generierte Spiegel nur die Foundation-Werte kennt.

Docs & Blog

Doku-Seiten liegen unter src/content/docs/<lang>/<bereich>/<slug>.md mit Frontmatter title, description, section, order, icon, updated, draft. Bereiche und Labels stehen in src/data/docs.ts. Blogposts unter src/content/blog/<lang>/<slug>.md (title, description, pubDate, author, icon, tags); gleicher Slug in allen Sprachen = Übersetzung mit hreflang. RSS je Sprache (rss.xml, en/rss.xml), llms.txt wird aus Doku-Baum und Blog generiert.

Blog entfernen: src/content/blog/, src/pages/blog/ + en/blog/, rss.xml.ts (beide), src/lib/{blog,rss}.ts, die blog-Collection in content.config.ts, Blog-Links in Header/Footer, Blog-Block in llms.txt.ts, RSS-Link in BaseLayout, Blog-Tests in smoke.spec.ts.

Sprachen

Default-Sprache an der Wurzel, weitere unter /<code>/ als eigene Zweige: src/pages/<code>/, src/components/<code>/, src/content/{docs,blog}/<code>/. Konfiguriert in languages (site.ts) und im i18n-Block von astro.config.mjs. Der Sprach-Umschalter ist eine Link-Pille (kein JS-Toggle); ab drei Sprachen ein Flaggen-Dropdown.

Sprache entfernen: die drei en/-Ordner löschen, Eintrag in languages und astro.config.mjs entfernen, EN-Importe in BaseLayout und die EN-Tests streichen. Sprache hinzufügen: en/ kopieren, übersetzen, languages/i18n/docSections/docsLabels erweitern, BaseLayout-Zweig ergänzen.

Kontaktformular

Ziel	endpoint	hiddenFields
Demo (Default)	`''`	– (UI funktioniert, nichts wird gesendet)
n8n-Webhook	`https://<host>/webhook/kontakt`	– (Workflow: IF botcheck leer → Ziel, z. B. Notion-Node)
Web3Forms	`https://api.web3forms.com/submit`	`{ access_key }`
Formspree	`https://formspree.io/f/<id>`	–

Honeypot botcheck serverseitig prüfen; Empfänger in die Datenschutzerklärung aufnehmen. Der Endpoint ist die einzige erlaubte externe Verbindung des Templates.

Tests & Deploy

npm test = Mirror-Check + Farb-Guard + Playwright (Desktop 1280 × Mobile 390): jede Seite ohne Konsolenfehler, Theme folgt OS, Toggle persistiert, No-JS-Dark-Fallback, Docs-Navigation, Suche, Copy-Button, Mobile-Menü, Sprachwechsel, hreflang, Blog, RSS/Sitemap/robots/llms, 404 DE/EN, Kontaktformular, FAQ, App-Panel-Regel. Headless-Chrome braucht wegen der View-Transitions reducedMotion: 'reduce' – die Suite erzwingt das.

Deploy: .github/workflows/deploy.yml – Jobs build, test, deploy (GitHub Pages). Im Template-Repo liegt diese Produktseite an der Wurzel, die Demo unter /demo/.

Updates aus dem Template ziehen

Foundation: @jungherz-de/notionkit in package.json anheben, npm run build:mirror, Foundation-Changelog lesen.
Template: git remote add template https://github.com/JUNGHERZ/NotionKit-Web.git, git fetch template.
Erst git show template/main:SKILL.md und CHANGELOG.md lesen – die Einträge seit dem letzten Sync sind der Update-Guide.
Mechanik-Dateien bewusst übernehmen: site.css, site.js, scripts/, SKILL.md; BaseLayout, tests, playwright.config.ts nur nach Diff.
Nie überschreiben: site.ts, brand.css, components/**, content/**, public/**, Rechtsseiten.
Neue Opt-in-Sektionen einzeln entscheiden, dann npm test und Commit template-sync: <sha>.

KI-Prompt

Für Claude Code, Cursor & Co.: Die SKILL.md ist die maschinenlesbare Referenz. Prompt-Vorlage:

textLies SKILL.md aus https://github.com/JUNGHERZ/NotionKit-Web und leite daraus
ein neues Projekt für <Marke> ab (Rezept §5). Hero: <Product|Docs|Editorial>.
Sprachen: <de, en>. Blog: <ja|nein>. Halte dich an die Regeln in §4:
.nkw-Präfix, nur --nk-*-Tokens, kein Scoped CSS, href()-Helper, ein Breakpoint.