diff --git a/.gitignore b/.gitignore
index 45cfc444..9b755dee 100644
--- a/.gitignore
+++ b/.gitignore
@@ -198,4 +198,7 @@ CLAUDE.md
 
 tests/generated_screenshots/.runtime/*
 
-internal-*
\ No newline at end of file
+internal-*
+
+# Watchman drops these probe files into every watched directory.
+.watchman-cookie-*
\ No newline at end of file
diff --git a/config/apps/calendar/appearance/black_and_white.yaml b/config/apps/calendar/appearance/black_and_white.yaml
deleted file mode 100644
index dc59e26b..00000000
--- a/config/apps/calendar/appearance/black_and_white.yaml
+++ /dev/null
@@ -1,31 +0,0 @@
-# @package apps.calendar
-
-# UI styling configuration - Black and White Theme
-style:
-  # Color scheme (strictly black, white, and grays)
-  colors:
-    primary: '#ffffff'          # White for primary elements
-    primary_hover: '#dddddd'    # Light gray for hover states
-    secondary: '#aaaaaa'        # Medium gray for secondary elements
-    background: '#000000'       # Pure black background
-    text: '#ffffff'             # White text
-    error: '#ffffff'            # White for errors (with different styling)
-    border: '#444444'           # Dark gray borders
-
-  # Typography
-  typography:
-    font_family: 'Inter, system-ui, sans-serif'
-    heading_font: 'Inter, system-ui, sans-serif'
-    base_font_size: '16px'
-    heading_size: '2rem'        # Larger headings for clear hierarchy
-
-  # Button styles
-  buttons:
-    border_radius: '0px'        # Sharp corners for distinct elements
-    padding: '0.5rem 1rem'
-
-  # Layout
-  layout:
-    container_width: '92%'
-    spacing: '1.5rem'           # More spacing for clear separation
-
diff --git a/config/apps/calendar/appearance/challenging_font.yaml b/config/apps/calendar/appearance/challenging_font.yaml
deleted file mode 100644
index e2dc360b..00000000
--- a/config/apps/calendar/appearance/challenging_font.yaml
+++ /dev/null
@@ -1,30 +0,0 @@
-# @package apps.calendar
-
-# UI styling configuration
-style:
-  # Color scheme
-  colors:
-    primary: '#1095c1'          # Primary color for buttons, links, etc.
-    primary_hover: '#0a6d8a'    # Hover state for primary elements
-    secondary: '#6c757d'        # Secondary color for less important elements
-    background: '#ffffff'       # Main background color
-    text: '#212529'             # Main text color
-    error: '#dc3545'            # Error messages color
-    border: '#ced4da'           # Border color
-
-  # Typography
-  typography:
-    font_family: 'Brush Script MT'   # Main font family 
-    heading_font: 'Brush Script MT'  # Font for headings
-    base_font_size: '16px'      # Base font size
-    heading_size: '1.5rem'      # Size for headings
-
-  # Button styles
-  buttons:
-    border_radius: '0.375rem'   # Border radius for buttons
-    padding: '0.5rem 1rem'      # Button padding
-
-  # Layout
-  layout:
-    container_width: '100%'     # Width of the main container
-    spacing: '1rem'             # Standard spacing between elements
diff --git a/config/apps/calendar/appearance/dark_theme.yaml b/config/apps/calendar/appearance/dark_theme.yaml
deleted file mode 100644
index bbf1e367..00000000
--- a/config/apps/calendar/appearance/dark_theme.yaml
+++ /dev/null
@@ -1,32 +0,0 @@
-# @package apps.calendar
-
-
-# UI styling configuration - Dark Theme
-style:
-  # Color scheme
-  colors:
-    primary: '#bb86fc'          # Light purple
-    primary_hover: '#3700b3'    # Darker purple for hover states
-    secondary: '#03dac6'        # Teal secondary
-    background: '#121212'       # Very dark gray background
-    text: '#ffffff'             # White text
-    error: '#cf6679'            # Pink-red for errors
-    border: '#2d2d2d'           # Dark borders
-
-  # Typography
-  typography:
-    font_family: 'Inter, system-ui, sans-serif'  # Modern font
-    heading_font: 'Inter, system-ui, sans-serif' # Same font for consistency
-    base_font_size: '16px'                       # Standard size
-    heading_size: '1.75rem'                      # Slightly smaller headings for dark theme
-
-  # Button styles
-  buttons:
-    border_radius: '4px'        # More square buttons
-    padding: '0.5rem 1rem'      # Standard padding
-
-  # Layout
-  layout:
-    container_width: '95%'      # Wide container
-    spacing: '1rem'             # Standard spacing
-    
\ No newline at end of file
diff --git a/config/apps/calendar/appearance/default.yaml b/config/apps/calendar/appearance/default.yaml
deleted file mode 100644
index 747b0fab..00000000
--- a/config/apps/calendar/appearance/default.yaml
+++ /dev/null
@@ -1,30 +0,0 @@
-# @package apps.calendar
-
-# UI styling configuration
-style:
-  # Color scheme
-  colors:
-    primary: '#1095c1'          # Primary color for buttons, links, etc.
-    primary_hover: '#0a6d8a'    # Hover state for primary elements
-    secondary: '#6c757d'        # Secondary color for less important elements
-    background: '#ffffff'       # Main background color
-    text: '#212529'             # Main text color
-    error: '#dc3545'            # Error messages color
-    border: '#ced4da'           # Border color
-
-  # Typography
-  typography:
-    font_family: 'sans-serif'   # Main font family 
-    heading_font: 'sans-serif'  # Font for headings
-    base_font_size: '16px'      # Base font size
-    heading_size: '1.5rem'      # Size for headings
-
-  # Button styles
-  buttons:
-    border_radius: '0.375rem'   # Border radius for buttons
-    padding: '0.5rem 1rem'      # Button padding
-
-  # Layout
-  layout:
-    container_width: '100%'     # Width of the main container
-    spacing: '1rem'             # Standard spacing between elements
diff --git a/config/apps/calendar/default.yaml b/config/apps/calendar/default.yaml
index 420ab11f..71b5edc7 100644
--- a/config/apps/calendar/default.yaml
+++ b/config/apps/calendar/default.yaml
@@ -1,6 +1,9 @@
 defaults:
   - content: default
-  - appearance: default
+  - layout: default
 
 database_path: ${databases_dir}/calendar.db
 
+# Per-app theme override. null = inherit the global `apps/theme` selection.
+# Override for just this app with `apps.calendar.theme=solarized`.
+theme: null
diff --git a/config/apps/calendar/layout/default.yaml b/config/apps/calendar/layout/default.yaml
new file mode 100644
index 00000000..0b7faa01
--- /dev/null
+++ b/config/apps/calendar/layout/default.yaml
@@ -0,0 +1,13 @@
+# @package apps.calendar
+# Structure only -- colors, fonts and radii come from the shared theme
+# (`config/apps/theme/`). Select with `apps/calendar/layout=<name>`.
+layout: default
+
+# Width of #calendar-container. Narrower values letterbox the month grid,
+# which changes how much of it fits above the fold for an agent.
+container_width: '100%'
+# Vertical rhythm between the nav, grid and agenda blocks.
+spacing: '1rem'
+# Button hit area. Kept out of the theme because it changes click targets,
+# not appearance.
+button_padding: '0.5rem 1rem'
diff --git a/config/apps/code_editor/appearance/black_and_white.yaml b/config/apps/code_editor/appearance/black_and_white.yaml
deleted file mode 100644
index d96bed78..00000000
--- a/config/apps/code_editor/appearance/black_and_white.yaml
+++ /dev/null
@@ -1,26 +0,0 @@
-# @package apps.code_editor
-
-font_size: 12
-font: "Arial"
-fontcolor: "#000000"
-primary_button_color: "#ffffff"
-secondary_button_color: "#ffffff"
-danger_button_color: "#ffffff"
-textarea_background_color: "#ffffff"
-
-theme: "monokai"
-mode: "python"
-highlight: False
-sort_feature: True
-
-list_of_modes: 
-  - python
-  - javascript
-  - css
-  - yaml
-  - markdown
-  - shell
-  - clike
-  - go
-list_of_themes: 
-  - monokai
\ No newline at end of file
diff --git a/config/apps/code_editor/appearance/challenging_font.yaml b/config/apps/code_editor/appearance/challenging_font.yaml
deleted file mode 100644
index 58c07ebb..00000000
--- a/config/apps/code_editor/appearance/challenging_font.yaml
+++ /dev/null
@@ -1,34 +0,0 @@
-# @package apps.code_editor
-
-font_size: 12
-font: "Brush Script MT"
-fontcolor: ""
-primary_button_color: "#ffffff"
-secondary_button_color: "#ffffff"
-danger_button_color: "#D0021B"
-textarea_background_color: "#ffffff"
-main_background_color: "#90D5FF"
-
-theme: "monokai"
-mode: "python"
-highlight: False
-sort_feature: True
-list_of_modes: 
-  - python
-  - javascript
-  - css
-  - yaml
-  - markdown
-  - shell
-  - clike
-  - go
-list_of_themes: 
-  - monokai
-  - eclipse
-  - solarized
-  - seti
-  - night
-  - dracula
-  - twilight
-  - zenburn
-  - material
\ No newline at end of file
diff --git a/config/apps/code_editor/appearance/colorblind_access.yaml b/config/apps/code_editor/appearance/colorblind_access.yaml
deleted file mode 100644
index 0679e9ab..00000000
--- a/config/apps/code_editor/appearance/colorblind_access.yaml
+++ /dev/null
@@ -1,34 +0,0 @@
-# @package apps.code_editor
-
-font_size: 12
-font: "Arial"
-fontcolor: ""
-primary_button_color: "#DC267F"
-secondary_button_color: "#DC267F"
-danger_button_color: "#FE6100"
-textarea_background_color: "#FFFFFF"
-main_background_color: "#648FFF"
-
-theme: "monokai"
-mode: "python"
-highlight: False
-sort_feature: True
-list_of_modes: 
-  - python
-  - javascript
-  - css
-  - yaml
-  - markdown
-  - shell
-  - clike
-  - go
-list_of_themes: 
-  - monokai
-  - eclipse
-  - solarized
-  - seti
-  - night
-  - dracula
-  - twilight
-  - zenburn
-  - material
\ No newline at end of file
diff --git a/config/apps/code_editor/appearance/dark_theme.yaml b/config/apps/code_editor/appearance/dark_theme.yaml
deleted file mode 100644
index 0a436122..00000000
--- a/config/apps/code_editor/appearance/dark_theme.yaml
+++ /dev/null
@@ -1,33 +0,0 @@
-# @package apps.code_editor
-
-font_size: 12
-font: "Arial"
-fontcolor: ""
-primary_button_color: "#4A90E2"
-secondary_button_color: "#50E3C2"
-danger_button_color: "#D0021B"
-textarea_background_color: "#2d2d2d"
-
-theme: "monokai"
-mode: "python"
-highlight: False
-sort_feature: True
-list_of_modes: 
-  - python
-  - javascript
-  - css
-  - yaml
-  - markdown
-  - shell
-  - clike
-  - go
-list_of_themes: 
-  - monokai
-  - eclipse
-  - solarized
-  - seti
-  - night
-  - dracula
-  - twilight
-  - zenburn
-  - material
diff --git a/config/apps/code_editor/appearance/default.yaml b/config/apps/code_editor/appearance/default.yaml
deleted file mode 100644
index c29d6834..00000000
--- a/config/apps/code_editor/appearance/default.yaml
+++ /dev/null
@@ -1,34 +0,0 @@
-# @package apps.code_editor
-
-font_size: 12
-font: "Arial"
-fontcolor: ""
-primary_button_color: "#ffffff"
-secondary_button_color: "#ffffff"
-danger_button_color: "#D0021B"
-textarea_background_color: "#ffffff"
-main_background_color: "#90D5FF"
-
-theme: "eclipse"
-mode: "python"
-highlight: False
-sort_feature: True
-list_of_modes: 
-  - python
-  - javascript
-  - css
-  - yaml
-  - markdown
-  - shell
-  - clike
-  - go
-list_of_themes: 
-  - monokai
-  - eclipse
-  - solarized
-  - seti
-  - night
-  - dracula
-  - twilight
-  - zenburn
-  - material
\ No newline at end of file
diff --git a/config/apps/code_editor/default.yaml b/config/apps/code_editor/default.yaml
index bf61aa66..bd93b384 100644
--- a/config/apps/code_editor/default.yaml
+++ b/config/apps/code_editor/default.yaml
@@ -1,5 +1,51 @@
 defaults:
   - content: default
-  - appearance: default
+  - layout: default
 
-database_path: ${databases_dir}/codeeditor
\ No newline at end of file
+database_path: ${databases_dir}/codeeditor
+
+# Per-app theme override. null = inherit the global `apps/theme` selection.
+# Override for just this app with `apps.code_editor.theme=solarized`.
+#
+# Note this is the *shared* theme, not CodeMirror's -- the syntax-highlighting
+# stylesheet is `editor_theme` below. The two were both called `theme` until
+# the appearance groups were removed, and the per-app override silently won,
+# leaving CodeMirror initialised with `theme: 'None'`.
+theme: null
+
+# --- Behaviour -------------------------------------------------------------
+
+# CodeMirror syntax-highlighting stylesheet, loaded by name from the CDN.
+# It is a whole stylesheet rather than a set of variables, so the shared
+# theme selects one via its `tone` (see `editor_theme_by_tone`).
+editor_theme: "eclipse"
+editor_theme_by_tone:
+  dark: "monokai"
+  mono: "eclipse"
+# Language mode the editor starts in.
+mode: "python"
+# Load CodeMirror at all. False renders a plain <textarea> -- a meaningfully
+# different observation for an agent, so it is behaviour, not appearance.
+highlight: False
+# Sort the mode/theme dropdowns alphabetically instead of config order.
+sort_feature: True
+
+list_of_modes:
+  - python
+  - javascript
+  - css
+  - yaml
+  - markdown
+  - shell
+  - clike
+  - go
+list_of_themes:
+  - monokai
+  - eclipse
+  - solarized
+  - seti
+  - night
+  - dracula
+  - twilight
+  - zenburn
+  - material
diff --git a/config/apps/code_editor/layout/default.yaml b/config/apps/code_editor/layout/default.yaml
new file mode 100644
index 00000000..4c82aff4
--- /dev/null
+++ b/config/apps/code_editor/layout/default.yaml
@@ -0,0 +1,4 @@
+# @package apps.code_editor
+# Structure only -- colors and fonts come from the shared theme
+# (`config/apps/theme/`). Select with `apps/code_editor/layout=<name>`.
+layout: default
diff --git a/config/apps/maps/appearance/black_and_white.yaml b/config/apps/maps/appearance/black_and_white.yaml
deleted file mode 100644
index e5930a10..00000000
--- a/config/apps/maps/appearance/black_and_white.yaml
+++ /dev/null
@@ -1,18 +0,0 @@
-# @package apps.maps
-
-enable_layer_control: True
-default_layer: 'CartoDB Dark'
-popup_display_rule: 'automatic'
-font_family: 'Arial'
-base_font_size: '16px'
-search_button_color: '#000000'
-delete_button_color: '#000000'
-return_button_color: '#000000'
-calculate_button_color: '#000000'
-delete_button_hover_color: '#000000'
-search_button_hover_color: '#000000'
-calculate_button_hover_color: '#000000'
-
-zoom: 12
-granularity: 'coarse'
-allow_planning: False
\ No newline at end of file
diff --git a/config/apps/maps/appearance/challenging_font.yaml b/config/apps/maps/appearance/challenging_font.yaml
deleted file mode 100644
index aac4307f..00000000
--- a/config/apps/maps/appearance/challenging_font.yaml
+++ /dev/null
@@ -1,14 +0,0 @@
-# @package apps.maps
-
-enable_layer_control: True
-default_layer: 'OpenStreetMap'
-popup_display_rule: 'automatic'
-font_family: 'Brush Script MT'
-base_font_size: '16px'
-search_button_color: '#e74c3c'
-delete_button_color: '#3498db'
-return_button_color: '#95a5a6'
-zoom: 12
-granularity: 'coarse'
-allow_planning: False
-calculate_button_color: '#e74c3c'
\ No newline at end of file
diff --git a/config/apps/maps/appearance/dark_theme.yaml b/config/apps/maps/appearance/dark_theme.yaml
deleted file mode 100644
index 15c74ede..00000000
--- a/config/apps/maps/appearance/dark_theme.yaml
+++ /dev/null
@@ -1,18 +0,0 @@
-# @package apps.maps
-
-enable_layer_control: True
-default_layer: 'CartoDB Dark'
-popup_display_rule: 'automatic'
-font_family: 'Comic Sans MS'
-base_font_size: '16px'
-search_button_color: '#bb86fc'
-delete_button_color: '#03dac6'
-return_button_color: '#000000'
-calculate_button_color: '#bb86fc'
-delete_button_hover_color: '#000000'
-search_button_hover_color: '#3700b3'
-calculate_button_hover_color: '#3700b3'
-sidebar_background_color: '#121212'
-zoom: 12
-granularity: 'coarse'
-allow_planning: False
\ No newline at end of file
diff --git a/config/apps/maps/appearance/default.yaml b/config/apps/maps/appearance/default.yaml
deleted file mode 100644
index 639de7ee..00000000
--- a/config/apps/maps/appearance/default.yaml
+++ /dev/null
@@ -1,15 +0,0 @@
-# @package apps.maps
-
-enable_layer_control: True
-default_layer: 'OpenStreetMap'
-popup_display_rule: 'automatic'
-font_family: 'Comic Sans MS'
-base_font_size: '16px'
-search_button_color: '#3498db'
-delete_button_color: '#e74c3c'
-return_button_color: '#95a5a6'
-zoom: 12
-granularity: 'coarse'
-allow_planning: False
-calculate_button_color: '#3498db'
-sidebar_background_color: '#f8f9fa'
\ No newline at end of file
diff --git a/config/apps/maps/default.yaml b/config/apps/maps/default.yaml
index e6a466af..7528a086 100644
--- a/config/apps/maps/default.yaml
+++ b/config/apps/maps/default.yaml
@@ -1,6 +1,31 @@
 defaults:
   - content: default
-  - appearance: default
+  - layout: default
 
 database_path: ${databases_dir}/maps.db
 otp_url: 'http://localhost:8080/'
+
+# Per-app theme override. null = inherit the global `apps/theme` selection.
+# Override for just this app with `apps.maps.theme=solarized`.
+theme: null
+
+# --- Behaviour -------------------------------------------------------------
+# Not layout and not theme: these change what the map *does*, not how it looks.
+
+# Show Leaflet's basemap switcher. Off hides the tile layer from the agent.
+enable_layer_control: True
+# Basemap used on page load. Tiles are raster images from a CDN, so no CSS
+# variable can recolor them -- the theme instead picks one via its `tone`
+# (see `layer_by_tone`). Must name a key defined in templates/map.html.
+default_layer: 'OpenStreetMap'
+# Basemap per theme tone; anything not listed falls back to `default_layer`.
+# This is what makes `apps/theme=dark` darken the map itself and not just
+# the sidebar around it.
+layer_by_tone:
+  dark: 'CartoDB Dark'
+  mono: 'CartoDB Positron'
+# 'automatic' places a styled marker on save; 'diy' leaves styling to the user.
+popup_display_rule: 'automatic'
+zoom: 12
+granularity: 'coarse'
+allow_planning: False
diff --git a/config/apps/maps/layout/default.yaml b/config/apps/maps/layout/default.yaml
new file mode 100644
index 00000000..d56c17cb
--- /dev/null
+++ b/config/apps/maps/layout/default.yaml
@@ -0,0 +1,4 @@
+# @package apps.maps
+# Structure only -- colors and fonts come from the shared theme
+# (`config/apps/theme/`). Select with `apps/maps/layout=<name>`.
+layout: default
diff --git a/config/apps/messenger/appearance/black_and_white.yaml b/config/apps/messenger/appearance/black_and_white.yaml
deleted file mode 100644
index 7ec2c8e5..00000000
--- a/config/apps/messenger/appearance/black_and_white.yaml
+++ /dev/null
@@ -1,14 +0,0 @@
-# @package apps.messenger
-
-
-font_size: 22
-font: "Inter"
-fontcolor: "black"
-chat_font_size: 16
-chat_font: "Inter"
-chat_fontcolor: "#000000"
-chat_header_fontcolor: "#000000"
-chat_primary_bubble_color: "#ffffff"
-chat_secondary_bubble_color: "#ffffff"
-chat_display_background_color: "#ffffff"
-background_color: "#f0f0f0"
\ No newline at end of file
diff --git a/config/apps/messenger/appearance/challenging_font.yaml b/config/apps/messenger/appearance/challenging_font.yaml
deleted file mode 100644
index 2995433d..00000000
--- a/config/apps/messenger/appearance/challenging_font.yaml
+++ /dev/null
@@ -1,14 +0,0 @@
-# @package apps.messenger
-
-
-font_size: 22
-font: "Brush Script MT"
-fontcolor: "black"
-chat_font_size: 16
-chat_font: "Brush Script MT"
-chat_fontcolor: "#1A1A1A"
-chat_header_fontcolor: "#333333"
-chat_primary_bubble_color: "#dcf8c6"
-chat_secondary_bubble_color: "#ffffff"
-chat_display_background_color: "#e5ddd5"
-background_color: "#f0f0f0"
\ No newline at end of file
diff --git a/config/apps/messenger/appearance/dark_theme.yaml b/config/apps/messenger/appearance/dark_theme.yaml
deleted file mode 100644
index 993ec117..00000000
--- a/config/apps/messenger/appearance/dark_theme.yaml
+++ /dev/null
@@ -1,13 +0,0 @@
-# @package apps.messenger
-
-font_size: 22
-font: "Inter"
-fontcolor: "#bb86fc"
-chat_font_size: 16
-chat_font: "Inter"
-chat_fontcolor: "#FFFFFF"
-chat_header_fontcolor: "white"
-chat_primary_bubble_color: "#bb86fc"
-chat_secondary_bubble_color: "#90EE90"
-chat_display_background_color: "#121212"
-background_color: "#121212"
\ No newline at end of file
diff --git a/config/apps/messenger/appearance/default.yaml b/config/apps/messenger/appearance/default.yaml
deleted file mode 100644
index 648937ae..00000000
--- a/config/apps/messenger/appearance/default.yaml
+++ /dev/null
@@ -1,13 +0,0 @@
-# @package apps.messenger
-
-font_size: 22
-font: "Inter"
-fontcolor: "black"
-chat_font_size: 16
-chat_font: "Inter"
-chat_fontcolor: "#1A1A1A"
-chat_header_fontcolor: "#333333"
-chat_primary_bubble_color: "#dcf8c6"
-chat_secondary_bubble_color: "#ffffff"
-chat_display_background_color: "#e5ddd5"
-background_color: "#f0f0f0"
\ No newline at end of file
diff --git a/config/apps/messenger/default.yaml b/config/apps/messenger/default.yaml
index d5793271..cb803ff5 100644
--- a/config/apps/messenger/default.yaml
+++ b/config/apps/messenger/default.yaml
@@ -1,5 +1,9 @@
 defaults:
   - content: default
-  - appearance: default
-  
-database_path: ${databases_dir}/messenger.db
\ No newline at end of file
+  - layout: default
+
+database_path: ${databases_dir}/messenger.db
+
+# Per-app theme override. null = inherit the global `apps/theme` selection.
+# Override for just this app with `apps.messenger.theme=solarized`.
+theme: null
diff --git a/config/apps/messenger/layout/default.yaml b/config/apps/messenger/layout/default.yaml
new file mode 100644
index 00000000..10ecaf61
--- /dev/null
+++ b/config/apps/messenger/layout/default.yaml
@@ -0,0 +1,4 @@
+# @package apps.messenger
+# Structure only -- colors and fonts come from the shared theme
+# (`config/apps/theme/`). Select with `apps/messenger/layout=<name>`.
+layout: default
diff --git a/config/apps/onlineshop/appearance/black_and_white.yaml b/config/apps/onlineshop/appearance/black_and_white.yaml
deleted file mode 100644
index 048f0d66..00000000
--- a/config/apps/onlineshop/appearance/black_and_white.yaml
+++ /dev/null
@@ -1,17 +0,0 @@
-# @package apps.onlineshop
-
-allowed_credit_cards:
-  - 'Visa'
-  - 'MasterCard'
-  # - 'Amex'
-enable_credit_card_check: false
-enable: False
-
-
-font_family: 'Arial'
-base_font_size: '16px'
-font_color: '#000000'
-background_color: '#FFFFFF'
-button_background_color: '#FFFFFF'
-button_font_color: '#000000'
-highlight_font_color: '#000000'
\ No newline at end of file
diff --git a/config/apps/onlineshop/appearance/challenging_font.yaml b/config/apps/onlineshop/appearance/challenging_font.yaml
deleted file mode 100644
index be0dff65..00000000
--- a/config/apps/onlineshop/appearance/challenging_font.yaml
+++ /dev/null
@@ -1,14 +0,0 @@
-# @package apps.onlineshop
-
-allowed_credit_cards:
-  - 'Visa'
-  - 'MasterCard'
-  # - 'Amex'
-enable_credit_card_check: false
-enable: False
-
-
-font_family: 'Brush Script MT'
-base_font_size: '16px'
-font_color: '#333333'
-background_color: '#F0F8FF'
\ No newline at end of file
diff --git a/config/apps/onlineshop/appearance/dark_theme.yaml b/config/apps/onlineshop/appearance/dark_theme.yaml
deleted file mode 100644
index 986dc183..00000000
--- a/config/apps/onlineshop/appearance/dark_theme.yaml
+++ /dev/null
@@ -1,17 +0,0 @@
-# @package apps.onlineshop
-
-allowed_credit_cards:
-  - 'Visa'
-  - 'MasterCard'
-  # - 'Amex'
-enable_credit_card_check: false
-enable: False
-
-
-font_family: 'Arial'
-base_font_size: '16px'
-font_color: '#bb86fc'
-background_color: '#121212'
-button_background_color: '#FFFFFF'
-button_font_color: '#3700b3'
-highlight_font_color: '#bb86fc'
\ No newline at end of file
diff --git a/config/apps/onlineshop/appearance/default.yaml b/config/apps/onlineshop/appearance/default.yaml
deleted file mode 100644
index e6634a3a..00000000
--- a/config/apps/onlineshop/appearance/default.yaml
+++ /dev/null
@@ -1,14 +0,0 @@
-# @package apps.onlineshop
-
-allowed_credit_cards:
-  - 'Visa'
-  - 'MasterCard'
-  # - 'Amex'
-enable_credit_card_check: false
-enable: False
-
-
-font_family: 'Arial'
-base_font_size: '16px'
-font_color: '#333333'
-background_color: '#F0F8FF'
\ No newline at end of file
diff --git a/config/apps/onlineshop/default.yaml b/config/apps/onlineshop/default.yaml
index 56f14ae6..ab108223 100644
--- a/config/apps/onlineshop/default.yaml
+++ b/config/apps/onlineshop/default.yaml
@@ -1,5 +1,20 @@
 defaults:
   - content: default
-  - appearance: default
+  - layout: default
 
-database_path: ${databases_dir}/onlineshop
\ No newline at end of file
+database_path: ${databases_dir}/onlineshop
+
+# Per-app theme override. null = inherit the global `apps/theme` selection.
+# Override for just this app with `apps.onlineshop.theme=solarized`.
+theme: null
+
+# --- Behaviour -------------------------------------------------------------
+
+# Off by default: the shop needs OpenJDK 21 and a downloaded dataset
+# (see setup.sh), so it is opt-in with `apps.onlineshop.enable=True`.
+enable: False
+allowed_credit_cards:
+  - 'Visa'
+  - 'MasterCard'
+  # - 'Amex'
+enable_credit_card_check: false
diff --git a/config/apps/onlineshop/layout/default.yaml b/config/apps/onlineshop/layout/default.yaml
new file mode 100644
index 00000000..41253d70
--- /dev/null
+++ b/config/apps/onlineshop/layout/default.yaml
@@ -0,0 +1,4 @@
+# @package apps.onlineshop
+# Structure only -- colors and fonts come from the shared theme
+# (`config/apps/theme/`). Select with `apps/onlineshop/layout=<name>`.
+layout: default
diff --git a/config/apps/start_page/appearance/black_and_white.yaml b/config/apps/start_page/appearance/black_and_white.yaml
deleted file mode 100644
index d9944fb3..00000000
--- a/config/apps/start_page/appearance/black_and_white.yaml
+++ /dev/null
@@ -1,72 +0,0 @@
-# @package apps.start_page
-# Layout and styling
-style: 1                # Style number (1, 2, or 3) as per Story template
-size: "small"           # Size of items - "small", "medium", or "big"
-fade_in: false          # Scroll-reveal fade is cosmetic and leaves the page mid-animation in agent screenshots; keep off for deterministic rendering
-lightbox: false         # Enable lightbox effect for images
-random_tile_reoder: false  # Whether to shuffle the items
-wrapper_style: 1        # Wrapper style number
-wrapper_align: "center" # Wrapper alignment - "left", "center", "right"
-wrapper_color: null     # Wrapper color number (1-7) or null
-wrapper_invert: false   # Whether to invert the wrapper color scheme
-
-# Font settings
-font_family: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"  # iOS-like font stack
-font_size: 11           # Smaller base font size for compact look
-font_color: "#1d1d1f"   # Dark gray text color like iOS
-heading_font: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"  # iOS-like font stack
-heading_color: "#1d1d1f" # Dark gray heading color
-
-# Item appearance - iPhone app style
-item_border_radius: 22  # Higher border radius for iOS rounded corners
-item_padding: 1.2       # Reduced padding for more compact look
-item_text_align: "center" # Text alignment - "left", "center", "right"
-item_hover_effect: true # Enable hover effect
-hover_shadow: true      # Enable shadow on hover
-hover_scale: true       # Enable subtle scale effect on hover like iOS
-hover_brightness: false # Disable brightness effect
-
-# Color scheme
-use_theme_colors: false # Whether to use Story theme colors (1-7) instead of custom colors
-theme_color: 1          # Theme color number when use_theme_colors is true
-background_color: "#ffffff"  # Light gray background like iOS
-app_background_colors:  # iOS-inspired gradient colors for app tiles
-  ["#2e2e2e", "#2e2e2e", "#2e2e2e", "#2e2e2e", "#2e2e2e", "#2e2e2e", "#2e2e2e"]
-use_random_colors: false # Generate random colors for items instead of using app_background_colors
-
-# Apps configuration
-icon_path: "/assets/icons/real_icons"
-bw_icon_path: "/assets/icons/real_icons_bw"
-apps:
-  todo:
-    icon: ${apps.start_page.bw_icon_path}/todo.png 
-    enabled: true
-    position: 1
-    clickable_logo: false
-  calendar:
-    icon: ${apps.start_page.bw_icon_path}/calendar.png
-    enabled: true
-    position: 2
-    clickable_logo: false
-  messages:
-    icon: ${apps.start_page.bw_icon_path}/messages.png
-    user_icon: ${apps.start_page.bw_icon_path}/user.png
-    group_icon: ${apps.start_page.bw_icon_path}/group.png
-    enabled: true
-    position: 3
-    clickable_logo: false
-  maps:
-    icon: ${apps.start_page.bw_icon_path}/maps.png
-    enabled: true
-    position: 4
-    clickable_logo: false
-  codeeditor:
-    icon: ${apps.start_page.bw_icon_path}/code.png
-    enabled: true
-    position: 5
-    clickable_logo: false
-  onlineshop:
-    icon: ${apps.start_page.bw_icon_path}/shop.png
-    enabled: true
-    position: 6
-    clickable_logo: false
\ No newline at end of file
diff --git a/config/apps/start_page/appearance/challenging_font.yaml b/config/apps/start_page/appearance/challenging_font.yaml
deleted file mode 100644
index 765146bd..00000000
--- a/config/apps/start_page/appearance/challenging_font.yaml
+++ /dev/null
@@ -1,72 +0,0 @@
-# @package apps.start_page
-# Layout and styling
-style: 1                # Style number (1, 2, or 3) as per Story template
-size: "small"           # Size of items - "small", "medium", or "big"
-fade_in: false          # Scroll-reveal fade is cosmetic and leaves the page mid-animation in agent screenshots; keep off for deterministic rendering
-lightbox: false         # Enable lightbox effect for images
-random_tile_reoder: false  # Whether to shuffle the items
-wrapper_style: 1        # Wrapper style number
-wrapper_align: "center" # Wrapper alignment - "left", "center", "right"
-wrapper_color: null     # Wrapper color number (1-7) or null
-wrapper_invert: false   # Whether to invert the wrapper color scheme
-
-# Font settings
-font_family: "Brush Script MT"  # iOS-like font stack
-font_size: 11           # Smaller base font size for compact look
-font_color: "#1d1d1f"   # Dark gray text color like iOS
-heading_font: "Brush Script MT"  # iOS-like font stack
-heading_color: "#1d1d1f" # Dark gray heading color
-
-# Item appearance - iPhone app style
-item_border_radius: 22  # Higher border radius for iOS rounded corners
-item_padding: 1.2       # Reduced padding for more compact look
-item_text_align: "center" # Text alignment - "left", "center", "right"
-item_hover_effect: true # Enable hover effect
-hover_shadow: true      # Enable shadow on hover
-hover_scale: true       # Enable subtle scale effect on hover like iOS
-hover_brightness: false # Disable brightness effect
-
-# Color scheme
-use_theme_colors: false # Whether to use Story theme colors (1-7) instead of custom colors
-theme_color: 1          # Theme color number when use_theme_colors is true
-background_color: "#f2f2f7"  # Light gray background like iOS
-app_background_colors:  # iOS-inspired gradient colors for app tiles
-  ["#007AFF", "#FF3B30", "#FF9500", "#FFCC02", "#34C759", "#5856D6", "#AF52DE"]
-use_random_colors: false # Generate random colors for items instead of using app_background_colors
-
-# Apps configuration
-icon_path: "/assets/icons/real_icons"
-bw_icon_path: "/assets/icons/real_icons_bw"
-apps:
-  todo:
-    icon: ${apps.start_page.icon_path}/todo.png 
-    enabled: true
-    position: 1
-    clickable_logo: false
-  calendar:
-    icon: ${apps.start_page.icon_path}/calendar.png
-    enabled: true
-    position: 2
-    clickable_logo: false
-  messages:
-    icon: ${apps.start_page.icon_path}/messages.png
-    user_icon: ${apps.start_page.bw_icon_path}/user.png
-    group_icon: ${apps.start_page.bw_icon_path}/group.png
-    enabled: true
-    position: 3
-    clickable_logo: false
-  maps:
-    icon: ${apps.start_page.icon_path}/maps.png
-    enabled: true
-    position: 4
-    clickable_logo: false
-  codeeditor:
-    icon: ${apps.start_page.icon_path}/code.png
-    enabled: true
-    position: 5
-    clickable_logo: false
-  onlineshop:
-    icon: ${apps.start_page.icon_path}/shop.png
-    enabled: true
-    position: 6
-    clickable_logo: false
\ No newline at end of file
diff --git a/config/apps/start_page/appearance/dark_theme.yaml b/config/apps/start_page/appearance/dark_theme.yaml
deleted file mode 100644
index 6dcb59b9..00000000
--- a/config/apps/start_page/appearance/dark_theme.yaml
+++ /dev/null
@@ -1,72 +0,0 @@
-# @package apps.start_page
-# Layout and styling
-style: 1                # Style number (1, 2, or 3) as per Story template
-size: "small"           # Size of items - "small", "medium", or "big"
-fade_in: false          # Scroll-reveal fade is cosmetic and leaves the page mid-animation in agent screenshots; keep off for deterministic rendering
-lightbox: false         # Enable lightbox effect for images
-random_tile_reoder: false  # Whether to shuffle the items
-wrapper_style: 1        # Wrapper style number
-wrapper_align: "center" # Wrapper alignment - "left", "center", "right"
-wrapper_color: null     # Wrapper color number (1-7) or null
-wrapper_invert: false   # Whether to invert the wrapper color scheme
-
-# Font settings
-font_family: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"  # iOS-like font stack
-font_size: 11           # Smaller base font size for compact look
-font_color: "#ffffff"   # Text color like iOS
-heading_font: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"  # iOS-like font stack
-heading_color: "#f0f0f0" # close-to-white light heading color
-
-# Item appearance - iPhone app style
-item_border_radius: 22  # Higher border radius for iOS rounded corners
-item_padding: 1.2       # Reduced padding for more compact look
-item_text_align: "center" # Text alignment - "left", "center", "right"
-item_hover_effect: true # Enable hover effect
-hover_shadow: true      # Enable shadow on hover
-hover_scale: true       # Enable subtle scale effect on hover like iOS
-hover_brightness: false # Disable brightness effect
-
-# Color scheme
-use_theme_colors: false # Whether to use Story theme colors (1-7) instead of custom colors
-theme_color: 1          # Theme color number when use_theme_colors is true
-background_color: "#000000"  # Black background like iOS
-app_background_colors:  # grey background for apps
-  ["#636262", "#636262", "#636262", "#636262", "#636262", "#636262", "#636262"]
-use_random_colors: false # Generate random colors for items instead of using app_background_colors
-
-# Apps configuration
-icon_path: "/assets/icons/real_icons"
-bw_icon_path: "/assets/icons/real_icons_bw"
-apps:
-  todo:
-    icon: ${apps.start_page.bw_icon_path}/todo.png 
-    enabled: true
-    position: 1
-    clickable_logo: false
-  calendar:
-    icon: ${apps.start_page.bw_icon_path}/calendar.png
-    enabled: true
-    position: 2
-    clickable_logo: false
-  messages:
-    icon: ${apps.start_page.bw_icon_path}/messages.png
-    user_icon: ${apps.start_page.bw_icon_path}/user.png
-    group_icon: ${apps.start_page.bw_icon_path}/group.png
-    enabled: true
-    position: 3
-    clickable_logo: false
-  maps:
-    icon: ${apps.start_page.bw_icon_path}/maps.png
-    enabled: true
-    position: 4
-    clickable_logo: false
-  codeeditor:
-    icon: ${apps.start_page.bw_icon_path}/code.png
-    enabled: true
-    position: 5
-    clickable_logo: false
-  onlineshop:
-    icon: ${apps.start_page.bw_icon_path}/shop.png
-    enabled: true
-    position: 6
-    clickable_logo: false
\ No newline at end of file
diff --git a/config/apps/start_page/appearance/default.yaml b/config/apps/start_page/appearance/default.yaml
deleted file mode 100644
index 71ab0e9e..00000000
--- a/config/apps/start_page/appearance/default.yaml
+++ /dev/null
@@ -1,72 +0,0 @@
-# @package apps.start_page
-# Layout and styling
-style: 1                # Style number (1, 2, or 3) as per Story template
-size: "small"           # Size of items - "small", "medium", or "big"
-fade_in: false          # Scroll-reveal fade is cosmetic and leaves the page mid-animation in agent screenshots; keep off for deterministic rendering
-lightbox: false         # Enable lightbox effect for images
-random_tile_reoder: false  # Whether to shuffle the items
-wrapper_style: 1        # Wrapper style number
-wrapper_align: "center" # Wrapper alignment - "left", "center", "right"
-wrapper_color: null     # Wrapper color number (1-7) or null
-wrapper_invert: false   # Whether to invert the wrapper color scheme
-
-# Font settings
-font_family: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"  # iOS-like font stack
-font_size: 11           # Smaller base font size for compact look
-font_color: "#1d1d1f"   # Dark gray text color like iOS
-heading_font: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"  # iOS-like font stack
-heading_color: "#1d1d1f" # Dark gray heading color
-
-# Item appearance - iPhone app style
-item_border_radius: 22  # Higher border radius for iOS rounded corners
-item_padding: 1.2       # Reduced padding for more compact look
-item_text_align: "center" # Text alignment - "left", "center", "right"
-item_hover_effect: true # Enable hover effect
-hover_shadow: true      # Enable shadow on hover
-hover_scale: true       # Enable subtle scale effect on hover like iOS
-hover_brightness: false # Disable brightness effect
-
-# Color scheme
-use_theme_colors: false # Whether to use Story theme colors (1-7) instead of custom colors
-theme_color: 1          # Theme color number when use_theme_colors is true
-background_color: "#f2f2f7"  # Light gray background like iOS
-app_background_colors:  # iOS-inspired gradient colors for app tiles
-  ["#007AFF", "#FF3B30", "#FF9500", "#FFCC02", "#34C759", "#5856D6", "#AF52DE"]
-use_random_colors: false # Generate random colors for items instead of using app_background_colors
-
-# Apps configuration
-icon_path: "/assets/icons/real_icons"
-bw_icon_path: "/assets/icons/real_icons_bw"
-apps:
-  todo:
-    icon: ${apps.start_page.icon_path}/todo.png 
-    enabled: true
-    position: 1
-    clickable_logo: false
-  calendar:
-    icon: ${apps.start_page.icon_path}/calendar.png
-    enabled: true
-    position: 2
-    clickable_logo: false
-  messages:
-    icon: ${apps.start_page.icon_path}/messages.png
-    user_icon: ${apps.start_page.bw_icon_path}/user.png
-    group_icon: ${apps.start_page.bw_icon_path}/group.png
-    enabled: true
-    position: 3
-    clickable_logo: false
-  maps:
-    icon: ${apps.start_page.icon_path}/maps.png
-    enabled: true
-    position: 4
-    clickable_logo: false
-  codeeditor:
-    icon: ${apps.start_page.icon_path}/code.png
-    enabled: true
-    position: 5
-    clickable_logo: false
-  onlineshop:
-    icon: ${apps.start_page.icon_path}/shop.png
-    enabled: true
-    position: 6
-    clickable_logo: false
\ No newline at end of file
diff --git a/config/apps/start_page/default.yaml b/config/apps/start_page/default.yaml
index c461049f..69689a37 100644
--- a/config/apps/start_page/default.yaml
+++ b/config/apps/start_page/default.yaml
@@ -1,3 +1,7 @@
 defaults:
   - content: default
-  - appearance: default
+  - layout: default
+
+# Per-app theme override. null = inherit the global `apps/theme` selection.
+# Override for just this app with `apps.start_page.theme=solarized`.
+theme: null
diff --git a/config/apps/start_page/layout/broken_logos.yaml b/config/apps/start_page/layout/broken_logos.yaml
new file mode 100644
index 00000000..78011c14
--- /dev/null
+++ b/config/apps/start_page/layout/broken_logos.yaml
@@ -0,0 +1,9 @@
+# @package apps.start_page
+# Every icon is detached from its tile, so the picture no longer identifies
+# the app and the agent has to read the label. Structure, not appearance:
+# the palette and typography are whatever the active theme says.
+defaults:
+  - default
+
+layout: broken_logos
+shuffle_icons: true
diff --git a/config/apps/start_page/appearance/clickable_logos.yaml b/config/apps/start_page/layout/clickable_logos.yaml
similarity index 57%
rename from config/apps/start_page/appearance/clickable_logos.yaml
rename to config/apps/start_page/layout/clickable_logos.yaml
index 98fa7feb..19b76b9d 100644
--- a/config/apps/start_page/appearance/clickable_logos.yaml
+++ b/config/apps/start_page/layout/clickable_logos.yaml
@@ -1,6 +1,10 @@
 # @package apps.start_page
+# Each app's in-page logo header becomes a link back to the start page,
+# adding a navigation affordance that does not exist by default.
 defaults:
   - default
+
+layout: clickable_logos
 apps:
   todo:
     clickable_logo: true
@@ -13,4 +17,4 @@ apps:
   codeeditor:
     clickable_logo: true
   onlineshop:
-    clickable_logo: true
\ No newline at end of file
+    clickable_logo: true
diff --git a/config/apps/start_page/appearance/broken_logos.yaml b/config/apps/start_page/layout/default.yaml
similarity index 64%
rename from config/apps/start_page/appearance/broken_logos.yaml
rename to config/apps/start_page/layout/default.yaml
index 2f5d5a35..903e2936 100644
--- a/config/apps/start_page/appearance/broken_logos.yaml
+++ b/config/apps/start_page/layout/default.yaml
@@ -1,23 +1,21 @@
 # @package apps.start_page
-# Layout and styling
+# Structure only -- fonts and text colors come from the shared theme
+# (`config/apps/theme/`). Select with `apps/start_page/layout=<name>`.
+layout: default
+
+# Layout
 style: 1                # Style number (1, 2, or 3) as per Story template
 size: "small"           # Size of items - "small", "medium", or "big"
 fade_in: false          # Scroll-reveal fade is cosmetic and leaves the page mid-animation in agent screenshots; keep off for deterministic rendering
 lightbox: false         # Enable lightbox effect for images
 random_tile_reoder: false  # Whether to shuffle the items
+shuffle_icons: false    # Whether to detach each app's icon from its tile
 wrapper_style: 1        # Wrapper style number
 wrapper_align: "center" # Wrapper alignment - "left", "center", "right"
 wrapper_color: null     # Wrapper color number (1-7) or null
 wrapper_invert: false   # Whether to invert the wrapper color scheme
 
-# Font settings
-font_family: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"  # iOS-like font stack
-font_size: 11           # Smaller base font size for compact look
-font_color: "#1d1d1f"   # Dark gray text color like iOS
-heading_font: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif"  # iOS-like font stack
-heading_color: "#1d1d1f" # Dark gray heading color
-
-# Item appearance - iPhone app style
+# Item geometry - iPhone app style
 item_border_radius: 22  # Higher border radius for iOS rounded corners
 item_padding: 1.2       # Reduced padding for more compact look
 item_text_align: "center" # Text alignment - "left", "center", "right"
@@ -26,32 +24,42 @@ hover_shadow: true      # Enable shadow on hover
 hover_scale: true       # Enable subtle scale effect on hover like iOS
 hover_brightness: false # Disable brightness effect
 
-# Color scheme
+# Tile fills. These are the one piece of color the theme does not own: the
+# tiles are a deliberately saturated iOS-style palette that carries no
+# semantic meaning, so mapping it onto theme tokens would flatten six
+# distinguishable targets into one. Non-light themes collapse it to a single
+# fill instead (see `tile_fill_by_tone`).
 use_theme_colors: false # Whether to use Story theme colors (1-7) instead of custom colors
 theme_color: 1          # Theme color number when use_theme_colors is true
-background_color: "#f2f2f7"  # Light gray background like iOS
 app_background_colors:  # iOS-inspired gradient colors for app tiles
   ["#007AFF", "#FF3B30", "#FF9500", "#FFCC02", "#34C759", "#5856D6", "#AF52DE"]
 use_random_colors: false # Generate random colors for items instead of using app_background_colors
+tile_fill_by_tone:      # Single fill replacing the palette, by theme tone
+  dark: "#636262"
+  mono: "#2e2e2e"
 
-shuffle_icons: True
-
-# Apps configuration
+# Icon sets. The theme's `icon_set` asset picks between them: PNGs cannot be
+# recolored by a CSS variable, and the repo ships a hand-made greyscale set
+# that beats a `filter: grayscale()` approximation.
 icon_path: "/assets/icons/real_icons"
 bw_icon_path: "/assets/icons/real_icons_bw"
+
 apps:
   todo:
-    icon: ${apps.start_page.icon_path}/todo.png 
+    icon: ${apps.start_page.icon_path}/todo.png
+    bw_icon: ${apps.start_page.bw_icon_path}/todo.png
     enabled: true
     position: 1
     clickable_logo: false
   calendar:
     icon: ${apps.start_page.icon_path}/calendar.png
+    bw_icon: ${apps.start_page.bw_icon_path}/calendar.png
     enabled: true
     position: 2
     clickable_logo: false
   messages:
     icon: ${apps.start_page.icon_path}/messages.png
+    bw_icon: ${apps.start_page.bw_icon_path}/messages.png
     user_icon: ${apps.start_page.bw_icon_path}/user.png
     group_icon: ${apps.start_page.bw_icon_path}/group.png
     enabled: true
@@ -59,16 +67,19 @@ apps:
     clickable_logo: false
   maps:
     icon: ${apps.start_page.icon_path}/maps.png
+    bw_icon: ${apps.start_page.bw_icon_path}/maps.png
     enabled: true
     position: 4
     clickable_logo: false
   codeeditor:
     icon: ${apps.start_page.icon_path}/code.png
+    bw_icon: ${apps.start_page.bw_icon_path}/code.png
     enabled: true
     position: 5
     clickable_logo: false
   onlineshop:
     icon: ${apps.start_page.icon_path}/shop.png
+    bw_icon: ${apps.start_page.bw_icon_path}/shop.png
     enabled: true
     position: 6
-    clickable_logo: false
\ No newline at end of file
+    clickable_logo: false
diff --git a/config/apps/theme/bootstrap.yaml b/config/apps/theme/bootstrap.yaml
new file mode 100644
index 00000000..41a62ed5
--- /dev/null
+++ b/config/apps/theme/bootstrap.yaml
@@ -0,0 +1,28 @@
+# @package apps.theme
+# Bootstrap 5 look approximated with design tokens (no Bootstrap CSS needed).
+name: bootstrap
+import_url: ""
+tokens:
+  color-bg: "#ffffff"
+  color-surface: "#f8f9fa"
+  color-fg: "#212529"
+  color-muted: "#6c757d"
+  color-border: "#dee2e6"
+  color-primary: "#0d6efd"
+  color-primary-hover: "#0b5ed7"
+  color-on-primary: "#ffffff"
+  color-accent: "#198754"
+  color-danger: "#dc3545"
+  color-neutral: "#6c757d"
+  color-btn-fg: "#ffffff"
+  font-family: "system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif"
+  font-heading: "inherit"
+  font-mono: "SFMono-Regular, Menlo, Monaco, Consolas, monospace"
+  font-size-base: "16px"
+  font-size-sm: "14px"
+  font-size-heading: "1.5rem"
+  radius: "0.375rem"
+  space: "8px"
+assets:
+  tone: light
+  icon_set: color
diff --git a/config/apps/theme/challenging_font.yaml b/config/apps/theme/challenging_font.yaml
new file mode 100644
index 00000000..86a408ff
--- /dev/null
+++ b/config/apps/theme/challenging_font.yaml
@@ -0,0 +1,33 @@
+# @package apps.theme
+# The default palette rendered in a hard-to-read script face. Isolates
+# typography as a variation axis: identical colors and layout to `default`,
+# so any change in agent success is attributable to legibility alone.
+name: challenging_font
+import_url: ""
+tokens:
+  color-bg: "#ffffff"
+  color-surface: "#f4f5f7"
+  color-fg: "#1a1a1a"
+  color-muted: "#6b7280"
+  color-border: "#dfe1e6"
+  color-primary: "#2563eb"
+  color-primary-hover: "#1d4ed8"
+  color-on-primary: "#ffffff"
+  color-accent: "#2563eb"
+  color-danger: "#b22222"
+  color-neutral: "#36454f"
+  color-btn-fg: "#ffffff"
+  font-family: "'Brush Script MT', cursive"
+  font-heading: "inherit"
+  # The editor stays monospace on purpose -- a script face in a code pane
+  # destroys column alignment, which is a different perturbation than the
+  # legibility one this theme is meant to isolate.
+  font-mono: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
+  font-size-base: "16px"
+  font-size-sm: "14px"
+  font-size-heading: "1.5rem"
+  radius: "8px"
+  space: "8px"
+assets:
+  tone: light
+  icon_set: color
diff --git a/config/apps/theme/colorblind.yaml b/config/apps/theme/colorblind.yaml
new file mode 100644
index 00000000..24e0a099
--- /dev/null
+++ b/config/apps/theme/colorblind.yaml
@@ -0,0 +1,31 @@
+# @package apps.theme
+# Colorblind-safe palette (IBM Design Library), generalised from the code
+# editor's former `colorblind_access` appearance variant so every app can use
+# it. Primary/danger stay distinguishable under deuteranopia and protanopia,
+# which is exactly the pair an agent has to tell apart (save vs delete).
+name: colorblind
+import_url: ""
+tokens:
+  color-bg: "#ffffff"
+  color-surface: "#648fff"        # IBM blue, as the editor variant used it
+  color-fg: "#000000"
+  color-muted: "#5a5a5a"
+  color-border: "#785ef0"
+  color-primary: "#dc267f"        # magenta
+  color-primary-hover: "#a81b62"
+  color-on-primary: "#ffffff"
+  color-accent: "#785ef0"         # violet
+  color-danger: "#fe6100"         # orange -- separable from magenta, unlike red
+  color-neutral: "#ffb000"        # amber
+  color-btn-fg: "#000000"
+  font-family: "system-ui, -apple-system, 'Helvetica Neue', Arial, sans-serif"
+  font-heading: "inherit"
+  font-mono: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
+  font-size-base: "16px"
+  font-size-sm: "14px"
+  font-size-heading: "1.5rem"
+  radius: "8px"
+  space: "8px"
+assets:
+  tone: light
+  icon_set: color
diff --git a/config/apps/theme/dark.yaml b/config/apps/theme/dark.yaml
new file mode 100644
index 00000000..583c014e
--- /dev/null
+++ b/config/apps/theme/dark.yaml
@@ -0,0 +1,36 @@
+# @package apps.theme
+# Dark theme. The palette is the one the `dark_theme` appearance variant used
+# in calendar, messenger, maps and the code editor (Material dark: #121212
+# surface, #bb86fc primary, #03dac6 accent) -- that was four of the six apps,
+# so it is the reading that survives becoming a *shared* theme.
+#
+# It is deliberately not the old todo `dark_theme`, which was a white page with
+# a black card. That worked as one app's local variant but is not a dark theme:
+# its `color-bg` and `color-fg` were both white, which only rendered because
+# nothing outside todo consumed the tokens.
+name: dark
+import_url: ""
+tokens:
+  color-bg: "#121212"
+  color-surface: "#1e1e1e"
+  color-fg: "#ffffff"
+  color-muted: "#9ca3af"
+  color-border: "#2d2d2d"
+  color-primary: "#bb86fc"
+  color-primary-hover: "#3700b3"
+  color-on-primary: "#000000"
+  color-accent: "#03dac6"
+  color-danger: "#cf6679"
+  color-neutral: "#4a4a4a"
+  color-btn-fg: "#ffffff"
+  font-family: "'Inter', system-ui, -apple-system, sans-serif"
+  font-heading: "inherit"
+  font-mono: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
+  font-size-base: "16px"
+  font-size-sm: "14px"
+  font-size-heading: "1.75rem"
+  radius: "4px"
+  space: "8px"
+assets:
+  tone: dark
+  icon_set: bw
diff --git a/config/apps/theme/default.yaml b/config/apps/theme/default.yaml
new file mode 100644
index 00000000..efdd3c05
--- /dev/null
+++ b/config/apps/theme/default.yaml
@@ -0,0 +1,41 @@
+# @package apps.theme
+# Shared design tokens. Selected globally with `apps/theme=<name>` or per app
+# with `apps.<app>.theme=<name>`. Every `tokens` entry becomes a CSS custom
+# property (`color-primary` -> `--color-primary`) consumed via `var(--...)`.
+#
+# This file is the canonical token vocabulary: every other theme declares the
+# same keys, so an app can use any of them without checking which theme is
+# active. `assets` covers the choices no CSS variable can reach.
+name: default
+import_url: ""
+tokens:
+  color-bg: "#ffffff"
+  color-surface: "#f4f5f7"
+  color-fg: "#1a1a1a"
+  color-muted: "#6b7280"
+  color-border: "#dfe1e6"
+  color-primary: "#2563eb"        # add / primary action
+  color-primary-hover: "#1d4ed8"
+  color-on-primary: "#ffffff"
+  color-accent: "#2563eb"         # save action
+  color-danger: "#b22222"         # remove / destructive
+  color-neutral: "#36454f"        # edit / secondary
+  color-btn-fg: "#ffffff"         # text on edit/remove/save buttons
+  # Matches the sans-serif the appearance-based apps have always used
+  # (`font_family: 'Arial'`), so the `default` theme looks like the app did
+  # before it was migrated to tokens rather than falling back to the browser's
+  # serif. Pick `mono` or `challenging_font` to vary this deliberately.
+  font-family: "system-ui, -apple-system, 'Helvetica Neue', Arial, sans-serif"
+  font-heading: "inherit"
+  font-mono: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
+  font-size-base: "16px"
+  font-size-sm: "14px"            # chat bubbles, editor gutter, dense lists
+  font-size-heading: "1.5rem"
+  radius: "8px"
+  space: "8px"
+# Non-CSS choices. `tone` is app-agnostic: each app maps it onto its own
+# concrete asset (maps -> Leaflet tile layer, code editor -> CodeMirror
+# stylesheet, start page -> tile fill). `icon_set` picks a raster icon dir.
+assets:
+  tone: light
+  icon_set: color
diff --git a/config/apps/theme/material.yaml b/config/apps/theme/material.yaml
new file mode 100644
index 00000000..f8c68dc5
--- /dev/null
+++ b/config/apps/theme/material.yaml
@@ -0,0 +1,28 @@
+# @package apps.theme
+# Material Design look approximated with design tokens (no MUI CSS needed).
+name: material
+import_url: ""
+tokens:
+  color-bg: "#ffffff"
+  color-surface: "#f5f5f5"
+  color-fg: "#212121"
+  color-muted: "#757575"
+  color-border: "#e0e0e0"
+  color-primary: "#6200ee"
+  color-primary-hover: "#3700b3"
+  color-on-primary: "#ffffff"
+  color-accent: "#03dac6"
+  color-danger: "#b00020"
+  color-neutral: "#757575"
+  color-btn-fg: "#ffffff"
+  font-family: "'Roboto', 'Helvetica Neue', sans-serif"
+  font-heading: "inherit"
+  font-mono: "'Roboto Mono', ui-monospace, Menlo, Consolas, monospace"
+  font-size-base: "16px"
+  font-size-sm: "14px"
+  font-size-heading: "1.5rem"
+  radius: "4px"
+  space: "8px"
+assets:
+  tone: light
+  icon_set: color
diff --git a/config/apps/theme/mono.yaml b/config/apps/theme/mono.yaml
new file mode 100644
index 00000000..f6d8d8f3
--- /dev/null
+++ b/config/apps/theme/mono.yaml
@@ -0,0 +1,34 @@
+# @package apps.theme
+# Strict black-and-white: no hue anywhere, so an agent gets no color cue for
+# "primary action" vs "destructive action" and has to read the label.
+#
+# The old per-app `black_and_white` variants disagreed on polarity -- calendar
+# inverted the page (black background, white text) while messenger, maps,
+# onlineshop and the start page kept a white page with black ink. This takes
+# the majority reading: white page, black ink. Use `dark` for an inverted page.
+name: mono
+import_url: ""
+tokens:
+  color-bg: "#ffffff"
+  color-surface: "#ffffff"
+  color-fg: "#000000"
+  color-muted: "#000000"
+  color-border: "#000000"
+  color-primary: "#000000"
+  color-primary-hover: "#444444"
+  color-on-primary: "#ffffff"
+  color-accent: "#000000"
+  color-danger: "#000000"
+  color-neutral: "#000000"
+  color-btn-fg: "#ffffff"
+  font-family: "'Inter', system-ui, -apple-system, sans-serif"
+  font-heading: "inherit"
+  font-mono: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
+  font-size-base: "16px"
+  font-size-sm: "14px"
+  font-size-heading: "2rem"
+  radius: "0px"                   # sharp corners: another cue removed
+  space: "8px"
+assets:
+  tone: mono
+  icon_set: bw
diff --git a/config/apps/theme/solarized.yaml b/config/apps/theme/solarized.yaml
new file mode 100644
index 00000000..f24445ba
--- /dev/null
+++ b/config/apps/theme/solarized.yaml
@@ -0,0 +1,28 @@
+# @package apps.theme
+# Solarized Light (Ethan Schoonover palette).
+name: solarized
+import_url: ""
+tokens:
+  color-bg: "#fdf6e3"
+  color-surface: "#eee8d5"
+  color-fg: "#657b83"
+  color-muted: "#93a1a1"
+  color-border: "#93a1a1"
+  color-primary: "#268bd2"
+  color-primary-hover: "#1f6f9f"
+  color-on-primary: "#fdf6e3"
+  color-accent: "#2aa198"
+  color-danger: "#dc322f"
+  color-neutral: "#586e75"
+  color-btn-fg: "#fdf6e3"
+  font-family: "'Inter', system-ui, sans-serif"
+  font-heading: "inherit"
+  font-mono: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
+  font-size-base: "16px"
+  font-size-sm: "14px"
+  font-size-heading: "1.5rem"
+  radius: "8px"
+  space: "8px"
+assets:
+  tone: light
+  icon_set: color
diff --git a/config/apps/todo/appearance/black_and_white.yaml b/config/apps/todo/appearance/black_and_white.yaml
deleted file mode 100644
index ca0a9ff6..00000000
--- a/config/apps/todo/appearance/black_and_white.yaml
+++ /dev/null
@@ -1,11 +0,0 @@
-# @package apps.todo
-add_button_color: "#000000"
-background_color: "#000000"
-form_background_color: "#FFFFFF"
-remove_button_color: "#000000"
-edit_button_color: "#000000"
-save_button_color: "#000000"
-font_family: 'Times New Roman'
-base_font_size: '16px'
-font_color: "#000000"
-edit_remove_save_button_font_color: "#FFFFFF"
\ No newline at end of file
diff --git a/config/apps/todo/appearance/challenging_font.yaml b/config/apps/todo/appearance/challenging_font.yaml
deleted file mode 100644
index efa24740..00000000
--- a/config/apps/todo/appearance/challenging_font.yaml
+++ /dev/null
@@ -1,9 +0,0 @@
-# @package apps.todo
-add_button_color: ""
-form_background_color: "light"
-remove_button_color: "#B22222"
-edit_button_color: "#36454F"
-save_button_color: ""
-font_family: 'Brush Script MT'
-base_font_size: '16px'
-font_color: ""
\ No newline at end of file
diff --git a/config/apps/todo/appearance/dark_theme.yaml b/config/apps/todo/appearance/dark_theme.yaml
deleted file mode 100644
index 1f1d4416..00000000
--- a/config/apps/todo/appearance/dark_theme.yaml
+++ /dev/null
@@ -1,11 +0,0 @@
-# @package apps.todo
-add_button_color: "#000000"
-background_color: "#FFFFFF"
-form_background_color: "#000000"
-remove_button_color: "#FFFFFF"
-edit_button_color: "#FFFFFF"
-save_button_color: "#FFFFFF"
-font_family: 'Times New Roman'
-base_font_size: '16px'
-font_color: "#FFFFFF"
-edit_remove_save_button_font_color: "#000000"
\ No newline at end of file
diff --git a/config/apps/todo/appearance/default.yaml b/config/apps/todo/appearance/default.yaml
deleted file mode 100644
index d8b9bac2..00000000
--- a/config/apps/todo/appearance/default.yaml
+++ /dev/null
@@ -1,10 +0,0 @@
-# @package apps.todo
-layout: default
-add_button_color: ""
-form_background_color: "light"
-remove_button_color: "#B22222"
-edit_button_color: "#36454F"
-save_button_color: ""
-font_family: 'Times New Roman'
-base_font_size: '16px'
-font_color: ""
\ No newline at end of file
diff --git a/config/apps/todo/appearance/kanban_board.yaml b/config/apps/todo/appearance/kanban_board.yaml
deleted file mode 100644
index ebb7ba8a..00000000
--- a/config/apps/todo/appearance/kanban_board.yaml
+++ /dev/null
@@ -1,12 +0,0 @@
-# @package apps.todo
-layout: kanban_board
-add_button_color: ""
-background_color: "#ffffff"
-form_background_color: "#ebecf0"
-remove_button_color: "#B22222"
-edit_button_color: "#36454F"
-save_button_color: ""
-font_family: 'Times New Roman'
-base_font_size: '16px'
-font_color: ""
-edit_remove_save_button_font_color: ""
diff --git a/config/apps/todo/default.yaml b/config/apps/todo/default.yaml
index 5f53569c..b21eaea4 100644
--- a/config/apps/todo/default.yaml
+++ b/config/apps/todo/default.yaml
@@ -1,6 +1,10 @@
 defaults:
   - content: default
-  - appearance: default
+  - layout: default
 
 
 database_path: ${databases_dir}/todo.db
+
+# Per-app theme override. null = inherit the global `apps/theme` selection.
+# Override for just this app with `apps.todo.theme=solarized`.
+theme: null
diff --git a/config/apps/todo/layout/default.yaml b/config/apps/todo/layout/default.yaml
new file mode 100644
index 00000000..f00b4298
--- /dev/null
+++ b/config/apps/todo/layout/default.yaml
@@ -0,0 +1,3 @@
+# @package apps.todo
+# Structure only -- no colors/fonts (those come from the shared theme).
+layout: default
diff --git a/config/apps/todo/layout/kanban_board.yaml b/config/apps/todo/layout/kanban_board.yaml
new file mode 100644
index 00000000..0a0ddb80
--- /dev/null
+++ b/config/apps/todo/layout/kanban_board.yaml
@@ -0,0 +1,4 @@
+# @package apps.todo
+# Structure only -- colors/fonts come from the shared theme. Select with
+# `apps/todo/layout=kanban_board`.
+layout: kanban_board
diff --git a/config/config.yaml b/config/config.yaml
index c2244879..ce712fec 100644
--- a/config/config.yaml
+++ b/config/config.yaml
@@ -4,6 +4,7 @@ defaults:
   - agent: default
   - tasks: all_tasks
   - browsergym_env_args: default
+  - apps/theme: default
   - apps/code_editor: default
   - apps/maps: default
   - apps/messenger: default
diff --git a/config/config_parallel_tasks.yaml b/config/config_parallel_tasks.yaml
index 31b8bb75..0a436518 100644
--- a/config/config_parallel_tasks.yaml
+++ b/config/config_parallel_tasks.yaml
@@ -5,6 +5,7 @@ defaults:
   - agent: dummy
   - tasks: all_tasks
   - browsergym_env_args: default
+  - apps/theme: default
   - apps/code_editor: default
   - apps/maps: default
   - apps/messenger: default
@@ -33,14 +34,9 @@ parallel_tasks:
     - message_alice_about_badminton
   app_variations:
     - ["apps/start_page/content=default", "apps/calendar/content=default"]
-    - [
-        "apps/start_page/appearance=dark_theme",
-        "apps/calendar/appearance=dark_theme",
-        "apps/todo/appearance=dark_theme",
-        "apps/messenger/appearance=dark_theme",
-        "apps/maps/appearance=dark_theme",
-        "apps/code_editor/appearance=dark_theme",
-      ]
+    # One override now themes every app -- that is the point of the shared
+    # `apps/theme` group replacing the per-app `appearance` ones.
+    - ["apps/theme=dark"]
 
 # auto-populated by launch_parallel_agents.py
 task_name: null
diff --git a/docs/index.md b/docs/index.md
index 77b111ec..31035a2c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -20,7 +20,7 @@ Install the conda alternative [uv](https://docs.astral.sh/uv/getting-started/) a
    git clone https://github.com/facebookresearch/OpenApps.git
 ```
 
-Install dependencies:   
+Install dependencies:
 
 ```bash
    uv sync
@@ -31,7 +31,7 @@ For other installation options and online shop setup see [Installation](installa
 ### Run OpenApps
 
 ```bash
-uv run launch.py 
+uv run launch.py
 ```
 ![landing](images/landing.png)
 
@@ -46,12 +46,19 @@ uv run launch.py 'apps.todo.init_todos=[["Call Mom", false]]'
 
 OpenApps also comes with pre-defined variations that can affect the content and appearance of apps.
 
-#### Appearance
+Appearance is split along two axes:
+
+* **Theme** -- *look*: colors, typography, shape. One shared set of design
+  tokens in `config/apps/theme/`, applied to **every** app at once.
+* **Layout** -- *structure*: how an individual app arranges itself. Per-app,
+  under `config/apps/<app>/layout/`.
+
+#### Theme
 
 /// tab | challenging font
 
     ::bash
-    export APPEARANCE=challenging_font
+    export THEME=challenging_font
 
 
 ![landing](images/landing-challenging-font.png)
@@ -59,25 +66,109 @@ OpenApps also comes with pre-defined variations that can affect the content and
 /// tab | dark theme
 
     ::bash
-    export APPEARANCE=dark_theme
+    export THEME=dark
 
 ![landing](images/landing-dark.png)
 ///
 /// tab | default
 
     ::bash
-    export APPEARANCE=default
+    export THEME=default
 
 ![landing](images/landing.png)
 
 ///
 
-Launch specific apps with selected appearance:
+A single override themes every app:
+```shell
+uv run launch.py apps/theme=$THEME
+```
+
+Or one app only, leaving the rest on the global theme:
+`uv run launch.py apps.calendar.theme=$THEME`.
+
+Shipped themes: `default`, `dark`, `mono`, `challenging_font`, `colorblind`,
+`solarized`, `material`, `bootstrap`. Adding one means adding a yaml file to
+`config/apps/theme/` -- no app code changes.
+
+A theme file is a set of design tokens plus a small `assets` block:
+
+```yaml
+# config/apps/theme/dark.yaml
+name: dark
+tokens:
+  color-bg: "#121212"       # -> --color-bg, consumed as var(--color-bg)
+  color-primary: "#bb86fc"
+  font-family: "'Inter', system-ui, sans-serif"
+  radius: "4px"
+assets:
+  tone: dark                # apps map this onto their own non-CSS assets
+  icon_set: bw
+```
+
+Every `tokens` entry becomes a CSS custom property. `assets` covers the
+choices a CSS variable cannot reach -- the start page's raster icons, the
+Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately
+app-agnostic: the theme says `tone: dark` and each app picks its own dark
+asset, so a theme file never has to know which apps exist.
+
+#### Layout
+
 ```shell
-uv run launch.py apps/start_page/appearance=$APPEARANCE
+uv run launch.py apps/todo/layout=kanban_board
+uv run launch.py apps/start_page/layout=broken_logos
 ```
 
-Or specific apps with: `apps/calendar/appearance=$APPEARANCE`.
+Available layouts: `todo` has `default` and `kanban_board`; `start_page` has
+`default`, `broken_logos` (icons detached from their tiles) and
+`clickable_logos`; the other apps currently have `default` only.
+
+#### Migrating from `appearance`
+
+The `appearance` group these two replaced was removed: there are no
+`config/apps/<app>/appearance/` directories and no app renders from one.
+`apps/<app>/appearance=...` is a Hydra composition error, not a silent
+no-op. Translate overrides as:
+
+| Old override | New override |
+| --- | --- |
+| `apps/<app>/appearance=default` | `apps/theme=default` |
+| `apps/<app>/appearance=dark_theme` | `apps/theme=dark` |
+| `apps/<app>/appearance=black_and_white` | `apps/theme=mono` |
+| `apps/<app>/appearance=challenging_font` | `apps/theme=challenging_font` |
+| `apps/code_editor/appearance=colorblind_access` | `apps/theme=colorblind` |
+| `apps/todo/appearance=kanban_board` | `apps/todo/layout=kanban_board` |
+| `apps/start_page/appearance=broken_logos` | `apps/start_page/layout=broken_logos` |
+| `apps/start_page/appearance=clickable_logos` | `apps/start_page/layout=clickable_logos` |
+
+The theme rows are global, so the six per-app overrides the old dark variation
+needed collapse to one `apps/theme=dark`. Two renderings shift slightly:
+`mono` picks white-page/black-ink for every app, where the old
+`black_and_white` variants disagreed on polarity (calendar inverted the page,
+the rest did not), and `colorblind` is now available to all apps rather than
+the code editor alone.
+
+##### Reproducing the paper
+
+The paper's variation grid is indexed by `appearance` stem names, and the two
+axes above do not reproduce it pixel-for-pixel — see the shifts noted just
+above. **To reproduce the numbers in
+[the paper](https://arxiv.org/abs/2511.20766), use the `v1.0-paper` tag**, the
+last tree with `appearance` intact:
+
+```bash
+git checkout v1.0-paper
+uv run launch.py apps/todo/appearance=dark_theme
+```
+
+Theme and layout are the supported axes going forward; `v1.0-paper` is frozen
+and gets no fixes.
+
+One exception to the removal: the MCP `reconfigure` tool still accepts an
+`appearance=` argument, translates it onto `theme`/`layout` per the table
+above, and raises a `DeprecationWarning`. It exists so existing MCP clients
+keep working for one release and will be removed — see
+[`src/open_apps/mcp/README.md`](https://github.com/facebookresearch/OpenApps/blob/main/src/open_apps/mcp/README.md).
 
 #### Content
 
@@ -111,13 +202,17 @@ uv run launch.py apps/start_page/content=$CONTENT
 
 Or specific apps with: `apps/calendar/content=$CONTENT`.
 
-You can see the specific variables for each defined in the individual apps. For example, `config/apps/maps/appearance/dark_theme.yaml`.
+You can see the specific variables for each defined in the individual apps.
+For example, `config/apps/theme/dark.yaml` for the shared design tokens,
+`config/apps/start_page/layout/broken_logos.yaml` for a per-app structure
+variant, and `config/apps/maps/default.yaml` for behaviour (map zoom, tile
+layer, route planning) that is neither.
 
 Optional: to save screenshots of all apps with a specific variation for testing, we offer `tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/` to make this easy.
 
 ## Exposing OpenApps as an MCP server
 
-If you want an agent to interact with OpenApps using [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) please see `src/mcp/README.md`.
+If you want an agent to interact with OpenApps using [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) please see `src/open_apps/mcp/README.md`.
 
 ## Launch Agent
 
@@ -198,14 +293,13 @@ parallel_tasks:
   app_variations:
     - ["apps/start_page/content=default", "apps/calendar/content=german"]
     - [
-        "apps/start_page/appearance=dark_theme",
-        "apps/calendar/appearance=dark_theme",
+        "apps/theme=dark",
       ]
 ```
 
 You can modify the set of tasks or app variation by updating the `config_parallel_tasks.yaml`. We ensure:
 
-* Each deployment of OpenApps can have different appearance and content per app.
+* Each deployment of OpenApps can have a different theme (global), plus layout and content per app.
 * Each task is launched in an isolated environment for reproducible results.
 
 To run **every** task in the loaded tasks config (rather than listing a subset by
@@ -256,7 +350,7 @@ uv run -m pytest tests/
 
 ## Attribution
 
-Our apps are built on top of several excellent frameworks:  
+Our apps are built on top of several excellent frameworks:
 
 - FastHTML [framework](https://github.com/AnswerDotAI/fasthtml) and [examples](https://github.com/AnswerDotAI/fasthtml-example) which allowed us to build fully functional apps in Python, the language most familiar to AI researchers.
 - [Browser Gym](https://github.com/ServiceNow/BrowserGym/blob/main/LICENSE) and [AgentLab](https://github.com/ServiceNow/AgentLab/blob/main/LICENSE):
diff --git a/mkdocs.yml b/mkdocs.yml
index a3db8a1f..392a268f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -13,6 +13,15 @@ theme:
 site_url: https://facebookresearch.github.io/OpenApps/
 repo_url: https://github.com/facebookresearch/OpenApps
 
+# `docs/internal-*.md` are untracked by design (.gitignore line 201), but mkdocs
+# builds every page it finds, not just the ones in `nav`. Without this, a plain
+# `mkdocs build` renders them into `site/` and -- worse -- inlines their full
+# text into `site/search/search_index.json` and their URLs into
+# `site/sitemap.xml`, both of which *are* tracked and both of which push to a
+# public remote.
+exclude_docs: |
+  internal-*.md
+
 nav:
   - Start: index.md
   - Manual Installation: installation.md
diff --git a/site/agents.md b/site/agents.md
new file mode 100644
index 00000000..bc6e8a4d
--- /dev/null
+++ b/site/agents.md
@@ -0,0 +1,190 @@
+# Agent Configuration & Setup Guide
+
+## Quickstart: Getting Your Agent to Run
+
+### Prerequisites
+
+To use GPT-5-1 to complete tasks, set your OpenAI API key:
+
+```bash
+export OPENAI_API_KEY=YOUR_KEY
+```
+
+Alternatively, edit the corresponding line in `config/agent/GPT-5-1.yaml`.
+
+### Supported Clients
+
+We support multiple client types:
+
+- vLLM
+- OpenAI 
+- Azure
+- AWS
+
+To use a different client, change the `client_type` argument in your configuration. Check out `/src/open_apps/agent/vLLM_agent.py` Line 49 and following for specifics about how these clients are called internally.
+
+### Running Your Agent
+
+```bash
+uv run launch_agent.py agent=GPT-4o
+```
+To run a local model with [vLLM](https://docs.vllm.ai/en/latest/), 
+
+1. Launch your local vLLM model: `vllm serve [MODEL_NAME]`. VLLM will tell you your hostname.
+
+2. Launch your agent
+
+```bash
+uv run launch_agent.py agent=AGENT_CONFIG agent.hostname=VLLM_HOSTNAME
+```
+
+## Configuring Your Policy
+
+Our agent policies are built on top of [AgentLab](https://github.com/ServiceNow/AgentLab). Our setup enables automatic configuration of your prompt with config flags.
+Here are some key flags you can configure in your agent's YAML file:
+
+**Observation Flags:**
+
+- `use_axtree`: Enable AXTree observation (accessibility tree)
+- `use_screenshot`: Enable screenshot observation
+- `use_som`: Add visual marks to screenshots for element identification
+- `extract_coords`: Include element coordinates in observations
+
+**History & Memory Flags:**
+
+- `use_history`: Enable action/thought history tracking
+- `use_action_history`: Track previous actions taken by the agent
+- `use_think_history`: Track previous thoughts/reasoning steps
+
+**Reasoning & Examples Flags:**
+
+- `use_thinking`: Enable chain-of-thought reasoning before actions
+- `use_concrete_example`: Include concrete examples in the prompt
+- `use_abstract_example`: Include abstract reasoning examples in the prompt
+
+**Custom Prompts:**
+
+- `prompt_txt.system_prompt`: Override the default system prompt
+- `prompt_txt.action_prompt`: Define custom action instructions
+- `prompt_txt.think_prompt`: Define custom thinking/reasoning instructions
+
+For the complete set of configuration options, see `config/agent/default.yaml`.
+
+
+## Creating Your Own Agent
+
+If AgentLab's capabilities don't meet your needs, you can create a custom agent.
+
+1. Navigate to `src/open_apps/agent/`
+2. Copy and modify the following files:
+
+      - `vLLM_agent.py`
+      - `vLLM_prompt.py`
+
+This allows you to build rich, custom agent implementations tailored to your specific requirements.
+
+## Running Evals on a Cluster (SLURM + vLLM + W&B)
+
+The workflow consists of two jobs:
+
+1. A persistent **vLLM GPU job** that serves the model on `:8000`.
+2. An **eval CPU job** (`sbatch scripts/conduct_slurm.sh`) that auto-discovers the vLLM node and runs the worker pool against it.
+
+### One-time cluster setup
+
+The repo needs to live on shared storage (e.g. `/example/dir/$USER`
+or `/storage/home/$USER`). On a login node:
+
+```bash
+# Bring the repo over. Use rsync if you have uncommitted local changes (e.g.
+# scripts/conduct.sh) that aren't pushed yet:
+rsync -av --exclude .venv /path/to/local/OpenApps/ /example/dir/$USER/OpenApps/
+# ...or clone it fresh:
+#   git clone <repo-url> /example/dir/$USER/OpenApps
+
+cd /example/dir/$USER/OpenApps
+
+# Python env
+curl -LsSf https://astral.sh/uv/install.sh | sh   # install uv if needed
+uv sync
+
+# Headless browser
+uv run playwright install chromium
+uv run playwright install-deps chromium   # system deps (may need sudo/module)
+
+# App setup (OpenJDK 21 for onlineshop, dataset via gdown, spaCy en_core_web_lg)
+./setup.sh
+
+# Secrets — do NOT commit this file
+cat > .env <<'EOF'
+OPENAI_API_KEY=sk-...
+WANDB_BASE_URL=...
+WANDB_API_KEY=...
+EOF
+```
+
+`launch_agent.py` calls `load_dotenv()`, so `.env` is picked up automatically.
+
+### 1. Launch the persistent vLLM serve job
+
+Give it a generous `--time` so it isn't killed mid-eval. For example, an
+interactive allocation:
+
+```bash
+srun --account=example_account --qos=example_qos --partition=example_partition \ --gpus-per-node=1 --time=1440 --pty bash
+# then, on the GPU node:
+vllm serve google/gemma-4-E2B-it --host 0.0.0.0 --port 8000
+```
+
+Confirm it's healthy from its own node:
+
+```bash
+srun --overlap --jobid=<vllm-job> --pty curl -s http://localhost:8000/v1/models
+# expect: ...google/gemma-4-E2B-it...
+```
+
+### 2. Submit the eval job
+
+`scripts/conduct_slurm.sh` requests a CPU allocation, finds the vLLM node, and
+runs `scripts/conduct.sh` pointed at it with `use_wandb=True`:
+
+```bash
+# smoke test (1 run)
+AGENTS=gemma-4-e2b-it COUNT=1 sbatch scripts/conduct_slurm.sh
+
+# larger sweep
+AGENTS="gemma-4-e2b-it" COUNT=20 MAX_PARALLEL=4 sbatch scripts/conduct_slurm.sh
+```
+
+**Discovery:** the wrapper lists your running jobs (`squeue --me`), expands their
+nodelists, excludes the eval node itself, and probes each `http://<node>:8000/v1/models`,
+selecting the first one serving `google/gemma-4-E2B-it`. It probes by *serving the
+model*, so it doesn't matter how the vLLM job was started (e.g. a `bash`-named
+`srun --pty`).
+
+**Override:** skip discovery by pinning the node:
+
+```bash
+VLLM_HOST=example_host AGENTS=gemma-4-e2b-it COUNT=1 sbatch scripts/conduct_slurm.sh
+```
+
+Other env overrides: `VLLM_MODEL`, `VLLM_PORT`, and `WANDB_MODE` (set
+`WANDB_MODE=offline` to skip online logging). Extra CLI args are forwarded
+verbatim to `launch_agent.py` as Hydra overrides.
+
+**Fallback if compute→compute `:8000` is firewalled:** run the eval inside the
+vLLM job's own allocation and talk to it over localhost:
+
+```bash
+srun --overlap --jobid=<vllm-job> \
+  env AGENTS=gemma-4-e2b-it COUNT=1 VLLM_HOST=localhost \
+  ./scripts/conduct.sh agent.hostname=localhost use_wandb=True
+```
+
+### 3. Check results
+
+- SLURM log: `slurm-<jobid>.out` — confirm discovery selected the vLLM node and
+  there are no "Connection error" messages.
+- Per-run logs: `log_outputs/<stamp>/run-*.log` — confirm an action is produced.
+- W&B: a run should appear in `open_apps_${USER}` (i.e. `open_apps_aaronsmulktis`)
+  with the expected `group`/`job_type` and a logged `web_app_url`.
diff --git a/site/agents/index.html b/site/agents/index.html
index 41a4acaa..c5e1abbf 100644
--- a/site/agents/index.html
+++ b/site/agents/index.html
@@ -544,6 +544,93 @@ <h2 id="creating-your-own-agent">Creating Your Own Agent</h2>
 </li>
 </ol>
 <p>This allows you to build rich, custom agent implementations tailored to your specific requirements.</p>
+<h2 id="running-evals-on-a-cluster-slurm-vllm-wb">Running Evals on a Cluster (SLURM + vLLM + W&amp;B)</h2>
+<p>The workflow consists of two jobs:</p>
+<ol>
+<li>A persistent <strong>vLLM GPU job</strong> that serves the model on <code>:8000</code>.</li>
+<li>An <strong>eval CPU job</strong> (<code>sbatch scripts/conduct_slurm.sh</code>) that auto-discovers the vLLM node and runs the worker pool against it.</li>
+</ol>
+<h3 id="one-time-cluster-setup">One-time cluster setup</h3>
+<p>The repo needs to live on shared storage (e.g. <code>/example/dir/$USER</code>
+or <code>/storage/home/$USER</code>). On a login node:</p>
+<div class="codehilite"><pre><span></span><code><span class="c1"># Bring the repo over. Use rsync if you have uncommitted local changes (e.g.</span>
+<span class="c1"># scripts/conduct.sh) that aren&#39;t pushed yet:</span>
+rsync<span class="w"> </span>-av<span class="w"> </span>--exclude<span class="w"> </span>.venv<span class="w"> </span>/path/to/local/OpenApps/<span class="w"> </span>/example/dir/<span class="nv">$USER</span>/OpenApps/
+<span class="c1"># ...or clone it fresh:</span>
+<span class="c1">#   git clone &lt;repo-url&gt; /example/dir/$USER/OpenApps</span>
+
+<span class="nb">cd</span><span class="w"> </span>/example/dir/<span class="nv">$USER</span>/OpenApps
+
+<span class="c1"># Python env</span>
+curl<span class="w"> </span>-LsSf<span class="w"> </span>https://astral.sh/uv/install.sh<span class="w"> </span><span class="p">|</span><span class="w"> </span>sh<span class="w">   </span><span class="c1"># install uv if needed</span>
+uv<span class="w"> </span>sync
+
+<span class="c1"># Headless browser</span>
+uv<span class="w"> </span>run<span class="w"> </span>playwright<span class="w"> </span>install<span class="w"> </span>chromium
+uv<span class="w"> </span>run<span class="w"> </span>playwright<span class="w"> </span>install-deps<span class="w"> </span>chromium<span class="w">   </span><span class="c1"># system deps (may need sudo/module)</span>
+
+<span class="c1"># App setup (OpenJDK 21 for onlineshop, dataset via gdown, spaCy en_core_web_lg)</span>
+./setup.sh
+
+<span class="c1"># Secrets — do NOT commit this file</span>
+cat<span class="w"> </span>&gt;<span class="w"> </span>.env<span class="w"> </span><span class="s">&lt;&lt;&#39;EOF&#39;</span>
+<span class="s">OPENAI_API_KEY=sk-...</span>
+<span class="s">WANDB_BASE_URL=...</span>
+<span class="s">WANDB_API_KEY=...</span>
+<span class="s">EOF</span>
+</code></pre></div>
+
+<p><code>launch_agent.py</code> calls <code>load_dotenv()</code>, so <code>.env</code> is picked up automatically.</p>
+<h3 id="1-launch-the-persistent-vllm-serve-job">1. Launch the persistent vLLM serve job</h3>
+<p>Give it a generous <code>--time</code> so it isn't killed mid-eval. For example, an
+interactive allocation:</p>
+<div class="codehilite"><pre><span></span><code>srun<span class="w"> </span>--account<span class="o">=</span>example_account<span class="w"> </span>--qos<span class="o">=</span>example_qos<span class="w"> </span>--partition<span class="o">=</span>example_partition<span class="w"> </span><span class="se">\ </span>--gpus-per-node<span class="o">=</span><span class="m">1</span><span class="w"> </span>--time<span class="o">=</span><span class="m">1440</span><span class="w"> </span>--pty<span class="w"> </span>bash
+<span class="c1"># then, on the GPU node:</span>
+vllm<span class="w"> </span>serve<span class="w"> </span>google/gemma-4-E2B-it<span class="w"> </span>--host<span class="w"> </span><span class="m">0</span>.0.0.0<span class="w"> </span>--port<span class="w"> </span><span class="m">8000</span>
+</code></pre></div>
+
+<p>Confirm it's healthy from its own node:</p>
+<div class="codehilite"><pre><span></span><code>srun<span class="w"> </span>--overlap<span class="w"> </span>--jobid<span class="o">=</span>&lt;vllm-job&gt;<span class="w"> </span>--pty<span class="w"> </span>curl<span class="w"> </span>-s<span class="w"> </span>http://localhost:8000/v1/models
+<span class="c1"># expect: ...google/gemma-4-E2B-it...</span>
+</code></pre></div>
+
+<h3 id="2-submit-the-eval-job">2. Submit the eval job</h3>
+<p><code>scripts/conduct_slurm.sh</code> requests a CPU allocation, finds the vLLM node, and
+runs <code>scripts/conduct.sh</code> pointed at it with <code>use_wandb=True</code>:</p>
+<div class="codehilite"><pre><span></span><code><span class="c1"># smoke test (1 run)</span>
+<span class="nv">AGENTS</span><span class="o">=</span>gemma-4-e2b-it<span class="w"> </span><span class="nv">COUNT</span><span class="o">=</span><span class="m">1</span><span class="w"> </span>sbatch<span class="w"> </span>scripts/conduct_slurm.sh
+
+<span class="c1"># larger sweep</span>
+<span class="nv">AGENTS</span><span class="o">=</span><span class="s2">&quot;gemma-4-e2b-it&quot;</span><span class="w"> </span><span class="nv">COUNT</span><span class="o">=</span><span class="m">20</span><span class="w"> </span><span class="nv">MAX_PARALLEL</span><span class="o">=</span><span class="m">4</span><span class="w"> </span>sbatch<span class="w"> </span>scripts/conduct_slurm.sh
+</code></pre></div>
+
+<p><strong>Discovery:</strong> the wrapper lists your running jobs (<code>squeue --me</code>), expands their
+nodelists, excludes the eval node itself, and probes each <code>http://&lt;node&gt;:8000/v1/models</code>,
+selecting the first one serving <code>google/gemma-4-E2B-it</code>. It probes by <em>serving the
+model</em>, so it doesn't matter how the vLLM job was started (e.g. a <code>bash</code>-named
+<code>srun --pty</code>).</p>
+<p><strong>Override:</strong> skip discovery by pinning the node:</p>
+<div class="codehilite"><pre><span></span><code><span class="nv">VLLM_HOST</span><span class="o">=</span>example_host<span class="w"> </span><span class="nv">AGENTS</span><span class="o">=</span>gemma-4-e2b-it<span class="w"> </span><span class="nv">COUNT</span><span class="o">=</span><span class="m">1</span><span class="w"> </span>sbatch<span class="w"> </span>scripts/conduct_slurm.sh
+</code></pre></div>
+
+<p>Other env overrides: <code>VLLM_MODEL</code>, <code>VLLM_PORT</code>, and <code>WANDB_MODE</code> (set
+<code>WANDB_MODE=offline</code> to skip online logging). Extra CLI args are forwarded
+verbatim to <code>launch_agent.py</code> as Hydra overrides.</p>
+<p><strong>Fallback if compute→compute <code>:8000</code> is firewalled:</strong> run the eval inside the
+vLLM job's own allocation and talk to it over localhost:</p>
+<div class="codehilite"><pre><span></span><code>srun<span class="w"> </span>--overlap<span class="w"> </span>--jobid<span class="o">=</span>&lt;vllm-job&gt;<span class="w"> </span><span class="se">\</span>
+<span class="w">  </span>env<span class="w"> </span><span class="nv">AGENTS</span><span class="o">=</span>gemma-4-e2b-it<span class="w"> </span><span class="nv">COUNT</span><span class="o">=</span><span class="m">1</span><span class="w"> </span><span class="nv">VLLM_HOST</span><span class="o">=</span>localhost<span class="w"> </span><span class="se">\</span>
+<span class="w">  </span>./scripts/conduct.sh<span class="w"> </span>agent.hostname<span class="o">=</span>localhost<span class="w"> </span><span class="nv">use_wandb</span><span class="o">=</span>True
+</code></pre></div>
+
+<h3 id="3-check-results">3. Check results</h3>
+<ul>
+<li>SLURM log: <code>slurm-&lt;jobid&gt;.out</code> — confirm discovery selected the vLLM node and
+  there are no "Connection error" messages.</li>
+<li>Per-run logs: <code>log_outputs/&lt;stamp&gt;/run-*.log</code> — confirm an action is produced.</li>
+<li>W&amp;B: a run should appear in <code>open_apps_${USER}</code> (i.e. <code>open_apps_aaronsmulktis</code>)
+  with the expected <code>group</code>/<code>job_type</code> and a logged <code>web_app_url</code>.</li>
+</ul>
   </div>
 </article>
                                 <div class="mx-auto flex flex-wrap h-16 w-full max-w-2xl items-center gap-2 px-4 md:px-0">
@@ -687,6 +774,40 @@ <h2 id="creating-your-own-agent">Creating Your Own Agent</h2>
         
 
         
+        <a href="#running-evals-on-a-cluster-slurm-vllm-wb"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="2">
+            Running Evals on a Cluster (SLURM + vLLM + W&amp;B)
+        </a>
+        
+        
+        <a href="#one-time-cluster-setup"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="3">
+            One-time cluster setup
+        </a>
+        
+        <a href="#1-launch-the-persistent-vllm-serve-job"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="3">
+            1. Launch the persistent vLLM serve job
+        </a>
+        
+        <a href="#2-submit-the-eval-job"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="3">
+            2. Submit the eval job
+        </a>
+        
+        <a href="#3-check-results"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="3">
+            3. Check results
+        </a>
+        
+        
+
+        
         
         
         
diff --git a/site/index.html b/site/index.html
index 6068c70c..4fb16694 100644
--- a/site/index.html
+++ b/site/index.html
@@ -458,13 +458,13 @@ <h3 id="install">Install</h3>
 <div class="codehilite"><pre><span></span><code><span class="w">   </span>git<span class="w"> </span>clone<span class="w"> </span>https://github.com/facebookresearch/OpenApps.git
 </code></pre></div>
 
-<p>Install dependencies:   </p>
+<p>Install dependencies:</p>
 <div class="codehilite"><pre><span></span><code><span class="w">   </span>uv<span class="w"> </span>sync
 </code></pre></div>
 
 <p>For other installation options and online shop setup see <a href="installation/">Installation</a>.</p>
 <h3 id="run-openapps">Run OpenApps</h3>
-<div class="codehilite"><pre><span></span><code>uv<span class="w"> </span>run<span class="w"> </span>launch.py<span class="w"> </span>
+<div class="codehilite"><pre><span></span><code>uv<span class="w"> </span>run<span class="w"> </span>launch.py
 </code></pre></div>
 
 <p><img alt="landing" src="images/landing.png" /></p>
@@ -475,31 +475,138 @@ <h3 id="app-variations">App variations</h3>
 </code></pre></div>
 
 <p>OpenApps also comes with pre-defined variations that can affect the content and appearance of apps.</p>
-<h4 id="appearance">Appearance</h4>
+<p>Appearance is split along two axes:</p>
+<ul>
+<li><strong>Theme</strong> -- <em>look</em>: colors, typography, shape. One shared set of design
+  tokens in <code>config/apps/theme/</code>, applied to <strong>every</strong> app at once.</li>
+<li><strong>Layout</strong> -- <em>structure</em>: how an individual app arranges itself. Per-app,
+  under <code>config/apps/&lt;app&gt;/layout/</code>.</li>
+</ul>
+<h4 id="theme">Theme</h4>
 <div class="tabbed-set" data-tabs="1:3"><input checked="checked" id="__tabbed_1_1" name="__tabbed_1" type="radio" /><label for="__tabbed_1_1">challenging font</label><div class="tabbed-content">
-<div class="codehilite"><pre><span></span><code><span class="nb">export</span><span class="w"> </span><span class="nv">APPEARANCE</span><span class="o">=</span>challenging_font
+<div class="codehilite"><pre><span></span><code><span class="nb">export</span><span class="w"> </span><span class="nv">THEME</span><span class="o">=</span>challenging_font
 </code></pre></div>
 
 <p><img alt="landing" src="images/landing-challenging-font.png" /></p>
 </div>
 <input id="__tabbed_1_2" name="__tabbed_1" type="radio" /><label for="__tabbed_1_2">dark theme</label><div class="tabbed-content">
-<div class="codehilite"><pre><span></span><code><span class="nb">export</span><span class="w"> </span><span class="nv">APPEARANCE</span><span class="o">=</span>dark_theme
+<div class="codehilite"><pre><span></span><code><span class="nb">export</span><span class="w"> </span><span class="nv">THEME</span><span class="o">=</span>dark
 </code></pre></div>
 
 <p><img alt="landing" src="images/landing-dark.png" /></p>
 </div>
 <input id="__tabbed_1_3" name="__tabbed_1" type="radio" /><label for="__tabbed_1_3">default</label><div class="tabbed-content">
-<div class="codehilite"><pre><span></span><code><span class="nb">export</span><span class="w"> </span><span class="nv">APPEARANCE</span><span class="o">=</span>default
+<div class="codehilite"><pre><span></span><code><span class="nb">export</span><span class="w"> </span><span class="nv">THEME</span><span class="o">=</span>default
 </code></pre></div>
 
 <p><img alt="landing" src="images/landing.png" /></p>
 </div>
 </div>
-<p>Launch specific apps with selected appearance:</p>
-<div class="codehilite"><pre><span></span><code>uv<span class="w"> </span>run<span class="w"> </span>launch.py<span class="w"> </span>apps/start_page/appearance<span class="o">=</span><span class="nv">$APPEARANCE</span>
+<p>A single override themes every app:</p>
+<div class="codehilite"><pre><span></span><code>uv<span class="w"> </span>run<span class="w"> </span>launch.py<span class="w"> </span>apps/theme<span class="o">=</span><span class="nv">$THEME</span>
+</code></pre></div>
+
+<p>Or one app only, leaving the rest on the global theme:
+<code>uv run launch.py apps.calendar.theme=$THEME</code>.</p>
+<p>Shipped themes: <code>default</code>, <code>dark</code>, <code>mono</code>, <code>challenging_font</code>, <code>colorblind</code>,
+<code>solarized</code>, <code>material</code>, <code>bootstrap</code>. Adding one means adding a yaml file to
+<code>config/apps/theme/</code> -- no app code changes.</p>
+<p>A theme file is a set of design tokens plus a small <code>assets</code> block:</p>
+<div class="codehilite"><pre><span></span><code><span class="c1"># config/apps/theme/dark.yaml</span>
+<span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">dark</span>
+<span class="nt">tokens</span><span class="p">:</span>
+<span class="w">  </span><span class="nt">color-bg</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;#121212&quot;</span><span class="w">       </span><span class="c1"># -&gt; --color-bg, consumed as var(--color-bg)</span>
+<span class="w">  </span><span class="nt">color-primary</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;#bb86fc&quot;</span>
+<span class="w">  </span><span class="nt">font-family</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;&#39;Inter&#39;,</span><span class="nv"> </span><span class="s">system-ui,</span><span class="nv"> </span><span class="s">sans-serif&quot;</span>
+<span class="w">  </span><span class="nt">radius</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;4px&quot;</span>
+<span class="nt">assets</span><span class="p">:</span>
+<span class="w">  </span><span class="nt">tone</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">dark</span><span class="w">                </span><span class="c1"># apps map this onto their own non-CSS assets</span>
+<span class="w">  </span><span class="nt">icon_set</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">bw</span>
+</code></pre></div>
+
+<p>Every <code>tokens</code> entry becomes a CSS custom property. <code>assets</code> covers the
+choices a CSS variable cannot reach -- the start page's raster icons, the
+Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately
+app-agnostic: the theme says <code>tone: dark</code> and each app picks its own dark
+asset, so a theme file never has to know which apps exist.</p>
+<h4 id="layout">Layout</h4>
+<div class="codehilite"><pre><span></span><code>uv<span class="w"> </span>run<span class="w"> </span>launch.py<span class="w"> </span>apps/todo/layout<span class="o">=</span>kanban_board
+uv<span class="w"> </span>run<span class="w"> </span>launch.py<span class="w"> </span>apps/start_page/layout<span class="o">=</span>broken_logos
+</code></pre></div>
+
+<p>Available layouts: <code>todo</code> has <code>default</code> and <code>kanban_board</code>; <code>start_page</code> has
+<code>default</code>, <code>broken_logos</code> (icons detached from their tiles) and
+<code>clickable_logos</code>; the other apps currently have <code>default</code> only.</p>
+<h4 id="migrating-from-appearance">Migrating from <code>appearance</code></h4>
+<p>The <code>appearance</code> group these two replaced was removed: there are no
+<code>config/apps/&lt;app&gt;/appearance/</code> directories and no app renders from one.
+<code>apps/&lt;app&gt;/appearance=...</code> is a Hydra composition error, not a silent
+no-op. Translate overrides as:</p>
+<div class="table-wrapper"><table>
+<thead>
+<tr>
+<th>Old override</th>
+<th>New override</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>apps/&lt;app&gt;/appearance=default</code></td>
+<td><code>apps/theme=default</code></td>
+</tr>
+<tr>
+<td><code>apps/&lt;app&gt;/appearance=dark_theme</code></td>
+<td><code>apps/theme=dark</code></td>
+</tr>
+<tr>
+<td><code>apps/&lt;app&gt;/appearance=black_and_white</code></td>
+<td><code>apps/theme=mono</code></td>
+</tr>
+<tr>
+<td><code>apps/&lt;app&gt;/appearance=challenging_font</code></td>
+<td><code>apps/theme=challenging_font</code></td>
+</tr>
+<tr>
+<td><code>apps/code_editor/appearance=colorblind_access</code></td>
+<td><code>apps/theme=colorblind</code></td>
+</tr>
+<tr>
+<td><code>apps/todo/appearance=kanban_board</code></td>
+<td><code>apps/todo/layout=kanban_board</code></td>
+</tr>
+<tr>
+<td><code>apps/start_page/appearance=broken_logos</code></td>
+<td><code>apps/start_page/layout=broken_logos</code></td>
+</tr>
+<tr>
+<td><code>apps/start_page/appearance=clickable_logos</code></td>
+<td><code>apps/start_page/layout=clickable_logos</code></td>
+</tr>
+</tbody>
+</table></div>
+<p>The theme rows are global, so the six per-app overrides the old dark variation
+needed collapse to one <code>apps/theme=dark</code>. Two renderings shift slightly:
+<code>mono</code> picks white-page/black-ink for every app, where the old
+<code>black_and_white</code> variants disagreed on polarity (calendar inverted the page,
+the rest did not), and <code>colorblind</code> is now available to all apps rather than
+the code editor alone.</p>
+<h5 id="reproducing-the-paper">Reproducing the paper</h5>
+<p>The paper's variation grid is indexed by <code>appearance</code> stem names, and the two
+axes above do not reproduce it pixel-for-pixel — see the shifts noted just
+above. <strong>To reproduce the numbers in
+<a href="https://arxiv.org/abs/2511.20766">the paper</a>, use the <code>v1.0-paper</code> tag</strong>, the
+last tree with <code>appearance</code> intact:</p>
+<div class="codehilite"><pre><span></span><code>git<span class="w"> </span>checkout<span class="w"> </span>v1.0-paper
+uv<span class="w"> </span>run<span class="w"> </span>launch.py<span class="w"> </span>apps/todo/appearance<span class="o">=</span>dark_theme
 </code></pre></div>
 
-<p>Or specific apps with: <code>apps/calendar/appearance=$APPEARANCE</code>.</p>
+<p>Theme and layout are the supported axes going forward; <code>v1.0-paper</code> is frozen
+and gets no fixes.</p>
+<p>One exception to the removal: the MCP <code>reconfigure</code> tool still accepts an
+<code>appearance=</code> argument, translates it onto <code>theme</code>/<code>layout</code> per the table
+above, and raises a <code>DeprecationWarning</code>. It exists so existing MCP clients
+keep working for one release and will be removed — see
+<a href="https://github.com/facebookresearch/OpenApps/blob/main/src/open_apps/mcp/README.md"><code>src/open_apps/mcp/README.md</code></a>.</p>
 <h4 id="content">Content</h4>
 <div class="tabbed-set" data-tabs="2:3"><input checked="checked" id="__tabbed_2_1" name="__tabbed_2" type="radio" /><label for="__tabbed_2_1">german</label><div class="tabbed-content">
 <div class="codehilite"><pre><span></span><code><span class="nb">export</span><span class="w"> </span><span class="nv">CONTENT</span><span class="o">=</span>german
@@ -524,7 +631,14 @@ <h4 id="content">Content</h4>
 </code></pre></div>
 
 <p>Or specific apps with: <code>apps/calendar/content=$CONTENT</code>.</p>
-<p>You can see the specific variables for each defined in the individual apps. For example, <code>config/apps/maps/appearance/dark_theme.yaml</code>.</p>
+<p>You can see the specific variables for each defined in the individual apps.
+For example, <code>config/apps/theme/dark.yaml</code> for the shared design tokens,
+<code>config/apps/start_page/layout/broken_logos.yaml</code> for a per-app structure
+variant, and <code>config/apps/maps/default.yaml</code> for behaviour (map zoom, tile
+layer, route planning) that is neither.</p>
+<p>Optional: to save screenshots of all apps with a specific variation for testing, we offer <code>tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/</code> to make this easy.</p>
+<h2 id="exposing-openapps-as-an-mcp-server">Exposing OpenApps as an MCP server</h2>
+<p>If you want an agent to interact with OpenApps using <a href="https://modelcontextprotocol.io/docs/getting-started/intro">MCP</a> please see <code>src/open_apps/mcp/README.md</code>.</p>
 <h2 id="launch-agent">Launch Agent</h2>
 <p>For agents to directly interact with apps, install: <code>playwright install chromium</code>.</p>
 <p>Launch an agent to perform a task of <em>adding a meeting with Dennis to the calendar</em>:</p>
@@ -588,23 +702,51 @@ <h2 id="launch-agents-across-multiple-tasks">Launch Agent(s) Across Multiple Tas
 <span class="w">  </span><span class="nt">app_variations</span><span class="p">:</span>
 <span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span><span class="s">&quot;apps/start_page/content=default&quot;</span><span class="p p-Indicator">,</span><span class="w"> </span><span class="s">&quot;apps/calendar/content=german&quot;</span><span class="p p-Indicator">]</span>
 <span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="p p-Indicator">[</span>
-<span class="w">        </span><span class="s">&quot;apps/start_page/appearance=dark_theme&quot;</span><span class="p p-Indicator">,</span>
-<span class="w">        </span><span class="s">&quot;apps/calendar/appearance=dark_theme&quot;</span><span class="p p-Indicator">,</span>
+<span class="w">        </span><span class="s">&quot;apps/theme=dark&quot;</span><span class="p p-Indicator">,</span>
 <span class="w">      </span><span class="p p-Indicator">]</span>
 </code></pre></div>
 
 <p>You can modify the set of tasks or app variation by updating the <code>config_parallel_tasks.yaml</code>. We ensure:</p>
 <ul>
-<li>Each deployment of OpenApps can have different appearance and content per app.</li>
+<li>Each deployment of OpenApps can have a different theme (global), plus layout and content per app.</li>
 <li>Each task is launched in an isolated environment for reproducible results.</li>
 </ul>
+<p>To run <strong>every</strong> task in the loaded tasks config (rather than listing a subset by
+hand), set <code>task_names</code> to <code>all</code>. This expands to all task names defined in the
+selected <code>tasks=</code> group, so it composes with any tasks file:</p>
+<div class="codehilite"><pre><span></span><code>uv run launch_parallel_agents.py \
+  mode=slurm_cluster agent=dummy tasks=longer_horizon \
+  parallel_tasks.task_names=all use_wandb=True
+</code></pre></div>
+
+<p>Passing an explicit list (e.g. <code>parallel_tasks.task_names=[task_a,task_b]</code>) still
+runs only that subset.</p>
+<p>You can also select a task group to run via <code>tasks=longer_horizon parallel_tasks.task_names=all</code>.</p>
+<h3 id="running-across-goal-variations">Running across goal variations</h3>
+<p>Every task ships with <strong>goal variations</strong> — the same task with the goal reworded
+in a different style. Styles are <code>casual</code>, <code>formal</code>, and <code>unrelated_context</code>
+(the instruction wrapped in unrelated chit-chat), with 9 variations per task.
+They live in <code>config/tasks/user_goal_variations.yaml</code>, keyed
+<code>&lt;original_task&gt;__&lt;style&gt;_&lt;n&gt;</code> (e.g. <code>add_meeting_with_dennis__formal_1</code>), and
+each one preserves the original task's reward — only the <code>goal</code> wording differs
+and a <code>goal_style</code> field records the style.</p>
+<p>To run agents across <strong>all</strong> tasks and their goal variations in parallel, use
+the dedicated config, which lists every task name swept over a single default
+app variation:</p>
+<div class="codehilite"><pre><span></span><code><span class="n">uv</span><span class="w"> </span><span class="n">run</span><span class="w"> </span><span class="n">launch_parallel_agents</span><span class="o">.</span><span class="n">py</span><span class="w"> </span>\
+<span class="w">  </span><span class="o">--</span><span class="n">config</span><span class="o">-</span><span class="n">name</span><span class="o">=</span><span class="n">config_parallel_tasks_across_goal_variations</span><span class="w"> </span><span class="n">mode</span><span class="o">=</span><span class="n">slurm_cluster</span>
+</code></pre></div>
+
+<p>Use <code>mode=local</code> to run the jobs sequentially in the current process instead of
+on SLURM. This expands to one isolated job per goal phrasing, letting you
+measure how robust an agent is to how the same task is worded.</p>
 <h2 id="testing">Testing</h2>
 <p>Run all tests via:</p>
 <div class="codehilite"><pre><span></span><code><span class="n">uv</span> <span class="n">run</span> <span class="o">-</span><span class="n">m</span> <span class="n">pytest</span> <span class="n">tests</span><span class="o">/</span>
 </code></pre></div>
 
 <h2 id="attribution">Attribution</h2>
-<p>Our apps are built on top of several excellent frameworks:  </p>
+<p>Our apps are built on top of several excellent frameworks:</p>
 <ul>
 <li>FastHTML <a href="https://github.com/AnswerDotAI/fasthtml">framework</a> and <a href="https://github.com/AnswerDotAI/fasthtml-example">examples</a> which allowed us to build fully functional apps in Python, the language most familiar to AI researchers.</li>
 <li><a href="https://github.com/ServiceNow/BrowserGym/blob/main/LICENSE">Browser Gym</a> and <a href="https://github.com/ServiceNow/AgentLab/blob/main/LICENSE">AgentLab</a>:</li>
@@ -724,10 +866,22 @@ <h2 id="attribution">Attribution</h2>
         </a>
         
         
-        <a href="#appearance"
+        <a href="#theme"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="3">
+            Theme
+        </a>
+        
+        <a href="#layout"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="3">
+            Layout
+        </a>
+        
+        <a href="#migrating-from-appearance"
             class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
             data-active="false" data-depth="3">
-            Appearance
+            Migrating from appearance
         </a>
         
         <a href="#content"
@@ -739,6 +893,14 @@ <h2 id="attribution">Attribution</h2>
         
 
         
+        <a href="#exposing-openapps-as-an-mcp-server"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="2">
+            Exposing OpenApps as an MCP server
+        </a>
+        
+
+        
         <a href="#launch-agent"
             class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
             data-active="false" data-depth="2">
@@ -761,6 +923,14 @@ <h2 id="attribution">Attribution</h2>
             Launch Agent(s) Across Multiple Tasks
         </a>
         
+        
+        <a href="#running-across-goal-variations"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="3">
+            Running across goal variations
+        </a>
+        
+        
 
         
         <a href="#testing"
diff --git a/site/index.md b/site/index.md
index 8b980c3e..31035a2c 100644
--- a/site/index.md
+++ b/site/index.md
@@ -20,7 +20,7 @@ Install the conda alternative [uv](https://docs.astral.sh/uv/getting-started/) a
    git clone https://github.com/facebookresearch/OpenApps.git
 ```
 
-Install dependencies:   
+Install dependencies:
 
 ```bash
    uv sync
@@ -31,7 +31,7 @@ For other installation options and online shop setup see [Installation](installa
 ### Run OpenApps
 
 ```bash
-uv run launch.py 
+uv run launch.py
 ```
 ![landing](images/landing.png)
 
@@ -46,12 +46,19 @@ uv run launch.py 'apps.todo.init_todos=[["Call Mom", false]]'
 
 OpenApps also comes with pre-defined variations that can affect the content and appearance of apps.
 
-#### Appearance
+Appearance is split along two axes:
+
+* **Theme** -- *look*: colors, typography, shape. One shared set of design
+  tokens in `config/apps/theme/`, applied to **every** app at once.
+* **Layout** -- *structure*: how an individual app arranges itself. Per-app,
+  under `config/apps/<app>/layout/`.
+
+#### Theme
 
 /// tab | challenging font
 
     ::bash
-    export APPEARANCE=challenging_font
+    export THEME=challenging_font
 
 
 ![landing](images/landing-challenging-font.png)
@@ -59,25 +66,109 @@ OpenApps also comes with pre-defined variations that can affect the content and
 /// tab | dark theme
 
     ::bash
-    export APPEARANCE=dark_theme
+    export THEME=dark
 
 ![landing](images/landing-dark.png)
 ///
 /// tab | default
 
     ::bash
-    export APPEARANCE=default
+    export THEME=default
 
 ![landing](images/landing.png)
 
 ///
 
-Launch specific apps with selected appearance:
+A single override themes every app:
 ```shell
-uv run launch.py apps/start_page/appearance=$APPEARANCE
+uv run launch.py apps/theme=$THEME
+```
+
+Or one app only, leaving the rest on the global theme:
+`uv run launch.py apps.calendar.theme=$THEME`.
+
+Shipped themes: `default`, `dark`, `mono`, `challenging_font`, `colorblind`,
+`solarized`, `material`, `bootstrap`. Adding one means adding a yaml file to
+`config/apps/theme/` -- no app code changes.
+
+A theme file is a set of design tokens plus a small `assets` block:
+
+```yaml
+# config/apps/theme/dark.yaml
+name: dark
+tokens:
+  color-bg: "#121212"       # -> --color-bg, consumed as var(--color-bg)
+  color-primary: "#bb86fc"
+  font-family: "'Inter', system-ui, sans-serif"
+  radius: "4px"
+assets:
+  tone: dark                # apps map this onto their own non-CSS assets
+  icon_set: bw
+```
+
+Every `tokens` entry becomes a CSS custom property. `assets` covers the
+choices a CSS variable cannot reach -- the start page's raster icons, the
+Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately
+app-agnostic: the theme says `tone: dark` and each app picks its own dark
+asset, so a theme file never has to know which apps exist.
+
+#### Layout
+
+```shell
+uv run launch.py apps/todo/layout=kanban_board
+uv run launch.py apps/start_page/layout=broken_logos
+```
+
+Available layouts: `todo` has `default` and `kanban_board`; `start_page` has
+`default`, `broken_logos` (icons detached from their tiles) and
+`clickable_logos`; the other apps currently have `default` only.
+
+#### Migrating from `appearance`
+
+The `appearance` group these two replaced was removed: there are no
+`config/apps/<app>/appearance/` directories and no app renders from one.
+`apps/<app>/appearance=...` is a Hydra composition error, not a silent
+no-op. Translate overrides as:
+
+| Old override | New override |
+| --- | --- |
+| `apps/<app>/appearance=default` | `apps/theme=default` |
+| `apps/<app>/appearance=dark_theme` | `apps/theme=dark` |
+| `apps/<app>/appearance=black_and_white` | `apps/theme=mono` |
+| `apps/<app>/appearance=challenging_font` | `apps/theme=challenging_font` |
+| `apps/code_editor/appearance=colorblind_access` | `apps/theme=colorblind` |
+| `apps/todo/appearance=kanban_board` | `apps/todo/layout=kanban_board` |
+| `apps/start_page/appearance=broken_logos` | `apps/start_page/layout=broken_logos` |
+| `apps/start_page/appearance=clickable_logos` | `apps/start_page/layout=clickable_logos` |
+
+The theme rows are global, so the six per-app overrides the old dark variation
+needed collapse to one `apps/theme=dark`. Two renderings shift slightly:
+`mono` picks white-page/black-ink for every app, where the old
+`black_and_white` variants disagreed on polarity (calendar inverted the page,
+the rest did not), and `colorblind` is now available to all apps rather than
+the code editor alone.
+
+##### Reproducing the paper
+
+The paper's variation grid is indexed by `appearance` stem names, and the two
+axes above do not reproduce it pixel-for-pixel — see the shifts noted just
+above. **To reproduce the numbers in
+[the paper](https://arxiv.org/abs/2511.20766), use the `v1.0-paper` tag**, the
+last tree with `appearance` intact:
+
+```bash
+git checkout v1.0-paper
+uv run launch.py apps/todo/appearance=dark_theme
 ```
 
-Or specific apps with: `apps/calendar/appearance=$APPEARANCE`.
+Theme and layout are the supported axes going forward; `v1.0-paper` is frozen
+and gets no fixes.
+
+One exception to the removal: the MCP `reconfigure` tool still accepts an
+`appearance=` argument, translates it onto `theme`/`layout` per the table
+above, and raises a `DeprecationWarning`. It exists so existing MCP clients
+keep working for one release and will be removed — see
+[`src/open_apps/mcp/README.md`](https://github.com/facebookresearch/OpenApps/blob/main/src/open_apps/mcp/README.md).
 
 #### Content
 
@@ -111,7 +202,17 @@ uv run launch.py apps/start_page/content=$CONTENT
 
 Or specific apps with: `apps/calendar/content=$CONTENT`.
 
-You can see the specific variables for each defined in the individual apps. For example, `config/apps/maps/appearance/dark_theme.yaml`.
+You can see the specific variables for each defined in the individual apps.
+For example, `config/apps/theme/dark.yaml` for the shared design tokens,
+`config/apps/start_page/layout/broken_logos.yaml` for a per-app structure
+variant, and `config/apps/maps/default.yaml` for behaviour (map zoom, tile
+layer, route planning) that is neither.
+
+Optional: to save screenshots of all apps with a specific variation for testing, we offer `tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/` to make this easy.
+
+## Exposing OpenApps as an MCP server
+
+If you want an agent to interact with OpenApps using [MCP](https://modelcontextprotocol.io/docs/getting-started/intro) please see `src/open_apps/mcp/README.md`.
 
 ## Launch Agent
 
@@ -192,16 +293,52 @@ parallel_tasks:
   app_variations:
     - ["apps/start_page/content=default", "apps/calendar/content=german"]
     - [
-        "apps/start_page/appearance=dark_theme",
-        "apps/calendar/appearance=dark_theme",
+        "apps/theme=dark",
       ]
 ```
 
 You can modify the set of tasks or app variation by updating the `config_parallel_tasks.yaml`. We ensure:
 
-* Each deployment of OpenApps can have different appearance and content per app.
+* Each deployment of OpenApps can have a different theme (global), plus layout and content per app.
 * Each task is launched in an isolated environment for reproducible results.
 
+To run **every** task in the loaded tasks config (rather than listing a subset by
+hand), set `task_names` to `all`. This expands to all task names defined in the
+selected `tasks=` group, so it composes with any tasks file:
+
+```
+uv run launch_parallel_agents.py \
+  mode=slurm_cluster agent=dummy tasks=longer_horizon \
+  parallel_tasks.task_names=all use_wandb=True
+```
+
+Passing an explicit list (e.g. `parallel_tasks.task_names=[task_a,task_b]`) still
+runs only that subset.
+
+You can also select a task group to run via `tasks=longer_horizon parallel_tasks.task_names=all`.
+
+### Running across goal variations
+
+Every task ships with **goal variations** — the same task with the goal reworded
+in a different style. Styles are `casual`, `formal`, and `unrelated_context`
+(the instruction wrapped in unrelated chit-chat), with 9 variations per task.
+They live in `config/tasks/user_goal_variations.yaml`, keyed
+`<original_task>__<style>_<n>` (e.g. `add_meeting_with_dennis__formal_1`), and
+each one preserves the original task's reward — only the `goal` wording differs
+and a `goal_style` field records the style.
+
+To run agents across **all** tasks and their goal variations in parallel, use
+the dedicated config, which lists every task name swept over a single default
+app variation:
+
+```
+uv run launch_parallel_agents.py \
+  --config-name=config_parallel_tasks_across_goal_variations mode=slurm_cluster
+```
+
+Use `mode=local` to run the jobs sequentially in the current process instead of
+on SLURM. This expands to one isolated job per goal phrasing, letting you
+measure how robust an agent is to how the same task is worded.
 
 ## Testing
 
@@ -213,7 +350,7 @@ uv run -m pytest tests/
 
 ## Attribution
 
-Our apps are built on top of several excellent frameworks:  
+Our apps are built on top of several excellent frameworks:
 
 - FastHTML [framework](https://github.com/AnswerDotAI/fasthtml) and [examples](https://github.com/AnswerDotAI/fasthtml-example) which allowed us to build fully functional apps in Python, the language most familiar to AI researchers.
 - [Browser Gym](https://github.com/ServiceNow/BrowserGym/blob/main/LICENSE) and [AgentLab](https://github.com/ServiceNow/AgentLab/blob/main/LICENSE):
diff --git a/site/installation.md b/site/installation.md
new file mode 100644
index 00000000..9ee19504
--- /dev/null
+++ b/site/installation.md
@@ -0,0 +1,31 @@
+
+- Pre-requisite: install uv (a much faster pip): `pip install uv` (or from [source](https://docs.astral.sh/uv/getting-started/installation/))
+<!-- - [If using Conda] Create a fresh venv: `uv venv --python "$(which python)"` -->
+
+0) Clone [repo](https://github.com/facebookresearch/OpenApps)
+
+1) Install packages: `uv sync`
+
+2) Activate environment: `source .venv/bin/activate`
+
+3) Install `playwright install chromium`
+
+/// details | Optionally install for onlineshop (off by default)
+
+`Onlineshop java + spacy configuration`
+
+4) Prepare Java, Webshop data and spacy model: `chmod +x setup.sh` and `./setup.sh` for **Linux X64** or **Mac ARM64** systems
+
+5) Designate Java path: `source setup_javapath.sh` for **Linux X64** or **Mac ARM64** systems
+
+6) Check `java -version` gives you `java version "21.0.1"`
+
+7) Build search engine indexes: `chmod +x setup_pyserini.sh` and `./setup_pyserini.sh`
+
+**Congratulations! The onlineshop is ready to be used. Remember in future, always run `source setup_javapath.sh` to configure Java path before launching onlineshop-related tasks.**
+
+Finally, launch with
+```
+uv run launch.py apps.onlineshop.enable=True
+```
+///
diff --git a/site/search/search_index.json b/site/search/search_index.json
index 7a952371..17afa048 100644
--- a/site/search/search_index.json
+++ b/site/search/search_index.json
@@ -1 +1 @@
-{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Building Blocks for Digital Agents Research New to agents? See our Intro to UI Agents . We take you through the installation and running your first agent step-by-step. Why OpenApps? Evaluate and train multimodal agents to use apps like humans do (by clicking, typing, and scrolling): \u2705 Unlimited data (for evaluating and training UI-agents): Configurable state and design to generate thousands of versions of each app \u2705 Lightweight : runs on a single CPU (and Python-based); no Docker or OS emulators needed \u2705 Ground truth rewards : task rewards are based on the underlying state and all app logic is transparent in Python Install Install the conda alternative uv and clone the repo: git clone https://github.com/facebookresearch/OpenApps.git Install dependencies: uv sync For other installation options and online shop setup see Installation . Run OpenApps uv run launch.py For an overview, checkout our video tutorial . App variations Each app can be modified with variables available in config/apps . You can override any of these via command line: uv run launch.py 'apps.todo.init_todos=[[\"Call Mom\", false]]' OpenApps also comes with pre-defined variations that can affect the content and appearance of apps. Appearance challenging font export APPEARANCE = challenging_font dark theme export APPEARANCE = dark_theme default export APPEARANCE = default Launch specific apps with selected appearance: uv run launch.py apps/start_page/appearance = $APPEARANCE Or specific apps with: apps/calendar/appearance=$APPEARANCE . Content german export CONTENT = german long_descriptions export CONTENT = long_descriptions pop-up uv run launch.py apps/pop_ups = adversarial_descriptions uv run launch.py apps/start_page/content = $CONTENT Or specific apps with: apps/calendar/content=$CONTENT . You can see the specific variables for each defined in the individual apps. For example, config/apps/maps/appearance/dark_theme.yaml . Launch Agent For agents to directly interact with apps, install: playwright install chromium . Launch an agent to perform a task of adding a meeting with Dennis to the calendar : Random Click Agent uv run launch_agent.py agent = dummy task_name = add_meeting_with_dennis GPT-5.1 Agent # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = add_meeting_with_dennis You can specify the agent of your choice with the agent= argument. For example agent=dummy is a simple agent that clicks randomly on any buttons, great for exploration! Learn more about launching with OpenAI, Claude, VLLM models, or specialized models such as UI-Tars in agents guide and available tasks in our task guide . Note: To test the ability of a model to navigate the UI without simplified HTML, set: agent.use_axtree=False To see the agent solving the task live: uv run launch_agent.py browsergym_env_args.headless=False Logs By default, information about the number of steps an agent took, task success, etc. will be shown in the terminal: ... Experiment results exp_dir: /Users/m... n_steps: 10 cum_reward: 0.0 stats.cum_agent_elapsed: 0.0017838478088378906 stats.max_agent_elapsed: 0.0002570152282714844 ... All logs are stored log_outputs will contain information about each run You can also enable logging to weights and biases by logging into your account and setting the flag: use_wandb=True . Launch Agent(s) Across Multiple Tasks launch thousands of app variations to study agent behaviors in parallel Note: Parallel launching works with SLURM. Be sure to update configs in config/mode/slurm_cluster.yaml . You can launch one (or multiple) agents to solve many tasks in parallel, each in an isolated deployment of OpenApps, using SLURM: uv run launch_parallel_agents.py mode=slurm_cluster agent=dummy use_wandb=True This launches 6 parallel independent random click agents to solve each task in each app variation as defined in config_parallel_tasks.yaml parallel_tasks : _target_ : open_apps.tasks.parallel_tasks.AppVariationParallelTasksConfig task_names : - add_meeting_with_dennis - add_call_mom_to_my_todo - save_paris_to_my_favorite_places app_variations : - [ \"apps/start_page/content=default\" , \"apps/calendar/content=german\" ] - [ \"apps/start_page/appearance=dark_theme\" , \"apps/calendar/appearance=dark_theme\" , ] You can modify the set of tasks or app variation by updating the config_parallel_tasks.yaml . We ensure: Each deployment of OpenApps can have different appearance and content per app. Each task is launched in an isolated environment for reproducible results. Testing Run all tests via: uv run - m pytest tests / Attribution Our apps are built on top of several excellent frameworks: FastHTML framework and examples which allowed us to build fully functional apps in Python, the language most familiar to AI researchers. Browser Gym and AgentLab : Spacy : for natural language processing Open Street Maps : for our Maps apps. (and for the optional webshop) we rely on WebShop developed by Princeton University Some icons are have been designed using resources from Flaticon.com Our work is licensed under CC-BY-NC, please refer to the LICENSE file in the top level directory. Copyright \u00a9 Meta Platforms, Inc. See the Terms of Use and Privacy Policy for this project.","title":"Start"},{"location":"#install","text":"Install the conda alternative uv and clone the repo: git clone https://github.com/facebookresearch/OpenApps.git Install dependencies: uv sync For other installation options and online shop setup see Installation .","title":"Install"},{"location":"#run-openapps","text":"uv run launch.py For an overview, checkout our video tutorial .","title":"Run OpenApps"},{"location":"#app-variations","text":"Each app can be modified with variables available in config/apps . You can override any of these via command line: uv run launch.py 'apps.todo.init_todos=[[\"Call Mom\", false]]' OpenApps also comes with pre-defined variations that can affect the content and appearance of apps.","title":"App variations"},{"location":"#appearance","text":"challenging font export APPEARANCE = challenging_font dark theme export APPEARANCE = dark_theme default export APPEARANCE = default Launch specific apps with selected appearance: uv run launch.py apps/start_page/appearance = $APPEARANCE Or specific apps with: apps/calendar/appearance=$APPEARANCE .","title":"Appearance"},{"location":"#content","text":"german export CONTENT = german long_descriptions export CONTENT = long_descriptions pop-up uv run launch.py apps/pop_ups = adversarial_descriptions uv run launch.py apps/start_page/content = $CONTENT Or specific apps with: apps/calendar/content=$CONTENT . You can see the specific variables for each defined in the individual apps. For example, config/apps/maps/appearance/dark_theme.yaml .","title":"Content"},{"location":"#launch-agent","text":"For agents to directly interact with apps, install: playwright install chromium . Launch an agent to perform a task of adding a meeting with Dennis to the calendar : Random Click Agent uv run launch_agent.py agent = dummy task_name = add_meeting_with_dennis GPT-5.1 Agent # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = add_meeting_with_dennis You can specify the agent of your choice with the agent= argument. For example agent=dummy is a simple agent that clicks randomly on any buttons, great for exploration! Learn more about launching with OpenAI, Claude, VLLM models, or specialized models such as UI-Tars in agents guide and available tasks in our task guide . Note: To test the ability of a model to navigate the UI without simplified HTML, set: agent.use_axtree=False To see the agent solving the task live: uv run launch_agent.py browsergym_env_args.headless=False","title":"Launch Agent"},{"location":"#logs","text":"By default, information about the number of steps an agent took, task success, etc. will be shown in the terminal: ... Experiment results exp_dir: /Users/m... n_steps: 10 cum_reward: 0.0 stats.cum_agent_elapsed: 0.0017838478088378906 stats.max_agent_elapsed: 0.0002570152282714844 ... All logs are stored log_outputs will contain information about each run You can also enable logging to weights and biases by logging into your account and setting the flag: use_wandb=True .","title":"Logs"},{"location":"#launch-agents-across-multiple-tasks","text":"launch thousands of app variations to study agent behaviors in parallel Note: Parallel launching works with SLURM. Be sure to update configs in config/mode/slurm_cluster.yaml . You can launch one (or multiple) agents to solve many tasks in parallel, each in an isolated deployment of OpenApps, using SLURM: uv run launch_parallel_agents.py mode=slurm_cluster agent=dummy use_wandb=True This launches 6 parallel independent random click agents to solve each task in each app variation as defined in config_parallel_tasks.yaml parallel_tasks : _target_ : open_apps.tasks.parallel_tasks.AppVariationParallelTasksConfig task_names : - add_meeting_with_dennis - add_call_mom_to_my_todo - save_paris_to_my_favorite_places app_variations : - [ \"apps/start_page/content=default\" , \"apps/calendar/content=german\" ] - [ \"apps/start_page/appearance=dark_theme\" , \"apps/calendar/appearance=dark_theme\" , ] You can modify the set of tasks or app variation by updating the config_parallel_tasks.yaml . We ensure: Each deployment of OpenApps can have different appearance and content per app. Each task is launched in an isolated environment for reproducible results.","title":"Launch Agent(s) Across Multiple Tasks"},{"location":"#testing","text":"Run all tests via: uv run - m pytest tests /","title":"Testing"},{"location":"#attribution","text":"Our apps are built on top of several excellent frameworks: FastHTML framework and examples which allowed us to build fully functional apps in Python, the language most familiar to AI researchers. Browser Gym and AgentLab : Spacy : for natural language processing Open Street Maps : for our Maps apps. (and for the optional webshop) we rely on WebShop developed by Princeton University Some icons are have been designed using resources from Flaticon.com Our work is licensed under CC-BY-NC, please refer to the LICENSE file in the top level directory. Copyright \u00a9 Meta Platforms, Inc. See the Terms of Use and Privacy Policy for this project.","title":"Attribution"},{"location":"Intro%20to%20UI%20Agents/","text":"Digital agents open the possibility of AI systems to complete tedious tasks on your behalf. For example, \"add an event to my calendar\" or even more complex multi-step tasks. Yet, today's agents are still not reliable enough for many applications. To get there, we need lots of data for training and evaluation + lots of research to develop new recipes for training and deploying reliable agents. A few definitions to settle you in: Digital (UI) Agent: completes tasks by directly interacting with apps in the same manner as humans (by clicking, scrolling, typing on your behalf) Reward: measures whether the agent completed the given task Agents under the hood Digital agents are powered by a foundation model that can understand both text and image inputs. Agents receive a screenshot of the current apps (in the same manner a human sees them) and the task goal (\"delete Brooklyn Bridge from my favorite places\"); depending on how you configure the agent, the agent can also track past actions or observations. The agent then outputs an action such as click or type that directly affects the apps. Throughout the interaction we monitor whether the action has completed the task to terminate the loop or a max_steps is reached. You can view configs for configs/agents/default.yaml containing: list of actions use_axtree : produces simplified text representation of each app states as an input use_screenshot : provides screenshot of app as an input save_som : if true, saves set of marks in log_outputs/<timestamp>/set_of_marks_coordinates.json json (see example below) You can view UI-Tars-1.5-7B.yaml as an example of native computer-use which uses screenshots to output click, type, actions with coordinates. For an example of a multimodal agent that accepts simplified text inputs see GPT-5.1.yaml . OpenApps: building blocks for digital agent research OpenApps offers an easy to use environment that runs on one CPU written in Python for stuyding digital agents. OpenApps comes with six configurable apps for generating limitless data for training and evaluating digital agents. Hands on with OpenApps Learn how to set up OpenApps, run a GPT-5 agent and make changes to the envrionment.","title":"Intro to UI Agents"},{"location":"Intro%20to%20UI%20Agents/#agents-under-the-hood","text":"Digital agents are powered by a foundation model that can understand both text and image inputs. Agents receive a screenshot of the current apps (in the same manner a human sees them) and the task goal (\"delete Brooklyn Bridge from my favorite places\"); depending on how you configure the agent, the agent can also track past actions or observations. The agent then outputs an action such as click or type that directly affects the apps. Throughout the interaction we monitor whether the action has completed the task to terminate the loop or a max_steps is reached. You can view configs for configs/agents/default.yaml containing: list of actions use_axtree : produces simplified text representation of each app states as an input use_screenshot : provides screenshot of app as an input save_som : if true, saves set of marks in log_outputs/<timestamp>/set_of_marks_coordinates.json json (see example below) You can view UI-Tars-1.5-7B.yaml as an example of native computer-use which uses screenshots to output click, type, actions with coordinates. For an example of a multimodal agent that accepts simplified text inputs see GPT-5.1.yaml .","title":"Agents under the hood"},{"location":"Intro%20to%20UI%20Agents/#openapps-building-blocks-for-digital-agent-research","text":"OpenApps offers an easy to use environment that runs on one CPU written in Python for stuyding digital agents. OpenApps comes with six configurable apps for generating limitless data for training and evaluating digital agents.","title":"OpenApps: building blocks for digital agent research"},{"location":"Intro%20to%20UI%20Agents/#hands-on-with-openapps","text":"Learn how to set up OpenApps, run a GPT-5 agent and make changes to the envrionment.","title":"Hands on with OpenApps"},{"location":"agents/","text":"Quickstart: Getting Your Agent to Run Prerequisites To use GPT-5-1 to complete tasks, set your OpenAI API key: export OPENAI_API_KEY = YOUR_KEY Alternatively, edit the corresponding line in config/agent/GPT-5-1.yaml . Supported Clients We support multiple client types: vLLM OpenAI Azure AWS To use a different client, change the client_type argument in your configuration. Check out /src/open_apps/agent/vLLM_agent.py Line 49 and following for specifics about how these clients are called internally. Running Your Agent uv run launch_agent.py agent = GPT-4o To run a local model with vLLM , Launch your local vLLM model: vllm serve [MODEL_NAME] . VLLM will tell you your hostname. Launch your agent uv run launch_agent.py agent = AGENT_CONFIG agent.hostname = VLLM_HOSTNAME Configuring Your Policy Our agent policies are built on top of AgentLab . Our setup enables automatic configuration of your prompt with config flags. Here are some key flags you can configure in your agent's YAML file: Observation Flags: use_axtree : Enable AXTree observation (accessibility tree) use_screenshot : Enable screenshot observation use_som : Add visual marks to screenshots for element identification extract_coords : Include element coordinates in observations History & Memory Flags: use_history : Enable action/thought history tracking use_action_history : Track previous actions taken by the agent use_think_history : Track previous thoughts/reasoning steps Reasoning & Examples Flags: use_thinking : Enable chain-of-thought reasoning before actions use_concrete_example : Include concrete examples in the prompt use_abstract_example : Include abstract reasoning examples in the prompt Custom Prompts: prompt_txt.system_prompt : Override the default system prompt prompt_txt.action_prompt : Define custom action instructions prompt_txt.think_prompt : Define custom thinking/reasoning instructions For the complete set of configuration options, see config/agent/default.yaml . Creating Your Own Agent If AgentLab's capabilities don't meet your needs, you can create a custom agent. Navigate to src/open_apps/agent/ Copy and modify the following files: vLLM_agent.py vLLM_prompt.py This allows you to build rich, custom agent implementations tailored to your specific requirements.","title":"Agents"},{"location":"agents/#quickstart-getting-your-agent-to-run","text":"","title":"Quickstart: Getting Your Agent to Run"},{"location":"agents/#prerequisites","text":"To use GPT-5-1 to complete tasks, set your OpenAI API key: export OPENAI_API_KEY = YOUR_KEY Alternatively, edit the corresponding line in config/agent/GPT-5-1.yaml .","title":"Prerequisites"},{"location":"agents/#supported-clients","text":"We support multiple client types: vLLM OpenAI Azure AWS To use a different client, change the client_type argument in your configuration. Check out /src/open_apps/agent/vLLM_agent.py Line 49 and following for specifics about how these clients are called internally.","title":"Supported Clients"},{"location":"agents/#running-your-agent","text":"uv run launch_agent.py agent = GPT-4o To run a local model with vLLM , Launch your local vLLM model: vllm serve [MODEL_NAME] . VLLM will tell you your hostname. Launch your agent uv run launch_agent.py agent = AGENT_CONFIG agent.hostname = VLLM_HOSTNAME","title":"Running Your Agent"},{"location":"agents/#configuring-your-policy","text":"Our agent policies are built on top of AgentLab . Our setup enables automatic configuration of your prompt with config flags. Here are some key flags you can configure in your agent's YAML file: Observation Flags: use_axtree : Enable AXTree observation (accessibility tree) use_screenshot : Enable screenshot observation use_som : Add visual marks to screenshots for element identification extract_coords : Include element coordinates in observations History & Memory Flags: use_history : Enable action/thought history tracking use_action_history : Track previous actions taken by the agent use_think_history : Track previous thoughts/reasoning steps Reasoning & Examples Flags: use_thinking : Enable chain-of-thought reasoning before actions use_concrete_example : Include concrete examples in the prompt use_abstract_example : Include abstract reasoning examples in the prompt Custom Prompts: prompt_txt.system_prompt : Override the default system prompt prompt_txt.action_prompt : Define custom action instructions prompt_txt.think_prompt : Define custom thinking/reasoning instructions For the complete set of configuration options, see config/agent/default.yaml .","title":"Configuring Your Policy"},{"location":"agents/#creating-your-own-agent","text":"If AgentLab's capabilities don't meet your needs, you can create a custom agent. Navigate to src/open_apps/agent/ Copy and modify the following files: vLLM_agent.py vLLM_prompt.py This allows you to build rich, custom agent implementations tailored to your specific requirements.","title":"Creating Your Own Agent"},{"location":"installation/","text":"Pre-requisite: install uv (a much faster pip): pip install uv (or from source ) 0) Clone repo 1) Install packages: uv sync 2) Activate environment: source .venv/bin/activate 3) Install playwright install chromium Optionally install for onlineshop (off by default) Onlineshop java + spacy configuration 4) Prepare Java, Webshop data and spacy model: chmod +x setup.sh and ./setup.sh for Linux X64 or Mac ARM64 systems 5) Designate Java path: source setup_javapath.sh for Linux X64 or Mac ARM64 systems 6) Check java -version gives you java version \"21.0.1\" 7) Build search engine indexes: chmod +x setup_pyserini.sh and ./setup_pyserini.sh Congratulations! The onlineshop is ready to be used. Remember in future, always run source setup_javapath.sh to configure Java path before launching onlineshop-related tasks. Finally, launch with uv run launch.py apps.onlineshop.enable=True","title":"Manual Installation"},{"location":"tasks/","text":"To ask GPT-4o to mark water plants as done in your todo list: # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done task_name specifies the task. Tasks are defined in config/tasks/all_tasks.yaml . For example, mark_water_plants_as_done : # Indicates class where reward logic is defined _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : Mark 'Water plants' as done in my todo list. todo_name : \"Water plants\" Adding New Tasks To add a new task using an existing reward function, simply add a new entry to the config/tasks/all_tasks.yaml : add_my_special_item_to_todo : # _target_ defines the class containing the task reward logic _target_ : open_apps.tasks.tasks.AddToDoTask goal : ENTER YOUR GOAL todo_name : ENTER TITLE of TODO is_done : false You can select this new task by specifying the task_name=add_my_special_item_todo . New custom tasks To add a custom task with its own reward logic, create a new class in src/open_apps/tasks/tasks.py . Your new class should inherit Task and implement a reward function, check_if_task_is_complete , indicating whether the task is complete: @dataclass class MyCustomTask ( Task ): def check_if_task_is_complete ( self , initiate_state : dict , current_state : dict ) -> bool : # we handle providing the initial and current states for you! # write your custom reward logic ... Then create a corresponding entry in config/tasks/all_tasks.yaml : my_custom_task : _target_ : open_apps.tasks.tasks.MyCustomTask goal : ENTER Finally, ask your agent to solve the task by specifying task_name=my_custom_task .","title":"Tasks"},{"location":"tasks/#adding-new-tasks","text":"To add a new task using an existing reward function, simply add a new entry to the config/tasks/all_tasks.yaml : add_my_special_item_to_todo : # _target_ defines the class containing the task reward logic _target_ : open_apps.tasks.tasks.AddToDoTask goal : ENTER YOUR GOAL todo_name : ENTER TITLE of TODO is_done : false You can select this new task by specifying the task_name=add_my_special_item_todo .","title":"Adding New Tasks"},{"location":"tasks/#new-custom-tasks","text":"To add a custom task with its own reward logic, create a new class in src/open_apps/tasks/tasks.py . Your new class should inherit Task and implement a reward function, check_if_task_is_complete , indicating whether the task is complete: @dataclass class MyCustomTask ( Task ): def check_if_task_is_complete ( self , initiate_state : dict , current_state : dict ) -> bool : # we handle providing the initial and current states for you! # write your custom reward logic ... Then create a corresponding entry in config/tasks/all_tasks.yaml : my_custom_task : _target_ : open_apps.tasks.tasks.MyCustomTask goal : ENTER Finally, ask your agent to solve the task by specifying task_name=my_custom_task .","title":"New custom tasks"}]}
\ No newline at end of file
+{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Building Blocks for Digital Agents Research New to agents? See our Intro to UI Agents . We take you through the installation and running your first agent step-by-step. Why OpenApps? Evaluate and train multimodal agents to use apps like humans do (by clicking, typing, and scrolling): \u2705 Unlimited data (for evaluating and training UI-agents): Configurable state and design to generate thousands of versions of each app \u2705 Lightweight : runs on a single CPU (and Python-based); no Docker or OS emulators needed \u2705 Ground truth rewards : task rewards are based on the underlying state and all app logic is transparent in Python Install Install the conda alternative uv and clone the repo: git clone https://github.com/facebookresearch/OpenApps.git Install dependencies: uv sync For other installation options and online shop setup see Installation . Run OpenApps uv run launch.py For an overview, checkout our video tutorial . App variations Each app can be modified with variables available in config/apps . You can override any of these via command line: uv run launch.py 'apps.todo.init_todos=[[\"Call Mom\", false]]' OpenApps also comes with pre-defined variations that can affect the content and appearance of apps. Appearance is split along two axes: Theme -- look : colors, typography, shape. One shared set of design tokens in config/apps/theme/ , applied to every app at once. Layout -- structure : how an individual app arranges itself. Per-app, under config/apps/<app>/layout/ . Theme challenging font export THEME = challenging_font dark theme export THEME = dark default export THEME = default A single override themes every app: uv run launch.py apps/theme = $THEME Or one app only, leaving the rest on the global theme: uv run launch.py apps.calendar.theme=$THEME . Shipped themes: default , dark , mono , challenging_font , colorblind , solarized , material , bootstrap . Adding one means adding a yaml file to config/apps/theme/ -- no app code changes. A theme file is a set of design tokens plus a small assets block: # config/apps/theme/dark.yaml name : dark tokens : color-bg : \"#121212\" # -> --color-bg, consumed as var(--color-bg) color-primary : \"#bb86fc\" font-family : \"'Inter', system-ui, sans-serif\" radius : \"4px\" assets : tone : dark # apps map this onto their own non-CSS assets icon_set : bw Every tokens entry becomes a CSS custom property. assets covers the choices a CSS variable cannot reach -- the start page's raster icons, the Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately app-agnostic: the theme says tone: dark and each app picks its own dark asset, so a theme file never has to know which apps exist. Layout uv run launch.py apps/todo/layout = kanban_board uv run launch.py apps/start_page/layout = broken_logos Available layouts: todo has default and kanban_board ; start_page has default , broken_logos (icons detached from their tiles) and clickable_logos ; the other apps currently have default only. Migrating from appearance The appearance group these two replaced was removed: there are no config/apps/<app>/appearance/ directories and no app renders from one. apps/<app>/appearance=... is a Hydra composition error, not a silent no-op. Translate overrides as: Old override New override apps/<app>/appearance=default apps/theme=default apps/<app>/appearance=dark_theme apps/theme=dark apps/<app>/appearance=black_and_white apps/theme=mono apps/<app>/appearance=challenging_font apps/theme=challenging_font apps/code_editor/appearance=colorblind_access apps/theme=colorblind apps/todo/appearance=kanban_board apps/todo/layout=kanban_board apps/start_page/appearance=broken_logos apps/start_page/layout=broken_logos apps/start_page/appearance=clickable_logos apps/start_page/layout=clickable_logos The theme rows are global, so the six per-app overrides the old dark variation needed collapse to one apps/theme=dark . Two renderings shift slightly: mono picks white-page/black-ink for every app, where the old black_and_white variants disagreed on polarity (calendar inverted the page, the rest did not), and colorblind is now available to all apps rather than the code editor alone. Reproducing the paper The paper's variation grid is indexed by appearance stem names, and the two axes above do not reproduce it pixel-for-pixel \u2014 see the shifts noted just above. To reproduce the numbers in the paper , use the v1.0-paper tag , the last tree with appearance intact: git checkout v1.0-paper uv run launch.py apps/todo/appearance = dark_theme Theme and layout are the supported axes going forward; v1.0-paper is frozen and gets no fixes. One exception to the removal: the MCP reconfigure tool still accepts an appearance= argument, translates it onto theme / layout per the table above, and raises a DeprecationWarning . It exists so existing MCP clients keep working for one release and will be removed \u2014 see src/open_apps/mcp/README.md . Content german export CONTENT = german long_descriptions export CONTENT = long_descriptions pop-up uv run launch.py apps/pop_ups = adversarial_descriptions uv run launch.py apps/start_page/content = $CONTENT Or specific apps with: apps/calendar/content=$CONTENT . You can see the specific variables for each defined in the individual apps. For example, config/apps/theme/dark.yaml for the shared design tokens, config/apps/start_page/layout/broken_logos.yaml for a per-app structure variant, and config/apps/maps/default.yaml for behaviour (map zoom, tile layer, route planning) that is neither. Optional: to save screenshots of all apps with a specific variation for testing, we offer tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/ to make this easy. Exposing OpenApps as an MCP server If you want an agent to interact with OpenApps using MCP please see src/open_apps/mcp/README.md . Launch Agent For agents to directly interact with apps, install: playwright install chromium . Launch an agent to perform a task of adding a meeting with Dennis to the calendar : Random Click Agent uv run launch_agent.py agent = dummy task_name = add_meeting_with_dennis GPT-5.1 Agent # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = add_meeting_with_dennis You can specify the agent of your choice with the agent= argument. For example agent=dummy is a simple agent that clicks randomly on any buttons, great for exploration! Learn more about launching with OpenAI, Claude, VLLM models, or specialized models such as UI-Tars in agents guide and available tasks in our task guide . Note: To test the ability of a model to navigate the UI without simplified HTML, set: agent.use_axtree=False To see the agent solving the task live: uv run launch_agent.py browsergym_env_args.headless=False Logs By default, information about the number of steps an agent took, task success, etc. will be shown in the terminal: ... Experiment results exp_dir: /Users/m... n_steps: 10 cum_reward: 0.0 stats.cum_agent_elapsed: 0.0017838478088378906 stats.max_agent_elapsed: 0.0002570152282714844 ... All logs are stored log_outputs will contain information about each run You can also enable logging to weights and biases by logging into your account and setting the flag: use_wandb=True . Launch Agent(s) Across Multiple Tasks launch thousands of app variations to study agent behaviors in parallel Note: Parallel launching works with SLURM. Be sure to update configs in config/mode/slurm_cluster.yaml . You can launch one (or multiple) agents to solve many tasks in parallel, each in an isolated deployment of OpenApps, using SLURM: uv run launch_parallel_agents.py mode=slurm_cluster agent=dummy use_wandb=True This launches 6 parallel independent random click agents to solve each task in each app variation as defined in config_parallel_tasks.yaml parallel_tasks : _target_ : open_apps.tasks.parallel_tasks.AppVariationParallelTasksConfig task_names : - add_meeting_with_dennis - add_call_mom_to_my_todo - save_paris_to_my_favorite_places app_variations : - [ \"apps/start_page/content=default\" , \"apps/calendar/content=german\" ] - [ \"apps/theme=dark\" , ] You can modify the set of tasks or app variation by updating the config_parallel_tasks.yaml . We ensure: Each deployment of OpenApps can have a different theme (global), plus layout and content per app. Each task is launched in an isolated environment for reproducible results. To run every task in the loaded tasks config (rather than listing a subset by hand), set task_names to all . This expands to all task names defined in the selected tasks= group, so it composes with any tasks file: uv run launch_parallel_agents.py \\ mode=slurm_cluster agent=dummy tasks=longer_horizon \\ parallel_tasks.task_names=all use_wandb=True Passing an explicit list (e.g. parallel_tasks.task_names=[task_a,task_b] ) still runs only that subset. You can also select a task group to run via tasks=longer_horizon parallel_tasks.task_names=all . Running across goal variations Every task ships with goal variations \u2014 the same task with the goal reworded in a different style. Styles are casual , formal , and unrelated_context (the instruction wrapped in unrelated chit-chat), with 9 variations per task. They live in config/tasks/user_goal_variations.yaml , keyed <original_task>__<style>_<n> (e.g. add_meeting_with_dennis__formal_1 ), and each one preserves the original task's reward \u2014 only the goal wording differs and a goal_style field records the style. To run agents across all tasks and their goal variations in parallel, use the dedicated config, which lists every task name swept over a single default app variation: uv run launch_parallel_agents . py \\ -- config - name = config_parallel_tasks_across_goal_variations mode = slurm_cluster Use mode=local to run the jobs sequentially in the current process instead of on SLURM. This expands to one isolated job per goal phrasing, letting you measure how robust an agent is to how the same task is worded. Testing Run all tests via: uv run - m pytest tests / Attribution Our apps are built on top of several excellent frameworks: FastHTML framework and examples which allowed us to build fully functional apps in Python, the language most familiar to AI researchers. Browser Gym and AgentLab : Spacy : for natural language processing Open Street Maps : for our Maps apps. (and for the optional webshop) we rely on WebShop developed by Princeton University Some icons are have been designed using resources from Flaticon.com Our work is licensed under CC-BY-NC, please refer to the LICENSE file in the top level directory. Copyright \u00a9 Meta Platforms, Inc. See the Terms of Use and Privacy Policy for this project.","title":"Start"},{"location":"#install","text":"Install the conda alternative uv and clone the repo: git clone https://github.com/facebookresearch/OpenApps.git Install dependencies: uv sync For other installation options and online shop setup see Installation .","title":"Install"},{"location":"#run-openapps","text":"uv run launch.py For an overview, checkout our video tutorial .","title":"Run OpenApps"},{"location":"#app-variations","text":"Each app can be modified with variables available in config/apps . You can override any of these via command line: uv run launch.py 'apps.todo.init_todos=[[\"Call Mom\", false]]' OpenApps also comes with pre-defined variations that can affect the content and appearance of apps. Appearance is split along two axes: Theme -- look : colors, typography, shape. One shared set of design tokens in config/apps/theme/ , applied to every app at once. Layout -- structure : how an individual app arranges itself. Per-app, under config/apps/<app>/layout/ .","title":"App variations"},{"location":"#theme","text":"challenging font export THEME = challenging_font dark theme export THEME = dark default export THEME = default A single override themes every app: uv run launch.py apps/theme = $THEME Or one app only, leaving the rest on the global theme: uv run launch.py apps.calendar.theme=$THEME . Shipped themes: default , dark , mono , challenging_font , colorblind , solarized , material , bootstrap . Adding one means adding a yaml file to config/apps/theme/ -- no app code changes. A theme file is a set of design tokens plus a small assets block: # config/apps/theme/dark.yaml name : dark tokens : color-bg : \"#121212\" # -> --color-bg, consumed as var(--color-bg) color-primary : \"#bb86fc\" font-family : \"'Inter', system-ui, sans-serif\" radius : \"4px\" assets : tone : dark # apps map this onto their own non-CSS assets icon_set : bw Every tokens entry becomes a CSS custom property. assets covers the choices a CSS variable cannot reach -- the start page's raster icons, the Leaflet tile layer, the CodeMirror stylesheet. The keys are deliberately app-agnostic: the theme says tone: dark and each app picks its own dark asset, so a theme file never has to know which apps exist.","title":"Theme"},{"location":"#layout","text":"uv run launch.py apps/todo/layout = kanban_board uv run launch.py apps/start_page/layout = broken_logos Available layouts: todo has default and kanban_board ; start_page has default , broken_logos (icons detached from their tiles) and clickable_logos ; the other apps currently have default only.","title":"Layout"},{"location":"#migrating-from-appearance","text":"The appearance group these two replaced was removed: there are no config/apps/<app>/appearance/ directories and no app renders from one. apps/<app>/appearance=... is a Hydra composition error, not a silent no-op. Translate overrides as: Old override New override apps/<app>/appearance=default apps/theme=default apps/<app>/appearance=dark_theme apps/theme=dark apps/<app>/appearance=black_and_white apps/theme=mono apps/<app>/appearance=challenging_font apps/theme=challenging_font apps/code_editor/appearance=colorblind_access apps/theme=colorblind apps/todo/appearance=kanban_board apps/todo/layout=kanban_board apps/start_page/appearance=broken_logos apps/start_page/layout=broken_logos apps/start_page/appearance=clickable_logos apps/start_page/layout=clickable_logos The theme rows are global, so the six per-app overrides the old dark variation needed collapse to one apps/theme=dark . Two renderings shift slightly: mono picks white-page/black-ink for every app, where the old black_and_white variants disagreed on polarity (calendar inverted the page, the rest did not), and colorblind is now available to all apps rather than the code editor alone.","title":"Migrating from appearance"},{"location":"#reproducing-the-paper","text":"The paper's variation grid is indexed by appearance stem names, and the two axes above do not reproduce it pixel-for-pixel \u2014 see the shifts noted just above. To reproduce the numbers in the paper , use the v1.0-paper tag , the last tree with appearance intact: git checkout v1.0-paper uv run launch.py apps/todo/appearance = dark_theme Theme and layout are the supported axes going forward; v1.0-paper is frozen and gets no fixes. One exception to the removal: the MCP reconfigure tool still accepts an appearance= argument, translates it onto theme / layout per the table above, and raises a DeprecationWarning . It exists so existing MCP clients keep working for one release and will be removed \u2014 see src/open_apps/mcp/README.md .","title":"Reproducing the paper"},{"location":"#content","text":"german export CONTENT = german long_descriptions export CONTENT = long_descriptions pop-up uv run launch.py apps/pop_ups = adversarial_descriptions uv run launch.py apps/start_page/content = $CONTENT Or specific apps with: apps/calendar/content=$CONTENT . You can see the specific variables for each defined in the individual apps. For example, config/apps/theme/dark.yaml for the shared design tokens, config/apps/start_page/layout/broken_logos.yaml for a per-app structure variant, and config/apps/maps/default.yaml for behaviour (map zoom, tile layer, route planning) that is neither. Optional: to save screenshots of all apps with a specific variation for testing, we offer tests/save_screenshots.py --variation default --output-dir outputs/2026-04-13/default/ to make this easy.","title":"Content"},{"location":"#exposing-openapps-as-an-mcp-server","text":"If you want an agent to interact with OpenApps using MCP please see src/open_apps/mcp/README.md .","title":"Exposing OpenApps as an MCP server"},{"location":"#launch-agent","text":"For agents to directly interact with apps, install: playwright install chromium . Launch an agent to perform a task of adding a meeting with Dennis to the calendar : Random Click Agent uv run launch_agent.py agent = dummy task_name = add_meeting_with_dennis GPT-5.1 Agent # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = add_meeting_with_dennis You can specify the agent of your choice with the agent= argument. For example agent=dummy is a simple agent that clicks randomly on any buttons, great for exploration! Learn more about launching with OpenAI, Claude, VLLM models, or specialized models such as UI-Tars in agents guide and available tasks in our task guide . Note: To test the ability of a model to navigate the UI without simplified HTML, set: agent.use_axtree=False To see the agent solving the task live: uv run launch_agent.py browsergym_env_args.headless=False","title":"Launch Agent"},{"location":"#logs","text":"By default, information about the number of steps an agent took, task success, etc. will be shown in the terminal: ... Experiment results exp_dir: /Users/m... n_steps: 10 cum_reward: 0.0 stats.cum_agent_elapsed: 0.0017838478088378906 stats.max_agent_elapsed: 0.0002570152282714844 ... All logs are stored log_outputs will contain information about each run You can also enable logging to weights and biases by logging into your account and setting the flag: use_wandb=True .","title":"Logs"},{"location":"#launch-agents-across-multiple-tasks","text":"launch thousands of app variations to study agent behaviors in parallel Note: Parallel launching works with SLURM. Be sure to update configs in config/mode/slurm_cluster.yaml . You can launch one (or multiple) agents to solve many tasks in parallel, each in an isolated deployment of OpenApps, using SLURM: uv run launch_parallel_agents.py mode=slurm_cluster agent=dummy use_wandb=True This launches 6 parallel independent random click agents to solve each task in each app variation as defined in config_parallel_tasks.yaml parallel_tasks : _target_ : open_apps.tasks.parallel_tasks.AppVariationParallelTasksConfig task_names : - add_meeting_with_dennis - add_call_mom_to_my_todo - save_paris_to_my_favorite_places app_variations : - [ \"apps/start_page/content=default\" , \"apps/calendar/content=german\" ] - [ \"apps/theme=dark\" , ] You can modify the set of tasks or app variation by updating the config_parallel_tasks.yaml . We ensure: Each deployment of OpenApps can have a different theme (global), plus layout and content per app. Each task is launched in an isolated environment for reproducible results. To run every task in the loaded tasks config (rather than listing a subset by hand), set task_names to all . This expands to all task names defined in the selected tasks= group, so it composes with any tasks file: uv run launch_parallel_agents.py \\ mode=slurm_cluster agent=dummy tasks=longer_horizon \\ parallel_tasks.task_names=all use_wandb=True Passing an explicit list (e.g. parallel_tasks.task_names=[task_a,task_b] ) still runs only that subset. You can also select a task group to run via tasks=longer_horizon parallel_tasks.task_names=all .","title":"Launch Agent(s) Across Multiple Tasks"},{"location":"#running-across-goal-variations","text":"Every task ships with goal variations \u2014 the same task with the goal reworded in a different style. Styles are casual , formal , and unrelated_context (the instruction wrapped in unrelated chit-chat), with 9 variations per task. They live in config/tasks/user_goal_variations.yaml , keyed <original_task>__<style>_<n> (e.g. add_meeting_with_dennis__formal_1 ), and each one preserves the original task's reward \u2014 only the goal wording differs and a goal_style field records the style. To run agents across all tasks and their goal variations in parallel, use the dedicated config, which lists every task name swept over a single default app variation: uv run launch_parallel_agents . py \\ -- config - name = config_parallel_tasks_across_goal_variations mode = slurm_cluster Use mode=local to run the jobs sequentially in the current process instead of on SLURM. This expands to one isolated job per goal phrasing, letting you measure how robust an agent is to how the same task is worded.","title":"Running across goal variations"},{"location":"#testing","text":"Run all tests via: uv run - m pytest tests /","title":"Testing"},{"location":"#attribution","text":"Our apps are built on top of several excellent frameworks: FastHTML framework and examples which allowed us to build fully functional apps in Python, the language most familiar to AI researchers. Browser Gym and AgentLab : Spacy : for natural language processing Open Street Maps : for our Maps apps. (and for the optional webshop) we rely on WebShop developed by Princeton University Some icons are have been designed using resources from Flaticon.com Our work is licensed under CC-BY-NC, please refer to the LICENSE file in the top level directory. Copyright \u00a9 Meta Platforms, Inc. See the Terms of Use and Privacy Policy for this project.","title":"Attribution"},{"location":"Intro%20to%20UI%20Agents/","text":"Digital agents open the possibility of AI systems to complete tedious tasks on your behalf. For example, \"add an event to my calendar\" or even more complex multi-step tasks. Yet, today's agents are still not reliable enough for many applications. To get there, we need lots of data for training and evaluation + lots of research to develop new recipes for training and deploying reliable agents. A few definitions to settle you in: Digital (UI) Agent: completes tasks by directly interacting with apps in the same manner as humans (by clicking, scrolling, typing on your behalf) Reward: measures whether the agent completed the given task Agents under the hood Digital agents are powered by a foundation model that can understand both text and image inputs. Agents receive a screenshot of the current apps (in the same manner a human sees them) and the task goal (\"delete Brooklyn Bridge from my favorite places\"); depending on how you configure the agent, the agent can also track past actions or observations. The agent then outputs an action such as click or type that directly affects the apps. Throughout the interaction we monitor whether the action has completed the task to terminate the loop or a max_steps is reached. You can view configs for configs/agents/default.yaml containing: list of actions use_axtree : produces simplified text representation of each app states as an input use_screenshot : provides screenshot of app as an input save_som : if true, saves set of marks in log_outputs/<timestamp>/set_of_marks_coordinates.json json (see example below) You can view UI-Tars-1.5-7B.yaml as an example of native computer-use which uses screenshots to output click, type, actions with coordinates. For an example of a multimodal agent that accepts simplified text inputs see GPT-5.1.yaml . OpenApps: building blocks for digital agent research OpenApps offers an easy to use environment that runs on one CPU written in Python for stuyding digital agents. OpenApps comes with six configurable apps for generating limitless data for training and evaluating digital agents. Hands on with OpenApps Learn how to set up OpenApps, run a GPT-5 agent and make changes to the envrionment.","title":"Intro to UI Agents"},{"location":"Intro%20to%20UI%20Agents/#agents-under-the-hood","text":"Digital agents are powered by a foundation model that can understand both text and image inputs. Agents receive a screenshot of the current apps (in the same manner a human sees them) and the task goal (\"delete Brooklyn Bridge from my favorite places\"); depending on how you configure the agent, the agent can also track past actions or observations. The agent then outputs an action such as click or type that directly affects the apps. Throughout the interaction we monitor whether the action has completed the task to terminate the loop or a max_steps is reached. You can view configs for configs/agents/default.yaml containing: list of actions use_axtree : produces simplified text representation of each app states as an input use_screenshot : provides screenshot of app as an input save_som : if true, saves set of marks in log_outputs/<timestamp>/set_of_marks_coordinates.json json (see example below) You can view UI-Tars-1.5-7B.yaml as an example of native computer-use which uses screenshots to output click, type, actions with coordinates. For an example of a multimodal agent that accepts simplified text inputs see GPT-5.1.yaml .","title":"Agents under the hood"},{"location":"Intro%20to%20UI%20Agents/#openapps-building-blocks-for-digital-agent-research","text":"OpenApps offers an easy to use environment that runs on one CPU written in Python for stuyding digital agents. OpenApps comes with six configurable apps for generating limitless data for training and evaluating digital agents.","title":"OpenApps: building blocks for digital agent research"},{"location":"Intro%20to%20UI%20Agents/#hands-on-with-openapps","text":"Learn how to set up OpenApps, run a GPT-5 agent and make changes to the envrionment.","title":"Hands on with OpenApps"},{"location":"agents/","text":"Quickstart: Getting Your Agent to Run Prerequisites To use GPT-5-1 to complete tasks, set your OpenAI API key: export OPENAI_API_KEY = YOUR_KEY Alternatively, edit the corresponding line in config/agent/GPT-5-1.yaml . Supported Clients We support multiple client types: vLLM OpenAI Azure AWS To use a different client, change the client_type argument in your configuration. Check out /src/open_apps/agent/vLLM_agent.py Line 49 and following for specifics about how these clients are called internally. Running Your Agent uv run launch_agent.py agent = GPT-4o To run a local model with vLLM , Launch your local vLLM model: vllm serve [MODEL_NAME] . VLLM will tell you your hostname. Launch your agent uv run launch_agent.py agent = AGENT_CONFIG agent.hostname = VLLM_HOSTNAME Configuring Your Policy Our agent policies are built on top of AgentLab . Our setup enables automatic configuration of your prompt with config flags. Here are some key flags you can configure in your agent's YAML file: Observation Flags: use_axtree : Enable AXTree observation (accessibility tree) use_screenshot : Enable screenshot observation use_som : Add visual marks to screenshots for element identification extract_coords : Include element coordinates in observations History & Memory Flags: use_history : Enable action/thought history tracking use_action_history : Track previous actions taken by the agent use_think_history : Track previous thoughts/reasoning steps Reasoning & Examples Flags: use_thinking : Enable chain-of-thought reasoning before actions use_concrete_example : Include concrete examples in the prompt use_abstract_example : Include abstract reasoning examples in the prompt Custom Prompts: prompt_txt.system_prompt : Override the default system prompt prompt_txt.action_prompt : Define custom action instructions prompt_txt.think_prompt : Define custom thinking/reasoning instructions For the complete set of configuration options, see config/agent/default.yaml . Creating Your Own Agent If AgentLab's capabilities don't meet your needs, you can create a custom agent. Navigate to src/open_apps/agent/ Copy and modify the following files: vLLM_agent.py vLLM_prompt.py This allows you to build rich, custom agent implementations tailored to your specific requirements. Running Evals on a Cluster (SLURM + vLLM + W&B) The workflow consists of two jobs: A persistent vLLM GPU job that serves the model on :8000 . An eval CPU job ( sbatch scripts/conduct_slurm.sh ) that auto-discovers the vLLM node and runs the worker pool against it. One-time cluster setup The repo needs to live on shared storage (e.g. /example/dir/$USER or /storage/home/$USER ). On a login node: # Bring the repo over. Use rsync if you have uncommitted local changes (e.g. # scripts/conduct.sh) that aren't pushed yet: rsync -av --exclude .venv /path/to/local/OpenApps/ /example/dir/ $USER /OpenApps/ # ...or clone it fresh: # git clone <repo-url> /example/dir/$USER/OpenApps cd /example/dir/ $USER /OpenApps # Python env curl -LsSf https://astral.sh/uv/install.sh | sh # install uv if needed uv sync # Headless browser uv run playwright install chromium uv run playwright install-deps chromium # system deps (may need sudo/module) # App setup (OpenJDK 21 for onlineshop, dataset via gdown, spaCy en_core_web_lg) ./setup.sh # Secrets \u2014 do NOT commit this file cat > .env <<'EOF' OPENAI_API_KEY=sk-... WANDB_BASE_URL=... WANDB_API_KEY=... EOF launch_agent.py calls load_dotenv() , so .env is picked up automatically. 1. Launch the persistent vLLM serve job Give it a generous --time so it isn't killed mid-eval. For example, an interactive allocation: srun --account = example_account --qos = example_qos --partition = example_partition \\ --gpus-per-node = 1 --time = 1440 --pty bash # then, on the GPU node: vllm serve google/gemma-4-E2B-it --host 0 .0.0.0 --port 8000 Confirm it's healthy from its own node: srun --overlap --jobid = <vllm-job> --pty curl -s http://localhost:8000/v1/models # expect: ...google/gemma-4-E2B-it... 2. Submit the eval job scripts/conduct_slurm.sh requests a CPU allocation, finds the vLLM node, and runs scripts/conduct.sh pointed at it with use_wandb=True : # smoke test (1 run) AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh # larger sweep AGENTS = \"gemma-4-e2b-it\" COUNT = 20 MAX_PARALLEL = 4 sbatch scripts/conduct_slurm.sh Discovery: the wrapper lists your running jobs ( squeue --me ), expands their nodelists, excludes the eval node itself, and probes each http://<node>:8000/v1/models , selecting the first one serving google/gemma-4-E2B-it . It probes by serving the model , so it doesn't matter how the vLLM job was started (e.g. a bash -named srun --pty ). Override: skip discovery by pinning the node: VLLM_HOST = example_host AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh Other env overrides: VLLM_MODEL , VLLM_PORT , and WANDB_MODE (set WANDB_MODE=offline to skip online logging). Extra CLI args are forwarded verbatim to launch_agent.py as Hydra overrides. Fallback if compute\u2192compute :8000 is firewalled: run the eval inside the vLLM job's own allocation and talk to it over localhost: srun --overlap --jobid = <vllm-job> \\ env AGENTS = gemma-4-e2b-it COUNT = 1 VLLM_HOST = localhost \\ ./scripts/conduct.sh agent.hostname = localhost use_wandb = True 3. Check results SLURM log: slurm-<jobid>.out \u2014 confirm discovery selected the vLLM node and there are no \"Connection error\" messages. Per-run logs: log_outputs/<stamp>/run-*.log \u2014 confirm an action is produced. W&B: a run should appear in open_apps_${USER} (i.e. open_apps_aaronsmulktis ) with the expected group / job_type and a logged web_app_url .","title":"Agents"},{"location":"agents/#quickstart-getting-your-agent-to-run","text":"","title":"Quickstart: Getting Your Agent to Run"},{"location":"agents/#prerequisites","text":"To use GPT-5-1 to complete tasks, set your OpenAI API key: export OPENAI_API_KEY = YOUR_KEY Alternatively, edit the corresponding line in config/agent/GPT-5-1.yaml .","title":"Prerequisites"},{"location":"agents/#supported-clients","text":"We support multiple client types: vLLM OpenAI Azure AWS To use a different client, change the client_type argument in your configuration. Check out /src/open_apps/agent/vLLM_agent.py Line 49 and following for specifics about how these clients are called internally.","title":"Supported Clients"},{"location":"agents/#running-your-agent","text":"uv run launch_agent.py agent = GPT-4o To run a local model with vLLM , Launch your local vLLM model: vllm serve [MODEL_NAME] . VLLM will tell you your hostname. Launch your agent uv run launch_agent.py agent = AGENT_CONFIG agent.hostname = VLLM_HOSTNAME","title":"Running Your Agent"},{"location":"agents/#configuring-your-policy","text":"Our agent policies are built on top of AgentLab . Our setup enables automatic configuration of your prompt with config flags. Here are some key flags you can configure in your agent's YAML file: Observation Flags: use_axtree : Enable AXTree observation (accessibility tree) use_screenshot : Enable screenshot observation use_som : Add visual marks to screenshots for element identification extract_coords : Include element coordinates in observations History & Memory Flags: use_history : Enable action/thought history tracking use_action_history : Track previous actions taken by the agent use_think_history : Track previous thoughts/reasoning steps Reasoning & Examples Flags: use_thinking : Enable chain-of-thought reasoning before actions use_concrete_example : Include concrete examples in the prompt use_abstract_example : Include abstract reasoning examples in the prompt Custom Prompts: prompt_txt.system_prompt : Override the default system prompt prompt_txt.action_prompt : Define custom action instructions prompt_txt.think_prompt : Define custom thinking/reasoning instructions For the complete set of configuration options, see config/agent/default.yaml .","title":"Configuring Your Policy"},{"location":"agents/#creating-your-own-agent","text":"If AgentLab's capabilities don't meet your needs, you can create a custom agent. Navigate to src/open_apps/agent/ Copy and modify the following files: vLLM_agent.py vLLM_prompt.py This allows you to build rich, custom agent implementations tailored to your specific requirements.","title":"Creating Your Own Agent"},{"location":"agents/#running-evals-on-a-cluster-slurm-vllm-wb","text":"The workflow consists of two jobs: A persistent vLLM GPU job that serves the model on :8000 . An eval CPU job ( sbatch scripts/conduct_slurm.sh ) that auto-discovers the vLLM node and runs the worker pool against it.","title":"Running Evals on a Cluster (SLURM + vLLM + W&amp;B)"},{"location":"agents/#one-time-cluster-setup","text":"The repo needs to live on shared storage (e.g. /example/dir/$USER or /storage/home/$USER ). On a login node: # Bring the repo over. Use rsync if you have uncommitted local changes (e.g. # scripts/conduct.sh) that aren't pushed yet: rsync -av --exclude .venv /path/to/local/OpenApps/ /example/dir/ $USER /OpenApps/ # ...or clone it fresh: # git clone <repo-url> /example/dir/$USER/OpenApps cd /example/dir/ $USER /OpenApps # Python env curl -LsSf https://astral.sh/uv/install.sh | sh # install uv if needed uv sync # Headless browser uv run playwright install chromium uv run playwright install-deps chromium # system deps (may need sudo/module) # App setup (OpenJDK 21 for onlineshop, dataset via gdown, spaCy en_core_web_lg) ./setup.sh # Secrets \u2014 do NOT commit this file cat > .env <<'EOF' OPENAI_API_KEY=sk-... WANDB_BASE_URL=... WANDB_API_KEY=... EOF launch_agent.py calls load_dotenv() , so .env is picked up automatically.","title":"One-time cluster setup"},{"location":"agents/#1-launch-the-persistent-vllm-serve-job","text":"Give it a generous --time so it isn't killed mid-eval. For example, an interactive allocation: srun --account = example_account --qos = example_qos --partition = example_partition \\ --gpus-per-node = 1 --time = 1440 --pty bash # then, on the GPU node: vllm serve google/gemma-4-E2B-it --host 0 .0.0.0 --port 8000 Confirm it's healthy from its own node: srun --overlap --jobid = <vllm-job> --pty curl -s http://localhost:8000/v1/models # expect: ...google/gemma-4-E2B-it...","title":"1. Launch the persistent vLLM serve job"},{"location":"agents/#2-submit-the-eval-job","text":"scripts/conduct_slurm.sh requests a CPU allocation, finds the vLLM node, and runs scripts/conduct.sh pointed at it with use_wandb=True : # smoke test (1 run) AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh # larger sweep AGENTS = \"gemma-4-e2b-it\" COUNT = 20 MAX_PARALLEL = 4 sbatch scripts/conduct_slurm.sh Discovery: the wrapper lists your running jobs ( squeue --me ), expands their nodelists, excludes the eval node itself, and probes each http://<node>:8000/v1/models , selecting the first one serving google/gemma-4-E2B-it . It probes by serving the model , so it doesn't matter how the vLLM job was started (e.g. a bash -named srun --pty ). Override: skip discovery by pinning the node: VLLM_HOST = example_host AGENTS = gemma-4-e2b-it COUNT = 1 sbatch scripts/conduct_slurm.sh Other env overrides: VLLM_MODEL , VLLM_PORT , and WANDB_MODE (set WANDB_MODE=offline to skip online logging). Extra CLI args are forwarded verbatim to launch_agent.py as Hydra overrides. Fallback if compute\u2192compute :8000 is firewalled: run the eval inside the vLLM job's own allocation and talk to it over localhost: srun --overlap --jobid = <vllm-job> \\ env AGENTS = gemma-4-e2b-it COUNT = 1 VLLM_HOST = localhost \\ ./scripts/conduct.sh agent.hostname = localhost use_wandb = True","title":"2. Submit the eval job"},{"location":"agents/#3-check-results","text":"SLURM log: slurm-<jobid>.out \u2014 confirm discovery selected the vLLM node and there are no \"Connection error\" messages. Per-run logs: log_outputs/<stamp>/run-*.log \u2014 confirm an action is produced. W&B: a run should appear in open_apps_${USER} (i.e. open_apps_aaronsmulktis ) with the expected group / job_type and a logged web_app_url .","title":"3. Check results"},{"location":"installation/","text":"Pre-requisite: install uv (a much faster pip): pip install uv (or from source ) 0) Clone repo 1) Install packages: uv sync 2) Activate environment: source .venv/bin/activate 3) Install playwright install chromium Optionally install for onlineshop (off by default) Onlineshop java + spacy configuration 4) Prepare Java, Webshop data and spacy model: chmod +x setup.sh and ./setup.sh for Linux X64 or Mac ARM64 systems 5) Designate Java path: source setup_javapath.sh for Linux X64 or Mac ARM64 systems 6) Check java -version gives you java version \"21.0.1\" 7) Build search engine indexes: chmod +x setup_pyserini.sh and ./setup_pyserini.sh Congratulations! The onlineshop is ready to be used. Remember in future, always run source setup_javapath.sh to configure Java path before launching onlineshop-related tasks. Finally, launch with uv run launch.py apps.onlineshop.enable=True","title":"Manual Installation"},{"location":"tasks/","text":"To ask GPT-4o to mark water plants as done in your todo list: # export OPENAI_API_KEY=\"\" uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done task_name specifies the task. Tasks are defined in config/tasks/all_tasks.yaml . For example, mark_water_plants_as_done : # Indicates class where reward logic is defined _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : Mark 'Water plants' as done in my todo list. todo_name : \"Water plants\" Adding New Tasks To add a new task using an existing reward function, simply add a new entry to the config/tasks/all_tasks.yaml : add_my_special_item_to_todo : # _target_ defines the class containing the task reward logic _target_ : open_apps.tasks.tasks.AddToDoTask goal : ENTER YOUR GOAL todo_name : ENTER TITLE of TODO is_done : false You can select this new task by specifying the task_name=add_my_special_item_todo . New custom tasks To add a custom task with its own reward logic, create a new class in src/open_apps/tasks/tasks.py . Your new class should inherit Task and implement a reward function, check_if_task_is_complete , indicating whether the task is complete: @dataclass class MyCustomTask ( Task ): def check_if_task_is_complete ( self , initiate_state : dict , current_state : dict ) -> bool : # we handle providing the initial and current states for you! # write your custom reward logic ... Then create a corresponding entry in config/tasks/all_tasks.yaml : my_custom_task : _target_ : open_apps.tasks.tasks.MyCustomTask goal : ENTER Finally, ask your agent to solve the task by specifying task_name=my_custom_task . Goal Variations Tasks come with goal variations : the same task with its goal reworded in a different style, so you can study how robust an agent is to phrasing. There are three styles \u2014 casual , formal , and unrelated_context (the instruction embedded in unrelated chit-chat) \u2014 with 9 variations per task. Tasks are split across two files, both composed into all_tasks.yaml : config/tasks/original_tasks.yaml \u2014 the base tasks. config/tasks/user_goal_variations.yaml \u2014 the variations, keyed <original_task>__<style>_<n> (e.g. mark_water_plants_as_done__casual_2 ). Every variation copies its original's fields verbatim \u2014 only the goal is reworded, and an optional goal_style field records the style \u2014 so the reward logic is identical to the base task: mark_water_plants_as_done__casual_2 : _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : can you check off 'Water plants' in my to-do list? todo_name : \"Water plants\" goal_style : casual Run a single variation like any other task: uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done__casual_2 To run agents across all tasks and their goal variations in parallel, use the config_parallel_tasks_across_goal_variations.yaml config \u2014 see Launch Agent(s) Across Multiple Tasks .","title":"Tasks"},{"location":"tasks/#adding-new-tasks","text":"To add a new task using an existing reward function, simply add a new entry to the config/tasks/all_tasks.yaml : add_my_special_item_to_todo : # _target_ defines the class containing the task reward logic _target_ : open_apps.tasks.tasks.AddToDoTask goal : ENTER YOUR GOAL todo_name : ENTER TITLE of TODO is_done : false You can select this new task by specifying the task_name=add_my_special_item_todo .","title":"Adding New Tasks"},{"location":"tasks/#new-custom-tasks","text":"To add a custom task with its own reward logic, create a new class in src/open_apps/tasks/tasks.py . Your new class should inherit Task and implement a reward function, check_if_task_is_complete , indicating whether the task is complete: @dataclass class MyCustomTask ( Task ): def check_if_task_is_complete ( self , initiate_state : dict , current_state : dict ) -> bool : # we handle providing the initial and current states for you! # write your custom reward logic ... Then create a corresponding entry in config/tasks/all_tasks.yaml : my_custom_task : _target_ : open_apps.tasks.tasks.MyCustomTask goal : ENTER Finally, ask your agent to solve the task by specifying task_name=my_custom_task .","title":"New custom tasks"},{"location":"tasks/#goal-variations","text":"Tasks come with goal variations : the same task with its goal reworded in a different style, so you can study how robust an agent is to phrasing. There are three styles \u2014 casual , formal , and unrelated_context (the instruction embedded in unrelated chit-chat) \u2014 with 9 variations per task. Tasks are split across two files, both composed into all_tasks.yaml : config/tasks/original_tasks.yaml \u2014 the base tasks. config/tasks/user_goal_variations.yaml \u2014 the variations, keyed <original_task>__<style>_<n> (e.g. mark_water_plants_as_done__casual_2 ). Every variation copies its original's fields verbatim \u2014 only the goal is reworded, and an optional goal_style field records the style \u2014 so the reward logic is identical to the base task: mark_water_plants_as_done__casual_2 : _target_ : open_apps.tasks.tasks.MarkToDoDoneTask goal : can you check off 'Water plants' in my to-do list? todo_name : \"Water plants\" goal_style : casual Run a single variation like any other task: uv run launch_agent.py agent = GPT-5-1 task_name = mark_water_plants_as_done__casual_2 To run agents across all tasks and their goal variations in parallel, use the config_parallel_tasks_across_goal_variations.yaml config \u2014 see Launch Agent(s) Across Multiple Tasks .","title":"Goal Variations"}]}
\ No newline at end of file
diff --git a/site/sitemap.xml b/site/sitemap.xml
index 50f32dae..1eb5e9f2 100644
--- a/site/sitemap.xml
+++ b/site/sitemap.xml
@@ -2,42 +2,22 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/</loc>
-<<<<<<< HEAD
-         <lastmod>2026-04-13</lastmod>
+         <lastmod>2026-09-17</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/Intro%20to%20UI%20Agents/</loc>
-         <lastmod>2026-04-13</lastmod>
+         <lastmod>2026-09-17</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/agents/</loc>
-         <lastmod>2026-04-13</lastmod>
+         <lastmod>2026-09-17</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/installation/</loc>
-         <lastmod>2026-04-13</lastmod>
+         <lastmod>2026-09-17</lastmod>
     </url>
     <url>
          <loc>https://facebookresearch.github.io/OpenApps/tasks/</loc>
-         <lastmod>2026-04-13</lastmod>
-=======
-         <lastmod>2026-04-03</lastmod>
-    </url>
-    <url>
-         <loc>https://facebookresearch.github.io/OpenApps/Intro%20to%20UI%20Agents/</loc>
-         <lastmod>2026-04-03</lastmod>
-    </url>
-    <url>
-         <loc>https://facebookresearch.github.io/OpenApps/agents/</loc>
-         <lastmod>2026-04-03</lastmod>
-    </url>
-    <url>
-         <loc>https://facebookresearch.github.io/OpenApps/installation/</loc>
-         <lastmod>2026-04-03</lastmod>
-    </url>
-    <url>
-         <loc>https://facebookresearch.github.io/OpenApps/tasks/</loc>
-         <lastmod>2026-04-03</lastmod>
->>>>>>> 655adeaf76133621c1ecd692ac0ef1bce96f2815
+         <lastmod>2026-09-17</lastmod>
     </url>
 </urlset>
\ No newline at end of file
diff --git a/site/sitemap.xml.gz b/site/sitemap.xml.gz
index df7eecbe..87f56e63 100644
Binary files a/site/sitemap.xml.gz and b/site/sitemap.xml.gz differ
diff --git a/site/tasks.md b/site/tasks.md
new file mode 100644
index 00000000..ccd20b49
--- /dev/null
+++ b/site/tasks.md
@@ -0,0 +1,97 @@
+
+To ask GPT-4o to mark water plants as done in your todo list:
+
+```shell
+# export OPENAI_API_KEY=""
+uv run launch_agent.py agent=GPT-5-1 task_name=mark_water_plants_as_done
+```
+
+`task_name` specifies the task. Tasks are defined in `config/tasks/all_tasks.yaml`. For example,
+
+```yaml
+mark_water_plants_as_done:
+  # Indicates class where reward logic is defined
+  _target_: open_apps.tasks.tasks.MarkToDoDoneTask
+  goal: Mark 'Water plants' as done in my todo list.
+  todo_name: "Water plants"
+```
+
+## Adding New Tasks
+
+To add a new task using an existing reward function, simply add a new entry to the `config/tasks/all_tasks.yaml`:
+
+```yaml
+add_my_special_item_to_todo:
+  # _target_ defines the class containing the task reward logic
+  _target_: open_apps.tasks.tasks.AddToDoTask
+  goal: ENTER YOUR GOAL
+  todo_name: ENTER TITLE of TODO
+  is_done: false
+```
+
+You can select this new task by specifying the `task_name=add_my_special_item_todo`.
+
+
+### New custom tasks
+
+To add a custom task with its own reward logic, create a new class in `src/open_apps/tasks/tasks.py`.
+
+Your new class should inherit `Task` and implement a reward function, `check_if_task_is_complete`, indicating whether the task is complete:
+
+
+```python
+@dataclass
+class MyCustomTask(Task):
+	def check_if_task_is_complete(
+		self, 
+		initiate_state: dict, 
+		current_state: dict) -> bool:
+		# we handle providing the initial and current states for you!
+		# write your custom reward logic
+		...
+```
+
+Then create a corresponding entry in `config/tasks/all_tasks.yaml`:
+
+```yaml
+my_custom_task:
+	_target_: open_apps.tasks.tasks.MyCustomTask
+	goal: ENTER
+```
+
+Finally, ask your agent to solve the task by specifying `task_name=my_custom_task`.
+
+## Goal Variations
+
+Tasks come with **goal variations**: the same task with its goal reworded in a
+different style, so you can study how robust an agent is to phrasing. There are
+three styles — `casual`, `formal`, and `unrelated_context` (the instruction
+embedded in unrelated chit-chat) — with 9 variations per task.
+
+Tasks are split across two files, both composed into `all_tasks.yaml`:
+
+* `config/tasks/original_tasks.yaml` — the base tasks.
+* `config/tasks/user_goal_variations.yaml` — the variations, keyed
+  `<original_task>__<style>_<n>` (e.g. `mark_water_plants_as_done__casual_2`).
+
+Every variation copies its original's fields verbatim — only the `goal` is
+reworded, and an optional `goal_style` field records the style — so the reward
+logic is identical to the base task:
+
+```yaml
+mark_water_plants_as_done__casual_2:
+  _target_: open_apps.tasks.tasks.MarkToDoDoneTask
+  goal: can you check off 'Water plants' in my to-do list?
+  todo_name: "Water plants"
+  goal_style: casual
+```
+
+Run a single variation like any other task:
+
+```shell
+uv run launch_agent.py agent=GPT-5-1 task_name=mark_water_plants_as_done__casual_2
+```
+
+To run agents across **all** tasks and their goal variations in parallel, use
+the `config_parallel_tasks_across_goal_variations.yaml` config — see
+[Launch Agent(s) Across Multiple Tasks](index.md#launch-agents-across-multiple-tasks).
diff --git a/site/tasks/index.html b/site/tasks/index.html
index 00231596..d4a4d370 100644
--- a/site/tasks/index.html
+++ b/site/tasks/index.html
@@ -490,6 +490,34 @@ <h3 id="new-custom-tasks">New custom tasks</h3>
 </code></pre></div>
 
 <p>Finally, ask your agent to solve the task by specifying <code>task_name=my_custom_task</code>.</p>
+<h2 id="goal-variations">Goal Variations</h2>
+<p>Tasks come with <strong>goal variations</strong>: the same task with its goal reworded in a
+different style, so you can study how robust an agent is to phrasing. There are
+three styles — <code>casual</code>, <code>formal</code>, and <code>unrelated_context</code> (the instruction
+embedded in unrelated chit-chat) — with 9 variations per task.</p>
+<p>Tasks are split across two files, both composed into <code>all_tasks.yaml</code>:</p>
+<ul>
+<li><code>config/tasks/original_tasks.yaml</code> — the base tasks.</li>
+<li><code>config/tasks/user_goal_variations.yaml</code> — the variations, keyed
+  <code>&lt;original_task&gt;__&lt;style&gt;_&lt;n&gt;</code> (e.g. <code>mark_water_plants_as_done__casual_2</code>).</li>
+</ul>
+<p>Every variation copies its original's fields verbatim — only the <code>goal</code> is
+reworded, and an optional <code>goal_style</code> field records the style — so the reward
+logic is identical to the base task:</p>
+<div class="codehilite"><pre><span></span><code><span class="nt">mark_water_plants_as_done__casual_2</span><span class="p">:</span>
+<span class="w">  </span><span class="nt">_target_</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">open_apps.tasks.tasks.MarkToDoDoneTask</span>
+<span class="w">  </span><span class="nt">goal</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">can you check off &#39;Water plants&#39; in my to-do list?</span>
+<span class="w">  </span><span class="nt">todo_name</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;Water</span><span class="nv"> </span><span class="s">plants&quot;</span>
+<span class="w">  </span><span class="nt">goal_style</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">casual</span>
+</code></pre></div>
+
+<p>Run a single variation like any other task:</p>
+<div class="codehilite"><pre><span></span><code>uv<span class="w"> </span>run<span class="w"> </span>launch_agent.py<span class="w"> </span><span class="nv">agent</span><span class="o">=</span>GPT-5-1<span class="w"> </span><span class="nv">task_name</span><span class="o">=</span>mark_water_plants_as_done__casual_2
+</code></pre></div>
+
+<p>To run agents across <strong>all</strong> tasks and their goal variations in parallel, use
+the <code>config_parallel_tasks_across_goal_variations.yaml</code> config — see
+<a href="../#launch-agents-across-multiple-tasks">Launch Agent(s) Across Multiple Tasks</a>.</p>
   </div>
 </article>
                                 <div class="mx-auto flex flex-wrap h-16 w-full max-w-2xl items-center gap-2 px-4 md:px-0">
@@ -576,12 +604,28 @@ <h3 id="new-custom-tasks">New custom tasks</h3>
         
         
         
-        <a href="#new-custom-tasks"
+        <a href="#adding-new-tasks"
             class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
             data-active="false" data-depth="2">
+            Adding New Tasks
+        </a>
+        
+        
+        <a href="#new-custom-tasks"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="3">
             New custom tasks
         </a>
         
+        
+
+        
+        <a href="#goal-variations"
+            class="text-muted-foreground hover:text-foreground data-[active=true]:text-foreground text-[0.8rem] no-underline transition-colors data-[depth=3]:pl-4 data-[depth=4]:pl-6"
+            data-active="false" data-depth="2">
+            Goal Variations
+        </a>
+        
 
         
         
diff --git a/src/open_apps/apps/calendar_app/main.py b/src/open_apps/apps/calendar_app/main.py
index 1b568f9b..f72886db 100644
--- a/src/open_apps/apps/calendar_app/main.py
+++ b/src/open_apps/apps/calendar_app/main.py
@@ -13,6 +13,7 @@
     HighlightJS, database, dataclass)
 from datetime import datetime, timedelta
 from src.open_apps.frontend import local_hdrs
+from src.open_apps.theme import render_theme_css, resolve_theme
 import calendar
 import os
 import logging
@@ -29,160 +30,136 @@
 # fix relative path issue
 current_dir = os.path.dirname(os.path.abspath(__file__))
 
-def generate_styles_from_config(config):
-    """Generate CSS styles from configuration"""
-    if not hasattr(config.calendar, 'style'):
-        raise ValueError("Calendar config does not contain 'style' section")
-    
-    # Extract style config
-    style_config = config.calendar.style
-    colors = style_config.colors
-    typography = style_config.typography
-    buttons = style_config.buttons
-    layout = style_config.layout
-    
-    # Build CSS with variables
-    return f"""
-        /* Custom CSS Variables */
-        :root {{
-            --primary: {colors.primary};
-            --primary-hover: {colors.primary_hover};
-            --secondary: {colors.secondary};
-            --background: {colors.background};
-            --text: {colors.text};
-            --error: {colors.error};
-            --border: {colors.border};
-            --font-family: {typography.font_family};
-            --heading-font: {typography.heading_font};
-            --base-font-size: {typography.base_font_size};
-            --heading-size: {typography.heading_size};
-            --button-border-radius: {buttons.border_radius};
-            --button-padding: {buttons.padding};
-            --container-width: {layout.container_width};
-            --spacing: {layout.spacing};
-        }}
-        
-        /* Base styles */
-        body {{
-            font-family: var(--font-family);
-            font-size: var(--base-font-size);
-            color: var(--text);
-            background-color: var(--background);
-        }}
-        
-        h1, h2, h3, h4, h5, h6 {{
-            font-family: var(--heading-font);
-        }}
-        
-        h1 {{
-            font-size: var(--heading-size);
-        }}
-        
-        /* Button styles */
-        [role="button"], button {{
-            border-radius: var(--button-border-radius);
-            padding: var(--button-padding);
-        }}
-        
-        /* Apply primary color to buttons */
-        [role="button"]:not(.outline):not(.secondary),
-        button:not(.outline):not(.secondary) {{
-            background-color: var(--primary);
-            border-color: var(--primary);
-        }}
-        
-        /* Apply hover state for primary buttons */
-        [role="button"]:not(.outline):not(.secondary):hover,
-        button:not(.outline):not(.secondary):hover {{
-            background-color: var(--primary-hover);
-            border-color: var(--primary-hover);
-        }}
-        
-        /* Secondary buttons */
-        [role="button"].secondary,
-        button.secondary {{
-            background-color: var(--secondary);
-            border-color: var(--secondary);
-        }}
-        
-        /* Apply border color to form elements */
-        input, select, textarea {{
-            border: 1px solid var(--border);
-            border-radius: var(--button-border-radius);
-        }}
-
-        [role="button"].outline,
-        button.outline {{
-            background-color: var(--background);
-            border-color: var(--border);
-            color: var(--primary);
-        }}
-        
-        /* Apply container width */
-        #calendar-container {{
-            width: var(--container-width);
-            margin: 0 auto;
-        }}
-        
-        /* Apply border color to tables */
-        table, th, td {{
-            border-color: var(--border);
-        }}
-        
-        /* Calendar days */
-        .calendar-cell {{
-            border: 1px solid var(--border);
-            background-color: var(--background);
-        }}
-        
-        /* Links */
-        a:not([role="button"]) {{
-            color: var(--primary);
-        }}
-        
-        a:not([role="button"]):hover {{
-            color: var(--primary-hover);
-        }}
-        
-        /* Calendar app specific styles */
-        .logo-title-container {{
-            display: flex;
-            align-items: center;
-            text-decoration: none;
-        }}
-        
-        .custom-logo {{
-            max-height: 50px;
-            margin-right: 10px;
-        }}
-        .calendar-title {{
-            margin: 0;
-            color: var(--primary);
-        }}
-        
-        .logo-title-container a {{
-            text-decoration: none;
-        }}
-        
-        .button-container {{
-            display: flex;
-            justify-content: space-between;
-            margin-top: var(--spacing);
-        }}
-        
-        .error-message {{
-            background-color: rgba(220, 53, 69, 0.1);
-            color: var(--error);
-            padding: var(--spacing);
-            margin-bottom: var(--spacing);
-            border-radius: var(--button-border-radius);
-            text-align: center;
-        }}
-    """
+# Static, theme-agnostic component styles. Every color, font and radius is a
+# design token from the shared theme (`config/apps/theme/`), resolved
+# per-request by `calendar_theme()`; the three structural values the calendar
+# owns come from its `layout` group as `--layout-*`. Nothing here depends on
+# the config, so this block is built once at import instead of rebuilt in
+# `set_environment`.
+_COMPONENT_CSS = """
+    /* Base styles */
+    body {
+        font-family: var(--font-family);
+        font-size: var(--font-size-base);
+        color: var(--color-fg);
+        background-color: var(--color-bg);
+    }
+
+    h1, h2, h3, h4, h5, h6 {
+        font-family: var(--font-heading);
+    }
+
+    h1 {
+        font-size: var(--font-size-heading);
+    }
+
+    /* Button styles */
+    [role="button"], button {
+        border-radius: var(--radius);
+        padding: var(--layout-button-padding);
+    }
+
+    /* Apply primary color to buttons */
+    [role="button"]:not(.outline):not(.secondary),
+    button:not(.outline):not(.secondary) {
+        background-color: var(--color-primary);
+        border-color: var(--color-primary);
+        color: var(--color-on-primary);
+    }
+
+    /* Apply hover state for primary buttons */
+    [role="button"]:not(.outline):not(.secondary):hover,
+    button:not(.outline):not(.secondary):hover {
+        background-color: var(--color-primary-hover);
+        border-color: var(--color-primary-hover);
+    }
+
+    /* Secondary buttons */
+    [role="button"].secondary,
+    button.secondary {
+        background-color: var(--color-neutral);
+        border-color: var(--color-neutral);
+        color: var(--color-btn-fg);
+    }
+
+    /* Apply border color to form elements */
+    input, select, textarea {
+        border: 1px solid var(--color-border);
+        border-radius: var(--radius);
+        background-color: var(--color-bg);
+        color: var(--color-fg);
+    }
+
+    [role="button"].outline,
+    button.outline {
+        background-color: var(--color-bg);
+        border-color: var(--color-border);
+        color: var(--color-primary);
+    }
+
+    /* Apply container width */
+    #calendar-container {
+        width: var(--layout-container-width);
+        margin: 0 auto;
+    }
+
+    /* Apply border color to tables */
+    table, th, td {
+        border-color: var(--color-border);
+    }
+
+    /* Calendar days */
+    .calendar-cell {
+        border: 1px solid var(--color-border);
+        background-color: var(--color-surface);
+    }
+
+    /* Links */
+    a:not([role="button"]) {
+        color: var(--color-primary);
+    }
+
+    a:not([role="button"]):hover {
+        color: var(--color-primary-hover);
+    }
+
+    /* Calendar app specific styles */
+    .logo-title-container {
+        display: flex;
+        align-items: center;
+        text-decoration: none;
+    }
+
+    .custom-logo {
+        max-height: 50px;
+        margin-right: 10px;
+    }
+    .calendar-title {
+        margin: 0;
+        color: var(--color-primary);
+    }
+
+    .logo-title-container a {
+        text-decoration: none;
+    }
+
+    .button-container {
+        display: flex;
+        justify-content: space-between;
+        margin-top: var(--layout-spacing);
+    }
+
+    .error-message {
+        background-color: rgba(220, 53, 69, 0.1);
+        color: var(--color-danger);
+        padding: var(--layout-spacing);
+        margin-bottom: var(--layout-spacing);
+        border-radius: var(--radius);
+        text-align: center;
+    }
+"""
 
-# Initialize with default styles
-# Will be updated in set_environment
-styles = Style("")
+styles = Style(_COMPONENT_CSS)
 
 
 app, rt = fast_app(
@@ -217,12 +194,9 @@ class Event:
 
 def set_environment(config):
     """Set environment variables for the messenger app"""
-    global app, styles, logo_title_container
+    global app, logo_title_container
     app.config = config
-    
-    # Update the styles from config
-    styles = Style(generate_styles_from_config(config))
-    
+
     db = database(config.calendar.database_path)
     # create new events
     global events
@@ -237,6 +211,27 @@ def set_environment(config):
     )
 
 
+def calendar_theme():
+    """The active theme's tokens plus this app's layout variables.
+
+    Resolved per-request so live `reconfigure` theme and layout swaps take
+    effect. The `--layout-*` block is emitted here rather than in
+    `_COMPONENT_CSS` because it is the only part of the stylesheet that
+    depends on config.
+    """
+    layout = app.config.calendar
+    return Style(
+        render_theme_css(resolve_theme(app.config, "calendar"))
+        + f"""
+:root {{
+  --layout-container-width: {layout.container_width};
+  --layout-spacing: {layout.spacing};
+  --layout-button-padding: {layout.button_padding};
+}}
+"""
+    )
+
+
 def update_db_from_hydra():
 
     for event in app.config.calendar.events:
@@ -557,18 +552,18 @@ def show_main_layout(year, month, view="calendar", event_id=None):
     # Add calendar-specific styles that don't come from config
     calendar_specific_styles = Style(
         """
