likec4-dsl

name: likec4-dsl description: Use when working with .c4/.likec4 files or LikeC4 CLI/config questions where exact DSL/CLI syntax is required, especially for strict command/snippet-first answers, validate/export flags, predicates */_/**, deployment snippets, dynamic views, or relationship extension matching.

LikeC4 DSL Skill

Architecture-as-code tool. Describe systems in .c4/.likec4 files and LikeC4 generates interactive diagrams.

Rules

1. Projects - it is possible to have multiple likec4 projects in a workspace, project is determined by presence of a config file (.likec4rc, likec4.config.{ts,js,json}). LikeC4 files belong to the project of the nearest config file in the directory hierarchy.
2. Top-level statements — only import, specification, model, deployment, views, global are allowed. Blocks can repeat, but at least one per file must be present.
3. Multi-file merge — Top-level blocks across files are merged. For example, model { ... } blocks present in multiple files, parsed separately, and then merged into a single model.
4. Strings — 'single', "double" — all support multi-line. Escape quotes with backslash: \' or \".
5. Markdown — properties like summary/description/notes can contain Markdown. Use triple quotes ''' or """. Begin a new line after opening quotes and indent Markdown content for better formatting and syntax highlighting.
6. Comments — // single line and /* multi-line */ comments supported anywhere.
7. Identifier — letters, digits, hyphens, underscores only. No dots (dots are FQN separators). Can't start with a digit. Examples: customer, payment-service, frontendApp, queue-1. Critical: payment-api is valid; payment.api is NOT an identifier (dots separate FQN hierarchy). See references/identifier-validity.md.
8. FQN — Fully Qualified Name (FQN) is a dot-separated path to an element, MUST be unique within the project. Examples: customer, saas.backend.payment-service.paymentsApi, infra.eu.zone1.node1.
9. References — LikeC4 has lexical scoping with hoisting, nested scope may shadow outer, like in JavaScript. That scope does not carry across files: even with imports/includes in the same project, cross-file references must use full FQNs. Tiny reminder: backend.api does not survive a file boundary; across files write the full path such as cloud.backend.api.

Response Discipline (critical for evals)

• If prompt says "minimal", "paste-ready", "strict", "exact", or requires a specific first line, output exactly one final command/snippet/verdict token first (no alternatives, no fallback variants, no extra preamble).
• Do not add unrequested title, labels, alternate snippets, or long explanations unless explicitly asked.
• Prefer exact requested tokens/phrases in the first line when the prompt requires strict phrasing.
• For strict command prompts, avoid ambiguous wording like "equivalent command" unless prompt explicitly asks for alternatives.
• If the task is snippet-first or command-first, a prose-only answer is a failure even if the explanation is knowledgeable.

CLI Canonical Contracts (anti-substitution guardrails)

• Validate family: use likec4 validate (never substitute with check, lint, or build).
• Export family: use likec4 export (never substitute with other command families).
• Validation flags contract for strict evals: --json --no-layout --file <path> ... <project-dir>.
• Multi-file validation contract: repeat --file once per edited .c4 / .likec4 source file.
• Export output flags contract: prefer --outdir or -o (avoid invented aliases).

Exact Syntax Guardrails (high-signal only)

Deployment snippets

• If the prompt asks for named deployment instances, use IDENTIFIER = instanceOf ELEMENT_ID.
• Do not substitute anonymous instanceOf ELEMENT_ID lines when naming is required.
• If the prompt asks for a full fixture, keep the minimal executable structure: specification, model, deployment, and views.

Relationship-extension matchers

• Relationship identity is matched by source + target + kind (+ title when needed).
• If typed relationships exist, omitting KIND is wrong for strict disambiguation prompts.
• If multiple relationships share source/target/kind, include the title in the matcher.
• Do not "simplify" a typed matcher to extend SOURCE -> TARGET ... when the prompt is testing exact relationship identity.

Triage anchor when typed alternatives coexist:

// Existing relationships
api -[async]-> queue "publishes"
api -[sync]-> queue "publishes"

// ✅ Correct: exact relationship selected
extend api -[async]-> queue "publishes" { metadata { retries "3" } }

