diff --git a/README.md b/README.md index fb6b30ed9..1a01af025 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,6 @@ See the [Storybook Here](https://igniteui.github.io/igniteui-webcomponents) | Calendar | ✅ | [Docs][Calendar Docs] | [1.0.0] | [MIT](LICENSE) | | Card | ✅ | [Docs][Card Docs] | [1.0.0] | [MIT](LICENSE) | | Checkbox | ✅ | [Docs][Checkbox Docs] | [1.0.0] | [MIT](LICENSE) | -| Form | ✅ | [Docs][Form Docs] | [1.0.0] | [MIT](LICENSE) | | Icon | ✅ | [Docs][Icon Docs] | [1.0.0] | [MIT](LICENSE) | | Icon Button | ✅ | [Docs][Icon Button Docs] | [1.0.0] | [MIT](LICENSE) | | Input | ✅ | [Docs][Input Docs] | [1.0.0] | [MIT](LICENSE) | @@ -212,7 +211,7 @@ npm run storybook:build [safari_48x48]: https://user-images.githubusercontent.com/2188411/168109527-6c58f2cf-7386-4b97-98b1-cfe0ab4e8626.png [Contribution Guidelines]: https://github.com/IgniteUI/igniteui-webcomponents/blob/master/.github/CONTRIBUTING.md [Data Grid]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/grids/data-grid -[Hierarchical Grid]: https://www.infragistics.com/webcomponentssite/components/grids/hierarchical-grid/overview +[Hierarchical Grid]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/grids/hierarchical-grid/overview [Charts]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/charts/chart-overview [Dock Manager]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/layouts/dock-manager [Pivot Grid Docs]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/grids/pivot-grid/overview @@ -228,7 +227,6 @@ npm run storybook:build [Input Docs]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/input [Icon Button Docs]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/icon-button [Icon Docs]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/layouts/icon -[Form Docs]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/form [Checkbox Docs]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/checkbox [Card Docs]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/layouts/card [Calendar Docs]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/scheduling/calendar @@ -242,7 +240,7 @@ npm run storybook:build [Chip Docs]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/chip [Circular Progress Docs]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/circular-progress [Linear Progress Docs]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/linear-progress -[Dropdown Docs]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/notifications/toast +[Dropdown Docs]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/dropdown [Tree Docs]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/grids/tree [Expansion Panel Docs]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/layouts/expansion-panel [Masked Input Docs]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/input @@ -266,7 +264,7 @@ npm run storybook:build [Chat Docs]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/interactivity/chat [Commercial License]: https://www.infragistics.com/legal/license [Grid Lite]: https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/grid-lite/overview -[Ignite UI Web Components Grid Lite]: https://www.npmjs.com/package/igniteui-webcomponents-grid-lite +[Ignite UI Web Components Grid Lite]: https://www.npmjs.com/package/igniteui-grid-lite [1.0.0]: https://github.com/IgniteUI/igniteui-webcomponents/releases/tag/1.0.0 [2.0.0]: https://github.com/IgniteUI/igniteui-webcomponents/releases/tag/2.0.0 [2.1.0]: https://github.com/IgniteUI/igniteui-webcomponents/releases/tag/2.1.0 diff --git a/scripts/build.mjs b/scripts/build.mjs index aad7a65da..2927b45e4 100644 --- a/scripts/build.mjs +++ b/scripts/build.mjs @@ -1,5 +1,5 @@ import { exec as _exec } from 'node:child_process'; -import { copyFile, writeFile } from 'node:fs/promises'; +import { copyFile, writeFile, cp } from 'node:fs/promises'; import path from 'node:path'; import { fileURLToPath } from 'node:url'; import { promisify } from 'node:util'; @@ -87,5 +87,9 @@ async function runTask(tag, cmd) { ]) ); + await runTask('Copy skills directory', () => { + cp('skills', DEST_DIR('skills'), { recursive: true }); + }); + report.success('Done! 🎉'); })(); diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 000000000..fc3eda53b --- /dev/null +++ b/skills/README.md @@ -0,0 +1,65 @@ +# LLM Agent Skills for End Users + +This directory contains skills for GitHub Copilot and other LLM agents to help developers use Ignite UI Web Components effectively in their applications. + +## What are Skills? + +Skills are structured instructions that help AI agents understand and execute common tasks consistently. Each skill is a self-contained guide that provides step-by-step instructions, code examples, and best practices. + +## Available Skills + +| Skill | Description | Use When | +| ----------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------- | +| [igniteui-wc-choose-components](./igniteui-wc-choose-components/SKILL.md) | Identify the right components for a UI pattern and navigate to official docs/demos | Deciding which components to use | +| [igniteui-wc-integrate-with-framework](./igniteui-wc-integrate-with-framework/SKILL.md) | Integrate components into React, Angular, Vue, or vanilla JS applications | Setting up components in your project | +| [igniteui-wc-customize-component-theme](./igniteui-wc-customize-component-theme/SKILL.md) | Customize styling using CSS custom properties, parts, and theming system | Applying custom brand colors/styles | +| [igniteui-wc-optimize-bundle-size](./igniteui-wc-optimize-bundle-size/SKILL.md) | Reduce bundle size by importing only needed components and lazy loading | Optimizing production performance | + +## How to Use + +When working with an AI agent like GitHub Copilot, reference skills by name or ask questions naturally: + +### Natural Questions +- "How do I integrate igniteui-webcomponents with React?" +- "Help me customize the button colors to match my brand" +- "My bundle size is too large, how can I reduce it?" +- "Show me how to use these components in Vue" + +### Direct Skill Reference +- "Follow the integrate-with-framework skill for my Angular app" +- "Use the customize-component-theme skill to help me style components" +- "Apply the optimize-bundle-size skill to reduce my bundle" + +## Skill Structure + +Each skill contains: + +- **Example Usage**: Common questions or scenarios +- **When to Use**: Situations where the skill applies +- **Related Skills**: Other relevant skills to explore +- **Step-by-Step Instructions**: Detailed guidance with code examples +- **Framework-Specific Examples**: React, Angular, Vue, and vanilla JS patterns +- **Common Issues & Solutions**: Troubleshooting guidance +- **Best Practices**: Recommended approaches +- **Additional Resources**: Further reading and documentation + +## Contributing + +If you identify gaps in the skills or have suggestions for improvements: + +1. [Open an issue](https://github.com/IgniteUI/igniteui-webcomponents/issues) describing the improvement +2. Submit a pull request with the proposed changes +3. Follow the skill format and structure of existing skills + +For skills related to **contributing to the library itself** (creating components, reviewing PRs, etc.), see [`.github/skills/`](../.github/skills/). + +## Additional Resources + +- [Component Documentation](https://igniteui.github.io/igniteui-webcomponents) +- [Project README](../README.md) +- [Code Examples & Storybook](https://igniteui.github.io/igniteui-webcomponents) +- [GitHub Repository](https://github.com/IgniteUI/igniteui-webcomponents) + +## License + +These skills are provided under the same license as the Ignite UI Web Components library. See [LICENSE](../LICENSE) for details. diff --git a/skills/igniteui-wc-choose-components/SKILL.md b/skills/igniteui-wc-choose-components/SKILL.md new file mode 100644 index 000000000..02c01cec2 --- /dev/null +++ b/skills/igniteui-wc-choose-components/SKILL.md @@ -0,0 +1,358 @@ +--- +name: igniteui-wc-choose-components +description: Identify and select the right Ignite UI Web Components for your app UI, then navigate to official docs, usage examples, and API references +user-invokable: true +--- + +# Choose the Right Ignite UI Components + +This skill helps AI agents and developers identify the best Ignite UI components for any UI requirement, then provides direct links to official documentation, usage examples, and API references. + +## Example Usage + +- "What component should I use to display a list of items with actions?" +- "I need a date picker for a booking form" +- "How do I show file upload progress?" +- "What's the best component for a navigation sidebar?" +- "I need a searchable dropdown with multi-select" +- "Build a dashboard layout with cards and a data grid" +- "I want to display hierarchical/tree data" +- "Show me components for notifications and alerts" + +## Related Skills + +- [igniteui-wc-integrate-with-framework](../igniteui-wc-integrate-with-framework/SKILL.md) — Set up chosen components in React, Angular, Vue, or vanilla JS +- [igniteui-wc-customize-component-theme](../igniteui-wc-customize-component-theme/SKILL.md) — Style and theme the components you select +- [igniteui-wc-optimize-bundle-size](../igniteui-wc-optimize-bundle-size/SKILL.md) — Import only the components you actually use + +## When to Use + +- Agent or user needs to decide which component fits a UI requirement +- User describes a UI pattern and needs a matching component name +- User wants to explore what components are available +- User needs links to official docs or live examples for a specific component +- Starting a new feature and mapping requirements to components +- Reworking existing UI with new or different component requirements + +--- + +## Available Packages + +Ignite UI for Web Components is distributed across several packages depending on your needs: + +| Package | License | Install | Best For | +|---|---|---|---| +| [`igniteui-webcomponents`](https://www.npmjs.com/package/igniteui-webcomponents) | MIT | `npm install igniteui-webcomponents` | General UI components (inputs, layouts, notifications, scheduling) | +| [`igniteui-webcomponents-grids`](https://www.npmjs.com/package/igniteui-webcomponents-grids) | Commercial | `npm install igniteui-webcomponents-grids` (trial) | Advanced data grids (Data Grid, Tree Grid, Hierarchical Grid, Pivot Grid) with many built-in functionalities | +| [`igniteui-grid-lite`](https://www.npmjs.com/package/igniteui-grid-lite) | MIT | `npm install igniteui-grid-lite` | Lightweight data grid for simpler tabular data | +| [`igniteui-dockmanager`](https://www.npmjs.com/package/igniteui-dockmanager) | Commercial | `npm install igniteui-dockmanager` (trial) | Windowing / docking layouts (IDE-style panels) | + +--- + +## Component Catalogue by UI Pattern + +Use the table below to map a UI need to the right component, then follow the documentation link. + +### Inputs & Forms + +All inputs are form-associated and integrate natively with `
`. + +| UI Need | Component | Tag | Docs | +|---|---|---|---| +| Text field / text input | Input | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/input) | +| Multi-line text | Textarea | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/text-area) | +| Checkbox | Checkbox | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/checkbox) | +| On/off toggle | Switch | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/switch) | +| Single choice from a list | Radio / Radio Group | `` / `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/radio) | +| Star / score rating | Rating | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/rating) | +| Formatted / masked text input | Mask Input | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/input) | +| Date and time input | Date Time Input | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/date-time-input) | +| File upload | File Input | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/file-input) | +| Simple dropdown / select | Select | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/select) | +| Searchable dropdown, single or multi-select | Combo | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/combo/overview) | +| Grouped toggle buttons | Button Group | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/button-group) | +| Range / numeric slider | Slider | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/slider) | +| Range slider (two handles) | Range Slider | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/slider) | + +### Buttons & Actions + +| UI Need | Component | Tag | Docs | +|---|---|---|---| +| Standard clickable button | Button | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/button) | +| Icon-only button | Icon Button | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/icon-button) | +| Click ripple effect | Ripple | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/ripple) | +| Removable tag / filter chip | Chip | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/chip) | + +### Scheduling & Date Pickers + +| UI Need | Component | Tag | Docs | +|---|---|---|---| +| Full calendar view | Calendar | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/scheduling/calendar) | +| Date picker (popup calendar) | Date Picker | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/scheduling/date-picker) | +| Date range selection | Date Range Picker | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/scheduling/date-range-picker) | + +### Notifications & Feedback + +| UI Need | Component | Tag | Docs | +|---|---|---|---| +| Brief auto-dismiss notification | Toast | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/notifications/toast) | +| Actionable dismissible notification bar | Snackbar | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/notifications/snackbar) | +| Persistent status banner (e.g. warning, error) | Banner | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/notifications/banner) | +| Modal confirmation or content dialog | Dialog | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/notifications/dialog) | +| Tooltip on hover | Tooltip | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/tooltip) | +| Small count / status indicator | Badge | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/badge) | + +### Progress Indicators + +| UI Need | Component | Tag | Docs | +|---|---|---|---| +| Horizontal progress bar | Linear Progress | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/linear-progress) | +| Circular / spinner progress | Circular Progress | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/circular-progress) | + +### Layouts & Containers + +| UI Need | Component | Tag | Docs | +|---|---|---|---| +| Generic content card | Card | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/layouts/card) | +| User avatar / profile image | Avatar | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/layouts/avatar) | +| Icon display | Icon | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/layouts/icon) | +| Horizontal or vertical divider line | Divider | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/layouts/divider) | +| Collapsible section | Expansion Panel | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/layouts/expansion-panel) | +| Multiple collapsible sections (accordion) | Accordion | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/layouts/accordion) | +| Tabbed content panels | Tabs | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/layouts/tabs) | +| Image / content slideshow | Carousel | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/layouts/carousel) | +| Multi-step wizard / onboarding flow | Stepper | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/layouts/stepper) | +| Resizable, draggable dashboard tiles | Tile Manager | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/layouts/tile-manager) | +| IDE-style docking / floating panels | Dock Manager | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/layouts/dock-manager) | + +### Navigation + +| UI Need | Component | Tag | Docs | +|---|---|---|---| +| Top application bar / toolbar | Navbar | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/menus/navbar) | +| Side navigation drawer | Navigation Drawer | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/menus/navigation-drawer) | +| Context menu / actions dropdown | Drop Down | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/dropdown) | + +### Lists & Data Display + +| UI Need | Component | Tag | Docs | +|---|---|---|---| +| Simple scrollable list | List | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/grids/list) | +| Hierarchical / tree data | Tree | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/grids/tree) | +| Tabular data (MIT, lightweight) | Grid Lite | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/grid-lite/overview) | +| Full-featured tabular data grid | Data Grid | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/grids/grid/overview) | +| Nested / master-detail grid | Hierarchical Grid | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/grids/hierarchical-grid/overview) | +| Parent-child relational tree grid | Tree Grid | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/grids/tree-grid/overview) | +| Cross-tabulation / BI pivot table | Pivot Grid | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/web-components/components/grids/pivot-grid/overview) | + +### Conversational / AI + +| UI Need | Component | Tag | Docs | +|---|---|---|---| +| Chat / AI assistant message thread | Chat | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/interactivity/chat) | + +--- + +## Step-by-Step: Choosing Components for a UI + +Follow these steps when an agent or user describes a UI requirement: + +### Step 1 — Identify UI patterns + +Break the described UI into atomic patterns. Examples: +- "A booking form" → date input, text inputs, button, maybe a calendar picker +- "An admin dashboard" → navbar, nav drawer, cards, data grid, charts +- "A notification center" → snackbar or toast, badge, list +- "A settings page" → tabs or accordion, switch, input, select, button + +### Step 2 — Map patterns to components + +Use the **Component Catalogue** tables above to find matching components. When in doubt: + +| If the user needs… | Prefer… | Over… | +|---|---|---| +| Simple static list | `` | Data Grid | +| Basic dropdown | `` | `` | +| Searchable or multi-select dropdown | `` | `` | +| Tabular data with basic display and functionality | Grid Lite | Data Grid (commercial) | +| Tabular data, advanced features needed | Data Grid | Grid Lite | +| Single dismissible message | Toast | Snackbar | +| Message requiring user action | Snackbar | Toast | +| Collapsible single section | Expansion Panel | Accordion | +| Multiple collapsible sections | Accordion | Expansion Panel | +| Stepped wizard UI | Stepper | Tabs | +| Content tabs / view switching | Tabs | Stepper | + +### Step 3 — Check the package + +Confirm which package provides the component: + +- **MIT components** (inputs, layout, notifications, scheduling, chat) → `igniteui-webcomponents` +- **Advanced grids** (Data Grid, Tree Grid, Hierarchical Grid, Pivot Grid) → `igniteui-webcomponents-grids` *(commercial)* +- **Lightweight grid** (Grid Lite) → `igniteui-grid-lite` *(MIT)* +- **Docking layout** → `igniteui-dockmanager` *(commercial)* + +### Step 4 — Link to official resources + +Always direct the user to the official documentation linked in the tables above. Key entry points: + +- **Component overview**: [Ignite UI Web Components Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/general-getting-started) +- **Live Storybook demos**: [https://igniteui.github.io/igniteui-webcomponents](https://igniteui.github.io/igniteui-webcomponents) +- **npm package**: [https://www.npmjs.com/package/igniteui-webcomponents](https://www.npmjs.com/package/igniteui-webcomponents) +- **GitHub repository**: [https://github.com/IgniteUI/igniteui-webcomponents](https://github.com/IgniteUI/igniteui-webcomponents) +- **Changelog / releases**: [https://github.com/IgniteUI/igniteui-webcomponents/blob/master/CHANGELOG.md](https://github.com/IgniteUI/igniteui-webcomponents/blob/master/CHANGELOG.md) + +### Step 5 — Provide a starter code snippet + +Once components are identified, give the user a minimal working snippet. Example for an admin dashboard shell: + +```typescript +import { + defineComponents, + IgcNavbarComponent, + IgcNavDrawerComponent, + IgcCardComponent, + IgcIconComponent, + IgcButtonComponent, + registerIconFromText, +} from 'igniteui-webcomponents'; + +defineComponents( + IgcNavbarComponent, + IgcNavDrawerComponent, + IgcCardComponent, + IgcIconComponent, + IgcButtonComponent +); + +registerIconFromText('menu', '', 'material'); +registerIconFromText('home', '', 'material'); +registerIconFromText('build', '', 'material'); +``` + +```html + + +

