1eaa5f5d16
Phase 04: Theme Engine - Template syntax decisions (Twig-style, string templates) - Layout composition (WinterCMS-style placeholders) - Asset pipeline requirements (hot reload, bundling) - Rendering modes (SPA, hybrid, static)
83 lines
2.7 KiB
Markdown
83 lines
2.7 KiB
Markdown
# Phase 4: Theme Engine - Context
|
|
|
|
**Gathered:** 2026-02-04
|
|
**Status:** Ready for planning
|
|
|
|
<domain>
|
|
## Phase Boundary
|
|
|
|
Render themes with layouts, partials, and Vue integration. Includes asset management and multiple rendering modes (SPA, hybrid, static). Theme creation tooling and CLI scaffolding are separate phases.
|
|
|
|
</domain>
|
|
|
|
<decisions>
|
|
## Implementation Decisions
|
|
|
|
### Template Syntax
|
|
- String templates with interpolation (not ScalaTags) — designers can work with HTML directly
|
|
- Twig-style syntax for includes: `{% partial 'header' %}`
|
|
- Variable passing supports both named parameters and context objects:
|
|
- Simple: `{% partial 'card' title='Hello' count=5 %}`
|
|
- Complex: `{% partial 'card' with cardData %}`
|
|
- Components expose variables implicitly — templates can use component data directly (WinterCMS style)
|
|
|
|
### Layout Composition
|
|
- Pages declare layout in front matter YAML: `layout: default`
|
|
- WinterCMS-style placeholder system:
|
|
- `{% page %}` injects main page content
|
|
- Named placeholders supported: `{% placeholder 'sidebar' %}`
|
|
- Flat layout structure only — no layout inheritance
|
|
- Use partials for shared pieces across layouts
|
|
- Theme metadata in `theme.yaml` at theme root
|
|
|
|
### Asset Pipeline
|
|
- Research best Scala ecosystem options for manifest/bundling
|
|
- Manifest file preferred if no better standard tool exists
|
|
- Hot reload essential for development workflow
|
|
- Production optimization requirements:
|
|
- Minification with content hashing for cache busting
|
|
- Separate bundles: vendor, app, critical CSS
|
|
- Plugin asset injection like WinterCMS:
|
|
- `addCss()` and `addJs()` for global hooks
|
|
- Component-scoped assets load when components are used
|
|
- Both mechanisms supported
|
|
|
|
### Rendering Modes
|
|
- Theme default in `theme.yaml`, per-page override in front matter
|
|
- Three modes: `spa`, `hybrid`, `static`
|
|
- SPA mode: Server renders HTML, Vue 3 hydrates on client
|
|
- Hybrid mode: Page-level granularity (whole page is either server or SPA)
|
|
- Static mode supports both:
|
|
- Build-time generation via CLI command
|
|
- On-demand generation with caching
|
|
|
|
### Claude's Discretion
|
|
- Specific string template library/implementation for Scala
|
|
- Asset bundling tool selection (investigate Scala ecosystem)
|
|
- Hot reload implementation approach
|
|
- Exact Vue hydration setup
|
|
- Cache invalidation strategy for static mode
|
|
|
|
</decisions>
|
|
|
|
<specifics>
|
|
## Specific Ideas
|
|
|
|
- Template syntax should feel familiar to WinterCMS developers — Twig-style tags
|
|
- Asset injection API similar to WinterCMS `addCss()` and `addJs()` functions
|
|
- Hot reload is essential — CSS/JS changes must reflect immediately in dev mode
|
|
|
|
</specifics>
|
|
|
|
<deferred>
|
|
## Deferred Ideas
|
|
|
|
None — discussion stayed within phase scope
|
|
|
|
</deferred>
|
|
|
|
---
|
|
|
|
*Phase: 04-theme-engine*
|
|
*Context gathered: 2026-02-04*
|