How to Create Custom Semantic Tech Labels and Map Them to Visual Categories in Archify
Archify converts technology names like "Kafka" or "Redis" into CSS custom property-driven visual categories by prefixing them with c- and mapping them to color variables in the HTML template.
Archify (tt-a1i/archify) is an open-source diagramming engine that renders JSON Intermediate Representation (IR) into SVG architecture diagrams. By creating custom semantic tech labels, you can tag nodes with technology identifiers that automatically drive visual styling—eliminating the need for heavyweight icon assets while maintaining consistent color coding across your documentation.
Declare Tech Labels in the JSON IR
Each node in your Archify diagram accepts a technology field that accepts either a single string or an array of strings. These values become semantic class identifiers that the renderer uses during SVG generation.
In your JSON IR (typically stored in files like archify/examples/workflow-example.json), attach labels to nodes as follows:
{
"id": "order-service",
"type": "service",
"technology": ["Kafka", "Redis"]
}
Archify processes this array and generates corresponding CSS classes on the SVG elements. According to archify/SKILL.md, the renderer treats these labels as semantic class identifiers that control visual appearance.
Map Labels to Visual Categories with CSS Custom Properties
Archify's styling system relies on CSS custom properties (variables) defined in the HTML wrapper. The built-in template at archify/assets/template.html provides the foundation, but you extend it by declaring variables that match your custom labels.
Define Color Variables
Add CSS variables to your HTML template following the --c-{label} naming convention. Archify's built-in stylesheet automatically recognizes any variable prefixed with --c- and applies it to elements carrying the corresponding class.
:root {
--c-kafka: #ff7043; /* orange-red for streaming */
--c-redis: #4caf50; /* green for caching */
--c-s3: #2196f3; /* blue for object storage */
}
Create CSS Rules for Visual Styling
While Archify includes generic rules that consume --c-* variables, you should explicitly define how each class renders. Archify automatically prefixes every technology label with c- when generating SVG classes, converting Kafka into c-kafka.
Add specific rules to your <style> block to control fill, stroke, or opacity:
.c-kafka {
fill: var(--c-kafka);
stroke: var(--c-kafka);
stroke-width: 2px;
}
.c-redis {
fill: var(--c-redis);
transition: all 0.2s ease;
}
As documented in README.md (lines 390-406), this approach allows semantic labels to drive the visual category mapping without modifying the core rendering logic.
Complete Working Example
The following HTML implementation demonstrates the full pipeline: declaring technologies in the JSON IR, defining CSS variables, and invoking archify.render() to generate the styled SVG.
<!DOCTYPE html>
<html data-theme="light">
<head>
<meta charset="utf-8">
<title>Custom Tech Labels Demo</title>
<style>
:root {
--c-kafka: #ff7043;
--c-redis: #4caf50;
}
.c-kafka, .c-redis {
transition: all 0.2s ease;
}
.c-kafka {
stroke: var(--c-kafka);
stroke-width: 2px;
}
</style>
</head>
<body>
<script type="application/json" id="archify-ir">
{
"diagram_type": "workflow",
"lanes": [{ "id": "main", "label": "User Journey" }],
"nodes": [
{
"id": "svc-A",
"type": "service",
"label": "Order Service",
"technology": ["Kafka", "Redis"]
}
],
"edges": []
}
</script>
<script src="https://cdn.jsdelivr.net/npm/archify@latest/dist/archify.js"></script>
<script>
archify.render(document.getElementById('archify-ir'));
</script>
</body>
</html>
When executed, Archify processes the IR, attaches the classes c-kafka and c-redis to the Order Service node, and applies the CSS variables to render the custom colors.
Summary
- Declare labels using the
technologyarray in your JSON IR nodes to create semantic identifiers. - Define variables in
archify/assets/template.htmlor your custom HTML wrapper using the--c-{label}pattern. - Target classes by referencing the
c-{label}format (lowercase, hyphenated) that Archify automatically generates from your technology names. - Extend styling beyond fill colors by adding stroke, opacity, or transition rules to the CSS classes.
- Reference examples in
archify/examples/*.jsonto see production implementations of thetechnologyfield.
Frequently Asked Questions
Where does Archify define the semantic class naming convention?
The naming convention is documented in archify/SKILL.md, which specifies that technology labels become semantic class identifiers prefixed with c- when rendered to SVG.
Can I customize attributes beyond fill color using semantic tech labels?
Yes. Since Archify injects the c-{label} class directly onto SVG elements, you can target these classes in your CSS to control any SVG presentation attribute, including stroke, stroke-width, opacity, and filter effects.
How do I render a diagram with custom tech labels programmatically?
Call archify.render() and pass the DOM element containing your JSON IR, as shown in archify/assets/template.html. The function automatically processes the technology arrays and applies the corresponding CSS classes to the generated SVG nodes.
What is the performance impact of using many custom tech labels?
Semantic tech labels introduce minimal overhead because they leverage standard CSS classes and custom properties. According to the source implementation, the renderer performs a simple string transformation (prefixing with c-) and relies on the browser's native CSS engine for styling, making this approach significantly lighter than embedding icon assets.
Have a question about this repo?
These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:
curl -s "https://instagit.com/install.md" 
Maintain an open-source project? Get it listed too →