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/sshahine/JFoenix 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 3y ago

• 23+ active contributors
• Distributed ownership (top contributor 38% of recent commits)
• MIT licensed
• CI configured
• ⚠ Stale — last commit 3y ago
• ⚠ No test directory 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 sshahine/JFoenix repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/sshahine/JFoenix.

What it runs against: a local clone of sshahine/JFoenix — 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 sshahine/JFoenix | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | 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 ≤ 1075 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of sshahine/JFoenix. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/sshahine/JFoenix.git
#   cd JFoenix
#
# 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 sshahine/JFoenix and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT 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 "build.gradle" \\
  && ok "build.gradle" \\
  || miss "missing critical file: build.gradle"
test -f "demo/src/main/java/demos/MainDemo.java" \\
  && ok "demo/src/main/java/demos/MainDemo.java" \\
  || miss "missing critical file: demo/src/main/java/demos/MainDemo.java"
test -f "demo/src/main/java/demos/gui/main/MainController.java" \\
  && ok "demo/src/main/java/demos/gui/main/MainController.java" \\
  || miss "missing critical file: demo/src/main/java/demos/gui/main/MainController.java"
test -f "demo/src/main/resources/fxml/Main.fxml" \\
  && ok "demo/src/main/resources/fxml/Main.fxml" \\
  || miss "missing critical file: demo/src/main/resources/fxml/Main.fxml"
test -f "demo/src/main/resources/css/jfoenix-main-demo.css" \\
  && ok "demo/src/main/resources/css/jfoenix-main-demo.css" \\
  || miss "missing critical file: demo/src/main/resources/css/jfoenix-main-demo.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 1075 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1045d)"
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/sshahine/JFoenix"
  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).

JFoenix is a JavaFX library that implements Google's Material Design specification using pure Java components. It provides ~30+ Material-Design-compliant UI controls (buttons, text fields, chips, date pickers, drawers, etc.) that can be dropped into JavaFX applications with CSS-based theming, eliminating the need to build custom Material Design controls from scratch. Single-module Maven/Gradle project: jfoenix/ contains core Material Design components as Java classes using JavaFX primitives, demo/ is a runnable showcase application (MainDemo.java) with 30+ component demo classes organized by type (AlertDemo, ButtonDemo, etc.), and config/ holds build rules (Checkstyle, FindBugs, license headers). CSS styling lives alongside component classes.

JavaFX desktop application developers who need Google Material Design aesthetics without writing custom CSS or graphics code. Also targets teams maintaining enterprise Java Swing-to-JavaFX migrations that want modern UI patterns.

Production-ready and actively maintained. The project is well-established (evidenced by 20+ production users listed in README including HMCL launcher and XR3Player), has comprehensive CI/CD via CircleCI, publishes to Maven Central, and maintains Java 8 and Java 9+ versions. Recent commits and active issue tracking suggest ongoing development, though the original maintainer model may have evolved.

Low structural risk but moderate ecosystem concerns. The codebase is stable with strong code quality gates (SonarQube integration, Checkstyle, FindBugs checks), but JavaFX itself is evolving and JFoenix tracks multiple Java versions (8.x and 9.x branches). Single-repo structure means breaking Material Design spec changes could impact all components simultaneously.

Active maintenance with CI/CD via CircleCI (.circleci/config.yml), SonarCloud quality gates enabled, and Stale bot configured (.github/stale.yml). The demo application continues to be enhanced with new component showcases. No major version changes visible in recent structure, suggesting stability-focused iteration.

Clone the repo and build: git clone https://github.com/sshahine/JFoenix.git && cd JFoenix && ./gradlew build. Run the demo application: ./gradlew demo:run (requires Java 8+, JavaFX SDK in JAVA_HOME). Artifacts are published to Maven Central via Gradle Bintray plugin.

Daily commands: ./gradlew demo:run launches the MainDemo.java application showing all 30+ components interactively. For library development: ./gradlew build compiles and runs tests (code coverage via Gradle config), ./gradlew check runs Checkstyle and FindBugs, ./gradlew sonarqube publishes to SonarCloud.

