opendevbrowser 0.0.17 → 0.0.18

package/skills/opendevbrowser-design-agent/artifacts/component-pattern-index.md

@@ -0,0 +1,130 @@
+# Component Pattern Index
+
+Use this index before inventing a new screen structure from scratch. Pick one dominant pattern family, justify it in the design contract, then adapt it to the repo's product language.
+
+## 1. App Shells And Navigation
+
+Use when the page has repeatable navigation, toolbars, inspectors, or multistep depth.
+
+- Preferred families:
+  - top bar + primary content + optional inspector rail
+  - split navigation with list/detail content
+  - dense workspace shell with command row, canvas pane, and secondary panels
+- Web guidance:
+  - keep route navigation and panel toggles separate
+  - treat command bars, breadcrumbs, and tab rows as one system
+  - collapse secondary rails deliberately on tablet and mobile
+- Failure signals:
+  - toolbar actions compete with global navigation
+  - left rail, tabs, and breadcrumbs all claim the same hierarchy
+
+## 2. Search, Filters, And Segmentation
+
+Use when the user must narrow or switch views quickly.
+
+- Preferred families:
+  - search plus token filters
+  - segmented control plus summary count
+  - stacked refinement rail for dense datasets
+- Web guidance:
+  - keep search query, filter state, and sort state addressable in URL params when the view should survive refresh or sharing
+  - separate quick toggles from advanced filters
+- Failure signals:
+  - filter chips, tabs, and sort dropdown all mutate the same state without a clear owner
+
+## 3. Collections, Cards, And Feeds
+
+Use when the UI is primarily about scanning repeated items.
+
+- Preferred families:
+  - editorial card stacks
+  - compact data cards with one clear primary action
+  - masonry or asymmetric feature grids only when the content supports it
+- Web guidance:
+  - define card anatomy once: media, eyebrow, title, metadata, actions
+  - keep empty, loading, and error states visually related to the collection pattern
+  - declare the scan unit and stable item identity before adding per-card motion or toolbar complexity
+  - choose progressive reveal, lazy containers, or virtualization intentionally when realistic data volume will make the surface heavy
+- Failure signals:
+  - each card variant invents its own spacing, radius, or action order
+  - card identity or expansion state is index-based and collapses during reordering or filtering
+
+## 4. Forms, Settings, And Editors
+
+Use when the interface collects or edits structured input.
+
+- Preferred families:
+  - grouped settings sections with clear save semantics
+  - single-column editor with sticky action bar
+  - split preview/editor only when the comparison is essential
+- Web guidance:
+  - state whether the flow autosaves, batches, or requires explicit submit
+  - keep validation, hint text, and irreversible actions visually distinct
+- Failure signals:
+  - field-level save and page-level save coexist without clear precedence
+
+## 5. Dashboards, Tables, And Detail Panes
+
+Use when the screen mixes overview metrics with drill-down detail.
+
+- Preferred families:
+  - summary strip plus focused detail pane
+  - table with sticky controls and adjacent record inspector
+  - dashboard sections ordered by operator task frequency, not by visual symmetry
+- Web guidance:
+  - choose whether the primary scan unit is a row, card, or metric tile
+  - keep dense tables readable before adding ornamental styling
+  - keep inspectors, previews, and secondary panels lazy when the primary task is scanning or triage
+- Failure signals:
+  - cards, charts, and tables all have equal prominence and no scan path
+
+## 6. Overlays, Drawers, Sheets, And Menus
+
+Use when work must happen without leaving the current context.
+
+- Preferred families:
+  - item-owned detail drawer
+  - single modal for confirmation or destructive review
+  - contextual menu for low-commitment actions
+- Web guidance:
+  - use one owner for overlay visibility
+  - prefer item-based presentation over multiple booleans
+  - define escape, backdrop, and focus-return behavior up front
+- Failure signals:
+  - sibling components toggle the same modal independently
+  - multiple overlays can stack accidentally
+
+## 7. Empty, Loading, Success, And Error States
+
+Treat state surfaces as first-class components, not afterthoughts.
+
+- Required questions:
+  - what reassures the user while data loads
+  - what action is possible from the empty state
+  - what recovery path exists from the error state
+- Web guidance:
+  - reuse the same layout skeleton as the successful state whenever possible
+  - success states should confirm progress without hijacking the next action
+
+## 8. Scroll-Driven Storytelling And Motion
+
+Use only when motion improves comprehension or narrative sequencing.
+
+- Preferred families:
+  - section reveal with normalized progress
+  - pinned explainer with explicit stage transitions
+  - lightweight parallax reserved for emphasis, not default decoration
+- Web guidance:
+  - drive the effect from one progress model, not many competing observers
+  - define reduced-motion fallbacks before implementation
+- Failure signals:
+  - every section animates differently
+  - motion blocks reading or keyboard interaction
+
+## Reference Routine
+
+1. Pick one dominant pattern family.
+2. Write the choice into the design contract and explain why it fits the task.
+3. Declare the required states and state ownership before component code.
+4. Validate the pattern in isolation or in `/canvas` preview before broad rollout.
+5. Validate the integrated screen on a real browser surface.

