docs(SimpleCard): add comprehensive native rendering guide

[Copilot]

Context

Added exhaustive documentation for configuring SimpleCard to match native Shopify product card behavior. Covers variant selection, swatch rendering across 6 persistence models (native, image-based, metafield, JSON config, metaobject library, metaobject references), SKU alternatives from multiple data sources, and production patterns. Includes a visual UI configuration form illustration.

Related Jira ticket

N/A

Screenshots

UI Configuration Form Illustration

Comprehensive configuration editor showing all SimpleCard options in an interactive form layout:

---

Contents

Configuration & Integration (Core attributes, global defaults, variant selection patterns, event-based communication)

Swatch Rendering Models

• Shopify native swatches (hex in swatch field)
• Image-based swatches (patterns/textures)
• Metafield-based colors (legacy migrations)
• File-based JSON mapping (static config)
• Metaobject library (centralized definitions)
• Metaobject references (direct references from product option values)

Data Sources (Shopify API, metafields, collections, Nosto recommendations, bundles)

Styling (CSS Parts reference, theming, dark mode)

Production Examples (4 complete implementations: native clone, advanced swatches, collection alternatives, dynamic bundles)

Performance (Lazy loading, caching, batch queries, preloading, debouncing)

File: /src/components/SimpleCard/native-rendering-guide.md (1,795 lines)

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[timowestnosto]

@copilot describe also an alternative path where the swatch value metadata is pulled from metaobject references

[Copilot]

Added an alternative approach under Model 5 that shows how to pull swatch values from metaobject references directly attached to product option values. This includes:

• GraphQL query with metaobject references in the swatch field
• Implementation to extract and apply swatch data from metaobject fields
• Support for both hex colors and image-based swatches in metaobjects
• Benefits of product-specific swatch configurations vs centralized library

Commit: 1edc4fe

[timowestnosto]

@copilot create an illustration of a UI form that makes all of the extended SimpleCard configuration editable
attach as screenshot

[Copilot]

@copilot create an illustration of a UI form that makes all of the extended SimpleCard configuration editable
attach as screenshot

Created a comprehensive UI configuration form that makes all extended SimpleCard configuration options editable:

Sections included:

• Core Attributes (handle, variant-id, image-mode, rating)
• Display Options (brand, discount, mock, image-sizes)
• Swatch Rendering Models (all 6 models with selection UI)
• SKU Alternatives & Data Sources (Shopify API, metafields, collections, Nosto)
• Styling Configuration (theme presets, CSS parts override)
• Performance Optimization (lazy loading, caching, debouncing)
• Generated Configuration Code (live preview)

The form features a modern gradient design with organized sections, badges for required/optional fields, interactive controls for all configuration options, and a code preview panel showing the generated SimpleCard setup.