• build.gradle — Root build configuration defining all subprojects, plugins, and shared dependencies for the entire Material Design library
• demo/src/main/java/demos/MainDemo.java — Main entry point for the demo application showcasing all JFoenix Material Design components
• demo/src/main/java/demos/gui/main/MainController.java — Primary controller managing the demo application's main window and component navigation flow
• demo/src/main/resources/fxml/Main.fxml — Root FXML layout defining the overall UI structure and integration point for all demo components
• demo/src/main/resources/css/jfoenix-main-demo.css — Master stylesheet applying Material Design theming and visual styling across the entire demo application
• .github/workflows/ci.yml — CI/CD pipeline definition for automated testing and quality gates (SonarCloud, builds)
• gradle.properties — Project properties and version configuration used across all Gradle builds

Add a New Material Design Component Demo

1. Create a new FXML layout file for the component in demo/src/main/resources/fxml/ui/ (demo/src/main/resources/fxml/ui/NewComponent.fxml)
2. Create a new controller class in demo/src/main/java/demos/gui/uicomponents/ (demo/src/main/java/demos/gui/uicomponents/NewComponentController.java)
3. Add the controller to the MainController to wire up navigation and component switching (demo/src/main/java/demos/gui/main/MainController.java)
4. Add a menu item in SideMenu.fxml to make the new component accessible from the sidebar (demo/src/main/resources/fxml/SideMenu.fxml)
5. Add component-specific styling rules to jfoenix-components.css (demo/src/main/resources/css/jfoenix-components.css)

Update Material Design Styling Across Demo

1. Modify the global Material Design theme and color palette in jfoenix-main-demo.css (demo/src/main/resources/css/jfoenix-main-demo.css)
2. Update component-specific styles in jfoenix-components.css to match new theme (demo/src/main/resources/css/jfoenix-components.css)
3. Rebuild and run the demo to verify visual consistency across all Material Design components (demo/build.gradle)

Add a New Demo Category or Section

1. Create a new controller class in demos/gui/uicomponents/ for the new category logic (demo/src/main/java/demos/gui/uicomponents/NewCategoryController.java)
2. Define the FXML layout for the new category in demo/src/main/resources/fxml/ui/ (demo/src/main/resources/fxml/ui/NewCategory.fxml)
3. Register the new category in MainController to add it to the navigation flow (demo/src/main/java/demos/gui/main/MainController.java)
4. Update SideMenu.fxml to add menu items for accessing the new category (demo/src/main/resources/fxml/SideMenu.fxml)

• JavaFX — Cross-platform GUI framework providing native UI capabilities and CSS styling support for Material Design implementation
• Gradle — Modern build tool enabling multi-project structure, dependency management, and plugin ecosystem for Java builds
• FXML — XML-based UI markup language for JavaFX that separates UI layout from controller logic, enabling clean MVC architecture
• CSS — Cascading stylesheets providing Material Design theming, color schemes, and visual consistency across all components
• GitHub Actions & SonarCloud — Automated CI/CD pipeline ensuring code quality gates, style compliance, and continuous integration before merge

• FXML-based UI definitions over programmatic JavaFX construction

  • Why: FXML provides declarative, designer-friendly UI layouts that separate concerns and improve maintainability
  • Consequence: Adds XML parsing overhead at runtime but gains flexibility in UI redesign without recompiling Java code

• Centralized CSS styling in jfoenix-main-demo.css and jfoenix-components.css

  • Why: Ensures consistent Material Design theming and reduces style duplication across all component demos
  • Consequence: Global CSS changes can have unexpected side effects; requires careful testing when updating styles

• Monolithic demo application in single project structure

  • Why: Simplifies navigation, reduces build complexity, and keeps all component examples in one cohesive application
  • Consequence: Large single JAR artifact; component dependencies all bundled together even if only using one component

• Does not provide server-side or backend services; purely a UI library and demo application
• Not a real-time collaborative editing platform or multi-user system
• Does not include persistent data storage, authentication, or user account management
• Not designed for web deployment; requires Java runtime environment (desktop-only)

JavaFX SDK must be available at build time (configured in gradle/javafx.gradle but can fail silently if JAVA_HOME is misconfigured). Module path issues in Java 9+ require --add-modules flags (handled in build.gradle but custom IDEs may need explicit setup). RetroLambda plugin is declared for Android support but may conflict with Java 8-only builds. CSS paths are tightly coupled to component class locations; moving a component breaks its CSS unless both are updated together. SonarCloud integration requires SONAR_TOKEN environment variable in CI but won't fail local builds.

