Style Rules & Presentation (`styles`)

In Scapius, visual presentation concerns (such as colors, borders, stroke styles, shapes, icons, and CSS classes) are strictly decoupled from the underlying architecture domain models.

Visual styles are declared declaratively in dedicated styles { ... } blocks at the workspace root or inside individual views.

Reusable Design Systems

To package, share, and reuse styles across multiple workspaces, define a standalone Theme & Design System (.theme file).

workspace styled_enterprise "Styled Enterprise Architecture" {
    # Architecture entities and relationships...

    styles {
        theme "dark-modern"
        import_css "./corporate-theme.css"

        # Style rule on entities
        style system where tier == "Tier-1" {
            fill "#1e293b"
            stroke "#38bdf8"
            stroke_width "2px"
            shape "rounded_rectangle"
            icon "shield-check"
        }

        # Style rule on relationship edges
        style flows_to where attr.sec:encrypted == "true" {
            stroke "#22c55e"
            stroke_width "2px"
            stroke_style "dashed"
        }
    }
}

1. Syntax Overview

styles {
    # Optional theme presets & stylesheet imports
    theme "<theme_preset_name_or_file>"
    import_css "<relative_css_file_path>"

    # Declarative Style Rules
    style <selector> (where <predicate_expression>)? {
        <style_property> <value>
    }
}

Security & Scoping of Custom Stylesheets

import_css imports local CSS files from within the workspace (e.g. ./corporate-theme.css, styles/branding.css).

