feat: custom identifier coloring

17 files changed, 334 insertions, 20 deletions

diff --git a/subprojects/frontend/package.json b/subprojects/frontend/package.json
index 73bb463d..970d00a3 100644
--- a/subprojects/frontend/package.json
+++ b/subprojects/frontend/package.json
@@ -55,6 +55,7 @@
     "ansi-styles": "^6.2.1",
     "csstype": "^3.1.3",
     "d3": "^7.8.5",
+    "d3-color": "^3.1.0",
     "d3-graphviz": "patch:d3-graphviz@npm%3A5.3.0#~/.yarn/patches/d3-graphviz-npm-5.3.0-e0eace978a.patch",
     "d3-selection": "^3.0.0",
     "d3-zoom": "patch:d3-zoom@npm%3A3.0.0#~/.yarn/patches/d3-zoom-npm-3.0.0-18f706a421.patch",
@@ -78,6 +79,7 @@
   "devDependencies": {
     "@lezer/generator": "^1.6.0",
     "@types/d3": "^7.4.3",
+    "@types/d3-color": "^3.1.3",
     "@types/d3-graphviz": "^2.6.10",
     "@types/d3-selection": "^3.0.10",
     "@types/d3-zoom": "^3.0.8",
diff --git a/subprojects/frontend/src/editor/EditorArea.tsx b/subprojects/frontend/src/editor/EditorArea.tsx
index aafaad40..ae5cff34 100644
--- a/subprojects/frontend/src/editor/EditorArea.tsx
+++ b/subprojects/frontend/src/editor/EditorArea.tsx
@@ -39,6 +39,7 @@ export default observer(function EditorArea({
         showLineNumbers={editorStore.showLineNumbers}
         showActiveLine={!editorStore.hasSelection}
         colorIdentifiers={editorStore.colorIdentifiers}
+        hexTypeHashes={editorStore.hexTypeHashes}
         ref={editorParentRef}
       />
     </Box>
diff --git a/subprojects/frontend/src/editor/EditorStore.ts b/subprojects/frontend/src/editor/EditorStore.ts
index 33bca382..f128d70d 100644
--- a/subprojects/frontend/src/editor/EditorStore.ts
+++ b/subprojects/frontend/src/editor/EditorStore.ts
@@ -111,6 +111,8 @@ export default class EditorStore {
 
   unsavedChanges = false;
 
+  hexTypeHashes: string[] = [];
+
   constructor(
     initialValue: string,
     pwaStore: PWAStore,
@@ -275,8 +277,12 @@ export default class EditorStore {
     this.doCommand(nextDiagnostic);
   }
 
-  updateSemanticHighlighting(ranges: IHighlightRange[]): void {
+  updateSemanticHighlighting(
+    ranges: IHighlightRange[],
+    hexTypeHashes: string[],
+  ): void {
     this.dispatch(setSemanticHighlighting(ranges));
+    this.hexTypeHashes = hexTypeHashes;
   }
 
   updateOccurrences(write: IOccurrence[], read: IOccurrence[]): void {
diff --git a/subprojects/frontend/src/editor/EditorTheme.ts b/subprojects/frontend/src/editor/EditorTheme.ts
index 4978c7f7..6deda080 100644
--- a/subprojects/frontend/src/editor/EditorTheme.ts
+++ b/subprojects/frontend/src/editor/EditorTheme.ts
@@ -14,6 +14,7 @@ import {
   type CSSObject,
   type Theme,
 } from '@mui/material/styles';
+import { lch } from 'd3-color';
 import { range } from 'lodash-es';
 
 import svgURL from '../utils/svgURL';
@@ -21,6 +22,7 @@ import svgURL from '../utils/svgURL';
 function createTypeHashStyles(
   theme: Theme,
   colorIdentifiers: boolean,
+  hexTypeHashes: string[],
 ): CSSObject {
   if (!colorIdentifiers) {
     return {};
@@ -34,6 +36,26 @@ function createTypeHashStyles(
       },
     };
   });
+  hexTypeHashes.forEach((typeHash) => {
+    let color = lch(`#${typeHash}`);
+    if (theme.palette.mode === 'dark') {
+      color = color.brighter();
+      if (color.l < 60) {
+        color.l = 60;
+      }
+    } else {
+      color = color.darker();
+      if (color.l > 60) {
+        color.l = 60;
+      }
+    }
+    result[`.tok-problem-typeHash-_${typeHash}`] = {
+      '&, .tok-typeName': {
+        color: color.formatRgb(),
+        fontWeight: theme.typography.fontWeightEditorTypeHash,
+      },
+    };
+  });
   return result;
 }
 
@@ -42,12 +64,20 @@ export default styled('div', {
   shouldForwardProp: (propName) =>
     propName !== 'showLineNumbers' &&
     propName !== 'showActiveLine' &&
-    propName !== 'colorIdentifiers',
+    propName !== 'colorIdentifiers' &&
+    propName !== 'hexTypeHashes',
 })<{
   showLineNumbers: boolean;
   showActiveLine: boolean;
   colorIdentifiers: boolean;
-}>(({ theme, showLineNumbers, showActiveLine, colorIdentifiers }) => {
+  hexTypeHashes: string[];
+}>(({
+  theme,
+  showLineNumbers,
+  showActiveLine,
+  colorIdentifiers,
+  hexTypeHashes,
+}) => {
   const editorFontStyle: CSSObject = {
     ...theme.typography.editor,
     fontWeight: theme.typography.fontWeightEditorNormal,
@@ -157,7 +187,7 @@ export default styled('div', {
         fontStyle: 'normal',
       },
     },
-    ...createTypeHashStyles(theme, colorIdentifiers),
+    ...createTypeHashStyles(theme, colorIdentifiers, hexTypeHashes),
   };
 
   const matchingStyle: CSSObject = {
diff --git a/subprojects/frontend/src/graph/DotGraphVisualizer.tsx b/subprojects/frontend/src/graph/DotGraphVisualizer.tsx
index cc8b5116..0980ea20 100644
--- a/subprojects/frontend/src/graph/DotGraphVisualizer.tsx
+++ b/subprojects/frontend/src/graph/DotGraphVisualizer.tsx
@@ -154,7 +154,13 @@ function DotGraphVisualizer({
     ],
   );
 
-  return <GraphTheme ref={setElement} colorNodes={graph.colorNodes} />;
+  return (
+    <GraphTheme
+      ref={setElement}
+      colorNodes={graph.colorNodes}
+      hexTypeHashes={graph.hexTypeHashes}
+    />
+  );
 }
 
 DotGraphVisualizer.defaultProps = {
diff --git a/subprojects/frontend/src/graph/GraphStore.ts b/subprojects/frontend/src/graph/GraphStore.ts
index d9282326..301b4d86 100644
--- a/subprojects/frontend/src/graph/GraphStore.ts
+++ b/subprojects/frontend/src/graph/GraphStore.ts
@@ -49,6 +49,8 @@ export function isVisibilityAllowed(
   return true;
 }
 
+const TYPE_HASH_HEX_PREFFIX = '_';
+
 export default class GraphStore {
   semantics: SemanticsSuccessResult = {
     nodes: [],
@@ -66,6 +68,10 @@ export default class GraphStore {
 
   selectedSymbol: RelationMetadata | undefined;
 
+  hexTypeHashes: string[] = [];
+
+  private typeHashesMap = new Map<string, number>();
+
   constructor(
     private readonly editorStore: EditorStore,
     private readonly nameOverride?: string,
@@ -188,6 +194,36 @@ export default class GraphStore {
       this.visibility.delete(key);
     });
     this.setSelectedSymbol(this.selectedSymbol);
+    this.updateTypeHashes();
+  }
+
+  /**
+   * Maintains a list of past and current color codes to avoid flashing
+   * when the graph view updates.
+   *
+   * As long as the previously used colors are still in in `typeHashesMap`,
+   * the view will not flash while Graphviz is recomputing, because we'll
+   * keep emitting styles for the colors.
+   */
+  private updateTypeHashes(): void {
+    this.semantics.nodes.forEach(({ typeHash }) => {
+      if (
+        typeHash !== undefined &&
+        typeHash.startsWith(TYPE_HASH_HEX_PREFFIX)
+      ) {
+        const key = typeHash.substring(TYPE_HASH_HEX_PREFFIX.length);
+        this.typeHashesMap.set(key, 0);
+      }
+    });
+    this.hexTypeHashes = Array.from(this.typeHashesMap.keys());
+    this.hexTypeHashes.forEach((typeHash) => {
+      const age = this.typeHashesMap.get(typeHash);
+      if (age !== undefined && age < 10) {
+        this.typeHashesMap.set(typeHash, age + 1);
+      } else {
+        this.typeHashesMap.delete(typeHash);
+      }
+    });
   }
 
   get colorNodes(): boolean {
diff --git a/subprojects/frontend/src/graph/GraphTheme.tsx b/subprojects/frontend/src/graph/GraphTheme.tsx
index 34954345..50a003e0 100644
--- a/subprojects/frontend/src/graph/GraphTheme.tsx
+++ b/subprojects/frontend/src/graph/GraphTheme.tsx
@@ -13,10 +13,13 @@ import {
   type CSSObject,
   type Theme,
 } from '@mui/material/styles';
+import { lch } from 'd3-color';
 import { range } from 'lodash-es';
 
 import svgURL from '../utils/svgURL';
 
+import obfuscateColor from './obfuscateColor';
+
 function createEdgeColor(
   suffix: string,
   stroke: string,
@@ -37,16 +40,32 @@ function createEdgeColor(
   };
 }
 
-function createTypeHashStyles(theme: Theme, colorNodes: boolean): CSSObject {
+function createTypeHashStyles(
+  theme: Theme,
+  colorNodes: boolean,
+  typeHashes: string[],
+): CSSObject {
   if (!colorNodes) {
     return {};
   }
   const result: CSSObject = {};
   range(theme.palette.highlight.typeHash.length).forEach((i) => {
-    result[`.node-typeHash-${i} .node-header`] = {
+    result[`.node-typeHash-${obfuscateColor(i.toString(10))} .node-header`] = {
       fill: theme.palette.highlight.typeHash[i]?.box,
     };
   });
+  typeHashes.forEach((typeHash) => {
+    let color = lch(`#${typeHash}`);
+    if (theme.palette.mode === 'dark') {
+      color = color.darker();
+      if (color.l > 50) {
+        color.l = 50;
+      }
+    }
+    result[`.node-typeHash-_${obfuscateColor(typeHash)} .node-header`] = {
+      fill: color.formatRgb(),
+    };
+  });
   return result;
 }
 
@@ -69,10 +88,12 @@ function iconStyle(
 export function createGraphTheme({
   theme,
   colorNodes,
+  hexTypeHashes,
   noEmbedIcons,
 }: {
   theme: Theme;
   colorNodes: boolean;
+  hexTypeHashes: string[];
   noEmbedIcons?: boolean;
 }): CSSObject {
   const shadowAlapha = theme.palette.mode === 'dark' ? 0.32 : 0.24;
@@ -111,7 +132,7 @@ export function createGraphTheme({
     '.node-exists-UNKNOWN .node-outline': {
       strokeDasharray: '5 2',
     },
-    ...createTypeHashStyles(theme, colorNodes),
+    ...createTypeHashStyles(theme, colorNodes, hexTypeHashes),
     '.edge': {
       '& text': {
         fontFamily: theme.typography.fontFamily,
@@ -155,7 +176,9 @@ export function createGraphTheme({
 
 export default styled('div', {
   name: 'GraphTheme',
-})<{ colorNodes: boolean }>((args) => ({
+  shouldForwardProp: (prop) =>
+    prop !== 'colorNodes' && prop !== 'hexTypeHashes',
+})<{ colorNodes: boolean; hexTypeHashes: string[] }>((args) => ({
   '& svg': {
     userSelect: 'none',
     ...createGraphTheme(args),
diff --git a/subprojects/frontend/src/graph/dotSource.ts b/subprojects/frontend/src/graph/dotSource.ts
index 3ac5eb1c..bcd386cf 100644
--- a/subprojects/frontend/src/graph/dotSource.ts
+++ b/subprojects/frontend/src/graph/dotSource.ts
@@ -10,6 +10,7 @@ import type {
 } from '../xtext/xtextServiceResults';
 
 import type GraphStore from './GraphStore';
+import obfuscateColor from './obfuscateColor';
 
 const EDGE_WEIGHT = 1;
 const CONTAINMENT_WEIGHT = 5;
@@ -143,7 +144,7 @@ function createNodes(
       classList.push('node-empty');
     }
     if (node.typeHash !== undefined) {
-      classList.push(`node-typeHash-${node.typeHash}`);
+      classList.push(`node-typeHash-${obfuscateColor(node.typeHash)}`);
     }
     const classes = classList.join(' ');
     const name = nodeName(graph, node);
diff --git a/subprojects/frontend/src/graph/export/exportDiagram.tsx b/subprojects/frontend/src/graph/export/exportDiagram.tsx
index 44489d28..6abbcfdf 100644
--- a/subprojects/frontend/src/graph/export/exportDiagram.tsx
+++ b/subprojects/frontend/src/graph/export/exportDiagram.tsx
@@ -147,6 +147,7 @@ function appendStyles(
   svg: SVGSVGElement,
   theme: Theme,
   colorNodes: boolean,
+  hexTypeHashes: string[],
   fontsCSS: string,
 ): void {
   const cache = createCache({
@@ -159,6 +160,7 @@ function appendStyles(
   const styles = serializeStyles([createGraphTheme], cache.registered, {
     theme,
     colorNodes,
+    hexTypeHashes,
     noEmbedIcons: true,
   });
   const rules: string[] = [fontsCSS];
@@ -336,7 +338,14 @@ export default async function exportDiagram(
   } else if (settings.format === 'svg' && settings.embedFonts) {
     fontsCSS = await fetchFontCSS();
   }
-  appendStyles(svgDocument, copyOfSVG, theme, colorNodes, fontsCSS);
+  appendStyles(
+    svgDocument,
+    copyOfSVG,
+    theme,
+    colorNodes,
+    graph.hexTypeHashes,
+    fontsCSS,
+  );
 
   if (settings.format === 'pdf') {
     const pdf = await serializePDF(copyOfSVG, settings);
diff --git a/subprojects/frontend/src/graph/obfuscateColor.ts b/subprojects/frontend/src/graph/obfuscateColor.ts
new file mode 100644
index 00000000..57c15804
--- /dev/null
+++ b/subprojects/frontend/src/graph/obfuscateColor.ts
@@ -0,0 +1,21 @@
+/*
+ * SPDX-FileCopyrightText: 2023-2024 The Refinery Authors <https://refinery.tools/>
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+
+const regExp = /\d/g;
+const offset = 'g'.charCodeAt(0) - '0'.charCodeAt(0);
+
+/*
+ * The SVG animation framework we use garbles all numbers while interpolating,
+ * so we mask numbers in hex color codes by replacing them with letters.
+ *
+ * @param color The hex code.
+ * @return The hex code with no number characters.
+ */
+export default function obfuscateColor(color: string): string {
+  return color.replaceAll(regExp, (match) =>
+    String.fromCharCode(match.charCodeAt(0) + offset),
+  );
+}
diff --git a/subprojects/frontend/src/xtext/HighlightingService.ts b/subprojects/frontend/src/xtext/HighlightingService.ts
index 447f1401..eacee117 100644
--- a/subprojects/frontend/src/xtext/HighlightingService.ts
+++ b/subprojects/frontend/src/xtext/HighlightingService.ts
@@ -10,6 +10,8 @@ import type { IHighlightRange } from '../editor/semanticHighlighting';
 import type UpdateService from './UpdateService';
 import { highlightingResult } from './xtextServiceResults';
 
+const TYPE_HASH_HEX_PREFIX = 'typeHash-_';
+
 export default class HighlightingService {
   constructor(
     private readonly store: EditorStore,
@@ -20,6 +22,7 @@ export default class HighlightingService {
     const { regions } = highlightingResult.parse(push);
     const allChanges = this.updateService.computeChangesSinceLastUpdate();
     const ranges: IHighlightRange[] = [];
+    const hexTypeHashes = new Set<string>();
     regions.forEach(({ offset, length, styleClasses }) => {
       if (styleClasses.length === 0) {
         return;
@@ -34,11 +37,16 @@ export default class HighlightingService {
         to,
         classes: styleClasses,
       });
+      styleClasses.forEach((styleClass) => {
+        if (styleClass.startsWith(TYPE_HASH_HEX_PREFIX)) {
+          hexTypeHashes.add(styleClass.substring(TYPE_HASH_HEX_PREFIX.length));
+        }
+      });
     });
-    this.store.updateSemanticHighlighting(ranges);
+    this.store.updateSemanticHighlighting(ranges, Array.from(hexTypeHashes));
   }
 
   onDisconnect(): void {
-    this.store.updateSemanticHighlighting([]);
+    this.store.updateSemanticHighlighting([], []);
   }
 }
diff --git a/subprojects/language-ide/src/main/java/tools/refinery/language/ide/syntaxcoloring/TypeHashProvider.java b/subprojects/language-ide/src/main/java/tools/refinery/language/ide/syntaxcoloring/TypeHashProvider.java
index dd9f1053..82a6af06 100644
--- a/subprojects/language-ide/src/main/java/tools/refinery/language/ide/syntaxcoloring/TypeHashProvider.java
+++ b/subprojects/language-ide/src/main/java/tools/refinery/language/ide/syntaxcoloring/TypeHashProvider.java
@@ -5,16 +5,17 @@
  */
 package tools.refinery.language.ide.syntaxcoloring;
 
-import com.google.common.collect.ImmutableMap;
 import com.google.inject.Inject;
 import com.google.inject.Singleton;
 import org.eclipse.xtext.EcoreUtil2;
 import org.eclipse.xtext.naming.IQualifiedNameConverter;
 import org.eclipse.xtext.naming.IQualifiedNameProvider;
+import org.eclipse.xtext.resource.IEObjectDescription;
 import org.eclipse.xtext.resource.IResourceDescription;
 import org.eclipse.xtext.scoping.IScopeProvider;
 import org.eclipse.xtext.scoping.impl.GlobalResourceDescriptionProvider;
 import org.eclipse.xtext.util.IResourceScopeCache;
+import tools.refinery.language.documentation.DocumentationCommentParser;
 import tools.refinery.language.model.problem.*;
 import tools.refinery.language.resource.ProblemResourceDescriptionStrategy;
 import tools.refinery.language.scoping.imports.ImportCollector;
@@ -65,21 +66,30 @@ public class TypeHashProvider {
 
         private Map<String, String> computeHashes(Problem problem) {
                 var resourceDescriptions = getResourceDescriptions(problem);
+                var map = new HashMap<String, String>();
                 var qualifiedNameStrings = new TreeSet<String>();
                 for (var resourceDescription : resourceDescriptions) {
                         for (var description : resourceDescription.getExportedObjectsByType(ProblemPackage.Literals.RELATION)) {
                                 if (ProblemResourceDescriptionStrategy.COLOR_RELATION_TRUE.equals(
                                                 description.getUserData(ProblemResourceDescriptionStrategy.COLOR_RELATION))) {
                                         var qualifiedNameString = qualifiedNameConverter.toString(description.getQualifiedName());
+                                        var presetColor = getPresetColor(description);
+                                        if (presetColor != null) {
+                                                map.put(qualifiedNameString, presetColor);
+                                        }
                                         qualifiedNameStrings.add(qualifiedNameString);
                                 }
                         }
                 }
                 var stringList = new ArrayList<>(qualifiedNameStrings);
                 int size = stringList.size();
-                if (size == 0) {
-                        return Map.of();
+                if (size != 0) {
+                        shuffleColors(size, stringList, map);
                 }
+                return Collections.unmodifiableMap(map);
+        }
+
+        private static void shuffleColors(int size, ArrayList<String> stringList, Map<String, String> map) {
                 // The use of a non-cryptographic random generator is safe here, because we only use it to shuffle the color
                 // IDs in a pseudo-random way. The shuffle depends on the size of the list of identifiers before padding to
                 // make sure that adding a new class randomizes all color IDs.
@@ -91,15 +101,13 @@ public class TypeHashProvider {
                 }
                 size += padding;
                 Collections.shuffle(stringList, random);
-                var mapBuilder = ImmutableMap.<String, String>builder();
                 for (int i = 0; i < size; i++) {
                         var key = stringList.get(i);
                         if (key != null) {
                                 int colorId = i % COLOR_COUNT;
-                                mapBuilder.put(key, Integer.toString(colorId));
+                                map.putIfAbsent(key, Integer.toString(colorId));
                         }
                 }
-                return mapBuilder.build();
         }
 
         private List<IResourceDescription> getResourceDescriptions(Problem problem) {
@@ -127,4 +135,8 @@ public class TypeHashProvider {
                 }
                 return resourceDescriptions;
         }
+
+        private String getPresetColor(IEObjectDescription description) {
+                return description.getUserData(DocumentationCommentParser.COLOR_TAG);
+        }
 }
diff --git a/subprojects/language/src/main/java/tools/refinery/language/ProblemRuntimeModule.java b/subprojects/language/src/main/java/tools/refinery/language/ProblemRuntimeModule.java
index f9a564b0..f7039027 100644
--- a/subprojects/language/src/main/java/tools/refinery/language/ProblemRuntimeModule.java
+++ b/subprojects/language/src/main/java/tools/refinery/language/ProblemRuntimeModule.java
@@ -12,6 +12,7 @@ package tools.refinery.language;
 import com.google.inject.Binder;
 import com.google.inject.name.Names;
 import org.eclipse.xtext.conversion.IValueConverterService;
+import org.eclipse.xtext.documentation.impl.AbstractMultiLineCommentProvider;
 import org.eclipse.xtext.linking.ILinkingService;
 import org.eclipse.xtext.naming.IQualifiedNameConverter;
 import org.eclipse.xtext.naming.IQualifiedNameProvider;
@@ -144,4 +145,11 @@ public class ProblemRuntimeModule extends AbstractProblemRuntimeModule {
         public Class<? extends IDiagnosticConverter> bindIDiagnosticConverter() {
                 return ProblemDiagnosticConverter.class;
         }
+
+        public void configureAbstractMultiLineCommentProvider(Binder binder) {
+                // Only parse documentation tags from Javadoc-style comments.
+                binder.bind(String.class)
+                                .annotatedWith(Names.named(AbstractMultiLineCommentProvider.START_TAG))
+                                .toInstance("/\\*\\*");
+        }
 }
diff --git a/subprojects/language/src/main/java/tools/refinery/language/documentation/DocumentationCommentParser.java b/subprojects/language/src/main/java/tools/refinery/language/documentation/DocumentationCommentParser.java
new file mode 100644
index 00000000..3586abd2
--- /dev/null
+++ b/subprojects/language/src/main/java/tools/refinery/language/documentation/DocumentationCommentParser.java
@@ -0,0 +1,42 @@
+/*
+ * SPDX-FileCopyrightText: 2024 The Refinery Authors <https://refinery.tools/>
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package tools.refinery.language.documentation;
+
+import com.google.inject.Inject;
+import com.google.inject.Singleton;
+import org.eclipse.emf.ecore.EObject;
+import org.eclipse.xtext.documentation.IEObjectDocumentationProvider;
+
+import java.util.Locale;
+import java.util.Map;
+import java.util.regex.Pattern;
+
+@Singleton
+public class DocumentationCommentParser {
+        private static final String PREFIX = "tools.refinery.language.documentation.DocumentationCommentParser.";
+        public static final String COLOR_TAG = PREFIX + "COLOR_TAG";
+
+        private static final Pattern COLOR_PATTERN = Pattern.compile(
+                        "(?m)^@color[ \t]+(\\d|#[\\da-fA-F]{6}|#[\\da-fA-F]{3})");
+
+        @Inject
+        private IEObjectDocumentationProvider documentationProvider;
+
+        public Map<String, String> parseDocumentation(EObject eObject) {
+                var documentation = documentationProvider.getDocumentation(eObject);
+                if (documentation == null) {
+                        return Map.of();
+                }
+                var colorMatch = COLOR_PATTERN.matcher(documentation);
+                if (colorMatch.find()) {
+                        // Use a {@code _} instead of a {@code #} to signify hex codes, because the type hashes have to be valid
+                        // CSS class names.
+                        var color = colorMatch.group(1).toLowerCase(Locale.ROOT).replace("#", "_");
+                        return Map.of(COLOR_TAG, color);
+                }
+                return Map.of();
+        }
+}
diff --git a/subprojects/language/src/main/java/tools/refinery/language/resource/ProblemResourceDescriptionStrategy.java b/subprojects/language/src/main/java/tools/refinery/language/resource/ProblemResourceDescriptionStrategy.java
index 3080a78e..3dcf6b1f 100644
--- a/subprojects/language/src/main/java/tools/refinery/language/resource/ProblemResourceDescriptionStrategy.java
+++ b/subprojects/language/src/main/java/tools/refinery/language/resource/ProblemResourceDescriptionStrategy.java
@@ -18,6 +18,7 @@ import org.eclipse.xtext.resource.EObjectDescription;
 import org.eclipse.xtext.resource.IEObjectDescription;
 import org.eclipse.xtext.resource.impl.DefaultResourceDescriptionStrategy;
 import org.eclipse.xtext.util.IAcceptor;
+import tools.refinery.language.documentation.DocumentationCommentParser;
 import tools.refinery.language.naming.ProblemQualifiedNameProvider;
 import tools.refinery.language.scoping.imports.ImportCollector;
 import tools.refinery.language.model.problem.*;
@@ -56,6 +57,9 @@ public class ProblemResourceDescriptionStrategy extends DefaultResourceDescripti
         @Inject
         private ImportCollector importCollector;
 
+        @Inject
+        private DocumentationCommentParser documentationCommentParser;
+
         @Override
         public boolean createEObjectDescriptions(EObject eObject, IAcceptor<IEObjectDescription> acceptor) {
                 if (!shouldExport(eObject)) {
@@ -154,6 +158,8 @@ public class ProblemResourceDescriptionStrategy extends DefaultResourceDescripti
                 if (eObject instanceof PredicateDefinition predicateDefinition && predicateDefinition.isError()) {
                         builder.put(ERROR_PREDICATE, ERROR_PREDICATE_TRUE);
                 }
+                var documentationMap = documentationCommentParser.parseDocumentation(eObject);
+                builder.putAll(documentationMap);
                 return builder.build();
         }
 
diff --git a/subprojects/language/src/test/java/tools/refinery/language/tests/documentation/DocumentationCommentParserTest.java b/subprojects/language/src/test/java/tools/refinery/language/tests/documentation/DocumentationCommentParserTest.java
new file mode 100644
index 00000000..0566e7e2
--- /dev/null
+++ b/subprojects/language/src/test/java/tools/refinery/language/tests/documentation/DocumentationCommentParserTest.java
@@ -0,0 +1,94 @@
+/*
+ * SPDX-FileCopyrightText: 2024 The Refinery Authors <https://refinery.tools/>
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package tools.refinery.language.tests.documentation;
+
+import com.google.inject.Inject;
+import org.eclipse.xtext.testing.InjectWith;
+import org.eclipse.xtext.testing.extensions.InjectionExtension;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+import tools.refinery.language.documentation.DocumentationCommentParser;
+import tools.refinery.language.model.tests.utils.ProblemParseHelper;
+import tools.refinery.language.tests.ProblemInjectorProvider;
+
+import java.util.stream.Stream;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.is;
+
+@ExtendWith(InjectionExtension.class)
+@InjectWith(ProblemInjectorProvider.class)
+class DocumentationCommentParserTest {
+        @Inject
+        private ProblemParseHelper parseHelper;
+
+        @Inject
+        private DocumentationCommentParser commentParser;
+
+        @ParameterizedTest
+        @MethodSource
+        void colorTest(String text, String expectedColor) {
+                var parseResult = parseHelper.parse(text);
+                var foo = parseResult.findClass("Foo").classDeclaration();
+                var documentation = commentParser.parseDocumentation(foo);
+                var actualColor = documentation.get(DocumentationCommentParser.COLOR_TAG);
+                assertThat(actualColor, is(expectedColor));
+        }
+
+        static Stream<Arguments> colorTest() {
+                return Stream.of(
+                                Arguments.of("class Foo.", null),
+                                Arguments.of("""
+                                                % @color #ff0000
+                                                class Foo.
+                                                """, null),
+                                Arguments.of("""
+                                                /*
+                                                 * @color #ff0000
+                                                 */
+                                                class Foo.
+                                                """, null),
+                                Arguments.of("""
+                                                /**
+                                                 * @color #ff0000
+                                                 */
+                                                class Foo.
+                                                """, "_ff0000"),
+                                Arguments.of("""
+                                                /**
+                                                 * @color #ff0000 other
+                                                 */
+                                                class Foo.
+                                                """, "_ff0000"),
+                                Arguments.of("""
+                                                /** @color #ff0000 */
+                                                class Foo.
+                                                """, "_ff0000"),
+                                Arguments.of("""
+                                                /**@color #ff0000*/
+                                                class Foo.
+                                                """, "_ff0000"),
+                                Arguments.of("""
+                                                /**@color\t  #ff0000*/
+                                                class Foo.
+                                                """, "_ff0000"),
+                                Arguments.of("""
+                                                /** @color #F2af00 */
+                                                class Foo.
+                                                """, "_f2af00"),
+                                Arguments.of("""
+                                                /** @color #Fa0 */
+                                                class Foo.
+                                                """, "_fa0"),
+                                Arguments.of("""
+                                                /** @color 4 */
+                                                class Foo.
+                                                """, "4")
+                );
+        }
+}
diff --git a/yarn.lock b/yarn.lock
index 13125135..98cbf7fc 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -2192,6 +2192,7 @@ __metadata:
     "@mui/system": "npm:^5.15.11"
     "@mui/x-data-grid": "npm:^6.19.5"
     "@types/d3": "npm:^7.4.3"
+    "@types/d3-color": "npm:^3.1.3"
     "@types/d3-graphviz": "npm:^2.6.10"
     "@types/d3-selection": "npm:^3.0.10"
     "@types/d3-zoom": "npm:^3.0.8"
@@ -2213,6 +2214,7 @@ __metadata:
     cross-env: "npm:^7.0.3"
     csstype: "npm:^3.1.3"
     d3: "npm:^7.8.5"
+    d3-color: "npm:^3.1.0"
     d3-graphviz: "patch:d3-graphviz@npm%3A5.3.0#~/.yarn/patches/d3-graphviz-npm-5.3.0-e0eace978a.patch"
     d3-selection: "npm:^3.0.0"
     d3-zoom: "patch:d3-zoom@npm%3A3.0.0#~/.yarn/patches/d3-zoom-npm-3.0.0-18f706a421.patch"
@@ -2607,6 +2609,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/d3-color@npm:^3.1.3":
+  version: 3.1.3
+  resolution: "@types/d3-color@npm:3.1.3"
+  checksum: 10c0/65eb0487de606eb5ad81735a9a5b3142d30bc5ea801ed9b14b77cb14c9b909f718c059f13af341264ee189acf171508053342142bdf99338667cea26a2d8d6ae
+  languageName: node
+  linkType: hard
+
 "@types/d3-contour@npm:*":
   version: 3.0.2
   resolution: "@types/d3-contour@npm:3.0.2"
@@ -4133,7 +4142,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"d3-color@npm:1 - 3, d3-color@npm:3":
+"d3-color@npm:1 - 3, d3-color@npm:3, d3-color@npm:^3.1.0":
   version: 3.1.0
   resolution: "d3-color@npm:3.1.0"
   checksum: 10c0/a4e20e1115fa696fce041fbe13fbc80dc4c19150fa72027a7c128ade980bc0eeeba4bcf28c9e21f0bce0e0dbfe7ca5869ef67746541dcfda053e4802ad19783c