Zum Hauptinhalt springen

Proposal: Documentation Assets

🤖 Generated with Claude Code

⚠️ Not yet reviewed

Co-Authored-By: Claude (noreply@anthropic.com)

Status: Umgesetzt — die Assets liegen in diesem Repository unter assets/, der Brand Guide unter development/brand-guide/. Das Dokument bleibt als Aufzeichnung der Entscheidung.

Die URLs weiter unten sind die vorgeschlagenen, nicht die tatsächlichen: baseUrl ist /, es gibt kein /docs/-Präfix, und die Assets werden aus dem Site-Root ausgeliefert (/colors/…, /icons/…). Siehe DEPLOYMENT.md.

Problem​

V2 im tis-cca.styleguide Repo enthält Brand Assets für technische Dokumentation (D2-Farben, Templates, AI-Agent-Guides). Konzeptionell gehört das nicht in einen UI-Styleguide:

  • Styleguide (V1): SCSS-Komponenten fĂĽr Apps → Zielgruppe: Frontend-Devs
  • V2: Diagramm-Assets, Doku-Standards → Zielgruppe: Architekten, AI-Agents

Lösung​

V2 nach docs/ migrieren als documentation-assets/ oder brand-guide/.

CDN-Struktur​

Hosting unter cdn.togethercca.com/docs/:

/docs/
├── index.html # Docusaurus Landing
├── colors.json # Maschinenlesbare Farben
├── d2/
│ └── colors.d2 # D2 Import-File
├── quick-reference.md # Raw Markdown für Agent-Context
└── guide/ # Docusaurus Pages

Agent-Integration​

Projekte referenzieren in CLAUDE.md:

FĂĽr Diagramme und Doku-Standards:
- Quick Reference: https://cdn.togethercca.com/docs/quick-reference.md
- D2 Colors: https://cdn.togethercca.com/docs/d2/colors.d2

Farb-Sync​

V2 leitet Farben von @tis-cca/theme ab. Optionen:

  1. Build-Step: Script fetcht _variables.scss aus Styleguide-CDN
  2. Manual Sync: Selten Aenderungen, manuell aktualisieren reicht

Pipeline​

Erste Pipeline im docs-Repo:

  • Trigger: Push auf main
  • Build: Docusaurus
  • Deploy: CDN-Subfolder (/docs/)

Offene Fragen​

  • Ordnerstruktur: documentation-assets/ vs brand-guide/ vs guide/?
  • Versionierung: /docs/v1/ oder nur /docs/latest/?
  • Farb-Sync: Automatisch oder manuell?

Nicht in Scope​

  • npm-Package (Overhead, Agents brauchen Internet sowieso)
  • App/UI-Farben (bleiben in @tis-cca/theme)