---
type: ai-agent-documentation
version: 2.0
audience: ai-coding-agents-only
style: exact-patterns
human-readable: false
attributes-reference: /docs/ATTRIBUTES.md
---
# PM7-UI: Technical Documentation for AI Coding Agents
DEFINITION: PM7-UI is a framework-agnostic UI component library built with pure CSS and vanilla JavaScript, offering full TypeScript support. It is optimized for AI agents to generate UI components efficiently.
## 🚨 CRITICAL USAGE RULE: NPM PACKAGE ONLY
**MANDATORY**: You MUST use PM7-UI EXCLUSIVELY via the official npm package `@pm7/core`.
**FORBIDDEN ACTIONS**:
- ❌ NEVER use local file paths like `file:../../../pm7-ui`
- ❌ NEVER import from local PM7-UI development folders
- ❌ NEVER access PM7-UI source files directly
- ❌ NEVER assume you have access to the PM7-UI repository
**REQUIRED MINDSET**: You are a 3rd party developer with NO access to PM7-UI source code. You can ONLY use what is publicly available via npm.
**ENFORCEMENT**: Any attempt to use local PM7-UI files is a CRITICAL ERROR that must be immediately corrected by installing the npm package instead.
## 🚨🚨🚨 CRITICAL VERSION REQUIREMENT 🚨🚨🚨
**MANDATORY FIRST STEP**: ALWAYS check and update to the LATEST version of @pm7/core before ANY debugging or implementation!
```bash
# ALWAYS run this FIRST when working with PM7-UI:
npm list @pm7/core # Check current version
npm update @pm7/core # Update to latest version
# or
npm install @pm7/core@latest
```
**WHY THIS IS CRITICAL**:
- Old versions may lack essential features (e.g., `initFramework()` was added in v2.x)
- Bug fixes and improvements are released regularly
- Framework integration features evolve rapidly
- Using an outdated version WILL cause problems that waste hours of debugging
**REAL EXAMPLE**: A dialog rendering issue that took hours to debug was instantly solved by updating from v1.1.4 to v2.7.1.
**RULE**: If ANY PM7-UI component doesn't work as documented, your FIRST action must be to check and update the version!
## Installation
### NPM/Yarn/PNPM (ONLY APPROVED METHOD)
```bash
npm install @pm7/core
# or
yarn add @pm7/core
# or
pnpm add @pm7/core
```
**IMPORTANT**: If you see `"@pm7/core": "file:..."` in package.json, this is WRONG and must be replaced with the npm version.
### CDN
```html
```
## CSS Import
REQUIRED: Import the CSS file once in your project.
```javascript
// ES modules (React, Vue, etc.)
import '@pm7/core/dist/pm7.css';
// Vanilla HTML
```
## JavaScript Initialization
PM7-UI components are initialized automatically when the main JavaScript file (`pm7.js`) is loaded and the DOM is ready. For dynamically added components, `window.PM7.init()` must be called.
```javascript
// Auto-initialization (recommended for most cases)
import '@pm7/core'; // This imports and runs the initialization script
// For components added to the DOM after initial page load
window.PM7.init();
// For framework-specific re-initialization (includes self-healing)
window.PM7.initFramework();
```
## CSS Naming Convention
PM7-UI uses a modified BEM-like naming convention:
- **Base classes**: `pm7-[component]` (e.g., `pm7-button`, `pm7-menu`)
- **Sub-elements**: `pm7-[component]-[element]` with single dashes (e.g., `pm7-menu-trigger`, `pm7-menu-item`)
- **Modifiers**: `pm7-[component]--[modifier]` with double dashes (e.g., `pm7-button--primary`, `pm7-input--sm`)
### Rules for Naming Convention
- **ALWAYS**: Use `pm7-` prefix for all PM7-UI classes.
- **ALWAYS**: Use single dashes (`-`) for sub-elements.
- **ALWAYS**: Use double dashes (`--`) for modifiers.
- **NEVER**: Use double underscores (`__`) for any part of the class name.
## Components Requiring JavaScript
Most PM7-UI components are CSS-only. The following components require JavaScript for their interactive functionality:
- **Accordion** (`[data-pm7-accordion]`) - Collapsible panels
- **Dialog** (`[data-pm7-dialog]`) - Modal overlays
- **Menu** (`[data-pm7-menu]`) - Dropdown menus
- **Sidebar** (`[data-pm7-sidebar]`) - Navigation panels
- **Tab Selector** (`[data-pm7-tab-selector]`) - Tab switching
- **Theme Switch** (`[data-pm7-theme-switch]`) - Theme toggling
- **Toast** (via `showToast()` function) - Non-blocking notifications
- **Tooltip** (`[data-pm7-tooltip]`) - Contextual popovers
## Self-Healing Components (v2.5.0+)
All interactive PM7-UI components automatically detect and recover from framework re-renders (e.g., in React, Vue, Angular). This eliminates the need for manual re-initialization workarounds.
### How Self-Healing Works
1. Components detect when their DOM elements have been re-rendered by a framework.
2. Their internal state (e.g., open/closed, active tab) is automatically preserved.
3. Event listeners are cleaned up and re-attached to the new DOM elements.
4. The component restores its previous state, ensuring seamless user experience.
### Manual Healing (for advanced use cases)
```javascript
// Heal all components of all types
window.PM7.heal();
// Heal specific component types
window.PM7.healMenus();
window.PM7.healAccordions();
window.PM7.healTabSelectors();
window.PM7.healTooltips();
window.PM7.healSidebars();
```
## Dark Mode Support
PM7-UI provides comprehensive dark mode support with a built-in `ThemeSwitch` component and flicker-free theme switching.
### Flicker Prevention Script
CRITICAL: This script MUST be placed in the `` of your HTML, BEFORE any stylesheets, to prevent a flash of unstyled content when switching to dark mode.
```html
```
### Dark Mode Best Practices
- **ALWAYS**: Use PM7-UI's CSS variables (e.g., `--pm7-surface`, `--pm7-foreground`) for all colors in your application to ensure consistent theming.
- **NEVER**: Hardcode color values (e.g., `background: white; color: #000;`) in your CSS or inline styles.
## Global JavaScript Functions
Some components expose global functions on the `window` object for convenience.
| Function | Component | Parameters | Returns | Description |
|---|---|---|---|---|
| `window.openDialog` | Dialog | `id: string` | `void` | Opens a specific dialog. |
| `window.closeDialog` | Dialog | `id: string` | `void` | Closes a specific dialog. |
| `window.closeAllDialogs` | Dialog | `(none)` | `void` | Closes all open dialogs. |
| `window.showToast` | Toast | `options: ToastOptions` | `string` | Displays a new toast notification. |
| `window.closeToast` | Toast | `id: string` | `void` | Closes a specific toast. |
| `window.closeAllToasts` | Toast | `(none)` | `void` | Closes all toasts. |
## Component Documentation Links
For detailed documentation on specific components, refer to their individual `README.md` files:
- [Accordion](packages/core/src/components/accordion/README.md)
- [Button](packages/core/src/components/button/README.md)
- [Card](packages/core/src/components/card/README.md)
- [Dialog](packages/core/src/components/dialog/README.md)
- [Input](packages/core/src/components/input/README.md)
- [Menu](packages/core/src/components/menu/README.md)
- [Sidebar](packages/core/src/components/sidebar/README.md)
- [Tab Selector](packages/core/src/components/tab-selector/README.md)
- [Theme Switch](packages/core/src/components/theme-switch/README.md)
- [Toast](packages/core/src/components/toast/README.md)
- [Tooltip](packages/core/src/components/tooltip/README.md)
## Quick Attribute Reference
See [/docs/ATTRIBUTES.md](/docs/ATTRIBUTES.md) for a comprehensive list of all `data-pm7-*` attributes and common ARIA attributes used across PM7-UI components.
## Important Development Guidelines
### Testing Components in Isolation
- **ALWAYS**: Test components without documentation-specific CSS to ensure they work correctly for end users.
- **NEVER**: Add component-specific styling or functionality only in `docs.css` or documentation-specific files.
### CSS Variable Dependencies
- **ALWAYS**: Define CSS variables before using them.
- **NEVER**: Expect CSS variables to work if they are undefined; CSS fails silently in such cases.
## Complete Example: Basic Application Layout
```html
PM7-UI Basic App
My PM7 App
Welcome!
This is a simple application built with PM7-UI components.