@zohofinance/commerce 1.0.0 → 1.1.0

package/ts-dist/mocks/init-theme/.cursor/rules/design-spec-extraction.mdc

@@ -0,0 +1,255 @@
+---
+description: Reusable design spec extraction protocol — extracts exact values from Figma MCP for any command
+globs: ["sections/*.liquid", "snippets/*.liquid"]
+---
+
+# Design Spec Extraction Protocol
+
+This rule defines a **reusable, rigorous extraction process** for reading Figma MCP data.
+It is used by `/build-section`, `/compare-section`, `/redesign-section`, and `/build-theme`.
+
+The goal: extract EVERY visual property as an exact, resolved value — never vague descriptions.
+Additionally, extract the COMPLETE element hierarchy so the agent knows exactly what elements exist, how they're nested, and what children each container has.
+
+---
+
+## Step 0 — Extract Element Hierarchy (Structure Tree)
+
+Before extracting visual properties, first map out the COMPLETE structure of the Figma frame as a tree.
+This is critical — without it, the agent will invent its own structure.
+
+### Read the Figma MCP response top-to-bottom. Produce a tree like this:
+
+```
+ELEMENT HIERARCHY — <section_name>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Section wrapper (column)
+├── Header row (row, justify-between)
+│   ├── Title block (column)
+│   │   ├── Heading H2 "Action Toys"
+│   │   └── Description paragraph
+│   └── Sort block (row)
+│       ├── "Sort By:" label
+│       └── Dropdown (row, border, bg)
+│           ├── Selected text "New Arrivals"
+│           └── Chevron icon
+├── Divider (border-top)
+└── Content area (row)
+    ├── Filter sidebar (column, w-300px)
+    │   ├── "Filter By" heading
+    │   ├── Filter group: Categories (column, border-bottom)
+    │   │   ├── Group header (row: search icon + title + chevron)
+    │   │   ├── Checkbox item: "Anime toys" (pl-36px)
+    │   │   ├── Checkbox item: "Soft toys"
+    │   │   ├── Checkbox item: "Wooden toys"
+    │   │   ├── Checkbox item: "Outdoor toys"
+    │   │   └── "42+ More" link (purple)
+    │   ├── Filter group: Age group (same structure)
+    │   ├── Filter group: Price (radio buttons instead of checkboxes)
+    │   └── Filter group: Brand (radio buttons)
+    └── Product grid area (column, flex-1)
+        ├── Product grid (grid, 3 cols, gap-x-12 gap-y-28)
+        │   ├── Product card (column)
+        │   │   ├── Image container (h-408px, bg-neutral)
+        │   │   │   └── Product image
+        │   │   └── Card info (column, pt-20px)
+        │   │       ├── Product name (Lato Bold 24px)
+        │   │       ├── Category tags row (Lato Medium 16px, gap-8px)
+        │   │       └── Price + rating row (justify-between)
+        │   │           ├── Price block (column)
+        │   │           │   ├── Current price (₹ symbol 28px + amount 36px Oswald Bold)
+        │   │           │   └── Original price (16px, line-through, purple)
+        │   │           └── Rating block (row: "4/5" text + star icon)
+        │   ├── Product card (same) — with "Add to Bag" button
+        │   ├── Product card (same) × 7 more
+        │   └── ...
+        └── Pagination (row, justify-center, pt-60px, gap-24px)
+            ├── Prev arrow (48px)
+            ├── Page numbers (40px each, active=purple bg)
+            └── Next arrow (48px)
+```
+
+### Rules for hierarchy extraction:
+- List EVERY element, not just major sections
+- Note the layout type of each container (row/column/grid)
+- Note the number of children (especially for grids and repeating patterns)
+- Note key structural properties: width constraints, alignment, justify
+- For repeating elements (cards, filter items), describe one fully and note "× N more"
+- If an element has a special variant (e.g. one card has an "Add to Bag" button), note it
+
+This tree is the STRUCTURAL CONTRACT. The generated HTML must reproduce this exact nesting.
+Cross-reference it with the reference section — if the reference has a different structure, the Figma tree wins for HTML, but preserve the reference's Liquid logic.
+
+---
+
+## Step 1 — Resolve ALL var() Values First
+
+Figma MCP returns values like `var(--font/size/9xl, 56px)` or `var(--radius/xl, 25px)`.
+
+For EVERY `var()` in the MCP response:
+1. Strip `--` prefix, normalize slashes: `--radius\/xl` → `radius/xl`
+2. Look up in `figma-variables.json` by traversing the path
+3. If node has `$value` → use that (theme-mode specific, e.g. B2BIZMART)
+4. If not found → use the fallback from the MCP response
+5. If no fallback AND not in JSON → flag as `⚠️ UNRESOLVED` and STOP for that value
+
+**Never skip this step. Never use the variable name as a value.**
+
+---
+
+## Step 2 — Extract Per-Element Design Spec
+
+For EVERY visible element in the Figma frame, extract these properties into a structured list.
+Do NOT describe elements vaguely ("large heading", "tight spacing"). Use exact values.
+
+### For each TEXT element:
+```
+Element: [description, e.g. "Section heading H2"]
+- Font size: [resolved px] → [Tailwind class, e.g. text-5xl]
+- Font weight: [resolved number] → [Tailwind class, e.g. font-bold]
+- Line height: [resolved px or ratio] → [Tailwind class if applicable]
+- Letter spacing: [resolved px] → [Tailwind class if applicable]
+- Text color: [resolved hex] → [CSS variable, e.g. var(--color-heading)]
+- Text alignment: [left/center/right]
+- Max width: [if constrained]
+```
+
+### For each CONTAINER / LAYOUT element:
+```
+Element: [description, e.g. "Card grid wrapper"]
+- Layout: [flex-row / flex-col / grid]
+- Columns: [count] at [breakpoint]
+- Gap: [resolved px] → [Tailwind class, e.g. gap-6]
+- Padding: [top] [right] [bottom] [left] in px → [Tailwind classes]
+- Margin: [if any] → [Tailwind classes]
+- Max width: [if constrained]
+- Alignment: [items-start / items-center / justify-between, etc.]
+- Background: [resolved hex] → [CSS variable]
+```
+
+### For each IMAGE element:
+```
+Element: [description, e.g. "Hero background image"]
+- Width: [px or %]
+- Height: [px or %]
+- Aspect ratio: [e.g. 16/9, 4/3, 1/1]
+- Object fit: [cover / contain / fill]
+- Border radius: [resolved px] → [Tailwind class]
+- Position: [inline / background / overlapping]
+```
+
+### For each BUTTON / CTA element:
+```
+Element: [description, e.g. "Primary CTA button"]
+- Padding: [vertical]px [horizontal]px → [Tailwind classes]
+- Font size: [resolved px] → [Tailwind class]
+- Font weight: [resolved number] → [Tailwind class]
+- Background: [resolved hex] → [CSS variable]
+- Text color: [resolved hex] → [CSS variable]
+- Border: [width]px [color] → [Tailwind/CSS]
+- Border radius: [resolved px] → [Tailwind class]
+- Min height: [px if specified]
+```
+
+### For each CARD element:
+```
+Element: [description, e.g. "Product card"]
+- Padding: [inner padding px] → [Tailwind]
+- Background: [hex] → [CSS variable]
+- Border: [width] [color] → [Tailwind/CSS]
+- Border radius: [px] → [Tailwind]
+- Shadow: [if any] → [Tailwind shadow class]
+- Internal layout: [flex direction, gap between children]
+- Children: [list each child element with its own spec]
+```
+
+### For SECTION-LEVEL properties:
+```
+Section: [name]
+- Total padding top: [px]
+- Total padding bottom: [px]
+- Background: [hex] → [CSS variable]
+- Max width: [constrained or full-bleed]
+- Horizontal padding: [px] → var(--section-padding-x) or Tailwind
+```
+
+---
+
+## Step 3 — Extract Responsive Differences (Mobile Frame)
+
+If a mobile Figma frame is available, extract ONLY what DIFFERS from desktop:
+
+```
+MOBILE OVERRIDES (vs desktop):
+- Grid: [desktop columns] → [mobile columns]
+- Heading font size: [desktop class] → [mobile class]
+- Subheading font size: [desktop class] → [mobile class]
+- Gap: [desktop gap] → [mobile gap]
+- Padding: [desktop padding] → [mobile padding]
+- Element visibility: [hidden on mobile / shown on mobile]
+- Stack direction: [row on desktop] → [column on mobile]
+- Element order: [reordered on mobile?]
+```
+
+---
+
+## Step 4 — Produce the Design Spec Table
+
+Compile all extracted values into a single reference table that the build stage will use.
+Format:
+
+```
+DESIGN SPEC — <section_name>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+SECTION-LEVEL
+  Padding top: 48px | Padding bottom: 48px
+  Background: var(--color-background) | Full width: yes
+  Container max-width: max-w-container-theme
+
+ELEMENT MAP (top to bottom, left to right)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+#  | Element          | Property        | Desktop Value      | Mobile Override    | Tailwind/CSS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+1  | Section heading  | font-size       | 48px               | 30px               | text-5xl / md:text-3xl
+1  | Section heading  | font-weight     | 700                | —                  | font-bold
+1  | Section heading  | color           | #1a1a1a            | —                  | var(--color-heading)
+1  | Section heading  | text-align      | center             | center             | text-center
+1  | Section heading  | margin-bottom   | 16px               | 12px               | mb-4 / md:mb-3
+2  | Subheading       | font-size       | 18px               | 16px               | text-lg / md:text-base
+2  | Subheading       | color           | #666666            | —                  | var(--color-body)
+3  | Card grid        | layout          | grid               | grid               | grid
+3  | Card grid        | columns         | 4                  | 2                  | grid-cols-2 md:grid-cols-4
+3  | Card grid        | gap             | 24px               | 16px               | gap-4 md:gap-6
+4  | Card             | padding         | 16px               | 12px               | p-3 md:p-4
+4  | Card             | border-radius   | 12px               | 12px               | rounded-xl
+4  | Card             | border          | 1px #e5e5e5        | —                  | border border-[var(--color-border)]
+4  | Card             | shadow          | 0 1px 3px rgba()   | —                  | shadow-sm
+5  | Card image       | aspect-ratio    | 1/1                | 1/1                | aspect-square
+5  | Card image       | border-radius   | 8px                | 8px                | rounded-lg
+5  | Card image       | object-fit      | cover              | cover              | object-cover
+6  | Card title       | font-size       | 16px               | 14px               | text-base / md:text-sm
+6  | Card title       | font-weight     | 600                | —                  | font-semibold
+7  | CTA button       | padding         | 12px 24px          | 10px 20px          | py-3 px-6 / md:py-2.5 md:px-5
+7  | CTA button       | font-size       | 16px               | 14px               | text-base / md:text-sm
+7  | CTA button       | bg              | #2563eb            | —                  | var(--color-primary)
+7  | CTA button       | text            | #ffffff            | —                  | var(--color-on-primary)
+7  | CTA button       | border-radius   | 8px                | —                  | rounded-lg
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+UNRESOLVED VALUES: [list any that could not be determined]
+```
+
+This table is the CONTRACT. Every value in this table MUST appear in the generated code.
+During self-QA, check every row against the written HTML/CSS.
+
+---
+
+## Rules
+
+- NEVER describe values qualitatively ("large", "tight", "prominent"). Always use exact px/hex.
+- NEVER skip elements. If an element is in the Figma frame, it must be in the spec.
+- NEVER guess values. If a value cannot be determined, flag it as unresolved and ask.
+- ALWAYS resolve var() before adding to the spec table.
+- ALWAYS include both desktop and mobile values when a mobile frame is available.
+- The spec table is an ordered list (top-to-bottom, left-to-right in the visual layout).

