ldraney/pal-enterprises

Fork 0

Remove Tailwind, implement plain CSS design system #15

Merged

forgejo_admin merged 1 commit from 10-remove-tailwind-plain-css into main

2026-05-10 02:45:03 +00:00

forgejo_admin commented

2026-05-10 02:40:14 +00:00

Contributor

Summary

Tailwind v4's content scanner fails during Docker production builds, producing a 4.5KB CSS with all utility classes purged
Replace Tailwind with a static plain CSS design system served by Propshaft -- zero build steps, zero compilation
All CSS follows ror-css-guide conventions: design tokens in :root, mobile-first with 600px breakpoint, semantic BEM-lite naming

Changes

Gemfile / Gemfile.lock -- removed tailwindcss-rails gem and all transitive dependencies
app/assets/tailwind/application.css -- deleted (was @import "tailwindcss")
app/assets/builds/.keep -- deleted (no longer needed without Tailwind build output)
app/assets/stylesheets/application.css -- full design system: tokens in :root, reset, layout, navbar, flash messages, hero, cards, buttons, forms, login, dashboard components
app/views/layouts/application.html.erb -- replaced Tailwind utility classes with semantic classes, switched stylesheet tag from :app to "application"
app/views/pages/home.html.erb -- semantic classes (.hero, .card-grid, .card, .section-heading)
app/views/contacts/_form.html.erb -- .form > .field pattern per CSS guide
app/views/contacts/new.html.erb -- .contact-page wrapper
app/views/sessions/new.html.erb -- .login-page with .btn .btn-primary .btn-lg
app/views/dashboard/index.html.erb -- .dashboard-grid, .dashboard-card, .is-success state
Procfile.dev -- removed css: bin/rails tailwindcss:watch
README.md -- updated stack table from "Tailwind" to "plain CSS"

Test Plan

docker build -t pal-enterprises . succeeds (no Tailwind build step needed)
Landing page renders hero, 3 feature cards, contact form at 390px and 600px+
Contact page renders form with labels, inputs, submit button
Login page renders styled Keycloak sign-in button
Dashboard renders 2-column card grid after authentication
Flash messages render styled for both notice and alert
Zero hardcoded hex values outside :root tokens

Review Checklist

Passed automated review-fix loop
No secrets committed
No unnecessary file changes
Commit messages are descriptive

Closes #10
pal-enterprises -- the project this work belongs to

## Summary - Tailwind v4's content scanner fails during Docker production builds, producing a 4.5KB CSS with all utility classes purged - Replace Tailwind with a static plain CSS design system served by Propshaft -- zero build steps, zero compilation - All CSS follows ror-css-guide conventions: design tokens in `:root`, mobile-first with 600px breakpoint, semantic BEM-lite naming ## Changes - `Gemfile` / `Gemfile.lock` -- removed `tailwindcss-rails` gem and all transitive dependencies - `app/assets/tailwind/application.css` -- deleted (was `@import "tailwindcss"`) - `app/assets/builds/.keep` -- deleted (no longer needed without Tailwind build output) - `app/assets/stylesheets/application.css` -- full design system: tokens in `:root`, reset, layout, navbar, flash messages, hero, cards, buttons, forms, login, dashboard components - `app/views/layouts/application.html.erb` -- replaced Tailwind utility classes with semantic classes, switched stylesheet tag from `:app` to `"application"` - `app/views/pages/home.html.erb` -- semantic classes (`.hero`, `.card-grid`, `.card`, `.section-heading`) - `app/views/contacts/_form.html.erb` -- `.form > .field` pattern per CSS guide - `app/views/contacts/new.html.erb` -- `.contact-page` wrapper - `app/views/sessions/new.html.erb` -- `.login-page` with `.btn .btn-primary .btn-lg` - `app/views/dashboard/index.html.erb` -- `.dashboard-grid`, `.dashboard-card`, `.is-success` state - `Procfile.dev` -- removed `css: bin/rails tailwindcss:watch` - `README.md` -- updated stack table from "Tailwind" to "plain CSS" ## Test Plan - [ ] `docker build -t pal-enterprises .` succeeds (no Tailwind build step needed) - [ ] Landing page renders hero, 3 feature cards, contact form at 390px and 600px+ - [ ] Contact page renders form with labels, inputs, submit button - [ ] Login page renders styled Keycloak sign-in button - [ ] Dashboard renders 2-column card grid after authentication - [ ] Flash messages render styled for both `notice` and `alert` - [ ] Zero hardcoded hex values outside `:root` tokens ## Review Checklist - [ ] Passed automated review-fix loop - [ ] No secrets committed - [ ] No unnecessary file changes - [ ] Commit messages are descriptive ## Related Notes - Closes #10 - `pal-enterprises` -- the project this work belongs to