• Material Design System (Google Material 2) — JFoenix implements Google Material Design spec (color palettes, typography scales, elevation shadows, motion curves, component patterns); understanding Material Design principles is essential to extending or theming components correctly
• JavaFX CSS Styling & Lookup — JFoenix components use JavaFX's CSS engine to apply Material Design theming; knowing CSS selectors, pseudo-classes (:hover, :focused), and the lookup() API is required to customize component appearance
• JavaFX Property Binding & Observables — JFoenix components expose Material Design state changes (ripple effects, focus state, validation errors) via JavaFX ObservableValue and Property APIs; understanding two-way binding is needed to react to component changes
• Ripple Effect Animation (Material Ink) — JFoenix's RipplerDemo and Material Design components feature animated ripple effects on click; this requires understanding JavaFX's Timeline/AnimationTimer and custom Node rendering for the Material ink ripple signature
• Control Skinning in JavaFX — JFoenix components often extend javafx.scene.control.Control with custom skins; understanding the Skin API and node hierarchy (parent/child layout) is needed to modify component rendering without breaking layouts
• Gradle Subproject Configuration & Publishing — JFoenix uses Gradle's multi-project build with shared config files (gradle/*.gradle); understanding how subprojects inherit configuration and Bintray/Maven publishing plugins is needed to modify build rules or release process
• RetroLambda & Java 8 Backporting — JFoenix targets Java 8 via RetroLambda plugin for Android compatibility; lambda syntax and functional interfaces are used throughout, but understanding Java 8 feature level is required when backporting code to older targets

• jfoenixadmin/JFoenix — This is the official GitHub organization mirror; same codebase as sshahine/JFoenix but maintained under the JFoenix admin account
• controlsfx/controlsfx — Alternative JavaFX control library with different Material Design approach; pre-dates JFoenix and influenced early design decisions
• materialfx/MaterialFX — Newer Material Design JavaFX library with similar goals; useful for comparing modern Material 3 implementations vs JFoenix's Material 2 focus
• google/material-design-icons — Google's official Material Design icon set; JFoenix apps often embed these icons, making the canonical reference essential
• javafxports/openjdk-jfx — JavaFX SDK source repository; JFoenix extends JavaFX controls, so understanding upstream Control/Region/CSS APIs is critical for deep modifications

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.

Add comprehensive unit tests for JFoenix Material Design components

The repo has 20+ demo components (ButtonDemo, CheckBoxDemo, DatePickerDemo, etc.) in demo/src/main/java/demos/components but there's no visible test directory structure. Given the presence of code-coverage.gradle and checkstyle configuration, a dedicated src/test/java directory with unit tests for core components would significantly improve code quality and catch regressions. This aligns with the SonarCloud integration already in place.

• [ ] Create src/test/java directory structure mirroring main components
• [ ] Add JUnit 4/5 tests for 3-5 critical components (e.g., JFXButton, JFXCheckBox, JFXDatePicker)
• [ ] Ensure tests cover initialization, styling, and event handling for Material Design behavior
• [ ] Run gradle tasks to verify code-coverage.gradle reports test metrics

Add GitHub Actions workflow for automated JavaDoc and demo artifact publishing

The repo has .github/workflows/ci.yml (CircleCI referenced in README) and uses Gradle with Javadoc configuration, but there's no apparent automated publication of API documentation or demo build artifacts. Adding a GitHub Actions workflow to generate and deploy JavaDoc to GitHub Pages and create release artifacts would improve discoverability and make releases more professional.

• [ ] Create .github/workflows/javadoc-publish.yml to generate JavaDoc on release tags
• [ ] Configure JVM heap settings in workflow to handle demo/build.gradle compilation
• [ ] Add step to deploy generated JavaDoc to gh-pages branch
• [ ] Include optional artifact upload for demo JAR to GitHub Releases

Create integration tests for demo application controllers using TestFX framework

The demo module has 15+ controllers (MainController, ButtonController, CheckboxController, DialogController, etc.) in demo/src/main/java/demos/gui/uicomponents but lacks automated integration tests. Adding TestFX-based UI tests would validate that Material Design components work correctly in real JavaFX application contexts and catch layout/interaction bugs.

