update-component-styles

name	update-component-styles
description	Update component styling following the SCSS to Lit CSS workflow with proper theme support

Update Component Styles

This skill guides you through updating component styles following the project's SCSS workflow and theming system.

Example Usage

• "Update the badge component border radius"
• "Add hover styles to the button component"
• "Change the card component padding"

Related Skills

• create-new-component - Styling for new components

When to Use

• User asks to modify component appearance
• Need to add or change CSS styles
• Updating theme-specific styles
• Adding new CSS custom properties

Prerequisites

• Target component exists
• Style change requirements are clear
• Understand which theme files to modify

Required Context

Gather or confirm:

• Component name: Which component to style
• Style changes: What CSS needs to change
• Scope: Base styles, theme-specific, or both
• CSS parts: Whether to add/modify exposed parts

Steps

1. Identify Style Files to Modify

Component styles are organized as:

• [component]/themes/[component].base.scss - Base structural styles
• [component]/themes/shared/[component].common.css.js - Common cross-theme styles (if exists)
• [component]/themes/shared/[component].bootstrap.scss - Bootstrap theme
• [component]/themes/shared/[component].material.scss - Material theme
• [component]/themes/shared/[component].fluent.scss - Fluent theme
• [component]/themes/shared/[component].indigo.scss - Indigo theme
• [component]/themes/light/[component].[theme].scss - Light theme overrides
• [component]/themes/dark/[component].[theme].scss - Dark theme overrides

Decision tree:

• Structural changes (layout, display) → Edit base.scss
• Theme-agnostic styles → Edit shared/*.scss
• Theme-specific styles → Edit specific theme file
• Light/dark variants → Edit light/_ or dark/_ files

2. Edit SCSS Files

Base styles (themes/[component].base.scss):

@use '../../../styles/utilities' as *;

:host {
  display: block;
}

[part='base'] {
  padding: 1rem;
  border-radius: 4px;
  // Structural styles here
}

Theme-specific styles (themes/shared/[component].bootstrap.scss):

@use '../../../../theming/functions' as *;

:host {
  // Use theming functions from igniteui-theming
  --component-color: #{color('primary', 500)};
}

[part='base'] {
  background: var(--component-color);
}

Light/Dark overrides (themes/light/[component].bootstrap.scss):

:host {
  --component-color: white;
}

3. Use CSS Parts for External Styling

If adding new styleable parts, update component render and JSDoc:

Update render method:

protected override render() {
  return html`
    <div part="base new-part">
      <span part="content">Content</span>
    </div>
  `;
}

Update JSDoc:

/**
 * ...
 * @csspart base - The main container
 * @csspart new-part - Description of new part
 * @csspart content - The content wrapper
 */
export default class IgcComponentComponent extends LitElement {

4. Add CSS Custom Properties (if needed)

For values that should be customizable:

In SCSS:

:host {
  --component-padding: 1rem;
  --component-radius: 4px;
}

[part='base'] {
  padding: var(--component-padding);
  border-radius: var(--component-radius);
}

Document in JSDoc:

/**
 * ...
 * @cssproperty --component-padding - The internal padding
 * @cssproperty --component-radius - The border radius
 */
export default class IgcComponentComponent extends LitElement {

5. Transpile SCSS to TypeScript

After editing SCSS files, transpile them:

npm run build:styles

This converts .scss to .css.js files with Lit's css template literal.

Verify: Check that .css.js files are updated with your changes.

6. Test Style Changes

Manual testing in Storybook:

npm run storybook

Check:

• Styles render correctly in all theme variants
• Light and dark modes both work
• CSS parts are styleable from outside
• CSS custom properties work

Automated testing (if style affects behavior):

it('should apply correct CSS class', async () => {
  const el = await fixture<IgcComponentComponent>(
    html`<igc-component variant="outlined"></igc-component>`
  );

  const part = el.shadowRoot?.querySelector('[part="base"]');
  // Test computed styles or classes if critical
});

7. Update Documentation (if needed)

If adding new CSS parts or custom properties:

1. JSDoc comments are automatically extracted
2. Verify in Storybook's "Docs" tab
3. Check that parts/properties appear in documentation

Validation Checklist

• SCSS files edited correctly
• Styles transpiled (npm run build:styles)
• No TypeScript compilation errors
• Styles render correctly in Storybook
• All theme variants checked (bootstrap, material, fluent, indigo)
• Light and dark modes both work
• New CSS parts documented in JSDoc
• New CSS custom properties documented
• No visual regressions on other components

Common Pitfalls

1. Forgetting to Transpile

Problem: Style changes don't appear Solution: Always run npm run build:styles after editing SCSS

2. Editing .css.js Files Directly

Problem: Changes get overwritten on next build Solution: Only edit .scss files, never .css.js files

3. Wrong Theme File

Problem: Styles appear in some themes but not others Solution: Edit the correct theme file or shared file for all themes

4. Not Using Theming Functions

Problem: Hardcoded colors don't match theme Solution: Use color(), theme() functions from igniteui-theming

5. Overly Specific Selectors

Problem: Users can't override styles Solution: Keep selector specificity low, expose CSS parts

6. Missing :host Styles

Problem: Component doesn't display correctly Solution: Always set :host { display: block; } or appropriate display value

Reference Examples

Simple Component Styles: Badge

See: src/components/badge/themes/

Structure:

• Base styles for structure
• Theme files for colors/variants
• Uses CSS custom properties
• Exposes base and icon parts

Complex Component Styles: Textarea

See: src/components/textarea/themes/

Structure:

• More complex base styles
• Multiple CSS parts
• Theme-specific variants
• Light/dark overrides

Theming System

Available Functions

From igniteui-theming package:

• color($palette, $variant) - Get theme color
• contrast-color($color) - Get contrasting text color
• theme($property) - Get theme value

Theme Structure

@use '../../../../theming/functions' as *;

:host {
  --bg: #{color('surface', 500)};
  --text: #{contrast-color(color('surface', 500))};
}

Resources

• Lit Styles
• Shadow Parts
• CSS Custom Properties
• igniteui-theming Package
• Coding Guidelines - Comprehensive coding standards