Back to Details

web-styling-scss-modules

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Styling & Design System

样式与设计系统

Quick Guide: Two-tier token system (Core primitives -> Semantic tokens). Foreground/background color pairs. Components use semantic tokens only. SCSS Modules + CSS Cascade Layers. HSL format. Dark mode via 
.dark
class with mixin. Data-attributes for state. Self-contained (no external dependencies).
<critical_requirements>
快速指南： 双层令牌系统（核心原语 -> 语义令牌）。前景/背景颜色配对。组件仅使用语义令牌。SCSS Modules + CSS Cascade Layers。HSL格式。通过带mixin的
.dark
类实现深色模式。使用数据属性处理状态。自包含（无外部依赖）。
<critical_requirements>

CRITICAL: Before Using This Skill

重要提示：使用此技能之前

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, 
import type
, named constants)
(You MUST wrap ALL UI package component styles in 
@layer components {}
for proper cascade precedence)
(You MUST use semantic tokens ONLY in components - NEVER use core tokens directly)
(You MUST use HSL format for colors with CSS color functions - NO Sass color functions like darken/lighten)
(You MUST use data-attributes for state styling - NOT className toggling)
(You MUST use 
@use
for imports - 
@import
is deprecated and will be removed in Dart Sass 3.0.0)
</critical_requirements>
Auto-detection: UI components, styling patterns, design tokens, SCSS modules, CSS Cascade Layers, dark mode theming
When to use:
  • Implementing design tokens and theming
  • Building component styles with SCSS Modules
  • Ensuring visual consistency across applications
  • Working with colors, spacing, typography
  • Implementing dark mode with class-based theming
  • Setting up CSS Cascade Layers for predictable style precedence
Key patterns covered:
  • Two-tier token system (Core -> Semantic)
  • SCSS Module patterns with CSS Cascade Layers
  • Color system (HSL format, semantic naming, foreground/background pairs)
  • Spacing and typography systems
  • Dark mode implementation (
    .dark
    class with mixin pattern)
  • Component structure and organization
When NOT to use:
  • One-off prototypes without design system needs (use inline styles or basic CSS)
  • External component libraries with their own theming (Material-UI, Chakra)
  • Projects requiring comprehensive utility classes (use Tailwind CSS instead)
Detailed Resources:
  • examples/core.md - Token system, HSL colors, cascade layers
  • examples/tokens.md - Spacing and typography systems
  • examples/theming.md - Dark mode implementation
  • examples/patterns.md - Module structure, data-attributes, mixins, global styles, icons
  • examples/cva.md - cva integration with SCSS Modules
  • examples/advanced.md - :has(), :global(), nesting patterns
  • examples/modules.md - Sass module system (@use and @forward)
  • reference.md - Decision frameworks and anti-patterns
<philosophy>
所有代码必须遵循CLAUDE.md中的项目约定（短横线命名法、命名导出、导入顺序、
import type
、命名常量）
（必须将所有UI包组件样式包裹在
@layer components {}
中，以确保正确的层级优先级）
（组件中必须仅使用语义令牌——绝不能直接使用核心令牌）
（必须使用HSL格式配合CSS颜色函数——禁止使用Sass颜色函数如darken/lighten）
（必须使用数据属性进行状态样式设置——不能使用className切换）
（必须使用
@use
进行导入——
@import
已被弃用，将在Dart Sass 3.0.0中移除）
</critical_requirements>
自动检测： UI组件、样式模式、设计令牌、SCSS模块、CSS Cascade Layers、深色模式主题
适用场景：
  • 实现设计令牌与主题系统
  • 使用SCSS Modules构建组件样式
  • 确保跨应用的视觉一致性
  • 处理颜色、间距、排版
  • 基于类实现深色模式主题
  • 设置CSS Cascade Layers以实现可预测的样式优先级
涵盖的核心模式：
  • 双层令牌系统（核心 -> 语义）
  • 结合CSS Cascade Layers的SCSS模块模式
  • 颜色系统（HSL格式、语义命名、前景/背景配对）
  • 间距与排版系统
  • 深色模式实现（
    .dark
    类配合mixin模式）
  • 组件结构与组织
不适用场景：
  • 无需设计系统的一次性原型（使用内联样式或基础CSS）
  • 自带主题系统的外部组件库（Material-UI、Chakra）
  • 需要全面工具类的项目（改用Tailwind CSS）
