Update Component Styles

Changes component styles through the SCSS → Lit CSS build and the igniteui-theming schemas. The directory layout and rules are in Styles and Theming.

Related: create-new-component for a new theme scaffold.

Where a Change Goes

Steps

1. Edit the SCSS

Use 4-space indentation and load-path specifiers (@use 'styles/utilities' as *), not relative paths into src/styles. Read theme values with var-get():

// shared/[component].common.scss
@use 'styles/utilities' as *;
@use '../light/themes' as *;

$theme: $material;

[part~='base'] {
    background: var-get($theme, 'background');
    color: var-get($theme, 'text-color');
}

// dark/[component].bootstrap.scss: emit only the difference from the light base
@use 'styles/utilities' as *;
@use 'themes' as *;
@use '../light/themes' as light;

$theme: $bootstrap;

:host {
    @include css-vars-from-theme(diff(light.$base, $theme));
}

• Do not hardcode colors or sizes. Use var-get(), color(), contrast-color(), sizable() and --ig-size.
• Match parts with [part~='name']. partMap emits a space-separated list.
• Keep specificity low. Document the custom properties that consumers can set, and prefix internal ones with --_.
• Key composite-anchor selectors off data-role / data-haspopup, not role / aria-* (see ARIA across shadow boundaries).
• var-get() resolves only keys that are in the schema. For a new key, add it to igniteui-theming, or declare a local variable in shared/[component].common.scss.

2. Document new parts or custom properties

/**
 * @csspart base - The main container.
 * @cssproperty --component-padding - The internal padding.
 */

Run npm run cem && npm run build:meta. Parts and custom properties are public API, so also add a row to ### CSS Shadow parts or ### CSS custom properties in spec.md, add a TOC entry for a new section, and add a row to ## Revision history. A visual change that adds no part or property does not change the spec, unless it contradicts documented behavior.

3. Transpile and verify

npm run build:styles
npm run lint:styles
npm run storybook

npm run storybook and npm run test:watch also rebuild the styles when you save. Check all four themes in light and dark mode.

[!IMPORTANT] The generated .css.ts files are gitignored. Do not edit or commit them. The build compiles only *.{base,common,shared,material,bootstrap,indigo,fluent}.scss. Give helper partials a _ prefix and @use them.

Validation Checklist

• Only .scss files are in the diff
• Load-path specifiers. Values come from the theming functions.
• [part~='…'] selectors
• Dark files emit only diff(light.$base, $theme)
• New parts and custom properties are in the JSDoc and in spec.md
• build:styles and lint:styles pass. All themes checked.
• CHANGELOG updated if the change is user-visible

Common Pitfalls

Reference Examples

• src/components/badge/themes/: a complete, compact scaffold
• src/components/input/themes/: many parts, material notch, data-role selectors
• src/components/rating/spec.md: parts and custom properties documented together