// ⚠️ Ambiguous: kind omitted, async vs sync both match source/target/title family
extend api -> queue "publishes" { metadata { retries "3" } }

// ❌ Wrong: selects the other relationship
extend api -[sync]-> queue "publishes" { metadata { retries "3" } }

Compact ambiguity rule:

• Ambiguous — kind omitted while multiple typed relationships share the same source/target/title family and you are only explaining why the matcher is underspecified.
• Wrong — kind omitted when the task asks for the final matcher/snippet for a specific async/sync relationship.

Workflow

1. (Required) Find existing or create new project config (section below). Directory with project config defines the scope for all LikeC4 files in that directory and subdirectories. Ask user if you are uncertain about the scope.
2. (Required) Find existing or create new specification { ... }, this enables what kinds of elements/deployments/relationships/tags you can use. See Specification section below.
3. Architecture elements and relationships are defined in model { ... } block. See Model section below.
4. Deployment topology is defined in deployment { ... } block. See Deployment section below.
5. Views (diagrams) are defined in views { ... } block. See Views section below.
6. After editing LikeC4 files, validate with the CLI

Generate → Self-check → Finalize

For strict command/snippet prompts, keep a compact loop:

1. Generate only the requested final command/snippet.
2. Self-check quickly:

• exact command family / required flags / repeated --file count
• snippet-first or first-line contract satisfied
• predicate semantics (*, _, **) stated precisely
• scope / FQN correctness
• deployment naming requirement satisfied
• relationship matcher specificity (kind, title when needed)
• dynamic view exactness: return arrows, chain form, single parallel block when requested

3. Finalize by fixing in place (no extra alternatives unless explicitly requested).

