hayatosc/html-artifacts

HTML-Artefakte

Liefere eine einzelne, menschenlesbare .html-Datei aus, die sich von der Festplatte öffnen lässt und offline funktioniert. Verwende den gebündelten Digital Agency Design System (DADS)-Adapter der japanischen Digitalbehörde – kein CDN und kein Framework. Halte den agentenseitigen Quellcode in Markdown. Dies ist ein inoffizieller Dokumentenadapter, keine vollständige Implementierung aller DADS-Komponenten.

Vorgehen

1. Die Leserschaft und Quelle verstehen

Identifiziere Thema, Zielgruppe, Zweck und Belege, bevor du die Struktur wählst. Bei Plänen bewahre Ziele, Abschlusskriterien, Einschränkungen, Kontrollpunkte und Risiken. Füge einen beschreibenden Titel, eine kurze Orientierung sowie Quellen-/Datumsangaben hinzu. Füge ein Inhaltsverzeichnis nur hinzu, wenn es nützlich ist; erzwinge keine Abschnittsanzahl oder Diagramme.

Erkläre von Grund auf: Beginne mit einer konkreten Situation und dem, was das Thema bewirkt, dann führe Fachbegriffe ein. Definiere Fachjargon bei der ersten Verwendung, gib jedem Schritt eine Idee und verwende ein beschriftetes Bild nur, wenn es klarer erklärt als Prosa. Verwende Analogien nur, wenn ihre Verbindung und ihre Grenzen explizit sind; behalte einen erwachsenen, direkten Ton bei, es sei denn, du schreibst für Kinder. Ein Neuling sollte verstehen, was passiert, warum und was als Nächstes zu tun ist.

2. Mechanisch bauen – CSS niemals neu eintippen

Lies build.md. Bestimme das Fertigkeitsverzeichnis anhand des Speicherorts dieser Datei, nicht des aktuellen Projektverzeichnisses. Mit Python 3.10+:

python /absoluter/pfad/zu/html-artifacts/scripts/build.py /absoluter/pfad/zu/ausgabe.html --title "Thema"

Der Builder liest assets/template.html, bettet alle assets/dads.css und assets/print.js ein und fügt eine Offline-Content-Security-Policy (CSP) hinzu. Er weigert sich, eine vorhandene Datei zu überschreiben. Es sind keine Downloads, Paketinstallationen, Server, Bundler oder zusätzliche Asset-Ordner erforderlich. Verwende in diesem Repository den Python-Runner (uv run python funktioniert auch).

3. Den Inhalt bearbeiten, nicht die Basis

Bearbeite die generierte Datei. Ersetze den erklärenden Inhalt des Starters, die Quellenangabe und das Inhaltsverzeichnis; entferne unnötige Abschnitte. Behalte style#dads-css, script#dads-print, die CSP, den Zeichensatz, den Viewport und die only light-Farbschena-Metadaten bei.

• Nur Inline-SVG und eingebettete Rasterbilder. Keine entfernten/lokalen Stylesheets, Skripte, Schriftarten, Bilder, Iframes, Imports, Fetch- oder Analyseabhängigkeiten. Gewöhnliche Quell-Hyperlinks dürfen auf das Web verweisen; kennzeichne lokale Quelldateien als Text und nicht als defekte relative Links.
• Verwende semantisches HTML und die gebündelten Klassen/Tokens. Lies dads.md für die Klassen-API, offizielle Quellen und lokale Anpassungen. Mische keine data-type-/data-size-APIs von oben mit den Modifikatoren dieses Adapters.
• Verwende diagrams.md vor dem Hinzufügen von SVG. Gib jedem aussagekräftigen Diagramm einen Titel, eine Beschreibung, Beschriftungen und eine Textalternative. Platziere breite Diagramme in einem beschrifteten, tastaturfokussierbaren .dads-diagram-scroll-Bereich.
• Verwende installierte Schriftarten-Fallbacks; fehlendes Noto darf Text nicht verbergen. Passe lang an den Inhalt an. Der Körper ist 1rem/1.7 (16px bei Standardeinstellung). Bewahre Browser-Zoom und Reflow.
• Standardmäßig Links und native Offenlegungen. Lasse Offenlegungen zunächst open, sodass das Drucken ohne Skript den Inhalt behält; das gebündelte Skript öffnet auch jede vom Leser zugeklappte Offenlegung zum Drucken und stellt sie danach wieder her. Füge keine Tabs, toten Schaltflächen, beliebiges JavaScript oder Event-Handler-Attribute hinzu.
• Bleibe hell bei dunklen OS-Einstellungen: Dieser Adapter hat keine verifizierte offizielle dunkle Palette. Invertiere nicht nur den Seitenhintergrund und erfinde kein dunkles Token-Set. Respektiere erzwungene Farben und reduzierte Bewegungen.
• Bevorzuge vorhandene Komponenten. Wenn unbedingt nötig, platziere kleine dokumentenspezifische Regeln in einem separaten Inline-<style>; neue Klassen müssen artifact-* heißen und dort Definitionen haben. Verwende bekannte Tokens, definiere sie niemals neu und ändere das gebündelte CSS nicht. Überprüfe diese Regeln im Browser; statische Validierung ist kein CSS-Parser oder Kontrast-Audit.

