saltjsx/build-design-system

Ein Designsystem erstellen

Das Vokabular befindet sich in references/glossary.md, die Vorgaben für Verbote und Breiten in references/taste.md. Der eigene Look der App ist die Quelle. Erfinden Sie keinen Farb-, Schrift-, Schatten-, Verlaufs- oder Bewegungswert, den die App nicht bereits hat, es sei denn, die Person hat eine Designquelle ausgewählt und ein Muster bestätigt.

Skripte befinden sich im scripts/-Verzeichnis dieses Skills. Führen Sie sie vom Stammverzeichnis des Repos mit node aus und lesen Sie zuerst --help. scripts/capture.mjs erstellt die Screenshots, die von scripts/capture-guard.mjs geschützt werden (das jeden Schreibzugriff blockiert), und scripts/pixdiff.mjs vergleicht sie. Capture und pixdiff benötigen Playwright und ein Chromium, was scripts/find-chromium.mjs findet oder erklärt, wie man es installiert.

Schritte

1. Rahmen. Lesen Sie AGENTS.md oder CLAUDE.md, das Manifest und den Routenbaum. Schreiben Sie die Beschwerde in den Worten der Person, die erste sichtbare Änderung, die darauf antwortet, und den Pilotdurchlauf (den, den die Beschwerde nennt, sonst den Durchlauf mit den meisten Komponentenfamilien und einem Formular mit einem Fehlerzustand). Fügen Sie .design-system/ zu .git/info/exclude hinzu, sodass keine Notiz, kein Capture und keine Scratch-Datei jemals committet wird. Verwenden Sie den von der Person genannten Branch als Ausführungsbranch oder erstellen Sie einen neuen und schreiben Sie den Branch, auf dem Sie begonnen haben, in .design-system/start-branch, was land.mjs ablehnt. Bieten Sie references/taste.md einmal mit seinen deaktivierten Verboten an und speichern Sie die akzeptierte Kopie als .design-system/taste.md. Fragen Sie nichts anderes. Übernehmen Sie die Standardeinstellung, notieren Sie sie als default (unanswered) und fahren Sie fort. Erledigt, wenn die Beschwerde, der Pilot, der Branch und die akzeptierte Taste-Datei aufgeschrieben sind.