My Dashboard

+ + + + + + Home + + + + Settings + + + + + +

Summary

+ + Dashboard content here + +``` + +--- + +## Common UI Scenarios → Recommended Component Sets + +### Login / Authentication Form +- `` — email and password fields +- `` — "Remember me" +- `` — submit +- `` — error/success feedback +- **Docs**: [Input](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/input) · [Button](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/button) · [Snackbar](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/notifications/snackbar) + +### User Profile / Settings Page +- `` — profile picture +- `` — section navigation (Profile, Security, Notifications) +- `` / `` — editable fields +- `` — feature toggles +- `` — preference dropdowns +- `` — save/cancel actions +- **Docs**: [Avatar](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/layouts/avatar) · [Tabs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/layouts/tabs) · [Switch](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/switch) + +### Data Table / Admin List View +- `` — search bar +- `` — filter dropdowns +- `` (Grid Lite) or Data Grid — tabular data +- `` / `` — actions +- `` — confirm delete modal +- `` — status indicators +- **Docs**: [Grid Lite](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/grid-lite/overview) · [Data Grid](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/grids/grid/overview) · [Dialog](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/notifications/dialog) + +### Booking / Reservation Form +- `` — check-in / check-out +- `` — guest details +- `` — room type +- `` — multi-step booking flow +- `` — next / confirm +- `` — booking confirmation +- **Docs**: [Date Range Picker](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/scheduling/date-range-picker) · [Stepper](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/layouts/stepper) + +### Analytics / Reporting Dashboard +- `` — top bar +- `` — side navigation +- `` — KPI summary cards +- `` or `` — section layout +- Data Grid or Pivot Grid — detailed data tables +- `` / `` — loading states +- **Docs**: [Tile Manager](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/layouts/tile-manager) · [Pivot Grid](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/grids/pivot-grid/overview) + +### Notification / Activity Feed +- `` — activity items +- `` — user avatars in each item +- `` — unread count +- `` — real-time alerts +- `` — filter tags (All, Mentions, Replies) +- **Docs**: [List](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/grids/list) · [Badge](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/badge) · [Chip](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/inputs/chip) + +### AI / Chatbot Interface +- `` — full chat UI with message threading +- `` or `` — message input +- `` — send button +- `` — bot and user avatars +- `` — "thinking" indicator +- **Docs**: [Chat](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/interactivity/chat) · [Avatar](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/layouts/avatar) + +--- + +## Common Issues & Solutions + +### "I can't find a component for X" + +1. Check the [full component list](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/general-getting-started) in the official docs +2. Consider composing two simpler components (e.g., `` + `` for a list card) + +### "Which grid should I use?" + +| Scenario | Component | Package | License | +|---|---|---|---| +| Simple table with basic features | Grid Lite | `igniteui-grid-lite` | MIT | +| Advanced/excel-style filtering, paging, editing | Data Grid | `igniteui-webcomponents-grids` | Commercial | +| Master-detail / nested rows | Hierarchical Grid | `igniteui-webcomponents-grids` | Commercial | +| Parent-child with shared columns | Tree Grid | `igniteui-webcomponents-grids` | Commercial | +| Cross-tabulation / OLAP analysis | Pivot Grid | `igniteui-webcomponents-grids` | Commercial | + +### "I need React support" + +Use the [`igniteui-react`](https://www.npmjs.com/package/igniteui-react) package. Components are wrapped with React-friendly event bindings and props. See the [igniteui-wc-integrate-with-framework](../igniteui-wc-integrate-with-framework/SKILL.md) skill for setup. + +### "How do I get commercial components?" + +Visit [https://www.infragistics.com/products/ignite-ui-web-components](https://www.infragistics.com/products/ignite-ui-web-components) or contact [Infragistics sales](https://www.infragistics.com/about-us/contact-us) for licensing information. + +--- + +## Additional Resources + +| Resource | Link | +|---|---| +| Getting started guide | [https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/general-getting-started](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/general-getting-started) | +| GitHub repository | [https://github.com/IgniteUI/igniteui-webcomponents](https://github.com/IgniteUI/igniteui-webcomponents) | +| Changelog | [https://github.com/IgniteUI/igniteui-webcomponents/blob/master/CHANGELOG.md](https://github.com/IgniteUI/igniteui-webcomponents/blob/master/CHANGELOG.md) | +| Discord community | [https://discord.gg/39MjrTRqds](https://discord.gg/39MjrTRqds) | +| Infragistics contact | [https://www.infragistics.com/about-us/contact-us](https://www.infragistics.com/about-us/contact-us) | diff --git a/skills/igniteui-wc-customize-component-theme/SKILL.md b/skills/igniteui-wc-customize-component-theme/SKILL.md new file mode 100644 index 000000000..a5dddd3fa --- /dev/null +++ b/skills/igniteui-wc-customize-component-theme/SKILL.md @@ -0,0 +1,615 @@ +--- +name: igniteui-wc-customize-component-theme +description: Customize Ignite UI Web Components styling using CSS custom properties, optional Sass, and the igniteui-theming MCP server for AI-assisted theming +user-invokable: true +--- + +# Ignite UI Web Components — Theming Skill + +## Description + +This skill teaches AI agents how to theme Ignite UI Web Components (and React via `igniteui-react`) applications. Two approaches are supported: + +- **CSS custom properties** — works in any project without additional build tooling +- **Sass** — available when the project has Sass configured; provides the full palette/typography/elevation API + +The skill also covers component-level theming, layout controls (spacing, sizing, roundness), and how to use the **Ignite UI Theming MCP server** for AI-assisted code generation. + +## Prerequisites + +- A project with `igniteui-webcomponents` (or `igniteui-react`) installed +- The **Ignite UI Theming MCP server** (`igniteui-theming`) available as a tool provider +- **Optional**: Sass configured in the project (enables the Sass-based theming API) + +> **AGENT INSTRUCTION — MCP Server Setup (REQUIRED)** +> +> Before using any theming tools, you MUST verify the MCP server is available +> by calling `detect_platform`. If the tool is not available or the call fails, +> you MUST automatically configure it by following the setup process steps described below. +> +> After writing the file, inform the user that the MCP server has been +> configured and they may need to reload the editor for the tools to activate. +> Start the MCP server and wait for that MCP server to start before continuing the theming related work. +> Do NOT skip this step or ask the user to do it manually. + +## Setting Up the Theming MCP Server + +The Ignite UI Theming MCP server enables AI assistants to generate production-ready theming code. It must be configured in your editor before the theming tools become available. + +### VS Code + +Create or edit `.vscode/mcp.json` in your project: + +```json +{ + "servers": { + "igniteui-theming": { + "command": "npx", + "args": ["-y", "igniteui-theming", "igniteui-theming-mcp"] + } + } +} +``` + +This works whether `igniteui-theming` is installed locally in `node_modules` or needs to be pulled from the npm registry — `npx -y` handles both cases. + +### Cursor + +Create or edit `.cursor/mcp.json`: + +```json +{ + "mcpServers": { + "igniteui-theming": { + "command": "npx", + "args": ["-y", "igniteui-theming", "igniteui-theming-mcp"] + } + } +} +``` + +### Claude Desktop + +Edit the Claude Desktop config file: +- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` +- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` + +```json +{ + "mcpServers": { + "igniteui-theming": { + "command": "npx", + "args": ["-y", "igniteui-theming", "igniteui-theming-mcp"] + } + } +} +``` + +### WebStorm / JetBrains IDEs + +1. Go to **Settings → Tools → AI Assistant → MCP Servers** +2. Click **+ Add MCP Server** +3. Set Command to `npx` and Arguments to `igniteui-theming igniteui-theming-mcp` +4. Click OK and restart the AI Assistant + +### Verifying the Setup + +After configuring the MCP server, ask your AI assistant: + +> "Detect which Ignite UI platform my project uses" + +If the MCP server is running, the `detect_platform` tool will analyze your `package.json` and return the detected platform (e.g., `webcomponents`). + +## Theming Architecture + +The Ignite UI theming system is built on four pillars: + +| Concept | Purpose | +|---|---| +| **Palette** | Color system with primary, secondary, surface, gray, info, success, warn, error families, each with shades 50–900 + accents A100–A700 | +| **Typography** | Font family, type scale (h1–h6, subtitle, body, button, caption, overline) | +| **Elevations** | Box-shadow levels 0–24 for visual depth | +| **Schema** | Per-component recipes mapping palette colors to component tokens | + +### Design Systems + +Four built-in design systems are available: + +- **Material** (default) — Material Design 3 +- **Bootstrap** — Bootstrap-inspired +- **Fluent** — Microsoft Fluent Design +- **Indigo** — Infragistics Indigo Design + +Each has light and dark variants (e.g., `$light-material-schema`, `$dark-fluent-schema`). + +## Pre-built Themes + +The quickest way to theme an app is to import a pre-built CSS file in your entry point: + +```typescript +import 'igniteui-webcomponents/themes/light/bootstrap.css'; +``` + +Available pre-built CSS files: + +| Import path | Theme | +|---|---| +| `igniteui-webcomponents/themes/light/bootstrap.css` | Bootstrap Light | +| `igniteui-webcomponents/themes/dark/bootstrap.css` | Bootstrap Dark | +| `igniteui-webcomponents/themes/light/material.css` | Material Light | +| `igniteui-webcomponents/themes/dark/material.css` | Material Dark | +| `igniteui-webcomponents/themes/light/fluent.css` | Fluent Light | +| `igniteui-webcomponents/themes/dark/fluent.css` | Fluent Dark | +| `igniteui-webcomponents/themes/light/indigo.css` | Indigo Light | +| `igniteui-webcomponents/themes/dark/indigo.css` | Indigo Dark | + +## Custom Theme via CSS Custom Properties + +> No Sass required. Works in any project after importing a pre-built theme. + +After importing a pre-built theme, override individual design tokens with CSS custom properties on `:root` or a scoped selector: + +```css +:root { + /* Override palette hue/saturation/lightness channels */ + --ig-primary-h: 211deg; + --ig-primary-s: 100%; + --ig-primary-l: 50%; + + --ig-secondary-h: 33deg; + --ig-secondary-s: 100%; + --ig-secondary-l: 50%; +} +``` + +To scope overrides to a specific container: + +```css +.admin-panel { + --ig-primary-h: 260deg; + --ig-primary-s: 60%; + --ig-primary-l: 45%; +} +``` + +For dark mode, either import a dark theme CSS file directly or toggle overrides with a class or media query: + +```css +@media (prefers-color-scheme: dark) { + :root { + --ig-surface-h: 0deg; + --ig-surface-s: 0%; + --ig-surface-l: 7%; + } +} + +/* Or manually with a class */ +.dark-theme { + --ig-surface-h: 0deg; + --ig-surface-s: 0%; + --ig-surface-l: 7%; +} +``` + +## Custom Theme via Sass + +> Requires Sass configured in the project. First check whether the project has a Sass setup (e.g., a `styles.scss` entry file, `sass` in `devDependencies`, or a Vite/webpack Sass plugin). + +The Sass API for `igniteui-webcomponents` uses `@use 'igniteui-theming'` with individual mixins — **not** the Angular-specific `core()` / `theme()` combined mixins. + +```scss +@use 'igniteui-theming' as *; + +// 1. Define a palette +$my-palette: palette( + $primary: #1976D2, + $secondary: #FF9800, + $surface: #FAFAFA +); + +// 2. Apply the palette +@include palette($my-palette); + +// 3. Optional: Typography +@include typography($font-family: "'Roboto', sans-serif"); + +// 4. Optional: Elevations +@include elevations(); + +// 5. Optional: Spacing +@include spacing(); +``` + +For dark themes, use a dark surface color and a dark schema: + +```scss +@use 'igniteui-theming' as *; + +$dark-palette: palette( + $primary: #90CAF9, + $secondary: #FFB74D, + $surface: #121212 +); + +@include palette($dark-palette, $schema: $dark-material-schema); +``` + +To scope a Sass theme to a container: + +```scss +.admin-panel { + @include palette($admin-palette, $schema: $light-indigo-schema); +} +``` + +## Component-Level Theming + +Override individual component appearance using component theme functions and the `tokens` mixin. + +> **AGENT INSTRUCTION — No Hardcoded Colors (CRITICAL)** +> +> Once a palette has been generated (via `palette()` in Sass or `create_palette` / `create_theme` via MCP), +> **every color reference MUST come from the generated palette tokens** — never hardcode hex/RGB/HSL values. +> +> Use `var(--ig-primary-500)`, `var(--ig-secondary-300)`, `var(--ig-surface-500)`, etc. in CSS, +> or the `get_color` MCP tool to obtain the correct token reference. +> +> **WRONG** (hardcoded hex — breaks theme switching, ignores the palette): +> ```css +> igc-avatar { +> --ig-avatar-background: #E91E63; /* ✗ hardcoded */ +> --ig-avatar-color: #FFFFFF; /* ✗ hardcoded */ +> } +> ``` +> +> **RIGHT — CSS** (palette token — stays in sync with the theme): +> ```css +> igc-avatar { +> --ig-avatar-background: var(--ig-primary-500); +> --ig-avatar-color: var(--ig-primary-500-contrast); +> } +> ``` +> +> **RIGHT — Sass** (when Sass is configured): +> ```scss +> $custom-avatar: avatar-theme( +> $schema: $light-material-schema, +> $background: var(--ig-primary-500), +> $color: var(--ig-primary-500-contrast) +> ); +> ``` +> +> This applies to **all** style code: component themes, custom CSS rules, and inline styles. +> The only place raw hex values belong is the **initial `palette()` call** that seeds the color system. +> Everything downstream must reference the palette. + +```css +igc-avatar { + --ig-avatar-background: var(--ig-primary-500); + --ig-avatar-color: var(--ig-primary-500-contrast); +} +``` + +When Sass is available, use the component theme function and `tokens` mixin: + +```scss +@use 'igniteui-theming' as *; + +$custom-avatar: avatar-theme( + $schema: $light-material-schema, + $background: var(--ig-primary-500), + $color: var(--ig-primary-500-contrast) +); + +igc-avatar { + @include tokens($custom-avatar); +} +``` + +### Discovering Available Tokens + +Each component has its own set of design tokens (themeable CSS custom properties). Before theming a component, you must know which tokens exist. Use the **MCP tool** `get_component_design_tokens` to discover them. + +### Compound Components + +Some components (e.g., `combo`, `grid`, `date-picker`, `select`) are **compound** — they contain internal child components, each requiring their own theme. For example, `date-picker` uses `calendar`, `flat-button`, and `input-group` internally. + +Workflow for compound components: +1. Call `get_component_design_tokens` for the parent (e.g., `date-picker`) +2. The response lists related themes and scope selectors +3. Call `create_component_theme` for each child, using the parent's selector as the wrapper + +## Layout Controls + +### Sizing + +Controls the size of components via `--ig-size` (values: 1 = small, 2 = medium, 3 = large): + +```css +/* Global */ +:root { --ig-size: 2; } + +/* Component-scoped */ +igc-grid { --ig-size: 1; } +``` + +### Spacing + +Controls internal padding via `--ig-spacing` (1 = default, 0.5 = compact, 2 = spacious): + +```css +:root { --ig-spacing: 1; } +.compact-section { --ig-spacing: 0.75; } +``` + +### Roundness + +Controls border-radius via `--ig-radius-factor` (0 = square, 1 = maximum radius): + +```css +:root { --ig-radius-factor: 1; } +igc-avatar { --ig-radius-factor: 0.5; } +``` + +## Using the Theming MCP Server + +The Ignite UI Theming MCP server provides tools for AI-assisted theme code generation. + +> **IMPORTANT — File Safety Rule**: When generating or updating theme code, **never overwrite existing style files directly**. Instead, always **propose the changes as an update** and let the user review and approve before writing to disk. If a `styles.scss` (or any target file) already exists, show the generated code as a diff or suggestion rather than replacing the file contents. This prevents accidental loss of custom styles the user has already written. + +Always follow this workflow: + +### Step 1 — Detect Platform + +``` +Tool: detect_platform +``` +This auto-detects `webcomponents` from `package.json` and sets the correct import paths. + +### Step 2 — Generate a Full Theme + +``` +Tool: create_theme +Params: { + platform: "webcomponents", + designSystem: "material", + primaryColor: "#1976D2", + secondaryColor: "#FF9800", + surfaceColor: "#FAFAFA", + variant: "light", + fontFamily: "'Roboto', sans-serif", + includeTypography: true, + includeElevations: true +} +``` + +Generates a complete Sass file with palette, typography, elevations, and the `theme()` mixin call. + +### Step 3 — Customize Individual Components + +``` +Tool: get_component_design_tokens +Params: { component: "grid" } +``` + +Then use **palette token references** (not hardcoded hex values) for every color: + +``` +Tool: create_component_theme +Params: { + platform: "webcomponents", + designSystem: "material", + variant: "light", + component: "grid", + tokens: { + "header-background": "var(--ig-primary-50)", + "header-text-color": "var(--ig-primary-800)" + } +} +``` + +> **Reminder**: After a palette is generated, all token values passed to +> `create_component_theme` must reference palette CSS custom properties +> (e.g., `var(--ig-primary-500)`, `var(--ig-secondary-A200)`, +> `var(--ig-gray-100)`). Never pass raw hex values like `"#E3F2FD"`. + +### Step 4 — Generate a Palette + +For simple mid-luminance base colors: + +``` +Tool: create_palette +Params: { + platform: "webcomponents", + primary: "#1976D2", + secondary: "#FF9800", + surface: "#FAFAFA", + variant: "light" +} +``` + +For brand-specific exact shade values, use `create_custom_palette` with `mode: "explicit"` for full control over each shade. + +### Step 5 — Adjust Layout + +By default, layout tools emit **CSS**. If the project has Sass configured, add `output: "sass"` to get Sass output: + +``` +Tool: set_size → { size: "medium" } # CSS (default) +Tool: set_size → { size: "medium", output: "sass" } # Sass +Tool: set_spacing → { spacing: 0.75, component: "grid" } # CSS (default) +Tool: set_spacing → { spacing: 0.75, component: "grid", output: "sass" } # Sass +Tool: set_roundness → { radiusFactor: 0.8 } # CSS (default) +Tool: set_roundness → { radiusFactor: 0.8, output: "sass" } # Sass +``` + +### Step 6 — Reference Palette Colors (MANDATORY for All Color Usage) + +After a palette is generated, **always** use the `get_color` tool to obtain the correct CSS custom property reference. Never hardcode hex/RGB/HSL values in component themes, custom CSS, or Sass variables. + +``` +Tool: get_color +Params: { color: "primary", variant: "600" } +→ var(--ig-primary-600) + +Params: { color: "primary", variant: "600", contrast: true } +→ var(--ig-primary-600-contrast) + +Params: { color: "primary", opacity: 0.5 } +→ hsl(from var(--ig-primary-500) h s l / 0.5) +``` + +Use these token references everywhere: +- Component theme `tokens` values +- Custom CSS rules (`color`, `background`, `border-color`, `fill`, `stroke`, etc.) + +The **only** place raw hex values are acceptable is in the initial `palette()` call or the `create_palette` / `create_theme` MCP tool inputs that seed the color system. + +### Loading Reference Data + +Use `read_resource` with these URIs for preset values and documentation: + +| URI | Content | +|---|---| +| `theming://presets/palettes` | Preset palette colors | +| `theming://presets/typography` | Typography presets | +| `theming://presets/elevations` | Elevation shadow presets | +| `theming://guidance/colors/usage` | Which shades for which purpose | +| `theming://guidance/colors/roles` | Semantic color roles | +| `theming://guidance/colors/rules` | Light/dark theme rules | +| `theming://platforms/webcomponents` | Web Components platform specifics | +| `theming://platforms` | All supported platforms | + +## Referencing Colors in Custom Styles + +After a theme is applied, the palette is available as CSS custom properties on `:root`. Use these tokens in all custom CSS — never introduce standalone hex/RGB variables for colors that the palette already provides. + +### Correct: Palette Tokens + +```css +/* All colors come from the theme — respects palette changes and dark/light switching */ +.sidebar { + background: var(--ig-surface-500); + color: var(--ig-gray-900); + border-right: 1px solid var(--ig-gray-200); +} + +.accent-badge { + background: var(--ig-secondary-500); + color: var(--ig-secondary-500-contrast); +} + +.hero-section { + /* Semi-transparent primary overlay */ + background: hsl(from var(--ig-primary-500) h s l / 0.12); +} +``` + +### Incorrect: Hardcoded Values + +```css +/* WRONG — these break when the palette changes and ignore dark/light mode */ +.sidebar { + background: #F0F5FA; /* ✗ not a palette token */ + color: #333; /* ✗ not a palette token */ +} +``` + +### When Raw Hex Values Are OK + +Raw hex values are acceptable **only** in these contexts: + +1. **`palette()` call** — the initial seed colors that generate the full palette +2. **`create_palette` / `create_theme` MCP tool inputs** — the base colors passed to the tool +3. **Non-palette decorative values** — e.g., a one-off SVG illustration color that intentionally stays fixed regardless of theme + +Everything else must use `var(--ig--)` tokens. + +## Common Patterns + +### Switching Between Light and Dark Themes — CSS approach + +Import the appropriate theme CSS and toggle with a class or media query: + +```typescript +// In your entry point — choose one variant as the default +import 'igniteui-webcomponents/themes/light/bootstrap.css'; +``` + +```css +/* Override surface tokens for dark mode */ +.dark-theme { + --ig-surface-h: 0deg; + --ig-surface-s: 0%; + --ig-surface-l: 7%; +} + +@media (prefers-color-scheme: dark) { + :root { + --ig-surface-h: 0deg; + --ig-surface-s: 0%; + --ig-surface-l: 7%; + } +} +``` + +Or dynamically swap the stylesheet at runtime: + +```typescript +function setTheme(variant: 'light' | 'dark', design = 'bootstrap') { + const link = document.getElementById('igc-theme') as HTMLLinkElement; + link.href = `node_modules/igniteui-webcomponents/themes/${variant}/${design}.css`; +} +``` + +### Switching Between Light and Dark Themes — Sass approach + +When Sass is configured, define both palettes and apply them under separate selectors: + +```scss +@use 'igniteui-theming' as *; + +$light-palette: palette($primary: #1976D2, $secondary: #FF9800, $surface: #FAFAFA); +$dark-palette: palette($primary: #90CAF9, $secondary: #FFB74D, $surface: #121212); + +@include typography($font-family: "'Roboto', sans-serif"); +@include elevations(); + +// Light is default +@include palette($light-palette, $schema: $light-material-schema); + +// Dark via class on or +.dark-theme { + @include palette($dark-palette, $schema: $dark-material-schema); +} +``` + +### Scoping a Theme to a Container — CSS approach + +```css +.admin-panel { + --ig-primary-h: 260deg; + --ig-primary-s: 60%; + --ig-primary-l: 45%; +} +``` + +### Scoping a Theme to a Container — Sass approach + +```scss +.admin-panel { + @include palette($admin-palette, $schema: $light-indigo-schema); +} +``` + +## Key Rules + +1. **Never overwrite existing files directly** — always propose theme code as an update for user review; do not replace existing style files without confirmation +2. **Always call `detect_platform` first** when using MCP tools +3. **Always call `get_component_design_tokens` before `create_component_theme`** to discover valid token names +4. **Palette shades 50 = lightest, 900 = darkest** for all chromatic colors — never invert for dark themes (only gray inverts) +5. **Surface color must match the variant** — light color for `light`, dark color for `dark` +6. **Sass only**: Use `@include palette()`, `@include typography()`, and `@include elevations()` individually — `@use 'igniteui-theming'` is the correct module for web components and React (not `igniteui-angular/theming`); the Angular-specific `core()` / `theme()` combined mixins do **not** apply here +7. **Sass only**: Component themes use `@include tokens($theme)` inside a selector to emit CSS custom properties +8. **For compound components**, follow the full checklist returned by `get_component_design_tokens` — theme each child component with its scoped selector +9. **Never hardcode colors after palette generation** — once a palette is created, every color in component themes, custom CSS, and Sass variables must use `var(--ig--)` palette tokens (e.g., `var(--ig-primary-500)`, `var(--ig-gray-200)`). Raw hex/RGB/HSL values are only acceptable in the initial `palette()` seed call. This ensures themes remain consistent, switchable (light/dark), and maintainable diff --git a/skills/igniteui-wc-integrate-with-framework/SKILL.md b/skills/igniteui-wc-integrate-with-framework/SKILL.md new file mode 100644 index 000000000..ce74f0c3e --- /dev/null +++ b/skills/igniteui-wc-integrate-with-framework/SKILL.md @@ -0,0 +1,112 @@ +--- +name: igniteui-wc-integrate-with-framework +description: Integrate igniteui-webcomponents into React, Angular, Vue, or vanilla JS applications with framework-specific configurations +user-invokable: true +--- + +# Integrate with Framework + +This skill helps users integrate Ignite UI Web Components into their application. It detects the framework or platform in use and loads the appropriate step-by-step integration reference. + +## Example Usage + +- "How do I use igniteui-webcomponents in my React app?" +- "Integrate the button component in Angular" +- "Set up igniteui-webcomponents in Vue 3" +- "Help me add web components to my vanilla JS project" + +## Related Skills + +- [igniteui-wc-optimize-bundle-size](../igniteui-wc-optimize-bundle-size/SKILL.md) - Reduce bundle size after integration +- [igniteui-wc-customize-component-theme](../igniteui-wc-customize-component-theme/SKILL.md) - Style components after setup + +## When to Use + +- User wants to add igniteui-webcomponents to a framework project +- User is experiencing framework-specific integration issues +- User needs help with component imports and registration +- User asks about React, Angular, Vue, or vanilla JS setup + +--- + +## Framework Detection + +Before loading a reference, identify the target framework from the project context. Check the following signals in order: + +### 1. Detect React + +**Evidence to look for:** +- `package.json` contains `"react"` or `"react-dom"` in `dependencies` or `devDependencies` +- Files with `.tsx` or `.jsx` extensions exist in `src/` +- Entry point imports `ReactDOM` or `createRoot` +- `vite.config.ts` uses `@vitejs/plugin-react` or `@vitejs/plugin-react-swc` + +→ **Load:** [react.md](./references/react.md) + +--- + +### 2. Detect Angular + +**Evidence to look for:** +- `package.json` contains `"@angular/core"` in `dependencies` +- `angular.json` file exists in the workspace root +- Files with `.component.ts`, `.module.ts`, or `.component.html` patterns exist +- Entry point calls `bootstrapApplication` or `platformBrowserDynamic` + +→ **Load:** [angular.md](./references/angular.md) + +--- + +### 3. Detect Vue 3 + +**Evidence to look for:** +- `package.json` contains `"vue"` in `dependencies` or `devDependencies` +- Files with `.vue` extensions exist in `src/` +- `vite.config.ts` uses `@vitejs/plugin-vue` +- Entry point calls `createApp` + +→ **Load:** [vue.md](./references/vue.md) + +--- + +### 4. Vanilla JavaScript / HTML (fallback) + +**Evidence to look for:** +- No major framework found in `package.json` +- Plain `.html` files reference a ` + + + Click me + + + +``` + +## TypeScript Support + +The `igniteui-webcomponents` package automatically provides global type declarations for all components via `HTMLElementTagNameMap`. DOM queries are fully typed without any extra configuration: + +```typescript +import { defineComponents, IgcButtonComponent } from 'igniteui-webcomponents'; + +defineComponents(IgcButtonComponent); + +// Automatically typed as IgcButtonComponent | null +const button = document.querySelector('igc-button'); +button?.setAttribute('variant', 'outlined'); +``` + +You can also import component types directly for annotations: + +```typescript +import type { IgcButtonComponent } from 'igniteui-webcomponents'; + +const button = document.querySelector('igc-button') as IgcButtonComponent; +``` + +## Working with Complex Properties + +Attributes only accept strings. For objects and arrays, set properties via JavaScript: + +```typescript +// ❌ Wrong — attributes only accept strings +// + +// ✅ Correct — set via DOM property +const combo = document.querySelector('igc-combo'); +combo.data = [ + { value: 1, label: 'Item 1' }, + { value: 2, label: 'Item 2' } +]; +``` + +## Common Issues + +### Components not rendering + +Register components **before** they appear in the DOM: + +```typescript +// ❌ Wrong +document.body.innerHTML = 'Click'; +defineComponents(IgcButtonComponent); + +// ✅ Correct +defineComponents(IgcButtonComponent); +document.body.innerHTML = 'Click'; +``` + +### No styles applied + +Ensure you import a theme CSS file in your entry point. Without it, components render unstyled. + +## Next Steps + +- [Optimize bundle size](../../igniteui-wc-optimize-bundle-size/SKILL.md) — import only the components you use +- [Customize themes](../../igniteui-wc-customize-component-theme/) — apply your brand colors +- [Component documentation](https://igniteui.github.io/igniteui-webcomponents) — full API reference diff --git a/skills/igniteui-wc-integrate-with-framework/references/vue.md b/skills/igniteui-wc-integrate-with-framework/references/vue.md new file mode 100644 index 000000000..0f830cb94 --- /dev/null +++ b/skills/igniteui-wc-integrate-with-framework/references/vue.md @@ -0,0 +1,181 @@ +# Integrating Ignite UI Web Components — Vue 3 + +## Installation + +```bash +npm install igniteui-webcomponents +``` + +## Setup + +### Step 1 — Configure Vue to recognize custom elements + +Vue needs to know which tags are custom elements so it does not warn about unknown components. + +**With Vite** (`vite.config.ts`): + +```typescript +import { defineConfig } from 'vite'; +import vue from '@vitejs/plugin-vue'; + +export default defineConfig({ + plugins: [ + vue({ + template: { + compilerOptions: { + // Treat all igc-* tags as custom elements + isCustomElement: (tag) => tag.startsWith('igc-') + } + } + }) + ] +}); +``` + +**With Vue CLI** (`vue.config.js`): + +```javascript +module.exports = { + chainWebpack: config => { + config.module + .rule('vue') + .use('vue-loader') + .tap(options => ({ + ...options, + compilerOptions: { + isCustomElement: tag => tag.startsWith('igc-') + } + })); + } +}; +``` + +### Step 2 — Register the theme and components + +In `src/main.ts`, import a theme and register the components before mounting: + +```typescript +import { createApp } from 'vue'; +import App from './App.vue'; +import 'igniteui-webcomponents/themes/light/bootstrap.css'; +import { defineComponents, IgcButtonComponent, IgcInputComponent } from 'igniteui-webcomponents'; + +defineComponents(IgcButtonComponent, IgcInputComponent); + +createApp(App).mount('#app'); +``` + +## Available Themes + +| Theme | Light | Dark | +|-----------|--------------------------------------------------------|-------------------------------------------------------| +| Bootstrap | `igniteui-webcomponents/themes/light/bootstrap.css` | `igniteui-webcomponents/themes/dark/bootstrap.css` | +| Material | `igniteui-webcomponents/themes/light/material.css` | `igniteui-webcomponents/themes/dark/material.css` | +| Fluent | `igniteui-webcomponents/themes/light/fluent.css` | `igniteui-webcomponents/themes/dark/fluent.css` | +| Indigo | `igniteui-webcomponents/themes/light/indigo.css` | `igniteui-webcomponents/themes/dark/indigo.css` | + +## Usage in Components + +```vue + + + +``` + +## Working with Complex Properties + +Attributes only accept strings. Pass objects and arrays using a template ref: + +```vue + + + +``` + +## Key Considerations + +| Concern | Details | +|---------|---------| +| **isCustomElement** | Required in Vite/CLI config so Vue doesn't treat `igc-*` tags as unresolved components | +| **Event binding** | Use `@igcInput`, `@igcChange`, etc. — not `@input` or `@change` | +| **Property binding** | Use `:property="value"` or `v-bind:property="value"` for reactive data | +| **Complex data** | Use a template ref and set the property in `onMounted` | + +## TypeScript Support + +The `igniteui-webcomponents` package automatically registers all component types in `HTMLElementTagNameMap`. DOM queries are fully typed: + +```typescript +import { defineComponents, IgcButtonComponent } from 'igniteui-webcomponents'; + +defineComponents(IgcButtonComponent); + +// Automatically typed as IgcButtonComponent | null +const button = document.querySelector('igc-button'); +``` + +## Common Issues + +### Vue warns "Unknown custom element: igc-button" + +Configure `isCustomElement` in `vite.config.ts` (or `vue.config.js`) so Vue skips resolution for `igc-*` tags. + +### Events not firing + +Use Vue's `@igcInput` / `@igcChange` syntax. Ignite UI components emit prefixed custom events — standard DOM events like `input` or `change` behave differently. + +### No styles applied + +Ensure you import a theme CSS file in `main.ts` before `createApp`. Without it, components render unstyled. + +### Complex data not reflecting + +Set objects and arrays via a `ref` in `onMounted`. Do not bind them as HTML attributes — attributes only accept serialized strings. + +--- + +## Next Steps + +- [Optimize bundle size](../../igniteui-wc-optimize-bundle-size/) — import only the components you use +- [Customize themes](../../igniteui-wc-customize-component-theme/) — apply your brand colors +- [Component documentation](https://igniteui.github.io/igniteui-webcomponents) — full API reference diff --git a/skills/igniteui-wc-optimize-bundle-size/SKILL.md b/skills/igniteui-wc-optimize-bundle-size/SKILL.md new file mode 100644 index 000000000..2c7edf21b --- /dev/null +++ b/skills/igniteui-wc-optimize-bundle-size/SKILL.md @@ -0,0 +1,709 @@ +--- +name: igniteui-wc-optimize-bundle-size +description: Optimize application bundle size by importing only necessary components and using tree-shaking effectively +user-invokable: true +--- + +# Optimize Bundle Size + +This skill helps users minimize their application's bundle size when using Ignite UI Web Components by importing only the components they need and following best practices for tree-shaking. + +## Example Usage + +- "My bundle size is too large" +- "How do I reduce the size of igniteui-webcomponents?" +- "Import only the components I need" +- "Tree-shake unused components" +- "Optimize imports for production" + +## Related Skills + +- [igniteui-wc-integrate-with-framework](../igniteui-wc-integrate-with-framework/SKILL.md) - Proper integration setup +- [igniteui-wc-customize-component-theme](../igniteui-wc-customize-component-theme/SKILL.md) - Theming after optimization + +## When to Use + +- User's bundle size is too large +- User wants to optimize for production +- User is importing more components than needed +- User asks about tree-shaking or optimization +- User wants to improve load times + +## Key Principles + +1. **Import only what you use** - Don't use `defineAllComponents()` +2. **Use named imports** - Enable tree-shaking +3. **Analyze your bundle** - Identify what's being included +4. **Lazy load when possible** - Load components on demand + +## Import Strategies + +### ❌ Bad: Import Everything + +```typescript +// DON'T DO THIS - imports ALL components (~500KB+) +import { defineAllComponents } from 'igniteui-webcomponents'; + +defineAllComponents(); +``` + +**Impact:** Includes all 60+ components whether you use them or not. + +### ✅ Good: Import Specific Components + +```typescript +// DO THIS - import only what you need +import { + defineComponents, + IgcButtonComponent, + IgcInputComponent, + IgcCardComponent +} from 'igniteui-webcomponents'; + +defineComponents(IgcButtonComponent, IgcInputComponent, IgcCardComponent); +``` + +**Impact:** Bundle includes only 3 components and their dependencies. + +## React Applications + +If you're using React, consider using the **`igniteui-react`** package instead of `igniteui-webcomponents`. It provides the same components with React-friendly wrappers and typically results in better tree-shaking: + +```bash +npm install igniteui-react +``` + +```tsx +import { IgrButton, IgrInput, IgrCard } from 'igniteui-react'; + +// No need to call defineComponents - components register automatically +function MyComponent() { + return ( +
+ Click me + + Content +
+ ); +} +``` + +**Benefits for bundle size:** +- Automatic tree-shaking (only imported components are included) +- No need for component registration overhead +- Better integration with React build tools + +For more details, see the [igniteui-wc-integrate-with-framework](../igniteui-wc-integrate-with-framework/SKILL.md) skill. + +## Analyzing Your Bundle + +### Using Webpack Bundle Analyzer + +**Installation:** + +```bash +npm install --save-dev webpack-bundle-analyzer +``` + +**Configuration (`webpack.config.js`):** + +```javascript +const { BundleAnalyzerPlugin } = require('webpack-bundle-analyzer'); + +module.exports = { + plugins: [ + new BundleAnalyzerPlugin({ + analyzerMode: 'static', + openAnalyzer: false, + reportFilename: 'bundle-report.html' + }) + ] +}; +``` + +**Run analysis:** + +```bash +npm run build +# Open bundle-report.html to see what's included +``` + +### Using Vite Bundle Analyzer + +**Installation:** + +```bash +npm install --save-dev rollup-plugin-visualizer +``` + +**Configuration (`vite.config.ts`):** + +```typescript +import { defineConfig } from 'vite'; +import { visualizer } from 'rollup-plugin-visualizer'; + +export default defineConfig({ + plugins: [ + visualizer({ + open: true, + gzipSize: true, + brotliSize: true, + }) + ] +}); +``` + +**Run analysis:** + +```bash +npm run build +# Opens stats.html automatically +``` + +### Using source-map-explorer + +**Installation:** + +```bash +npm install --save-dev source-map-explorer +``` + +**Package.json:** + +```json +{ + "scripts": { + "analyze": "source-map-explorer 'dist/**/*.js'" + } +} +``` + +**Run:** + +```bash +npm run build +npm run analyze +``` + +## Audit Your Component Usage + +### 1. Find What Components You're Actually Using + +Search your codebase for component usage: + +```bash +# Search for component tags in templates +grep -r "igc-" src/ --include="*.html" --include="*.tsx" --include="*.vue" + +# List unique components +grep -roh "igc-[a-z-]*" src/ | sort | uniq +``` + +### 2. Compare with Your Imports + +Check what you're importing vs what you're using: + +```typescript +// Find in your code +import { + defineComponents, + IgcButtonComponent, + IgcInputComponent, + IgcCardComponent, + IgcSelectComponent, // ← Are you using this? + IgcComboComponent, // ← Are you using this? +} from 'igniteui-webcomponents'; +``` + +### 3. Remove Unused Imports + +Remove components you're not using: + +```typescript +// Before: 5 components imported +import { + defineComponents, + IgcButtonComponent, + IgcInputComponent, + IgcCardComponent, + IgcSelectComponent, + IgcComboComponent, +} from 'igniteui-webcomponents'; + +defineComponents( + IgcButtonComponent, + IgcInputComponent, + IgcCardComponent, + IgcSelectComponent, + IgcComboComponent +); + +// After: Only 3 components needed +import { + defineComponents, + IgcButtonComponent, + IgcInputComponent, + IgcCardComponent, +} from 'igniteui-webcomponents'; + +defineComponents(IgcButtonComponent, IgcInputComponent, IgcCardComponent); +``` + +## Lazy Loading Components + +Load components only when needed to reduce initial bundle size. + +### Vanilla JavaScript / TypeScript + +```typescript +// Load immediately (increases initial bundle) +import { defineComponents, IgcDialogComponent } from 'igniteui-webcomponents'; +defineComponents(IgcDialogComponent); + +// Lazy load (smaller initial bundle) +async function showDialog() { + const { defineComponents, IgcDialogComponent } = await import('igniteui-webcomponents'); + defineComponents(IgcDialogComponent); + + const dialog = document.createElement('igc-dialog'); + // ... use dialog +} +``` + +### React (using igniteui-react) + +```tsx +import React, { lazy, Suspense, useState } from 'react'; + +// Lazy load the dialog component +const IgrDialog = lazy(() => + import('igniteui-react').then(module => ({ default: module.IgrDialog })) +); + +function MyComponent() { + const [showDialog, setShowDialog] = useState(false); + + return ( + <> + + {showDialog && ( + Loading...}> + +