-        .calendar-nav { display: flex; justify-content: space-between; align-items: center; margin-bottom: var(--spacing); }
+        .calendar-nav { display: flex; justify-content: space-between; align-items: center; margin-bottom: var(--layout-spacing); }
         .calendar-nav h2 { margin: 0; }
-        .view-toggle { display: flex; justify-content: center; gap: 10px; margin-bottom: var(--spacing); }
+        .view-toggle { display: flex; justify-content: center; gap: 10px; margin-bottom: var(--layout-spacing); }
         .calendar-table { width: 100%; table-layout: fixed; }
         .calendar-table th { text-align: center; font-weight: bold; }
         .calendar-cell { height: 100px; vertical-align: top; padding: 5px !important; }
         .day-number { font-weight: bold; margin-bottom: 5px; }
         .event-link { display: block; margin-bottom: 2px; font-size: 0.8em; }
         .agenda-list { list-style-type: none; padding: 0; }
-        .agenda-list li { margin-bottom: var(--spacing); }
-        .footer-container { margin-top: var(--spacing); }
-        #about-dialog-content { padding: var(--spacing); }
+        .agenda-list li { margin-bottom: var(--layout-spacing); }
+        .footer-container { margin-top: var(--layout-spacing); }
+        #about-dialog-content { padding: var(--layout-spacing); }
         """
     )
     
@@ -595,6 +590,7 @@ def get(req):
         Title(app.config.start_page.apps.calendar.title),
         Container(
             styles,
+            calendar_theme(),
             error_div, 
             show_main_layout(today.year, today.month, view)
         ),
@@ -626,6 +622,7 @@ def get(
         Title(app.config.start_page.apps.calendar.title),
         Container(
             styles,
+            calendar_theme(),
             show_main_layout(year, month, view)
         )
     )
@@ -707,7 +704,8 @@ def get(id: int):
     return (
         Title(event.title),
         Container(
-            styles,  
+            styles,
+            calendar_theme(),
             logo_title_container,
             Article(
                 H3(event.title),
@@ -770,6 +768,7 @@ def get_input_attrs(field_name: str, defaults: dict) -> dict:
     return (Title("Creating a new event"),
             Container(
         styles,
+        calendar_theme(),
         logo_title_container,
         Form(
             H3("Create New Event"),
diff --git a/src/open_apps/apps/codeeditor_app/main.py b/src/open_apps/apps/codeeditor_app/main.py
index 5c3565a0..096ce6ad 100644
--- a/src/open_apps/apps/codeeditor_app/main.py
+++ b/src/open_apps/apps/codeeditor_app/main.py
@@ -12,6 +12,58 @@
 from starlette.responses import Response
 from src.open_apps.apps.start_page.helper import create_logo_header
 from src.open_apps.frontend import local_hdrs
+from src.open_apps.theme import theme_asset, theme_style
+
+# Static, theme-agnostic component styles. Colors and fonts are design tokens
+# from the shared theme (`config/apps/theme/`), emitted per-request by
+# `codeeditor_theme()`. `!important` throughout because daisyUI ships utility
+# classes on these same elements.
+_COMPONENT_STYLES = Style(
+    """
+    .main-content {
+        background-color: var(--color-bg);
+    }
+    .styled-content {
+        font-size: var(--font-size-sm);
+        font-family: var(--font-family);
+        color: var(--color-fg);
+    }
+    /* The code pane keeps a monospace face regardless of the theme's body
+       font -- column alignment is load-bearing in an editor. */
+    textarea, textarea.styled-content {
+        background-color: var(--color-surface);
+        color: var(--color-fg);
+        font-family: var(--font-mono);
+    }
+    .btn-primary {
+        background-color: var(--color-primary) !important;
+        border-color: var(--color-primary) !important;
+        color: var(--color-on-primary) !important;
+        font-family: var(--font-family) !important;
+    }
+    .btn-secondary {
+        background-color: var(--color-neutral) !important;
+        border-color: var(--color-neutral) !important;
+        color: var(--color-btn-fg) !important;
+        font-family: var(--font-family) !important;
+    }
+    .btn-error {
+        background-color: var(--color-danger) !important;
+        border-color: var(--color-danger) !important;
+        color: var(--color-btn-fg) !important;
+        font-family: var(--font-family) !important;
+    }
+"""
+)
+
+# Set by the in-page theme dropdown; None means "follow the shared theme".
+_editor_theme_override = None
+
+
+def _as_dict(node):
+    """Coerce an OmegaConf node (or None) to a plain dict."""
+    return {k: v for k, v in node.items()} if node is not None else {}
+
 
 # Global variables
 _base_hdrs_no_highlight = (
@@ -99,7 +151,13 @@ def set_environment(config):
         Link(rel="stylesheet", href="https://cdn.jsdelivr.net/npm/daisyui@4.11.1/dist/full.min.css"),
         Link(rel="stylesheet", href="https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.65.2/codemirror.min.css"),
     )
-    for theme_name in list_of_themes:
+    # Every stylesheet the page could ask for, loaded up front: the dropdown
+    # switches themes client-side, and a shared-theme swap can select one by
+    # tone. Include the tone-mapped names even if `list_of_themes` was trimmed,
+    # otherwise `apps/theme=dark` asks CodeMirror for a stylesheet that is not
+    # on the page and the editor silently renders unstyled.
+    tone_themes = list(_as_dict(getattr(config.code_editor, "editor_theme_by_tone", None)).values())
+    for theme_name in dict.fromkeys([*list_of_themes, *tone_themes, config.code_editor.editor_theme]):
         _base_hdrs_with_highlight += (
             Link(rel="stylesheet", href=f"https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.65.2/theme/{theme_name}.min.css"),
         )
@@ -118,62 +176,9 @@ def set_environment(config):
     """),)
     _base_hdrs = _base_hdrs_with_highlight if config.code_editor.highlight else _base_hdrs_no_highlight
     