package/ts-dist/mocks/init-theme/.cursor/rules/extract-tokens.mdc

@@ -0,0 +1,43 @@
+---
+description: Validate the Figma variables JSON exists for a theme
+alwaysApply: false
+---
+
+# /extract-tokens
+
+Verify the designer-exported `figma-variables.json` is in place.
+This is the only setup step needed before building sections.
+
+## Usage
+```
+/extract-tokens <theme_name>
+```
+
+---
+
+## Step 1 — Check JSON Exists
+
+Look for `figma-variables.json`.
+
+If missing, STOP and tell the developer:
+```
+❌ Missing: figma-variables.json
+
+Ask your designer to:
+  Figma → Variables panel → ··· menu → Export variables → JSON
+  Place the file at: figma-variables.json
+
+Re-run /extract-tokens once the file is in place.
+```
+
+## Step 2 — Confirm
+
+If the file exists, confirm:
+```
+✅ figma-variables.json found at figma-variables.json
+→ All build/compare/qa commands will read this file directly for token values.
+→ When designer updates tokens: re-export JSON, replace the file, done.
+→ Next step: run /audit-page <theme_name> <page_name>
+```
+
+No conversion needed. Commands read the JSON directly.

package/ts-dist/mocks/init-theme/.cursor/rules/figma-mcp-resolution.mdc

