Skill: brand-review

Der Marken-Check. Diese Skill prüft, statt zu erstellen: Sie nimmt einen Text, ein Visual, einen Post oder ein UI-Snippet und sagt regelweise, ob es nach Miragon aussieht und klingt, mit konkreten Fix-Vorschlägen. Die mechanischen Regeln prüft dabei brand-lint automatisch.

Plugin	miragon-brand
Aufruf	/miragon-brand:brand-review
Quelle	plugins/miragon-brand/skills/brand-review

Was die Skill macht

Sie verwandelt die Regeln aus Corporate Design und Tonalität in eine Prüfung mit klarem Urteil. Zuerst ordnet sie ein, was vorliegt (Text, Visual, Code oder gemischt), und prüft nur die passenden Regeln. Liegen Dateien vor, läuft brand-lint darüber. Den Rest beurteilt sie selbst, mit den exakten Werten aus tokens.json und contrast.json.

Bei Icons bestimmt sie zuerst die Zeichenart. Funktionsicons kommen aus Lucide (B9). Ein Modeler-Icon aus dem Set ist als App-Icon, Favicon oder Datei-Icon eines Modelers erlaubt. Ein verändertes Modeler-Icon oder ein selbst gezeichnetes Zeichen ist ein Befund (B12), ebenso ein Modeler-Icon an der Stelle des Komets (Empty State, Splash, Software, die kein Modeler ist).

Das Ergebnis ist immer gleich aufgebaut: eine Tabelle Regel, Status (✓ PASS, ✗ FAIL, ○ n.a., ? unklar), Befund und Fix, danach ein Gesamturteil (on-brand, fast, off-brand) mit Muss- und Kann-Fixes.

Wann sie triggert

Wenn du Miragon-Material gegen die Marke prüfen lassen willst: „ist das markenkonform?", „CI-Check", „on-brand?", „klingt das nach Miragon?", „Dark Mode prüfen". Allgemeine Code-Reviews lösen sie nicht aus.

Automatisch prüfen: brand-lint

brand-lint ist der Linter hinter der Skill. Er findet ohne AI, was sich mechanisch prüfen lässt: Siezen, Em-Dashes, Umlaut-Ersatz, Floskeln, den alten Claim, falsche Schreibweisen, AI-Muster aus dem Anti-Slop-Kanon, Farben außerhalb der Tokens und den Dark Mode (C6): getönte Flächen, Farben mit Deckkraft, Tailwind-Grautöne und Host-Farben. Er hat keine Abhängigkeiten und liegt im Plugin unter scripts/brand-lint.mjs.

Im CI-Repo selbst:

npm run lint:brand                 # Doku, Skills und README prüfen

In einem anderen Repo, mit installiertem Plugin oder einer Kopie des Skripts:

node brand-lint.mjs docs/ src/     # Ordner oder Dateien
node brand-lint.mjs --nur-hart .   # nur harte Verstöße

Harte Verstöße lassen den Aufruf mit Exit-Code 1 enden, damit eignet er sich für die CI. Weiche Hinweise sind Richtwerte.

Welche Dateien brand-lint prüft

Dateityp	Text	Farben (B1)	CSS-Muster (C1, U5)	Dark Mode (C6)
.md, .mdx, .markdown, .txt	ja, auch die Werte im YAML-Frontmatter	nein	nein	nein
.astro	ja, Template, Textattribute und Strings mit Text	überall	im <style>-Block	im <style>-Block, in Tailwind-Klassen, Host-Farben auch im style-Attribut
.vue, .html, .htm	ja, Text im Template	überall	im <style>-Block	wie .astro
.css, .scss, .sass, .less	nein	ja	ja	ja, auch Klassen in @apply
.js, .mjs, .cjs, .ts, .tsx, .jsx	nein	ja	nein	in Tailwind-Klassen
.svg	nein	ja	nein	nein

Andere Dateien, etwa .json, prüft brand-lint nicht. Text in .ts, .tsx und .js beurteilt das Review. Generierte Dateien (*.generated.*) überspringt es.

