Clarify l_ui_head guidance: steer styling to overrides/app stylesheet

[thomasgallagher]

l_ui_head's inline <style> example led host-app LLMs to dump all custom CSS into the head as raw CSS. Reframe the advice (skill, README, dummy docs) so l_ui_head reads as arbitrary head content - scripts, inline page-specific <script>, meta tags, preload hints, stylesheet links - with styling advised toward layered_ui_overrides.css (layered-ui token/ component overrides) or the host app stylesheet. Per-request theming is shown as a Rails-served stylesheet link. Advisory, not prohibitive.

[claude]

Review

Documentation-only PR that reframes content_for :l_ui_head from a per-tenant theming slot to a general head-injection slot, steering styling toward the overrides file or a controller-served stylesheet.

Issues

Severity	File	Line(s)	Description
MEDIUM	README.md	120, 130–138	Line 120 describes the new stylesheet_link_tag pattern as "CSP-friendly", but the immediately following unchanged CSP block (130–138) shows <style nonce=…> as the CSP solution without clarifying that the new primary pattern already satisfies style-src 'self' without a nonce. A reader following the new recommendation may be confused by the juxtaposition - either wondering whether their stylesheet link also needs a nonce, or missing the CSP section entirely because it appears to describe a different pattern.

Verdict

🟧 Ship (with known minor issues) - The reframing is correct and the security posture improves by steering away from inline style interpolation. The CSP section should be updated to note that the stylesheet_link_tag approach is already style-src 'self' compatible, which would make the existing nonce guidance clearly applicable only to users who choose inline <style> blocks.

[claude]

Review

Documentation-only PR that reframes content_for :l_ui_head guidance: broadens the usage description to arbitrary head content, steers styling to the overrides file or app stylesheet, and replaces the inline <style> example with a Rails-served stylesheet link for per-tenant theming.

Issues

Severity	File	Line(s)	Description
MEDIUM	test/dummy/app/views/pages/layout_head.html.erb	26-27	The code example uses # as a comment character inside what is presented as CSS content. # is not valid CSS comment syntax (CSS uses /* */). Developers copying this snippet would get a parse error or silent mismatch. Consider moving the annotation outside the <pre> block as a prose paragraph, or using /* the controller renders CSS... */ inside the block.

Verdict

🟧 Ship (with known minor issues) - the reframing is correct and the security note is preserved; one code example uses invalid CSS comment syntax that could trip up copy-paste users.

[claude]

Review

Documentation-only PR that reframes guidance away from inline <style> blocks toward controller-served stylesheets and proper CSS files, motivated by LLMs (and presumably humans) misusing the slot to dump all custom CSS into the head.

No issues found. The security warning is preserved and moved to an appropriate place on the dummy page; the CSP/Turbo explanations are retained and consolidated. The updated advice is sound and internally consistent across all three changed files.

Verdict

✅ Ship