2. Inventur und Basislinien. Listen Sie jede Oberfläche, ihre Zustände und ob sie Daten schreibt. Zählen Sie Rohwerte in Vorkommen (#fff, text-gray-500, p-[13px]) mit scripts/check-system.mjs --no-allowlist --no-self-test --json und gruppieren Sie Komponenten in Familien. Erfassen Sie jede Oberfläche in jedem Zustand bei der schmalsten und breitesten unterstützten Breite (standardmäßig 390 und 1280), eine frische Navigation pro Breite, vor jeder Bearbeitung. Listen Sie bei laufender App (Port 3000 hier) jede Oberfläche als surface<TAB>route<TAB>states-Zeile in .design-system/surfaces.tsv und jeden Schreibzugriff, den die App sendet, als METHOD URL in .design-system/writes.txt, kopiert aus dem Netzwerkprotokoll, und führen Sie dann node <this skill>/scripts/capture.mjs --base http://localhost:3000 --kind before --out .design-system/captures --surfaces .design-system/surfaces.tsv --writes .design-system/writes.txt aus. Es weigert sich zu starten ohne --writes (oder --no-backend für eine App, die keine Schreibzugriffe sendet), beweist, dass jeder Schreibzugriff blockiert ist, bevor der Browser geöffnet wird, speichert den Barrierefreiheitsbaum jedes Captures und beendet sich mit 1 bei jedem verpassten Capture. Löschen Sie, was niemand verwendet, in einem eigenen Commit. Erledigt, wenn jede Oberfläche eine Baseline oder einen genannten not captured Grund hat.

3. Tokens. Gruppieren Sie Rohwerte nach Rolle, benennen Sie sie nach Zweck und ordnen Sie jede Oberfläche ihrem Vordergrund zu (references/tokens.md). Führen Sie token-mapping aus, bis jeder Rohwert einer Rolle, einer Zusammenführung oder einer gelisteten Ausnahme zugeordnet ist. Zusammenführungen innerhalb der Toleranz sind Entscheidungen. Jenseits der Toleranz öffnen Sie ein Gate pro Cluster, dessen Standard die Zusammenführung ist. Führen Sie jeden identischen Wertetausch auf jeder Route durch. Erledigt, wenn token-mapping null Lücken außerhalb der Ausnahmeliste meldet und pixdiff.mjs bei Toleranz 0 0 % für jede von einem Tausch betroffene Oberfläche meldet.

4. Komponenten. Bauen Sie die am häufigsten verwendete Familie zuerst Ende-zu-Ende (references/components.md). Das Text-Primitiv und das Small-Text-Primitiv werden in Welle 1 neben dem Button ausgeliefert. Dokumentieren Sie jedes mit component-docs. Zeigen Sie die Familie der Person vor dem Ausrollen, denn ein Kernfehler, der entdeckt wird, nachdem Bildschirme das System übernommen haben, kostet einen Sweep (ein deaktiviertes Feld, das immer noch rot gezeichnet wird, eine Combobox, die 2px höher als Input ist, Panel-Aktionen, die nicht umbrechen, ein Datei-Drop, der stillschweigend fehlschlägt). Erledigt, wenn jede kanonische Komponente eine Registry-Zeile und eine Dokumentation hat und ihre deaktivierten, erforderlichen, Fehler- und Langtext-Zustände in der Showcase erfasst und der Person gezeigt wurden.

5. Prüfungen. Kopieren Sie scripts/check-system.mjs und scripts/oklch.mjs in das scripts/-Verzeichnis des Repos, führen Sie --init aus, dann einmal --init-allowlist. Eine Regel zählt erst, wenn sie als fehlschlagend beobachtet wurde: Pflanzen Sie einen Verstoß in einem gescannten Ordner, führen Sie --files <plant> --no-allowlist aus, sehen Sie Exit 1, der die Regel nennt, und löschen Sie dann die Pflanze. Die Allowlist und die Ratsche schrumpfen nur. Ein Verbot wird mit seiner Prüfregel in derselben Änderung ausgeliefert. Kopierregeln werden mit ihren Ausnahmen (elementbezogen) für Text, der wörtlich bleiben muss (Zitate, Begriffe, Versionszeichenfolgen) und für Nutzlastzeichenfolgen geliefert, die eine Person oder Maschine woanders einfügt (eine Eingabeaufforderung, ein API-Beispiel, ein Zwischenablagewert), da deren Umschreibung ändert, was jemand anderes erhält. Erledigt, wenn die Prüfung auf einem sauberen Clone mit 0 endet, --self-test mit „all as expected“ endet und jede Regel, die der Lauf hinzugefügt hat, in dieser Sitzung als fehlschlagend auf ihrer Pflanze gesehen wurde.

6. Pilot. Verschieben Sie den Pilotdurchlauf mit einer Codemod, die Sie hunksweise lesen. Erfassen Sie danach mit dem Befehl, den Breiten, Themes und Daten der Baseline, ändern Sie nur --kind after, führen Sie dann pixdiff.mjs auf die beiden Ordner aus. Eine unerklärte Abweichung ist ein Fehler. Gehen Sie den Durchlauf mit der Tastatur durch, erzwingen Sie seine Fehler- und Ladezustände und führen Sie dann ui-review auf den After-Captures aus. Erledigt, wenn jede Abweichung in den Captures auf eine Entscheidung oder ein Gate zurückzuführen ist. Eine gerenderte Änderung ohne Erfassung wird als checks-only gemeldet.

7. Bereitschaft. Bevor eine Migration ausgerollt wird, müssen die fünf folgenden Audits entweder bestanden sein oder einen aufgezeichneten Ausnahmegrund haben.

8. Übergabe. Führen Sie die Zählungen erneut aus. Berichten Sie, was das System abdeckt, in Zahlen, zuerst die unbeantworteten Voreinstellungen, dann was gefunden und nicht behoben wurde, sortiert nach Priorität. Bieten Sie die Migration mit ihrer Größe an. Beginnen Sie nicht damit. Erledigt, wenn jede Zahl im Bericht den Befehl nennt, der sie erzeugt hat.

Bereitschafts-Audits

Eine Lücke, die entdeckt wird, nachdem Bildschirme das System übernommen haben, kostet einen Sweep. Eine Lücke, die vorher entdeckt wird, kostet eine Zeile. Führen Sie diese am Ende von Schritt 5 und erneut vor der ersten Welle aus. Schreiben Sie jedes Ergebnis in .design-system/readiness.md mit einem Bewertungswort.

1. Slot- und Prop-Parität. Jeder Prop jedes alten Primitivs, das Aufrufstellen hat, hat einen passenden Prop auf dem neuen Primitiv oder eine Lückenzeile.
2. Verhaltensverträge. Eine „Was feuert wann“-Tabelle pro interaktivem Primitiv, jede Zeile ein Test (references/components.md).
3. Ton-Parität. Jedes drückbare und Zeilen-Primitiv, gekreuzt mit jedem Status-Ton plus muted. Jede leere Zelle ist eine Lückenzeile oder als nicht unterstützt gekennzeichnet.
4. Festgeschriebene Zeichenfolgen. Jede alte Testabfrage nach Rollennamen oder Text hat einen Standardnamen auf dem neuen Primitiv und eine Label-Überschreibung.
5. Schwierigste Bildschirme. Eine schwierigste Aufrufstelle pro Familie wird in der Showcase gerendert, mit einem Screenshot.

Eine Familie, die nicht bereit ist, wird nicht migriert. Ihre Bildschirme bleiben auf dem alten System.

Niemals

• Pushen, veröffentlichen oder deployen, es sei denn, die Person bittet in dieser Sitzung darum.
• Auf dem Branch committen, auf dem der Lauf begonnen hat. Erstellen Sie zuerst den Ausführungsbranch.
• Stashen oder Branches in einem verschmutzten Checkout wechseln. Ein verschmutzter Checkout erhält den Ausführungsbranch in einem eigenen Worktree (git worktree add).
• Löschen, was ein anderes Paket oder eine öffentliche API exportiert. Stoppen Sie und listen Sie es als Gate mit seinen Importierenden auf.
• Einen Schritt stillschweigend überspringen. Wenn die App nicht erstellt oder ausgeführt werden kann, sagt der Bericht code-complete, not runtime-verified und nennt, was nicht getestet wurde.
• Nennen Sie Ihre eigene Arbeit verified. Auf einem Host, der keine anderen Agenten starten kann, führen Sie die Schritte der Reihe nach aus, prüfen Sie jeden durch ein frisches Lesen des Diffs und der Captures und markieren Sie diese Bewertungen als self-verified.

Regeln

• Rohwertgerüche sind #fff, rgb(, text-gray-500, p-[13px] und style={{ padding: 12 }}. Jeder wird einem semantischen Token oder einer gelisteten Ausnahme zugeordnet.
• Ein fehlendes Primitiv ist eine Lückenzeile, niemals ein Workaround innerhalb einer Oberfläche.
• Farbzusammenführungen innerhalb delta E OK 2 und Abstandszusammenführungen innerhalb 2px sind Entscheidungen. Rahmenbreite, -stärke und -verlauf haben keine Toleranz.
• Eine Änderung, die nur Semantik hinzufügt (ein Name, eine Rolle, aria-current) ist eine Entscheidung. Eine, die Semantik entfernt oder umstrukturiert, ist ein Gate.
• Falsch: {saving ? "Saving..." : "Save"}. Richtig: Das Leerlauf-Label bleibt, ein Spinner sitzt innerhalb derselben Box, aria-busy wird gesetzt.
• Eine Korrektur, die zweimal vorkommt, wird zu einer Prüfregel oder einem Skript, nicht zu einem weiteren Satz.
• Eine Baseline wird niemals bearbeitet, um einen Diff bestehen zu lassen. Eine Prüfung, die korrekten Code markiert, wird in der Prüfung korrigiert, mit einem eingepflanzten Fall, der die Korrektur beweist, niemals durch Beugen des Codes.
• Eine Zählung, die kein Skript erzeugt hat, oder eine Prüfung, die nie als fehlschlagend gesehen wurde, wird nicht gemeldet.

Erledigt

Die Prüfung endet mit 0 auf einem sauberen Clone, wobei jede Regel als fehlschlagend gesehen wurde, jede Route antwortet mit 200 auf dem Produktionsbuild (capture.mjs --status), der Pilot stimmt mit seiner Baseline überein, abgesehen von den gelisteten beabsichtigten Änderungen, und jede Übergabezählung stammt von einem Skript.

references/traps.md listet Verhaltensfallen nach ID auf. references/tokens.md enthält Ebenen, Namen, Toleranzen und Bewegungsvoreinstellungen.