You are a senior WordPress theme architect, Gutenberg developer, frontend engineer, accessibility specialist, and QA engineer.
Your task is to take the ZIP file attached to this prompt and convert its website/design into a complete, production-quality, installable WordPress theme.
The input ZIP may represent ANY category or type of website, including:
* Blog
* Magazine
* News
* Technology
* Business
* Corporate
* SaaS
* Agency
* Portfolio
* Real estate
* Directory
* Restaurant
* Travel
* Ecommerce-oriented content site
* Personal site
* Education
* Medical
* Legal
* Finance
* Automotive
* Classifieds
* Events
* Reviews
* Other specialized verticals
Do NOT assume that every source ZIP requires the same architecture.
You must first inspect and understand the supplied website and then independently determine which WordPress architecture, post types, taxonomies, fields, templates, blocks, menus, settings, permalink structure, and functionality are appropriate.
The final deliverable MUST be an installable `.zip` WordPress theme.
---
# PRIMARY OBJECTIVE
Convert the supplied website as-is into a real Gutenberg-compatible WordPress theme. Do NOT redesign or rebuild its frontend from scratch.
## NON-NEGOTIABLE SOURCE-PRESERVATION CONTRACT
Gutenberg is an editing layer over the original frontend, NEVER a replacement frontend.
1. MUST copy and ship original production HTML fragments, CSS files, JavaScript files, fonts, images, icons, and responsive assets before creating blocks.
2. MUST derive each block's frontend `save` markup or PHP render markup directly from the corresponding original HTML fragment. Preserve element order, nesting, tag names, classes, IDs, `data-*` attributes, and behavior hooks.
3. MUST load original CSS unchanged as the primary frontend stylesheet. Add only minimal WordPress compatibility CSS. NEVER recreate original styling with new design tokens, core-block presets, generic grids, or approximate CSS.
4. MUST load original JavaScript unchanged when browser-compatible. Adapt only selectors, data endpoints, or initialization boundaries required by WordPress. NEVER replace working source interactions with a new implementation for convenience.
5. MUST make content editable by replacing text/media/URLs/data inside preserved nodes. NEVER make content editable by replacing preserved nodes with visually similar core-block markup.
6. Core blocks MAY be used only when their rendered frontend DOM is byte-equivalent in all behavior/styling-relevant nodes. Otherwise create a custom block or server render that emits source markup.
7. Editor canvas appearance is not proof. Acceptance compares public frontend URL against original source URL.
DO NOT:
```html
```
TARGET:
```html
```
Before implementation, create a source-preservation manifest for every template/component containing:
- source HTML file + exact fragment/root selector;
- original CSS files and selectors governing it;
- original JavaScript files and behavior hooks;
- output template/block responsible for it;
- intended editable fields;
- allowed DOM deviations with concrete WordPress/security reason.
Missing manifest entry means implementation MUST stop. No design may be generated from screenshots, inferred aesthetics, or memory.
The original ZIP is the visual source of truth and the functional reference.
Preserve its rendered HTML structure, CSS, design, layout, content structure, page types, visual hierarchy, responsive behavior, and important interactions while translating content and behavior into proper WordPress concepts.
The finished theme must behave like a professionally developed commercial or WordPress.org-quality theme.
It must NOT be a static HTML website copied into PHP templates or hidden inside giant Custom HTML blocks.
---
# MANDATORY FINAL OUTPUT
You must actually create all files and return a downloadable ZIP.
Do not merely provide code snippets.
Do not provide an implementation guide instead of creating the theme.
Do not stop after analysis.
Do not tell me what files I should create.
CREATE THEM.
The final response must contain a direct link to the generated installable WordPress theme ZIP.
The ZIP must contain exactly one valid theme root directory so it can be installed through:
WordPress Admin → Appearance → Themes → Add New → Upload Theme
or extracted directly into:
`wp-content/themes/`
---
# PHASE 1 — INSPECT THE INPUT BEFORE CODING
Extract and thoroughly inspect the attached ZIP.
Determine:
* All available pages.
* Page hierarchy.
* Shared site components.
* Header structure.
* Navigation structure.
* Footer structure.
* Sidebars.
* Search interfaces.
* Forms.
* Hero sections.
* Cards.
* Lists.
* Tables.
* Filters.
* Galleries.
* Sliders.
* Modals.
* Tabs.
* Accordions.
* Maps.
* Calls to action.
* Article layouts.
* Archive layouts.
* Category layouts.
* Author layouts.
* Search layouts.
* Landing pages.
* Listing pages.
* Detail pages.
* Authentication-related UI if present.
* Special content types.
* Metadata attached to content.
* Relationships between different content entities.
* Structured URLs present in the source.
* JavaScript interactions.
* Existing responsive states.
* Existing image assets.
* Icons.
* Fonts.
* Colors.
* Border radii.
* Shadows.
* spacing conventions.
* typography conventions.
* repeated UI patterns.
* forms and their purposes.
* schema or structured data hints.
* SEO-related structure.
Do not blindly reproduce the folder structure of the source project.
Infer the underlying content model.
For example, if the source contains property listings, determine whether those should become a `property` Custom Post Type with taxonomies and fields.
If the source contains reviews, products, destinations, recipes, team members, jobs, events, listings, documentation, or other structured entities, model them properly in WordPress.
---
# PHASE 2 — CHOOSE THE CORRECT WORDPRESS ARCHITECTURE
Choose the architecture based on the source website instead of applying one universal architecture.
Use the simplest architecture that fully supports the website.
You may use:
* Native posts
* Native pages
* Categories
* Tags
* Custom Post Types
* Custom taxonomies
* Custom meta
* ACF field groups
* Gutenberg
* Custom Gutenberg blocks
* Block patterns
* Block styles
* Template parts
* Reusable components
* Query Loop
* Navigation menus
* Widget/sidebar areas where appropriate
* WordPress Customizer where appropriate
* Theme settings pages where appropriate
* theme.json
* WordPress REST API where appropriate
* AJAX where appropriate
* Rewrite rules where appropriate
* Custom image sizes
* Custom capabilities where genuinely necessary
Do not introduce complexity without a reason.
Do not turn normal pages into Custom Post Types.
Do not create custom database tables unless there is a genuine technical reason.
Prefer WordPress-native architecture whenever possible.
---
# BLOCK THEME VS CLASSIC/HYBRID THEME
Analyze the source and choose between:
1. Native block theme / Full Site Editing architecture.
2. Hybrid Gutenberg theme.
3. Classic theme with deep Gutenberg support.
Prefer modern WordPress block capabilities whenever practical.
Regardless of architecture, normal content editing MUST use Gutenberg visually.
Users must not need to edit HTML source code to change ordinary content.
---
# GUTENBERG IS MANDATORY
The WordPress editor must provide REAL element management.
Do NOT solve this task by putting an entire page into:
* a Custom HTML block;
* one giant shortcode;
* one giant PHP-generated content string;
* one enormous custom block whose only editable field is HTML;
* an iframe;
* a hardcoded template containing all page content.
That is explicitly unacceptable.
Convert source components into appropriate Gutenberg constructs.
Examples include:
* Heading → `core/heading`
* Paragraph → `core/paragraph`
* Image → `core/image`
* Gallery → `core/gallery`
* Columns → `core/columns`
* Column → `core/column`
* Button → `core/button`
* Buttons → `core/buttons`
* Quote → `core/quote`
* List → `core/list`
* Separator → `core/separator`
* Spacer → `core/spacer` only where semantic spacing controls are insufficient
* Cover/hero image → `core/cover`
* Video → appropriate video/embed block
* FAQ → native Details blocks or a dedicated semantic FAQ block when required
* Dynamic listings → Query Loop or purpose-built dynamic block
* Structured specialty components → purpose-built Gutenberg blocks
Every page should be visually manageable from WordPress.
---
# CUSTOM GUTENBERG BLOCK POLICY
Create custom blocks only when native Gutenberg blocks are insufficient.
Examples where custom blocks may make sense:
* Property search
* Property details
* Stock ticker
* Recipe metadata
* Review score
* Event schedule
* Pricing calculator
* Advanced filtering
* Directory listing
* Comparison table
* Specialized CTA
* Dynamic news ticker
* Author information panel
* Interactive map
* Advanced hero component
* Custom data-driven cards
Custom blocks must:
* Have visual editor controls.
* Use InspectorControls appropriately.
* Use InnerBlocks when content composition is appropriate.
* Support alignment where appropriate.
* Support spacing controls.
* Support typography controls where appropriate.
* Support color controls where appropriate.
* Support responsive behavior.
* Sanitize saved values.
* Escape frontend output.
* Avoid storing arbitrary HTML when structured attributes can be used.
* Render correctly in both editor and frontend.
The editor preview should closely resemble the frontend.
---
# DESIGN SYSTEM — CRITICAL REQUIREMENT
Do NOT use random hardcoded measurements throughout the stylesheet.
Build a coherent design-token system.
Define reusable variables/tokens for at least:
* Colors
* Background colors
* Text colors
* Muted colors
* Accent colors
* Border colors
* Success/warning/error colors where applicable
* Font families
* Font sizes
* Font weights
* Line heights
* Letter spacing
* Container widths
* Narrow content widths
* Wide content widths
* Page gutters
* Section spacing
* Element spacing
* Grid gaps
* Border radii
* Borders
* Shadows
* Header heights where required
* Transition durations
* Focus styles
* Breakpoints when CSS requires them
Prefer `theme.json` presets plus CSS custom properties.
For source conversions, preserve existing CSS values and cascade. Introduce tokens only when they alias original values without changing selectors, specificity, computed styles, or responsive behavior.
Example conceptual system:
`--wp--preset--spacing--10`
`--wp--preset--spacing--20`
`--wp--preset--spacing--30`
and theme-specific tokens when necessary.
Use a deliberate spacing scale rather than unrelated values such as:
`17px`
`23px`
`38px`
`11px`
scattered throughout the project.
All visually related components should use the same spacing system.
---
# RESPONSIVENESS — ZERO COLLISION REQUIREMENT
The entire theme must be genuinely responsive.
Do not merely add one mobile breakpoint.
Test layouts conceptually and technically across at least:
* 320px
* 360px
* 375px
* 390px
* 414px
* 480px
* 768px
* 1024px
* 1280px
* 1440px
* 1920px
Components must adapt correctly between these widths.
Prevent:
* Text overlapping images.
* Navigation overlapping logos.
* Buttons colliding.
* Cards colliding.
* Horizontal overflow.
* Elements escaping containers.
* Fixed-width content breaking mobile.
* Long headings overflowing.
* Long URLs overflowing.
* Form elements overflowing.
* Table overflow.
* Absolute-positioned decorative elements covering content.
* Sticky elements hiding content.
* Dropdowns rendering off-screen.
* Modal overflow.
* Footer columns colliding.
* Grid cards becoming too narrow.
* Images stretching incorrectly.
* Text becoming unreadably small.
* Touch targets becoming too small.
Use modern responsive CSS appropriately:
* Grid
* Flexbox
* `minmax()`
* `clamp()`
* `min()`
* `max()`
* `auto-fit`
* `auto-fill`
* container-aware behavior where useful
* fluid typography
* fluid spacing where useful
Avoid unnecessary fixed heights.
Avoid arbitrary negative margins.
Avoid layout hacks.
If absolute positioning is used decoratively, it must not determine critical document layout.
---
# ACCESSIBILITY — WCAG-ORIENTED IMPLEMENTATION
Build accessibility into the theme from the beginning.
Target WCAG 2.2 AA practices.
Include:
* Semantic HTML landmarks.
* Correct heading hierarchy.
* Keyboard-accessible navigation.
* Visible `:focus-visible` states.
* Skip-to-content link.
* Proper form labels.
* Accessible error messaging.
* Accessible menu toggles.
* Correct `aria-expanded`.
* Correct `aria-controls` where relevant.
* Meaningful button labels.
* Meaningful link text.
* Alt-text support.
* Sufficient text contrast.
* Sufficient interactive-state contrast.
* Minimum usable touch targets.
* Reduced-motion handling through `prefers-reduced-motion`.
* No functionality requiring hover alone.
* Accessible accordions/tabs/modals if these exist.
* Correct table semantics.
* Screen-reader text where necessary.
Do not solve accessibility by indiscriminately adding ARIA.
Use semantic native HTML first.
---
# GLOBAL STYLE EDITING
The administrator must be able to manage important global design settings.
Where appropriate expose:
* Brand colors.
* Accent color.
* Background color.
* Text colors.
* Link colors.
* Typography.
* Content width.
* Wide content width.
* Button styles.
* Border radius.
* General spacing presets.
* Logo.
* Site icon.
* Header options.
* Footer options.
Prefer WordPress Global Styles and `theme.json` for values Gutenberg already understands.
Do not unnecessarily duplicate controls in multiple places.
---
# HEADER AND NAVIGATION
Navigation must use real WordPress menu/navigation functionality.
Do not hardcode menu items into templates.
Determine the navigation locations required by the source.
Examples may include:
* Primary
* Secondary
* Utility
* Mobile
* Footer
* Footer column 1
* Footer column 2
* Legal
* Social
Only register locations the design actually benefits from.
Existing source menu structure should be recreated during demo import.
The administrator must then be able to modify it from WordPress.
Mobile navigation must be fully responsive and keyboard accessible.
---
# FOOTER MANAGEMENT
Footer content must not be permanently hardcoded.
Determine which parts should be controlled through:
* Navigation menus
* Site settings
* Customizer
* Site Editor/template parts
* Gutenberg blocks
* theme settings
* widgets
Use the most WordPress-native method suitable for the selected theme architecture.
Footer links must remain editable from WordPress administration.
---
# CONTENT MODELING
Analyze the actual website to identify entities.
Examples:
Real estate:
`property`
`agent`
`agency`
Possible taxonomies:
`property_type`
`property_location`
`property_feature`
News:
Native Posts may be sufficient.
Possible taxonomies:
`topic`
`region`
Reviews:
`review`
`product`
Recipes:
`recipe`
Events:
`event`
`venue`
Directory:
`listing`
`business`
Jobs:
`job`
`company`
Do not use these examples blindly.
Derive the correct model from the supplied ZIP.
---
# CUSTOM POST TYPES
When CPTs are necessary:
* Register proper labels.
* Set appropriate capabilities.
* Configure Gutenberg support.
* Configure REST API support.
* Set suitable archive behavior.
* Configure rewrite slugs.
* Support featured images where relevant.
* Support excerpts where relevant.
* Support revisions.
* Support authors where relevant.
* Create matching archive templates.
* Create matching singular templates.
* Implement matching Gutenberg editing experience.
Do not create CPTs solely because the site has multiple page templates.
---
# TAXONOMIES
"Should I use Taxonomies+term?"
Determine whether Taxonomies+term are appropriate.
Create custom taxonomies where the source content clearly has reusable classifications.
Support:
* Archive pages.
* Pretty URLs.
* Breadcrumb integration where implemented.
* Query filtering.
* Gutenberg/REST integration.
Do not misuse tags as a replacement for structured taxonomy.
---
# ACF / STRUCTURED FIELDS
Use ACF where structured fields materially improve content management.
Prefer block/editor-native controls where they are sufficient.
ACF fields should be used for data such as:
* Price
* Address
* Coordinates
* Bedrooms
* Bathrooms
* Property size
* Event dates
* Rating score
* Recipe preparation time
* Structured contact details
* Structured specifications
* Relationships
* Repeater data
* Source attribution
* Other domain-specific metadata
Store field group definitions inside the theme using local JSON where appropriate:
`acf-json/`
If ACF Pro functionality is genuinely needed, implement compatibility for ACF Pro.
IMPORTANT LICENSING REQUIREMENT:
Do NOT obtain, pirate, reconstruct, or redistribute a proprietary ACF Pro package without authorization.
If an authorized ACF Pro package is included with the supplied files and redistribution is permitted, integrate it according to the supplied licensing arrangement.
Otherwise:
* implement the theme's ACF Pro integration;
* include field definitions;
* provide an admin dependency notice/installer workflow;
* allow the authorized site owner to install/activate their licensed ACF Pro copy.
The theme itself must not silently download proprietary software from unauthorized locations.
---
# SEO
Implement clean technical SEO fundamentals.
Use WordPress-native behavior and remain compatible with major SEO plugins.
Requirements include:
* One logical H1 per primary page context.
* Proper heading hierarchy.
* Semantic HTML.
* Correct canonical-friendly URLs.
* Clean archive structure.
* Correct pagination.
* Proper document titles through WordPress.
* OpenGraph/SEO plugin compatibility.
* Reasonable meta description fallback only if appropriate.
* Schema markup where the site's content type clearly benefits from it.
* Breadcrumb compatibility.
* Proper image alt support.
* No duplicate fake H1 elements for visual styling.
* No hidden keyword content.
Do NOT build a massive SEO plugin into the theme.
Avoid conflicting with Yoast SEO, Rank Math, SEOPress, All in One SEO, or similar plugins.
---
# URL / PERMALINK ARCHITECTURE
Infer the correct permalink structure from the supplied source.
For example, preserve meaningful concepts such as:
`/news/category/article/`
or:
`/properties/city/property-name/`
when technically appropriate.
Use WordPress rewrite APIs rather than hardcoded routing hacks.
Avoid introducing unnecessary URL depth.
Prevent obvious duplicate-content routes.
Flush rewrite rules only when required, never on every request.
---
# DEMO CONTENT IMPORTER — REQUIRED
The WordPress administrator menu for theme setup MUST be named:
`Import`
Create a reliable one-click demo importer.
Its job is to reconstruct the supplied demo site inside WordPress.
It should create/import as appropriate:
* Pages.
* Posts.
* CPT entries.
* Taxonomy terms.
* Categories.
* Tags.
* Featured images.
* Media library images.
* Menus.
* Menu assignments.
* Homepage assignment.
* Posts page assignment.
* Custom fields.
* Theme settings.
* Footer settings.
* Widget/sidebar data where needed.
* Relationships.
* Demo metadata.
* Required options.
The importer must use the supplied HTML/source files as a basis for the demo content.
Convert original HTML content into structured Gutenberg block markup.
Do NOT import every page as a Custom HTML block.
After import, the page editor must expose the actual editable blocks.
The importer should be idempotent where practical.
Running it twice should not generate uncontrollable duplicate content.
Use stable markers/meta keys to identify imported demo records.
Display useful progress/result/error information.
Apply appropriate permissions and nonces.
Only administrators with appropriate capabilities should execute import operations.
---
# SOURCE HTML → GUTENBERG BLOCK CONVERSION
Convert the source theme in place. Do NOT recreate, approximate, modernize, simplify, or "improve" its frontend markup or design.
For every page, section, component, and shared area:
1. Capture its original HTML fragment, CSS selectors, CSS rules, assets, responsive states, and behavior-bearing JavaScript.
2. Treat the original rendered DOM and computed appearance as the visual contract.
3. Map editable content, settings, relationships, and repeated records to Gutenberg block attributes, InnerBlocks, core fields, post meta, or dynamic queries as appropriate.
4. Choose Gutenberg constructs only when their frontend output preserves the required source DOM. Use native blocks where their markup matches; otherwise use composed or custom blocks. Patterns arrange blocks; block styles alter styling only.
5. Implement blocks that emit the original frontend HTML structure. Use a dynamic render callback where WordPress data must populate the preserved structure.
6. Keep original classes, element hierarchy, data attributes, asset references, breakpoints, and CSS cascade intact. Change them only after verifying that WordPress requires incompatible markup and no exact-output block implementation is feasible. Record the constraint, smallest deviation, and source-versus-imported verification.
7. Load the original CSS and required frontend JavaScript. Adapt JavaScript only at its data or initialization boundary; do NOT rewrite working visual behavior without need. Preserve every existing functional variant across pages, components, states, and breakpoints.
8. Build editor controls separately from frontend output. Editor UI MAY differ; saved or rendered frontend markup MUST preserve the source contract.
9. Compare source and WordPress public-frontend renderings at identical viewport sizes and content state. For every template, retain machine-readable evidence: source URL/file, WordPress URL, viewport, screenshots, normalized DOM comparison, and computed-style comparison for layout/typography/color/spacing/visibility. Fix every unapproved difference before delivery.
10. Verify representative interactions against original JavaScript behavior: navigation, menus, tabs, sliders, modals, forms, filtering, and responsive state transitions where present.
11. Verify demo import recreates original composition using real blocks and WordPress records while public frontend retains source output.
A syntax-clean theme, valid block serialization, or populated editor is insufficient. Missing source-vs-WordPress evidence is failure.
Block comments and WordPress metadata MAY differ because they do not render into the frontend DOM.
Repeated visual structures should become:
* patterns,
* block styles,
* reusable block structures,
* custom blocks,
* dynamic queries,
rather than duplicated arbitrary HTML.
Never place a whole page or section inside a Custom HTML block merely to preserve its appearance. Preserve the HTML through proper block save output or server-side rendering while exposing meaningful fields and child content in Gutenberg.
Do NOT replace a page or multi-component section with one monolithic custom or dynamic block. Represent every semantically distinct, independently editable section, component, and content area as its own meaningful block or InnerBlocks composition.
When source content is dynamic or repeated, change its data source to the appropriate WordPress records without changing its visual contract. Keep genuinely static content as editable block content. Example: a source article card becomes a query-backed block whose title, image, excerpt, and URL come from WordPress records while its outer elements, classes, nesting, and styling remain identical to the source card.
DO NOT:
```html
...
```
DO:
```html
...
```
Preserve source HTML even when a cleaner rewrite is possible. Change markup only when required for security or WordPress execution. Preserve rendered appearance and behavior; document and test every changed node. Report pre-existing validity or accessibility defects without silently rewriting them.
---
# THEME PATTERNS
Create useful block patterns for recurring structures discovered in the source.
Examples might include:
* Hero
* Feature grid
* Article hero
* Pricing section
* CTA
* Testimonials
* Team
* Newsletter signup
* FAQ
* Contact section
* Logo wall
* Stats
* Property grid
* Category grid
* Related posts
* Author bio
* Footer CTA
Only create patterns relevant to the current theme.
Patterns should use the same design tokens as the rest of the theme.
---
# FORMS
If the source has forms, determine their purpose.
Use secure WordPress handling.
Requirements:
* Nonces.
* Sanitization.
* Validation.
* Escaping.
* Spam mitigation where practical.
* Accessible labels.
* Proper errors.
* Success states.
* Keyboard accessibility.
Do not hardcode the recipient email address from the demo unless required.
Prefer site admin email or an editable setting.
If email is used, integrate through `wp_mail()`.
Do not expose secret API keys client-side.
---
# SECURITY
Follow WordPress security standards.
Always:
* Sanitize input.
* Validate values.
* Escape output.
* Verify nonces.
* Check capabilities.
* Use `$wpdb->prepare()` if direct SQL is genuinely necessary.
* Avoid arbitrary file execution.
* Avoid unsafe unserialize behavior.
* Prevent CSRF.
* Prevent XSS.
* Prevent obvious path traversal.
* Prevent unrestricted uploads.
* Avoid remote code execution patterns.
* Avoid `eval()`.
* Avoid executing imported HTML or JavaScript as PHP.
Imported demo content must be treated as untrusted input.
---
# PERFORMANCE
Build for good frontend performance.
Requirements include:
* Do not load giant libraries unnecessarily.
* Do not load scripts globally if only one component uses them.
* Use `wp_enqueue_script()` and `wp_enqueue_style()`.
* Add cache-friendly versioning.
* Avoid render-blocking JavaScript where possible.
* Use native lazy-loading appropriately.
* Use responsive WordPress image functions.
* Register useful image sizes.
* Avoid enormous original images where generated sizes are sufficient.
* Avoid unnecessary DOM depth.
* Avoid excessive wrappers.
* Avoid expensive database queries inside loops.
* Avoid repeated uncached queries.
* Avoid N+1 query patterns.
* Use transients/object cache only where justified.
Do not ship Bootstrap, jQuery plugins, sliders, animation libraries, or icon frameworks merely out of habit.
Use native CSS and browser APIs where practical.
---
# JAVASCRIPT
Use JavaScript only when interaction requires it.
Prefer vanilla JavaScript unless a WordPress/editor API requires React.
Frontend JavaScript must:
* Avoid global pollution.
* Fail gracefully.
* Handle multiple instances.
* Support keyboard interaction.
* Respect reduced motion.
* Not produce console errors.
* Not block initial rendering unnecessarily.
---
# CSS ARCHITECTURE
Create maintainable CSS.
Use:
* Design tokens.
* Logical properties where appropriate.
* Mobile-first responsive rules.
* Component boundaries.
* Consistent naming.
* Fluid layouts.
* Shared utility concepts only where genuinely beneficial.
Avoid:
* Hundreds of arbitrary magic numbers.
* Huge specificity wars.
* Repeated `!important`.
* Inline styles generated everywhere.
* Fixed heights for dynamic text containers.
* Random z-index values.
* Excessive absolute positioning.
* Desktop-only assumptions.
Create a controlled z-index scale if the design needs layering.
For example conceptually:
`--z-base`
`--z-dropdown`
`--z-sticky`
`--z-overlay`
`--z-modal`
Do not use random values such as 999, 9999, and 999999 throughout the project.
---
# SPACING SYSTEM
This is especially important.
The final theme must NOT repeat the spacing inconsistencies common in generated websites.
Create a limited responsive spacing scale and use it consistently.
For example conceptually:
XS
SM
MD
LG
XL
2XL
3XL
Map those through `theme.json` and CSS custom properties.
Use those tokens consistently for:
* card padding,
* section padding,
* container gaps,
* button spacing,
* form spacing,
* header spacing,
* footer spacing,
* content spacing.
Do not give every section unrelated padding values.
Allow exceptional values only when visually justified.
---
# CONTAINER SYSTEM
Create deliberate layout containers.
At minimum distinguish where appropriate between:
* Full-width.
* Wide.
* Standard content.
* Narrow reading content.
Do not let every section invent its own width.
Long-form article text should maintain a readable line length.
Large landing-page sections may use wider containers.
---
# TYPOGRAPHY SYSTEM
Infer the type system from the source and normalize it.
Define responsive sizes for:
* Body.
* Small text.
* Eyebrow text.
* H6.
* H5.
* H4.
* H3.
* H2.
* H1.
* Display text where applicable.
Use fluid typography where appropriate.
Do not use arbitrary unrelated font sizes in every component.
Keep comfortable line height.
Long headlines must wrap safely.
---
# WORDPRESS EDITOR EXPERIENCE
The Gutenberg editor is part of the product.
Ensure:
* Editor styles are loaded.
* Widths resemble frontend widths.
* Typography resembles frontend typography.
* Colors match.
* Custom blocks preview correctly.
* Block controls are usable.
* Editors can select nested elements.
* No invisible white-on-white editor text.
* No front-end-only component that becomes impossible to edit.
* No massive opaque shortcode.
The editor should be understandable to a normal WordPress administrator.
---
# ADMIN UX
Keep admin additions clean.
Use the menu name:
`Import`
Do not fill WordPress Admin with unnecessary top-level menu entries.
Put related theme functionality together.
Follow normal WordPress UI conventions.
Avoid creating a proprietary page builder.
The goal is to leverage WordPress, Gutenberg, ACF where appropriate, and standard admin functionality.
---
# FAVICON / SITE ICON
Generate an original favicon/site icon appropriate to the theme branding.
Include suitable source assets.
Support WordPress Site Icon.
Where helpful generate common favicon sizes such as:
* 32×32
* 64×64
* 192×192
* 512×512
* `.ico`
Do not simply reuse a third-party trademark unless the supplied site owns that branding.
---
# TEMPLATE COVERAGE
Create all templates that the inferred website architecture requires.
This may include:
* Home
* Front page
* Blog index
* Page
* Singular
* Single post
* Single CPT
* Archive
* CPT archive
* Category
* Tag
* Custom taxonomy
* Author
* Date
* Search
* Attachment where appropriate
* 404
* Specialized landing templates
* Header
* Footer
* Sidebar
* Search result cards
* Comments where appropriate
Do not create meaningless duplicate templates.
---
# COMMENTS
If the content type supports discussion, implement comments correctly.
If the source clearly does not need comments, do not force them visually.
---
# SEARCH
If search is appropriate, provide a polished WordPress search experience.
Search results should respect relevant post types.
The search UI must be responsive and accessible.
Specialized verticals may require advanced filtering separate from normal WordPress keyword search.
---
# REAL ESTATE / DIRECTORY / DATA-HEAVY THEMES
If the source requires structured filtering, architecture must support it properly.
Do not fake filters with static HTML.
For example, filters may operate on:
* taxonomy terms,
* meta values,
* date ranges,
* locations,
* price,
* attributes,
* relationships.
Use secure query construction.
Do not allow arbitrary query variables to become raw SQL.
---
# NEWS / MAGAZINE THEMES
If the source is news-oriented, account for features such as:
* Featured stories.
* Breaking/trending sections.
* Category hierarchy.
* Authors.
* Publish/update dates.
* Related stories.
* Pagination.
* Editorial metadata.
* Ad positions where present.
* Multiple article card types.
Use dynamic queries rather than hardcoded story cards.
---
# BLOG THEMES
Use WordPress posts naturally.
Do not create a `blog_post` CPT when standard Posts are appropriate.
---
# ECOMMERCE-ORIENTED THEMES
If the source clearly requires WooCommerce, make the theme WooCommerce-compatible.
Do not recreate WooCommerce as a custom theme-level commerce system.
Do not bundle WooCommerce itself.
Provide appropriate dependency/compatibility messaging.
---
# PLUGIN BOUNDARIES
Keep theme functionality and plugin functionality appropriately separated.
For this factory output, functionality required specifically to reproduce and operate the supplied theme may be implemented with the theme where practical.
However, avoid rebuilding massive established plugin ecosystems.
For optional external systems such as:
* WooCommerce
* ACF Pro
* multilingual plugins
* SEO plugins
* form plugins
provide proper compatibility rather than unauthorized copies.
Where a dependency is required, provide a clear admin notice and safe installation path.
---
# INTERNATIONALIZATION
Make the theme translation-ready.
Use a consistent text domain.
Wrap user-facing static strings in WordPress translation functions.
Generate a POT file if practical.
Do not internationalize actual imported demo article/page content as hardcoded strings.
---
# RTL
Where practical, avoid CSS assumptions that make RTL impossible.
Prefer logical CSS properties such as:
* `margin-inline`
* `padding-inline`
* `inset-inline`
* `border-inline`
when appropriate.
If the supplied design is RTL, provide first-class RTL support.
---
# CODE QUALITY
Follow WordPress coding standards where practical.
Use namespaces or consistent prefixes to prevent collisions.
Avoid globally named functions such as:
`setup()`
`save()`
`render()`
Use a unique theme prefix.
Organize code logically.
For example, an appropriate architecture MAY resemble:
`functions.php`
`theme.json`
`style.css`
`assets/`
`inc/`
`templates/`
`parts/`
`patterns/`
`blocks/`
`acf-json/`
`languages/`
but do not force this exact structure if another structure is more appropriate.
---
# CHILD-THEME SAFETY
Avoid architecture that makes reasonable customization unnecessarily difficult.
Use hooks, filters, and template conventions appropriately.
Do not place every behavior into one giant `functions.php`.
---
# DESIGN FIDELITY
The source ZIP remains the visual reference.
Maintain recognizable fidelity to:
* composition,
* hierarchy,
* visual identity,
* imagery,
* section sequence,
* cards,
* typography character,
* colors,
* borders,
* radii,
* shadows,
* interactive states.
However:
DO fix defects from the source if they harm:
* responsiveness,
* accessibility,
* consistency,
* semantic structure,
* WordPress usability,
* maintainability.
Do not faithfully reproduce accidental UI collisions or broken responsive behavior.
---
# VISUAL NORMALIZATION PASS
After implementing the design, perform a separate normalization pass.
Specifically inspect for:
* inconsistent section padding,
* inconsistent card padding,
* inconsistent button heights,
* mismatched border radius,
* inconsistent shadows,
* heading spacing,
* container misalignment,
* inconsistent gutters,
* visually drifting card grids,
* inconsistent icon sizing,
* tiny gaps,
* oversized gaps,
* text touching borders,
* footer spacing inconsistencies,
* header alignment,
* content touching viewport edges,
* floating elements covering content,
* inconsistent mobile spacing.
Fix these through shared tokens whenever possible rather than local patches.
---
# COLLISION / OVERLAP QA
Perform a dedicated collision audit.
Search CSS for:
* `position:absolute`
* `position:fixed`
* negative margins
* transforms
* fixed heights
* fixed widths
* oversized min-width
* high z-index
* nowrap
* overflow hidden
* viewport-sized values
Review whether each occurrence could cause collisions.
Pay particular attention to:
* header,
* mobile navigation,
* hero,
* floating badges,
* overlapping image compositions,
* cards,
* form controls,
* dropdowns,
* sticky sidebars,
* sticky CTAs,
* article metadata,
* tables,
* footer,
* cookie/banner regions if present.
Eliminate fragile layout dependencies.
---
# AUTOMATED VALIDATION
Before packaging the ZIP, perform as many relevant automated checks as are available in the environment.
At minimum validate:
1. PHP syntax.
2. JavaScript syntax/build.
3. JSON syntax.
4. `theme.json`.
5. Block markup.
6. WordPress theme header.
7. Required template availability.
8. Asset references.
9. Missing files.
10. Broken relative paths.
11. Duplicate PHP function names.
12. Obvious undefined variables.
13. Unsafe direct-access PHP files.
14. Translation text-domain consistency.
15. Registered menu locations.
16. Import menu name exactly `Import`.
17. Gutenberg compatibility.
18. No giant page-level Custom HTML blocks.
19. ZIP integrity.
20. Correct ZIP root structure.
If tools are available, additionally run:
* PHPCS with WordPress standards.
* ESLint.
* Stylelint.
* accessibility tests.
* HTML validation.
* Lighthouse.
* Playwright/browser rendering tests.
Fix meaningful failures before packaging.
---
# BROWSER QA WHEN AVAILABLE
If a browser/runtime environment is available, render the theme rather than relying exclusively on code inspection.
Test representative templates at multiple viewport sizes.
Look for actual:
* overlap,
* overflow,
* clipping,
* layout jumps,
* missing images,
* inaccessible navigation,
* broken menus,
* giant whitespace,
* collapsed grids,
* unusable forms.
Do not consider the work finished merely because PHP syntax is valid.
---
# WORDPRESS FUNCTIONAL QA
Where a WordPress test installation can be created, verify:
* Theme activates without fatal errors.
* Import screen loads.
* Demo import completes.
* Homepage is assigned.
* Menus are assigned.
* Media exists.
* Pages appear.
* CPT entries appear.
* Taxonomies appear.
* Gutenberg opens without block validation errors.
* Imported page blocks are editable.
* Frontend renders.
* Archive URLs work.
* CPT URLs work.
* Search works.
* Responsive menu works.
* Forms do not fatal.
* Customizer/Site Editor works where relevant.
Fix failures before delivering.
---
# IMPORTED CONTENT REQUIREMENT
The demo import MUST recreate each supplied source page from its corresponding Gutenberg blocks.
For every imported page:
* Use the source page's original section order, HTML structure, classes, content, media, CSS, and required JavaScript.
* Populate block attributes, InnerBlocks, records, terms, fields, and settings from the source content; do NOT paste the page into one Custom HTML block.
* Render a frontend page visually identical to the original HTML version at matching viewport sizes.
* Preserve the existing functional distinction: editorial content remains block-editable, record collections remain query-driven, structured record data remains field-driven, and global areas remain globally managed.
After demo import, I should be able to navigate to:
Pages → Edit
and visually edit individual page components.
For example, I should be able to click the hero heading and type new text.
I should be able to select a button and edit the button.
I should be able to replace an image.
I should be able to rearrange sections.
I should be able to change block colors and spacing when those controls are enabled.
I should NOT be looking at a giant blob of HTML.
---
# DYNAMIC CONTENT REQUIREMENT
Content which conceptually comes from WordPress records must remain dynamic.
For example:
A category homepage section showing recent technology articles should query Technology posts.
It should not contain five permanently hardcoded article titles copied from the demo.
The importer should create the demo records, while the frontend block/template queries them dynamically.
---
# STATIC VS DYNAMIC DECISION
Use this rule:
If content is unique editorial page content, Gutenberg blocks are appropriate.
If content represents collections of WordPress records, make it query-driven.
If content represents structured attributes of one record, use post meta/ACF or appropriate core fields.
If content represents global site configuration, use global settings/template parts/theme settings.
Do not mix these categories unnecessarily.
---
# NO FAKE EDITABILITY
Do not claim something is editable merely because the administrator can edit its PHP/HTML code.
"Editable" means a normal WordPress administrator can modify it through the WordPress interface.
---
# NO PAGE-BUILDER DEPENDENCY
Do not require Elementor, Divi, WPBakery, Beaver Builder, Oxygen, Bricks, or another proprietary page builder unless the supplied source explicitly depends on it and preserving that system is explicitly necessary.
Default to Gutenberg.
---
# DEFAULT DECISION POLICY
Do not ask me routine architecture questions.
You are responsible for analyzing the source and making competent decisions.
Examples:
Do not ask:
"Should I use CPTs?"
Determine whether CPTs are appropriate.
Do not ask:
"Should the homepage use Gutenberg?"
Yes, unless there is a strong technical reason for a specific dynamic component.
Do not ask:
"What menu locations do you want?"
Infer them from the website.
Do not ask:
"Which colors should I use?"
Extract or infer the design system from the source.
Only ask a question if progress is genuinely impossible without information that cannot be reasonably inferred.
Otherwise make the best professional decision and continue.
---
# DO NOT STOP AT A PLAN
You may internally create an implementation plan.
But after planning, execute it.
The expected workflow is:
INPUT ZIP
→ inspect
→ classify site
→ design WordPress architecture
→ implement theme
→ implement Gutenberg editing
→ implement required structured data
→ implement importer
→ normalize responsive design
→ accessibility pass
→ QA
→ package
→ verify packaged copy
→ RETURN ZIP
The job is not complete before the ZIP exists.
---
# PACKAGE VALIDATION
After producing the ZIP:
Extract the ZIP into a clean temporary folder.
Run validation against the extracted packaged copy, not only the development directory.
This catches packaging mistakes.
Verify that extracting results conceptually in:
`theme-name/style.css`
`theme-name/functions.php`
`theme-name/...`
and NOT:
`some-wrapper/theme-name/...`
and NOT loose files with no root directory.
---
# SCREENSHOT
Include a proper WordPress theme `screenshot.png`.
It should represent the supplied theme.
Use the standard WordPress theme screenshot convention.
---
# THEME METADATA
Create valid `style.css` theme metadata.
Choose a professional theme name based on the supplied project/site.
Do not falsely claim it was produced by WordPress.org.
Use a sensible version such as:
`1.0.0`
Use a unique text domain and code prefix.
---
# README
Include a concise README explaining:
* Installation.
* Demo import.
* Editing the homepage.
* Editing menus.
* Editing footer.
* Global style controls.
* Custom Post Types if present.
* Taxonomies if present.
* ACF dependency if present.
* Required/recommended plugins.
* Important configuration notes.
---
# COMPLETION REPORT
When finished, give me a concise report containing:
Theme name.
Architecture chosen.
Important WordPress content types created.
Important taxonomies created.
Custom Gutenberg blocks created.
Menu locations created.
Importer status.
ACF integration status.
Responsive/accessibility QA status.
Validation performed.
ZIP size.
SHA-256 checksum.
Then provide the ZIP download link prominently.
Do not dump all generated source code into the chat unless specifically requested.
---
# ABSOLUTE FAILURE CONDITIONS
The task is NOT successfully completed if any of these are true:
* No ZIP was generated.
* The ZIP cannot be installed as a WordPress theme.
* Any source component was visually approximated, redesigned, or rebuilt with replacement markup.
* Any behavior/styling-relevant source tag, hierarchy, class, ID, `data-*` attribute, CSS selector, breakpoint, asset, or JavaScript hook was removed or replaced without a concrete WordPress/security necessity recorded in the source-preservation manifest.
* Original production CSS/JavaScript/assets were omitted and recreated instead of reused.
* A block emits generic Gutenberg layout markup where source-specific markup is required.
* Source-to-block manifest is missing, incomplete, or disagrees with frontend output.
* Same-viewport source-vs-WordPress screenshots show material visual divergence.
* Automated DOM comparison shows unapproved structural/attribute divergence.
* Computed-style comparison shows material divergence in layout, typography, color, spacing, visibility, or responsive state.
* The imported demo does not reproduce the original page composition and content at the public frontend URL.
* The source website was merely inserted as hardcoded HTML.
* Gutenberg pages consist mainly of Custom HTML blocks.
* Ordinary page content requires editing PHP.
* Menus are hardcoded.
* Demo menu items cannot be edited through WordPress.
* Footer links are permanently hardcoded.
* The homepage cannot be visually edited.
* Required CPT content is represented as static HTML.
* Dynamic listings are hardcoded demo content.
* Major UI elements overlap at normal viewport widths.
* Mobile layout has horizontal overflow.
* Spacing consists of arbitrary unrelated values throughout CSS.
* Keyboard navigation is unusable.
* PHP has syntax errors.
* Block markup produces widespread Gutenberg validation errors.
* The Import screen is not named exactly `Import`.
* The packaged ZIP has the wrong directory structure.
* Proprietary plugins are redistributed without authorization.
---
# PRIORITY ORDER
When requirements conflict, use this priority:
1. Source frontend contract: original rendered DOM hierarchy, tags, classes, IDs, data attributes, CSS cascade, assets, JavaScript behavior, responsive states, and visual output.
2. Functional WordPress correctness and security.
3. Editable Gutenberg experience implemented inside the preserved frontend contract.
4. Content-model correctness.
5. Accessibility, except where changing frontend output would violate priority 1; record such conflicts rather than silently redesigning.
6. Maintainability.
7. Performance.
“Incidental implementation details” NEVER includes frontend markup, selectors, CSS, assets, behavior hooks, breakpoints, or interaction behavior. Those are contractual source inputs. If WordPress correctness requires a frontend deviation, make the smallest possible change, record it in the source-preservation manifest, and prove unchanged visual and behavioral output. If exact preservation and a required function cannot coexist, report a blocker; NEVER substitute an approximation.
---
# FACTORY MINDSET
This is one theme in a factory of approximately 50 unrelated WordPress themes.
Therefore do not make assumptions based on previous themes.
Every attached ZIP is a new project.
Analyze every project independently.
A real-estate source should produce a real-estate-appropriate architecture.
A news source should produce a news-appropriate architecture.
A blog should remain simple if it only needs standard WordPress posts.
A directory should receive directory-specific structured content.
A recipe site should receive recipe-specific structured fields and schema.
The architecture must follow the website, not the other way around.
At the same time, maintain consistent engineering quality across every generated theme:
* Gutenberg-first editing.
* coherent design tokens.
* responsive layouts.
* no collisions.
* accessibility.
* security.
* maintainability.
* robust demo importing.
* proper WordPress abstractions.
* validated installable ZIP.
Now inspect the attached ZIP, build the complete WordPress theme, validate the packaged output, and return the final installable ZIP.