--- name: foundry-design-control description: Start and operate a local Foundry precision design session for live web, SwiftUI, or React Native interfaces; directly manipulate rendered elements; inspect project-native tokens, components, variants, breakpoints, states, and motion; resolve semantic source mappings; apply a reviewed batch with Codex, Cursor, or Claude; and verify rebuilt values. Use when the user asks to start Foundry, visually design in code, refine a running product, apply a Foundry batch, or continue a Foundry apply-and-verify run. --- # Foundry Design Control Use Foundry as a reviewable bridge between precise visual decisions and source code. Keep preview overrides temporary. Apply source edits only after the user resolves ambiguous mappings and reviews the change ledger. Resolve `` to the directory containing this `SKILL.md` before running any command below. Never treat `scripts/foundry.sh` as a path inside the user's project. ## Start a session 1. Inspect the project, current worktree, framework, development command, and existing Foundry configuration. 2. Run `/scripts/foundry.sh doctor --project `. 3. If setup is absent, stale, or Doctor reports a missing or conflicting connection, read [platform-setup.md](references/platform-setup.md), then run `/scripts/foundry.sh doctor --project --repair`. Repair refreshes both project-scoped and shared agent configuration to the same exact release. It is transactional, validates the project, and restores every touched file if Foundry introduces a failure. 4. Confirm that `foundry_design_wait_for_work` or the legacy `foundry_design_wait_for_apply` is callable before promising agent collaboration. If setup just added MCP configuration but neither tool is available in the current process, stop and ask the user to restart their coding agent and reopen the same project root. Do not start a session or describe the connection as ready. 5. Run `/scripts/foundry.sh start --project `. It may start the detected development command and resumes the most recent session for the same source revision. Use `--new` only when the user explicitly wants a clean ledger. 6. Read the project design graph, then immediately call `foundry_design_wait_for_work` in bounded waits using the returned session credentials and current revisions. This one listener receives reviewed Apply runs and grounded Visual Agent requests. Fall back to `foundry_design_wait_for_apply` only when the unified tool is unavailable. Repeat the wait while the session is active. Do not finish the turn merely because one wait returns `waiting`; the browser cannot initiate a new agent turn by itself. 7. Keep the Foundry runtime and agent listener alive while the user selects, discusses, and refines elements. End the wait loop only when the user exits Foundry, cancels the workflow, or asks to stop. In web sessions, selection mode stays active so ordinary clicks can move continuously between elements. Inspector categories filter the selected element's controls without changing selection mode. Switch the pointer tool to interaction mode only when testing the underlying app; Option-click still makes a temporary selection there. Repeating a click cycles overlapping layers, and Option-click prioritizes the strongest mapped or semantic target. Use the Layers panel or the Parent and Child controls for obscured and nested targets. Shift-click builds a multi-selection and exposes measured gaps when the layers share a parent. Use the inspector controls as the user's visual editing surface, not as source truth. For sizing modes, project values, component variants, layer reordering, comparison, keyboard commands, and reset behavior, read [visual-workbench.md](references/visual-workbench.md). When the user asks to explore, compare, or edit a component across its instances, variants, or interaction states, read [component-workshop.md](references/component-workshop.md). Keep state previews temporary and require an exact source mapping before using variant or component scope. When the user asks to inspect, compare, or repair behavior across viewport widths, read [responsive-design-lab.md](references/responsive-design-lab.md). Preserve real iframe viewport dimensions, keep stress tests temporary, and require exact source mapping before promoting an edit across breakpoints. When the user asks to audit, trace, consolidate, or extend project tokens and component conventions, read [design-system-intelligence.md](references/design-system-intelligence.md). Treat findings and impact previews as evidence, preserve semantic aliases, and route every proposed source change through review. When the user asks to inspect, scrub, preview, or edit rendered motion, read [motion-studio.md](references/motion-studio.md). Keep transport and scrubbing preview-only, preserve exact source timing and keyframe semantics, and review every editable motion change before apply. When the user asks to audit, preview, or change fonts, type rhythm, scale, or reusable type styles, read [typography-studio.md](references/typography-studio.md). Keep local fonts preview-only, require an explicit integration strategy for new Google Fonts, and validate reviewed typography across the recorded viewport, theme, and state contexts. When the user asks to explore, compare, combine, reject, choose, export, import, or restore parallel visual directions, read [design-branches.md](references/design-branches.md). For portable chosen and rejected outcomes, also read [portable-branch-records.md](references/portable-branch-records.md). Keep every direction isolated from Main, switch preview values reversibly, require explicit promotion before anything enters Review and apply, and never turn a portable record into Design Memory without a separate user action. When the user runs Design Health or asks to correct its findings, read [design-health.md](references/design-health.md). Preserve evidence-only findings when Foundry cannot propose a narrow, reversible preview. For web sessions, `start` indexes the local project design graph. Use `/scripts/foundry.sh index --project ` when the graph must be refreshed independently. Do not launch Foundry merely because a task contains design work. Require an explicit request for a visual or Foundry session. ## Read and review changes 1. Prefer the Foundry MCP tools when available. Otherwise export with `/scripts/foundry.sh export --format json`. 2. Treat JSON as canonical and the consolidated prompt as a portable rendering of that JSON. 3. Check every target's source reference, locator evidence, mapping confidence, state, theme, breakpoint, and instance/component scope. 4. Read [semantic-mapping-contract.md](references/semantic-mapping-contract.md) when a change belongs to a direct manipulation operation. 5. Keep `unresolved` targets and operations out of the apply batch. Require the user's selected mapping rather than guessing. 6. Collapse repeated changes only by target, property, scope, breakpoint, theme, and state set. Preserve the first measured value and final requested value. Read [change-contract.md](references/change-contract.md) when interpreting or troubleshooting a change set. ## Discuss a visual request When `foundry_design_wait_for_work` returns `kind: visual_request`, read [visual-agent-conversation.md](references/visual-agent-conversation.md). Ground the response in the attached rendered targets or region, source locations, viewport, theme, state, measurements, project tokens, and contextual comments. Return concrete proposals through `foundry_design_respond_to_visual_request`, then resume the unified listener. Never edit source from a proposal. Only a proposal the user previews, promotes to Review, and applies through a reviewed Apply run authorizes source work. ## Apply the reviewed batch 1. Read the project design graph with `foundry_design_get_project_design`. 2. For an interactive session, keep calling `foundry_design_wait_for_work` in bounded waits as soon as Foundry starts. Include the current source revision, design-graph revision, and agent identity. A reviewed run or visual request may already be queued while the agent was offline. A `waiting` result means poll again while the session remains active, not that the workflow is complete. 3. If a run is claimed, retain its `claimAttemptId`, read [apply-run-contract.md](references/apply-run-contract.md), and follow its state transitions. Do not edit from an unreviewed draft ledger. 4. Immediately report `applying` with the current `claimAttemptId`, then reinspect current source before editing. The MCP bridge automatically renews a fresh claim while this turn is inspecting prerequisites, but do not rely on that as a progress state. If a long prerequisite prevents the transition, explicitly extend the lease with `foundry_design_heartbeat_apply_run` while the run remains `claimed`. 5. Stop if the claim is no longer active or the source inspection finds a stale revision, stale graph, unresolved target, or unresolved operation. Return to `foundry_design_wait_for_work` when Foundry has safely requeued an abandoned handoff. 6. Implement the user's selected semantic mapping at the narrowest source of truth. 7. Preserve existing tokens and component conventions. Prefer a matching token over a new literal. Do not invent a global token for an instance-scoped adjustment. 8. Apply the batch as a normal, reviewable source diff. Never write generated preview styles into production code. 9. After the source edit and rebuild, report `rebuilding` with the same `claimAttemptId`, the complete changed-file list, and at least one real validation result. Every validation must pass before Apply can continue. 10. While the run is still `rebuilding`, call `foundry_design_record_apply_result` exactly once with the run ID, claim attempt ID, and the exact frozen change IDs. This acknowledges server-measured source proof; it does not mark the changes applied or complete verification. 11. Only after that acknowledgement succeeds, report `verifying` with the same `claimAttemptId`. Report `failed` for a terminal source or validation failure. 12. Report any request that cannot be represented without changing the requested scope or architecture. ## Verify 1. Run the project's targeted tests, type checks, lint, and build in proportion to the edited surface. 2. Rebuild the target in the same device, viewport, theme, breakpoint, and state recorded by the session. 3. Read [state-workbench.md](references/state-workbench.md) for multi-state verification and unsupported browser states. 4. Report `verifying` only after the real source diff and passing validation have been acknowledged once through `foundry_design_record_apply_result`. The web adapter then reloads to clear preview overrides, obtains a one-use verification challenge, and measures the rebuilt result. 5. Require measured geometry for selection targets. Treat zero-size, fallback, or out-of-bounds targets as failures. 6. Do not mark changes applied directly and do not submit manual web verification. Foundry marks the frozen changes applied only after the live web adapter proves every recorded context against the acknowledged source result. 7. Treat the browser challenge as a local, one-use, origin-bound handoff rather than remote attestation. Native verification is accepted only through the private claim capability held by the MCP bridge; `claimAttemptId` is correlation, not authority. 8. Read the completed apply run and return the source diff summary, validation results, verification count, and unresolved items. 9. If the run needs attention, explain the mismatch and wait for the user to authorize the in-product retry. Never retry automatically. For native limitations and motion registration, read [platform-setup.md](references/platform-setup.md). ## Update project integration When the user asks to update Foundry, run `/scripts/foundry.sh update --project --yes`. The updater refreshes checksum-matched Foundry files, skill bundles, and agent configuration, while preserving files that changed after installation. Run doctor after the update, report every preserved path, and ask the user to restart their coding agent before starting a new apply session. ## Remove project integration Run `/scripts/foundry.sh uninstall --project ` only when the user explicitly asks. Preserve any Foundry-generated file whose contents changed after setup.