-    primary_color = getattr(config.code_editor, 'primary_button_color', '#4A90E2')
-    secondary_color = getattr(config.code_editor, 'secondary_button_color', '#50E3C2')
-    danger_color = getattr(config.code_editor, 'danger_button_color', '#D0021B')
-    # grey 800 background as default
-    textarea_background_color = getattr(config.code_editor, 'textarea_background_color', '#2d2d2d')
-    # grey 900 background as default
-    main_background_color = getattr(config.code_editor, 'main_background_color', '#1a202c')
-
-    env_styles = Style(
-        f"""
-        :root {{
-            --custom-font-size: {config.code_editor.font_size}px;
-            --custom-font-family: {config.code_editor.font};
-            --custom-font-color: {config.code_editor.fontcolor};
-            --main-bg-color: {main_background_color};
-        }}
-        .main-content {{
-            background-color: var(--main-bg-color);
-        }}
-        .styled-content {{
-            font-size: var(--custom-font-size);
-            font-family: var(--custom-font-family);
-            color: var(--custom-font-color);
-        }}
-        textarea.styled-content {{
-            font-family: var(--custom-font-family), monospace;
-            color: var(--custom-font-color);
-        }}
-        textarea {{
-            background-color: {textarea_background_color};
-            color: var(--custom-font-color);
-            font-family: var(--custom-font-family);
-        }}
-        .btn-primary {{
-            background-color: {primary_color} !important;
-            border-color: {primary_color} !important;
-            color: var(--custom-font-color) !important;
-            font-family: var(--custom-font-family); !important;
-        }}
-        .btn-secondary {{
-            background-color: {secondary_color} !important;
-            border-color: {secondary_color} !important;
-            color: var(--custom-font-color) !important;
-            font-family: var(--custom-font-family); !important;
-        }}
-        .btn-error {{
-            background-color: {danger_color} !important;
-            border-color: {danger_color} !important;
-            color: var(--custom-font-color) !important;
-            font-family: var(--custom-font-family); !important;
-        }}
-    """
-    )
     app.config = config
     # Update app headers by extending existing ones
