Skip to content

CONTRIBUTING.de.md

Latest commit

 

History

History
300 lines (207 loc) · 19.2 KB

CONTRIBUTING.de.md

File metadata and controls

300 lines (207 loc) · 19.2 KB
Raw

Zu Open Design beitragen

Danke, dass Sie über einen Beitrag nachdenken. OD ist bewusst klein gehalten — der größte Teil des Werts steckt in Dateien (Skills, Designsysteme, Prompt-Fragmente) statt in Framework-Code. Die wirkungsvollsten Beiträge sind deshalb oft ein Ordner, eine Markdown-Datei oder ein PR-großer Adapter.

Dieser Leitfaden zeigt, wo Sie für welche Art Beitrag suchen sollten und welche Messlatte ein PR vor dem Merge erfüllen muss.

English · Português (Brasil) · Deutsch · Français · 简体中文 · 日本語 · 한국어 · ภาษาไทย

Drei Dinge, die Sie an einem Nachmittag liefern können

Wenn Sie möchten… Fügen Sie eigentlich hinzu Ort Umfang
OD eine neue Artifact-Art rendern lassen (Rechnung, iOS Settings Screen, One-Pager…) ein Design-Template design-templates/<your-template>/ ein Ordner mit SKILL.md und Render-Assets
Eine funktionale Fähigkeit ergänzen, die Agents während einer Aufgabe aufrufen einen Skill skills/<your-skill>/ ein Ordner mit SKILL.md und optionalen Ressourcen
OD die visuelle Sprache einer neuen Marke sprechen lassen ein Design System design-systems/<brand>/ ein Paket: manifest.json, DESIGN.md und tokens.css
Eine neue coding-agent CLI anbinden einen Agent adapter apps/daemon/src/runtimes/defs/ eine Definition plus Registry-Eintrag
Feature ergänzen, Bug fixen, UX-Pattern aus open-codesign übernehmen Code apps/web/src/, apps/daemon/ normaler PR
Dokumentation verbessern, Französisch / Deutsch / 中文 ergänzen, Tippfehler fixen Dokumentation README.md, README.fr.md, README.de.md, README.zh-CN.md, docs/, QUICKSTART.md ein PR

Wenn Sie nicht sicher sind, in welchen Bereich Ihre Idee fällt, öffnen Sie zuerst eine Discussion / Issue. Wir zeigen Ihnen dann die passende Oberfläche.

Lokales Setup

Das vollständige One-Page-Setup steht in QUICKSTART.de.md. TL;DR für Mitwirkende:

git clone https://github.com/nexu-io/open-design.git
cd open-design
corepack enable           # wählt das gepinnte pnpm aus packageManager
pnpm install
pnpm tools-dev run web    # daemon + web foreground loop
pnpm typecheck            # tsc -b --noEmit
pnpm --filter @open-design/web build  # Web-Paket bei Bedarf bauen

Node ~24 und pnpm 10.33.x sind erforderlich. nvm / fnm sind optional; nutzen Sie nvm install 24 && nvm use 24 oder fnm install 24 && fnm use 24, wenn Sie Node so verwalten. macOS, Linux und WSL2 sind die primären Pfade. Windows nativ wird unterstützt; siehe docs/windows-troubleshooting.md für die häufigsten Setup-Stolpersteine.

Sie brauchen keine Agent-CLI im PATH, um OD selbst zu entwickeln. Der daemon meldet dann "no agents found" und fällt auf den Anthropic API · BYOK Pfad zurück, der oft die schnellste Dev-Schleife ist.

Ein neues Design-Template hinzufügen

Ein Design-Template ist ein Ordner unter design-templates/ mit SKILL.md im Root. Es folgt der Claude Code SKILL.md Konvention plus optionaler od: Erweiterung und bündelt Form sowie Render-Ressourcen eines Artifacts für die Templates-Galerie.

→ Der vollständige Leitfaden steht in docs/skills-contributing.md

