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):

<!-- 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):

npm install @conciso/design-system

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):

@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:

<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.

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. Maintainer: Design-System-Team (bitte eintragen).