styles —— la source des styles

styles/ est l’unique source des styles BEM des composants de toute la famille (ligne rouge 2) : 58 répertoires de composants + la couche de jetons theme/common/. Aucune bibliothèque UI n’a le droit d’en copier les styles pour les modifier.

La structure du répertoire

styles/
├── index.scss                  # L'agrégat complet (jetons + tous les composants), importé en une ligne
├── theme/
│   ├── common/
│   │   ├── var.scss            # Les jetons clairs (:root, 185 variables CSS)
│   │   ├── var-dark.scss       # La surcharge sombre ([data-theme='dark'], .dark, 118 entrées)
│   │   ├── variables.scss      # La couche de variables SCSS (183 $lh-*, des constantes de compilation)
│   │   ├── patterns.scss       # Le système de motifs style chinois (6 textures)
│   │   ├── transition.scss     # La source unique des classes de transition (3 mixins)
│   │   └── …                   # La couche commune de mixins / functions
│   └── index.scss              # L'entrée de l'agrégat du thème
├── button/index.scss           # Les styles d'un composant (58 répertoires)
├── dialog/index.scss
└── …

Chaque répertoire de composant est un simple index.scss, importé par @lh-ui/share/styles/<name> (vite résout le répertoire vers index).

Comment importer

// Les quatre façons (voir le guide de démarrage)
import '@lh-ui/share/styles/button'        // Un seul composant
import '@lh-ui/share/styles'                // Tout (styles/index.scss)
import '@lh-ui/share/styles/theme'          // Uniquement les jetons du thème
import '@lh-ui/share/styles/theme/common/var-dark'  // Jusqu'au fichier précis

Les stratégies d’injection diffèrent selon la bibliothèque UI : plus injecte tout à l’entrée de la bibliothèque, vue2 laisse l’utilisateur importer à la demande (voir Stratégies d’injection).

Les conventions BEM

Les noms de classes portent toujours le préfixe lh- et suivent les trois couches BEM :

.lh-button {                    // Block
  &__text { }                   // Element
  &--primary { }                // Modifier
  &__text--disabled { }         // Element + Modifier
  &.is-loading { }              // Classe d'état (préfixe is-, sans espace de noms)
}