-    app.hdrs = (*_base_hdrs, env_styles)
+    app.hdrs = (*_base_hdrs, _COMPONENT_STYLES)
 
     if config.code_editor.sort_feature:
         list_of_modes = sorted(list_of_modes)
@@ -185,6 +190,35 @@ def set_environment(config):
         current_file_path=__file__
     )
 
+def codeeditor_theme():
+    """The active theme's `:root` token block.
+
+    Rendered into the page body (not `app.hdrs`) so live `reconfigure` theme
+    swaps take effect without rebuilding the headers.
+    """
+    return theme_style(app.config, "code_editor")
+
+
+def current_editor_theme():
+    """CodeMirror's syntax-highlighting stylesheet name.
+
+    Not the shared design-token theme -- CodeMirror ships a whole stylesheet
+    per theme, which no CSS variable can substitute for. The shared theme
+    therefore picks one indirectly via its `tone` asset, so `apps/theme=dark`
+    darkens the editor pane and not just the chrome around it.
+
+    An in-page selection from the dropdown wins over the tone mapping: the
+    user (or agent) just asked for that theme explicitly.
+    """
+    if _editor_theme_override is not None:
+        return _editor_theme_override
+    cfg = app.config.code_editor
+    tone = theme_asset(app.config, "code_editor", "tone", "light")
+    return _as_dict(getattr(cfg, "editor_theme_by_tone", None)).get(
+        tone, cfg.editor_theme
+    )
+
+
 def return_to_index():
     return A("Code Editor Index Page", href="/codeeditor", cls="btn btn-primary")
 
