If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/gravityblast/web-app-theme shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 23+ active contributors
• Distributed ownership (top contributor 47% of recent commits)
• Other licensed
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live gravityblast/web-app-theme repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/gravityblast/web-app-theme.

What it runs against: a local clone of gravityblast/web-app-theme — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in gravityblast/web-app-theme | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 830 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of gravityblast/web-app-theme. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/gravityblast/web-app-theme.git
#   cd web-app-theme
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of gravityblast/web-app-theme and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "gravityblast/web-app-theme(\\.git)?\\b" \\
  && ok "origin remote is gravityblast/web-app-theme" \\
  || miss "origin remote is not gravityblast/web-app-theme (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/web-app-theme.rb" \\
  && ok "lib/web-app-theme.rb" \\
  || miss "missing critical file: lib/web-app-theme.rb"
test -f "lib/generators/web_app_theme/theme/theme_generator.rb" \\
  && ok "lib/generators/web_app_theme/theme/theme_generator.rb" \\
  || miss "missing critical file: lib/generators/web_app_theme/theme/theme_generator.rb"
test -f "lib/generators/web_app_theme/themed/themed_generator.rb" \\
  && ok "lib/generators/web_app_theme/themed/themed_generator.rb" \\
  || miss "missing critical file: lib/generators/web_app_theme/themed/themed_generator.rb"
test -f "lib/generators/web_app_theme/assets/assets_generator.rb" \\
  && ok "lib/generators/web_app_theme/assets/assets_generator.rb" \\
  || miss "missing critical file: lib/generators/web_app_theme/assets/assets_generator.rb"
test -f "app/assets/stylesheets/web-app-theme/base.css" \\
  && ok "app/assets/stylesheets/web-app-theme/base.css" \\
  || miss "missing critical file: app/assets/stylesheets/web-app-theme/base.css"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 830 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~800d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/gravityblast/web-app-theme"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Web App Theme is a Ruby on Rails gem that provides a generator-based theming system for rapidly scaffolding admin panels and web application layouts. It ships with multiple pre-built CSS themes (default, activo, amro, bec, blue, etc.) and generates ERB/HAML layout templates that developers can customize. The core value is reducing boilerplate—run rails g web_app_theme:theme admin --theme=blue and get a complete themed layout with navigation, icons, and styling instead of building from scratch. Gem structure: lib/ contains generators (web_app_theme:theme, web_app_theme:assets, web_app_theme:themed), app/assets/stylesheets/web-app-theme/ contains base CSS and theme subdirectories (activo, amro, bec, blue, default, etc.), and app/assets/images/web-app-theme/ contains theme-specific images and icons. Themes are self-contained: each theme folder has a style.css, fonts/, and images/ subdirectory. The generator outputs an application.html.erb (or custom layout name) with theme CSS includes and standard admin nav structure.

Rails developers (particularly on Rails ≥3.1) building internal admin interfaces or dashboards who want pre-designed, production-ready themes without hiring a designer or writing CSS from scratch. Contributors are likely Rails developers maintaining legacy admin UIs or building rapid prototypes.

This is a mature but aging project. The gem targets Rails 3.1+ (released 2011), supports multiple themes with custom fonts (Museo Sans, Museo 700), and has a clear CHANGELOG.rdoc documenting releases. However, the README mentions Rails 2 compatibility in 0.5.3, suggesting this gem predates Rails 4+. No visible CI badge, test directory, or recent commits are mentioned in the provided data—this appears to be a stable, unmaintained library (likely last updated ~2012-2014 era) rather than actively developed.

High risk for new projects: Rails 3.1 EOL was June 2013, and there is no evidence of Rails 4+ or Rails 5+ support. The gem depends on the asset pipeline (app/assets/stylesheets, app/assets/images), which changed significantly in Rails 5+. No test suite or CI are visible, making it risky to fork for modern Rails. Single-maintainer gem (Andrea Franz) with no visible GitHub activity mentioned—standard for old abandonware.

No recent activity is visible. The file list shows no in-progress work, open PRs, or active issues. This appears to be a legacy stable gem in maintenance-only mode, with the last significant changes likely documented in CHANGELOG.rdoc (not provided here).

Clone the repo with git clone https://github.com/gravityblast/web-app-theme.git && cd web-app-theme. Install dependencies with bundle install (see Gemfile). No bin/dev or Rakefile commands are listed in the data, so check rake -T for available tasks. To test locally, create a Rails ≥3.1 app in a sibling directory and point its Gemfile to gem 'web-app-theme', path: '../web-app-theme', then run rails g web_app_theme:theme.

