OpenParable
Skip to content
← Back to skills

Prototype

Design
prototype

Prototype is an Agent Skill for design published in the podman-desktop/podman-desktop repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Set up or tear down the UX prototype screen switcher in the Podman Desktop titlebar. Use when the user wants to start a new UI/UX prototype, add prototype screen states, or remove the prototype infrastructure after a prototype ships. Triggers: "set up a prototype", "new prototype", "prototype switcher", "remove prototype", "tear down prototype".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/podman-desktop/podman-desktop/blob/HEAD/.agents/skills/prototype-switcher/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/prototype, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

UX Prototype Screen Switcher

Manages reusable prototype infrastructure that adds a screen switcher dropdown to the Podman Desktop window titlebar. Each prototype defines named screens with typed override data and optional timed phase transitions.

When invoked

Determine what the user needs:

  1. Set up - install the infrastructure files and help wire a new prototype
  2. Tear down - remove the infrastructure after a prototype ships

Set up

Step 1 - Install infrastructure files

Check whether these files already exist. If they do, skip to Step 2.

  1. Create the store at packages/renderer/src/stores/prototype.ts Copy the contents from references/prototype-store.ts (in this skill's directory).

  2. Create the selector at packages/renderer/src/lib/ui/PrototypeSelector.svelte Copy the contents from references/PrototypeSelector.svelte (in this skill's directory).

  3. Patch TitleBar at packages/renderer/src/lib/ui/TitleBar.svelte

    • Add import: import PrototypeSelector from './PrototypeSelector.svelte'; (place it alphabetically among the relative imports, after any /@/ imports)
    • In the <!-- right --> section, add items-center to the div's classes (skip if the class is already present)
    • Add <PrototypeSelector /> as the first child of that div, before WindowControlButtons

    The right section should look like:

    <!-- right -->
    <div class="flex flex-row grow justify-end items-center">
      <PrototypeSelector />
      {#if platform !== 'darwin'}
        <WindowControlButtons platform={platform} />
      {/if}
    </div>
    

Step 2 - Wire the prototype

Ask the user for:

  • Prototype name - short title shown in the titlebar (e.g. "Badge visibility")
  • Screens - list of named states to switch between
  • Override shape - what data each screen provides to the consuming component
  • Timelines (optional) - which screens have timed phase transitions

Then create the registration in the appropriate component. Pattern:

import { onDestroy } from 'svelte';

import { registerPrototype, unregisterPrototype } from '/@/stores/prototype';

interface MyOverride {
  // the user's override shape
}

const override = registerPrototype<MyOverride>({
  name: 'Prototype name here',
  screens: [
    { value: 'idle', label: 'Idle state' },
    { value: 'active', label: 'Active state' },
  ],
  overrides: {
    idle: {
      /* ... */
    },
    active: {
      /* ... */
    },
  },
});

onDestroy(unregisterPrototype);

To consume the override reactively in the component:

let currentState: MyOverride | undefined;
const unsubscribe = override.subscribe(value => {
  currentState = value;
});
onDestroy(unsubscribe);

Phase transitions

For screens that should auto-advance through phases on a timer, add timelines and phase-keyed overrides using the screenValue:phaseNumber convention:

registerPrototype({
  // ...
  overrides: {
    animated: { status: 'starting' }, // phase 0 (default)
    'animated:1': { status: 'running' }, // phase 1 (after 3s)
    'animated:2': { status: 'complete' }, // phase 2 (after 8s)
  },
  timelines: {
    animated: [
      { delay: 3000, phase: 1 },
      { delay: 8000, phase: 2 },
    ],
  },
});

Step 3 - Verify

  1. Run pnpm typecheck:renderer - should pass with 0 errors
  2. Run pnpm lint:check - no new errors in the changed files
  3. Run pnpm watch - confirm the titlebar shows the selector when the prototype is registered

Tear down

When a prototype has shipped as a real feature and the switcher is no longer needed:

  1. Remove registerPrototype() / unregisterPrototype() calls from the prototype's component(s)

  2. Remove the prototype's override interface and config object

  3. Check if any other prototype still uses the infrastructure:

    grep -r "registerPrototype\|unregisterPrototype" packages/renderer/src/ --include="*.ts" --include="*.svelte"
    
  4. If no other prototype uses it, remove the infrastructure:

    • Delete packages/renderer/src/stores/prototype.ts
    • Delete packages/renderer/src/lib/ui/PrototypeSelector.svelte
    • Revert packages/renderer/src/lib/ui/TitleBar.svelte:
      • Remove the PrototypeSelector import
      • Remove <PrototypeSelector /> from the right section
      • Remove items-center from the right section div
  5. Verify clean removal:

    grep -r "prototype" packages/renderer/src/stores/ --include="*.ts"
    grep -r "PrototypeSelector" packages/renderer/src/ --include="*.svelte"
    grep -r "registerPrototype\|unregisterPrototype" packages/renderer/src/
    

    All three should return zero results.


Branch hygiene

The infrastructure files (prototype.ts, PrototypeSelector.svelte) and TitleBar patch live in real production paths. They should only be committed to a prototype feature branch, never to main. When the prototype work is done:

  • If the files were committed: use tear-down above, then commit the removals.
  • If the files were never committed: git checkout -- <path> or delete from the working tree before opening a PR.