Themes & Design Systems (theme)

In Scapius, Themes allow you to package and reuse comprehensive visual design systems across multiple architecture models and workspaces.

Themes can be defined as standalone .theme files (e.g. default.theme, dark.theme, enterprise.theme) or declared inline within architecture documents.

# default.theme
theme "enterprise-light" {
    # Strategy Layer styling
    style capability {
        shape "rounded_rectangle"
        fill "#ede9fe"
        stroke "#a78bfa"
        stroke_width "1.5px"
        color "#4c1d95"
    }

    # Application Layer styling
    style system {
        shape "rounded_rectangle"
        fill "#e0f2fe"
        stroke "#38bdf8"
        stroke_width "2px"
        color "#0369a1"
    }

    # Relationship edge styling
    style flows_to {
        stroke "#0284c7"
        stroke_width "2px"
    }
}

---

1. Referencing Themes in Workspaces

To apply a theme to your architecture workspace, reference it inside the root styles { ... } block using the theme statement:

workspace my_architecture "Corporate Architecture" {
    # Architecture entities...

    styles {
        # Reference a standalone .theme file
        theme "default.theme"

        # Optional: Import custom CSS stylesheets
        import_css "./branding.css"

        # Optional: Workspace-level override rules (applied on top of the theme)
        style system where tier == "Tier-1" {
            stroke "#ef4444"
            stroke_width "3px"
            icon "shield-alert"
        }
    }
}

---

2. Standalone .theme File Structure

A .theme file consists of a top-level theme "<name>" { ... } block enclosing a collection of style rules.

Typical Theme Layer Mapping Conventions

A well-structured enterprise theme establishes consistent visual language across architectural layers:

theme "corporate-palette" {

    # ========================================================
    # 1. Strategy & Motivation Layer (Violet / Purple Family)
    # ========================================================
    style capability {
        shape "rounded_rectangle"
        fill "#ede9fe"
        stroke "#a78bfa"
        stroke_width "1.5px"
        color "#4c1d95"
    }

    style goal {
        shape "circle"
        fill "#fce7f3"
        stroke "#f472b6"
        stroke_width "1.5px"
        color "#831843"
    }

    style kpi {
        shape "octagon"
        fill "#dcfce7"
        stroke "#4ade80"
        stroke_width "1.5px"
        color "#14532d"
    }

    # ========================================================
    # 2. Business Architecture Layer (Warm / Amber Family)
    # ========================================================
    style actor {
        shape "actor"
        fill "#ffedd5"
        stroke "#fb923c"
        stroke_width "2px"
        color "#7c2d12"
    }

    style process {
        shape "rounded_rectangle"
        fill "#fef3c7"
        stroke "#f59e0b"
        stroke_width "1.5px"
        color "#92400e"
    }

    # ========================================================
    # 3. Application Layer (Sky Blue / Cyan Family)
    # ========================================================
    style system {
        shape "rounded_rectangle"
        fill "#e0f2fe"
        stroke "#38bdf8"
        stroke_width "2px"
        color "#0369a1"
    }

    style app {
        shape "rectangle"
        fill "#f0f9ff"
        stroke "#0ea5e9"
        stroke_width "1.5px"
        color "#0c4a6e"
    }

    style component {
        shape "rectangle"
        fill "#ffffff"
        stroke "#94a3b8"
        stroke_width "1px"
        color "#334155"
    }

    # ========================================================
    # 4. Data Layer (Teal / Emerald Family)
    # ========================================================
    style data_object {
        shape "cylinder"
        fill "#ccfbf1"
        stroke "#2dd4bf"
        stroke_width "1.5px"
        color "#115e59"
    }

    # ========================================================
    # 5. Technology Layer (Slate / Neutral Family)
    # ========================================================
    style infrastructure {
        shape "cylinder"
        fill "#f1f5f9"
        stroke "#64748b"
        stroke_width "1.5px"
        color "#1e293b"
    }

    style environment {
        shape "cloud"
        fill "#f8fafc"
        stroke "#94a3b8"
        stroke_style "dashed"
        color "#334155"
    }

    # ========================================================
    # 6. Security & Governance Layer
    # ========================================================
    style trust_boundary {
        shape "rectangle"
        stroke "#f59e0b"
        stroke_width "2px"
        stroke_style "dashed"
    }

    style threat {
        shape "diamond"
        fill "#fee2e2"
        stroke "#ef4444"
        color "#991b1b"
    }

    style control {
        shape "rounded_rectangle"
        fill "#dcfce7"
        stroke "#22c55e"
        color "#15803d"
    }

    # ========================================================
    # 7. Default Relationship Edge Styling
    # ========================================================
    style realizes {
        stroke "#10b981"
        stroke_width "1.5px"
    }

    style flows_to {
        stroke "#0ea5e9"
        stroke_width "2px"
    }

    style depends_on {
        stroke "#64748b"
        stroke_width "1.5px"
        stroke_style "dashed"
    }

    style targets {
        stroke "#ef4444"
        stroke_width "2px"
    }

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

---

3. Style Cascade & Precedence

Scapius applies styling rules according to a strict cascading hierarchy:

Default Engine Presets
        ↓ (overridden by)
Base Theme (.theme file or theme statement)
        ↓ (overridden by)
Workspace-Level Styles Block (styles { ... })
        ↓ (overridden by)
View-Scoped Style Rules (views { landscape v1 { style ... } })

1. Base Theme: Sets baseline shapes, stroke widths, palette colors, and typography.
2. Workspace Styles: Overrides base theme properties for domain-specific models (e.g. conditional rules on tier == "Tier-1").
3. View-Level Rules: The most specific rules, applied exclusively to diagrams projected in that single view.

---

4. Multi-Theme Switching in Workspaces

By placing multiple .theme files in your workspace, you can switch between light/dark themes or brand variants by updating a single line in styles:

my-enterprise/
├── architecture.ea
├── light.theme
└── dark.theme

# In architecture.ea:
styles {
    theme "dark.theme"   # Switch theme instantly
}