smyrna-pergamum/aperture-topology-story

Historia de topología con apertura

Una página de producto que se comporta como un documento de ingeniería tranquilo con un único movimiento cinematográfico: el lector se desplaza hacia un nodo de la red y la página oscura se abre como el diafragma de una cámara hacia un espacio de trabajo claro donde se representa el flujo de trabajo real del producto con tarjetas. Es adecuado para herramientas cuyo valor es un pipeline que se puede mostrar (entradas → fuentes/pares → resultados → salida): mallas de inferencia, herramientas OSINT y de investigación, pipelines de datos, CI, motores de sincronización, registros de paquetes. No es adecuado para marcas de estilo de vida o moda.

La construcción de referencia es example/index.html: el sitio web real para OSINT-Book (un cuaderno OSINT pasivo y basado en fuentes para Android y Windows), EN/TR, en los colores propios de la aplicación. El código detallado está en references/components.md; screenshots/ muestra cada sección, cada fase de la historia, turco, movimiento reducido y móvil.

Si el usuario nombra un sitio de referencia, toma solo su estilo. Nunca copies sus renders, nombres de producto, textos, logotipo o datos.

1. Antes de diseñar

1. Lee primero las fuentes del producto: README, guía de usuario, modelo de privacidad/amenazas, API o registro de fuentes, notas de la versión, CHANGELOG. Cada afirmación en la página corresponde a una de ellas. Copia los números exactamente (versiones, nombres de archivo, tamaños, SHA-256, puertos). Si dos fuentes discrepan (por ejemplo, "22 módulos" frente a una tabla de 20 filas), muestra lo que demuestra la tabla.
2. Toma los colores del propio producto: icono del lanzador, colors.xml de Android / lightColorScheme y darkColorScheme de Compose, propiedades personalizadas CSS web. Asigna el esquema oscuro de la aplicación al fondo oscuro y su esquema claro al espacio de trabajo de apertura — la página entonces cambia literalmente de un tema de la aplicación al otro.
3. Encuentra la historia: escribe el flujo de trabajo del producto como cuatro verbos (OSINT-Book: objetivo → hallazgos → análisis → informe; una malla de inferencia: modelo → segmento → lugar → servir). Una fase por verbo. Cada fase necesita un encabezado de ≤ 6 palabras.
4. Los datos de muestra en la historia deben ser obviamente de muestra: example.org, IPs de documentación (192.0.2.x, 203.0.113.x), un chip "sample data" en cada tarjeta. Nunca inventes estadísticas, recuentos de usuarios, puntos de referencia o testimonios.
5. Usa capturas de pantalla reales de la aplicación (WebP, ~800px de ancho) para la sección de arquitectura.

2. ADN visual

Elemento	Regla
Fondo oscuro	Casi negro, ligeramente teñido con la marca: --bg-2 (página) / --bg / --surface / --surface-2 / --surface-3. Una cuadrícula de 36px de líneas de 1px a ~7% de la tinta clara sobre todo el cuerpo. Zonas de brillo radial (color de marca al ~13%, segunda señal al ~6%) detrás del héroe y el escenario.
Espacio de trabajo claro	El fondo claro de la aplicación (--paper) con una cuadrícula de 34px al ~5.5% de tinta y un lavado radial suave del color del contenedor de la marca en el medio. Solo dentro de la apertura.
Tinta	Oscura: --fg / --fg-2 / --muted (muted ≥ 4.5:1 sobre el fondo). Clara: --ink / --ink-2 / --ink-muted.
Marca	El color del producto para el nodo objetivo, origen de apertura, chips "sample data", estados de Atención, elemento de riel activo, bordes al hover. En oscuro usa el tono más claro (--brand-2), en papel el tono más profundo (--brand-ink).
Señales	Dos tonos más, cada uno con un significado: verde azulado = gratuito / ok / hallazgo devuelto; dorado = necesita una clave / opcional / faltante. Los paquetes salientes usan la marca, los paquetes retornantes usan verde azulado. La gravedad es siempre color + icono + palabra.
Visualización	Rajdhani 700, interlineado .84–.98, espaciado de letras 0, oración con mayúscula inicial. Héroe 2.6–5.2rem con un brillo de cuatro capas: 0 0 2px #fff·86%, 0 0 18px brand-2·36%, 0 0 48px teal·14%, 0 18px 52px #000·60%. Sobre papel la misma tipografía con 0 1px #fff, 0 14px 34px ink·12%.
Cuerpo / UI	Geist 400–700, 14–17px.
Etiquetas	Geist Mono 10–13px: etiquetas de nodo, subetiquetas, chips, cuotas de tabla, terminal, riel, cejas (01 / ai analysis, mayúsculas + .14em solo aquí).
Tarjetas	Paneles oscuros: radio 16px, 1px --line-2, degradado vertical de superficie. Tarjetas de papel: blancas, radio 14px, línea cálida de 1px, sombra 0 14px 34px -14px. Los chips son píldoras (20px de alto). Las filas de hallazgos tienen un asa degradada de 6×18px a la izquierda.
Botones	Primario = relleno casi blanco con tinta oscura (radio 8px, 40px). Fantasma = línea de 1px que se vuelve brand-2 al hover. Los botones tipo píldora en la navegación llevan un sufijo mono (· web-v0.2.2).
Iconos	Iconos de cuadrícula 24, trazo único de 1.7px en un sprite <symbol> inline; el mismo sprite se usa con <use> dentro del gráfico SVG.

3. Patrones de sección

1. Navegación fija (64px, translúcida oscura + desenfoque de 16px, línea inferior fina) – icono + marca de dos tonos, enlaces pequeños, píldora de GitHub con versión, alternancia EN/TR, botón primario.
2. Héroe – topología SVG de ancho completo (viewBox 1200×520; nodo objetivo en el medio con halo + anillo; 5–7 nodos fuente en bordes discontinuos curvos, cada uno con una etiqueta mono y una subetiqueta mono que indica el acceso: key-free, your key). El título de visualización se sitúa sobre la parte inferior izquierda del gráfico. Debajo: una oración de introducción y una fila de tres columnas – "run it" (un chip de comando con copiar + botones de descarga primario/fantasma + enlace "follow …"), "what it is" (primera oración en negrita + fila de datos con puntos de colores) y una pequeña insignia de marca. Si el producto tiene una característica destacada que la topología no muestra (OSINT-Book: análisis de IA opcional), menciónala en la introducción y añade una píldora debajo: una etiqueta de marca rellena (AI analysis) + una línea + flecha, que enlace a esa sección, que entonces va primero después de la historia.
3. Historia de apertura (fija, ~640vh) – ver §4.
4. Franja de integración – etiqueta mono mayúscula a la izquierda, una lista envuelta de nombres punteados a la derecha, líneas finas arriba y abajo.
5. Conmutador de arquitectura – encabezado de sección (título grande de visualización a la izquierda, párrafo a la derecha), luego un panel oscuro: una lista de pestañas (píldora rellena = seleccionada), una columna de texto (título, un párrafo, lista con ✓) y un diagrama de nodos HTML sobre un SVG de conectores discontinuos animados (marca = lo que sale, verde azulado = lo que retorna, dorado = opcional), luego una franja horizontal de capturas de pantalla reales con subtítulos mono, luego un pie de leyenda.
6. Bloques de módulos – bloques con dos pequeñas "pestañas de puzzle" en el borde superior: fila de entradas → una fila lateral / centro / lateral (bloque central más grande, teñido de marca, fuente de visualización) → una fila de 6 salidas; una nota mono debajo.
7. Tabla de catálogo – campo de búsqueda + selects con etiqueta mono, una tabla con nombre + id mono, píldoras de tipo, una columna de acceso con puntos de colores, una columna de cuota mono, notas; pie con "Showing x–y of n · source file" y un paginador. Una lista <details> "left out, on purpose" debajo.
8. División de alcance – dos paneles oscuros, "What it does" (cuadrado verde azulado) / "What it never does" (cuadrado rojo), cada elemento una introducción en negrita más una oración, línea fina a la izquierda.
9. Instalación – dos tarjetas de descarga (icono en mosaico, nombre, nombre de archivo mono · tamaño), luego una ventana de terminal (luces de tráfico, pestañas mono, COPY que copia solo los comandos, indicador coloreado / comando / banderas / comentarios / salida) con un pie de estado (punto vivo brillante), luego una nota honesta dorada "Early releases".
10. Pie de página – texto sobre + píldoras de idioma, dos listas de tarjetas de enlace (filas con flechas; ↗ externo, → documentos), fila inferior con marca de palabra, chip de versión y línea de atribución.

4. Interacción característica: la historia de apertura

Un section.story (altura ≈ 640vh) contiene un escenario position:sticky; top:0; height:100svh con dos capas:

• Capa oscura – el mismo gráfico de topología otra vez, una pista mono (scroll · follow one target) y la línea de cierre.
• Capa clara – clip-path: circle(R at X Y) donde X/Y es la posición en pantalla del nodo objetivo (medida con getBoundingClientRect). Dentro: cuatro encabezados apilados (solo uno .on), un tablero lógico (1120×560 de ancho, 360×640 estrecho) escalado para ajustarse, y un riel de fase mono.

Un único valor de progreso p = -rect.top / (story.offsetHeight - innerHeight) lo impulsa todo; cada elemento tiene fotogramas clave [p, {x, y, s, o}] interpolados con ease-in-out-cubic y aplicados como translate() scale() + opacity. Desplazarse hacia atrás rebobina exactamente.