详细资源：
  • examples/core.md - 令牌系统、HSL颜色、层级控制
  • examples/tokens.md - 间距与排版系统
  • examples/theming.md - 深色模式实现
  • examples/patterns.md - 模块结构、数据属性、mixin、全局样式、图标
  • examples/cva.md - cva与SCSS Modules的集成
  • examples/advanced.md - :has(), :global(), 嵌套模式
  • examples/modules.md - Sass模块系统（@use和@forward）
  • reference.md - 决策框架与反模式
<philosophy>

Philosophy

设计理念

The design system follows a self-contained, two-tier token architecture where core primitives (raw HSL values, base sizes) map to semantic tokens (purpose-driven names). Components consume only semantic tokens, enabling theme changes without component modifications.
Core Principles:
  • Self-contained: No external dependencies (no Open Props, no Tailwind for tokens)
  • Two-tier system: Core tokens provide raw values, semantic tokens provide meaning
  • HSL-first: Use modern CSS color functions, not Sass color manipulation
  • Layer-based: CSS Cascade Layers ensure predictable style precedence across monorepo
  • Theme-agnostic components: Components use semantic tokens and adapt automatically to light/dark mode
</philosophy>
<patterns>
本设计系统遵循自包含的双层令牌架构，其中核心原语（原始HSL值、基础尺寸）映射到语义令牌（具有明确用途的命名）。组件仅使用语义令牌，无需修改组件代码即可实现主题变更。
核心原则：
  • 自包含： 无外部依赖（不使用Open Props、不依赖Tailwind实现令牌）
  • 双层系统： 核心令牌提供原始值，语义令牌赋予含义
  • 优先HSL： 使用现代CSS颜色函数，而非Sass颜色操作
  • 基于层级： CSS Cascade Layers确保在单体仓库中实现可预测的样式优先级
  • 主题无关组件： 组件使用语义令牌，可自动适配亮色/深色模式
</philosophy>
<patterns>

Core Patterns

核心模式

Pattern 1: Two-Tier Token System

模式1：双层令牌系统

The design system uses a two-tier token architecture: Tier 1 (Core tokens) provides raw values, Tier 2 (Semantic tokens) references core tokens with purpose-driven names.
设计系统采用双层令牌架构：**第一层（核心令牌）**提供原始值，**第二层（语义令牌）**通过具有明确用途的命名引用核心令牌。

Token Architecture

令牌架构

Location: 
packages/ui/src/styles/design-tokens.scss
Tier 1: Core tokens - Raw HSL values, base sizes, primitives
scss
--color-white: 0 0% 100%;
--color-gray-900: 222 47% 11%;
--color-red-500: 0 84% 60%;
--space-unit: 0.2rem;
Tier 2: Semantic tokens - Reference core tokens with purpose-driven names
scss
--color-background-base: var(--color-white);
--color-text-default: var(--color-gray-500);
--color-primary: var(--color-gray-900);
--color-primary-foreground: var(--color-white);
--color-destructive: var(--color-red-500);
Why this matters: Semantic tokens make purpose clear (what the token is for), theme changes only update token values (not component code), components remain theme-agnostic.
For complete implementation examples, see examples/core.md.
位置： 
packages/ui/src/styles/design-tokens.scss
第一层：核心令牌 - 原始HSL值、基础尺寸、原语
scss
--color-white: 0 0% 100%;
--color-gray-900: 222 47% 11%;
--color-red-500: 0 84% 60%;
--space-unit: 0.2rem;
第二层：语义令牌 - 通过具有明确用途的命名引用核心令牌
scss
--color-background-base: var(--color-white);
--color-text-default: var(--color-gray-500);
--color-primary: var(--color-gray-900);
--color-primary-foreground: var(--color-white);
--color-destructive: var(--color-red-500);
重要性： 语义令牌明确了用途（令牌的作用），主题变更仅需更新令牌值（无需修改组件代码），组件保持主题无关。
完整实现示例请查看examples/core.md。

Pattern 2: HSL Color Format with CSS Color Functions

模式2：结合CSS颜色函数的HSL颜色格式

Store HSL values without the 
hsl()
wrapper in tokens, apply 
hsl()
wrapper when using tokens, and use modern CSS color functions for transparency and color mixing.
在令牌中存储不带
hsl()
包装器的HSL值，使用令牌时添加
hsl()
包装器，并使用现代CSS颜色函数实现透明度和颜色混合。

Color Format Rules

