|
| 1 | +--- |
| 2 | +name: igniteui-wc-generate-from-image-design |
| 3 | +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. |
| 4 | +user-invocable: true |
| 5 | +--- |
| 6 | + |
| 7 | +# Implementing Ignite UI Web Components Views from Design Images |
| 8 | + |
| 9 | +## MANDATORY AGENT PROTOCOL |
| 10 | + |
| 11 | +Before writing any implementation code, you must complete these steps in order: |
| 12 | + |
| 13 | +1. Analyze the image and identify all visible regions and UI patterns. |
| 14 | +2. Read [references/component-mapping.md](references/component-mapping.md) and [references/gotchas.md](references/gotchas.md). |
| 15 | +3. This skill is Web Components-first. Check package layout or licensing only when package choice, component registration, or theming depend on it. |
| 16 | +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. |
| 17 | +5. Call `get_doc` for every chosen component family before using it. |
| 18 | +6. Only then start coding. |
| 19 | + |
| 20 | +## Workflow |
| 21 | + |
| 22 | +1. **Analyze the design image** - Read the image, identify every UI section, component, layout structure. |
| 23 | +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. |
| 24 | +3. **Discover components** - Call `list_components` with targeted filters to find matching components for each UI pattern. |
| 25 | +4. **Look up component docs** - Call `get_doc` for every chosen component family before coding. |
| 26 | +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. |
| 27 | +6. **Implement** - Build the screenshot-first layout, data, and view components. |
| 28 | +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. |
| 29 | +8. **Validate** - Build, test, run, compare against the image, and fix differences. |
| 30 | + |
| 31 | +## Step 1: Analyze the Design Image |
| 32 | + |
| 33 | +Read the input image carefully. For each visual section, identify: |
| 34 | + |
| 35 | +- **Layout structure**: grid rows/columns, sidebar, navbar, content area proportions, and estimated fixed widths or percentages for major regions. |
| 36 | +> 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. |
| 37 | +- **Component type**: chart, list, card, grid, form, navigation, etc. |
| 38 | +- **Color palette**: primary, secondary, surface/background, accent, text colors. |
| 39 | +- **Typography**: font sizes, weights, letter-spacing patterns. |
| 40 | +- **Surface styling**: borders, border-radius, shadows, elevation, divider treatments. |
| 41 | +- **Data patterns**: what mock data is needed (time series, lists, KPIs, tabular, scheduling). |
| 42 | +- **Spacing system**: translate observed padding and gaps into a small reusable scale derived from the design. |
| 43 | + |
| 44 | +Before writing code, create a decomposition table with one row per visible region containing: |
| 45 | + |
| 46 | +| Region | Visual role | Candidate component | Custom CSS required | Data type | |
| 47 | +|---|---|---|---|---| |
| 48 | +| Example: sidebar item list | repeated rows with icon + label | `IgcListComponent` + `IgcListItemComponent` | yes - item height, icon size | domain-appropriate mock data | |
| 49 | +| Example: top bar | brand + tabs + search | `IgcNavbarComponent` | yes - multi-zone slot layout | n/a | |
| 50 | +| Example: side panel | always-visible navigation | `IgcNavDrawerComponent` | yes - width, item styling | n/a | |
| 51 | + |
| 52 | +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. |
| 53 | + |
| 54 | +Before writing code, produce a compact implementation brief that captures: |
| 55 | + |
| 56 | +- chosen components per region |
| 57 | +- fallback HTML regions |
| 58 | +- theme strategy |
| 59 | +- package needs |
| 60 | +- component registration needs |
| 61 | +- major assumptions |
| 62 | + |
| 63 | +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. |
| 64 | + |
| 65 | +## Step 2-3: Use MCP Tools for Discovery |
| 66 | + |
| 67 | +This skill is Web Components-first. Check package layout or licensing only when package choice, component registration, or theming depend on it. |
| 68 | + |
| 69 | +- If the project is unlicensed or uses trial package layout, do not mark documented trial packages as blocked or licensed-only during implementation. |
| 70 | +- If the result indicates a licensed package layout, follow the licensed import paths shown in the component reference when needed. |
| 71 | + |
| 72 | +Then call `list_components` with `framework: "webcomponents"` and relevant filters to find components matching each UI pattern. Common filters: |
| 73 | + |
| 74 | +- `chart`, `sparkline` - for data visualization |
| 75 | +- `list view`, `card`, `avatar`, `badge` - for data display |
| 76 | +- `nav`, `navbar`, `drawer`, `dock manager` - for navigation and shell layouts |
| 77 | +- `progress` - for metrics |
| 78 | +- `grid lite`, `data grid`, `tree grid` - for tabular data |
| 79 | +- `calendar`, `date picker`, `combo`, `select`, `input` - for forms and scheduling |
| 80 | + |
| 81 | +Use narrow search terms to reduce noisy MCP results. Search for the specific UI pattern you need, such as `list view` instead of `list`. |
| 82 | + |
| 83 | +For component-to-Ignite-UI mapping, see [references/component-mapping.md](references/component-mapping.md). |
| 84 | + |
| 85 | +## Step 4: Look Up Component API |
| 86 | + |
| 87 | +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. |
| 88 | + |
| 89 | +Call `search_docs` for feature-based questions (e.g., "how to configure [component] for [specific behavior or styling need]"). |
| 90 | + |
| 91 | +## Step 5: Generate Theme with MCP |
| 92 | + |
| 93 | +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. |
| 94 | + |
| 95 | +### 5a - Existing app guard (always run first) |
| 96 | + |
| 97 | +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: |
| 98 | + |
| 99 | +- an imported pre-built theme CSS file such as `igniteui-webcomponents/themes/light/material.css` |
| 100 | +- existing palette tokens or semantic CSS variables already exposed by the app |
| 101 | +- existing app-level typography or elevation variables already exposed by the app |
| 102 | + |
| 103 | +- **Existing theme found** -> the global theme is already set. Do **not** call `create_palette` unless the user explicitly wants a global theme change. Instead: |
| 104 | + 1. Inspect the existing theme import, palette definition, and any exposed semantic CSS variables. |
| 105 | + 2. Reuse the current design system, variant, and palette tokens wherever they already match the design image. |
| 106 | + 3. Skip to **5c** and apply only minimal scoped overrides for the new view's components. |
| 107 | +- **No theme found / blank theme setup** -> proceed with **5b** to generate a fresh CSS-based theme baseline. |
| 108 | + |
| 109 | +### 5b - Global theme generation (new projects only) |
| 110 | + |
| 111 | +Follow this order - MCP guidance first, image extraction second: |
| 112 | + |
| 113 | +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. |
| 114 | +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. |
| 115 | +3. **Extract from the image** - now that you know the available slots, extract values only for the inputs you actually need. |
| 116 | +4. **Call `create_palette` or `create_custom_palette`** with the extracted seed values: |
| 117 | + |
| 118 | +``` |
| 119 | +create_palette({ |
| 120 | + primary: "<color extracted from image for primary slot>", |
| 121 | + secondary: "<color extracted from image for secondary slot>", |
| 122 | + surface: "<color extracted from image for surface/background slot>", |
| 123 | + variant: "<resolved theme variant>", |
| 124 | + platform: "webcomponents" |
| 125 | +}) |
| 126 | +``` |
| 127 | + |
| 128 | +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. |
| 129 | + |
| 130 | +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. |
| 131 | + |
| 132 | +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. |
| 133 | + |
| 134 | +### 5c - Per-component token discovery and mapping (always run) |
| 135 | + |
| 136 | +> **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. |
| 137 | +
|
| 138 | +For **every** chosen Ignite UI component family in Steps 3-4, follow this MCP-first loop - query MCP before touching the image: |
| 139 | + |
| 140 | +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. |
| 141 | +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. |
| 142 | +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. |
| 143 | + |
| 144 | +**Example - theming a grid:** |
| 145 | +- `get_component_design_tokens("grid")` returns `header-background`, `content-background`, `row-hover-background` among many others. |
| 146 | +- Look at the grid region in the image -> extract the color intent for header, row background, and hover state. |
| 147 | +- Resolve each value to a palette token or local semantic CSS variable. |
| 148 | +- Call `create_component_theme("grid", ...)` with only `{ "header-background": "<resolved token>", "content-background": "<resolved token>", "row-hover-background": "<resolved token>" }`. |
| 149 | + |
| 150 | +Apply the generated theme blocks to the component selector or a scoped wrapper exactly as shown in the `create_component_theme` output. |
| 151 | + |
| 152 | +Do not run `create_component_theme` for regions built with custom HTML/CSS only. |
| 153 | + |
| 154 | +### 5d - Theming sequence summary |
| 155 | + |
| 156 | +Apply in this exact order: |
| 157 | + |
| 158 | +1. Inspect the entry point and main stylesheet(s) -> existing theme or blank? |
| 159 | +2. Create or update a theme baseline: pre-built theme import plus palette-backed CSS variables and token overrides (Step 5b) |
| 160 | +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) |
| 161 | +4. Use `get_color` after palette generation whenever a palette token can represent the final color intent |
| 162 | + |
| 163 | +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. |
| 164 | + |
| 165 | +## Step 6: Install Required Packages |
| 166 | + |
| 167 | +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). |
| 168 | + |
| 169 | +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. |
| 170 | + |
| 171 | +If required packages are missing, identify the exact packages and versions required first, then ask for approval before installing packages or changing dependency manifests. |
| 172 | + |
| 173 | +## Step 7: Implement |
| 174 | + |
| 175 | +### Structure |
| 176 | + |
| 177 | +- **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. |
| 178 | +- **Data**: use typed mock data that matches the design's density and domain; add models/services only when they help the implementation. |
| 179 | +- **View**: keep layout, spacing, typography, and surface styling in CSS rather than inline attributes. |
| 180 | +- **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. |
| 181 | + |
| 182 | +### Implementation Checks |
| 183 | + |
| 184 | +- Follow repo conventions from `.github/copilot-instructions.md` and `.github/CODING_GUIDELINES.md`. |
| 185 | +- Use [references/component-mapping.md](references/component-mapping.md) for component-choice and semantic-fallback rules. |
| 186 | +- Use [references/gotchas.md](references/gotchas.md) for components, theming, registration, and API edge cases instead of re-encoding those rules inline. |
| 187 | +- Favor Ignite UI components over custom HTML when both approaches can reach similar visual fidelity. |
| 188 | +- Register only the custom elements you actually use, and place registration in the project's existing entry-point pattern. |
| 189 | +- Use slots, parts, and documented component APIs before reaching for shadow-DOM workarounds. |
| 190 | +- Preserve spacing, hierarchy, and data density before adding extra interactivity. |
| 191 | +- Avoid generic placeholders when the image shows domain-specific content. |
| 192 | +- Document brief assumptions when the image is ambiguous instead of silently guessing. |
| 193 | + |
| 194 | +## Step 8: Refine |
| 195 | + |
| 196 | +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). |
| 197 | + |
| 198 | +## Step 9: Validate |
| 199 | + |
| 200 | +Use this validation loop explicitly: |
| 201 | + |
| 202 | +1. Build |
| 203 | +2. Test |
| 204 | +3. Run the app |
| 205 | +4. Visually compare against the image |
| 206 | +5. Adjust and repeat |
| 207 | + |
| 208 | +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. |
| 209 | + |
| 210 | +Use this checklist during the first visual comparison: |
| 211 | + |
| 212 | +- panel proportions |
| 213 | +- control density |
| 214 | +- chart shape |
| 215 | +- legend placement |
| 216 | +- button prominence |
| 217 | +- row heights |
| 218 | +- spacing between regions |
| 219 | + |
| 220 | +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: |
| 221 | + |
| 222 | +- revisiting chart data density, smoothing, or marker visibility |
| 223 | +- adjusting layout ratios, region spacing, or row heights |
| 224 | +- correcting navigation mode, panel chrome, package choice, or component choice |
| 225 | +- tuning theme tokens, component overrides, and dark-surface hierarchy |
| 226 | +- re-examining the original design for overlooked sections or missing registration/imports |
| 227 | + |
| 228 | +After the build succeeds with zero errors, refine layout proportions, color values, missing sections, and typography until the view matches closely. |
0 commit comments