package/skills/opendevbrowser-design-agent/artifacts/design-contract-playbook.md

@@ -0,0 +1,157 @@
+# Design Contract Playbook
+
+The design contract is the single source of truth for frontend decisions in this skill.
+
+## 1. Intent
+
+Capture why the design exists.
+
+- `audience`: who is this for
+- `task`: what must they accomplish
+- `successCriteria`: how the UI proves it succeeded
+- `trustPosture`: conservative, neutral, bold, editorial, etc.
+
+If the task does not have a crisp audience or job-to-be-done, stop and define it before styling anything.
+
+## 2. Design Language
+
+Choose one coherent direction.
+
+- `direction`: a named visual family
+- `styleAxes`: contrast, density, warmth, shape language, texture, depth, motion
+- `semanticTokenSource`: which shell or provider owns semantic color, spacing, radius, shadow, and motion tokens
+- `approvedLibraries`: allowed component, icon, and styling libraries
+
+Do not mix multiple unrelated directions inside one screen.
+
+## 3. Content Model
+
+Content is part of the design system, not filler.
+
+- define the primary message
+- define the supporting messages
+- require real content when possible
+- list the UI states that must exist
+- define loading, empty, error, and transient feedback behavior
+- avoid placeholder copy unless the task explicitly needs scaffolding
+
+## 4. Async Model
+
+State how async work begins, restarts, and stops.
+
+- `owner`: which layer owns query, result, and status transitions
+- `loadTrigger`: load-on-enter, restart-on-input, or long-lived workflow
+- `restartTriggers`: query, scope, sort, selection, or route changes
+- `debounceMs`: the delay for user-driven restarts
+- `emptyQueryBehavior`: what happens when the query clears
+- `cancellationPolicy`: how stale work is ignored
+- `urlOwnership`: when query, scope, or sort belongs in the URL
+
+If async ownership is unclear, the design contract is incomplete even if the visual direction is strong.
+
+## 5. Navigation Model
+
+State how routes, tabs, overlays, and deep links are translated into UI state.
+
+- `owner`: which shell or controller owns route resolution
+- `primaryRouteModel`: the canonical route, tab, or view map
+- `deepLinkPolicy`: which params survive refresh, sharing, or external entry
+- `invalidRouteFallback`: what happens when params are missing, stale, or malformed
+- `overlayEntryPoints`: which routes or actions are allowed to open drawers, sheets, or modal review states
+
+Do not let buttons, tabs, and row actions invent route strings independently. One navigation owner should translate external entry points into screen state.
+
+## 6. Layout System
+
+State the page architecture, not just the component list.
+
+- grid type
+- container strategy
+- spacing rhythm
+- alignment rules
+- section sequencing
+- scan unit for dense collections or dashboards
+
+## 7. Typography System
+
+Decide typography deliberately.
+
+- primary and secondary families
+- scale
+- measure
+- fallback policy
+- loading strategy
+
+## 8. Motion System
+
+Motion must help comprehension.
+
+- timing and easing
+- where motion is allowed
+- reduced-motion posture
+- whether depth, 3D, or parallax are justified
+
+## 9. Performance Model
+
+State the performance posture before interaction regressions appear.
+
+- `renderHotspots`: which subtree is most likely to churn
+- `stableIdentityPolicy`: how rows, cards, tabs, or stages keep stable ids
+- `listStrategy`: static list, lazy container, progressive reveal, or virtualization threshold
+- `secondaryPanelPolicy`: whether inspectors, previews, or editors load eagerly or on demand
+- `measurementPlan`: which profiler or browser evidence proves the screen is healthy under realistic data
+
+If scan-heavy or motion-heavy screens have no performance model, the design contract is incomplete.
+
+## 10. Responsive System
+
+Responsive behavior is an authored outcome.
+
+- breakpoints
+- layout changes by breakpoint
+- touch targets
+- overflow rules
+- collapsed navigation or panel behavior
+
+## 11. Accessibility Policy
+
+Accessibility must be explicit.
+
+- WCAG target
+- keyboard requirements
+- focus visibility rules
+- semantic structure requirements
+- color contrast expectations
+
+## 12. Generation Plan
+
+This is the mutation-safe subset used by `/canvas`.
+
+Required keys:
+
+- `targetOutcome`
+- `visualDirection`
+- `layoutStrategy`
+- `contentStrategy`
+- `componentStrategy`
+- `motionPosture`
+- `responsivePosture`
+- `accessibilityPosture`
+- `validationTargets`
+
+Use `scripts/extract-canvas-plan.sh` to derive this from the full contract.
+
+## Review Questions
+
+Before implementation, answer:
+
+1. What should the user notice first?
+2. What should they do second?
+3. What content is real, and what still needs product input?
+4. Which layer owns async restarts, query state, and stale-request handling?
+5. Which layer owns route translation, deep-link recovery, and overlay entry points?
+6. What loading, empty, error, and transient feedback surfaces are required?
+7. Where is the canonical theme or token source?
+8. Which list, grid, or pane is most likely to become render-heavy under realistic data?
+9. What part of the design is most likely to regress on mobile?
+10. What evidence will prove the design works on a real browser surface?

