likec4 1.59.3 → 1.60.0

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

@@ -0,0 +1,151 @@
+# Model (LikeC4 DSL)
+
+The `model` block defines the logical architecture: elements (systems, containers, components, actors) organized in a hierarchy, with relationships between them. Views project from this model.
+
+**Key rules:**
+
+- Elements MUST have a kind (from specification) and an identifier unique within their parent.
+- Relationships cannot exist directly between parent and child — move them outside the parent element.
+- `this` and `it` are aliases for the current element inside a nested relationship.
+- Cross-file references require the full FQN (e.g. `cloud.backend.api`); short names are file-scoped.
+- `extend FQN { }` adds tags, metadata, and links to an existing element without redefining it.
+
+## Syntax
+
+```likec4
+model {
+  // Elements — top-level elements are global, referenceable by ID anywhere in the project
+  IDENTIFIER = KIND                         // no title, no body (title defaults to identifier)
+  IDENTIFIER = KIND "title"                 // with title, without body
+  KIND IDENTIFIER "title"                   // alternative: kind before identifier
+
+  IDENTIFIER = KIND {
+    TAGS                                    // optional, must come first if present
+    PROPERTIES                              // optional, must come before nested elements/relationships
+
+    IDENTIFIER = KIND "Child Title" { ... } // nested element (unlimited depth)
+    KIND IDENTIFIER "Child Title"           // nested, kind-first syntax
+
+    // Relationships inside element body (current element is implicitly SOURCE)
+    SOURCE -> TARGET                        // explicit, both sides named
+    -> TARGET "title"                       // implicit source (current element)
+    -> TARGET "title" { TAGS; PROPERTIES }
+    <-> TARGET "title"                      // bidirectional relationship
+    -[REL_KIND]-> TARGET "title"            // typed directed relationship
+    -[REL_KIND]<-> TARGET "title"           // typed bidirectional relationship
+    .REL_KIND TARGET "title"                // alternative typed syntax
+    SOURCE -> it                            // TARGET = current element (alias)
+    this -> TARGET                          // SOURCE = current element (alias)
+  }
+
+  // Top-level relationships (outside element body): SOURCE is required
+  SOURCE -> TARGET "title"
+  SOURCE <-> TARGET "title"
+  SOURCE -> TARGET "title" { TAGS; PROPERTIES }
+  SOURCE -[REL_KIND]-> TARGET
+  SOURCE -[REL_KIND]<-> TARGET
+  SOURCE .REL_KIND TARGET
+
+  // Extend existing element (by FQN, from any file)
+  extend FQN {
+    TAGS                                    // additional tags to apply
+    PROPERTIES                              // only `metadata` and `link` are allowed
+    NESTED_ELEMENTS | RELATIONSHIPS         // additional children or edges
+  }
+
+  // Extend existing relationship — matcher contract:
+  // 1) SOURCE and TARGET always required.
+  // 2) Include KIND when extending a typed relationship.
+  // 3) Include TITLE when extending a titled relationship.
+  // Omitting KIND is WRONG (not merely ambiguous) when a typed relation exists.
+  // Omitting TITLE is WRONG when the matched relation is titled.
+  extend SOURCE -> TARGET { TAGS; PROPERTIES }                  // untitled directed relationship
+  extend SOURCE -> TARGET "title" { TAGS; PROPERTIES }          // titled directed relationship
+  extend SOURCE <-> TARGET { TAGS; PROPERTIES }                 // untitled bidirectional relationship
+  extend SOURCE <-> TARGET "title" { TAGS; PROPERTIES }         // titled bidirectional relationship
+  extend SOURCE -[REL_KIND]-> TARGET "title" { TAGS; PROPERTIES } // typed titled relationship
+  extend SOURCE -[REL_KIND]<-> TARGET "title" { TAGS; PROPERTIES } // typed titled bidirectional
+}
+```
+
+## Full Example
+
+```likec4
+model {
+  customer = actor {
+    title "Customer"
+    summary "Consumes Cloud Services"
+    description """
+      User with **active** subscription
+      ... detailed description
+    """
+  }
+
+  cloud = system "Cloud" {
+    ui = container "Frontend" {
+      technology "React"
+      style { shape browser }
+      metadata { version "1.0.0"; owners ["Name 1", "Name 2"] }
+      link https://github.com/likec4/likec4 "Repository"
+      link ../relative/adr1.md
+
+      dashboard = app "Dashboard" { icon tech:react }
+    }
+    backend = container "Backend" {
+      api = service "API" {
+        #critical
+        -[sql]-> db "reads/writes"
+      }
+      db = database "DB" {
+        style { icon tech:postgresql; shape storage }
+      }
+    }
+    ui.dashboard -> backend.api { title "calls"; technology "HTTPS" }
+  }
+
+  customer -> cloud.ui.dashboard "browses" {
+    metadata { protocol "HTTPS" }
+  }
+}
+```
+
+## Element Properties
+
+| Property        | Values                                                                                   |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| **title**       | String, single line                                                                      |
+| **description** | String, prefer Markdown. If > 150 chars, also add `summary`.                             |
+| **summary**     | String, max 150 characters                                                               |
+| **technology**  | String, no multi-line                                                                    |
+| **style**       | `style { ... }` — see `references/style-tokens-colors.md`                                |
+| **icon**        | Shortcut for `style { icon ... }`, takes precedence over the style block                 |
+| **metadata**    | `metadata { KEY VALUE }` — key is identifier format; value is string or array of strings |
+| **link**        | `link URL "Optional title"` — repeatable; URL can be relative to the document            |
+| **navigateTo**  | ID of a dynamic view to navigate to on click                                             |
+
+## Relationship Properties
+
+`title`, `description`, `technology`, `metadata`, `style`, `link`, `navigateTo`
+
+## Extend Patterns
+
+```likec4
+// Add metadata and a link to an existing element from another file:
+extend cloud.backend.api {
+  metadata { team "platform"; criticality "high" }
+  link ./adr-002.md "Scaling decision"
+}
+
+// Extend an untyped relationship:
+extend cloud.ui.dashboard -> cloud.backend.api {
+  metadata { sla "99.9%" }
+}
+
+// Extend a typed relationship — include KIND to avoid ambiguous match:
+extend cloud.ui.dashboard -[http]-> cloud.backend.api "calls" {
+  metadata { sla "99.9%" }
+}
+
+// Wrong: if a typed relationship exists, this silently targets the wrong relation
+// extend cloud.ui.dashboard -> cloud.backend.api "calls" { ... }
+```

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

