likec4 1.59.4 → 1.61.0

package/skills/likec4-dsl/references/style-tokens-colors.md

@@ -0,0 +1,150 @@
+# Style Tokens and Colors (LikeC4 DSL)
+
+## Canonical color tokens (semantic names)
+
+LikeC4 provides a curated set of semantic color tokens. **Prefer these named tokens over raw hex colors** for consistency and automatic light/dark theme adaptation.
+
+### Core semantic token palette
+
+| Token       | Usage                              | Light appearance | Dark appearance |
+| ----------- | ---------------------------------- | ---------------- | --------------- |
+| `primary`   | Primary brand color, main emphasis | #2F80ED (blue)   | lighter blue    |
+| `secondary` | Secondary accent, de-emphasis      | #7C3AED (purple) | lighter purple  |
+| `muted`     | Muted text, disabled states        | #9CA3AF (gray)   | lighter gray    |
+| `slate`     | Neutral backgrounds, borders       | #475569          | lighter slate   |
+| `blue`      | Technical/IT systems               | #3B82F6          | lighter blue    |
+| `indigo`    | Data/analytics systems             | #6366F1          | lighter indigo  |
+| `sky`       | Cloud, external services           | #0EA5E9          | lighter sky     |
+| `red`       | Alerts, critical systems           | #EF4444          | lighter red     |
+| `gray`      | Infrastructure, generic            | #6B7280          | lighter gray    |
+| `green`     | Success, operational systems       | #10B981          | lighter green   |
+| `amber`     | Warnings, async/queue patterns     | #F59E0B          | lighter amber   |
+
+## Correct usage: semantic tokens
+
+```likec4
+specification {
+  element service {
+    style { color primary }    // ✓ Correct: semantic token
+  }
+  element critical {
+    style { color red }        // ✓ Correct: semantic token
+  }
+  element queue {
+    style { color amber }      // ✓ Correct: semantic token
+  }
+}
+```
+
+## When hex colors are acceptable
+
+Hex colors can be used if you define a custom named color in the specification:
+
+```likec4
+specification {
+  color my-brand-blue #003366   // Define a custom named token
+  
+  element service {
+    style { color my-brand-blue } // Reference the custom token
+  }
+}
+```
+
+**Do not use raw hex colors directly in styles without first defining them as named tokens in the specification.**
+
+## What NOT to do
+
+```likec4
+style { color #FF5733 }      // ✗ Wrong: raw hex color
+style { color rgb(255,87,51) } // ✗ Wrong: rgb() notation
+style { color "primary" }    // ✗ Wrong: quoted string (remove quotes)
+```
+
+## Style tokens vs. theme colors
+
+- **Semantic tokens** (`primary`, `secondary`, `muted`, etc.) automatically adapt to light/dark mode.
+- **Custom named colors** defined in specification are explicit hex values; use them sparingly for brand colors.
+- **Raw hex** in a style property is not recommended — always register in specification first.
+
+## Icon packs
+
+Icons use the format `group:name` (e.g. `tech:react`, `aws:lambda`, `azure:app-service`). Five built-in groups are available:
+
+| Group       | Count | Examples                                       |
+| ----------- | ----- | ---------------------------------------------- |
+| `aws`       | ~307  | `aws:lambda`, `aws:s3`, `aws:dynamo-db`        |
+| `azure`     | ~614  | `azure:app-service`, `azure:cosmos-db`         |
+| `gcp`       | ~216  | `gcp:cloud-run`, `gcp:bigquery`                |
+| `tech`      | ~2000 | `tech:react`, `tech:postgresql`, `tech:docker` |
+| `bootstrap` | ~2051 | `bootstrap:gear`, `bootstrap:person`           |
+
+To get the full up-to-date list, run `likec4 list-icons` or `likec4 list-icons --group tech` (see `references/cli.md`)
+
+## Complete style example
+
+```likec4
+specification {
+  color brand-orange #FF8C42     // Custom brand color
+  
+  element actor {
+    style { 
+      shape person
+      color primary 
+      icon tech:user
+    }
+  }
+  
+  element service {
+    style {
+      shape component
+      color primary
+      icon tech:gear
+    }
+  }
+  
+  element critical-service {
+    style {
+      shape component
+      color red      // Critical system
+      icon tech:alert
+    }
+  }
+  
+  element queue {
+    style {
+      shape queue
+      color amber    // Async/queue pattern
+    }
+  }
+}
+
+model {
+  customer = actor {
+    style { color primary }
+  }
+  
+  api = service {
+    style { color primary }
+  }
+  
+  alert-responder = critical-service {
+    style { color red }
+  }
+  
+  job-queue = queue {
+    style { color amber }
+  }
+}
+```
+
+## Summary
+
+| Use case              | Correct                                                                              | Incorrect                   |
+| --------------------- | ------------------------------------------------------------------------------------ | --------------------------- |
+| Brand primary color   | `style { color primary }`                                                            | `style { color "#2F80ED" }` |
+| Critical system alert | `style { color red }`                                                                | `style { color "#FF0000" }` |
+| Async/queue pattern   | `style { color amber }`                                                              | `style { color "#FFC107" }` |
+| Custom brand color    | Define in spec + use token: `color my-brand #XXXXXX` then `style { color my-brand }` | Use raw hex in style        |
+| Theme-aware styling   | Use semantic tokens (`primary`, `secondary`, etc.)                                   | Use fixed hex values        |
+
+**Best practice:** Use semantic color tokens for all element and relationship coloring. Define custom named colors in specification only for brand compliance, never use raw hex in styles.

