/magento-hyva

name: magento-hyva
description: >-
  Hyvä theme development for Magento 2 / Mage-OS / Adobe Commerce: building and customizing
  Hyvä storefronts with Alpine.js and Tailwind CSS, Magewire reactive server-driven components,
  child-theme setup and the Tailwind build, overriding Hyvä/Luma templates and layout XML, and
  Luma-to-Hyvä compatibility. Use this skill whenever the user mentions Hyvä (hyva), or is
  doing Magento frontend work with Alpine.js, Tailwind, or Magewire — creating or styling a
  Hyvä theme, writing Alpine components in .phtml, configuring tailwind.config.js, building a
  Magewire component, fixing a Luma module that breaks on Hyvä, or converting a storefront from
  Luma to Hyvä. Strong triggers: "hyva theme", "alpine.js in magento", "tailwind in magento",
  "magewire", "my hyva component isn't reactive", "convert luma to hyva". For backend/module
  work (plugins, observers, db schema, DI, REST/GraphQL, CLI) use the magento-module skill; for
  storefront performance audits use the magento-audit skill.

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) |

2. **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

3. **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ä.

4. **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](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.