Índice de la documentación

Documentación del template

La guía del starter EchoSistema: cómo correrlo, dónde vive cada cosa y cómo usar los tokens y componentes del sistema.

Introducción

Starter Nuxt de los sitios de plataforma del grupo: el Liquid Glass entero parametrizado por cuatro tokens de marca.

Tokens de marca

Cuatro hex y un gradiente derivan todo el CSS por color-mix; cambiar la paleta es editar un bloque.

Tema claro y oscuro

Paridad automática: todo valor tematizable tiene gemelo dark, y el tema correcto pinta antes del primer paint.

Tres idiomas

Español canónico en la raíz, pt-BR e inglés con prefijo, catálogo único y locales en lockstep.

Componentes nativos

Dialog, details y selects del navegador vestidos por el sistema: accesibilidad gratis.

Inicio rápido

pnpm instala, corre y valida. Los mismos scripts del package.json, sin pasos escondidos.

ComandoPapel
pnpm devServidor de desarrollo con hot reload.
pnpm buildBuild de producción (SSR).
pnpm generateSitio estático prerenderizado.
pnpm previewSirve el build de producción localmente.
pnpm lintESLint en todo el proyecto.
pnpm typecheckvue-tsc sobre la app y la configuración.

Estructura

Layout estándar de Nuxt 4: app/ es el sitio, i18n/ los textos, shared/ lo que servidor y cliente comparten.

app/
  assets/css/main.css
  components/
  composables/
  data/
  layouts/
  pages/
  plugins/
  utils/
i18n/locales/
shared/
nuxt.config.ts

main.css es el único punto de entrada de estilo: los .vue no cargan style. El catálogo de idiomas vive en shared/languages.ts y la navegación en app/data/nav.ts.

Tokens de marca

El bloque MARCA al tope del main.css es el único lugar con hex de marca.

Fondos, textos, vidrio, botones y el panel de código derivan de estos cuatro tokens vía color-mix, con paridad claro/oscuro automática. Para rebautizar un sitio derivado, cambia este bloque y nada más; las paletas agro y consumer quedan comentadas en el archivo como ejemplo.

:root {
  --brand-1: #426ab2;
  --brand-2: #40c1c3;
  --brand-deep: #040b2d;
  --brand-link: #3d91cf;
}

Tema e idiomas

El tema gira en html[data-theme]; el idioma es dueño de la URL.

data-theme

Un script pre-paint en el head lee la preferencia guardada (o la del sistema) y define data-theme antes del primer paint: sin flash de tema equivocado. El cambio en runtime es el mismo atributo.

prefix_except_default

El español canónico vive sin prefijo; /pt-BR y /en prefijan las demás rutas. Agregar un idioma es una entrada en el catálogo de shared/languages.ts más el archivo de locale correspondiente.

Tipografía

El contenido semántico se viste por el contenedor: .es-prose estiliza los elementos de adentro.

Títulos, párrafos, citas, código y los demás elementos de texto ganan el estilo del sistema al entrar en una .es-prose, sin utility por elemento. Las familias cargadas son Manrope, Montserrat y JetBrains Mono.

<div class="es-prose">
  <h2>…</h2>
  <p>…</p>
  <blockquote>…</blockquote>
</div>
Ver la referencia de tipografía

Inventario

Los 41 componentes de app/components/echo, por papel. Cada uno viste un elemento nativo cuando existe: de ahí vienen teclado, foco y anuncio, sin reimplementación.

Acciones y navegación

Button · Chip · Badge · Pill · Dropdown · Pagination · Breadcrumb · Tabs

Formularios

Input · Textarea · Select · SearchSelect · TagsInput · Checkbox · Radio · Switch · Slider · Rating · FileButton · Dropzone

Respuesta y espera

Alert · Modal · Drawer · Toaster · Block · Skeleton · Spinner · Progress · Ring

Contenido

Card · List · ListItem · DataTable · Avatar · Gallery · Tree · Timeline · Collapse · Divider · Stat · Player

Intenciones y variantes

Dos ejes que nunca se combinan a mano: .es-i--* da el color, la variante lo consume.

Diez intenciones definen tokens locales (--i, --i-on, --i-grad y derivados) que las cuatro familias de etiqueta y el modal consumen. Las variantes (filled, gradient, outline, glass, ghost) se escriben una sola vez.

primarysuccessdangerwarningcautiondark
<echo-button variant="filled" intent="danger">…</echo-button>

<echo-chip variant="soft" intent="info">…</echo-chip>

<echo-badge variant="filled" intent="success">…</echo-badge>

<echo-pill variant="outline" intent="caution">…</echo-pill>

Alerts

Ocho tonos sobre la misma paleta, con la cuña de acento en el borde.

Cuatro semánticos de estado (info, success, warn, danger) y cuatro tonales nombrados (caution, steel-blue, navy-blue, dark). El texto queda en los grises del tema; el acento entra en el ícono, el título y la cuña.

<echo-alert tone="success" title="…">
  …
</echo-alert>

Modales

El dialog nativo: foco atrapado, Esc, fondo inerte y borroso.

Superficie opaca del tema, cuña de intención como en los alerts, fondo ilegible por el blur mientras está abierto y scroll trabado. El clic afuera no cierra; cierran el Esc, el cerrar del encabezado y las acciones del pie. El ancho sigue la escala sm, md, lg, xl y xxl.