Farben sind Hex-Werte, rgb(), rgba(), hsl(), oklch(), oklab(), lch() und lab(), brand-lint rechnet sie in Hex um. hsl() und die Schreibweisen aus CSS Color 4 prüft es in CSS-Deklarationen: außerhalb der Dunkel-Blöcke als B1, darin als C6. Die dunklen Neutralen (#282828, #2F2F2F, #383838, #464646, #BBBBBB) sind erlaubt, C1 schlägt dafür die Rolle --cd-ui-* vor. Für den Dark Mode (C6) gilt:

• Dunkel-Blöcke erkennt brand-lint an .dark, html.dark, [data-cd-theme="dark"], .vscode-dark, .vscode-high-contrast, @media (prefers-color-scheme: dark) und @variant dark, auch verschachtelt. Ein heller Marker weiter rechts im Selektor ([data-cd-theme="light"]) macht die Regel wieder hell. Ein not vor dem Farbschema oder vor der ganzen Query macht sie unbekannt, ein not vor einer anderen Bedingung ((not (prefers-contrast: more))) nicht.
• Im Dunkel-Block meldet es -soft, Farben mit Deckkraft außer Schwarz, color-mix mit Farbe, getönte Grautöne (auch oklch() und nackte HSL-Werte in Custom Properties wie bei shadcn), --cd-linie und --cd-text-leise, Blau, blau-link, --cd-info und --cd-danger als Text sowie invert(), brightness(), hue-rotate() und mix-blend-mode.
• Überall meldet es Host-Farben (var(--vscode-*), außer Schrift) und Grün als Button-Fläche.
• Tailwind-Klassen: Palettenklassen (gray, slate, zinc, neutral, stone, blue-950 …), bg-black und prose-invert sind überall hart, unter dark: dazu Filter, -soft, Blau als Text und eine Farbe der CI mit Deckkraft-Modifikator (dark:bg-blau/10). Ohne dark: oder mit unbekanntem Namen (bg-tertiary/10) kommt Deckkraft als weicher Hinweis, ebenso dark:text-info und dark:text-danger, die in der Vorlage Rollen sind. Sichtbarer Text, <pre> und <code> bleiben still.

Wo ein Status als Text stehen darf, kennt brand-lint nicht, weil es den Hintergrund nicht sieht. Das prüft das Review mit contrast.json.

In .astro prüft brand-lint, was Menschen lesen:

• Text im Template, auch JSX in {…}-Ausdrücken
• Textattribute wie alt, title, aria-label, placeholder, label, description, text, eyebrow und subtitle, auch als Endung (imageAlt, ctaLabel, meta_title), dazu set:text
• Strings im Frontmatter und in Ausdrücken, wenn sie nach Text aussehen (Leerzeichen, Umlaut oder ein Kompositum mit Großbuchstaben am Anfang) oder unter einem Textschlüssel stehen (title: "…")
• JSON-LD, denn name und description erscheinen in den Suchergebnissen

Imports, Klassen, IDs, Pfade, URLs, Code, Code-Kommentare, <script>, <pre> und <code> lässt brand-lint aus, ebenso Meldungen für Entwicklerinnen und Entwickler in console.*(…), Error(…) und new …Error(…). Im <style>-Block zählen nur Farben und CSS-Muster. Zitate unter quote, quotes, testimonials und den anderen Zitat-Schlüsseln bleiben wie im Frontmatter unangetastet, auch als Attribut (quote="…").

JSON-LD prüft brand-lint in .astro, .vue und .html einheitlich als Text: im Rumpf von <script type="application/ld+json">, über set:html={JSON.stringify(…)} und aus dem Frontmatter. Geprüft werden die String-Werte, die nach Text aussehen oder unter einem Textschlüssel wie description stehen. Schlüssel, Typen ("@type": "Service") und URLs bleiben still.

Bekannte Lücken: Am Satzanfang ist „Sie" oder „Ihr" mehrdeutig, deshalb meldet A1 es dort nicht. Jeder Attributwert und jeder String steht für sich und damit am Satzanfang. „Ihre Vorteile" in title="…", in einer Prop oder als <h2> bleibt also still, genau wie ## Ihre Vorteile in Markdown. Nur in placeholder zählt „Ihre" auch am Anfang. Ebenfalls nicht geprüft werden value (etwa bei Submit-Buttons) und Tooltips in data-*-Attributen. Diese Stellen prüft das Review.

Beim Schreiben mit Claude (Hook)

Das Plugin bringt einen Hook mit: Nach jedem Schreiben oder Editieren prüft brand-lint die geänderte Datei und meldet Verstöße sofort an Claude zurück. Harte Verstöße korrigiert Claude direkt, weiche Hinweise bekommt es als Kontext.

Der Hook ist nur in Repos aktiv, die das ausdrücklich wollen. Lege dafür eine Datei .miragon/brand.json an:

{
  "ignorieren": ["docs/archiv/", "*.min.css"],
  "aus": ["S6"]
}

Ohne diese Datei bleibt der Hook stumm. So greift die Miragon-Marke nie in Kundenprojekte ein, auch wenn das Plugin für deinen ganzen Account installiert ist.

Ausnahmen im Text

Negativbeispiele sollen nicht als Verstoß zählen. brand-lint überspringt deshalb Code, Links, alles in Anführungszeichen, Zeilen mit ✗ und Tabellenspalten mit der Überschrift „✗ So nicht", „Statt" oder „Nicht".

Im Frontmatter (etwa bei Astro- oder VitePress-Seiten) gelten Werte in Anführungszeichen als Inhalt und werden geprüft. Ausgenommen sind dort Schlüssel, Pfade, URLs und Zitate echter Menschen: Werte unter quote, quotes, zitat, testimonials, feedback oder stimmen schreibt niemand auf Markenstimme um.

Für alles andere gibt es Anweisungen im Kommentar:

<!-- brand-lint-disable -->
… bewusst ausgenommener Text …
<!-- brand-lint-enable -->

<!-- brand-lint-disable-next-line -->
Nur diese Zeile bleibt ausgenommen.

Je nach Dateityp steht die Anweisung in einem anderen Kommentar:

Wo	Anweisung
Markdown, .astro, .vue, .html, .svg	<!-- brand-lint-disable --> bis <!-- brand-lint-enable -->, <!-- brand-lint-disable-next-line -->
MDX, Template in .astro, JSX in .tsx und .jsx	dieselben Anweisungen als {/* brand-lint-disable-next-line */}
CSS und <style>	nur /* brand-lint-disable-next-line */, ebenso disable und enable. In CSS ist // kein Kommentar: Der Browser hängt die Zeile an den nächsten Selektor und verwirft genau die Regel, die du ausnehmen wolltest.
JS und TS (auch <script>), Frontmatter von .astro, SCSS, Sass, Less	// brand-lint-disable-next-line oder /* brand-lint-disable-next-line */, ebenso disable und enable
YAML-Frontmatter von .md und .mdx	# brand-lint-disable-next-line in der Zeile vor dem Schlüssel. Das gilt für den ganzen Wert, auch über mehrere Zeilen und bei Block-Skalaren (>-).

In Markdown wirken die Anweisungen auf den Text. In allen anderen Dateien wirken sie auf alle Befunde der Zeilen, also auch auf Farben. Setz sie sparsam und nur mit Grund, etwa für die Farbe einer fremden Marke oder ein Zitat, das nicht unter einem Zitat-Schlüssel steht.

Ein brand-lint-disable ohne brand-lint-enable gilt bis zum Dateiende. Außerhalb von Markdown meldet brand-lint das als weichen Hinweis L1 (Offene Ausnahme), weil sonst still der Rest der Datei ungeprüft bliebe, auch die Farben. Steht die Anweisung nur in einem String, etwa in einem Testnamen, fällt das so ebenfalls auf.

Regelkatalog

Der Katalog steht in brand/regeln.yaml. Diese Tabellen, die Skill und brand-lint werden daraus erzeugt.

Text

ID	Regel	Verstoß, wenn	Schwere	Prüfung
A1	du-Ansprache, klein	„Sie", „Ihnen", „Ihr" als Höflichkeitsform oder unpersönliches „man" in kundenorientiertem Text. „ihr/euer" ist okay, wenn ein ganzes Team gemeint ist.	hart	automatisch + Review
A2	Kein Em-Dash als Verbinder	Geviertstrich „—" oder Halbgeviertstrich mit Leerzeichen „ – " als dramatische Pause oder Verbinder. Bindestriche in Komposita (Open-Source, BPMN-Training) und Bereiche ohne Leerzeichen (1–2) sind okay.	hart	automatisch
A3	Korrekte Umlaute	ae, oe, ue oder ss als Ersatz für ä, ö, ü, ß. Ausnahmen sind URL-Slugs, Dateinamen, Pfade und Token-Namen (gruen, weiss).	hart	automatisch
A4	Aktiv statt passiv	Vermeidbares Passiv, wo eine aktive Formulierung geht.	weich	im Review
A5	Konkret statt Floskel	Floskeln und Buzzwords ohne Substanz, etwa „innovative Lösungen", „digitale Zukunft", „Synergien", „ganzheitlich". Die vollständige Liste steht im Vokabular.	weich	automatisch + Review
A6	Belegen statt behaupten	Selbstlob ohne Beleg („Wir sind die Besten") oder behauptete Frische („jung und frisch").	weich	im Review
A7	Aktueller Claim	Der veraltete Claim wird verwendet, auch abgewandelt (etwa in Sie-Form oder ohne „Wir").	hart	automatisch
A8	Klingt nach Mensch	Typische AI-Muster aus dem Anti-Slop-Kanon (Regeln S1 bis S8): Antithesen-Reflex, Fett-Stichwort-Listen, Dreierketten, Doppelpunkt-Pointen, rhetorische Einstiegsfragen, leere Verstärker.	weich	automatisch + Review
A9	Unerschrocken, aber wohlwollend	Direktheit, die überheblich statt hilfreich klingt.	weich	im Review
A10	Schreibweisen	Abweichung von den verbindlichen Schreibweisen im Vokabular (AI statt KI, Miragon statt MIRAGON im Text, CIB seven, Camunda 8, technologieoffen, „die Skill").	weich	automatisch + Review
A11	Gendern	Kurzformen mit Doppelpunkt, Sternchen, Unterstrich oder Binnen-I (Entwickler:innen, Entwickler*innen, Entwickler_innen, EntwicklerInnen) oder generisches Maskulinum im Fließtext, wenn alle gemeint sind. Richtig ist direkte Ansprache, eine neutrale Form oder die Paarform.	weich	automatisch + Review

Visual und Design

ID	Regel	Verstoß, wenn	Schwere	Prüfung
B1	Exakte Palettenfarben	Eine Farbe, die nicht in brand/tokens.json steht, oder ein „ungefähres" Blau oder Grün, als Hex, rgb(), hsl() oder oklch(). Erlaubt sind die Markenfarben, die Statusfarben (nur für Zustände), die UI-Ebene (linie, kontur, text-leise) und im Dark Mode die dunklen Neutralen (nur über die Rollen --cd-ui-*).	hart	automatisch + Review
B2	Blau führt, Grün akzentuiert	Grün großflächig als Basis statt sparsamer Akzent, oder mehr als ein, zwei grüne Akzente pro Motiv.	weich	im Review
B3	Grün nicht als Fließtext auf Weiß	Grüner Fließtext auf Weiß (Kontrast 1,67:1). Grün nur groß und fett, als Fläche oder Grafik-Akzent.	hart	im Review
B4	Kontrast AA in beiden Modi	Text-Hintergrund-Kombination unter WCAG AA (normal mindestens 4,5:1, groß und fett mindestens 3:1) oder ein bedeutungstragendes Nicht-Text-Element (Rahmen, Icon, Fokus) unter 3:1, im hellen oder im dunklen Modus. Die geprüften Paare beider Modi stehen in contrast.json.	weich	im Review
B5	Logo unverändert	Logo verzerrt, gedreht, umgefärbt (außer den definierten Varianten) oder mit Schatten, Outline oder Glow.	hart	im Review
B6	Richtige Logo-Variante	Falsche Variante für den Grund. Hell bekommt Grün (alternativ Blau), dunkel, Markenfarbe und Foto Weiß (alternativ Grün), der Dark Mode einer App oder Webseite ebenso, monochrom Schwarz.	weich	im Review
B7	Schutzraum und Mindestgröße	Weniger Schutzraum als die Höhe des „M" oder kleiner als die Mindestgröße (Wortmarke 96 px bzw. 20 mm, Komet 24 px bzw. 8 mm).	weich	im Review
B8	Schrift Geist	Eine andere Schrift als Geist (für Code Geist Mono).	weich	im Review
B9	Funktionsicons aus Lucide	Ein Funktionsicon (in Buttons, Menüs, Listen, Navigation oder Material) stammt nicht aus Lucide, oder Icon-Stile sind gemischt. Komet und Modeler-Icons sind Zeichen und keine Funktionsicons, für sie gelten B5 und B12.	weich	im Review
B10	Social-Formate	Das Pixelmaß passt nicht zur Plattform (siehe tokens.json, social).	weich	im Review
B11	Kein AI-Einheitslook	Gestaltungsmuster aus dem Anti-Slop-Kanon (Regeln U1 bis U10): Template-Hero, Icon-Kachel-Raster, Glas auf Verlauf, Sparkles als AI-Symbol, Verlaufstext, Effekte als Hierarchie, erfundene Belege, Emoji als Gestaltung, Violett-Default, Navy-Dark-Default.	weich	automatisch + Review
B12	Modeler-Icon aus dem Set, unverändert	Ein Modeler-Icon ist verändert (Form, Farbe, Kachel, Strich) oder stammt nicht aus dem Set, ein Produkt trägt ein selbst gezeichnetes Zeichen, oder ein Modeler-Icon steht, wo der Komet hingehört (Empty State, Splash, Software, die kein Modeler ist). Neue Modeler-Icons entstehen nur per PR in Miragon/corporate-identity.	hart	im Review

Code und UI

ID	Regel	Verstoß, wenn	Schwere	Prüfung
C1	Tokens statt Hex	Rohe Marken-Hex oder rgb() im Code, wo ein Token (--cd-*) verfügbar ist. Für die dunklen Neutralen ist das die Rolle, die den Wert im Dark Mode trägt.	weich	automatisch
C2	8-Punkt-Raster	Abstände außerhalb der Skala 4, 8, 16, 24, 32, 48, 64, 96.	weich	im Review
C3	Fokus und Bewegung	Kein sichtbarer Fokus-Zustand oder Animation ohne Rücksicht auf prefers-reduced-motion. Der Fokusrahmen ist 2px in --cd-ui-fokus mit 2px Abstand, hell blau-link, im Dark Mode blau-hell.	weich	im Review
C4	Alt-Texte	Fehlender oder falscher Alt-Text. Dekorativ bleibt leer, inhaltstragend wird beschrieben, ein eingebrannter Claim gehört in den Alt-Text.	weich	im Review
C5	UI-Texte auf Deutsch	Miragon-eigene Produkt-Oberflächen mit englischen UI-Texten oder gesiezten Meldungen.	weich	im Review
C6	Dark Mode aus den Rollen	Ein Dark Mode in einer App oder auf einer Webseite, der nicht aus den Rollen --cd-ui-* kommt: eine dunkle Fläche in Dunkelblau, Navy oder einem bläulichen Grauton (auch Tailwind gray, slate, zinc, neutral, stone, bg-black, prose-invert), eine Farbe mit Deckkraft oder color-mix auf dunklem Grund (erlaubt sind Schwarz für Backdrop und Schatten und die Deckkraft schwebender Karten über --cd-ui-chrome-deckkraft, dunkel 100 %), -soft auf Dunkel, Blau, blau-link oder die festen Werte --cd-info und --cd-danger als Text auf Dunkel, ein Status als Text außerhalb der Statustext-Tabelle, ui.linie oder ui.text-leise auf Dunkel, Grün als Button-Fläche, Host-Farben wie --vscode-editor-background, invert() oder brightness() statt Rollen. Dunkle Flächen sind Schwarz oder eine neutrale Stufe, Links Grün, Buttons Blau mit weißer Schrift, Status als Text nur über die Status-Rollen (--cd-ui-success bis --cd-ui-info) und nur, wo contrast.json ihn erlaubt.	hart	automatisch + Review

Aufbau

brand-review/
├── SKILL.md            # Ablauf, Ausgabeformat, harte Verstöße
└── assets/
    └── regeln.md       # Regelkatalog, Anti-Slop-Kanon, Vokabular (generiert)

Verwandt

• brand-tone und corporate-design: erstellen statt prüfen. brand-review nutzt deren Regeln als Maßstab.
• Anti-Slop: die AI-Muster, die brand-review und brand-lint mitprüfen.
• icon-design: die drei Zeichenarten, das Set der Modeler-Icons und der Lucide-Stil. Maßstab für die Regeln B9 und B12.