颜色格式规则

  • Store HSL values without 
    hsl()
    wrapper: 
    --color-gray-900: 222 47% 11%;
  • Use 
    hsl()
    wrapper when applying: 
    background-color: hsl(var(--color-primary))
  • Use CSS color functions for derived colors:
    • Transparency: 
      hsl(var(--color-primary) / 0.5)
      (append alpha to HSL components)
    • Color mixing: 
      color-mix(in srgb, hsl(var(--color-primary)), white 10%)
    • Channel manipulation: 
      hsl(from hsl(var(--color-primary)) h s calc(l * 0.8))
      (wrap origin in 
      hsl()
      first)
  • NEVER use Sass color functions: No 
    darken()
    , 
    lighten()
    , 
    transparentize()
  • Always use semantic color tokens (not raw HSL in components)
Why HSL: HSL format eliminates Sass dependencies, CSS color functions work natively in browsers, semantic naming clarifies purpose (not just value), theme changes update token values without touching components.
For complete implementation examples, see examples/core.md.
  • 存储不带
    hsl()
    包装器的HSL值：
    --color-gray-900: 222 47% 11%;
  • 使用时添加
    hsl()
    包装器：
    background-color: hsl(var(--color-primary))
  • 使用CSS颜色函数生成衍生颜色：
    • 透明度：
      hsl(var(--color-primary) / 0.5)
      （在HSL组件后追加alpha值）
    • 颜色混合：
      color-mix(in srgb, hsl(var(--color-primary)), white 10%)
    • 通道操作：
      hsl(from hsl(var(--color-primary)) h s calc(l * 0.8))
      （先将原始值包裹在
      hsl()
      中）
  • 禁止使用Sass颜色函数： 不得使用
    darken()
    、
    lighten()
    、
    transparentize()
  • 始终使用语义颜色令牌（组件中不得使用原始HSL值）
为什么选择HSL： HSL格式消除了对Sass的依赖，CSS颜色函数可在浏览器中原生运行，语义命名明确了用途（而非仅值），主题变更仅需更新令牌值，无需修改组件。
完整实现示例请查看examples/core.md。

Pattern 3: CSS Cascade Layers for Predictable Precedence

模式3：用于可预测优先级的CSS Cascade Layers

Use CSS Cascade Layers to control style precedence across the monorepo, ensuring UI package components have lower priority than app-specific overrides.
使用CSS Cascade Layers控制单体仓库中的样式优先级，确保UI包组件的优先级低于应用特定的覆盖样式。

Layer Hierarchy (lowest -> highest priority)

层级结构（优先级从低到高）

  1. @layer reset
    - Browser resets and normalizations
  2. @layer components
    - Design system component styles (UI package)
  3. Unlayered styles - App-specific overrides (highest priority)
  1. @layer reset
    - 浏览器重置与规范化
  2. @layer components
    - 设计系统组件样式（UI包）
  3. 无层级样式 - 应用特定覆盖样式（最高优先级）

Key Rules

核心规则

  • UI package components: Always wrap in 
    @layer components {}
  • App-specific styles: Never wrap in layers (unlayered = highest priority)
  • Layer declaration: Import 
    layers.scss
    first to declare layer order
Why layers: Wrapping in 
@layer components {}
ensures app styles can override without specificity wars, loading order becomes irrelevant, predictable precedence across monorepo.
For complete implementation examples, see examples/core.md.
  • UI包组件： 始终包裹在
    @layer components {}
    中
  • 应用特定样式： 绝不包裹在层级中（无层级=最高优先级）
  • 层级声明： 先导入
    layers.scss
    以声明层级顺序
为什么使用层级： 包裹在
@layer components {}
中可确保应用样式无需通过特殊性竞争即可覆盖，加载顺序不再重要，在单体仓库中实现可预测的优先级。
完整实现示例请查看examples/core.md。

Pattern 4: Dark Mode with 
.dark
Class and Mixin

模式4：使用
.dark
类和Mixin的深色模式

Implement dark mode by adding 
.dark
class to root element, which overrides semantic tokens. Use mixin pattern for organization.
通过在根元素添加
.dark
类实现深色模式，该类会覆盖语义令牌。使用mixin模式进行组织。

Key Principles

核心原则

  • Components remain theme-agnostic (no theme logic in component code)
  • Semantic tokens provide indirection between theme and components
  • Only override Tier 2 semantic tokens in 
    .dark
    class, never Tier 1 core tokens
  • Theme switching is instant (just CSS variable changes)
