Was macht Components.build Spezifikation?
Umfassende Richtlinien zur Erstellung moderner, komponierbarer und barrierefreier UI-Komponenten. Enthält 16 Regelkategorien, die von Kernprinzipien bis zur Verteilung reichen, gemeinsam verfasst von Hayden Bleasel und shadcn.
Wann anzuwenden
Beziehe dich auf diese Richtlinien, wenn:
- Neue React-Komponenten oder Komponentenbibliotheken erstellt werden
- Komponenten-APIs und Props-Schnittstellen entworfen werden
- Barrierefreiheitsfunktionen (Tastatur, ARIA, Fokusverwaltung) implementiert werden
- Komponierbare Komponentenarchitekturen aufgebaut werden
- Komponenten mit Tailwind CSS und CVA gestylt werden
- Komponenten in Registries oder npm veröffentlicht werden
Regelkategorien nach Priorität
| Priorität | Kategorie | Fokus | Präfix |
|---|---|---|---|
| 1 | Übersicht | Umfang und Ziele der Spezifikation | overview |
| 2 | Prinzipien | Kern-Designphilosophie | principles |
| 3 | Definitionen | Allgemeine Terminologie | definitions |
| 4 | Komposition | Aufteilung komplexer Komponenten | composition |
| 5 | Barrierefreiheit | Tastatur, Screenreader, ARIA | accessibility |
| 6 | Zustand | Controlled/uncontrolled-Muster | state |
| 7 | Typen | TypeScript-Props und -Schnittstellen | types |
| 8 | Polymorphismus | Elementwechsel mit der as-Prop | polymorphism |
| 9 | As-Child | Radix-Slot-Kompositionsmuster | as-child |
| 10 | Datenattribute | data-state und data-slot | data-attributes |
| 11 | Styling | Tailwind CSS, cn-Hilfsfunktion, CVA | styling |
| 12 | Design-Tokens | CSS-Variablen und Theming | design-tokens |
| 13 | Dokumentation | Komponentendokumentation | documentation |
| 14 | Registry | Komponenten-Registries | registry |
| 15 | NPM | Veröffentlichung auf npm | npm |
| 16 | Marktplätze | Komponenten-Marktplätze | marketplaces |
Kurzreferenz
1. Übersicht
overview- Umfang, Ziele und Philosophie der Spezifikation
2. Prinzipien
principles- Komponierbarkeit, Barrierefreiheit, Anpassbarkeit, Transparenz
3. Definitionen
definitions- Allgemeine Terminologie (primitiv, zusammengesetzt, headless, usw.)
4. Komposition
composition-root- Root-Komponente mit Kontext für gemeinsamen Zustandcomposition-item- Item-Wrapper-Komponentencomposition-trigger- Interaktive Trigger-Komponentencomposition-content- Inhaltsanzeige-Komponentencomposition-export- Namespace-Exportmuster
5. Barrierefreiheit
accessibility-semantic-html- Verwendung geeigneter HTML-Elementeaccessibility-keyboard- Vollständige Tastaturnavigationaccessibility-aria- Korrekte ARIA-Rollen, -Zustände und -Eigenschaftenaccessibility-focus- Fokusverwaltung und -wiederherstellungaccessibility-live-regions- Screenreader-Ankündigungenaccessibility-contrast- Farbkontrastanforderungen
6. Zustand
state-uncontrolled- Internes Zustandsmanagementstate-controlled- Externes Zustandsmanagementstate-controllable- Unterstützung beider Muster mit useControllableState
7. Typen
types-extend-html- Erweiterung nativer HTML-Attributetypes-export- Export von Prop-Typen für Konsumententypes-single-element- Eine Komponente umschließt ein Element
8. Polymorphismus
polymorphism-as-prop- Änderung des gerenderten Elementtypspolymorphism-typescript- Typsichere polymorphe Komponentenpolymorphism-defaults- Semantische Standardelemente
9. As-Child
as-child-slot- Radix-Slot zur Prop-Verschmelzungas-child-composition- Komposition mit Kindkomponenten
10. Datenattribute
data-attributes-state- Verwendung vondata-statezum Stylen von Zuständendata-attributes-slot- Verwendung vondata-slotzur Zielbestimmung von Unterkomponenten
11. Styling
styling-cn-utility- Kombination von clsx und tailwind-mergestyling-order- Basis → Varianten → Bedingungen → Benutzer-Overridestyling-cva- Class Variance Authority für Variantenstyling-css-variables- Dynamische Werte mit CSS-Variablen
12. Design-Tokens
design-tokens-css-variables- Definition von Tokens als CSS-Variablendesign-tokens-theming- Unterstützung von Hell-/Dunkelmodi und Themes
13. Dokumentation
documentation-props- Dokumentation aller Props mit JSDocdocumentation-examples- Bereitstellung von Nutzungsbeispielen
14. Registry
registry-structure- Dateistruktur der Registryregistry-schema- Metadatenschema der Komponente
15. NPM
npm-package-json- Paketkonfigurationnpm-exports- Modul-Exporte
16. Marktplätze
marketplaces-distribution- Strategien zur Komponentenverteilung
Verwendung
Lies die einzelnen Regeldateien für detaillierte Erklärungen und Codebeispiele:
regeln/komposition/SKILL.md
regeln/barrierefreiheit/SKILL.md
regeln/styling/SKILL.md
Jede Regeldatei enthält:
- Kurze Erklärung, warum sie wichtig ist
- Falsches Codebeispiel mit Erklärung
- Korrektes Codebeispiel mit Erklärung
- Best Practices und häufige Fehler
Vollständig kompiliertes Dokument
Für die vollständige Anleitung mit allen erweiterten Regeln: AGENTS.md
Wichtige Prinzipien
- Komposition vor Konfiguration - Zerlege Komponenten in komponierbare Unterkomponenten
- Barrierefreiheit standardmäßig - Kein nachträglicher Gedanke, sondern eine Anforderung
- Einzelnes Element umschließen - Jede Komponente umschließt ein HTML-Element
- HTML-Attribute erweitern - Erweitere immer native Element-Props
- Typen exportieren - Mache Prop-Typen für Konsumenten verfügbar
- Beide Zustandsmuster unterstützen - Controlled und uncontrolled
- Intelligente Klassen-Verschmelzung - Verwende die
cn()-Hilfsfunktion mit tailwind-merge
Autoren
Gemeinsam verfasst von:
- Hayden Bleasel (@haydenbleasel)
- shadcn (@shadcn)
Als KI-Fertigkeit adaptiert von:
- Jordan Gilliam (@nolansym)
Basiert auf der components.build-Spezifikation.