| 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:
- Capture the current generated screenshot with recorded viewport/state.
- Run
$visual-verdict comparing the approved reference and generated screenshot.
- Treat the JSON verdict as authoritative.
- If
score < 90, convert differences[] and suggestions[] into the next edit plan.
- 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}}
