Guía del Framework CSS — Design System Surco

Sistema de diseño basado en CSS puro (sin dependencias de frameworks externos como Tailwind, Bootstrap o Material). Reutilizable en cualquier plataforma web.

1. Archivos del Framework

ArchivoRol
design-system-surco.cssNúcleo de estilos: variables, reset, componentes, responsive
design-system-surco.jsLógica de interactividad (toasts, selects avanzados, firma digital)

2. Integración en un Nuevo Proyecto

Paso 1: Copiar los archivos

Copia design-system-surco.css y design-system-surco.js al directorio de assets de tu proyecto.

Paso 2: Vincular en HTML

<!-- En el head -->
<link rel="stylesheet" href="ruta/design-system-surco.css">

<!-- Al final del body -->
<script src="https://unpkg.com/lucide@latest/dist/umd/lucide.min.js"></script>
<script src="ruta/design-system-surco.js"></script>
<script>lucide.createIcons()</script>

Paso 3: Inicializar íconos

Los íconos usan Lucide. Después de cargar el script de Lucide, llama lucide.createIcons() para renderizar los íconos con data-lucide.

3. Tokens de Diseño (Variables CSS)

Todas las variables están definidas en :root al inicio de design-system-surco.css.

Espaciado

VariableValorEquivale a
--s14pxEspaciado mínimo
--s28pxPequeño
--s312pxMedio-pequeño
--s416pxMedio
--s520pxMedio-grande
--s624pxGrande
--s832pxExtra-grande
--s1040pxMáximo

Colores

VariableDescripción
--whBlanco
--g1 – --g9Escala de grises (1=oscuro, 9=claro)
--cpColor primario (verde Surco)
--cpdColor primario oscuro
--csColor secundario
--cdColor danger (rojo)
--cplColor primario claro (fondo hover)
--cslColor secundario claro

Tipografía

VariableDescripción
--fFamilia: 'Chivo', sans-serif
--tsm13px
--tb14px
--tmd16px
--txs11px

Bordes y Sombras

VariableDescripción
--rmd8px (radio medio)
--rlg12px (radio grande)
--rfl999px (radio completo)
--shsmSombra pequeña
--shmdSombra mediana

4. Clases de Componentes

Layout

ClaseDescripción
.navBarra de navegación superior (flex, 60px de alto)
.nav-logoLogo (icono + texto, flex-shrink:0)
.nav-searchContenedor de búsqueda (flex:1, max-width:460px)
.nav-linksLinks de navegación (visible en desktop, hidden en ≤900px)
.nav-toggleBotón hamburguesa (visible en ≤600px)
.mainContenido principal (min-width:0, padding responsivo)
.sidebarBarra lateral (hidden en ≤900px)
.layoutContenedor flex de sidebar + main

Cards

ClaseDescripción
.cardTarjeta con fondo blanco, borde y sombra
.ch2Cabecera de tarjeta (padding, border-bottom, flex)
.chtTítulo de cabecera de tarjeta
.cbCuerpo de tarjeta
.cfPie de tarjeta

Botones

ClaseDescripción
.btnBase de botón
.bpBotón primario (fondo var(--cp))
.boBotón outline
.bg2Botón secundario/ghost
.bmdBotón mediano
.bsmBotón pequeño
.wfwidth: 100%

Inputs y Formularios

ClaseDescripción
.inpInput estándar
.inp.errInput con error
.selSelect estilizado
.ilLabel de input
.igInput group

Badges y Estados

ClaseDescripción
.bdgBadge base
.bdg.dngBadge danger (rojo)
.bdg.dwnBadge warning (naranja)
.bdg.dokBadge success (verde)
.bdg.dntBadge neutral (gris)
.dotPunto indicador

Tabs

ClaseDescripción
.tabsContenedor de tabs (flex, overflow-x:auto)
.tabTab individual (flex-shrink:0)
.tab.actTab activo

Tooltips

ClaseDescripción
.ttp-wrapContenedor relativo (inline-flex)
.ttpTooltip (absoluto, fondo g9)
.ttp.ttp-rightTooltip a la derecha
.ttp.ttp-bottomTooltip abajo

Filter Bar

ClaseDescripción
.flt-barBarra de filtros (flex, flex-wrap)
.flt-searchCampo de búsqueda
.flt-groupGrupo label+select
.flt-selSelect de filtro
.flt-chipChip de filtro activo
.flt-resultsContador de resultados

Header App

ClaseDescripción
.hdr-wrapWrapper del header
.hdrHeader flex (64px, background var(--cp))
.hdr-brandMarca (icon + texto)
.hdr-navNavegación interna
.hdr-actionsAcciones (iconos, avatar)
.hdr-subSub-nav
.hdr-userUsuario (avatar + nombre + rol)

