igniteui-cli 15.8.1 → 15.8.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +4 -4
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/client-scripts.md +7 -7
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/form-controls.md +65 -18
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-components/references/setup.md +1 -1
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-generate-from-image-design/references/component-mapping.md +5 -5
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-generate-from-image-design/references/gotchas.md +23 -4
- package/templates/blazor/igb/projects/ai-config/files/skills/igniteui-blazor-grids/references/editing.md +4 -3
- package/templates/react/igr-ts/constants.d.ts +1 -1
- package/templates/react/igr-ts/constants.js +1 -1
- package/templates/webcomponents/igc-ts/constants.d.ts +1 -1
- package/templates/webcomponents/igc-ts/constants.js +1 -1
- package/templates/webcomponents/igc-ts/projects/_base_with_home/files/package.json +1 -1
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/README.md +15 -15
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-choose-components/SKILL.md +36 -36
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-choose-components/reference/mcp-setup.md +8 -6
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-customize-component-theme/SKILL.md +62 -60
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-customize-component-theme/references/mcp-setup.md +8 -6
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-figma-to-app/SKILL.md +107 -94
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-figma-to-app/references/asset-extraction.md +32 -32
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-figma-to-app/references/design-provenance.md +32 -30
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-figma-to-app/references/design-token-bridge.md +84 -71
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-figma-to-app/references/figma-component-map.md +45 -44
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-figma-to-app/references/figma-exploration.md +57 -51
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-figma-to-app/references/mcp-setup.md +23 -23
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-figma-to-app/references/project-setup.md +28 -26
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-figma-to-app/references/theme-generation.md +45 -35
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-figma-to-app/references/validation-patterns.md +38 -29
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-generate-from-image-design/SKILL.md +63 -63
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-generate-from-image-design/references/component-mapping.md +12 -12
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-generate-from-image-design/references/gotchas.md +24 -24
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-grids/SKILL.md +23 -23
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-integrate-with-framework/SKILL.md +23 -23
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-integrate-with-framework/references/angular.md +10 -10
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-integrate-with-framework/references/react.md +9 -9
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-integrate-with-framework/references/vanilla-js.md +9 -9
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-integrate-with-framework/references/vue.md +11 -11
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-migrate-grid-lite-to-premium/SKILL.md +18 -18
- package/templates/webcomponents/igc-ts/projects/ai-config/files/skills/igniteui-wc-optimize-bundle-size/SKILL.md +78 -48
|
@@ -2,19 +2,19 @@
|
|
|
2
2
|
|
|
3
3
|
> **Part of the [`igniteui-wc-figma-to-app`](../SKILL.md) skill.**
|
|
4
4
|
>
|
|
5
|
-
> Use this file in Phase 1h to identify and extract image assets from Figma artboards before implementation. Read
|
|
5
|
+
> Use this file in Phase 1h to identify and extract image assets from Figma artboards before implementation. Read all of it before you call an extraction tool.
|
|
6
6
|
>
|
|
7
|
-
> **Zero-placeholder policy:** every image asset visible in the Figma design
|
|
7
|
+
> **Zero-placeholder policy:** extract and commit every image asset that is visible in the Figma design before Phase 4 starts. Do not use gradient placeholders or empty `<div>` boxes. If the highest-fidelity method is not available, use the next tier. Always extract a real asset.
|
|
8
8
|
|
|
9
9
|
---
|
|
10
10
|
|
|
11
11
|
## Step 0 — Decide Where Assets Live
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
Before you download an asset, find the row that matches your project:
|
|
14
14
|
|
|
15
15
|
| Project shape | Asset directory | Referenced as |
|
|
16
16
|
| --- | --- | --- |
|
|
17
|
-
| CLI-scaffolded (`igniteui-cli new --framework=webcomponents`) | `src/assets/images/`, `src/assets/icons/` | `/assets/images/hero.jpg` —
|
|
17
|
+
| CLI-scaffolded (`igniteui-cli new --framework=webcomponents`) | `src/assets/images/`, `src/assets/icons/` | `/assets/images/hero.jpg` — `vite-plugin-static-copy` copies it to the build output |
|
|
18
18
|
| Stock Vite / plain bundler | `public/images/`, `public/icons/` | `/images/hero.jpg` |
|
|
19
19
|
| Bundler-processed (hashed) assets | anywhere under `src/` | `import heroUrl from '../assets/hero.jpg'` then bind the URL |
|
|
20
20
|
|
|
@@ -28,9 +28,9 @@ mkdir -p src/assets/images src/assets/icons # or public/images public/icons
|
|
|
28
28
|
|
|
29
29
|
## Step 1 — Acquire the Figma File Key (Required for the REST API)
|
|
30
30
|
|
|
31
|
-
The Figma REST API needs a **file key**
|
|
31
|
+
The Figma REST API needs a **file key** and a **personal access token**. The file key is the identifier in each Figma file URL. If you have the file key from Phase 1, use it again (the remote Figma server always has one). If you do not have it, ask the user:
|
|
32
32
|
|
|
33
|
-
> "To extract image assets at the highest quality, I need the Figma file key. In the Figma desktop app
|
|
33
|
+
> "To extract image assets at the highest quality, I need the Figma file key. In the Figma desktop app, right-click the file tab and select **Copy link**. The URL looks like `https://www.figma.com/design/ABCDEF1234567890/My-File-Name`. The file key is the segment after `/design/`: **`ABCDEF1234567890`**. If you cannot get it now, I will use the fallback methods. I will also tell you which assets to export again at higher quality."
|
|
34
34
|
|
|
35
35
|
```bash
|
|
36
36
|
echo "https://www.figma.com/design/ABCDEF1234567890/My-App" \
|
|
@@ -40,7 +40,7 @@ export FILE_KEY="ABCDEF1234567890"
|
|
|
40
40
|
export FIGMA_TOKEN="your-personal-access-token" # REST API only — see below
|
|
41
41
|
```
|
|
42
42
|
|
|
43
|
-
The Figma MCP servers do **not** use a personal access token, so this is a separate token (see `mcp-setup.md § Personal access token`). Ask the user to export it in the agent's shell
|
|
43
|
+
The Figma MCP servers do **not** use a personal access token, so this token is a separate token (see `mcp-setup.md § Personal access token`). Ask the user to export it in the agent's shell. Do not write it into a project file.
|
|
44
44
|
|
|
45
45
|
---
|
|
46
46
|
|
|
@@ -51,7 +51,7 @@ The Figma MCP servers do **not** use a personal access token, so this is a separ
|
|
|
51
51
|
| **Image fill** | A photo, texture, or raster image dragged/pasted into Figma, stored as an IMAGE fill | Layer has a fill of type `IMAGE`; `imageRef` in node data | REST API Method A → original source file |
|
|
52
52
|
| **Vector asset** | A logo, icon, or illustration drawn in Figma with vector tools | Node type `VECTOR`, `BOOLEAN_OPERATION`, or `GROUP` | REST API Method B → clean SVG |
|
|
53
53
|
|
|
54
|
-
Do **not** confuse
|
|
54
|
+
Do **not** confuse these assets with component instances that Phase 1f mapped to a canonical role. These instances can come from the Indigo.Design UI Kits or from a different kit. They become Ignite UI components, not extracted assets.
|
|
55
55
|
|
|
56
56
|
---
|
|
57
57
|
|
|
@@ -73,7 +73,7 @@ Do **not** confuse either with component instances — from the Indigo.Design UI
|
|
|
73
73
|
>
|
|
74
74
|
> - Any layer that Table A maps to a component (`_Button`, `_Input`, `Button`, `Text field`, … — kit component instances from any kit)
|
|
75
75
|
> - Icon glyphs available from a registerable package (Material Icons Extended, Material Symbols, Lucide, Fluent, …; see `figma-component-map.md § Icons`). Register them with `registerIconFromText` and render `<igc-icon>` instead
|
|
76
|
-
> - Artboard
|
|
76
|
+
> - Artboard and frame boundaries
|
|
77
77
|
|
|
78
78
|
### Size heuristic
|
|
79
79
|
|
|
@@ -81,7 +81,7 @@ Large rectangles (width or height > 200px) at key layout positions (hero area, s
|
|
|
81
81
|
|
|
82
82
|
### Confirm with design context
|
|
83
83
|
|
|
84
|
-
`figma_get_design_context` returns the reference code **plus a JSON block of download URLs for the assets it references**. Each entry confirms the node is a real asset and gives you
|
|
84
|
+
`figma_get_design_context` returns the reference code **plus a JSON block of download URLs for the assets it references**. Each entry confirms that the node is a real asset and gives a URL that you can download directly. Record these URLs. Tier 2 uses them, and they expire after a short time.
|
|
85
85
|
|
|
86
86
|
---
|
|
87
87
|
|
|
@@ -98,11 +98,11 @@ Do you have BOTH the FILE_KEY and a FIGMA_TOKEN?
|
|
|
98
98
|
└─ NO → Tier 4 (CSS placeholder + TODO — last resort only).
|
|
99
99
|
```
|
|
100
100
|
|
|
101
|
-
The remote server also
|
|
101
|
+
The remote server also has `figma_download_assets` (a maximum of 20 nodes for each call; it gives exports and original images). If this tool is in the tool list and you do not have a FIGMA_TOKEN, use it for Tier 2.
|
|
102
102
|
|
|
103
103
|
**At the end of Phase 1h, if you used Tier 2 or Tier 3 for any asset:**
|
|
104
104
|
|
|
105
|
-
> Tell the user: "
|
|
105
|
+
> Tell the user: "I extracted the following assets at reduced quality because the Figma REST API was not available (no file key or no personal access token): [list]. To replace them with the original source files, run the Tier 1 REST API commands when you have both."
|
|
106
106
|
|
|
107
107
|
---
|
|
108
108
|
|
|
@@ -112,7 +112,7 @@ The remote server also offers `figma_download_assets` (up to 20 nodes per call,
|
|
|
112
112
|
|
|
113
113
|
#### Method A — Original Image Fills
|
|
114
114
|
|
|
115
|
-
|
|
115
|
+
This method downloads the **original uploaded file** at native resolution. It never downloads a re-render.
|
|
116
116
|
|
|
117
117
|
```bash
|
|
118
118
|
# A.1 — all image fill URLs in the file
|
|
@@ -132,7 +132,7 @@ IMAGE_URL=$(jq -r '.images["<imageRef>"]' /tmp/figma_image_fills.json)
|
|
|
132
132
|
curl -sL "$IMAGE_URL" -o src/assets/images/hero-background.jpg
|
|
133
133
|
```
|
|
134
134
|
|
|
135
|
-
> **URL expiry:** image fill URLs expire in **14 days**. Download during the session.
|
|
135
|
+
> **URL expiry:** image fill URLs expire in **14 days**. Download the images during the session.
|
|
136
136
|
|
|
137
137
|
#### Method B — Node Export (SVG, PNG, JPG)
|
|
138
138
|
|
|
@@ -169,25 +169,25 @@ done
|
|
|
169
169
|
| `svg_outline_text` | `false` | Keep text as `<text>` elements (smaller, accessible) |
|
|
170
170
|
| `contents_only` | `true` | Render the node in isolation |
|
|
171
171
|
|
|
172
|
-
> **Export URL expiry:** export URLs expire in **30 days**. Download immediately
|
|
172
|
+
> **Export URL expiry:** export URLs expire in **30 days**. Download the files immediately. Then rename each file by its purpose.
|
|
173
173
|
|
|
174
174
|
---
|
|
175
175
|
|
|
176
176
|
### Tier 2 — Download the Design Context Asset URLs
|
|
177
177
|
|
|
178
|
-
**Use when:** Tier 1 is
|
|
178
|
+
**Use when:** Tier 1 is not available, but `figma_get_design_context` returned asset URLs for the node.
|
|
179
179
|
|
|
180
180
|
```bash
|
|
181
181
|
curl -sL "<asset-url-from-design-context>" -o src/assets/images/hero-background.png
|
|
182
182
|
curl -sL "<asset-url-from-design-context>" -o src/assets/icons/logo.svg
|
|
183
183
|
```
|
|
184
184
|
|
|
185
|
-
|
|
185
|
+
The URLs are in these locations in the response:
|
|
186
186
|
|
|
187
|
-
- the JSON block of download URLs
|
|
188
|
-
- `const imgXxx = "…";` declarations at the top of the generated code,
|
|
187
|
+
- the JSON block of download URLs that comes with the reference code, and
|
|
188
|
+
- `const imgXxx = "…";` declarations at the top of the generated code, which `<img src={imgXxx} />` or `background-image` references
|
|
189
189
|
|
|
190
|
-
**Limitations:** these are renderer outputs, not originals
|
|
190
|
+
**Limitations:** these files are renderer outputs, not originals. Vectors can come back rasterized. The URLs expire: a desktop-server URL stops working when the Figma desktop app closes, and a remote-server URL expires after a short time. Download the files before you do other work. Give each file a descriptive name, and flag it in the manifest:
|
|
191
191
|
|
|
192
192
|
```typescript
|
|
193
193
|
// TODO: re-export via Tier 1 REST API once FILE_KEY and FIGMA_TOKEN are available
|
|
@@ -198,7 +198,7 @@ heroBg: '/assets/images/hero-background.png',
|
|
|
198
198
|
|
|
199
199
|
### Tier 3 — `figma_get_screenshot` per Node
|
|
200
200
|
|
|
201
|
-
|
|
201
|
+
Specify the node the same way as in Phase 1 (`figma-exploration.md § Before the First Call`):
|
|
202
202
|
|
|
203
203
|
```
|
|
204
204
|
// Remote server
|
|
@@ -208,9 +208,9 @@ figma_get_screenshot({ nodeId: "<nodeId>", maxDimension: 2048 })
|
|
|
208
208
|
figma_get_screenshot({})
|
|
209
209
|
```
|
|
210
210
|
|
|
211
|
-
If the response is a URL, download it
|
|
211
|
+
If the response is a URL, download it directly into the assets directory, because the URL expires after a short time. If the image comes back inline, save it from the response. To get more detail, increase `maxDimension`.
|
|
212
212
|
|
|
213
|
-
**Limitations:** a render, not a source file
|
|
213
|
+
**Limitations:** the result is a render, not a source file. Vectors are rasterized. The image can include the surrounding canvas. Label these files:
|
|
214
214
|
|
|
215
215
|
```typescript
|
|
216
216
|
// TODO: re-export at higher fidelity via Tier 1 — current version is a node render
|
|
@@ -221,7 +221,7 @@ heroBg: '/assets/images/hero-background.png',
|
|
|
221
221
|
|
|
222
222
|
### Tier 4 — CSS Fallback (Last Resort Only)
|
|
223
223
|
|
|
224
|
-
**Use only when** the layer is
|
|
224
|
+
**Use only when** you confirm that the layer is a pure color fill or gradient. Do not use it because extraction is difficult.
|
|
225
225
|
|
|
226
226
|
```css
|
|
227
227
|
.hero-banner {
|
|
@@ -274,7 +274,7 @@ render() {
|
|
|
274
274
|
}
|
|
275
275
|
```
|
|
276
276
|
|
|
277
|
-
Always set `width`/`height` (or a CSS aspect ratio) to
|
|
277
|
+
Always set `width`/`height` (or a CSS aspect ratio) to prevent layout shift. Always set `alt` for the Phase 5g accessibility check. Use `loading="lazy"` for below-the-fold images and `fetchpriority="high"` for the LCP image.
|
|
278
278
|
|
|
279
279
|
### Background images in component styles
|
|
280
280
|
|
|
@@ -288,7 +288,7 @@ static styles = css`
|
|
|
288
288
|
`;
|
|
289
289
|
```
|
|
290
290
|
|
|
291
|
-
> **Use root-absolute paths inside `css`.** A Lit `css` template is not a stylesheet file on disk
|
|
291
|
+
> **Use root-absolute paths inside `css`.** A Lit `css` template is not a stylesheet file on disk. Relative URLs resolve against the *document*, not the component, so `url('../x.png')` fails on nested routes. Use `/assets/...`, or let the bundler hash the asset:
|
|
292
292
|
>
|
|
293
293
|
> ```typescript
|
|
294
294
|
> import heroUrl from '../../assets/images/hero-background.jpg';
|
|
@@ -297,7 +297,7 @@ static styles = css`
|
|
|
297
297
|
|
|
298
298
|
### Images inside Ignite UI components
|
|
299
299
|
|
|
300
|
-
Use the component's slot
|
|
300
|
+
Use the component's slot instead of absolute positioning:
|
|
301
301
|
|
|
302
302
|
```html
|
|
303
303
|
<igc-card>
|
|
@@ -320,7 +320,7 @@ registerIconFromText('brand-logo', logoSvg, 'app');
|
|
|
320
320
|
<igc-icon name="brand-logo" collection="app"></igc-icon>
|
|
321
321
|
```
|
|
322
322
|
|
|
323
|
-
|
|
323
|
+
When you register an extracted SVG, it inherits `color` and the theme. A plain `<img>` cannot do this. See `figma-component-map.md § Icons` for the Material Icons Extended setup.
|
|
324
324
|
|
|
325
325
|
---
|
|
326
326
|
|
|
@@ -328,16 +328,16 @@ Registering an extracted SVG lets it inherit `color` and the theme, which a plai
|
|
|
328
328
|
|
|
329
329
|
| Pitfall | Consequence | Fix |
|
|
330
330
|
| ------------------------------------------------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
|
|
331
|
-
| Skipping asset extraction (gradient placeholders) |
|
|
331
|
+
| Skipping asset extraction (gradient placeholders) | The implementation does not match the design; Phase 5 fails | Always use at least Tier 2 or Tier 3 — never skip |
|
|
332
332
|
| Not asking for the file key before starting | Falls back to Tier 2/3 when Tier 1 was possible | Reuse the Phase 1 file key, or ask for it in Step 1, and ask for a REST token |
|
|
333
333
|
| Leaving design-context or CDN URLs in source code | URLs expire in hours to 30 days; production breaks | Download during the session; reference only local paths |
|
|
334
|
-
| Naming assets by node ID (`node-123-456.png`) |
|
|
334
|
+
| Naming assets by node ID (`node-123-456.png`) | Difficult to maintain | Name by purpose: `hero-background.jpg`, `company-logo.svg` |
|
|
335
335
|
| Relative `url()` inside a Lit `css` template | 404s on nested routes — the URL resolves against the document | Use `/assets/...` or a bundler import |
|
|
336
|
-
| Putting assets in `src/` in a stock Vite app |
|
|
336
|
+
| Putting assets in `src/` in a stock Vite app | The dev server serves them, but `vite build` does not emit them unless you import or copy them (the Ignite UI CLI scaffold copies `src/assets`); 404 in production | Use `public/`, or import the asset so the bundler emits it |
|
|
337
337
|
| Using a node screenshot for an SVG logo | Rasterized logo, no scaling, no theming | Tier 1 Method B with `format=svg` |
|
|
338
338
|
| Exporting PNG at `scale=1` | Blurry on HiDPI screens | Always `scale=2` |
|
|
339
339
|
| `svg_outline_text=true` (the default) | Text converted to paths; larger file; no accessibility | Set `svg_outline_text=false` |
|
|
340
340
|
| Extracting kit component instances as images | A static picture instead of a working component | Check Table A / `figma-component-map.md` — those are components, whatever kit they came from |
|
|
341
341
|
| Extracting registerable icons as PNGs | Icons cannot inherit theme color | Register the SVG and use `<igc-icon>` |
|
|
342
|
-
| Extracting background colors or gradients as images |
|
|
342
|
+
| Extracting background colors or gradients as images | A larger bundle; theming breaks | Colors → palette variables and component tokens |
|
|
343
343
|
| Not creating asset directories before `curl` | Silent failures or files in the wrong place | `mkdir -p` first |
|
|
@@ -2,32 +2,32 @@
|
|
|
2
2
|
|
|
3
3
|
> **Part of the [`igniteui-wc-figma-to-app`](../SKILL.md) skill.**
|
|
4
4
|
>
|
|
5
|
-
> Use this file in Phase 1f to decide **where every component in the design came from
|
|
5
|
+
> Use this file in Phase 1f to decide **where every component in the design came from**. Also use it to normalize each component into a **canonical role**. [figma-component-map.md](figma-component-map.md) resolves the canonical role to an Ignite UI tag. Read this file in full before you build the Phase 1g decomposition table.
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
## Why This Step Exists
|
|
10
10
|
|
|
11
|
-
Designers build Figma screens from many sources
|
|
11
|
+
Designers build Figma screens from many sources. These sources include the Infragistics **Indigo.Design UI Kits** and public kits (Material 3 Design Kit, Fluent 2, Bootstrap, shadcn/ui, Untitled UI, Ant Design, iOS/Apple kits). They also include an in-house design system, or plain frames with no components at all. The Ignite UI kits map to Ignite UI one-to-one by layer name. Other kits do not. However, they describe the same **roles** (a high-emphasis button, an outlined text field, a tab strip) with different names and variant properties.
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
A direct translation from each kit to Ignite UI tags needs one mapping table for each kit. Instead, this skill uses two steps: **kit → canonical role** (a small vocabulary, normalized here) and **canonical role → Ignite UI** (one table, in `figma-component-map.md`). A kit that you have not seen before also works, if you can normalize its variant names.
|
|
14
14
|
|
|
15
15
|
---
|
|
16
16
|
|
|
17
17
|
## Step 1 — Collect the Evidence for Each Instance
|
|
18
18
|
|
|
19
|
-
For every component-like layer in the target artboard,
|
|
19
|
+
For every component-like layer in the target artboard, collect the evidence that the design data shows. Use the least expensive source first.
|
|
20
20
|
|
|
21
21
|
| Evidence | Where it comes from | Strength |
|
|
22
22
|
| --- | --- | --- |
|
|
23
23
|
| **Layer / main-component name** | `data-name` in `figma_get_design_context`; instance names in `figma_get_metadata` XML | Medium. Designers rename layers, and detached instances keep the old name. |
|
|
24
24
|
| **Variant properties** (`Variant=Primary`, `Size=md`, `State=Hover`) | The design-context code (component props), or the REST API (below) | Strong. This is the kit's own statement of role and variant. |
|
|
25
25
|
| **Component description** | REST `components` map, or design-context annotations | Strong when present. Kits often document intent here. |
|
|
26
|
-
| **Code Connect mapping** | `figma_get_code_connect_map` | Strong for **role**, but it
|
|
27
|
-
| **Library / source file name** | `figma_get_libraries` (the libraries the file subscribes to: name, key, description) and `figma_search_design_system` (returns `libraryName` for a component name). Check the connected server
|
|
26
|
+
| **Code Connect mapping** | `figma_get_code_connect_map` | Strong for **role**, but it can point to a *different* library. See the caveat below. |
|
|
27
|
+
| **Library / source file name** | `figma_get_libraries` (the libraries the file subscribes to: name, key, description) and `figma_search_design_system` (returns `libraryName` for a component name). Check the tool list of the connected server, because the available tools change with the Figma MCP version. | Strong for kit identity. Call `get_libraries` **once per file**: it identifies the kits that the file uses before you look at a single instance. |
|
|
28
28
|
| **Structure + visuals** | Auto-layout, children, fills, size, the screenshot | Weak alone. It is the only evidence for un-componentized frames. |
|
|
29
29
|
|
|
30
|
-
**Reading exact variant properties
|
|
30
|
+
**Reading exact variant properties through the REST API** (use it when names are ambiguous and `FIGMA_TOKEN` + `FILE_KEY` are available. The token is the REST API token from `mcp-setup.md § Personal access token`, not an MCP credential):
|
|
31
31
|
|
|
32
32
|
```bash
|
|
33
33
|
curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
|
|
@@ -44,30 +44,30 @@ jq '.nodes[].components, .nodes[].componentSets' /tmp/figma_nodes.json
|
|
|
44
44
|
|
|
45
45
|
**Design-context quirks that matter here:**
|
|
46
46
|
|
|
47
|
-
- `data-name`
|
|
47
|
+
- `data-name` keeps the main-component name, for example `.Status badge`. Components can also show as local functions with typed props (`Button({ variant = "outline" })`). These props contain the variant values.
|
|
48
48
|
- Nodes inside an instance have IDs like `I9:12;6:3`. Treat those as parts of the parent component, not as components of their own.
|
|
49
|
-
- If the response
|
|
50
|
-
-
|
|
49
|
+
- If the response has the **sparse** flag (large frames), fetch the visible child nodes in one parallel batch. Do not guess from the partial output.
|
|
50
|
+
- Code Connect can map components to a non-Ignite library. In that case, pass `disableCodeConnect: true` (where the server supports it). This keeps foreign imports out of the reference output. Read the mapping separately with `figma_get_code_connect_map`.
|
|
51
51
|
|
|
52
|
-
`remote: true` on a component means it came from a published library. `componentSetId` groups the variants of one component. Use the **component-set name** as the main-component name, because instance layer names
|
|
52
|
+
`remote: true` on a component means that it came from a published library. `componentSetId` groups the variants of one component. Use the **component-set name** as the main-component name, because designers frequently edit instance layer names.
|
|
53
53
|
|
|
54
54
|
---
|
|
55
55
|
|
|
56
56
|
## Step 2 — Classify Provenance (Per Instance)
|
|
57
57
|
|
|
58
|
-
Classify **per instance**, not per file. Real files mix sources
|
|
58
|
+
Classify **per instance**, not per file. Real files mix sources. For example, an Ignite UI kit navbar can be next to a hand-drawn KPI tile and a third-party date picker.
|
|
59
59
|
|
|
60
60
|
| Tier | What it is | Recognized by | Resolution path |
|
|
61
61
|
| --- | --- | --- | --- |
|
|
62
62
|
| **A — Ignite UI kit** | Instance of an Indigo.Design UI Kit component | Leading-underscore names (`_Button/Contained`, `_Input/Border`), `Indigo.Design` library names, hidden `size-[0.5px]` variant-indicator nodes, the kit variable collections | Direct lookup in `figma-component-map.md` by kit name. Highest confidence. |
|
|
63
|
-
| **B — Other component library** | Instance of any other published or local component (public kit or in-house) | A main component / component set with variant properties, without Tier A fingerprints | **Normalize** (Step 3) to a canonical role, then
|
|
64
|
-
| **C — Un-componentized** | Plain frames, groups, or detached instances | No main component. Type is `FRAME` / `GROUP`, or a detached copy that still
|
|
63
|
+
| **B — Other component library** | Instance of any other published or local component (public kit or in-house) | A main component / component set with variant properties, without Tier A fingerprints | **Normalize** (Step 3) to a canonical role, then find it in the canonical role index of `figma-component-map.md`. |
|
|
64
|
+
| **C — Un-componentized** | Plain frames, groups, or detached instances | No main component. Type is `FRAME` / `GROUP`, or a detached copy that still has a component-like name | **Infer** the role from structure and visuals (Step 4). Lowest confidence. Confirm with the user. |
|
|
65
65
|
|
|
66
66
|
Record the tier and a confidence (**high / medium / low**) in the Phase 1g Table A.
|
|
67
67
|
|
|
68
68
|
### Recognizing common public kits (confirmation only)
|
|
69
69
|
|
|
70
|
-
These fingerprints help name the kit in the plan and choose the theme baseline (Phase 3b). Normalization does **not** depend on them. Kit files change between versions, so treat every row as a hint, not a rule.
|
|
70
|
+
These fingerprints help you name the kit in the plan and choose the theme baseline (Phase 3b). Normalization does **not** depend on them. Kit files change between versions, so treat every row as a hint, not a rule.
|
|
71
71
|
|
|
72
72
|
| Kit | Typical fingerprints | Default icon set |
|
|
73
73
|
| --- | --- | --- |
|
|
@@ -77,17 +77,19 @@ These fingerprints help name the kit in the plan and choose the theme baseline (
|
|
|
77
77
|
| shadcn/ui kits | Semantic variables `background`, `foreground`, `primary`, `primary-foreground`, `muted`, `accent`, `border`, `input`, `ring`, `radius`; button variants *default / secondary / outline / ghost / link / destructive* | Lucide |
|
|
78
78
|
| Untitled UI | `Colors/Brand/600`, `Colors/Gray (light mode)/…`, `bg-primary`, `text-secondary`; button hierarchy *Primary / Secondary / Tertiary / Link* (+ *color / gray*) | Untitled UI Icons (paid Pro tier; check the license) |
|
|
79
79
|
| Ant Design kits | Button type *Primary / Default / Dashed / Text / Link*; `colorPrimary`, `colorBgContainer` tokens | Ant Design Icons |
|
|
80
|
-
| iOS / Apple kits | SF Pro type, *Filled / Tinted / Gray / Plain* buttons, grouped inset lists, tab bars at the bottom | SF Symbols (not licensed for web; substitute) |
|
|
80
|
+
| iOS / Apple kits | SF Pro type, *Filled / Tinted / Gray / Plain* buttons, grouped inset lists, tab bars at the bottom | SF Symbols (not licensed for web; use a substitute) |
|
|
81
81
|
|
|
82
82
|
---
|
|
83
83
|
|
|
84
84
|
## Step 3 — Normalize Tier B Instances Into Canonical Roles
|
|
85
85
|
|
|
86
|
-
Normalize **role**, **emphasis**, **style**, **size**, and **state** separately. Match property values case-insensitively and by meaning, not exact spelling.
|
|
86
|
+
Normalize **role**, **emphasis**, **style**, **size**, and **state** separately. Match property values case-insensitively and by meaning, not by exact spelling.
|
|
87
87
|
|
|
88
88
|
### Role (from the component or component-set name)
|
|
89
89
|
|
|
90
|
-
|
|
90
|
+
Remove prefixes, sigils, status emoji, numbering, and platform tags (`.Button`, `Button / Base`, `❖ Button`, `✅ Button`, `[Web] Button`, `Buttons`). A leading `.` usually marks a private or base component. A leading `_` with a `/` path (`_Button/Contained`) is the Tier A Indigo.Design fingerprint. Classify the component before you remove anything.
|
|
91
|
+
|
|
92
|
+
Ignore the order of variant axes: `Button (M, Accent)` is the same as `Button (Accent, M)`. Then compare the result with the canonical roles in `figma-component-map.md § Canonical Role Index`. Common synonyms:
|
|
91
93
|
|
|
92
94
|
| Canonical role | Also called |
|
|
93
95
|
| --- | --- |
|
|
@@ -126,7 +128,7 @@ Strip prefixes, sigils, status emoji, numbering, and platform tags (`.Button`, `
|
|
|
126
128
|
| **elevated** | Elevated, Raised |
|
|
127
129
|
| **danger** (modifier) | Destructive, Danger, Error, Critical |
|
|
128
130
|
|
|
129
|
-
"Secondary" means *outlined* in some kits and *a filled button in the secondary color* in others. Read the visuals of that instance (fill vs stroke) before
|
|
131
|
+
"Secondary" means *outlined* in some kits and *a filled button in the secondary color* in others. Read the visuals of that instance (fill vs stroke) before you choose.
|
|
130
132
|
|
|
131
133
|
### Style (form fields)
|
|
132
134
|
|
|
@@ -140,8 +142,8 @@ Strip prefixes, sigils, status emoji, numbering, and platform tags (`.Button`, `
|
|
|
140
142
|
|
|
141
143
|
### Size and state
|
|
142
144
|
|
|
143
|
-
- **Size:** record the measured control **height** in px (from the design context), not the kit's size name. Kits
|
|
144
|
-
- **State:** `Hover`, `Focused`, `Pressed`, `Disabled`, `Error`, `Selected` variants are **states**, not different components. Implement the default state,
|
|
145
|
+
- **Size:** record the measured control **height** in px (from the design context), not the kit's size name. Kits give `md` different meanings. Phase 3d converts heights to `--ig-size`.
|
|
146
|
+
- **State:** `Hover`, `Focused`, `Pressed`, `Disabled`, `Error`, `Selected` variants are **states**, not different components. Implement the default state. In Phase 3d, use state values only as token inputs (hover color, focus ring). If a screen shows a `State=Error` field, the design wants validation styling. It does not mean that the field is always invalid.
|
|
145
147
|
|
|
146
148
|
---
|
|
147
149
|
|
|
@@ -162,15 +164,15 @@ Use the exact values from the design context and the screenshot together:
|
|
|
162
164
|
|
|
163
165
|
Rules for Tier C:
|
|
164
166
|
|
|
165
|
-
- **Confidence is low by default.** List Tier C mappings separately in the Phase 1g review so the user can correct them.
|
|
166
|
-
- **Purely decorative or bespoke layouts** (hero sections, marketing tiles, KPI cards) stay plain semantic HTML plus CSS. Do not force them into a component because a name suggests one.
|
|
167
|
-
- **Interactive controls stay components.**
|
|
167
|
+
- **Confidence is low by default.** List Tier C mappings separately in the Phase 1g review, so that the user can correct them.
|
|
168
|
+
- **Purely decorative or bespoke layouts** (hero sections, marketing tiles, KPI cards) stay plain semantic HTML plus CSS. Do not force them into a component only because a name suggests one.
|
|
169
|
+
- **Interactive controls stay components.** A Tier C frame can clearly be an input, select, date field, table, or tab strip. In that case, use the Ignite UI component, also when its anatomy is different. The component gives keyboard, focus, ARIA, and form behavior that a custom frame does not have.
|
|
168
170
|
|
|
169
171
|
---
|
|
170
172
|
|
|
171
173
|
## Code Connect Caveat
|
|
172
174
|
|
|
173
|
-
`figma_get_code_connect_map`
|
|
175
|
+
`figma_get_code_connect_map` can return mappings to **another** library. For example, a shadcn kit can connect to `@/components/ui/button`, or an in-house kit can connect to the company's React package. Use these mappings as **strong evidence of the role and props**. For example, a Code Connect snippet `<Button variant="outline" size="sm">` confirms *button / medium emphasis / small*. **Never** copy their imports, tags, or props into the implementation. The target is always Ignite UI.
|
|
174
176
|
|
|
175
177
|
---
|
|
176
178
|
|
|
@@ -183,17 +185,17 @@ Rules for Tier C:
|
|
|
183
185
|
| **Dropdown** | A form field in some kits, a menu in others | `igc-select` (field) vs `igc-dropdown` (menu) |
|
|
184
186
|
| **Select** with search (shadcn Combobox, Ant Select `showSearch`) | Filterable single select | `igc-combo single-select` |
|
|
185
187
|
| **Tabs** styled as a pill track (shadcn, Fluent "segmented") | Either view switching or a value toggle | `igc-tabs` if it switches panels; `igc-button-group` if it sets a value |
|
|
186
|
-
| **Sheet** / **Drawer** (overlay) | Temporary side panel | `igc-nav-drawer` for navigation. There is no dedicated sheet component
|
|
188
|
+
| **Sheet** / **Drawer** (overlay) | Temporary side panel | `igc-nav-drawer` for navigation. There is no dedicated sheet component. For content panels, use `igc-dialog` or custom markup, and record it as an anatomy delta |
|
|
187
189
|
| **Alert** | Inline message (not modal) | `igc-banner`, or semantic HTML for static callouts |
|
|
188
190
|
| **Toast** vs **Snackbar** | Transient message | `igc-toast` (text only) or `igc-snackbar` (with action) |
|
|
189
|
-
| **Card** with complex internal layout | A surface container | `igc-card` only if header/content/actions anatomy fits
|
|
191
|
+
| **Card** with complex internal layout | A surface container | `igc-card` only if header/content/actions anatomy fits. Otherwise, use a Table B surface |
|
|
190
192
|
| **Navigation rail** | Icon-only side nav | `igc-nav-drawer position="relative"` with the `mini` slot, and **without** `open`. The rail is hidden while the drawer is open |
|
|
191
|
-
| **Tab bar** at the bottom (iOS, M3 navigation bar) | App-level navigation |
|
|
193
|
+
| **Tab bar** at the bottom (iOS, M3 navigation bar) | App-level navigation | Web Components have no bottom navigation. Use `igc-tabs` or custom markup, and document the substitution |
|
|
192
194
|
|
|
193
195
|
---
|
|
194
196
|
|
|
195
197
|
## Output of This Step
|
|
196
198
|
|
|
197
|
-
Fill the **Tier**, **Kit / Source**, **Canonical Role + Props**, **Confidence**, **Token Work**, and **Suspected Anatomy Deltas** columns of the Phase 1g **Table A**.
|
|
199
|
+
Fill the **Tier**, **Kit / Source**, **Canonical Role + Props**, **Confidence**, **Token Work**, and **Suspected Anatomy Deltas** columns of the Phase 1g **Table A**. `figma-exploration.md § 1g` is the only place that defines the table and its column rules.
|
|
198
200
|
|
|
199
|
-
Only the **Suspected Anatomy Deltas** column
|
|
201
|
+
Only the **Suspected Anatomy Deltas** column supplies the Phase 2d delta ledger. Token Work is never a delta.
|