Guía detallada para estructurar un proyecto web básico

yanqui.rm

Publicado el 01/09/2025

Guía detallada para estructurar un proyecto web básico

Cuando creamos un sitio web estático, aunque sea pequeño, conviene ordenar carpetas y ficheros para que el proyecto sea fácil de mantener y escalar. Aquí tienes cómo hacerlo, con explicaciones de por qué cada decisión.

1. Principios básicos

Separación clara de responsabilidades:

HTML = contenido y estructura.
CSS = estilo visual.
JS = comportamiento.

Carpetas previsibles para no perderse cuando crezca el proyecto.

Nombres consistentes (ejemplo: kebab-case → about-us.html, main.css).

Evolución sin dolor: aunque no uses build ahora, tu estructura debe permitir añadir más páginas, imágenes o scripts fácilmente.

2. Estructura recomendada


mi-sitio/
├── index.html
├── about.html
├── assets/
│   ├── css/
│   │   └── styles.css
│   ├── js/
│   │   ├── main.js
│   │   ├── accordion.js
│   │   └── menu.js
│   ├── img/
│   │   ├── hero.avif
│   │   ├── hero.webp
│   │   └── hero.jpg
│   ├── svg/
│   │   └── icons.svg
│   ├── fonts/
│   │   └── Inter.woff2
│   └── icons/
│       └── favicon.ico
├── robots.txt
└── sitemap.xml

¿Por qué así?

assets/ agrupa todo lo no-HTML.
Subcarpetas (css, js, img, svg, fonts) evitan mezclarlo todo.
icons/ separa favicon y manifest de otras imágenes.
Archivos raíz (robots.txt, sitemap.xml) ayudan al SEO.

3. HTML: base semántica y accesible

Ejemplo de index.html mínimo pero sólido:


<!DOCTYPE html>
<html lang="es">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Inicio • Mi Sitio</title>
  <meta name="description" content="Breve descripción de la página.">
  <!-- SEO y redes sociales -->
  <link rel="canonical" href="https://ejemplo.com/">
  <meta property="og:title" content="Inicio • Mi Sitio">
  <meta property="og:description" content="Breve descripción.">
  <meta property="og:type" content="website">
  <meta property="og:url" content="https://ejemplo.com/">
  <meta property="og:image" content="https://ejemplo.com/assets/img/og-image.jpg">
  <!-- Iconos y PWA -->
  <link rel="manifest" href="/assets/icons/site.webmanifest">
  <link rel="icon" href="/assets/icons/favicon.ico">
  <!-- CSS -->
  <link rel="stylesheet" href="/assets/css/styles.css">
  <!-- JS -->
  <script src="/assets/js/main.js" defer></script>
</head>
<body>
  <a class="skip-link" href="#contenido">Saltar al contenido</a>
  <header class="site-header">
    <nav aria-label="principal">
      <ul>
        <li><a href="index.html">Inicio</a></li>
        <li><a href="about.html">Acerca</a></li>
      </ul>
    </nav>
  </header>
  <main id="contenido" tabindex="-1">
    <h1>Bienvenido a mi sitio</h1>
    <p>Contenido de ejemplo…</p>
  </main>
  <footer class="site-footer">
    <p>© <span id="year"></span> Mi Sitio</p>
  </footer>
</body>
</html>

Puntos clave:

lang="es" ayuda a lectores de pantalla y buscadores.
<meta name="description"> mejora SEO.
<a class="skip-link"> da accesibilidad al navegar con teclado.
defer en el script evita bloquear el render.
<main tabindex="-1"> facilita enfocar el contenido tras usar “saltar al contenido”.

Si estás interesado en aprender a crear tu primera página web, te recomendamos leer este artículo: Cómo Crear tu Primera Página Web: Guía Básica para Principiantes. En él encontrarás los pasos esenciales y consejos prácticos para comenzar desde cero.

4. CSS: orden en capas sencillas

En /assets/css/styles.css puedes organizar:


/* 1. Reset / normalización */
* { box-sizing: border-box; margin: 0; padding: 0; }

/* 2. Variables (tokens) */
:root {
  --color-bg: #fff;
  --color-fg: #111;
  --color-primary: #1e66f5;
  --space: 1rem;
}

