Magento Hyva

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:

| Task | Read first | |---|---| | New child theme, Tailwind build setup | [references/theme-setup.md](references/theme-setup.md) | | Interactivity in templates (Alpine.js) | [references/alpine.md](references/alpine.md) | | Styling, Tailwind config, design tokens | [references/tailwind.md](references/tailwind.md) | | Reactive server-driven components (forms, cart) | [references/magewire.md](references/magewire.md) | | Override a template, add a block, layout XML | [references/overriding.md](references/overriding.md) | | A Luma module/extension breaks on Hyvä | [references/luma-compat.md](references/luma-compat.md) |

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

files and the web/tailwind/ build directory deterministically:

``bash 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:

``bash 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](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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: staksoft
• Source: staksoft/magento-claude-skills
• License: MIT
• Homepage: https://www.staksoft.com

Install and usage instructions live in the source repository linked above.