Design · Figma-Integration · docs/design/

Figma Integration Rules — SOLCOM Drupal Codebase

TL;DR — Dieses Dokument beschreibt, wie das SOLCOM-Drupal-Projekt organisiert ist, damit Figma-MCP-Calls (get_design_context, get_metadata, get_variable_defs) und die Agenten dieses Repos (solcom-design-scanner, solcom-design-explorer, solcom-figma-reviewer) die Code-Seite zuverlässig adressieren können. Generiert 2026-05-03 via create_design_system_rules. Ergänzt — schreibt nicht um: byte_theme/AGENTS.md, Skills solcom-styleguide, solcom-design-mapping, drupal-twig-sdc-authoring, ADR-0001/0003/0004/0005. Bei Konflikt: die genannte Quelle gewinnt.

1. Token Definitions

Wo liegen die Tokens? theme.brand.css · theme.css · main.css
DateiInhalt
src/theme.brand.cssBrand-Tokens 1:1 aus Figma (Source-of-Truth). Verweis auf Figma-File CHHDfbpX8Ys2LBiGs5HVK0 Node 657:12324 ("Colors").
src/theme.cssSemantic-Aliasse im shadcn/ui-Stil — mappen Brand-Tokens auf --primary, --background, --foreground, etc.
src/main.css@theme inline {} macht alle CSS-Tokens als Tailwind-4-Theme-Variablen verfügbar (bg-primary, text-brand-lime, …).
src/fonts.css@font-face-Definitionen (ScalaSansWeb 400/700, Montserrat ExtraBold 800).
docs/adr/0003-solcom-color-tokens-hybrid-mapping.htmlBegründung Hybrid-Mapping. Insbesondere: --accent ist NICHT Lime.
Figma → Code Mapping theme.brand.css ↔ Figma Node 657:12324

Der Figma-MCP gibt häufig CSS-Variablen-Hints zurück. Mapping-Regel:

Figma-Brand-HexBrand-LayerSemantic-LayerTailwind-Utility
#BEDC00 (Lime)--brand-lime--primarybg-primary / bg-brand-lime
#011C53 (BG Blue)--brand-bg-blue--backgroundbg-background
#001F46 (Dark Blue)--brand-dark-blue--primary-foregroundtext-primary-foreground
#EBEBEB (Light Gray)--brand-light-gray--accent / --secondarybg-accent
#F59678 (Error)--brand-error--destructivebg-destructive

