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/JFormDesigner/FlatLaf 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.

GO — Healthy across all four use cases

• Last commit 3d ago
• 6 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 93% of recent commits

_{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 JFormDesigner/FlatLaf repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/JFormDesigner/FlatLaf.

What it runs against: a local clone of JFormDesigner/FlatLaf — 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 JFormDesigner/FlatLaf | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

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

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

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

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

# 4. Critical files exist
test -f "flatlaf-core/src/main/java/com/formdev/flatlaf/FlatLaf.java" \\
  && ok "flatlaf-core/src/main/java/com/formdev/flatlaf/FlatLaf.java" \\
  || miss "missing critical file: flatlaf-core/src/main/java/com/formdev/flatlaf/FlatLaf.java"
test -f "flatlaf-core/src/main/java/com/formdev/flatlaf/UIDefaultsLoader.java" \\
  && ok "flatlaf-core/src/main/java/com/formdev/flatlaf/UIDefaultsLoader.java" \\
  || miss "missing critical file: flatlaf-core/src/main/java/com/formdev/flatlaf/UIDefaultsLoader.java"
test -f "flatlaf-core/src/main/java/com/formdev/flatlaf/IntelliJTheme.java" \\
  && ok "flatlaf-core/src/main/java/com/formdev/flatlaf/IntelliJTheme.java" \\
  || miss "missing critical file: flatlaf-core/src/main/java/com/formdev/flatlaf/IntelliJTheme.java"
test -f "flatlaf-core/src/main/java/com/formdev/flatlaf/FlatClientProperties.java" \\
  && ok "flatlaf-core/src/main/java/com/formdev/flatlaf/FlatClientProperties.java" \\
  || miss "missing critical file: flatlaf-core/src/main/java/com/formdev/flatlaf/FlatClientProperties.java"
test -f "flatlaf-core/src/main/java/com/formdev/flatlaf/icons/FlatAbstractIcon.java" \\
  && ok "flatlaf-core/src/main/java/com/formdev/flatlaf/icons/FlatAbstractIcon.java" \\
  || miss "missing critical file: flatlaf-core/src/main/java/com/formdev/flatlaf/icons/FlatAbstractIcon.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
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/JFormDesigner/FlatLaf"
  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).

FlatLaf is a modern cross-platform Look and Feel (LAF) library for Java Swing applications that provides a flat, minimalist UI with Light, Dark, IntelliJ, and Darcula themes. It delivers HiDPI scaling support and pixel-perfect rendering across Windows, macOS, and Linux, heavily inspired by IntelliJ IDEA's Darcula theme while supporting 3rd-party IntelliJ Platform themes. Multi-module Gradle monorepo: flatlaf-core contains the main LAF implementation (com.formdev.flatlaf package in src/main/java), separate modules for demo, IntelliJ theme support, and native libraries. Custom Gradle plugins in buildSrc (flatlaf-cpp-library.gradle.kts, flatlaf-jni-headers.gradle.kts) manage C++ interop and module-info configuration for Java 9+ modular system.

Java Swing developers building desktop applications (especially on JetBrains IDEs and enterprise tools) who need a modern, themeable UI that matches current design trends without writing custom LAF code. Maintainers of legacy Swing apps wanting to modernize their look without migrating to web frameworks.

Production-ready and actively maintained. The codebase is substantial (~4.2M LOC Java) with stable multi-module structure (flatlaf-core, flatlaf-demo, flatlaf-intellij-themes), CI/CD pipelines via GitHub Actions (.github/workflows/ci.yml, natives.yml), and Maven Central distribution. Regular updates visible in CHANGELOG.md indicate ongoing active development.

Low risk for core usage. Single maintainer (JFormDesigner organization) is a potential concern for critical bug fixes, but the project has been stable and well-documented. Native library components (C++, Objective-C, Swift in buildSrc/src/main/kotlin/flatlaf-cpp-library.gradle.kts) add complexity for platform-specific features like font rendering and native window styling; breaking changes to Swing APIs (rare in Java LTS) could affect compatibility.

Active development on theme support and platform-specific features. CI workflows track error detection (error-prone.yml), native library builds (natives.yml), and font management (fonts.yml). PR snapshots generated automatically, indicating rapid iteration. Recent focus appears to be on macOS theme parity (flat_macos_themes.png in images) and IntelliJ Platform theme compatibility.

Clone: git clone https://github.com/JFormDesigner/FlatLaf.git. Install: cd FlatLaf && ./gradlew build (uses Gradle wrapper). Run demo: ./gradlew flatlaf-demo:run or java -jar build/flatlaf-demo-<version>.jar. Requires Java 8+ (LTS or latest).