p	Fase	Qué se mueve
.015 → .10	Apertura se abre	R crece de 0 a la esquina más lejana; la pista se desvanece. Luego clip-path:none.
.00 → .33	1 · entrada	La tarjeta de entrada sube; sus filas de lista de verificación se marcan una por una (p > .13 + i·.026); las filas restringidas por clave permanecen sin marcar.
.31 → .56	2 · resultados	La tarjeta de entrada se desvanece; la tarjeta "notebook" toma su lugar; seis tarjetas de origen aparecen a su alrededor; un chip por origen vuela desde su tarjeta a una ranura en el cuaderno (st = .37 + i·.024, llega st + .04). El chip de espacio es discontinuo.
.56 → .79	3 · interpretación	Las tarjetas de origen se encogen hasta convertirse en puntos; el cuaderno se desliza a la izquierda (los chips siguen su transformación); tres tarjetas de observación se deslizan desde la derecha; conectores discontinuos se dibujan desde el chip citado a cada tarjeta; aparece una píldora "no verdict".
.79 → .92	4 · salida	Todo se pliega en una tarjeta de informe; una tarjeta de commit sube debajo y sus seis puntos de ruta se iluminan.
.915 → .975	Apertura se cierra	R se encoge a 0 de vuelta al nodo; la línea de cierre brillante aparece gradualmente en la capa oscura.

• Solo cambian transform, opacity, clip-path y atributos SVG mientras se desplaza (un único controlador rAF-throttled).
• Los paquetes del gráfico se ejecutan en un bucle rAF solo mientras un gráfico está en pantalla, nunca con movimiento reducido o una pestaña oculta.
• Pantallas estrechas (< 760px): un segundo diseño de tablero (fuentes como una cuadrícula de píldoras 3×2 en la parte superior, cuaderno escalado a .6 en la fase 3, observaciones apiladas, conectores ocultos). Misma línea de tiempo.
• Movimiento reducido (o ?motion=reduce para revisión): sin fijación, sin apertura; la historia se representa como cuatro marcos de papel estáticos (el tablero en p = .30, .55, .78, 1) con sus encabezados.
• El tablero es aria-hidden; una lista ordenada sr-only cuenta los mismos cuatro pasos.

5. Reglas de construcción

• Un único index.html independiente: doctype, charset, viewport, color-scheme: dark, theme-color; CSS y JS inline; solo Google Fonts (Rajdhani, Geist, Geist Mono); imágenes junto a la página como WebP; iconos como un sprite SVG inline.
• Tokens en :root; cada color de la página proviene de ellos (§2). Nómbralos según su función, conserva los valores hexadecimales del producto.
• i18n: el inglés vive en el HTML (las claves data-i18n se leen una vez como fuente en inglés); otros idiomas en un diccionario JS; las cadenas construidas por JS usan T({en, tr}). Persiste la elección en localStorage dentro de try/catch. Traduce también las cejas (mayúsculas + configuración regional turca convierte "install" en "İNSTALL").
• Accesibilidad: contraste AA en ambos fondos, anillo de enfoque visible (brand-2), enlace de salto, pestañas con role=tab, aria-selected, tabindex rotativo y teclas de flecha, <table> y <details> reales, botones de copiar con etiquetas.
• Responsive: ≥1060px diseño completo; <1060px insignia lateral del héroe oculta, cuadrícula de IA apilada, ediciones apiladas; <760px una columna, viewBox del gráfico recortado (150 40 900 480) con etiquetas más grandes y sin subetiquetas, tablero de historia estrecho, nodos de diagrama sin líneas secundarias. Sin desplazamiento horizontal a 360px; verifica que los hijos de grid tengan min-width:0.
• Escapa < y > en cualquier cadena de datos que renderices con innerHTML (http://<server-ip>).

6. Escribir el texto

• Los encabezados son dos líneas cortas que expresan una propiedad, no una promesa: "Every finding keeps its source." "Two editions. One file format." "AI that reads findings. Never rewrites them."
• Párrafos: una o dos oraciones simples con los sustantivos concretos (puertos, formatos, algoritmos, nombres de archivo).
• Los límites reciben el mismo peso que las características ("What it never does", "Early releases", "left out, on purpose").
• Las etiquetas mono son minúsculas y concisas (key-free, your key, target · sample, sha-256 3f9a…).

7. Lista de verificación de finalización

• Cada afirmación, número, nombre de archivo y hash coincide con los archivos propios del producto y la versión actual.
• Los tokens de color provienen del producto (icono + esquemas claro/oscuro); la gravedad nunca solo por color.
• La historia está sincronizada en ambos sentidos, la apertura se abre desde el nodo y se cierra en él, nada se superpone en p = .27/.5/.75/.9.
• El diseño estrecho y los fotogramas de movimiento reducido se leen correctamente; los paquetes se detienen fuera de pantalla.
• Las pestañas, el paginador, la búsqueda, los filtros y los botones de copiar funcionan con el teclado; el enfoque es visible.
• El conmutador EN/TR vuelve a renderizar el tablero, el diagrama, la tabla, el terminal y las cejas.
• Sin desplazamiento horizontal a 360/390px; sin errores de consola.
• Capturas de pantalla a 1440×900 y 390×844: node scripts/screenshots.mjs example/index.html screenshots.