using-likec4

name: using-likec4 description: Use when writing LikeC4 architecture diagrams, creating .c4 or .likec4 files, defining architecture-as-code with element kinds, relationships, views, or deployment models. Use when user mentions LikeC4, C4 diagrams, architecture-as-code, or structurizr-like syntax.

Using LikeC4

Overview

LikeC4 is architecture-as-code: define element kinds, model hierarchy, relationships, and views in .c4 files. Similar to Structurizr but with richer view predicates and deployment modeling.

Workflow

1. Write/edit .c4 files
2. Always validate: bun likec4 validate
3. Fix any errors before completing
4. Suggest bun likec4 dev for visual preview (starts dev server on port 5173)

MCP server: bun likec4 mcp provides live validation and feedback during editing.

File Structure

A .c4 file contains any combination of top-level blocks:

specification { }  // Define vocabulary: element kinds, relationship kinds, tags, colors
model { }          // Declare elements and relationships
views { }          // Define diagram views
global { }         // Reusable predicate groups and style groups
deployment { }     // Physical infrastructure layer

All .c4/.likec4 files in a folder merge into one model. Split freely across files.

Quick Reference

Icons

Always use icons where possible. Bundled packs (5000+ icons):

• aws: -- AWS architecture icons (aws-icons.com)
• tech: -- Technology/framework icons (techicons.dev)
• azure:, gcp:, bootstrap: -- also available

Bundled icons (except bootstrap:) auto-derive technology label.

NEVER guess icon names. Always look up the exact name in icons-aws.txt or icons-tech.txt in this skill directory before using an icon. AWS icon names are often not what you'd expect (e.g. aws:organizations not aws:aws-organizations, aws:cloud-watch not aws:cloudwatch, aws:virtual-private-cloud not aws:vpc).

icon aws:lambda        // AWS Lambda
icon tech:postgresql   // PostgreSQL
icon tech:react        // React
icon tech:django       // Django

CLI Reference

Common Mistakes

• Tags must be first in element body -- #tag before description, icon, etc. or parse error
• Tags declared without # in spec, used with # in model -- specification { tag prod } then element { #prod }
• Only valid colors: primary, secondary, muted, amber, gray, green, indigo, red, blue, sky, slate + custom colors defined in spec. No violet, purple, orange, etc.
• Guessing icon names -- AWS icons especially have non-obvious names. Always grep icons-aws.txt/icons-tech.txt first
• Dynamic views are top-level -- dynamic view name { } directly inside views {}, NOT nested inside a regular view
• Forgetting to define element kinds in specification before using them in model
• Using -> without a source outside an element body (inside element body, parent is implicit source)
• Missing include predicates in views -- views show nothing by default
• Using this/it outside element body context
• Forgetting that * in unscoped view = top-level only; in scoped view = element + children
• Using reserved keywords as element names (e.g. views, model, specification, global, deployment)
• All .c4 files in one folder merge into one model -- duplicate kind/element/view names across files cause errors
• In dynamic views, use full FQN paths (e.g. app.monolith.api) not short names

Reference Files

• syntax-reference.md -- Full DSL syntax for all blocks
• styling-reference.md -- All style properties, shapes, colors, icons
• like-c4.langium -- Raw Langium grammar for validation
• icons-aws.txt / icons-tech.txt -- Complete icon name lists
• templates/ -- Annotated starter examples

C4 Model Defaults

Follow standard C4 conventions as baseline:

• Person/Actor -- users of the system
• System -- top-level software systems
• Container -- deployable units (apps, databases, queues)
• Component -- logical groupings within containers