updated documentation

README.md

@@ -148,6 +148,11 @@ Pages have an `environment` field (`dev`, `stage`, `production`) that determines
 | `audio_player` | Audio player |
 | `popup` | Modal popup |
 
+**Element Defaults:** Each element type has configurable default settings that follow a three-tier hierarchy:
+- **Global** (`element_type_defaults`) - Platform-wide defaults (auto-seeded)
+- **Project** (`project_element_defaults`) - Per-project overrides (auto-snapshotted on project creation)
+- **Instance** (`tour_pages.ui_schema_json`) - Page-specific element values
+
 ## API Overview
 
 Base URL: `http://localhost:8080/api`

frontend/README.md

@@ -233,6 +233,20 @@ The tour builder supports these UI elements:
 | `audio_player` | Audio player |
 | `popup` | Popup/modal |
 
+### Element Defaults Hierarchy
+
+Element types follow a three-tier defaults system:
+
+1. **Global** (`element_type_defaults`) - Platform-wide default settings (11 predefined types)
+2. **Project** (`project_element_defaults`) - Project-specific overrides (auto-snapshotted on project creation)
+3. **Instance** (`tour_pages.ui_schema_json`) - Page-specific element instances with custom settings
+
+The constructor fetches project defaults via `/api/project-element-defaults?projectId=xxx` and merges them when creating new elements. Existing element values in `ui_schema_json` take precedence over defaults.
+
+**Key files:**
+- `types/constructor.ts` - `normalizeElementDefault()`, `buildElementDefaultsMap()` utilities
+- `pages/constructor.tsx` - Loads project defaults, creates elements with merged settings
+
 ## Content Environments
 
 Tour pages have a three-tier environment model: