heraspec 0.1.12 → 0.1.14

package/dist/core/templates/skills/unit-test-skill.md

@@ -1,111 +1,111 @@
-# Skill: Unit Testing (Cross-Cutting)
-
-## Purpose
-
-This skill is used to create unit tests for code components. Unit tests verify that individual functions, methods, or classes work correctly in isolation.
-
-## When to Use
-
-- When testing individual functions or methods
-- When testing class methods in isolation
-- When testing utility functions
-- When testing business logic
-- When testing data transformations
-- When ensuring code correctness before integration
-
-## Step-by-Step Process
-
-### Step 1: Identify Test Targets
-- Analyze the code to identify testable units
-- List all public methods/functions
-- Identify edge cases and boundary conditions
-- Determine expected inputs and outputs
-
-### Step 2: Set Up Test Framework
-- Choose appropriate testing framework (Jest, PHPUnit, pytest, etc.)
-- Configure test environment
-- Set up test structure matching project conventions
-- Ensure test framework is installed and configured
-
-### Step 3: Write Test Cases
-- Create test file matching source file structure
-- Write tests for each function/method
-- Test normal cases (happy path)
-- Test edge cases (null, empty, boundary values)
-- Test error cases (invalid input, exceptions)
-- Use descriptive test names
-
-### Step 4: Run and Verify
-- Run tests to ensure they pass
-- Check test coverage if available
-- Refactor if needed
-- Ensure tests are fast and isolated
-
-### Step 5: Document Test Cases
-- Add comments for complex test scenarios
-- Document test data and expected outcomes
-- Update test documentation if needed
-
-## Required Input
-
-- **Source code**: Code to be tested (functions, methods, classes)
-- **Test framework**: Testing framework to use (Jest, PHPUnit, pytest, etc.)
-- **Project structure**: Understanding of where tests should be placed
-- **Dependencies**: List of dependencies that need to be mocked
-
-## Expected Output
-
-- Complete unit test files
-- Tests covering normal, edge, and error cases
-- Test assertions verifying expected behavior
-- Test data and fixtures if needed
-- Passing test suite
-
-## Tone & Rules
-
-### Test Naming
-- Use descriptive names: `test_user_registration_with_valid_email()`
-- Follow pattern: `test_<what>_<condition>_<expected_result>`
-- Use clear, readable test names
-
-### Test Structure
-- Arrange: Set up test data and dependencies
-- Act: Execute the code being tested
-- Assert: Verify the results
-- Clean up: Reset state if needed
-
-### Coverage Goals
-- Aim for high coverage of critical paths
-- Test all public methods
-- Test edge cases and error handling
-- Don't test implementation details
-
-### Limitations
-- ❌ DO NOT test private methods directly (test through public interface)
-- ❌ DO NOT write tests that depend on other tests
-- ❌ DO NOT test external dependencies (use mocks)
-- ❌ DO NOT write slow tests (use mocks for I/O)
-- ❌ DO NOT test framework code
-
-## Available Templates
-
-- `templates/unit-test-template.js` - JavaScript/Jest template
-- `templates/unit-test-template.php` - PHP/PHPUnit template
-- `templates/unit-test-template.py` - Python/pytest template
-
-## Available Scripts
-
-- `scripts/generate-test-stubs.sh` - Generate test file stubs from source code
-
-## Examples
-
-See `examples/` directory for reference:
-- `good-unit-test/` - Well-structured unit tests
-- `bad-unit-test/` - Examples to avoid
-
-## Links to Other Skills
-
-- **integration-test**: Use after unit tests for integration testing
-- **e2e-test**: Use for end-to-end testing
-- **documents**: Use to document test strategy
-
+# Skill: Unit Testing (Cross-Cutting)
+
+## Purpose
+
+This skill is used to create unit tests for code components. Unit tests verify that individual functions, methods, or classes work correctly in isolation.
+
+## When to Use
+
+- When testing individual functions or methods
+- When testing class methods in isolation
+- When testing utility functions
+- When testing business logic
+- When testing data transformations
+- When ensuring code correctness before integration
+
+## Step-by-Step Process
+
+### Step 1: Identify Test Targets
+- Analyze the code to identify testable units
+- List all public methods/functions
+- Identify edge cases and boundary conditions
+- Determine expected inputs and outputs
+
+### Step 2: Set Up Test Framework
+- Choose appropriate testing framework (Jest, PHPUnit, pytest, etc.)
+- Configure test environment
+- Set up test structure matching project conventions
+- Ensure test framework is installed and configured
+
+### Step 3: Write Test Cases
+- Create test file matching source file structure
+- Write tests for each function/method
+- Test normal cases (happy path)
+- Test edge cases (null, empty, boundary values)
+- Test error cases (invalid input, exceptions)
+- Use descriptive test names
+
+### Step 4: Run and Verify
+- Run tests to ensure they pass
+- Check test coverage if available
+- Refactor if needed
+- Ensure tests are fast and isolated
+
+### Step 5: Document Test Cases
+- Add comments for complex test scenarios
+- Document test data and expected outcomes
+- Update test documentation if needed
+
+## Required Input
+
+- **Source code**: Code to be tested (functions, methods, classes)
+- **Test framework**: Testing framework to use (Jest, PHPUnit, pytest, etc.)
+- **Project structure**: Understanding of where tests should be placed
+- **Dependencies**: List of dependencies that need to be mocked
+
+## Expected Output
+
+- Complete unit test files
+- Tests covering normal, edge, and error cases
+- Test assertions verifying expected behavior
+- Test data and fixtures if needed
+- Passing test suite
+
+## Tone & Rules
+
+### Test Naming
+- Use descriptive names: `test_user_registration_with_valid_email()`
+- Follow pattern: `test_<what>_<condition>_<expected_result>`
+- Use clear, readable test names
+
+### Test Structure
+- Arrange: Set up test data and dependencies
+- Act: Execute the code being tested
+- Assert: Verify the results
+- Clean up: Reset state if needed
+
+### Coverage Goals
+- Aim for high coverage of critical paths
+- Test all public methods
+- Test edge cases and error handling
+- Don't test implementation details
+
+### Limitations
+- ❌ DO NOT test private methods directly (test through public interface)
+- ❌ DO NOT write tests that depend on other tests
+- ❌ DO NOT test external dependencies (use mocks)
+- ❌ DO NOT write slow tests (use mocks for I/O)
+- ❌ DO NOT test framework code
+
+## Available Templates
+
+- `templates/unit-test-template.js` - JavaScript/Jest template
+- `templates/unit-test-template.php` - PHP/PHPUnit template
+- `templates/unit-test-template.py` - Python/pytest template
+
+## Available Scripts
+
+- `scripts/generate-test-stubs.sh` - Generate test file stubs from source code
+
+## Examples
+
+See `examples/` directory for reference:
+- `good-unit-test/` - Well-structured unit tests
+- `bad-unit-test/` - Examples to avoid
+
+## Links to Other Skills
+
+- **integration-test**: Use after unit tests for integration testing
+- **e2e-test**: Use for end-to-end testing
+- **documents**: Use to document test strategy
+

