CSS - web-foundation

Paquete: @tiendana/web-foundation

Sistema de diseño SCSS independiente de plataforma con tokens, colores, estilos base, utilidades y componentes.

Características

✅ SCSS moderno con módulos @use/@forward
✅ Variables CSS (custom properties) exportadas en :root
✅ Modo oscuro con la clase scheme-dark en <body>
✅ Superficies con elevación - Tokens --bg-0dp a --bg-3dp
✅ Independiente de plataforma - Funciona con Angular, React, Vue o HTML puro
✅ Metodología BEM - Nomenclatura consistente de clases
✅ Mixins SCSS - Breakpoints, unidades, URLs de assets y bordes
✅ Animaciones y scrollbars - Keyframes con clases animate-* y scrollbars configurables

Instalación

npm install @tiendana/web-foundation

El paquete se publica en CodeArtifact: autentica npm con tdn auth npm antes de instalar. Ver Configuración de CodeArtifact.

Uso

Todo el CSS desde SCSS (Recomendado)

/styles emite variables, estilos base, componentes y utilidades:

// styles.scss
@use '@tiendana/web-foundation/styles';

CSS compilado

Con un bundler que resuelva el exports del paquete, importa el subpath css para obtener el CSS ya compilado, sin pasar por Sass:

@import '@tiendana/web-foundation/css';

.my-button {
  background-color: var(--color-forrest);
  color: var(--color-white);
  padding: var(--spacing-sm) var(--spacing-md);
  border-radius: var(--border-radius-md);
}

Tokens y mixins en SCSS

La raíz del paquete no emite CSS: solo expone tokens, colores, mixins y funciones.

@use '@tiendana/web-foundation' as tdn;

.my-component {
  background: tdn.$color-forrest;
  padding: tdn.$spacing-md;

  @include tdn.respond-to(md) {
    padding: tdn.$spacing-lg;
  }
}

Módulos específicos

@use '@tiendana/web-foundation/tokens/spacing' as spacing;
@use '@tiendana/web-foundation/colors/primary' as primary;
@use '@tiendana/web-foundation/base/scrollbars';
@use '@tiendana/web-foundation/components/buttons';
@use '@tiendana/web-foundation/utilities/animations';

El mapa completo de rutas (/tokens/*, /colors/*, /base/*, /components/*, /utilities/*) está en Mixins y Funciones.

Modo oscuro

Activa el modo oscuro añadiendo la clase scheme-dark al <body>:

<body class="scheme-dark">
  <button class="bttn bttn--primary">Botón</button>
</body>

No hay detección automática de prefers-color-scheme: la clase se gestiona desde la aplicación. Con scheme-dark el CSS redefine la escala de grises, --color-light-forrest, --color-dark-forrest, --color-text-primary, las superficies --bg-0dp a --bg-3dp, --input-border, --border y --ds-shadow-border. Los colores de marca (natura, forrest, sun...) no cambian.

Variables CSS vs tokens SCSS

Concepto	Variable CSS	Token SCSS
Ejemplo	var(--spacing-md)	tdn.$spacing-md
Cuándo	Estilos de componentes y aplicaciones	Mixins, mapas y cálculos en compilación
Cambia con el tema	Sí (scheme-dark)	No

Recomendación

Usa variables CSS (var(--*)) en tu código. Los tokens SCSS son para cálculos y mixins. Algunos tokens solo existen en SCSS ($shadow-xs, $shadow-inner, $border-radius-none, $spacing-base).

Configuración avanzada

Las variables con !default se configuran al cargar el módulo:

@use '@tiendana/web-foundation' as tdn with (
  $browser-context: 16px,
  $cdn-domain: 'cdn.mysite.com',
  $s3-bucket: 'my-bucket',
  $cloudfront-id: 'my-distribution'
);

Variables configurables

• $browser-context - Contexto en píxeles para rem() y em() (por defecto 14px)
• $cdn-domain - Dominio del CDN (por defecto d320eox725dcq1.cloudfront.net)
• $cloudfront-id - ID de la distribución de CloudFront
• $s3-bucket y $s3-region - Bucket y región de S3 (región por defecto us-east-1)
• $bg-0dp a $bg-3dp, sus variantes -dark y $input-border-dark - Superficies y borde de inputs en modo oscuro. $input-border no cambia el modo claro porque los estilos de formulario redefinen --input-border: #c3c3c3; usa $input-border-dark o sobrescribe --input-border en CSS. Los $bg-* solo llegan al CSS emitido si /styles se carga después del @use configurado, en la misma compilación.

Los breakpoints no se pueden configurar. Detalle en Mixins y Funciones.

Estilos base

/base/* agrupa fuentes, reset, tipografía de elementos, layout y scrollbars:

• fonts - @font-face de Host Grotesk y Material Symbols Rounded desde el CDN, y la clase .material-symbols-rounded
• reset - Reset moderno (box-sizing, formularios, enlaces, foco)
• typography - body, h1 a h6, p, a, code, pre y blockquote
• layout - .flex y .grid con sus modificadores --*, y los modificadores de hijos .flex-item--* y .grid-item--*
• scrollbars - Scrollbars configurables (ver abajo)

Movimiento reducido

El reset respeta prefers-reduced-motion: reduce: reduce a 0.01ms la duración de todas las animaciones y transiciones, incluidas las clases animate-*, y desactiva el scroll suave.

Scrollbars

Los scrollbars usan los pseudoelementos ::-webkit-scrollbar (Chrome, Edge y Safari), por lo que Firefox muestra su scrollbar nativo. Se personalizan con variables CSS sobre :root o sobre cualquier contenedor:

Variable	Valor por defecto
--sb-size	var(--spacing-sm)
--sb-track-color	transparent
--sb-track-border-radius	var(--border-radius-2xl)
--sb-track-border-color	#000
--sb-track-border-width	0
--sb-thumb-color	#555555
--sb-thumb-border-radius	var(--border-radius-2xl)
--sb-thumb-border-color	#000
--sb-thumb-border-width	0

.table-wrapper {
  --sb-size: var(--spacing-xs);
  --sb-thumb-color: var(--color-gray-400);
  overflow: auto;
}

Las clases animate-* y los keyframes están en Utilidades CSS.

Arquitectura

• tokens/ - Tokens de diseño atómicos (espaciado, tipografía, sombras, bordes, z-index)
• mixins/ - Funciones y mixins SCSS
• colors/ - Paletas de colores con variantes de modo oscuro
• base/ - Estilos base (fuentes, reset, tipografía, layout, scrollbars)
• components/ - Componentes UI (botones, formularios, tablas, etc.)
• utilities/ - Clases de utilidad (espaciado, texto, display, fondos, bordes, sombras, animaciones)

Ver También

• Foundations - Colors - Paleta de colores completa
• Foundations - Typography - Sistema tipográfico
• Foundations - Spacing - Tokens de espaciado
• Foundations - Logomark - El símbolo de Tiendana y sus colourways
• Utilities Overview - Clases de utilidad
• Mixins Overview - Funciones SCSS

Ejemplo Rápido

<!DOCTYPE html>
<html lang="es">
<head>
  <!-- Resultado de compilar @use '@tiendana/web-foundation/styles' -->
  <link rel="stylesheet" href="/css/web-foundation.css">
</head>
<body>
  <button class="bttn bttn--primary">Botón Primario</button>
  <button class="bttn bttn--secondary">Botón Secundario</button>
</body>
</html>