Daily commands: This is a gem, not an executable app. To test generators: bundle exec rails g web_app_theme:theme --help to see options. To use: add to Gemfile as gem 'web-app-theme', '~> 0.8.0', run bundle install, then invoke generators: rails g web_app_theme:theme (default theme + layout.html.erb), rails g web_app_theme:theme admin --theme=blue (blue theme, admin.html.erb layout), rails g web_app_theme:assets --theme=blue (copy theme CSS/images to app/).

• lib/web-app-theme.rb — Main entry point that loads the gem and all generators; required for understanding how the theme system initializes
• lib/generators/web_app_theme/theme/theme_generator.rb — Core generator that scaffolds theme files and layout templates; essential for understanding how themes are created
• lib/generators/web_app_theme/themed/themed_generator.rb — Generator for themed views (CRUD scaffolding); critical for understanding how view templates are generated
• lib/generators/web_app_theme/assets/assets_generator.rb — Handles asset extraction and copying; needed to understand Rails asset pipeline integration
• app/assets/stylesheets/web-app-theme/base.css — Base stylesheet foundation for all themes; defines core styling patterns that all themes build upon
• README.md — Documents gem purpose, installation, and Rails version compatibility; mandatory for understanding the project scope
• lib/web-app-theme/version.rb — Version definition used by gemspec and installation; needed for dependency resolution

Add a new theme variant

1. Create a new theme directory under app/assets/stylesheets/web-app-theme/themes/YOUR_THEME_NAME/ (app/assets/stylesheets/web-app-theme/themes/)
2. Copy base styling from an existing theme (e.g., default/style.css) and customize colors/fonts (app/assets/stylesheets/web-app-theme/themes/default/style.css)
3. Add corresponding theme images to app/assets/images/web-app-theme/themes/YOUR_THEME_NAME/images/ if using custom background or button images (app/assets/images/web-app-theme/themes/default/images/)
4. Reference the new theme in generators by modifying theme_generator.rb to include your theme in available options (lib/generators/web_app_theme/theme/theme_generator.rb)

Customize a themed view template

1. Generate themed views using the generator: rails generate web_app_theme:themed (lib/generators/web_app_theme/themed/themed_generator.rb)
2. Edit the generated template in app/views/YOUR_CONTROLLER/ (e.g., index.html.erb uses view_tables.html.erb as base) (lib/generators/web_app_theme/themed/templates/view_tables.html.erb)
3. Modify the original template in lib/generators/web_app_theme/themed/templates/ to change default scaffolding for future generators (lib/generators/web_app_theme/themed/templates/view_edit.html.erb)

Add internationalization (i18n) support for a new language

1. Create a new YAML file in config/locales/ named with your language code (e.g., fr.yml for French) (config/locales/de_de.yml)
2. Copy the structure from an existing locale file and translate strings (config/locales/es.yml)
3. Use translated strings in templates via <%= t('key') %> ERB syntax (lib/generators/web_app_theme/themed/templates/view_signin.html.erb)

Extract and customize pre-built assets

1. Run the assets generator: rails generate web_app_theme:assets (lib/generators/web_app_theme/assets/assets_generator.rb)
2. Assets are copied to app/assets/stylesheets/web-app-theme/ and app/assets/images/web-app-theme/ in your Rails app (app/assets/stylesheets/web-app-theme/base.css)
3. Edit base.css or theme CSS files directly in your app for customization without modifying the gem (app/assets/stylesheets/web-app-theme/themes/default/style.css)

• Rails Generators — Provides extensible framework for code scaffolding and template rendering via ruby; standard Rails integration pattern for gems
• ERB templates — Ruby standard for HTML templating; allows dynamic layout generation with embedded logic and Rails helpers
• CSS with Web Fonts (@font-face) — Museo fonts enable consistent typography; WOFF/EOT formats support cross-browser fallbacks before modern font APIs
• Rails Asset Pipeline — Manages CSS/image minification, fingerprinting, and caching; automatic inclusion via app/assets/ structure
• Cucumber BDD — Human-readable feature specs validate generator behavior and theme output without mocking Rails internals

• Gem includes pre-built themes instead of dynamically generating from config

  • Why: Avoids complex CSS generation logic; designers can hand-craft pixel-perfect themes
  • Consequence: Adding themes requires CSS file duplication; each new theme adds ~30KB to gem size

