codebase-to-wordpress-converter

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codebase to WordPress Converter

代码库转WordPress主题转换器

Overview

概述

This skill is designed for the high-fidelity conversion of static or React-based frontends into fully functional, CMS-driven WordPress themes. It acts as a Senior WordPress Architect, React Expert, and QA Engineer to ensure a 100% pixel-perfect match while integrating deep WordPress functionality like ACF, dynamic menus, and technical SEO preservation.

本技能旨在将静态或基于React的前端高保真转换为功能完备、由CMS驱动的WordPress主题。它同时扮演资深WordPress架构师、React专家和QA工程师的角色，确保与原设计100%像素级匹配，同时集成ACF、动态菜单、技术SEO保留等深度WordPress功能。

When to Use This Skill

适用场景

Use when converting a React (CRA/Vite/Next.js) or HTML project into a WordPress theme.
Use when the client demands a 100% pixel-perfect match with the original source.
Use when auditing an existing WordPress conversion for structural or SEO flaws.
Use when you need to ensure technical SEO (Schema, Meta tags, Heading hierarchy) is preserved exactly.

当需要将React（CRA/Vite/Next.js）或HTML项目转换为WordPress主题时使用。
当客户要求与原始设计100%像素级匹配时使用。
当需要审计现有WordPress转换项目的结构或SEO缺陷时使用。
当需要确保技术SEO（Schema、Meta标签、标题层级）完全保留时使用。

Core Capabilities

核心能力

Phased Conversion & Audit

分阶段转换与审计

The skill follows a strict 4-phase forensic process:

Phase 1: Forensic UI Comparison: Side-by-side table audit of React components vs. WordPress templates to find discrepancies.
Phase 2: Full Audit: Deep dive into UI, SEO, CMS Editability, Navigation, Functionality, and Performance.
Phase 3: Action Plan: Tasks classified as SAFE, RISKY, or BLOCKED to prevent breaking the UI.
Phase 4: Iterative Fixing: Executing one safe task at a time with validation after each step.

本技能遵循严格的四阶段精细化流程：

阶段1：UI逐项对比审计：将React组件与WordPress模板进行逐项表格对比，找出差异。
阶段2：全面审计：深入审查UI、SEO、CMS可编辑性、导航、功能与性能。
阶段3：行动计划：将任务分为安全（SAFE）、**风险（RISKY）或阻塞（BLOCKED）**三类，避免破坏UI。
阶段4：迭代修复：每次执行一项安全任务，并在每一步后进行验证。

Absolute UI Lock

绝对UI锁定

Strict enforcement of non-negotiable rules:

No alterations to layout, spacing, typography, or colors.
Exact preservation of Tailwind or CSS class names.
Zero changes to DOM structure or HTML nesting.

严格执行不可协商的规则：

不得修改布局、间距、排版或颜色。
精确保留Tailwind或CSS类名。
不得更改DOM结构或HTML嵌套。

Step-by-Step Guide

分步指南

1. Discovery & Forensic Audit

1. 发现与精细化审计

Start by identifying all components in the source code. Create a UI Comparison table comparing the original source output against the target WordPress output.

Rule: No fixes are allowed during this phase; only detection.

首先识别源代码中的所有组件。创建UI对比表格，对比原始输出与目标WordPress输出。

规则：此阶段仅允许检测问题，不得进行修复。

2. Strategic Field Mapping

2. 策略性字段映射

Map static React/HTML content to dynamic WordPress functions:

Replace static text with
```
the_title()
```
,
```
get_field()
```
, or
```
the_content()
```
.
Replace static paths with
```
get_template_directory_uri()
```
.

将静态React/HTML内容映射到动态WordPress函数：

使用
```
the_title()
```
、
```
get_field()
```
或
```
the_content()
```
替换静态文本。
使用
```
get_template_directory_uri()
```
替换静态路径。

3. Implementation of Core Hooks

3. 核心钩子实现

Ensure every theme includes the foundational WordPress hooks correctly:

Layout Files (
header.php
/
footer.php
): Must include

wp_head()

before

</head>

and

wp_footer()

before

</body>

Page Templates: Must call
```
get_header()
```
and
```
get_footer()
```
.
```
register_nav_menus()
```
for dynamic navigation without breaking original HTML structure.

确保每个主题正确包含基础WordPress钩子：

布局文件（
header.php
/
footer.php
）：必须在
```
</head>
```
前包含
```
wp_head()
```
，在
```
</body>
```
前包含
```
wp_footer()
```
。
页面模板：必须调用
```
get_header()
```
和
```
get_footer()
```
。
使用
```
register_nav_menus()
```
实现动态导航，同时不破坏原始HTML结构。

4. Validation & Live Tracker

4. 验证与实时追踪

Maintain a live tracker of Total Issues, Fixed, and Remaining. Every fix must be followed by a confirmation:

✅ No UI change
✅ No DOM change
✅ No class change

维护问题总数、已修复数和剩余数的实时追踪表。每次修复后必须确认：

✅ 无UI变更
✅ 无DOM变更
✅ 无类名变更

Examples

示例

Example 1: Navigation Conversion

示例1：导航转换

php

// WRONG: Static replacement that adds wrappers
wp_nav_menu(['theme_location' => 'primary']);

// CORRECT: Preserving original Tailwind classes and structure
wp_nav_menu([
    'theme_location' => 'primary',
    'container' => false,
    'items_wrap' => '<ul class="flex space-x-8">%3$s</ul>',
    'walker' => new Custom_Tailwind_Walker()
]);

php

// 错误：添加额外容器的静态替换方式
wp_nav_menu(['theme_location' => 'primary']);

// 正确：保留原始Tailwind类名与结构
wp_nav_menu([
    'theme_location' => 'primary',
    'container' => false,
    'items_wrap' => '<ul class="flex space-x-8">%3$s</ul>',
    'walker' => new Custom_Tailwind_Walker()
]);

Example 2: Asset Pathing

示例2：资源路径处理

php

// Source: <img src="/images/logo.png" />
// WP Conversion:
<img src="<?php echo get_template_directory_uri(); ?>/assets/images/logo.png" alt="Logo" />

php

// 原始代码：<img src="/images/logo.png" />
// WordPress转换后：
<img src="<?php echo get_template_directory_uri(); ?>/assets/images/logo.png" alt="Logo" />

Best Practices

最佳实践

✅ Do: Use
```
get_page_by_path()
```
for robust internal linking.
✅ Do: Implement ACF (Advanced Custom Fields) fallbacks in
```
functions.php
```
.
✅ Do: Keep the Tailwind configuration in the
```
header.php
```
to ensure global styles are active.
❌ Don't: Add "div" wrappers or rename classes to "clean up" the code.
❌ Don't: Use standard WordPress default styles if they conflict with the original design.

✅ 建议： 使用
```
get_page_by_path()
```
实现可靠的内部链接。
✅ 建议： 在
```
functions.php
```
中实现ACF（Advanced Custom Fields）降级方案。
✅ 建议： 将Tailwind配置放在
```
header.php
```
中，确保全局样式生效。
❌ 禁止： 添加额外div容器或重命名类名来“清理”代码。
❌ 禁止： 如果与原始设计冲突，请勿使用WordPress默认样式。

Additional Resources

额外资源

Limitations

局限性

Use this skill only when the task clearly matches the scope described above.
Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

仅当任务完全符合上述描述的范围时使用本技能。
请勿将输出结果替代环境特定的验证、测试或专家评审。
如果缺少必要的输入、权限、安全边界或成功标准，请停止操作并请求澄清。