@iyulab/components 0.3.0 → 1.0.0

package/plugins/vite-plugin-react-wrapper.js

@@ -0,0 +1,206 @@
+import { resolve, join, relative, dirname, basename } from 'path';
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { gzipSync } from 'zlib';
+import { globSync } from 'glob';
+/**
+ * Lit Element 컴포넌트를 React 래퍼로 자동 생성하는 Vite 플러그인
+ */
+export default function reactWrapperPlugin(options) {
+    let rootDir;
+    let buildOutDir;
+    let outDir;
+    return {
+        name: 'vite-plugin-react-wrapper',
+        configResolved(config) {
+            rootDir = config.root;
+            buildOutDir = resolve(rootDir, config.build.outDir);
+            outDir = resolve(buildOutDir, options.output || 'react');
+        },
+        closeBundle() {
+            const log = (msg) => console.log(`\x1b[36m[react-wrapper]\x1b[0m ${msg}`);
+            log('Generating React wrappers...');
+            // 컴포넌트 수집
+            const inputPattern = (options.input || 'src/components') + '/**/*.ts';
+            const files = globSync(inputPattern, { cwd: rootDir, absolute: true });
+            const components = files.flatMap((f) => parseComponent(f));
+            if (components.length === 0) {
+                log('No components found.');
+                return;
+            }
+            // 출력 디렉토리 생성
+            mkdirSync(outDir, { recursive: true });
+            // 래퍼 생성
+            const generated = [];
+            for (const comp of components) {
+                generated.push(...writeWrapper(comp, outDir, buildOutDir));
+            }
+            generated.push(...writeIndex(components, outDir, buildOutDir));
+            // 결과 출력
+            generated.sort((a, b) => a.size - b.size);
+            for (const f of generated) {
+                const kb = (f.size / 1024).toFixed(2);
+                const gzKb = (f.gzipSize / 1024).toFixed(2);
+                const pad = ' '.repeat(Math.max(0, 50 - f.path.length));
+                console.log(`${f.path}${pad}${kb.padStart(6)} kB │ gzip: ${gzKb.padStart(6)} kB`);
+            }
+            log(`Generated ${components.length} React wrappers.`);
+        }
+    };
+}
+// --- 컴포넌트 파싱 ---
+function parseComponent(filePath) {
+    const content = readFileSync(filePath, 'utf-8');
+    // @customElement('tag-name') 데코레이터 확인
+    const tagMatch = content.match(/@customElement\s*\(\s*['"]([^'"]+)['"]\s*\)/);
+    if (!tagMatch)
+        return [];
+    // export class ClassName 추출
+    const classMatch = content.match(/export\s+class\s+(\w+)/);
+    if (!classMatch)
+        return [];
+    const events = collectEvents(content);
+    return [{
+            className: classMatch[1],
+            tagName: tagMatch[1],
+            filePath,
+            events,
+        }];
+}
+function collectEvents(content) {
+    // import 구문에서 타입명 → 소스 경로 매핑 수집
+    // 예: import { ShowEventDetail } from '../../events/ShowEvent.js';
+    const typeImportMap = new Map();
+    for (const m of content.matchAll(/import\s+\{([^}]+)\}\s+from\s+['"]([^'"]+)['"]/g)) {
+        const importPath = m[2];
+        for (const name of m[1].split(',')) {
+            const typeName = name.replace(/type\s+/, '').trim();
+            if (typeName)
+                typeImportMap.set(typeName, importPath);
+        }
+    }
+    const eventMap = new Map();
+    // JSDoc @event 패턴: @event eventName
+    for (const m of content.matchAll(/@event\s+([\w-]+)/g)) {
+        if (!eventMap.has(m[1]))
+            eventMap.set(m[1], { detailType: 'unknown', importPath: '' });
+    }
+    // this.fire<DetailType>('eventName') 패턴 - 제네릭 타입 추출
+    for (const m of content.matchAll(/this\.fire\s*(?:<([^>]+)>)?\s*\(\s*['"]([\w-]+)['"]/g)) {
+        const detailType = m[1] || 'unknown';
+        const importPath = typeImportMap.get(detailType) || '';
+        eventMap.set(m[2], { detailType, importPath });
+    }
+    return Array.from(eventMap, ([name, { detailType, importPath }]) => ({
+        name,
+        reactName: toCamelEvent(name),
+        detailType,
+        importPath,
+    }));
+}
+/** kebab-case 이벤트명을 onCamelCase로 변환 (예: shift-start → onShiftStart) */
+function toCamelEvent(name) {
+    return 'on' + name.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join('');
+}
+function writeFile(filePath, content, buildOutDir) {
+    writeFileSync(filePath, content, 'utf-8');
+    return {
+        path: relative(buildOutDir, filePath).replace(/\\/g, '/'),
+        size: Buffer.byteLength(content, 'utf-8'),
+        gzipSize: gzipSync(content).length,
+    };
+}
+function computeImportPath(from, to) {
+    let rel = relative(dirname(from), to).replace(/\\/g, '/').replace(/\.ts$/, '');
+    if (!rel.startsWith('.'))
+        rel = './' + rel;
+    return rel;
+}
+function writeWrapper(comp, outDir, buildOutDir) {
+    const { className, tagName, events } = comp;
+    const jsPath = join(outDir, `${className}.js`);
+    const dtsPath = join(outDir, `${className}.d.ts`);
+    // 소스 파일의 빌드 출력 경로 추정 (src/ → 빌드 outDir 매핑)
+    const srcIndex = comp.filePath.replace(/\\/g, '/').indexOf('/src/');
+    const relFromSrc = srcIndex >= 0
+        ? comp.filePath.substring(srcIndex + 5).replace(/\\/g, '/').replace(/\.ts$/, '')
+        : basename(comp.filePath, '.ts');
+    const builtModulePath = resolve(buildOutDir, relFromSrc + '.js');
+    const importPath = computeImportPath(jsPath, builtModulePath);
+    // events 객체 생성
+    const eventsObj = events.length > 0
+        ? `{\n${events.map(e => `    ${e.reactName}: '${e.name}',`).join('\n')}\n  }`
+        : '{}';
+    // .js
+    const js = `import React from 'react';
+import { createComponent } from '@lit/react';
+import { ${className} } from '${importPath}';
+
+export const ${className} = createComponent({
+  react: React,
+  tagName: '${tagName}',
+  elementClass: ${className},
+  events: ${eventsObj},
+});
+`;
+    // .d.ts - import 구문 생성
+    const dtsImportPath = importPath.replace(/\.js$/, '');
+    const dtsImports = [
+        `import React from 'react';`,
+        `import { ${className} as ${className}Element } from '${dtsImportPath}';`,
+    ];
+    // 이벤트 detail 타입별 import - 소스 원본 경로 기준으로 빌드 경로 계산
+    const srcDir = dirname(comp.filePath);
+    const detailImportMap = new Map(); // 빌드경로 → [타입명]
+    for (const e of events) {
+        if (e.detailType === 'unknown' || !e.importPath)
+            continue;
+        // 소스 상대경로를 절대경로로 변환 후 빌드 경로 계산
+        const absEventSrc = resolve(srcDir, e.importPath).replace(/\\/g, '/');
+        const eventSrcIndex = absEventSrc.indexOf('/src/');
+        const relFromSrc = eventSrcIndex >= 0
+            ? absEventSrc.substring(eventSrcIndex + 5).replace(/\.js$/, '')
+            : '';
+        if (!relFromSrc)
+            continue;
+        const absEventBuilt = resolve(buildOutDir, relFromSrc);
+        const eventImportPath = computeImportPath(dtsPath, absEventBuilt + '.js').replace(/\.js$/, '');
+        const types = detailImportMap.get(eventImportPath) || [];
+        if (!types.includes(e.detailType))
+            types.push(e.detailType);
+        detailImportMap.set(eventImportPath, types);
+    }
+    for (const [path, types] of detailImportMap) {
+        dtsImports.push(`import { type ${types.join(', type ')} } from '${path}';`);
+    }
+    const eventTypes = events.length > 0
+        ? events.map(e => {
+            const type = e.detailType !== 'unknown' ? `CustomEvent<${e.detailType}>` : 'CustomEvent';
+            return `  ${e.reactName}?: (event: ${type}) => void;`;
+        }).join('\n') + '\n'
+        : '';
+    const dts = `${dtsImports.join('\n')}
+
+export declare const ${className}: React.ForwardRefExoticComponent<
+  Partial<${className}Element> & React.HTMLAttributes<${className}Element> & {
+${eventTypes}  }
+>;
+
+export type ${className}Props = React.ComponentProps<typeof ${className}>;
+`;
+    return [
+        writeFile(jsPath, js, buildOutDir),
+        writeFile(dtsPath, dts, buildOutDir),
+    ];
+}
+function writeIndex(components, outDir, buildOutDir) {
+    const jsExports = components
+        .map(c => `export { ${c.className} } from './${c.className}.js';`)
+        .join('\n');
+    const dtsExports = components
+        .map(c => `export { ${c.className}, ${c.className}Props } from './${c.className}';`)
+        .join('\n');
+    return [
+        writeFile(join(outDir, 'index.js'), jsExports + '\n', buildOutDir),
+        writeFile(join(outDir, 'index.d.ts'), dtsExports + '\n', buildOutDir),
+    ];
+}

package/skills/iyulab-components/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: iyulab-components
+description: Web component library built on Lit. Covers all u-* custom elements (buttons, forms, overlays, navigation, data display), utilities (Theme, Toast, Dialog, icons), and base classes for extension. Use when working with @iyulab/components package.
+license: MIT
+metadata:
+  author: iyulab
+  version: "1.0.0"
+---
+
+# @iyulab/components
+
+Web component library built on [Lit](https://lit.dev/). All components are custom elements (`u-*` tags) that work in any framework or vanilla HTML.
+
+## Quick Start
+
+Install the package:
+
+```bash
+npm install @iyulab/components
+```
+
+Initialize theme and import all components:
+
+```ts
+import { Theme } from '@iyulab/components';
+import '@iyulab/components'; // registers all u-* custom elements
+
+await Theme.init(); // optional — applies system/light/dark theme
+```
+
+Import individual components (tree-shakable):
+
+```ts
+import '@iyulab/components/dist/components/button/UButton.js';
+import '@iyulab/components/dist/components/input/UInput.js';
+```
+
+React wrappers (requires `@lit/react`):
+
+```ts
+import { UButton, UInput } from '@iyulab/components/react';
+```
+
+> For detailed guidance on theming, icon setup, and advanced usage, see [./references/usage.md](./references/usage.md).
+
+---
+
+## Components
+
+### Feedback
+
+- [`u-alert`](./references/components/alert.md) — Closable message banner with status variants and auto-dismiss
+- [`u-spinner`](./references/components/spinner.md) — Animated loading indicator
+- [`u-skeleton`](./references/components/skeleton.md) — Placeholder shape shown while content loads
+- [`u-progress-bar`](./references/components/progress-bar.md) — Linear progress indicator with buffer and segment support
+- [`u-progress-ring`](./references/components/progress-ring.md) — Circular progress indicator
+
+### Buttons & Actions
+
+- [`u-button`](./references/components/button.md) — Versatile button with multiple variants; renders as `<a>` when `href` is set
+- [`u-icon-button`](./references/components/icon-button.md) — Square icon-only button with built-in tooltip
+- [`u-button-group`](./references/components/button-group.md) — Groups buttons with shared variant and disabled state
+
+### Form Controls
+
+- [`u-input`](./references/components/input.md) — Text input; combobox mode when `u-option` children are present
+- [`u-textarea`](./references/components/textarea.md) — Multi-line text input with auto-resize and character counter
+- [`u-select`](./references/components/select.md) — Dropdown select; single or multiple, with search
+- [`u-checkbox`](./references/components/checkbox.md) — Checkbox with indeterminate state support
+- [`u-radio`](./references/components/radio.md) — Radio group built from `u-option` children
+- [`u-switch`](./references/components/switch.md) — Toggle switch
+- [`u-slider`](./references/components/slider.md) — Range slider; single-thumb or dual-thumb (range) mode
+- [`u-rating`](./references/components/rating.md) — Star/custom-symbol rating input
+- [`u-field`](./references/components/field.md) — Layout wrapper providing label, description, and validation message
+- [`u-form`](./references/components/form.md) — Form group with two-way model binding and validation
+- [`u-option`](./references/components/option.md) — Selectable option item for `u-select`, `u-radio`, `u-input`
+
+### Overlay & Floating
+
+- [`u-dialog`](./references/components/dialog.md) — Modal/non-modal dialog with configurable placement
+- [`u-drawer`](./references/components/drawer.md) — Side-panel that slides in from any edge
+- [`u-popover`](./references/components/popover.md) — Anchored floating panel with flexible trigger/dismiss policies
+- [`u-tooltip`](./references/components/tooltip.md) — Hover/focus tooltip anchored to a target element
+
+### Navigation
+
+- [`u-breadcrumb`](./references/components/breadcrumb.md) — Hierarchical location indicator
+- [`u-breadcrumb-item`](./references/components/breadcrumb.md) — Individual breadcrumb link/label
+- [`u-menu`](./references/components/menu.md) — Menu container with keyboard navigation and selection modes
+- [`u-menu-item`](./references/components/menu.md) — Menu entry with optional sub-menu
+- [`u-tab-panel`](./references/components/tab-panel.md) — Tab-based content switcher
+- [`u-tab`](./references/components/tab-panel.md) — Individual tab button used inside `u-tab-panel`
+- [`u-tree`](./references/components/tree.md) — Hierarchical tree with select, check, and drag-and-drop
+- [`u-tree-item`](./references/components/tree.md) — Individual node inside `u-tree`
+
+### Layout & Display
+
+- [`u-card`](./references/components/card.md) — Content card with media, header, and footer slots
+- [`u-carousel`](./references/components/carousel.md) — Slide carousel with autoplay, navigation, and pagination
+- [`u-split-panel`](./references/components/split-panel.md) — Resizable two-panel layout
+- [`u-panel`](./references/components/panel.md) — General-purpose content panel with optional collapsing
+- [`u-divider`](./references/components/divider.md) — Horizontal or vertical separator line
+
+### Data Display
+
+- [`u-avatar`](./references/components/avatar.md) — User avatar with image, initials, or custom slot
+- [`u-badge`](./references/components/badge.md) — Status badge; can be anchored on top of other elements
+- [`u-chip`](./references/components/chip.md) — Selectable/removable chip tag
+- [`u-tag`](./references/components/tag.md) — Non-interactive label tag
+- [`u-icon`](./references/components/icon.md) — SVG icon from built-in or external icon library
+
+---
+
+## Utilities
+
+- [`Theme`](./references/utilities/theme.md) — Apply and manage light/dark/system theme
+- [`Toast`](./references/utilities/toast.md) — Programmatically show toast notifications
+- [`Dialog`](./references/utilities/dialog.md) — Programmatically show alert/confirm/prompt dialogs
+- [`IconRegistry`](./references/utilities/icons.md) — Register and resolve icon libraries
+- [`BrowserStorage`](./references/utilities/browser-storage.md) — Unified localStorage / Cookie API
+- [`converters`](./references/utilities/converters.md) — Lit property attribute converters (array, JSON, date, url…)
+- [`sanitizers`](./references/utilities/sanitizers.md) — XSS-safe HTML/URL escape helpers
+- [`elements`](./references/utilities/elements.md) — Shadow-DOM-aware DOM query helpers
+- [`OverlayManager`](./references/utilities/overlay-manager.md) — Internal overlay stack and z-index manager
+
+---
+
+## Extensions
+
+`@iyulab/components` exposes abstract base classes you can extend to build custom components that integrate seamlessly with the library's patterns (form association, overlays, floating positioning, etc.).
+
+> See [./references/extensions/](./references/extensions/) for per-class details.
+
+- [`UElement`](./references/extensions/element.md) — Root base for all components; provides `fire()`, `relay()`, `replace()` helpers
+- [`UFormControlElement<T>`](./references/extensions/form-control.md) — Base for form-associated controls; handles `disabled`, `readonly`, `invalid`, validation lifecycle
+- [`UFloatingElement`](./references/extensions/floating.md) — Base for anchored floating UI (popover, tooltip); wraps `@floating-ui/dom`
+- [`UOverlayElement`](./references/extensions/overlay.md) — Base for full-screen overlays (dialog, drawer); manages focus-trap, scroll-lock, ESC/backdrop close
+- [`UDataElement`](./references/extensions/data.md) — Base for data-driven components; auto-loads JSON from inline `<script type="application/json">`

package/skills/iyulab-components/references/components/alert.md

@@ -0,0 +1,74 @@
+# u-alert
+
+```ts
+import '@iyulab/components/dist/components/alert/UAlert.js';
+```
+
+**Tag:** `u-alert`
+
+Closable message banner with status icons, auto-dismiss timer, and open/hide transition.
+
+```html
+<u-alert status="success" closable open>
+  Your changes have been saved.
+</u-alert>
+
+<u-alert status="error" variant="outlined" open>
+  Failed to load data.
+  <u-button slot="footer" variant="solid">Retry</u-button>
+</u-alert>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | Alert body content |
+| `footer` | Bottom area (e.g. action buttons) |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `open` | `boolean` | `false` | ✓ | Show/hide the alert |
+| `closable` | `boolean` | `false` | ✓ | Show close button |
+| `variant` | `'solid'\|'filled'\|'outlined'\|'glass'` | `'solid'` | ✓ | Visual style |
+| `status` | `'error'\|'warning'\|'success'\|'info'\|'notice'` | — | ✓ | Status type; controls icon and color |
+| `title` | `string` | `''` | — | Title label (falls back to status name) |
+| `duration` | `number` | `0` | — | Auto-dismiss delay in ms; `0` disables |
+
+## Events
+
+| Event | Cancelable | Description |
+|-------|------------|-------------|
+| `show` | ✓ | Fires before the alert becomes visible |
+| `hide` | ✓ | Fires before the alert is hidden |
+
+## Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `show()` | `boolean` | Opens the alert; returns `false` if cancelled |
+| `hide()` | `boolean` | Closes the alert; returns `false` if cancelled |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `container` | Outer flex column wrapper |
+| `header` | Row containing icon, title, and close button |
+| `icon` | Status icon (hidden when `status` is unset) |
+| `title` | Title text |
+| `close-btn` | Close button (visible when `closable`) |
+| `content` | Scrollable body area |
+| `footer` | Footer slot wrapper |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--alert-background-color` | Background color (auto-set by status) |
+| `--alert-border-color` | Border color (auto-set by status) |
+| `--alert-icon-color` | Icon color (auto-set by status) |

package/skills/iyulab-components/references/components/avatar.md

@@ -0,0 +1,41 @@
+# u-avatar
+
+```ts
+import '@iyulab/components/dist/components/avatar/UAvatar.js';
+```
+
+**Tag:** `u-avatar`
+
+Displays a user avatar as an image, initials label, or custom slot content.
+
+```html
+<u-avatar image="/photo.jpg" label="Alice"></u-avatar>
+<u-avatar label="AB" shape="square"></u-avatar>
+<u-avatar outline>
+  <u-icon lib="tabler" name="user"></u-icon>
+</u-avatar>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | Custom content shown when neither `image` nor `label` is set |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `shape` | `'circle'\|'square'\|'rounded'` | `'circle'` | ✓ | Avatar shape |
+| `outline` | `boolean` | `false` | ✓ | Show border ring |
+| `image` | `string` | — | — | Image URL |
+| `label` | `string` | — | — | Initials text (first 2 chars shown; used as `alt` for image) |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `image` | `<img>` element |
+| `label` | Initials `<span>` element |

package/skills/iyulab-components/references/components/badge.md

@@ -0,0 +1,38 @@
+# u-badge
+
+```ts
+import '@iyulab/components/dist/components/badge/UBadge.js';
+```
+
+**Tag:** `u-badge`
+
+Status badge for numbers, labels, or dot indicators. Use `anchor` to position it absolutely on a parent element.
+
+```html
+<!-- Standalone -->
+<u-badge color="red">5</u-badge>
+
+<!-- Anchored on another element -->
+<div style="position:relative; display:inline-block;">
+  <u-icon lib="tabler" name="bell"></u-icon>
+  <u-badge variant="dot" color="red" anchor="top-right"></u-badge>
+</div>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| `prefix` | Content before the main label |
+| *(default)* | Badge label (text or icon) |
+| `suffix` | Content after the main label |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `variant` | `'pill'\|'dot'\|'square'` | `'pill'` | ✓ | Shape variant; `dot` renders no content |
+| `color` | `'neutral'\|'blue'\|'green'\|'yellow'\|'red'\|'orange'\|'teal'\|'cyan'\|'purple'\|'pink'` | `'neutral'` | ✓ | Badge color |
+| `anchor` | `'top-right'\|'top-left'\|'bottom-right'\|'bottom-left'` | — | ✓ | Absolute anchor position relative to parent |

package/skills/iyulab-components/references/components/breadcrumb.md

@@ -0,0 +1,75 @@
+# u-breadcrumb / u-breadcrumb-item
+
+```ts
+import '@iyulab/components/dist/components/breadcrumb/UBreadcrumb.js';
+import '@iyulab/components/dist/components/breadcrumb-item/UBreadcrumbItem.js';
+```
+
+**Tags:** `u-breadcrumb`, `u-breadcrumb-item`
+
+Hierarchical location indicator. Compose `u-breadcrumb-item` elements inside `u-breadcrumb`.
+
+```html
+<u-breadcrumb>
+  <u-breadcrumb-item href="/">Home</u-breadcrumb-item>
+  <u-breadcrumb-item href="/products">Products</u-breadcrumb-item>
+  <u-breadcrumb-item>Detail</u-breadcrumb-item>
+</u-breadcrumb>
+
+<!-- Custom separator -->
+<u-breadcrumb>
+  <span slot="separator">/</span>
+  <u-breadcrumb-item href="/">Home</u-breadcrumb-item>
+  <u-breadcrumb-item>Page</u-breadcrumb-item>
+</u-breadcrumb>
+```
+
+---
+
+## u-breadcrumb
+
+### Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | `u-breadcrumb-item` elements |
+| `separator` | Custom separator content (default: chevron icon) |
+
+### CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `nav` | `<nav>` wrapper element |
+
+---
+
+## u-breadcrumb-item
+
+### Slots
+
+| Name | Description |
+|------|-------------|
+| `prefix` | Content before the label |
+| *(default)* | Item label |
+| `suffix` | Content after the label |
+
+### Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `disabled` | `boolean` | `false` | ✓ | Disable the item |
+| `href` | `string` | — | — | Link URL; renders as `<a>` when set |
+| `target` | `string` | — | — | Link `target` attribute |
+| `rel` | `string` | — | — | Link `rel` attribute |
+
+### Events
+
+| Event | Cancelable | Description |
+|-------|------------|-------------|
+| `navigate` | ✓ | Fires when the item is clicked |
+
+### CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `link` | Inner `<a>` or `<span>` element |

package/skills/iyulab-components/references/components/button-group.md

@@ -0,0 +1,38 @@
+# u-button-group
+
+```ts
+import '@iyulab/components/dist/components/button-group/UButtonGroup.js';
+```
+
+**Tag:** `u-button-group`
+
+Groups `u-button` or `u-icon-button` elements. Propagates `variant` and `disabled` to all child buttons automatically.
+
+```html
+<u-button-group variant="outlined">
+  <u-button>Left</u-button>
+  <u-button>Center</u-button>
+  <u-button>Right</u-button>
+</u-button-group>
+
+<u-button-group vertical disabled>
+  <u-button>Top</u-button>
+  <u-button>Bottom</u-button>
+</u-button-group>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | `u-button` or `u-icon-button` elements |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `variant` | `'solid'\|'surface'\|'filled'\|'outlined'\|'ghost'\|'link'` | `'solid'` | ✓ | Variant propagated to all child buttons |
+| `vertical` | `boolean` | `false` | ✓ | Stack buttons vertically |
+| `disabled` | `boolean` | `false` | ✓ | Disable all child buttons |

package/skills/iyulab-components/references/components/button.md

@@ -0,0 +1,56 @@
+# u-button
+
+```ts
+import '@iyulab/components/dist/components/button/UButton.js';
+```
+
+**Tag:** `u-button`
+
+Versatile button with multiple visual variants. Renders as an `<a>` element when `href` is provided.
+
+```html
+<u-button>Default</u-button>
+<u-button variant="outlined">Outlined</u-button>
+<u-button variant="ghost" loading>Loading</u-button>
+<u-button href="https://example.com" target="_blank">Link</u-button>
+
+<!-- With prefix/suffix icons -->
+<u-button variant="solid">
+  <u-icon slot="prefix" lib="tabler" name="download"></u-icon>
+  Download
+</u-button>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | Button label |
+| `prefix` | Content before the label |
+| `suffix` | Content after the label |
+| `spinner` | Custom spinner shown when `loading` |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `variant` | `'solid'\|'surface'\|'filled'\|'outlined'\|'ghost'\|'link'` | `'solid'` | ✓ | Visual style |
+| `rounded` | `boolean` | `false` | ✓ | Pill-shaped border radius |
+| `disabled` | `boolean` | `false` | ✓ | Disable the button |
+| `loading` | `boolean` | `false` | ✓ | Show loading spinner; disables interaction |
+| `type` | `'button'\|'submit'\|'reset'` | `'button'` | — | Button `type` attribute |
+| `href` | `string` | — | — | Link URL (renders as `<a>`) |
+| `target` | `string` | — | — | Link `target` |
+| `rel` | `string` | — | — | Link `rel` |
+| `download` | `string` | — | — | Download filename |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `button` | Inner `<button>` element |
+| `link` | Inner `<a>` element (when `href` is set) |
+| `content` | Content wrapper (prefix + label + suffix) |
+| `mask` | Loading overlay mask |