package/dist/core/templates/skills/ux-element/templates/Controller.php

@@ -1,50 +1,50 @@
-<?php
-
-namespace {{namespace_prefix}}\Controllers\Elements;
-
-use polyxgo\PolyUtilities\Core\Helper;
-
-class Element{{ElementName}}Controller
-{
-    public function register_hooks()
-    {
-        // 1. Frontend Shortcode
-        add_shortcode('{{shortcode_prefix}}{{element_slug}}', [$this, 'render_element']);
-
-        // 2. UX Builder Integration (Flatsome only)
-        if (Helper::is_flatsome_theme_activated()) {
-            add_action('ux_builder_setup', [$this, 'register_ux_builder_element']);
-        }
-    }
-
-    public function register_ux_builder_element()
-    {
-        if (function_exists('add_ux_builder_shortcode')) {
-            // Include the UI registration file
-            require_once Helper::get_poly_ux_builder_shortcode('{{element_slug}}');
-        }
-    }
-
-    public function render_element($atts, $content = null)
-    {
-        $atts = shortcode_atts([
-            '_id' => '{{element_slug}}-' . rand(),
-            'title' => '',
-            'class' => '',
-            'visibility' => '',
-            // Add more attributes here
-        ], $atts, '{{shortcode_prefix}}{{element_slug}}');
-
-        ob_start();
-        $view_path = plugin_dir_path({{plugin_dir_const}}) . '/inc/Views/elements/{{element_slug}}.php';
-        
-        if (file_exists($view_path)) {
-            include $view_path;
-        } else {
-            // Fallback inline rendering
-            echo '<div class="' . esc_attr($atts['class']) . '">' . esc_html($atts['title']) . '</div>';
-        }
-        
-        return ob_get_clean();
-    }
-}
+<?php
+
+namespace {{namespace_prefix}}\Controllers\Elements;
+
+use polyxgo\PolyUtilities\Core\Helper;
+
+class Element{{ElementName}}Controller
+{
+    public function register_hooks()
+    {
+        // 1. Frontend Shortcode
+        add_shortcode('{{shortcode_prefix}}{{element_slug}}', [$this, 'render_element']);
+
+        // 2. UX Builder Integration (Flatsome only)
+        if (Helper::is_flatsome_theme_activated()) {
+            add_action('ux_builder_setup', [$this, 'register_ux_builder_element']);
+        }
+    }
+
+    public function register_ux_builder_element()
+    {
+        if (function_exists('add_ux_builder_shortcode')) {
+            // Include the UI registration file
+            require_once Helper::get_poly_ux_builder_shortcode('{{element_slug}}');
+        }
+    }
+
+    public function render_element($atts, $content = null)
+    {
+        $atts = shortcode_atts([
+            '_id' => '{{element_slug}}-' . rand(),
+            'title' => '',
+            'class' => '',
+            'visibility' => '',
+            // Add more attributes here
+        ], $atts, '{{shortcode_prefix}}{{element_slug}}');
+
+        ob_start();
+        $view_path = plugin_dir_path({{plugin_dir_const}}) . '/inc/Views/elements/{{element_slug}}.php';
+        
+        if (file_exists($view_path)) {
+            include $view_path;
+        } else {
+            // Fallback inline rendering
+            echo '<div class="' . esc_attr($atts['class']) . '">' . esc_html($atts['title']) . '</div>';
+        }
+        
+        return ob_get_clean();
+    }
+}

