Design System MCP README

Conciso Design System

Das Design System von Conciso: Design Tokens + CSS-Komponenten + Light/Dark-Mode, framework-agnostisch und auf WCAG 2.1 Stufe AA ausgelegt (also alle Kriterien der Stufen A und AA; AAA wo ohne Nachteil erreichbar, aber nicht als Bedingung). Keine Build-Pflicht für die Nutzung — die Komponenten sind CSS-Klassen, die auf semantisches HTML angewendet werden, plus optionales Vanilla-JS für interaktive Muster (Theme-Toggle, Topnav-Dropdowns).

Status: Inhaltlich stabil. Distribution (npm-Paket), Token-Export und Repo-Hygiene werden gerade ergänzt — siehe die GitHub-Releases dieses Repos und den eingefrorenen Stand im CHANGELOG.

Für wen?

Entwickler:innen, die Conciso-Oberflächen bauen (Website, CMS-Templates, künftig Framework-Apps).
Designer:innen, die Komponenten, Tokens und Konventionen nachschlagen.

Dokumentation ansehen

Die Doku ist das Storybook: https://conciso.github.io/conciso-design-system/. Es enthält Marke, Grundlagen, alle Komponenten mit Verwendungsregeln und die Seitenmuster, und ist über den MCP-Server auch für KI-Assistenten abfragbar.

Nutzung im eigenen Projekt

Ausführlich in docs/GETTING-STARTED.md. Kurzfassung:

Variante A — CSS direkt einbinden (funktioniert heute, kein Build):

html

<!-- Self-Host-Fonts (DSGVO: keine Google-CDN-Anfrage) -->
<link rel="stylesheet" href="css/fonts.css">

<!-- Design System: REIHENFOLGE EINHALTEN -->
<link rel="stylesheet" href="css/tokens.css">
<link rel="stylesheet" href="css/dark-mode.css">
<link rel="stylesheet" href="css/base.css">
<link rel="stylesheet" href="css/components.css">

Die Schriften (Montserrat + Libre Baskerville) liegen self-hosted unter fonts/ und werden über css/fonts.css eingebunden — keine externe CDN-Anfrage. Das gebündelte dist/conciso-ds.css enthält die @font-face-Regeln bereits.

Variante B — als npm-Paket von npmjs.org (der empfohlene Weg):

Terminal

npm install @conciso/design-system

server.ts

import '@conciso/design-system/dist/conciso-ds.css';
// Tokens (optional, für JS/Framework):
import { tokens } from '@conciso/design-system/tokens';
// Icons (optional, maschinenlesbar — komplette <svg>-Bodies, currentColor): benannter Import
// pro Icon, tree-shakable — nur importierte Glyphen landen im Bundle:
import { uiShieldCheck } from '@conciso/design-system/icons';
// Das aggregierte `icons`-Objekt (oder icons.json) zieht immer alle Icons ins Bundle — nur
// für Kataloge/Doku, nicht für Apps. Details stehen im Storybook unter Grundlagen → Icons.
// Brand-Logo (Wortmarke, drei Varianten):
import logo from '@conciso/design-system/assets/brand/logo-conciso.svg';

Keine .npmrc nötig — das Paket liegt auf der öffentlichen npm-Registry, npm install funktioniert ohne weitere Einrichtung. Siehe ADR-0011. Gilt ab dem ersten echten Release nach dem Merge dieser Änderung; bis dahin liegt auf npmjs nur eine Bootstrap-Platzhalterversion (siehe ADR-0011).

Die Wortmarke liegt als SVG unter assets/brand/ (Default, Light, Dark). Größen, Schutzraum und Verwendung stehen in der Doku unter Marke → Logo.

Das Paket steht unter der MIT-Lizenz (Ausnahmen — Brand-Assets, Schriften, Icons — siehe NOTICE).

Alternative — GitHub Packages (weiterhin verfügbar, unverändert, z. B. für Consumer innerhalb der GitHub-Organisation conciso): eine .npmrc, die den @conciso-Scope umleitet, plus ein Token mit Scope read:packages auch fürs Lesen (in GitHub Actions genügt secrets.GITHUB_TOKEN):
ini
@conciso:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
GitHub Packages verlangt diese Auth wegen der Registry, nicht wegen der Lizenz. Details in Getting Started, Begründung in ADR-0004. Ohne Installation kann das gebaute Paket per npm pack @conciso/design-system@<version> entpackt oder das CSS versionsgepinnt von jsDelivr geladen werden.

Die Doku (Storybook, die Komponenten-Referenz der Angular-Lib) ist öffentlich einsehbar unter https://conciso.github.io/conciso-design-system/ — ohne Auth, aber noindex (nicht für Suchmaschinen bestimmt). Details und Abwägung in ADR-0009.

Angular: Für Angular gibt es Komponenten statt nur CSS-Klassen — @conciso/design-system-angular aus denselben beiden Registries, im Lockstep auf derselben Version. Siehe README der Lib.

