/sync-ui-state-with-urls

When to use it

The skill is meant to be pulled in when one of these conditions is true.

• A modal, drawer, inspector, or detail panel contains content people need to share or revisit.
• Refresh, direct entry, back, or close behavior feels unpredictable.
• Desktop and mobile need different presentations of the same content.
• UI state is important but trapped in component memory.

Start by asking

These questions keep the work from jumping straight to implementation details.

• Which states represent meaningful content or workflow?
• Which states are temporary presentation and should stay local?
• What happens on direct entry, refresh, back, close, and mobile?
• Where should focus go when the state opens and closes?
• Can the content render as a full page if the overlay pattern is unavailable?

Universal principal-level checks

Every skill should carry these concerns, even when the immediate request sounds narrower.

Skill-specific considerations

Process

Deliver

• A state classification map.
• A route model and fallback page behavior.
• A focus, scroll, and close-behavior plan.
• A list of states that should deliberately remain local.

Failure modes

These are the quiet ways the work can look finished while still being risky.

• The URL opens an empty overlay because it depends on previous page state.
• Back navigation closes the wrong layer or loses unsaved work.
• Mobile renders a desktop overlay that traps content off screen.

Avoid

• Putting every hover, tab, tooltip, or menu state in the URL.
• Building separate overlay and page implementations that drift.
• Closing overlays by destroying route history unpredictably.

Verify before finishing

• Does a copied URL open the meaningful state?
• Does refresh keep the user somewhere useful?
• Do close, back, escape, and mobile entry all have deliberate behavior?

Prompt to copy

Paste this into an AI session when you want the model to apply the full skill instead of giving a shallow answer.

Use this skill: /sync-ui-state-with-urls.
Title: Sync UI state with URLs

Goal: Give important UI states durable URLs so navigation, sharing, refresh, and mobile layouts stay coherent.

Frame: Use this skill when interface state has enough meaning that it should survive navigation. The goal is to make routing, presentation, and accessibility agree across overlays, pages, drawers, tabs, inspectors, and mobile views.

Universal principal-level considerations:
- Product intent
  - Name the user, operator, developer, or business outcome the work protects.
  - Separate what the system must do from how the current implementation happens to do it.
  - Identify the smallest useful improvement and the larger direction it should not block.
- Ownership and boundaries
  - Decide which layer owns policy, presentation, transport, persistence, validation, and side effects.
  - Make shared abstractions explicit about what they own and what they leave to the caller.
  - Prefer boundaries that reduce repeated decisions without hiding important context.
- Data and state integrity
  - Define the source of truth, derived state, cached state, temporary state, and persisted state.
  - Handle missing, stale, partial, conflicting, duplicated, and invalid data deliberately.
  - Keep transformations close to system boundaries so product code does not accumulate guesses.
- Security, privacy, and abuse
  - Treat external input, user-provided values, remote resources, generated output, and stored content as untrusted.
  - Avoid leaking internal identifiers, sensitive defaults, private routes, tokens, or implementation details.
  - Consider who can trigger expensive, destructive, or externally visible behavior.
- Accessibility and comprehension
  - Check semantic structure, accessible names, focus order, keyboard behavior, contrast, and reduced-motion behavior.
  - Write states and errors so a user can understand what happened and what to do next.
  - Make important information available without relying only on color, animation, hover, or layout position.
- Performance and scale
  - Identify work that runs per request, per render, per item, per file, per route, or per user action.
  - Avoid moving repeated work into a shared abstraction if that also hides expensive behavior.
  - Plan for growth in records, tenants, users, routes, generated files, and integration consumers.
- Reliability and operations
  - Design for retries, partial failure, timeouts, idempotency, rollback, reconciliation, and observability.
  - Make failures explain what broke, who is affected, and what should be inspected next.
  - Leave an audit trail for changes that affect access, content, billing, data, publishing, or public behavior.
- Testing and release
  - Test the contract, not only the implementation detail.
  - Cover role, permission, plan, device, theme, and failure-state differences when they change behavior.
  - Add preflight checks for generated files, configuration, fixtures, migrations, and runtime definitions.
- Documentation and handoff
  - Document decisions, tradeoffs, naming rules, escape hatches, and cleanup conditions.
  - Write for the next person who has to extend, debug, or remove the system.
  - Keep examples small enough to trust and realistic enough to reuse.
- Maintenance and reversibility
  - Prefer changes that can be migrated incrementally and rolled back safely.
  - Name temporary decisions and set conditions for removing them.
  - Watch for abstractions that become permanent because nobody knows what they were originally solving.

Use this when:
- A modal, drawer, inspector, or detail panel contains content people need to share or revisit.
- Refresh, direct entry, back, or close behavior feels unpredictable.
- Desktop and mobile need different presentations of the same content.
- UI state is important but trapped in component memory.

Start by asking:
- Which states represent meaningful content or workflow?
- Which states are temporary presentation and should stay local?
- What happens on direct entry, refresh, back, close, and mobile?
- Where should focus go when the state opens and closes?
- Can the content render as a full page if the overlay pattern is unavailable?

Skill-specific considerations:
- Navigation contract
  - Define open, close, back, refresh, direct-entry, and copied-link behavior.
  - Avoid creating URLs for purely temporary UI decoration.
  - Make the fallback page useful without relying on the previous page context.
- Accessibility
  - Give overlays accessible names and predictable focus entry.
  - Return focus when closing only when the previous trigger still exists.
  - Ensure keyboard users can leave the state without losing work.
- Responsive behavior
  - Let the same route use an overlay on large screens and a page on small screens.
  - Preserve scroll position and data loading across layout changes.
  - Avoid duplicating content logic for each presentation.

Process:
- Classify
  - Sort states into addressable, local, derived, and ephemeral groups.
  - Choose route-backed state only when it improves continuity or sharing.
- Model
  - Write a behavior table for open, close, back, refresh, direct entry, and mobile.
  - Define data loading and error behavior for each entry path.
- Verify
  - Test the route by clicking, direct loading, refreshing, and using browser back.
  - Check focus, scroll restoration, reduced motion, and small-screen layout.

Deliver:
- A state classification map.
- A route model and fallback page behavior.
- A focus, scroll, and close-behavior plan.
- A list of states that should deliberately remain local.

Watch for failure modes:
- The URL opens an empty overlay because it depends on previous page state.
- Back navigation closes the wrong layer or loses unsaved work.
- Mobile renders a desktop overlay that traps content off screen.

Avoid:
- Putting every hover, tab, tooltip, or menu state in the URL.
- Building separate overlay and page implementations that drift.
- Closing overlays by destroying route history unpredictably.

Verify before finishing:
- Does a copied URL open the meaningful state?
- Does refresh keep the user somewhere useful?
- Do close, back, escape, and mobile entry all have deliberate behavior?