@@ -0,0 +1,123 @@
+# Predicates
+
+Predicates are view rules that define what elements and relationships to include or exclude from a view. Predicate types:
+
+- Wildcard predicate - used to select all elements/relationships, based on view scope
+- Element predicates - used to select elements
+- Relationship predicates - used to select relationships
+- Filter predicates - used to apply filters to element and relationship predicates
+- Custom predicates - used to override properties of elements/relationships (can be used with `include` only)
+
+Syntax:
+
+```
+EXPRESSION ::= WILDCARD | ELEMENT_EXPRESSION | RELATIONSHIP_EXPRESSION
+FILTER_PREDICATE ::= EXPRESSION where FILTER_CONDITIONS
+CUSTOMIZE_PREDICATE ::= (EXPRESSION | FILTER_PREDICATE) with { ... }
+PREDICATE ::= EXPRESSION | FILTER_PREDICATE | CUSTOMIZE_PREDICATE
+```
+
+Example:
+
+```likec4
+include *                               // WILDCARD
+include some.element                    // ELEMENT_EXPRESSION
+include some.from -> some.to            // RELATIONSHIP_EXPRESSION
+include * where tag is #production      // FILTER_PREDICATE
+include some.element with { color red } // CUSTOMIZE_PREDICATE on ELEMENT_EXPRESSION
+include                                 // CUSTOMIZE_PREDICATE on FILTER_PREDICATE
+  some.*
+  where
+    tag is #production and kind is component
+  with {
+    color red
+  }
+```
+
+## Expressions
+
+Expressions inside `exclude` clause match against the accumulated result of previous predicates. Expressions inside `include` clause match against the accumulated result of previous predicates and the model. Element expressions select elements first, and then relationships connected to these elements. Relationship expressions select relationships first, and then elements that are connected by these relationships.
+
+### Element expression
+
+- `<element_ref>` - selects element by reference from the current file scope, or globally available if not found in the current file, together with all relationships between this element and accumulated result
+- `<element_ref>.<child>` - selects unique child within `<element_ref>` together with all relationships between this child and accumulated result
+- `<element_ref>.*` - selects **direct children only** of `<element_ref>`, together with all relationships between these children and accumulated result
+- `<element_ref>._` - selects direct children of `<element_ref>` that have relationships with accumulated result
+- `<element_ref>.**` - selects **all recursive descendants** of `<element_ref>` that have relationships with accumulated result
+
+For detailed wildcard edge cases (`*` vs `_` vs `**`), load `references/include-predicates-wildcards.md`.
+
+### Wildcard expression
+
+Wildcard expression is a special element expression.
+
+- If used inside a scoped view, it selects the scoped element, its direct children, and all relationships with them.
+- If used inside an unscoped view, it selects top-level elements and all relationships between them.
+
+### Relationship expression
+
+Relationship expression uses element expressions as source and target.
+If expression matches, predicate adds matched relationships together with matching source and target elements.
+
+- `<expr1> -> <expr2>` - relationships from elements selected by `expr1` to elements selected by `expr2`
+- `<expr1> -> <element_ref>.*` - relationships from elements selected by `expr1` to direct children of `element_ref`
+- `<expr1> <-> <expr2>` - any relationships between elements selected by `expr1` and `expr2` (both directions)
+- `-> <expr>` - any relationships, from accumulated result to the elements selected by `expr`
+- `<expr> ->` - any relationships, from the elements selected by `expr` to accumulated result
+- `-> <expr> ->` - any relationships, between the elements selected by `expr` and accumulated result
+- `* -> *` - all relationships
+
+## Filter Conditions
+
+After expression is evaluated and selected elements/relationships, filter conditions are applied to refine the selection.
+
+Core filters:
+
+- Tags: `* where tag is #primary` / `* where tag is not #primary`
+- Kind: `* where kind is component` / `* where kind is not component`
+- Metadata value: `* where metadata.region is "eu"`
+- Missing metadata key: `* where not metadata.owner`
+- Arrays: `metadata.regions is "eu"` matches if the array contains `"eu"`
+- Booleans: `metadata.critical is true`
+- Combine with `and`, `or`, and parentheses
+
+For relationship expressions:
+
+- `* -> * where tag is #http` - relationship tag
+- `* -> * where metadata.protocol is "grpc"` - relationship metadata
+- `* -> * where source.tag is #primary` - source element tag
+- `* -> * where target.kind is component` - target element kind
+- `* -> * where source.metadata.zone is "public"` - source element metadata
+- `* -> * where target.metadata.zone is "restricted"` - target element metadata
+
+The same filters work in `exclude`, for example:
+
+```likec4
+exclude * where not metadata.owner
+exclude * -> * where metadata.protocol is "http"
+exclude * -> * where target.metadata.zone is "restricted"
+```
+
+Use the same `where` forms with `include`.
+
+In deployment views, instance tags are cumulative; instance metadata replaces logical metadata as a whole when present, otherwise logical metadata is the fallback.
+
+## Customize Predicates
+
+Customize predicates allow you to override properties of selected elements/relationships per view (for example, in different diagrams).
+For example:
+
+```likec4
+include 
+  * -> some.component.*
+  where
+    tag is #primary
+  with {
+    color red
+  }
+```
+
+- Selects all relationships incoming to the children of `some.component.*`
+- Filters relationships by tag `#primary`
+- Overrides color of selected relationships to red