/* 3. Utilidades */
.visually-hidden {
  position: absolute;
  width: 1px; height: 1px;
  overflow: hidden; clip: rect(0 0 0 0);
  white-space: nowrap;
}

/* 4. Layout */
body {
  font-family: system-ui, sans-serif;
  background: var(--color-bg);
  color: var(--color-fg);
  line-height: 1.5;
  padding: var(--space);
}

/* 5. Componentes */
.site-header nav ul {
  list-style: none;
  display: flex;
  gap: var(--space);
}

a {
  color: var(--color-primary);
  text-decoration: none;
}

a:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
}

Por qué así:

Resets aseguran consistencia entre navegadores.
Variables (--color-*) permiten cambiar temas fácilmente.
Ordenar por bloques (reset → tokens → utilidades → layout → componentes) hace predecible la cascada.

5. JS: modular y discreto

En /assets/js/main.js:


document.addEventListener('DOMContentLoaded', () => {
  // Actualizar año en el footer
  const y = document.getElementById('year');
  if (y) y.textContent = new Date().getFullYear();

  // Ejemplo: menú desplegable
  const menuBtn = document.querySelector([data-menu-btn]);
  const menu = document.querySelector([data-menu]);
  if (menuBtn && menu) {
    menuBtn.addEventListener('click', () => {
      const open = menuBtn.getAttribute('aria-expanded') === 'true';
      menuBtn.setAttribute('aria-expanded', String(!open));
      menu.hidden = open;
    });
  }
});

Claves:

Usa DOMContentLoaded para esperar al DOM.
Modulariza si crece (ej. accordion.js, menu.js).
Usa data-attributes para conectar JS con HTML sin depender de clases de estilo.

6. Imágenes, iconos y fuentes

Imágenes responsivas


<picture>
  <source srcset="/assets/img/hero.avif" type="image/avif">
  <source srcset="/assets/img/hero.webp" type="image/webp">
  <img src="/assets/img/hero.jpg" alt="Descripción de la imagen" width="1600" height="900" loading="lazy">
</picture>

Descubre por qué el formato WebP es ideal para mejorar la velocidad y el SEO de tu página web. Te invitamos a leer este artículo: Por Qué Usar el Formato WebP es Mejor para tu Página Web: SEO, Velocidad y Más. En él aprenderás cómo el formato WebP puede optimizar tus imágenes y mejorar la experiencia del usuario.

SVG


<svg width="24" height="24" aria-hidden="true">
    <use href="/assets/svg/icons.svg#mail"></use>
</svg>

Guárdalos en /assets/svg/. Para iconos, puedes usar sprite:

Fuentes

Si usas fuentes externas (Google Fonts o locales):


@font-face {
  font-family: 'Inter';
  src: url('/assets/fonts/Inter.woff2') format('woff2');
  font-display: swap;
}

7. Accesibilidad rápida

Siempre usa alt en imágenes.
Usa encabezados en orden (h1 > h2 > h3).
Asegura contraste suficiente (4.5:1 mínimo en texto normal).
Asegura foco visible en enlaces y botones.
Todo debe funcionar con teclado.

8. SEO básico en sitios estáticos

Cada página debe tener un <title> y <meta description> únicos.
URLs claras (about.html en vez de page2.html).
robots.txt para bots:


User-agent: *
Allow: /
Sitemap: https://yanquirm.dev/sitemap.xml

sitemap.xml con enlaces de todas las páginas.

Es fundamental que comiences a implementar buenas prácticas de SEO desde el inicio de tus proyectos. Lee este artículo: 5 Claves Básicas de SEO para Desarrolladores Web Principiantes, y descubre cómo mejorar la visibilidad de tus sitios web desde el primer momento.

9. Buenas prácticas extra

Nombra imágenes descriptivamente (equipo-2025.jpg mejor que IMG_001.jpg).
Usa validadores:

W3C HTML Validator
WAVE para accesibilidad
PageSpeed Insights para rendimiento.

10. Checklist rápido al publicar

Revisa títulos y descripciones únicas.
Comprime imágenes (usa WebP/AVIF).
Prueba navegación con teclado.
Verifica contraste de colores.
Sube robots.txt y sitemap.xml.
Haz prueba en móviles (viewport, legibilidad, botones accesibles).

Conclusión

Con esto tienes un esqueleto simple y claro, sin necesidad de herramientas de compilación.