# Ignite UI Angular Gotchas & Pitfalls

## Table of Contents
- [Sass Conflicts](#sass-conflicts)
- [Chart Properties](#chart-properties)
- [Component Properties](#component-properties)
- [Theming Pitfalls](#theming-pitfalls)
- [Map Component](#map-component)
- [Dark Theme Specifics](#dark-theme-specifics)

## Sass Conflicts

### `contrast()` function collision
The CSS `contrast()` filter function can collide with `igniteui-theming`'s `contrast()` Sass function. When you need the native CSS function, call it explicitly via `sass:meta`:
```scss
@use "sass:meta";

.uses-css-contrast {
  filter: meta.call(meta.get-function("contrast", $css: true), <contrast-value>);
}
```
Prefer this approach over string escaping when a native CSS function name collides with a Sass function.

### Font family in typography mixin
Comma-separated font families are parsed as multiple Sass arguments. Wrap in parentheses:
```scss
// BAD
@include typography($font-family: "Primary Font", "Fallback Font", sans-serif);

// GOOD
@include typography($font-family: ("Primary Font", "Fallback Font", sans-serif));
```
Replace `"Primary Font"` and `"Fallback Font"` with the font families extracted from the design image.

## Chart Properties

### Markers shown by default
Category charts show markers at every data point by default. If the screenshot does not show markers, set `markerTypes` to the matching no-marker option documented for the component:
```html
[markerTypes]="<resolvedMarkerTypes>"
```

`markerTypes` expects values such as `"Circle"` or `"None"`, or an `IgxMarkerTypeCollection`. Do not pass an array of lowercase strings.

### `plotAreaBackground` does NOT exist on `igx-category-chart`
Use CSS to style the chart container background instead.

### `areaFillOpacity` exists on `IgxCategoryChartComponent` (via domain chart parent)
It does NOT exist on `IgxSparklineComponent`.

### `includedProperties` must be a bound array
Use property binding, not a plain string attribute:
```html
<igx-category-chart [includedProperties]="['fieldOne', 'fieldTwo', 'fieldThree']"></igx-category-chart>
```
Replace `'fieldOne'`, `'fieldTwo'`, etc. with the actual data property names from your mock data.

### Chart callback inputs must use Angular property binding
Function-valued chart inputs must be bound, not passed as plain attributes:
```html
<igx-category-chart [xAxisFormatLabel]="<labelFormatter>"></igx-category-chart>
```

### Smooth area charts
For smooth-looking area charts where the data should appear continuous rather than spiky:
- Increase data density until the line or area reads as continuous at the rendered size
- Apply smoothing only when the source shape in the design looks smoothed rather than point-to-point
- Hide markers unless the screenshot clearly shows visible data points
- Tune fill opacity and label density to match the screenshot instead of relying on a fixed default

### Charts inside CSS Grid can collapse
In a flexible CSS Grid track, set `min-height: 0` on the grid cell and `height: 100%` on the chart element:
```scss
.chart-panel {
  min-height: 0;
}

igx-category-chart {
  display: block;
  height: 100%;
}
```

## Component Properties

### `roundShape` does NOT exist on `IgxAvatarComponent`
Use the supported `shape` input alone. Do not add `[roundShape]="true"`.

### `IgxListLineDirective` is the directive for `igxListLine`
It must be imported for list item text content. Confirm the exact package variant and entry point from the workspace and component docs before adding the import.

### Avatar background color via CSS variable
```html
<igx-avatar [style.--ig-avatar-background]="color"></igx-avatar>
```

## Theming Pitfalls

### DV components do NOT inherit Sass theme colors
Charts, maps, gauges, and sparklines ignore the global Sass theme. Set their visual properties explicitly via component inputs. After a palette exists, prefer palette tokens or local semantic CSS variables over leaving raw color literals in the final template:
```html
[brushes]="'<resolved-series-brush>'"
[outlines]="'<resolved-series-outline>'"
[xAxisLabelTextColor]="'<resolved-axis-label-color>'"
[yAxisMajorStroke]="'<resolved-grid-line-color>'"
```

### Component theme functions
For core UI component theming, prefer `create_component_theme` and apply the returned theme block as generated by the MCP server.

### Nav drawer width
Override the drawer aside width via its internal class using the width measured from the design image:
```scss
igx-nav-drawer {
  --ig-nav-drawer-size: <extracted-sidebar-width>; // <- Use this to overwrite the width of the full navdrawer
  --ig-nav-drawer-size--mini: <extracted-mini-drawer-width>; // <- Use this to overwrite the width of the mini navdrawer
}
```

### Dark theme overrides for `IgxGridComponent`
Grid internals often need explicit dark-theme overrides. Use `get_component_design_tokens("grid")` to discover available tokens, then call `create_component_theme` with the tokens that differ from the global theme. Apply the returned theme with the `tokens`:
```scss
@include tokens($custom-grid-theme);
```

### Read luminance warnings from theme generation
If `create_theme` returns a luminance warning for a generated surface, do not ignore it. If the design needs multiple surface depths, use `create_custom_palette` or define semantic CSS variables such as `--surface-1` and `--surface-2` in `styles.scss` instead of relying on a single generated surface color.

## Map Component

### Adding markers programmatically
The geographic map often requires programmatic series setup once the map instance is available:
```typescript
const symbolSeries = new IgxGeographicSymbolSeriesComponent();
symbolSeries.dataSource = locations;
symbolSeries.latitudeMemberPath = '<latitude-field>';
symbolSeries.longitudeMemberPath = '<longitude-field>';
symbolSeries.markerType = <resolvedMarkerType>;
symbolSeries.markerBrush = '<resolved-accent-color>';
symbolSeries.markerOutline = '<resolved-accent-color>';
map.series.add(symbolSeries);
// Set zoom bounds to match the geographic region visible in the design image
map.zoomToGeographic({ left: <min-longitude>, top: <top-latitude>, width: <longitude-span>, height: <latitude-span> });
```

### Dark map styling
OpenStreetMap tiles are light by default. For dark themes, apply a CSS filter to the container. Adjust the values to match the map tone in the design image:
```scss
.map-container {
  /* tune grayscale (0-1) and brightness (0-1) to match the design */
  filter: grayscale(<0-1>) brightness(<0-1>);
}
```

## Dark Theme Specifics

### Use the resolved dark schema for dark themes
```scss
@include theme(
  $palette: $resolved-palette,
  $schema: <resolved-dark-schema>
);
```

### CSS custom properties for dark panels
When the design uses multiple dark surface depths (panels, sidebars, cards on a dark background), define reusable semantic tokens using palette references or values derived from the design intent:

```scss
:root {
  --surface-primary: <resolved-surface-token>;
  --surface-secondary: <resolved-surface-token>;
  --accent-strong: <resolved-accent-token>;
  --text-primary: <resolved-text-token>;
  --text-secondary: <resolved-text-token>;
}
```

If `create_theme` returns a single surface color that doesn't cover all depth levels visible in the design, define additional surface tokens (`--surface-1`, `--surface-2`, etc.) for each distinct depth.

### Standalone pipes must be imported explicitly
When using Angular pipes in a standalone component template, add the pipe classes to the component `imports` array:
```typescript
import { CurrencyPipe, DatePipe, DecimalPipe } from '@angular/common';

@Component({
  imports: [DecimalPipe, DatePipe, CurrencyPipe]
})
export class <ViewComponent> {}
```