web-styling-scss-modules_skill

Overview

This skill delivers a SCSS Modules-based styling system built around a two-tier design token architecture, CSS Cascade Layers, and HSL-first color rules. It provides patterns and conventions for theme-agnostic components, predictable cascade precedence, and class-based dark mode. Use it to standardize component styling across a monorepo and enable safe app-level overrides.

How this skill works

The skill defines core tokens (raw HSL values and primitives) and semantic tokens (purpose-driven references) so components consume only semantic tokens. Styles are authored as SCSS Modules and must be wrapped in @layer components {} to enforce layer ordering. Dark mode is implemented by overriding semantic tokens under a .dark class, and state styling uses data-attributes rather than toggled class names.

When to use it

• When building reusable UI components that must remain theme-agnostic
• When implementing a scalable design-token system and theming strategy
• When you need predictable style precedence across packages in a monorepo
• When implementing class-based dark mode that swaps semantic tokens
• When enforcing HSL-first color rules and avoiding Sass color functions

Best practices

• Always wrap UI package component styles in @layer components {} for correct precedence
• Use semantic tokens only inside components; never reference core tokens directly
• Store color token values as raw HSL channels and apply via hsl(var(--token))
• Use data-attributes for interactive/state styling (e.g., [data-open]) instead of toggling classes
• Import Sass with @use and follow project import/constant naming and ordering conventions

Example use cases

• Creating a button component where light/dark themes swap only semantic tokens
• Setting up a spacing and typography token set for consistent layout across apps
• Building an icon system that derives foreground/background pairs via semantic tokens
• Providing a UI package whose styles can be safely overridden by app-level CSS
• Integrating CVA (Class Variance Authority) with semantic tokens for variant styling