Convenciones de nomenclatura que escalan
El patrón $category-property-modifier es el estándar de facto en sistemas de diseño maduros. $color-primary-500 es superior a $blue porque comunica tres cosas: tipo (color), rol (primario) y variación (nivel 500 en la escala tonal).
Error frecuente: valores hardcodeados sin semántica. $spacing-24px es peor que $spacing-lg porque el primero queda obsoleto si decidís cambiar el valor a 28px. El segundo mantiene la intención ('espaciado grande') independiente de la implementación.
Para colores, adoptá escalas numéricas (50-900) en lugar de nombres subjetivos (light/lighter/lightest). Material Design y Tailwind popularizaron este approach porque permite interpolación visual clara: $color-gray-400 está necesariamente entre 300 y 500. Reservá nombres descriptivos para casos excepcionales: $color-brand-primary está bien porque ese color tiene significado de negocio específico.
Organizar variables por capas de abstracción
Estructura en tres niveles: primitivas, semánticas y componentes. Primitivas son valores brutos: $blue-500: #3b82f6;. Semánticas mapean uso: $color-primary: $blue-500;. Componentes aplican contexto: $button-bg-primary: $color-primary;.
Esto permite cambios globales sin tocar componentes. Si el diseño requiere que el primario pase de azul a verde, modificás una línea ($color-primary: $green-500;) en lugar de buscar/reemplazar en 50 archivos. Los componentes siguen usando $button-bg-primary sin cambios.
Para tipografía, evitá variables sueltas tipo $font-size-button. Mejor: $button-text-size: $font-size-sm;. Esto mantiene el button ligado al sistema tipográfico global. Si después decidís que todos los tamaños 'sm' deben aumentar 1px, el botón escala automáticamente. Pensá en tokens de diseño como capas de indirección que reducen acoplamiento.
Patrones para responsive y theming
Breakpoints deben ser variables nombradas, no magic numbers: $breakpoint-md: 768px;. Así podés crear mixins reutilizables: @include respond-above($breakpoint-md) { ... }. Algunos equipos prefieren nombres contextuales ($breakpoint-tablet) sobre genéricos (md), pero los genéricos son más resilientes cuando las definiciones de 'tablet' cambian.
Para dark mode, no dupliques todo el palette. Mejor: definí variables semánticas que cambien según contexto. $color-surface-base puede ser #ffffff en light mode y #1a1a1a en dark. Los componentes usan $color-surface-base sin saber qué theme está activo. Implementalo con CSS custom properties si necesitás switching runtime: --color-surface: #{$color-surface-base};.
Evitá variables responsive inline tipo $padding-mobile y $padding-desktop. Preferí un solo $padding-component que cambie valor en media queries. Reduce la cantidad de variables y mantiene la lógica responsive encapsulada en el componente.
Integración con design tokens y handoff
Si trabajás con Figma/Sketch, tus variables SASS deben espejear los design tokens del archivo de diseño. Herramientas como Style Dictionary o Theo automatizan la conversión: diseño exporta tokens JSON, build genera SCSS. Esto elimina transcripción manual y errores de sincronización.
Formato recomendado para tokens: JSON con metadata. En lugar de {"blue-500": "#3b82f6"}, usá {"blue-500": { "value": "#3b82f6", "type": "color", "category": "primitive" }}. La metadata permite validaciones (verificar que solo colors se asignen a propiedades de color) y documentación auto-generada.
Para componentes complejos, documentá las variables en comentarios SCSS: /// @prop {length} $button-height-md - Altura por defecto de botones (40px). Herramientas como SassDoc parsean esto y generan sites de documentación. En equipos grandes, la documentación inline es la única que se mantiene actualizada; wikis externos quedan obsoletos en semanas.