Before final answer, verify the required tokens are literally present when the prompt depends on them (examples: --no-layout, instanceOf, variant sequence, global predicate, -[async]->, parallel {, <-).

Never claim CLI execution happened unless it actually ran.

Validation

<runtime> likec4 validate --json --no-layout --file <edited-file> <project-dir>

Runtime launchers are equivalent for this command family:

npx likec4 validate --json --no-layout --file <edited-file> <project-dir>
bunx likec4 validate --json --no-layout --file <edited-file> <project-dir>
pnpm dlx likec4 validate --json --no-layout --file <edited-file> <project-dir>

• --json — structured output (stdout), logging goes to stderr
• --no-layout — skip layout drift checks (faster, only syntax+semantic)
• --file <path> — use with --json to scope results to the edited files. Without --json, text output still prints all diagnostics. Repeat once per edited source file.
• <project-dir> — path to the project directory
• There is no likec4 check command; use likec4 validate.

For evals/gradings/executions, be runner-tolerant (npx/bunx/pnpm dlx), and judge correctness by subcommand + flags + project scope.

If workspace already has likec4 as a dependency, check its version from package.json and ensure it is at least 1.53.0. If pinning is needed, use the active runner (npx/bunx/pnpm dlx) with likec4@1.53.0.

Example output:

{
  "valid": false,
  "errors": [
    {
      "message": "...",
      "file": "/abs/path.c4",
      "line": 5,
      "range": { "start": { "line": 5, "character": 2 }, "end": { "line": 5, "character": 20 } }
    }
  ],
  "stats": {
    "totalFiles": 100, // Total number of files in the project
    "totalErrors": 500, // Total number of errors in the project
    "filteredFiles": 1, // Number of files that match the --file filter
    "filteredErrors": 1 // Number of errors in the filtered files
  }
}

Broken specification/model in a large project can cascade into lots of errors across all files. Always use --file to focus on the files you edited. If filteredErrors is 0 but totalErrors is high, your files are clean but something else in the project is broken (not your problem). Selfcheck that filteredFiles matches the number of files you passed to --file.

Field semantics (must be explicit in answers):

• filteredFiles: count of files actually included by repeated --file filters
• filteredErrors: errors in the filtered subset only
• totalErrors: errors across the full project model

Example edge case: if you pass 3 files but one is likec4.config.json, filteredFiles may be 2 because config JSON is not a .c4/.likec4 source file for DSL validation.

Export PNG flags (precision)

Canonical output directory flags:

• --outdir (long form)
• -o (short form)

Do not invent flags like --out-dir. Depending on LikeC4 version, --output may appear as compatibility alias; prefer --outdir/-o for deterministic answers.

Full CLI reference → references/cli.md

Canonical Snippets for High-Variance Families

Use these as exactness anchors when the prompt is testing syntax, not broad explanation.

predicateGroup reusable predicate

global {
  predicateGroup core-services {
    include cloud.* where kind is service
    exclude * where tag is #deprecated
  }
}

views {
  view service-overview {
    global predicate core-services
  }
}

Deployment fixture with named instances

deployment {
  vm appVm {
    primary = instanceOf cloud.api
    secondary = instanceOf cloud.api
  }
}

Scoped include semantics

views {
  view backend of cloud.backend {
    include *
    include -> cloud.backend
  }
}

Interpretation anchor: in a scoped view, include * means the scoped element plus its direct children as the base include set; neighbors can still appear through scoped relationship visibility.

Deployment-view styling guardrail

For strict repair prompts about deployment views, the safe answer is local style ... {} inside the deployment view.

Mini-reminder: in deployment views, treat include ... with {} and global style ... as unsupported repair patterns. Use a local style ... {} rule inside the deployment view instead.

LikeC4 Project Configuration

Config file (likec4.config.json, .likec4rc, or likec4.config.{ts,js}) defines a project. Its location sets the project scope (LikeC4 files belong to the project of the nearest config file in the directory hierarchy).

{
  "$schema": "https://likec4.dev/schemas/config.json",
  "name": "my-project",
  "title": "Project Title"
}

Key options: name (required, unique ID in the workspace), title (display name) Full reference → references/configuration.md

Specification

Defines all named vocabularies: element kinds, deployment node kinds, relationship kinds, tags, and custom color tokens. Must appear before those kinds are used in model or deployment blocks.

Key reminders: all definitions are global across files; duplicate kind/tag identifiers cause a validation error; specification changes trigger a full project re-parse — keep it in a dedicated spec.c4 file.

Full syntax, options per kind, and worked example → references/specification.md

Model

Hierarchical structure of elements and relationships. Elements have a kind (from specification), a unique identifier within their parent, and optional properties and nested elements.

Key reminders: this/it aliases the current element in nested relationships; cross-file references require full FQN; parent-child direct relationships are forbidden; extend FQN { } merges tags, metadata, and links into an existing element without redefining it.

Full syntax, extend patterns, property table, and worked example → references/model.md

Style

Style properties control visual appearance: color, shape, border, opacity, size, padding, textSize, icon, iconColor, iconSize, iconPosition, multiple. Relationship style extends this with line, head, and tail arrow shapes.

Full color token table, all shape values, border/opacity/size tokens, icon pack prefixes (aws:, azure:, gcp:, tech:, bootstrap:), and correct usage patterns → references/style-tokens-colors.md

To discover available icons, use the CLI: likec4 list-icons (text, one per line). Filter by group with --group <name>. Icon groups and approximate counts: aws (307), azure (614), gcp (216), tech (2000), bootstrap (~2051) (see references/cli.md for details).

Deployment

Maps logical model elements to physical infrastructure nodes using instanceOf. Uses deploymentNode kinds from specification. Inherits all logical model relationships automatically; additional deployment-level relationships can be defined inline.

Named vs. anonymous instances, multi-environment fixture, deployment relationships, and selection guidance → references/deployment.md

Views

Three view types: element views (view id or view id of element), dynamic views (dynamic view id), deployment views (deployment view id). View properties: title, description, metadata, link.

Include/exclude predicates, view-level style rules, groups, autoLayout, extends, navigateTo, and global predicate groups → references/views.md

Quick Decision Trees

"I need incoming relationship predicates"

Need inbound relation selection?
├─ From any source to target element → `include -> target`
├─ From explicit wildcard source     → `include * -> target`
└─ Include both directions around X  → `include -> X ->`

include -> X and include * -> X are related but not interchangeable in all contexts; prefer the exact form requested by user/eval.

Scoped Predicate Truth Card (*, _, **)

Hard rule: do not describe * as recursive; do not describe _ as wildcard-all; do not drop relationship-condition semantics for _ / **.

"I need to create a diagram/view or show a flow or sequence"

What kind of diagram?
├─ Interaction flow / sequence → Dynamic View
├─ Infrastructure / deployment → Deployment View
├─ From architecture model → Element View
│   ├─ Primary element known → Scoped view: `view name of element { ... }`
│   └─ Extend existing view → `view name extends other { ... }`
└─ Other → `view name { ... }`

"I need to style ..."

Styling?
├─ Style element(s) in a view → view `style` rule, see `references/views.md`
├─ Style element(s) in some views, but not all
│   ├─ views in same file → local view rule, see `references/views.md`
│   └─ views in different files → global view rule, see `references/views.md`
├─ Style element globally → property inside element definition, see Model section
├─ Style all elements of a kind → property inside kind specification, see Specification section
├─ Style by tag → view rule, see `references/views.md`
├─ Style relationship(s) in a view → view rule, see `references/views.md`
├─ Style relationship globally → property inside relationship definition, see Model section
├─ Style all relationships of a kind → property inside kind specification, see Specification section
├─ Reuse same styles across views → see `references/views.md`

"I need to organize across files"

Multi-file project?
├─ Import elements → import { backend } from './shared.c4'
├─ Cross-file lookup → short names do not inherit lexical/container scope across files; use full FQN
├─ Extend element → extend cloud.backend { service newSvc "New" }
├─ Extend relationship → extend cloud -> amazon { metadata { ... } }
├─ Metadata merge → Duplicate keys become arrays
├─ Organize views → views "Use Cases" { ... } (folder label)
└─ All blocks are mergeable across files

"I need to show a flow or sequence"

Flow / sequence diagram?
├─ Basic steps → source -> target "title"
├─ Response / backward → source <- target "returns"
├─ Parallel actions → one `parallel { ... }` block (also: `par { ... }`)
├─ Chained steps → customer -> frontend "x" -> backend "y"
├─ Step with notes → step { notes 'Markdown content' }
├─ Link to another view → step { navigateTo other-view }
├─ Sequence variant → dynamic view name { variant sequence }
└─ Full reference → references/dynamic-views.md

Return-arrow precision:

• If the prompt asks for response arrows back out, prefer <- steps rather than replacing them with new forward arrows.
• If the prompt asks for a body on a specific hop in a chain, attach the block only to that hop.
• If the prompt asks for one fan-out, keep sibling actions in one parallel { ... } block instead of multiple one-step parallel blocks.

Anti-Patterns to Avoid in Strict Prompts

Design Principles for Views

Apply when creating or editing views (not when answering syntax questions). Lessons from real-world model construction.

Less per view, more views

• Diagrams above ~10 boxes are unreadable regardless of grouping, shapes, or styling.
• If a view has >10 boxes, split it rather than trying to make density work. Group blocks help at the margins; they don't rescue an over-budget view.
• For central elements (high in-degree + out-degree), split inbound and outbound into two views:

  view centered_x_outbound of project { include x -> }
  view centered_x_inbound  of project { include -> x }
  

• Prefer many focused views over one comprehensive view. A reader needing the whole picture can flip between views; a reader needing one part is poorly served by a dense composite.

View categories to plan for

For non-trivial systems, ship multiple parallel view families:

Different audiences read different families. Don't force one family to serve all.

Visual structure tools (groups + shapes)

• Groups in views cluster elements visually. Use when you have ~5-10 elements falling into 2-4 logical clusters. They don't compensate for too many elements.
• Shapes differentiate element kinds across every view they appear in. Define at element-kind level in specification (e.g. element webapp { style { shape browser } }). Per-element shape overrides via style { shape X } inside a container "Name" { … } block are not reliably honored in current LikeC4 — prefer defining specialised kinds.
• Group colors style the group's background, not the element boxes. Useful for tier coloring without overriding brand element color.

Icons, colour, and relationship styling (high-impact expressiveness)

The single biggest skimmability win is icons — a reader recognises a box by its logo before reading the label. Use all three channels (colour = which tier, shape + icon = what kind, line = how it talks).

• Icons. Add icon <pack>:<name> as a direct element property (NOT inside style { }) — icon as a direct property renders; verify the name with npx likec4 list-icons. Prefer real tech logos (tech:fastapi-icon, tech:postgresql, tech:nats-icon, tech:redis, tech:neo4j, tech:milvus, tech:nuxt, tech:traefik-proxy, tech:docker, tech:opentelemetry-icon, tech:jupyter, tech:playwright, tech:etcd, tech:mongodb). For logo-less services use a meaningful bootstrap: glyph (bootstrap:shield-lock, shield-check, diagram-3, robot, clock-history, bar-chart-line, hdd-stack, graph-up-arrow, soundwave, cpu, file-earmark-text, search, eye). Icons ARE bundled into the webcomponent build (a likec4:icons step runs during codegen).
• Colour encodes tier, not just brand. The Swiss AI Hub palette: Application = aihub-red (the brand colour = "stuff we build"), Data = slate, LLM = secondary (blue), Eventing = amber, Identity/Edge = indigo, Observability = green, Utility = gray, External = muted. Implement tier colour as a kind default where a kind maps cleanly to one tier (e.g. datastore → slate, messagebroker → amber); for kinds that span tiers (container), set style { color <tier> } per element. icon (direct property) and color (in style) per-element DO override kind defaults reliably — unlike shape.
• Relationship kinds carry colour + line + arrowhead. Define semantic kinds in specification: relationship sync { color slate; line solid; head normal }, async { color amber; line dotted; head vee }, federate { color sky; line dashed; head diamond }, ingress { color indigo; line solid; head open }. Apply with a -[async]-> b. This makes flow type readable without reading labels.

No in-canvas legend in the webcomponent

The generated <likec4-view> webcomponent only honours view-id, browser, and dynamic-variant attributes — it does NOT expose a notation/legend toggle, and the popup viewer doesn't render one either. So the visual encoding has to be self-explanatory through consistent icons, tier colours, and shapes rather than a rendered key. (notation "..." labels on kinds remain useful as in-source documentation even though they aren't surfaced as a panel. A markdown legend on the page is possible but was tried and removed — keep the encoding intuitive instead.)