Dark Mode: data-theme="dark" am <html> setzen. Siehe Getting Started für das Anti-Flash-Snippet.

Erstes Element:

html

<button class="btn btn-filled btn-co">Kontakt</button>
<p style="font:var(--ty-body-md);color:var(--tx-primary)">Fließtext.</p>

Verzeichnisse

Pfad	Inhalt
`packages/css/`	`@conciso/design-system`: `css/` (`tokens.css` · `dark-mode.css` · `base.css` · `components.css`, Ladereihenfolge!), `fonts/` (Self-Host-Fonts, woff2, OFL-Lizenztexte), `assets/brand/`, `icons/` (Quellen `source/*.svg` und `manifest.json`), `scripts/` (Build) und `dist/` (Build-Ausgabe, generiert und gitignored)
`packages/angular/`	`@conciso/design-system-angular`: Wrapper-Komponenten (`src/`), gebaut nach `dist/`
`packages/mcp/`	`@conciso/design-system-mcp`: MCP-Server mit Storybook-Snapshot
`apps/storybook/`	Storybook, die öffentliche Doku (GitHub Pages)
`templates/`	Vorlagen, die Nutzer kopieren
`tools/`	Nur für das Repo: `release/` · `checks/` · `consumer-fixture/`
`docs/`	ADRs · Agenten-Doku · `GETTING-STARTED.md` · `legacy-site/` (veraltete Doku-Site)

Das npm-Paket @conciso/design-system (Ordner packages/css/) enthält die Quellen unter css/, den frisch gebauten Ordner dist/, Fonts, Brand-Assets und die Icon-Quellen (icons/source/*.svg, icons/manifest.json), aber keine Doku-Site. Icon-Details und Mapping stehen im generierten dist/icons/README.md des Pakets.

Mitwirken / Erweitern

Konventionen und der Workflow zum Hinzufügen von Tokens/Komponenten stehen in CONTRIBUTING.md — bitte vor Änderungen lesen. Das ist der Kern für eine konsistente, nachhaltige Pflege.

Prüfungen

npm ci baut packages/css/dist/ über den prepare-Hook des CSS-Pakets; dasselbe passiert vor npm pack und npm publish. Nach Änderungen an packages/css/css/, packages/css/icons/source/ oder den Build-Skripten npm run build ausführen.

Terminal

npm run build             # CSS-Schicht (Tokens, Icons, Bundle), Angular-Lib, Storybook, MCP-Snapshot; alles Generierte liegt gitignored unter dist/ bzw. snapshot/
npm run check:dark-states # Zustands-Regeln, die im Dark dunkel-auf-dunkel laufen
npm run check:contrast    # Kontrast der gerenderten Doku in Light UND Dark

check:contrast rendert docs/legacy-site/index.html in beiden Modi in Chromium und prüft Text (4,5:1 bzw. 3:1 bei Großtext), getönte Bauteil-Füllungen und Bedienelement-Grenzen (3:1). Es misst die fertige Kette und findet damit auch inline gesetzte Farben, die kein Token-Check sieht. Der Stand ist 0 Verstöße; jede Abweichung meldet das Skript mit Pfad, Farbe und Sollwert (--list zeigt jeden Fund einzeln). Es braucht einen Browser; die Playwright-Abhängigkeit dafür hängt am Workspace apps/storybook und kommt mit dem npm install im Repo-Wurzelverzeichnis mit (npm-Workspaces, das Skript findet sie auch hoisted); lokal genügt ein installiertes Chrome. In der Pipeline läuft es in storybook-angular.yml.

Versionierung

SemVer. Die Version steht nicht im Repo, sondern im jeweiligen Git-Tag vX.Y.Z; Änderungen dazu stehen im zugehörigen GitHub-Release. Releases entstehen automatisch aus Conventional Commits auf main (ADR-0010) und werden nach npmjs.org und GitHub Packages veröffentlicht (ADR-0011). Der handgeschriebene CHANGELOG ist mit Version 2.0.0 eingefroren. @conciso/design-system und @conciso/design-system-angular tragen dabei im Lockstep immer dieselbe Version, damit die peerDependency der Angular-Lib auf die CSS-Schicht eng gepinnt auflöst (ADR-0004).

Lizenz & Kontakt

MIT, siehe LICENSE. Ausnahmen (Brand-Assets unter assets/brand/, Schriften, Icons) siehe NOTICE. Fragen und Beiträge über GitHub Issues im Repo.

Alle in diesem Repository enthaltenen Firmennamen, Marken, Dienstleistungsmarken, Logos und sonstigen Markenbestandteile sind von der MIT-Lizenz ausgenommen.

Diese Bestandteile verbleiben im Eigentum der jeweiligen Rechteinhaber. Durch die MIT-Lizenz werden weder Markenrechte noch sonstige Rechte zur Nutzung dieser Markenbestandteile eingeräumt.

Jede Nutzung dieser Bestandteile bedarf einer gesonderten Genehmigung durch den jeweiligen Rechteinhaber, sofern nicht nach geltendem Recht anderweitig zulässig.