PSA/ee/docs/plans/2026-02-04-ui-kit-showcase-extension/PRD.md

PRD: UI Kit Showcase Extension

Problem Statement

Extension developers need a reference implementation demonstrating all UI kit components (@alga/ui-kit) with their variants, states, and usage patterns. Currently there is no comprehensive example showing how to use the full component library within an extension context.

Additionally, the UI kit uses --alga-* CSS variables while the main app uses --color-* variables, causing theming inconsistencies. A theme bridge is needed to ensure UI kit components render correctly within the host application.

Goals

1. Create a sample extension that showcases every UI kit component
2. Demonstrate all variants, sizes, and states for each component
3. Provide interactive examples that developers can reference
4. Create a theme bridge mapping --alga-* to --color-* variables
5. Serve as a living documentation and testing ground for the UI kit

Non-Goals

• Production use case functionality (this is purely a demo)
• Backend/handler logic beyond minimal scaffolding
• Persisting any data
• Authentication or authorization flows

Target Users

• Extension developers building on Alga PSA
• Internal developers testing UI kit components
• QA engineers validating component behavior

Primary Flows

Flow 1: Browse Component Categories

User opens the extension → sees tabbed navigation with categories:

• Core: Button, Input, CustomSelect, Card, Alert, Text, Stack, Badge
• Data: DataTable
• Dialogs: Dialog, ConfirmDialog
• Feedback: Spinner, LoadingIndicator, Tooltip, Progress, Skeleton
• Form: Checkbox, Switch, TextArea, Label, SearchInput
• Navigation: Tabs, Drawer, DropdownMenu

Flow 2: Interact with Component Demo

User selects a component → sees:

1. Live interactive example
2. All variants displayed (e.g., Button: primary, secondary, ghost, danger)
3. All sizes displayed (e.g., sm, md, lg)
4. All states (disabled, loading, error, etc.)
5. Props control panel to toggle options in real-time

Flow 3: Theme Preview

User toggles theme → components update to show light/dark mode rendering via the theme bridge.

UX/UI Notes

Layout Structure

┌─────────────────────────────────────────────────┐
│  UI Kit Showcase                    [Theme Toggle] │
├─────────────────────────────────────────────────┤
│ [Core] [Data] [Dialogs] [Feedback] [Form] [Nav] │
├─────────────────────────────────────────────────┤
│                                                 │
│  Component Name                                 │
│  ─────────────────                              │
│                                                 │
│  ┌─────────────────────────────────────────┐   │
│  │  Live Demo Area                         │   │
│  │  (Interactive component examples)       │   │
│  └─────────────────────────────────────────┘   │
│                                                 │
│  Variants                                       │
│  ─────────                                      │
│  [primary] [secondary] [ghost] [danger]        │
│                                                 │
│  Sizes                                          │
│  ─────                                          │
│  [sm] [md] [lg]                                 │
│                                                 │
│  States                                         │
│  ──────                                         │
│  ☐ Disabled  ☐ Loading                         │
│                                                 │
└─────────────────────────────────────────────────┘

Component Sections

Each component demo section includes:

• Title with component name
• Description of component purpose
• Live examples showing the component in action
• Variant showcase showing all style variants
• Size showcase showing all size options
• State toggles for interactive state changes

Technical Approach

Extension Structure

