ADR-0007: Render YourBOX Frontend With Twig, Tailwind CSS And Stimulus

Status

Accepted

Context

The current YourBOX frontend mixes server rendered PHP, jQuery, hand-written CSS files per page and inline JavaScript that builds dynamic HTML inside PHP heredoc strings. Each page loads a separate stylesheet, the jQuery file is a vendored copy of 3.5.1 from 2020, and the search results page literally writes the rendered HTML to disk to cache it.

The frontend rewrite targets Tailwind CSS for styling, a clean separation between templates and view logic via Twig, and a thin progressive enhancement layer for interactivity. The other applications in the workspace pick React for SPA work, but yourbox does not require a full SPA: every page is already server rendered, navigation is page based, and Turbo plus Stimulus handle the interactive surface.

Decision

YourBOX renders its HTML through Twig templates served by the Symfony controllers introduced in ADR-0002. Templates live under app/templates/<context>/<action>.html.twig and follow the bounded contexts from ADR-0006. A base.html.twig carries the shell, the menu and the flash messages; concrete pages extend it and only fill the content block.

Styling uses Tailwind CSS v4 via the Symfony AssetMapper integration. Custom design tokens live in app/assets/styles/tokens.css and the build pipeline runs tailwindcss at container build time. The hand-written CSS files under YourBOX/src/assets/stylesheets/ are removed when the corresponding route is rewritten. There is no Bootstrap, Foundation or other UI framework: Tailwind utilities plus a few component classes carry the entire styling.

Interactivity uses Stimulus controllers via the Symfony StimulusBundle. Controllers handle the cases that today rely on jQuery: the search box auto submit, the comment reply toggle, the like and dislike buttons, the video player keyboard shortcuts and the upload progress bar. There is no jQuery, no Vue or React for the yourbox surface. The Stimulus controllers live under app/assets/controllers/ and are mapped automatically by the Symfony StimulusBundle.

Form handling uses Symfony Forms with Twig form themes. CSRF protection is enabled by default for every state changing endpoint.

For richer client side behavior, Symfony UX Turbo is enabled on the catalog and comment threads so that link navigation feels instant without writing a SPA.

Consequences

• The application keeps a single rendering pipeline. Adding a page is a controller plus a Twig template, not a new build target.
• Styling becomes consistent. Tailwind’s utility approach removes the per page stylesheet pattern; the bundle size shrinks because unused classes are tree shaken by the Tailwind compiler.
• Stimulus controllers are testable through the Symfony UX testing helpers and through Jest for pure logic. The jQuery global namespace is gone.
• Existing CSS is removed page by page as routes are rewritten. The legacy pages keep their inline CSS during the transition, which is acceptable while the strangler bundle owns them.
• A small client side build is added to the Docker image. The build stage runs tailwindcss --minify and emits the bundle into app/public/assets/.
• Accessibility audits become easier because the markup is consistent and component classes carry semantic intent.