| name | minoo:frontend-ssr |
| description | Use when working on Minoo templates, CSS design system, or SSR rendering in templates/, public/css/, or src/Controller/ render methods |
Minoo Frontend / SSR Specialist
Scope
Files: templates/, public/css/*.css, SSR rendering in src/Controller/
Tests: Playwright E2E in e2e/
Directory Layout
templates/
├── layouts/base.html.twig # Page shell (only layout; extended by all pages)
├── pages/<domain>/<view>.html.twig # Route-level templates
│ └── static/ # Static content pages (about, how-it-works, etc.)
├── components/
│ ├── shared/{layout,ui,data,feedback}/ # Cross-domain partials
│ └── domain/<name>/ # Domain-scoped partials
├── email/ # Mail bodies rendered by framework AuthMailer
├── 403.html.twig # Framework hardcodes path — do not move
└── 404.html.twig # Framework hardcodes path — do not move
Framework constraint: vendor/waaseyaa/ssr/src/RenderController.php hardcodes 403.html.twig and 404.html.twig at the templates root. Do not relocate.
Routing
No path-based template auto-resolution. Controllers call $this->twig->render('pages/<domain>/<view>.html.twig', ...) explicitly. Each route in App\Provider\AppServiceProvider maps to a controller method that chooses its template path.
Static pages with no domain logic are served through StaticPageController, which renders templates from pages/static/ or the appropriate pages/<domain>/ folder.
Template Inheritance
All page templates extend layouts/base.html.twig and override blocks:
{% extends "layouts/base.html.twig" %}
{% block title %}Page Title{% endblock %}
{% block content %}
{# Page content here #}
{% endblock %}
Available blocks: title, meta_description, og_title, og_description, og_image, og_type, head, content, scripts.
Component Conventions
Components live under templates/components/:
shared/layout/ — sidebar-nav, location-bar, breadcrumb, hero-imageshared/ui/ — chat, language-switcher, pagination, theme-toggle, user-role-cardshared/data/ — search-result-card, empty-state, protocol-noticeshared/feedback/ — flash-messagesdomain/<name>/ — cards, filters, and domain-scoped partials (events/, teachings/, groups/, people/, businesses/, communities/, feed/, language/, oral-histories/)
Include components with explicit with and only:
{% include "components/domain/events/card.html.twig" with {
title: event.get('title'),
type: event.get('type'),
date: event.get('starts_at'),
url: "/events/" ~ event.get('slug'),
} only %}
CSS Architecture
public/css/minoo.css is a manifest — no rules, only the layer declaration and @import statements.
public/css/
├── minoo.css # Manifest: @layer order + @imports
├── reset.css # @layer reset
├── tokens.css # @layer tokens
├── base.css # @layer base
├── layout.css # @layer layout
├── components.css # @layer components
├── utilities.css # @layer utilities
└── orphans.css # Un-layered rules (font-face, legacy rules, @media print)
Manifest content:
@layer reset, tokens, base, layout, components, utilities;
@import "reset.css";
@import "tokens.css";
@import "base.css";
@import "layout.css";
@import "components.css";
@import "utilities.css";
@import "orphans.css";
orphans.css: Rules that existed outside any @layer block in the pre-split history — @font-face declarations, a few legacy unlayered rule sets, and @media print blocks. Imported after the layered files so they retain highest cascade priority (same behavior as before the split). Do not move rules in or out without understanding the cascade implications.
Layer Contents
| Layer | Purpose |
|---|
reset | Box-sizing, margin reset, media elements, font inheritance |
tokens | Design tokens: colors, typography, spacing, widths, radii, shadows |
base | Body, headings, links, code, lists — use tokens only |
layout | Page shell: header, sidebar, grid surfaces, app shell |
components | Cards, detail views, filters, pagination, domain UI blocks |
utilities | .flow, .flow-lg, .sr-only, single-purpose helpers |
Design Tokens
OKLCH earth / forest / water / sun / berry palette with shadcn-style Tier-2 semantic aliases (--background, --foreground, --muted, --card, --popover, --destructive, --ring, --input). Typography uses fluid clamp() scales; spacing uses a 1.5-ratio fluid scale; widths: --width-prose: 65ch, --width-content: 80rem, --width-narrow: 40rem, --width-card: 25rem.
CSS Conventions
- Logical properties only (
margin-block, padding-inline) — no left/right
gap for sibling spacing- Native CSS nesting
- Container queries on components; media queries reserved for page shell
- No
!important
Cache Busting
layouts/base.html.twig references the manifest with a version query: <link rel="stylesheet" href="/css/minoo.css?v=N">. Bump N after any CSS change.
Component Patterns
Cards: .card with container-type: inline-size. Variants: .card--event, .card--group, .card--community, .card--teaching, .card--language, .card--person, .card--elder, .card--detail, .card--dashboard. Parts: .card__badge, .card__title, .card__meta, .card__body, .card__tags. Grid: .card-grid.
Forms: .form > .form__field > .form__label + .form__input. Error state: .form__input--error + .form__error[role="alert"]. Buttons: .form__submit--primary, --secondary, --danger, --sm.
Buttons: .btn with --primary, --secondary, --accent, --ghost, --lg.
Layout: .flow / .flow-lg for vertical rhythm, .prose for readable text, .content-section for page sections.
Detail pages: .detail > .detail__back, .detail__header, .detail__meta, .detail__body.
Common Twig Patterns
Entity field access via .get():
{{ item.get('title') }}
{% if item.get('status') == 1 %}Published{% endif %}
Active nav via aria-current:
<a href="/events"{% if path starts with '/events' %} aria-current="page"{% endif %}>
Common Mistakes
- Moving 403/404 out of templates root — framework hardcodes these paths; moves break error handling
- Dot notation on entities — use
entity.get('field'), not entity.field
- CSS
left/right — always use logical properties (margin-inline-start, padding-block-end)
margin for spacing — use gap in flex/grid; .flow pattern for vertical stacks- Media queries on components — use container queries (
@container); media queries only for page shell
- Missing
path variable — every SSR controller must pass path in LayoutTwigContext::withAccount(...)
- Editing
minoo.css directly — it's a manifest; add rules to the matching layer file (components.css, layout.css, etc.)
- Moving rules into/out of
orphans.css — unlayered rules outrank all @layer rules; understand the cascade impact before touching
- Forgetting the
?v=N bump — stale CSS after deploy is the #1 "it looks broken" cause
- Duplicate route names in
AppServiceProvider — later registration silently wins. Games use games.<name> for /games/<name> and games.<name>.short for /<name>
Related Specs
docs/specs/frontend-ssr.md — authoritative directory layout, inheritance, CSS architecture, smoke test routes- Framework:
waaseyaa_get_spec api-layer — Response types, RenderController