Local files only: Remote URLs (http://, https://, //) are disallowed for security to eliminate SSRF and data exfiltration vectors.
Canvas Scoping: Imported CSS rules are automatically scoped to the diagram canvas viewport via native CSS @scope (.diagram-canvas-viewport), ensuring workspace stylesheets style diagram nodes and matrix cards without polluting or breaking application navigation, header bars, editors, or modal dialogs.

2. Entity (Node) Style Properties

When styling architectural entities (system, app, capability, actor, data_object, infrastructure, etc.), the following visual properties are supported:

Property Name	Synonyms / Aliases	Accepted Values	Description & Example
`fill`	`background`, `background_color`	Hex, RGB, or named color	Node background fill color: `fill "#0f172a"`
`stroke`	`border`, `border_color`	Hex, RGB, or named color	Node boundary stroke color: `stroke "#38bdf8"`
`stroke_width`	`border_width`	Dimension string (e.g. `"1px"`, `"2px"`, `"3px"`)	Border thickness: `stroke_width "2px"`
`stroke_style`	`border_style`	`"solid"`, `"dashed"`, `"dotted"`	Border dash pattern: `stroke_style "dashed"`
`color`	`text_color`	Hex, RGB, or named color	Node primary label text color: `color "#ffffff"`
`shape`	-	`"rounded_rectangle"`, `"rectangle"`, `"person"`, `"cylinder"`, `"mobile"`, `"chevron"`, `"hexagon"`, `"octagon"`, `"folder"`, `"shield"`, `"document"`	Visual geometric node shape (11 canonical shapes): `shape "rounded_rectangle"`
`icon`	-	Icon token string	Embedded icon vector: `icon "aws:ec2"`, `icon "tech:kafka"`, `icon "account_balance"`
`css_class`	-	CSS class name	External stylesheet class name: `css_class "pci-glow"`
`custom_css`	-	Inline CSS string	Raw SVG/HTML CSS declarations: `custom_css "filter: drop-shadow(0 0 8px #38bdf8);"`
`font_size`	-	Dimension string or number	Text font size: `font_size "14px"`
`font_weight`	-	`"normal"`, `"semibold"`, `"bold"`, number	Text font weight: `font_weight "bold"`
`font_family`	-	CSS font family string	Typography font family: `font_family "monospace"`
`font_style`	-	`"normal"`, `"italic"`	Text slant style: `font_style "italic"`
`text_transform`	-	`"uppercase"`, `"lowercase"`, `"capitalize"`, `"none"`	Letter case transformation: `text_transform "uppercase"`
`line_height`	-	Dimension string or number	Multi-line text line spacing: `line_height "1.4"`

2.1 Canonical Node Shapes Reference

Scapius provides 11 canonical node shapes designed for enterprise architecture modeling. Every shape is supported across all view projections, live interactive cards, canvas legend generation, and pixel-perfect SVG/PNG exports:

Shape Name	DSL Syntax	Visual Geometry	Primary Semantic Usage
Rounded Rectangle	`shape "rounded_rectangle"`	Clean rectangle with modern 12px rounded corners. Replaces legacy `pill` shape.	Standard enterprise applications, systems, capabilities, goals.
Rectangle	`shape "rectangle"`	Sharp rectangular boundary (0px border radius).	Infrastructure servers, value streams, trust boundaries.
Person	`shape "person"`	Torso silhouette with head disc.	Business actors, human roles, end-users, customers.
Cylinder	`shape "cylinder"`	3D relational cylinder drum with top ellipse.	Databases, data objects, caches, persistence volumes.
Mobile	`shape "mobile"`	Smartphone device silhouette with speaker notch and home indicator bar.	Mobile applications, iOS/Android apps, edge devices.
Chevron	`shape "chevron"`	Forward-pointing directional arrow polygon.	Business processes, value stream stages, pipeline workflows.
Hexagon	`shape "hexagon"`	Six-sided regular polygon.	AI agents, automated bots, microservices.
Octagon	`shape "octagon"`	Eight-sided stop sign polygon.	Threat events, security vulnerabilities, risk scenarios, KPIs.
Folder	`shape "folder"`	Tabbed file directory silhouette.	Logical groups, architectural packages, namespaces.
Shield	`shape "shield"`	Security crest polygon with curved pointed base.	Security controls, firewalls, compliance mitigations.
Document	`shape "document"`	Page silhouette with a folded top-right corner.	Governance policies, enterprise standards, compliance docs.

Pill Shape Deprecation

The legacy pill shape (which had extreme 50% border curvature that constrained usable text width) has been replaced by rounded_rectangle. Use shape "rounded_rectangle" for all modern entity representations.

Cloud & Technology Architecture Icons

Scapius includes a built-in, offline-first vector repository of over 1,760 official cloud and tech architecture icons. Icons can be assigned to entity types, specific entity IDs, or conditional selectors:

styles {
    // 1. Default icon by entity type
    style system {
        icon "account_balance"
    }

    style app {
        icon "tech:react"
    }

    // 2. Specific icon by entity ID
    style "inf_aws_eks" {
        icon "tech:kubernetes"
    }

    style "app_instant_pay" {
        icon "aws:api-gateway"
    }

    // 3. Conditional matching
    style infrastructure where id == "inf_prod_db" {
        icon "tech:postgresql"
    }

    style app where internet_facing == true {
        icon "aws:api-gateway"
    }
}

Supported Icon Providers & Formats

Prefix / Kind	Description	Examples
Default / Lucide (`{name}` or `lucide:{id}`)	Official Lucide Enterprise Icons (1,590+ vectors). If no namespace is specified, Scapius defaults to Lucide.	`icon "server"` `icon "database"` `icon "shield-check"` `icon "credit-card"` `icon "cpu"` `icon "lucide:workflow"`
`assets:{path}`	Workspace Co-Located Assets. References custom SVGs/images inside the active workspace's `assets/` directory.	`icon "assets:systems/mainframe.svg"` `icon "assets:logos/partner-bank.png"`
`aws:{id}`	Official AWS Architecture & Service icons (739+ vectors)	`icon "aws:ec2"` `icon "aws:api-gateway"` `icon "aws:lambda"` `icon "aws:s3"`
`azure:{id}`	Official Microsoft Azure Architecture icons (626+ vectors)	`icon "azure:virtual-machine"` `icon "azure:cosmos-db"` `icon "azure:app-service"`
`gcp:{id}`	Official Google Cloud Platform icons (214+ vectors)	`icon "gcp:compute-engine"` `icon "gcp:cloud-storage"` `icon "gcp:bigquery"`
`k8s:{id}`	Official Kubernetes & CNCF resource icons (38+ vectors)	`icon "k8s:pod"` `icon "k8s:service"` `icon "k8s:deployment"` `icon "k8s:worker-node"`
`tech:{id}`	Curated devops, database, runtime, and streaming brand logos (152+ vectors)	`icon "tech:docker"` `icon "tech:kafka"` `icon "tech:postgresql"` `icon "tech:redis"` `icon "tech:spring-boot"` `icon "tech:python"` `icon "tech:go"`
`material:{name}` / Fallback	Google Material Symbols ligature names (explicit or un-matched fallback)	`icon "material:account_balance"` `icon "material:dns"`
`https://...`	Direct external image or SVG URL	`icon "https://my-cdn.com/custom-logo.svg"`

Workspace Custom Assets (`assets:`)

Enterprises can co-locate proprietary architecture icons and brand logos directly inside their architecture Git repository:

Place custom SVGs or PNGs in the <workspace-root>/assets/ folder (e.g. assets/systems/mainframe.svg).

Reference them in .ea models or .theme stylesheets using icon "assets:<path>":

system coreLedger "Core Banking Ledger" {
    icon "assets:systems/mainframe.svg"
}

Scapius serves assets directly through high-performance static file streaming with path-traversal protection and workspace isolation.

Icon Explorer Tool

Scapius includes an interactive Icon Explorer page built directly into the web application:

URL: Navigate to /icon-explorer (or click Icons in the top navigation bar).
Features: Browse by provider tabs (Lucide, AWS, Azure, GCP, Kubernetes, Tech Stack), filter by architectural domain categories (Compute, Database, Storage, Networking, Security, etc.), search across 3,360+ icons in real time, and copy ready-to-paste DSL syntax with a single click.

Security & Offline Reliability

Zero Runtime Third-Party CDN Calls: All SVGs are persisted locally and served directly from static file mappings (/icons/...).
Strict Security Sanitization: All SVGs pass through strict security filters during ingestion:
- Purges any <script>, <foreignObject>, <iframe>, <embed>, <object>, <link>, or <style> tags.
- Strips all on* inline event handlers (onload, onclick, onerror, etc.) and javascript: URIs.
- Removes XML DOCTYPE and entity declarations to block XXE attacks.
- Restricts markup to an allowlist of pure SVG geometry primitives (path, circle, rect, line, polyline, polygon, ellipse).
Sandboxed Execution: Cloud and external SVGs render inside isolated <img> elements to guarantee browser-level DOM and JavaScript execution isolation, while Lucide renders as clean inline vector primitives.
Vector Fidelity on Export: Diagram exports (SVG, PNG) automatically inline icons as Base64 Data URLs or native SVG nodes, avoiding cross-origin canvas tainting and preserving crisp vector quality at any zoom level.

3. Relationship (Edge) Style Properties

When targeting relationship verbs (flows_to, realizes, serves, depends_on, mitigates, targets, governed_by, protects, etc.), the following edge properties are supported:

Property Name	Accepted Values	Description & Example
`stroke`	Hex, RGB, or named color	Edge line color: `stroke "#ef4444"`
`stroke_width`	Dimension string (e.g. `"1px"`, `"2px"`, `"3px"`)	Edge line thickness: `stroke_width "2px"`
`stroke_style`	`"solid"`, `"dashed"`, `"dotted"`	Line pattern: `stroke_style "dashed"` (useful for async/event flows)
`curve_type`	`"smooth_step"`, `"step"`, `"straight"`, `"bezier"`	Edge routing interpolation algorithm (default: `"smooth_step"`): `curve_type "bezier"`
`arrow`	`"standard"`, `"open"`, `"diamond"`, `"none"`	Edge arrow terminal marker (default: `"standard"`): `arrow "none"`
`css_class`	CSS class name	External CSS class applied to the SVG path: `css_class "animated-flow-line"`
`custom_css`	Inline CSS string	Raw SVG edge styling: `custom_css "stroke-dasharray: 6 3;"`

Edge Label Styling (`label { ... }`)

Edge labels are styled using a dedicated nested label { ... } block inside any relationship style rule:

style flows_to {
    stroke "#38bdf8"
    curve_type "smooth_step"
    arrow "standard"

    label {
        visible true
        color "#f8fafc"
        background "#1e293b"
        stroke "#38bdf8"
        stroke_width "1px"
        border_radius "4px"
        font_size "11px"
        font_weight "600"
    }
}

Label Property	Synonyms	Accepted Values	Description & Example
`visible`	-	`true`, `false`	Shows or hides the relationship label badge: `visible false`
`color`	-	Hex, RGB, or named color	Label text color: `color "#f8fafc"`
`fill`	`background`	Hex, RGB, `"transparent"`	Badge pill background fill: `fill "#0f172a"` (or `background "#0f172a"`)
`stroke`	-	Hex, RGB, `"none"`, `"transparent"`	Badge boundary border stroke color: `stroke "none"`
`stroke_width`	-	Dimension string or number	Badge border thickness: `stroke_width "1px"`
`border_radius`	-	Dimension string or number	Pill corner rounding: `border_radius "4px"` (or `"9999px"` for capsule)
`font_size`	-	Dimension string or number	Text font size: `font_size "11px"`
`font_weight`	-	`"normal"`, `"semibold"`, `"bold"`, number	Text font weight: `font_weight "bold"`
`font_family`	-	CSS font family string	Typography font family: `font_family "monospace"`
`font_style`	-	`"normal"`, `"italic"`	Text slant style: `font_style "italic"`
`text_transform`	-	`"uppercase"`, `"lowercase"`, `"capitalize"`, `"none"`	Letter case transformation: `text_transform "uppercase"`
`line_height`	-	Dimension string or number	Label text line spacing: `line_height "1.2"`
`css_class`	-	CSS class name	External CSS class applied to the label badge: `css_class "badge-primary"`
`custom_css`	-	Inline CSS string	Inline styles applied to the label badge: `custom_css "box-shadow: 0 2px 4px rgba(0,0,0,0.1);"`

4. Selectors

Selectors determine which elements the style rule applies to:

Entity Selectors

Wildcard (*): Targets all entities across the entire model.
Entity Type: Targets all entities of a specific kind (e.g. system, app, component, capability, actor, process, data_object, threat, control, risk_scenario, infrastructure, trust_boundary).
Entity ID: Targets a specific entity by its identifier (e.g. sys_core_banking, cap_customer_onboarding).

Relationship Selectors

Relationship Verb: Targets all edges using a specific verb (e.g. realizes, serves, hosts, reads, writes, flows_to, triggers, composed_of, influences, migrates_to, depends_on, governed_by, mitigates, protects, targets, encloses).
Wildcard / Specific Source-Target Pairs: Targets relationships by verb and source/target predicates.

View Data Element Selectors (`phase.<value>`, `time.<value>`)

Data-driven view elements (such as timeline bars in lifecycle_roadmap and scatter points in portfolio_matrix) use dotted selectors prefixed by the authoring keyword that drives them:

Selector Form	Values	Target Visual Element	Legal View Scopes
`phase.<value>`	`Plan`, `Build`, `Run`, `Retire`	Phased Gantt timeline bars	Workspace root or inside `lifecycle_roadmap`
`time.<value>`	`Invest`, `Tolerate`, `Migrate`, `Eliminate`	Scatter plot markers & quadrant tints	Workspace root or inside `portfolio_matrix`

Applicable Properties: Supports fill (background), css_class, custom_css, and label { ... }.
Disallowed Properties: Rejects shape, icon, arrow, and curve_type with hard compiler errors.
Owning Entity Predicates: In style <prefix>.<value> where <predicate>, predicates evaluate against the owning entity (e.g. style phase.Retire where criticality == "High").
Isolation: Wildcard rules (style *) never match or recolor data elements.

5. Predicate Expressions (`where ...`)

Predicates allow dynamic conditional styling based on architectural properties, tags, lifecycle phases, and custom attributes.

Supported Operators

Equality & Comparison: ==, !=, >, <, >=, <=
String Operations: contains, starts_with, ends_with
Logical Operators: && (AND), || (OR), parenthetical grouping ( ... )

Common Predicate Fields for Entities

Nested AI governance fields are addressed with their qualified names. The autonomy_level value must be one of Autonomous, Semi-Autonomous, Assisted, or Manual. The same fields are available on agent, app, system, component, and process entities. Entities without an ai_governance block are not included in AI governance dashboard metrics:

style agent where ai_governance.autonomy_level == "Assisted" {
    icon "bot"
}

style system where ai_governance.human_in_loop == true {
    shape "shield"
}

# TIME portfolio disposition
style capability where time == "Invest" { fill "#dcfce7" stroke "#15803d" }
style system where time == "Eliminate" { fill "#fee2e2" stroke "#dc2626" }

# Criticality & Tier
style system where tier == "Tier-1" && internet_facing == true {
    stroke "#ef4444"
    stroke_width "3px"
    icon "shield-alert"
}

# Strategic Assessment Score
style system where score.business_value >= 8 && score.tech_fit <= 3 {
    css_class "high-value-legacy-remediation"
}

# Security Classification
style data_object where security.confidentiality == "Critical" || pii == true {
    stroke "#dc2626"
    stroke_style "dashed"
    shape "cylinder"
}

# Custom FinOps & Cloud Attributes
style infrastructure where attr.cloud:provider == "AWS" && attr.finops:tier == "Production" {
    stroke "#f59e0b"
}

Common Predicate Fields for Relationships

# Directional and protocol-based edge styling
style flows_to where interface_type == "gRPC" {
    stroke "#38bdf8"
    stroke_style "solid"
}

style flows_to where interface_type == "Kafka" {
    stroke "#f59e0b"
    stroke_style "dashed"
}

# Compliance & Audit status on relationships
style governed_by where status == "Non-Compliant" {
    stroke "#ef4444"
    stroke_width "2px"
    stroke_style "dotted"
}

style mitigates {
    stroke "#22c55e"
    stroke_width "2px"
}

6. Complete Comprehensive Example

workspace modern_styled_bank "Styled Financial Architecture" {

    layer "Business Layer" {
        capability cap_payments "Payment Processing" {
            maturity "High"
        }
    }

    layer "Application Layer" {
        system sys_gateway "Public API Gateway" {
            tier "Tier-1"
            internet_facing true
        }

        system sys_legacy_ledger "Legacy Mainframe Core" {
            tier "Tier-1"
            time "Eliminate"
            internet_facing false
        }
    }

    # Relationship statements
    sys_gateway flows_to sys_legacy_ledger "Synchronous Transactions" {
        interface_type "gRPC"
        attr sec:encrypted "true"
    }

    # Visual Presentation Block
    styles {
        theme "dark-modern"
        import_css "./custom-palette.css"

        # 1. Entity Node Styling
        style capability where time == "Invest" {
            fill "#064e3b"
            stroke "#059669"
            stroke_width "2px"
            shape "rounded_rectangle"
            color "#ecfdf5"
            icon "trending-up"
        }

        style system where internet_facing == true {
            stroke "#ef4444"
            stroke_width "2px"
            icon "globe"
        }

        style system where time == "Eliminate" {
            fill "#450a0a"
            stroke "#dc2626"
            stroke_style "dashed"
            color "#fef2f2"
        }

        # 2. Relationship Edge Styling
        style flows_to where attr.sec:encrypted == "true" {
            stroke "#22c55e"
            stroke_width "2px"
            stroke_style "solid"
            curve_type "smooth_step"
            arrow "standard"
            label {
                color "#86efac"
                background "#052e16"
                stroke "#22c55e"
            }
        }

        style flows_to where interface_type == "Kafka" {
            stroke "#f59e0b"
            stroke_style "dashed"
            curve_type bezier
            arrow open
            label {
                visible false
            }
        }
    }
}

1. Syntax Overview​

2. Entity (Node) Style Properties​

2.1 Canonical Node Shapes Reference​

Cloud & Technology Architecture Icons​

Supported Icon Providers & Formats​

Workspace Custom Assets (assets:)​

Icon Explorer Tool​

Security & Offline Reliability​

3. Relationship (Edge) Style Properties​

Edge Label Styling (label { ... })​

4. Selectors​

Entity Selectors​

Relationship Selectors​

View Data Element Selectors (phase.<value>, time.<value>)​

5. Predicate Expressions (where ...)​

Supported Operators​

Common Predicate Fields for Entities​

Common Predicate Fields for Relationships​

6. Complete Comprehensive Example​