@shopkit/cli 0.1.0 → 0.2.0

package/README.md

@@ -48,6 +48,127 @@ bun run validate:template --theme=dawn
 bun run cli
 ```
 
+## Theme Generator Output
+
+Running `bun run g theme <name>` creates the following structure:
+
+```
+src/themes/{theme-id}/
+├── theme.json                    # Theme configuration
+├── templates/
+│   ├── home/default.ts           # Home page template
+│   ├── home-b/default.ts         # Home A/B variant
+│   ├── products/default.ts       # Products page template
+│   ├── products-b/default.ts     # Products A/B variant
+│   ├── collection/default.ts     # Collection page template
+│   ├── collection-b/default.ts   # Collection A/B variant
+│   ├── orders/default.ts         # Orders/Thank You page
+│   └── variant-registry.ts       # Template registry
+└── locales/
+    ├── common/{lang}.json        # Common translations (logo, site_name, etc.)
+    └── pages/
+        ├── home/{lang}.json
+        ├── home-b/{lang}.json
+        ├── products/{lang}.json
+        ├── products-b/{lang}.json
+        ├── collections/{lang}.json
+        ├── collections-b/{lang}.json
+        └── orders/{lang}.json
+```
+
+### Template Structure
+
+All generated templates follow this consistent pattern:
+
+```typescript
+// Each template has three sections:
+{
+  sections: [
+    // 1. Header Section
+    {
+      type: SECTION_TYPES.HEADER_SECTION,
+      widgets: [{ type: WIDGET_TYPES.Header }]
+    },
+    // 2. Main Content Section
+    {
+      type: SECTION_TYPES.CONTENT_SECTION,
+      widgets: [{
+        type: WIDGET_TYPES.PageContent,
+        settings: {
+          heading: "t:{page_name}.heading",
+          description: "t:{page_name}.description"
+        }
+      }]
+    },
+    // 3. Footer Section
+    {
+      type: SECTION_TYPES.FOOTER_SECTION,
+      widgets: [{ type: WIDGET_TYPES.Footer }]
+    }
+  ]
+}
+```
+
+### Translation Key Structure
+
+Each page has a corresponding locale file with this structure:
+
+```json
+{
+  "{page_name}": {
+    "page_title": "Page Title",
+    "heading": "Page Heading",
+    "description": "Welcome to the page."
+  }
+}
+```
+
+Translation keys are referenced in templates using the `t:` prefix:
+- `t:home.heading` - Resolves to the heading from home locale
+- `t:products.description` - Resolves to the description from products locale
+
+### Essential Widgets
+
+The theme generator creates these essential widgets if they don't exist:
+
+| Widget | Purpose |
+|--------|---------|
+| `Header` | Site header with navigation |
+| `Footer` | Site footer with links |
+| `PageContent` | Displays translated heading and description |
+
+### A/B Variant Templates
+
+Templates with `-b` suffix (home-b, products-b, collection-b) are for A/B testing:
+- Use the same translation structure as their base templates
+- Allow different layouts/widgets for experimentation
+- Can be served to different user segments
+
+## Widget Generator Output
+
+Running `bun run g widget <name>` creates:
+
+```
+src/widgets/{scope}/{WidgetName}/
+├── index.tsx           # Widget entry point with variant resolution
+├── types.ts            # TypeScript interfaces (Settings, Data, Props)
+├── variants.ts         # Variant registry
+└── V1/
+    └── index.tsx       # Default V1 variant component
+```
+
+## Template Generator Output
+
+Running `bun run g template <name>` creates:
+
+```
+src/themes/{theme}/templates/{template-name}/
+└── default.ts          # Template configuration
+
+src/themes/{theme}/locales/pages/{template-name}/
+└── {lang}.json         # Translation file for each supported language
+```
+
 ## Programmatic Usage
 
 ```typescript
@@ -62,6 +183,9 @@ import {
 // Generate a widget programmatically
 await generateWidget({ name: "HeroBanner", scope: "common" });
 
+// Generate a theme
+await generateTheme({ name: "dawn", lang: "en" });
+
 // Validate widgets
 const { passed, errors } = await runWidgetValidation();
 ```