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.light.theme
theme light {
    style capability {
        shape "rounded_rectangle"
        fill "#ede9fe"
        stroke "#a78bfa"
        stroke_width "1.5px"
        color "#4c1d95"
    }

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

# default.dark.theme
theme dark {
    style system {
        fill "#0f172a"
        stroke "#38bdf8"
        stroke_width "2px"
        color "#f8fafc"
    }
}

---

1. Referencing Themes in Workspaces

To apply a theme to your architecture workspace, reference it inside the root styles { ... } block using the theme statement. You can declare mode-specific theme files, universal theme files, or both:

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

    styles {
        # Reference theme files (modes defined within each .theme file)
        theme "default.light.theme"
        theme "default.dark.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. Light and Dark Theme Switching

When you declare mode-specific themes, the frontend web UI and rendering pipeline automatically fetch the matching theme when toggling between light and dark modes:

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

# In architecture.ea:
styles {
    theme "default.light.theme"
    theme "default.dark.theme"
}

Rule Resolution & Cascading Semantics

1. Universal Rules (theme { ... } / theme "base" { ... }): Rules defined without a mode apply to both light and dark themes.
2. Mode Rules (theme light { ... } / theme dark { ... }): Applied only when that specific mode is active, layered on top of universal rules.
3. Conflicting Properties (Last One Wins): If multiple matching rules target the same entity property, the later declaration in the stylesheet cascade takes precedence.
4. API Query Contract: Theme endpoints require a mode parameter (GET /api/workspaces/{id}/theme?mode=light|dark) to guarantee deterministic styling for each color scheme.