Dialog Content

+ + + )} + + ); +} +``` + +### React (using web components directly) + +```tsx +import React, { useState } from 'react'; + +// Lazy load component registration +const lazyLoadDialog = async () => { + const { defineComponents, IgcDialogComponent } = await import('igniteui-webcomponents'); + defineComponents(IgcDialogComponent); +}; + +function MyComponent() { + const [dialogReady, setDialogReady] = useState(false); + + const openDialog = async () => { + if (!dialogReady) { + await lazyLoadDialog(); + setDialogReady(true); + } + // Show dialog + }; + + return ( + + ); +} +``` + +### Vue 3 + +```vue + + + +``` + +### Angular + +```typescript +import { Component } from '@angular/core'; + +@Component({ + selector: 'app-my-component', + template: ` + + +

Dialog Content

+ + ` +}) +export class MyComponent { + dialogReady = false; + + async openDialog() { + if (!this.dialogReady) { + const { defineComponents, IgcDialogComponent } = await import('igniteui-webcomponents'); + defineComponents(IgcDialogComponent); + this.dialogReady = true; + } + } +} +``` + +## Route-Based Code Splitting + +Load components only for specific routes. + +### React Router + +```tsx +import { BrowserRouter, Routes, Route } from 'react-router-dom'; +import { lazy, Suspense } from 'react'; + +// Lazy load route components +const HomePage = lazy(() => import('./pages/Home')); +const DashboardPage = lazy(() => import('./pages/Dashboard')); + +function App() { + return ( + + Loading...}> + + } /> + } /> + + + + ); +} +``` + +**In route component (`pages/Dashboard.tsx`):** + +```tsx +import { IgrCard, IgrButton } from 'igniteui-react'; + +function Dashboard() { + return ( +
+ +