package/skills/opendevbrowser-design-agent/artifacts/design-release-gate.md

@@ -0,0 +1,40 @@
+# Design Release Gate
+
+Use this before calling a design task shipped.
+
+## Blocking Checks
+
+- The design contract is complete and still matches the implemented screen.
+- A reference pattern board exists when external inspiration shaped the work.
+- Default, empty, loading, success, and error states were checked when relevant.
+- Responsive behavior was validated intentionally.
+- Accessibility posture was reviewed against the contract.
+- Real-browser evidence exists for the primary surface.
+- Cross-surface parity was checked when the acceptance criteria require it.
+- `/canvas` work obeyed the session handshake and saved only after required governance blocks were satisfied.
+- Docs, AGENTS guidance, and skill references were updated in the same pass when the design surface changed.
+
+## Required Artifacts
+
+Record the gate in `assets/templates/design-release-gate.v1.json` and keep it aligned with:
+
+- `assets/templates/design-review-checklist.json`
+- `assets/templates/real-surface-design-matrix.json`
+- `assets/templates/reference-pattern-board.v1.json` when research harvest was used
+
+## Minimum Shipping Loop
+
+1. Re-read the design contract.
+2. Compare the shipped UI against the contract and the pattern board.
+3. Run the real-surface matrix on the required modes.
+4. Record evidence and blockers in the release-gate JSON.
+5. Fix gaps.
+6. Repeat until every required check is `pass` or explicitly `not_applicable` with evidence.
+
+## Do Not Ship If
+
+- the direction drifted away from the contract
+- the visual language mixes unrelated patterns
+- feedback/loading states still cause layout reflow or state confusion
+- the design relies on unsupported libraries or hidden runtime assumptions
+- the final answer claims parity or design quality that the browser evidence does not prove

