From c92a9e9e88ca8b253acd4d4c04b7119d4961c14e Mon Sep 17 00:00:00 2001 From: Brian Date: Wed, 1 Apr 2026 22:50:33 -0400 Subject: [PATCH] docs: update code guidelines and add UI component skill Add UI development guidelines covering color-registry usage, Icon component from @podman-desktop/ui-svelte, and component reuse priorities. Adds a new .agents/skills/ui-components/ skill for detailed reference. Addresses feedback from PR #1205 review (benoitf, gastoner). Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Brian --- .agents/skills/ui-components/SKILL.md | 162 ++++++++++++++++++++++++++ AGENTS.md | 2 + CODE-GUIDELINES.md | 95 +++++++++++++++ 3 files changed, 259 insertions(+) create mode 100644 .agents/skills/ui-components/SKILL.md diff --git a/.agents/skills/ui-components/SKILL.md b/.agents/skills/ui-components/SKILL.md new file mode 100644 index 0000000000..7674778166 --- /dev/null +++ b/.agents/skills/ui-components/SKILL.md @@ -0,0 +1,162 @@ +# UI Component Development Guide for Kortex + +## Core Rules + +### 1. Check `@podman-desktop/ui-svelte` before building from scratch + +Before creating any new UI component, **always check `@podman-desktop/ui-svelte` first**. This is the shared component library that Kortex builds on. Only build custom components when nothing in this library fits. + +**Available components from `@podman-desktop/ui-svelte`:** + +| Component | Purpose | +| ------------------------------------------------------------------------------ | ------------------- | +| `Button`, `CloseButton`, `Expandable` | Button variants | +| `Input`, `NumberInput`, `SearchInput` | Form inputs | +| `Checkbox` | Checkboxes | +| `Dropdown`, `DropdownMenu` | Selection menus | +| `Table`, `TableColumn`, `TableRow`, `TableSimpleColumn`, `TableDurationColumn` | Data tables | +| `DetailsPage`, `FormPage`, `NavPage`, `Page` | Page layouts | +| `Modal` | Modal dialogs | +| `Tab` | Tab navigation | +| `Tooltip` | Tooltips | +| `Link` | Styled links | +| `Spinner`, `LinearProgress` | Loading indicators | +| `StatusIcon` | Status indicators | +| `EmptyScreen`, `FilteredEmptyScreen` | Empty state views | +| `ErrorMessage` | Error alerts | +| `Carousel` | Carousel | +| `ListOrganizer` | List management | +| `SettingsNavItem` | Settings navigation | + +**Icons** are available from `@podman-desktop/ui-svelte/icons` (see rule 3 below). + +**Priority order when building UI:** + +1. Use a component from `@podman-desktop/ui-svelte` +2. Use an existing Kortex shared component (see rule 4) +3. Extend an existing component if close but not quite right +4. Only build from scratch as a last resort + +### 2. Never use Tailwind colors directly + +**Never use raw Tailwind color classes** like `bg-red-500`, `text-gray-700`, `border-blue-300`, etc. + +Always use CSS variables from the color-registry so that values can be tuned by themes (light/dark mode and custom themes). + +Format: `[var(--pd-)]` + +```svelte + +
...
+ + +
...
+``` + +Non-color Tailwind utilities (layout, spacing, sizing, typography, borders, effects) are fine. + +### 3. Use the Icon component for all icons + +Use the `Icon` component from `@podman-desktop/ui-svelte/icons` instead of inline SVGs, custom icon wrappers, or direct `` usage. + +```svelte + + + + + + + + + + +``` + +The Icon component supports: + +- FontAwesome `IconDefinition` objects (via `` internally) +- Font class icon strings (`fas fa-*`, `far fa-*`, `fab fa-*`, or `-icon` suffix) +- Data URI images (strings starting with `data:image/`) +- Svelte Components + +### 4. Reuse existing Kortex Svelte components + +If `@podman-desktop/ui-svelte` doesn't have what you need, check Kortex's own shared components before building from scratch: + +**Primary shared component locations:** + +- `packages/renderer/src/lib/ui/` — Core UI components (~50 components) +- `packages/renderer/src/lib/button/` — Button components +- `packages/renderer/src/lib/table/` — Table components +- `packages/renderer/src/lib/modal/` — Modal dialogs +- `packages/renderer/src/lib/forms/` — Form components +- `packages/renderer/src/lib/dialogs/` — Dialog components +- `packages/renderer/src/lib/appearance/` — Theme/appearance components + +**Key reusable components include:** + +| Component | File | Purpose | +| ----------------- | ------------------------------- | ---------------------------- | +| `Badge` | `lib/ui/Badge.svelte` | Status badges and labels | +| `Button` | `lib/button/Button.svelte` | Standard buttons | +| `DetailsPage` | `lib/ui/DetailsPage.svelte` | Detail view layouts | +| `FormPage` | `lib/ui/FormPage.svelte` | Form page layouts | +| `Label` | `lib/ui/Label.svelte` | Form labels | +| `SlideToggle` | `lib/ui/SlideToggle.svelte` | Toggle switches | +| `Typeahead` | `lib/ui/Typeahead.svelte` | Autocomplete inputs | +| `StatusDot` | `lib/ui/StatusDot.svelte` | Status indicators | +| `Steps` | `lib/ui/Steps.svelte` | Step-by-step wizards | +| `WarningMessage` | `lib/ui/WarningMessage.svelte` | Warning banners | +| `FileInput` | `lib/ui/FileInput.svelte` | File upload inputs | +| `PasswordInput` | `lib/ui/PasswordInput.svelte` | Password fields | +| `CopyToClipboard` | `lib/ui/CopyToClipboard.svelte` | Clipboard copy functionality | + +Always search for existing components before creating new ones. If an existing component is close but not quite right, prefer extending it over duplicating it. + +## How the Color Registry Works + +Colors are defined in `packages/main/src/plugin/color-registry.ts` in the `initColors()` method, organized by category. + +### Finding the right color variable + +1. Open `packages/main/src/plugin/color-registry.ts` +2. Find the appropriate category in `initColors()` (e.g. `initButton()`, `initInput()`, `initTable()`) +3. Each category has a prefix constant (e.g. `const button = 'button-';`) +4. The CSS variable name is `--pd-` + prefix + specific name + +### Common color categories and prefixes + +| Category | Prefix | Example variable | Usage | +| ---------- | -------------- | ------------------------ | ---------------------- | +| Content | `content-` | `--pd-content-bg` | Page backgrounds, text | +| Button | `button-` | `--pd-button-primary-bg` | Button colors | +| Input | `input-field-` | `--pd-input-field-bg` | Form input colors | +| Table | `table-` | `--pd-table-header-bg` | Table styling | +| Modal | `modal-` | `--pd-modal-bg` | Modal dialogs | +| Card | `card-` | `--pd-card-bg` | Card components | +| Tab | `tab-` | `--pd-tab-active-bg` | Tab navigation | +| Status | `status-` | `--pd-status-running` | Status indicators | +| Navigation | `global-nav-` | `--pd-global-nav-bg` | Navigation bars | + +### Example: Styling a new component + +```svelte + + +
+

Title

+

Description

+ + +
+``` diff --git a/AGENTS.md b/AGENTS.md index 296bdd9a04..2e755973f8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -123,6 +123,8 @@ pnpm run test:watch For detailed Playwright E2E testing guidance (Page Object Model, fixtures, locator conventions, examples), see `.agents/skills/playwright-testing/`. +For UI component development guidelines (color-registry usage, Icon component, reusable components), see `.agents/skills/ui-components/` and `CODE-GUIDELINES.md`. + ### Code Quality ```bash diff --git a/CODE-GUIDELINES.md b/CODE-GUIDELINES.md index aac1f17596..b0f5ac1483 100644 --- a/CODE-GUIDELINES.md +++ b/CODE-GUIDELINES.md @@ -19,6 +19,101 @@ import { WinPlatform } from './win-platform'; import type { WSL2Check } from '../checks/windows/wsl2-check'; ``` +### UI Colors + +Never use raw Tailwind color classes (e.g. `bg-red-500`, `text-gray-700`, `border-blue-300`) directly. Always use CSS variables from the color-registry so values can be tuned by themes (light/dark mode and custom themes). + +Format: `[var(--pd-)]` + +✅ **Use this pattern:** + +```svelte +
...
+