@modyo/mcp 0.1.0

package/docs/channels/css-js/organization.md

@@ -0,0 +1,529 @@
+# CSS Organization Guide for Modyo
+
+> **Critical Guide**: Understanding when to use CSS templates vs snippets is essential for proper CSS organization in Modyo. This guide addresses the most common architecture mistake.
+
+---
+
+## Table of Contents
+
+1. [The Problem: CSS Templates vs Snippets](#the-problem-css-templates-vs-snippets)
+2. [When to Use CSS Templates](#when-to-use-css-templates)
+3. [When to Use CSS Snippets](#when-to-use-css-snippets)
+4. [Recommended Architecture](#recommended-architecture)
+5. [Component Naming Conventions](#component-naming-conventions)
+6. [Implementation Examples](#implementation-examples)
+7. [Common Mistakes](#common-mistakes)
+
+---
+
+## The Problem: CSS Templates vs Snippets
+
+### ⚠️ Critical Issue Discovered (Iteration 11)
+
+**CSS templates CANNOT include Liquid snippet references** because:
+- CSS/JS templates are served from CDN
+- Liquid preprocessing happens before CDN caching
+- `{% snippet 'name' %}` tags are **stripped out** during CDN processing
+- Result: Empty CSS file, no styles applied
+
+### ❌ WRONG Pattern
+
+```liquid
+<!-- globals.css (CSS template) -->
+{% snippet 'footer_css' %}  <!-- THIS GETS STRIPPED OUT -->
+{% snippet 'header_css' %}  <!-- THIS GETS STRIPPED OUT -->
+
+/* Actual CSS */
+body { margin: 0; }
+```
+
+**Result**: The snippet includes are removed, only `body { margin: 0; }` remains.
+
+### ✅ CORRECT Pattern
+
+```liquid
+<!-- In head snippet or layout -->
+{{ 'globals' | asset_url: 'css' | stylesheet_tag: media: 'screen', nonce: csp_nonce }}
+{% snippet 'footer_css' %}
+{% snippet 'header_css' %}
+{{ 'base' | asset_url: 'css' | stylesheet_tag: media: 'screen', nonce: csp_nonce }}
+```
+
+---
+
+## When to Use CSS Templates
+
+### Use CSS Templates For:
+
+✅ **Global stylesheets** that need CDN caching:
+- `root.css` - CSS variables and design tokens
+- `base.css` - Base styles (typography, resets, utilities)
+- `theme.css` - Theme-specific styles
+- `layout.css` - Grid systems and layout utilities
+
+✅ **Pure CSS without Liquid logic**:
+- No variables, no conditionals, no loops
+- Static styles that don't change per request
+
+✅ **Styles that benefit from CDN edge caching**:
+- Large CSS files (Bootstrap, vendor libraries)
+- Rarely-changing styles
+
+### How to Reference CSS Templates
+
+```liquid
+<!-- In head snippet -->
+{{ 'root' | asset_url: 'css' | stylesheet_tag: media: 'screen', nonce: csp_nonce }}
+{{ 'base' | asset_url: 'css' | stylesheet_tag: media: 'screen', nonce: csp_nonce }}
+```
+
+### Creating CSS Templates
+
+```typescript
+// Using MCP tools
+mcp__modyo-mcp__template-create({
+  platformSlug: "fed-team",
+  siteId: 4612,
+  name: "globals",
+  type: "css",
+  body: "/* Global styles */\nbody { margin: 0; }"
+})
+```
+
+---
+
+## When to Use CSS Snippets
+
+### Use CSS Snippets For:
+
+✅ **Component-specific styles**:
+- Footer styles (`footer_css`)
+- Header styles (`header_css`)
+- Navigation styles (`navigation_css`)
+- Widget-specific styles
+
+✅ **Styles that need CSP nonce**:
+- All inline `<style>` tags must include nonce
+- CSS snippets can use `{{csp_nonce}}` template variable
+- CSS templates cannot (CDN-served, no dynamic content)
+
+✅ **Styles with Liquid logic**:
+- Conditional styles based on site settings
+- Dynamic values from content
+- User-specific styling
+
+✅ **Server-rendered component styles**:
+- Styles for header, footer, widgets that render on server
+- Styles that need access to Liquid drops (user, session, content)
+
+### How to Create CSS Snippets
+
+```typescript
+// Using MCP tools
+mcp__modyo-mcp__template-create({
+  platformSlug: "fed-team",
+  siteId: 4612,
+  name: "footer_css",
+  type: "snippet",
+  body: `<style nonce="{{csp_nonce}}">
+/* Footer-specific styles */
+.footer-accordion .accordion-button {
+  background: linear-gradient(135deg, #002a8d 0%, #004bb5 100%);
+  color: white;
+}
+</style>`
+})
+```
+
+### How to Reference CSS Snippets
+
+```liquid
+<!-- In head snippet -->
+{% snippet 'footer_css' %}
+{% snippet 'header_css' %}
+{% snippet 'navigation_css' %}
+```
+
+---
+
+## Recommended Architecture
+
+### Complete CSS Loading Order
+
+```liquid
+<!-- In head snippet (_head.html.liquid) -->
+
+<!-- 1. Root CSS Variables (CSS template) -->
+{{ 'root' | asset_url: 'css' | stylesheet_tag: media: 'screen', nonce: csp_nonce }}
+
+<!-- 2. Global Utility CSS (CSS template, optional) -->
+{{ 'globals' | asset_url: 'css' | stylesheet_tag: media: 'screen', nonce: csp_nonce }}
+
+<!-- 3. Component-Specific CSS (Snippets) -->
+{% snippet 'header_css' %}
+{% snippet 'navigation_css' %}
+{% snippet 'footer_css' %}
+<!-- Add more component snippets as needed -->
+
+<!-- 4. Base Styles (CSS template) -->
+{{ 'base' | asset_url: 'css' | stylesheet_tag: media: 'screen', nonce: csp_nonce }}
+
+<!-- 5. Page-specific CSS (if needed) -->
+{% if template == 'home' %}
+  {% snippet 'home_css' %}
+{% endif %}
+```
+
+### Why This Order?
+
+1. **Root first**: CSS variables must be defined before use
+2. **Globals**: General utilities and resets
+3. **Components**: Specific component styles (can use root variables)
+4. **Base**: Core typography and element styles
+5. **Page-specific**: Override or extend for specific pages
+
+---
+
+## Component Naming Conventions
+
+### CSS Snippet Naming Pattern
+
+Use `{{component_name}}_css` format:
+
+```
+✅ footer_css
+✅ header_css
+✅ navigation_css
+✅ hero_banner_css
+✅ product_card_css
+✅ sidebar_css
+```
+
+### Why This Pattern?
+
+- **Consistent**: Easy to find and maintain
+- **Descriptive**: Name indicates purpose
+- **Organized**: Groups by component
+- **Searchable**: Quick to locate in template list
+
+### CSS Template Naming Pattern
+
+Use descriptive, generic names:
+
+```
+✅ root.css
+✅ base.css
+✅ theme.css
+✅ layout.css
+✅ utilities.css
+```
+
+---
+
+## Implementation Examples
+
+### Example 1: Footer Component CSS
+
+**Step 1: Check if snippet exists**
+```typescript
+// List snippets to avoid duplicates
+mcp__modyo-mcp__template-list({
+  platformSlug: "fed-team",
+  siteId: 4612,
+  type: "snippet"
+})
+```
+
+**Step 2: Create footer_css snippet**
+```typescript
+mcp__modyo-mcp__template-create({
+  platformSlug: "fed-team",
+  siteId: 4612,
+  name: "footer_css",
+  type: "snippet"
+})
+```
+
+**Step 3: Add CSS content**
+```typescript
+mcp__modyo-mcp__template-save({
+  platformSlug: "fed-team",
+  siteId: 4612,
+  templateId: 561234,  // From create response
+  body: `<style nonce="{{csp_nonce}}">
+/* Footer Styles */
+.site-footer {
+  background: var(--color-primary);
+  color: white;
+  padding: 3rem 0;
+}
+
+.footer-accordion .accordion-button {
+  background: linear-gradient(135deg, #002a8d 0%, #004bb5 100%);
+  color: white;
+  border: none;
+}
+
+.footer-accordion .accordion-button:not(.collapsed) {
+  background: linear-gradient(135deg, #001f6d 0%, #003a95 100%);
+}
+
+@media (max-width: 767px) {
+  .site-footer {
+    padding: 2rem 0;
+  }
+}
+</style>`
+})
+```
+
+**Step 4: Reference in head template**
+```liquid
+<!-- In _head.html.liquid snippet -->
+{% snippet 'footer_css' %}
+```
+
+**Step 5: Publish both snippets**
+```typescript
+mcp__modyo-mcp__release-create({
+  platformSlug: "fed-team",
+  siteId: 4612,
+  data: {
+    template: [
+      { id: 561234, selected: true },  // footer_css
+      { id: 560123, selected: true }   // _head
+    ]
+  }
+})
+```
+
+### Example 2: Global CSS Variables (CSS Template)
+
+**Step 1: Create root.css template**
+```typescript
+mcp__modyo-mcp__template-create({
+  platformSlug: "fed-team",
+  siteId: 4612,
+  name: "root",
+  type: "css"
+})
+```
+
+**Step 2: Add CSS variables**
+```css
+:root {
+  /* Colors - Mibanco Style */
+  --color-primary: #005596;
+  --color-secondary: #0066cc;
+  --color-accent: #00a8e8;
+
+  /* Typography */
+  --font-family-base: 'Montserrat', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  --font-size-base: 1rem;
+  --line-height-base: 1.7;
+
+  /* Spacing */
+  --spacing-unit: 0.5rem;
+  --spacing-xs: calc(var(--spacing-unit) * 1);
+  --spacing-sm: calc(var(--spacing-unit) * 2);
+  --spacing-md: calc(var(--spacing-unit) * 3);
+  --spacing-lg: calc(var(--spacing-unit) * 4);
+  --spacing-xl: calc(var(--spacing-unit) * 6);
+
+  /* Border Radius */
+  --radius-sm: 0.25rem;
+  --radius-md: 0.5rem;
+  --radius-lg: 1rem;
+  --radius-full: 9999px;
+
+  /* Shadows */
+  --shadow-sm: 0 2px 4px rgba(0, 0, 0, 0.1);
+  --shadow-md: 0 4px 8px rgba(0, 0, 0, 0.12);
+  --shadow-lg: 0 8px 16px rgba(0, 0, 0, 0.15);
+}
+```
+
+**Step 3: Reference in head**
+```liquid
+{{ 'root' | asset_url: 'css' | stylesheet_tag: media: 'screen', nonce: csp_nonce }}
+```
+
+### Example 3: Widget-Specific CSS
+
+For widgets, you have two options:
+
+**Option A: Include CSS in widget definition** (best for widget-specific styles)
+```typescript
+mcp__modyo-mcp__widget-definition-update({
+  platformSlug: "fed-team",
+  siteId: 4612,
+  widgetId: 86891,
+  html: "<!-- Widget HTML -->",
+  css: `
+/* Hero Banner Widget Styles */
+.hero-banner {
+  min-height: 500px;
+  position: relative;
+}
+`,
+  js: ""
+})
+```
+
+**Option B: Create snippet for shared widget styles**
+```liquid
+<!-- For styles shared across multiple widgets -->
+{% snippet 'widget_common_css' %}
+```
+
+---
+
+## Common Mistakes
+
+### ❌ Mistake 1: Trying to Include Snippets in CSS Templates
+
+```liquid
+<!-- globals.css (CSS template) -->
+{% snippet 'footer_css' %}  <!-- STRIPPED OUT, WON'T WORK -->
+```
+
+**Fix**: Reference snippets in HTML head, not in CSS templates.
+
+### ❌ Mistake 2: Missing CSP Nonce in Snippets
+
+```liquid
+<!-- footer_css snippet -->
+<style>  <!-- WRONG: No nonce, will be blocked by CSP -->
+.footer { background: blue; }
+</style>
+```
+
+**Fix**: Always include nonce:
+```liquid
+<style nonce="{{csp_nonce}}">
+.footer { background: blue; }
+</style>
+```
+
+### ❌ Mistake 3: Using Snippets for Large Static CSS
+
+```liquid
+<!-- base_css snippet with 5000 lines of CSS -->
+<style nonce="{{csp_nonce}}">
+/* 5000 lines of static CSS... */
+</style>
+```
+
+**Fix**: Use CSS template for large static files (better CDN caching):
+```typescript
+// Create as CSS template instead
+mcp__modyo-mcp__template-create({
+  name: "base",
+  type: "css",  // Not snippet
+  body: "/* 5000 lines of CSS */"
+})
+```
+
+### ❌ Mistake 4: Creating Duplicate Snippets
+
+```typescript
+// Creating footer_css twice
+mcp__modyo-mcp__template-create({ name: "footer_css", type: "snippet" })
+mcp__modyo-mcp__template-create({ name: "footer_css", type: "snippet" })  // ERROR or duplicate
+```
+
+**Fix**: Always check existence first:
+```typescript
+// 1. List to check if exists
+const templates = await mcp__modyo-mcp__template-list({
+  platformSlug: "fed-team",
+  siteId: 4612,
+  type: "snippet"
+})
+
+// 2. Check if footer_css already exists
+const exists = templates.some(t => t.name === "footer_css")
+
+// 3. Only create if doesn't exist
+if (!exists) {
+  await mcp__modyo-mcp__template-create({ name: "footer_css", type: "snippet" })
+}
+```
+
+### ❌ Mistake 5: Forgetting to Publish Snippets
+
+```typescript
+// Created/updated snippet but didn't publish
+mcp__modyo-mcp__template-save({ templateId: 123, body: "..." })
+// FORGOT TO PUBLISH - changes not visible on site
+```
+
+**Fix**: Always publish after changes:
+```typescript
+// Get publishable elements
+const elements = await mcp__modyo-mcp__release-get-elements-to-publish({
+  platformSlug: "fed-team",
+  siteId: 4612
+})
+
+// Publish template(s)
+await mcp__modyo-mcp__release-create({
+  platformSlug: "fed-team",
+  siteId: 4612,
+  data: {
+    template: elements.templates.filter(t => t.id === 123).map(t => ({ id: t.id, selected: true }))
+  }
+})
+```
+
+---
+
+## Workflow Checklist
+
+When organizing component CSS:
+
+- [ ] ✅ Determine if CSS is component-specific or global
+- [ ] ✅ Choose CSS template (global, static) or snippet (component, dynamic)
+- [ ] ✅ Check if snippet/template already exists (`template-list`)
+- [ ] ✅ Use correct naming convention (`footer_css`, `root.css`)
+- [ ] ✅ Include CSP nonce in snippets: `<style nonce="{{csp_nonce}}">`
+- [ ] ✅ Reference CSS templates via `asset_url | stylesheet_tag`
+- [ ] ✅ Reference snippets via `{% snippet 'name' %}`
+- [ ] ✅ Add to head in correct order (root → components → base)
+- [ ] ✅ Publish all related templates together
+- [ ] ✅ Test on live site to verify styles applied
+
+---
+
+## Quick Reference Table
+
+| Use Case | Solution | Example | CSP Nonce | CDN Cached |
+|----------|----------|---------|-----------|------------|
+| Global CSS variables | CSS Template | `root.css` | ❌ No | ✅ Yes |
+| Base typography | CSS Template | `base.css` | ❌ No | ✅ Yes |
+| Footer component | CSS Snippet | `footer_css` | ✅ Yes | ❌ No |
+| Header component | CSS Snippet | `header_css` | ✅ Yes | ❌ No |
+| Widget styles | Widget CSS Property | In widget definition | N/A | ✅ Yes |
+| Conditional styles | CSS Snippet | With Liquid logic | ✅ Yes | ❌ No |
+
+---
+
+## Related Documentation
+
+- [Liquid Best Practices](./LIQUID_BEST_PRACTICES.md) - Liquid syntax and patterns
+- [Template Workflows Guide](./TEMPLATE_WORKFLOWS.md) - Safe template editing
+- [Widget Workflows Guide](./WIDGET_WORKFLOWS.md) - Widget development patterns
+- [Modyo Snippets Architecture](./MODYO_SNIPPETS_ARCHITECTURE.md) - Deep dive into snippet system
+
+---
+
+## Further Reading
+
+- [Modyo Documentation: Templates](https://docs.modyo.com/en/platform/channels/templates.html)
+- [CSP Guide](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)
+- [CSS Architecture Patterns](https://web.dev/css-architecture/)
+
+---
+
+**Last Updated**: October 23, 2025
+**Source**: Iteration 11 findings from mcp-improvements.md