Instalación en CSS/HTML

Aprende cómo instalar y usar el Sistema de Diseño de Tiendana con HTML/CSS/JavaScript puro.

Requisitos Previos

• Node.js 20.x o superior y acceso a CodeArtifact (no hay CDN pública)
• Conocimientos básicos de HTML/CSS

Instalación

Autenticación Requerida

Los paquetes @tiendana están alojados en AWS CodeArtifact privado. No están disponibles en npmjs.com ni en CDNs públicas como unpkg.com o jsdelivr.com. Autentica npm con Tiendana CLI (tdn auth npm) antes de instalar.

📖 Guía completa: Configuración de CodeArtifact

1. Autenticarse con CodeArtifact

tdn auth npm

O en la app de la barra de menú: Tiendana CLI → Registries → npm → Refresh. El proyecto necesita además el .npmrc que dirige el scope @tiendana a CodeArtifact; ver Configurar el Proyecto.

2. Instalar vía npm

Una vez autenticado, instala los paquetes:

npm install @tiendana/web-foundation @tiendana/utils

Esta documentación se escribió contra @tiendana/web-foundation ^0.5.5 y @tiendana/utils ^0.5.0. En versiones 0.x el rango ^ no cruza de minor, así que actualiza ambos cuando salga un minor nuevo.

3. Elegir el Punto de Entrada

El paquete publicado es plano: el CSS compilado vive en la raíz del paquete (no hay carpeta dist/), junto a src/ con el SCSS de origen. Importa siempre por el subpath exportado y no por la ruta del archivo, que es un detalle de empaquetado:

Entrada	Qué es	Uso
@tiendana/web-foundation/css	CSS compilado completo (index.css)	import en un bundler
@tiendana/web-foundation/styles	SCSS completo (src/index.scss)	@use para compilar la hoja con tu propio Sass
@tiendana/web-foundation	Solo tokens, colores, funciones y mixins SCSS (no emite CSS)	@use ... as tdn
@tiendana/web-foundation/tokens/*, colors/*, base/*, components/*, utilities/*	Un parcial SCSS concreto	@use para tree-shaking manual

No existe una entrada mixins/*: los mixins y funciones llegan por la entrada raíz (tdn.respond-to(md), tdn.cdn-url(...)).

Con un bundler (Vite, Webpack, Parcel), importa el CSS compilado:

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

O compila el SCSS completo en tu hoja de estilos:

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

Para usarlo en un HTML sin bundler, enlaza el archivo publicado en la raíz del paquete:

<link rel="stylesheet" href="node_modules/@tiendana/web-foundation/index.css">

También se publica index.min.css, la versión minificada.

CDN No Disponible

Los paquetes @tiendana NO están disponibles en CDNs públicas como unpkg.com o jsdelivr.com. Debes instalarlos vía npm con autenticación a CodeArtifact.

La hoja de estilos sí descarga sus fuentes (Host Grotesk y Material Symbols Rounded) desde d320eox725dcq1.cloudfront.net. Esa es la CDN de assets de Tiendana, no un registro de paquetes: tu página necesita salida a internet para tener la tipografía y los íconos.

La hoja reinicia todo el documento

index.css incluye un reset global (márgenes, paddings y listas sin viñetas). Si lo añades a una página existente, revisa el aspecto de tu contenido.

Uso Básico

Estructura HTML

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Sistema de Diseño Tiendana</title>
  
  <!-- Incluir CSS de Web Foundation -->
  <link rel="stylesheet" href="node_modules/@tiendana/web-foundation/index.css">
</head>
<body>
  <div class="container">
    <h1>Bienvenido a Tiendana</h1>
    
    <!-- Usar clases del sistema de diseño -->
    <button class="bttn bttn--primary">
      Haz clic
    </button>
    
    <button class="bttn bttn--secondary bttn--small">
      Botón pequeño
    </button>
    
    <button class="bttn bttn--outlined bttn--lavender">
      Botón outlined
    </button>
  </div>
</body>
</html>

Usando SCSS

Para usar los tokens, mixins y funciones en tu propio SCSS, impórtalos con un namespace. Esta entrada no emite CSS: carga la hoja completa con @use '@tiendana/web-foundation/styles' o con el CSS compilado.

// Importar tokens, colores, funciones y mixins (no emite CSS)
@use '@tiendana/web-foundation' as tdn;

// Usar tokens, mixins y funciones
.my-component {
  color: tdn.$color-natura;
  padding: tdn.$spacing-md;

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

Usando Utilidades JavaScript

Importa utilidades como módulos ES:

import {
  deepMerge,
  Patterns,
  downloadFile,
  copyTextToClipboard
} from '@tiendana/utils';

// Validar email
if (Patterns.EMAIL.test('usuario@ejemplo.com')) {
  console.log('¡Email válido!');
}

// Combinar objetos
const config = deepMerge(defaultConfig, userConfig);

// Copiar al portapapeles (muestra el snackbar "Copiado al portapapeles")
await copyTextToClipboard('Texto a copiar');

// Descargar un archivo a partir de una URL; el segundo argumento es el nombre
const blob = new Blob([JSON.stringify(data)], { type: 'application/json' });
const url = URL.createObjectURL(blob);
downloadFile(url, 'datos.json');
setTimeout(() => URL.revokeObjectURL(url), 100);

@tiendana/utils declara sideEffects: false, así que el bundler descarta lo que no uses, y solo se pueden importar @tiendana/utils y @tiendana/utils/logomark desde TypeScript, y @tiendana/utils/logomark/colourways desde SCSS (@use). El logomark de Tiendana (<tdn-logomark>) se importa desde @tiendana/utils/logomark, no desde el barrel raíz.

Referencia de Clases CSS

Todos los componentes siguen la convención de nombres BEM:

Botones:

• .bttn - Clase base del botón
• .bttn--primary - Variante primaria (Natura verde)
• .bttn--secondary - Variante secundaria (Forrest)
• .bttn--lavender - Variante lavanda
• .bttn--sky - Variante sky (celeste)
• .bttn--sun - Variante sun (naranja)
• .bttn--green-neon - Variante verde neón
• .bttn--error - Variante error (rojo)
• .bttn--outlined - Estilo outlined (borde)
• .bttn--small - Tamaño pequeño (26px)
• .bttn--icon - Botón de solo ícono
• .bttn--column - Layout en columna
• .bttn--disabled - Estado deshabilitado
• .bttn--active - Estado activo

Ver la sección Componentes para ejemplos completos de botones.

Variables CSS (Tokens)

Web Foundation expone propiedades personalizadas CSS para tematización:

:root {
  --color-natura: #00D47E;
  --color-forrest: #1B434C;
  --spacing-md: 16px;
  --border-radius-md: 4px;
  --border-radius-button: 14px;
  --font-size-base: 14px;
  /* ... más tokens */
}

