codex-visual-web-builder 1.0.0

package/README.md

@@ -0,0 +1,54 @@
+# codex-visual-web-builder
+
+Installs the `$visual-web-builder` Codex skill.
+
+This skill combines image generation with image-first frontend implementation:
+
+- generate or edit raster images and visual references
+- create section-by-section website references
+- analyze typography, layout, spacing, colors, components, and image treatment
+- implement the frontend from those references
+
+## Install
+
+```bash
+npx codex-visual-web-builder
+```
+
+If the skill already exists:
+
+```bash
+npx codex-visual-web-builder --force
+```
+
+## Use
+
+After installing, invoke it in Codex:
+
+```text
+Use $visual-web-builder to create a premium landing page for a boutique gym.
+Generate visual references first, analyze them, then implement the site.
+```
+
+Useful prompt details:
+
+- brand or project name
+- target audience
+- page goal
+- style direction
+- sections needed
+- required copy
+- target stack or current project
+
+## Example
+
+```text
+Use $visual-web-builder to build a 5-section landing page.
+
+Brand: Forma Studio
+Business: pilates boutique studio in Milan
+Goal: book trial classes
+Style: premium, calm, editorial, light mode
+Sections: hero, class types, instructors, testimonials, booking CTA
+Output: implement in the current React project
+```