• Generators copy templates to app/ rather than rendering from gem at runtime

  • Why: Enables users to customize scaffolded output without monkey-patching; clear separation of generated vs. gem code
  • Consequence: Gem updates do not auto-update existing generated files; users must manually refresh or regenerate

• Supports Rails 3.1+ only (for Asset Pipeline) in latest version; dropped Rails 2 support

  • Why: Asset Pipeline eliminates manual asset copying; reduces maintenance burden and bundle size
  • Consequence: Users on Rails < 3.1 must use older gem versions (0.6.x); version matrix fragmentation

• Localization files stored in config/locales/ (YAML) rather than bundled translations

  • Why: Allows apps to override translations; standard Rails i18n integration
  • Consequence: Gem ships with only partial translations (de_de, es, pt_br); other languages unsupported without user contribution

• Not a CSS framework—does not generate responsive grids or utility classes; purely a curated admin UI

Rails version constraint: gem targets 3.1.0+, but Rails 3.1 is EOL and untested on Rails 4+. Asset pipeline must be enabled (no documentation on fallback for older Rails). Generator output assumes app/views/layouts/ and app/assets/ exist—may fail or behave oddly in non-standard Rails layouts. Theme filenames are hardcoded in generator (activo, amro, bec, blue, default, etc.); custom themes require manual integration if not in gem. No environment variables or runtime config mentioned—all configuration is generator arguments at scaffold time. Fonts are Museo Sans and Museo 700 (web fonts in default theme); licensing unclear if commercial use required.

• Rails Asset Pipeline — Web-app-theme entirely relies on Rails 3.1+ asset pipeline for CSS/image delivery; understanding app/assets, Sprockets, and manifest files is critical to debugging asset loading or customizing themes.
• Rails Generators (Thor) — This gem is a generator gem; its core functionality is Thor generators that scaffold layouts and copy assets. Modifying or extending web-app-theme requires understanding rails g mechanics.
• CSS Theming via Stylesheets — Web-app-theme's architecture uses separate theme CSS files (base.css + theme/*/style.css) rather than SCSS variables; understanding CSS cascade and specificity is essential to create or modify themes.
• ERB/HAML Template Engines — Generators output layouts in ERB (default) or HAML (with --engine=haml flag); understanding template syntax and Rails view helpers is needed to customize generated layouts.
• Web Font Delivery (@font-face) — Default theme includes Museo Sans and Museo 700 fonts as .eot/.svg/.ttf/.woff files with @font-face CSS rules; understanding font format compatibility and web font loading is relevant for theme creation.
• Icon Sprites and Image Assets — Web-app-theme bundles PNGs (application_edit.png, cross.png, tick.png, error/warning/notice message icons) as separate files; modern approaches use SVG/icon fonts, making this gem's image-heavy approach a design pattern worth understanding for legacy Rails.

• plataformatec/devise — Common companion to web-app-theme; Devise provides authentication scaffolding (user registration, login) that pairs with this gem's admin layout theming.
• activeadmin/activeadmin — Direct modern alternative solving the same problem (rapid admin UI generation) but with Ruby DSL and real data binding instead of pure theme generators.
• thoughtbot/administrate — Another modern admin panel generator for Rails; successor mindset to web-app-theme with component-based theming and ActiveRecord integration.
• rails/rails — The host framework; understanding Rails 3.1 asset pipeline and generator architecture is essential to extend this gem.
• gravityblast/web-app-theme-examples — Likely official examples/demo repo by the same author showing how to use web-app-theme with real Rails controllers and views.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Create theme preview/demo documentation with screenshots and CSS variable mappings

The repo contains 15+ themes (activo, amro, bec, blue, default, djime-cerulean, drastic-dark, kathleene, olive, orange, red, reidb-greenish, warehouse, etc.) but the README lacks any visual guide showing what each theme looks like or their key color/style differences. New contributors can't easily understand theme structure or contribute new themes without this reference.

• [ ] Create app/assets/stylesheets/web-app-theme/themes/THEME_GUIDE.md documenting each theme's primary colors and typography
• [ ] Extract color variables from app/assets/stylesheets/web-app-theme/themes/*/style.css files and document them
• [ ] Add a themes comparison table to README.md with theme names, color schemes, and intended use cases
• [ ] Document the base.css structure and how themes override it

Add comprehensive SCSS/SASS migration for theme stylesheets with variable system

Currently all theme stylesheets are plain CSS files with duplicated values across multiple themes (app/assets/stylesheets/web-app-theme/themes/*/style.css). Converting to SCSS with shared variables would reduce file size, improve maintainability, and make theme customization and contribution easier.