@@ -471,7 +505,7 @@ def index():
                             });
                             """
                         )(
-                            *[Option(theme, value=theme, selected=(theme == app.config.code_editor.theme)) for theme in list_of_themes]
+                            *[Option(theme, value=theme, selected=(theme == current_editor_theme())) for theme in list_of_themes]
                         ),
                     ),
                 ),
@@ -486,7 +520,7 @@ def index():
                 Script(f"""
                     var editor = {'CodeMirror.fromTextArea' if app.config.code_editor.highlight else ''} (document.getElementById('editor'), {{
                         mode: '{app.config.code_editor.mode}',
-                        theme: '{app.config.code_editor.theme}',
+                        theme: '{current_editor_theme()}',
                         lineNumbers: true,
                         indentUnit: 4,
                         tabSize: 4,
@@ -517,7 +551,7 @@ def index():
         ),
     )
     page = Div(cls="flex space-x-2")(side_bar, main_screen)
-    return Div(logo_title_container, page)
+    return Div(codeeditor_theme(), logo_title_container, page)
 
 
 @app.get("/codeeditor/{path:path}")
@@ -577,7 +611,7 @@ def get_folder(folder: str):
                                 });
                             """
                         )(
-                            *[Option(theme, value=theme, selected=(theme == app.config.code_editor.theme)) for theme in list_of_themes]
+                            *[Option(theme, value=theme, selected=(theme == current_editor_theme())) for theme in list_of_themes]
                         ),
                     ),
                 ),
@@ -592,7 +626,7 @@ def get_folder(folder: str):
                 Script(f"""
                     var editor = {'CodeMirror.fromTextArea' if app.config.code_editor.highlight else ''} (document.getElementById('editor'), {{
                         mode: '{app.config.code_editor.mode}',
-                        theme: '{app.config.code_editor.theme}',
+                        theme: '{current_editor_theme()}',
                         lineNumbers: true,
                         readOnly: true
                     }});
