Component Modernization
Productivitycomponent-modernizationComponent Modernization is an Agent Skill for productivity published in the podman-desktop/podman-desktop repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Prepare and execute Design System component modernization. Drafts GitHub subtask issues, applies the Storybook HMR patch, and guides the modernization workflow. Use when starting work on a new component modernization, creating subtask issues, or when the user mentions design system modernization.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/podman-desktop/podman-desktop/blob/HEAD/.agents/skills/component-modernization/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/component-modernization, 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.
Component Modernization Workflow
End-to-end workflow for modernizing a Podman Desktop UI component as part of the Design System Modernization initiative (#13479).
Step 1: Apply Storybook HMR patch
Before starting, apply the local HMR patch so Storybook hot-reloads when UI component source files change:
/usr/bin/git apply .agents/skills/storybook-hmr/patches/storybook-hmr.patch
If it fails due to upstream changes, use /storybook-hmr skill to regenerate.
Step 2: Draft subtask issues
For each component modernization epic, create two subtasks as GitHub issues (type: Task). The user files these manually - never use the GitHub MCP to create issues.
Subtask 1: Storybook stories
Title: Storybook: Add stories for \{ComponentName}` component**Label:**area/storybook`
Body template:
### Task content
Add comprehensive Storybook stories for the `{ComponentName}` component (`{component_path}`) to document all current behaviors and usage contexts.
- Parent: #{parent_issue}
### Stories to create
{story_list - tailored to the specific component, typically 4-6 stories covering:}
1. **Basic** - interactive controls
2. **Usage context stories** - mock real layouts where the component appears
3. **Accessibility** - ARIA attributes, HC support, reduced motion
4. **Comparison** (if applicable) - side-by-side with related components
### Notes
- Follow the `kind` dispatch pattern established in `ProgressBar.stories.svelte`
- Use CSS-variable Tailwind classes for theme compatibility across all 4 themes (light, dark, hc-light, hc-dark)
- Include `autodocs` tag for auto-generated documentation
- {import_note - relative path for renderer components, package import for ui-svelte components}
Subtask 2: Modernize component
Title: Modernize \{ComponentName}`**Label:**area/ui`
Body template:
### Task content
Modernize the `{ComponentName}` component (`{component_path}`) as part of the Design System Modernization initiative.
- Parent: #{parent_issue}
- Blocked by: {storybook_subtask_reference}
### Changes
1. {change_list - tailored to the specific component, typically covering:}
- Tailwind v4 syntax updates
- Color registry token usage (with HC support)
- ARIA / a11y improvements
- Animation updates
- Replace inline implementations with shared components
- Test updates
- Storybook annotation updates
### Key design decisions
{decisions - component-specific choices like rounded corners, dimensions, modes}
Step 3: Research the component
Before implementing, investigate:
- All usage sites - grep for imports and component usage across the codebase
- Color registry tokens - check which tokens exist and which need to be added
- Existing tests - understand current test coverage
- Related components - identify inline duplicates or related progress/loading indicators
- The parent epic - read the issue body for context and screenshots
Step 4: Implement
Follow this order:
- Storybook stories first - create comprehensive stories documenting current behavior
- Rebuild UI package -
pnpm --filter @podman-desktop/ui-svelte build - Component modernization - apply visual/a11y changes
- Update tests - match new structure
- Verify - run tests, check all 4 themes in Storybook, check in running app
Step 5: Before committing
- Revert the HMR patch:
git checkout -- storybook/vite.config.js - Run all checks:
pnpm lint-staged,pnpm test:ui,pnpm typecheck,pnpm lint:check - The user handles committing, pushing, and filing PRs
Reference: ProgressBar modernization
The completed ProgressBar modernization (#16244) is the reference implementation:
- Stories PR: #17417 - comprehensive Storybook stories with
kinddispatch pattern - Move PR: #17424 - moved from renderer to UI package (if applicable)
- Modernize PR: #17422 - visual/a11y modernization
Key patterns established:
- Neutral stone palette with full HC support (hcDark/hcLight)
- WAI-ARIA attributes on
role="progressbar"elements - High-contrast guide lines (transparent in normal, visible in HC)
- Outline borders for definition
prefers-reduced-motionsupport- Tailwind v4 CSS variable shorthand syntax