@@ -0,0 +1,40 @@
+---
+description: Resolve Figma MCP variable names using theme figma-variables.json (e.g. B2BIZMART mode)
+globs: ["sections/*.liquid", "snippets/*.liquid"]
+---
+
+# Figma MCP Variable Resolution
+
+When using **Figma MCP** (e.g. `get_design_context`) for any command or fix:
+
+## Rule
+
+Figma MCP returns values like `var(--variable-name, fallback)` (e.g. `var(--radius/xl, 25px)`, `var(--color/background-1/background-1, white)`). The fallback is from whatever mode is active in Figma (e.g. TWICE). The theme may use a different mode (e.g. B2BIZMART) whose values are in `figma-variables.json`.
+
+**Always resolve variable names from the theme’s `figma-variables.json` first; use the MCP fallback only if the variable is not present.**
+
+## Steps
+
+1. **Read** `figma-variables.json`.
+2. **For each** `var(--name, fallback)` in the Figma MCP output:
+   - Normalize the variable name: strip the leading `--` and unescape slashes (e.g. `--radius\/xl` → `radius/xl`).
+   - **Look up** in the JSON by path: split the name on `/` and traverse (e.g. `radius/xl` → `json["radius"]["xl"]`).
+   - If the path exists and the node has a **`$value`** property, **use that value** (theme/mode-specific).
+   - If the path is missing or has no `$value`, **use the fallback** from the MCP response.
+3. **Use the resolved value** (from JSON or fallback) when mapping to Tailwind classes, CSS variables, or inline styles. Never use the raw variable name for comparison or output.
+
+## Example
+
+- MCP returns: `rounded-[var(--radius\/xl, 25px)]`
+- Variable name: `radius/xl`
+- Look up: `figma-variables.json` → `radius.xl.$value` → e.g. `24`
+- **Use 24** (from JSON) for border-radius, not 25 (fallback). Map to Tailwind or `24px` as needed.
+
+## Commands that use this
+
+- `/compare-section` — when extracting Figma values from MCP data
+- `/fix-section` — when applying design from Figma MCP selection
+- `/build-section` — when reading Figma frame and mapping tokens
+- `/redesign-section` — when reading Figma frame for layout/typography/colors
+
+Reference this rule whenever Figma MCP output is used so the theme’s mode (e.g. B2BIZMART) is respected.