forgejo_admin added 1 commit

2026-05-10 02:40:14 +00:00

Remove Tailwind CSS, implement plain CSS design system (#10 ) e3b209b0af

Tailwind v4 content scanner fails during Docker production builds,
producing a 4.5KB CSS file with all utility classes purged. Rather
than fix the build pipeline, switch to static CSS served by Propshaft
with zero build steps.

- Remove tailwindcss-rails gem and all Tailwind asset files
- Create design token system in :root variables (ror-css-guide conventions)
- Replace all Tailwind utility classes with semantic component classes
- Mobile-first layout with single 600px breakpoint
- Flash messages styled for notice and alert types
- Forms use .form > .field pattern per CSS guide
- Remove Tailwind watcher from Procfile.dev

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

forgejo_admin commented

2026-05-10 02:41:06 +00:00

Author

Contributor

QA Review -- PR #15

Tailwind Removal

Gemfile: tailwindcss-rails removed, no residual gem references
Gemfile.lock: all tailwindcss-rails and tailwindcss-ruby entries removed (GEM, DEPENDENCIES, CHECKSUMS sections)
app/assets/tailwind/application.css deleted
app/assets/builds/.keep deleted
Procfile.dev: css: bin/rails tailwindcss:watch line removed
No remaining tailwind string in any .rb, .erb, .css, or .yml file

CSS Guide Compliance (ror-css-guide)

All colors use var(--token) -- zero hardcoded hex outside :root
Design tokens match spec: --color-accent: #0366d6, --max-width: 48rem, Atkinson Hyperlegible font
Mobile-first layout with single @media (min-width: 600px) breakpoint
CSS comments mark every component boundary with partial/view paths
Forms use .form > .field pattern -- no classes on individual inputs
Semantic BEM-lite naming (.navbar-brand, .card-title, .dashboard-card)
No Sass, no PostCSS, no build step -- static CSS served by Propshaft

View Migrations

layouts/application.html.erb: Tailwind utilities replaced with .navbar, .container, .flash classes. Stylesheet tag fixed from :app to "application" (Propshaft convention)
pages/home.html.erb: .hero, .card-grid, .card, .section-heading
contacts/_form.html.erb: .form > .field pattern, .btn .btn-primary .btn-full
contacts/new.html.erb: .contact-page wrapper
sessions/new.html.erb: .login-page, .btn .btn-primary .btn-lg
dashboard/index.html.erb: .dashboard-grid, .dashboard-card, .is-success state class

Constraints Respected

No Ruby code changes (controllers, models, routes untouched)
No Sass/PostCSS/build tooling added
No JavaScript/Stimulus changes
README updated to reflect "plain CSS" in stack table

Note

Gemfile.lock was manually edited (not regenerated via bundle install) due to missing native dependencies in the build environment. The Docker build will regenerate a correct lockfile via bundle install during image creation. This is acceptable for this PR.

VERDICT: PASS

## QA Review -- PR #15 ### Tailwind Removal - Gemfile: `tailwindcss-rails` removed, no residual gem references - Gemfile.lock: all `tailwindcss-rails` and `tailwindcss-ruby` entries removed (GEM, DEPENDENCIES, CHECKSUMS sections) - `app/assets/tailwind/application.css` deleted - `app/assets/builds/.keep` deleted - `Procfile.dev`: `css: bin/rails tailwindcss:watch` line removed - No remaining `tailwind` string in any `.rb`, `.erb`, `.css`, or `.yml` file ### CSS Guide Compliance (ror-css-guide) - All colors use `var(--token)` -- zero hardcoded hex outside `:root` - Design tokens match spec: `--color-accent: #0366d6`, `--max-width: 48rem`, Atkinson Hyperlegible font - Mobile-first layout with single `@media (min-width: 600px)` breakpoint - CSS comments mark every component boundary with partial/view paths - Forms use `.form > .field` pattern -- no classes on individual inputs - Semantic BEM-lite naming (`.navbar-brand`, `.card-title`, `.dashboard-card`) - No Sass, no PostCSS, no build step -- static CSS served by Propshaft ### View Migrations - `layouts/application.html.erb`: Tailwind utilities replaced with `.navbar`, `.container`, `.flash` classes. Stylesheet tag fixed from `:app` to `"application"` (Propshaft convention) - `pages/home.html.erb`: `.hero`, `.card-grid`, `.card`, `.section-heading` - `contacts/_form.html.erb`: `.form > .field` pattern, `.btn .btn-primary .btn-full` - `contacts/new.html.erb`: `.contact-page` wrapper - `sessions/new.html.erb`: `.login-page`, `.btn .btn-primary .btn-lg` - `dashboard/index.html.erb`: `.dashboard-grid`, `.dashboard-card`, `.is-success` state class ### Constraints Respected - No Ruby code changes (controllers, models, routes untouched) - No Sass/PostCSS/build tooling added - No JavaScript/Stimulus changes - README updated to reflect "plain CSS" in stack table ### Note - `Gemfile.lock` was manually edited (not regenerated via `bundle install`) due to missing native dependencies in the build environment. The Docker build will regenerate a correct lockfile via `bundle install` during image creation. This is acceptable for this PR. ### VERDICT: PASS

forgejo_admin commented

2026-05-10 02:43:31 +00:00

Author

Contributor

PR #15 Review

DOMAIN REVIEW

Tech stack: Ruby on Rails 8.1, ERB views, plain CSS (Propshaft), no JS framework changes.

This is a CSS-only refactor: replacing Tailwind utility classes with a semantic plain CSS design system. The domain checklist is CSS/frontend quality.

CSS Quality Assessment

The CSS design system is well-structured and follows the conventions documented in arch-rails-app:

Design tokens defined in :root -- all colors, spacing, fonts, radii use custom properties. No hardcoded hex values outside :root. This is correct.
Mobile-first with a single 600px breakpoint, consistent across .hero-title, .card-grid, and .dashboard-grid. Matches the documented convention.
Component sections are clearly delineated with comment blocks referencing the corresponding view partials (View: pages/home.html.erb, etc.). Good for maintainability.
Semantic BEM-lite naming (.card-title, .dashboard-card-link, .flash-notice, .btn-primary) is consistent throughout.
Spacing uses only --spacing-* tokens. No magic pixel values.
One CSS file served by Propshaft -- zero build steps. Solves the root cause (Tailwind v4 content scanner failing during Docker prod builds).

Minor CSS observations (non-blocking):

--max-width: 48rem replaces the old Tailwind max-w-5xl (64rem). This is a deliberate narrowing of the content area from 1024px to 768px. Not a bug -- just a design decision worth noting since it significantly changes the layout feel on wide screens.
box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08) appears in .navbar, .card, and .dashboard-card. Could be extracted to a --shadow token for DRY consistency, but this is not a blocker for a CSS file of this size.
The reset (*, *::before, *::after { ... }) removes all default list markers and margins globally. This is fine since the app controls all rendering, but worth noting for future contributors.

