Files

IGNY8 VPS (Salman) 128b186865 temproary docs uplaoded

2026-03-23 09:02:49 +00:00

46 KiB

Raw Blame History

[THEME NAME] — Complete Build Plan

By: Alorig Systems
For: AI Agent (Claude Code / Opus 4.6 in VSCode)
Version: 1.0
Date: March 2026
Status: Reference Document for Development

Executive Summary

A premium WordPress theme that provides the physical infrastructure for SAG-optimized sites. It registers all the custom post types, custom taxonomies, meta fields, and template systems needed to display a fully structured semantic site — whether that structure is built manually or pushed from IGNY8.

The theme handles presentation, structure, and site infrastructure (performance, forms, security). The IGNY8 plugin handles intelligence, content, SEO, social, and analytics.

Two deliverables:

Theme — CPTs, taxonomies, templates, block patterns, landing page builder, design system, WooCommerce templates
Companion Plugin (Toolkit) — Performance/caching, forms, security, SMTP, WooCommerce enhancements

Distribution: Free version on WordPress.org (limited patterns + features). Premium version sold on Alorig site (full pattern library, all toolkit modules, priority support).

Part 1: What This Theme Does (and Doesn't Do)

1.1 Theme Owns (Presentation + Structure)

Responsibility	Details
Custom Post Types	Services, Portfolio/Case Studies, Landing Pages, Team Members, Testimonials, FAQs, Documentation
Custom Taxonomies	Service categories, service attributes (area, type, property type), portfolio categories, documentation categories — all SAG-compatible
SAG Structural Templates	Term landing pages, cluster hub pages, attribute archive pages — all designed to display rich content, not just post lists
Landing Page Builder	Section-based CPT with pre-designed section templates + presets
Block Patterns	50+ patterns organized by type (heroes, features, social proof, CTAs, etc.)
FSE Templates	Complete template sets for 5 site types (blog, SaaS, eCommerce, corporate, portfolio)
WooCommerce Templates	Custom shop, product, cart, checkout templates that respect SAG structure
Design System	theme.json tokens, custom utility CSS, typography, spacing scale
Interlinking Display	Renders related content sections, cluster navigation, term relationships — reading data from IGNY8 plugin or manual configuration
WordPress Cleanup	Remove bloat, conditional asset loading, zero jQuery on frontend

1.2 IGNY8 Plugin Owns (Intelligence + Marketing)

The theme does NOT include any of these — they live in the IGNY8 plugin:

SEO meta tags, title tags, canonical, robots
Schema / JSON-LD structured data
XML sitemaps
Redirects + 404 monitoring
OG tags + social meta
Share buttons + social posting
Analytics (GA, GTM, pixels)
Google Search Console integration
Content analysis + scoring
Internal link calculation + suggestions
Site intelligence / audit
Content sync from IGNY8 platform
SAG blueprint sync + taxonomy creation logic

1.3 Toolkit Plugin Owns (Site Infrastructure)

Page caching + HTML optimization
CSS/JS minification + combination
Image optimization + WebP conversion
Critical CSS generation
Contact forms + submission handling
Security hardening + firewall
SMTP mail handling
WooCommerce enhancements (quick view, wishlist, ajax cart, filters)

1.4 How They Work Together

┌─────────────────────────────────────────────────────────────────┐
│                         THEME                                    │
│  Registers CPTs + Taxonomies + Templates + Design System         │
│  Displays everything: pages, terms, clusters, products,          │
│  services, landing pages, interlinking sections                  │
│                                                                  │
│  Reads from:                                                     │
│  ├── IGNY8 Plugin (SEO data, related links, cluster nav,         │
│  │   term content, breadcrumbs, share buttons)                   │
│  ├── Toolkit Plugin (cached pages, form shortcodes)              │
│  └── WordPress core (menus, widgets, customizer)                 │
│                                                                  │
│  Works WITHOUT either plugin (graceful degradation)              │
└─────────────────────────────────────────────────────────────────┘

┌──────────────────────────┐  ┌──────────────────────────────────┐
│     IGNY8 PLUGIN         │  │     TOOLKIT PLUGIN               │
│  SEO, Schema, Social,    │  │  Performance, Forms,             │
│  Analytics, GSC, Linking, │  │  Security, SMTP,                │
│  Content Sync, SAG       │  │  WooCommerce Enhancements        │
│  Intelligence            │  │                                  │
│                          │  │                                  │
│  Works with ANY theme    │  │  Works with ANY theme            │
│  Enhanced with companion │  │  Enhanced with companion         │
└──────────────────────────┘  └──────────────────────────────────┘

Graceful degradation: Theme checks function_exists('igny8') before reading plugin data. If IGNY8 plugin is not installed, interlinking sections don't render, breadcrumbs fall back to theme's own simple breadcrumbs, term pages show WordPress default content. Everything still works — just without the intelligence layer.

Part 2: SAG Structural Support

This is the core differentiator. The theme physically implements the structures that SAG requires in WordPress.

2.1 Custom Post Types

CPT	Slug	Purpose	SAG Role
Services	`service`	Individual service pages	Maps to SAG service clusters. Each service belongs to service categories + service attributes.
Landing Pages	`landing_page`	Section-based marketing pages	Cluster hub pages, campaign pages, any freeform landing page
Portfolio	`portfolio`	Case studies, projects	Supports attribute-based filtering (industry, service type, etc.)
Team Members	`team_member`	Staff/team profiles	Used in team sections and about pages
Testimonials	`testimonial`	Client testimonials	Used in social proof sections across site
FAQs	`faq`	Frequently asked questions	Maps to clusters/terms, generates FAQPage schema (via IGNY8 plugin)
Documentation	`documentation`	Knowledge base / docs	SaaS sites: organized by doc categories

CPT Registration Details:

service
  - Public: true
  - Has archive: true (services listing page)
  - Supports: title, editor, thumbnail, excerpt, revisions, page-attributes
  - Menu icon: dashicons-admin-tools
  - Rewrite: /services/%service_category%/%postname%/
  - Taxonomies: service_category, service_area, service_attribute, cluster

landing_page
  - Public: true
  - Has archive: false
  - Supports: title, thumbnail, excerpt, revisions
  - Does NOT support: editor (replaced by section meta box)
  - Menu icon: dashicons-layout
  - Rewrite: /l/%postname%/ (short URLs for campaigns) or /%postname%/ (flexible)

portfolio
  - Public: true
  - Has archive: true
  - Supports: title, editor, thumbnail, excerpt, revisions
  - Menu icon: dashicons-portfolio
  - Rewrite: /portfolio/%portfolio_category%/%postname%/
  - Taxonomies: portfolio_category, portfolio_tag, service_category (shared)

team_member
  - Public: true
  - Has archive: true (team page)
  - Supports: title, editor, thumbnail
  - Menu icon: dashicons-groups
  - Rewrite: /team/%postname%/

testimonial
  - Public: false (displayed via blocks/shortcodes, not individual pages)
  - Supports: title, editor, thumbnail
  - Menu icon: dashicons-format-quote

faq
  - Public: true
  - Has archive: true (FAQ page)
  - Supports: title, editor
  - Menu icon: dashicons-editor-help
  - Taxonomies: faq_category, cluster
  - Rewrite: /faq/%faq_category%/%postname%/

documentation
  - Public: true
  - Has archive: true
  - Supports: title, editor, thumbnail, page-attributes (for ordering)
  - Hierarchical: true (parent/child docs)
  - Menu icon: dashicons-book
  - Rewrite: /docs/%doc_category%/%postname%/
  - Taxonomies: doc_category

2.2 Custom Taxonomies

These taxonomies directly map to SAG dimensional axes. When IGNY8 plugin is connected, it populates these taxonomies with SAG attribute values. When used standalone, users create terms manually.

Taxonomy	Slug	For CPTs	Hierarchical	SAG Mapping
Service Category	`service_category`	service, portfolio	Yes	Primary attribute (e.g., "Service Type": Emergency, Drain Cleaning, etc.)
Service Area	`service_area`	service	Yes	Tertiary attribute (geographic: user-populated per location)
Service Attribute	`service_attribute`	service	No	Secondary attributes (e.g., "Property Type": Residential, Commercial; "Urgency": Emergency, Same-Day)
Portfolio Category	`portfolio_category`	portfolio	Yes	Groups projects by type
Portfolio Tag	`portfolio_tag`	portfolio	No	Descriptive tags for filtering
FAQ Category	`faq_category`	faq	Yes	Groups FAQs by topic (maps to clusters)
Doc Category	`doc_category`	documentation	Yes	Documentation sections
Content Cluster	`cluster`	post, service, faq, page	No	SAG cluster assignment. Each post/service/FAQ maps to a cluster. This is the key taxonomy that ties content to the SAG grid.
Topic Tag	`topic_tag`	post, service, faq, documentation	No	Granular topical tags beyond clusters

WooCommerce Taxonomies (when Woo is active):

The theme does NOT register WooCommerce's built-in taxonomies (product_cat, product_tag, pa_*). Instead it:

Respects and templates all WooCommerce taxonomies natively
Provides rich term archive templates for product_cat, product_tag
Provides attribute archive templates for all pa_* taxonomies
Registers the cluster taxonomy for the product post type too — so products can be cluster-mapped

2.3 Meta Fields Per CPT

Service Meta Fields:

_theme_service_price_range        -- Text: e.g., "$150 - $500"
_theme_service_duration           -- Text: e.g., "2-4 hours"
_theme_service_process_steps      -- JSON array: [{step_number, title, description, icon}]
_theme_service_outcomes           -- JSON array: [{title, description}]
_theme_service_faqs               -- JSON array: [{question, answer}] (also rendered as FAQPage schema via IGNY8)
_theme_service_cta_text           -- Text: custom CTA button text
_theme_service_cta_url            -- URL: custom CTA destination
_theme_service_areas_served       -- JSON array: geographic areas (populates service_area terms)
_theme_service_gallery            -- JSON array: attachment IDs
_theme_service_related_services   -- JSON array: post IDs (manual override; IGNY8 auto-calculates if connected)

Portfolio Meta Fields:

_theme_portfolio_client           -- Text: client name
_theme_portfolio_date             -- Date: project completion date
_theme_portfolio_url              -- URL: live project link
_theme_portfolio_results          -- JSON array: [{metric, value, description}] e.g., "50% increase in traffic"
_theme_portfolio_technologies     -- Text: comma-separated tech/tools used
_theme_portfolio_testimonial_id   -- Int: linked testimonial post ID
_theme_portfolio_gallery          -- JSON array: attachment IDs
_theme_portfolio_before_after     -- JSON: {before_image, after_image}

Team Member Meta Fields:

_theme_team_position              -- Text: job title
_theme_team_email                 -- Email
_theme_team_phone                 -- Text
_theme_team_social                -- JSON: {linkedin, twitter, facebook, website}
_theme_team_order                 -- Int: display order
_theme_team_department            -- Text: department/group

Testimonial Meta Fields:

_theme_testimonial_author_name    -- Text: person's name
_theme_testimonial_author_title   -- Text: job title
_theme_testimonial_company        -- Text: company name
_theme_testimonial_rating         -- Int: 1-5 stars
_theme_testimonial_image          -- Attachment ID: author photo
_theme_testimonial_featured       -- Boolean: show in featured sections
_theme_testimonial_service_id     -- Int: linked service post ID
_theme_testimonial_product_id     -- Int: linked product ID (WooCommerce)

FAQ Meta Fields:

(FAQs use title = question, editor = answer. Additional meta:)
_theme_faq_order                  -- Int: display order within category
_theme_faq_schema_enabled         -- Boolean: include in FAQPage schema

Documentation Meta Fields:

_theme_doc_sidebar_enabled        -- Boolean: show doc sidebar navigation
_theme_doc_toc_enabled            -- Boolean: show table of contents
_theme_doc_last_reviewed          -- Date: content last reviewed date
_theme_doc_related_docs           -- JSON array: related doc post IDs

2.4 Term Landing Page Templates

Every taxonomy term archive in this theme renders as a rich landing page, not a simple post list. This is the SAG architecture in action.

Template hierarchy for term archives:

taxonomy-service_category-{slug}.html    → Specific service category
taxonomy-service_category.html           → All service categories
taxonomy-service_area.html               → Service area archives
taxonomy-service_attribute.html          → Service attribute archives
taxonomy-cluster.html                    → Cluster hub pages
taxonomy-faq_category.html               → FAQ category pages
taxonomy-product_cat.html                → WooCommerce product categories
taxonomy-product_tag.html                → WooCommerce product tags
taxonomy-pa_{attribute}.html             → WooCommerce product attributes
archive-service.html                     → Services listing
archive-portfolio.html                   → Portfolio listing
archive-faq.html                         → FAQ listing
archive-documentation.html               → Docs listing

Term Landing Page Structure (universal):

Every term archive template follows this section order:

1. TERM HERO
   - Term name as H1
   - Term description (rich content from _igny8_term_content if IGNY8 active,
     otherwise standard WordPress term description)
   - Breadcrumbs
   - Post count

2. KEY SUBTOPICS (if child terms exist)
   - Grid of child term cards
   - Each card: term name, description excerpt, post count, link
   - This creates the dimensional navigation (e.g., "Emergency Plumbing" term
     page shows child terms like "Burst Pipe Emergency", "Frozen Pipe Emergency")

3. CONTENT GRID
   - Posts/services/products belonging to this term
   - Configurable layout: grid (2/3/4 col), list
   - Filterable by secondary taxonomy if applicable
   - Pagination

4. RELATED TERMS (sibling terms in same taxonomy)
   - "Related [Taxonomy Label]" section
   - If IGNY8 active: reads _igny8_term_related_terms for intelligent suggestions
   - If standalone: shows sibling terms (same parent)

5. CLUSTER CROSS-LINKS (if IGNY8 active)
   - "Related Topics" section
   - Links to other clusters that share dimensional axes
   - E.g., "Dog x Joint Health" cluster page links to "Dog x Senior Care" and "Cat x Joint Health"

6. FAQ SECTION (if term has FAQs)
   - If IGNY8 active: reads _igny8_term_faq
   - If standalone: shows FAQ posts in matching faq_category
   - Accordion display

7. CTA / CONVERSION
   - Configurable per term or global default
   - "Get a free quote", "Browse products", "Contact us" etc.

Cluster Hub Page Template (taxonomy-cluster.html):

Cluster pages are special — they're the hub of a SAG cluster. The template:

1. CLUSTER HERO
   - Cluster name as H1
   - Cluster description (rich content)
   - Breadcrumbs showing dimensional path
   - Total content count in cluster

2. HUB CONTENT
   - The main cluster hub article content
   - This is the comprehensive "pillar" page for the cluster
   - Content from _igny8_term_content or editor

3. SUPPORTING CONTENT
   - All posts/services/products mapped to this cluster
   - Organized by content type: posts first, then services, then products
   - Each with excerpt, featured image, link

4. ATTRIBUTE NAVIGATION
   - "Browse by [Attribute]" sections
   - Shows which attribute values this cluster intersects
   - E.g., for "Dog Anxiety Relief Products" cluster:
     "Pet Type: Dog" | "Pet Need: Anxiety Relief" | "Product Category: Health"

5. RELATED CLUSTERS
   - Other clusters sharing one or more attribute values
   - Intelligent cross-linking that builds the SAG web

6. FAQ
   - Cluster-specific FAQs

7. CTA

2.5 Interlinking Display Components

The theme provides template parts that render interlinking sections. These read data from IGNY8 plugin when available, or from manual post meta when not.

Component: Related Content Block

Location: After post/service/product content
Data source: _igny8_related_links post meta (array of {post_id, anchor_text, priority})
Fallback: WordPress related posts by shared categories/tags
Display: 3-4 cards with featured image, title, excerpt
Template part: parts/related-content.html

Component: Cluster Navigation

Location: Sidebar or after content
Data source: IGNY8 plugin API → igny8()->linking->get_cluster_navigation($post_id)
Fallback: Posts in same cluster taxonomy term
Display: "More in [Cluster Name]" with linked list
Template part: parts/cluster-navigation.html

Component: Attribute Browse

Location: Term archive pages, sidebar
Data source: Custom taxonomy terms for current context
Display: Pills/tags showing browsable attribute values
Template part: parts/attribute-browse.html
E.g., on a service page: "Service Type: Emergency" | "Property: Residential" | "Area: Downtown"

Component: Breadcrumb Trail

Location: Below header on all pages
Data source: IGNY8 plugin breadcrumbs (if active), else theme's own breadcrumbs
Display: Home > [Taxonomy] > [Parent Term] > [Child Term] > [Post Title]
Template part: parts/breadcrumbs.html
SAG aware: Breadcrumbs follow dimensional path, not just hierarchy

Component: Term Quick Links

Location: Single post/service sidebar or footer
Data source: All terms assigned to current post across all taxonomies
Display: Grouped by taxonomy label: "Service Type: Emergency | Drain Cleaning"
                                     "Property Type: Residential"
                                     "Cluster: Emergency Drain Services"
Template part: parts/term-quick-links.html

Component: Child Term Grid

Location: Term archive pages (when term has children)
Data source: get_term_children() + term meta
Display: Card grid with term image, name, description, post count
Template part: parts/child-term-grid.html

Part 3: Landing Page System

3.1 Architecture

Identical to previous plan — section-based CPT with repeater meta box. No changes needed here since landing pages are theme-owned.

CPT: landing_page Meta key: _theme_landing_sections (serialized array of section objects)

3.2 Section Types (15 total)

#	Section Type	Key Fields
1	hero	headline, subheadline, cta_text, cta_url, cta2_text, cta2_url, background_type (color/image/gradient/video), background_value, text_alignment, overlay_opacity
2	features-grid	section_title, section_subtitle, columns (2/3/4), items[] (icon, title, description, link)
3	how-it-works	section_title, section_subtitle, steps[] (number, title, description, icon)
4	social-proof	section_title, layout (grid/slider/single), testimonials[] (quote, name, title, image, company, rating)
5	pricing	section_title, section_subtitle, billing_toggle, plans[] (name, monthly_price, annual_price, description, features[], cta_text, cta_url, is_featured, badge)
6	faq	section_title, section_subtitle, items[] (question, answer), schema_enabled
7	cta-band	headline, subheadline, cta_text, cta_url, background_color, text_color
8	content-block	section_title, content (wp_editor), image, image_position (left/right/top), background
9	stats-counter	section_title, stats[] (number, suffix, label), background, animate
10	team	section_title, section_subtitle, members[] (name, title, bio, image, social_links) OR pull from team_member CPT
11	portfolio-grid	section_title, columns, items[] (title, category, image, link, description) OR pull from portfolio CPT
12	contact-form	section_title, section_subtitle, form_shortcode, show_map, address, phone, email
13	video-embed	section_title, video_url, poster_image, autoplay, full_width
14	logo-bar	section_title, logos[] (image, alt, link), style (grid/scroll)
15	comparison-table	section_title, columns[] (heading), rows[] (label, values[]), highlight_column

3.3 Landing Page Presets

Preset	Sections in Order
SaaS Product	hero → logo-bar → features-grid → how-it-works → social-proof → pricing → faq → cta-band
Service Business	hero → features-grid → content-block → stats-counter → social-proof → team → contact-form → cta-band
Product Launch	hero → content-block → features-grid → video-embed → social-proof → pricing → faq → cta-band
Lead Generation	hero → features-grid → social-proof → cta-band
Portfolio / Agency	hero → portfolio-grid → how-it-works → social-proof → stats-counter → contact-form
Event / Webinar	hero → content-block → features-grid → social-proof → faq → cta-band
Cluster Hub	hero → content-block → features-grid → faq → cta-band
Term Landing	hero → content-block → features-grid → social-proof → faq → cta-band

The last two presets are specifically for when IGNY8 generates hub/term content — the content gets pasted into the section fields for immediate designed output.

Part 4: Theme File Structure

theme-name/
├── style.css
├── theme.json
├── functions.php
├── screenshot.png
│
├── assets/
│   ├── css/
│   │   ├── base.css                   # Reset, typography, utilities (~25KB)
│   │   ├── blocks.css                 # Block pattern styles
│   │   ├── components.css             # Shared components (cards, buttons, badges, etc.)
│   │   ├── landing-sections.css       # Landing page section styles
│   │   ├── term-pages.css             # Term archive / landing page styles
│   │   ├── woocommerce.css            # WooCommerce overrides (conditional)
│   │   └── admin.css                  # Admin-only styles
│   ├── js/
│   │   ├── app.js                     # Core frontend (~8KB)
│   │   ├── navigation.js              # Mobile menu, dropdowns
│   │   ├── scroll-effects.js          # Sticky header, smooth scroll, back-to-top
│   │   ├── counter-animation.js       # Stats counter animation (conditional)
│   │   ├── accordion.js               # FAQ accordion (conditional)
│   │   ├── landing-page-admin.js      # Section builder admin UI
│   │   └── meta-box-admin.js          # CPT meta box admin UI
│   ├── images/
│   │   └── placeholder.svg
│   └── fonts/
│       ├── inter-400.woff2
│       ├── inter-500.woff2
│       ├── inter-600.woff2
│       └── inter-700.woff2
│
├── inc/
│   ├── setup.php                      # Theme supports, menus, sidebars, image sizes
│   ├── cleanup.php                    # Remove WP bloat
│   ├── enqueue.php                    # Conditional asset loading
│   ├── template-tags.php              # Template helper functions
│   ├── breadcrumbs.php                # Fallback breadcrumbs (when IGNY8 not active)
│   ├── walkers.php                    # Custom menu walkers
│   ├── customizer.php                 # Theme customizer settings
│   ├── theme-bridge.php               # IGNY8 plugin detection + data reading
│   │
│   ├── cpt/                           # Custom Post Types
│   │   ├── register.php               # All CPT registrations
│   │   ├── service.php                # Service CPT specifics + meta boxes
│   │   ├── landing-page.php           # Landing page CPT specifics
│   │   ├── portfolio.php              # Portfolio CPT + meta boxes
│   │   ├── team-member.php            # Team member CPT + meta boxes
│   │   ├── testimonial.php            # Testimonial CPT + meta boxes
│   │   ├── faq.php                    # FAQ CPT + meta boxes
│   │   └── documentation.php          # Documentation CPT + meta boxes
│   │
│   ├── taxonomies/                    # Custom Taxonomies
│   │   ├── register.php               # All taxonomy registrations
│   │   ├── service-category.php       # Service category specifics
│   │   ├── service-area.php           # Service area specifics
│   │   ├── service-attribute.php      # Service attribute specifics
│   │   ├── cluster.php                # Content cluster taxonomy
│   │   ├── portfolio-category.php     # Portfolio category
│   │   ├── faq-category.php           # FAQ category
│   │   └── doc-category.php           # Documentation category
│   │
│   ├── meta-fields/                   # Meta box definitions
│   │   ├── class-meta-box-base.php    # Base meta box class
│   │   ├── service-meta.php           # Service meta fields
│   │   ├── portfolio-meta.php         # Portfolio meta fields
│   │   ├── team-meta.php              # Team member meta fields
│   │   ├── testimonial-meta.php       # Testimonial meta fields
│   │   ├── faq-meta.php               # FAQ meta fields
│   │   └── doc-meta.php               # Documentation meta fields
│   │
│   ├── landing-pages/                 # Landing page system
│   │   ├── register-cpt.php           # (delegated from cpt/landing-page.php)
│   │   ├── meta-boxes.php             # Section repeater meta box
│   │   ├── presets.php                # Pre-built page layouts
│   │   ├── render.php                 # Frontend section renderer
│   │   └── sections/                  # Individual section templates
│   │       ├── hero.php
│   │       ├── features-grid.php
│   │       ├── how-it-works.php
│   │       ├── social-proof.php
│   │       ├── pricing.php
│   │       ├── faq.php
│   │       ├── cta-band.php
│   │       ├── content-block.php
│   │       ├── stats-counter.php
│   │       ├── team.php
│   │       ├── portfolio-grid.php
│   │       ├── contact-form.php
│   │       ├── video-embed.php
│   │       ├── logo-bar.php
│   │       └── comparison-table.php
│   │
│   ├── interlinking/                  # Interlinking display components
│   │   ├── related-content.php        # Related content block (reads IGNY8 data)
│   │   ├── cluster-navigation.php     # "More in this cluster" block
│   │   ├── attribute-browse.php       # Attribute pills/tag navigation
│   │   ├── term-quick-links.php       # Term assignments display
│   │   └── child-term-grid.php        # Child term card grid
│   │
│   ├── blocks/                        # Custom Gutenberg blocks
│   │   ├── register.php
│   │   ├── pricing-table/
│   │   ├── feature-grid/
│   │   ├── testimonial-slider/
│   │   ├── stats-counter/
│   │   ├── team-grid/
│   │   ├── faq-accordion/
│   │   ├── cta-banner/
│   │   ├── logo-carousel/
│   │   ├── comparison-table/
│   │   ├── icon-box/
│   │   ├── service-grid/              # Pulls from service CPT
│   │   ├── portfolio-showcase/        # Pulls from portfolio CPT
│   │   └── doc-sidebar/               # Documentation navigation
│   │
│   └── patterns/                      # Block patterns
│       ├── register.php
│       ├── heroes/
│       │   ├── hero-centered.php
│       │   ├── hero-split.php
│       │   ├── hero-video-bg.php
│       │   └── hero-slider.php
│       ├── content/
│       │   ├── features-3col.php
│       │   ├── features-alternating.php
│       │   ├── how-it-works.php
│       │   └── benefits-icons.php
│       ├── social-proof/
│       │   ├── testimonials-grid.php
│       │   ├── testimonials-slider.php
│       │   ├── logo-bar.php
│       │   └── stats-row.php
│       ├── conversion/
│       │   ├── cta-simple.php
│       │   ├── cta-with-form.php
│       │   ├── pricing-section.php
│       │   └── newsletter-signup.php
│       ├── services/                  # Service-specific patterns
│       │   ├── service-cards.php
│       │   ├── service-list.php
│       │   └── service-with-sidebar.php
│       ├── portfolio/
│       │   ├── portfolio-grid.php
│       │   ├── portfolio-masonry.php
│       │   └── case-study-layout.php
│       └── footers/
│           ├── footer-4col.php
│           ├── footer-centered.php
│           └── footer-minimal.php
│
├── templates/                         # FSE templates
│   ├── index.html
│   ├── home.html
│   ├── single.html                    # Single post
│   ├── single-service.html            # Single service
│   ├── single-portfolio.html          # Single portfolio item
│   ├── single-landing_page.html       # Landing page (section renderer)
│   ├── single-documentation.html      # Single doc (with sidebar nav)
│   ├── page.html
│   ├── archive.html                   # Default archive
│   ├── archive-service.html           # Services listing
│   ├── archive-portfolio.html         # Portfolio listing
│   ├── archive-faq.html               # FAQ listing
│   ├── archive-documentation.html     # Docs home
│   ├── taxonomy-service_category.html # Service category term page
│   ├── taxonomy-service_area.html     # Service area term page
│   ├── taxonomy-service_attribute.html # Service attribute term page
│   ├── taxonomy-cluster.html          # Cluster hub page
│   ├── taxonomy-faq_category.html     # FAQ category page
│   ├── taxonomy-product_cat.html      # WooCommerce product category (rich landing)
│   ├── taxonomy-product_tag.html      # WooCommerce product tag
│   ├── search.html
│   ├── 404.html
│   │
│   ├── starter-blog/
│   │   ├── front-page.html
│   │   ├── single.html
│   │   └── archive.html
│   ├── starter-saas/
│   │   ├── front-page.html
│   │   ├── page-features.html
│   │   ├── page-pricing.html
│   │   └── page-docs.html
│   ├── starter-corporate/
│   │   ├── front-page.html
│   │   ├── page-about.html
│   │   ├── page-services.html
│   │   └── page-contact.html
│   ├── starter-ecommerce/
│   │   ├── front-page.html
│   │   ├── archive-product.html
│   │   └── single-product.html
│   └── starter-portfolio/
│       ├── front-page.html
│       ├── archive-portfolio.html
│       └── single-portfolio.html
│
├── parts/                             # FSE template parts
│   ├── header.html
│   ├── header-transparent.html
│   ├── header-minimal.html
│   ├── footer.html
│   ├── footer-minimal.html
│   ├── sidebar.html
│   ├── sidebar-docs.html              # Documentation sidebar navigation
│   ├── post-meta.html
│   ├── author-box.html
│   ├── related-content.html           # Related content (reads IGNY8 data)
│   ├── cluster-navigation.html        # Cluster siblings
│   ├── attribute-browse.html          # Attribute term pills
│   ├── term-quick-links.html          # Assigned terms display
│   ├── child-term-grid.html           # Child term cards
│   ├── breadcrumbs.html               # Breadcrumbs (IGNY8 or fallback)
│   ├── term-hero.html                 # Term archive hero section
│   ├── term-content.html              # Term rich content section
│   ├── term-faq.html                  # Term FAQ section
│   ├── comments.html
│   └── pagination.html
│
└── woocommerce/                       # WooCommerce template overrides
    ├── archive-product.php            # Shop page (SAG-structured)
    ├── single-product.php             # Product page (enhanced)
    ├── taxonomy-product_cat.php       # Product category (rich landing)
    ├── content-product.php            # Product card in archives
    ├── cart/
    ├── checkout/
    └── myaccount/

Part 5: Toolkit Plugin (Companion)

5.1 Scope

Only site infrastructure — no SEO, no social, no analytics (those are in IGNY8 plugin).

Module	Purpose	Replaces
Performance	Page cache, asset optimization, image optimization, critical CSS, HTML minification, preload/prefetch	WP Rocket, LiteSpeed Cache, Smush
Forms	Form builder, submissions, notifications, anti-spam	Contact Form 7, Gravity Forms
Security	Login protection, firewall, hardening, security headers, audit log	Wordfence, Sucuri
SMTP	Mail delivery override, email log, test email	WP Mail SMTP
WooCommerce	Quick view, wishlist, AJAX cart, product filters, enhanced gallery	5-6 separate Woo plugins

5.2 Plugin File Structure

theme-name-toolkit/
├── theme-name-toolkit.php
├── readme.txt
│
├── includes/
│   ├── class-toolkit.php              # Main class
│   ├── class-module-manager.php       # Module toggle system
│   │
│   ├── modules/
│   │   ├── performance/
│   │   │   ├── class-performance-module.php
│   │   │   ├── class-page-cache.php
│   │   │   ├── class-asset-optimizer.php
│   │   │   ├── class-image-optimizer.php
│   │   │   ├── class-critical-css.php
│   │   │   ├── class-html-minifier.php
│   │   │   ├── class-browser-cache.php
│   │   │   ├── class-preload.php
│   │   │   └── class-database-optimizer.php
│   │   │
│   │   ├── forms/
│   │   │   ├── class-forms-module.php
│   │   │   ├── class-form-builder.php
│   │   │   ├── class-form-renderer.php
│   │   │   ├── class-form-processor.php
│   │   │   ├── class-form-notifications.php
│   │   │   ├── class-form-entries.php
│   │   │   └── class-form-antispam.php
│   │   │
│   │   ├── security/
│   │   │   ├── class-security-module.php
│   │   │   ├── class-login-protection.php
│   │   │   ├── class-firewall.php
│   │   │   ├── class-hardening.php
│   │   │   ├── class-headers.php
│   │   │   └── class-audit-log.php
│   │   │
│   │   ├── smtp/
│   │   │   ├── class-smtp-module.php
│   │   │   ├── class-smtp-mailer.php
│   │   │   ├── class-email-log.php
│   │   │   └── class-email-test.php
│   │   │
│   │   └── woocommerce/
│   │       ├── class-woo-module.php
│   │       ├── class-quick-view.php
│   │       ├── class-wishlist.php
│   │       ├── class-ajax-cart.php
│   │       ├── class-product-filters.php
│   │       └── class-product-gallery.php
│   │
│   └── admin/
│       ├── class-dashboard.php
│       └── views/
│           └── dashboard.php
│
└── languages/

Part 6: Design System (theme.json)

Same as previous plan — complete design token system with colors, typography, spacing, shadows, border radius, transitions. No changes needed.

Key additions specific to SAG:

{
  "custom": {
    // Term page specific tokens
    "termPage": {
      "heroPadding": "4rem",
      "sectionGap": "3rem",
      "childTermCardMinWidth": "250px"
    },
    // Interlinking component tokens
    "interlink": {
      "relatedBg": "var(--wp--preset--color--surface)",
      "clusterNavBorder": "var(--wp--preset--color--primary-light)",
      "attributePillBg": "var(--wp--preset--color--primary-light)",
      "attributePillText": "var(--wp--preset--color--primary-dark)"
    }
  }
}

Part 7: Setup Wizard

Theme activation launches a wizard (works independently of plugin wizards):

Step 1: Site Type

Blog, SaaS, eCommerce, Corporate/Services, Portfolio
Determines: which CPTs are active, which starter templates import, which patterns are highlighted

Step 2: Brand Identity

Logo upload
Primary color (generates full palette)
Font selection (heading + body from curated list)
Live preview panel

Step 3: CPT Configuration

Based on site type, shows which CPTs will be enabled:

Services site → Services, FAQ, Testimonials, Team enabled
SaaS site → Documentation, FAQ, Team enabled
eCommerce → WooCommerce detected, FAQ, Testimonials enabled
Blog → FAQ enabled, others optional
User can toggle any CPT on/off

Step 4: Demo Content Import

Import starter content for selected site type
Or start blank
Creates: homepage, core pages, sample CPT entries, sample taxonomy terms

Step 5: Plugin Recommendations

"For full SEO and content intelligence, install IGNY8 plugin"
"For performance and security, install [Theme] Toolkit"
Download/install buttons (or WordPress.org search links)

Part 8: Build Execution Plan

Phase 1: Foundation (Days 1-3)

Day	Task
1	Theme skeleton: style.css, functions.php, theme.json (full tokens), cleanup.php, enqueue.php
1	FSE base: index.html, single.html, page.html, archive.html, 404.html, search.html
2	Template parts: header.html (3 variants), footer.html (3 variants), sidebar.html, breadcrumbs.html
2	CSS design system: base.css (reset, typography, utilities), components.css (cards, buttons, badges, forms)
3	Core JS: app.js, navigation.js, scroll-effects.js
3	Theme customizer: logo, colors, fonts, layout options

Phase 2: CPTs + Taxonomies (Days 4-6)

Day	Task
4	Register all 7 CPTs with full configuration (supports, rewrite rules, menu icons)
4	Register all custom taxonomies with hierarchical/non-hierarchical settings
5	Meta boxes: service meta, portfolio meta, team meta, testimonial meta
5	Meta boxes: FAQ meta, documentation meta
6	Admin UI: meta box JS for repeater fields (process steps, outcomes, gallery, social links)
6	Theme bridge: IGNY8 plugin detection, graceful fallback functions

Phase 3: Term Landing Page Templates (Days 7-9)

Day	Task
7	Term hero template part: H1, description, breadcrumbs, post count
7	Term content template part: rich content from IGNY8 or WP description
8	Child term grid template part
8	Term archive templates: taxonomy-service_category, taxonomy-service_area, taxonomy-service_attribute
9	Term archive templates: taxonomy-cluster (hub page), taxonomy-faq_category
9	WooCommerce term templates: taxonomy-product_cat, taxonomy-product_tag
9	Term page CSS: term-pages.css

Phase 4: Interlinking Display (Days 10-11)

Day	Task
10	Related content component: read IGNY8 data or fallback to category matching
10	Cluster navigation component: sidebar/footer cluster siblings
11	Attribute browse component: term pills navigation
11	Term quick links, child term grid finalization
11	Integration testing: all components with IGNY8 active and inactive

Phase 5: Landing Page System (Days 12-14)

Day	Task
12	Landing page CPT + section repeater meta box
12	Admin JS: dynamic section fields, drag-to-reorder, add/remove/duplicate
13	Section templates (first 8): hero, features-grid, how-it-works, social-proof, pricing, faq, cta-band, content-block
13	Section CSS: landing-sections.css
14	Section templates (remaining 7): stats-counter, team, portfolio-grid, contact-form, video-embed, logo-bar, comparison-table
14	Presets: all 8 preset configurations, preset loader on page creation
14	Frontend renderer: section loop, responsive testing

Phase 6: Single Templates (Days 15-16)

Day	Task
15	single-service.html: hero, content, process steps, outcomes, gallery, FAQs, related services, CTA
15	single-portfolio.html: hero, content, results, gallery, before/after, testimonial, related projects
16	single-documentation.html: sidebar nav, content, TOC, related docs, prev/next navigation
16	archive templates: archive-service, archive-portfolio, archive-faq, archive-documentation

Phase 7: Custom Blocks + Patterns (Days 17-19)

Day	Task
17	Custom blocks: pricing-table, feature-grid, testimonial-slider, stats-counter, faq-accordion
18	Custom blocks: team-grid, cta-banner, logo-carousel, comparison-table, icon-box
18	Custom blocks: service-grid (CPT-powered), portfolio-showcase (CPT-powered), doc-sidebar
19	Block patterns: heroes (4), content (4), social proof (4), conversion (4), services (3), portfolio (3), footers (3)

Phase 8: Site-Type Starters + WooCommerce (Days 20-22)

Day	Task
20	Starter templates: blog (homepage, single, archive)
20	Starter templates: SaaS (homepage, features, pricing, docs)
21	Starter templates: corporate (homepage, about, services, contact)
21	Starter templates: eCommerce (homepage, shop, product)
22	Starter templates: portfolio (homepage, portfolio, case study)
22	WooCommerce template overrides: shop, product, cart, checkout, account

Phase 9: Toolkit Plugin (Days 23-27)

Day	Task
23	Plugin skeleton: main file, module manager, dashboard
23	Performance module: page cache, HTML minifier
24	Performance module: asset optimizer, image optimizer, WebP, lazy load
24	Performance module: critical CSS, preload, browser cache
25	Forms module: builder UI, field types, renderer, processor
25	Forms module: notifications, entries admin, anti-spam
26	Security module: login protection, firewall, hardening, headers, audit log
26	SMTP module: mailer, email log, test email
27	WooCommerce module: quick view, ajax cart, wishlist, product filters

Phase 10: Setup Wizard + Polish (Days 28-30)

Day	Task
28	Setup wizard: 5-step flow (site type → brand → CPTs → demo → plugins)
28	Demo content: sample data for each site type
29	Cross-component testing: all CPTs, taxonomies, templates, interlinking
29	Performance audit: measure load times per site type
30	Responsive testing: all templates at all breakpoints
30	Accessibility: ARIA labels, keyboard nav, contrast
30	Package: readme.txt, screenshot, build script

Part 9: Performance Targets

Same targets as previous plan:

Metric	Target
First Contentful Paint	< 1.0s
Largest Contentful Paint	< 1.5s
Total Blocking Time	< 50ms
Cumulative Layout Shift	< 0.05
Page Weight	< 200KB (uncached)
PageSpeed Score	95+ mobile
Theme CSS total	< 35KB gzipped
Frontend JS total	< 15KB gzipped

Part 10: Naming Conventions

PHP

Theme prefix: themename_ (replace with chosen name)
Toolkit prefix: themename_toolkit_
CPT slugs: service, landing_page, portfolio, team_member, testimonial, faq, documentation
Taxonomy slugs: service_category, service_area, service_attribute, cluster, portfolio_category, portfolio_tag, faq_category, doc_category, topic_tag
Meta key prefix: _theme_ for theme meta, reads _igny8_ for plugin data
Text domain: theme-name

CSS

BEM: .tn-block__element--modifier
Term page classes: .tn-term-hero, .tn-term-content, .tn-child-grid
Landing section classes: .tn-section--hero, .tn-section--pricing
Interlinking classes: .tn-related, .tn-cluster-nav, .tn-attribute-browse

JavaScript

ES6+, vanilla JS, no jQuery on frontend
Each feature in own file, loaded conditionally

Part 11: Free vs Premium Split (WordPress.org)

Free Theme (WordPress.org):

All CPTs and taxonomies
All term landing page templates
Basic interlinking display components
3 landing page section types (hero, content-block, cta-band)
2 presets (generic, service)
10 block patterns (2 per category)
2 starter templates (blog, corporate)
IGNY8 plugin bridge (full)
Basic customizer options

Premium Theme:

All 15 landing page section types
All 8 presets
All 50+ block patterns
All 5 starter templates
WooCommerce templates
Setup wizard with demo import
Priority support
Updates for 1 year

Free Toolkit Plugin (WordPress.org):

Performance: page cache + HTML minification
Security: basic hardening + login protection
Forms: basic form builder (5 field types)
SMTP: basic mail override

Premium Toolkit:

Performance: full suite (critical CSS, image optimization, WebP, asset optimization)
Security: full suite (firewall, audit log, 2FA)
Forms: full suite (conditional logic, multi-step, file upload, entries management)
SMTP: full suite (email log, templates)
WooCommerce: all enhancements

End of Theme Build Plan

46 KiB Raw Blame History