agentleFS
PMDevSolutionsPMDevSolutions/Flavian/.claude/skills/canva-to-fse-autonomous-workflow/SKILL.md

canva-to-fse-autonomous-workflow

Skill20 starsChanged 14 days agoMITView on GitHub

Use when converting Canva HTML/CSS exports to WordPress FSE block themes. Orchestrates autonomous workflow from CSS token extraction through template generation. Keywords: Canva to WordPress, FSE conversion, HTML export, CSS design tokens, autonomous template generation

The file

Show its rules and text

We split this skill into the rules it gives an agent

23 rules. About 0 are common, 13 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈13

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill when:

    line 18
  2. Distinctive:

    When NOT to use:

    line 31
  3. Distinctive:

    Critical: If no HTML/CSS files are found in the provided directory, STOP and inform user before proceeding.

    line 58
  4. Distinctive:

    Before creating or modifying ANY theme files, verify:

    line 71
  5. Distinctive:

    CRITICAL: When Canva CSS extraction is incomplete, returns partial results, or fails entirely, use these professional fallback defaults.

    line 87
  6. Distinctive:

    All colors are WCAG AA compliant with appropriate contrast ratios:

    line 91
  7. Very specific:

    Never leave theme.json with missing values

    line 178
  8. Distinctive:

    Ask user for the Canva export directory path.

    line 192
  9. Very specific:

    CRITICAL: Create theme.json IMMEDIATELY, before any template conversion.

    line 199
  10. Very specific:

    If CSS is minimal: scan inline <style> blocks and style="" attributes in HTML

    line 245
  11. Very specific:

    Ensure minimum viable theme.json (13+ colors, 9+ sizes, 10+ spacing)

    line 250
  12. Very specific:

    Check file exists: themes/<theme-name>/theme.json

    line 307
  13. Distinctive:

    Verify completeness (13+ colors, 9+ font sizes, 10+ spacing tokens)

    line 308
  14. Distinctive:

    Add semantic HTML attributes (aria labels, roles)

    line 335
  15. Distinctive:

    Create PHP patterns for image-containing sections (pattern-first architecture)

    line 341
  16. Very specific:

    Write template to themes/{theme-name}/templates/{page}.html

    line 342
  17. Distinctive:

    After all pages are converted:

    line 347
  18. Very specific:

    Create style.css with WordPress theme header:

    line 349
  19. Very specific:

    Create functions.php with asset enqueuing and pattern registration

    line 363
  20. Very specific:

    NEVER put PHP code in .html template files

    line 389
  21. Very specific:

    NEVER use empty src="" attributes

    line 390
  22. Distinctive:

    All generated themes MUST meet these criteria:

    line 445
  23. Distinctive:

    Security scan clean: - All output escaped, all URLs sanitized

    line 452

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Canva-to-FSE Autonomous Workflow

Overview

This skill orchestrates the complete autonomous conversion of Canva HTML/CSS exports into WordPress Full Site Editing (FSE) block themes. It parses static HTML and CSS files exported from Canva, extracts design tokens, and generates standards-compliant FSE templates without requiring any live design tool connection.

Core Innovation: Hybrid approach with brief clarification phase (1-2 min) followed by fully autonomous execution using superpowers:executing-plans.

Key Principle: Design system FIRST -> theme.json foundation SECOND -> templates THIRD -> verification FOURTH. Extract ALL design tokens from CSS wholesale before generating any templates.

When to Use

Use this skill when:

  • Converting Canva designs/exports to WordPress FSE themes
  • Building WordPress themes from Canva HTML/CSS export files
  • Generating FSE templates from static HTML page exports
  • Extracting CSS design tokens to theme.json

Trigger phrases:

  • "Convert Canva to WordPress"
  • "Canva to FSE theme"
  • "Import Canva export"
  • "Turn Canva export into WordPress theme"
  • "Generate FSE theme from Canva"

When NOT to use:

  • Classic WordPress themes (non-FSE)
  • Plugin development
  • Simple CSS changes to existing themes
  • Designs in Figma (use figma-to-fse-autonomous-workflow skill instead)

Prerequisites

Before starting, verify:

  • Canva export directory exists with HTML and CSS files
  • Expected structure: export/ directory with *.html pages and style.css (or similar CSS file)
  • Image assets exported separately (PNG/JPG/SVG files available)
  • WordPress theme structure exists (themes/ directory at project root)