Anti-Pattern: Hardcoded Hex-Werte im SDC oder Tailwind-bg-[#bedc00]-Brackets. Immer den semantischen Alias oder zumindest den Brand-Layer benutzen.

Bekannte API-Limits (get_variable_defs) 2026-05-04
  • Opacity-Variants: API liefert nur Base-Color #828282, nicht den aufgelösten transparenten Wert. Code nutzt color-mix(in oklab, #828282 N%, transparent).
  • Gradient-Tokens: API liefert leeren String. Code-Werte (linear-gradient(135deg, #bedc00 0%, #00aaaa 50%, #0050a0 100%)) müssen visuell geprüft werden.
  • Naming-Inkonsistenz „Grey" vs. „Gray": Figma = britisch, Code = amerikanisch. 3 Tokens betroffen. Kein Wert-Drift.

2. Component Library

Wo liegen die SDCs? byte_theme/components/

web/themes/custom/byte_theme/components/<name>/ — pro Komponente ein Verzeichnis. 29 SDCs Stand 2026-05-03:

accordion, accordion-container, anchor, badge, blockquote,
bubble-card-frame, button, button-anchor, button-badge, button-link,
card, card-bubble-profile, card-bubble-profile-no-button, card-meta-list,
cta, footer, group, heading, hero-billboard, hero-blog, hero-side-by-side,
icon, image, meta-row, navbar, section, sticky-apply-bar, text, video

Plus _partials/ (Helper, kein SDC).

Architektur: Drupal SDC + CVA component.yml + twig + tailwind.css

Drupal 11 Single Directory Components (SDC). Pro Verzeichnis: <name>.component.yml, <name>.twig, optional <name>.tailwind.css, <name>.js.

Includes zwischen SDCs: Twig-Namespace @byte_theme/components/ mit with_context: false (PFLICHT — AGENTS.md Regel 11).

Kein Storybook. Drupal Canvas ist die visuelle Compositions-Umgebung. ADRs und MAPPING.html sind die Referenz-Dokumentation.

3. Frameworks & Libraries

UI-Framework, Styling, Build-System Drupal 11 · Tailwind 4 · CVA
  • Drupal 11.3+ — Twig, SDC (native ab 10.3), Canvas (canvas:canvas), CVA (cva:cva).
  • Tailwind CSS 4.1.18 als alleiniges Style-Framework. Kein SCSS, kein PostCSS-Stack, kein CSS-in-JS.
  • Build: npm run build → tailwindcss --input ./src/main.css --minify --output ./build/main.min.css.
  • Pflicht-Workflow: nach Theme-Code-Änderung npm run format + npm run build (AGENTS.md Regel 13).
  • PHP-Stack: Drupal 11.3+, lokale Entwicklung via DDEV (ddev drush cache:rebuild nach Twig/SDC-Änderungen Pflicht).

4. Asset Management

Statische Assets, Fonts, Uploads byte_theme/fonts/ · byte_theme/icons/
  • Fonts direkt im Repo getrackt (ScalaSansWeb.woff, Montserrat-ExtraBold-latin.woff2) — eingebunden via src/fonts.css @font-face.
  • Icons als rohe SVGs unter icons/phosphor/ und icons/solcom/, registriert in byte_theme.icons.yml.
  • User-Uploads: Drupal-Standard web/sites/*/files/ (gitignored).
  • Asset-Optimierung: Tailwind CLI --minify → build/main.min.css. Drupal-Library markiert mit preprocess: false + minified: true.
  • CDN: Cloudflare (Edge-Layer vor mittwald-Hosting) — Theme-Code ist Cloudflare-agnostisch.

5. Icon System

Phosphor Icons + SOLCOM Brand Icons byte_theme.icons.yml · icon-SDC

Hub-SDC components/icon/ ist die einzige Zugriffsstelle. Direkter icon('phosphor', …)-Call außerhalb des Hub-SDC ist Anti-Pattern.

Verwendung aus anderen SDCs:

{{ include(
  '@byte_theme/components/icon/icon.twig',
  { icon: 'arrow-right', icon_size: 'small' },
  with_context: false
) }}

Naming: Phosphor = kebab-case (arrow-right, caret-down). SOLCOM = kebab-case, prefix-frei (brand-arrow).

6. Styling Approach

Tailwind 4 utility-first + CVA + Custom Properties AGENTS.md Regeln 1–5
  • Tailwind 4 utility-first für Layout, Spacing, Color, Typography.
  • CVA via html_cva() für Variant-Komposition (Conditional-Klassen, Multi-Axis-Varianten).
  • Custom-Property-driven Brand-Tokens statt hardcoded Hex.
  • Per-Komponenten-CSS (components/<name>/<name>.tailwind.css) in src/main.css per @import eingezogen.
  • Responsive: Standard-Tailwind-Breakpoints, Mobile-first konsequent.

7. Project Structure

Top-Level-Struktur des Repos solcom/ 
solcom/
├── AGENTS.md / CONTEXT.md          # Master-Docs
├── composer.json / composer.lock   # Drupal 11 Setup
├── .ddev/                          # DDEV
├── config/sync/ + splits/          # Drupal Config Management
├── docs/
│   ├── adr/                        # Architecture Decision Records
│   ├── context/                    # Snapshots externer Quellen
│   ├── design/                     # Figma↔SDC Mapping + Snapshots
│   ├── plans/ · prds/ · brainstorms/
│   └── agents/                     # Meta-Doku für Agenten
├── .claude/skills/ + agents/
└── web/
    ├── modules/custom/
    └── themes/custom/byte_theme/
        ├── components/<sdc>/       # 29 SDCs
        ├── src/                    # CSS-Source (Tailwind-Input)
        ├── build/                  # Tailwind-Output
        ├── fonts/ · icons/ · js/
        ├── byte_theme.info.yml
        ├── byte_theme.libraries.yml
        └── byte_theme.icons.yml

Source-of-Truth-Hierarchie:

  1. byte_theme/AGENTS.md — Authoring-Regeln (CVA, Twig, Includes).
  2. ADRs unter docs/adr/ — Decisions.
  3. src/theme.brand.css + theme.css — Token-Werte.
  4. docs/design/MAPPING.html — was als SDC umgesetzt ist.
  5. Figma-File (CHHDfbpX8Ys2LBiGs5HVK0) — Design-Spec.

FAQ

Wo finde ich die Brand-Hex-Werte?
web/themes/custom/byte_theme/src/theme.brand.css — Source-of-Truth, 1:1 aus Figma Node 657:12324.
Welcher Token mappt auf Lime?
--brand-lime: #bedc00 im Brand-Layer; semantisch --primary. Nicht --accent — das ist --brand-light-gray (ADR-0003).
Wie finde ich eine Figma-Node-ID für get_design_context?
Ausschließlich über Figma Desktop — Frame anklicken → URL auslesen: node-id=<int>-<int>. Die API (search_design_system) liefert nur componentKeys, die für get_design_context nicht nutzbar sind.
Gibt es Storybook?
Nein. Drupal Canvas ist die visuelle Compositions-Umgebung. Komponenten-Referenz: MAPPING.html + ADRs unter docs/adr/.
Wer darf MAPPING.html schreiben?
Nur Agent solcom-design-scanner (oder manueller User-Edit). Refactor-Skills (simplify etc.) dürfen die Datei nicht anfassen.