raster-texture-reconstruction

name

raster-texture-reconstruction

description

Reconstruct source-specific raster texture such as grain, halftone, scanlines, RGB offset, chromatic aberration, edge erosion, distress, and banded glitch while keeping structural text and UI live. Use when a mockup-to-code manifest explicitly sets rasterTexture.required=true, or when a user explicitly asks to reproduce identity-bearing raster texture without shipping source pixels or rasterizing structural copy.

Raster Texture Reconstruction

Rebuild raster-specific visual character as a Web-owned effect layer. Preserve semantic HTML, responsive behavior, and accessibility; use source crops only as measurement and comparison evidence.

This first version is explicit-only. Start only when the parent manifest sets rasterTexture.required: true. If the user explicitly requests the skill, record that decision first with reason: "user-request" and exact existing target ids. Block when no parent manifest or resolvable target exists. Do not auto-detect a requirement from weak background noise.

Workflow

1. Read the parent manifest and normalize rasterTexture into a four-key raster-texture-contract/v1 snapshot: schemaVersion, required, reason, and targetIds. Bind that snapshot in the report and copy targetIds exactly. The report receipt can then be added to the parent manifest without creating a circular whole-manifest hash.

2. Create one target row per manifest id. Bind a real source crop and classify every effect separately with its own coordinateSpace, methods, and ownership. Use glyph-local, element-local, or section-field; one target may legitimately combine spaces.

3. Record only source-observed effect types. Give each effect a stable target-local id. Read references/reconstruction-methods.md before selecting CSS, SVG filter, content-free mask, or procedural-raster methods.

4. Read the actual desktop/mobile QA viewports from the parent workflow. Define each state's width, height, intensity scale, and spatial scale. Keep motion static unless the parent manifest separately requires motion.

5. Set the report safety assertions exactly:

   {
     "sourcePixelsShipped": false,
     "contentFreeAsset": true,
     "structuralTextRemainsLive": true
   }
   

6. Validate the plan before implementation:

   SKILL_ROOT="${SKILL_ROOT:-${CODEX_HOME:-$HOME/.codex}/skills}"
   "$SKILL_ROOT/mockup-to-code/scripts/skill-pack-python" \
     "$SKILL_ROOT/raster-texture-reconstruction/scripts/validate_raster_texture_report.py" \
     reports/raster-texture-report.json --root . --phase pre-css --receipt
   

   A pre-CSS report uses status: "ready" and target implementation.status: "planned". A fully passing completion report is also valid at this phase.

7. Implement the effect outside the source pixels. Structural headings, labels, CTA copy, navigation, body, and legal text remain selectable live DOM text. Keep CSS-owned surfaces and image-owned assets separate.

8. Measure matched source/build crops with the supplied helper. Treat the result as diagnostic evidence, not a universal quality score:

   SKILL_ROOT="${SKILL_ROOT:-${CODEX_HOME:-$HOME/.codex}/skills}"
   "$SKILL_ROOT/mockup-to-code/scripts/skill-pack-python" \
     "$SKILL_ROOT/raster-texture-reconstruction/scripts/texture_metrics.py" \
     --target-id hero.heading \
     --source reports/crops/hero-heading-source.png \
     --build reports/crops/hero-heading-build.png \
     --out reports/texture-metrics-hero-heading.json
   

9. Use the parent workflow's render/capture commands at the declared widths and heights. Capture readable desktop and mobile crop pairs and record the dimensions. Bind current hashes for implementation files, any content-free assets, the metrics report, and both crop pairs. Set each target verdict and the report status to pass.

10. Validate completion and copy the emitted receipt into specialistReports.rasterTexture:

    SKILL_ROOT="${SKILL_ROOT:-${CODEX_HOME:-$HOME/.codex}/skills}"
    "$SKILL_ROOT/mockup-to-code/scripts/skill-pack-python" \
      "$SKILL_ROOT/raster-texture-reconstruction/scripts/validate_raster_texture_report.py" \
      reports/raster-texture-report.json --root . --phase completion --receipt
    

11. Return the crop pairs to the parent workflow's existing independent visual reviewer. Do not create a second reviewer system inside this skill. A specialist pass means the evidence contract is complete; it does not override a parent reviewer rejection.

Hard Rules

• Never ship pixels copied, cropped, masked, blurred, recolored, or downscaled from the source mockup.
• Never rasterize structural text to obtain texture fidelity.
• Prefer filters, masks, and pseudo-elements over duplicated text. If a decorative DOM copy is unavoidable, it must be aria-hidden="true", must not own the semantic target id, and must not replace the accessible live node.
• Treat generated masks and procedural rasters as content-free: no readable words, logos, UI, faces, products, or source-identifying composition.
• Keep effect ownership local to the declared target. A glyph-local effect may not become an unbounded section overlay.
• Preserve legibility and contrast. Texture may erode edges; it may not destroy the parent workflow's content, accessibility, or CTA requirements.
• Keep desktop/mobile tuning explicit. Do not reuse desktop grain size, scanline pitch, glitch-band width, or RGB displacement blindly on mobile.
• Keep animation separate from static texture fidelity. If motion is requested, follow the parent motion contract and prove a settled static state plus reduced-motion behavior.
• Do not turn helper metrics into one synthetic pass score. Use crop pairs and the parent independent review for final visual judgment.
• Emit blocked or needs_work when evidence is unavailable. Do not fill receipts with placeholders or retrospective hashes.
• Keep source/build crops and measurement evidence under the work root's report area. They may not be referenced by site code, copied into deploy assets, or included in the production bundle.

Contract

• Read schemas/raster-texture-report-v1.schema.json before creating or transforming a report.
• Start blocked work from templates/raster-texture-report.blocked.json.
• Use relative, traversal-free paths rooted at --root.
• Use raster-texture-report/v1 for the specialist report and raster-texture-metrics/v1 for helper measurements.
• The stable parent receipt shape is {contract:"raster-texture-report/v1",path,sha256}.

Validation

Run the focused tests and structural skill validation after changes:

SKILL_ROOT="${SKILL_ROOT:-${CODEX_HOME:-$HOME/.codex}/skills}"
"$SKILL_ROOT/mockup-to-code/scripts/skill-pack-python" \
  "$SKILL_ROOT/raster-texture-reconstruction/scripts/quick_validate.py"