Expected Canva export layout:

export/
├── index.html          # Homepage
├── about.html          # About page (optional)
├── contact.html        # Contact page (optional)
├── style.css           # Main stylesheet (or styles.css, css/style.css)
└── images/             # Exported image assets
    ├── hero-bg.jpg
    ├── logo.png
    └── ...

Critical: If no HTML/CSS files are found in the provided directory, STOP and inform user before proceeding.

CRITICAL: File Location Requirements

This project uses ROOT-LEVEL folders for theme development:

project-root/
└── themes/[theme-name]/     <- ALL theme files go HERE (NOT wp-content/themes/)

PRE-FLIGHT VALIDATION (Run BEFORE any file writes):

Before creating or modifying ANY theme files, verify:

  1. themes/ directory exists at project root
  2. NO files being created in wp-content/themes/ (NEVER use this path)
  3. Theme name slug is valid (lowercase, hyphens only, no spaces)

Auto-validation: the registered PreToolUse hook .claude/hooks/validate-theme-location.sh blocks incorrect paths (a copy also lives at scripts/canva-fse/validate-theme-location.sh).

Why root-level?

  • Clean development structure (no nested wp-content)
  • Easier version control
  • Testing copies files to WordPress wp-content/ separately

Deployment Note: During testing, files are copied from themes/ to WordPress wp-content/themes/. See TESTING-GUIDE.md for deployment procedures.

Fallback Design Tokens (Default Design System)

CRITICAL: When Canva CSS extraction is incomplete, returns partial results, or fails entirely, use these professional fallback defaults. This ensures the workflow NEVER blocks on missing design data.

Fallback Color Palette (13 tokens)

All colors are WCAG AA compliant with appropriate contrast ratios:

const FALLBACK_COLORS = {
  // Primary palette (Professional blue-gray)
  "primary": "#34495e",           // Main brand color
  "primary-dark": "#293a4b",      // Darker variant
  "primary-darker": "#141d25",    // Darkest variant
  "primary-light": "#707f8e",     // Lighter variant
  "primary-lightest": "#eaecee",  // Lightest variant

  // Accent palette (Teal)
  "accent": "#16a085",            // Accent color
  "accent-dark": "#11806a",       // Darker accent
  "accent-darker": "#084035",     // Darkest accent
  "accent-lightest": "#e7f5f2",   // Lightest accent

  // Neutrals
  "white": "#ffffff",             // Pure white
  "black": "#0c0c0c",            // Near black (softer than pure black)
  "background": "#fdfdfd",        // Off-white background
  "gray": "#5e6060"               // Mid-tone gray
};

Fallback Typography (2 families, 9 sizes)

Font families:

  • Primary: "Inter", "system-ui", "-apple-system", "BlinkMacSystemFont", "Segoe UI", "Roboto", "sans-serif"
  • Heading: "Questrial", "Georgia", "serif"

Font sizes (9-point scale):

const FALLBACK_FONT_SIZES = [
  { slug: "small", size: "14px", name: "Small" },          // Body small
  { slug: "base", size: "16px", name: "Base" },            // Body text
  { slug: "medium", size: "18px", name: "Medium" },        // Large body
  { slug: "large", size: "20px", name: "Large" },          // Subheading
  { slug: "x-large", size: "24px", name: "Extra Large" },  // H4
  { slug: "2x-large", size: "32px", name: "2X Large" },    // H3
  { slug: "3x-large", size: "40px", name: "3X Large" },    // H2
  { slug: "4x-large", size: "56px", name: "4X Large" },    // H1
  { slug: "5x-large", size: "72px", name: "5X Large" }     // Hero heading
];

Fallback Spacing (10 tokens)

Based on 4px base unit:

const FALLBACK_SPACING = [
  { slug: "20", size: "4px", name: "1" },      // xs: 4px
  { slug: "30", size: "8px", name: "2" },      // sm: 8px
  { slug: "40", size: "16px", name: "3" },     // base: 16px
  { slug: "50", size: "24px", name: "4" },     // md: 24px
  { slug: "60", size: "32px", name: "5" },     // lg: 32px
  { slug: "70", size: "40px", name: "6" },     // xl: 40px
  { slug: "80", size: "48px", name: "7" },     // 2xl: 48px
  { slug: "90", size: "64px", name: "8" },     // 3xl: 64px
  { slug: "100", size: "80px", name: "9" },    // 4xl: 80px
  { slug: "110", size: "112px", name: "10" }   // 5xl: 112px
];

