ladder-web

🪜 LADDER Landing

Landing profesional para agencia digital especializada en desarrollo móvil, automatizaciones con IA y digitalización de administraciones públicas.

🎯 Características

Astro 7 — SSG, componentes .astro, astro:i18n nativo (build-time, sin localStorage)
Tailwind CSS v4 — vía @tailwindcss/vite, build-time (no CDN)
TypeScript — Revealing Module pattern en src/scripts/
SEO optimizado — Meta tags, structured data, Open Graph
100% accesible — Semántica HTML5, ARIA labels
Responsive — Optimizado para móvil, tablet y desktop

📁 Estructura del Proyecto

ladder-web/
├── src/
│   ├── pages/                      # Rutas Astro — ES sin prefijo, EN bajo /en/
│   │   ├── index.astro
│   │   ├── nosotros.astro, contacto.astro, faq.astro, ...
│   │   ├── servicios/*.astro       # 6 páginas de servicio
│   │   ├── admin/*.astro           # login, dashboard, access-denied, reset_password
│   │   └── en/                     # espejo EN de todo lo anterior
│   ├── layouts/                    # BaseLayout, AuthLayout
│   ├── components/                 # Header, Footer, AdminHeader, AdminFooter
│   ├── scripts/                    # Client scripts TS (Revealing Module, window.X)
│   ├── i18n/                       # useTranslations + 22 namespaces × es/en
│   └── styles/global.css
│
├── tests/                           # tests/unit (Vitest) + tests/e2e (Playwright)
├── doc/                             # Documentación operativa (español)
├── docs/adr/                        # Architectural Decision Records
├── .claude/                         # Contexto Claude Code (arquitectura, convenciones, estado)
├── astro.config.mjs                 # i18n (es/en, prefixDefaultLocale: false), @tailwindcss/vite
├── vitest.config.js                 # Tests unitarios (independiente del build)
├── package.json
└── netlify.toml                     # Deploy config

🚀 Stack Tecnológico

Frontend

Astro 7 — SSG, componentes .astro, routing i18n nativo
Tailwind CSS v4 — @tailwindcss/vite, procesado en build
TypeScript — src/scripts/**, Revealing Module tipado
GSAP — animaciones (src/scripts/animations.ts)
Better Auth (cliente) — sesión de admin (src/scripts/authStore.ts), consumido contra ladder-api

Backend

ladder-api (Hono + Drizzle ORM + PostgreSQL + Better Auth, arquitectura hexagonal) — backend propio, consumido vía fetch/REST. Ver ADR-G019 y worlds/ladder-api/CLAUDE.md. Migración desde Supabase completa, sin legacy en este repo.

Herramientas de Desarrollo

ESLint / Stylelint — linting
Prettier — formateo de código
Vitest — tests unitarios (195 tests)
Playwright — tests e2e/visuales (16 specs)

Deploy

Netlify — hosting con build automático, dist/ como output

🛠️ Instalación

git clone https://github.com/Ledder-Dev/ladder-web.git
cd ladder-web

pnpm install   # pnpm-lock.yaml es la lockfile del proyecto, no usar npm install

cp .env.example .env   # completar PUBLIC_API_BASE_URL y PUBLIC_AUTH_BASE_URL, ver sección siguiente

pnpm run dev

La aplicación estará disponible en http://localhost:4321

Variables de entorno (`PUBLIC_API_BASE_URL`, `PUBLIC_AUTH_BASE_URL`)

src/scripts/config.ts lee ambas (prefijo PUBLIC_ = convención Astro para exponerlas al cliente). No hay valor por defecto hardcodeado en prod — .env decide contra qué backend corre el front. Van separadas porque son dos servicios distintos: PUBLIC_API_BASE_URL es el resto de la API de negocio (vía ladder-gateway), PUBLIC_AUTH_BASE_URL es ladder-auth-service directo — login/signup/passkey/getSession NUNCA pasan por el gateway (evita dependencia circular JWKS, ver ladder-auth-service/README.md sección 2).

# .env — apuntar a ladder-api/ladder-auth-service corriendo en local
PUBLIC_API_BASE_URL=http://localhost:3000
PUBLIC_AUTH_BASE_URL=http://localhost:4000

# .env — apuntar a los servicios ya desplegados (sin levantar nada en local)
PUBLIC_API_BASE_URL=https://gateway.ladderdev.com
PUBLIC_AUTH_BASE_URL=https://auth.ladderdev.com

Con el segundo par, pnpm run dev sirve el front en localhost:4321 pero todas las requests de negocio (/leads, /service-prices, /analytics/*) van contra ladder-gateway y las de auth (/api/auth/*) contra ladder-auth-service — útil para levantar el front sin tocar ladder-api/Postgres en local. Requiere que ambos tengan http://localhost:4321 en sus trustedOrigins/CORS.

📝 Scripts Disponibles

# Desarrollo
pnpm run dev              # Astro dev server (puerto 4321)
pnpm run build            # astro build → dist/
pnpm run preview          # astro preview

# Linting
pnpm run lint             # stylelint + eslint
pnpm run lint:fix         # Auto-fix CSS y JS

# Formateo
pnpm run format            # Prettier
pnpm run format:check      # Verificar formato

# Validación
pnpm run validate           # Lint + format check
pnpm run check:links        # Verificar enlaces rotos
pnpm run check:a11y         # Verificar accesibilidad
pnpm run pre-commit          # validate + check:links (antes de cada commit)

# Tests
pnpm run test               # vitest run (195 tests)
pnpm run test:coverage      # vitest run --coverage
pnpm run test:visual        # Playwright — 16 tests e2e (login, access-denied, navigation, ...)

Deploy real es automático vía Netlify (netlify.toml) en cada push a master — no hay script deploy:* en package.json.

🌐 i18n

Routing build-time vía astro:i18n: / = español (default), /en/* = inglés. Ningún toggle en cliente ni localStorage — cambiar idioma es navegar a la página espejo. Texto vía {t('namespace.key')}, nunca hardcodeado. Detalle → .claude/BUSINESS_LOGIC.md.

🎨 Convenciones de Código

Nunca usar: React / Vue / Angular · jQuery · Bootstrap · SASS
HTML: elementos semánticos, alt en imágenes, labels en inputs, ARIA labels
CSS: Tailwind-first, BEM para clases custom
JS/TS: Revealing Module pattern, const/let, async/await, try/catch en funciones async

Detalle completo → .claude/CONVENTIONS.md

🎨 Design System (Tailwind v4, `@theme` en `src/styles/global.css`)

Token	Hex	Uso
`brand-blood`	`#900000`	CTA primario, acentos
`brand-deep-red`	`#660000`	Estados hover
`background-dark`	`#0a0a0a`	Fondo de página
`surface-dark`	`#121212`	Superficies elevadas
`card-dark`	`#1a1a1a`	Fondos de tarjetas

Tipografía: Plus Jakarta Sans — clase font-display en <body>.

🌐 SEO

Meta tags únicos por página, Open Graph, Twitter Card
Structured data (JSON-LD) por página
Sitemap generado en build

♿ Accesibilidad

Contraste WCAG AA, navegación por teclado, screen reader compatible, ARIA labels

🚀 Deploy

Netlify (actual)

Conectar repositorio en Netlify
Build command: pnpm run build · Output directory: dist
Configuración completa en netlify.toml
Deploy automático en cada push a master

📖 Documentación

Arquitectura — estructura del proyecto
Convenciones — guía de estilo
Backend / schema — ladder-api (Hono + Drizzle), fuente de verdad de la BD
Lógica de negocio — auth, i18n, analytics, forms
Estado actual
ADRs — decisiones arquitectónicas

🤝 Contribuir

Crear rama feature (git checkout -b feature/nueva-funcionalidad)
Commit con mensaje descriptivo (git commit -m 'feat: añadir nueva funcionalidad')
Push a la rama y abrir Pull Request

Tipos de commits

feat · fix · style · refactor · docs · perf · test

👥 Equipo

LADDER Agency — Especialistas en digitalización estratégica

Hecho con ❤️ por LADDER Agency

Arquitectura

Ver diagrama interactivo