Stylus 最佳实践 #

styles/
├── abstracts/           # 抽象层（不输出样式）
│   ├── _variables.styl  # 变量定义
│   ├── _mixins.styl     # 混入定义
│   ├── _functions.styl  # 函数定义
│   └── _index.styl      # 统一导出
│
├── base/                # 基础样式
│   ├── _reset.styl      # 重置样式
│   ├── _typography.styl # 排版样式
│   └── _base.styl       # 基础元素
│
├── components/          # 组件样式
│   ├── _buttons.styl
│   ├── _cards.styl
│   ├── _forms.styl
│   └── _index.styl
│
├── layout/              # 布局样式
│   ├── _header.styl
│   ├── _footer.styl
│   ├── _sidebar.styl
│   └── _grid.styl
│
├── pages/               # 页面样式
│   ├── _home.styl
│   └── _about.styl
│
├── themes/              # 主题样式
│   ├── _light.styl
│   └── _dark.styl
│
├── utilities/           # 工具类
│   └── _utilities.styl
│
└── main.styl            # 主入口

// main.styl

// 1. 配置和变量
@require 'abstracts/variables'

// 2. 混入和函数
@require 'abstracts/mixins'
@require 'abstracts/functions'

// 3. 基础样式
@require 'base/reset'
@require 'base/typography'
@require 'base/base'

// 4. 布局
@require 'layout/grid'
@require 'layout/header'
@require 'layout/footer'

// 5. 组件
@require 'components'

// 6. 页面
@require 'pages/home'
@require 'pages/about'

// 7. 主题
@require 'themes/default'

// 8. 工具类
@require 'utilities/utilities'

// 推荐：语义化、连字符分隔
primary-color = #3498db
secondary-color = #2ecc71
base-font-size = 16px
base-line-height = 1.5
container-width = 1200px

// 推荐：使用对象组织
colors = {
  primary: #3498db,
  secondary: #2ecc71,
  success: #27ae60,
  warning: #f39c12,
  danger: #e74c3c
}

spacing = {
  xs: 4px,
  sm: 8px,
  md: 16px,
  lg: 24px,
  xl: 32px
}

// 不推荐：无意义命名
color1 = #3498db
color2 = #2ecc71
value1 = 16px

// 推荐：动词或描述性名称
flex-center()
clearfix()
text-overflow()
border-radius()

// 推荐：带前缀区分
button-variant()
card-style()
form-input()

// 不推荐：无意义名称
helper1()
do-something()

// 推荐：返回值描述
px-to-rem(px)
text-contrast(bg-color)
grid-width(columns)

// 不推荐：模糊名称
convert(x)
calculate(n)

// BEM 命名模式
.block
  // 块
  
  &__element
    // 元素
    
  &--modifier
    // 修饰符

// 示例
.card
  border 1px solid #ddd
  border-radius 8px
  
  &__header
    padding 15px
    border-bottom 1px solid #ddd
    
  &__body
    padding 20px
    
  &__footer
    padding 15px
    border-top 1px solid #ddd
    
  &--featured
    border-color #3498db
    
    .card__header
      background-color #3498db
      color #fff

// 不推荐：嵌套太深
.page
  .content
    .article
      .body
        .paragraph
          color #333

// 推荐：最多 3 层
.article-paragraph
  color #333

// 或使用 BEM
.article
  &__paragraph
    color #333

// 推荐：按类型分组
.element
  // 1. 定位
  position absolute
  top 0
  left 0
  z-index 10
  
  // 2. 盒模型
  display flex
  width 100px
  height 100px
  padding 10px
  margin 10px
  
  // 3. 边框和背景
  border 1px solid #ddd
  border-radius 4px
  background-color #fff
  
  // 4. 文字
  font-size 14px
  line-height 1.5
  color #333
  text-align center
  
  // 5. 其他
  cursor pointer
  transition all 0.3s

// 推荐：使用变量
primary-color = #3498db

.button
  background-color primary-color
  
  &:hover
    background-color darken(primary-color, 10%)

// 不推荐：硬编码
.button
  background-color #3498db
  
  &:hover
    background-color #2980b9

// 推荐：使用混入复用
flex-center()
  display flex
  justify-content center
  align-items center

.modal
  flex-center()

.tooltip
  flex-center()

// 不推荐：重复代码
.modal
  display flex
  justify-content center
  align-items center

.tooltip
  display flex
  justify-content center
  align-items center

// 不推荐：选择器太长
.header .nav .list .item .link .icon
  color #333

// 推荐：简洁选择器
.nav-icon
  color #333

// 不推荐：重复属性
.button-primary
  padding 10px 20px
  border-radius 4px
  background-color #3498db

.button-secondary
  padding 10px 20px
  border-radius 4px
  background-color #2ecc71

// 推荐：使用 @extend 或混入
button-base()
  padding 10px 20px
  border-radius 4px

.button-primary
  button-base()
  background-color #3498db

.button-secondary
  button-base()
  background-color #2ecc71

// 推荐：使用 @require 避免重复
@require 'variables'

// 不推荐：使用 @import 可能重复
@import 'variables'
@import 'variables'  // 会重复导入

// 只在需要时包含
features = {
  icons: true,
  charts: false,
  animations: true
}

if features.icons
  @require 'components/icons'

if features.charts
  @require 'components/charts'

if features.animations
  @require 'components/animations'

// 陷阱：变量覆盖
color = #333

.button
  color = #3498db  // 局部变量
  background-color color  // #3498db

.link
  color color  // #333（全局变量）

// 解决：使用 !global 或不同命名
color = #333

.button
  button-color = #3498db
  background-color button-color

// 陷阱：单位丢失
width = 100 / 2  // 50（无单位）

// 解决：保持单位
width = 100px / 2  // 50px

// 陷阱：不同单位运算
width = 100px + 1em  // calc(100px + 1em)

// 解决：统一单位或使用 calc
width = 100px + 16px  // 116px

// 陷阱：过度嵌套导致选择器权重过高
.container
  .content
    .article
      .body
        .paragraph
          color #333  // .container .content .article .body .paragraph

// 解决：扁平化
.article-paragraph
  color #333

// 陷阱：生成过多 CSS
for i in 1..1000
  .w-{i}
    width i * 1%

// 解决：只生成需要的
widths = 10 20 25 30 33 40 50 60 66 70 75 80 90 100
for w in widths
  .w-{w}
    width w * 1%

// 陷阱：变量未定义
.button
  color primary-color  // 错误：primary-color 未定义

@require 'variables'

// 解决：先导入变量
@require 'variables'

.button
  color primary-color

// settings.json
{
  "stylusSupremacy.insertColons": false,
  "stylusSupremacy.insertSemicolons": false,
  "stylusSupremacy.insertBraces": false,
  "stylusSupremacy.sortProperties": "grouped",
  "stylusSupremacy.alwaysUseImport": true,
  "stylusSupremacy.quoteChar": "'"
}

// .stylintrc
{
  "colons": "never",
  "semicolons": "never",
  "quotes": "single",
  "brackets": "never",
  "parenSpace": true,
  "prefixVarsWithDollar": false,
  "sortProperties": "grouped"
}