For complete implementation examples, see examples/theming.md.
  • 组件保持主题无关（组件代码中无主题逻辑）
  • 语义令牌在主题与组件之间提供间接层
  • 仅在
    .dark
    类中覆盖第二层语义令牌，绝不能覆盖第一层核心令牌
  • 主题切换即时生效（仅需修改CSS变量）
完整实现示例请查看examples/theming.md。

Additional Patterns

其他模式

The following patterns are documented with full examples in the examples/ folder:
  • Pattern 5: SCSS Module Structure with Cascade Layers - examples/patterns.md
  • Pattern 6: Spacing System with Semantic Tokens - examples/tokens.md
  • Pattern 7: Typography System with REM-Based Sizing - examples/tokens.md
  • Pattern 8: Data-Attributes for State Styling - examples/patterns.md
  • Pattern 9: SCSS Mixins for Reusable Patterns - examples/patterns.md
  • Pattern 10: Global Styles Organization - examples/patterns.md
  • Pattern 11: Icon Styling - examples/patterns.md
  • Pattern 12: cva Integration - examples/cva.md
  • Pattern 13: Advanced CSS Features - examples/advanced.md
  • Pattern 14: Sass Module System (@use and @forward) - examples/modules.md
</patterns>
<red_flags>
以下模式在examples/文件夹中有完整示例文档：
  • 模式5： 结合Cascade Layers的SCSS模块结构 - examples/patterns.md
  • 模式6： 基于语义令牌的间距系统 - examples/tokens.md
  • 模式7： 基于REM尺寸的排版系统 - examples/tokens.md
  • 模式8： 用于状态样式的数据属性 - examples/patterns.md
  • 模式9： 用于可复用模式的SCSS Mixins - examples/patterns.md
  • 模式10： 全局样式组织 - examples/patterns.md
  • 模式11： 图标样式 - examples/patterns.md
  • 模式12： cva集成 - examples/cva.md
  • 模式13： 高级CSS特性 - examples/advanced.md
  • 模式14： Sass模块系统（@use和@forward） - examples/modules.md
</patterns>
<red_flags>

RED FLAGS

注意事项

For complete anti-patterns and red flags, see reference.md.
High Priority Issues:
  • Using core tokens directly in components (use semantic tokens)
  • Component styles not wrapped in 
    @layer components {}
  • Using Sass color functions (
    darken()
    , 
    lighten()
    )
  • Hardcoded color/spacing values
  • Theme logic in components
  • Using 
    @import
    instead of 
    @use
    (deprecated in Dart Sass 1.80.0, removed in 3.0.0)
  • Using 
    /
    for division instead of 
    math.div()
    (deprecated)
</red_flags>
<critical_reminders>
完整的反模式与注意事项请查看reference.md。
高优先级问题：
  • 在组件中直接使用核心令牌（应使用语义令牌）
  • 组件样式未包裹在
    @layer components {}
    中
  • 使用Sass颜色函数（
    darken()
    、
    lighten()
    ）
  • 硬编码颜色/间距值
  • 组件中包含主题逻辑
  • 使用
    @import
    而非
    @use
    （在Dart Sass 1.80.0中已弃用，3.0.0中移除）
  • 使用
    /
    进行除法而非
    math.div()
    （已弃用）
</red_flags>
<critical_reminders>

CRITICAL REMINDERS

重要提醒

All code must follow project conventions in CLAUDE.md
(You MUST wrap ALL UI package component styles in 
@layer components {}
for proper cascade precedence)
(You MUST use semantic tokens ONLY in components - NEVER use core tokens directly)
(You MUST use HSL format for colors with CSS color functions - NO Sass color functions like darken/lighten)
(You MUST use data-attributes for state styling - NOT className toggling)
(You MUST use 
@use
for imports - 
@import
is deprecated and will be removed in Dart Sass 3.0.0)
Failure to follow these rules will break theming, create cascade precedence issues, and violate design system conventions.
</critical_reminders>
所有代码必须遵循CLAUDE.md中的项目约定
（必须将所有UI包组件样式包裹在
@layer components {}
中，以确保正确的层级优先级）
（组件中必须仅使用语义令牌——绝不能直接使用核心令牌）
（必须使用HSL格式配合CSS颜色函数——禁止使用Sass颜色函数如darken/lighten）
（必须使用数据属性进行状态样式设置——不能使用className切换）
（必须使用
@use
进行导入——
@import
已被弃用，将在Dart Sass 3.0.0中移除）
不遵守这些规则会破坏主题系统、导致层级优先级问题，并违反设计系统约定。
</critical_reminders>