package/skills/opendevbrowser-design-agent/artifacts/design-workflows.md

@@ -0,0 +1,153 @@
+# Design Workflows
+
+This file turns the design-agent skill into repeatable execution paths.
+
+## Workflow A — Contract-First Frontend Delivery
+
+Use when the task starts from a PRD, issue, or user request.
+
+1. Fill `assets/templates/design-brief.v1.md`.
+2. Translate the brief into `assets/templates/design-contract.v1.json`.
+3. Check `artifacts/opendevbrowser-ui-example-map.md` for nearby repo patterns worth reusing.
+4. If a nearby shipped surface exists, review `artifacts/existing-surface-adaptation.md` before changing shells or component anatomy.
+5. Pick the dominant screen family from `artifacts/component-pattern-index.md`.
+6. Declare shell and route ownership with `artifacts/app-shell-and-state-wiring.md`.
+7. Declare state ownership using `artifacts/state-ownership-matrix.md`.
+8. Declare navigation and deep-link ownership in the contract before route-changing controls are wired.
+9. Declare async and search ownership with `artifacts/async-search-state-ownership.md`.
+10. Declare theme and token ownership with `artifacts/theming-and-token-ownership.md`.
+11. Declare loading, empty/error, and transient feedback behavior with `artifacts/loading-and-feedback-surfaces.md`.
+12. If the surface is scan-heavy or pane-heavy, declare the performance posture with `artifacts/performance-audit-playbook.md` before implementation.
+13. If motion depends on scroll or pinned stages, add `artifacts/scroll-reveal-surface-planning.md` to the contract inputs.
+14. Confirm the contract answers:
+   - audience and task
+   - primary and secondary message
+   - route owner, deep-link policy, and invalid-route fallback
+   - async trigger, query ownership, and restart policy
+   - layout approach
+   - list identity and heavy-surface strategy
+   - theme and token source
+   - type system
+   - motion posture
+   - responsive rules
+   - accessibility target
+   - loading, empty, error, and transient feedback plan
+   - validation plan
+15. Review `artifacts/frontend-evaluation-rubric.md` and `artifacts/implementation-anti-patterns.md`.
+16. Implement the smallest coherent slice that satisfies the contract.
+17. Validate in an isolated fixture first, then in a real browser before declaring the work complete.
+
+## Workflow B — Screenshot Or Existing-Page Audit
+
+Use when a screenshot, mock, or live page is the starting point.
+
+1. Identify the visible structure:
+   - information hierarchy
+   - grid or container model
+   - spacing rhythm
+   - typography scale
+   - color, contrast, and token system
+   - interaction states
+   - loading and transient feedback surfaces
+2. Convert those observations into the shared design contract.
+3. Map the screen to one dominant family from `artifacts/component-pattern-index.md`.
+4. If the repo already ships a related shell or surface, review `artifacts/existing-surface-adaptation.md`.
+5. Flag gaps explicitly:
+   - unknown mobile behavior
+   - unknown route, deep-link, or invalid-param fallback behavior
+   - unknown query, filter, or sort ownership
+   - missing empty/loading/error states
+   - layout-shifting placeholders or spinner stacking
+   - unstable row or card identity under filtering, sorting, or refresh
+   - raw-value token drift across repeated components
+   - inaccessible focus treatment
+   - inconsistent spacing or type rules
+6. If search, async work, theming, transient feedback, or scroll-driven motion matter to the task, cross-check:
+   - `artifacts/async-search-state-ownership.md`
+   - `artifacts/theming-and-token-ownership.md`
+   - `artifacts/loading-and-feedback-surfaces.md`
+   - `artifacts/scroll-reveal-surface-planning.md`
+7. Check `artifacts/implementation-anti-patterns.md` for ownership or pattern drift traps.
+8. Record the audit in `assets/templates/design-audit-report.v1.md`.
+9. Implement changes only after the contract reflects the intended end state.
+
+## Workflow C — `/canvas` Contract-Governed Iteration
+
+Use when the work should flow through the OpenDevBrowser design canvas.
+
+1. Open a canvas session.
+2. Read the handshake and document context.
+3. Fill the full design contract.
+4. Extract the `generationPlan`.
+5. Send `canvas.plan.set`.
+6. Mutate with `canvas.document.patch`.
+7. Poll feedback and refresh preview until the contract and runtime match.
+
+Canonical command order:
+
+```bash
+npx opendevbrowser canvas --command canvas.session.open --params '{"requestId":"req_open_01","browserSessionId":"<browser-session-id>","documentId":null,"repoPath":null,"mode":"dual-track"}'
+npx opendevbrowser canvas --command canvas.plan.set --params-file ./tmp/canvas-plan.json
+npx opendevbrowser canvas --command canvas.document.patch --params-file ./tmp/canvas-patch.json
+npx opendevbrowser canvas --command canvas.feedback.poll --params '{"requestId":"req_feedback_01","canvasSessionId":"<canvas-session-id>","documentId":"<document-id>","targetId":"<target-id>","afterCursor":null}'
+npx opendevbrowser canvas --command canvas.preview.render --params '{"requestId":"req_preview_01","canvasSessionId":"<canvas-session-id>","leaseId":"<lease-id>","targetId":"<target-id>","projection":"canvas_html"}'
+```
+
+## Workflow D — Real-Surface Validation
+
+Use when design quality must be demonstrated, not inferred.
+
+1. Validate the final or intermediate UI in a real browser session.
+2. Validate the same state matrix in an isolated preview or fixture when the component family is still moving.
+3. Confirm the preview installs deterministic data and the same theme or token dependencies the real surface expects.
+4. If the interaction is scroll-driven, confirm the live surface still matches `artifacts/scroll-reveal-surface-planning.md`.
+5. Capture:
+   - snapshots for structure
+   - screenshots for visual output
+   - debug traces when behavior or styling is dynamic
+6. Confirm:
+   - expected layout at mobile, tablet, and desktop widths
+   - focus visibility and keyboard reachability
+   - loading, error, success, and empty states where relevant
+   - search, filter, or sort transitions do not surface stale or duplicated results
+   - no console or network regressions caused by the UI change
+7. If parity matters, repeat across supported surfaces before sign-off.
+
+## Workflow E — Performance Audit
+
+Use when the screen is visually correct but interaction quality is poor.
+
+1. Describe the slow interaction, viewport, and data size.
+2. Capture a baseline with the framework profiler or browser performance tooling.
+3. Use `artifacts/performance-audit-playbook.md` to classify the problem.
+4. If scroll progression is part of the issue, verify the single progress owner with `artifacts/scroll-reveal-surface-planning.md`.
+5. Record evidence and fixes in `assets/templates/design-audit-report.v1.md`.
+6. Re-measure before declaring the issue fixed.
+
+Recommended command sequence:
+
+```bash
+npx opendevbrowser launch --no-extension --start-url https://example.com
+npx opendevbrowser snapshot --session-id <session-id>
+npx opendevbrowser screenshot --session-id <session-id>
+npx opendevbrowser debug-trace-snapshot --session-id <session-id>
+```
+
+## Workflow F — Ship Audit
+
+Use after implementation and before final sign-off.
+
+1. Re-read the design contract.
+2. Compare the shipped output against the contract and the rubric.
+3. Re-check shell and route ownership against `artifacts/app-shell-and-state-wiring.md`.
+4. Re-check whether the work extended the nearest shipped surface appropriately with `artifacts/existing-surface-adaptation.md`.
+5. Re-check state and overlay ownership against `artifacts/state-ownership-matrix.md`.
+6. Re-check:
+   - `artifacts/async-search-state-ownership.md`
+   - `artifacts/theming-and-token-ownership.md`
+   - `artifacts/loading-and-feedback-surfaces.md`
+   - `artifacts/scroll-reveal-surface-planning.md`
+7. Re-scan `artifacts/implementation-anti-patterns.md` for any regressions introduced during polishing.
+8. Re-run the relevant skill validators.
+9. Update README, CLI docs, architecture docs, AGENTS, and skill docs if any user-visible behavior changed.
+10. Record blockers explicitly; do not convert uncertainty into a pass.