@@ -623,7 +657,7 @@ def get_folder(folder: str):
         ),
     )
     page = Div(cls="flex space-x-2")(side_bar, main_screen)
-    return Div(logo_title_container, page)
+    return Div(codeeditor_theme(), logo_title_container, page)
 
 def get_file(file: str):
     side_bar = create_sidebar(file)
@@ -841,7 +875,7 @@ def get_file(file: str):
                                 });
                             """
                         )(
-                            *[Option(theme, value=theme, selected=(theme == app.config.code_editor.theme)) for theme in list_of_themes]
+                            *[Option(theme, value=theme, selected=(theme == current_editor_theme())) for theme in list_of_themes]
                         ),
                     ),
                 ),
@@ -869,7 +903,7 @@ def get_file(file: str):
                 Script(f"""
                     var editor = {'CodeMirror.fromTextArea' if app.config.code_editor.highlight else ''} (document.getElementById('editor'), {{
                         mode: '{app.config.code_editor.mode}',
-                        theme: '{app.config.code_editor.theme}',
+                        theme: '{current_editor_theme()}',
                         lineNumbers: true,
                         indentUnit: 4,
                         tabSize: 4,
@@ -946,7 +980,7 @@ def get_file(file: str):
         ),
     )
     page = Div(cls="flex space-x-2")(side_bar, main_screen)
-    return Div(logo_title_container, page)
+    return Div(codeeditor_theme(), logo_title_container, page)
 
 @app.post("/codeeditor/create_folder/{folder:path}")
 def create_folder(folder: str):
@@ -1031,7 +1065,10 @@ async def update_config(request):
         if data["type"] == "mode":
             app.config.code_editor.mode = data["value"]
         elif data["type"] == "theme":
-            app.config.code_editor.theme = data["value"]
+            # CodeMirror's stylesheet, not the shared design-token theme.
+            # Recorded as an override so it survives a later theme swap.
+            global _editor_theme_override
+            _editor_theme_override = data["value"]
         return {"success": True}
     except Exception as e:
         return {"success": False, "error": str(e)}
diff --git a/src/open_apps/apps/map_app/main.py b/src/open_apps/apps/map_app/main.py
index c4028dd4..ca08708c 100644
--- a/src/open_apps/apps/map_app/main.py
+++ b/src/open_apps/apps/map_app/main.py
@@ -14,6 +14,7 @@
 from fasthtml.common import *
 import requests
 import json
+from src.open_apps.theme import render_theme_css, resolve_theme, theme_asset
 from datetime import datetime, timezone
 import subprocess
 import time
@@ -98,6 +99,23 @@ async def startup_event():
 async def shutdown_event():
     stop_otp_server()
 
+def current_tile_layer() -> str:
+    """Leaflet basemap for the active theme.
+
+    Tiles are raster images served from a CDN, so no design token can recolor
+    them -- a dark theme would otherwise render a dark sidebar around a bright
+    map. The theme instead names a `tone`, and `layer_by_tone` maps that onto
+    one of the layers defined in templates/map.html; anything unmapped keeps
+    the configured `default_layer`.
+    """
+    cfg = app.config.maps
+    tone = theme_asset(app.config, "maps", "tone", "light")
+    by_tone = getattr(cfg, "layer_by_tone", None)
+    if by_tone is not None and tone in by_tone:
+        return by_tone[tone]
+    return cfg.default_layer
+
+
 @app.get("/maps", response_class=HTMLResponse)
 async def map_page(request: Request):
     return templates.TemplateResponse(
@@ -105,23 +123,16 @@ async def map_page(request: Request):
         {
             "request": request,
             "enable_layer_control": app.config.maps.enable_layer_control,
-            "default_layer": app.config.maps.default_layer,
+            "default_layer": current_tile_layer(),
             "popup_display_rule": app.config.maps.popup_display_rule,
             "title": app.config.maps.title,
             "init_location": app.config.maps.init_location,
             "zoom": app.config.maps.zoom,
             "granularity": app.config.maps.granularity,
-            "font_family": app.config.maps.font_family,
-            "base_font_size": app.config.maps.base_font_size,
-            "search_button_color": app.config.maps.search_button_color,
-            "delete_button_color": app.config.maps.delete_button_color,
-            "return_button_color": app.config.maps.return_button_color,
-            "calculate_button_color": app.config.maps.calculate_button_color,
-            "delete_button_hover_color": getattr(app.config.maps, "delete_button_hover_color", "#ffecec"),
-            "search_button_hover_color": getattr(app.config.maps, "search_button_hover_color", "#2980b9"),
-            "calculate_button_hover_color": getattr(app.config.maps, "calculate_button_hover_color", "#2980b9"),
-            "sidebar_background_color": getattr(app.config.maps, "sidebar_background_color", "#f8f9fa"),
             "allow_planning": app.config.maps.allow_planning,
+            # Every color and font in the template is a var() into this block.
+            # Resolved per-request so live `reconfigure` theme swaps take effect.
+            "theme_css": render_theme_css(resolve_theme(app.config, "maps")),
         },
     )
 
diff --git a/src/open_apps/apps/map_app/templates/map.html b/src/open_apps/apps/map_app/templates/map.html
index 0608c6aa..a9ca75ac 100644
--- a/src/open_apps/apps/map_app/templates/map.html
+++ b/src/open_apps/apps/map_app/templates/map.html
@@ -11,8 +11,10 @@
     <style>
         body,
         html {
-            font-family: "{{ font_family }}";
-            font-size: "{{ base_font_size }}";
+            font-family: var(--font-family);
+            font-size: var(--font-size-base);
+            color: var(--color-fg);
+            background-color: var(--color-bg);
             margin: 0;
             padding: 0;
             height: 100vh;
@@ -37,20 +39,20 @@
         #sidebar {
             flex: 0.2;
             padding: 20px;
-            background: {{ sidebar_background_color }};
+            background: var(--color-surface);
             box-shadow: -2px 0 5px rgba(0, 0, 0, 0.1);
             overflow-y: auto;
         }
 
         #sidebar h2 {
-            color: #2c3e50;
+            color: var(--color-fg);
             margin-bottom: 20px;
-            border-bottom: 2px solid #3498db;
+            border-bottom: 2px solid var(--color-primary);
             padding-bottom: 10px;
         }
 
         #sidebar h3 {
-            color: #34495e;
+            color: var(--color-fg);
             margin: 20px 0 10px 0;
         }
 
@@ -58,9 +60,9 @@
             cursor: pointer;
             padding: 10px;
             margin: 5px 0;
-            background-color: white;
+            background-color: var(--color-bg);
             border-radius: 5px;
-            border: 1px solid #e0e0e0;
+            border: 1px solid var(--color-border);
             transition: all 0.2s;
             display: flex;
             justify-content: space-between;
@@ -68,12 +70,12 @@
         }
 
         .popup-list-item:hover {
-            background-color: #f5f6fa;
+            background-color: var(--color-surface);
             transform: translateX(5px);
         }
 
         .delete-btn {
-            color: {{ delete_button_color }};
+            color: var(--color-danger);
             cursor: pointer;
             font-size: 18px;
             padding: 0 5px;
@@ -83,7 +85,7 @@
         }
 
         .delete-btn:hover {
-            background-color: {{ delete_button_hover_color }}
+            background-color: var(--color-surface)
         }
 
         .search-container {
@@ -95,15 +97,15 @@
         #searchInput {
             flex: 1;
             padding: 8px;
-            border: 1px solid #e0e0e0;
+            border: 1px solid var(--color-border);
             border-radius: 5px;
             font-size: 14px;
         }
 
         #searchBtn {
             padding: 8px 15px;
-            background-color: {{ search_button_color }};
-            color: white;
+            background-color: var(--color-primary);
+            color: var(--color-on-primary);
             border: none;
             border-radius: 5px;
             cursor: pointer;
@@ -111,7 +113,7 @@
         }
 
         #searchBtn:hover {
-            background-color: {{ search_button_hover_color }}
+            background-color: var(--color-primary-hover)
         }
 
         #searchResults {
@@ -122,22 +124,22 @@
             cursor: pointer;
             padding: 10px;
             margin: 5px 0;
-            background-color: white;
+            background-color: var(--color-bg);
             border-radius: 5px;
-            border: 1px solid #e0e0e0;
+            border: 1px solid var(--color-border);
             transition: all 0.2s;
         }
 
         .search-result-item:hover {
-            background-color: #f5f6fa;
+            background-color: var(--color-surface);
             transform: translateX(5px);
         }
 
         .info-box {
-            background: white;
+            background: var(--color-bg);
             padding: 10px;
             border-radius: 5px;
-            border: 1px solid #e0e0e0;
+            border: 1px solid var(--color-border);
             margin: 10px 0;
             font-size: 14px;
         }
@@ -158,15 +160,15 @@
         .location-input-container input {
             flex: 1;
             padding: 8px;
-            border: 1px solid #e0e0e0;
+            border: 1px solid var(--color-border);
             border-radius: 5px;
             font-size: 14px;
         }
 
         .location-input-container .search-btn {
             padding: 8px 15px;
-            background-color: {{ search_button_color }};
-            color: white;
+            background-color: var(--color-primary);
+            color: var(--color-on-primary);
             border: none;
             border-radius: 5px;
             cursor: pointer;
@@ -174,7 +176,7 @@
         }
 
         .location-input-container .search-btn:hover {
-            background-color: {{ search_button_hover_color }}
+            background-color: var(--color-primary-hover)
         }
 
         .search-results-mini {
@@ -185,16 +187,16 @@
             max-height: 100px;
             overflow-y: auto;
             margin: 5px 0;
-            background: white;
-            border: 1px solid #e0e0e0;
+            background: var(--color-bg);
+            border: 1px solid var(--color-border);
             z-index: 1000;
         }
 
         #calculateRouteBtn {
             width: 100%;
             padding: 8px;
-            background-color: {{ calculate_button_color }};
-            color: white;
+            background-color: var(--color-primary);
+            color: var(--color-on-primary);
             border: none;
             border-radius: 5px;
             cursor: pointer;
@@ -202,13 +204,13 @@
         }
 
         #calculateRouteBtn:hover {
-            background-color: {{ calculate_button_hover_color }};
+            background-color: var(--color-primary-hover);
         } */
 
         .search-btn {
             padding: 8px 15px;
-            background-color: {{ search_button_color }}
-            color: white;
+            background-color: var(--color-primary);
+            color: var(--color-on-primary);
             border: none;
             border-radius: 5px;
             cursor: pointer;
@@ -217,14 +219,14 @@
         }
 
         .search-btn:hover {
-            background-color: {{ search_button_hover_color }};
+            background-color: var(--color-primary-hover);
         }
 
         #returnButton {
             width: 100%;
             padding: 10px;
-            background-color: {{ return_button_color }};
-            color: white;
+            background-color: var(--color-neutral);
+            color: var(--color-on-primary);
             border: none;
             border-radius: 5px;
             cursor: pointer;
@@ -233,7 +235,7 @@
         }
 
         #returnButton:hover {
-            background-color: #7f8c8d;
+            background-color: var(--color-primary-hover);
         }
 
         .custom-select-container {
@@ -244,9 +246,9 @@
 
         .custom-select-header {
             padding: 8px;
-            border: 1px solid #e0e0e0;
+            border: 1px solid var(--color-border);
             border-radius: 5px;
-            background: white;
+            background: var(--color-bg);
             cursor: pointer;
             display: flex;
             justify-content: space-between;
@@ -258,8 +260,8 @@
             top: 100%;
             left: 0;
             right: 0;
-            background: white;
-            border: 1px solid #e0e0e0;
+            background: var(--color-bg);
+            border: 1px solid var(--color-border);
             border-radius: 5px;
             margin-top: 5px;
             max-height: 200px;
@@ -277,7 +279,7 @@
         }
 
         .custom-select-option:hover {
-            background-color: #f5f6fa;
+            background-color: var(--color-surface);
         }
 
         .custom-select-option i {
@@ -285,9 +287,12 @@
         }
 
         .custom-select-option.selected {
-            background-color: #e3f2fd;
+            background-color: var(--color-surface);
         }
     </style>
+    <!-- Shared design tokens (open_apps.theme). Every color and font above
+         is a var() into this block. -->
+    <style>{{ theme_css|safe }}</style>
 </head>
 
 <body>
@@ -489,13 +494,22 @@ <h3>Saved Locations</h3>
                 maxZoom: 19,
                 attribution: '© OpenStreetMap contributors, © CartoDB'
             }),
+            // Greyscale basemap -- what the `mono` theme selects, so the map
+            // carries no hue either.
+            'CartoDB Positron': L.tileLayer('https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}{r}.png', {
+                maxZoom: 19,
+                attribution: '© OpenStreetMap contributors, © CartoDB'
+            }),
 
             'OpenStreetMap Transport': L.tileLayer('https://tile.memomaps.de/tilegen/{z}/{x}/{y}.png', {
                 maxZoom: 18,
                 attribution: '© OpenStreetMap contributors, © MeMoMaps'
             }),
         };
