Implementar modo oscuro con Claude Code

Empieza por el riesgo de producto

Implementar modo oscuro con Claude Code no consiste en pedir a Claude Code una pantalla más vistosa. El objetivo práctico es mejorar una interfaz real sin romper conversión, lectura, accesibilidad ni diseño móvil. En producción importan detalles poco brillantes: estados vacíos, carga, errores, foco de teclado, textos largos, anuncios, bloques de código y posición del CTA.

Lee también claude code design system, claude code accessibility, claude code code review. Para las referencias oficiales usa Claude Code docs, MDN prefers-color-scheme, MDN color-scheme, WCAG contrast. La instrucción a Claude Code debe incluir objetivo, límites, use case, pitfall y verificación.

Prompt recomendado

Implementa esta mejora con el cambio seguro más pequeño.
Respeta componentes existentes, tokens de diseño y rutas.
Cubre use case, pitfall, accesibilidad, móvil y estados de error.
Devuelve código copiable y una review checklist.

Use case checklist

1. Landing pages y artículos donde el lector debe encontrar el siguiente paso sin perder confianza.
2. Dashboards SaaS con estados de carga, vacío, error y éxito.
3. Flujos de compra, registro y consulta donde el botón principal debe seguir dominando.
4. Revisión en equipo, donde Claude Code entrega código y criterios de verificación.

Código de implementación

:root {
  color-scheme: light;
  --color-page: #ffffff;
  --color-surface: #f8fafc;
  --color-text: #0f172a;
  --color-muted: #475569;
  --color-border: #dbe3ef;
  --color-link: #2563eb;
  --color-focus: #f59e0b;
}

[data-theme="dark"] {
  color-scheme: dark;
  --color-page: #0b1120;
  --color-surface: #111827;
  --color-text: #f8fafc;
  --color-muted: #cbd5e1;
  --color-border: #334155;
  --color-link: #93c5fd;
  --color-focus: #fbbf24;
}

body {
  background: var(--color-page);
  color: var(--color-text);
}

:focus-visible {
  outline: 3px solid var(--color-focus);
  outline-offset: 3px;
}

const storageKey = "theme";
const root = document.documentElement;
const stored = localStorage.getItem(storageKey);
const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
const theme = stored === "light" || stored === "dark" ? stored : prefersDark ? "dark" : "light";

root.dataset.theme = theme;

type Theme = "light" | "dark" | "system";

export function ThemeToggle({ value, onChange }: { value: Theme; onChange: (theme: Theme) => void }) {
  return (
    <fieldset aria-label="Theme">
      {(["light", "dark", "system"] as const).map((theme) => (
        <button
          key={theme}
          type="button"
          aria-pressed={value === theme}
          onClick={() => onChange(theme)}
        >
          {theme}
        </button>
      ))}
    </fieldset>
  );
}

Pitfall checklist

• Optimizar solo para la captura de pantalla puede empeorar el recorrido real.
• Depender solo del color reduce la accesibilidad.
• No probar a 375px puede crear scroll horizontal en móvil.
• Ignorar datos vacíos, etiquetas largas y red lenta provoca errores reales.
• Permitir cambios no relacionados aumenta el coste de revisión.

Verificación

Pide a Claude Code una segunda pasada solo de review. Debe listar archivos cambiados, riesgos, comprobaciones de navegador y pruebas manuales. Después revisa la página en móvil, confirma que no hay overflow, que el bloque de código se desplaza, que el CTA sigue visible y que el foco se ve.

Ángulo de monetización

Este trabajo afecta anuncios, tarjetas de producto, enlaces de consulta, tablas de precios y formularios. Si quieres aplicarlo en un repositorio real, la página de formación y consultoría Claude Code convierte estas prácticas en un flujo repetible.

Notas extra de revisión

• Compara capturas antes y después, revisando CTA, anuncios, texto, formularios y bloques de código.
• Pregunta a Claude Code qué se puede eliminar, qué nombres no encajan y qué supuestos son arriesgados.
• Antes de desplegar, prueba móvil, escritorio, teclado, red lenta, datos vacíos y recarga.

Nota de prueba práctica

Probé el patrón en tres pasos: implementación, review y verificación móvil. El cambio fue más fácil de revisar que un rediseño grande y permitió detectar problemas antes del despliegue. En modo oscuro, lo que más problemas evita es declarar color-scheme y leer la preferencia del sistema antes de pintar, para que no aparezca un destello claro durante la hidratación. También conviene comprobar el contraste de texto, enlaces y foco en los dos temas, porque un color que funciona en claro puede quedar ilegible en oscuro.