Dashboard

ClaseDescripción
.sc2Stat card (flex, min-width:190px)
.siStat icon (48x48, flex-center)
.svStat value
.slStat label

Tablas

ClaseDescripción
.twTable wrapper (overflow-x:auto, border)
tableTabla (width:100%, border-collapse)
thead thHeader de tabla
tbody trFila (hover)
tdCelda

Upload Zone

ClaseDescripción
.upld-zoneZona de drop (border dashed)
.upld-listLista de archivos
.upld-itemItem de archivo
.upld-item-infoInfo del archivo (flex:1)
.upld-item-nameNombre (ellipsis)
.upld-progressBarra de progreso

Signature Pad

ClaseDescripción
.sig-pad-wrapWrapper del canvas
.sig-canvasCanvas de firma
.sig-actionsActions bar

5. Utilidades de Layout

ClaseDescripción
.flexdisplay: flex
.fwflex-wrap: wrap
.g2, .g3, .g4Gap (8px, 12px, 16px)
.icalign-items: center
.isalign-items: flex-start
.wfwidth: 100%

6. Breakpoints Responsive

BreakpointAnchoComportamiento
> 900pxDesktopSidebar visible, nav-links visibles, búsqueda visible
≤ 900pxTabletSidebar oculto, nav-links ocultos, búsqueda visible
≤ 720pxTablet pequeñoDashboard cards a 100%, header wrap, tabs scroll
≤ 640pxMóvil grandeTipography rows apiladas verticalmente
≤ 600pxMóvilNav-toggle visible, búsqueda oculta, menú hamburguesa
≤ 420pxMóvil pequeñoLogo texto oculto (solo icono)

7. Personalización y Temas

Cambiar colores primarios

Sobrescribe las variables en tu CSS antes de importar el framework:

:root {
  --cp: #YOUR_PRIMARY_COLOR;
  --cpd: #DARKER_VARIANT;
  --cpl: #LIGHTER_VARIANT;
}

Cambiar espaciado

:root {
  --s4: 20px;
}

Tema oscuro

[data-theme="dark"] {
  --wh: #1a1a2e;
  --g1: #0f0f1a;
  --g9: #e0e0e0;
  --g5: #888;
}

8. Implementación por Plataforma

React / Next.js

// Copiar archivos
cp design-system-surco.css src/styles/
cp design-system-surco.js src/lib/

// En _app.js o layout.js
import 'styles/design-system-surco.css';
import 'lib/design-system-surco.js';

Vue / Nuxt

// nuxt.config.ts
export default defineNuxtConfig({
  css: ['~/assets/css/design-system-surco.css'],
  scripts: [
    { src: 'https://unpkg.com/lucide@latest/dist/umd/lucide.min.js', defer: true },
    { src: '~/assets/js/design-system-surco.js', defer: true }
  ]
})

Angular

// angular.json
"styles": ["src/styles/design-system-surco.css"],
"scripts": [
  "https://unpkg.com/lucide@latest/dist/umd/lucide.min.js",
  "src/assets/js/design-system-surco.js"
]

HTML Puro

<link rel="stylesheet" href="design-system-surco.css">
<script src="https://unpkg.com/lucide@latest/dist/umd/lucide.min.js"></script>
<script src="design-system-surco.js"></script>
<script>lucide.createIcons()</script>

9. Ejemplo Mínimo

<!DOCTYPE html>
<html lang="es">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <link rel="stylesheet" href="design-system-surco.css">
</head>
<body>
  <nav class="nav">
    <a href="#" class="nav-logo">Mi App</a>
  </nav>
  <main class="main">
    <div class="card">
      <div class="ch2"><span class="cht">Bienvenido</span></div>
      <div class="cb">
        <p>Contenido de la tarjeta.</p>
        <button class="btn bp bmd">Acción Principal</button>
      </div>
    </div>
  </main>
  <script src="https://unpkg.com/lucide@latest/dist/umd/lucide.min.js"></script>
  <script src="design-system-surco.js"></script>
  <script>lucide.createIcons()</script>
</body>
</html>

10. Notas de Mantenimiento

  • No editar design-system-surco.css directamente en proyectos derivados. Crea un archivo CSS de overrides.
  • Variables CSS: todas las variables están en :root, lo que permite sobrescribirlas fácilmente.
  • Lucide Icons: el framework depende de Lucide para íconos. Si no necesitas íconos, usa SVG inline directamente.
  • Responsive: los breakpoints están en el CSS. Para agregar nuevos, extiende los @media existentes.
  • Versionado: sigue versionado semántico (major.minor.patch).

© 2026 Centro de Operaciones C4 — Municipalidad de Santiago de Surco.