package/ts-dist/mocks/init-theme/.cursor/rules/fix-section.mdc

@@ -0,0 +1,154 @@
+---
+
+description: Fix a bug in an existing section with minimal blast radius
+alwaysApply: false
+---
+
+
+# /fix-section
+
+Fix a specific bug in an existing section.
+Minimal blast radius — only touch what is broken, nothing else.
+
+## Usage
+```
+/fix-section <theme_name> <section_name>
+```
+Describe the bug clearly: what you see vs what you expect.
+
+**Visual bugs (spacing, alignment, colour, typography, borders, CTA size, selected state):** Prefer running `/compare-section <theme_name> <section_name>` with desktop and mobile Figma URLs first; use the mismatch report to apply fixes, then `/qa-section`. Use fix-section for logic/schema issues or when Figma is not available.
+
+---
+
+
+## Pre-flight
+1. Read `sections/<section_name>.liquid` directly — do not ask for it
+2. Read ALL snippets referenced via `{% render %}` in the section automatically
+   - Read `snippets/<snippet-name>.liquid` for each
+   - Repeat recursively for nested snippets
+3. **When using Figma MCP** (e.g. get_design_context): resolve every `var(--name, fallback)` by looking up the variable name (path split by `/`) in `figma-variables.json`; if present use `$value`, else use fallback. See `.cursor/rules/figma-mcp-resolution.mdc`.
+4. Ask the user if they haven't already described:
+   - What is the current broken behaviour?
+   - What is the expected behaviour?
+   - Does it happen always or only in certain conditions (e.g. empty data, mobile, specific setting value)?
+
+---
+
+
+## Stage 1 — Diagnose Before Fixing
+Read the full section file and identify:
+
+### Common Bug Categories — check each
+
+**Schema / Settings mismatch**
+- Is a `section.settings.X` referenced in Liquid but missing from schema?
+- Is a field type wrong? (e.g. rendered as `.value` but schema type is `text` not `select`)
+- Is a `url` field rendered as `{{ field }}` instead of `{{ field.handle }}`?
+- Is a `select` field rendered as `{{ field }}` instead of `{{ field.value }}`?
+- Is an `image` field rendered as `{{ field }}` instead of `{{ field.url }}`?
+
+**Liquid Logic**
+- Is a loop missing an empty state guard (`{% if items.size > 0 %}`)?
+- Is a condition using wrong operator (`==` vs `!=`, `and` vs `or`)?
+- Is a variable assigned after it's used?
+- Is `{% render %}` passing the wrong variable name?
+
+**HTML / CSS**
+- Is a Tailwind class missing a responsive prefix (`md:`, `lg:`)?
+- Is a flex/grid container missing `items-center` or `justify-between`?
+- Is a `hidden` class conflicting with a display class?
+- Is a `z-index` missing on an overlay or dropdown?
+
+**Page JSON**
+- Is the section type in the page JSON mismatched with the actual filename?
+- Is a setting value in the wrong format? (e.g. `"value"` instead of `{ "display_name": "...", "value": "..." }`)
+- Is a block missing from `block_order`?
+- Theme block not rendering? Check section schema opts in (`@theme` or `zc_theme__<name>`), page JSON `type` uses `zc_theme__` prefix, and `blocks/<name>.liquid` exists
+- Theme block missing from picker? Check `blocks/<name>.liquid` has `"presets"`
+
+---
+
+
+## Stage 2 — State the Diagnosis
+Before making any edit, clearly state:
+
+```
+BUG DIAGNOSIS — <section_name>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ROOT CAUSE:
+  section.settings.cta_url is rendered as {{ cta_url.handle }} but
+  schema defines it as type "text", not type "url" — so .handle doesn't exist.
+
+LOCATION:
+  Line 34: <a href="{{ cta_url.handle }}">
+
+FIX:
+  Option A: Change schema field type from "text" to "url" (if it should be a URL)
+  Option B: Change render to {{ cta_url }} (if it should stay as text)
+
+RECOMMENDED: Option A — the field is clearly meant to be a URL based on usage.
+
+BLAST RADIUS:
+  - 1 schema field change
+  - 1 line Liquid change
+  - page JSON default value may need updating
+
+UNRELATED ISSUES NOTICED (not fixing now):
+  - Line 67: loop has no empty state — recommend /fix-section pass 2
+```
+
+Ask: "Proceed with recommended fix?" before editing.
+
+---
+
+
+## Stage 3 — Apply Fix
+- Change ONLY what is identified in the diagnosis
+- Do not refactor surrounding code
+- Do not improve unrelated areas
+- Do not change Tailwind classes unless they are the bug
+- Add a comment near the fixed line using standard Liquid comments:
+  `{% comment %} fixed: changed type text → url, was rendering .handle incorrectly {% endcomment %}`
+  - Never use `{{-- ... --}}` comment syntax — it may break rendering in this codebase.
+
+---
+
+
+## Stage 4 — Check Blast Radius
+After the fix, check all affected areas:
+
+**If schema field type changed:**
+- [ ] All Liquid references to this field updated to match new type syntax
+- [ ] Page JSON default value format matches new type
+  - url → `{ "display_name": "...", "handle": "/path" }`
+  - select → `{ "display_name": "...", "value": "..." }`
+
+**If Liquid logic changed:**
+- [ ] Check all branches of the condition are still valid
+- [ ] Check loop still has empty state
+
+**If HTML changed:**
+- [ ] Check responsive behaviour still intact
+- [ ] Check no other elements were accidentally shifted
+
+---
+
+
+## Output
+```
+✅ Fix applied: sections/<section_name>.liquid
+
+ROOT CAUSE: [one line summary]
+
+CHANGED:
+- Line 34: schema field type text → url
+- Line 34: render changed from {{ cta_url }} to {{ cta_url.handle }}
+- pages/<page>.json: default updated to { "display_name": "...", "handle": "/" }
+
+UNTOUCHED: everything else
+
+⚠️ OTHER ISSUES NOTICED (not fixed — separate passes recommended):
+- Line 67: loop missing empty state → run /fix-section again describing this
+
+NEXT: Run /qa-section <theme_name> <section_name> to verify
+```