package/skills/likec4-dsl/references/relationships-bidirectional.md

@@ -0,0 +1,176 @@
+# Bidirectional vs. Unidirectional Relationships
+
+## Key distinction: model relationships vs. view predicates
+
+LikeC4 supports `<->` in two places with related but different meanings:
+
+- In `model { ... }`, `<->` declares one semantic bidirectional relationship.
+- In `deployment { ... }`, `<->` declares one semantic bidirectional deployment relationship.
+- In `views { ... }`, `A <-> B` is a binary predicate that includes relationships between two element sets in either direction.
+
+## Declaring relationships in the model
+
+The short snippets in this reference are fragments unless they include their own element declarations. Declare the
+referenced elements in your model before using them.
+
+Use `->` when one element initiates the relationship:
+
+```likec4
+model {
+  frontend -> api "REST call"
+}
+```
+
+Use `<->` when both elements actively communicate as one mutual interaction:
+
+```likec4
+model {
+  frontend <-> backend "synchronizes"
+}
+```
+
+Bidirectional model relationships render with arrows at both ends by default. Style can still override the rendered arrow tail, but the relationship remains semantically bidirectional for view predicates such as `include -> frontend`.
+
+## Kinded bidirectional relationships
+
+Use `-[kind]->` for a directed kinded relationship and `-[kind]<->` for a bidirectional kinded relationship:
+
+```likec4
+specification {
+  element component
+  relationship sync
+  relationship async
+}
+
+model {
+  component frontend
+  component backend
+
+  frontend -[async]-> backend "publishes events"
+  frontend -[sync]<-> backend "replicates state"
+}
+```
+
+The relationship kind participates in extension matching. When extending a kinded relationship, include the kind in `extend`; also include the title whenever the relationship is titled.
+
+## Bidirectional deployment relationships
+
+Deployment relationships use the same notation and semantics:
+
+```likec4
+specification {
+  element component
+  deploymentNode vm
+  relationship sync
+}
+
+model {
+  component database
+}
+
+deployment {
+  vm vm1 {
+    db = instanceOf database
+  }
+  vm vm2 {
+    db = instanceOf database
+  }
+
+  vm1.db <-> vm2.db "replicates"
+  vm1 -[sync]<-> vm2 "heartbeat"
+}
+```
+
+There is no `extend` for deployment relationships, so extension matching does not apply here.
+
+## Extending bidirectional relationships
+
+Bidirectional relationship extensions are matched by source, target, kind, title, and bidirectionality. Endpoint order is normalized for bidirectional relationships, so these match the same relationship:
+
+```likec4
+model {
+  frontend <-> backend "sync"
+
+  extend backend <-> frontend "sync" {
+    metadata {
+      protocol "websocket"
+    }
+  }
+}
+```
+
+Directed and bidirectional matchers are not interchangeable:
+
+```likec4
+model {
+  frontend -> backend "calls"
+  frontend <-> backend "sync"
+
+  // Matches only the directed relationship.
+  extend frontend -> backend "calls" { metadata { protocol "https" } }
+
+  // Matches only the bidirectional relationship.
+  extend frontend <-> backend "sync" { metadata { protocol "websocket" } }
+}
+```
+
+## When to use one bidirectional relation vs. two directed relations
+
+Use one `<->` relationship when the model has one mutual interaction:
+
+```likec4
+model {
+  primaryDb <-> replicaDb "replicates"
+}
+```
+
+Use two directed relationships when each direction has separate meaning, labels, technology, or lifecycle:
+
+```likec4
+model {
+  frontend -> backend "request"
+  backend -> frontend "callback"
+}
+```
+
+By default LikeC4 may merge opposite relationships into one bidirectional-looking edge. Set `multiple true` in the relationship kind or view style when each direction must render as a separate edge.
+
+## Relationship predicates in views
+
+Inside views, `<->` is the "any relationship between both sides" predicate. It is binary and matches relationships between the two sides in either direction:
+
+```likec4
+views {
+  view backend-detail of backend {
+    include *
+    include -> backend
+    include backend ->
+    include -> backend ->
+    include backend <-> frontend
+  }
+}
+```
+
+- `-> X` includes incoming relationships to `X`; semantic bidirectional relationships involving `X` are also included.
+- `X ->` includes outgoing relationships from `X`.
+- `-> X ->` includes both incoming and outgoing relationships of `X`.
+- `A <-> B` includes relationships between `A` and `B` in either direction.
+
+There is no prefix `<-> X` predicate. Use `-> X ->` when you need both incoming and outgoing relationships around one scope.
+
+## Summary
+
+| Syntax              | Where          | Meaning                                                     |
+| ------------------- | -------------- | ----------------------------------------------------------- |
+| `A -> B`            | model          | Directed relationship: A initiates/calls/sends to B         |
+| `A <-> B`           | model          | One bidirectional relationship between A and B              |
+| `A <-> B`           | deployment     | One bidirectional deployment relationship between A and B   |
+| `A -[kind]-> B`     | model          | Directed relationship with relationship kind                |
+| `A -[kind]<-> B`    | model          | Bidirectional relationship with relationship kind           |
+| `A -> B` + `B -> A` | model          | Two separate directed relationships                         |
+| `-> X`              | view predicate | Incoming relationships to X, plus bidirectional involving X |
+| `X ->`              | view predicate | Outgoing relationships from X                               |
+| `-> X ->`           | view predicate | Both incoming and outgoing relationships of X               |
+| `A <-> B`           | view predicate | Relationships between A and B in either direction           |
+
+When in doubt, use `->` for request-response patterns where one side initiates. Use `<->` for one mutual interaction, and use two `->` relationships when each direction should be modeled independently.

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