/* Usar en tus estilos personalizados */
.mi-elemento-personalizado {
  background-color: var(--color-natura);
  padding: var(--spacing-md);
  border-radius: var(--border-radius-md);
}

Modo Oscuro

Web Foundation soporta modo oscuro a través de la clase .scheme-dark:

<!-- Modo claro (por defecto) -->
<body>
  <!-- contenido -->
</body>

<!-- Modo oscuro -->
<body class="scheme-dark">
  <!-- contenido -->
</body>

Alterna el modo oscuro con JavaScript:

// Alternar modo oscuro
document.body.classList.toggle('scheme-dark');

// Establecer según la preferencia del usuario
if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
  document.body.classList.add('scheme-dark');
}

Próximos Pasos

• Explora Fundamentos para entender los tokens, colores y tipografía
• Navega por Componentes para ver los componentes CSS disponibles
• Consulta las Utilidades CSS para clases de utilidad
• Aprende sobre los Mixins SCSS para personalización avanzada
• Añade el logomark de Tiendana a tu página

Herramientas de Construcción

Web Foundation funciona con cualquier herramienta de construcción moderna. Recomendamos Vite por su velocidad y simplicidad:

Vite (Recomendado)

npm create vite@latest my-app
cd my-app
npm install
npm install @tiendana/web-foundation @tiendana/utils

Vite soporta SCSS de forma nativa. Solo instala el preprocesador:

npm install -D sass

Luego importa la hoja completa (y, si usas tokens o mixins, la entrada raíz con namespace) en tu archivo principal:

// src/styles/main.scss
@use '@tiendana/web-foundation/styles';
@use '@tiendana/web-foundation' as tdn;

Otras herramientas compatibles

• Webpack: Usa sass-loader para compilar SCSS
• Parcel: Detecta y compila SCSS automáticamente
• PostCSS: Agrega autoprefixer para compatibilidad con navegadores