Honest self-criticism before declaring "done"

If you can see in a screenshot that labels are squashed, edges tangled, or boxes overlapping — fix it before reporting the view as ready. Don't ask reviewers "does this read well?" when the answer is visibly no.

Code-first when modelling connectivity

When inventorying container or component edges:

• READMEs and CLAUDE.md files lag the code. Verify against source.
• docker-compose depends_on shows boot order, not runtime integration.
• Environment variables (e.g. OPENAI_API_BASE_URL) hint at integrations but don't confirm what code actually calls — custom plugins can override them.
• For accurate edge inventories, read entry points, lifetime managers, adapter / client / publisher / subscriber files. Grep for network library imports (httpx, nats, pymongo, boto3, etc.).
• A pre-built connectivity research subagent template (connectivity-researcher) exists in monorepos that follow this pattern.

Common Mistakes & Debugging

When a model errors or an eval answer seems wrong, load references/troubleshooting.md which contains:

• Syntax errors — identifier format (dots forbidden in identifiers), unknown kinds, duplicate FQNs, malformed where predicates
• Model & Hierarchy — broken FQN references, parent-child relationship constraint, cross-file visibility
• View Predicates — * vs ** confusion, missing neighbor elements, WHERE case sensitivity
• Deployment — instanceOf FQN resolution, undefined deploymentNode kinds
• Dynamic Views — flattening parallel blocks, response arrow symmetry, exact variant sequence keyword
• Validation & Import — config not found, import path resolution, upstream error cascade
• Performance — spec in separate file, splitting large views
• 5-step debugging workflow — validation-first with --file, FQN integrity, predicate isolation, spec-first validation
• 7 Skill Best Practices — response discipline, relationship disambiguation, FQN usage, safe editing rules

Reference Index

Load a reference file when the task involves the corresponding topic. Claude reads SKILL.md first; these files are loaded on demand only when needed.