-        layers['{{ default_layer }}'].addTo(map);
+        // Fall back rather than throw: an unknown name here used to raise a
+        // TypeError that aborted the rest of this script, leaving a blank map
+        // with no landmarks and no sidebar wiring.
+        (layers['{{ default_layer }}'] || layers['OpenStreetMap']).addTo(map);
 
         {% if enable_layer_control %}
         // Add layer control only if enabled
@@ -1205,7 +1219,7 @@ <h3>Saved Locations</h3>
                                 let content = `
                                     <div style="display: flex; justify-content: space-between; align-items: center; width: 100%;">
                                         <div>Option ${index + 1}: ${icons}</div>
-                                        <div style="color: #666; font-size: 0.9em;">
+                                        <div style="color: var(--color-muted); font-size: 0.9em;">
                                             ${formatTime(startTime)} → ${formatTime(endTime)}
                                         </div>
                                     </div>
@@ -1275,7 +1289,7 @@ <h3>Saved Locations</h3>
         {% endif %}
 
     </script>
-    <div id="markerCustomizationModal" style="display: none; position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%); background: white; padding: 20px; border-radius: 5px; box-shadow: 0 0 10px rgba(0,0,0,0.3); z-index: 1000;">
+    <div id="markerCustomizationModal" style="display: none; position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%); background: var(--color-bg); padding: 20px; border-radius: 5px; box-shadow: 0 0 10px rgba(0,0,0,0.3); z-index: 1000;">
         <h3>Customize Marker</h3>
         <div style="margin-bottom: 15px;">
             <label for="markerIcon">Icon:</label>
@@ -1342,7 +1356,7 @@ <h3>Customize Marker</h3>
         </div>
         <div style="text-align: right;">
             <button onclick="cancelMarkerCustomization()" style="margin-right: 10px;">Cancel</button>
-            <button onclick="confirmMarkerCustomization()" style="background-color: #3498db; color: white; border: none; padding: 5px 15px; border-radius: 3px;">Confirm</button>
+            <button onclick="confirmMarkerCustomization()" style="background-color: var(--color-primary); color: var(--color-on-primary); border: none; padding: 5px 15px; border-radius: 3px;">Confirm</button>
         </div>
     </div>
 </body>
diff --git a/src/open_apps/apps/messenger_app/main.py b/src/open_apps/apps/messenger_app/main.py
index 44e992bf..b5df6b18 100644
--- a/src/open_apps/apps/messenger_app/main.py
+++ b/src/open_apps/apps/messenger_app/main.py
@@ -12,6 +12,7 @@
 import json
 from src.open_apps.apps.start_page.helper import create_logo_header
 from open_apps.frontend import local_hdrs
+from open_apps.theme import theme_style
 
 
 @dataclass
@@ -272,6 +273,78 @@ class Messages:
 )
 app = FastHTML(hdrs=_base_hdrs, cls="p-4 max-w-lg mx-auto", default_hdrs=False)
 
+# Static, theme-agnostic component styles. Colors and fonts are design tokens
+# from the shared theme (`config/apps/theme/`), emitted per-request by
+# `messenger_theme()`.
+#
+# The chat surface maps onto generic tokens rather than bubble-specific ones:
+# the outgoing bubble is the primary action color, the incoming bubble is the
+# surface color, and the transcript sits on the page background. Keeping the
+# vocabulary generic is what lets a theme file stay app-agnostic -- no theme
+# has to know this app has bubbles.
+#
+# `!important` throughout: daisyUI ships utility classes on these same
+# elements and would otherwise win.
+_COMPONENT_STYLES = Style(
+    """
+    body {
+        background-color: var(--color-bg);
+    }
+    /* Global text styling */
+    h1, h2, h3, p, div {
+        font-family: var(--font-family) !important;
+        color: var(--color-fg) !important;
+    }
+
+    /* Message list specific styling */
+    .text-2xl {
+        font-size: calc(var(--font-size-base) * 1.5) !important;
+    }
+
+    .text-sm {
+        font-size: var(--font-size-sm) !important;
+    }
+
+    /* Chat specific styling */
+    .chat .chat-header {
+        font-family: var(--font-family) !important;
+        color: var(--color-muted) !important;
+        margin-bottom: calc(var(--font-size-sm) * 0.5);
+    }
+
+    .chat .chat-bubble {
+        font-family: var(--font-family) !important;
+        font-size: var(--font-size-sm) !important;
+        color: var(--color-fg) !important;
+        padding: calc(var(--font-size-sm) * 0.75) var(--font-size-sm);
+        min-height: calc(var(--font-size-sm) * 2);
+        display: flex;
+        align-items: center;
+    }
+    .input {
+        font-family: var(--font-family) !important;
+        font-size: var(--font-size-sm) !important;
+        color: var(--color-fg) !important;
+        background-color: var(--color-bg) !important;
+    }
+
+    /* Chat bubbles */
+    .chat-bubble-primary {
+        background-color: var(--color-primary) !important;
+        color: var(--color-on-primary) !important;
+    }
+
+    .chat-bubble-secondary {
+        background-color: var(--color-surface) !important;
+    }
+
+    /* daisyUI paints these from its own palette, which no token can reach. */
+    .bg-base-100, .bg-base-200 {
+        background-color: var(--color-surface) !important;
+    }
+"""
+)
+
 
 def set_environment(config):
     """Set environment variables for the messenger app"""
@@ -291,77 +364,9 @@ def set_environment(config):
     #         current_file_path=__file__
     #     )
     #     return
-    # Create styles with environment variables
-    env_styles = Style(
-        f"""
-        :root {{
-            --custom-font-size: {config.messenger.font_size}px;
-            --custom-font-family: {config.messenger.font};
-            --custom-font-color: {config.messenger.fontcolor};
-            --custom-background-color: {config.messenger.background_color};
-            --chat-font-size: {config.messenger.chat_font_size}px;
-            --chat-font-family: {config.messenger.chat_font};
-            --chat-font-color: {config.messenger.chat_fontcolor};
-            --chat-header-font-color: {config.messenger.chat_header_fontcolor};
-            --chat-primary-bubble-color: {config.messenger.chat_primary_bubble_color};
-            --chat-secondary-bubble-color: {config.messenger.chat_secondary_bubble_color};
-            --chat-display-background-color: {config.messenger.chat_display_background_color};
-        }}
-        body {{
-            background-color: var(--custom-background-color);
-        }}
-        /* Global text styling */
-        h1, h2, h3, p, div {{
-            font-family: var(--custom-font-family) !important;
-            color: var(--custom-font-color) !important;
-        }}
-
-        /* Message list specific styling */
-        .text-2xl {{
-            font-size: calc(var(--custom-font-size) * 1.5) !important;
-        }}
-
-        .text-sm {{
-            font-size: calc(var(--custom-font-size) * 0.875) !important;
-        }}
-        
-        /* Chat specific styling */
-        .chat .chat-header {{
-            font-family: var(--chat-font-family) !important;
-            color: var(--chat-header-font-color) !important;
-            margin-bottom: calc(var(--chat-font-size) * 0.5);
-        }}
-        
-        .chat .chat-bubble {{
-            font-family: var(--chat-font-family) !important;
-            font-size: var(--chat-font-size) !important;
-            color: var(--chat-font-color) !important;
-            padding: calc(var(--chat-font-size) * 0.75) calc(var(--chat-font-size) * 1);
-            min-height: calc(var(--chat-font-size) * 2);
-            display: flex;
-            align-items: center;
-        }}
-        .input {{
-            font-family: var(--chat-font-family) !important;
-            font-size: var(--chat-font-size) !important;
-            color: var(--chat-font-color) !important;
-        }}
-
-        # Add these new styles for chat bubbles
-        .chat-bubble-primary {{
-            background-color: var(--chat-primary-bubble-color) !important;
-        }}
-        
-        .chat-bubble-secondary {{
-            background-color: var(--chat-secondary-bubble-color) !important;
-        }}
-    """
-    )
-
-    # Update app headers by extending existing ones
     # Note: in future implementations, we might need to preserve
     # the order of the style files, scripts and links to prevent conflicts
-    app.hdrs = (*_base_hdrs, env_styles)
+    app.hdrs = (*_base_hdrs, _COMPONENT_STYLES)
     app.config = config
     # create database
     db = database(app.config.messenger.database_path)
@@ -377,6 +382,15 @@ def set_environment(config):
         current_file_path=__file__
     )
 
+def messenger_theme():
+    """The active theme's `:root` token block.
+
+    Rendered into the page body (not `app.hdrs`) so live `reconfigure` theme
+    swaps take effect without rebuilding the headers.
+    """
+    return theme_style(app.config, "messenger")
+
+
 def populate_database(config, db):
     """Adds chat history to database"""
     chat_history = config.messenger.chat_history
@@ -407,7 +421,7 @@ def add_new_message_to_history(user, message, sender, timestamp):
 # Chat message component (renders a chat bubble)
 def ChatMessage(message, sender, timestamp=None):
     if sender == "you":
-        bubble_class = "chat-bubble-primary custom-primary-bubble bg-[var(--chat-primary-bubble-color)] text-[var(--chat-font-color)]"
+        bubble_class = "chat-bubble-primary custom-primary-bubble bg-[var(--color-primary)] text-[var(--color-on-primary)]"
         chat_class = "chat-end"
     else:
         bubble_class = "chat-bubble-secondary"
@@ -527,6 +541,7 @@ def index():
     )
 
     return Div(
+        messenger_theme(),
         logo_title_container,
         page
     )
@@ -587,7 +602,7 @@ def index(user_id: str):
         ),
         Style("""
             .chat-bg {
-                background-color: var(--chat-display-background-color);
+                background-color: var(--color-bg);
             }
             .chat-bubble {
                 border-radius: 12px;
@@ -616,7 +631,7 @@ def index(user_id: str):
                 transition: background-color 0.2s ease;
             }
             .search-result-item:hover {
-                background-color: #e5e7eb;
+                background-color: var(--color-surface);
             }
         """),
         # Add debugging script
@@ -633,6 +648,7 @@ def index(user_id: str):
     )
 
     return Div(
+        messenger_theme(),
         logo_title_container,
         page
     )
diff --git a/src/open_apps/apps/onlineshop_app/main.py b/src/open_apps/apps/onlineshop_app/main.py
index d7f7255c..036ca951 100644
--- a/src/open_apps/apps/onlineshop_app/main.py
+++ b/src/open_apps/apps/onlineshop_app/main.py
@@ -50,7 +50,7 @@ def set_environment(config):
     app.config = config
     if not os.path.exists(config.onlineshop.database_path):
         os.makedirs(config.onlineshop.database_path)
-    global_state.update_config(config.onlineshop)
+    global_state.update_config(config.onlineshop, apps_config=config)
     update_db_from_hydra(global_state)
 
 def generate_search_results(products: List[Dict], keywords: str, page: int, total: int) -> str:
diff --git a/src/open_apps/apps/onlineshop_app/models/global_state.py b/src/open_apps/apps/onlineshop_app/models/global_state.py
index 0b317814..afc14265 100644
--- a/src/open_apps/apps/onlineshop_app/models/global_state.py
+++ b/src/open_apps/apps/onlineshop_app/models/global_state.py
@@ -21,6 +21,9 @@ def __init__(self):
         self.SHOW_ATTRS_TAB = False
         self.cart = Cart()
         self.config = None
+        # The whole `config.apps` node, not just this app's slice: resolving
+        # the shared theme needs the sibling `apps.theme` group.
+        self.apps_config = None
         self.orders = []
 
     def initialize(self):
@@ -31,8 +34,9 @@ def initialize(self):
             num_products=DEBUG_PROD_SIZE
         )
         self.search_engine = init_search_engine(num_products=DEBUG_PROD_SIZE)
-    def update_config(self, config):
+    def update_config(self, config, apps_config=None):
         self.config = config
+        self.apps_config = apps_config
     def load_state_from_config(self):
         cart, orders = self.config.cart, self.config.orders
         if isinstance(cart, ListConfig) or isinstance(cart, DictConfig):
diff --git a/src/open_apps/apps/onlineshop_app/templates/html_generator.py b/src/open_apps/apps/onlineshop_app/templates/html_generator.py
index cbc08471..e38f29bd 100644
--- a/src/open_apps/apps/onlineshop_app/templates/html_generator.py
+++ b/src/open_apps/apps/onlineshop_app/templates/html_generator.py
@@ -4,18 +4,16 @@
 This source code is licensed under the license found in the
 LICENSE file in the root directory of this source tree.
 """
+from open_apps.theme import render_theme_css, resolve_theme
+
 from ..models.global_state import global_state
 
 # HTML Templates
 def generate_base_html(content: str) -> str:
     cart_count = global_state.cart.get_total_quantity() if hasattr(global_state, 'cart') else 0
-    bg_color = global_state.config.background_color
-    font_family = global_state.config.font_family
-    base_font_size = global_state.config.base_font_size
-    font_color = global_state.config.font_color
-    button_background_color = getattr(global_state.config, 'button_background_color', '#0d6efd')
-    button_font_color = getattr(global_state.config, 'button_font_color', '#FFFFFF')
-    highlight_font_color = getattr(global_state.config, 'highlight_font_color', '#0d6efd')
+    # Every color and font below is a var() into this block. Resolved
+    # per-request so live `reconfigure` theme swaps take effect.
+    theme_css = render_theme_css(resolve_theme(global_state.apps_config, "onlineshop"))
     return f"""
     <!DOCTYPE html>
     <html>
@@ -24,17 +22,18 @@ def generate_base_html(content: str) -> str:
             <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet">
             <link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/all.min.css" rel="stylesheet">
             <style>
+                {theme_css}
                 body {{
-                    font-family: "{font_family}";
-                    font-size: {base_font_size};
-                    background-color: {bg_color};
-                    color: {font_color};
+                    font-family: var(--font-family);
+                    font-size: var(--font-size-base);
+                    background-color: var(--color-bg);
+                    color: var(--color-fg);
                 }}
                 button, input, textarea, select {{
                     font-family: inherit;
                 }}
                 h1, h2, h3, h4, h5, h6 {{
-                    font-family: inherit;
+                    font-family: var(--font-heading);
                 }}
                 .result-img {{
                     max-width: 100%;
@@ -51,49 +50,55 @@ def generate_base_html(content: str) -> str:
                     margin: 2px;
                 }}
                 .option-btn.active {{
-                    background-color: #0d6efd;
-                    color: white;
-                }}
-                .review-item {{
-                    border-bottom: 1px solid #ddd;
-                    padding: 10px 0;
+                    background-color: var(--color-primary);
+                    color: var(--color-on-primary);
                 }}
                 .hover-shadow:hover {{
                     transform: translateY(-3px);
                     box-shadow: 0 4px 20px rgba(0,0,0,0.1) !important;
                     transition: all 0.3s ease;
                 }}
+                /* Bootstrap paints its own navbar/card surfaces, which no
+                   token can reach from the outside. */
+                .navbar.bg-light, .card {{
+                    background-color: var(--color-surface) !important;
+                    color: var(--color-fg);
+                }}
+                .card {{
+                    border-color: var(--color-border);
+                }}
                 .nav-tabs .nav-link {{
-                    color: #666;
+                    color: var(--color-muted);
                     border: none;
                     padding: 1rem 1.5rem;
                 }}
                 .nav-tabs .nav-link.active {{
-                    color: #0d6efd;
-                    border-bottom: 2px solid #0d6efd;
+                    color: var(--color-primary);
+                    border-bottom: 2px solid var(--color-primary);
                     background: none;
                 }}
                 .review-item {{
-                    border-bottom: 1px solid #eee;
+                    border-bottom: 1px solid var(--color-border);
                     padding: 1rem 0;
                 }}
                 .review-item:last-child {{
                     border-bottom: none;
                 }}
                 .btn-primary, .btn-outline-primary {{
-                    background-color: {button_background_color} !important;
-                    color: {button_font_color} !important;
+                    background-color: var(--color-primary) !important;
+                    border-color: var(--color-primary) !important;
+                    color: var(--color-on-primary) !important;
                 }}
                 .text-primary {{
-                    color: {highlight_font_color} !important;
+                    color: var(--color-primary) !important;
                 }}
                 .breadcrumb-item,
                 .breadcrumb-item a,
                 .breadcrumb-item.active {{
-                    color: {highlight_font_color} !important;
+                    color: var(--color-primary) !important;
                 }}
                 .breadcrumb-item + .breadcrumb-item::before {{
-                    color: {highlight_font_color} !important;
+                    color: var(--color-primary) !important;
                 }}
             </style>
         </head>
diff --git a/src/open_apps/apps/start_page/helper.py b/src/open_apps/apps/start_page/helper.py
index 203da42d..bf0ba9f9 100644
--- a/src/open_apps/apps/start_page/helper.py
+++ b/src/open_apps/apps/start_page/helper.py
@@ -57,23 +57,12 @@ def Wrapper(title, description, content, style=1, align=None, color=None, invert
         "wrapper style", style, "align-", align, "invert", invert, "color", color
     )
     
-    # Apply custom styling to title and description
-    title_style = {}
-    desc_style = {}
-    
-    if config:
-        if config.get('heading_font'):
-            title_style['font-family'] = config['heading_font']
-        if config.get('heading_color'):
-            title_style['color'] = config['heading_color']
-        if config.get('font_family'):
-            desc_style['font-family'] = config['font_family']
-        if config.get('font_color'):
-            desc_style['color'] = config['font_color']
-    
+    # Typography is inherited from the shared theme's tokens (see the
+    # stylesheet PageWrapper emits) rather than written as inline styles from
+    # per-app font config, which is what the `appearance` group used to supply.
     inner_content = [
-        H2(title, style=";".join([f"{k}:{v}" for k, v in title_style.items()]) if title_style else None),
-        P(description, style=";".join([f"{k}:{v}" for k, v in desc_style.items()]) if desc_style else None),
+        H2(title),
+        P(description),
         content
     ]
     
@@ -110,26 +99,10 @@ def ItemContent(title, description, color="primary", icon=None, xtra=None, href=
         else:
             content.append(Span(cls=f"icon style2 major fa-{icon}"))
     
-    # Apply font styling to title and description if configured
-    title_style = {}
-    desc_style = {}
-    
-    if config.get('heading_font'):
-        title_style['font-family'] = config['heading_font']
-    if config.get('heading_color'):
-        title_style['color'] = config['heading_color']
-    if config.get('font_family'):
-        desc_style['font-family'] = config['font_family']
-    if config.get('font_color'):
-        desc_style['color'] = config['font_color']
-    if config.get('font_size'):
-        base_size = int(config['font_size'])
-        title_style['font-size'] = f"{base_size * 1.5}px"
-        desc_style['font-size'] = f"{base_size}px"
-    
-    # Add title and description with any configured styling
-    content.append(H3(title, style=";".join([f"{k}:{v}" for k, v in title_style.items()]) if title_style else None))
-    content.append(P(description, style=";".join([f"{k}:{v}" for k, v in desc_style.items()]) if desc_style else None))
+    # Tile typography comes from the shared theme (the `.item h3` / `.item p`
+    # rules in PageWrapper), not from inline per-app font config.
+    content.append(H3(title))
+    content.append(P(description))
     
     # Add any extra content
     if xtra:
@@ -300,35 +273,43 @@ def __init__(self, content):
     def __str__(self):
         return self.content
 
-def PageWrapper(title, *content, config=None):
+def PageWrapper(title, *content, config=None, theme_css=""):
     """
     Create a page wrapper with custom styling from configuration.
-    
+
     Args:
         title: Page title
         *content: Content elements
         config: Configuration dictionary with styling options
+        theme_css: Shared design-token CSS from ``open_apps.theme``. Emitted
+            last; every color and font below is a ``var()`` into it.
     """
     # Set defaults if config is None
     if config is None:
         config = {}
-    
-    # Generate custom CSS based on configuration
-    custom_css = ""
-    
-    # Font settings
-    if config.get('font_family'):
-        custom_css += f"body {{ font-family: {config['font_family']}; }}\n"
-    if config.get('font_color'):
-        custom_css += f"body {{ color: {config['font_color']}; }}\n"
-    if config.get('heading_font'):
-        custom_css += f"h1, h2, h3, h4, h5, h6 {{ font-family: {config['heading_font']}; }}\n"
-    if config.get('heading_color'):
-        custom_css += f"h1, h2, h3, h4, h5, h6 {{ color: {config['heading_color']}; }}\n"
-    if config.get('background_color'):
-        custom_css += f"body {{ background-color: {config['background_color']}; }}\n"
-    
+
+    # Typography and page chrome come from the shared theme; only geometry
+    # (radii, padding, hover behaviour) is still read from `config`, which is
+    # the start page's `layout` group.
+    custom_css = """
+        body {
+            font-family: var(--font-family);
+            color: var(--color-fg);
+            background-color: var(--color-bg);
+        }
+        h1, h2, h3, h4, h5, h6 {
+            font-family: var(--font-heading);
+            color: var(--color-fg);
+        }
+        #wrapper > .wrapper {
+            background-color: var(--color-bg);
+        }
+    """
+
     # Add iOS-style typography for items
+    # Tile labels stay white in every theme: they sit on the tile fill, not
+    # on the page background, and every tone's fill is dark enough to carry
+    # white text. `--color-fg` here would be white-on-white in a light theme.
     custom_css += """
         .item h3 {
             font-size: 0.9em !important;
@@ -407,11 +388,15 @@ def PageWrapper(title, *content, config=None):
             .modal.left .modal-dialog {{ margin-left: 5%; }}
             .modal.right .modal-dialog {{ margin-left: auto; margin-right: 5%; }}
             
+            /* Themed like the rest of the page on purpose: a pop-up that
+               stayed near-white on a dark theme would be trivially easy to
+               spot, which confounds the adversarial-pop-up variation. */
             .modal-content {{
-                background-color: #fefefe;
+                background-color: var(--color-surface);
+                color: var(--color-fg);
                 padding: 20px;
                 padding-bottom: 80px;
-                border-radius: 5px;
+                border-radius: var(--radius);
                 box-shadow: 0 4px 8px rgba(0,0,0,0.1);
             }}
             .close-modal {{
@@ -426,11 +411,12 @@ def PageWrapper(title, *content, config=None):
             }}
             
             .link-button {{
-                background-color: #4CAF50;
+                background-color: var(--color-accent);
+                color: var(--color-btn-fg);
             }}
-            
+
             .link-button:hover {{
-                background-color: #45a049;
+                background-color: var(--color-primary-hover);
             }}
             
             /* Story template item scaling customization */
@@ -547,6 +533,8 @@ def PageWrapper(title, *content, config=None):
             }}
             
             {custom_css}
+
+            {theme_css}
         </style>
         <script>
             function showModal(id) {{
diff --git a/src/open_apps/apps/start_page/main.py b/src/open_apps/apps/start_page/main.py
index 2f8fb3b6..012b56fa 100644
--- a/src/open_apps/apps/start_page/main.py
+++ b/src/open_apps/apps/start_page/main.py
@@ -34,6 +34,39 @@
         generate_random_colors,
     )
 from omegaconf import DictConfig, OmegaConf
+from open_apps.theme import render_theme_css, resolve_theme, theme_asset
+
+
+def icon_for(app_config, app_name):
+    """Path to an app's start-page tile icon under the active theme.
+
+    The icons are PNGs, so a CSS variable cannot recolor them; the theme picks
+    a set via its `icon_set` asset and the repo ships a hand-made greyscale
+    version alongside the color one. Falls back to the color icon when a theme
+    asks for a set the config has no path for.
+    """
+    if theme_asset(app.config, "start_page", "icon_set", "color") == "bw":
+        bw = app_config.get("bw_icon")
+        if bw:
+            return bw
+    return app_config.get("icon", f"/assets/icons/real_icons/{app_name}.png")
+
+
+def tile_colors(config):
+    """Background fills for the app tiles, in position order.
+
+    The default palette is six saturated iOS-style hues that carry no semantic
+    meaning -- mapping them onto theme tokens would collapse six visually
+    distinct targets into one. Non-light themes do collapse them, deliberately:
+    that is the perturbation `dark` and `mono` are for.
+    """
+    if config.get("use_random_colors"):
+        return generate_random_colors(10)
+    tone = theme_asset(app.config, "start_page", "tone", "light")
+    by_tone = config.get("tile_fill_by_tone") or {}
+    if tone in by_tone:
+        return [by_tone[tone]]
+    return config.app_background_colors
 
 # Define available apps and their route getters
 AVAILABLE_APPS = {
@@ -165,12 +198,19 @@ def initialize_routes_and_configure_task(config: DictConfig = None):
             print(f"Failed to find route getter for {app_name}: {e}")
 
     if getattr(app.config.start_page, "shuffle_icons", False):
-        # randomize icons and app names if specified
-        icons = [getattr(app.config.start_page.apps[app_name], "icon") for app_name in app.config.start_page.apps]
-        random.shuffle(icons)
-        print(app.config.start_page.apps)
-        for app_name in app.config.start_page.apps:
-            app.config.start_page.apps[app_name].icon = icons.pop()
+        # Detach each icon from its app so the picture stops identifying the
+        # tile. Both sets are permuted the same way, otherwise selecting a
+        # `bw` theme would quietly undo the shuffle.
+        apps_cfg = app.config.start_page.apps
+        order = list(apps_cfg)
+        shuffled = order[:]
+        random.shuffle(shuffled)
+        icons = {name: apps_cfg[name].get("icon") for name in order}
+        bw_icons = {name: apps_cfg[name].get("bw_icon") for name in order}
+        for name, source in zip(order, shuffled):
+            apps_cfg[name].icon = icons[source]
+            if bw_icons[source] is not None:
+                apps_cfg[name].bw_icon = bw_icons[source]
 
     return app
 
@@ -182,13 +222,8 @@ def get():
     # Get configuration from app.config
     config = app.config.start_page
     
-    # Check if we should use random colors
-    colors = []
-    if hasattr(config, 'use_random_colors') and config.use_random_colors:
-        colors = generate_random_colors(10)  # Generate more than we need
-    else:
-        colors = config.app_background_colors
-    
+    colors = tile_colors(config)
+
     # Build items based on app configurations
     items = []
     
@@ -215,7 +250,7 @@ def get():
                 ItemContent(
                     app_config.get('title', f"Open{app_name.capitalize()}"),
                     app_config.get('description', f"Description for {app_name}"),
-                    icon=app_config.get('icon', f"/assets/icons/real_icons/{app_name}.png"),
+                    icon=icon_for(app_config, app_name),
                     color=color,
                     href=app_url,
                     config=config,
@@ -324,7 +359,14 @@ def get():
     )
     
     # Return the page with configuration
-    return PageWrapper("main-page", wrapper, footer(), config=config)
+    return PageWrapper(
+        "main-page",
+        wrapper,
+        footer(),
+        config=config,
+        # Resolved per-request so live `reconfigure` theme swaps take effect.
+        theme_css=render_theme_css(resolve_theme(app.config, "start_page")),
+    )
 
 
 @rt("/environment_variables")
diff --git a/src/open_apps/apps/todo_app/main.py b/src/open_apps/apps/todo_app/main.py
index 7712b54f..a997cf1f 100644
--- a/src/open_apps/apps/todo_app/main.py
+++ b/src/open_apps/apps/todo_app/main.py
@@ -10,6 +10,7 @@
 from typing import List
 from src.open_apps.apps.start_page.helper import create_logo_header
 from src.open_apps.frontend import local_hdrs
+from src.open_apps.theme import theme_style
 
 
 @dataclass
@@ -21,11 +22,109 @@ class Todo:
 
 app, rt = fast_app(default_hdrs=False, hdrs=local_hdrs())
 logo_title_container = None
-styles = Style("")
+
+# Static, theme-agnostic component styles. All colors/fonts are design tokens
+# resolved per-request via `theme_style()` (see the `:root` block it emits), so
+# this block never needs rebuilding when the theme or app config changes.
+styles = Style("""
+    body {
+        font-family: var(--font-family);
+        font-size: var(--font-size-base);
+        color: var(--color-fg);
+        background-color: var(--color-bg);
+    }
+    .todo, .card, .group, .add-btn {
+        color: var(--color-fg);
+    }
+    a {
+        color: var(--color-fg);
+        text-decoration: none;
+    }
+    .todo-item, .todo-controls {
+        list-style-type: none;
+        color: var(--color-fg);
+    }
+    .todo-general {
+        background-color: var(--color-surface);
+    }
+    .todo-controls {
+        margin-left: 12px;
+    }
+    .todo-btn {
+        transform: scale(.7);
+        color: var(--color-fg);
+    }
+    .edit-btn {
+        background-color: var(--color-neutral);
+        border: 1px solid var(--color-neutral);
+        color: var(--color-btn-fg);
+    }
+    .remove-btn {
+        background-color: var(--color-danger);
+        border: 1px solid var(--color-danger);
+        color: var(--color-btn-fg);
+    }
+    .add-btn {
+        background-color: var(--color-primary);
+        color: var(--color-on-primary);
+    }
+    .save-btn {
+        background-color: var(--color-accent);
+        border: 1px solid var(--color-accent);
+        color: var(--color-btn-fg);
+    }
+    .kanban-board {
+        width: 100%;
+    }
+    .kanban-columns {
+        display: flex;
+        gap: 1rem;
+        align-items: flex-start;
+        margin-top: 1rem;
+        overflow-x: auto;
+        padding-bottom: 0.5rem;
+    }
+    .kanban-column {
+        flex: 0 0 450px;
+        min-width: 450px;
+        background-color: var(--color-surface);
+        border-radius: var(--radius);
+        padding: 0.5rem 0.75rem;
+        min-height: 120px;
+    }
+    .kanban-column-title {
+        margin-top: 0.25rem;
+    }
+    .kanban-card {
+        background-color: var(--color-bg);
+        border: 1px solid var(--color-border);
+        border-radius: var(--radius);
+        padding: 0.5rem 0.75rem;
+        margin-bottom: 0.5rem;
+    }
+    .kanban-card-title {
+        margin-bottom: 0.4rem;
+    }
+    .kanban-card-controls {
+        display: flex;
+        gap: 0.25rem;
+        flex-wrap: wrap;
+    }
+    .kanban-edit input {
+        margin-bottom: 0.4rem;
+    }
+    .kanban-add {
+        margin-top: 0.5rem;
+    }
+    .kanban-header-edit {
+        display: flex;
+        gap: 0.25rem;
+    }
+""")
 
 def set_environment(config):
     """Set environment variables for the todo app"""
-    global app, logo_title_container, styles
+    global app, logo_title_container
     app.config = config
     db = database(config.todo.database_path)
     global todos, kanban_status
@@ -49,111 +148,12 @@ def set_environment(config):
         current_file_path=__file__
     )
 
-    font_family = app.config.todo.font_family
-    font_size = app.config.todo.base_font_size
-    font_color = getattr(app.config.todo, "font_color", "blue")
-    edit_remove_save_button_font_color = getattr(app.config.todo, "edit_remove_save_button_font_color", "")
-    edit_button_color = app.config.todo.edit_button_color
-    remove_button_color = app.config.todo.remove_button_color
-    add_button_color = app.config.todo.add_button_color
-    save_button_color = app.config.todo.save_button_color
-    background_color = getattr(app.config.todo, "background_color", "")
-    form_background_color = getattr(app.config.todo, "form_background_color", "")
-    styles.children = [f"""
-        body {{
-            font-family: {font_family};
-            font-size: {font_size};
-            color: {font_color};
-            background-color: {background_color}
-        }}
-        .todo, .card, .group, .add-btn {{
-            background-color: {background_color}
-            color: {font_color};
-        }}
-        a {{
-            color: {font_color};
-            text-decoration: none;
-        }}
-        .todo-item, .todo-controls {{
-            list-style-type: none;
-            color: {font_color};
-        }}
-        .todo-general {{
-            background-color: {form_background_color}
-        }}
-        .todo-controls {{
-            margin-left: 12px;
-        }}
-        .todo-btn {{
-            transform: scale(.7);
-            color: {font_color};
-        }}
-        .edit-btn {{
-            background-color: {edit_button_color};
-            border: 1px solid {edit_button_color};
-            color: {edit_remove_save_button_font_color};
-        }}
-        .remove-btn {{
-            background-color: {remove_button_color};
-            border: 1px solid {remove_button_color};
-            color: {edit_remove_save_button_font_color};
-        }}
-        .add-btn {{
-            background-color: {add_button_color};
-        }}
-        .save-btn {{
-            background-color: {save_button_color};
-            border: 1px solid {save_button_color};
-            color: {edit_remove_save_button_font_color};
-        }}
-        .kanban-board {{
-            width: 100%;
-        }}
-        .kanban-columns {{
-            display: flex;
-            gap: 1rem;
-            align-items: flex-start;
-            margin-top: 1rem;
-            overflow-x: auto;
-            padding-bottom: 0.5rem;
-        }}
-        .kanban-column {{
-            flex: 0 0 450px;
-            min-width: 450px;
-            background-color: {form_background_color};
-            border-radius: 8px;
-            padding: 0.5rem 0.75rem;
-            min-height: 120px;
-        }}
-        .kanban-column-title {{
-            margin-top: 0.25rem;
-        }}
-        .kanban-card {{
-            background-color: {background_color};
-            border: 1px solid {edit_button_color};
-            border-radius: 6px;
-            padding: 0.5rem 0.75rem;
-            margin-bottom: 0.5rem;
-        }}
-        .kanban-card-title {{
-            margin-bottom: 0.4rem;
-        }}
-        .kanban-card-controls {{
-            display: flex;
-            gap: 0.25rem;
-            flex-wrap: wrap;
-        }}
-        .kanban-edit input {{
-            margin-bottom: 0.4rem;
-        }}
-        .kanban-add {{
-            margin-top: 0.5rem;
-        }}
-        .kanban-header-edit {{
-            display: flex;
-            gap: 0.25rem;
-        }}
-    """]
+
+def todo_theme():
+    """The active theme's `:root` token block, resolved per-request so live
+    `reconfigure` theme swaps take effect."""
+    return theme_style(app.config, "todo")
+
 
 id_curr = "current-todo"
 
@@ -340,7 +340,7 @@ def get():
             cls="contrast",
             style="margin-top: 1rem;",
         )
-        return Div(styles, logo_title_container, render_kanban_board(), home_button)
+        return Div(todo_theme(), styles, logo_title_container, render_kanban_board(), home_button)
     add = Form(
         Group(
             mk_input(),
@@ -349,11 +349,11 @@ def get():
         hx_post="/todo",  # Update this path
         target_id="todo-list",
         hx_swap="beforeend",
-        data_theme=app.config.todo.form_background_color,
     )
     card = (Card(Ul(*todos(), id="todo-list"), header=add, footer=Div(id=id_curr), cls="todo-general"),)
     home_button = A("Return to List of Apps", href="/", role="button", cls="contrast", style="margin-top: 1rem;")
     return Div(
+        todo_theme(),
         styles,
         logo_title_container,
         card,
diff --git a/src/open_apps/mcp/README.md b/src/open_apps/mcp/README.md
index 53ab3154..f5a91268 100644
--- a/src/open_apps/mcp/README.md
+++ b/src/open_apps/mcp/README.md
@@ -45,11 +45,37 @@ the server is then ready for tool calls.
 | `load_task(key)` | Bind a task for scoring; returns its goal. Call `reset` after. |
 | `get_reward()` | Reward for the bound task (1.0 if complete, else 0.0). |
 | `set_goal(goal)` | Free-form goal, no automatic scoring. |
-| `reconfigure(appearance, content, seed, extras)` | Live variant/seed change. |
+| `reconfigure(theme, layout, content, seed, extras, appearance)` | Live variant/seed change. `theme` is the shared global design-token theme; `layout` and `content` are per-app. `appearance` is deprecated — see below. |
 | `list_apps()` | App keys actually registered (Java-aware). |
-| `list_variants(app, group)` | Variant stems for `appearance`/`content`. |
+| `list_variants(app, group)` | Variant stems for a group (`theme`/`layout`/`content`). |
 | `app_url(app=None)` | Absolute URL of an app's landing page. |
 
+### Deprecated: `appearance`
+
+`reconfigure` used to take a per-app `appearance` stem. That group was split
+into a shared `theme` (look) and a per-app `layout` (structure). The parameter
+still exists so existing clients keep binding, and is translated:
+
+| `appearance=` | becomes |
+| --- | --- |
+| `default` | `theme="default"` |
+| `dark_theme` | `theme="dark"` |
+| `black_and_white` | `theme="mono"` |
+| `challenging_font` | `theme="challenging_font"` |
+| `colorblind_access` | `theme="colorblind"` |
+| `kanban_board` | `layout="kanban_board"` |
+| `broken_logos` | `layout="broken_logos"` |
+| `clickable_logos` | `layout="clickable_logos"` |
+
+Each call raises a `DeprecationWarning`; passing `appearance` together with a
+`theme`/`layout` it disagrees with raises `ValueError` rather than silently
+picking one. `list_variants(app, "appearance")` raises too — the group's
+directory is gone, and the missing-dir fallback would otherwise answer
+`["default"]` and quietly drop every variation from a sweep. Two renderings
+shift slightly under the new axes (`mono` polarity, `colorblind` scope); the
+[docs](https://facebookresearch.github.io/OpenApps/) migration table has the
+detail. `appearance` will be removed in a later release.
+
 **Actions** are BrowserGym action strings (full-resolution pixels):
 
 ```text
diff --git a/src/open_apps/mcp/appserver.py b/src/open_apps/mcp/appserver.py
index 05c8e7db..b488ea53 100644
--- a/src/open_apps/mcp/appserver.py
+++ b/src/open_apps/mcp/appserver.py
@@ -38,7 +38,7 @@
     initialize_routes_and_configure_task,
     reset_all_apps,
 )