package/dist/core/templates/skills/ux-element/templates/Shortcode.php

@@ -1,23 +1,23 @@
-<?php
-
-use polyxgo\PolyUtilities\Core\Helper;
-use polyxgo\PolyUtilities\Core\Options;
-
-add_ux_builder_shortcode('{{shortcode_prefix}}{{element_slug}}', array(
-    'name'      => __('{{ElementName}}', 'polyutilities'),
-    'category'  => __('PolyUtilities', 'polyutilities'),
-    'template'  => Helper::get_poly_ux_builder_template('{{element_slug}}'),
-    'thumbnail' => Helper::get_poly_ux_builder_thumbnail('{{element_slug}}'),
-    'info'      => '{{ title }}',
-    'priority'  => 10,
-    'options'   => array(
-        'title' => array(
-            'type'        => 'textfield',
-            'heading'     => __('Title', 'polyutilities'),
-            'default'     => 'Element Title',
-            'auto_focus'  => true,
-        ),
-        // Add more options here (colorpicker, slider, select, etc.)
-        'advanced_options' => require Helper::get_poly_ux_builder_element('commons', 'advanced'),
-    ),
-));
+<?php
+
+use polyxgo\PolyUtilities\Core\Helper;
+use polyxgo\PolyUtilities\Core\Options;
+
+add_ux_builder_shortcode('{{shortcode_prefix}}{{element_slug}}', array(
+    'name'      => __('{{ElementName}}', 'polyutilities'),
+    'category'  => __('PolyUtilities', 'polyutilities'),
+    'template'  => Helper::get_poly_ux_builder_template('{{element_slug}}'),
+    'thumbnail' => Helper::get_poly_ux_builder_thumbnail('{{element_slug}}'),
+    'info'      => '{{ title }}',
+    'priority'  => 10,
+    'options'   => array(
+        'title' => array(
+            'type'        => 'textfield',
+            'heading'     => __('Title', 'polyutilities'),
+            'default'     => 'Element Title',
+            'auto_focus'  => true,
+        ),
+        // Add more options here (colorpicker, slider, select, etc.)
+        'advanced_options' => require Helper::get_poly_ux_builder_element('commons', 'advanced'),
+    ),
+));

package/dist/core/templates/skills/ux-element/templates/Template.html