• [ ] Convert app/assets/stylesheets/web-app-theme/base.css to SCSS with shared mixins for common patterns
• [ ] Create app/assets/stylesheets/web-app-theme/_theme-variables.scss with colors, fonts, and spacing used across themes
• [ ] Migrate one theme (e.g., default) to SCSS format and document the pattern
• [ ] Add generator documentation for how new themes should use the variable system

Document Rails generator templates and add configuration examples

The README mentions 'rails generator' multiple times but provides no details on what the generator actually creates, what options it accepts, or how to customize generated layouts. The app/ directory shows theme assets but not the actual generator templates or configuration helpers that developers need.

• [ ] Create lib/generators/web_app_theme/GENERATOR_GUIDE.md documenting all available generator commands
• [ ] Add examples to README.md showing: rails generate web_app_theme:theme blue, rails generate web_app_theme:assets, and expected outputs
• [ ] Document Rails helper methods available (e.g., theme-specific CSS includes) with usage examples
• [ ] Add a section explaining how to customize generated templates and theme selections

• Create an SCSS version of base.css and theme stylesheets. Currently pure CSS with no mixins or nesting; convert to SCSS with variables for colors and spacing to make theme customization easier and reduce repetition across themes.
• Add a test suite for generators. No test files are visible; write RSpec specs for web_app_theme:theme, web_app_theme:assets, and web_app_theme:themed generators to ensure they produce valid ERB/HAML and copy assets correctly.
• Document theme anatomy and provide a theme template. Add a guide to app/assets/stylesheets/web-app-theme/THEME_STRUCTURE.md with a minimal 'skeleton' theme (app/assets/stylesheets/web-app-theme/themes/skeleton/) showing folder structure, required CSS, image naming conventions, and fonts.

The web-app-theme gem is a legacy Rails theme generator with a moderate security posture. The primary concerns are the outdated version (0.8.0 from ~2013) which may have unpatched vulnerabilities, potential XSS risks in the dynamic code generators without visible input sanitization, and lack of security guidance for developers. The gem consists primarily of static assets (stylesheets, images, fonts) which have lower attack surface than dynamic code. Developers using this gem should: (1) verify no vulnerabilities exist via bundle audit, (2) ensure generators properly sanitize inputs, (3) implement comprehensive security headers in their applications, and (4) consider migrating to more actively maintained theme frameworks if security is a critical concern.

• Medium · Outdated Gem Specification — README.md, Gemfile. The README references gem 'web-app-theme', '~> 0.8.0', which is an old version (last release was around 2013). This version may contain unpatched security vulnerabilities in Rails-related dependencies, especially for CSRF protection, XSS mitigation, and other security features. Fix: Update to the latest version of the gem or consider migrating to more actively maintained theme/UI frameworks. Review all dependencies with bundle audit to identify known vulnerabilities.
• Medium · Potential XSS Vulnerability in Theme Generator — lib/generators/web_app_theme/. The gem generates theme-related code and assets dynamically. Without visible sanitization in the generator code structure (lib/generators/web_app_theme/), there is a risk that user-supplied theme names or customization parameters could be injected into generated CSS/HTML files without proper escaping. Fix: Review generator code to ensure all user inputs are properly validated and sanitized before being written to generated files. Use Rails' built-in sanitization helpers.
• Low · Missing Security Headers Documentation — README.md, Documentation. This is a theme/UI gem that does not appear to include any security-related headers or security policy configuration guidance in the README or documentation visible in the codebase. Fix: Add documentation advising developers to implement security headers (CSP, X-Frame-Options, X-Content-Type-Options, etc.) in their applications that use this theme.
• Low · No Dependency Pinning in Gemfile — Gemfile. The Gemfile is not visible, but best practices indicate that dependency versions should be pinned or constrained to prevent supply chain attacks and unexpected breaking changes. Fix: Use specific version constraints in Gemfile (e.g., ~> 3.x.x) and maintain a Gemfile.lock in version control. Regularly audit dependencies with bundle audit.
• Low · Web Fonts May Contain Tracking Vectors — app/assets/stylesheets/web-app-theme/themes/default/fonts/. The theme includes custom web fonts (Museo fonts) stored locally. Depending on the font source and licensing, there could be privacy concerns if fonts were loaded from CDNs in production. Fix: Ensure web fonts are properly licensed and loaded from trusted sources. Audit font files for unnecessary metadata that could track users.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.