@@ -0,0 +1,75 @@
+# Specification (LikeC4 DSL)
+
+The `specification` block defines all named vocabularies for the project: element kinds, deployment node kinds, relationship kinds, tags, and custom color tokens. Every kind used in `model` or `deployment` blocks must be declared here first.
+
+**Key rules:**
+- Specification is global across all files in the project.
+- Duplicate identifiers (same kind, same tag, etc.) will cause a validation error.
+- Multiple `specification` blocks (in one file or across files) are allowed, but not recommended.
+- Keep specification in a dedicated file, e.g. `specification.c4` — changes to specification trigger a full project re-parse, so isolating it reduces edit latency on model/view files.
+
+## Syntax
+
+```likec4
+specification {
+  // Define a tag; outside specification it is referenced as #IDENTIFIER
+  tag IDENTIFIER
+
+  // Define element kind for use in model
+  element IDENTIFIER {
+    #tag-1 #tag-2          // tags applied to all elements of this kind
+    title "default title for this kind"
+    technology "default tech for this kind"
+    description "default description for this kind"
+    notation "legend title for this kind"
+    style { ... }          // see references/style-tokens-colors.md
+  }
+
+  // Define deployment node kind for use in deployment block
+  deploymentNode IDENTIFIER {
+    // same properties and styles as element kind
+  }
+
+  // Define relationship kind with default properties and styles
+  relationship IDENTIFIER {
+    technology "default tech for this relationship kind"
+    description "default description for this relationship kind"
+    style { ... }          // default style for this relationship kind
+  }
+
+  // Define a custom named color token
+  color IDENTIFIER #FFFFFF  // or rgba(255,255,255,1)
+}
+```
+
+## Example
+
+```likec4
+specification {
+  element actor    { notation "Person";    style { shape person } }
+  element service  { description "Same for all of the kind"; style { shape component } }
+  element webapp   { style { shape browser } }
+  element queue    { style { shape queue; color secondary } }
+  element database { style { shape storage } }
+  element system
+
+  relationship async { color amber; line dotted; head diamond; tail vee }
+  relationship sql   { technology "SQL"; line dashed }
+
+  tag deprecated
+  tag critical
+
+  deploymentNode environment { notation "Environment"; style { color gray } }
+  deploymentNode zone        { notation "Network Zone" }
+  deploymentNode vm
+}
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Using a kind not defined here | Define `element KIND { }` or `deploymentNode KIND { }` in specification first |
+| Duplicate tag or kind identifier | Each identifier must be unique within its type category |
+| `#tag` in specification argument | Tags are defined without `#`; they are used with `#` elsewhere: `tag critical` → `#critical` |
+| Raw hex color in style | Define a named color token first: `color my-blue #003366`, then use `color my-blue` in styles |

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.