Fallback Layout Settings

const FALLBACK_LAYOUT = {
  contentSize: "768px",    // Standard content width
  wideSize: "1280px"       // Wide content width
};

When to Use Fallback Tokens

Use fallback tokens when:

  1. Canva CSS has NO custom properties or design variables
  2. CSS parsing fails or returns incomplete results
  3. Inline styles dominate with no consistent design system
  4. Export contains only minimal or reset stylesheets
  5. Token extraction errors occur

Merge strategy (when partial CSS tokens exist):

  • Canva-extracted tokens take precedence
  • Fallback tokens fill gaps
  • Never leave theme.json with missing values

Example merge:

// Canva CSS has 5 colors, fallback has 13
// Result: 5 Canva colors + 8 additional fallback colors = 13 total

The Workflow

Phase 1: Import & Parse (1-2 minutes, Interactive)

Step 1.1: Gather Export Location

Ask user for the Canva export directory path. Verify:

  1. Directory exists and contains HTML files
  2. At least one CSS file is present (check style.css, styles.css, css/style.css, or inline <style> blocks)
  3. Note any image assets directory

Step 1.2: Create theme.json Foundation FIRST

CRITICAL: Create theme.json IMMEDIATELY, before any template conversion. This step NEVER blocks the workflow.

CSS extraction workflow:

async function createThemeJsonFoundation(exportDir, themeName) {
  console.log("Step 1.2: Creating theme.json foundation...");

  // 1. Parse CSS files for design tokens (non-blocking)
  const cssTokens = await parseCssForTokens(exportDir);

  let tokens;

  if (cssTokens && cssTokens.colors.length > 0) {
    // CSS tokens found - use them
    console.log(`Found ${cssTokens.colors.length} colors, ${cssTokens.fontSizes.length} font sizes`);
    tokens = cssTokens;
  } else {
    // No usable tokens - use fallback defaults
    console.log("No CSS design tokens found, using professional fallback tokens");
    tokens = FALLBACK_DESIGN_TOKENS;
  }

  // 2. Merge extracted tokens with fallbacks (extracted takes precedence)
  const mergedTokens = mergeCssWithDefaults(tokens, FALLBACK_DESIGN_TOKENS);

  // 3. Generate theme.json immediately
  const themeJson = generateThemeJson(mergedTokens, themeName);

  // 4. Write to file (root-level themes/ folder)
  await writeFile(`themes/${themeName}/theme.json`, themeJson);
  console.log(`theme.json created at themes/${themeName}/theme.json`);

  return { themeJson, tokens: mergedTokens };
}

Run: ./scripts/canva-fse/parse-canva-export.sh --theme-json export/style.css

CSS parsing targets:

  • CSS custom properties (--color-primary, --font-size-lg, etc.)
  • Repeated hex colors, RGB/HSL values across rules
  • Font-family declarations
  • Font-size values
  • Margin/padding patterns (for spacing tokens)
  • Max-width values (for layout dimensions)
  • If CSS is minimal: scan inline <style> blocks and style="" attributes in HTML

Merge strategy:

  • Canva CSS tokens override fallback tokens (by slug)
  • Fill gaps with fallback tokens
  • Ensure minimum viable theme.json (13+ colors, 9+ sizes, 10+ spacing)

Result: theme.json exists with complete design system BEFORE template work begins.

Step 1.3: Survey Exported HTML Pages

Scan the export directory for HTML files:

  1. List all *.html files
  2. Open each file and identify its page type (homepage, about, services, contact, etc.)
  3. Note structural patterns (shared headers, footers, navigation)
  4. Identify image references and their paths

Step 1.4: Create Conversion Plan

Map HTML structures to WordPress blocks using the element mapping table (see below). Use superpowers:writing-plans to create a detailed plan:

Plan structure:
1. theme.json already created (Phase 1.2)
2. Create theme directory structure (style.css, templates/, parts/, patterns/)
3. Extract shared components (header, footer, navigation)
4. For each HTML page (1-N):
   - Parse HTML structure into block hierarchy
   - Convert elements to WordPress blocks
   - Replace hardcoded colors/sizes with theme.json token slugs
   - Create PHP patterns for image-containing sections
   - Generate FSE template
