# Phase: Experience Theme & Layout Engine (11.3)

| Field | Value |
| --- | --- |
| Identifier | `experience-11.3` |
| Status | Complete |
| Owner | Platform |
| Module(s) | Themes, Theme Versions, Layouts, Layout Versions, Site Theme Bindings, Page Layout Bindings |
| Service(s) | `experience` (Torbat Pages) |
| Depends On | `experience-11.2` |
| ADR(s) | [ADR-016](architecture/adr/ADR-016.md), [ADR-008](architecture/adr/ADR-008.md) |
| Manifest | [phase-manifest.yaml](ai-framework/phase-manifest.yaml) |

## Enterprise Phase Discovery Record

| Input | Finding |
| --- | --- |
| Roadmap / manifest | Next unfinished Experience phase = `experience-11.3` Theme & Layout Engine |
| Prior handover | [phase-11-2.md](phase-handover/phase-11-2.md) — themes/layouts only; no template catalog |
| Boundaries | Experience owns themes/layouts; brand tokens align with ADR-008; no Core DB access |
| Existing codebase | Components/versions/placements complete; themes/layouts were capability flags False |
| Missing vs DoD | Theme packs, dynamic layouts, directionality shells, site/page assignments, policies/specs/CQ |

Derived capabilities: replaceable theme packs with immutable, versioned CSS tokens; dynamic layouts with immutable, versioned regions; RTL/LTR/both shells; bind a published theme version to a site and a published layout version to a page. **Not** templates, forms, SEO, visual builder UI.

## Objective

Deliver production-ready replaceable themes and dynamic layouts on `experience_db` using a catalog + immutable version model (mirrors the Phase 11.2 component/component-version pattern) with directionality-ready shells and binding APIs — without a template catalog engine.

## Scope

### In Scope

- `ExperienceTheme` (catalog: code, name, direction_mode, status, latest/published version pointers)
- `ExperienceThemeVersion` (immutable once published: tokens, brand_shell, direction_mode override)
- `ExperienceLayout` (catalog: code, name, kind, direction_mode, status, latest/published version pointers)
- `ExperienceLayoutVersion` (immutable once published: regions, structure_shell)
- `SiteThemeBinding` (pins a published theme version to a site; replaceable)
- `PageLayoutBinding` (pins a published layout version to a page; replaceable)
- Policies, specifications, commands, queries
- Pagination / filter / sort / search on list APIs
- Permissions `experience.themes.*` / `experience.layouts.*`
- Events `experience.theme.*` / `experience.theme_version.*` / `experience.layout.*` / `experience.layout_version.*` / `experience.site_theme.*` / `experience.page_layout.*`
- Alembic `0004_phase_113_themes_layouts`; version `0.11.3.0`
- Seed discovery: `direction_modes` via `/capabilities`

### Out of Scope

- Template catalog / instantiation — Phase 11.4
- Full localization media pipeline — Phase 11.5
- Forms / surveys — Phase 11.6
- Owning Core tenant brand tables (ADR-008 remains Core; Experience stores theme packs)

### Models

| Entity | Soft delete | Audit | Tenant | Optimistic lock |
| --- | --- | --- | --- | --- |
| ExperienceTheme | Yes | Yes | Yes | Yes |
| ExperienceThemeVersion | Yes | Yes | Yes | Yes |
| ExperienceLayout | Yes | Yes | Yes | Yes |
| ExperienceLayoutVersion | Yes | Yes | Yes | Yes |
| SiteThemeBinding | Yes | Yes | Yes | Yes |
| PageLayoutBinding | Yes | Yes | Yes | Yes |

### Permissions

`experience.themes.view|create|update|delete|manage`

`experience.layouts.view|create|update|delete|manage`

### Events

`experience.theme.created|updated|activated|deprecated|archived`

`experience.theme_version.created|updated|published|retired`

`experience.layout.created|updated|activated|deprecated|archived`

`experience.layout_version.created|updated|published|retired`

`experience.site_theme.assigned|replaced|unassigned`

`experience.page_layout.assigned|replaced|unassigned`

### APIs

| Method | Path |
| --- | --- |
| * | `/api/v1/themes` (+ activate/deprecate/archive/delete) |
| * | `/api/v1/theme-versions` (+ publish/retire) |
| * | `/api/v1/layouts` (+ activate/deprecate/archive/delete) |
| * | `/api/v1/layout-versions` (+ publish/retire) |
| * | `/api/v1/site-theme-bindings` (+ unassign) |
| * | `/api/v1/page-layout-bindings` (+ unassign) |

### Artifact coverage (DoD)

| Artifact | Status |
| --- | --- |
| Discovery | This record |
| Policies / Specs / Commands / Queries | Implemented |
| Soft delete / Optimistic lock / Audit / Tenant | Yes |
| Pagination / Filter / Sort / Search | Yes |
| Background jobs | N/A — no async work in phase boundary |
| Templates | Explicitly out of scope |

### Tests

- [x] Unit policies
- [x] API theme/layout/assignment flow
- [x] Tenant isolation + optimistic lock
- [x] Architecture / permission / migration / docs

## Completion Criteria

- [x] Theme and layout APIs + tests green
- [x] No template catalog engine
- [x] Docs / manifests / handover updated

## Related Documents

- [Handover](phase-handover/phase-11-3.md)
- [Phase 11.2](experience-phase-11-2.md)
- [Experience Roadmap](experience-roadmap.md)
- [ADR-016](architecture/adr/ADR-016.md)
- [ADR-008](architecture/adr/ADR-008.md)