Design-Template-Ordnerlayout

design-templates/your-template/
├── SKILL.md                    # erforderlich
├── assets/template.html        # optional, aber empfohlen — Seed-Datei
├── references/                 # optional — Wissensdateien für den Agent
│   ├── layouts.md
│   ├── components.md
│   └── checklist.md
└── example.html                # stark empfohlen — echtes, handgebautes Beispiel

SKILL.md Frontmatter

Die ersten drei Keys sind die Claude Code Basis-Spec: name, description, triggers. Alles unter od: ist OD-spezifisch und optional, aber od.mode bestimmt, in welcher Gruppe das Template erscheint.

---
name: your-template
description: |
  One-paragraph elevator pitch. The agent reads this verbatim to decide
  if the user's brief matches. Be concrete: surface, audience, what's in
  the artifact, what's not.
triggers:
  - "your trigger phrase"
  - "another phrase"
  - "中文触发词"
od:
  mode: prototype           # prototype | deck | template | design-system
  platform: desktop         # desktop | mobile
  scenario: marketing       # free-form tag for grouping
  featured: 1               # any positive integer surfaces it under "Showcase examples"
  preview:
    type: html              # html | jsx | pptx | markdown
  design_system:
    requires: true
  craft:
    requires: [typography, color, anti-ai-slop]
  example_prompt: "A copy-pastable prompt that nicely shows what this template does."
---

# Your Template

Body is free-form Markdown describing the workflow the agent should follow…

Die vollständige aktive Grammatik (od.mode, od.surface, od.craft.requires, od.critique.policy, Gallery-Hinweise und mehr) steht in docs/skills-protocol.md. Ältere portable Felder wie od.inputs, od.parameters und od.capabilities_required können in externen Bundles noch auftauchen, werden aber vom Skill-/Template-Registry nicht ausgewertet.

Merge-Messlatte für ein neues Design-Template

  1. Ein echtes example.html. Handgebaut, direkt von Disk öffnend, mit Designer-Qualität. Kein Lorem ipsum, kein <svg><rect/></svg> Placeholder-Hero.
  2. Anti-AI-slop Checklist bestehen. Keine violetten Gradients, keine generischen Emoji-Icons, keine runde Karte mit linkem Border-Akzent, kein Inter als Display-Font, keine erfundenen Zahlen.
  3. Ehrliche Platzhalter. Wenn der Agent keine echte Zahl hat, schreiben Sie — oder einen beschrifteten grauen Block, nicht "10× faster".
  4. references/checklist.md mit mindestens P0 Gates. Format an design-templates/guizang-ppt/references/checklist.md oder design-templates/dating-web/references/checklist.md anlehnen.
  5. Screenshot unter docs/screenshots/skills/<skill>.png, wenn das Template featured ist. PNG, ca. 1024×640 retina, aus dem echten example.html.
  6. Ein einzelner, in sich geschlossener Ordner. Keine CDN-Imports außer bereits verwendeten, keine unlizenzierte Fonts, keine Bilder über ca. 250 KB.

Wenn Sie ein vorhandenes Design-Template forken, behalten Sie LICENSE und Autorenschaft in references/ und erwähnen Sie es in der PR-Beschreibung.

Vorhandene Design-Templates zum Nachahmen

Einen funktionalen Skill hinzufügen

Ein funktionaler Skill ist eine Fähigkeit, die der Agent während einer Aufgabe auf Benutzereingaben anwendet. Die Abgrenzung steht in skills/README.md, der Ordnervertrag in skills/AGENTS.md, und die gemeinsame SKILL.md-Grammatik in docs/skills-protocol.md. Der Lazy Scanner des Daemons durchsucht die Skill-Roots bei der nächsten Anfrage an /api/skills; lokal ist weder ein Rebuild noch ein Daemon-Neustart nötig.

Ein neues Design System hinzufügen

Ein neues Designsystem im Repository ist ein Paket unter design-systems/<slug>/, keine einzelne Markdown-Datei. Alle 151 gebündelten Systeme verwenden inzwischen den Paketvertrag unten. Der Daemon akzeptiert für ältere oder benutzerinstallierte Inhalte weiterhin DESIGN.md-only-Ordner als Kompatibilitätspfad; neue gebündelte Systeme dürfen diese Legacy-Form nicht verwenden. Der Katalog wird bei jeder Anfrage an /api/design-systems neu gescannt: Aktualisieren Sie nach einer Änderung die Design-System-Oberfläche, ein Daemon-Neustart ist nicht nötig.

Minimales Paketlayout

design-systems/your-brand/
├── manifest.json
├── DESIGN.md
└── tokens.css

manifest.json enthält stabile ID, Anzeigename, Kategorie, Beschreibung, Provenienz und deklarierte Paketpfade. DESIGN.md erklärt die Designabsicht für Agents; tokens.css ist das kanonische kompilierte Stylesheet für semantische Tokens. Der vollständige Vertrag steht in docs/design-systems.md und design-systems/_schema/AGENTS.md.

DESIGN.md Form

# YourBrand Design System

## Visual Theme
…

## Color Roles
…

## Typography
…

## Layout and Spacing
## Components and States
## Motion and Interaction
## Accessibility
## Anti-patterns

Es gibt kein festes Neun-Abschnitte-Schema. Der Paketqualitäts-Guard verlangt mindestens sieben inhaltlich substantielle H2-Abschnitte, schreibt aber weder Namen noch Reihenfolge oder Nummerierung vor. Verwenden Sie Überschriften, die zum tatsächlichen System passen.

Merge-Messlatte für ein neues Designsystem

  1. Alle drei Pflichtdateien liefern. Ordner-Slug und manifest.id stimmen überein und verwenden normalisiertes ASCII (linear.app → linear-app, x.ai → x-ai).
  2. Mindestens sieben substantielle H2-Abschnitte schreiben. Keine leeren Überschriften nur für den Zähler.
  3. Prosa und Tokens konsistent halten. Farben, Typografie, Abstände und Motion in DESIGN.md müssen mit tokens.css übereinstimmen; die gemeinsamen Token-Guards müssen bestehen.
  4. Echte Evidenz und klare Provenienz verwenden. Direkt vom Quellprodukt oder der Website sampeln und die Quelle im Manifest beziehungsweise in der Paketevidenz festhalten.
  5. Nützliche Katalogtexte schreiben. manifest.name, category und description sind die primären Picker-Metadaten; Marketing-Fluff gehört nicht hinein.

Die upstream-abgeleiteten Produktsysteme werden aus VoltAgent/awesome-design-md über scripts/sync-design-systems.ts importiert. Wenn Ihre Marke upstream passt, schicken Sie den PR zuerst dorthin; OD übernimmt ihn beim nächsten Sync. design-systems/ enthält außerdem projekt-eigene Ergänzungen, die nicht upstream passen.

Eine neue coding-agent CLI hinzufügen

Eine neue Agent-CLI erhält eine Definition unter apps/daemon/src/runtimes/defs/ plus einen Import und Eintrag in runtimes/registry.ts:

import type { RuntimeAgentDef } from '../types.js';

export const fooAgentDef = {
  id: 'foo',
  name: 'Foo Coder',
  bin: 'foo',
  versionArgs: ['--version'],
  fallbackModels: [{ id: 'default', label: 'Default', default: true }],
  buildArgs: (prompt) => ['exec', '-p', prompt],
  streamFormat: 'plain',           // or 'claude-stream-json' if it speaks that
} satisfies RuntimeAgentDef;

