Guías de Diseño para Plugins

Diez guías para construir plugins que se sientan nativos del admin — uso de componentes, soporte de modo oscuro, estados de carga, estados vacíos y patrones de navegación.

Los plugins que siguen estas guías se sienten como una parte natural del admin en lugar de una experiencia externa embebida.

1. Usa la biblioteca de componentes WUI

Los componentes pre-construidos coinciden con el lenguaje de diseño del admin. Úsalos en vez de construir componentes personalizados para patrones comunes — tarjetas, badges, banners, botones y tipografía están todos cubiertos.

2. Sigue el patrón de página

Cada página de plugin debe comenzar con Page y PageHeader:

<Page>
  <PageHeader title="Page Title" description="What this page does" />
  {/* Content */}
</Page>

La descripción es opcional pero ayuda a los comerciantes a entender el propósito de la página de un vistazo.

En tu manifiesto whatalo.app.ts:

Usa títulos de página descriptivos y orientados a la acción
Mantén la primera página como tu dashboard principal
Usa una página de configuración dedicada en lugar de mezclarla con el dashboard
Las etiquetas cortas ayudan cuando el sidebar es estrecho

4. Soporta el modo oscuro

Siempre usa useThemeSync() y referencia tokens CSS --wui-* para los colores. Nunca hardcodees valores hexadecimales — el mismo componente debe verse correcto tanto en modo claro como oscuro.

5. Considera los viewports estrechos

El admin es responsivo. Tu plugin debe adaptarse bien cuando el iframe es estrecho. Prefiere BlockStack (vertical) sobre InlineStack (horizontal) para el contenido principal, ya que los layouts verticales se adaptan mejor a contenedores estrechos.

6. Muestra estados de carga

Siempre renderiza un indicador de carga mientras obtienes datos. Nunca muestres un layout vacío o roto mientras una solicitud está en vuelo:

{loading ? (
  <Spinner />
) : (
  <DataTable data={orders} />
)}

7. Muestra estados vacíos útiles

Cuando una lista o conjunto de datos no tiene elementos, explica el porqué y sugiere un próximo paso:

{orders.length === 0 ? (
  <Banner status="info" title="No orders yet">
    Orders will appear here once merchants start placing them.
  </Banner>
) : (
  <OrderList orders={orders} />
)}

8. Confirma las acciones con feedback

Usa toasts para confirmar que una acción se completó. Nunca dejes al comerciante preguntándose si su acción funcionó:

const handleSave = async () => {
  await saveSettings(data);
  bridge.toast.show("Settings saved", { variant: "success" });
};

9. Mantén la navegación simple

Usa switch(currentPage) para el enrutamiento entre páginas del plugin. React Router y la manipulación de URLs del lado del cliente no son necesarios — el bridge entrega la página actual como una cadena desde el manifiesto.

Cada página debe ser autocontenida y no depender del estado pasado desde otra página.

10. Escribe copy claro

Usa etiquetas de botón orientadas a la acción: "Save changes" no "Submit"
Los títulos de página deben describir lo que hace la página, no lo que es
Usa el locale del comerciante (bridge.locale) al formatear fechas y números
Evita jerga técnica en el texto visible para el usuario