| name | add-template |
| description | Add new UI style template to the ui-style-react project. This skill should be used when users want to add a new style template with HTML/CSS code, create a new preview page, or register a template in the system. Triggers include "add template", "create new style", "add new template", or when users provide HTML code for a new UI style. |
Add Template
Overview
This skill automates the complete workflow for adding new UI style templates to the ui-style-react project. It handles directory creation, file generation, and automatic registration in the preview system.
When to Use
- When a user says "add new template" or "create style template"
- When a user provides HTML/CSS code that should become a new template
- When a user wants to add a new style to
/styles/preview/ pages
- When migrating templates from external sources
Quick Start
To add a new template, collect the following information:
| Parameter | Required | Description | Example |
|---|
category | ✅ | Style category | visual, core, retro, interaction, layout |
familyId | ✅ | Family/group name | grain, glassmorphism, minimalism |
templateId | ✅ | Unique template ID | visual-grain-film-noir |
htmlContent | ✅ | Full HTML content | Complete <!DOCTYPE html> page |
cssContent | ✅ | CSS styles | Corresponding stylesheet |
titleZh | Optional | Chinese title | 胶片黑色风格 |
titleEn | Optional | English title | Film Noir Style |
setAsDefault | ✅ Default: true | Set new template as default (first in list) | true / false |
⭐ Default Template Behavior / 默认模板行为
By default, newly added templates are set as the default template (first in the list).
新添加的模板默认会被设置为默认模板（列表中的第一个）。
setAsDefault: true (默认) - 新模板显示在第一位，用户打开预览页面首先看到新模板setAsDefault: false - 新模板添加到列表末尾
Workflow
🚨🚨🚨 CRITICAL RULES (READ FIRST!) 🚨🚨🚨
关键规则（必须首先阅读！）
Rule 1: ALWAYS check existing templates BEFORE creating manifest.json
- List existing template directories in
public/data/content/styles/{category}/{familyId}/
- The number of templates in manifest.json MUST equal the number of directories
Rule 2: NEVER overwrite existing templates in manifest.json
- When adding to an existing family, READ the current manifest.json first
- ADD your new template to the EXISTING templates array
- Do NOT create a new templates array with only your template
Rule 3: New templates are DEFAULT by default (first position)
- Unless user specifies otherwise, place new template FIRST in the templates array
- First template = default template shown when user opens preview page
Rule 4: Verify templatesCount after build
- After running build script, check that
templatesCount matches expected value
- If templatesCount is wrong, you likely forgot to include existing templates
⚠️ Pre-flight Checklist (MUST DO FIRST!)
⚠️ 预检清单（必须首先执行！）
Before starting the workflow, ALWAYS check for existing templates in the target family:
# 1. Check if family directory exists and list existing templates
ls -la public/data/content/styles/{category}/{familyId}/ 2>/dev/null || echo "New family - no existing templates"
# 2. Check existing manifest.json
cat src/data/styles/generated/{category}/{familyId}/manifest.json 2>/dev/null | grep -A 30 '"templates"' || echo "No existing manifest"
# 3. Count existing templates
EXISTING_COUNT=$(ls -d public/data/content/styles/{category}/{familyId}/*/ 2>/dev/null | wc -l | tr -d ' ')
echo "Existing templates: $EXISTING_COUNT"
echo "Expected after adding: $((EXISTING_COUNT + 1))"
Record the expected templatesCount and verify it after Step 8!
Step 1: Validate Parameters
Verify all required parameters are provided:
category must be one of: core, visual, retro, interaction, layoutfamilyId should match existing family or be a new valid nametemplateId should follow format: {category}-{familyId}-{variant} (kebab-case)htmlContent should be a complete HTML document with <!DOCTYPE html>cssContent should contain valid CSS
Step 2: Create Directory Structure
Create the template directory:
public/data/content/styles/{category}/{familyId}/{templateId}/
├── fullpage.html
└── fullpage.css
Execute:
mkdir -p public/data/content/styles/{category}/{familyId}/{templateId}
Step 3: Write Template Files
Write fullpage.html:
- Ensure the HTML links to
fullpage.css with: <link rel="stylesheet" href="fullpage.css">
- Remove any inline
<style> tags, move content to CSS file
- Keep
<script> tags for interactivity
Write fullpage.css:
- Extract all CSS from the original HTML
- Include any CSS variables and custom properties
🚨 JSX Template Format Requirements (CRITICAL!)
🚨 JSX 模板格式要求（关键！）
If the user provides React JSX code instead of HTML, you MUST follow these rules:
Rule 1: Use export default function syntax (NOT arrow function)
规则 1：使用 export default function 语法（不要用箭头函数）
The JSX compiler (jsxCompiler.js) uses regex to strip export statements. It ONLY matches:
export default function ComponentName()
JSX 编译器使用正则表达式来处理 export 语句，它只能匹配上述格式！
// ✅ CORRECT - 正确格式（编译器可以处理）
import React, { useState } from 'react';
import { Icon1, Icon2 } from 'lucide-react';
export default function MyComponent() {
const [state, setState] = useState(null);
return (
<div>...</div>
);
}
// ← 文件在这里结束，不需要额外的 export 语句！
// ❌ WRONG - 错误格式（会导致 "Unexpected token 'export'" 错误！）
import React, { useState } from 'react';
import { Icon1, Icon2 } from 'lucide-react';
const MyComponent = () => { // ← 箭头函数
const [state, setState] = useState(null);
return (
<div>...</div>
);
};
export default MyComponent; // ← 这行不会被编译器移除，导致运行时错误！
Rule 2: File naming for JSX templates
规则 2：JSX 模板文件命名
public/data/content/styles/{category}/{familyId}/{templateId}/
├── fullpage.jsx ← React/JSX component
└── fullpage.css ← Base styles (can be minimal for Tailwind CSS)
Rule 3: Supported imports (automatically provided by runtime)
规则 3：支持的 imports（运行时自动提供）
The React runtime (reactRuntime.js) provides these globally:
- All React hooks:
useState, useEffect, useRef, useMemo, etc.
- All Lucide React icons:
Zap, Star, Heart, ArrowRight, etc.
- React APIs:
createElement, Fragment, memo, forwardRef, etc.
You can import them normally - the compiler will strip the imports and use the runtime-provided versions.
Rule 4: Component name extraction
规则 4：组件名称提取
The compiler extracts the component name from export default function ComponentName. Make sure:
- Component name starts with uppercase letter
- Component name matches the expected preview component
Step 4: Update previewIdMapping
Edit src/utils/previewLoader.js:
Find the previewIdMapping object (around line 107) and add:
'{templateId}': {
category: '{category}',
familyId: '{familyId}',
templateId: '{templateId}'
},
Important: Add the entry in alphabetical order within the appropriate section (organized by category comments).
Step 5: Update styleTagsMapping
Edit src/data/metadata/styleTagsMapping.js:
Find the styleEnhancements object and add:
'{templateId}': {
primaryCategory: '{category}',
categories: ['{category}'],
tags: ['contemporary'],
relatedStyles: []
},
⚠️ Pre-flight Checklist (MUST DO FIRST!)
🚨 THIS IS CRITICAL - NEVER SKIP THIS STEP! This prevents the "only one template showing" bug!
Before doing anything, ALWAYS check for existing templates in the target family. This is the #1 cause of the manifest.json mistake!
# 1. Check if family directory exists and list existing templates
echo "=== Checking existing templates in {category}/{familyId} ===" && \
ls -la public/data/content/styles/{category}/{familyId}/ 2>/dev/null || echo "✓ New family - no existing templates"
# 2. Check existing manifest.json
echo "=== Checking existing manifest.json ===" && \
cat src/data/styles/generated/{category}/{familyId}/manifest.json 2>/dev/null | grep -A 50 '\"templates\"' || echo "✓ No existing manifest"
# 3. Count existing templates (CRITICAL!)
echo "=== Template Count ===" && \
EXISTING_COUNT=$(ls -d public/data/content/styles/{category}/{familyId}/*/ 2>/dev/null | wc -l | tr -d ' ') && \
echo "Existing template directories: $EXISTING_COUNT" && \
echo "Expected templatesCount after adding: $((EXISTING_COUNT + 1))"
⚠️ SAVE THE NUMBERS ABOVE! Use them to verify after Step 8!
If existing templates found: SAVE the existing manifest.json - you will add to it, not replace it!
Step 6: Check Existing Templates (⚠️ CRITICAL!)
步骤 6：检查现有模板（⚠️ 关键！）
Before creating or modifying manifest.json, you MUST check for existing templates!
在创建或修改 manifest.json 之前，必须检查现有模板！
6.1 List existing template directories
ls -la public/data/content/styles/{category}/{familyId}/
This will show all existing template directories. For example:
core-flat-design/
core-flat-design-ecommerce-landing/
6.2 Check existing manifest.json (if exists)
cat src/data/styles/generated/{category}/{familyId}/manifest.json 2>/dev/null || echo "No existing manifest"
If manifest.json exists, read and preserve the existing templates array!
6.3 Count expected templates
Formula: Expected templatesCount = Existing templates + 1 (new template)
Record this number to verify after the build.
Step 7: Create/Update Manifest File (⚠️ PRESERVE EXISTING!)
步骤 7：创建/更新 Manifest 文件（⚠️ 保留现有模板！）
Path: src/data/styles/generated/{category}/{familyId}/manifest.json
mkdir -p src/data/styles/generated/{category}/{familyId}
Scenario A: New Family (no existing manifest)
Create new manifest.json:
{
"id": "{category}-{familyId}",
"category": "{category}",
"family": {
"name": {
"zh-CN": "{Chinese Title}",
"en-US": "{English Title}"
},
"description": {
"zh-CN": "{Chinese description}",
"en-US": "{English description}"
},
"tags": ["contemporary", "other-tags"],
"relatedStyles": ["related-style-1", "related-style-2"]
},
"templates": [
{
"id": "{templateId}",
"title": {
"zh-CN": "{Chinese Template Title}",
"en-US": "{English Template Title}"
}
}
]
}
Scenario B: Existing Family (🚨 ADD to existing templates array!)
╔════════════════════════════════════════════════════════════════════════════╗
║ 🚨 CRITICAL: THIS IS WHERE THE BUG HAPPENS! ║
║ ║
║ You MUST: ║
║ 1. READ the EXISTING manifest.json file ║
║ 2. COPY all existing templates from the array ║
║ 3. ADD your new template to the array (first or last position) ║
║ 4. NEVER create a new array with only your template! ║
║ ║
║ ❌ WRONG: "templates": [ { "id": "new-only" } ] ║
║ This deletes all existing templates! ║
║ ║
║ ✅ RIGHT: "templates": [ ║
║ { "id": "existing-1" }, ← Keep! ║
║ { "id": "new-template" }, ← Add! ║
║ { "id": "existing-2" } ← Keep! ║
║ ] ║
║ ║
║ If you skip this, the preview page will ONLY show 1 template! ║
║ 用户将只看到 1 个模板！ ║
╚════════════════════════════════════════════════════════════════════════════╝
DO NOT OVERWRITE the templates array! You must:
- Read the existing manifest.json
- Keep ALL existing templates in the array
- Add the new template based on
setAsDefault setting:
setAsDefault: true (默认) → 添加到数组开头（第一位）setAsDefault: false → 添加到数组末尾
Example - WRONG ❌:
"templates": [
{ "id": "new-template-only", "title": {...} } // 🚫 Lost existing templates!
]
Example - CORRECT ✅ (setAsDefault: true - 默认行为):
"templates": [
{ "id": "new-template", "title": {...} }, // ⭐ NEW - 第一位 = 默认模板
{ "id": "existing-template-1", "title": {...} }, // ✅ Keep existing
{ "id": "existing-template-2", "title": {...} } // ✅ Keep existing
]
Example - CORRECT ✅ (setAsDefault: false):
"templates": [
{ "id": "existing-template-1", "title": {...} }, // ✅ Keep existing (still default)
{ "id": "existing-template-2", "title": {...} }, // ✅ Keep existing
{ "id": "new-template", "title": {...} } // ✅ Add new at end
]
Important:
- The
family.name should match the family's visual/design style name
- The
templates array MUST contain ALL templates in this family (existing + new)
- Include meaningful tags and relatedStyles for better discoverability
- Verify templatesCount after build matches the number of templates in the array!
Step 8: Rebuild Styles Index
Run the build script to regenerate the consolidated styles index:
node scripts/build-styles-index.js
This script:
- Reads all manifest.json files from
src/data/styles/generated/
- Aggregates metadata into a single index
- Outputs to
public/data/styles-index.json
- Updates
templatesCount for each family
- Ensures the style card appears in the frontend style list
Verification:
- Check the output for:
✨ Build complete!
- Verify success count includes your new family
- Check that
templatesCount is > 0 for your template
Step 9: Stage Files for Git (⚠️ IMPORTANT!)
步骤 9：将文件添加到 Git 暂存区（⚠️ 重要！）
After creating all files, you MUST stage them for git commit!
创建所有文件后，必须将它们添加到 git 暂存区！
This prevents CI failures due to missing files that exist locally but weren't committed.
这可以防止因本地存在但未提交的文件而导致的 CI 失败。
# Stage all new template files
git add "public/data/content/styles/{category}/{familyId}/{templateId}/"
git add "src/data/styles/generated/{category}/{familyId}/manifest.json"
git add "public/data/styles-index.json"
# If JSX template, also stage compiled JSX
git add "public/data/compiled-jsx/{category}-{familyId}-{templateId}*" 2>/dev/null || true
# If previewIdMapping was updated
git add "src/utils/previewLoader.js"
# If styleTagsMapping was updated
git add "src/data/metadata/styleTagsMapping.js"
# Verify staged files
git status
⚠️ Common Mistake: Creating files locally but forgetting to commit them causes CI test failures like:
Cannot find module '...'Missing content directories for template
Step 10: Verify and Report
After completing all steps, verify:
-
Template files exist:
ls -la public/data/content/styles/{category}/{familyId}/{templateId}/
-
previewIdMapping contains the new entry in src/utils/previewLoader.js
-
styleTagsMapping contains the new entry in src/data/metadata/styleTagsMapping.js
-
manifest.json exists and contains ALL templates:
cat src/data/styles/generated/{category}/{familyId}/manifest.json | grep -A 50 '"templates"'
-
Build script ran successfully: Check for ✨ Build complete! message
-
⚠️ CRITICAL: Verify templatesCount matches expected value:
# Check templatesCount in styles-index.json
cat public/data/styles-index.json | python3 -c "import sys,json; d=json.load(sys.stdin); families=[f for c in d['categories'].values() for f in c.get('families',[]) if f['familyId']=='{familyId}']; print(f'templatesCount: {families[0][\"templatesCount\"]}' if families else 'Family not found')"
Expected: templatesCount should equal the number of template directories in public/data/content/styles/{category}/{familyId}/
If templatesCount is wrong: Go back to Step 7 and ensure manifest.json includes ALL templates!
Quick Verification Commands (Run After Step 8!)
快速验证命令（步骤 8 之后运行！）
# 1. Count template directories (should match templatesCount)
echo "=== Template Directories ===" && ls -d public/data/content/styles/{category}/{familyId}/*/ 2>/dev/null | wc -l
# 2. Check manifest.json templates count
echo "=== Manifest Templates ===" && cat src/data/styles/generated/{category}/{familyId}/manifest.json | grep -c '"id":'
# 3. Check styles-index.json templatesCount
echo "=== Index templatesCount ===" && grep -A 3 '"familyId": "{familyId}"' public/data/styles-index.json | grep templatesCount
# All three numbers above should be EQUAL!
If numbers don't match: Go back to Step 7 and ensure manifest.json includes ALL templates!
Output success report:
✅ Template created successfully!
📁 Files created:
- public/data/content/styles/{category}/{familyId}/{templateId}/fullpage.html
- public/data/content/styles/{category}/{familyId}/{templateId}/fullpage.css
- src/data/styles/generated/{category}/{familyId}/manifest.json
📝 Registrations updated:
- src/utils/previewLoader.js (previewIdMapping)
- src/data/metadata/styleTagsMapping.js (styleEnhancements)
- public/data/styles-index.json (rebuilt with templatesCount)
⭐ Default Template: {Yes/No}
{If Yes: "This template will be shown first when users open the preview page"}
🌐 Preview URL: http://localhost:1000/styles/preview/{templateId}
✨ Frontend Integration:
✅ Style card will appear in the styles list
✅ Template is registered and discoverable
✅ Related styles are linked
⭐ {If default: "Set as default template (shown first)"}
🔧 Git Status:
✅ Files staged for commit (verify with: git status)
⚠️ Next steps:
1. Verify staged files: git status
2. Commit changes: git commit -m "✨ feat: add {templateId} template"
3. Push to remote: git push
4. Restart dev server: npm run dev
5. Visit the preview URL to verify
6. Check the styles list page to see the new style card
7. Update tags in styleTagsMapping.js for better discoverability
Interactive Mode
When parameters are incomplete, ask users step by step:
-
Category Selection:
"Which category should this template belong to?"
- core (Core design systems)
- visual (Visual effects and styles)
- retro (Retro/vintage styles)
- interaction (Interactive elements)
- layout (Layout patterns)
-
Family ID:
"What family/group should this template belong to? (e.g., grain, glassmorphism, minimalism)"
-
Template ID:
"What should the unique template ID be? Suggested format: {category}-{familyId}-{variant}"
-
⭐ Set as Default Template (默认模板设置):
"Should this template be the default (shown first when users open the preview page)?"
- Yes (Recommended) - 设为默认，用户打开预览页首先看到此模板
- No - 添加到列表末尾
Note: By default, new templates are set as the default template (first in list).
-
HTML Content:
"Please provide the complete HTML content for the template."
-
CSS Content:
"Please provide the CSS styles. If CSS is inline in the HTML, I'll extract it automatically."
Directory Structure Reference
ui-style-react/
├── public/
│ └── data/
│ └── content/
│ └── styles/
│ └── {category}/ # core, visual, retro, etc.
│ └── {familyId}/ # grain, glassmorphism, etc.
│ └── {templateId}/ # visual-grain-film-noir
│ ├── fullpage.html
│ └── fullpage.css
├── src/
│ ├── utils/
│ │ └── previewLoader.js # Contains previewIdMapping
│ └── data/
│ └── metadata/
│ └── styleTagsMapping.js # Contains styleEnhancements
Available Categories
| Category | Description |
|---|
core | Core design systems (minimalism, material design, flat design) |
visual | Visual effects (grain, glassmorphism, neon, gradients) |
retro | Retro/vintage styles (vaporwave, art deco, 80s) |
interaction | Interactive elements (mouse tracking, scroll effects) |
layout | Layout patterns (bento grids, masonry) |
Adding Second/Multiple Templates to Existing Family
向现有 Family 添加第二个/多个模板（关键！）
When adding a new template variant to an existing family (e.g., adding a second Vaporwave template), you must update the manifest.json file. This is the most common mistake!
当向现有 family 添加新模板变体时（例如：向 Vaporwave 添加第二个模板），必须更新 manifest.json 文件。这是最常见的错误！
Why This Matters / 为什么重要
The frontend reads the template list from manifest.json, NOT from the JS template file's previews array. If you only update the JS file but forget to update manifest.json, the new template will NOT appear in the preview selector.
前端从 manifest.json 读取模板列表，而不是从 JS 模板文件的 previews 数组。如果你只更新了 JS 文件而忘记更新 manifest.json，新模板将不会显示在预览选择器中。
Checklist for Adding Template to Existing Family
向现有 Family 添加模板的清单
-
✅ Create new template JS file (e.g., templates/visual/vaporwave/vaporwaveDreams.js)
创建新的模板 JS 文件
-
✅ Update family's index.js to import and add to previews array
更新 family 的 index.js，导入并添加到 previews 数组
-
✅ Add entry to previewIdMapping in src/utils/previewLoader.js
在 previewIdMapping 中添加条目
-
✅ Create content directory: public/data/content/styles/{category}/{familyId}/{templateId}/
创建内容目录（fullpage.html + fullpage.css）
-
⚠️ CRITICAL: Update manifest.json - Add new template to templates array:
⚠️ 关键：更新 manifest.json - 添加新模板到 templates 数组：
File: src/data/styles/generated/{category}/{familyId}/manifest.json
{
"templates": [
{
"id": "existing-template-id",
"title": { "zh-CN": "现有模板", "en-US": "Existing Template" }
},
{
"id": "new-template-id",
"title": { "zh-CN": "新模板", "en-US": "New Template" }
}
]
}
-
✅ Run build script: node scripts/build-styles-index.js
运行构建脚本
-
✅ Verify templatesCount increased in public/data/styles-index.json
验证 templatesCount 已增加
Quick Verification / 快速验证
After adding a new template variant, check:
添加新模板变体后检查：
# Check manifest.json has multiple templates
# 检查 manifest.json 有多个模板
cat src/data/styles/generated/{category}/{familyId}/manifest.json | grep -A 20 '"templates"'
# Verify templatesCount in styles-index.json
# 验证 styles-index.json 中的 templatesCount
grep -A 5 '"familyId": "{familyId}"' public/data/styles-index.json | grep templatesCount
Common Issues
🚨 CI Test Failure: "Cannot find module" or "Missing content directories" (NEW!)
🚨 CI 测试失败："Cannot find module" 或 "Missing content directories"（新！）
Symptoms / 症状:
- CI/GitHub Actions fails with:
Cannot find module '...'
- CI fails with:
Missing content directories for template
- Tests pass locally but fail in CI
- Files exist on your machine but CI can't find them
Root Cause / 根本原因:
You created files locally but forgot to commit them to git! Untracked files (shown as ?? in git status) won't be pushed to the remote repository.
你在本地创建了文件，但忘记提交到 git！未追踪的文件（在 git status 中显示为 ??）不会被推送到远程仓库。
Solution / 解决方案:
# 1. Check for untracked files
git status
# 2. Stage the missing files
git add "public/data/content/styles/{category}/{familyId}/{templateId}/"
git add "src/data/styles/generated/{category}/{familyId}/manifest.json"
git add "public/data/compiled-jsx/*" # If JSX template
git add "src/utils/*.js" # If new utility files
# 3. Commit and push
git commit -m "🐛 fix: add missing template files"
git push
Prevention / 预防:
- Always run
git status before pushing
- Follow Step 9 (Stage Files for Git) in this workflow
- The success report includes a Git Status section - verify it!
🚨 JSX Runtime Error: "Unexpected token 'export'" (NEW!)
🚨 JSX 运行时错误："Unexpected token 'export'"（新！）
Symptoms / 症状:
- Preview shows:
Runtime Error: Uncaught SyntaxError: Unexpected token 'export' (line XXX)
- The line number matches the location of
export default ComponentName; at the end of the file
Root Cause / 根本原因:
The JSX file uses arrow function + separate export syntax, which the JSX compiler cannot process:
// ❌ This pattern causes the error:
const MyComponent = () => { ... };
export default MyComponent; // ← This line is NOT stripped by compiler!
Solution / 解决方案:
Convert to export default function syntax:
// ✅ Change to this:
export default function MyComponent() {
// ... component code
}
// No separate export statement needed!
Technical Explanation / 技术说明:
The JSX compiler (src/utils/jsxCompiler.js) uses this regex to match exports:
const exportMatch = processedCode.match(/export\s+default\s+function\s+(\w+)/);
processedCode = processedCode.replace(/export\s+default\s+function\s+/, 'function ');
It ONLY matches export default function Name, not export default Name (variable export).
🚨 CRITICAL BUG: Second/Multiple Templates Not Showing! (Most Common!)
🚨 关键 BUG：第二个/多个模板未显示！（最常见！）
This happens when you add a new template to an existing family but manifest.json only shows 1 template!
这发生在你添加新模板到现有 family 时，但 manifest.json 只显示 1 个模板！
Symptoms / 症状:
- Preview page shows "Only 1 template available"
- Dropdown/selector only has 1 template option
- Expected 2+ templates, but only 1 shows
- Build script shows
templatesCount: 1 instead of 2
Root Cause / 根本原因:
You replaced the existing templates array instead of adding to it.
Example of WRONG approach:
// ❌ WRONG: This deletes the original template!
"templates": [
{ "id": "visual-antiDesign-studio", "title": {...} } // Lost the original!
]
Solution / 解决方案 (Do This NOW):
-
Read the existing manifest.json and check what templates exist:
cat src/data/styles/generated/{category}/{familyId}/manifest.json | grep -A 50 '"templates"'
-
Edit manifest.json and ADD your new template to the existing array:
"templates": [
{ "id": "visual-tech-anti-design", "title": {...} }, // ← EXISTING
{ "id": "visual-antiDesign-studio", "title": {...} } // ← NEW (added)
]
-
Rebuild the styles index:
node scripts/build-styles-index.js
-
Verify templatesCount increased:
# Before: templatesCount: 1
# After: templatesCount: 2
grep -A 3 '"familyId": "{familyId}"' public/data/styles-index.json | grep templatesCount
-
Restart dev server:
npm run dev
-
Check preview page - Should now show both templates!
⚠️ Second template not showing in preview selector (Most Common!)
⚠️ 第二个模板没有显示在预览选择器中（最常见！）
Cause / 原因: manifest.json was not updated with the new template entry. The frontend reads template list from manifest.json, not from the JS file's previews array.
manifest.json 没有更新新模板条目。前端从 manifest.json 读取模板列表，而不是从 JS 文件的 previews 数组。
Solution / 解决方案:
- Edit
src/data/styles/generated/{category}/{familyId}/manifest.json
- Add new template to the
templates array
- Run
node scripts/build-styles-index.js
- Verify
templatesCount is now correct (e.g., 2 instead of 1)
- Restart dev server
Example / 示例:
// Before (错误 - 只有1个模板)
"templates": [
{ "id": "visual-vaporwave-vaporwave-aesthetic", "title": {...} }
]
// After (正确 - 2个模板)
"templates": [
{ "id": "visual-vaporwave-vaporwave-aesthetic", "title": {...} },
{ "id": "visual-vaporwave-vaporwave-dreams", "title": {...} }
]
Template not showing in style list
Cause: templatesCount is 0 in public/data/styles-index.json
Solution:
- Ensure manifest.json exists at:
src/data/styles/generated/{category}/{familyId}/manifest.json
- Manifest must be in correct JSON format with valid
templates array
- Run build script:
node scripts/build-styles-index.js
- Verify
templatesCount is > 0 in public/data/styles-index.json
Template not showing in preview (404 error)
Cause: Preview route mapping or file path mismatch
Solutions:
- Verify directory path matches exactly:
public/data/content/styles/{category}/{familyId}/{templateId}/
- Check that
templateId in previewIdMapping matches the directory name exactly
- Verify previewIdMapping entry is added correctly
- Restart the dev server after making changes
CSS not loading in preview
Cause: Missing or incorrectly named CSS file
Solutions:
- Ensure
fullpage.html has: <link rel="stylesheet" href="fullpage.css">
- Check that CSS file is named exactly
fullpage.css
- Verify CSS file is in the correct directory:
public/data/content/styles/{category}/{familyId}/{templateId}/
Build script fails or shows ❌ for new family
Cause: manifest.json is missing or malformed
Solutions:
- Verify manifest.json exists and is valid JSON
- Check manifest structure matches the template in Step 6
- Ensure
templates array is not empty
- Run build script again:
node scripts/build-styles-index.js
Template ID conflicts
- Use unique IDs following the pattern:
{category}-{familyId}-{variant}
- Check existing mappings before creating new ones
- Verify no duplicate entries in previewIdMapping
Automated Script (Recommended!)
自动化脚本（推荐！）
IMPORTANT: The project has a built-in create-template.js script that automates the entire workflow, including manifest.json update!
重要：项目有内置的 create-template.js 脚本，可以自动化整个工作流，包括自动更新 manifest.json！
Quick Usage / 快速使用
# Interactive mode (recommended) / 交互式模式（推荐）
npm run create-template
# Or with CLI parameters / 或使用命令行参数
npm run create-template -- \
-c visual \
-f vaporwave \
-t visual-vaporwave-dreams \
--title-zh "梦幻美学" \
--title-en "Dreams Aesthetic"
What the Script Does Automatically / 脚本自动完成的工作
- ✅ Creates directory structure:
public/data/content/styles/{category}/{family}/{templateId}/
- ✅ Generates HTML/CSS template files (demo.html, fullpage.html, etc.)
- ✅ Updates
manifest.json - Adds new template to the templates array
- ✅ Updates
styleTagsMapping.js - Adds template enhancement config
- ✅ Creates Prompt files (optional):
custom.md and style.md
CLI Parameters / 命令行参数
| Parameter | Short | Description | Required |
|---|
--category | -c | Category (core/visual/retro/interaction/layout) | ✅ |
--family | -f | Family name | ✅ |
--template-id | -t | Template ID (format: {category}-{family}-{variant}) | ✅ |
--title-zh | - | Chinese title | ❌ |
--title-en | - | English title | ❌ |
--format | - | File format (html/jsx) | ❌ |
--skip-prompts | - | Skip Prompt file creation | ❌ |
Examples / 示例
# Add second template to existing vaporwave family
# 向现有 vaporwave family 添加第二个模板
npm run create-template -- \
-c visual \
-f vaporwave \
-t visual-vaporwave-neon-city \
--title-zh "霓虹都市" \
--title-en "Neon City"
# JSX format template
# JSX 格式模板
npm run create-template -- \
-c visual \
-f glassmorphism \
-t visual-glassmorphism-dashboard \
--title-zh "仪表板" \
--title-en "Dashboard" \
--format jsx
# Skip Prompt files
# 跳过 Prompt 文件
npm run create-template -- \
-c retro \
-f arcadeCRT \
-t retro-arcadeCRT-game-ui \
--title-zh "游戏界面" \
--title-en "Game UI" \
--skip-prompts
After Running the Script / 脚本运行后
-
Edit template files - Add your actual HTML/CSS content
编辑模板文件 - 添加实际的 HTML/CSS 内容
-
Run build script - Regenerate styles index
运行构建脚本 - 重新生成样式索引
node scripts/build-styles-index.js
-
Add to previewIdMapping - If preview route is needed
添加到 previewIdMapping - 如果需要预览路由
// src/utils/previewLoader.js
'{templateId}': { category: '{category}', familyId: '{familyId}', templateId: '{templateId}' },
-
Restart dev server and test
重启开发服务器并测试
npm run dev
Script Architecture / 脚本架构
scripts/
├── create-template.js # Main CLI entry point
└── lib/
├── interactive.js # Interactive input logic
├── generators.js # File template generators
├── metadata-updater.js # manifest.json & styleTagsMapping.js updater
└── validator.js # Input validators
Resources
references/
See references/existing-families.md for a complete list of existing family IDs and their descriptions.
scripts/
scripts/create-template.js - Main template creation script (recommended!)scripts/build-styles-index.js - Rebuild styles-index.json after changesscripts/README.md - Full documentation for the create-template script