4. Abschließende Selbstkontrolle – Fehler vor der Auslieferung beheben

Führe nach der letzten Bearbeitung aus:

python /absoluter/pfad/zu/html-artifacts/scripts/check.py /absoluter/pfad/zu/ausgabe.html

Überprüfe dann die tatsächliche Datei in einem Browser, nach Möglichkeit mit deaktiviertem Netzwerk:

1. Inhalt: Starter-Prosa/Platzhalter sind entfernt; angeforderte Belege, Quellen, Daten und nächste Schritte sind vorhanden. Lies Diagrammbeschreibungen unabhängig; sie müssen die Bedeutung vermitteln.
2. Offline: Keine Ressourcenanfragen, fehlgeschlagenen Assets, CSP-Verstöße oder Konsolenfehler. Quell-Hyperlinks sind Navigation, keine eingebetteten Abhängigkeiten.
3. Mobil/Desktop: Prüfe Screenshots bei 390px und 1280px; überprüfe zusätzlich den Reflow bei 320px/200% Textgröße. Kein seitenweites horizontales Überlaufen; nur beschriftete, fokussierbare Code-/Tabellen-/Diagrammbereiche dürfen scrollen. Prüfe tatsächliche japanische Zeichen und lange URLs.
4. Tastatur/Zustände: Folge dem Skip-Link und dem Inhaltsverzeichnis, tabbiere zu Scrollbereichen, schalte Offenlegungen um und prüfe sichtbaren Fokus und Button-Link-Kontrast (einschließlich besucht/hover). Keine farbige Bedeutung.
5. Dunkel/Druck: Emuliere dunkle Präferenz (die Seite muss hell lesbar bleiben), drucke mit einer zugeklappten Offenlegung, überprüfe, ob ihr Körper gedruckt wird, und prüfe breite Tabellen/Code sowie Seitenumbrüche. Bewahre den Inhalt ohne JavaScript, indem Offenlegungen zunächst open bleiben.

Der Checker erzwingt den gebündelten Asset-/Policy-Vertrag, bekannte Klassen/Tokens und konservative Offline-Ressourcenregeln. Er beweist nicht die CSS-Syntax, das Layout, den Kontrast, die Barrierefreiheit oder die Korrektheit von beliebigem HTML. Wenn kein Browser verfügbar ist, gib an, welche visuellen/Interaktionsprüfungen unverifiziert bleiben; behaupte niemals Screenshots allein aus statischen Prüfungen.

5. Ausliefern

Speichere neben der Quelle oder im Arbeitsverzeichnis, benannt nach dem Thema (PLAN.html für einen Plan). Gib den Artefakt-Link und materielle Einschränkungen zurück, keine Kopie des Dokuments oder eine zweite generische Selbstprüfung.

Bei SSH/anderem Gerät folge remote-preview.md. Ein entfernter Pfad oder xdg-open ist keine brauchbare Betrachtungsübergabe. Serviere nur eine isolierte Kopie, verwende einen öffentlichen Tunnel nur für Inhalte, die zur öffentlichen Weitergabe autorisiert sind, verwende andernfalls SSH-Weiterleitung/Zugriffskontrolle und gib Cleanup-Anweisungen. Halte das ursprüngliche HTML offline-sicher.

Ressourcen

• assets/template.html, assets/dads.css, assets/print.js: mechanisch eingebettete Quellen.
• scripts/build.py, scripts/check.py: Build und abschließende Vertragsprüfung aus der Standardbibliothek.
• build.md: Bearbeitungsmuster und Fehlerbehebung.
• dads.md: offizielle Herkunft, Tokens, Komponenten-API des Adapters.
• diagrams.md: lesbare Inline-SVG-Muster.
• remote-preview.md: sichere entfernte Übergabe.

Der Ansatz "von Grund auf erklären" ist inspiriert von der ELI5-Fertigkeit.