# Solar

> Sistema de diseño de la Cámara de Comercio de Santiago (CCS): componentes en HTML y Tailwind CSS, con tokens propios (ccs-*). Versión 0.8.0.

Cada componente tiene una versión en Markdown con su HTML exacto. Usa ese HTML tal cual.

Licencia: Solar es de uso público (código con licencia MIT, documentación con CC BY 4.0; detalle en https://utiliza.me/solar/LICENSE.md). La marca CCS es de uso restringido: su nombre y logos, los colores primarios y secundarios, y el nombre y logo de Solar. Si el proyecto no es de la CCS, cambia los valores de los colores de marca en ccs-tailwind-config.js (los nombres ccs-* pueden quedar), usa el logo del proyecto y no lo presentes como de la CCS.

Si trabajas en la carpeta de Solar (repositorio), lee los archivos locales de `public_html/solar/` (`components/*.md`, `assets/js/ccs-tailwind-config.js`) en vez de seguir los links: los links llevan a la versión publicada, que puede ir atrasada.

## Antes de empezar

Antes de nada, pregunta qué tipo de trabajo es, salvo que la persona ya lo haya dicho. Hazlo aunque el pedido parezca claro: una lista de campos no dice si es una idea para conversar o algo que se va a usar. Haz una sola pregunta, con estas opciones:

1. Una maqueta para conversar una idea: sigue la "Guía para armar una maqueta", más abajo en este archivo.
2. Algo nuevo que se va a usar de verdad: pregunta por el problema, el usuario y el objetivo, y propón qué componentes de Solar usarías antes de construir.
3. Mejorar algo que ya existe: pide una captura o el enlace, y qué no funciona bien.
4. Consultar o copiar un componente: responde directo.

Las reglas de la sección siguiente aplican cuando se construye con Solar. En una maqueta de baja fidelidad no aplican.

## Reglas

- Usa solo los componentes y los tokens de Solar (ccs-*, definidos en ccs-tailwind-config.js). No uses colores, tamaños ni espaciados fijos.
- Si Solar no tiene un componente, dilo. No lo inventes ni crees una variante parecida.
- Fondo blanco (#FFFFFF). Las superficies se separan con bordes del token ccs-line, no con rellenos de color. Avisos y mensajes van con el componente Alertas: fondo suave del estado, sin borde (un aviso fijo de la página lleva role="note"). Campos, selectores, casillas, radios, interruptores apagados y botones de contorno usan ccs-line-strong (en oscuro, ccs-dark-line-strong). El fondo en hover de botones neutros usa ccs-hover.
- Casillas y radios: copia el HTML de Formularios. Llevan la clase ccs-check (de ccs-ui-kit.css), que reemplaza la casilla del navegador; el color al marcar sale de text-ccs-blue (en oscuro, text-ccs-blue-mid).
- Tipografía: Inter para texto y JetBrains Mono para código. No uses otras. En producción se alojan en el proyecto, no se cargan desde Google Fonts.
- Tamaños de texto: títulos y párrafos de contenido con los estilos de Solar (text-ccs-h1-hero, text-ccs-h1, text-ccs-h2, text-ccs-h3, text-ccs-body-xl, text-ccs-body-l, text-ccs-body, text-ccs-caption; el H1 Hero va como text-ccs-h1-hero-sm lg:text-ccs-h1-hero; text-ccs-display es solo para el título de la portada), que ya traen tamaño, interlineado y peso: no les sumes font-* ni leading-*. Texto de interfaz (botones, campos, menús, tablas) con text-xs, text-sm o text-base de Tailwind. Nunca valores entre corchetes como text-[14px].
- Espacios y pesos con la escala de Tailwind (h-10, px-4, gap-2, font-medium). Solar crea un token solo si Tailwind no tiene el valor o si es una decisión de marca; criterio en https://utiliza.me/solar/documentacion/por-que-tailwind/.
- Botones: copia el HTML de Botones. Todos llevan foco con anillo (focus-visible:ring-2 ring-offset-2 ring-ccs-blue, en oscuro ring-ccs-dark-accent; sobre fondo de color, ring-white sin separación) y se achican al presionar (active:scale-95 motion-reduce:active:scale-100, con transition).
- Radios: rounded-ccs (15 px) en superficies y botones con texto; rounded-lg (8 px) en campos y piezas dentro de una superficie (ítems de menú, teclas, chips cuadrados, botón copiar); rounded-full en círculos y píldoras; rounded (4 px) solo en casillas ccs-check; rounded-none en muestras de color. No uses rounded-sm, rounded-md ni rounded-xl. Sombras: shadow-ccs o shadow-ccs-sm.
- Nada de gradientes genéricos: solo bg-ccs-banner y bg-ccs-icon.
- Accesibilidad: WCAG 2.2 nivel AA, salvo el contraste, que se mide con APCA-W3 0.1.9 (librería apca-w3), usando el valor Lc absoluto.
- Mínimos de contraste: Lc 75 texto de lectura (párrafos, descripciones, links dentro de un texto); 60 otros textos (botones, etiquetas, links sueltos); 45 texto grande (24px en negrita o 36px) e íconos de línea; 30 textos auxiliares (placeholder, deshabilitado, números en gráficos), íconos sólidos y bordes de campos; 15 líneas y divisores.
- Sobre un color, el texto va en blanco si alcanza el mínimo. Si no, usa el de mayor contraste o agranda el texto.
- Estados: usa los tokens de éxito, advertencia y error, nunca la paleta de Tailwind (rose, amber, green…). En claro: ccs-{estado} (texto), ccs-{estado}-fill y -fill-hover (relleno con texto blanco), ccs-{estado}-soft y -soft-hover (fondo suave) y ccs-{estado}-line (borde). Éxito y error tienen además ccs-{estado}-hover, el texto sobre -soft-hover. En oscuro: ccs-dark-{estado} (texto), ccs-dark-{estado}-fill y -fill-hover; fondo suave ccs-dark-{estado}-fill/10 (hover /20) y borde ccs-dark-{estado}/35. {estado} = success, warning o error.
- No cambies colores que APCA aprueba porque una herramienta de WCAG 2 (Lighthouse, axe) los marque como error de contraste.
- Modo oscuro: agrega variantes dark: con los tokens de la paleta oscura (las clases de cada color, en claro y en oscuro, están en https://utiliza.me/solar/componentes/color/). Se activa con la clase .dark en <html>.
- Íconos: Solar Icons (Iconify, prefijo solar:). Dos familias. De interfaz (junto a un texto, 12 a 24 px): Bold hasta 16 px; Bold u Outline desde 20 px, una sola por pantalla. De contenido (cards, banners, estados vacíos, 32 px o más): Bold duotone, Line duotone, Bold u Outline. Los duotone nunca junto a texto ni en tamaños chicos. No uses Linear ni Broken.
- Íconos: tamaños 12, 14, 16, 20, 24, 32 y 48 px, sin tamaños intermedios. Heredan el color del texto (currentColor). En claro y en oscuro va la misma variante y solo cambia el color, con el token y su dark: (sin blanco puro). Lc mínimo 45 en íconos de línea y 30 en sólidos.
- Íconos: decorativo con aria-hidden="true"; botón solo ícono con aria-label y área de 40 px o más, solo para acciones muy conocidas (buscar, cerrar, menú, editar); informativo con role="img" y aria-label. Éxito, advertencia y error siempre con texto, no solo color.
- Íconos: si Solar Icons no tiene el ícono, usa Phosphor (ph:), Hugeicons, MingCute o Myna UI, con trazo y esquinas parecidos y una variante rellena para tamaños chicos. No mezcles familias en un mismo conjunto. Solar Icons es CC BY 4.0 de 480 Design: pide atribución.
- Íconos en producción: aloja iconify-icon.min.js y solar-iconos.js de Solar (https://utiliza.me/solar/instalacion.html), en ese orden, solar-iconos.js primero. No pidas íconos a la API de Iconify.
- Comportamiento: Solar no entrega JavaScript. Usa HTML nativo (<dialog> abierto con commandfor y command="show-modal", form method="dialog", <details>). Si un componente necesita JS, su sección Comportamiento dice qué debe pasar (teclado, foco, anuncios); prográmalo en tu proyecto. No copies el JS del sitio de Solar.
- Textos en español de Chile, con tuteo y sin tecnicismos; primero qué pasó y luego qué hacer; botones con verbo y objeto; “correo”, no “email”. En textos largos (landings, descripciones, correos), sin muletillas de IA: nada de “no es X, es Y”, aperturas de relleno, palabras infladas (“potenciar”, “clave”, “de vanguardia”), grupos de tres por ritmo, preguntas retóricas, cierres solemnes ni cifras sin fuente; una cosa, un nombre. Detalle en https://utiliza.me/solar/documentacion/voz-y-tono/.
- Antes de construir algo nuevo, pregunta por el problema, el usuario y el objetivo, también cuando el pedido parece claro: una lista de campos no dice para quién es ni qué problema resuelve.

## Guía para armar una maqueta

Cuándo se usa: cuando la persona elige la opción 1 de "Antes de empezar", o pide una maqueta o un wireframe, aunque no mencione esta guía.

Qué es una maqueta aquí: un boceto de pantallas para conversar una idea con otras personas antes de diseñarla. No es un diseño final y no está validada con usuarios.

Esta guía no define cómo se ve la maqueta. Define los pasos previos y cómo entregarla. Las reglas de Solar de este archivo aplican solo si la persona decide armarla con Solar.

### Cómo conversar

- Habla simple. Di "maqueta", no "wireframe", salvo que la persona use esa palabra.
- Haz una pregunta a la vez, con un ejemplo de respuesta. Son ocho preguntas como máximo.
- Si la persona no sabe algo, anótalo como supuesto y sigue.
- Si pide saltarse las preguntas, hazlo, pero marca todo como supuesto.
- No construyas nada hasta que la persona confirme el resumen del paso 3.

### Paso 1. Qué tipo de trabajo es

Pregunta si la idea es algo nuevo o una mejora de algo que ya existe. Si no sabe, ayúdale a decidir.

### Paso 2. Entender la idea

Si es algo nuevo:

1. ¿Qué problema resuelve? Ejemplo: "Los socios no saben qué beneficios tienen".
2. ¿Para quién es?
3. ¿Cómo lo resuelven hoy, sin esto?
4. ¿Qué tiene que lograr la persona que lo use? ¿Es una sola cosa o varias?
5. ¿Desde dónde lo usaría: celular, computador o ambos?
6. De lo que me contaste, ¿qué sabes por datos, reclamos o conversaciones, y qué es intuición?
7. ¿Quién decide si esto sigue adelante?

Si es una mejora:

1. ¿Me compartes una captura o el enlace?
2. ¿Qué no funciona bien?
3. ¿Cómo lo sabes: reclamos, datos o intuición?
4. ¿Quién lo usa hoy?
5. ¿Qué no se puede cambiar?
6. ¿Quién decide si esto sigue adelante?

### Paso 3. Resumen y confirmación

Muestra un resumen corto con estas partes:

- La idea en una frase.
- Para quién es.
- Qué tiene que lograr.
- Lo que se sabe, con su fuente.
- Los supuestos, marcados como tales.
- Las preguntas que quedan abiertas.

Pregunta si está bien y corrige lo que la persona indique. Recién entonces armas la maqueta.

### Paso 4. Armar la maqueta

Recomienda baja fidelidad: grises y cajas, sin logos, colores de marca ni fotos. Explica el porqué en una frase: una maqueta que parece terminada recibe comentarios sobre colores y no sobre la idea. Si la persona quiere usar diseño, respétalo: arma con Solar y sigue sus reglas (resto de este archivo).

En baja fidelidad:

- Usa textos reales y cortos, no "lorem ipsum". Los textos también son parte de la idea.
- Muestra el recorrido principal de principio a fin. Las pantallas secundarias pueden quedar como una caja con su nombre.
- Marca en la misma pantalla lo que es supuesto (por ejemplo, con una nota al costado).
- Si la persona quiere un estilo dibujado a mano, puedes usar una librería como PaperCSS, incrustada en el archivo. No es obligatorio.

### Paso 5. Entrega

- Un solo archivo .html descargable, aunque la persona no lo pida. Si tu herramienta publica la maqueta como página o artefacto, ofrece además el archivo.
- Todo dentro del archivo: CSS y JavaScript incluidos, sin CDN ni archivos externos, con las fuentes del sistema y sin fotos (o incrustadas). Tiene que verse igual sin internet.
- Al inicio del archivo, un bloque con el resumen confirmado, los supuestos y este aviso: "Esta maqueta sirve para conversar la idea. No está validada con usuarios: los supuestos son lo primero que hay que revisar."
- Nombre: maqueta-[idea]-[AAAA-MM-DD].html.
- Explícale cómo compartirla: mejor un enlace. Si va por email, adjunta el .html suelto, sin comprimirlo en un .zip, y avisa a quien lo recibe que tiene que descargarlo y abrirlo en el navegador de un computador.
- Siguiente paso: llevar la maqueta y el resumen a quien vaya a diseñarla.

## Instalación

- [Instalación](https://utiliza.me/solar/instalacion.html): cómo cargar Tailwind, las fuentes y el CSS de Solar.
- [Tokens](https://utiliza.me/solar/assets/js/ccs-tailwind-config.js): colores, sombras, radios y tipografía.
- Tailwind por CDN es solo para prototipos. Para producción, usa un build precompilado de Tailwind y aloja en el proyecto las tipografías y los íconos.

## Componentes: Base

- [Color](https://utiliza.me/solar/components/color.md): Clases de color por función, en claro y en oscuro.
- [Textos y tipografías](https://utiliza.me/solar/components/textos-y-tipografias.md): Escala tipográfica Inter, JetBrains Mono para datos técnicos y espacio entre párrafos y listas.
- [Iconografía](https://utiliza.me/solar/components/iconografia.md): Cuándo y cómo usar Solar Icons: familias, tamaños, color, accesibilidad y catálogo.
- [Forma y sombra](https://utiliza.me/solar/components/forma-y-sombra.md): Radios y sombras institucionales.

## Componentes: Acción

- [Botones](https://utiliza.me/solar/components/botones.md): Primarios, secundarios, acentos, tamaños, solo ícono, estados, soft, link, block y con ceja.
- [Tags & Badges](https://utiliza.me/solar/components/tags-y-badges.md): Etiquetas para categorizar contenido, estados y filtros: sólidas, suaves, con contorno, punteadas, con ícono, vacías y dentro de textos y botones.
- [Menú desplegable](https://utiliza.me/solar/components/menu-desplegable.md): Acciones y opciones que se abren desde un botón: íconos, atajos, casillas, opción única, submenú y menú de usuario.
- [Toggle](https://utiliza.me/solar/components/toggle.md): Botón que queda presionado, solo o en grupo: sin borde, con contorno, tamaños, vertical y con texto.
- [Tecla](https://utiliza.me/solar/components/tecla.md): Teclas y combinaciones del teclado para atajos en menús, tooltips, campos y textos.

## Componentes: Navegación

- [Barra de navegación](https://utiliza.me/solar/components/barra-de-navegacion.md): Menú principal y subnav.
- [Breadcrumb](https://utiliza.me/solar/components/breadcrumb.md): Ruta jerárquica de navegación.
- [Tabs](https://utiliza.me/solar/components/tabs.md): Pestañas estándar, pill, con íconos, verticales y deshabilitada.
- [Paginación](https://utiliza.me/solar/components/paginacion.md): Navegación entre páginas de resultados.
- [Sidebar](https://utiliza.me/solar/components/sidebar.md): Navegación lateral para apps, portales y dashboards.
- [Buscador](https://utiliza.me/solar/components/buscador.md): Búsqueda del sitio: campo en el header, búsqueda que se despliega, buscador destacado y de una sección, sugerencias y página de resultados.
- [Paleta de comandos](https://utiliza.me/solar/components/paleta-de-comandos.md): Buscador de acciones y páginas que se abre con Ctrl K: grupos, sin resultados y en diálogo.

## Componentes: Contenido

- [Cards](https://utiliza.me/solar/components/cards.md): Suaves (las de uso general) o con línea: categoría, enlace, noticias y eventos, cifras, testimonio y perfil.
- [Listas](https://utiliza.me/solar/components/listas.md): Bulleted, numeradas, con check y de definición.
- [Tablas](https://utiliza.me/solar/components/tablas.md): Tablas para mostrar contenido: básica, sin marco, filas alternas, fila destacada, comparación, compacta, con totales, encabezado fijo y apilada en el celular.
- [Hero](https://utiliza.me/solar/components/hero.md): Parte de arriba de una página: encabezado de página, editorial, foto a sangre, dividido y de landing, con captura y página de ejemplo.
- [Banners](https://utiliza.me/solar/components/banners.md): Campañas, inscripciones y comunicaciones.
- [Avatar](https://utiliza.me/solar/components/avatar.md): Foto o iniciales de una persona: tamaños, indicador de estado, grupos y con nombre.
- [Ítem](https://utiliza.me/solar/components/item.md): Fila con medio, título, descripción y acciones: variantes, tamaños, grupo, como enlace y con menú.
- [Estado vacío](https://utiliza.me/solar/components/estado-vacio.md): Qué mostrar cuando no hay datos: básico, contorno, con fondo, sin resultados, con avatares y página no encontrada.
- [Separador](https://utiliza.me/solar/components/separador.md): Línea horizontal o vertical entre grupos de contenido, también con texto o fecha.
- [Tabla de datos](https://utiliza.me/solar/components/tabla-de-datos.md): Tabla con filtro, orden por columna, selección de filas, menú de columnas, acciones por fila, barra de herramientas y sin resultados.
- [Gráficos](https://utiliza.me/solar/components/graficos.md): Reglas para barras, líneas y área en una card: colores, ejes, leyenda, tooltip y datos en tabla.
- [Carrusel](https://utiliza.me/solar/components/carrusel.md): Fila de tarjetas con flechas: indicador, varias por vista, vertical, automático con pausa y sin JS.

## Componentes: Formularios

- [Controles](https://utiliza.me/solar/components/controles.md): Texto, select, área de texto, casillas, radios e interruptor, con sus estados.
- [Campo](https://utiliza.me/solar/components/campo.md): Etiqueta, ayuda y error, conjuntos, fila con interruptor, tarjetas de opción, separadores y resumen de errores.
- [Campo con complementos](https://utiliza.me/solar/components/campo-con-complementos.md): Campo con ícono, texto fijo, botón, tecla, menú o spinner dentro del mismo borde, y área de texto con barra.
- [Código de verificación](https://utiliza.me/solar/components/codigo-de-verificacion.md): Casillas para el código de un solo uso: 6 y 4 dígitos, separador, alfanumérico, inválido y deshabilitado.
- [Combobox](https://utiliza.me/solar/components/combobox.md): Campo que filtra una lista: chips para elegir varias, grupos, opciones con detalle, inválido y desde un botón.
- [Calendario](https://utiliza.me/solar/components/calendario.md): Calendario para un día o un rango, mes y año en listas, atajos, días no disponibles, hora y selector de fecha.
- [Deslizador](https://utiliza.me/solar/components/deslizador.md): Control para elegir un valor o un rango arrastrando: marcas, varias manijas, vertical y deshabilitado.
- [Carga de archivos](https://utiliza.me/solar/components/carga-de-archivos.md): Zona de carga y ficha de cada archivo con su estado: en espera, subiendo, revisando, error y listo.

## Componentes: Feedback

- [Alertas](https://utiliza.me/solar/components/alertas.md): Avisos de información, éxito, advertencia y error: estados, estilos, íconos y accesibilidad.
- [Modal & Toast](https://utiliza.me/solar/components/modal-y-toast.md): Diálogos modales y notificaciones efímeras.
- [Tooltip](https://utiliza.me/solar/components/tooltip.md): Texto corto que aparece al pasar el cursor o enfocar un elemento.
- [FAQ / Acordeón](https://utiliza.me/solar/components/faq-acordeon.md): Preguntas frecuentes con expansión progresiva.
- [Popover](https://utiliza.me/solar/components/popover.md): Panel pequeño junto a un botón con un formulario corto, opciones o un enlace: básico, con acción y alineación.
- [Panel lateral](https://utiliza.me/solar/components/panel-lateral.md): Panel que entra desde un borde sobre la página: derecha, izquierda, sin botón de cerrar y abajo en el celular.
- [Tarjeta emergente](https://utiliza.me/solar/components/tarjeta-emergente.md): Vista previa de una persona o empresa al pasar el cursor sobre su nombre.

## Componentes: Estado & Progreso

- [Barras de progreso](https://utiliza.me/solar/components/barras-de-progreso.md): Lineal, indeterminada, radial y segmentada.
- [Stepper](https://utiliza.me/solar/components/stepper.md): Pasos de un formulario de varias pantallas.
- [Loading](https://utiliza.me/solar/components/loading.md): Spinners, botones loading y overlays.
- [Skeletons](https://utiliza.me/solar/components/skeletons.md): Placeholders animados para contenido en carga.

## Componentes: Estructura

- [Header](https://utiliza.me/solar/components/header.md): Encabezado del sitio: estructuras, comportamiento al hacer scroll, desplegables, estilos y combinaciones, con captura y página de ejemplo.
- [Footer](https://utiliza.me/solar/components/footer.md): Pie de página institucional con contacto y enlaces.

## Optional

- [Cómo trabajar](https://utiliza.me/solar/documentacion/que-quieres-hacer/): rutas para crear o mejorar algo, principios y prompts de revisión con IA
- [Documentación](https://utiliza.me/solar/documentacion/): qué es Solar y fundamentos