5. Run automated verification
6. Generate comparison report

Step 1.5: Present Plan to User

Show:

  • Complete design token mapping (colors, typography, spacing extracted from CSS)
  • List of HTML pages to convert
  • Element-to-block mapping strategy
  • Confirmation prompt: "Proceed with autonomous conversion?"

Phase 2: Autonomous Conversion (5-30 minutes, Zero Interruptions)

Critical: Once user approves, use superpowers:executing-plans to execute the plan WITHOUT any "should I continue?" prompts.

Step 2.1: Trigger Autonomous Execution

User: "Yes, proceed"
-> Invoke: Skill(superpowers:executing-plans)
-> Pass: Implementation plan from Phase 1
-> Mode: Autonomous (no checkpoint prompts)

Progress and resumability: as in the Figma pipeline, keep .claude/pipeline/<theme-name>/state.json current after every template and phase boundary (schema in figma-to-fse-autonomous-workflow/SKILL.md → Progress Tracking, with "pipeline": "canva-to-fse"). A fresh session resumes from it; TodoWrite is not used.

Step 2.2: Verify theme.json Foundation

theme.json already created in Phase 1.2 - verify it exists:

  • Check file exists: themes/<theme-name>/theme.json
  • Verify completeness (13+ colors, 9+ font sizes, 10+ spacing tokens)
  • Validate JSON syntax
  • Confirm NO placeholder values

Step 2.3: Create Theme Structure

themes/<theme-name>/
├── style.css          # Theme header
├── functions.php      # Asset enqueuing, pattern registration
├── theme.json         # Design system (from Phase 1)
├── templates/
│   ├── index.html     # Fallback (required)
│   └── [other templates as identified]
├── parts/
│   ├── header.html
│   └── footer.html
└── patterns/          # PHP patterns for image sections

Step 2.4: Convert Each HTML Page

For EACH exported HTML page:

  1. Run: ./scripts/canva-fse/convert-html-to-blocks.sh export/page.html
  2. Refine block markup:
    • Fix nesting (ensure valid block parent/child relationships)
    • Add semantic HTML attributes (aria labels, roles)
    • Replace inline styles with block attributes
  3. Replace hardcoded values with theme.json token slugs:
    • Hex colors -> var:preset|color|{slug}
    • Pixel font sizes -> var:preset|font-size|{slug}
    • Spacing values -> var:preset|spacing|{slug}
  4. Create PHP patterns for image-containing sections (pattern-first architecture)
  5. Write template to themes/{theme-name}/templates/{page}.html
  6. Validation hooks run automatically after each write

Step 2.5: Generate Supporting Files

After all pages are converted:

  1. Create style.css with WordPress theme header:
    /*
    Theme Name: {Theme Name}
    Description: FSE block theme converted from Canva export
    Requires at least: 6.0
    Tested up to: 6.7
    Requires PHP: 7.4
    Version: 1.0.0
    License: GNU General Public License v2 or later
    Text Domain: {theme-slug}
    */
  2. Create functions.php with asset enqueuing and pattern registration
  3. Generate comparison report: Run: ./scripts/canva-fse/generate-comparison-report.sh

Phase 3: Completion (<1 minute)

  1. Present summary:
    • Number of templates converted
    • Number of design tokens extracted from CSS
    • Number of PHP patterns created
    • Any issues or warnings encountered
  2. Link to comparison report
  3. Provide WordPress activation instructions:
    1. Copy themes/{theme-name}/ to your WordPress wp-content/themes/ directory
    2. In WordPress admin: Appearance -> Themes -> Activate "{Theme Name}"
    3. Visit your site to verify the theme

Pattern-First Architecture

CRITICAL RULES:

  • Images MUST go in patterns/*.php files (PHP executes there)
  • Templates reference patterns: <!-- wp:pattern {"slug":"theme/pattern-name"} /-->
  • NEVER put PHP code in .html template files
  • NEVER use empty src="" attributes

Example pattern (patterns/hero-image.php):

<?php
/**
 * Title: Hero Image
 * Slug: theme-name/hero-image
 * Categories: featured
 */
