Farben

Die Colors API ermöglicht die Verwaltung aller Farbdefinitionen Ihres Design Systems.

Endpunkte

Methode	Endpunkt	Beschreibung
`GET`	`/api/v1/design-system/colors`	Alle Farben auflisten
`POST`	`/api/v1/design-system/colors`	Neue Farbe erstellen
`GET`	`/api/v1/design-system/colors/{id}`	Einzelne Farbe abrufen
`PUT`	`/api/v1/design-system/colors/{id}`	Farbe aktualisieren
`DELETE`	`/api/v1/design-system/colors/{id}`	Farbe löschen

Das Color-Objekt

{
  "id": "col_abc123",
  "organizationId": "org_xyz789",
  "name": "brand-primary",
  "value": "#3b82f6",
  "category": "brand",
  "description": "Primäre Markenfarbe",
  "variants": {
    "50": "#eff6ff",
    "100": "#dbeafe",
    "200": "#bfdbfe",
    "300": "#93c5fd",
    "400": "#60a5fa",
    "500": "#3b82f6",
    "600": "#2563eb",
    "700": "#1d4ed8",
    "800": "#1e40af",
    "900": "#1e3a8a"
  },
  "usage": {
    "cssVariable": "--color-brand-primary",
    "tailwind": "brand-primary"
  },
  "order": 1,
  "createdAt": "2026-01-10T08:00:00Z",
  "updatedAt": "2026-01-22T12:00:00Z"
}

Attribute

Attribut	Typ	Beschreibung
`id`	string	Eindeutige Farb-ID
`organizationId`	string	Zugehörige Organisation
`name`	string	Farbname (Slug-Format)
`value`	string	Hex-Farbwert
`category`	string	Kategorie für Gruppierung
`description`	string	Beschreibung der Verwendung
`variants`	object	Farbabstufungen (50-900)
`usage`	object	Generierte Verwendungsnamen
`order`	integer	Sortierreihenfolge
`createdAt`	string	Erstellungszeitpunkt
`updatedAt`	string	Letzte Aktualisierung

Farbkategorien

Kategorie	Beschreibung
`brand`	Markenfarben (Primary, Secondary)
`neutral`	Graustufen für Text und Hintergründe
`semantic`	Bedeutungsfarben (Success, Error, Warning)
`accent`	Akzentfarben für Highlights

Farben auflisten

GET /api/v1/design-system/colors

Query-Parameter

Parameter	Typ	Default	Beschreibung
`organizationId`	string	Pflicht	Organisations-ID
`category`	string	–	Filter nach Kategorie

Beispiel-Response

{
  "success": true,
  "data": [
    {
      "id": "col_001",
      "name": "brand-primary",
      "value": "#3b82f6",
      "category": "brand",
      "order": 1
    },
    {
      "id": "col_002",
      "name": "brand-secondary",
      "value": "#8b5cf6",
      "category": "brand",
      "order": 2
    },
    {
      "id": "col_003",
      "name": "success",
      "value": "#10b981",
      "category": "semantic",
      "order": 1
    }
  ]
}

Farbe erstellen

POST /api/v1/design-system/colors

Request-Body

{
  "organizationId": "org_xyz789",
  "name": "accent-coral",
  "value": "#f97316",
  "category": "accent",
  "description": "Korallfarben für CTAs und Highlights",
  "generateVariants": true
}

Pflichtfelder

Feld	Typ	Beschreibung
`organizationId`	string	Ziel-Organisation
`name`	string	Farbname (Kleinbuchstaben, Bindestriche)
`value`	string	Hex-Farbwert (#RRGGBB oder #RGB)

Optionale Felder

Feld	Typ	Default	Beschreibung
`category`	string	`custom`	Farbkategorie
`description`	string	–	Beschreibung
`generateVariants`	boolean	`true`	Varianten automatisch generieren
`order`	integer	Auto	Sortierreihenfolge

Response

{
  "success": true,
  "data": {
    "id": "col_def456",
    "name": "accent-coral",
    "value": "#f97316",
    "category": "accent",
    "variants": {
      "50": "#fff7ed",
      "100": "#ffedd5",
      "200": "#fed7aa",
      "300": "#fdba74",
      "400": "#fb923c",
      "500": "#f97316",
      "600": "#ea580c",
      "700": "#c2410c",
      "800": "#9a3412",
      "900": "#7c2d12"
    },
    "usage": {
      "cssVariable": "--color-accent-coral",
      "tailwind": "accent-coral"
    }
  }
}

Farbformate

Die API akzeptiert verschiedene Farbformate:

Format	Beispiel	Beschreibung
Hex	`#3b82f6`	6-stelliger Hex-Code
Hex (kurz)	`#38f`	3-stelliger Hex-Code
RGB	`rgb(59, 130, 246)`	RGB-Notation
RGBA	`rgba(59, 130, 246, 0.5)`	RGBA mit Alpha
HSL	`hsl(217, 91%, 60%)`	HSL-Notation

Intern werden alle Farben als Hex gespeichert.

Varianten-Generierung

Bei generateVariants: true werden automatisch Farbabstufungen generiert:

50-400: Hellere Varianten
500: Basisfarbe
600-900: Dunklere Varianten

Manuelle Varianten

{
  "name": "custom-blue",
  "value": "#0066cc",
  "generateVariants": false,
  "variants": {
    "light": "#4d94db",
    "dark": "#004d99"
  }
}

CSS-Export

Farben werden als CSS-Variablen exportiert:

:root {
  --color-brand-primary: #3b82f6;
  --color-brand-primary-50: #eff6ff;
  --color-brand-primary-100: #dbeafe;
  /* ... */
  --color-brand-primary-900: #1e3a8a;
}

Fehler

Code	Beschreibung
`400`	Ungültiges Farbformat
`401`	Nicht authentifiziert
`403`	Keine Berechtigung
`404`	Farbe nicht gefunden
`409`	Farbname bereits vergeben

Nächste Schritte

Typografie – Schriften konfigurieren
Design System – Übersicht