Skip to content

.krs.style Syntax Reference

English (this file) · 日本語

Language version: .krs language v2.0. .krs and .krs.style share one language version, independent from every package’s npm version (ADR-2124). In v2.0 a rule that targets a tag or annotation outside the tool vocabulary matches nothing (below).

A style sheet reads each character outside strings and comments with the same classes as a .krs file (syntax.md § Lexical structure), so a node id, tag or facet id written in the model is the same word in a selector (#注文, [facets=個人情報]). Those two selectors name the service and the facet in this model:

facet 個人情報 {}
system Example {
service 注文 {
facets 個人情報
}
}

Two differences (#3140):

  • A word may also contain - (font-size, [team-1]), and a . followed by a word joins a dot-notation id (OrderDB.OrderTable).
  • A - starts a signed number before a digit (-20px) and an arrow in -> / -->. Any other - or --, like a non-ASCII character that starts no word, is a token no position accepts: in a value it is reported as style-token-type-mismatch and the declaration takes no effect (label-offset: - 20px is refused, not read as 20px).

Related TPLs: TPL-2707 (a character the lexer drops cannot be refused), TPL-2509 (every name position reads names with one lexical rule)

Selector Example Target
Kind service All nodes of the given kind
Multiple kinds service, domain All nodes of any listed kind
Tag [external] All nodes with the given tag
Annotation @deprecated All nodes with the given annotation
Compound (kind + tag) service[external] Matches both kind and tag
Compound (tag + annotation) [external]@deprecated Matches both tag and annotation
Compound (kind + tag + annotation) service[external]@deprecated Matches all three
Facet [facets=pii] All elements belonging to the given facet
Compound (kind + facet) service[facets=pii] Matches both kind and facet membership
ID #ECommerce A specific node only
Compound (kind + ID) team#Platform One team only (its card and its frame)
Edge edge All edges
Edge + tag edge[async] Edges with the given tag
Edge source edge[from=ApiGateway] All edges originating at the node
Edge target edge[to=ApiGateway] All edges terminating at the node
Edge + facet edge[facets=pii] Edges belonging to the given facet
Edge ID edge#criticalWrite, edge#A->B, edge#A-->B A specific edge only
Boundary boundary All boundary frames (Group by: boundary)
Boundary ID boundary#pci One boundary’s frame only

Selector Example Score
Kind service 1
Tag [external] 10
Annotation @deprecated 10
Kind + tag service[external] 11
Tag + annotation [external]@deprecated 20
Kind + tag + annotation service[external]@deprecated 21
Facet [facets=pii] 10
Kind + facet service[facets=pii] 11
ID #ECommerce 100
Kind + ID team#Platform 101
Edge edge 1
Edge + tag edge[async] 11
Edge source/target edge[from=ApiGateway] 11
Edge + facet edge[facets=pii] 11
Edge ID edge#criticalWrite 101
Boundary boundary 1
Boundary ID boundary#pci 101

edge#criticalWrite scores 101 = 100 for the id + 1 for the edge kind. When scores are equal, the later declaration wins (same as CSS).


Core notation from .krs language v2.0, like facet itself. It is the styling hook that arbitrary-name tag and annotation selectors used to provide.

Style the elements belonging to a declared facet (see syntax.md § Cross-cutting membership).

[facets=pii] {
border-color: #14B8A6;
border-width: 2px;
}
/* Compound with a kind — only the databases in PCI scope. */
database[facets=pci_scope] {
background-color: #FEF3C7;
}
/* Repeat to require several memberships at once (AND, like tags). */
[facets=pii][facets=gdpr] {
border-style: dashed;
}
  • Nodes and edges — but reaching an edge takes the edge type. facets is written on both. The kind-less [facets=pii] above stays node-scoped, like every other type-less selector: a selector with no edge type never matches an edge. Write edge[facets=pii] to style the edges that declare the membership, repeating the predicate to AND it as on a node. What it never does is widen: an edge[facets=...] that no edge is a member of matches nothing rather than every edge. Membership is the only test — whether the facet also has a top-level facet block is a separate question, answered by the next bullet.
  • Membership is read from the element, which is where facets <id> is written. Nothing about the selector reaches back into the facet declaration; the declaration carries the concern’s metadata, not its members.
  • Undeclared facet ids are not a style-side error. A facets pcl typo is reported once, where it is written, by facet-not-declared, and the selector says nothing about it — [facets=pcl] matches whatever wrote facets pcl, exactly as it would a declared id, because membership is the only test. Reporting it twice would ask the author to fix one mistake in two places. The rule the typo does break is the intended one: [facets=pci] no longer reaches the element, which is the symptom that sends the author to the warning.
  • Fact and style stay split. Membership is a fact and lives in .krs; what a facet looks like is a choice and lives here. The overlay in the preview is a third, separate thing: a reader’s temporary selection, written nowhere.

Migrating an arbitrary-name tag or annotation selector

Section titled “Migrating an arbitrary-name tag or annotation selector”

Through language v1.x .krs.style matched arbitrary tag and annotation names, and that was the only way to style a cross-cutting concern. Facet selectors are the replacement. In .krs language v2.0 a rule whose selector names a tag or annotation outside the tool vocabulary matches nothing, as a whole: service[pci] does not fall back to painting every service. Each such rule is warned as style-tag-selector-not-builtin / style-annotation-selector-not-builtin, which is the only sign the rule went dead, so a model that relied on it looks different until the rule is rewritten.

Before — the name carries the concern, and nothing declares what it means:

system Shop {
database CardVault [pci] {}
service Payments [pci] {}
}
[pci] {
border-color: #F59E0B;
}

After — the concern is declared once, membership moves to facets, and the selector targets it:

facet pci {
label "PCI scope"
description "In scope for the annual PCI DSS assessment"
link "https://example.com/policies/pci" "PCI policy"
}
system Shop {
database CardVault { facets pci }
service Payments { facets pci }
}
[facets=pci] {
border-color: #F59E0B;
}

Specificity is unchanged — [facets=pci] scores 10, exactly as [pci] did. That is deliberate: a sheet part-way through the migration must not change which rule wins, or the rewrite would have to be done in one commit.

Three things the model gains that the tag never had: a place for the concern’s own metadata (description, link), typo detection against the declared set (facets pcl is reported; [pcl] was silently a different tag), and the overlay — a reader can highlight the facet without editing anything.

Related TPLs: TPL-1503 — the selector is the effect that keeps facet from being inert in the styling dimension. TPL-2175 — a deprecation is announced in the release that ships its migration target, never before. TPL-1101 — the new selector form round-trips through karasu fmt / the sheet tidier.


Source/target edge selectors (edge[from=<id>] / edge[to=<id>])

Section titled “Source/target edge selectors (edge[from=<id>] / edge[to=<id>])”

Style all edges from (or to) a given node in one rule — the most useful “color-by-source” aid for dense diagrams, where a hub’s fan-out would otherwise need one edge#Hub->Target rule per target.

  • edge[from=<id>] — every edge whose source is the node <id>
  • edge[to=<id>] — every edge whose target is the node <id>
edge[from=ApiGateway] { color: #3B82F6; } /* whole ApiGateway fan-out in one color */
edge[from=Scheduler] { color: #10B981; }
edge[to=AuthService] { color: #F59E0B; } /* everything calling AuthService */

<id> is a node id. It may be a dot-notation endpoint (e.g. edge[to=OrderDB.OrderTable]) for synthesized usecase→resource edges, consistent with the base form edge#PlaceOrder->OrderDB.OrderTable. The id is compared against the edge’s from / to endpoint in the active view.

Both selectors score 11 (edge kind 1 + endpoint predicate 10) — the same tier as edge[<tag>]. They combine with tags and a single edge can match both a from= and a to= rule:

edge[from=ApiGateway][async] { stroke-style: dashed; } /* async edges out of ApiGateway */

An endpoint that is not one identifier is written as a string literal, as in edge#<id> (Endpoints that are not one identifier), and is compared without its quotes:

edge[from="Card Vault"] { color: #EF4444; }

Any attribute other than from / to (e.g. edge[source=X]) raises an unknown-edge-selector-attribute error.

Related TPLs: TPL-1761 (endpoint selectors must compare against the same id form the view stores).

Targets a single edge for surgical overrides. The <id> is the edge’s canonical id, derived after parsing:

  1. If the author wrote #<id> on the edge in .krs (or on the usecase resource row), that author id is the canonical id.
  2. Otherwise the canonical id is the base form <from><arrow><to>, where the arrow is -> for sync edges and --> for async edges.
/* Author-supplied id from `.krs`: A -> B "primary" #criticalWrite */
edge#criticalWrite { color: #EF4444; }
/* Base form for an unauthored edge */
edge#A->B { color: #00FF00; }
/* Async base form */
edge#A-->B { stroke-width: 2px; }
/* Dot-notation node refs in the base id (e.g. usecase→resource synthesized edges) */
edge#PlaceOrder->OrderDB.OrderTable { direction: down; }

When two edges share the same computed base id and neither has an author id, the parser raises an ambiguous-edge-base warning and the edge#<base> selector matches none of them. To disambiguate, give one of the edges an #<id> in .krs. See docs/spec/syntax.md and docs/adr/1096-edge-id-selector.md.

A quoted node id may hold any string, but an endpoint after edge# must read back as itself in .krs.style. The base form therefore writes an endpoint bare only when the style lexer reads it as one identifier, it does not end with - (an arrow after it would take the -), and it does not start with #. Any other endpoint is written as the .krs string literal, with \ and " escaped. Ids that are identifiers keep the plain join, so existing rules are unchanged.

system S {
service "a b" {}
service "b->c" {}
service "a->b" {}
service "a-" {}
service a {}
service c {}
"a b" -> c "reads"
a -> "b->c" "writes"
"a-" -> c "calls"
a --> c "notifies"
}
edge#"a b"->c { color: #00FF00; } /* endpoint with a space */
edge#a->"b->c" { color: #F59E0B; } /* -> inside an endpoint */
edge#"a-"->c { stroke-style: dashed; } /* sync, apart from the async a-->c */

"a->b" -> c and a -> "b->c" get different bases ("a->b"->c and a->"b->c"), so the warning no longer fires for that pair. Until #3481 is fixed, the two still share one resolved style when they are in the same view, so a rule for one of them is drawn on both.

The parser normalizes the base the same way, so a needless literal (edge#"a"->c) is the same selector as edge#a->c, and a spaced edge#a- -> c is edge#"a-"->c. An endpoint that starts with # may be written bare (edge#a->#db) and means "#db". A string literal without an arrow is not an author id (author ids are identifiers), so edge#"a b" is a parse error.

The app’s right-click edge-direction menu writes edge#<canonical id>, so it writes these quoted forms too. The ambiguous-edge-base warning and the facet overview show the base in the same form.

Related TPLs: TPL-3480 — the base form is written into .krs.style, so it must re-lex there as the same value. TPL-1352 — two edges with different endpoints never share a base.

For classification overrides like read vs. write, use the tag form (edge[write], edge[read]) rather than edge#<id>. Tag selectors follow the logical classification — when a usecase’s operations change, the matching edges follow automatically. Per-edge edge#<id> overrides are best reserved for genuinely one-off styling decisions where the identity of that specific edge is what matters.


Properties are separated by ;. A , between two declarations is a parse error (expected-semicolon-between-properties); the parser recovers by treating the comma as a semicolon and continues with the next property. Commas inside a single value (e.g. font-family: "X", sans-serif) remain valid.

/* Node properties */
background-color: #1D4ED8;
color: #DBEAFE; /* text color */
border-color: #1E40AF;
border-width: 2px;
border-style: solid; /* solid | dashed | dotted */
border-radius: 8px;
font-size: 13px;
font-weight: bold; /* normal | bold */
font-family: "Noto Sans JP", sans-serif;
opacity: 0.6;
/* Edge properties */
color: #94A3B8;
stroke-width: 1.5px;
font-size: 11px;
stroke-style: solid; /* solid | dashed | dotted (canonical, see below) */
border-style: solid; /* solid | dashed | dotted (edge alias of stroke-style) */
direction: auto; /* up | down | left | right | auto (hint, see below) */
label-position: middle; /* start | middle | end | <0.0..1.0> */
label-offset: 0 0; /* <dy>px or <dx>px <dy>px (screen-axis) */
label-max-chars: 48; /* <n> | none (characters of the label drawn on the canvas) */
label-display: auto; /* auto | always | hover */
/* karasu-specific properties (not standard CSS) */
shape: box; /* box | user | cylinder | queue | hexagon | cloud | url("...") */
/* Annotation properties (badge display) */
badge-color: #EF4444;
badge-icon: "⚠";
badge-label: "Deprecated";

A declaration whose value does not fit its property is treated as if it were not written. The value is reported once, where it was written, and the cascade goes on without it: a weaker rule’s value for the same property applies, or the default when no rule sets one (CSS does the same). This holds for every property and every reason a value is rejected: out of range, an unknown keyword, a missing or wrong unit, a malformed color. The sheets karasu ships are not checked (#3141).

A number or a length may carry a sign: label-offset: -8px moves the label up. border-width, border-radius, font-size and stroke-width cannot be negative, and opacity lies in [0, 1] (style-out-of-range otherwise). A length needs its px, except 0, which is the same in every unit (border-width: 0). A whole value that holds more than one part without a comma (opacity: 0.5 0.2) is rejected, except where a property takes two parts (label-offset) or a font name of several words (font-family: Noto Sans, sans-serif).

Related TPLs: TPL-3141 — a value’s bounds live in the schema only and an invalid declaration is dropped once, in the cascade, so the diagnostic describes what is drawn.


stroke-style is the canonical name for an edge’s line style (solid | dashed | dotted), matching the SVG-flavored stroke-* vocabulary edges already use (stroke-width). border-style remains supported on edges as an alias for backward compatibility — existing stylesheets keep working unchanged.

edge[async] { stroke-style: dashed; } /* preferred */
edge[legacy] { border-style: dashed; } /* alias, same effect */

When both are declared for the same edge after the cascade, stroke-style wins regardless of declaration order:

edge { border-style: dotted; stroke-style: dashed; } /* → dashed */

On nodes, border-style is the only line-style property — stroke-style has no effect on node shapes.

Related TPLs: TPL-1296 — every property declared in this document’s css fences must exist in the in-app reference data, and every PROPERTY_SCHEMAS entry must be documented here (stroke-style was a schema-only ghost before being formalized — see ADR-1492 / #1492).


Keyword Shape Typical use
box Rounded rectangle service, domain (default)
user Person icon (head + body) user
cylinder Cylinder databases
queue Horizontal cylinder queues
hexagon Hexagon microservices
cloud Cloud external cloud services

Custom shapes — an SVG icon, named by url(...):

service[external] {
shape: url("cloud-node");
}

The argument is the name of a registered icon, not a path to a file. The built-in set — the manifest at packages/core/icons/icons.json (service, database, cloud-node, client-web, table, oci, … — the same icons icon mode draws) — is registered by core itself, so it resolves the same on every surface: the browser app, karasu render, the VS Code preview, the LSP. A host may add its own icons on top (resolveIconManifest / loadAndRegisterIcon). A url() that names no registered icon is reported as a style-unknown-icon warning at the declaration and the node falls back to box.

That warning is decided against the registry of the process that reads the sheet, so it answers for the built-in set everywhere. A host’s own icons live in that host’s process only: the language server and karasu lint-style run elsewhere and report a name they registered as unknown, while the host draws it correctly. An embedder that adds icons registers them before it compiles or validates.

An icon body is a drawing, not a card: it has nowhere to spend the node’s background-color / border-color / border-width / border-radius. Those are painted behind it as the node’s card instead, in both display modes. For an icon that should stand on the canvas alone, declare the card away:

service[external] {
shape: url("cloud-node");
background-color: transparent;
border-width: 0;
}

What is drawn on that card depends on what the icon declares.

An icon carrying text slots (krs-label / krs-description) is a card design: its body is a card of its own, with its own place for a label and a description. In icon mode the node is drawn on exactly that card, so the body is used whole and its slots carry the node’s text. In shape mode the card is measured from the node’s own text instead, so only the icon’s pictogram (<g class="krs-pictogram">) is taken: it is drawn at its native size in the card’s top-left padding corner, and the text is the same stack every other shape gets — label, description, role, the client resource and capability chips, and the link / team meta row.

An icon with no text slots is a standalone drawing, and the node’s text is drawn over it in the usual stack in either mode. Where the drawing sits differs: in shape mode it is fitted inside the card, keeps its viewBox ratio (never stretched to a card measured from the text) and is centred in the leftover space; in icon mode it fills the fixed card it is drawn on, which is the card the mode sizes every node to.

Related TPLs: TPL-2385 — the card frame stays on the node’s box, so edges and chrome attach to what is drawn while the body is fitted inside it. TPL-1001 — both display modes are checked on every drawing surface; the frame is painted in both, and the modes differ in the card’s size and in whether the icon’s slots are read. TPL-2802 — the registry url() reads is filled by core itself, so neither the drawing nor the style-unknown-icon verdict depends on what a host registered. TPL-2803 — the card’s text is drawn by the layout its size was measured for, so a shape-mode card keeps every line measurement reserved for it.


This section describes how the builtin sheet assigns colors to kinds. It is not a constraint on your own stylesheets — a user rule overrides any of it. It is written down so the defaults stay readable as a system, and so a kind added later inherits a rule instead of a fresh guess.

Two rules, plus a hue table.

Rule 1 — the logical layer separates by fill, not by hue

Section titled “Rule 1 — the logical layer separates by fill, not by hue”

domain, usecase, resource and member all describe one system from one point of view, so they share a blue family rather than competing for attention with four unrelated hues. What separates them is how the card is filled:

Kind Treatment Reading
domain Navy fill Structure this layer owns
usecase Fill-less — canvas shows through, border only Behaviour, lighter than the structure holding it
resource Neutral slate fill A reference to something the physical layer owns
member Navy fill, shape: user Already separated by shape

A fill-less kind has two consequences worth knowing about:

  • Its border is its outline. With no fill, the border is the only thing drawing the card, so it carries the WCAG non-text bar of 3:1. That bar is measured over three things at once: the bare canvas, the canvas under stacked boundary-frame tints (membership is 1:N, so frames overlap — up to three deep is checked), and the card at the opacity @deprecated fades it to, where a filled card would still have a body but a fill-less one has only the outline. Clearing all three is why the two themes’ usecase borders sit near opposite ends of the blue ramp, and why both are further from the canvas than a purely visual choice would put them.

    Opacity states lighter than that fade — the facet-overlay dim and the diff ghost — are exempt, and not by preference: at those alphas no color reaches 3:1 at all. White is the best a border can do, and over the dark canvas it reaches 2.50:1 at the dim’s alpha and 2.70:1 at the ghost’s. This is the carve-out WCAG 1.4.11 makes for inactive components.

  • Boundary membership becomes visible through it. Under Group by: boundary, the frame’s tint reaches the card interior instead of being hidden behind an opaque fill, so a fill-less card reads as part of its boundary in color, not only in position.

Use transparent — not none — to make a card fill-less. transparent still paints, so the card keeps its hit area for clicks and hovers.

Rule 2 — a deploy kind is one hue taken three ways

Section titled “Rule 2 — a deploy kind is one hue taken three ways”

Each deploy kind owns a hue. The three colors of its card are that same hue at three lightnesses, so the accent belongs to the card instead of floating on it:

  • border-color / badge-color — the accent, full chroma
  • background-color — the fill, at the lightness end nearest the canvas, so the card sits on the canvas rather than punching a hole in it
  • color — the label, at the opposite end, as far from the fill as the hue goes

The two lightness ends swap with the theme, which is why the same rule produces a near-black oci fill on the dark canvas and a pale one on the light canvas. Anchoring the rule to the canvas rather than to an absolute lightness is what lets one sentence describe both themes.

Kind Hue
oci blue
lambda purple
jar green
war orange
function yellow
assets cyan
job red
artifact gray
store teal

The table fixes the hue and the rule, not the hex values. Concrete hexes are whatever satisfies both rules and the contrast guard in both themes: every kind that sets background-color also sets a paired color, and that pair clears 4.5:1. Adding a kind therefore means adding a row here and deriving its three colors from that row — the guard verifies the result (packages/core/src/builtins/default-style-contrast.test.ts).

Note that job shares red with edge[cyclic]. That collision predates this section and is kept rather than reshuffling established kind colors; new kinds should not add another one.

An infra leaf (table, queue-item, bucket) has no colors of its own: in each theme the builtin sheet gives it the colors of its store (database, queue, storage), and only the colors, so the leaf keeps its own shape. A user rule on the store does not reach the leaf; name both kinds to recolor them together (database, table { background-color: …; }).

Related TPLs: TPL-2421 — adding a kind means adding a hue-table row and deriving fill / text from it, with the contrast guard verifying the hex; TPL-1697 — a kind that sets background-color sets the paired text color, per theme; TPL-2366 — colors drawn as text directly on the canvas are contrast-checked per theme.


Use as a last resort. karasu’s auto-layout (rows by kind + reachability, orthogonal edge routing, port distribution) handles most diagrams without input. A layout hint is appropriate only when the auto-layout cannot express the author’s intent — e.g. an admin actor that must read on the right, or external services grouped to one side. Reach for the heuristics first; reach for hints last.

Buckets a node into one of three columns within its layer. The middle bucket merges center and unspecified nodes, so authors can pin only the extremes:

service[external] { column: right; }
queue, database, storage { column: center; }
/* internal services left unspecified — they fall into the middle bucket */

Within each bucket, the existing within-layer order is preserved (declaration order in system view; barycenter elsewhere). The hint does not move a node to a different layer (row); for that, file an auto-layout heuristic issue rather than reaching for a new hint.

External services (system view): column picks the side

Section titled “External services (system view): column picks the side”

In the system view, [external] services are placed in left/right side columns by default (not a bottom row), so service → external edges run horizontally and don’t weave through the downward infra fan-out. The side is chosen automatically from the consuming service’s position (each external is grouped to the side of the service that calls it). column: left / column: right on an external service overrides that auto-assignment and pins it to the named side:

#LegacyBilling { column: left; } /* pin this external SaaS to the left side */

column: center / unspecified on an external service leaves the side to the auto-assignment. (infra kinds — database / queue / storage — stay in the bottom row regardless of any [external] tag; see Tags.)

Related TPLs: TPL-1761

View Behavior
system Honored as described above.
deploy Ignored. A style-column-ignored-non-system-view warning is emitted on resolution.
org Ignored. Same warning.

Any other value is reported as style-invalid-enum-value and dropped, as every invalid value is (see Property list).

Sets how many columns a container’s direct children wrap into. By default the layout already wraps many siblings into a balanced grid so a wide sibling set does not sprawl into one row that forces a zoom-out — keeping a view graspable at a glance (see Concepts, scoped glance / resolution axis). The default column count auto-balances toward a square: a small set (up to five) stays on one row, and a larger set uses ceil(sqrt(n)) columns, capped at five, so it grows downward rather than sideways.

grid-columns overrides that default for a specific container — set it on the node whose children you want to re-flow (the system for its services, a service for its domains, a domain for its usecases, a team for its member grid):

#PlatformSystem { grid-columns: 3; } /* its services wrap into 3 columns */
#BillingDomain { grid-columns: 2; } /* its usecases wrap into 2 columns */

A row still wraps early if it would exceed the row-width budget, so an oversized grid-columns cannot overflow the frame. On the system, drill-down and deploy views that budget is not a fixed constant: the layout tries a fixed list of candidate widths and keeps the one whose canvas holds the least empty space while staying inside a screen-shaped aspect band, so a view that would otherwise grow into a tall ribbon spreads sideways instead. The choice depends only on the model and on layout constants — never on the viewport — so the same input always renders the same SVG, and a view that already fits keeps the exact layout it had. The org member grid is not part of that: it wraps at a fixed number of cards per row, which grid-columns overrides. Unlike column (system view only), this hint is honored on the system and drill-down views and the org member grid. The deploy view auto-balances its container grid as well, and a container holding more than three units wraps them into a grid too rather than stacking them in one column. It groups containers by realizes target rather than by a container node, so it has no per-container grid-columns override in v1.

A value that is not a positive integer (e.g. 0 or 2.5) is reported once (style-out-of-range / style-invalid-enum-value) and dropped, as every invalid value is; without another rule’s value, the layout auto-balances.

Related TPLs: TPL-1223 — limit how much is shown at once; a single view keeps a graspable resolution (the balanced grid keeps visual density bounded). TPL-2593 — the per-view row-width budget is chosen by a search, which has to stay deterministic, floor-first and monotone or this section’s “same input, same SVG” promise breaks.

direction — auto | up | down | left | right

Section titled “direction — auto | up | down | left | right”

A layout hint on edges. Suggests the visual direction in which the edge should flow; default auto lets the layout engine decide.

edge[write] { direction: down; }
edge[read] { direction: right; }
edge#criticalWrite { direction: down; }

The hint travels through the resolver into ResolvedEdgeStyle.direction and is consumed by both the GUI editing flow (#1076 / #1098) and the karasu layered layout.

  • auto (default): no bias; the engine is free to choose.
  • up: place the source below the target so the visual arrow flows upward. Implemented by reversing the edge in the topological layer assignment, or — under the forced kind-based system view — by pushing the source one layer below the target. The visual from -> to orientation of the arrow itself is unchanged.
  • down: place the source above the target so the visual arrow flows downward, even when other constraints (e.g. a back-edge in the forced kind-based layout) would otherwise route it the other way. Mirrors up: under the forced kind-based layout the source is pushed one layer above the target, leaving the target and other same-kind nodes in place. No-op when the target is already at layer 0 (no room to push the source above the topmost row) — falls back to the natural orientation. In drill-down views without forced layers the natural topological order already satisfies down, so it is observationally identical to auto there.
  • left / right: orient the visual arrow leftward / rightward, mirroring the way up / down name the arrow flow. The source endpoint lands on the opposite side of the target from the arrowhead — direction: right puts the source on the left of the target so the arrow ends up flowing rightward; direction: left mirrors. When the natural layered layout puts source and target in different rows (the common case for service-to-service edges), the engine pulls the source into the target’s layer first, then runs the within-layer reorder. The reorder pass runs after bucketByColumn so it overrides node column placement for the source endpoint; the target’s column stays in effect. Conflicts on the same source resolve last-wins, matching the cascade convention. See docs/adr/1135-edge-direction-horizontal.md.

up is a hint, not a constraint. The engine drops the reversal in two cases:

  • Cycle guard. If applying up would close a cycle in the layer DAG, the engine ignores the reversals for the affected edges and renders with the natural orientation.
  • Forced kind-based layouts. The top-level system view stratifies nodes by kind (user → client → service → ...). direction: up is honored by moving the source one layer below the target; the target itself stays in its kind row, and other nodes of the same kind are unaffected. The kind stratification is therefore only perturbed for the explicitly-flagged edge.

See docs/adr/9019-edge-direction-style.md for the rationale.

An invalid value is reported and dropped, as every invalid value is (see Property list): a weaker rule’s direction applies, or auto when no rule sets one.

label-position — start | middle | end | <0.0..1.0>

Section titled “label-position — start | middle | end | <0.0..1.0>”

Where along the edge the label anchor sits. Default middle (= 0.5).

edge[delivers] { label-position: start; } /* near the source end */
edge[implicit] { label-position: end; } /* near the target end */
edge#criticalWrite { label-position: 0.25; }

The renderer keeps the historical “longest-segment midpoint” heuristic when the value is the default (0.5) and label-offset is 0, so existing diagrams stay byte-stable. As soon as the author sets either property, the anchor is computed by walking the edge polyline and landing at position × totalLength.

An invalid value (an unknown keyword, a number outside [0, 1]) is reported and dropped, as every invalid value is: the label is drawn where it would be without the declaration, at middle unless a weaker rule says otherwise. A number outside the range is not clamped to the nearer end.

Auto placement vs. author intent. When the author leaves both label-position and label-offset at their defaults, the renderer may automatically nudge a label off a collision with a node card, another label, another edge’s line or a frame border (edge-label collision-avoidance, ADR-2048, ADR-2360). This auto pass fires only on default-positioned labels; setting either property opts the label out of auto placement, so an explicit label-position / label-offset always wins.

Related TPLs: TPL-2048 — label placement is measured numerically (label↔label / label↔node overlap), non-colliding diagrams stay byte-stable, and author-set positions are never auto-moved.

Screen-axis nudge of the label relative to its computed anchor, in pixels. CSS-shorthand parsing:

  • One value (label-offset: 8px) → dx = 0, dy = 8. The most common “shift labels downward” case
  • Two values (label-offset: 4px 8px) → dx = 4, dy = 8

The values are separated by a space. A third value, or a comma (4px, 8px), makes the declaration invalid; it is not read as its first two values.

edge { label-offset: 0 8px; } /* every label drops 8px below its anchor */
edge#wide { label-offset: 4px 8px; }

Screen axis (not edge-perpendicular) so a global rule applies a uniform visual shift regardless of each edge’s slope. Positive values shift right (x) and down (y); negative values shift left and up.

The offset is independent of the existing -6px typographic lift the renderer applies above the anchor — the lift stays in place to keep labels off the line, and the offset adds on top.

Earlier draft (rejected): an earlier iteration of this property defined label-offset as a 1-axis perpendicular nudge relative to the edge direction. That made edge { label-offset: 8px; } produce a different visual direction per edge slope, which was hard to reason about. Switched to screen-axis CSS-shorthand semantics — see ADR-1184.

How many characters of the label the canvas draws. Default 48. A longer label is cut at a word boundary and ends with …. The count includes the ellipsis, so the drawn text never exceeds the budget.

edge { label-max-chars: 24; } /* tighter, for a dense canvas */
edge#criticalWrite { label-max-chars: none; } /* always draw this one whole */

The authored label is not lost. A truncated edge carries it in full as data-edge-label and in a <title>, so a viewer can show all of it on hover, a static SVG opened in a browser included. The edge is marked data-edge-label-withheld="truncated". An edge whose label fits is emitted exactly as it was before this property existed.

Characters are counted as code points, not as rendered width. A value that is not a positive whole number is reported and dropped, as every invalid value is.

Machine-generated labels (the W / R markers on usecase → resource edges, the N domain edges count on an aggregated edge) are never truncated.

Whether the canvas draws the label at all. Default auto.

Value The canvas draws the label
auto only where it can be seated clear of node cards, other labels and other edges’ lines, with no stroked frame border crossing the label box and on the same side of each frame as its default position
always wherever it lands, even into a collision
hover never; the viewer shows it on hover
edge { label-display: always; } /* every label, wherever it lands */
edge[async] { label-display: hover; } /* keep these quiet until hovered */

Under auto, the automatic placement (see label-position above) first tries to move the label to a clear position: one where it overlaps no card, no other label and no other edge’s line, has no stroked frame border crossing the label box, and is on the same side of each frame (inside or outside) as its default position. A frame stroke merely touching the box edge is allowed. If no position within its reach is clear, the label is left off the canvas instead of being drawn there, and the labels placed after it may use the room. A canvas whose labels all find a clear position is identical under auto and always.

A label left off the canvas stays reachable on the same surface. The edge carries the authored text as data-edge-label and in a <title>, and is marked data-edge-label-withheld="deferred".

Some labels are always drawn, whatever the value:

  • Under auto, a label the author positioned with label-position or label-offset. The author’s position wins, so it is drawn there even into a collision.
  • A machine-generated label (W / R, N domain edges). It is not authored text, so nothing could show it again on hover.
  • The label of an aggregated edge. It is what a reader clicks to open the edge’s breakdown.

To get the behaviour from before these two properties existed:

edge { label-max-chars: none; label-display: always; }

Related TPLs: TPL-3022 — authored content the canvas truncates or withholds stays reachable in full on the same surface. TPL-2048 — label collisions are measured numerically, and a canvas with nothing to withhold stays byte-stable.


  • Global scope (applies to the entire file).
  • The path is relative to the .krs file that declares the @import, and a sheet several files import is loaded once; see @import scope in the syntax reference.
  • When the same selector is defined in multiple files, the last one wins.
  • A warning is emitted on conflict (not an error).
⚠ Warning: Selector "service" is defined in multiple files
- default.krs.style:3
- my-theme.krs.style:2
The definition in my-theme.krs.style is applied (last wins)

function resolveStyle(node, rules) {
return rules
.filter(rule => matches(node, rule.selector))
.sort((a, b) => specificity(a.selector) - specificity(b.selector))
.reduce((acc, rule) => ({ ...acc, ...rule.style }), {})
}
function specificity(selector) {
let score = 0
if (selector.id) score += 100
score += selector.tags.length * 10
score += selector.annotations.length * 10
if (selector.type) score += 1
return score
}

/* ── Kind selectors ── */
user {
background-color: #1D4ED8;
color: #DBEAFE;
border-color: #1E40AF;
border-width: 2px;
border-radius: 8px;
font-size: 13px;
font-weight: bold;
shape: user;
}
service {
background-color: #0369A1;
color: #E0F2FE;
border-color: #075985;
border-width: 2px;
border-radius: 8px;
font-size: 13px;
font-weight: bold;
shape: box;
}
domain {
background-color: #15803D;
color: #D1FAE5;
border-color: #166534;
shape: box;
}
usecase {
background-color: #1F2937;
color: #F9FAFB;
border-color: #374151;
font-size: 11px;
shape: box;
}
impl {
background-color: #78350F;
color: #FEF3C7;
border-color: #92400E;
shape: box;
}
/* ── Tag selectors ── */
[external] {
background-color: #1F2937;
color: #D1D5DB;
border-color: #374151;
border-style: dashed;
}
/* ── Annotation selectors ── */
@deprecated {
badge-color: #EF4444;
badge-icon: "⚠";
badge-label: "Deprecated";
opacity: 0.6;
}
@new {
badge-color: #10B981;
badge-icon: "✦";
badge-label: "NEW";
}
@experimental {
badge-color: #F59E0B;
badge-icon: "⚗";
badge-label: "Experimental";
}
@migration_target {
badge-color: #3B82F6;
badge-icon: "→";
badge-label: "Migration target";
}
/* ── Compound selectors ── */
user[external] {
color: #9CA3AF;
}
[external]@deprecated {
border-color: #EF4444;
}
/* ── ID selectors ── */
#ECommerce {
background-color: #7C3AED;
}
/* ── Edges ── */
edge {
color: #94A3B8;
stroke-width: 1.5px;
font-size: 11px;
}
edge[async] {
border-style: dashed;
color: #6B7280;
}
/* ── Organization diagram (Org Tree View) ── */
team {
background-color: #1E3A5F;
color: #E2E8F0;
border-color: #3B82F6;
}
member {
background-color: #0F172A;
border-color: #334155;
}
/* Highlight a specific team */
#BackendTeam {
border-color: #F59E0B;
border-width: 2px;
}

Boundary frame selectors (boundary / boundary#<id>)

Section titled “Boundary frame selectors (boundary / boundary#<id>)”

Under Group by: boundary the system view draws a dashed frame around each boundary’s members, in an identifying colour cycled by declaration order. A style sheet can take that colour over.

boundary { border-style: solid; } /* every frame */
boundary#pci { border-color: #C0392B; } /* one boundary */

The keyword is what selects the id space. A boundary is not a node, so a bare #pci addresses a node called pci and never reaches the frame, exactly as #criticalWrite addresses a node rather than the edge edge#criticalWrite names. Specificity follows from the same parts as everywhere else: boundary scores 1, boundary#pci scores 101 (100 for the id + 1 for the kind).

Boundaries a sheet does not name keep their cycled colour, so naming one does not disturb the rest.

Scoped boundaries. A boundary declared inside a node block has identity (declaring scope, id), so two scopes may each hold a pci. boundary#pci names the id without naming a scope, and therefore matches that id in every scope, including the top level. There is no way to target one scope’s boundary today; if that turns out to be needed, a qualified form can be added without changing what the unqualified one means.

Supported properties:

Property Effect
border-color The frame’s colour. Also drives the fill and the title, unless those are set explicitly
background-color The frame’s low-alpha fill, when it should differ from border-color
color The frame title, when it should differ from border-color
border-width Frame line width (px)
border-style solid / dashed / dotted. Default dashed

Note: one declaration of border-color repaints the stroke, the fill and the title together. A boundary’s colour is what lets two overlapping frames read as an overlap rather than as one nested in the other, so a single declaration must not split it in two. Set background-color / color when you want them apart.

Note: shape / opacity / border-radius / font-* / badge-* are ignored on a frame. A frame that reaches out of its band is drawn as a rectilinear outline, which has no corner radius to set.

Team frames (Group by: team) are addressed differently, because a team is a node and #<id> already reaches it — see Team frames below.

The selector shares the compatibility tier of the construct it styles: boundary is core from .krs language v2.0 (syntax.md).

Related TPLs: TPL-2234 — a boundary’s colour reaches the frame and the ◇ tab, which are drawn by different code; both read one resolver so a style override cannot repaint only half of it. TPL-1503 — a bare boundary rule parsed and did nothing before this selector existed; it now has an effect. TPL-1296 — the specificity rows above are generated from reference-data.ts, not written here.


Organization diagram node selectors (Org Tree View)

Section titled “Organization diagram node selectors (Org Tree View)”

The Org Tree View supports team / member kind selectors and ID selectors (#NodeId).

Selector Target
team All team cards
member All member cards
#TeamId A specific team card
team#TeamId The same, narrowed to the team kind
#MemberId A specific member card
edge Bézier connectors between teams

Supported properties:

Property Effect
background-color Card background color
color Text color
border-color Border color
border-width Border width (px)
border-radius Border radius (px)
font-size Font size (px)
font-weight Font weight (normal / bold)
font-family Font family

Note: opacity / shape / badge-* are ignored in the Org Tree View. Tag/annotation compound selectors (team[external], etc.) are not supported at this time.

Under Group by: team the system view draws a frame around each team’s members. That frame and the card above are two renderings of one team, so the selectors above address both. There is no separate frame keyword.

team { border-color: #64748B; } /* every team card, and every team frame */
#Platform { border-color: #C0392B; } /* the Platform card, and the Platform frame */
team#Platform { border-color: #C0392B; } /* the same, narrowed to the team kind */

team#<id> is a compound selector, not a second id space: it means “the node with this id, if it is a team”. It scores 101 (100 for the id + 1 for the kind), so it beats a bare #<id> at 100 and a bare team at 1. This is the opposite of boundary#<id>, where the keyword names an id space a bare #<id> cannot reach at all — a boundary is not a node, and a team is.

Which property reaches which rendering. Each one lands on the part of the frame that answers to the part of the card it paints:

Property Card (Org Tree View) Frame (Group by: team)
border-color Border colour Outline colour
background-color Card fill Low-alpha tint inside the frame
color Label colour Frame title colour
border-width Border width (px) Outline width (px)
border-style not applied solid / dashed / dotted. Default dashed
border-radius / font-size / font-weight / font-family as documented above not applied

Note: unlike a boundary frame, a team frame’s tint does not follow border-color. Boundary frames overlap, and there one colour has to reach the tint or the overlap reads as nesting. Team frames never overlap, so each property follows the card instead, which is the reading a single declaration predicts.

Each rendering keeps its own default. The built-in sheet’s team { … } rule is the card’s default and does not reach the frame; the frame’s default is the muted dashed outline the view draws on its own. So a team no sheet names is unchanged, and naming one team does not disturb the rest.

Note: only the three selectors above reach the frame. A rule that adds a predicate — team@deprecated, team[tag], team[from=<id>] — styles the card where it applies and leaves the frame alone. The frame is resolved from the sheet without the organization model in hand, so a predicate about the team cannot be evaluated there; the rule is declined rather than applied with its predicate dropped, which would widen it to every frame.

Related TPLs: TPL-2234 — a team is drawn as a card and as a frame by different code, and one declaration must not repaint only half of it. TPL-2269 — the built-in sheet styles the card only; reading it for the frame would repaint every frame by default. TPL-1101 — team#<id> survives karasu fmt instead of being re-emitted as the wider #<id>. TPL-1296 — the specificity scores quoted here are generated from reference-data.ts.

© 2026 Hiroki Kondo · Licensed underApache-2.0

Built with Cloudflare