open-beauty

ES — Un harness de diseño en TypeScript con servidor MCP. Le das a un modelo un brief corto y devuelve una página HTML completa o un GIF, con tipografía, paleta, bordes, movimiento y validación ya decididos. La IA escribe el contenido; el sistema escribe el gusto.

EN — A TypeScript design harness with an MCP server. Give a small model a short brief and get a complete HTML page or looping GIF with typography, palette, borders, motion and a validator already decided. The model writes content; the system writes taste.

Por qué existe

Los modelos chicos pueden escribir un buen titular. Lo que no pueden hacer de forma consistente es elegir una tipografía, un acento, un ancho de borde y un ritmo de animación que funcionen juntos. El resultado típico es la estética "IA genérica": Inter, tarjetas redondeadas, degradados violetas, todo centrado, nada recordado.

Este repo mueve esas decisiones a tres sistemas editoriales completos. El modelo solo tiene que elegir uno, escribir contenido real y llamar a una herramienta.

• Sin LLM en runtime. El render es determinista: brief + preset → HTML/GIF.

• Sin plantillas genéricas. Cada estilo tiene su propio layout, no un recoloreo.

• Con validador. Un página que se sale de la línea editorial se detecta y se corrige antes de publicar.

• Un solo archivo. El HTML es autocontenido; el GIF se genera con canvas y gifenc.

Related MCP server: visualspec

Los tres estilos

Cada estilo incluye tokens exactos, reglas de layout, recetas de componentes, voz de copy y una lista de "nunca". Están en docs/STYLEGUIDE.md y en las skills de skills/.

GIFs

Los tres salen del mismo comando que las páginas y comparten la línea editorial.

Sitios educativos

El harness también sirve para lecciones, museos y explicadores, no solo para landings. Dos versiones propias, con copy real y fuentes citadas:

Ambas pasan A/100 y vision 4/4. El método para escribir una lección está en skills/education.md.

Quickstart

Requisitos: Node ≥ 22, pnpm, Git.

git clone https://github.com/jdsalasca/open-beauty-site.git
cd open-beauty-site
pnpm install
pnpm build

# ver los estilos
node dist/cli.js styles

# crear una página
node dist/cli.js page \
  --style brutalist \
  --title "LUNA / SIGNAL" \
  --tagline "A transmission from the other side of the prompt." \
  --intro "We build signals for people who are tired of being talked to." \
  --out out/luna.html

# crear un GIF
node dist/cli.js gif \
  --style papercraft \
  --text "Taller Papel" \
  --subtitle "Hecho a mano" \
  --out out/taller.gif

# auditar
node dist/cli.js validate out/luna.html --style brutalist --strict

También podés generar los tres ejemplos completos:

pnpm examples

MCP

El servidor habla stdio y expone siete herramientas. Está pensado para que un modelo débil no tenga que adivinar nada.

node dist/mcp/server.js

Claude Code

claude mcp add -s user open-beauty -- node "C:/absolute/path/open-beauty-site/dist/mcp/server.js"

Codex

[mcp_servers.open_beauty]
command = "node"
args = ["C:/absolute/path/open-beauty-site/dist/mcp/server.js"]
startup_timeout_sec = 30.0

Cursor / genérico

{
  "mcpServers": {
    "open-beauty": {
      "command": "node",
      "args": ["C:/absolute/path/open-beauty-site/dist/mcp/server.js"]
    }
  }
}

Herramientas

Recursos: beauty://styles/{renaissance|brutalist|papercraft} y beauty://skills/beauty.md.

El servidor manda instrucciones al conectarse: listar estilos → leer el estilo → crear con copy real → validar hasta A. La misma secuencia está en skills/beauty.md.

Validación

El validador no es un navegador; es un auditor de la línea editorial. Devuelve dos números: craft (¿obedece el manual?) y vision (¿tiene una idea visual?).

A · 100/100 · brutalist
vision 4/4 · all checks pass · scale-jump, flat-fields, asymmetry-or-bleed, material
No craft issues. The page respects the editorial system.
stats: {"bytes":18381,"colors":7,"fonts":["Space Mono","Archivo Black"],"radii":[],"durations":[0.25,0.3,0.45]}

Y cuando algo está mal:

[error] forbidden-font: "Inter" is forbidden in Brutalist.
  fix: Use Archivo Black for display and Space Mono for text.
[warn] radius-out-of-range: border-radius 8px is outside Brutalist's 10–48px range.
  fix: Use a cut corner, not a generic rounded rectangle.
[error] hard-shadow-in-papercraft: Paper Craft shadows must be soft.

Chequea fuentes, colores, bordes, radios, sombras, motion, landmarks, placeholders y contraste. La vision mide salto de escala, campos planos de color, asimetría/sangría y materia física. Craft A + vision 4/4 es el estándar; el resto son páginas obedientes, no arte. Los criterios están en docs/ART-DIRECTION.md.

Probado con modelos reales

No es una demo teórica. Dos agentes distintos, dos estilos distintos, sin HTML escrito a mano:

Luna llamó las herramientas MCP en orden y no escribió HTML. La v2 usa la dirección nueva (Fraunces Soft, capas de papel, geometría cortada) y pasó craft A + vision 4/4. La comparación v1/v2 está en examples/agents/: la v1 usaba DM Serif y Lato; la v2 usa Fraunces y Nunito Sans. El detalle de los runs está en docs/TESTING.md.

Cómo funciona

brief + style ──► preset ──► renderer ──► HTML ──► validator ──► score + fixes
                     │
                     └────► canvas frames ──► gifenc ──► GIF

• src/styles/presets.ts — los tres sistemas como datos: paleta, fuentes, reglas, guía.

• src/page/*.ts — un renderer por estilo, con CSS y markup propios.

• src/validate.ts — auditoría y scoring.

• src/gif.ts — frames con @napi-rs/canvas, encoding con gifenc.

• src/mcp/server.ts — el servidor MCP.

• src/cli.ts — la misma funcionalidad desde la terminal.

• skills/ — la mitad en lenguaje natural del harness.

Más detalle en docs/ARCHITECTURE.md y docs/MCP.md.

Estructura

open-beauty-site/
├── src/            # presets, renderers, validator (craft + vision), GIF, MCP, CLI
├── skills/         # beauty.md + education.md + una skill por estilo
├── docs/           # style guide, art direction, MCP, arquitectura, testing
├── examples/       # 3 páginas, 3 GIFs, 2 lecciones, agentes y previews
├── fonts/          # TTFs OFL para los GIFs
├── scripts/        # build de ejemplos/lecciones/docs, QA y e2e con colmena
└── test/           # tests de core y MCP

Roadmap

• Art Deco (Poiret One) para arquitectura, jazz y timelines.

• Isotype (Jost + IBM Plex) para datos, economía y matemática.

• Op Art (procedural) para percepción, geometría y física.

• Memphis y Ukiyo-e en una segunda ola, con bibliotecas de formas.

• format: slide (1600×900) y bloques figure, keyIdea, process.

• beauty_create_social para carruseles y OG images.

• Self-hosting de fuentes en el HTML para uso offline.

• Publicación en npm (npx open-beauty-site).

Las ideas completas, con paletas y tipografías, están en docs/ART-DIRECTION.md.

Contribuir

Las contribuciones son bienvenidas. Si agregás un estilo, tiene que pasar el validador en A, tener su skill generada y un ejemplo visual. Leé CONTRIBUTING.md.

Licencia

MIT. Las fuentes incluidas son OFL: EB Garamond, Archivo Black, Space Mono, Fraunces y Nunito Sans. Las licencias están en fonts/.

Hecho con demasiado café en Buenos Aires.