Skip to content

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 detail
  • platform/themes/base/README.md (in store-core, until it becomes store-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, …
LayerWhat it isCan be activated?Lives in
theme-kitA package: Blade components, design tokens, SCSSNowebhaki-cms-core → platform/packages/theme-kit
Base themeA hidden parent theme: layouts, header/footer, page views, theme optionsNo (hidden)site-base in site-core, store-base in store-core
Website themeOne website's look: inherits its base and overrides only what differsYesThe 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 providestheme-kit provides
Layouts (default, full-width, homepage, blog-sidebar)—
The site header and footer, assembled from logo + menu + switcherlogo, 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-base and store-base would 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.