diff --git a/.claude/skills/README.md b/.claude/skills/README.md new file mode 100644 index 0000000..19d14bf --- /dev/null +++ b/.claude/skills/README.md @@ -0,0 +1,68 @@ +# 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-generate-from-image-design](./igniteui-wc-generate-from-image-design/SKILL.md) | Implement a view from a screenshot or mockup using Ignite UI Web Components | Converting a design image into UI | +| [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" +- "Build this screenshot with Ignite UI Web Components" +- "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" +- "Use the generate-from-image-design skill to implement this mockup" +- "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/.claude/skills/igniteui-wc-choose-components/SKILL.md b/.claude/skills/igniteui-wc-choose-components/SKILL.md new file mode 100644 index 0000000..3b5c387 --- /dev/null +++ b/.claude/skills/igniteui-wc-choose-components/SKILL.md @@ -0,0 +1,431 @@ +--- +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-invocable: 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. + +## Prerequisites + +- The **Ignite UI CLI MCP server** (`igniteui-cli`) available as a tool provider + +> **AGENT INSTRUCTION — MCP Server Setup (REQUIRED)** +> +> Before using the Ignite UI CLI MCP tools, you MUST verify the MCP server is available +> by calling `list_components`. If the tool is not available or the call fails, +> you MUST automatically configure it by following the setup instructions in +> [`reference/mcp-setup.md`](./reference/mcp-setup.md). +> +> 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 component-related work. +> Do NOT skip this step or ask the user to do it manually. + +## Setting Up the Ignite UI CLI MCP Server + +> **Full setup instructions for VS Code, Cursor, Claude Desktop, and JetBrains IDEs are in [`reference/mcp-setup.md`](./reference/mcp-setup.md).** Read that file for editor-specific configuration steps and verification. + +## Before You Answer + +- Choose the package before writing imports or install steps. +- If the required package is not present in `package.json`, add or install the correct Ignite UI dependency first. Absence from `package.json` does not mean the package is invalid. +- If the user also needs setup or code, then load [igniteui-wc-integrate-with-framework](../igniteui-wc-integrate-with-framework/SKILL.md). + +## 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) | +| [`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 | +| [`@infragistics/igniteui-webcomponents-grids`](https://packages.infragistics.com/feeds/js-licensed/@infragistics/igniteui-webcomponents-grids) | Commercial | `npm install @infragistics/igniteui-webcomponents-grids` (licensed) | 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) | +| [`@infragistics/igniteui-dockmanager`](https://packages.infragistics.com/feeds/js-licensed/@infragistics/igniteui-dockmanager) | Commercial | `npm install @infragistics/igniteui-dockmanager` (licensed) | Windowing / docking layouts (IDE-style panels) | +| [`igniteui-webcomponents-charts`](https://www.npmjs.com/package/igniteui-webcomponents-charts) | Commercial | `npm install igniteui-webcomponents-core igniteui-webcomponents-charts` (trial) | Charts and data visualizations (65+ chart types) | +| [`@infragistics/igniteui-webcomponents-charts`](https://packages.infragistics.com/feeds/js-licensed/@infragistics/igniteui-webcomponents-charts) | Commercial | `npm install @infragistics/igniteui-webcomponents-core @infragistics/igniteui-webcomponents-charts` (licensed) | Charts and data visualizations (65+ chart types) | + +--- + +## Package Routing + +| Component family | Package | +|---|---| +| General UI components | `igniteui-webcomponents` | +| Advanced grids | `igniteui-webcomponents-grids` (trial) `@infragistics/igniteui-webcomponents-grids` (licensed) | +| Grid Lite | `igniteui-grid-lite` | +| Dock Manager | `igniteui-dockmanager` (trial) `@infragistics/igniteui-dockmanager` (licensed) | +| Charts | `igniteui-webcomponents-charts` (trial) `@infragistics/igniteui-webcomponents-charts` (licensed) | + +If the request only says "grid", choose by features: + +- Advanced features such as editing, paging, summaries, grouping, hierarchical data, or pivot behavior -> `igniteui-webcomponents-grids` +- Lightweight table -> `igniteui-grid-lite` + +## 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) | + +### Charting & Visualization + +> Charts are provided by the **`igniteui-webcomponents-charts`** package (commercial). Use `IgcCategoryChartComponent` or `IgcFinancialChartComponent` for simpler domain-specific scenarios; use `IgcDataChartComponent` for full flexibility (mixed series, numeric/time axes, scatter, polar, etc.). + +| UI Need | Component | Tag | Docs | +|---|---|---|---| +| Column chart (vertical bars, category comparison) | Category Chart | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/charts/types/column-chart) | +| Line chart (continuous data over time) | Category Chart | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/charts/types/line-chart) | +| Area chart (filled line, change over time) | Category Chart | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/charts/types/area-chart) | +| Spline chart (smooth curved lines) | Category Chart | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/charts/types/spline-chart) | +| Step chart (stepped line or area) | Category Chart | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/charts/types/step-chart) | +| Pie chart (part-to-whole, small data sets) | Pie Chart | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/charts/types/pie-chart) | +| Doughnut chart (part-to-whole with center label) | Doughnut Chart | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/charts/types/donut-chart) | +| Financial / stock chart (OHLC, candlestick, price series) | Financial Chart | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/charts/types/stock-chart) | +| Bar chart (horizontal bars, category comparison) | Data Chart | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/charts/types/bar-chart) | +| Scatter chart (X/Y data correlation) | Data Chart | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/charts/types/scatter-chart) | +| Bubble chart (3-value scatter with size dimension) | Data Chart | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/charts/types/bubble-chart) | +| Polar chart (angle/radius coordinate system) | Data Chart | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/charts/types/polar-chart) | +| Composite / combo chart (mixed series types) | Data Chart | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/charts/types/composite-chart) | +| Shape chart (polygons / polylines on a Cartesian plane) | Data Chart | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/charts/types/shape-chart) | +| Sparkline (word-sized inline mini-chart) | Sparkline | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/charts/types/sparkline-chart) | +| Treemap (hierarchical data as proportional nested nodes) | Treemap | `` | [Docs](https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/charts/types/treemap-chart) | + + +### 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)* +- **Charts & visualizations** (Category Chart, Data Chart, Financial Chart, Pie Chart, Sparkline, Treemap, etc.) → `igniteui-webcomponents-charts` *(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/.claude/skills/igniteui-wc-choose-components/reference/mcp-setup.md b/.claude/skills/igniteui-wc-choose-components/reference/mcp-setup.md new file mode 100644 index 0000000..b909e48 --- /dev/null +++ b/.claude/skills/igniteui-wc-choose-components/reference/mcp-setup.md @@ -0,0 +1,82 @@ +# Setting Up the Ignite UI CLI MCP Server + +> **Part of the [`igniteui-wc-choose-components`](../SKILL.md) skill hub.** + +## Contents + +- [Setting Up the Ignite UI CLI MCP Server](#setting-up-the-ignite-ui-cli-mcp-server) + - [Contents](#contents) + - [VS Code](#vs-code) + - [Cursor](#cursor) + - [Claude Desktop](#claude-desktop) + - [WebStorm / JetBrains IDEs](#webstorm--jetbrains-ides) + - [Verifying the Setup](#verifying-the-setup) + +The Ignite UI CLI MCP server enables AI assistants to discover Ignite UI components, access component documentation, and support related Ignite UI workflows. It must be configured in your editor before these tools become available. + +## VS Code + +Create or edit `.vscode/mcp.json` in your project: + +```json +{ + "servers": { + "igniteui-cli": { + "command": "npx", + "args": ["-y", "igniteui-cli", "mcp"] + } + } +} +``` + +This works whether `igniteui-cli` 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-cli": { + "command": "npx", + "args": ["-y", "igniteui-cli", "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-cli": { + "command": "npx", + "args": ["-y", "igniteui-cli", "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 `-y igniteui-cli mcp` +4. Click OK and restart the AI Assistant + +> The `-y` flag skips interactive prompts if `igniteui-cli` is not already installed locally. + +## Verifying the Setup + +After configuring the MCP server, ask your AI assistant: + +> "List all available Ignite UI components" + +If the MCP server is running, the `list_components` tool will return all available components for the detected framework. diff --git a/.claude/skills/igniteui-wc-customize-component-theme/SKILL.md b/.claude/skills/igniteui-wc-customize-component-theme/SKILL.md new file mode 100644 index 0000000..d04c6e0 --- /dev/null +++ b/.claude/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-invocable: 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/.claude/skills/igniteui-wc-generate-from-image-design/SKILL.md b/.claude/skills/igniteui-wc-generate-from-image-design/SKILL.md new file mode 100644 index 0000000..166972b --- /dev/null +++ b/.claude/skills/igniteui-wc-generate-from-image-design/SKILL.md @@ -0,0 +1,228 @@ +--- +name: igniteui-wc-generate-from-image-design +description: Implement application views from design images using Ignite UI Web Components. Uses MCP servers (igniteui-cli, igniteui-theming) to discover components, generate themes, and follow best practices. Triggers when the user provides a design image (screenshot, mockup, wireframe) and wants it built as a working view with Ignite UI Web Components. Also triggers when the user asks to "implement this design", "build this UI", "convert this mockup", or "create a page from this image" in an Ignite UI Web Components project. +user-invocable: true +--- + +# Implementing Ignite UI Web Components Views from Design Images + +## MANDATORY AGENT PROTOCOL + +Before writing any implementation code, you must complete these steps in order: + +1. Analyze the image and identify all visible regions and UI patterns. +2. Read [references/component-mapping.md](references/component-mapping.md) and [references/gotchas.md](references/gotchas.md). +3. This skill is Web Components-first. Check package layout or licensing only when package choice, component registration, or theming depend on it. +4. To apply a theme, use the theming workflow from this skill and the dedicated `igniteui-wc-customize-component-theme` skill; use the `igniteui-theming` MCP tools instead of styling from memory. +5. Call `get_doc` for every chosen component family before using it. +6. Only then start coding. + +## Workflow + +1. **Analyze the design image** - Read the image, identify every UI section, component, layout structure. +2. **Confirm package layout if needed** - Web Components packages are split by component family; check package layout or licensing only when package choice, component registration, or theming depend on it. +3. **Discover components** - Call `list_components` with targeted filters to find matching components for each UI pattern. +4. **Look up component docs** - Call `get_doc` for every chosen component family before coding. +5. **Generate theme** - (a) To generate a theme, first extract colors and create a color palette using `create_palette` or `create_custom_palette` depending on the scenario. Then extract elevations and call `create_elevations`. Then extract typography and call `create_typography`. Then call `create_theme` when Sass is configured, or import the closest pre-built theme CSS. (b) After a theme exists, prefer using design tokens or scoped semantic CSS variables over raw literals. (c) For every Ignite UI component family that exposes design tokens, call `get_component_design_tokens`, map extracted image tokens to token roles, then call `create_component_theme` with the tokens differing from the global theme for the specific component. +6. **Implement** - Build the screenshot-first layout, data, and view components. +7. **Refine** - Use the `set_size`, `set_spacing`, `set_roundness` tools to refine the view's visual fidelity against the image, then iterate on implementation and theming until the view matches the design closely. +8. **Validate** - Build, test, run, compare against the image, and fix differences. + +## Step 1: Analyze the Design Image + +Read the input image carefully. For each visual section, identify: + +- **Layout structure**: grid rows/columns, sidebar, navbar, content area proportions, and estimated fixed widths or percentages for major regions. +> Note: Do not guess the exact CSS properties at this stage; just identify the high-level structure and relative proportions. Do not try to fit the view into exact breakpoints or pixel values. Try to generate a flexible layout that preserves the observed proportions and can adapt to different screen sizes. You will refine the exact CSS rules in Step 8 after building a first version of the view. +- **Component type**: chart, list, card, grid, form, navigation, etc. +- **Color palette**: primary, secondary, surface/background, accent, text colors. +- **Typography**: font sizes, weights, letter-spacing patterns. +- **Surface styling**: borders, border-radius, shadows, elevation, divider treatments. +- **Data patterns**: what mock data is needed (time series, lists, KPIs, tabular, scheduling). +- **Spacing system**: translate observed padding and gaps into a small reusable scale derived from the design. + +Before writing code, create a decomposition table with one row per visible region containing: + +| Region | Visual role | Candidate component | Custom CSS required | Data type | +|---|---|---|---|---| +| Example: sidebar item list | repeated rows with icon + label | `IgcListComponent` + `IgcListItemComponent` | yes - item height, icon size | domain-appropriate mock data | +| Example: top bar | brand + tabs + search | `IgcNavbarComponent` | yes - multi-zone slot layout | n/a | +| Example: side panel | always-visible navigation | `IgcNavDrawerComponent` | yes - width, item styling | n/a | + +Start every region with the most appropriate Ignite UI component from [references/component-mapping.md](references/component-mapping.md). Only fall back to plain semantic HTML when the component DOM structure is fundamentally incompatible with the design after CSS overrides, tokens, slots, and documented `::part(...)` selectors are considered. Document the reason for any plain-HTML fallback in a code comment. + +Before writing code, produce a compact implementation brief that captures: + +- chosen components per region +- fallback HTML regions +- theme strategy +- package needs +- component registration needs +- major assumptions + +After the table, translate the image into CSS Grid rows and columns first. Preserve desktop proportions before adding responsive behavior, then define explicit breakpoint stacking rules for smaller screens. + +## Step 2-3: Use MCP Tools for Discovery + +This skill is Web Components-first. Check package layout or licensing only when package choice, component registration, or theming depend on it. + +- If the project is unlicensed or uses trial package layout, do not mark documented trial packages as blocked or licensed-only during implementation. +- If the result indicates a licensed package layout, follow the licensed import paths shown in the component reference when needed. + +Then call `list_components` with `framework: "webcomponents"` and relevant filters to find components matching each UI pattern. Common filters: + +- `chart`, `sparkline` - for data visualization +- `list view`, `card`, `avatar`, `badge` - for data display +- `nav`, `navbar`, `drawer`, `dock manager` - for navigation and shell layouts +- `progress` - for metrics +- `grid lite`, `data grid`, `tree grid` - for tabular data +- `calendar`, `date picker`, `combo`, `select`, `input` - for forms and scheduling + +Use narrow search terms to reduce noisy MCP results. Search for the specific UI pattern you need, such as `list view` instead of `list`. + +For component-to-Ignite-UI mapping, see [references/component-mapping.md](references/component-mapping.md). + +## Step 4: Look Up Component API + +For every chosen component category, call `get_doc` with the doc name from `list_components` results (e.g., `name: "card"`, `framework: "webcomponents"`). Use the doc `name` field from the MCP results, not the result title shown in the list. This is mandatory before coding and gives exact usage patterns, slots, events, registration, and API structure. + +Call `search_docs` for feature-based questions (e.g., "how to configure [component] for [specific behavior or styling need]"). + +## Step 5: Generate Theme with MCP + +Use this skill for the image-to-view theming workflow only. The dedicated [`igniteui-wc-customize-component-theme`](../igniteui-wc-customize-component-theme/SKILL.md) skill remains the source of truth for palette-token behavior, global theme rules, and broader theming-system guidance. + +### 5a - Existing app guard (always run first) + +Before generating any theme code, inspect the project's entry point and main stylesheet(s) (commonly `main.ts`, `main.js`, `index.ts`, `app.ts`, `styles.css`, or the app's main theme stylesheet). Look for: + +- an imported pre-built theme CSS file such as `igniteui-webcomponents/themes/light/material.css` +- existing palette tokens or semantic CSS variables already exposed by the app +- existing app-level typography or elevation variables already exposed by the app + +- **Existing theme found** -> the global theme is already set. Do **not** call `create_palette` unless the user explicitly wants a global theme change. Instead: + 1. Inspect the existing theme import, palette definition, and any exposed semantic CSS variables. + 2. Reuse the current design system, variant, and palette tokens wherever they already match the design image. + 3. Skip to **5c** and apply only minimal scoped overrides for the new view's components. +- **No theme found / blank theme setup** -> proceed with **5b** to generate a fresh CSS-based theme baseline. + +### 5b - Global theme generation (new projects only) + +Follow this order - MCP guidance first, image extraction second: + +1. **Read MCP guidance first** - call `theming://guidance/colors/rules` (or `get_theming_guidance`) before looking at the image. This tells you the available theme inputs and any luminance or variant constraints. +2. **Resolve the design system** - infer it from the existing workspace, explicit user request, or the closest visual match in the design. Do not assume one if a stronger signal exists. +3. **Extract from the image** - now that you know the available slots, extract values only for the inputs you actually need. +4. **Call `create_palette` or `create_custom_palette`** with the extracted seed values: + +``` +create_palette({ + primary: "", + secondary: "", + surface: "", + variant: "", + platform: "webcomponents" +}) +``` + +Import the closest built-in theme CSS for the resolved design system and variant, then use `get_color` to translate the generated palette into CSS custom properties, semantic app tokens, and component token values. Apply typography decisions with standard CSS `font-family`, `font-size`, and `font-weight` rules, and apply elevations with CSS box-shadow values or semantic shadow variables. + +Read and act on any luminance warnings returned. If the design needs multiple surface depths that a single generated surface color does not cover, use `create_custom_palette` or define semantic CSS variables for the additional depths in the main stylesheet. + +Use `create_palette` for straightforward designs with a small, coherent color system. Use `create_custom_palette` when the design has multiple distinct surface depths, several accent families, or when the generated palette cannot reliably match the screenshot. + +### 5c - Per-component token discovery and mapping (always run) + +> **Scope:** this step applies to every Ignite UI Web Components family that exposes design tokens. Core components - cards, inputs, select, combo, navbar, nav drawer, list, tabs, date pickers, chips, etc. - are the primary targets. For packages or components that do not expose a practical token surface in the current project, fall back to documented properties, `::part(...)` selectors, or wrapper styles instead of inventing unsupported tokens. + +For **every** chosen Ignite UI component family in Steps 3-4, follow this MCP-first loop - query MCP before touching the image: + +1. **Discover (MCP first)** - call `get_component_design_tokens(component)` before looking at the image for that component. Read the full token list with names, types, and descriptions. Identify which tokens correspond to visible surfaces, text, borders, icons, and interaction states. +2. **Extract (image second)** - now that you know the exact token names, go to the image region for that component and read the exact token value for each relevant token slot. Do not guess; zoom into the component region. +3. **Generate** - call `create_component_theme(component, platform, licensed, tokens)` passing only the tokens whose resolved value differs from the global theme. This produces the minimal scoped theme override set for the component. + +**Example - theming a grid:** +- `get_component_design_tokens("grid")` returns `header-background`, `content-background`, `row-hover-background` among many others. +- Look at the grid region in the image -> extract the color intent for header, row background, and hover state. +- Resolve each value to a palette token or local semantic CSS variable. +- Call `create_component_theme("grid", ...)` with only `{ "header-background": "", "content-background": "", "row-hover-background": "" }`. + +Apply the generated theme blocks to the component selector or a scoped wrapper exactly as shown in the `create_component_theme` output. + +Do not run `create_component_theme` for regions built with custom HTML/CSS only. + +### 5d - Theming sequence summary + +Apply in this exact order: + +1. Inspect the entry point and main stylesheet(s) -> existing theme or blank? +2. Create or update a theme baseline: pre-built theme import plus palette-backed CSS variables and token overrides (Step 5b) +3. For each Ignite UI component: `get_component_design_tokens` -> map image design tokens -> resolve values to design tokens or semantic CSS variables -> `create_component_theme` (Step 5c) +4. Use `get_color` after palette generation whenever a palette token can represent the final color intent + +Use standard CSS `font-family` lists in stylesheets or CSS variables for typography. Do not emit Sass typography mixins for Ignite UI Web Components apps. + +## Step 6: Install Required Packages + +General UI components ship with `igniteui-webcomponents`. Lightweight tabular data can use `igniteui-grid-lite`. Advanced grids, dock manager, and charts require additional packages and may vary by trial versus licensed package layout. Resolve the selected component families against the current workspace and [references/component-mapping.md](references/component-mapping.md). + +After selecting packages, register only the custom elements you actually use with `defineComponents(...)` in the appropriate entry point or setup module, unless the host framework integration already handles registration differently. Use [`igniteui-wc-integrate-with-framework`](../igniteui-wc-integrate-with-framework/SKILL.md) when framework-specific setup details matter. + +If required packages are missing, identify the exact packages and versions required first, then ask for approval before installing packages or changing dependency manifests. + +## Step 7: Implement + +### Structure + +- **Layout**: use Ignite UI layout and data-display components as the starting point for standard regions, then apply CSS Grid/Flexbox and component overrides to match the screenshot. Only substitute plain semantic HTML when an Ignite UI component remains structurally incompatible after a genuine attempt. +- **Data**: use typed mock data that matches the design's density and domain; add models/services only when they help the implementation. +- **View**: keep layout, spacing, typography, and surface styling in CSS rather than inline attributes. +- **Theming**: apply the resolved design system and theme variant from Step 5, and keep color usage aligned with palette tokens or local semantic CSS variables. + +### Implementation Checks + +- Follow repo conventions from `.github/copilot-instructions.md` and `.github/CODING_GUIDELINES.md`. +- Use [references/component-mapping.md](references/component-mapping.md) for component-choice and semantic-fallback rules. +- Use [references/gotchas.md](references/gotchas.md) for components, theming, registration, and API edge cases instead of re-encoding those rules inline. +- Favor Ignite UI components over custom HTML when both approaches can reach similar visual fidelity. +- Register only the custom elements you actually use, and place registration in the project's existing entry-point pattern. +- Use slots, parts, and documented component APIs before reaching for shadow-DOM workarounds. +- Preserve spacing, hierarchy, and data density before adding extra interactivity. +- Avoid generic placeholders when the image shows domain-specific content. +- Document brief assumptions when the image is ambiguous instead of silently guessing. + +## Step 8: Refine + +After the first implementation pass, use the `set_size`, `set_spacing`, and `set_roundness` tools to adjust the view's visual properties and close the gap with the image. Focus on the most visually distinctive elements first (e.g., panel proportions, chart shape, button prominence) before tuning smaller details (e.g., row heights, spacing between regions). + +## Step 9: Validate + +Use this validation loop explicitly: + +1. Build +2. Test +3. Run the app +4. Visually compare against the image +5. Adjust and repeat + +In terminal-only environments, the user performs the visual comparison and provides feedback on any mismatches. Only perform the visual check directly when the environment has browser and screenshot capabilities available to the agent. + +Use this checklist during the first visual comparison: + +- panel proportions +- control density +- chart shape +- legend placement +- button prominence +- row heights +- spacing between regions + +Fix TypeScript, registration, markup, or build errors immediately during the build/test steps. Use the build output, component docs, [references/gotchas.md](references/gotchas.md), and the user's visual feedback to close the remaining gaps. Typical adjustments include: + +- revisiting chart data density, smoothing, or marker visibility +- adjusting layout ratios, region spacing, or row heights +- correcting navigation mode, panel chrome, package choice, or component choice +- tuning theme tokens, component overrides, and dark-surface hierarchy +- re-examining the original design for overlooked sections or missing registration/imports + +After the build succeeds with zero errors, refine layout proportions, color values, missing sections, and typography until the view matches closely. diff --git a/.claude/skills/igniteui-wc-generate-from-image-design/references/component-mapping.md b/.claude/skills/igniteui-wc-generate-from-image-design/references/component-mapping.md new file mode 100644 index 0000000..1312fa6 --- /dev/null +++ b/.claude/skills/igniteui-wc-generate-from-image-design/references/component-mapping.md @@ -0,0 +1,130 @@ +# Ignite UI Web Components Component Mapping Reference + +## Table of Contents +- [Dashboard & Layout Components](#dashboard--layout-components) +- [Chart Components](#chart-components) +- [Data Display Components](#data-display-components) +- [Form & Input Components](#form--input-components) +- [Calendar & Scheduling Components](#calendar--scheduling-components) +- [Package Requirements](#package-requirements) +- [Import Patterns](#import-patterns) + +## Dashboard & Layout Components + +| UI Pattern | Ignite UI Component | Key Properties | +|---|---|---| +| Top navigation bar | `IgcNavbarComponent` | `slot="start"`, default slot, `slot="end"` | +| Side navigation | `IgcNavDrawerComponent` | `open`, `position`, default slot, `slot="mini"` | +| Content cards/panels | `IgcCardComponent` | ``, ``, `` | +| Tabbed content | `IgcTabsComponent` | `` children, `alignment`, `activation` | +| Accordion sections | `IgcAccordionComponent` | `IgcExpansionPanelComponent` children | +| Split layouts | `IgcSplitterComponent` | pane-based layout, nested split regions | +| Tile dashboard | `IgcTileManagerComponent` | drag/resize tiles | +| IDE-style dock layout | `IgcDockManagerComponent` | floating/docking panels (Commercial) | + +Decision rule: + +- Use `IgcNavbarComponent` for a top horizontal bar when its slot structure and behavior match the screenshot. Use slotted content and CSS flex overrides to achieve multi-zone layouts inside it. Use a plain `
` when that is a closer structural fit. +- Use `IgcNavDrawerComponent` for a sidebar or side-navigation panel when drawer structure and behavior match the screenshot. Configure `open`, `position`, and mini content according to whether the design shows fixed, collapsible, or icon-only navigation. Use a plain `