package/skills/likec4-dsl/references/troubleshooting.md

@@ -0,0 +1,101 @@
+# Common Mistakes & Debugging (LikeC4 DSL)
+
+Load this file when encountering validation errors, unexpected rendering, or when an eval answer is failing.
+
+## Syntax Errors
+
+| Error                                    | Cause                                     | Fix                                                                |
+| ---------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------ |
+| "Identifier PAYMENT.API not found"       | Dots in identifier name                   | Use `payment-api` not `payment.api`; dots are FQN separators only  |
+| "Unknown kind SERVICE"                   | Kind not in specification                 | Define `element service { ... }` in the specification block        |
+| "Duplicate FQN cloud.backend"            | Element ID repeated under the same parent | Rename one element; each sibling must have a unique identifier     |
+| "Expected property TYPE after include *" | Malformed filter predicate                | Use `include * where kind is component`, not `include * component` |
+| "Invalid relationship kind async-cache"  | Kind not found in specification           | Define `relationship async-cache { ... }` in specification first   |
+
+## Model & Hierarchy
+
+| Error                                            | Cause                                                              | Fix                                                                           |
+| ------------------------------------------------ | ------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
+| Element shows but relationships don't render     | Relationship references FQN incorrectly                            | Use exact FQN matching the model hierarchy                                    |
+| "Can't define relationship from parent to child" | Direct parent-child relationships are forbidden                    | Move the relationship outside the parent element or use implicit notation     |
+| Child element not visible from other files       | Referencing by short name instead of FQN                           | Import or use full FQN: `cloud.backend.api`                                   |
+| Extend block adds duplicate tags                 | Tags stack on merge                                                | Use consistent tag names; duplicates are not deduplicated automatically       |
+| Warning `Element 'api' not found` on `[[api]]`   | Markdown link target is not an absolute FQN of the current project | Use the full FQN: `[[cloud.backend.api]]`; imported elements cannot be linked |
+| Warning `Unknown link namespace 'deployment'`    | Only `view:` is a known prefix in `[[…]]`                          | Use `[[view:id]]` or an element FQN                                           |
+| `[[cloud.api]]` shows as raw text                | Plain `'…'` string, or inside inline/fenced code                   | Use a Markdown value `'''…'''`; move the link out of code                     |
+
+Labelled link breaks a Markdown table cell: a bare pipe splits GFM table cells, so inside tables write the separator as `\\|`, e.g. `[[cloud.api\\|API]]`.
+
+## View Predicates
+
+| Error                                       | Cause                              | Fix                                                                               |
+| ------------------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------- |
+| `include *` shows grandchildren             | Confusing `*` with `**`            | `*` = direct children only; use `**` for recursive descent                        |
+| Relationships disappear in scoped view      | Neighbors not explicitly included  | Add `include -> scope` or `include <-> scope` to pull in inbound/outbound sources |
+| "WHERE predicate not matching any elements" | Tag or kind name is case-sensitive | Use exact case: `#Critical` ≠ `#critical`                                         |
+| Element included but styled differently     | Global vs. local style conflict    | Local view styles override global; audit style rules order in the view block      |
+
+## Deployment
+
+| Error                                         | Cause                                           | Fix                                                                            |
+| --------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------ |
+| `instanceOf` doesn't resolve                  | Instance refers to wrong FQN                    | Use the exact logical model FQN, not the deployment node identifier            |
+| "Undefined DEPLOYMENT_KIND"                   | Kind referenced but not in specification        | Define `deploymentNode vm { ... }` in specification                            |
+| Deployment relationship inherits unexpectedly | Logical model edges are inherited automatically | Suppress inherited relationships explicitly in the deployment view if unwanted |
+
+## Dynamic Views
+
+| Error                                             | Cause                                                                         | Fix                                                                                                                                |
+| ------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `Nested parallel blocks are not allowed`          | Nested `parallel { parallel { ... } }` (or `par`)                             | Flatten: put all concurrent steps in a single `parallel { }` block. Other flow blocks (`opt`/`loop`/`try`/`alt`) may nest freely   |
+| `"loop" can not be used as an alternative branch` | Non-branch block (`loop`/`opt`/`parallel`/`try`) placed directly inside `alt` | `alt` accepts only `when`/`if`/`else` branches; nest the block inside a branch                                                     |
+| `"when" alternative branch must be inside "alt"`  | `when`/`if`/`else` used at top level or inside a non-`alt` block              | Wrap the branches in an `alt { ... }` block                                                                                        |
+| `catch`/`finally` rejected                        | `catch` without a preceding `try`, or `catch` after `finally`                 | Keep order `try` → `catch?` → `finally?`                                                                                           |
+| Response arrows (`<-`) show wrong direction       | Chained `<-` steps are not supported                                          | After `a -> b -> c`, write one `<-` step per hop: `b <- c`, then `a <- b`. `<-` cannot be chained (`a <- b <- c` is a parse error) |
+| `navigateTo` link doesn't work                    | Target view name does not exist                                               | Ensure the target view name exists in the same project; from a dynamic step it must be another `dynamic view`                      |
+| `variant sequence` is ignored                     | Wrong keyword or spelling                                                     | Use exact: `variant sequence` (not `type`, `mode`, or `sequence` alone)                                                            |
+
+## Validation & Import
+
+| Most Common                                         | Solution                                                                                                                                                                                                            |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `validate` reports config not found                 | Ensure `likec4.config.json` exists in the project root directory                                                                                                                                                    |
+| `Imported project not found`                        | `import` takes another project's `name` (from its `likec4.config`), not a file path: `import { x } from 'other-project'`. Files of the same project need no import; reference elements by full FQN                  |
+| Symbol from import invisible in model               | Symbol must be public (defined at top level); nested elements need FQN                                                                                                                                              |
+| Large error count in project but your file is clean | Use `likec4 validate --json --no-layout --file <edited-file> <project-dir>` and check `filteredErrors`/`filteredFiles`; text mode can also print diagnostics from other workspace files before the filtered summary |
+
+## Performance & Large Models
+
+| Symptom                        | Cause                                                      | Action                                                             |
+| ------------------------------ | ---------------------------------------------------------- | ------------------------------------------------------------------ |
+| Validation takes >30s          | Specification changes trigger full project re-parse        | Keep specification in a separate file; avoid editing it frequently |
+| Export generates a partial PNG | Layout engine timeout on complex view                      | Split large views with `navigateTo` or reduce the element count    |
+| IDE responsiveness slow        | Too many open files or large specification in working file | Split into `spec.c4` + `model.c4` + `views.c4`                     |
+
+## Debugging Workflow
+
+When encountering errors, follow these steps in order:
+
+1. **Run validation with `--file` and check `filteredErrors`:**
+   ```bash
+   likec4 validate --json --no-layout --file <your-file> <project-dir>
+   ```
+   If `filteredErrors` = 0 but `totalErrors` > 0, your file is clean; the error is in an upstream file.
+
+2. **Check FQN integrity:** Find the identifier from the error message and verify it matches the model hierarchy exactly.
+
+3. **Isolate predicate issues:** Copy the failing `include`/`exclude` rule into a new minimal test view to confirm predicate semantics in isolation.
+
+4. **Validate specification first:** Comment out `model`, `deployment`, and `views`; validate the `specification` block alone. If it passes, uncomment the next block and repeat.
+
+5. **Use `extend` strategically:** When enriching elements across files, use `extend FQN { }` rather than re-declaring — re-declarations cause duplicate FQN errors.
+
+## Skill Best Practices
+
+1. **Always start with project structure understanding.** Use the `understand-project-structure` skill before making changes to an unfamiliar project.
+2. **For relationship ambiguity, always include KIND + TITLE.** When source/target/kind match multiple relationships, include title in the matcher to avoid silently targeting the wrong one.
+3. **Response discipline on strict prompts.** Output one final answer first (no alternatives) when the prompt says "exact", "minimal", or "paste-ready".
+4. **Validate after each file edit.** Always run `likec4 validate --json --no-layout --file <edited-file> <project-dir>` after changes; use `--file` to focus on your changes only.
+5. **Cross-file references use FQN.** Never assume short names resolve across file boundaries; they don't.
+6. **Keep specification stable.** Changes invalidate the entire model parse; prefer a separate `spec.c4` file and minimize changes to it.
+7. **Test wildcard semantics locally.** When unsure whether `*` or `**` is correct, create a minimal test view to confirm behavior before committing.