@@ -1,20 +1,20 @@
-<span id="{{:: shortcode.$id }}">
-    <div class="{{class_prefix}}{{element_slug}} {{ shortcode.options.class }} {{ shortcode.options.visibility }}"
-         ng-style="{
-             'color': shortcode.options.textColor,
-             'background-color': shortcode.options.bgColor,
-             'font-family': shortcode.options.pxgClockFont
-         }">
-        <span ng-bind="shortcode.options.title"></span>
-    </div>
-
-    <style scope="scope">
-        #{{::shortcode.$id }} .{{class_prefix}}{{element_slug}} {
-            /* Add scoped styles here */
-        }
-        
-        #{{::shortcode.$id }} .{{class_prefix}}{{element_slug}}:hover {
-            /* Hover effects */
-        }
-    </style>
-</span>
+<span id="{{:: shortcode.$id }}">
+    <div class="{{class_prefix}}{{element_slug}} {{ shortcode.options.class }} {{ shortcode.options.visibility }}"
+         ng-style="{
+             'color': shortcode.options.textColor,
+             'background-color': shortcode.options.bgColor,
+             'font-family': shortcode.options.pxgClockFont
+         }">
+        <span ng-bind="shortcode.options.title"></span>
+    </div>
+
+    <style scope="scope">
+        #{{::shortcode.$id }} .{{class_prefix}}{{element_slug}} {
+            /* Add scoped styles here */
+        }
+        
+        #{{::shortcode.$id }} .{{class_prefix}}{{element_slug}}:hover {
+            /* Hover effects */
+        }
+    </style>
+</span>

package/dist/core/templates/skills/ux-element/templates/Thumbnail.svg

@@ -1,8 +1,8 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<svg width="100px" height="68px" viewBox="0 0 100 68" version="1.1" xmlns="http://www.w3.org/2000/svg">
-    <rect x="0" y="0" width="100" height="68" fill="#FFFFFF"></rect>
-    <!-- Placeholder: Replace with actual icon geometry -->
-    <rect x="25" y="20" width="50" height="28" rx="2" fill="#FCA5A5" stroke="#F87171" stroke-width="2"></rect>
-    <rect x="30" y="28" width="40" height="4" rx="1" fill="#FFFFFF"></rect>
-    <rect x="30" y="36" width="25" height="4" rx="1" fill="#FFFFFF"></rect>
-</svg>
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="100px" height="68px" viewBox="0 0 100 68" version="1.1" xmlns="http://www.w3.org/2000/svg">
+    <rect x="0" y="0" width="100" height="68" fill="#FFFFFF"></rect>
+    <!-- Placeholder: Replace with actual icon geometry -->
+    <rect x="25" y="20" width="50" height="28" rx="2" fill="#FCA5A5" stroke="#F87171" stroke-width="2"></rect>
+    <rect x="30" y="28" width="40" height="4" rx="1" fill="#FFFFFF"></rect>
+    <rect x="30" y="36" width="25" height="4" rx="1" fill="#FFFFFF"></rect>
+</svg>

package/dist/core/templates/skills/ux-element/templates/View.php

@@ -1,21 +1,21 @@
-<?php
-/**
- * Frontend view for {{ElementName}}
- * 
- * @var array $atts
- */
-
-$classes = array('{{class_prefix}}{{element_slug}}');
-if (!empty($atts['class'])) $classes[] = $atts['class'];
-if (!empty($atts['visibility'])) $classes[] = $atts['visibility'];
-
-$inline_style = '';
-if (!empty($atts['textColor'])) $inline_style .= 'color: ' . esc_attr($atts['textColor']) . ';';
-if (!empty($atts['bgColor'])) $inline_style .= 'background-color: ' . esc_attr($atts['bgColor']) . ';';
-
-?>
-<div id="<?php echo esc_attr($atts['_id']); ?>" 
-     class="<?php echo esc_attr(implode(' ', $classes)); ?>"
-     style="<?php echo esc_attr($inline_style); ?>">
-    <?php echo esc_html($atts['title']); ?>
-</div>
+<?php
+/**
+ * Frontend view for {{ElementName}}
+ * 
+ * @var array $atts
+ */
+
+$classes = array('{{class_prefix}}{{element_slug}}');
+if (!empty($atts['class'])) $classes[] = $atts['class'];
+if (!empty($atts['visibility'])) $classes[] = $atts['visibility'];
+
+$inline_style = '';
+if (!empty($atts['textColor'])) $inline_style .= 'color: ' . esc_attr($atts['textColor']) . ';';
+if (!empty($atts['bgColor'])) $inline_style .= 'background-color: ' . esc_attr($atts['bgColor']) . ';';
+
+?>
+<div id="<?php echo esc_attr($atts['_id']); ?>" 
+     class="<?php echo esc_attr(implode(' ', $classes)); ?>"
+     style="<?php echo esc_attr($inline_style); ?>">
+    <?php echo esc_html($atts['title']); ?>
+</div>

package/dist/core/templates/skills/ux-element-skill.md