package/ts-dist/mocks/init-theme/.cursor/rules/general.mdc

@@ -0,0 +1,30 @@
+---
+description: General project rules for this theme
+globs: ["**/*"]
+---
+
+# Project Overview
+This is a custom Liquid-based theme system (NOT standard Shopify).
+This is a single theme folder. The structure below describes the current theme:
+
+## Every Theme Follows This Folder Structure
+```
+
+  assets/         → JS, CSS, images, fonts
+  i18n/           → en.json, en.schema.json (translation keys)
+  layouts/        → theme.liquid, accounts.liquid, sitemap.liquid
+  sections/       → .liquid section files with embedded {% schema %}
+  snippets/       → reusable .liquid partials (rendered via {% render %})
+  pages/          → JSON page templates (index.json, product.json, etc.)
+  settings/       → schema.json, theme.json
+```
+
+## General Rules
+- NEVER reference Shopify-standard folder names like `templates/`, `config/`, `locales/`
+- Use `{% render 'snippet-name' %}` — NEVER use `{% include %}`
+- All user-facing strings must use translation keys: `"label": "t:sections.section_name.settings.field.label"`
+- CSS approach: Tailwind utility classes + CSS custom properties (e.g. `var(--color-primary)`)
+- JS: Vanilla JS only, class-based Web Components extending HTMLElement
+- Always use `loading="lazy"` on images except above-the-fold (use `loading="eager"` for hero/header)
+- Always escape user output: `{{ value | escape }}`
+- Assets referenced via: `{{ 'filename.js' | asset_url }}`