package/skills/likec4-dsl/references/views.md

@@ -0,0 +1,329 @@
+# Views
+
+Three types of views are supported:
+
+1. Element views - projections of the model, based on predicates
+2. Dynamic views - step-by-step sequence of interactions between elements
+3. Deployment views - projections of the deployment model, based on predicates
+
+View IDENTIFIER must be unique within the project, available across all files. Duplicate identifiers will result in a validation error.
+There is special view - `index`, if not defined, it will be automatically created to include all top-level elements.
+
+Syntax:
+
+```likec4
+views {
+
+  LOCAL_STYLE_RULES     // optional style rules, applied to all views in this block
+
+  // element view
+  view IDENTIFIER {
+    TAGS                // optional tags, must come first if present, before any properties
+    PROPERTIES          // optional, but must come before any view rules
+    ELEMENT_VIEW_RULES    
+  }
+  // element view can also be scoped to a specific element, explained below
+  view IDENTIFIER of ELEMENT_ID {     
+    TAGS
+    PROPERTIES
+    ELEMENT_VIEW_RULES    
+  }
+  // dynamic views
+  dynamic view IDENTIFIER {
+    TAGS
+    PROPERTIES  
+    DYNAMIC_VIEW_RULES
+  }
+  // deployment views
+  deployment view IDENTIFIER {
+    TAGS
+    PROPERTIES
+    DEPLOYMENT_VIEW_RULES
+  }
+}
+```
+
+## Element View Rules
+
+Syntax:
+
+```likec4
+include PREDICATE, PREDICATE, ...
+exclude PREDICATE, PREDICATE, ...
+style ELEMENT_EXPRESSION, ... {
+  // Apply style properties to elements matching the expressions
+}
+global style STYLE_GROUP_IDENTIFIER
+autoLayout TopBottom|BottomTop|LeftRight|RightLeft [rankSep] [nodeSep] [spline|ortho]
+```
+
+See [Predicates](./predicates.md) for more information on predicates and expressions.
+
+**Important:**
+
+- Rules order matters, as every next rule applies on top of the previous, accumulating result.
+- `exclude` only removes elements that were included by previous rules.
+- `style` rules override previously applied styles.
+  - Style cascade (each override the previous): Spec defaults → element properties → local styles → view-level styles → customized predicates
+
+## Edge routing
+
+To draw relationships with right-angle bends, set `routing ortho` in a view:
+
+```likec4
+view {
+  routing ortho
+  include *
+}
+```
+
+Use `spline` for curved relationships or `ortho` for horizontal and vertical segments. The default is `spline`. Routing applies to element, dynamic, and deployment views. Sequence diagrams ignore this setting.
+
+LikeC4 uses the first value defined in this precedence order:
+
+1. The view's `routing` property.
+2. The last `autoLayout` rule's routing parameter.
+3. The project default, `styles.defaults.view.routing`.
+4. The built-in default, `spline`.
+
+If both the view property and `autoLayout` set routing, the property takes precedence and the language server reports a warning. Changing routing alone preserves saved node positions and control points without invalidating the layout.
+
+Graphviz can route relationships through unrelated group boxes or place parallel routes close together. To reduce crowding, show fewer relationships or edit individual connections. Increasing `autoLayout` spacing gives nodes more room, but doesn't guarantee separation between routes.
+
+Edited edges that share a straight segment move onto separate tracks where space at their endpoints permits. Unedited Graphviz routes keep their positions. Automatic label placement avoids nodes, other labels, and routes where space permits; dense views can still contain overlaps.
+
+## Dynamic View Rules
+
+Syntax:
+
+```text
+STEP ::=
+   SOURCE -> TARGET [LABEL]       // forward message
+   | SOURCE <- TARGET [LABEL]     // backward message
+   [{
+      RELATIONSHIP_PROPERTIES
+      RELATIONSHIP_STYLE_PROPERTIES
+   }]
+
+
+DYNAMIC_VIEW_STYLE_RULE ::=
+   style EXPRESSION, ... {
+      // Apply style properties to elements matching the expressions
+   }
+
+
+DYNAMIC_VIEW_RULES ::=
+   STEP
+   STEP
+   DYNAMIC_VIEW_STYLE_RULE
+   ...
+```
+
+## Local Style Rules
+
+Styles placed inside `views {}` but outside any `view {}` apply to all views in that block:
+
+```likec4
+views {
+  // This style applies to ALL views in this block
+  style * { color green }
+
+  view view1 {
+    include *                      // All elements are green
+  }
+  view index {
+    include *
+    style backend { color red }    // All elements are green, except backend which is red
+  }
+}
+```
+
+## Global Style Groups
+
+Reusable style groups defined in `global { ... }`:
+
+Syntax:
+
+```likec4
+global {
+  styleGroup GROUP_IDENTIFIER {
+    style EXPRESSION { ... }
+    style EXPRESSION { ... }
+  }
+}
+
+views {
+  view index {    
+    global style GROUP_IDENTIFIER
+  }
+}
+```
+
+```likec4
+global {
+  styleGroup brandColors {
+    style * { color primary }
+    style element.tag = #deprecated { color muted; opacity 30% }
+    style element.tag = #critical { color red; border dashed }
+  }
+}
+
+views {
+  view index {
+    include *
+    global style brandColors    // Apply the style group
+  }
+}
+```
+
+Style groups can contain multiple `style` rules. They are applied in the order defined within the group. When used in a view, global styles sit between local styles and view-level styles in the cascade.
+
+# Dynamic Views — Detailed Reference
+
+## Steps
+
+Each step represents an interaction between two elements:
+
+```likec4
+// Forward step
+customer -> frontend "opens app"
+
+// Backward step (response/return flow)
+frontend <- backend "returns data"
+
+// Step with full properties
+customer -> frontend "places order" {
+  title "Customer places an order"       // Override step label
+  description "Detailed description"
+  technology "HTTPS"
+  notes '''
+    Additional notes displayed in sidebar.
+    Supports **Markdown** formatting.
+  '''
+  color red
+  navigateTo order-detail                // Link to another dynamic view
+}
+```
+
+Step properties: `title`, `description`, `technology`, `notes`, `navigateTo`, all relationship properties.
+
+### Chained Steps
+
+Steps can be chained to reduce repetition:
+
+```likec4
+customer
+  -> frontend "opens"     // Read as "customer opens frontend"
+  -> backend "requests"   // Read as "frontend requests backend"
+  -> database "queries"   // Read as "backend queries database"
+backend <- database "responds"   // Read as "database responds to backend"
+```
+
+Each arrow in the chain creates a separate step. The target of the previous step becomes the source of the next. A chain can continue with `->` or a relationship-kind arrow such as `-[kind]->`. A chain cannot continue with `<-`, so write a response as its own step.
+
+## Parallel Steps
+
+Use `parallel` (or `par`) blocks for concurrent interactions:
+
+```likec4
+dynamic view flow {
+  frontend -> backend "requests data"
+
+  parallel {
+    backend -> cache "checks cache"
+    backend -> database "queries DB"
+    backend -> external-api "fetches enrichment"
+  }
+
+  backend -> frontend "returns aggregated data"
+}
+```
+
+Parallel blocks can be mixed with sequential steps, but cannot be nested inside another `parallel`/`par` block (`Nested parallel blocks are not allowed`).
+
+## Variants
+
+| Variant             | Rendering                     | Use case                           |
+| ------------------- | ----------------------------- | ---------------------------------- |
+| `diagram` (default) | Animated box-and-line diagram | General flow visualization         |
+| `sequence`          | UML sequence diagram          | API call sequences, protocol flows |
+
+### Using `variant sequence`
+
+The `variant sequence` keyword renders the dynamic view as a UML sequence diagram. This is especially useful for API call sequences and protocol flows.
+
+**Key syntax points:**
+
+- Use `variant sequence` at the start of the dynamic view block
+- Use `->` for forward/call direction
+- Use `<-` for backward/return direction (not `->` with different semantics)
+- Sequence diagrams work best with leaf elements (not containers)
+
+```likec4
+dynamic view api-sequence {
+  variant sequence
+
+  client -> gateway "POST /orders"
+  gateway -> auth "validate token"
+  auth <- gateway "200 OK"
+  gateway -> orders "create order"
+  orders -> db "INSERT"
+  orders <- db "order_id"
+  gateway <- orders "201 Created"
+  client <- gateway "201 Created"
+}
+```
+
+**Common mistake:** Using `->` for returns instead of `<-`. The arrow direction indicates message flow:
+
+- `a -> b` means "a sends to b" (request/call)
+- `a <- b` means "b sends to a" (response/return)
+
+```likec4
+// ❌ WRONG - using -> for returns
+dynamic view wrong {
+  variant sequence
+  client -> gateway "request"
+  gateway -> client "response"  // This renders incorrectly!
+}
+
+// ✅ CORRECT - using <- for returns
+dynamic view correct {
+  variant sequence
+  client -> gateway "request"
+  client <- gateway "response"  // Proper return flow
+}
+```
+
+## Include in Dynamic Views
+
+Dynamic views support element-view predicates for context elements that do not participate in steps. Predicates do not generate or filter the step sequence itself.
+
+```likec4
+dynamic view flow {
+  customer -> frontend "opens"
+  frontend -> backend "requests"
+
+  // Add parent containers as visual context
+  include cloud with {
+    color muted
+    opacity 10%
+  }
+  include amazon
+}
+```
+
+## Styling in Dynamic Views
+
+Same styling rules as element views:
+
+```likec4
+dynamic view flow {
+  customer -> frontend "opens"
+  frontend -> backend "requests"
+
+  style customer { color green }
+  style * { size sm }
+  style frontend { color muted }
+}
+```