Dashboard

+

Dashboard content here

+ +
+ ); +} +``` + +### Vue Router + +```typescript +// router/index.ts +import { createRouter, createWebHistory } from 'vue-router'; + +const routes = [ + { + path: '/', + component: () => import('../views/Home.vue') // Lazy load + }, + { + path: '/dashboard', + component: () => import('../views/Dashboard.vue') // Lazy load + } +]; + +export default createRouter({ + history: createWebHistory(), + routes +}); +``` + +**In route component (`views/Dashboard.vue`):** + +```vue + +``` + +### Angular + +```typescript +// app-routing.module.ts +import { NgModule } from '@angular/core'; +import { RouterModule, Routes } from '@angular/router'; + +const routes: Routes = [ + { + path: 'dashboard', + loadChildren: () => import('./dashboard/dashboard.module').then(m => m.DashboardModule) + } +]; + +@NgModule({ + imports: [RouterModule.forRoot(routes)], + exports: [RouterModule] +}) +export class AppRoutingModule {} +``` + +## Build Configuration Optimizations + +### Vite Configuration + +```typescript +// vite.config.ts +import { defineConfig } from 'vite'; + +export default defineConfig({ + build: { + // Enable minification + minify: 'terser', + terserOptions: { + compress: { + drop_console: true, // Remove console.logs + drop_debugger: true + } + }, + + // Optimize chunk splitting + rollupOptions: { + output: { + manualChunks: { + // Separate vendor chunks + 'vendor': ['igniteui-webcomponents'], + } + } + }, + + // Set chunk size warning limit + chunkSizeWarningLimit: 600, + }, + + // Optimize deps + optimizeDeps: { + include: ['igniteui-webcomponents'] + } +}); +``` + +### Webpack Configuration + +```javascript +// webpack.config.js +module.exports = { + optimization: { + splitChunks: { + chunks: 'all', + cacheGroups: { + vendor: { + test: /[\\/]node_modules[\\/]/, + name: 'vendors', + priority: 10, + }, + igniteui: { + test: /[\\/]node_modules[\\/]igniteui-webcomponents[\\/]/, + name: 'igniteui', + priority: 20, + } + } + }, + minimize: true, + }, + + // Tree shaking + mode: 'production', +}; +``` + +## Size Comparison + +Here's what you can expect in terms of bundle size: + +| Import Strategy | Approximate Size (gzipped) | Components Included | +|----------------|---------------------------|---------------------| +| `defineAllComponents()` | ~500KB+ | All 60+ components | +| 10 components via `defineComponents()` | ~150-200KB | 10 components + deps | +| 5 components via `defineComponents()` | ~100-150KB | 5 components + deps | +| 3 components via `defineComponents()` | ~80-120KB | 3 components + deps | +| 1 component via `defineComponents()` | ~50-80KB | 1 component + deps | + +**Note:** Sizes vary based on which components you import (some have more dependencies than others). + +## Best Practices Checklist + +- [ ] **Never use `defineAllComponents()`** unless you truly need every component +- [ ] **Use `defineComponents()` with specific components** you need +- [ ] **Audit your imports regularly** - remove unused components +- [ ] **Lazy load rarely-used components** (dialogs, modals, etc.) +- [ ] **Split by routes** - load components only for active routes +- [ ] **Analyze your bundle** - use bundle analyzer tools +- [ ] **Enable tree-shaking** - use named imports, not side-effect imports +- [ ] **Minify in production** - ensure build tool minification is enabled +- [ ] **Use compression** - enable gzip/brotli on your server + +## Common Issues and Solutions + +### Issue: Bundle still large after following best practices + +**Investigate:** + +1. Check if you're importing many components at once +2. Verify tree-shaking is working (check build output) +3. Look for duplicate dependencies +4. Check if source maps are included in production +5. For React, ensure you're using `igniteui-react` instead of `igniteui-webcomponents` + +**Solutions:** + +```typescript +// Review your imports - are you using all of these? +import { + defineComponents, + IgcButtonComponent, + IgcInputComponent, + IgcSelectComponent, + IgcComboComponent, + IgcDatePickerComponent +} from 'igniteui-webcomponents'; + +// Consider lazy loading components you don't need immediately +async function loadDialog() { + const { defineComponents, IgcDialogComponent } = await import('igniteui-webcomponents'); + defineComponents(IgcDialogComponent); +} +``` + +### Issue: Components not working after optimizing imports + +**Cause:** Forgot to import a component you're using + +**Solution:** + +```typescript +// Error: not working +// You're using igc-button but didn't import it + +import { defineComponents, IgcButtonComponent } from 'igniteui-webcomponents'; +defineComponents(IgcButtonComponent); // Add this +``` + +### Issue: TypeScript errors after changing imports + +**Solution:** Update type imports: + +```typescript +// Import types separately if needed +import type { IgcButtonComponent } from 'igniteui-webcomponents'; +``` + +## Monitoring Bundle Size + +### Set up bundle size monitoring in CI/CD + +**Using bundlesize (for any build tool):** + +```bash +npm install --save-dev bundlesize +``` + +**Package.json:** + +```json +{ + "scripts": { + "test:size": "bundlesize" + }, + "bundlesize": [ + { + "path": "./dist/**/*.js", + "maxSize": "300 kB" + } + ] +} +``` + +**Run in CI:** + +```bash +npm run build +npm run test:size +``` + +### GitHub Actions Example + +```yaml +name: Bundle Size Check + +on: [pull_request] + +jobs: + size: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: actions/setup-node@v3 + - run: npm ci + - run: npm run build + - run: npm run test:size +``` + +## Expected Results + +After optimization, you should see: + +- **Initial load time reduced** by 40-60% +- **Bundle size reduced** by 50-80% +- **Better Core Web Vitals** scores +- **Faster time to interactive** +- **Lower bandwidth usage** for users + +## Next Steps + +- Profile your application with Chrome DevTools Performance tab +- Implement lazy loading for heavy components +- Consider using CDN for static assets +- Enable HTTP/2 for better resource loading +- Check [igniteui-wc-integrate-with-framework](../igniteui-wc-integrate-with-framework/SKILL.md) for proper setup + +## Additional Resources + +- [Webpack Tree Shaking](https://webpack.js.org/guides/tree-shaking/) +- [Vite Build Optimizations](https://vitejs.dev/guide/build.html) +- [Web Performance Optimization](https://web.dev/fast/) +- [Bundle Size Analysis Tools](https://bundlephobia.com/)