package/skills/opendevbrowser-design-agent/artifacts/existing-surface-adaptation.md

@@ -0,0 +1,56 @@
+# Existing Surface Adaptation
+
+Use this when the repo already has a nearby screen, shell, or component family and the goal is to evolve it instead of inventing a parallel UI language.
+
+## 1. Start With The Nearest Shipped Surface
+
+Before drafting a new structure:
+
+- read `artifacts/opendevbrowser-ui-example-map.md`
+- identify the closest shipped shell, editor, list/detail, or overlay pattern
+- inspect the existing state owner, route owner, and token owner before changing visuals
+
+If the repo already has the right family, extend it. Do not build a second shell that solves the same navigation or ownership problem.
+
+## 2. Read The Surface In This Order
+
+1. shell and route ownership
+2. state ownership and async ownership
+3. token and theme ownership
+4. component anatomy
+5. loading, empty, success, and error states
+6. preview or fixture coverage
+
+This keeps structural decisions ahead of styling polish.
+
+## 3. Reuse Before Recompose
+
+Prefer:
+
+- refining existing component anatomy
+- tightening spacing, hierarchy, and state handling
+- widening deterministic preview coverage
+- extracting a shared primitive only when two real surfaces need it
+
+Avoid:
+
+- forking a near-duplicate shell
+- replacing a working component family with a generic new one
+- moving ownership upward without a concrete cross-surface need
+
+## 4. Review Prompts
+
+Before implementation, answer:
+
+1. Which shipped surface is the closest reference?
+2. What should stay structurally stable?
+3. Which ownership boundary actually needs to move?
+4. Which visual or interaction debt is being corrected?
+5. Which preview or browser proof needs to be updated with the change?
+
+## Failure Signals
+
+- a new shell is introduced when an existing one already fits
+- component names and files diverge from the shipped family for cosmetic reasons
+- previews still prove only the old behavior after a real structural change
+- the work claims to preserve the design system while silently bypassing its token or state owners

