git.admin/roi-theme
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bf304f08fc44de2cf8572565748de04a9261a310
roi-theme/openspec/specs/flujo-componentes/spec.md
FrankZamora bf304f08fc fix(css): centrar verticalmente contenido del hero section 
Agrega propiedades flexbox al contenedor .hero-section para que el
contenido (título y badges) se muestre centrado verticalmente cuando
no hay badges de categorías.

Cambios:
- display: flex
- align-items: center
- justify-content: center

También incluye specs OpenSpec para arquitectura del tema.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-05 14:44:50 -06:00

15 KiB
Raw Blame History

Especificacion de Flujo de Componentes

Purpose

Define el flujo de trabajo de 5 fases para crear componentes en ROITheme, incluyendo convenciones de nomenclatura, estructura de archivos y validacion.

Requirements

Requirement: Nomenclatura NO NEGOCIABLE

The system MUST follow strict naming conventions that are NON-NEGOTIABLE.

Scenario: Nomenclatura de component_name en JSON y BD

  • WHEN se define el nombre del componente en JSON o base de datos
  • THEN DEBE usar kebab-case
  • AND ejemplo: featured-image, hero-section, top-bar

Scenario: Nomenclatura de archivo schema JSON

  • WHEN se crea un archivo de schema JSON
  • THEN el nombre DEBE ser kebab-case
  • AND ejemplo: featured-image.json, hero-section.json

Scenario: Nomenclatura de carpeta de modulo

  • WHEN se crea la carpeta del modulo
  • THEN DEBE usar PascalCase
  • AND ejemplo: FeaturedImage/, HeroSection/, TopBar/

Scenario: Nomenclatura de namespace PHP

  • WHEN se define el namespace PHP
  • THEN DEBE usar PascalCase
  • AND patron: ROITheme[Contexto][Componente][Capa]

Scenario: Nomenclatura de clases Renderer y FormBuilder

  • WHEN se nombran las clases Renderer o FormBuilder
  • THEN DEBEN usar PascalCase
  • AND ejemplo: FeaturedImageRenderer, HeroSectionFormBuilder

Scenario: Conversion kebab-case a PascalCase

  • WHEN se convierte de kebab-case a PascalCase
  • THEN se eliminan los guiones
  • AND se capitaliza cada palabra
  • AND ejemplo: featured-image se convierte en FeaturedImage

Requirement: Fase 1 - Creacion de Schema JSON

The first step MUST be creating the component JSON schema.

Scenario: Ubicacion del schema

  • WHEN se crea un schema JSON
  • THEN DEBE colocarse en Schemas/[nombre-en-kebab-case].json
  • AND ejemplo: Schemas/featured-image.json

Scenario: Campo component_name en schema

  • WHEN se define component_name en el schema
  • THEN DEBE usar kebab-case
  • AND ejemplo: component_name con valor featured-image

Scenario: Fuente del schema

  • WHEN se extrae informacion para el schema
  • THEN DEBE basarse en _planeacion/roi-theme/roi-theme-template/index.html
  • AND DEBEN extraerse TODOS los campos CSS y textos del HTML

Scenario: Campos obligatorios de visibilidad

  • WHEN se crea un schema
  • THEN DEBE incluir is_enabled como boolean
  • AND DEBE incluir show_on_desktop como boolean
  • AND DEBE incluir show_on_mobile como boolean

Scenario: Grupos JSON estandar con priorities

  • WHEN se estructura un schema JSON
  • THEN DEBE organizar campos en los 12 grupos estandar con priorities fijas
  • AND VISIBILITY DEBE tener priority 10
  • AND CONTENT DEBE tener priority 20
  • AND TYPOGRAPHY DEBE tener priority 30
  • AND COLORS DEBE tener priority 40
  • AND SPACING DEBE tener priority 50
  • AND VISUAL_EFFECTS DEBE tener priority 60
  • AND BEHAVIOR DEBE tener priority 70
  • AND LAYOUT DEBE tener priority 80
  • AND LINKS, ICONS, MEDIA, FORMS DEBEN tener priority 90