Daily commands: ./gradlew clean build (full build with native libraries), ./gradlew flatlaf-demo:run (start demo UI), ./gradlew test (run test suite). Use ./gradlew tasks to list all available targets. Build output: JAR in flatlaf-core/build/libs/, demo in flatlaf-demo/build/libs/.

• flatlaf-core/src/main/java/com/formdev/flatlaf/FlatLaf.java — Core base class for all FlatLaf Look and Feel implementations; entry point for theme initialization and UI defaults setup.
• flatlaf-core/src/main/java/com/formdev/flatlaf/UIDefaultsLoader.java — Loads and applies UI defaults from properties files; critical for theme application and component styling across the entire framework.
• flatlaf-core/src/main/java/com/formdev/flatlaf/IntelliJTheme.java — Handles IntelliJ Platform theme file parsing and integration; enables support for 3rd-party IntelliJ themes in FlatLaf applications.
• flatlaf-core/src/main/java/com/formdev/flatlaf/FlatClientProperties.java — Defines client properties API for component customization; essential reference for developers configuring FlatLaf behavior on individual components.
• flatlaf-core/src/main/java/com/formdev/flatlaf/icons/FlatAbstractIcon.java — Base class for all flat-style icons; foundation for the entire icon rendering system used throughout the Look and Feel.
• flatlaf-core/build.gradle.kts — Build configuration for core module; defines dependencies, Java version requirements (Java 8+), and module exports.
• build.gradle.kts — Root project configuration managing multi-module build, publication, and platform-specific native code compilation.

Add a new built-in theme

1. Create new LAF class extending FlatLaf in flatlaf-core/src/main/java/com/formdev/flatlaf/ (flatlaf-core/src/main/java/com/formdev/flatlaf/FlatLaf.java)
2. Create theme properties file in flatlaf-core/src/main/java/com/formdev/flatlaf/themes/ (e.g., FlatCustom.properties) (flatlaf-core/src/main/java/com/formdev/flatlaf/themes)
3. In new LAF class, call UIDefaultsLoader.loadDefaultsFromProperties() with your theme properties (flatlaf-core/src/main/java/com/formdev/flatlaf/UIDefaultsLoader.java)
4. Override installDefaults() to apply theme-specific colors and fonts (flatlaf-core/src/main/java/com/formdev/flatlaf/FlatLightLaf.java)

Add a new custom icon

1. Create new icon class extending FlatAbstractIcon in flatlaf-core/src/main/java/com/formdev/flatlaf/icons/ (flatlaf-core/src/main/java/com/formdev/flatlaf/icons/FlatAbstractIcon.java)
2. Override paintIcon(Graphics2D g) to draw the icon shape using Graphics2D operations (flatlaf-core/src/main/java/com/formdev/flatlaf/icons/FlatCheckBoxIcon.java)
3. Register icon in UIDefaults via theme properties file or programmatically in UIDefaultsLoader (flatlaf-core/src/main/java/com/formdev/flatlaf/UIDefaultsLoader.java)

Add support for IntelliJ Platform theme variant

1. Create .theme.json file following IntelliJ format in themes directory (flatlaf-core/src/main/java/com/formdev/flatlaf/themes)
2. Use IntelliJTheme.install(File themeFile) to load theme at runtime (flatlaf-core/src/main/java/com/formdev/flatlaf/IntelliJTheme.java)
3. Theme JSON is parsed via Json and JsonParser; color mappings applied to UIDefaults (flatlaf-core/src/main/java/com/formdev/flatlaf/json/JsonParser.java)

Customize component appearance via client properties

1. Review available client properties in FlatClientProperties (flatlaf-core/src/main/java/com/formdev/flatlaf/FlatClientProperties.java)
2. Set on component: component.putClientProperty(FlatClientProperties.BUTTON_TYPE, FlatClientProperties.BUTTON_TYPE_ROUNDED) (flatlaf-core/src/main/java/com/formdev/flatlaf/FlatClientProperties.java)
3. Component UI delegates read client properties and adjust rendering accordingly (no core code change needed) (flatlaf-core/src/main/java/com/formdev/flatlaf/FlatLaf.java)

• Java Swing — FlatLaf is a Look and Feel implementation; Swing is the standard GUI framework for cross-platform desktop Java applications.
• Gradle (Kotlin DSL) — Multi-module build system with complex native compilation (C++ for platform-specific features); Kotlin DSL provides type safety.
• JSON (custom parser) — IntelliJ Platform themes use JSON format; custom parser allows zero-dependency theme loading.
• Java 8+ (with Java 9+ module system) — Java 8 ensures wide compatibility; Java 9+ modules (module-info.java) support modern classpath and JPMS.
• Graphics2D rendering — All flat icons and component shapes are drawn programmatically using Graphics2D for resolution independence and HiDPI scaling