package/skills/opendevbrowser-design-agent/artifacts/external-pattern-synthesis.md

@@ -0,0 +1,103 @@
+# External Pattern Synthesis
+
+This file captures the external patterns that shaped the OpenDevBrowser design-agent skill.
+
+## Official Anthropic Patterns
+
+Sources:
+
+- Claude Code subagents: https://docs.anthropic.com/en/docs/claude-code/sub-agents
+- Claude Code settings: https://docs.anthropic.com/en/docs/claude-code/settings
+
+Patterns carried into this skill:
+
+- keep the agent focused on one domain instead of making a general prompt larger
+- be explicit about tool access, scope, and success criteria
+- preload reusable expertise so repeated tasks are faster and more consistent
+- use concrete examples and deterministic workflows instead of vague stylistic advice
+
+## Official Vercel v0 Patterns
+
+Source:
+
+- v0 prompting guide: https://v0.dev/docs/prompting/text
+
+Patterns carried into this skill:
+
+- specify stack, layout intent, and UI constraints directly
+- describe structure, state, and interaction, not just mood adjectives
+- break large UI requests into staged prompts and refinements
+- include enough design detail that the system does not invent critical behavior
+- collect concrete visual references before direction lock instead of treating "modern" or "premium" as sufficient input
+
+## Official Lovable Patterns
+
+Source:
+
+- Lovable prompting best practices: https://docs.lovable.dev/prompting/prompting-best-practices
+
+Patterns carried into this skill:
+
+- use real content and real workflows whenever possible
+- prompt by component and user flow, not by abstract buzzwords
+- keep iterations narrow and intentional
+- write prompts that explain what should improve and why it matters
+- keep inspiration grounded in screenshots and product references instead of text-only taste claims
+
+## Public Frontend-Designer Agent Patterns
+
+Source:
+
+- Public claude-agents repository: https://github.com/iannuttall/claude-agents
+
+Patterns carried into this skill:
+
+- assess the current stack and available assets before proposing UI direction
+- turn observations into a repeatable design schema
+- include an explicit review and feedback loop
+- combine aesthetics, accessibility, and implementation practicality in the same agent
+- split work into analyze, specify, and generate phases so direction-setting and implementation stay distinct
+
+## Dimillian SwiftUI UI Pattern Library
+
+Source:
+
+- Dimillian Skills repo: https://github.com/Dimillian/Skills/tree/main
+- SwiftUI UI patterns skill: https://github.com/Dimillian/Skills/blob/main/swiftui-ui-patterns/SKILL.md
+
+Patterns carried into this skill:
+
+- keep a component and screen-pattern index so the agent starts from proven families instead of inventing a structure every time
+- start from the closest existing surface when the repo already ships the right family, then adapt instead of forking a parallel shell
+- declare state ownership before component implementation, especially for navigation, overlays, async data, and editing flows
+- keep route translation and deep-link handling centralized instead of spreading string-based navigation across controls
+- prefer item-driven or enum-driven sheet and overlay routing so modal state stays typed and recoverable
+- define async restart, debounce, and cancellation behavior explicitly when user input can restart work
+- keep search-query ownership narrow and make URL ownership deliberate instead of accidental
+- preserve layout during loading with deterministic placeholder counts instead of spinner-heavy state drift
+- keep one semantic theme or token source so leaf components stay visual consumers instead of token owners
+- use overlays for transient banners or toasts so feedback does not reflow the main layout
+- document app wiring and shell boundaries explicitly so route, overlay, and shared-service ownership stay coherent
+- treat isolated previews and deterministic fixtures as a required stop before full integration
+- keep a reusable performance-audit path with baseline measurement, symptom classification, and evidence-backed fixes
+- give scroll-reveal and pinned-stage UIs one explicit progress owner plus a reduced-motion contract
+- keep scan-heavy screens fast by deciding stable identity, lazy container posture, and progressive reveal before polishing each item
+- include explicit anti-patterns so the skill blocks weak implementation habits instead of only describing ideal outcomes
+- treat previews, examples, and isolated validation as part of frontend engineering, not optional polish
+- document app wiring concerns such as shells, routing depth, overlay ownership, scroll drivers, and performance restraint alongside visual direction
+
+## OpenDevBrowser-Specific Adaptation
+
+The external patterns above are not copied verbatim into this pack. They are adapted to OpenDevBrowser's shipped capabilities:
+
+- `/canvas` governance handshake and `canvas.plan.set`
+- extension, managed, and CDP-backed validation
+- repo-local docs and AGENTS sync requirements
+- repeated audit/fix loops before sign-off
+- real-browser proof instead of purely textual design claims
+- web-first component families in `artifacts/component-pattern-index.md`
+- explicit ownership decisions in `artifacts/state-ownership-matrix.md`
+- async and query ownership decisions in `artifacts/async-search-state-ownership.md`
+- semantic token ownership in `artifacts/theming-and-token-ownership.md`
+- loading and transient feedback discipline in `artifacts/loading-and-feedback-surfaces.md`
+- failure shields in `artifacts/implementation-anti-patterns.md`