?>
<!-- wp:cover {"url":"<?php echo esc_url( get_theme_file_uri( 'assets/images/hero-bg.jpg' ) ); ?>","dimRatio":50} -->
<div class="wp-block-cover">
  <span aria-hidden="true" class="wp-block-cover__background has-background-dim"></span>
  <img class="wp-block-cover__image-background" alt="Hero background" src="<?php echo esc_url( get_theme_file_uri( 'assets/images/hero-bg.jpg' ) ); ?>" data-object-fit="cover"/>
  <div class="wp-block-cover__inner-container">
    <!-- wp:heading {"level":1,"style":{"color":{"text":"var:preset|color|white)"}}} -->
    <h1 class="wp-block-heading has-white-color has-text-color">Welcome</h1>
    <!-- /wp:heading -->
  </div>
</div>
<!-- /wp:cover -->

Example template referencing the pattern (templates/front-page.html):

<!-- wp:template-part {"slug":"header","area":"header"} /-->
<!-- wp:pattern {"slug":"theme-name/hero-image"} /-->
<!-- wp:template-part {"slug":"footer","area":"footer"} /-->

Canva Element to WordPress Block Mapping

Canva/HTML ElementWordPress BlockImplementation Notes
Heading text (<h1>-<h6>)wp:headingPreserve heading level hierarchy
Body text (<p>)wp:paragraphMap font styles to theme.json presets
Image (<img>)wp:image via patternAlways use pattern-first for images
Button/CTA (<a>, <button>)wp:buttonWrap in wp:buttons container
Section/container (<div>, <section>)wp:groupUse layout attributes for alignment
Multi-column layoutwp:columns + wp:columnMap flex/grid to column widths
List (<ul>, <ol>)wp:listPreserve list type and nesting
Divider (<hr>)wp:separatorMap border styles to separator style
Background image sectionwp:cover via patternUse dimRatio for overlay opacity
Navigation bar (<nav>)wp:navigationExtract menu items and links
Spacer elementwp:spacerUse theme.json spacing tokens for height
Blockquote (<blockquote>)wp:quotePreserve citation if present
Video embedwp:video or wp:embedUse embed for YouTube/Vimeo URLs
Icon/SVGwp:image via patternInline SVG or image reference
Formwp:form or third-party blockNote: core form block is limited

Quality Standards

All generated themes MUST meet these criteria:

  • 100% theme.json token usage - Zero hardcoded hex colors or pixel sizes in templates
  • All templates pass validate-template.sh
  • All patterns follow pattern-first architecture (no PHP in HTML templates)
  • All files in root-level themes/ directory (never wp-content/themes/)
  • WordPress coding standards compliance (PHP files pass PHPCS)
  • Security scan clean - All output escaped, all URLs sanitized
  • Valid block markup - Proper opening/closing comments, valid nesting
  • Accessibility - Semantic HTML, alt text on images, proper heading hierarchy

Error Recovery

Error ScenarioRecovery Strategy
Malformed HTMLUse Claude vision to analyze screenshots of the original Canva design, generate blocks manually
Missing CSS / no stylesheetUse fallback design tokens for the complete theme.json
Unsupported Canva elementsConvert to closest WordPress block equivalent, log warning in comparison report
Inline styles remaining after conversionExtract to theme.json tokens during refinement pass
Broken image pathsCreate pattern with get_theme_file_uri() pointing to assets/images/
Complex CSS grid layoutsSimplify to wp:columns with appropriate column counts
JavaScript-dependent elementsConvert to static block equivalent, note limitation in report
Empty or placeholder contentUse Lorem Ipsum with clear TODO comments for replacement

Differences from Figma Pipeline

AspectCanva PipelineFigma Pipeline
InputStatic HTML/CSS filesLive Figma MCP connection
Token extractionCSS parsing (parse-canva-export.sh)get_variable_defs API
Layout analysisHTML DOM structureStructured Figma component data
Image handlingPre-exported files in directoryDownloaded via Figma image export
MCP dependencyNone requiredFigma MCP server required
InteractivityFile path prompt onlyFigma URL + Dev Mode required
ValidationShared infrastructureShared infrastructure
Script directoryscripts/canva-fse/scripts/figma-fse/

Shared infrastructure:

  • Theme location validation logic
  • Template validation scripts
  • Pattern-first architecture rules
  • Fallback design tokens
  • Quality standards and security scans
  • WordPress coding standards checks

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.