visual-forge

name	visual-forge
description	Compatibility visual-delivery runtime for Roblox creator UI, HUD, and plugin work; the canonical completion owner is now Forge.
surface-class	canonical
domain	roblox-studio
audience	creator
artifact-type	skill

Visual Forge Skill

Visual Forge is the visual-delivery lane for Roblox creator UI, HUD, and plugin work. $forge remains the persistent implementation owner when the work turns into a code-bearing completion loop.

Use this skill when the user wants Codex to build or restyle Roblox creator UI through a compatibility visual-delivery loop: an approved generated reference, static reference, or captured inspiration baseline becomes the target, Forge implements, and Visual Verdict drives measured iteration rather than subjective description alone.

Purpose

Create a measured Roblox UI delivery loop from either a generated reference, a static reference, or a captured inspiration baseline:

creator brief / captured reference -> approved visual source of truth -> $forge implementation -> $visual-verdict + pixel diff -> reusable Studio-native design layer.

If a user brings an external website or app screenshot as inspiration, treat it only as a visual reference source for a Roblox HUD, menu, storefront, onboarding screen, or Studio plugin panel. Do not drift into generic website-cloning language or stack assumptions.

This is a workflow-composition skill. It composes existing skills and must not add runtime commands, dependencies, or app-specific assumptions by itself.

Use when

• The user describes a desired creator HUD, menu, storefront, launcher page, or companion UI and wants implementation, not just design advice.
• The user provides a live URL and wants a visual implementation or clone through measured Visual Verdict iteration.
• This skill owns the migrated $web-clone use case for visual implementation work.
• A generated raster mockup/reference image would make the target clearer.
• The task needs pixel-level visual iteration with a pass/fail threshold.
• The final result should leave reusable design tokens/components, not only a one-off screenshot match.

Do not use when

• The user only wants design critique or general creator UI advice; use a designer lane.
• The task is a non-visual gameplay/runtime implementation with no UI reference target.
• The user already supplied a final static reference image and only needs comparison/fixes; hand directly to $forge with $visual-verdict guidance.
• The requested output is a deterministic SVG/vector/code-native asset rather than a raster reference.

Workflow

1. Ground the target repo

Before stack-specific choices, inspect local evidence:

• ScreenGui / plugin widget hierarchy,
• Roact / ReactLua / Fusion usage,
• styling/token conventions,
• screenshot/test tooling,
• existing HUD/menu/panel components that should be reused.

Do not hardcode React, Vue, Tailwind, router concepts, or website-specific stacks unless the repository evidence actually supports an off-Studio surface.

2. Establish the visual reference

If external inspiration is used, capture or document that reference inside the visual-delivery artifacts and carry forward the relevant viewport, content-state, and interaction constraints. Do not invoke $web-clone; that standalone skill is hard-deprecated. Do not route new URL-driven website cloning work to $web-clone.

Live URL reference artifacts must include:

• source URL and permission/scope note,
• viewport(s), route/state, and any seed/login assumptions,
• captured baseline screenshot path or documented capture command/tool,
• interaction parity notes for visible controls,
• known exclusions such as server/account plumbing, personalized data, multi-page crawling, and third-party widget parity.

For generated UI concepts, use $imagegen to produce the reference from the user's UI description.

Prompt requirements:

• classify as ui-mockup, unless another imagegen taxonomy is clearly better,
• include viewport/aspect ratio and intended surface,
• specify layout, hierarchy, typography direction, color mood, and any exact text,
• forbid logos/watermarks/unrequested brand marks,
• ask imagegen to avoid impossible UI details or unreadable text.

For project-bound implementation, copy the approved reference into the workspace, for example under .rcs/artifacts/visual-forge/<slug>/reference.png. Never leave the implementation reference only in $CODEX_HOME/generated_images/....

3. Require explicit user approval

Stop after reference generation or URL-derived reference capture and ask the user to approve one reference image/state or request a targeted regeneration/capture adjustment.

Before approval:

• do not start UI implementation,
• do not invoke $forge,
• do not treat a rough image as final.

After approval, the confirmed image or URL-derived baseline becomes the visual source of truth. Major design pivots, replacing the reference, or changing the design direction require an explicit user request.

4. Hand off to $forge for implementation

Invoke $forge with:

• the approved reference image path or URL-derived baseline artifact,
• source URL, viewport(s), content state, and interaction parity notes for live URL tasks,
• the user description,
• the detected repo/UI-stack context,
• exact screenshot command/viewport requirements,
• the completion checklist below.

Forge may iterate autonomously after approval. It should edit code, run the app, capture screenshots, and keep improving until the approved reference is matched or a real blocker exists.

5. Use $visual-verdict before every next edit

For each visual iteration:

1. Capture the current generated screenshot with recorded viewport/state.
2. Run $visual-verdict comparing the approved reference and generated screenshot.
3. Treat the JSON verdict as authoritative.
4. If score < 90, convert differences[] and suggestions[] into the next edit plan.
5. Rerun before the next edit.

Required verdict shape is inherited from $visual-verdict: score, verdict, category_match, differences[], suggestions[], and reasoning.

6. Use pixel diff only as secondary debug evidence

When mismatch diagnosis is hard, generate a pixel diff or pixelmatch overlay to locate hotspots. Pixel diff does not replace $visual-verdict; it only helps translate visual hotspots into concrete edits.

Record final diff evidence with the reference/screenshot artifacts so the result can be audited.

7. Build a reproducible design system

The implementation is incomplete unless the visual match is encoded in repo-native reusable artifacts. Depending on the project, this may mean CSS variables, theme tokens, Tailwind config, component variants, Storybook stories, design docs, or existing equivalents.

Capture at least the applicable:

• colors,
• spacing scale,
• typography scale/weights,
• radii,
• shadows/elevation,
• important component variants and states.

Prefer existing token/component patterns. Do not introduce a new design-system layer if the repo already has one that can be extended.

Completion checklist

Do not declare done until all are true:

• Approved reference image or URL-derived reference artifact is saved in the workspace.
• Screenshot reproduction command, viewport, route, seed/state, and output paths are documented.
• $visual-verdict final score is >= 90 against the approved reference.
• Pixel diff or overlay evidence is recorded as secondary debug evidence.
• Design-system tokens/components are repo-native and reusable.
• Build/lint/test or the repo's equivalent verification passes.
• No unapproved major design pivot occurred after reference approval.
• Remaining visual differences, if any, are explicitly documented with rationale.

Handoff template

$forge "Implement the approved Roblox creator UI reference.
Reference: <workspace-reference-image-or-url-derived-artifact>
Source URL (if URL-derived): <url and permission/scope note>
Viewport/content state: <viewport, route/state, seed/login assumptions>
Interaction parity notes: <visible controls and known exclusions>
Route/surface: <route or component>
Screenshot command: <command and viewport>
Use $visual-verdict before every next edit; pass threshold score >= 90.
Use pixel diff only as secondary debug evidence.
Extract reusable design tokens/components for colors, spacing, typography, radii, shadows, and key variants.
Run build/lint/test before completion.
Do not make major design pivots unless explicitly requested."

Task: {{ARGUMENTS}}