Hyvä Theme Development (Magento 2 / Mage-OS)

Hyvä is a Magento frontend theme that replaces the Luma stack (RequireJS + Knockout + jQuery + LESS) with Alpine.js + Tailwind CSS, plus Magewire for reactive server-rendered components. It ships far less JavaScript and is the de-facto modern choice for new Magento and Mage-OS storefronts. Layout XML, view models, and the module system are unchanged — only the template/JS/CSS layer differs.

Hyvä's core theme is commercial (a one-time license, package hyva-themes/magento2-default-theme); the supporting Hyva_Theme module and many helpers are MIT. This skill covers the development conventions; it does not bundle or require the licensed theme.

Workflow

1. Identify the task and read the matching reference before writing code:

1. For a new theme, scaffold the skeleton with the script — it produces the child-theme

files and the web/tailwind/ build directory deterministically:

   python scripts/scaffold-theme.py "Vendor/theme-name" --parent Hyva/default

1. Implement templates with Alpine for client-side interactivity and Magewire when the

logic belongs on the server. Keep JavaScript minimal — that is the entire point of Hyvä.

1. Build the CSS and verify. Tailwind compiles web/tailwind/tailwind-source.css →

web/css/styles.css:

   cd app/design/frontend/Vendor/theme/web/tailwind && npm ci && npm run build
   bin/magento cache:flush
   # production: bin/magento setup:static-content:deploy -f

Non-negotiable conventions (why they matter)

• No RequireJS, Knockout, or jQuery. If you reach for data-mage-init, require([...]),

or $(...), you're writing Luma, not Hyvä. Use Alpine (x-data, @click, x-model) for client interactivity, Magewire for server interactivity.

• Style with Tailwind utility classes, not custom LESS/CSS files. Component classes go in

the Tailwind layer via @apply only when a utility string genuinely repeats.

• Escape output exactly as in Luma — $escaper->escapeHtml() / escapeHtmlAttr() /

escapeUrl(). Alpine expressions in attributes are still attribute values: escape the PHP-injected parts.

• CSP matters. Hyvä storefronts commonly run Magento's Content-Security-Policy in

restrict mode; inline event handlers and scripts must go through the secure renderer / Hyvä's CSP-friendly patterns (references/alpine.md).

• Logic still lives in view models, not blocks or templates — same rule as Luma

(see the magento-module frontend.md reference).

Verification note

A running Hyvä theme requires the licensed hyva-themes/magento2-default-theme package. When it isn't installed, verify generated code structurally: theme registration and theme.xml parent resolve, tailwind.config.js/package.json are valid, layout XML validates, and templates escape output. Note in your summary that a live render needs a Hyvä-licensed environment.

Pairing

• Backend for the feature (the module, its data, di.xml, APIs) → magento-module skill.
• "Why is my Hyvä store slow / not caching" → magento-audit skill.