igniteui-theming/dist/mcp/knowledge/docs/setup/platform.js

A set of Sass variables, mixins, and functions for generating palettes, typography, and elevations used by Ignite UI components.

//#region src/knowledge/docs/setup/platform.md?raw
var platform_default = "# Platform Setup Guide\n\nThis document is an instruction resource for AI agents using the Ignite UI Theming MCP. It describes how to detect, configure, and work with target platforms. Follow these rules when helping a user set up theming in their project.\n\n---\n\n## Step 1: Always Detect First\n\n**ALWAYS** call `detect_platform` before generating any theme code. Do not assume a platform; do not skip detection even if the user mentions a framework by name — detection confirms the actual project setup and returns Sass configuration guidance.\n\n```\ndetect_platform({ packageJsonPath: \"./package.json\" })\n```\n\nThe result determines every subsequent tool call's `platform` parameter.\n\n---\n\n## Step 2: Interpret the Detection Result\n\n### High-confidence product detection\n\nWhen `confidence` is `\"high\"` and `platform` is one of `angular`, `webcomponents`, `react`, or `blazor`:\n\n- Use the returned `platform` value in all subsequent tool calls.\n- Use the `platformInfo.themingModule` value for Sass import guidance.\n- If `licensed` is `true` (Angular only), also pass `licensed: true` to theme generation tools.\n\n### Generic (standalone) mode\n\nWhen `platform` is `\"generic\"`:\n\n- No Ignite UI product framework was found. The project can still use `igniteui-theming` directly.\n- Use `platform: \"generic\"` in all subsequent tool calls.\n- The Sass import is `@use 'igniteui-theming' as *;`.\n\n**Tool eligibility in generic mode:**\n\n| Tool                          | Available | Notes                                  |\n| ----------------------------- | --------- | -------------------------------------- |\n| `create_palette`              | YES       | Full functionality                     |\n| `create_custom_palette`       | YES       | Full functionality                     |\n| `create_typography`           | YES       | Full functionality                     |\n| `create_elevations`           | YES       | Full functionality                     |\n| `create_theme`                | YES       | Full functionality                     |\n| `set_size`                    | YES       | Use `scope`, not `component`           |\n| `set_spacing`                 | YES       | Use `scope`, not `component`           |\n| `set_roundness`               | YES       | Use `scope`, not `component`           |\n| `get_color`                   | YES       | Full functionality                     |\n| `read_resource`               | YES       | Full functionality                     |\n| `create_component_theme`      | **NO**    | Requires Ignite UI component selectors |\n| `get_component_design_tokens` | **NO**    | Requires Ignite UI components          |\n\n**IMPORTANT:** For layout tools (`set_size`, `set_spacing`, `set_roundness`) in generic mode, do NOT use the `component` parameter — it resolves Ignite UI component selectors that don't exist in the project. Use `scope` with a custom CSS selector, or omit both for `:root` targeting.\n\n### Ambiguous detection\n\nWhen `ambiguous` is `true` and `platform` is `null`:\n\n- Multiple Ignite UI products were detected (e.g., both Angular and React packages).\n- Do NOT guess. Ask the user which platform to target.\n- Present the `alternatives` array from the result so the user can choose.\n\n### Null / error state\n\nWhen `platform` is `null` and `ambiguous` is not `true`:\n\n- Something went wrong (package.json unreadable, invalid structure).\n- Report the `reason` to the user and ask them to specify a platform manually.\n- Suggest `\"generic\"` if they don't use an Ignite UI product.\n\n---\n\n## Step 3: Configure Sass Load Paths\n\nIf the user will consume **Sass output** (not CSS), they need `node_modules` in their Sass compiler's load paths so that `@use 'igniteui-theming' as *;` resolves correctly.\n\nThe `detect_platform` response includes config-file signals. Use them to give the right guidance:\n\n### Angular (`angular.json` detected)\n\n```json\n// In angular.json → architect → build → options:\n\"stylePreprocessorOptions\": {\n  \"includePaths\": [\"node_modules\"]\n}\n```\n\n### Vite (`vite.config.*` detected)\n\n```js\n// In vite.config.ts/js:\nexport default defineConfig({\n  css: {\n    preprocessorOptions: {\n      scss: {\n        loadPaths: ['node_modules'],\n      },\n    },\n  },\n});\n```\n\n### Next.js (`next.config.*` detected)\n\n```js\n// In next.config.js/mjs/ts:\nmodule.exports = {\n  sassOptions: {\n    loadPaths: ['node_modules'],\n  },\n};\n```\n\n### Other / unknown build tools\n\nIf no recognizable config file was detected, instruct the user to add `node_modules` to their Sass compiler's `loadPaths`. Angular CLI is the exception — it uses `includePaths` in `angular.json`. Investigate the project's build configuration to find the right setting.\n\n### When load paths are NOT needed\n\n- **CSS output**: CSS output is compiled server-side by the MCP. No local Sass toolchain or load path configuration is required. The user can paste the CSS output directly.\n- **Angular with Ignite UI for Angular**: The `igniteui-angular/theming` module is already resolved by Angular's build system when the package is installed.\n\n---\n\n## Step 4: Handle the igniteui-theming Dependency\n\nCheck whether `igniteui-theming` (or a product package like `igniteui-angular`) is in the project's dependencies.\n\n### Package IS installed\n\n- Sass output will work once load paths are configured.\n- CSS output works regardless.\n\n### Package is NOT installed\n\n- **CSS output** still works — the MCP compiles it server-side. Recommend this path for quick results.\n- **Sass output** requires the package to be resolvable. The user must either:\n  - Run `npm install igniteui-theming` (or the product-specific package), OR\n  - Ensure the package is available via `loadPaths` from a parent `node_modules`.\n\nWhen in doubt, suggest CSS output first — it has zero local dependencies.\n\n---\n\n## Step 5: Recommended Workflow\n\nAfter detection and setup, follow this order for a complete theme:\n\n1. **`detect_platform`** — Determine platform and configuration needs.\n2. **`create_palette`** or **`create_custom_palette`** — Define the color system.\n   - Read `theming://guidance/colors/rules` first if unsure about surface/gray color choices.\n3. **`create_typography`** — Set up the type scale (optional but recommended).\n4. **`create_elevations`** — Configure shadows (optional).\n5. **`create_theme`** — Generate the complete theme that brings everything together.\n6. **Layout tools** — Use `set_size`, `set_spacing`, `set_roundness` if the user wants to customize layout tokens.\n7. **`create_component_theme`** — Customize individual component appearances (only for product platforms, NOT generic).\n\n### Output format decision\n\n- Offer **CSS output** when the user wants quick, dependency-free results or is working in a non-Sass environment.\n- Offer **Sass output** when the user has a Sass toolchain set up and wants the flexibility of Sass variables and functions.\n- When both are viable, mention both options and let the user choose.\n\n---\n\n## Platform-Specific Notes\n\n### Angular\n\n- Uses `igniteui-angular/theming` (free) or `@infragistics/igniteui-angular/theming` (licensed) (not `igniteui-theming` directly).\n- Licensed packages use `@infragistics/igniteui-angular/theming` — pass `licensed: true`.\n- Requires `core()` mixin before `theme()` mixin.\n- Typography requires the `ig-typography` CSS class on the root element.\n- Read `theming://platforms/angular` for full platform configuration and usage examples.\n\n### Web Components\n\n- Uses `igniteui-theming` directly.\n- Provides runtime theming via `defineComponents()` and `register()` APIs.\n- Read `theming://platforms/webcomponents` for configuration and runtime config.\n\n### React\n\n- Uses `igniteui-theming` directly (same as Web Components).\n- Read `theming://platforms/react` for configuration and usage examples.\n\n### Blazor\n\n- Uses `igniteui-theming` directly (same as Web Components).\n- Detection relies on `.csproj` files with IgniteUI.Blazor references.\n- Read `theming://platforms/blazor` for configuration and usage examples.\n\n### Generic (Standalone)\n\n- Uses `igniteui-theming` directly.\n- No Ignite UI components — all theme output applies globally via CSS custom properties.\n- Component-specific tools are not available.\n- Layout tools work only with `:root` or custom `scope` selectors.\n- Read `theming://platforms/generic` for presets available in this mode.\n\n### Preset imports for non-Angular platforms\n\nFor all non-Angular platforms (Web Components, React, Blazor, Generic), using preset variables such as `$material-type-scale`, `$indigo-type-scale`, `$material-elevations`, or `$indigo-elevations` requires additional `@use` imports beyond the base `@use 'igniteui-theming' as *;`:\n\n```scss\n// Base module (always required)\n@use 'igniteui-theming' as *;\n\n// Typography presets (required for $<designSystem>-type-scale variables)\n@use 'igniteui-theming/sass/typography/presets' as *;\n\n// Elevation presets (required for $material-elevations / $indigo-elevations)\n@use 'igniteui-theming/sass/elevations/presets' as *;\n```\n\nThe MCP tools (`create_typography`, `create_elevations`, `create_theme`) automatically include these imports in their generated Sass output. Angular is not affected — its `igniteui-angular/theming` module re-exports all presets.\n\n---\n\n## Related Resources\n\n| Resource            | URI                                 | When to read                       |\n| ------------------- | ----------------------------------- | ---------------------------------- |\n| Supported Platforms | `theming://platforms`               | To list all platforms and metadata |\n| Color Guidance      | `theming://guidance/colors`         | Before creating palettes           |\n| Color Rules         | `theming://guidance/colors/rules`   | For surface/gray color decisions   |\n| Spacing & Sizing    | `theming://docs/spacing-and-sizing` | Before using layout tools          |\n";
//#endregion
export { platform_default as default };