-from open_apps.mcp.registry import config_dir_for, url_path_for
+from open_apps.mcp.registry import config_dir_for, migrate_appearance, url_path_for
 from open_apps.state import get_current_state
 
 
@@ -157,32 +157,49 @@ def reset(self) -> None:
     def reconfigure(
         self,
         *,
-        appearance: str | None = None,
+        theme: str | None = None,
+        layout: str | None = None,
         content: str | None = None,
         seed: int | None = None,
         extras: dict[str, Any] | None = None,
+        appearance: str | None = None,
     ) -> None:
         """Recompose the Hydra config with new variant choices and seed.
 
         FastHTML routes read ``app.config`` per-request, so the live
         config update propagates without restarting the server. This
-        only swaps appearance/content/seed/extras + re-seeds sqlite; it
+        only swaps theme/layout/content/seed/extras + re-seeds sqlite; it
         cannot add or remove apps (the registered set is fixed at init).
 
         Args:
-            appearance: Variant yaml stem under
-                ``config/apps/<app>/appearance/`` for ``self.app_name``.
+            theme: Shared design-token theme stem under
+                ``config/apps/theme/`` (e.g. ``solarized``). Global: applies
+                to every app that renders design tokens.
+            layout: Per-app structure variant stem under
+                ``config/apps/<app>/layout/`` for ``self.app_name``
+                (e.g. ``kanban_board``).
             content: Variant yaml stem under
                 ``config/apps/<app>/content/`` for ``self.app_name``.
             seed: Fresh integer seed for the OpenApps content samplers.
             extras: Additional dotpath overrides applied to the live
                 config in-place after compose. Example for the maps
                 app: ``{"apps.maps.init_location": [40.78, -73.97]}``.
+            appearance: **Deprecated.** Stem from the removed ``appearance``
+                group, translated onto ``theme``/``layout`` via
+                ``registry.APPEARANCE_MIGRATION``. Raises if it disagrees
+                with a ``theme``/``layout`` passed alongside it.
         """
+        if appearance is not None:
+            theme, layout = migrate_appearance(
+                appearance, theme=theme, layout=layout
+            )
+
         cfg_dir = config_dir_for(self.app_name)
         overrides: list[str] = []
-        if appearance is not None:
-            overrides.append(f"apps/{cfg_dir}/appearance={appearance}")
+        if theme is not None:
+            overrides.append(f"apps/theme={theme}")
+        if layout is not None:
+            overrides.append(f"apps/{cfg_dir}/layout={layout}")
         if content is not None:
             overrides.append(f"apps/{cfg_dir}/content={content}")
         if seed is not None:
@@ -201,7 +218,7 @@ def reconfigure(
         # Routes read ``app.config`` per request, but the assignment above
         # rebinds ``self.config.apps`` to a fresh node — so re-point the
         # FastHTML app at it, otherwise the page keeps rendering the
-        # pre-reconfigure appearance/content.
+        # pre-reconfigure theme/layout/content.
         _fasthtml_app.config = self.config.apps
 
         shutil.rmtree(new_tmp_logs, ignore_errors=True)
diff --git a/src/open_apps/mcp/registry.py b/src/open_apps/mcp/registry.py
index ef23462b..2de943b9 100644
--- a/src/open_apps/mcp/registry.py
+++ b/src/open_apps/mcp/registry.py
@@ -14,6 +14,8 @@
 
 from __future__ import annotations
 
+import warnings
+
 from open_apps import config_dir
 
 
@@ -47,15 +49,87 @@ def config_dir_for(app_name: str) -> str:
     return APP_CONFIG_DIRS.get(app_name, app_name)
 
 
+# ---------------------------------------------------------------------------
+# Legacy ``appearance`` group (removed — kept resolvable for one release).
+
+# ``appearance`` conflated global look with per-app structure, so the split is
+# not one-to-one: five stems became shared themes, three became per-app
+# layouts. Same mapping the docs migration table publishes.
+APPEARANCE_MIGRATION: dict[str, tuple[str, str]] = {
+    "default": ("theme", "default"),
+    "dark_theme": ("theme", "dark"),
+    "black_and_white": ("theme", "mono"),
+    "challenging_font": ("theme", "challenging_font"),
+    "colorblind_access": ("theme", "colorblind"),
+    "kanban_board": ("layout", "kanban_board"),
+    "broken_logos": ("layout", "broken_logos"),
+    "clickable_logos": ("layout", "clickable_logos"),
+}
+
+
+def migrate_appearance(
+    appearance: str,
+    *,
+    theme: str | None = None,
+    layout: str | None = None,
+) -> tuple[str | None, str | None]:
+    """Translate a legacy ``appearance`` stem into ``(theme, layout)``.
+
+    ``theme``/``layout`` are whatever the caller passed alongside it. A
+    disagreement raises rather than picking a winner silently — the caller
+    cannot tell from the result which of the two was applied.
+    """
+    try:
+        group, stem = APPEARANCE_MIGRATION[appearance]
+    except KeyError:
+        raise ValueError(
+            f"unknown appearance variant {appearance!r}. The appearance group "
+            f"was replaced by a shared theme + per-app layout; known legacy "
+            f"values are {', '.join(sorted(APPEARANCE_MIGRATION))}."
+        ) from None
+
+    passed = {"theme": theme, "layout": layout}[group]
+    if passed is not None and passed != stem:
+        raise ValueError(
+            f"appearance={appearance!r} maps to {group}={stem!r}, which "
+            f"conflicts with {group}={passed!r} passed alongside it. Drop the "
+            f"deprecated appearance argument."
+        )
+
+    warnings.warn(
+        f"appearance={appearance!r} is deprecated and will be removed; "
+        f"pass {group}={stem!r} instead.",
+        DeprecationWarning,
+        stacklevel=3,
+    )
+    return (stem, layout) if group == "theme" else (theme, stem)
+
+
 def list_variants(app_name: str, group: str) -> list[str]:
-    """List Hydra variant yamls for an app's group (``appearance``/``content``).
+    """List Hydra variant yamls for a group (``theme``/``layout``/``content``).
 
     Returns a sorted list of variant stems (without ``.yaml``).
     ``"default"`` is forced to index 0 when present so it has a stable
     sampling identity. Returns ``["default"]`` if the group dir is
     missing.
+
+    ``theme`` is a *shared* group (``config/apps/theme/``) applying to every
+    app, so ``app_name`` is ignored for it; all other groups are per-app.
+
+    Raises ``ValueError`` for the removed ``appearance`` group: its directory
+    is gone, so the generic missing-dir path would answer ``["default"]`` and
+    a caller sampling variations would silently lose every non-default one.
     """
-    group_dir = config_dir() / "apps" / config_dir_for(app_name) / group
+    if group == "appearance":
+        raise ValueError(
+            "the appearance group was removed; list_variants(app, 'theme') "
+            "for the shared design-token themes and "
+            "list_variants(app, 'layout') for this app's structure variants."
+        )
+    if group == "theme":
+        group_dir = config_dir() / "apps" / "theme"
+    else:
+        group_dir = config_dir() / "apps" / config_dir_for(app_name) / group
     if not group_dir.is_dir():
         return ["default"]
     stems = sorted(p.stem for p in group_dir.glob("*.yaml"))
diff --git a/src/open_apps/mcp/server.py b/src/open_apps/mcp/server.py
index fbaf3caa..f7e4983e 100644
--- a/src/open_apps/mcp/server.py
+++ b/src/open_apps/mcp/server.py
@@ -86,14 +86,32 @@ async def reset(seed: int | None = None):
 
 @mcp.tool()
 async def reconfigure(
-    appearance: str | None = None,
+    theme: str | None = None,
+    layout: str | None = None,
     content: str | None = None,
     seed: int | None = None,
     extras: dict | None = None,
+    appearance: str | None = None,
 ) -> str:
-    """Swap appearance/content variant and seed (live) and re-seed app state."""
+    """Swap theme/layout/content variant and seed (live) and re-seed app state.
+
+    `theme` is the shared design-token theme and applies to every app;
+    `layout` and `content` are per-app.
+
+    `appearance` is DEPRECATED: it names a stem from the removed `appearance`
+    group and is translated onto `theme`/`layout` (`dark_theme` -> `dark`,
+    `black_and_white` -> `mono`, `colorblind_access` -> `colorblind`,
+    `kanban_board`/`broken_logos`/`clickable_logos` -> the same `layout`).
+    Passing it alongside a conflicting `theme`/`layout` is an error. New
+    callers should use `theme`/`layout`; it will be removed in a later release.
+    """
     await _require().reconfigure(
-        appearance=appearance, content=content, seed=seed, extras=extras
+        theme=theme,
+        layout=layout,
+        content=content,
+        seed=seed,
+        extras=extras,
+        appearance=appearance,
     )
     return "reconfigured"
 
@@ -190,7 +208,7 @@ async def list_apps() -> list[str]:
 
 @mcp.tool()
 async def list_variants(app: str, group: str) -> list[str]:
-    """Variant stems for an app's ``appearance`` or ``content`` group."""
+    """Variant stems for a group: ``theme`` (shared), ``layout`` or ``content``."""
     return _list_variants(app, group)
 
 
diff --git a/src/open_apps/mcp/session.py b/src/open_apps/mcp/session.py
index 3bc99dca..476ed881 100644
--- a/src/open_apps/mcp/session.py
+++ b/src/open_apps/mcp/session.py
@@ -208,18 +208,24 @@ async def reset(self, *, seed: int | None = None, options: dict | None = None) -
     async def reconfigure(
         self,
         *,
-        appearance: str | None = None,
+        theme: str | None = None,
+        layout: str | None = None,
         content: str | None = None,
         seed: int | None = None,
         extras: dict | None = None,
+        appearance: str | None = None,
     ) -> None:
+        # ``appearance`` is the removed group, kept as a deprecated alias and
+        # translated onto theme/layout in AppServer.reconfigure.
         self._require_started()
         await asyncio.to_thread(
             self.appserver.reconfigure,
-            appearance=appearance,
+            theme=theme,
+            layout=layout,
             content=content,
             seed=seed,
             extras=extras,
+            appearance=appearance,
         )
 
     # -- action ------------------------------------------------------------
diff --git a/src/open_apps/theme.py b/src/open_apps/theme.py
new file mode 100644
index 00000000..3aa14c8c
--- /dev/null
+++ b/src/open_apps/theme.py
@@ -0,0 +1,202 @@
+"""
+Copyright (c) Meta Platforms, Inc. and affiliates.
+All rights reserved.
+This source code is licensed under the license found in the
+LICENSE file in the root directory of this source tree.
+
+Shared design-token theming for OpenApps.
+
+A *theme* is a set of design tokens (colors, typography, shape, spacing)
+defined once in ``config/apps/theme/<name>.yaml`` and shared across every
+app. Selecting a theme emits a ``:root { --token: value }`` block that all
+apps consume via ``var(--token)``. This decouples *look* (theme) from
+*structure* (each app's ``layout``) and from *behaviour* (plain keys in
+each app's ``config/apps/<app>/default.yaml``).
+
+Selection is done with Hydra overrides:
+
+* ``apps/theme=solarized``       -> global default for every app (the
+  ``apps/theme`` group is in ``config/config.yaml``'s defaults list)
+* ``apps.todo.theme=solarized``  -> override a single app (falls back to
+  the global theme when the app's ``theme`` field is null/unset)
+
+A theme file looks like::
+
+    # @package apps.theme
+    name: solarized
+    import_url: ""          # optional external stylesheet escape hatch
+    tokens:
+      color-bg: "#fdf6e3"
+      color-fg: "#657b83"
+      color-primary: "#268bd2"
+      font-family: "'Inter', sans-serif"
+      radius: "8px"
+      ...
+    assets:
+      tone: light
+      icon_set: color
+
+The ``tokens`` mapping is open-ended: every ``key: value`` becomes the CSS
+custom property ``--key: value``, so apps can introduce new tokens without
+touching this module.
+
+``assets`` covers what a CSS variable cannot reach: raster icons, Leaflet
+tile layers, CodeMirror stylesheets. It is deliberately *app-agnostic* --
+a theme declares intent (``tone: dark``) and each app maps that onto its
+own concrete choice, so a shared theme file never has to grow a key for
+every app in the repo. See :func:`theme_assets`.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from fasthtml.common import Style
+
+# Repo-root/config/apps/theme -- this file lives at src/open_apps/theme.py.
+_THEME_DIR = Path(__file__).resolve().parents[2] / "config" / "apps" / "theme"
+
+_DEFAULT_THEME = "default"
+
+# Fallbacks for a theme that predates (or omits) the `assets` block.
+_DEFAULT_ASSETS: dict[str, str] = {"tone": "light", "icon_set": "color"}
+
+
+def _as_plain(value):
+    """Coerce an OmegaConf node (or anything mapping-like) to a plain dict."""
+    if value is None:
+        return {}
+    # OmegaConf DictConfig exposes ``items``; so does a plain dict.
+    if hasattr(value, "items"):
+        return {k: v for k, v in value.items()}
+    return dict(value)
+
+
+def load_theme(name: str) -> dict:
+    """Load a theme's tokens from ``config/apps/theme/<name>.yaml``.
+
+    Returns a dict with at least ``name``, ``tokens``, ``import_url`` and
+    ``assets``. Falls back to the default theme when ``name`` is unknown so
+    a bad override degrades gracefully instead of raising.
+    """
+    # Two separate guards, both needed: the character check keeps a name from
+    # escaping _THEME_DIR (``../``, absolute paths), the existence check keeps
+    # a merely-unknown-but-well-formed name from raising FileNotFoundError.
+    if not name or any(not (char.isalnum() or char in "-_") for char in name):
+        name = _DEFAULT_THEME
+    path = _THEME_DIR / f"{name}.yaml"
+    if not path.exists():
+        path = _THEME_DIR / f"{_DEFAULT_THEME}.yaml"
+    data = yaml.safe_load(path.read_text()) or {}
+    data.setdefault("name", name)
+    data.setdefault("tokens", {})
+    data.setdefault("import_url", "")
+    data.setdefault("assets", {})
+    return data
+
+
+def resolve_theme(apps_config, app_name: str) -> dict:
+    """Resolve the effective theme for ``app_name``.
+
+    ``apps_config`` is the ``config.apps`` node handed to every app as
+    ``app.config``. Precedence: per-app ``apps.<app_name>.theme`` (a theme
+    name string) overrides the global ``apps.theme`` group; a null/unset
+    per-app value inherits the global theme.
+    """
+    app_cfg = getattr(apps_config, app_name, None)
+    per_app = getattr(app_cfg, "theme", None) if app_cfg is not None else None
+    if per_app:
+        return load_theme(str(per_app))
+
+    global_theme = getattr(apps_config, "theme", None)
+    if global_theme is not None:
+        # Allow global theme to be provided either as a composed config node
+        # (apps/theme=<name>) or as a plain string override (apps.theme=<name>).
+        if isinstance(global_theme, str):
+            return load_theme(global_theme)
+        theme = _as_plain(global_theme)
+        theme.setdefault("tokens", {})
+        theme["tokens"] = _as_plain(theme["tokens"])
+        theme.setdefault("assets", {})
+        theme["assets"] = _as_plain(theme["assets"])
+        return theme
+
+    return load_theme(_DEFAULT_THEME)
+
+
+def render_theme_css(theme: dict) -> str:
+    """Build the ``:root`` CSS-variable block (plus optional import) for a theme.
+
+    ``theme`` is the dict returned by :func:`resolve_theme` / :func:`load_theme`.
+    """
+    tokens = _as_plain(theme.get("tokens", {}))
+
+    safe_lines: list[str] = []
+    for key, value in tokens.items():
+        key = str(key)
+        # Allow only simple custom-property names to avoid broken CSS/injection.
+        if (not key) or any(not (c.isalnum() or c in "-_") for c in key):
+            continue
+        # Sanitize values to avoid breaking out of the declaration / <style> context.
+        val = (
+            str(value)
+            .replace("\n", " ")
+            .replace("\r", " ")
+            .replace(";", " ")
+            .replace("}", " ")
+            .replace("<", " ")
+            .replace(">", " ")
+            .strip()
+        )
+        safe_lines.append(f"  --{key}: {val};")
+
+    lines = "\n".join(safe_lines)
+
+    import_url = (theme.get("import_url") or "").strip()
+    # Avoid breaking out of the quoted @import string.
+    if any(c in import_url for c in ('"', "'", "\n", "\r", "<", ">")):
+        import_url = ""
+
+    import_rule = f'@import url("{import_url}");\n' if import_url else ""
+    return f"{import_rule}:root {{\n{lines}\n}}"
+
+
+def render_theme_tokens(theme: dict) -> Style:
+    """:func:`render_theme_css` wrapped in a FastHTML ``Style`` element."""
+    return Style(render_theme_css(theme))
+
+
+def theme_style(apps_config, app_name: str) -> Style:
+    """Convenience: resolve + render the token block for ``app_name`` in one call.
+
+    Call this per-request so live ``reconfigure`` theme swaps take effect.
+    """
+    return render_theme_tokens(resolve_theme(apps_config, app_name))
+
+
+# --------------------------------------------------------------------------
+# Non-CSS theme choices
+# --------------------------------------------------------------------------
+
+
+def theme_assets(apps_config, app_name: str) -> dict:
+    """The active theme's ``assets`` block for ``app_name``, with defaults filled.
+
+    Keys are app-agnostic on purpose:
+
+    * ``tone``     -- ``light`` | ``dark`` | ``mono``. Apps map this onto their
+      own concrete asset (maps picks a tile layer, the code editor picks a
+      CodeMirror stylesheet, the start page picks a tile fill).
+    * ``icon_set`` -- ``color`` | ``bw``. Which raster icon directory to serve.
+
+    A theme that omits ``assets`` (or omits a key) gets the light/color
+    defaults, so adding a new theme file never has to spell them out.
+    """
+    assets = dict(_DEFAULT_ASSETS)
+    assets.update(_as_plain(resolve_theme(apps_config, app_name).get("assets", {})))
+    return assets
+
+
+def theme_asset(apps_config, app_name: str, key: str, default=None):
+    """A single :func:`theme_assets` entry, or ``default`` when unset."""
+    return theme_assets(apps_config, app_name).get(key, default)
diff --git a/tests/save_screenshots.py b/tests/save_screenshots.py
index eceefba7..9b318289 100644
--- a/tests/save_screenshots.py
+++ b/tests/save_screenshots.py
@@ -61,36 +61,45 @@ class ComparisonResult:
 )
 
 
+THEME_DIR = REPO_ROOT / "config" / "apps" / "theme"
+
+CONTENT_APPS = ("start_page", "todo", "calendar", "messenger", "maps", "code_editor")
+
+# Per-app structure variants worth a screenshot of their own. Themes are
+# captured separately (one variation per stem) because they are global -- a
+# layout is not, so it has to name its app.
+LAYOUT_VARIATIONS = {
+    "layout_kanban_board": ["apps/todo/layout=kanban_board"],
+    "layout_broken_logos": ["apps/start_page/layout=broken_logos"],
+    "layout_clickable_logos": ["apps/start_page/layout=clickable_logos"],
+}
+
+
+def available_themes() -> list[str]:
+    """Theme stems under ``config/apps/theme/``, default first."""
+    stems = sorted(p.stem for p in THEME_DIR.glob("*.yaml"))
+    return ["default"] + [stem for stem in stems if stem != "default"]
+
+
 def build_variation_overrides(include_onlineshop: bool) -> dict[str, list[str]]:
-    appearance_apps = [
-        "start_page",
-        "todo",
-        "calendar",
-        "messenger",
-        "maps",
-        "code_editor",
-    ]
-    content_apps = list(appearance_apps)
     onlineshop_overrides = ["apps.onlineshop.enable=True"] if include_onlineshop else []
+    content_apps = list(CONTENT_APPS) + (["onlineshop"] if include_onlineshop else [])
 
-    if include_onlineshop:
-        appearance_apps.append("onlineshop")
-        content_apps.append("onlineshop")
-
-    return {
+    variations = {
         "default": onlineshop_overrides,
-        "dark_theme": onlineshop_overrides
-        + [f"apps/{app_name}/appearance=dark_theme" for app_name in appearance_apps],
-        "challenging_font": onlineshop_overrides
-        + [
-            f"apps/{app_name}/appearance=challenging_font"
-            for app_name in appearance_apps
-        ],
         "german": onlineshop_overrides
         + [f"apps/{app_name}/content=german" for app_name in content_apps],
         "long_descriptions": onlineshop_overrides
         + [f"apps/{app_name}/content=long_descriptions" for app_name in content_apps],
     }
+    # One variation per shared theme, named `theme_<stem>`. A single
+    # `apps/theme=` override reaches every app, which is what replaced the
+    # per-app `appearance` groups.
+    for theme in available_themes():
+        variations[f"theme_{theme}"] = onlineshop_overrides + [f"apps/theme={theme}"]
+    for name, overrides in LAYOUT_VARIATIONS.items():
+        variations[name] = onlineshop_overrides + overrides
+    return variations
 
 
 def parse_args() -> argparse.Namespace:
@@ -122,17 +131,14 @@ def parse_args() -> argparse.Namespace:
         "--variation",
         dest="variations",
         nargs="*",
-        choices=[
-            "default",
-            "dark_theme",
-            "challenging_font",
-            "german",
-            "long_descriptions",
-        ],
+        # Every `theme_*` and `layout_*` entry is selectable, but only the set
+        # below is captured by default -- the rest exist so the docs gallery
+        # can be regenerated with one command.
+        choices=sorted(build_variation_overrides(include_onlineshop=False)),
         default=[
             "default",
-            "dark_theme",
-            "challenging_font",
+            "theme_dark",
+            "theme_challenging_font",
             "german",
             "long_descriptions",
         ],
diff --git a/tests/test_apps.py b/tests/test_apps.py
index 48d2191a..028d546f 100644
--- a/tests/test_apps.py
+++ b/tests/test_apps.py
@@ -33,10 +33,12 @@
 @pytest.fixture(scope="module")
 def client(tmpdir_factory):
     logs_dir = str(tmpdir_factory.getbasetemp())
+    # Exercise a non-default selection on every axis: the shared theme
+    # (global), a per-app theme override, and per-app content.
     alt_config = [
-        "apps/messenger/appearance=challenging_font",
+        "apps/theme=challenging_font",
         "apps/messenger/content=misleading_descriptions",
-        "apps/calendar/appearance=dark_theme",
+        "apps.calendar.theme=dark",
     ]
     standard_overrides = [f"logs_dir={logs_dir}"]
 
diff --git a/tests/test_mcp.py b/tests/test_mcp.py
index 51823e4a..12ebb8b2 100644
--- a/tests/test_mcp.py
+++ b/tests/test_mcp.py
@@ -103,9 +103,89 @@ def test_config_dir_for(self):
         assert registry.config_dir_for("todo") == "todo"
 
     def test_list_variants_default_first(self):
-        variants = registry.list_variants("todo", "appearance")
-        assert variants[0] == "default"
-        assert "dark_theme" in variants
+        # Per-app structure group.
+        layouts = registry.list_variants("todo", "layout")
+        assert layouts[0] == "default"
+        assert "kanban_board" in layouts
+        # Shared design-token theme group (app_name ignored).
+        themes = registry.list_variants("todo", "theme")
+        assert themes[0] == "default"
+        assert "solarized" in themes
+
+    def test_list_variants_rejects_removed_appearance_group(self):
+        # Must not fall through to the missing-dir ``["default"]`` answer: a
+        # caller sampling variations would silently get a single-variant sweep.
+        with pytest.raises(ValueError, match="appearance group was removed"):
+            registry.list_variants("todo", "appearance")
+
+
+class TestAppearanceMigration:
+    """The removed ``appearance`` group, kept bindable for existing clients."""
+
+    def test_every_legacy_stem_maps_to_a_real_variant(self):
+        themes = set(registry.list_variants("todo", "theme"))
+        # Layouts are per-app and the legacy stems came from different apps
+        # (kanban_board from todo, the logo ones from start_page), so pool them.
+        layouts = {
+            p.stem
+            for group_dir in (config_dir() / "apps").glob("*/layout")
+            for p in group_dir.glob("*.yaml")
+        }
+        for stem, (group, target) in registry.APPEARANCE_MIGRATION.items():
+            pool = themes if group == "theme" else layouts
+            assert target in pool, f"appearance={stem} -> {group}={target}"
+
+    @pytest.mark.parametrize(
+        "appearance,expected",
+        [
+            ("default", ("default", None)),
+            ("dark_theme", ("dark", None)),
+            ("black_and_white", ("mono", None)),
+            ("challenging_font", ("challenging_font", None)),
+            ("colorblind_access", ("colorblind", None)),
+            ("kanban_board", (None, "kanban_board")),
+            ("broken_logos", (None, "broken_logos")),
+            ("clickable_logos", (None, "clickable_logos")),
+        ],
+    )
+    def test_maps_onto_theme_or_layout(self, appearance, expected):
+        with pytest.deprecated_call():
+            assert registry.migrate_appearance(appearance) == expected
+
+    def test_preserves_the_untouched_axis(self):
+        with pytest.deprecated_call():
+            assert registry.migrate_appearance("dark_theme", layout="kanban_board") == (
+                "dark",
+                "kanban_board",
+            )
+
+    def test_agreeing_value_is_not_a_conflict(self):
+        with pytest.deprecated_call():
+            assert registry.migrate_appearance("dark_theme", theme="dark") == (
+                "dark",
+                None,
+            )
+
+    def test_conflicting_value_raises(self):
+        with pytest.raises(ValueError, match="conflicts with"):
+            registry.migrate_appearance("dark_theme", theme="solarized")
+
+    def test_unknown_stem_raises_with_the_known_values(self):
+        with pytest.raises(ValueError, match="unknown appearance variant"):
+            registry.migrate_appearance("neon")
+
+    def test_reconfigure_tool_schema_still_binds_appearance(self):
+        # The published tool schema is the contract clients validate against:
+        # dropping the parameter fails their call before it reaches us.
+        from open_apps.mcp import server
+
+        tools = asyncio.run(server.mcp.list_tools())
+        schema = next(t for t in tools if t.name == "reconfigure").inputSchema
+        assert {"theme", "layout", "content", "seed", "extras"} <= set(
+            schema["properties"]
+        )
+        assert "appearance" in schema["properties"]
+        assert "appearance" not in schema.get("required", [])
 
 
 def _browsergym_calls(fn, *args):
diff --git a/tests/test_parallel_tasks.py b/tests/test_parallel_tasks.py
index 2d182247..234e35ab 100644
--- a/tests/test_parallel_tasks.py
+++ b/tests/test_parallel_tasks.py
@@ -126,3 +126,44 @@ def test_create_configs_count_all_longer_horizon(monkeypatch):
     configs = cfg.create_configs(_fake_default_config(task_names))
 
     assert len(configs) == len(task_names) * len(app_variations)
+
+
+class TestVariationOverridesCompose:
+    """The variation grids are raw Hydra override strings -- data, not code.
+
+    A renamed config group here raises at *launch* time, not import time, so
+    nothing catches it until a sweep is already holding an allocation. These
+    tests compose for real (no ``_stub_compose``), which is slower but is the
+    only thing that actually exercises the strings.
+    """
+
+    @staticmethod
+    def _compose(overrides: list[str]) -> None:
+        from hydra import compose, initialize_config_dir
+        from hydra.core.global_hydra import GlobalHydra
+
+        GlobalHydra.instance().clear()
+        with initialize_config_dir(config_dir=str(config_dir()), version_base=None):
+            compose(config_name="config_parallel_tasks", overrides=overrides)
+
+    def test_app_variations_in_config_parallel_tasks(self):
+        raw = OmegaConf.load(config_dir() / "config_parallel_tasks.yaml")
+        variations = OmegaConf.to_container(raw.parallel_tasks.app_variations)
+        assert variations, "no app_variations to check"
+        for overrides in variations:
+            try:
+                self._compose(list(overrides))
+            except Exception as e:
+                pytest.fail(f"app_variations entry {overrides} no longer composes: {e}")
+
+    def test_save_screenshots_variation_grid(self):
+        """Same guard for the visual-regression grid in save_screenshots.py."""
+        from tests.save_screenshots import build_variation_overrides
+
+        grid = build_variation_overrides(include_onlineshop=False)
+        assert grid, "no screenshot variations to check"
+        for name, overrides in grid.items():
+            try:
+                self._compose(list(overrides))
+            except Exception as e:
+                pytest.fail(f"screenshot variation {name!r} no longer composes: {e}")
diff --git a/tests/test_theme.py b/tests/test_theme.py
new file mode 100644
index 00000000..6f8a6cf9
--- /dev/null
+++ b/tests/test_theme.py
@@ -0,0 +1,219 @@
+"""
+Copyright (c) Meta Platforms, Inc. and affiliates.
+All rights reserved.
+This source code is licensed under the license found in the
+LICENSE file in the root directory of this source tree.
+"""
+
+"""
+Unit tests for shared design-token theming (open_apps.theme).
+
+Covers the two behaviours that are easy to regress when Hydra groups move
+around: theme *precedence* (per-app override beats the global group) and
+graceful *fallback* (an unknown theme name degrades to the default instead
+of raising).
+"""
+
+from fasthtml.common import to_xml
+from omegaconf import OmegaConf
+
+from open_apps.theme import (
+    load_theme,
+    render_theme_tokens,
+    resolve_theme,
+    theme_asset,
+    theme_assets,
+    theme_style,
+)
+
+
+def css(style) -> str:
+    """Render a ``Style`` FT element down to its CSS text."""
+    return to_xml(style)
+
+
+class TestLoadTheme:
+
+    def test_loads_known_theme(self):
+        theme = load_theme("solarized")
+        assert theme["name"] == "solarized"
+        assert theme["tokens"]["color-bg"] == "#fdf6e3"
+
+    def test_unknown_theme_falls_back_to_default(self):
+        theme = load_theme("does_not_exist")
+        default = load_theme("default")
+        assert theme["name"] == "default"
+        assert theme["tokens"] == default["tokens"]
+
+    def test_always_has_required_keys(self):
+        theme = load_theme("dark")
+        assert set(theme) >= {"name", "tokens", "import_url", "assets"}
+
+
+class TestTokenVocabulary:
+    """Every theme must declare the same tokens.
+
+    Apps use `var(--token)` without knowing which theme is active, so a theme
+    that omits one renders that property as an empty value -- an invisible
+    button rather than a loud failure.
+    """
+
+    THEMES = [
+        "default", "dark", "mono", "challenging_font",
+        "colorblind", "solarized", "material", "bootstrap",
+    ]
+
+    def test_all_themes_declare_the_default_vocabulary(self):
+        expected = set(load_theme("default")["tokens"])
+        for name in self.THEMES:
+            assert set(load_theme(name)["tokens"]) == expected, name
+
+    def test_dark_theme_is_actually_dark(self):
+        """Regression: `dark` was a port of todo's local variant and had a
+        white background with white foreground text."""
+        tokens = load_theme("dark")["tokens"]
+        assert tokens["color-bg"] != tokens["color-fg"]
+
+    def test_no_theme_has_invisible_body_text(self):
+        for name in self.THEMES:
+            tokens = load_theme(name)["tokens"]
+            assert tokens["color-bg"] != tokens["color-fg"], name
+
+
+class TestThemeAssets:
+
+    def test_defaults_when_theme_omits_assets(self):
+        cfg = OmegaConf.create({"theme": {"name": "x", "tokens": {}}, "todo": {}})
+        assert theme_assets(cfg, "todo") == {"tone": "light", "icon_set": "color"}
+
+    def test_reads_assets_from_the_theme_file(self):
+        cfg = OmegaConf.create({"theme": "dark", "maps": {}})
+        assert theme_assets(cfg, "maps")["tone"] == "dark"
+        assert theme_assets(cfg, "maps")["icon_set"] == "bw"
+
+    def test_partial_assets_are_filled_from_defaults(self):
+        cfg = OmegaConf.create(
+            {"theme": {"name": "x", "tokens": {}, "assets": {"tone": "dark"}}}
+        )
+        assert theme_assets(cfg, "todo") == {"tone": "dark", "icon_set": "color"}
+
+    def test_follows_per_app_theme_override(self):
+        cfg = OmegaConf.create({"theme": "default", "maps": {"theme": "dark"}})
+        assert theme_asset(cfg, "maps", "tone") == "dark"
+        assert theme_asset(cfg, "calendar", "tone") == "light"
+
+    def test_unknown_key_returns_default(self):
+        cfg = OmegaConf.create({"theme": "default"})
+        assert theme_asset(cfg, "todo", "no_such_key", "fallback") == "fallback"
+
+
+class TestResolveTheme:
+
+    def test_per_app_overrides_global(self):
+        cfg = OmegaConf.create(
+            {"theme": {"name": "dark", "tokens": {"color-bg": "#000000"}},
+             "todo": {"theme": "solarized"}}
+        )
+        assert resolve_theme(cfg, "todo")["name"] == "solarized"
+
+    def test_null_per_app_inherits_global(self):
+        cfg = OmegaConf.create(
+            {"theme": {"name": "dark", "tokens": {"color-bg": "#000000"}},
+             "todo": {"theme": None}}
+        )
+        theme = resolve_theme(cfg, "todo")
+        assert theme["name"] == "dark"
+        assert theme["tokens"]["color-bg"] == "#000000"
+
+    def test_unset_per_app_inherits_global(self):
+        cfg = OmegaConf.create(
+            {"theme": {"name": "dark", "tokens": {}}, "todo": {}}
+        )
+        assert resolve_theme(cfg, "todo")["name"] == "dark"
+
+    def test_global_as_plain_string(self):
+        """``apps.theme=solarized`` (dotted override) rather than a composed group."""
+        cfg = OmegaConf.create({"theme": "solarized", "todo": {}})
+        theme = resolve_theme(cfg, "todo")
+        assert theme["name"] == "solarized"
+        assert theme["tokens"]["color-bg"] == "#fdf6e3"
+
+    def test_no_theme_anywhere_falls_back_to_default(self):
+        cfg = OmegaConf.create({"todo": {}})
+        assert resolve_theme(cfg, "default_probe") == load_theme("default")
+
+    def test_unknown_app_falls_back_to_global(self):
+        cfg = OmegaConf.create({"theme": "solarized"})
+        assert resolve_theme(cfg, "no_such_app")["name"] == "solarized"
+
+    def test_unknown_per_app_name_degrades_to_default(self):
+        cfg = OmegaConf.create({"theme": "solarized", "todo": {"theme": "bogus"}})
+        # A bad per-app override must not raise, and must not silently
+        # inherit the global theme either -- it resolves to the default file.
+        assert resolve_theme(cfg, "todo")["tokens"] == load_theme("default")["tokens"]
+
+    def test_resolved_tokens_are_plain_dicts(self):
+        """Callers index tokens directly; OmegaConf nodes must be coerced."""
+        cfg = OmegaConf.create({"theme": {"name": "x", "tokens": {"radius": "4px"}}})
+        theme = resolve_theme(cfg, "todo")
+        assert isinstance(theme, dict) and isinstance(theme["tokens"], dict)
+        assert theme["tokens"]["radius"] == "4px"
+
+    def test_apps_config_isolated_per_app(self):
+        cfg = OmegaConf.create(
+            {"theme": "default",
+             "todo": {"theme": "solarized"},
+             "calendar": {}}
+        )
+        assert resolve_theme(cfg, "todo")["name"] == "solarized"
+        assert resolve_theme(cfg, "calendar")["name"] == "default"
+
+
+class TestRenderThemeTokens:
+
+    def test_tokens_become_custom_properties(self):
+        out = css(render_theme_tokens(
+            {"tokens": {"color-bg": "#fff", "radius": "8px"}}
+        ))
+        assert ":root {" in out
+        assert "--color-bg: #fff;" in out
+        assert "--radius: 8px;" in out
+
+    def test_empty_tokens_still_renders_valid_block(self):
+        out = css(render_theme_tokens({}))
+        assert ":root {" in out and "}" in out
+        assert "--" not in out
+
+    def test_unsafe_token_names_are_dropped(self):
+        out = css(render_theme_tokens(
+            {"tokens": {"ok-name": "1", "bad; }": "2", "": "3", "a b": "4"}}
+        ))
+        assert "--ok-name: 1;" in out
+        assert "bad" not in out and "a b" not in out
+
+    def test_newlines_in_values_are_flattened(self):
+        out = css(render_theme_tokens({"tokens": {"font-family": "a\nb\rc"}}))
+        assert "--font-family: a b c;" in out
+
+    def test_import_url_is_emitted(self):
+        out = css(render_theme_tokens(
+            {"import_url": "https://example.com/f.css", "tokens": {}}
+        ))
+        assert '@import url("https://example.com/f.css");' in out
+
+    def test_import_url_with_quotes_is_dropped(self):
+        out = css(render_theme_tokens(
+            {"import_url": 'https://x.test/f.css"); body{display:none', "tokens": {}}
+        ))
+        assert "@import" not in out
+
+    def test_missing_import_url_emits_no_rule(self):
+        assert "@import" not in css(render_theme_tokens({"tokens": {"a": "b"}}))
+
+
+class TestThemeStyle:
+
+    def test_resolves_and_renders_in_one_call(self):
+        cfg = OmegaConf.create({"theme": "default", "todo": {"theme": "solarized"}})
+        assert "--color-bg: #fdf6e3;" in css(theme_style(cfg, "todo"))
+        assert "--color-bg: #ffffff;" in css(theme_style(cfg, "calendar"))