igniteui-webcomponents 7.3.1 → 7.4.0

package/skills/igniteui-wc-figma-to-app/references/design-token-bridge.md

@@ -0,0 +1,407 @@
+# Figma Variables → Ignite UI Web Components Theming Bridge
+
+> **Part of the [`igniteui-wc-figma-to-app`](../SKILL.md) skill.**
+>
+> Use this file in Phase 3 to translate Figma variable values (from
+> `figma_get_variable_defs`) into Ignite UI Theming MCP inputs. Read it in full before
+> calling any theming tool. For the theming system itself — palette semantics, token
+> rules, compound components — the source of truth is
+> [`igniteui-wc-customize-component-theme`](../../igniteui-wc-customize-component-theme/SKILL.md).
+
+---
+
+## How the Indigo.Design UI Kits Organize Variables
+
+The **Indigo.Design UI Kits** are Figma component libraries published by Infragistics.
+Designers build their own app frames in Figma using these kits as shared libraries. The
+kits come in four design-system variants, each with light and dark themes:
+
+| Kit variant            | Figma library name pattern                      | `designSystem` value |
+| ---------------------- | ----------------------------------------------- | -------------------- |
+| Material (most common) | `Indigo.Design UI Kit for Material`             | `"material"`         |
+| Fluent                 | `Indigo.Design UI Kit for Fluent`               | `"fluent"`           |
+| Bootstrap              | `Indigo.Design UI Kit for Bootstrap`            | `"bootstrap"`        |
+| Indigo                 | `Indigo.Design UI Kit` / `Indigo.Design System` | `"indigo"`           |
+
+**Identifying the active kit variant** is the first task in Phase 3 because it sets the
+design system for the whole app. Use these signals in **strict precedence order** — stop
+at the first clear match:
+
+1. **Library source name** — `figma_get_design_context` / `figma_get_metadata` may
+   reference the source library file name.
+2. **Variable collection name** — `figma_get_variable_defs` may return collection names
+   that include the design system (e.g. `Material/color/primary`).
+3. **Elevation variable structure** — inspect `Elevations/*`:
+   - **Three-layer DROP_SHADOW** (umbra + penumbra + ambient, `Elevations/Shadow 01-03`) → **Material**
+   - **Single-layer DROP_SHADOW** → Indigo, Fluent, or Bootstrap
+4. **Palette shade naming** — `primary/500`, `primary/100`–`primary/900` follows the
+   Material 100–900 convention → likely **Material**.
+5. **Visual heuristics** — see the [Design System Detection table](#design-system-detection-from-figma).
+
+> **Never use font name as a primary signal.** "Titillium Web" is the default body font in
+> the Indigo.Design UI Kit for Material — it is not exclusive to any kit variant.
+
+All four kit variants share the same variable naming conventions:
+
+```
+Primitives collection  → raw palette values (e.g. blue/500 = #6200EE)
+Semantic collection    → role-based aliases (e.g. color/primary = alias → blue/500)
+Component collection   → per-component overrides (e.g. button/background = alias → color/primary)
+```
+
+---
+
+## The Web Components Theming Contract
+
+Before mapping any value, understand what actually drives a Web Components theme. This is
+the single biggest difference from the Angular flow.
+
+| Layer | What it is | How it gets set |
+| --- | --- | --- |
+| **Design system + variant** | `--ig-theme`, `--ig-theme-variant` on `:root` | A pre-built theme CSS import or the `:root` block generated by `create_theme`; `configureTheme(ds, variant)` switches component themes at runtime but does not rewrite these CSS variables |
+| **Palette** | `--ig-<family>-<shade>` and `--ig-<family>-<shade>-contrast` custom properties | `create_palette` / `create_theme`, or overriding the `*-500` base shade by hand |
+| **Typography** | `--ig-font-family` plus the type scale | `create_typography`, or plain CSS in a CSS-only project |
+| **Elevations** | shadow custom properties | `create_elevations` (`designSystem: "material" \| "indigo"`) |
+| **Layout** | `--ig-size`, `--ig-spacing`, `--ig-radius-factor` | `set_size` / `set_spacing` / `set_roundness` |
+| **Per component** | component design tokens | `get_component_design_tokens` → `create_component_theme` |
+
+Components read the design system **at runtime from CSS variables** and fall back to
+`bootstrap` / `light` when they are absent. A correct palette with a missing
+`--ig-theme` gives you the right colors on the wrong component anatomy.
+
+**Every theming tool accepts `output: "css" | "sass"`, defaulting to CSS.** Choose once in
+Phase 3 based on whether the project has Sass, and stay consistent. The Web Components Sass
+API is `@use 'igniteui-theming'` with individual `palette()`, `typography()`, `elevations()`,
+and `spacing()` mixins — the Angular `core()` / `theme()` mixins do not exist here.
+
+---
+
+## Global Palette Mapping
+
+### Primary Color
+
+| Figma Variable Pattern | Theming Input                 | Notes                                   |
+| ---------------------- | ----------------------------- | --------------------------------------- |
+| `color/primary`        | `primary` in `create_palette` | Use the resolved hex value              |
+| `primary/500`          | `primary`                     | The 500 shade is the seed color         |
+| `Primary/Default`      | `primary`                     | Alternative naming in some kit versions |
+| `palette/primary/500`  | `primary`                     | Prefixed naming pattern                 |
+
+> **Parameter names differ between tools.** `create_palette` takes `primary`, `secondary`,
+> `surface`, `gray`, `info`, `success`, `warn`, `error`. `create_theme` takes
+> `primaryColor`, `secondaryColor`, `surfaceColor`. Do not mix them up.
+
+### Secondary / Accent Color
+
+| Figma Variable Pattern | Theming Input                   | Notes                              |
+| ---------------------- | ------------------------------- | ---------------------------------- |
+| `color/secondary`      | `secondary` in `create_palette` | —                                  |
+| `secondary/500`        | `secondary`                     | —                                  |
+| `Secondary/Default`    | `secondary`                     | —                                  |
+| `color/accent`         | `secondary`                     | Some kit variants call it "accent" |
+
+### Surface / Background Color
+
+| Figma Variable Pattern | Theming Input                 | Notes               |
+| ---------------------- | ----------------------------- | ------------------- |
+| `color/surface`        | `surface` in `create_palette` | The main background |
+| `surface/default`      | `surface`                     | —                   |
+| `Surface`              | `surface`                     | —                   |
+| `color/background`     | `surface`                     | Alternative naming  |
+
+### Gray / Neutral Palette
+
+The gray scale is derived automatically from the surface color, and **gray is inverted
+relative to surface** in dark themes. Do not pass gray unless the Figma grays clearly
+diverge from the generated ones. Read `theming://guidance/colors/rules` before overriding.
+
+### Semantic Status Colors
+
+| Figma Variable Pattern           | Theming Input | Notes    |
+| -------------------------------- | ------------- | -------- |
+| `color/success` or `success/500` | `success`     | Optional |
+| `color/warning` or `warning/500` | `warn`        | Optional — the parameter is `warn`, not `warning` |
+| `color/error` or `error/500`     | `error`       | Optional |
+| `color/info` or `info/500`       | `info`        | Optional |
+
+### Multiple Surface Depths
+
+Designs frequently use two or three surface depths (page, panel, card) that a single
+generated `surface` cannot express. When that happens:
+
+- use `create_custom_palette` for explicit per-shade control, or
+- define semantic variables (`--surface-1`, `--surface-2`) alongside the palette and use
+  them in view CSS.
+
+Never satisfy a second depth with a raw hex value in component styles.
+
+### Resolving Colors Back Out
+
+Use `get_color({ color, variant, contrast, opacity })` to turn a color intent into the
+correct `var(--ig-<family>-<shade>)` reference — including contrast colors and
+transparency — instead of hand-writing variable names.
+
+---
+
+## Typography Mapping
+
+| Figma Variable Pattern           | Theming Input                          | Notes                                 |
+| -------------------------------- | -------------------------------------- | ------------------------------------- |
+| `typography/font-family`         | `fontFamily` in `create_typography`    | Primary font                          |
+| `typography/body/font-family`    | `fontFamily`                           | Body font family                      |
+| `typography/heading/font-family` | `fontFamily`                           | Use if the heading font differs       |
+| `font/primary`                   | `fontFamily`                           | Alternative naming                    |
+
+`create_typography` also accepts `designSystem` (which type scale to start from) and
+`customScale` (per-style overrides of `fontSize`, `fontWeight`, `lineHeight`,
+`letterSpacing`, `textTransform`, margins) — use `customScale` only when the design's type
+ramp genuinely differs from the design system's.
+
+In a CSS-only project, apply typography as plain CSS `font-family` / `font-size` /
+`font-weight` rules, or the CSS output of `create_typography`. **Do not emit Sass
+typography mixins into an app that has no Sass.**
+
+Web fonts must be loaded by the app (a `<link>` to the font provider or a local `@font-face`);
+setting a font family the browser cannot resolve silently falls back and fails Phase 5.
+
+---
+
+## Spacing, Sizing, and Roundness — Do Not Map Directly
+
+> **These tools are NOT equivalent to Figma spacing values.** Do not create a mapping
+> between Figma pixel values and these tools.
+
+`set_spacing` takes a **multiplier** (`1.0` = default, plus optional `inline` / `block`
+multipliers). `set_roundness` takes a `radiusFactor` between **0 and 1**. `set_size` takes
+a **density** (`small` / `medium` / `large`, or `1`–`3`). Passing a Figma `spacing/md = 16`
+as `set_spacing({ spacing: 16 })` would produce a 1600% increase.
+
+### When to touch these tools (sparingly)
+
+| Tool             | Use only when                                                                                                   | Never because                                                    |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `set_size`       | The design consistently uses a noticeably tighter or looser component density than the design system default    | A Figma spacing variable happens to be named "compact"           |
+| `set_spacing`    | Explicitly requested, or required to match a specific density contract; start at the default                    | A Figma `spacing/*` pixel value looks like the multiplier number |
+| `set_roundness`  | The entire app has a clearly distinct border-radius language (fully squared vs fully rounded)                   | A Figma `border-radius/md = 8` maps numerically to a multiplier  |
+
+### The correct adjustment path
+
+Scope `--ig-size` and `--ig-spacing` to the component that needs it — both tools take a
+`component` parameter (and `scope` for a sub-component or container selector) that generates
+exactly this:
+
+```
+set_size({ component: "calendar", size: "small", platform: "webcomponents" })
+// → igc-calendar { --ig-size: var(--ig-size-small); }
+
+set_spacing({ component: "calendar", spacing: 0.75, platform: "webcomponents" })
+// → igc-calendar { --ig-spacing: 0.75; }
+
+set_size({ scope: ".compact-toolbar", size: "small", platform: "webcomponents" })
+```
+
+Or set the custom properties directly:
+
+```css
+igc-calendar {
+  --ig-size: var(--ig-size-small);
+  --ig-spacing: 0.75;
+}
+```
+
+The Indigo.Design kit's component proportions are already calibrated per design system —
+start from the defaults and adjust only when there is a clear visual reason.
+
+---
+
+## Light vs Dark Mode Detection
+
+| Figma Signal                                             | Action                                                                   |
+| -------------------------------------------------------- | ------------------------------------------------------------------------ |
+| Dark artboard background (`#121212`, `#1a1a1a`, similar) | `variant: "dark"` + the dark theme CSS (`themes/dark/<ds>.css`)          |
+| Light artboard background (`#fff`, `#f5f5f5`, similar)   | `variant: "light"` + the light theme CSS                                 |
+| Multiple artboards — one light, one dark                 | Generate both; switch with a class, `prefers-color-scheme`, or `configureTheme` |
+| `color/mode` variable present                            | Its value (`light` or `dark`) is the authoritative signal                |
+
+Surface color must match the variant: a light surface with `variant: "dark"` produces
+unreadable components and a luminance warning from the palette tools. Read the warnings.
+
+---
+
+## Design System Detection from Figma
+
+| Figma Visual Signal                                                | Likely Design System       | `designSystem` Value |
+| ------------------------------------------------------------------ | -------------------------- | -------------------- |
+| Three-layer `DROP_SHADOW` on elevation variables (`Shadow 01-03`)  | Material Design            | `"material"`         |
+| Prominent single-layer shadows, rounded cards, ripple effects      | Material Design            | `"material"`         |
+| Flat surfaces, sharp corners, Segoe/Inter font                     | Microsoft Fluent           | `"fluent"`           |
+| Component borders, Bootstrap-like grid                             | Bootstrap                  | `"bootstrap"`        |
+| Purple/indigo accents, rounded corners, single shadow              | Infragistics Indigo        | `"indigo"`           |
+| `primary/500`, `primary/900` palette shade naming                  | Material (100–900 palette) | `"material"`         |
+
+`create_elevations` accepts only `"material"` or `"indigo"` as its `designSystem` — for a
+Fluent or Bootstrap design, pick the closer of the two (usually `material`).
+
+---
+
+## Per-Component Token Resolution
+
+### Step 1: Use the right theme key
+
+Theme keys are **not** tag names. Pass the key to `get_component_design_tokens` and
+`create_component_theme`:
+
+| Component in the design | Theme key           | Selector it generates for        |
+| ----------------------- | ------------------- | --------------------------------- |
+| Text input / any input  | `input-group`       | `igc-input`                       |
+| Navigation drawer       | `navdrawer`         | `igc-nav-drawer`                  |
+| Linear progress bar     | `progress-linear`   | `igc-linear-progress`             |
+| Circular progress       | `progress-circular` | `igc-circular-progress`           |
+| Single-select combo     | `simple-combo`      | `igc-combo[single-select]`        |
+| Flat / contained / outlined button | `flat-button`, `contained-button`, `outlined-button` | `igc-button[variant="…"]` |
+| Icon button variants    | `flat-icon-button`, `contained-icon-button`, `outlined-icon-button` | `igc-icon-button[variant="…"]` |
+| Premium grid            | `grid`              | `igc-grid`                        |
+| Lightweight grid        | `grid-lite`         | `igc-grid-lite`                   |
+| Dropdown menu           | `drop-down`         | `igc-dropdown`                    |
+| App scrollbars          | `scrollbar`         | `.ig-scrollbar`                   |
+
+Most other components use their obvious key (`card`, `list`, `navbar`, `chip`, `avatar`,
+`badge`, `calendar`, `date-picker`, `select`, `combo`, `tabs`, `stepper`, `tree`, `dialog`,
+`toast`, `snackbar`, `banner`, `tooltip`, `divider`, `rating`, `slider`, `switch`,
+`checkbox`, `radio`, `carousel`, `chat`, `expansion-panel`, `accordion`, `splitter`,
+`file-input`, `date-time-input`, `textarea`, `icon`, `ripple`, `highlight`).
+
+**Keys with no Web Components equivalent** — do not call the theming tools for these:
+`action-strip`, `bottom-nav`, `column-actions`, `overlay`, `query-builder`, `time-picker`,
+`date-range-start`, `date-range-end`. Sub-part keys (`card-header`, `list-item`, `step`,
+`tab-item`, `accordion-header`, `expansion-panel-header`, `drop-down-item`,
+`nav-drawer-item`) have no standalone selector either — style them through the parent's
+tokens, their documented `::part(...)`, or slotted content.
+
+### Step 2: Discover the tokens
+
+```
+get_component_design_tokens({ component: "<theme key>" })
+```
+
+The result lists every token with name, type, and description — and, for compound
+components, the **related themes** you must also theme.
+
+### Step 3: Match Figma variables to token names
+
+Kit component variables follow `<component>/<role>/<state>`:
+
+- `button/background` → token `background`
+- `button/foreground` → token `foreground-color`
+- `chip/background/selected` → token `selected-chip-color`
+- `grid/header-background` → token `header-background`
+- `navbar/background` → token `background`
+
+Lookup process: strip the component prefix, match the remainder against the token list, and
+when there is no exact match pick the token whose description names the same visual role.
+
+| Component | Figma Variable             | Likely Token Name       | Notes                   |
+| --------- | -------------------------- | ----------------------- | ----------------------- |
+| Button    | `button/background`        | `background`            | Per variant key         |
+| Button    | `button/foreground`        | `foreground-color`      | Text color              |
+| Button    | `button/border`            | `border-color`          | Outlined variant        |
+| Chip      | `chip/background`          | `background`            | Default state           |
+| Chip      | `chip/selected-background` | `selected-chip-color`   | —                       |
+| Grid      | `grid/header/background`   | `header-background`     | —                       |
+| Grid      | `grid/row/background`      | `content-background`    | —                       |
+| Grid      | `grid/row/hover`           | `row-hover-background`  | —                       |
+| Navbar    | `navbar/background`        | `background`            | —                       |
+| Input     | `input/background`         | `box-background`        | Filled appearance       |
+| Input     | `input/border`             | `border-color`          | `outlined` appearance   |
+| Card      | `card/background`          | `background`            | —                       |
+| List      | `list/item/background`     | `item-background`       | —                       |
+| List      | `list/item/hover`          | `item-hover-background` | —                       |
+| Dialog    | `dialog/background`        | `background`            | —                       |
+
+### Step 4: Generate the component theme
+
+Pass **only tokens that differ from the global theme**, and express values as palette
+references — never raw hex:
+
+```
+create_component_theme({
+  component: "<theme key>",
+  platform: "webcomponents",
+  designSystem: "<resolved>",
+  variant: "<light|dark>",
+  licensed: <true if @infragistics>,
+  tokens: {
+    "background": "var(--ig-surface-100)",
+    "foreground-color": "var(--ig-gray-900)"
+  },
+  selector: "<optional scope, e.g. .dashboard igc-card>",
+  output: "css"
+})
+```
+
+Apply the generated block exactly as returned. Use `selector` to scope an override to one
+region instead of every instance in the app.
+
+### Step 5: Compound components
+
+`combo`, `select`, `date-picker`, `date-range-picker`, `grid`, and `banner` render internal
+children with their own themes. Theme each related theme returned in Step 1 using the
+parent's selector as the wrapper. Styling only the parent leaves dropdown surfaces,
+calendars, and action buttons off-theme — a guaranteed Phase 5 failure.
+
+---
+
+## Chart Colors
+
+Charts have no design tokens. Take the series colors from the Figma design context and run
+them through the theming MCP before use:
+
+```
+get_chart_series_colors({ chartType: "category-chart" })         // which properties accept a brush list
+get_chart_series_colors({ customBrushes: ["#9DE772", "#6DB1FF"] }) // validate the Figma colors
+get_chart_series_colors({ mode: "color-blind" })                  // accessible alternative palette
+```
+
+Assign the result to the chart's `brushes` / `outlines` **properties** (arrays, not
+attributes). Without an explicit assignment the chart uses its own default palette and will
+not match the design.
+
+---
+
+## Variable Resolution Priority
+
+When multiple Figma variables could map to the same theming input:
+
+1. **Component-scoped variable** (e.g. `button/background`) → per-component token
+2. **Semantic role variable** (e.g. `color/primary`) → global palette input
+3. **Primitive variable** (e.g. `primary/500`) → global palette seed color
+4. **Raw hex/rgb value** (no variable) → extract directly from the design context
+
+---
+
+## What to Skip
+
+Do **not** call theming tools for:
+
+- Chart, gauge, and map components → configure via properties; series colors via
+  `get_chart_series_colors`
+- Dock Manager → it exposes its own CSS custom properties
+- Pure layout CSS (margins, grid columns, flex gaps) → write it directly in the view's styles
+- Icon colors → set `color` on the `igc-icon` host or its parent
+
+---
+
+## Loading Reference Data
+
+| URI | Content |
+| --- | --- |
+| `theming://platforms/webcomponents` | Web Components platform specifics |
+| `theming://guidance/colors/rules`   | Surface/gray luminance rules for light and dark |
+| `theming://guidance/colors/roles`   | Which components use primary vs secondary vs surface |
+| `theming://guidance/colors/usage`   | Which shade for which purpose |
+| `theming://guidance/colors/charts`  | Chart color guidance |
+| `theming://presets/palettes`        | Preset palette colors |
+| `theming://presets/typography`      | Typography presets |
+| `theming://presets/elevations`      | Elevation shadow presets |
+
+Read them with `read_resource({ uri: "<uri>" })`.