package/bin/install.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+function usage() {
+  console.log(`Install the Visual Web Builder Codex skill.
+
+Usage:
+  npx codex-visual-web-builder
+  npx codex-visual-web-builder --force
+  npx codex-visual-web-builder --target /path/to/.codex/skills
+
+Options:
+  --force          Replace an existing visual-web-builder skill.
+  --dry-run        Print the target path without writing files.
+  --target <dir>   Install into a specific skills directory.
+  --help           Show this help.
+`);
+}
+
+function parseArgs(argv) {
+  const args = { force: false, dryRun: false, target: null };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--force") {
+      args.force = true;
+    } else if (arg === "--dry-run") {
+      args.dryRun = true;
+    } else if (arg === "--target") {
+      const value = argv[i + 1];
+      if (!value) {
+        throw new Error("--target requires a directory path.");
+      }
+      args.target = value;
+      i += 1;
+    } else if (arg === "--help" || arg === "-h") {
+      args.help = true;
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  return args;
+}
+
+function defaultSkillsDir() {
+  const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+  return path.join(codexHome, "skills");
+}
+
+function copySkill(source, destination, force) {
+  if (fs.existsSync(destination)) {
+    if (!force) {
+      throw new Error(
+        `Skill already exists at ${destination}. Re-run with --force to replace it.`
+      );
+    }
+    fs.rmSync(destination, { recursive: true, force: true });
+  }
+
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.cpSync(source, destination, { recursive: true });
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    usage();
+    return;
+  }
+
+  const packageRoot = path.resolve(__dirname, "..");
+  const source = path.join(packageRoot, "skill");
+  const skillsDir = path.resolve(args.target || defaultSkillsDir());
+  const destination = path.join(skillsDir, "visual-web-builder");
+
+  if (args.dryRun) {
+    console.log(`Would install Visual Web Builder to: ${destination}`);
+    return;
+  }
+
+  copySkill(source, destination, args.force);
+  console.log(`Installed Visual Web Builder Codex skill to: ${destination}`);
+  console.log("Invoke it with: $visual-web-builder");
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "codex-visual-web-builder",
+  "version": "1.0.0",
+  "description": "Install the Visual Web Builder Codex skill, combining image generation with image-first frontend implementation.",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "codex-visual-web-builder": "bin/install.js",
+    "visual-web-builder": "bin/install.js"
+  },
+  "files": [
+    "bin",
+    "skill",
+    "README.md"
+  ],
+  "keywords": [
+    "codex",
+    "codex-skill",
+    "imagegen",
+    "image-to-code",
+    "frontend",
+    "web-design"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: visual-web-builder
+description: Use this combined Codex skill when a task needs AI image generation or image editing plus frontend implementation from those generated visuals. It orchestrates the system imagegen workflow for raster assets, mockups, edits, transparent cutouts, and image prompts, then applies the image-to-code workflow for visually important websites, hero sections, landing pages, product pages, portfolios, redesigns, and premium frontend implementation. Use when the user wants one renamed skill that combines $imagegen and $image-to-code into a single visual website builder.
+---
+
+# Visual Web Builder
+
+## Purpose
+
+This is an orchestrator skill that combines two existing skills without duplicating their full instructions:
+
+- `imagegen`: generate or edit raster images, visual references, transparent cutouts, UI mockups, product shots, and project-bound assets.
+- `image-to-code`: generate website section references first, analyze them deeply, then implement the frontend faithfully.
+
+Use this skill when the user wants a single workflow that starts with AI-generated visuals and ends with usable code.
+
+## Source Skills
+
+Load the source skill details only when needed:
+
+- Image generation source: `references/imagegen.md`
+- Image-to-code source: `references/image-to-code.md`
+
+Do not copy large sections from those files into context unless the task requires their exact rules. Prefer reading only the relevant portions.
+
+## Trigger
+
+Use this skill for:
+
+- visual website creation where image generation should happen before coding
+- landing pages, hero sections, product pages, portfolios, editorial pages, and startup sites
+- redesigns where the final frontend should closely match generated design references
+- tasks that need both generated bitmap assets and frontend integration
+- user requests that explicitly mention combining `$imagegen` and `$image-to-code`
+
+Do not use this skill for:
+
+- pure bug fixes or backend work
+- deterministic SVG/icon edits that are better done directly in code
+- simple image generation with no code output, unless the user explicitly asks for the combined skill
+
+## Workflow
+
+1. Classify the task:
+   - `asset-only`: generate or edit images, no implementation.
+   - `visual-to-code`: generate design references, analyze them, implement frontend.
+   - `asset-plus-code`: generate project assets, save them into the workspace, and wire them into code.
+2. For all image work, follow the `imagegen` skill rules:
+   - use built-in `image_gen` by default
+   - use CLI fallback only when explicitly requested or confirmed
+   - handle transparency with chroma-key removal first unless true native transparency is confirmed
+   - save project-bound assets inside the workspace and report final paths
+3. For visually important frontend work, follow the `image-to-code` sequence:
+   - generate visual reference images first
+   - prefer one large readable image per section
+   - generate fresh detail images when text, spacing, buttons, or components are unclear
+   - deeply analyze typography, colors, spacing, layout, image treatment, and component logic
+   - implement the frontend only after analysis
+4. Preserve the generated design during implementation:
+   - do not drift into generic templates
+   - keep the hero clean, spacious, and readable
+   - avoid nested cards, giant section wrappers, fake technical pills, and decorative micro-UI clutter
+   - use real project assets instead of leaving references under `$CODEX_HOME/generated_images`
+5. Verify:
+   - run the app or open the static page when appropriate
+   - use browser inspection/screenshots for local frontend work when available
+   - confirm images render from workspace paths
+   - report any tests or visual checks performed
+
+## Prompt Handling
+
+When generating website references, produce prompts that include:
+
+- section name and intended use
+- visual direction and brand mood
+- layout, typography, spacing, and component constraints
+- image treatment and asset requirements
+- exact text when the user provides it
+- constraints to avoid unreadable tiny text, overstuffed heroes, nested card structures, and generic AI-gradient styling
+
+When generating standalone assets, use the `imagegen` shared prompt schema and taxonomy from the source skill.
+
+## Output Discipline
+
+For final responses, include:
+
+- generated asset paths if files were saved
+- implemented file paths if code changed
+- local preview URL when a dev server was started
+- verification performed
+
+Keep the explanation concise. The value of this skill is the executed workflow, not a long written design brief.

package/skill/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Visual Web Builder"
+  short_description: "Generate visuals, then build faithful frontend"
+  default_prompt: "Use $visual-web-builder to generate section references first, analyze them, and implement a polished landing page."
+
+policy:
+  allow_implicit_invocation: true