ui-design-source

# ui-design-source

Use this skill when the user provides Figma material, design-export files, screenshots of design tools, PDFs, JSON, existing HTML, or asks for design-to-HTML/code fidelity. It adapts OpenDesign/Figma handoff discipline for UIDesigner without requiring a live Figma runtime.

This skill turns design-source evidence into a compact handoff for `ui-design-executor`. Add a durable contract, reference pack, design-system, or deep renderer skill only when its specialist trigger is present; do not fan an ordinary screenshot task out to all of them.

## Access Rules

- If a Figma connector, MCP, plugin API, or exported file is actually available, inspect it with the available tool or file reader.
- If the user only provides a Figma URL and no available Figma access exists, do not probe it with general `web_fetch`/browser search as substitute Figma access. Ask for a screenshot/export or continue only from visible notes. Do not claim "Figma imported", "frames inspected", or "variables read". Keep requested `exact`/1:1 work blocked until inspectable evidence arrives. Always put both next paths in the visible response before any question/form: **Exact** waits for a connector, screenshot, PDF, or export; **Adaptive (optional)** can start only after the user chooses it. Offer an `adaptive` provisional scaffold as non-fidelity work; never call it 1:1. Do not silently start the adaptive path.
- If the design source is an image or PDF, treat it like a screenshot: extract what is visible, label uncertain text/spacing, and preserve information architecture.
- If the design source is HTML/CSS, inspect the rendered surface when possible and use source files only to clarify tokens/components.

## Source Intake

Classify the source:

- `figma_url`: URL or file key, not enough by itself unless a connector/tool is available.
- `figma_export_json`: nodes, components, variables, styles, constraints, or plugin export.
- `design_screenshot`: frame image, prototype screenshot, app screenshot, or reference image.
- `design_pdf`: exported specs, deck, or annotated design handoff.
- `existing_html`: current artifact, app page, or prototype.
- `design_notes`: Markdown/text PRD, redlines, specs, or designer comments.

For each source, record:

- Path/link/attachment identity.
- What was actually inspectable.
- Confidence: `high`, `medium`, or `low`.
- Missing access or missing data.

## Extract Design Source Map

Before rendering, produce this compact map:

```markdown
## Design Source Map
- Source type:
- Frames/screens:
- Primary frame:
- Visible copy:
- Layout regions:
- Components:
- Variants/states:
- Variables/tokens:
- Assets/icons/images:
- Interactions/prototype notes:
- Responsive constraints:
- Implementation targets:
- Fidelity requirements:
- Unknowns:
```

For Figma-like sources, look specifically for:

- Frame size, grid, auto-layout direction, gaps, padding, constraints.
- Component instances, variants, slot/content overrides, states.
- Variables/styles for color, typography, radius, elevation, spacing, effects.
- Text styles and localization risks.
- Exportable assets and which assets must be replaced or recreated.
- Prototype links, overlays, interactions, transitions, and disabled/error states.

## Multi-Source Coverage Ledger

When the request covers a directory, batch, flow, or other set of multiple inspectable screens, inventory the complete authoritative source set before implementation. Do not treat a representative sample, shared tokens, or the first few screens as proof that the remaining sources were inspected.

Keep one row per promised source screen with:

- Source identity/path and target route/component.
- Must-preserve visible anchors: page type, primary heading/copy, major regions, density, and primary action.
- Fidelity mode and intentional changes.
- Independent status for `inspected`, `implemented`, and post-implementation `compared`.
- Remaining drift or blocker.

Batch source reads and comparisons when useful, but do not claim complete coverage until every promised row has a fresh rendered/source comparison. Build success, valid routes or links, shared tokens, no-overflow checks, and spot checks prove different properties; they do not prove visual fidelity for unreviewed screens. If the turn stops early, report the exact remaining source rows instead of saying the whole set is complete.

If the user says the mocks or screens do not match, reopen the full coverage ledger and compare the inspectable source set again. Do not ask them to supply one example as a substitute for auditing sources already available to the Agent.

## Source-To-HTML Checkpoints

For screenshot/design-to-HTML work, use a staged pass inspired by strong screenshot-to-code workflows, but keep UIDesigner's HTML-first and evidence-first rules:

1. Inventory the source before styling: visible text, major regions, controls, repeated patterns, image/icon assets, data shape, and unknown areas.
2. Choose the target stack from the user's request or repo context. Standalone drafts default to self-contained HTML/CSS; only use Tailwind, Bootstrap, React, Vue, or a component library when the target project already uses it or the user asks.
3. Create a source-to-HTML mapping for each major region: source region, intended HTML section/component, preserved details, intentional changes, and fidelity risk.
4. Render critical states, not just the happy path: loading, populated, empty, error, disabled, selected, hover/focus, validation, and mobile behavior when relevant.
5. Compare the HTML against the source/contract after rendering. Fix drift in layout, hierarchy, visible copy, density, and component role before decorative polish.

Do not fill missing screenshot content with dashboard metrics, sidebars, fake records, or template blocks. If sample data is necessary, label it as sample and keep it out of observed evidence.

## Fidelity Modes

Choose one mode and state it:

- `exact`: reproduce the supplied frame as