View Template Assessment

All ERB views are cleanly converted from Tailwind utility classes to semantic classes. The 1:1 mapping is complete:

layouts/application.html.erb -- layout, navbar, flash messages all use semantic classes
pages/home.html.erb -- hero, card-grid, section-heading
contacts/_form.html.erb -- .form > .field pattern with proper .actions wrapper
sessions/new.html.erb -- .login-page with reusable .btn classes
dashboard/index.html.erb -- .dashboard-grid, .dashboard-card, .is-success state modifier

The stylesheet_link_tag correctly changes from :app (Tailwind bundle name) to "application" (Propshaft default). This is the critical fix.

Gemfile/Lockfile

tailwindcss-rails and all transitive deps (tailwindcss-ruby platform variants) cleanly removed from both Gemfile and Gemfile.lock. The Procfile.dev correctly drops the css: bin/rails tailwindcss:watch line.

Accessibility

No regressions detected. The original Tailwind-based views had no ARIA attributes, and neither do the new ones. Focus styles are present on form inputs (:focus with box-shadow outline). This is acceptable for the current state of the app but should be addressed as the app matures.

BLOCKERS

None.

On test coverage: This PR has no automated tests, but this is not a blocker for the following reasons:

The project has explicitly opted out of test infrastructure (rails/test_unit/railtie is commented out in config/application.rb, no test/ or spec/ directory exists).
The changes are pure CSS and ERB template class renaming -- no Ruby logic, no controller changes, no model changes, no route changes.
The PR body includes a manual visual Test Plan with 7 checkboxes covering all affected pages and viewports.
Adding a test framework is a separate concern (and would be scope creep for this ticket).