Importieren Sie die Definition in runtimes/registry.ts und fügen Sie sie zu BASE_AGENT_DEFS hinzu. Die gemeinsame Engine erkennt sie dann im PATH, zeigt sie im Picker und baut den Aufruf. Verwenden Sie ein bestehendes streamFormat, wenn die Wire-Struktur passt. Ein wirklich neues Wire-Format braucht außerdem einen Parser unter apps/daemon/src/runtimes/ oder apps/daemon/src/agent-protocol/, Parser-Tests und einen passenden Dispatch-Zweig in server.ts.

Merge-Bar:

  1. Eine echte Session läuft end-to-end mit dem neuen Agent; fügen Sie den daemon log in die PR-Beschreibung ein.
  2. docs/agent-adapters.md dokumentiert die Eigenheiten der CLI.
  3. Die README-Tabelle "Unterstützte Code-Agenten" erhält eine Zeile.

Wartung von Lokalisierungen

Deutsch verwendet das formelle Sie, weil OD eine gemischte Zielgruppe aus Solo-Creators, Agenturen und Engineering-Teams anspricht; solange Projektfeedback keine informelle du-Stimme nahelegt, ist formelles Deutsch die am wenigsten überraschende Vorgabe. Locale-PRs sollen UI-Chrome, zentrale Dokumentation und display-only Gallery-Metadaten in apps/web/src/i18n/content.ts übersetzen, aber nicht skills/, design-systems/ oder Prompt-Bodies, die Agents ausführen. Diese Quell-Prompts sind Workflow-Eingaben; eine gemeinsame Quellsprache vermeidet multiplizierte Prompt-QA über alle Locales. Wenn ein Skill, Designsystem oder Prompt Template ergänzt oder umbenannt wird, aktualisieren Sie die deutschen Display-Metadaten und führen pnpm --filter @open-design/web test aus; content.test.ts schlägt fehl, wenn die deutsche Display-Coverage driftet. Daemon-Fehler, Export-Dateinamen und agent-generierte Artifact-Texte sind bekannte Grenzen, sofern ein PR sie nicht ausdrücklich umfasst.

Code Style

Wir sind beim Formatting nicht pedantisch (Prettier on save ist okay), aber zwei Regeln sind nicht verhandelbar:

  1. Single quotes in JS/TS. Strings sind single-quoted, außer Escaping macht sie hässlich.
  2. Kommentare auf Englisch. Auch wenn ein PR etwas ins Deutsche oder Chinesische übersetzt, bleiben Code-Kommentare englisch, damit es eine greppable Referenzsprache gibt.

Außerdem:

  • Nicht erzählen. Kein // import the module, kein // loop through items.
  • TypeScript für apps/web/src/. Der daemon (apps/daemon/) ist plain ESM JavaScript mit JSDoc, wenn Typen wichtig sind.
  • Keine neuen Top-Level Dependencies ohne Absatz in der PR-Beschreibung, was sie bringen und wie viele Bytes sie kosten.
  • Vor dem Push pnpm typecheck ausführen. CI tut es auch.

Commits & Pull Requests

  • Ein Anliegen pro PR.
  • Titel ist imperativ + Scope. add dating-web skill, fix daemon SSE backpressure when CLI hangs, docs: clarify storage contract.
  • Nutzen Sie das PR-Template. Füllen Sie jeden Abschnitt von .github/pull_request_template.md aus — Why, What users will see, Surface area, Screenshots (bei UI), Bug fix verification (bei Bugfix), Validation. Leere Abschnitte ergeben einen "please fill in"-Kommentar.
  • Body erklärt das Warum. Der Diff zeigt oft das Was, aber selten den Grund.
  • Issue referenzieren, falls vorhanden. Bei nicht-trivialen PRs ohne Issue bitte zuerst eines öffnen.
  • Während Review nicht squashen. Fixups pushen; wir squashen beim Merge.
  • Kein Force-Push auf Shared Branches, außer Reviewer fragen danach.

Wir erzwingen kein CLA. Apache-2.0 deckt Beiträge ab; Ihr Beitrag ist unter derselben Lizenz.