Le nommage est généré par createNamespace, garantissant la cohérence de toute la famille.
Les classes d’état portent le préfixe is- (is-loading / is-disabled / is-open), ce ne sont pas des modificateurs BEM.
Tout ajout de classe doit aussi mettre à jour docs/src/data/classes.json (généré par scripts/gen-docs-data.mjs en scannant styles/*/index.scss).

Les trois couches de jetons

Couche	Fichier	Quantité	Caractéristique
Variables CSS (clair)	`var.scss`	185 entrées	`:root { --lh-*: ... }`, surchargeable à l’exécution
Variables CSS (sombre)	`var-dark.scss`	118 entrées	Surcharge du clair via `[data-theme='dark'], .dark { ... }`
Variables SCSS	`variables.scss`	183 variables	Les `$lh-`, figées à la compilation*

Les composants ne peuvent consommer que des variables CSS

// ✅ Correct : repli en chaîne par var(), évalué à l'exécution
.lh-button--primary {
  color: var(--lh-color-on-primary, #fff);
  background: var(--lh-primary-color, #1677ff);
}

// ❌ Faux : référence directe à une variable SCSS, ne se retourne pas en mode sombre
.lh-button--primary {
  background: #{$lh-primary-color};
}

Le piège de la cuisson à la compilation

Dans var.scss, les jetons dont la valeur est de la forme #{$lh-foo} sont remplacés, à la compilation, par la valeur claire concrète ; ils ne se retournent pas automatiquement en mode sombre. De tels jetons doivent être explicitement redirigés, dans var-dark.scss, vers un jeton sémantique sombre :

[data-theme='dark'],
.dark {
  --lh-menu-item-color: var(--lh-text-primary);   // ← redirigé explicitement
}

Une telle lacune a déjà fait que, en mode sombre, les textes des menus / tableaux / timelines conservaient la valeur claire et devenaient invisibles. La vérification 7 de pnpm verify:styles (l’accessibilité du mode sombre) veille précisément là-dessus. À l’inverse, le repli en chaîne var(--lh-foo, var(--lh-bar, #x)) dans un composant est évalué à l’exécution : dès qu’un jeton de la chaîne possède une surcharge sombre, il est sûr, sans déclaration redondante. Voir Mode sombre.

`styles/index.scss` est un objet généré

Le fichier d’agrégat complet est généré par scripts/build-styles.mjs en scannant les répertoires de composants ; verify:styles en vérifie la cohérence — à ne pas modifier à la main. Un nouveau répertoire de composant est automatiquement couvert par l’agrégat.

Le marqueur hairline est abrogé

~~Toute déclaration de bordure fine 1px doit porter le marqueur en ligne /* hairline */~~ — cette ligne rouge est abrogée (uniapp v3 sort les px en direct, ne traduit plus les rpx, le marqueur a perdu son utilité ; voir docs/bugfix-log.md D-02). Les 65 marqueurs historiques de styles/ sont conservés comme des commentaires ordinaires, les nouvelles bordures 1px n’ont plus besoin d’être marquées. Les bordures structurelles (2px / 3px) ne l’ont jamais été.

La table complète des jetons du thème

主色与衍生语义

令牌	暗色	SCSS 源
`--lh-primary-color`	`#3D649E`	`$lh-primary`
`--lh-primary-color-hover`	`#5078AB`	`$lh-primary-hover`
`--lh-primary-color-active`	`#2B4C7C`	`$lh-primary-active`
`--lh-primary-color-bg`	`color-mix(in srgb, var(--lh-primary-color) 25%, transparent)`	`$lh-primary-light`
`--lh-primary-color-border`	`#2A3A4A`	`$lh-primary-lighter`
`--lh-color-on-primary`	`#fff`	`$lh-on-primary`

状态

令牌	明色	暗色	SCSS 源	备注
`--lh-hover-bg-color`		`rgba(255, 255, 255, 0.08)`	`$lh-hover-bg`
`--lh-selected-color`		`color-mix(in srgb, var(--lh-primary-color) 40%, #fff)`	—

功能色

令牌	暗色	SCSS 源
`--lh-success-color`	`#6FA36E`	`$lh-success`
`--lh-success-color-hover`	`#82B581`	`$lh-success-hover`
`--lh-success-color-active`	`#5B8C5A`	`$lh-success-active`
`--lh-success-color-bg`	`#1A2A1A`	`$lh-success-light`
`--lh-warning-color`	`#D4B76F`	`$lh-warning`
`--lh-warning-color-hover`	`#E0C680`	`$lh-warning-hover`
`--lh-warning-color-active`	`#C4A35A`	`$lh-warning-active`
`--lh-warning-color-bg`	`#2A251A`	`$lh-warning-light`
`--lh-danger-color`	`#C45050`	`$lh-danger`
`--lh-danger-color-hover`	`#D46060`	`$lh-danger-hover`
`--lh-danger-color-active`	`#B23A3A`	`$lh-danger-active`
`--lh-danger-color-bg`	`#2A1A1A`	`$lh-danger-light`
`--lh-info-color`	`#8F8F8F`	`$lh-info`
`--lh-info-color-hover`	`#A0A0A0`	`$lh-info-hover`
`--lh-info-color-active`	`#7A7A7A`	`$lh-info-active`
`--lh-info-color-bg`	`#1A1A1A`	`$lh-info-light`

国风装饰色

令牌	暗色	SCSS 源
`--lh-gold-color`	`#D4A843`	`$lh-gold`
`--lh-gold-color-hover`	`#E8C35C`	`$lh-gold-hover`
`--lh-gold-color-active`	`#B8860B`	`$lh-gold-active`
`--lh-gold-color-bg`	`#2A241A`	`$lh-gold-light`
`--lh-gold-color-border`	`#3A2E1A`	`$lh-gold-lighter`
`--lh-vermilion-color`	`#E85D4A`	`$lh-vermilion`
`--lh-vermilion-color-hover`	`#FF7B6B`	`$lh-vermilion-hover`
`--lh-vermilion-color-active`	`#C43A31`	`$lh-vermilion-active`
`--lh-vermilion-color-bg`	`#2A1A18`	`$lh-vermilion-light`
`--lh-jade-color`	`#7AAE7A`	`$lh-jade`
`--lh-jade-color-hover`	`#9CC89C`	`$lh-jade-hover`
`--lh-jade-color-active`	`#5B8C5A`	`$lh-jade-active`
`--lh-jade-color-bg`	`#1A2A1A`	`$lh-jade-light`
`--lh-decoration-color`	`rgba(212, 168, 67, 0.08)`	`$lh-decoration-color`

文本

令牌	暗色	SCSS 源
`--lh-text-primary`	`#E8E0D8`	`$lh-text-primary`
`--lh-text-regular`	`#C8C0B8`	`$lh-text-regular`
`--lh-text-secondary`	`#A09890`	`$lh-text-secondary`
`--lh-text-placeholder`	`#7A7270`	`$lh-text-placeholder`
`--lh-text-disabled`	`#5A5250`	`$lh-text-disabled`

边框

令牌	暗色	SCSS 源
`--lh-border-color-base`	`#3A3530`	`$lh-border-color-base`
`--lh-border-color-light`	`#302B28`	`$lh-border-color-light`
`--lh-border-color-lighter`	`#2A2520`	`$lh-border-color-lighter`
`--lh-border-color-extra-light`	`#242018`	`$lh-border-color-extra-light`

圆角

令牌	暗色	SCSS 源
`--lh-border-radius-base`	沿用明色	`$lh-border-radius-base`
`--lh-border-radius-small`	沿用明色	`$lh-border-radius-small`
`--lh-border-radius-round`	沿用明色	`$lh-border-radius-round`
`--lh-border-radius-circle`	沿用明色	`$lh-border-radius-circle`

背景

令牌	暗色	SCSS 源
`--lh-bg-color`	`#2A2520`	`$lh-bg-color`
`--lh-bg-color-page`	`#1E1A16`	`$lh-bg-color-page`
`--lh-bg-color-disabled`	`#242018`	`$lh-bg-color-disabled`
`--lh-bg-color-overlay`	`rgba(10, 8, 6, 0.7)`	`$lh-bg-color-overlay`

阴影

令牌	暗色	SCSS 源
`--lh-box-shadow-base`	`0 2px 12px 0 rgba(0, 0, 0, 0.5)`	`$lh-box-shadow-base`
`--lh-box-shadow-light`	`0 2px 4px 0 rgba(0, 0, 0, 0.4)`	`$lh-box-shadow-light`
`--lh-box-shadow-lighter`	`0 0 4px 0 rgba(0, 0, 0, 0.3)`	`$lh-box-shadow-lighter`

字体

令牌	暗色	SCSS 源
`--lh-font-family`	沿用明色	`$lh-font-family`
`--lh-font-size-extra-large`	沿用明色	`$lh-font-size-extra-large`
`--lh-font-size-large`	沿用明色	`$lh-font-size-large`
`--lh-font-size-medium`	沿用明色	`$lh-font-size-medium`
`--lh-font-size-base`	沿用明色	`$lh-font-size-base`
`--lh-font-size-small`	沿用明色	`$lh-font-size-small`
`--lh-font-size-extra-small`	沿用明色	`$lh-font-size-extra-small`
`--lh-font-weight-primary`	沿用明色	`$lh-font-weight-primary`
`--lh-font-weight-bold`	沿用明色	`$lh-font-weight-bold`
`--lh-font-line-height-primary`	沿用明色	`$lh-font-line-height-primary`

组件级 · control

令牌	暗色	SCSS 源
`--lh-control-height-mini`	沿用明色	`$lh-control-height-mini`
`--lh-control-height-small`	沿用明色	`$lh-control-height-small`
`--lh-control-height-medium`	沿用明色	`$lh-control-height-medium`
`--lh-control-height-large`	沿用明色	`$lh-control-height-large`
`--lh-control-height-x-large`	沿用明色	`$lh-control-height-x-large`

间距

令牌	暗色	SCSS 源
`--lh-spacing-xs`	沿用明色	`$lh-spacing-xs`
`--lh-spacing-sm`	沿用明色	`$lh-spacing-sm`
`--lh-spacing-md`	沿用明色	`$lh-spacing-md`
`--lh-spacing-base`	沿用明色	`$lh-spacing-base`
`--lh-spacing-lg`	沿用明色	`$lh-spacing-lg`
`--lh-spacing-xl`	沿用明色	`$lh-spacing-xl`
`--lh-spacing-xxl`	沿用明色	`$lh-spacing-xxl`

层级

令牌	暗色	SCSS 源
`--lh-z-index-normal`	沿用明色	`$lh-z-index-normal`
`--lh-z-index-dropdown`	沿用明色	`$lh-z-index-dropdown`
`--lh-z-index-sticky`	沿用明色	`$lh-z-index-sticky`
`--lh-z-index-fixed`	沿用明色	`$lh-z-index-fixed`
`--lh-z-index-modal-backdrop`	沿用明色	`$lh-z-index-modal-backdrop`
`--lh-z-index-modal`	沿用明色	`$lh-z-index-modal`
`--lh-z-index-popover`	沿用明色	`$lh-z-index-popover`
`--lh-z-index-tooltip`	沿用明色	`$lh-z-index-tooltip`

过渡

令牌	暗色	SCSS 源
`--lh-transition-duration-fast`	沿用明色	`$lh-transition-duration-fast`
`--lh-transition-duration-base`	沿用明色	`$lh-transition-duration-base`
`--lh-transition-duration-slow`	沿用明色	`$lh-transition-duration-slow`
`--lh-transition-function-ease-in-out`	沿用明色	`$lh-transition-function-ease-in-out`

禁用态

令牌	暗色	SCSS 源
`--lh-disabled-bg-color`	`#242018`	`$lh-disabled-bg-color`
`--lh-disabled-text-color`	`#5A5250`	`$lh-disabled-text-color`
`--lh-disabled-border-color`	`#302B28`	`$lh-disabled-border-color`
`--lh-disabled-opacity`	`0.5`	`$lh-disabled-opacity`

组件级 · popover

令牌	暗色	SCSS 源
`--lh-popover-bg-color`	`#2A2520`	`$lh-popover-bg-color`
`--lh-popover-border-color`	`#3A3530`	`$lh-popover-border-color`
`--lh-popover-border-radius`	沿用明色	`$lh-popover-border-radius`
`--lh-popover-padding`	沿用明色	`$lh-popover-padding`
`--lh-popover-title-color`	`#E8E0D8`	`$lh-popover-title-color`
`--lh-popover-content-color`	`#C8C0B8`	`$lh-popover-content-color`
`--lh-popover-arrow-size`	沿用明色	`$lh-popover-arrow-size`

组件级 · popconfirm

令牌	明色	暗色	SCSS 源	备注
`--lh-popconfirm-padding`		沿用明色	`$lh-popconfirm-padding`
`--lh-popconfirm-icon-size`		沿用明色	`$lh-popconfirm-icon-size`

组件级 · drawer

令牌	暗色	SCSS 源
`--lh-drawer-bg-color`	`#2A2520`	`$lh-drawer-bg-color`
`--lh-drawer-border-color`	`#3A3530`	`$lh-drawer-border-color`
`--lh-drawer-header-padding`	沿用明色	`$lh-drawer-header-padding`
`--lh-drawer-body-padding`	沿用明色	`$lh-drawer-body-padding`
`--lh-drawer-footer-padding`	沿用明色	`$lh-drawer-footer-padding`
`--lh-drawer-title-color`	`#E8E0D8`	`$lh-drawer-title-color`
`--lh-drawer-close-size`	沿用明色	`$lh-drawer-close-size`

组件级 · dropdown

令牌	暗色	SCSS 源
`--lh-dropdown-bg-color`	`#2A2520`	`$lh-dropdown-bg-color`
`--lh-dropdown-border-color`	`#3A3530`	`$lh-dropdown-border-color`
`--lh-dropdown-border-radius`	沿用明色	`$lh-dropdown-border-radius`
`--lh-dropdown-padding`	沿用明色	`$lh-dropdown-padding`
`--lh-dropdown-item-height`	沿用明色	`$lh-dropdown-item-height`
`--lh-dropdown-item-padding`	沿用明色	`$lh-dropdown-item-padding`
`--lh-dropdown-item-color`	`#C8C0B8`	`$lh-dropdown-item-color`
`--lh-dropdown-item-hover-bg-color`	`var(--lh-hover-bg-color)`	`$lh-dropdown-item-hover-bg-color`
`--lh-dropdown-divider-color`	`#302B28`	`$lh-dropdown-divider-color`

组件级 · message

令牌	暗色	SCSS 源
`--lh-message-bg`	`#2A2520`	`$lh-message-bg-color`
`--lh-message-border`	`#3A3530`	`$lh-message-border-color`
`--lh-message-color`	`#C8C0B8`	`$lh-message-content-color`
`--lh-message-shadow`	沿用明色	`$lh-message-shadow`

组件级 · notification

令牌	暗色	SCSS 源
`--lh-notification-bg`	`#2A2520`	`$lh-notification-bg-color`
`--lh-notification-border`	`#3A3530`	`$lh-notification-border-color`
`--lh-notification-title-color`	`#E8E0D8`	`$lh-notification-title-color`
`--lh-notification-content-color`	`#C8C0B8`	`$lh-notification-content-color`
`--lh-notification-width`	沿用明色	`$lh-notification-width`
`--lh-notification-gap`	沿用明色	`$lh-notification-gap`
`--lh-notification-shadow`	沿用明色	`$lh-notification-shadow`

组件级 · loading

令牌	明色	暗色	SCSS 源	备注
`--lh-loading-bg`		`rgba(10, 8, 6, 62%)`	`$lh-loading-bg-color`
`--lh-loading-text-color`		`#C8C0B8`	`$lh-loading-text-color`

组件级 · timeline

令牌	暗色	SCSS 源
`--lh-timeline-line`	`#302B28`	`$lh-timeline-line`
`--lh-timeline-dot`	`var(--lh-info-color)`	`$lh-timeline-dot`
`--lh-timeline-timestamp`	`var(--lh-text-secondary)`	`$lh-timeline-timestamp`

组件级 · collapse

令牌	明色	暗色	SCSS 源	备注
`--lh-collapse-border`		`#302B28`	`$lh-collapse-border`

组件级 · rate

令牌	明色	暗色	SCSS 源	备注
`--lh-rate-active`		`var(--lh-warning-color)`	`$lh-rate-active`

组件级 · segmented

令牌	明色	暗色	SCSS 源	备注
`--lh-segmented-bg`		`#242018`	`$lh-segmented-bg`

组件级 · calendar

令牌	明色	暗色	SCSS 源	备注
`--lh-calendar-border`		`var(--lh-border-color-lighter)`	`$lh-calendar-border`

组件级 · affix

令牌	明色	暗色	SCSS 源	备注
`--lh-affix-z-index`		沿用明色	`$lh-affix-z-index`

组件级 · backtop

令牌	明色	暗色	SCSS 源	备注
`--lh-backtop-z-index`		沿用明色	`$lh-backtop-z-index`

组件级 · menu

令牌	暗色	SCSS 源
`--lh-menu-bg`	`#242018`	`$lh-menu-bg`
`--lh-menu-padding`	沿用明色	`$lh-menu-padding`
`--lh-menu-border`	`#302B28`	`$lh-menu-border`
`--lh-menu-height`	沿用明色	`$lh-menu-height`
`--lh-menu-collapse-width`	沿用明色	`$lh-menu-collapse-width`
`--lh-menu-item-height`	沿用明色	`$lh-menu-item-height`
`--lh-menu-item-padding`	沿用明色	`$lh-menu-item-padding`
`--lh-menu-item-color`	`var(--lh-text-primary)`	`$lh-menu-item-color`
`--lh-menu-item-hover-bg`	`#302B28`	`$lh-menu-item-hover-bg`
`--lh-menu-item-active-color`	`var(--lh-selected-color)`	`$lh-menu-item-active-color`
`--lh-menu-item-active-bg`	`var(--lh-primary-color-bg)`	`$lh-menu-item-active-bg`
`--lh-menu-arrow-color`	`var(--lh-text-secondary)`	`$lh-menu-arrow-color`
`--lh-menu-z-index`	沿用明色	`$lh-menu-z-index`

组件级 · table

令牌	暗色	SCSS 源
`--lh-table-bg`	`#242018`	`$lh-table-bg`
`--lh-table-color`	`var(--lh-text-regular)`	`$lh-table-color`
`--lh-table-header-bg`	`#2A2420`	`$lh-table-header-bg`
`--lh-table-header-color`	`var(--lh-text-primary)`	`$lh-table-header-color`
`--lh-table-border`	`#302B28`	`$lh-table-border`
`--lh-table-row-hover-bg`	`#2A2420`	`$lh-table-row-hover-bg`
`--lh-table-stripe-bg`	`color-mix(in srgb, var(--lh-bg-color-page) 60%, transparent)`	`$lh-table-stripe-bg`
`--lh-table-cell-padding`	沿用明色	`$lh-table-cell-padding`

组件级 · layout

令牌	暗色	SCSS 源
`--lh-layout-header-height`	沿用明色	`$lh-layout-header-height`
`--lh-layout-header-bg`	`#242018`	`$lh-layout-header-bg`
`--lh-layout-aside-width`	沿用明色	`$lh-layout-aside-width`
`--lh-layout-aside-bg`	`#242018`	`$lh-layout-aside-bg`
`--lh-layout-main-bg`	`#1C1815`	`$lh-layout-main-bg`
`--lh-layout-border`	`#302B28`	`$lh-layout-border`

组件级 · row

令牌	明色	暗色	SCSS 源	备注
`--lh-row-gutter`		沿用明色	`$lh-row-gutter`

组件级 · tree

令牌	暗色	SCSS 源
`--lh-tree-color`	`#D8D0C8`	`$lh-tree-color`
`--lh-tree-padding`	沿用明色	`$lh-tree-padding`
`--lh-tree-node-height`	沿用明色	`$lh-tree-node-height`
`--lh-tree-node-hover-bg`	`#2A2420`	`$lh-tree-node-hover-bg`
`--lh-tree-node-selected-color`	`var(--lh-selected-color)`	`$lh-tree-node-selected-color`
`--lh-tree-node-selected-bg`	`var(--lh-primary-color-bg)`	`$lh-tree-node-selected-bg`
`--lh-tree-arrow-color`	`var(--lh-text-secondary)`	`$lh-tree-arrow-color`

组件级 · transfer

令牌	暗色	SCSS 源
`--lh-transfer-panel-width`	沿用明色	`$lh-transfer-panel-width`
`--lh-transfer-panel-height`	沿用明色	`$lh-transfer-panel-height`
`--lh-transfer-bg`	`#242018`	`$lh-transfer-bg`
`--lh-transfer-border`	`#302B28`	`$lh-transfer-border`

组件级 · upload

令牌	暗色	SCSS 源
`--lh-upload-bg`	`#242018`	`$lh-upload-bg`
`--lh-upload-border`	`var(--lh-border-color-base)`	`$lh-upload-border`
`--lh-upload-trigger-padding`	沿用明色	`$lh-upload-trigger-padding`

组件级 · anchor

令牌	明色	暗色	SCSS 源	备注
`--lh-anchor-color`		`var(--lh-text-regular)`	`$lh-anchor-color`

组件级 · image

令牌	明色	暗色	SCSS 源	备注
`--lh-image-viewer-mask`		`rgba(0, 0, 0, 80%)`	—

无障碍焦点环

令牌	暗色	SCSS 源
`--lh-focus-color`	`#7FA6D9`	`$lh-primary`
`--lh-focus-ring-width`	沿用明色	—
`--lh-focus-ring-offset`	沿用明色	—

(Les données des jetons sont générées par scripts/gen-docs-data.mjs en analysant var.scss / var-dark.scss / variables.scss, avec des assertions de quantité.)

Points d’attention

Les styles ne se modifient que dans ce dépôt : aucune bibliothèque UI ne doit conserver de copie des scss des composants. Les différences de classes de transition entre plateformes sont fédérées par le transition mixin.
Les couleurs sont toujours en var(--lh-*, fallback), pas de nouvelle valeur codée en dur (la vérification var fallback de verify:styles veille).
Tout nouveau composant doit avoir son styles/<name>/index.scss, sans quoi il n’aura pas d’artefact de styles sur une plateforme (le script de build l’ignore silencieusement, sans erreur).
L’exhaustivité du mode sombre est une exigence impérative : tous les composants prennent en charge le clair et le sombre par défaut ; les lacunes sombres sont interceptées par la vérification 7 de verify:styles.