package/ts-dist/mocks/init-theme/.cursor/rules/i18n.mdc

@@ -0,0 +1,85 @@
+---
+description: i18n translation key rules — applies to all themes
+globs: ["i18n/*.json", "sections/*.liquid"]
+---
+
+# i18n / Translation Rules — b2bizmart Theme
+
+## Translation Files
+```
+i18n/en.json          → actual translated string values
+i18n/en.schema.json   → schema label/option translations
+```
+
+---
+
+## Key Naming Convention
+All translation keys follow this dot-notation pattern:
+
+### For section settings
+```
+t:sections.{section_name}.settings.{setting_id}.label
+t:sections.{section_name}.settings.{setting_id}.default
+t:sections.{section_name}.settings.{setting_id}.info
+```
+
+### For select options
+```
+t:sections.{section_name}.settings.{setting_id}.option__{n}.label
+```
+
+### For section name
+```
+t:sections.{section_name}.name
+```
+
+### For block names
+```
+t:sections.{section_name}.blocks.{block_type}.name
+t:sections.{section_name}.blocks.{block_type}.settings.{setting_id}.label
+t:sections.{section_name}.blocks.{block_type}.settings.{setting_id}.default
+```
+
+### For headers (UI dividers)
+```
+t:sections.{section_name}.settings.{header_id}.content
+```
+
+### For presets
+```
+t:sections.{section_name}.presets.default.name
+```
+
+---
+
+## Usage in Schema
+```jsonc
+// label
+"label": "t:sections.header.settings.logo_width.label"
+
+// default for text
+"default": "t:sections.header.settings.explore_text.default"
+
+// default for url
+"default": { "display_name": "t:sections.header.settings.explore_url.default", "handle": "/home" }
+
+// default for select
+"default": { "display_name": "t:sections.header.settings.layout_type.default", "value": "left-alignment" }
+
+// default for menu
+"default": { "display_name": "t:sections.footer.blocks.footer_menu.settings.footer_menu.default", "handle": "" }
+
+// default for media_picker (video)
+"default": { "url": "video.mp4", "is_video": true }
+
+// content for header type
+"content": "t:sections.header.settings.header_links.content"
+```
+
+---
+
+## Rules
+- ❌ NEVER hardcode English strings in schema `label`, `default`, `content`, or `name` fields
+- ✅ ALWAYS use `t:` prefixed keys for all user-facing schema strings
+- When generating a new section, always create matching `t:` keys for every label, default, and option
+- `display_name` in url/select/menu defaults must ALWAYS be a `t:` key, never a plain string