1. Platform-specific native libraries: macOS font rendering and window styling require building C++/Objective-C code via buildSrc; incomplete native builds silently fall back to Java defaults without error warnings. 2) Java module system: flatlaf-core uses JPMS (module-info.java); if you add internal dependencies not exported, reflection-based theme loading may fail silently. 3) Theme color inheritance: IntelliJTheme.java has complex parent theme inheritance logic; applying a theme before UI is initialized can cause half-applied colors. 4) Swing's EDT thread safety: UI updates must run on Event Dispatch Thread; theme switching mid-render can deadlock. 5) HiDPI scaling assumptions: Code assumes 96 DPI baseline; custom DPI values on Linux may cause metric mismatches without explicit java.awt.Font scaling.

• Swing Look and Feel (LAF) Plugin Architecture — FlatLaf is a JAR-pluggable LAF that replaces the default Metal LAF; understanding javax.swing.LookAndFeel subclassing and UIManager registration is essential to grasp how FlatLaf injects itself into Swing apps.
• HiDPI / Retina Display Scaling — FlatLaf's core value is pixel-perfect rendering on high-DPI displays (2x, 4x scaling on macOS/Windows); the codebase heavily optimizes for Graphics2D transform stacks and font metrics that differ at non-96 DPI baselines.
• Java Module System (JPMS) and module-info.java — flatlaf-core publishes as a Java 9+ module; understanding requires, exports, and transitive dependencies in module-info is mandatory for Java 9+ projects and affects classloader behavior in complex scenarios.
• JNI (Java Native Interface) for C++ / Objective-C Integration — Native platform libraries (buildSrc/src/main/kotlin/flatlaf-cpp-library.gradle.kts) use JNI for macOS font rendering and window decorations; understanding JNI header generation and platform-specific compilation is necessary to extend platform features.
• Theme Inheritance and Property Cascading — IntelliJTheme.java supports theme parent inheritance and override hierarchies (similar to CSS cascade); many bugs stem from misunderstanding which properties override which when multiple themes or property files chain together.
• Gradle Multi-Module Build and Custom Plugins — buildSrc contains custom Gradle plugins (flatlaf-cpp-library.gradle.kts, flatlaf-module-info.gradle.kts) that orchestrate Java, C++, and Kotlin compilation in tandem; understanding Gradle's plugin API and task dependencies is critical for CI/build troubleshooting.
• UIManager and UIDefaults Registry — FlatLaf registers hundreds of UI component defaults (button borders, text colors, font families) via UIManager.getDefaults(); accessing and overriding these defaults is the standard Swing customization path used by FlatClientProperties.

• weisJ/darklaf — Alternative modern Swing LAF with similar flat design and dark theme support; direct competitor in the Java Swing modernization space
• freeplane/freeplane — Large Swing-based desktop app (mind-mapping tool) that uses FlatLaf for its UI; real-world integration example and test bed
• JetBrains/intellij-community — Original source of Darcula and IntelliJ theme design philosophy; FlatLaf reverse-engineered IntelliJ's colors and component styling from this codebase
• formdev/flatlaf-demo-kotlin — Official Kotlin/Gradle demo of FlatLaf showing modern Swing patterns; companion project for learning FlatLaf integration
• apache/commons-lang — Lightweight utility library often used alongside Swing projects; complementary to FlatLaf's component-level customization for property handling

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 FlatIconColors and icon rendering system

The flatlaf-core/src/main/java/com/formdev/flatlaf/icons/ directory contains 20+ icon classes (FlatCheckBoxIcon, FlatFileChooserDetailsViewIcon, etc.) but there's no visible test directory for these critical rendering components. This is high-value because icon rendering bugs directly impact UI quality across all themes (Light, Dark, IntelliJ, Darcula), and comprehensive tests would catch regressions early.

• [ ] Create flatlaf-core/src/test/java/com/formdev/flatlaf/icons/ directory structure
• [ ] Add unit tests for FlatAbstractIcon base class (scaling, HiDPI rendering)
• [ ] Add parameterized tests for icon color variants across all 4 themes using FlatIconColors
• [ ] Add visual regression tests for animated icons (FlatAnimatedIcon) to catch animation timing issues
• [ ] Integrate tests into build.gradle.kts test task

Add GitHub Actions workflow for testing IntelliJ theme pack compatibility

The repo mentions IntelliJ Platform Themes support and has a flatlaf-intellij-themes module referenced in README, but there's no visible CI workflow (.github/workflows/) specifically for validating third-party theme loading and rendering. This would catch regressions in IntelliJTheme.java and FlatPropertiesLaf.java when core changes are made.