Bugs melden

Öffnen Sie ein Issue mit:

  • Exaktem pnpm tools-dev ... Aufruf.
  • Ausgewählter Agent-CLI oder BYOK-Pfad.
  • Skill + Designsystem, die den Fehler ausgelöst haben.
  • Relevanter daemon stderr tail.
  • Screenshot, wenn es UI betrifft.

Für Prompt-Stack-Bugs fügen Sie die vollständige Assistant Message bei, damit klar ist, ob Modell oder Prompt verletzt wurde.

Fragen stellen

  • Architekturfrage, Designfrage, "Bug oder Fehlbenutzung?" → GitHub Discussions (bevorzugt, weil suchbar).
  • "Wie schreibe ich einen Skill für X?" → Discussion öffnen. Wir beantworten sie und übernehmen fehlende Muster in docs/skills-protocol.md.

Was wir nicht annehmen

Um das Projekt fokussiert zu halten, öffnen Sie bitte keine PRs, die:

  • Eine Model Runtime vendoren. OD setzt darauf, dass Ihre vorhandene CLI reicht.
  • Das Frontend ohne vorherige Abstimmung aus dem aktuellen Stack reißen. Next.js 16 App Router + React 18 + TS ist gesetzt.
  • Den daemon durch eine Serverless Function ersetzen. Der daemon besitzt ein echtes cwd und startet echte CLIs.
  • Telemetry oder externe Datenerfassung außerhalb des Datenschutzvertrags hinzufügen. Produktanalysen und maskierte Session-Replays sind einwilligungspflichtig; bereinigte Sicherheits-/Zuverlässigkeitstelemetrie ist in entsprechend konfigurierten Builds stets aktiv. Neue Events, Felder oder Ziele müssen die in PRIVACY.md dokumentierten Einwilligungs-, Minimierungs- und Bereinigungsgrenzen einhalten.
  • Ein Binary bündeln ohne Lizenzdatei und Autorenschaft direkt daneben.

Wenn Sie nicht sicher sind, ob eine Idee passt, öffnen Sie vor dem Code eine Discussion.

Maintainer werden

Wenn Sie kontinuierlich beigetragen haben und wissen möchten, wie der Weg zum Maintainer aussieht, finden Sie die Regeln in MAINTAINERS.md. Die Kurzfassung:

  • Ein Maintainer kann Issues prüfen, freigeben und schließen. Der Merge-Button bleibt beim Core Team — Ihre Freigabe zählt jedoch als die für den Merge erforderliche Freigabe.
  • Die Hürde liegt bei ≥ 20 merged PRs plus einer veröffentlichten Account-Qualitätsprüfung (Anti-Bot, Anti-Sock-Puppet) plus einer Einschätzung des Core Teams zur Qualität der Beiträge. Es gibt kein Bewerbungsformular; das Core Team bringt Kandidatinnen und Kandidaten intern zur Sprache und meldet sich.
  • Es gibt keine Quoten, keine SLAs und keine feste Amtszeit. Ein Rücktritt ist einfach und reversibel (Emeritus → Rückkehr, sobald sich das Leben wieder beruhigt).
  • Alle Schwellenwerte, der Nominierungsablauf, die Regeln zum Rücktritt und die Ausnahmeregelung für die frühe Projektphase stehen in MAINTAINERS.md. Lesen Sie dieses Dokument, falls Sie etwas davon interessiert.

Das tl;dr: Liefern Sie gute PRs, prüfen Sie sorgfältig, halten Sie sich in Discussions / Discord auf — und der Rest ergibt sich von selbst.

Lizenz

Mit Ihrem Beitrag erklären Sie sich einverstanden, dass er unter der Apache-2.0-Lizenz dieses Repositories steht. Ausnahme sind Dateien in design-templates/guizang-ppt/, die ihre ursprüngliche MIT-Lizenz und Autorenschaft von op7418 behalten.