This skill should be used when the user asks to design, redesign, audit, or implement frontend/UI work with OpenDevBrowser, screenshots, or the /canvas surface. It turns briefs and existing interfaces into contract-first, real-browser-validated design execution.
This skill should be used when the user asks to design, redesign, audit, or implement frontend/UI work with OpenDevBrowser, screenshots, or the /canvas surface. It turns briefs and existing interfaces into contract-first, real-browser-validated design execution.
version
1.1.0
Design Agent Skill
Use this skill for frontend work that must be visually strong, contract-first, and verified in a real browser instead of judged only from code.
Keep generated-help labels exact when referencing cross-pack capabilities: screencast / browser replay, desktop observation, and computer use / browser-scoped computer use.
Use browser replay (screencast-start / screencast-stop) during real-surface validation when motion, sequencing, or transition timing matters.
Load opendevbrowser-motion-design when motion-heavy work needs terminology, pattern catalog decisions, platform/framework policy, device posture, reduced-motion rules, performance budgets, or temporal proof.
Treat shader, WebGL, Spline-style, and custom 3D motion references as advisory cues unless current runtime evidence proves support.
Desktop observation stays read-only and is only for external window or OS-level evidence around the workflow; it is not a design-surface control lane.
Browser-scoped computer use remains a challenge posture knob via --challenge-automation-mode, not a desktop-agent capability.
Core Rules
Start with a design contract, not ad-hoc implementation.
Build a reference pattern board before locking a new direction when external inspiration matters; treat nextStepGuidance.readiness as recovery or continuation guidance only, and treat a harvest as design-ready only when top-level ready=true, productSuccess=true, artifactAuthority=product_ready, non-diagnostic evidenceAuthority, and manifest-backed reference evidence agree. For canonical Pinterest pin-media harvests, require evidenceAuthority=pin_media_ready and manifest-backed pin-media-index.json; snapshot_ready and motion_ready are not substitutes for pin-media readiness.
Choose a component family from artifacts/component-pattern-index.md before inventing a new screen structure.
Start from the closest shipped OpenDevBrowser example in artifacts/opendevbrowser-ui-example-map.md when the repo already has a related surface.
Route repo-first redesigns through artifacts/existing-surface-adaptation.md before changing shells or component anatomy.
Decide state ownership before writing component APIs, prompts, or /canvas patches.
Declare app-shell, route, and overlay ownership with artifacts/app-shell-and-state-wiring.md before expanding navigation chrome or shared panels.
Declare navigation and deep-link ownership in the contract before buttons, tabs, or search params start pushing route changes ad hoc.
Declare async and search ownership with artifacts/async-search-state-ownership.md before wiring input-driven fetches, scopes, or background refresh.
Keep one semantic token source with artifacts/theming-and-token-ownership.md; do not let leaf components invent raw colors, spacing, or type rules ad hoc.
Define layout-preserving loading, empty/error recovery, and transient feedback surfaces with artifacts/loading-and-feedback-surfaces.md before polishing the happy path.
For scan-heavy screens, declare list identity, lazy-loading, and progressive-reveal posture before polishing individual cards or rows.
Keep one visual direction per task. Do not mix unrelated design languages.
Prefer real content, realistic states, and explicit user journeys over placeholder copy.
Preserve the repo's existing design system when one already exists. Only introduce a new direction when the brief or product gap justifies it.
Design Contract
The mandatory design contract lives in assets/templates/design-contract.v1.json.
Every design task should answer these blocks before implementation:
intent
designLanguage
contentModel
navigationModel
asyncModel
layoutSystem
typographySystem
motionSystem
performanceModel
responsiveSystem
accessibilityPolicy
generationPlan
/canvas Required Generation Plan Fields
The generationPlan block must include:
targetOutcome
visualDirection
layoutStrategy
contentStrategy
componentStrategy
motionPosture
responsivePosture
accessibilityPosture
validationTargets
Optional designVectors may carry advanced motion advisories, but it must not change the required CanvasGenerationPlan fields or imply shader, WebGL, Spline, or 3D runtime support.
Use scripts/extract-canvas-plan.sh when the full contract already exists and only the /canvas payload is needed. The extracted request is a command payload, not the durable source of truth. Keep the filled full contract in .opendevbrowser/design-agent/<run-id>/design-contract.json and use .tmp/canvas-plan.request.json for scratch submission.
Recommended Workflow Modes
contract-first
Use when starting from a brief or existing product requirement.
Fill assets/templates/design-brief.v1.md.
Translate it into assets/templates/design-contract.v1.json.
Check artifacts/opendevbrowser-ui-example-map.md and artifacts/app-shell-and-state-wiring.md before deciding the shell structure.
If a nearby shipped surface exists, review artifacts/existing-surface-adaptation.md before changing shell or component structure.
Review artifacts/design-contract-playbook.md and artifacts/design-agent-work-products.md.
Implement only after the contract is coherent.
research-harvest
Use when a redesign needs external references or when the brief explicitly asks for competitive learning.
Start with artifacts/research-harvest-workflow.md.
Capture 3 to 5 live references with OpenDevBrowser.
For Pinterest, use the browser-native social/pinterest recipe with extension mode and cookies instead of treating Pinterest as a default full provider.
Before extension-mode Pinterest harvests, preflight npx opendevbrowser status --daemon --output-format json and continue only when data.fingerprintCurrent === true, data.relay.extensionConnected === true, and data.relay.extensionHandshakeComplete === true.
Inspect top-level ready, productSuccess, artifactAuthority, evidenceAuthority, and manifest-backed ranked reference evidence before using the bundle; use nextStepGuidance.readiness, nextStepGuidance.doNotProceedIf, and recovery commands only as follow-through or recovery guidance. For canonical Pinterest pin-media harvests, continue only with top-level ready=true, productSuccess=true, artifactAuthority=product_ready, evidenceAuthority=pin_media_ready, and manifest-backed pin-media-index.json; this is pin-media-first readiness, not screenshot or motion substitution.
Record ready evidence in assets/templates/reference-pattern-board.v1.json.
Turn the synthesis into contract deltas before implementation.
screenshot-audit
Use when starting from screenshots, mocks, or an existing page.
Decompose the design into layout, type, spacing, state, motion, and accessibility decisions.
Rewrite those observations into the same contract fields used for /canvas.
Record issues and fixes in assets/templates/design-audit-report.v1.md.
Use artifacts/frontend-evaluation-rubric.md before editing code.
If the screen uses scroll-driven sequencing, add artifacts/scroll-reveal-surface-planning.md to the audit inputs.
canvas-contract
Use when the task should run through the design canvas.
Start by creating .tmp/ and .opendevbrowser/design-agent/<run-id>/.
Copy assets/templates/design-contract.v1.json into .opendevbrowser/design-agent/<run-id>/design-contract.json, then fill the full contract before extraction.
Use artifacts/design-contract-playbook.md for section construction guidance and artifacts/design-agent-work-products.md for durable run files.
Start with canvas.session.open; use canvas.capabilities.get only after you have a canvasSessionId.
Use --output-format json for Canvas CLI commands whenever you read returned IDs, statuses, guidance, or follow-up fields.
Read the handshake and inspect planStatus, preflightState, generationPlanRequirements.allowedValues, generationPlanIssues, guidance.recommendedNextCommands, guidance.nextStepGuidance, params examples, field examples, validation checks, and do-not-proceed blockers before choosing the next command.
Treat preflightState="handshake_read" as the normal first-step checkpoint before canvas.plan.set; if the handshake already reports plan_invalid, repair the plan instead of mutating.
Extract the generation plan to .tmp/canvas-plan.request.json after session open by passing .tmp/canvas-session.open.json to scripts/extract-canvas-plan.sh; .tmp is scratch-only.
If canvas.plan.set succeeds with planStatus="accepted" or preflightState="plan_accepted", copy the accepted plan request into .opendevbrowser/design-agent/<run-id>/canvas-plan.request.json and follow the returned guidance.recommendedNextCommands.
Keep Canvas preview projection on canvas_html by default. Use bound_app_runtime only after runtime bridge preflight proves the bound app is reachable, intentional, and part of the accepted validation plan.
Copy assets/templates/canvas-patch.request.v1.json to .tmp/canvas-patch.request.json, then fill accepted , , latest numeric , page IDs, node IDs, and token placeholders before mutation.
real-surface-validation
Use when design work must be proven on live surfaces.
Validate the design on the actual browser surface with snapshot, screenshot, debug-trace-snapshot, and relevant /canvas preview commands.
Run artifacts/isolated-preview-validation.md first when the component family or state matrix is still unstable.
Run the same real task across supported modes when parity is part of the acceptance criteria.
Record blockers explicitly instead of hand-waving them away.
performance-audit
Use when the design feels heavy, re-renders too often, or becomes unstable with realistic content.
Capture the slow interaction and baseline with artifacts/performance-audit-playbook.md.
Use assets/templates/design-audit-report.v1.md to record issue / evidence / fix / validation.
Prefer ownership and structure fixes before memoization or micro-optimizations.
If scroll-driven motion is part of the problem, validate the progress owner with artifacts/scroll-reveal-surface-planning.md before tuning timing.
release-gate
Use when the implementation looks done and the remaining work is proof and cleanup.
Start with artifacts/design-release-gate.md.
Fill assets/templates/design-release-gate.v1.json.
Re-run the real-surface matrix and the design review checklist.
Follow the canonical direct-run release evidence policy from ../opendevbrowser-best-practices/SKILL.md; this pack does not redefine release-proof ownership.
Fix remaining gaps before ship-audit.
Research-Backed Patterns
These patterns are summarized in artifacts/external-pattern-synthesis.md and should shape how the skill is applied:
Specialized agents work best when scope, tooling, and examples are explicit.
Frontend generation quality improves when prompts specify stack, layout intent, interaction states, and visual references instead of generic adjectives.
Competitive harvest works best when each reference captures borrow and reject decisions instead of a mood board only.
Large UI tasks should be broken into deliberate passes: contract, structure, implementation, then live validation.
Real content and real workflows outperform placeholder-heavy prompts.
Frontend design agents should own both aesthetics and verification, not just code output.
Component libraries and screen families should be referenced intentionally instead of rediscovered from scratch on every task.
Existing shipped surfaces should be treated as first-class adaptation inputs, not obstacles to work around.
State ownership, overlay ownership, async ownership, and preview discipline need to be explicit or the implementation will drift even when the design language is strong.
Route ownership should be explicit and typed: one owner translates deep links, tabs, URL params, and external entry points into screen state.
Scroll-reveal work needs one declared progress owner and an explicit reduced-motion contract or it will regress across breakpoints.
Debounced async search, layout-preserving placeholders, semantic token ownership, and non-reflow feedback surfaces should be decided in the contract instead of improvised during polish.
Scan-heavy screens need stable item identity, lazy containers or progressive reveal where justified, and a declared scan unit before per-item polish or motion work.
Parallel Multitab Alignment
Apply shared concurrency policy from ../opendevbrowser-best-practices/SKILL.md ("Parallel Operations").
Treat design validation as session-per-worker; do not alternate unrelated target streams inside one session.
Re-check extension readiness before /canvas or relay-backed annotation steps after idle windows.
ISSUE-01: stale refs and DOM churn during iterative UI validation
ISSUE-07: MV3 extension state loss during /canvas and popup-driven design loops
ISSUE-08: restricted origins and unsupported extension pages during design validation
ISSUE-12: stale evidence or unsupported design claims in final deliverables
Reload discipline for unpacked-extension design work:
After npm run extension:build, do not trust a live Chrome result until the unpacked extension is actually reloaded in Chrome.
Stale MV3 runtime state can preserve old popup or /canvas design-tab behavior even when the repo bundle is already fixed.
If design-tab commands still throw restricted_url on chrome-extension://.../canvas.html, treat that as an unpacked-extension reload problem first, then reconnect the extension and rerun the design workflow.
Treat /canvas governance as the strongest contract in the repo: read the handshake, respect generationPlanRequirements, inspect typed repair examples, and do not mutate before the plan is accepted.
Treat preflightState="handshake_read" as the required ready state for the first post-open decision loop unless the handshake is already reporting an invalid-plan repair path.
Keep durable design-agent work products under .opendevbrowser/design-agent/<run-id>/; use .tmp/ only for disposable command params, extractor output, and scratch responses.
Preserve Canvas document persistence through canvas.document.save under .opendevbrowser/canvas/...; do not replace it with design-agent work-product storage.
For non-canvas frontend work, still fill the same design-contract fields before coding so decisions stay consistent across code, preview, and docs.
Use one owner for overlays, drawers, sheets, and detail panels; prefer item-backed state over boolean sprawl.
If motion depends on scroll or viewport progress, define the driver and reduced-motion fallback before implementation.
For animation systems, route the motion-specific decisions through ../opendevbrowser-motion-design/artifacts/motion-pattern-catalog.md, ../opendevbrowser-motion-design/artifacts/platform-framework-guide.md, ../opendevbrowser-motion-design/artifacts/performance-frame-budget.md, and ../opendevbrowser-motion-design/artifacts/open-dev-browser-motion-evidence.md.
Carry advanced motion cues through designVectors and motionSystem as design intent only; they do not authorize new runtime libraries.
Keep libraryPolicy.motion and libraryPolicy.threeD empty in samples unless a separate runtime change explicitly approves those lanes.
Use artifacts/scroll-reveal-surface-planning.md whenever the design depends on pinned sections, reveal stages, or viewport-driven sequencing.
Validate new patterns in isolation or /canvas preview with artifacts/isolated-preview-validation.md, including deterministic fixtures and installed dependencies, before declaring the integrated screen finished.
Verify default, hover, focus, empty, loading, success, and error states when they are relevant.
Validate responsive behavior intentionally; do not assume desktop layouts scale down cleanly.
If the UI feels slow or unstable, switch to artifacts/performance-audit-playbook.md and capture a baseline before changing structure.
Use OpenDevBrowser CLI for real-browser validation, not just static reasoning.
Record the final ship decision in assets/templates/design-release-gate.v1.json; if evidence is missing, the task is not done.
Finish by updating docs, AGENTS guidance, and any skill-pack references affected by the new UI behavior.
canvasSessionId
leaseId
baseRevision
If canvas.plan.set fails with generation_plan_invalid, inspect details.missingFields, details.issues, guidance.paramsExamples, guidance.fieldExamples, guidance.validationChecks, guidance.doNotProceedIf, and generationPlanIssues, then repair and resubmit the params file. Use canvas.plan.get or canvas.capabilities.get only when diagnostics are still needed after reading repair examples.
Inspect canvas.starter.list before hand-authoring common dashboard, auth, marketing, settings, or docs shells when the requested design resembles a starter. Starter use is advisory and must be rejected when it does not satisfy the design contract.
Use canvas.starter.apply only when a starter fits the contract; inspect or align any starter-seeded plan before further mutation.
For multi-agent or multi-section design reviews, use canvas.workspace.open, canvas.workspace.status, canvas.workspace.child.add, canvas.workspace.child.execute, canvas.workspace.child.close, and canvas.workspace.close only after each child has a normal canvas session. Treat the workspace manifest as refs-only orchestration; child documents, leases, code-sync bindings, previews, and feedback remain child-owned. Do not route nested workspace commands or mutate sibling children; each child owns its document state and accepted plan.
Call canvas.inventory.list after plan acceptance when reusable sections or components might fit. Use canvas.inventory.insert only with an accepted plan, current lease, page, parent, placement, and latest revision.
Mutate with canvas.document.patch --params-file .tmp/canvas-patch.request.json, then copy the exact submitted patch into .opendevbrowser/design-agent/<run-id>/canvas-patch.request.json.
Treat assets/templates/canvas-patch.request.v1.json as a minimal mutation smoke payload. Before canvas.document.save or canvas.document.export with exportTarget="design_document", patch every requiredBeforeSave governance block reported by the handshake or policy warnings.
After every successful canvas.document.patch, canvas.preview.render, canvas.preview.refresh, canvas.feedback.poll, canvas.document.save, or canvas.document.export, read guidance.recommendedNextCommands and guidance.reason before choosing the next step.
Validate extension-stage history controls against public canvas.history.undo and canvas.history.redo; design-tab clicks emit the internal canvas_history_requested event, but acceptance is still on the public command outcomes.
When token work is in scope, validate collection or mode authoring, token value or alias edits, selected-node binding, and token usage inspection in the extension stage.
If annotation send is part of the workflow, record whether the design tab returned Delivered to agent or Stored only; fetch with annotate --stored. Stored retrieval should expect Annotation V2 compact handoff with screenshot-free shared inbox storage, schemaVersion: 2, redaction metadata, selector bundles, and canvas identity when available; annotate --stored checks the shared repo-local inbox before extension-local fallback.
Use canvas.preview.render, canvas.feedback.poll, canvas.preview.refresh, canvas.document.save, and canvas.document.export as the validation and persistence loop. If canvas.feedback.poll returns a preflight-blocker, return to canvas.plan.set before continuing.
Remember that saved Canvas documents live under .opendevbrowser/canvas/...; .opendevbrowser/design-agent/<run-id>/ only stores planning, request, evidence, and handoff files.