• [ ] Add TestFX and JUnit dependencies to demo/build.gradle
• [ ] Create demo/src/test/java/demos/gui/uicomponents with integration tests for 3-4 key controllers
• [ ] Test user interactions (button clicks, text input, selections) and visual state changes
• [ ] Integrate tests into CI pipeline via .github/workflows/ci.yml or CircleCI config

• Add comprehensive unit tests for 5-10 core Material components (JFXButton, JFXTextField, JFXCheckBox, etc.) that currently lack test classes; start by examining demo/src/main/java/demos/components/ to understand expected behavior and create parallel test files in a new jfoenix/src/test/java/ directory
• Expand CSS documentation: Material Design components inherit from JavaFX CSS properties, but the relationship is underdocumented; create a CSS reference guide mapping JFoenix component selectors (e.g., .jfx-button, .jfx-text-field) to their Material Design properties, hosting in a new docs/ folder
• Add missing demo for new Material Design features (e.g., Material 3 color system, updated motion specs); check Material Design spec updates against existing demos in demo/src/main/java/demos/components/ and add a new DemoXXX.java class showcasing updated patterns

The JFoenix codebase has moderate security concerns primarily related to build configuration. The most critical issue is the use of HTTP for Maven repository access, which exposes the build process to man-in-the-middle attacks. Additionally, significantly outdated Gradle plugins and use of deprecated repositories (jcenter) create risks for unpatched security vulnerabilities and supply chain attacks. The lack of explicit dependency versioning and absence of security reporting policies further diminish the security posture. The codebase itself appears to be a UI library with no obvious injection vulnerabilities, hardcoded credentials, or exposed secrets based on the provided file structure.

• High · Insecure Maven Repository Over HTTP — build.gradle - repositories section. The build.gradle file configures a Maven repository using HTTP instead of HTTPS: 'http://sevntu-checkstyle.github.com/sevntu.checkstyle/maven2'. This allows for man-in-the-middle attacks during dependency resolution and could lead to malicious artifact injection. Fix: Change the repository URL to use HTTPS: 'https://sevntu-checkstyle.github.com/sevntu.checkstyle/maven2'. Ensure all Maven repositories use encrypted connections.
• Medium · Outdated Gradle Plugin Versions — build.gradle - plugins section. The build.gradle uses significantly outdated plugin versions: com.jfrog.bintray v1.7.3 (released 2016), com.github.hierynomus.license v0.14.0 (2017), net.nemerosa.versioning v2.6.1 (2017), and org.sonarqube v2.5 (2017). These old versions may contain known security vulnerabilities and lack modern security features. Fix: Update all plugins to the latest stable versions. Review release notes for each plugin to ensure compatibility and apply security patches.
• Medium · Deprecated jcenter() Repository — build.gradle - repositories section (buildscript and subprojects). The build.gradle file uses jcenter() repository which was sunset by JFrog in 2021. Relying on archived/unmaintained repositories may lead to dependency resolution issues and inability to receive security updates. Fix: Replace jcenter() with mavenCentral() exclusively. Remove all references to jcenter() from the build configuration.
• Medium · Missing Dependency Verification — build.gradle - dependencies section. The build configuration does not specify dependency versions explicitly in the root build.gradle file. Without version pinning or lock files, dependency resolution could be non-deterministic and vulnerable to supply chain attacks through minor/patch version updates. Fix: Implement dependency version management using a BOM (Bill of Materials) or dependency lock files. Use 'dependencyLocking' feature in Gradle to create reproducible builds.
• Low · Retrolambda Plugin Obsolescence — build.gradle - plugins section. The project includes me.tatarka.retrolambda v3.7.0 plugin which is designed to backport Java 8 lambda support to Java 7. Given that the project targets Java 8+ (sourceCompatibility = 1.8), this plugin is obsolete and may cause compatibility issues. Fix: Remove the retrolambda plugin as it's not needed for Java 8+ projects. Modern Java versions natively support lambda expressions.
• Low · Missing Security Headers and Policies — Repository root - missing SECURITY.md. No evidence of security policies in configuration files. The .github/stale.yml suggests GitHub automation but no SECURITY.md file is documented for vulnerability reporting. Fix: Create a SECURITY.md file documenting how security vulnerabilities should be reported, following GitHub's recommended security policy template.

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.