hyva-ui-component
Hyva UI Component
Applies Hyva UI template-based (non-CMS) components to a Hyvä theme by copying files from {hyva_ui_path}/components/ to app/design/frontend/{Vendor}/{Theme}/.
Path variable: {hyva_ui_path} = vendor/hyva-themes/hyva-ui (default) or user-provided custom path.
Command execution: For any commands that need to run inside the development environment (e.g., bin/magento commands), use the hyva-exec-shell-cmd skill to detect the environment and determine the appropriate command wrapper.
Step 0: Verify Hyva UI Installation
ls vendor/hyva-themes/hyva-ui/components/ 2>/dev/null
If NOT found, offer options: (A) User provides custom extraction path, (B) composer require --dev hyva-themes/hyva-ui, (C) Download from https://hyva.io/my-account/my-downloads/
After install, refresh catalog: <skill_path>/scripts/refresh_catalog.sh {hyva_ui_path} <skill_path>/references/components.md
Where <skill_path> is the directory containing this SKILL.md file.
Step 1: Identify Theme Path
Use the hyva-theme-list skill to find existing Hyvä themes. Filter the results to only include themes in app/design/frontend/ (exclude vendor themes).
Prompt the user to select:
- Existing Hyvä themes: List themes returned by the script as options (e.g.,
Example/winterWonderTheme) - Create new theme: Always include an option to create a new child theme
If user selects "Create new theme":
- Use the
hyva-child-themeskill to create the new theme first - Continue with the newly created theme path after the skill completes
If user selects an existing theme:
Continue with the selected theme path: app/design/frontend/{Vendor}/{Theme}
Step 2: List or Select Component
If no component specified or user asks to list components, show only the "Non-CMS Components (Template-Based)" section from references/components.md.
Do NOT list or mention:
- CMS components (accordion, card, categories, error-page, generic-content, order-confirmation, shortcuts, testimonial, usp, product-data/C-highlights)
- Plugins (alpine-collapse, splidejs, sticky-header, tailwind-v3-design-tokens, tailwind-v4)
These are internal dependencies or require the CMS Tailwind JIT compiler and are not applicable for direct installation via this skill.
Step 3: Show Variants
Variants: A=Basic, B=Enhanced, C=Advanced, D=Specialized. List with: ls {hyva_ui_path}/components/{component}/
Step 4: Read Component README
Always read {hyva_ui_path}/components/{component}/{variant}/README.md before copying. Present to user: dependencies, configuration options, special requirements.
Step 5: Copy Component Files
Before copying, check which destination files already exist to track created vs updated:
# List source files
find {hyva_ui_path}/components/{component}/{variant}/src -type f
# For each source file, check if destination exists
# e.g., for src/Magento_Catalog/templates/product/view/gallery.phtml
# check: {theme_path}/Magento_Catalog/templates/product/view/gallery.phtml
Track each file as either:
- created: Destination file did not exist before copy
- updated: Destination file already existed (will be overwritten)
Then copy:
cp -r {hyva_ui_path}/components/{component}/{variant}/src/* {theme_path}/
The src/ directory contains Magento module folders (Magento_Theme/, Magento_Catalog/, etc.) that map directly to theme structure. For existing layout XML files, merge content rather than overwriting.
Step 5.5: Add XML Configuration Options
Check if README contains XML configuration (look for <var name=", etc/view.xml).
If found:
- Extract the first XML block containing
<var name=elements with default values - Identify the module attribute (e.g.,
module="Magento_Catalog") - Add to
{theme_path}/etc/view.xml:- If file doesn't exist: Create with full
<view>structure - If
<vars module="...">exists: Add<var>elements inside it - If section missing: Add new
<vars module="...">before</view>
- If file doesn't exist: Create with full
- Notify: "Added configuration options to
{theme_path}/etc/view.xmlwith default values."
Preserve existing view.xml content and keep XML comments from README.
Step 6: Handle Dependencies
Check README for dependencies and install them automatically (do not ask the user to select plugins):
- Plugin dependencies: Copy required files from
{hyva_ui_path}/plugins/{plugin}/src/(e.g., splidejs for gallery/D-splide) - Component dependencies: Apply dependent components first
- External packages: e.g.,
composer require hyva-themes/magento2-hyva-payment-icons
Step 7: Ask to recompile styles
- Rebuild Tailwind: Always ask: "Do you need to recompile Tailwind CSS styles?" Never automatically build — an external tool may already be handling this. If the user wants to compile, use the
hyva-compile-tailwind-cssskill with the target theme.
Step 8: Output Summary
After applying all changes, output a summary of modifications:
8.1: List Modified Files
Display all files that were created or modified during this component installation. Use the tracking from Step 5 to label each file correctly:
- (created): File did not exist before and was newly created
- (updated): File already existed and was overwritten
Modified files:
- {theme_path}/Magento_Catalog/templates/product/view/gallery.phtml (updated)
- {theme_path}/Magento_Theme/templates/html/header.phtml (created)
- {theme_path}/etc/view.xml (updated)
8.2: XML Configuration Table
If XML configuration was added to {theme_path}/etc/view.xml, parse the XML block from the README and display a table of options:
# Extract the XML config block from README and parse it
php <skill_path>/scripts/parse_readme_xml.php --format=table < xml_block.txt
The table shows each option with columns:
- Option: The full option path without a common prefix (e.g.,
magnifier.enable) - Value: The default value configured
- Description: Explanatory text from the XML comment
Example output (common prefix like gallery. is automatically stripped):
Option | Value | Description
---------------------+------------+---------------------------------------------------
nav | thumbs | Gallery navigation style (false/thumbs/counter)
magnifier.enable | false | Turn on/off magnifier (true/false)
For markdown output (e.g., when creating documentation), use --format=md.
Step 9: Final steps
- Review copied templates for store-specific customization
Quick Reference
{hyva_ui_path}/components/{component}/{variant}/
├── README.md # Instructions
├── media/ # Preview images
└── src/ # Files to copy to theme
See references/components.md for the full component catalog (only show non-CMS section to users).
More from hyva-themes/hyva-ai-tools
hyva-exec-shell-cmd
Utility skill to detect Magento development environment and determine command wrapper. This skill should be used by other skills that need to execute shell commands in the Magento environment. It detects Warden, docker-magento, DDEV, and local environments and provides the appropriate command wrapper.
342hyva-alpine-component
Write CSP-compatible Alpine.js components for Hyvä themes in Magento 2. This skill should be used when the user wants to create Alpine components, add interactivity to Hyvä templates, write JavaScript for Hyvä themes, or needs help with Alpine.js patterns that work with Content Security Policy. Trigger phrases include "create alpine component", "add interactivity", "alpine for hyva", "x-data component", "csp compatibility", "csp compliant javascript".
336hyva-child-theme
Create a Hyvä child theme in a Magento 2 project. This skill should be used when the user wants to create a new Hyvä child theme, set up a custom theme based on Hyvä, or initialize a new frontend theme directory structure. Trigger phrases include "create hyva child theme", "new hyva theme", "setup child theme", "create custom theme", "initialize theme".
333hyva-render-media-image
Generate responsive image code for Hyvä Theme templates using the Media view model. This skill should be used when the user wants to render images in a Hyvä template, create responsive picture elements, add hero images, product images, or any image that needs responsive breakpoints. Trigger phrases include "render image", "add image to template", "responsive image", "picture element", "hero image", "responsive banner", "image for mobile and desktop", or "banner image".
329hyva-create-module
Create a new Magento 2 module in app/code/. This skill should be used when the user wants to create a module, scaffold a new module, generate module boilerplate, or set up a custom module. It handles registration.php, composer.json, module.xml generation with configurable dependencies. Trigger phrases include "create module", "new module", "scaffold module", "generate module".
327hyva-compile-tailwind-css
Compile Tailwind CSS for Hyvä themes in Magento 2. Use when the user wants to build styles, generate CSS, compile Tailwind, run Tailwind, or create production/development stylesheets for a Hyvä theme. Also use when Tailwind classes are not taking effect or some styles appear missing after template changes — this typically means CSS needs to be recompiled. Triggers include "compile tailwind", "build styles", "generate css", "styles not working", "styles are missing", "styles not applied".
326