CSS 架构与命名规范

/* 块 */
.card {
  background-color: white;
  border-radius: 8px;
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
  padding: 20px;
}

/* 元素 */
.card__header {
  margin-bottom: 15px;
  padding-bottom: 15px;
  border-bottom: 1px solid #eee;
}
.card__title {
  margin: 0;
  font-size: 1.25rem;
  font-weight: 600;
}
.card__body { margin-bottom: 15px; }
.card__text {
  margin: 0 0 10px 0;
  line-height: 1.6;
  color: #666;
}
.card__footer {
  display: flex;
  justify-content: flex-end;
  gap: 10px;
}

/* 修饰符 */
.card--featured { border: 2px solid #007bff; }
.card--compact  { padding: 10px; }
.card__title--large { font-size: 1.5rem; }

<!-- HTML 使用：类名即文档结构 -->
<div class="card card--featured">
  <div class="card__header">
    <h2 class="card__title card__title--large">标题</h2>
  </div>
  <div class="card__body">
    <p class="card__text">内容文本</p>
  </div>
  <div class="card__footer">
    <button class="card__button">按钮</button>
  </div>
</div>

/* 结构类：只管布局骨架 */
.media {
  display: flex;
  align-items: flex-start;
}
.media__object { margin-right: 1rem; }
.media__body {
  flex: 1;
  overflow: hidden;
}

/* 外观类（皮肤）：只管视觉，可任意叠加 */
.media--bordered {
  border: 1px solid #ddd;
  padding: 1rem;
  border-radius: 4px;
}
.media--spaced { margin-bottom: 1rem; }

<!-- 组合使用：结构 + 多个外观皮肤 -->
<div class="media media--bordered media--spaced">
  <img class="media__object" src="avatar.jpg" alt="头像">
  <div class="media__body">
    <h3>标题</h3>
    <p>内容文本</p>
  </div>
</div>

/* Base - 基础样式 */
* { box-sizing: border-box; }
body {
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
  line-height: 1.6;
  color: #333;
}

/* Layout - 布局样式（l- 前缀） */
.l-container {
  max-width: 1200px;
  margin: 0 auto;
  padding: 0 20px;
}
.l-grid { display: grid; gap: 20px; }

/* Module - 模块样式 */
.card {
  background-color: white;
  border-radius: 8px;
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
  padding: 20px;
}
.button {
  padding: 10px 20px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  transition: all 0.3s ease;
}

/* State - 状态样式（is- 前缀） */
.is-active   { background-color: #007bff; color: white; }
.is-hidden   { display: none; }
.is-disabled { opacity: 0.5; cursor: not-allowed; }

/* Theme - 主题样式（theme- 前缀） */
.theme-dark  { background-color: #1a1a1a; color: #fff; }
.theme-light { background-color: #fff; color: #333; }

/* 1. Settings：设计令牌 */
:root {
  --color-primary: #007bff;
  --space-md: 16px;
  --radius: 8px;
}

/* 4. Elements：裸元素 */
a { color: var(--color-primary); text-decoration: none; }

/* 5. Objects：o- 前缀，只做布局 */
.o-container {
  max-width: 1200px;
  margin-inline: auto;
  padding-inline: var(--space-md);
}

/* 6. Components：c- 前缀，具体组件 */
.c-button {
  padding: 10px 20px;
  border-radius: var(--radius);
  background: var(--color-primary);
  color: #fff;
}

/* 7. Utilities：u- 前缀，最高优先级 */
.u-hidden { display: none !important; }
.u-text-center { text-align: center !important; }

/* 间距工具类 */
.p-1 { padding: 0.25rem; }
.p-2 { padding: 0.5rem; }
.p-3 { padding: 1rem; }
.p-4 { padding: 1.5rem; }
.m-1 { margin: 0.25rem; }
.m-2 { margin: 0.5rem; }
.m-3 { margin: 1rem; }
.m-4 { margin: 1.5rem; }

/* 文本工具类 */
.text-center { text-align: center; }
.text-left   { text-align: left; }
.text-right  { text-align: right; }
.text-sm   { font-size: 0.875rem; }
.text-base { font-size: 1rem; }
.text-lg   { font-size: 1.125rem; }
.text-xl   { font-size: 1.25rem; }

/* 颜色工具类 */
.text-primary   { color: #007bff; }
.text-secondary { color: #6c757d; }
.text-success   { color: #28a745; }
.text-danger    { color: #dc3545; }
.bg-primary { background-color: #007bff; }
.bg-danger  { background-color: #dc3545; }

/* 布局工具类 */
.flex { display: flex; }
.flex-col { flex-direction: column; }
.items-center   { align-items: center; }
.justify-center { justify-content: center; }
.justify-between{ justify-content: space-between; }

<!-- 组合使用：无需为这个卡片写任何专属 CSS -->
<div class="p-4 bg-white rounded shadow">
  <h2 class="text-xl text-primary mb-2">标题</h2>
  <p class="text-base text-secondary mb-4">内容文本</p>
  <div class="flex justify-between">
    <button class="px-4 py-2 bg-primary text-white rounded">确定</button>
    <button class="px-4 py-2 bg-secondary text-white rounded">取消</button>
  </div>
</div>

/* CSS Modules：类名自动哈希，绝不冲突 */
/* Button.module.css -> .primary { background: #007bff; } */
import styles from './Button.module.css';

function Button() {
  return <button className={styles.primary}>确定</button>;
}

/* Styled-components：样式即组件，支持 props 动态化 */
import styled from 'styled-components';

const Button = styled.button`
  padding: 10px 20px;
  border-radius: 4px;
  background: ${(props) => (props.primary ? '#007bff' : '#6c757d')};
  color: #fff;
`;

// <Button primary>确定</Button>

/* 特异性对比：谁的权重高谁生效，与书写顺序无关 */
#nav .list li a       { color: red; }   /* (0,1,1,2) 权重高 */
.nav .list .item .link{ color: blue; }  /* (0,0,4,0) 权重反而低！ */
/* 结果：即使蓝色写在后面，红色因含 ID 仍胜出 */

/* 架构的目标：让选择器尽量保持在 (0,0,1,0) 这一层 */
.link { color: blue; } /* 扁平单类，特异性稳定、易覆盖 */

/* 一次性声明层的优先级顺序（越靠后优先级越高） */
@layer reset, base, components, utilities;

@layer components {
  /* 即便这里用了高特异性选择器 */
  .card .title#main { color: black; }
}

@layer utilities {
  /* 这个低特异性的类依然能覆盖上面的 —— 因为 utilities 层更靠后 */
  .text-red { color: red; }
}

/* Composition：通用间隔布局原语 */
.flow > * + * { margin-block-start: var(--flow-space, 1rem); }

/* Utility：原子类 */
.text-center { text-align: center; }

/* Block：组件特有样式 */
.card { border-radius: 8px; padding: var(--space-md); }

/* Exception：用 data 属性表达状态 */
.card[data-state="featured"] { border: 2px solid var(--color-primary); }

/* 定义语义化令牌，组件只消费语义变量，不碰具体色值 */
:root {
  --color-bg: #ffffff;
  --color-text: #1a1a1a;
  --color-surface: #f5f5f5;
  --color-primary: #007bff;
}

/* 暗色主题：只需覆盖同名变量 */
[data-theme="dark"] {
  --color-bg: #1a1a1a;
  --color-text: #f5f5f5;
  --color-surface: #2a2a2a;
  --color-primary: #4d9fff;
}

/* 组件消费语义变量，天然支持任意主题 */
.panel {
  background: var(--color-surface);
  color: var(--color-text);
}

/* 跟随系统偏好自动切换 */
@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    --color-bg: #1a1a1a;
    --color-text: #f5f5f5;
  }
}

// 配套的主题切换逻辑：改一个属性，全站变色
function toggleTheme() {
  const root = document.documentElement;
  const next = root.dataset.theme === 'dark' ? 'light' : 'dark';
  root.dataset.theme = next;
  localStorage.setItem('theme', next); // 记住用户选择
}

// .stylelintrc.js
module.exports = {
  extends: ['stylelint-config-standard'],
  rules: {
    // 限制选择器最大特异性，逼团队写扁平选择器
    'selector-max-specificity': '0,3,0',
    // 禁止 ID 选择器，避免特异性飙升
    'selector-max-id': 0,
    // 强制 BEM 命名格式
    'selector-class-pattern': '^[a-z]([a-z0-9-]+)?(__([a-z0-9-]+))?(--([a-z0-9-]+))?$',
    // 禁止 !important（架构失败信号）
    'declaration-no-important': true,
  }
};

{
  "color": {
    "primary": { "value": "#007bff" },
    "danger":  { "value": "#dc3545" }
  },
  "space": {
    "md": { "value": "16px" }
  }
}

/* 编译产出的 CSS（自动生成，勿手改） */
:root {
  --color-primary: #007bff;
  --color-danger: #dc3545;
  --space-md: 16px;
}

/* 声明容器 */
.card-container {
  container-type: inline-size;
  container-name: card;
}

/* 组件根据容器宽度而非视口宽度自适应 */
@container card (min-width: 400px) {
  .card { display: grid; grid-template-columns: 120px 1fr; }
}
@container card (max-width: 399px) {
  .card { display: block; }
}

// postcss.config.js —— 生产构建时清除未使用的 CSS
module.exports = {
  plugins: [
    require('@fullhuman/postcss-purgecss')({
      content: ['./src/**/*.{html,jsx,tsx,vue}'],
      // 保护动态拼接的类名不被误删
      safelist: [/^is-/, /^has-/, /^theme-/],
    })
  ]
};

/* 组件层：永远只用语义变量，与品牌无关 */
.btn-primary {
  background: var(--brand-primary);
  border-radius: var(--brand-radius);
  font-family: var(--brand-font);
}

/* 品牌 A 令牌 */
[data-brand="a"] {
  --brand-primary: #ff6b00;
  --brand-radius: 4px;
  --brand-font: 'Roboto', sans-serif;
}
/* 品牌 B 令牌 */
[data-brand="b"] {
  --brand-primary: #0066cc;
  --brand-radius: 12px;
  --brand-font: 'Inter', sans-serif;
}

/* Atoms：原子级——只关心自身，不关心上下文 */
.atom-button {
  display: inline-flex;
  align-items: center;
  gap: 0.5rem;
  padding: 0.5rem 1rem;
  border: none;
  border-radius: var(--radius);
  font: inherit;
  cursor: pointer;
}
.atom-input {
  padding: 0.5rem 0.75rem;
  border: 1px solid var(--color-border);
  border-radius: var(--radius);
}
.atom-icon {
  width: 1em;
  height: 1em;
  fill: currentColor;
}

/* Molecules：分子——由原子组合，负责它们之间的布局关系 */
.molecule-search {
  display: flex;
  gap: 0.5rem;
  align-items: center;
}
.molecule-search .atom-input { flex: 1; }

/* Organisms：有机体——较完整的功能区块 */
.organism-header {
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: 1rem 2rem;
  border-bottom: 1px solid var(--color-border);
}

/* base.module.css —— 抽出可复用的基础样式 */
.buttonBase {
  padding: 10px 20px;
  border-radius: 4px;
  cursor: pointer;
  border: none;
}

/* Button.module.css —— 用 composes 组合基础样式 */
.primary {
  composes: buttonBase from './base.module.css';
  background: #007bff;
  color: #fff;
}
.danger {
  composes: buttonBase from './base.module.css';
  background: #dc3545;
  color: #fff;
}

/* :global 逃逸——需要对接第三方库的全局类名时 */
:global(.ant-btn) {
  border-radius: 8px;
}

/* :local 显式声明局部（默认即局部，用于覆盖 :global 上下文） */
:global .theme-dark {
  :local(.primary) { background: #4d9fff; }
}

// 消费端：多个 module 类名可以随意组合
import styles from './Button.module.css';
import cx from 'classnames';

function Button({ variant = 'primary', disabled }) {
  return (
    <button className={cx(styles[variant], { [styles.disabled]: disabled })}>
      提交
    </button>
  );
}

// main.scss —— 唯一入口，按依赖顺序 @use
@use 'abstracts/variables';   // 1. 变量、令牌
@use 'abstracts/functions';   // 2. 函数
@use 'abstracts/mixins';      // 3. 混入
@use 'vendors/normalize';     // 4. 第三方
@use 'base/reset';            // 5. 重置
@use 'base/typography';       // 6. 排版
@use 'layout/grid';           // 7. 布局
@use 'layout/header';
@use 'components/button';     // 8. 组件
@use 'components/card';
@use 'pages/home';            // 9. 页面专属
@use 'themes/dark';           // 10. 主题

// abstracts/_mixins.scss —— 沉淀可复用的响应式与工具混入
@mixin respond-to($breakpoint) {
  @if $breakpoint == 'tablet' {
    @media (min-width: 768px) { @content; }
  } @else if $breakpoint == 'desktop' {
    @media (min-width: 1024px) { @content; }
  }
}

@mixin truncate($lines: 1) {
  @if $lines == 1 {
    white-space: nowrap;
    overflow: hidden;
    text-overflow: ellipsis;
  } @else {
    display: -webkit-box;
    -webkit-line-clamp: $lines;
    -webkit-box-orient: vertical;
    overflow: hidden;
  }
}

// 使用
.card__title {
  @include truncate(2);
  @include respond-to('desktop') { font-size: 1.5rem; }
}

// components/_button.scss —— 用 @each 批量生成变体，减少重复
$button-variants: (
  'primary': #007bff,
  'success': #28a745,
  'danger':  #dc3545,
);

.button {
  padding: 10px 20px;
  border-radius: 4px;

  @each $name, $color in $button-variants {
    &--#{$name} {
      background: $color;
      &:hover { background: darken($color, 10%); }
    }
  }
}

// postcss.config.js —— 典型的现代流水线配置
module.exports = {
  plugins: [
    // 1. 允许使用未来的 CSS 语法，自动降级
    require('postcss-preset-env')({
      stage: 2,
      features: {
        'nesting-rules': true,          // 原生嵌套降级
        'custom-media-queries': true,   // @custom-media
      },
    }),
    // 2. 自动补全浏览器前缀
    require('autoprefixer'),
    // 3. 生产环境压缩
    ...(process.env.NODE_ENV === 'production'
      ? [require('cssnano')({ preset: 'default' })]
      : []),
    // 4. 清除未使用的样式
    require('@fullhuman/postcss-purgecss')({
      content: ['./src/**/*.{html,jsx,tsx,vue}'],
      safelist: [/^is-/, /^has-/, /data-/],
    }),
  ],
};

/* @custom-media：把媒体查询也令牌化，断点集中管理 */
@custom-media --tablet (min-width: 768px);
@custom-media --desktop (min-width: 1024px);

.sidebar {
  display: none;
  @media (--desktop) { display: block; }
}

/* 坏：强依赖 DOM 结构，加一层 div 就失效 */
.sidebar > div > ul > li > a { color: #333; }

/* 好：给关键节点一个语义类，结构可自由调整 */
.sidebar__link { color: #333; }

/* 坏：按钮在头部和侧栏必须长得不一样才对 —— 其实是耦合了位置 */
.header .button { font-size: 14px; }
.sidebar .button { font-size: 12px; }

/* 好：用 modifier 表达差异，组件自身与位置解耦 */
.button--sm { font-size: 12px; }
.button--md { font-size: 14px; }

/* 坏：色值散落在组件里 */
.card { border: 1px solid #ddd; background: #fff; }

/* 好：组件只消费语义变量，主题层统一供给 */
.card { border: 1px solid var(--color-border); background: var(--color-surface); }

/* 状态类：单一职责，只描述"处于某状态时叠加什么" */
.is-loading  { opacity: 0.6; pointer-events: none; }
.is-active   { border-color: var(--color-primary); }
.is-hidden   { display: none !important; }
.is-expanded { max-height: 1000px; }
.has-error   { border-color: var(--color-danger); }
.has-error .field__hint { color: var(--color-danger); }

/* 与组件组合：组件 + 状态，正交叠加 */
.dropdown { max-height: 0; overflow: hidden; transition: max-height 0.3s; }
.dropdown.is-expanded { max-height: 400px; }

// JS 只负责切换状态类，不直接操作样式
const dropdown = document.querySelector('.dropdown');
button.addEventListener('click', () => {
  dropdown.classList.toggle('is-expanded');
});

[data-state="loading"] { opacity: 0.6; }
[data-state="error"]   { border-color: var(--color-danger); }

<!-- Vue 单文件组件：scoped 自动加属性选择器实现隔离 -->
<template>
  <button class="btn" :class="{ 'is-loading': loading }">
    <slot />
  </button>
</template>

<style scoped>
/* 编译后变成 .btn[data-v-xxxxxx]，作用域隔离 */
.btn {
  padding: 10px 20px;
  border-radius: var(--radius);
}
/* 深度选择器：需要穿透到子组件时 */
:deep(.child-class) { color: red; }
</style>

// React + CSS Modules：最主流的零运行时隔离方案
import styles from './Card.module.css';
export function Card({ children }) {
  return <div className={styles.card}>{children}</div>;
}

// React + Vanilla Extract：编译期 CSS-in-TS，类型安全且零运行时
import { style } from '@vanilla-extract/css';
export const card = style({
  padding: 20,
  borderRadius: 8,
  boxShadow: '0 2px 4px rgba(0,0,0,0.1)',
  ':hover': { transform: 'translateY(-2px)' },
});

<!-- 首屏关键 CSS 内联进 <head>，避免额外请求阻塞渲染 -->
<head>
  <style>
    /* 仅包含首屏可见区域的样式，通常 <14KB */
    .header { /* ... */ }
    .hero { /* ... */ }
  </style>
  <!-- 非关键 CSS 异步加载，不阻塞首屏 -->
  <link rel="preload" href="/main.css" as="style"
        onload="this.rel='stylesheet'">
</head>

// 按路由分割 CSS：只加载当前页需要的样式
// 现代打包器（Vite/webpack）配合动态 import 自动完成
const AboutPage = () => import('./pages/About.vue'); // 其 CSS 会被独立打包

/* 第一步：用 @layer 把老样式整体降到最低层，为新样式让路 */
@layer legacy, base, components, utilities;

@layer legacy {
  /* @import 老的巨石样式表进 legacy 层 */
}

/* 新样式写进更高的层，天然覆盖老样式，无需 !important */
@layer components {
  .c-button { /* 新版按钮 */ }
}

// package.json 里用 bundlesize 给 CSS 体积设预算，超标 CI 报错
{
  "bundlesize": [
    { "path": "./dist/*.css", "maxSize": "30 kB" }
  ]
}

# 用 wallace 分析一份 CSS 的健康度报告
npx wallace-cli dist/main.css
# 输出：选择器数量、特异性分布、!important 计数、重复规则等

/* 第一层：令牌（Design Tokens）—— 一份 JSON 编译到多端 */
:root {
  --ds-color-primary: #2563eb;
  --ds-color-danger: #dc2626;
  --ds-space-1: 4px;
  --ds-space-2: 8px;
  --ds-space-3: 16px;
  --ds-radius-md: 8px;
  --ds-font-size-body: 14px;
}

/* 第二层：基础组件（原子/分子）—— 只消费令牌 */
.ds-select {
  height: 36px;
  padding: 0 var(--ds-space-3);
  border: 1px solid var(--ds-color-border);
  border-radius: var(--ds-radius-md);
  font-size: var(--ds-font-size-body);
}
.ds-select:focus-visible {
  outline: 2px solid var(--ds-color-primary);
  outline-offset: 1px;
}

/* 第三层：主题皮肤 —— 各产品线只覆盖令牌 */
[data-product="finance"] { --ds-color-primary: #0f766e; }
[data-product="social"]  { --ds-color-primary: #db2777; }

<!-- 迁移前：需要在 SCSS 里定义 .promo-card 及其所有子元素 -->
<div class="promo-card">
  <h3 class="promo-card__title">标题</h3>
  <p class="promo-card__desc">描述</p>
</div>

<!-- 迁移后：原子类组合，无需写任何自定义 CSS -->
<div class="rounded-lg bg-white p-6 shadow-md">
  <h3 class="mb-2 text-xl font-semibold text-gray-900">标题</h3>
  <p class="text-sm text-gray-600">描述</p>
</div>

// 用 @apply 抽出高频组合，兼顾原子化与复用（避免类名地狱）
// components.css
.btn-primary {
  @apply inline-flex items-center rounded-md bg-blue-600 px-4 py-2
         font-medium text-white transition hover:bg-blue-700;
}

<!-- 方案 A：BEM —— 语义清晰、优先级扁平 -->
<div class="notice notice--warning">
  <span class="notice__icon"></span>
  <div class="notice__content">
    <h4 class="notice__title">标题</h4>
    <p class="notice__text">内容</p>
  </div>
</div>

<!-- 方案 B：Utility —— 无需自定义 CSS，但类名冗长 -->
<div class="flex gap-3 rounded-lg border-l-4 border-yellow-400 bg-yellow-50 p-4">
  <span class="h-5 w-5 shrink-0 text-yellow-500"></span>
  <div>
    <h4 class="font-semibold text-yellow-800">标题</h4>
    <p class="text-sm text-yellow-700">内容</p>
  </div>
</div>

<!-- 方案 C：CUBE CSS —— 组合原语 + 少量组件类 + data 状态 -->
<div class="notice cluster" data-variant="warning">
  <span class="notice__icon"></span>
  <div class="stack">
    <h4>标题</h4>
    <p>内容</p>
  </div>
</div>

/* CUBE CSS 配套：组合原语可跨组件复用 */
.cluster { display: flex; gap: var(--space-sm); }
.stack > * + * { margin-block-start: var(--space-xs); }
.notice[data-variant="warning"] {
  border-inline-start: 4px solid var(--color-warning);
  background: var(--color-warning-bg);
}

/* 1. 断点令牌化：断点集中定义，避免魔法数字散落 */
:root {
  --bp-sm: 640px;
  --bp-md: 768px;
  --bp-lg: 1024px;
  --bp-xl: 1280px;
}

/* 2. 移动优先：默认写窄屏样式，用 min-width 逐级增强 */
.grid {
  display: grid;
  grid-template-columns: 1fr;          /* 移动端单列 */
  gap: var(--space-md);
}
@media (min-width: 768px) {
  .grid { grid-template-columns: repeat(2, 1fr); }  /* 平板两列 */
}
@media (min-width: 1024px) {
  .grid { grid-template-columns: repeat(4, 1fr); }  /* 桌面四列 */
}

/* 3. 内在响应式：用 auto-fit + minmax 免写媒体查询 */
.auto-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  gap: var(--space-md);
}

/* 4. 容器查询补位：组件级响应式，不依赖视口 */
.widget-area { container-type: inline-size; }
@container (min-width: 400px) {
  .widget { display: flex; }
}

/* 1. 定义语义令牌（不是具体颜色，而是"用途"） */
:root {
  color-scheme: light;
  --bg-base: #ffffff;
  --bg-elevated: #f8f9fa;
  --text-primary: #1a1a1a;
  --text-secondary: #6b7280;
  --border-subtle: #e5e7eb;
  --shadow-color: 0 0 0 / 0.1;
}

/* 2. 暗色主题：只覆盖令牌，组件代码零改动 */
[data-theme="dark"] {
  color-scheme: dark;
  --bg-base: #0f172a;
  --bg-elevated: #1e293b;
  --text-primary: #f1f5f9;
  --text-secondary: #94a3b8;
  --border-subtle: #334155;
  --shadow-color: 0 0 0 / 0.4;
}

/* 3. 跟随系统偏好（用户未手动选择时） */
@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    color-scheme: dark;
    --bg-base: #0f172a;
    --text-primary: #f1f5f9;
  }
}

/* 4. 组件只消费语义令牌，自动支持所有主题 */
.card {
  background: var(--bg-elevated);
  color: var(--text-primary);
  border: 1px solid var(--border-subtle);
  box-shadow: 0 4px 12px rgb(var(--shadow-color));
}

// 主题切换：读取本地存储与系统偏好，避免刷新闪烁（FOUC）
// 这段应内联在 <head> 最前面同步执行
(function () {
  const stored = localStorage.getItem('theme');
  const prefersDark = matchMedia('(prefers-color-scheme: dark)').matches;
  const theme = stored || (prefersDark ? 'dark' : 'light');
  document.documentElement.dataset.theme = theme;
})();

/* 反模式 1：位置耦合——组件依赖它被放在哪 */
.homepage .sidebar .widget h3 { font-size: 18px; }   /* 坏 */
.widget__title { font-size: 18px; }                   /* 好 */

/* 反模式 2：特异性军备竞赛 */
.nav ul li a.active span { color: red !important; }   /* 坏 */
.nav__label--active { color: red; }                   /* 好 */

/* 反模式 3：魔法数字 */
.modal { top: 137px; left: 249px; }                   /* 坏 */
.modal { inset: 50%; translate: -50% -50%; }          /* 好 */

/* 反模式 4：颜色硬编码遍地开花 */
.btn { background: #3b82f6; }
.link { color: #3b82f6; }                             /* 坏：改主题要全局搜 */
.btn { background: var(--color-primary); }
.link { color: var(--color-primary); }                /* 好 */

/* 反模式 5：用 ID 写通用样式 */
#submit-button { padding: 10px; }                     /* 坏：优先级 100，难覆盖 */
.button { padding: 10px; }                            /* 好 */

/* 反模式 6：过度嵌套 */
.a .b .c .d .e { }                                    /* 坏：脆弱且慢 */
.deep-target { }                                      /* 好：扁平单类 */

// Button.stories.js —— 用 Storybook 沉淀所有组件状态
export default { title: 'Components/Button', component: Button };

export const Primary = { args: { variant: 'primary', children: '主按钮' } };
export const Loading = { args: { loading: true, children: '加载中' } };
export const Disabled = { args: { disabled: true, children: '禁用' } };
export const AllVariants = {
  render: () => `
    <button class="button button--primary">主要</button>
    <button class="button button--secondary">次要</button>
    <button class="button button--danger">危险</button>
  `,
};

// 配合 Chromatic 做视觉回归：每个 story 自动截图对比
// .storybook/main.js 里接入，PR 时自动跑，走样即拦截
export default {
  addons: ['@chromatic-com/storybook'],
};

/* 模式 1：变量兜底链——多级 fallback，令牌未定义时优雅降级 */
.card {
  padding: var(--card-padding, var(--space-md, 16px));
}

/* 模式 2：作用域覆盖——同名变量在局部重定义，实现"上下文皮肤" */
.sidebar {
  --color-primary: #7c3aed;  /* 侧栏内主色变紫，无需新类名 */
}
.sidebar .button { background: var(--color-primary); }

/* 模式 3：开关变量——用变量做 "CSS 版 if"（space toggle 技巧） */
.alert {
  --is-dismissible: ;          /* 空值 = 开 */
  --close-display: var(--is-dismissible) none;
}
.alert--permanent {
  --is-dismissible: initial;   /* initial 让下面回退 */
}

/* 模式 4：计算派生——用一个基准变量派生整套间距 */
:root { --space-unit: 8px; }
.box {
  padding: calc(var(--space-unit) * 2);   /* 16px */
  gap: calc(var(--space-unit) * 3);       /* 24px */
}

/* 模式 5：响应式变量——变量本身随媒体查询变化，组件自动跟随 */
:root { --gutter: 16px; }
@media (min-width: 1024px) { :root { --gutter: 32px; } }
.layout { padding-inline: var(--gutter); }

// .stylelintrc.js —— 生产级架构治理配置
module.exports = {
  extends: ['stylelint-config-standard', 'stylelint-config-recess-order'],
  plugins: ['stylelint-declaration-strict-value'],
  rules: {
    // 特异性与选择器约束
    'selector-max-specificity': '0,3,0',
    'selector-max-id': 0,
    'selector-max-compound-selectors': 3,     // 嵌套不超过 3 层
    'selector-no-qualifying-type': true,       // 禁止 div.foo 这种限定
    // 命名规范
    'selector-class-pattern':
      '^[a-z]([a-z0-9-]+)?(__([a-z0-9-]+))?(--([a-z0-9-]+))?$',
    // 禁止硬编码——颜色/字号必须走变量
    'scale-unlimited/declaration-strict-value': [
      ['/color/', 'font-size', 'z-index'],
      { ignoreValues: ['transparent', 'currentColor', 'inherit'] },
    ],
    // 架构失败信号
    'declaration-no-important': true,
    // 一致性
    'color-hex-length': 'short',
    'shorthand-property-no-redundant-values': true,
  },
};

// package.json —— 把检查挂进 lint-staged，提交即校验
{
  "lint-staged": {
    "*.{css,scss}": ["stylelint --fix", "prettier --write"]
  }
}