Scenario: Tipos de campo validos en schema

  • WHEN se define un campo en el schema JSON
  • THEN el type DEBE ser uno de: boolean, text, textarea, url, select, color
  • AND si type es select DEBE incluir array de options
  • AND si type es boolean el default DEBE ser true o false
  • AND si type es color el default DEBE ser formato hexadecimal (#RRGGBB)

Scenario: Campo heading_level para semantica HTML

  • WHEN un componente tiene titulo principal
  • THEN el grupo TYPOGRAPHY DEBE incluir campo heading_level
  • AND heading_level DEBE ser tipo select con options h1, h2, h3, h4, h5, h6
  • AND heading_level es critico para jerarquia semantica y SEO

Scenario: Campos de accesibilidad en MEDIA

  • WHEN un componente tiene imagenes
  • THEN el grupo MEDIA DEBE incluir campo image_alt
  • AND image_alt es obligatorio para accesibilidad (WCAG)
  • WHEN la imagen puede compartirse en redes sociales
  • THEN DEBE incluir campo is_og_image como boolean

Scenario: Campos tipicos del grupo BEHAVIOR

  • WHEN un componente tiene comportamiento interactivo
  • THEN el grupo BEHAVIOR puede incluir is_sticky, sticky_offset, collapse_on_mobile
  • AND para Table of Contents puede incluir generate_jump_links, enable_scrollspy
  • AND para animaciones puede incluir animation_type

Requirement: Fase 2 - Sincronizacion JSON a BD

The second step MUST synchronize the JSON schema with the database.

Scenario: Comando de sincronizacion

  • WHEN se necesita sincronizar un componente
  • THEN ejecutar wp roi-theme sync-component [nombre]
  • AND ejemplo: wp roi-theme sync-component featured-image

Scenario: Tabla destino

  • WHEN se sincroniza
  • THEN los datos van a la tabla wp_roi_theme_component_settings

Scenario: Preservacion de valores

  • WHEN se sincroniza un schema actualizado
  • THEN los valores existentes del usuario DEBEN preservarse
  • AND solo se agregan campos nuevos

Scenario: Conversion de valores para almacenamiento

  • WHEN se sincroniza un campo a BD
  • THEN arrays y objects DEBEN convertirse con json_encode()
  • AND booleans DEBEN convertirse a '1' o '0'
  • AND otros tipos DEBEN convertirse a string con cast

Requirement: Fase 3 - Creacion del Renderer

The third step MUST create the Renderer that converts DB data to HTML + CSS.

Scenario: Ubicacion del Renderer

  • WHEN se crea un Renderer
  • THEN DEBE colocarse en Public/[PascalCase]/Infrastructure/Ui/[PascalCase]Renderer.php
  • AND ejemplo: Public/FeaturedImage/Infrastructure/Ui/FeaturedImageRenderer.php

Scenario: Inyeccion de CSSGeneratorInterface

  • WHEN se implementa un Renderer
  • THEN DEBE inyectar CSSGeneratorInterface via constructor
  • AND NO DEBE tener CSS hardcodeado

Scenario: Generacion de CSS

  • WHEN se genera CSS en el Renderer
  • THEN DEBE usar $this->cssGenerator->generate()
  • AND CERO CSS hardcodeado en el codigo PHP

Scenario: Validacion de visibilidad

  • WHEN el Renderer procesa un componente
  • THEN DEBE validar is_enabled, show_on_desktop, show_on_mobile
  • AND NO renderizar si no cumple condiciones de visibilidad

Scenario: Clases responsive Bootstrap para visibilidad

  • WHEN el Renderer genera HTML para show_on_desktop y show_on_mobile
  • THEN DEBE usar clases Bootstrap d-none, d-lg-block, d-lg-none
  • AND NO DEBE usar CSS custom para visibilidad responsive
  • AND el breakpoint principal es lg (992px)

Scenario: Tabla de decision para visibilidad responsive

  • GIVEN campos show_on_desktop y show_on_mobile del componente
  • WHEN show_on_desktop es false AND show_on_mobile es true
  • THEN aplicar clase d-lg-none (solo visible en mobile)
  • WHEN show_on_desktop es true AND show_on_mobile es false
  • THEN aplicar clases d-none d-lg-block (solo visible en desktop)
  • WHEN show_on_desktop es false AND show_on_mobile es false
  • THEN NO renderizar componente y retornar string vacio
  • WHEN show_on_desktop es true AND show_on_mobile es true
  • THEN NO aplicar clases de visibilidad (visible en ambos)

Scenario: Metodo supports

  • WHEN se implementa el metodo supports()
  • THEN DEBE retornar el nombre en kebab-case
  • AND ejemplo: return 'featured-image'

Requirement: Contrato de CSSGeneratorInterface

The CSS generation service MUST follow a specific contract defined in Shared.

Scenario: Ubicacion de CSSGeneratorInterface

  • WHEN se necesita la interface de generacion CSS
  • THEN DEBE estar en Shared/Domain/Contracts/CSSGeneratorInterface.php

Scenario: Firma del metodo generate

  • WHEN se implementa CSSGeneratorInterface
  • THEN DEBE tener metodo generate(string $selector, array $styles): string
  • AND $selector es el selector CSS (ej: '.navbar')
  • AND $styles es array asociativo de propiedades CSS
  • AND retorna string CSS formateado

Scenario: Conversion de propiedades CSS

  • WHEN CSSGeneratorService procesa array de estilos
  • THEN DEBE convertir snake_case a kebab-case
  • AND ejemplo: background_color se convierte en background-color

Requirement: Fase 4 - Creacion del FormBuilder

The fourth step MUST create the FormBuilder for the admin panel.

Scenario: Ubicacion del FormBuilder

  • WHEN se crea un FormBuilder
  • THEN DEBE colocarse en Admin/[PascalCase]/Infrastructure/Ui/[PascalCase]FormBuilder.php
  • AND ejemplo: Admin/FeaturedImage/Infrastructure/Ui/FeaturedImageFormBuilder.php

Scenario: Inyeccion de AdminDashboardRenderer

  • WHEN se implementa un FormBuilder
  • THEN DEBE inyectar AdminDashboardRenderer

Requirement: Contrato de AdminDashboardRenderer

The admin panel rendering service MUST follow a specific contract.

Scenario: Ubicacion de AdminDashboardRenderer

  • WHEN se necesita el renderer del panel admin
  • THEN DEBE estar en Admin/Shared/Infrastructure/Ui/AdminDashboardRenderer.php

Scenario: Responsabilidad de AdminDashboardRenderer

  • WHEN se usa AdminDashboardRenderer
  • THEN DEBE generar el HTML de controles de formulario
  • AND DEBE aplicar el Design System del admin (gradiente, bordes)
  • AND DEBE usar Bootstrap 5 form controls

Scenario: Design System del admin

  • WHEN se implementa la UI del admin
  • THEN DEBE usar gradiente #0E2337 a #1e3a5f
  • AND borde naranja #FF8600
  • AND Bootstrap 5 form controls

Scenario: Registro en getComponents

  • WHEN se registra el FormBuilder
  • THEN DEBE registrarse en getComponents() con ID en kebab-case
  • AND ejemplo: 'featured-image'

Requirement: Fase 5 - Validacion de Arquitectura

The fifth and final step MUST validate the component architecture.

Scenario: Comando de validacion

  • WHEN se necesita validar un componente
  • THEN ejecutar php Shared/Infrastructure/Scripts/validate-architecture.php [nombre]
  • AND ejemplo: php Shared/Infrastructure/Scripts/validate-architecture.php featured-image

Scenario: Elementos validados

  • WHEN se ejecuta la validacion
  • THEN DEBE validar estructura de carpetas
  • AND DEBE validar schema JSON
  • AND DEBE validar datos en BD
  • AND DEBE validar Renderer
  • AND DEBE validar FormBuilder
  • AND DEBE validar cumplimiento SOLID

Requirement: Estructura de Archivos por Componente

A complete component MUST have a specific file structure.

Scenario: Estructura de componente en Public

  • GIVEN un componente FeaturedImage en Public
  • WHEN esta completo
  • THEN DEBE existir Public/FeaturedImage/Infrastructure/Ui/FeaturedImageRenderer.php

Scenario: Estructura de componente en Admin

  • GIVEN un componente FeaturedImage en Admin
  • WHEN esta completo
  • THEN DEBE existir Admin/FeaturedImage/Infrastructure/Ui/FeaturedImageFormBuilder.php

Scenario: Archivo schema

  • GIVEN un componente FeaturedImage
  • WHEN se necesita el schema
  • THEN DEBE existir en Schemas/featured-image.json

Requirement: Variables CSS del Tema

Code MUST use the theme CSS variables.

Scenario: Variables de color disponibles

  • WHEN se necesitan colores
  • THEN DEBEN usarse las variables como --color-navy-dark y --color-orange-primary

Scenario: Prohibicion de CSS hardcodeado

  • WHEN se genera CSS
  • THEN NO DEBE haber colores hardcodeados en PHP
  • AND DEBE usarse CSSGeneratorService

Requirement: Reglas NO Negociables del Flujo

These rules MUST always be followed, without exceptions.

Scenario: Creacion de archivos

  • WHEN se van a crear archivos para un componente
  • THEN DEBE leerse primero el template HTML
  • AND NO crear archivos sin esa referencia

Scenario: Campos de visibilidad

  • WHEN se crea un schema
  • THEN NO DEBE omitirse ninguno de los 3 campos obligatorios de visibilidad

Scenario: CSS en Renderers

  • WHEN se implementa un Renderer
  • THEN NO DEBE haber CSS inline
  • AND todo via CSSGeneratorService

Scenario: Instanciacion de servicios

  • WHEN se necesita un servicio
  • THEN NO instanciar directamente con new Service()
  • AND DEBE usarse Inyeccion de Dependencias

Scenario: Modificacion de campos en BD

  • WHEN se necesita modificar campos
  • THEN NO modificar campos en BD manualmente
  • AND modificar el schema JSON y sincronizar

Scenario: Validacion de arquitectura

  • WHEN se completa un componente
  • THEN NO saltarse la validacion de arquitectura
  • AND ejecutar validate-architecture.php

Scenario: Fases completas

  • WHEN se crea un componente
  • THEN NO crear componentes sin completar las 5 fases
  • AND cada fase es obligatoria

Requirement: Comandos WP-CLI

WP-CLI commands MUST be executed with the correct configuration.

Scenario: Ubicacion de WP-CLI

  • WHEN se necesita ejecutar WP-CLI
  • THEN usar C:\xampp\php_8.0.30_backup\wp-cli.phar

Scenario: Sincronizar un componente

  • WHEN se sincroniza un componente especifico
  • THEN ejecutar powershell -Command "php 'C:\xampp\php_8.0.30_backup\wp-cli.phar' roi-theme sync-component [nombre]"

Scenario: Sincronizar todos los componentes

  • WHEN se sincroniza todo
  • THEN ejecutar powershell -Command "php 'C:\xampp\php_8.0.30_backup\wp-cli.phar' roi-theme sync-all-components"

Requirement: Flujo de 5 Fases Secuencial

Component creation MUST follow the exact sequence.

Scenario: Flujo completo de 5 fases

  • WHEN se crea un nuevo componente
  • THEN Fase 1 es crear Schema JSON en Schemas/[nombre].json
  • AND Fase 2 es sincronizar con wp roi-theme sync-component [nombre]
  • AND Fase 3 es crear Renderer en Public/[Nombre]/Infrastructure/Ui/[Nombre]Renderer.php
  • AND Fase 4 es crear FormBuilder en Admin/[Nombre]/Infrastructure/Ui/[Nombre]FormBuilder.php
  • AND Fase 5 es validar con validate-architecture.php [nombre]

Scenario: No saltar fases

  • WHEN se desarrolla un componente
  • THEN NO se DEBE saltar ninguna fase
  • AND cada fase depende de la anterior
  • AND la validacion final es obligatoria

Requirement: Checklist de Componente Completo

A component MUST pass the checklist to be considered complete.

Scenario: Checklist de archivos

  • WHEN se verifica un componente
  • THEN DEBE existir Schemas/[nombre-kebab].json
  • AND DEBE existir Public/[NombrePascal]/Infrastructure/Ui/[NombrePascal]Renderer.php
  • AND DEBE existir Admin/[NombrePascal]/Infrastructure/Ui/[NombrePascal]FormBuilder.php

Scenario: Checklist de codigo

  • WHEN se verifica el codigo
  • THEN schema tiene los 3 campos de visibilidad
  • AND Renderer inyecta CSSGeneratorInterface
  • AND Renderer no tiene CSS hardcodeado
  • AND supports() retorna kebab-case
  • AND FormBuilder registrado con ID kebab-case
  • AND validacion de arquitectura pasa

Scenario: Checklist de BD

  • WHEN se verifica la base de datos
  • THEN datos sincronizados en wp_roi_theme_component_settings
  • AND component_name en kebab-case
Reference in New Issue View Git Blame Copy Permalink