Create custom Hyvä CMS component. This skill should be used when the user wants to create a new Hyvä CMS component, build a Hyvä component, or needs help with components.json and PHTML templates for Hyvä CMS. Trigger phrases include "create hyva cms component", "add cms component", "new hyva compone

Hyvä CMS Component Creator Overview This skill guides the interactive creation of custom Hyvä CMS components for Magento 2. It supports creating components in new or existing modules, with field presets for common patterns and automatic setup:upgrade execution. Command execution: For commands that need to run inside the development environment (e.g., bin/magento ), use the hyva exec shell cmd skill to detect the environment and determine the appropriate command wrapper. Workflow Step 1: Module Selection If not already specified in the prompt, ask the user where to create the component: Option A: New Module Ask for both values (do not assume defaults without asking): 1. Vendor name (e.g., Acme ) Required, no default. Do not suggest a Vendor name, prompt for user input. 2. Module name Suggest CmsComponents as default so user can press Enter to accept Then use the hyva create module skill with: dependencies : ["Hyva CmsBase"] composer require : {"hyva themes/commerce module cms": "^1.0"} Option B: Existing Module Request the module path (can be in app/code/ , vendor/ , or custom location) Verify the module has Hyva CmsBase as a dependency in etc/module.xml . If not present, add it. Verify the module has hyva themes/commerce module cms as a dependency in composer.json . If not present, add it. Step 2: Component Details Gather component information: 1. Component name (snake case, e.g., feature card ) 2. Label (display name in editor, e.g., "Feature Card") 3. Category (Layout, Elements, Media, Content, or Other) 4. Icon Automatically select an appropriate icon: Step 4a: Identify icons already in use Use the hyva cms components dump skill to dump all current CMS components. Extract all icon values from the output to build a list of icons already in use by existing components. Step 4b: Find available lucide icons List the SVG files in vendor/hyva themes/magento2 theme module/src/view/base/web/svg/lucide/ to get the full set of available icons. Step 4c: Select the best fitting icon From the available lucide icons that are NOT already in use by another component: Choose the icon whose name best matches the purpose/meaning of the new component Consider semantic meaning (e.g., shopping cart.svg for cart related, image.svg for image related, layout grid.svg for grid layouts) Format the selected icon as Hyva Theme::svg/lucide/[icon name].svg If no suitable unused icon can be found, or if the lucide directory doesn't exist, leave the icon property unset. Step 3: Field Selection Offer field presets or custom field creation. See references/field types.md "Field Presets" section for available presets (Basic Card, Image Card, CTA Block, Text Block, Feature Item, Testimonial, Accordion Item) or allow custom field definition. Authoritative field types: prefer the project's live list when available — run bin/magento hyva:cms:list fields (core + custom field types) via the hyva exec shell cmd wrapper. Fall back to references/field types.md only when the command is unavailable. For custom fields, iterate through each field asking: 1. Field name (snake case) 2. Field type (see references/field types.md ) 3. Label 4. Default value (optional) 5. Required? (yes/no) Note: This will be added as attributes.required , NOT as a direct field property 6. Any additional attributes (these go in the attributes object) Step 4: Variant Support Ask if the component needs template variants: If yes : Gather variant names and labels (e.g., default, compact, wide). See references/variant support.md for configuration details. If no : Use single template Step 5: Generate Files Create the required files: For New Modules The hyva create module skill creates the base module structure. Then add the CMS specific directories: For Existing Modules Create or update: etc/hyva cms/components.json (merge with existing if present) view/frontend/templates/elements/[component name].phtml Step 6: Run Setup After creating files, run bin/magento setup:upgrade using the appropriate command wrapper detected by the hyva exec shell cmd skill. File Generation Details components.json Structure Valid Component Properties IMPORTANT: Only specific properties are allowed at the component level. See references/component schema.md for the complete schema reference. Key properties: label (required), category , template , icon , children , require parent , content , design , advanced , disabled , custom properties . Invalid properties that will cause schema errors: hidden Does not exist. Use require parent: true for child only components, or disabled: true Any property not listed in the schema reference Children Configuration (CRITICAL) IMPORTANT: children is a ROOT LEVEL component property, NOT a field type within content , design , or advanced . INCORRECT ❌: CORRECT ✅: In templates, access children via $block getData('children') , NOT via a custom field name. Field Validation (CRITICAL) IMPORTANT: Field validation attributes like required must be placed in the attributes object, NOT as direct field properties. INCORRECT ❌: CORRECT ✅: Other validation attributes that go in attributes : required (boolean) minlength / maxlength (string) min / max (for numbers) pattern (regex string) placeholder (string) comment (help text) Custom data attributes for validation messages Child Only Components For components that should only be used as children of other components (like list items), use require parent: true : When template: false , the parent component renders the child data directly (NOT using $block createChildHtml() ). See "Rendering Children with template: false" below. PHTML Template Structure Every template must start with this header: Additional requirements: 1. $block getEditorAttrs() on root element 2. $block getEditorAttrs('field name') on editable elements 3. Proper escaping with $escaper escapeHtml() and $escaper escapeHtmlAttr() Template Patterns by Field Type Text fields: Richtext/HTML fields: Image fields: Use the hyva render media image skill for rendering images. It provides the complete API reference and code patterns for the \Hyva\Theme\ViewModel\Media view model. Add these imports when rendering images: The data from $block getData('image') can be passed directly to getResponsivePictureHtml() : For responsive images with separate desktop and mobile sources, see the hyva render media image skill. Link fields: Boolean fields: Select fields: Children fields (with their own templates): When child components have their own templates (default behavior), use $block createChildHtml() : Rendering Children with template: false : When child components have "template": false , the parent component renders them directly. Child data is flat field values are directly on the child array, NOT nested under a content key. Key points for template: false children: Child field data is flat: use $elementData['field name'] , NOT $elementData['content']['field name'] Each child has a uid property for editor attributes Use $block getEditorAttrs('field name', $childUid) to enable live editing of child fields Use $block getEditorAttrs('', $childUid) on the child's root element For images, check !empty($image['src']) and use $block getResponsiveImageData($image) to process the image data For advanced image rendering patterns (responsive breakpoints, etc.), see the hyva render media image skill Resources references/critical patterns.md READ THIS FIRST Essential patterns and common mistakes including: Correct children configuration (root level vs field type) Proper field validation with attributes Default value syntax Quick checklist before generating components Read this file before generating any component to avoid common errors. references/example component.md Complete end to end example showing a Feature Card component with: Full components.json definition Matching PHTML template with all field types Supporting module files (registration.php, module.xml, composer.json) Directory structure overview Read this file when you need a reference for how all the pieces fit together. Component/field schema (read from the project, with a bundled fallback) The Hyvä CMS schema is project version dependent. Prefer the live schema from the installed Hyvä Commerce package: if vendor/hyva themes/commerce module cms/src/liveview editor/etc/hyva cms/jsonschema/ exists, read its JSON files directly (no interpreter needed) for this project's authoritative component and field declarations: component declaration.json — valid component level properties component field declaration.json — field declaration properties, field types, validation attributes Only when Hyvä Commerce is not installed, fall back to the bundled references/component schema.md . Read either source when validating component structure or when encountering schema validation errors. The bundled references/component schema.md is a fallback snapshot. To refresh it after a Hyvä CMS update, regenerate it by reading the jsonschema/ .json files above — no helper script is required. references/field types.md Complete reference for all supported field types including: Field configuration syntax All available field types with examples Validation attributes Conditional visibility (show if/hide if) Field presets for common patterns Read this file when generating field configurations. references/variant support.md Guide for implementing template variants including: Directory structure for variant templates Variant field configuration in components.json Template implementation patterns Common variant patterns and best practices Read this file when the user wants multiple layout options for a component. references/troubleshooting.md Solutions for common issues including: Schema validation errors Component not visible in editor Template not rendering Live editor not working Image display issues Fallbacks when dependent skills are unavailable Read this file when encountering errors during component creation or testing. assets/templates/component/template.phtml.tpl Base PHTML structure for CMS components. Placeholders: {{CONTENT FIELDS}} PHP variable declarations {{TEMPLATE BODY}} HTML template content Important Guidelines 1. Always use getEditorAttrs() on the root element and on each editable field element 2. Never use <script tags in templates use Alpine.js via alpine:init event 3. Escape all user content with appropriate escaper methods 4. Use meaningful default values for better merchant experience 5. Include design/advanced sections via includes for consistency 6. Validate component names are snake case with only lowercase letters, numbers, and underscores 7. CRITICAL: Use default value key, NOT default The correct JSON key for default values is default value (with underscore), not default . Example: "default value": "My Title" ✅, NOT "default": "My Title" ❌ 8. CRITICAL: children is a root level property, NOT a field type Never use "type": "children" in content/design/advanced. Declare children at component root level. Access via $block getData('children') in templates. 9. CRITICAL: Validation goes in attributes , NOT as direct properties Use "attributes": {"required": true} ✅, NOT "required": true ❌. All HTML5 validation attributes (required, minlength, maxlength, pattern, min, max) must be inside the attributes object. <! Copyright © Hyvä Themes https://hyva.io. All rights res

hyva-cms-component