Appearance
Theme layers
How front-end themes are organized in Webhaki:
- the three theme layers: theme-kit, base themes and website themes
- how the theme engine finds views
- how to build, override and release a theme
Related:
- What goes where: which repo owns what
platform/packages/theme-kit/README.md(in cms-core): the theme-kit API in detailplatform/themes/base/README.md(in store-core, until it becomesstore-base): the base theme's design system
The three layers
webhaki-cms-core theme-kit (package) shared parts: components, design tokens, SCSS
│ used by
┌──────────────┴──────────────┐
webhaki-site-core site-base (hidden) webhaki-store-core store-base (hidden)
complete theme for complete theme for
business websites online stores
│ inherited by │ inherited by
website repos site-default, companyA, … default, mila, hatstore, …| Layer | What it is | Can be activated? | Lives in |
|---|---|---|---|
| theme-kit | A package: Blade components, design tokens, SCSS | No | webhaki-cms-core → platform/packages/theme-kit |
| Base theme | A hidden parent theme: layouts, header/footer, page views, theme options | No (hidden) | site-base in site-core, store-base in store-core |
| Website theme | One website's look: inherits its base and overrides only what differs | Yes | The website's repo (starters site-default / default in the cores) |
Theme-kit vs. base theme
theme-kit is a box of parts. A base theme is a finished, working theme built from those parts. You need both.
What theme-kit is
A package (a library), not a theme. It holds the small pieces every theme needs to look and behave the same:
- Blade components:
<x-theme-kit::logo />,<x-theme-kit::breadcrumbs />,<x-theme-kit::menu />,<x-theme-kit::icon />,<x-theme-kit::language-switcher /> - Design tokens (
--theme-color-primary, spacing, fonts…) and the SCSS variables and mixins - The CSS of those components
It cannot be activated. It has no layouts, no pages, no header or footer, no theme options, and no view fallback.
What a base theme is
A real (hidden) theme that puts the parts together into complete pages:
| A base theme provides | theme-kit provides |
|---|---|
| Layouts (default, full-width, homepage, blog-sidebar) | — |
| The site header and footer, assembled from logo + menu + switcher | logo, menu, switcher |
| Page, post, blog, search, 404 views | — |
Product, cart, checkout, account views (store-base only) | — |
| Theme options (colors, header, footer…) | tokens the options override |
| View fallback for child themes | — |
The last row is the main reason base themes exist. With 'inherit' => 'store-base', every view that mila doesn't have is taken from store-base. A package cannot do that: the theme engine only falls back to a theme, and only one level up (see How the theme engine works).
Why both
- Without base themes, every website theme would have to contain all layouts and views itself. A fix to the blog page would have to be made in every theme separately.
- Without theme-kit,
site-baseandstore-basewould each keep their own copy of the logo, menu, breadcrumbs and tokens. Inheritance can't share them (one base can't inherit the other), so the copies would drift apart.
Keep the base themes thin
A base theme's shared partials are one-line wrappers around the kit:
blade
{{-- platform/themes/store-base/partials/logo.blade.php --}}
<x-theme-kit::logo :class="$class ?? ''" :dark="$dark ?? false" />The partial names stay the same, so website themes and plugins that call Theme::partial('logo') keep working. The base itself only keeps what is specific to it: how pages are composed, plus the ecommerce views in store-base.
When both bases end up repeating a whole block (a header layout, a footer, a post card), move that block into theme-kit as a component. The bases get thinner over time, but never go away: view inheritance and page layouts have to live in a theme.