<echo-modal ref="modal" title-id="…"
            intent="warning" size="lg">
  <template #title>…</template>
  …
  <template #footer>…</template>
</echo-modal>

modal.value?.open()

Modales de cuenta

Entrar, crear cuenta, recuperar y cambiar la contraseña, y la sesión bloqueada. Cinco componentes listos en app/components/auth/, sobre el mismo echo-modal.

Los cinco siguen el mismo contrato: open() y close() expuestos por ref, un submit con los datos, y nada de red por dentro. Quien sabe la URL, el token y qué hacer con la respuesta es la aplicación — el componente solo recoge, valida lo que no depende del servidor y devuelve.

<auth-login-modal
  ref="login"
  :pending="sending"
  :error="failure"
  logo="/img/minha-marca.svg"
  title="Entrar no painel"
  @submit="signIn"
  @forgot="forgot?.open()"
  @register="register?.open()"
/>

login.value?.open()

El submit sale en el vocabulario de la API, no en el de las variables internas: mandar el payload directo al endpoint es el caso común, y traducir nombres de campo en cada sitio derivado sería el mismo de-para escrito muchas veces.

Contrato de los modales de cuenta
ComponenteCampos del submitEventos
<auth-login-modal>email, password, remember@submit @forgot @register
<auth-register-modal>name, email, gender (m|f|o), birth_date (yyyy-mm-dd), password, password_confirmation, terms (1|0)@submit @login
<auth-forgot-password-modal>email@submit @login
<auth-update-password-modal>password, password_confirmation@submit
<auth-lock-modal>password@submit @sign-out

Las props son las mismas en los cinco, con dos excepciones anotadas. Todas son opcionales.

logo

Arte del encabezado, cuando el modal representa otra marca que no es la del sitio. Sin ella, el logo del sitio.

title

Título propio en lugar del texto estándar del flujo.

pending

Bloquea los campos y cambia la etiqueta del botón mientras corre su llamada.

error

Mensaje del servidor, mostrado en una alerta sobre el formulario. Quien lo limpia es quien lo pasó.

sent

Solo en el de recuperación: cambia el formulario por la confirmación de envío. Es del llamador, porque quien sabe que el pedido llegó es quien lo hizo.

name / avatar

Solo en el de bloqueo: nombre y retrato de quien tiene la sesión trabada.

Ver los cinco funcionando

Formularios y collapses

Campos sobre la tinta de la lente y el details nativo de tarjeta.

es-input sirve para input y textarea; es-select es el select nativo con la misma tinta. El es-collapse viste el details del navegador: abre, cierra y es accesible sin una línea de JS.

<echo-input v-model="email" type="email" />

<echo-textarea v-model="message" rows="3" />

<echo-select v-model="topic">…</echo-select>

<echo-collapse>
  <template #summary>…</template>
  …
</echo-collapse>
Ver en la vitrina

Reglas

Las convenciones que valen para todo sitio derivado.

CSS en un solo lugar

Ningún bloque style en .vue: utility en el template y el resto en main.css.

Token para todo valor tematizable

Hex crudo en template es hallazgo; la marca entera vive en el bloque MARCA.

Prefijo es-

Toda clase componente y token del sistema usa el prefijo, renombrable en un replace global.

Contraste en ambos temas

Todo texto verificado contra el campo real; color de acento no es color de texto.

Movimiento y transparencia

prefers-reduced-motion y prefers-reduced-transparency respetados por toda animación y vidrio.

Locales en lockstep

Español canónico; toda string de interfaz vía t(), los contratos quedan literales.

Ayuda

¿Una duda que la documentación no cubre?

Habla con el grupo EchoSistema en echosistema.online.

Changelog

Lo que cambió en el template, de lo más reciente hacia atrás.

  • Vitrina dividida: La página única de ochocientas líneas se volvió seis rutas con menú lateral, una por asunto.
  • Navegación: Paginación, ruta, pestañas con tablist de la ARIA, línea de tiempo y panel lateral.
  • Primitivos de panel: Barra de progreso, anillo y línea de estadística; las tarjetas de panel se volvieron composición de ellos.
  • Tarjeta y lista: Card con encabezado, imagen y las cuatro acciones (contraer, actualizar, expandir, quitar), más List en tres densidades.
  • Media player: Plyr como primera dependencia de runtime, por Vimeo y YouTube detrás de una sola interfaz.
  • Toasts: Cola global con la posición en el estado, y la misma cuña de acento de los alerts y modales.
  • Valoración: Lectura con fracción e interactiva sobre radios nativos, con las flechas del teclado gratis.
  • Controles y escala: Toggler, casilla, radio, selectores nativos de fecha y color, y la escala sm/md/lg de los botones.
  • Sistema de intenciones: Diez intenciones con variantes para botones, chips, badges y pills, en dos ejes de clases.
  • Alerts en ocho tonos: Los cuatro tonales nombrados entran a la paleta, con la cuña redondeada de acento.
  • Modales nativos: Dialog opaco con cuña de intención, fondo borroso, escala de ancho y scroll trabado.
  • Vitrina y tipografía: Páginas /componentes y /tipografia con todos los elementos del sistema.
  • Tres familias: Manrope, Montserrat y JetBrains Mono, cada una con su papel fijo en el sistema.
EchoSistema TemplateVolver al sitio

La base visual de los sitios de plataforma del grupo EchoSistema.