@@ -1,83 +1,83 @@
-# Skill: Flatsome UX Element
-
-This skill guides the creation of custom UX Builder elements for the Flatsome theme within the PolyUtilities plugin.
-
-## Purpose
-Standardize the development of UX elements to ensure consistency across controllers, shortcodes, and templates, with special focus on real-time preview functionality. This skill is portable and uses dynamic prefixes for identity (Shortcode, Namespace, CSS Classes).
-
-## Required Variables
-When calling this skill, define the following identity prefixes:
-- `{{namespace_prefix}}`: The root namespace (e.g., `polyxgo\PolyUtilities`).
-- `{{shortcode_prefix}}`: Prefix for shortcode names (e.g., `poly_ux_`).
-- `{{class_prefix}}`: Prefix for CSS classes (e.g., `poly-`).
-- `{{plugin_dir_const}}`: The plugin directory constant (e.g., `__POLYUTILITIES_PLUGIN_DIR__`).
-
-## Prerequisites
-- Knowledge of PHP, WordPress Shortcodes, and AngularJS (for UX Builder templates).
-- Access to `inc/Core/Helper.php` for utility functions.
-
-## Implementation Steps
-
-### 1. Register Shortcode Logic (The Controller)
-Create a new controller class in `inc/Controllers/Elements/`.
-- **Namespace**: `{{namespace_prefix}}\Controllers\Elements`
-- **Method `register_hooks()`**: Add the shortcode `{{shortcode_prefix}}{{element_slug}}` and `ux_builder_setup` action.
-- **Method `render_element($atts, $content)`**: Handle the frontend output.
-
-### 2. Register UX Builder UI (The Shortcode)
-Create a registration file in `inc/builder/shortcodes/`.
-- Use `add_ux_builder_shortcode('{{shortcode_prefix}}{{element_slug}}', ...)`.
-- Define options (textfield, select, colorpicker, slider, etc.).
-- Link to the AngularJS template using `Helper::get_poly_ux_builder_template()`.
-
-### 3. Build the Preview Template (AngularJS)
-Create an HTML file in `inc/builder/shortcodes/templates/`.
-- **CRITICAL**: Wrap the entire content in a `<span>` with `id="{{:: shortcode.$id }}"`.
-- This ensures that clicking the element in the builder correctly selects it and shows options.
-- Use `ng-style` and `style scope="scope"` for real-time CSS updates.
-
-### 4. Create SVG Thumbnail
-Create an SVG file in `inc/builder/shortcodes/thumbnails/`.
-- **Naming**: Use `{{element_slug}}.svg`.
-- **Dimensions**: Use `100x68px`.
-- **Theme**: Use the "Pastel Red" theme (`#F87171` for accents, `#FCA5A5` for fills).
-
-### 5. Create the Frontend View
-(Optional) Extract the HTML into `inc/Views/elements/` for cleaner controllers.
-
-## Standards and Rules
-
-### The Wrapping Rule
-Every UX Builder template MUST follow this structure:
-```html
-<span id="{{:: shortcode.$id }}">
-    <!-- Main element (e.g., <a>, <div>, <section>) -->
-    <div class="{{class_prefix}}{{element_slug}}" ng-style="{ 'color': shortcode.options.color }">
-        {{ shortcode.options.text }}
-    </div>
-    
-    <!-- Scoped styles for hover effects or complex rules -->
-    <style scope="scope">
-        #{{::shortcode.$id }} .{{class_prefix}}{{element_slug}}:hover {
-            opacity: 0.8;
-        }
-    </style>
-</span>
-```
-
-### Variable Naming (PHP vs AngularJS)
-**CRITICAL**: When accessing shortcode options in the AngularJS template (`.html`), variables declared with underscores (`_`) in PHP MUST be accessed via **camelCase**.
-- **PHP**: `bg_color` → **AngularJS**: `shortcode.options.bgColor`
-- **PHP**: `pxg_clock_font` → **AngularJS**: `shortcode.options.pxgClockFont`
-- **PHP**: `text_align` → **AngularJS**: `shortcode.options.textAlign`
-
-### Color Handling
-- Use HEX or RGBA strings consistently.
-- Always provide default values in the shortcode registration or handle them in the template/controller.
-
-## Templates
-- [Controller.php](templates/Controller.php)
-- [Shortcode.php](templates/Shortcode.php)
-- [Template.html](templates/Template.html)
-- [View.php](templates/View.php)
-- [Thumbnail.svg](templates/Thumbnail.svg)
+# Skill: Flatsome UX Element
+
+This skill guides the creation of custom UX Builder elements for the Flatsome theme within the PolyUtilities plugin.
+
+## Purpose
+Standardize the development of UX elements to ensure consistency across controllers, shortcodes, and templates, with special focus on real-time preview functionality. This skill is portable and uses dynamic prefixes for identity (Shortcode, Namespace, CSS Classes).
+
+## Required Variables
+When calling this skill, define the following identity prefixes:
+- `{{namespace_prefix}}`: The root namespace (e.g., `polyxgo\PolyUtilities`).
+- `{{shortcode_prefix}}`: Prefix for shortcode names (e.g., `poly_ux_`).
+- `{{class_prefix}}`: Prefix for CSS classes (e.g., `poly-`).
+- `{{plugin_dir_const}}`: The plugin directory constant (e.g., `__POLYUTILITIES_PLUGIN_DIR__`).
+
+## Prerequisites
+- Knowledge of PHP, WordPress Shortcodes, and AngularJS (for UX Builder templates).
+- Access to `inc/Core/Helper.php` for utility functions.
+
+## Implementation Steps
+
+### 1. Register Shortcode Logic (The Controller)
+Create a new controller class in `inc/Controllers/Elements/`.
+- **Namespace**: `{{namespace_prefix}}\Controllers\Elements`
+- **Method `register_hooks()`**: Add the shortcode `{{shortcode_prefix}}{{element_slug}}` and `ux_builder_setup` action.
+- **Method `render_element($atts, $content)`**: Handle the frontend output.
+
+### 2. Register UX Builder UI (The Shortcode)
+Create a registration file in `inc/builder/shortcodes/`.
+- Use `add_ux_builder_shortcode('{{shortcode_prefix}}{{element_slug}}', ...)`.
+- Define options (textfield, select, colorpicker, slider, etc.).
+- Link to the AngularJS template using `Helper::get_poly_ux_builder_template()`.
+
+### 3. Build the Preview Template (AngularJS)
+Create an HTML file in `inc/builder/shortcodes/templates/`.
+- **CRITICAL**: Wrap the entire content in a `<span>` with `id="{{:: shortcode.$id }}"`.
+- This ensures that clicking the element in the builder correctly selects it and shows options.
+- Use `ng-style` and `style scope="scope"` for real-time CSS updates.
+
+### 4. Create SVG Thumbnail
+Create an SVG file in `inc/builder/shortcodes/thumbnails/`.
+- **Naming**: Use `{{element_slug}}.svg`.
+- **Dimensions**: Use `100x68px`.
+- **Theme**: Use the "Pastel Red" theme (`#F87171` for accents, `#FCA5A5` for fills).
+
+### 5. Create the Frontend View
+(Optional) Extract the HTML into `inc/Views/elements/` for cleaner controllers.
+
+## Standards and Rules
+
+### The Wrapping Rule
+Every UX Builder template MUST follow this structure:
+```html
+<span id="{{:: shortcode.$id }}">
+    <!-- Main element (e.g., <a>, <div>, <section>) -->
+    <div class="{{class_prefix}}{{element_slug}}" ng-style="{ 'color': shortcode.options.color }">
+        {{ shortcode.options.text }}
+    </div>
+    
+    <!-- Scoped styles for hover effects or complex rules -->
+    <style scope="scope">
+        #{{::shortcode.$id }} .{{class_prefix}}{{element_slug}}:hover {
+            opacity: 0.8;
+        }
+    </style>
+</span>
+```
+
+### Variable Naming (PHP vs AngularJS)
+**CRITICAL**: When accessing shortcode options in the AngularJS template (`.html`), variables declared with underscores (`_`) in PHP MUST be accessed via **camelCase**.
+- **PHP**: `bg_color` → **AngularJS**: `shortcode.options.bgColor`
+- **PHP**: `pxg_clock_font` → **AngularJS**: `shortcode.options.pxgClockFont`
+- **PHP**: `text_align` → **AngularJS**: `shortcode.options.textAlign`
+
+### Color Handling
+- Use HEX or RGBA strings consistently.
+- Always provide default values in the shortcode registration or handle them in the template/controller.
+
+## Templates
+- [Controller.php](templates/Controller.php)
+- [Shortcode.php](templates/Shortcode.php)
+- [Template.html](templates/Template.html)
+- [View.php](templates/View.php)
+- [Thumbnail.svg](templates/Thumbnail.svg)