ee/extensions/samples/ui-kit-showcase/
├── manifest.json
├── package.json
├── tsconfig.json
├── vite.iframe.config.ts
├── ui/
│   └── index.html
└── src/
    ├── iframe/
    │   └── main.tsx           # Entry point
    ├── components/
    │   ├── ThemeBridge.tsx    # CSS variable mapping
    │   ├── DemoSection.tsx    # Reusable demo wrapper
    │   └── PropsPanel.tsx     # Interactive props control
    └── demos/
        ├── ButtonDemo.tsx
        ├── InputDemo.tsx
        ├── SelectDemo.tsx
        ├── CardDemo.tsx
        ├── AlertDemo.tsx
        ├── TextDemo.tsx
        ├── StackDemo.tsx
        ├── BadgeDemo.tsx
        ├── DataTableDemo.tsx
        ├── DialogDemo.tsx
        ├── SpinnerDemo.tsx
        ├── TooltipDemo.tsx
        ├── ProgressDemo.tsx
        ├── SkeletonDemo.tsx
        ├── CheckboxDemo.tsx
        ├── SwitchDemo.tsx
        ├── TextAreaDemo.tsx
        ├── LabelDemo.tsx
        ├── SearchInputDemo.tsx
        ├── TabsDemo.tsx
        ├── DrawerDemo.tsx
        └── DropdownMenuDemo.tsx

Theme Bridge Implementation

The theme bridge will:

1. Map --color-* variables from the host app to --alga-* variables
2. Listen for theme changes (light/dark mode)
3. Apply mappings via a <style> element or CSS custom property overrides

// ThemeBridge.tsx - Conceptual implementation
const themeMapping = {
  '--alga-bg': 'var(--color-background)',
  '--alga-fg': 'var(--color-text-900)',
  '--alga-border': 'var(--color-border-200)',
  '--alga-primary': 'var(--color-primary-500)',
  '--alga-primary-foreground': '#ffffff',
  '--alga-muted': 'var(--color-border-100)',
  '--alga-muted-fg': 'var(--color-text-500)',
  '--alga-danger': 'var(--color-accent-red)',
  '--alga-warning': 'var(--color-accent-orange)',
  '--alga-success': 'var(--color-accent-green)',
  '--alga-radius': '6px',
};

Dependencies

• @alga/ui-kit (linked via file reference)
• react, react-dom
• react-router-dom (for potential future navigation)

Components to Showcase

Category	Components	Key Variants/Props
Core	Button	variant: primary/secondary/ghost/danger, size: sm/md/lg
Core	Input	disabled, placeholder
Core	CustomSelect	options, placeholder, disabled
Core	Card	children, style
Core	Alert	tone: info/success/warning/danger
Core	Text	as, size, weight, color
Core	Stack	direction, gap, align, justify
Core	Badge	tone: default/success/warning/danger/info
Data	DataTable	columns, pagination, sorting, responsiveColumns
Dialogs	Dialog	open, onClose, title
Dialogs	ConfirmDialog	onConfirm, onCancel, danger
Feedback	Spinner	size
Feedback	LoadingIndicator	text
Feedback	Tooltip	content, position: top/bottom/left/right
Feedback	Progress	value, variant: default/striped/animated, size
Feedback	Skeleton	variant, width, height, animation
Form	Checkbox	checked, indeterminate, label, disabled
Form	Switch	checked, size: sm/md/lg, disabled
Form	TextArea	rows, resize, disabled
Form	Label	required, size
Form	SearchInput	debounceMs, loading, showClear, size
Navigation	Tabs	variant: default/pills/underline, disabled tabs
Navigation	Drawer	position: left/right/top/bottom, size: sm/md/lg/full
Navigation	DropdownMenu	items, align: left/right, dividers

Risks & Mitigations

Risk	Mitigation
Theme bridge may not cover all edge cases	Start with core mappings, iterate based on visual testing
Extension iframe isolation may affect styling	Test thoroughly in actual extension context
Component updates may break demos	Keep demos simple, update alongside UI kit changes

Acceptance Criteria

1. Extension installs and loads in Alga PSA
2. All 22 UI kit components are demonstrated
3. Each component shows all variants and sizes
4. Interactive controls allow state changes
5. Theme bridge correctly maps CSS variables
6. Light/dark theme switching works
7. Extension serves as valid reference for developers

Open Questions

• Should demos include code snippets? → No, keep simple for v1
• Should we add search/filter for components? → Nice to have, not required for v1