zakblacki Botble Theme Development
Use this for theme-side work under platform/themes/{theme}. Theme code has different translation and rendering rules from plugins.
Workflow
- Inspect the active theme structure and existing partials before adding files.
- Keep Blade views focused; split files near 150 lines into partials.
- Register assets and theme behavior from
config.php, commonly insidebeforeRenderTheme. - Use
Theme::scope(),Theme::partial(),theme_option(), and Theme getters instead of ad hoc global access. - Create shortcodes with frontend views and admin config forms when content editors need controls.
- Create widgets with separate frontend and backend templates.
- Avoid DB queries in header/footer; use view composers or prepared data.
Structure
platform/themes/{theme}/
assets/
config.php
functions/
lang/
layouts/
partials/
public/
views/
widgets/
theme.json
vite.build.mjs
Rules
- Use
__('Text')in themes and flat JSON language files. - Use
trans()only for plugin/package/core namespaces from theme code. - Use
RvMedia::getImageUrl()for all media paths. - Use
Theme::getSiteTitle(),Theme::getLogo(), andTheme::getSiteCopyright()where applicable. - Use
ThemeSupport::registerSocialLinks(),registerPreloader(), and related helpers instead of custom duplicated options. - Register frontend routes through
Theme::registerRoutes()when theme routes are needed. - For multiple shortcode instances, generate unique slider/carousel IDs.
- Do not add CDN assets or inline scripts/styles.
- Declare theme asset entries in
vite.build.mjs; do not addwebpack.mix.js.
Shortcodes
Use admin config fields such as text, textarea, image, select, onOff, number, color, and tabs. Sanitize HTML output and pass editor-controlled images through RvMedia.
TailwindCSS v4 Themes
When the theme uses TailwindCSS v4:
- Keep configuration in CSS, not
tailwind.config.js. - Use
@source,@custom-variant dark, and@theme. - Use OKLCH colors when defining design tokens.
- Implement dark mode via the
.darkclass on<html>.
Asset Builds
- Run
npm run devfor an unminified build. - Run
npm run productionfor minified assets and the module-localpublic/mirror. - Do not prescribe
npm run watch; Botble's Vite pipeline has no watch mode or dev server.
Load References
Read references/theme-patterns.md for compact snippets.