On secrets: No secrets, credentials, API keys, or .env files in the diff.

On security: No user input handling changes. No auth logic changes. No SQL or XSS surface introduced.

NITS

Shadow token extraction -- The rgba(0, 0, 0, 0.08) shadow value is repeated 3 times. Consider adding --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.08) to :root and referencing it. Low priority.
max-width narrowing -- --max-width: 48rem is significantly narrower than the previous max-w-5xl (64rem). If this was intentional, no action needed. If it should match the old width, update to 64rem.
Font loading -- --font-body references 'Atkinson Hyperlegible' but there is no @font-face declaration or Google Fonts import in the CSS or layout. The font will silently fall back to system-ui. If Atkinson Hyperlegible is desired, a font import should be added in a follow-up.

SOP COMPLIANCE

Branch named after issue (10-remove-tailwind-plain-css references issue #10)
PR body follows template (Summary, Changes, Test Plan, Review Checklist, Related Notes all present)
Related Notes references pal-enterprises project and Closes #10
No secrets committed
No unnecessary file changes -- all 13 changed files are directly related to the Tailwind removal
Commit messages -- single PR, descriptive title
Related Notes does not reference a plan slug (no plan note found for this ticket -- minor gap)

PROCESS OBSERVATIONS

Change failure risk: LOW. This is a pure presentational change. No Ruby logic, no database, no auth flow touched. The worst failure mode is visual regression, which the manual Test Plan covers.
Deployment impact: This unblocks production Docker builds since the Tailwind content scanner was the root cause of broken CSS in prod. Merging this should fix the 4.5KB purged CSS issue documented in arch-rails-app.
Documentation: The arch-rails-app note in pal-e-docs still lists CSS as "Tailwind (broken)" -- should be updated post-merge to reflect plain CSS.
CI note: The GitHub Actions CI (ci.yml) does not reference Tailwind directly, so no CI changes needed. The scan_ruby, scan_js, and lint jobs should pass without modification.

VERDICT: APPROVED

## PR #15 Review ### DOMAIN REVIEW **Tech stack:** Ruby on Rails 8.1, ERB views, plain CSS (Propshaft), no JS framework changes. This is a CSS-only refactor: replacing Tailwind utility classes with a semantic plain CSS design system. The domain checklist is CSS/frontend quality. **CSS Quality Assessment** The CSS design system is well-structured and follows the conventions documented in `arch-rails-app`: - Design tokens defined in `:root` -- all colors, spacing, fonts, radii use custom properties. No hardcoded hex values outside `:root`. This is correct. - Mobile-first with a single 600px breakpoint, consistent across `.hero-title`, `.card-grid`, and `.dashboard-grid`. Matches the documented convention. - Component sections are clearly delineated with comment blocks referencing the corresponding view partials (`View: pages/home.html.erb`, etc.). Good for maintainability. - Semantic BEM-lite naming (`.card-title`, `.dashboard-card-link`, `.flash-notice`, `.btn-primary`) is consistent throughout. - Spacing uses only `--spacing-*` tokens. No magic pixel values. - One CSS file served by Propshaft -- zero build steps. Solves the root cause (Tailwind v4 content scanner failing during Docker prod builds). **Minor CSS observations (non-blocking):** 1. `--max-width: 48rem` replaces the old Tailwind `max-w-5xl` (64rem). This is a deliberate narrowing of the content area from 1024px to 768px. Not a bug -- just a design decision worth noting since it significantly changes the layout feel on wide screens. 2. `box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08)` appears in `.navbar`, `.card`, and `.dashboard-card`. Could be extracted to a `--shadow` token for DRY consistency, but this is not a blocker for a CSS file of this size. 3. The reset (`*, *::before, *::after { ... }`) removes all default list markers and margins globally. This is fine since the app controls all rendering, but worth noting for future contributors. **View Template Assessment** All ERB views are cleanly converted from Tailwind utility classes to semantic classes. The 1:1 mapping is complete: - `layouts/application.html.erb` -- layout, navbar, flash messages all use semantic classes - `pages/home.html.erb` -- hero, card-grid, section-heading - `contacts/_form.html.erb` -- `.form > .field` pattern with proper `.actions` wrapper - `sessions/new.html.erb` -- `.login-page` with reusable `.btn` classes - `dashboard/index.html.erb` -- `.dashboard-grid`, `.dashboard-card`, `.is-success` state modifier The `stylesheet_link_tag` correctly changes from `:app` (Tailwind bundle name) to `"application"` (Propshaft default). This is the critical fix. **Gemfile/Lockfile** `tailwindcss-rails` and all transitive deps (`tailwindcss-ruby` platform variants) cleanly removed from both `Gemfile` and `Gemfile.lock`. The `Procfile.dev` correctly drops the `css: bin/rails tailwindcss:watch` line. **Accessibility** No regressions detected. The original Tailwind-based views had no ARIA attributes, and neither do the new ones. Focus styles are present on form inputs (`:focus` with `box-shadow` outline). This is acceptable for the current state of the app but should be addressed as the app matures. ### BLOCKERS None. **On test coverage:** This PR has no automated tests, but this is not a blocker for the following reasons: - The project has explicitly opted out of test infrastructure (`rails/test_unit/railtie` is commented out in `config/application.rb`, no `test/` or `spec/` directory exists). - The changes are pure CSS and ERB template class renaming -- no Ruby logic, no controller changes, no model changes, no route changes. - The PR body includes a manual visual Test Plan with 7 checkboxes covering all affected pages and viewports. - Adding a test framework is a separate concern (and would be scope creep for this ticket). **On secrets:** No secrets, credentials, API keys, or `.env` files in the diff. **On security:** No user input handling changes. No auth logic changes. No SQL or XSS surface introduced. ### NITS 1. **Shadow token extraction** -- The `rgba(0, 0, 0, 0.08)` shadow value is repeated 3 times. Consider adding `--shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.08)` to `:root` and referencing it. Low priority. 2. **`max-width` narrowing** -- `--max-width: 48rem` is significantly narrower than the previous `max-w-5xl` (64rem). If this was intentional, no action needed. If it should match the old width, update to `64rem`. 3. **Font loading** -- `--font-body` references `'Atkinson Hyperlegible'` but there is no `@font-face` declaration or Google Fonts import in the CSS or layout. The font will silently fall back to `system-ui`. If Atkinson Hyperlegible is desired, a font import should be added in a follow-up. ### SOP COMPLIANCE - [x] Branch named after issue (`10-remove-tailwind-plain-css` references issue #10) - [x] PR body follows template (Summary, Changes, Test Plan, Review Checklist, Related Notes all present) - [x] Related Notes references `pal-enterprises` project and `Closes #10` - [x] No secrets committed - [x] No unnecessary file changes -- all 13 changed files are directly related to the Tailwind removal - [x] Commit messages -- single PR, descriptive title - [ ] Related Notes does not reference a plan slug (no plan note found for this ticket -- minor gap) ### PROCESS OBSERVATIONS - **Change failure risk: LOW.** This is a pure presentational change. No Ruby logic, no database, no auth flow touched. The worst failure mode is visual regression, which the manual Test Plan covers. - **Deployment impact:** This unblocks production Docker builds since the Tailwind content scanner was the root cause of broken CSS in prod. Merging this should fix the 4.5KB purged CSS issue documented in `arch-rails-app`. - **Documentation:** The `arch-rails-app` note in pal-e-docs still lists CSS as "Tailwind (broken)" -- should be updated post-merge to reflect plain CSS. - **CI note:** The GitHub Actions CI (`ci.yml`) does not reference Tailwind directly, so no CI changes needed. The `scan_ruby`, `scan_js`, and `lint` jobs should pass without modification. ### VERDICT: APPROVED