hyva-themes/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":

1. Use the hyva-child-theme skill to create the new theme first
2. 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:

1. Extract the first XML block containing <var name= elements with default values
2. Identify the module attribute (e.g., module="Magento_Catalog")
3. 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>
4. Notify: "Added configuration options to {theme_path}/etc/view.xml with 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-css skill 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

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

<!-- Copyright © Hyvä Themes https://hyva.io. All rights reserved. Licensed under OSL 3.0 -->