Agentic Development

BPL DS produce HTML + CSS sin dependencias de framework, sin build pipeline, y con una API declarativa basada en estándares web. Esas mismas características que lo hacen simple para un humano lo hacen especialmente apto para agentes de IA: el contrato de uso es explícito, verificable y sin ambigüedad.

Por qué los agentes funcionan bien con BPL DS

Un agente que recibe las reglas correctas puede implementar interfaces completas con BPL DS de forma consistente porque:

• El HTML es la API — no hay props, no hay configuración de build, no hay abstracciones de framework que aprender.
• Cada componente tiene documentación en esta web con el HTML exacto a usar y la Public API de customización.
• El estado visual vive en atributos del DOM (aria-selected, hidden, open) — no en clases de JS que el agente podría inventar de formas distintas.
• La customización es predecible: siempre CSS custom properties, siempre el mismo patrón.

Reglas agénticas — listas para copiar

Incluí el siguiente bloque en tu CLAUDE.md, .cursorrules, o system prompt. Define cómo el agente debe usar BPL DS al construir interfaces en tu proyecto.

Para Claude Code (CLAUDE.md)

## BPL DS

Este proyecto usa BPL DS como sistema de diseño. Reglas de uso:

### HTML
- Los componentes son HTML puro con clases CSS. No hay componentes de React, Vue ni Svelte del DS.
- Copiar el HTML de la documentación en https://bpl-ds.bepartnerlabs.com/components/<name>/
- Usar el elemento HTML semántico correcto: `<button>` para acciones, `<a>` para navegación, `<dialog>` para modals.

### CSS y customización
- Los tokens del proyecto están en `src/styles/tokens.css` como custom properties (`--bp-*`).
- Para customizar un componente, usar su Public API: CSS custom properties `--<component>-*` en el elemento root.
  Siempre hacerlo desde una clase CSS, nunca con `style=""` en el HTML.
- Para variaciones visuales: crear clases modificadoras BEM en el CSS del proyecto.

### Estado e interactividad
- El estado visual lo gestiona el CSS leyendo atributos ARIA y propiedades nativas del DOM.
- JS solo para: `dialog.showModal()` / `dialog.close()`, sincronizar `aria-selected`/`aria-expanded`, roving tabindex.
- No aplicar clases de estilo desde JS — aplicar atributos ARIA o propiedades nativas.
- Algunos componentes son Custom Elements (`<bp-dropdown>`, `<bp-table>`). Cargarlos con `<script type="module" src="...">` — sin ese script el HTML se renderiza pero sin interactividad de teclado.

### No hacer
- No usar `style=""` en HTML. Siempre clases CSS o custom properties en stylesheet.
- No inventar clases que no estén en la documentación del DS.
- No añadir dependencias de JS para comportamientos que el HTML nativo ya provee.

Para Cursor (.cursorrules)

# BPL DS usage rules

- Components are HTML + CSS classes. No React/Vue/Svelte wrappers.
- Reference component HTML from the docs site. Do not invent class names.
- Customization uses CSS custom properties (--<component>-*) in a stylesheet class, never inline style="".
- Visual state: CSS reads ARIA attributes and native DOM properties. JS sets aria-selected, aria-expanded,
  hidden, open — it does not set style classes.
- Use semantic HTML: <button> for actions, <a> for navigation, <dialog> for modals.
- No JS for behaviors that native HTML already provides.

Flujo recomendado

1. Describe la interfaz a construir
2. El agente lee los componentes disponibles en los docs
3. El agente genera el HTML con las clases BPL DS correspondientes
4. Para customización: el agente define CSS custom properties en un stylesheet, no inline
5. Para interactividad: el agente copia el snippet JS de la sección JavaScript del componente
6. Verificar en browser — no hay tests de DOM que mockear

Qué puede hacer el agente solo

Con las reglas correctas, el agente puede sin intervención humana:

• Componer layouts con .bp-content-grid y sus zonas (popout, breakout, full-width)
• Implementar cualquier componente del catálogo copiando el HTML de los docs
• Customizar tokens vía Public API en CSS
• Agregar interactividad copiando los snippets JS de cada componente
• Combinar componentes: carousel de cards, modal con form, nav con badges

Qué necesita decisión humana

• Qué elemento HTML usar cuando hay ambigüedad semántica (<dl> vs <div> para tabs de glosario)
• Cuándo construir un componente nuevo vs adaptar uno existente
• Decisiones de contenido y jerarquía (h1 vs h2, qué texto en aria-label)
• Customizaciones que requieren tocar el CSS del DS directamente

Verificación agéntica

La verificación de interfaces BPL DS no requiere un test runner. El agente puede verificar:

• Estructura: el HTML coincide con el patrón documentado (roles, IDs, aria-*)
• Visual: ejecutar pnpm dev y abrir la ruta en el browser
• Accesibilidad: axe-core desde la consola del browser o Lighthouse en DevTools
• Contraste y tokens: CSS custom properties inspeccionables en DevTools sin build adicional