• [ ] Create .github/workflows/intellij-themes-compatibility.yml workflow file
• [ ] Add test matrix for loading popular IntelliJ themes (Darcula, Material, Dracula, etc.)
• [ ] Validate theme color parsing and UIDefaults integration in the workflow
• [ ] Test cross-platform rendering (Linux, macOS, Windows) since .github/workflows/natives.yml exists for platform-specific code
• [ ] Add workflow trigger on PR for flatlaf-core/ changes to catch theme incompatibilities early

Create integration test suite for HiDPI scaling across platforms

FlatLaf explicitly supports HiDPI displays and has LinuxFontPolicy and platform-specific native code (.github/workflows/natives.yml), but there's no visible test suite validating that scaling works consistently across icon rendering, font sizing, and component layout. This is critical since HiDPI bugs manifest differently on Linux, macOS, and Windows.

• [ ] Create flatlaf-core/src/test/java/com/formdev/flatlaf/scaling/ test directory
• [ ] Add tests for LinuxFontPolicy.java DPI detection and font scaling edge cases (96, 120, 144, 192 DPI)
• [ ] Add visual tests validating icon scaling ratios (1x, 1.25x, 1.5x, 2x) don't blur or distort
• [ ] Add tests for FlatClientProperties and component-level scaling properties
• [ ] Create test matrix in CI workflow (.github/workflows/ci.yml) simulating different screen DPI values

• Add unit tests for IntelliJTheme.java theme parsing logic (currently visible theme files under src/main/resources lack coverage tests); start by creating flatlaf-core/src/test/java/com/formdev/flatlaf/IntelliJThemeTest.java and testing .theme.json deserialization edge cases.
• Document all FlatClientProperties keys with JavaDoc and a reference table in flatlaf-core/README.md; many properties are discoverable only via code inspection (e.g., 'Button.arc', 'Component.focusWidth') and lack centralized catalog.
• Add macOS dark mode detection example in flatlaf-demo (demo lacks runtime theme switching UI for Light↔Dark); implement a preferences dialog that toggles FlatLightLaf ↔ FlatDarkLaf and persists choice, improving UX story for new users.

FlatLaf is a UI Look-and-Feel library with a generally secure architectural design. No critical vulnerabilities were identified. Minor concerns include: (1) native code integration via JNI/C++ which requires ongoing security review, (2) theme loading capabilities that could be exploited if sources aren't properly validated, and (3) configuration loading from properties and external sources. The codebase appears well-maintained with proper CI/CD workflows (GitHub Actions). No hardcoded secrets or SQL injection vectors were identified in the file structure. Recommendations focus on ensuring strict validation of external inputs (themes, configurations) and keeping native dependencies current.

• Low · Build Script with Custom JAR Reordering — buildSrc/src/main/java/ReorderJarEntries.java. The buildSrc/src/main/java/ReorderJarEntries.java file suggests custom JAR manipulation during build process. While not inherently dangerous, custom build tools can introduce supply chain risks if not properly reviewed. Fix: Ensure this build tool is peer-reviewed, document its purpose clearly, and verify it doesn't modify security-sensitive bytecode.
• Low · Native Code Integration (JNI/C++) — buildSrc/src/main/kotlin/flatlaf-cpp-library.gradle.kts, buildSrc/src/main/kotlin/flatlaf-jni-headers.gradle.kts. The project includes JNI headers and C++ library integration (flatlaf-cpp-library.gradle.kts, flatlaf-jni-headers.gradle.kts). Native code can introduce memory safety issues and platform-specific vulnerabilities. Fix: Ensure all native code undergoes security review, use static analysis tools for C++ code, and keep native dependencies updated. Consider using memory-safe alternatives where possible.
• Low · Theme Loading from External Sources — flatlaf-core/src/main/java/com/formdev/flatlaf/IntelliJTheme.java. The IntelliJTheme.java file suggests loading themes that may come from external sources (IntelliJ Platform themes). This could potentially load and execute untrusted theme configurations. Fix: Implement strict validation for theme files, use digital signatures for theme verification, and sanitize all theme configuration inputs.
• Low · UI Defaults Loader — flatlaf-core/src/main/java/com/formdev/flatlaf/UIDefaultsLoader.java. UIDefaultsLoader.java loads UI defaults which could be source of injection if loaded from untrusted configuration files. Fix: Validate and sanitize all UI defaults sources, use allowlists for accepted configuration keys, and avoid executing arbitrary code through UI defaults.
• Informational · Property-Based Theme Configuration — flatlaf-core/src/main/java/com/formdev/flatlaf/FlatPropertiesLaf.java, flatlaf-core/src/main/java/com/formdev/flatlaf/FlatSystemProperties.java. FlatPropertiesLaf.java and FlatSystemProperties.java suggest property-based configuration which could be affected by system property injection if not properly validated. Fix: Implement input validation for all property sources, use type-safe configuration where possible, and document which system properties are accepted.

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.