New app checklist
The rules of this edition, cut down to what a new app meets before its first release: every MUST, grouped by area, and
the SHOULDs worth doing first. Each group links to the page with the rules and the Editora code to copy, and each line
names its rules. Every MUST of this edition is on a line; a line marked SHOULD holds only SHOULDs. A rule’s level is
the one on its own page, and npm run check fails when a line here disagrees with it.
Start from the template. adl-desktop-app-template is a GitHub template repository: a
small runnable app with its tests, CI and release workflows and every repository document, made toward the edition its
README names; its Pauta window lists what is left. Click Use this template, run scripts/rename.sh <AppName> <package>, then add any rule on this list from a later edition.
Conformance
Section titled “Conformance”Conformance · Pauta window · About window
- The app implements one edition, named by
pauta.versioninpom.xml, and states its conformance: Complete, Core or Partial · PAUTA-01 - A new app’s first release is at Core or Complete · PAUTA-03
- Every MUST and SHOULD the app does not meet is an exception in
pauta.json: not applicable, a deviation (SHOULDs only) with a decision record, or pending with an issue in the app’s own repository, each with a one-sentence reason · PAUTA-04, PAUTA-05, PAUTA-06, PAUTA-07, PAUTA-08, PAUTA-09 - A template repository says so in its
pauta.jsonand records the rules only an app made from it can meet asapp-only· PAUTA-16 - The conformance is computed from the exceptions by one helper, never stored, and a test holds the README to it · PAUTA-02
-
PautaConformanceTestcheckspauta.jsonagainst the edition’srules.json, and the README’s badge and line show the edition and the conformance · PAUTA-10, PAUTA-15 - Where
pauta.jsonhas acheckedlist, each entry records a by-hand rule a person checked and found met, and none is stale; an app that records none meets the rule · PAUTA-18 -
AGENTS.mdhas a section on Pauta that names the edition and links its numberedllms.txt· PAUTA-17 - About links the edition, Built to Pauta x.y.z or at Partial Working toward Pauta x.y.z, read from
pauta.version, and shows the conformance with a link that opens the Pauta window · ABOUT-05, ABOUT-06, ABOUT-07, ABOUT-08, ABOUT-09 - A Pauta window,
help.pauta, in the palette and in the Help menu where the app has one, listing every exception with fixed links · PWIN-01, PWIN-02, PWIN-03, PWIN-04 - A Pauta conformance page in the user docs with the same list · PAUTA-13
- That page generated from
pauta.jsonSHOULD · PAUTA-14
Platform
Section titled “Platform”- JDK 25 or newer (
release25 is the floor, and no enforcer rule refuses a newer JDK, in the main build or in a profile that turns itself on) and JavaFX 27 or newer · PLAT-01, PLAT-03 - A jlinked runtime in every installer, so users never install Java SHOULD · PLAT-02
- One named JPMS module · PLAT-04
- Maven Wrapper committed (
mvnw,mvnw.cmd,.mvn/wrapper/) · PLAT-08 - AtlantaFX 3 controls, and app stylesheets that take their colors from its
-color-*tokens or from tokens the app builds on them · PLAT-05, ICON-08
Same on every OS
Section titled “Same on every OS”- Every command, setting and window on Windows, macOS and Linux, with the same defaults; one the OS can’t serve is disabled and says why · OS-01
- One class answers which OS the app runs on, and no other class reads
os.name· OS-02 - A test runs as each OS and finds the same commands, menu rows and settings pages SHOULD · OS-03
- Nothing behaves or is laid out differently by OS, except as the table “Where the OS’s way wins” says · OS-04
Code quality
Section titled “Code quality”- Every package
@NullMarked; NullAway on Error Prone fails the build · PLAT-09 - Spotless with Palantir Java Format; CI fails an unformatted change in a Format job of its own · PLAT-10
- JUnit 5 and headless FX tests (
-Dglass.platform=Headless), every FX test class carrying one JUnit tag (Editora’sfx) · PLAT-11, QUAL-06 - JaCoCo check at 0.90 lines and 0.90 methods, which no profile that activates by OS or by JDK version lowers or skips · PLAT-12
- What decides whether a control is enabled or shown, or where a key or a click leads, lives in pure, unit-tested helpers; UI classes stay thin SHOULD · QUAL-05
- A capture hook or headless screenshot drives the real window for UI checks · QUAL-09
Performance
Section titled “Performance”- No I/O, process, parsing or waiting on the JavaFX application thread, but for the wait for the config read and the reading of the bundled resources the first window is built from (its fonts, the message catalog, the keymap, its icons) at start-up, and the last save as the app quits; results return through
Platform.runLater· PERF-01, PERF-02 - Background results applied under a generation guard; blocking work kept off the common pool · PERF-03, PERF-05
- Redraws coalesced to one per pulse; a stream the app shows delivered in batches; work only on what is visible and changed, with a virtualized control for a list the user or the data can grow without a limit the app sets · PERF-06, PERF-07, PERF-08
- Text-driven work that leaves the FX thread or outlasts a frame waits for typing to pause; filtering an in-memory list is exempt · PERF-23
- Logs, histories and caches bounded; large inputs guarded; a closed window releases what it held · PERF-11, PERF-12, PERF-13
- Only the first frame built before it paints; update check and extras deferred · PERF-14, PERF-15
- Every thread named and a daemon SHOULD · PERF-04
Keyboard and commands
Section titled “Keyboard and commands”Keyboard first · Command Palette · Find bar
- One command registry: every action is a command with an id, its title and one-line description from the message catalogs · KBD-01, KBD-03
- One Command Palette in each main window,
M-xin the Emacs keymap andCtrl+Shift+Pin the others or in an app’s one key table, an in-scene overlay, as every picker is (never aPopup), that lists every command · KBD-05, KBD-07, PAL-01, PAL-02 - Emacs and CUA keymaps at least, each
.mac.jsonvariant binding the same commands, with user overrides on top · KBD-09, KBD-21, KBD-11 - A find bar in the scene wherever there is text to search, the Debug Log window included: searches as you type with a count, Enter and Shift+Enter step, Escape closes it and, over a terminal, never reaches the shell; an app whose main content is a list filters it instead, and so does a log shown as a list · FIND-01, FIND-02, FIND-03, FIND-06, FIND-07
- One QuickOpen-style picker for every list choice (themes, keymaps, recent items, a setting’s values), and in an app with a picker, the picker in the overlay host SHOULD · QOPEN-01, QOPEN-02
Accessibility
Section titled “Accessibility”- Every control reachable with Tab and operable with Space or Enter, except controls whose command the keyboard reaches another way; every button, toggle, menu button, link, combo box, check box, radio button and text field shows the focus ring when the keyboard focuses it · KBD-15, KBD-16
- The focus ring 2 px wide at the default zoom, just outside the control, taking no room in the layout SHOULD · KBD-22
- A find-bar or filter control out of the Tab order only where a command does its work, or a key the bar’s field handles does · FIND-16
- Every control a person can reach has an accessible name, rows drawn from graphics included, held by a test · ACC-01
- Custom controls state their role and state; canvas content is exposed to the screen reader SHOULD · ACC-02, ACC-03
- Animations follow the OS’s reduced motion; color is never the only signal SHOULD · ACC-04, ACC-05
Window shell
Section titled “Window shell”Window shell · Welcome page · Confirm dialog · About window
- In an app with a menu bar: on Windows and Linux, the menu bar in the title bar (
HeaderBar) by default, with a setting to fall back to a decorated window; on macOS, the system menu bar · WIN-03 - A status bar whose echo area shows the last action’s feedback, errors in red and warnings in amber, and opens the Message Log on a click · WIN-01
- Every destructive action asks first, or can be taken back instead; where the app asks, the question names the thing, the button names the action in red, and Escape cancels · CONF-01, CONF-02, CONF-03, CONF-04
- Every such question has one default button, never the red one: Cancel, or Save where saving is an option, so Enter destroys nothing · CONF-13
- The buttons of every dialog with two or more buttons, a text prompt and a form included, are worded from the message catalog, never JavaFX’s stock OK, Yes, No, Cancel, Apply or Close · CONF-14
- Dialog buttons in one order on every OS, Cancel to the left of every action · WIN-11
- A UI zoom that scales the whole chrome, menus included, applied at once and kept across launches, with commands to zoom in, out and back · WIN-12
- One quit method for every quit entry point the app has: the Quit row, the
app.quitcommand and the system’s own Quit · WIN-13 - A Quit in every app: the
app.quitcommand and, where the app has a File menu or a main menu, a Quit row in that menu that runs the command · WIN-14 - On macOS, Settings in the application menu, showing the active keymap’s chord SHOULD · WIN-15
- About from the
help.aboutcommand, the Help menu where the app has one (a menu bar’s, or a Help submenu of its main menu), and the macOS application menu: version and build, runtime, license, links to the home page, the source code and the releases, and the last update check · ABOUT-01, ABOUT-02 - A Welcome page when there is nothing to restore, or an empty state that names the ways in with their chords SHOULD · WELC-01, WELC-02
Icons and color
Section titled “Icons and color”- Inter’s four faces bundled, registered before any CSS, and attached by a scene stylesheet to every scene, dialogs and popups included · ICON-01, ICON-02
- Light and dark themes switched at run time, a theme setting that offers “follow the system”, and an unknown theme falling back to the default · ICON-15, ICON-16, ICON-17
- State colors named once on
.rootfrom the theme’s roles, no fixed color in a component rule, whatever its spelling (a hex,rgba(),white) · ICON-07, ICON-08 - Tinted text at 4.5:1 on its fill and on both grounds;
-color-fg-emphasison an emphasis fill; one focus ring; a contrast test holds each · ICON-10, ICON-11, ICON-12 - Where the icons come in two families, each glyph in one family’s style class; the same glyph for an action everywhere it is reached, every glyph set credited in
NOTICE· ICON-19, ICON-20, ICON-24 - Readable text in
-color-fg-mutedor stronger, held by a contrast test · ICON-09 - The contrast tests pure: they read the stylesheets without starting the toolkit SHOULD · ICON-14
Toolbars and tooltips
Section titled “Toolbars and tooltips”- Icon-only buttons built by one helper that sets the tooltip and the accessible name from one string, chord included (
Icons.button,Icons.name) · TBAR-01 - In an app with a toolbar, its buttons out of the Tab order; every tooltip names the command and its chord from the active keymap · TBAR-02, TBAR-03
- Every tooltip shown after the same 400 ms delay SHOULD · TBAR-14
- A toolbar never holds the only way to an action · TBAR-08
- Groups separated by spacing on one chrome band, no hairlines; a toggle wears
:openwhile it is on SHOULD · TBAR-04, TBAR-06, TBAR-07 - The main toolbar: its icons overflow and its pinned tail never does, Settings last with Simple mode before it, buttons disabled while their command can’t act, a command hides the bar, and the bar keeps its height SHOULD · TBAR-15, TBAR-16, TBAR-17, TBAR-18, TBAR-19
Tabs and panels
Section titled “Tabs and panels”- In an app whose main window holds documents or sessions in tabs the user opens and closes: every tab operation is a command, on every tab of the strip, whatever it shows; a terminal app’s tabs have no close unmodified and no close all · TABS-01
- One tab header carries the title and the states:
•and amber italic for unsaved, a pin and bold for pinned, muted italic for read-only (TabHeaders); in a terminal, the running program as the title and a mark for a notification, bell or activity · TABS-02, TABS-03 - Bulk close skips pinned tabs, pinning moves a tab to the end of the pinned group, and Reopen Closed Tab brings the last one back (
ClosedTabs) · TABS-04, TABS-05, TABS-06 - A
tool.<id>command shows and hides each tool panel, onM-1toM-0in the Emacs keymap, and a panel’s content is built on first use (ToolWindowManager) · TABS-13, PERF-14 - Each panel’s place and size restored on the next launch SHOULD · TABS-15
- In an app with a menu bar, its rows are commands: title, chord and any icon from the registry and the active keymap, no
KeyCombinationaccelerators · MENU-01, MENU-02 - Every row of every menu the app draws, right-click menus and drop-downs included, shows its chord when bound · MENU-15
- The menus the app draws are in Inter 14 px at the default zoom whatever they were opened from, and follow the UI zoom (
.context-menusets the size from the zoom’s one value) · MENU-16 - Menu rows 34 px high with a 22 px icon column, the chord at least 18 px after the title, on a card whose shadow’s offset is at least its radius SHOULD · MENU-18
- In an app with a right-click menu: every row, tab, editor and read-only console, a log shown as text such as the Debug Log among them, has one with its own actions, each a command; a list that only navigates has none · MENU-05
- One right-click menu at a time; a press anywhere outside closes it, and so does Escape, returning focus (
ContextMenuDismissal) · MENU-06, MENU-07, MENU-08 - Right-click menus open from the Menu key and Shift+F10 at the selected row, or for the focused view where it has no rows (
RowContextMenu) · MENU-09
Tray and background
Section titled “Tray and background”Tray and background (for an app that keeps working without its window)
- The tray is a StatusNotifierItem on Linux, with no AWT fallback, and AWT’s
SystemTrayon Windows and macOS, and the app is fully usable when no icon comes up, its status line saying why · TRAY-01, TRAY-02 - Closing the window hides it only while an icon is up and the setting says so; the tray’s Quit runs the app’s one quit method and ends the program with the window hidden · TRAY-03, TRAY-04
- Start at login writes the OS’s own entry (XDG autostart, LaunchAgent,
HKCURun), and--minimizedcomes up behind the icon, minimized when the tray setting is off, and shown when an icon was asked for and none came SHOULD · TRAY-05, TRAY-06
Notifications (for an app that sends desktop notifications, with a tray or without one)
- Desktop notifications through one notifier, the text passed as data and never as part of a script and the call timed out after ten seconds or less, for what happened while the window was away, one switch per kind of event, most of them off at first · TRAY-09, TRAY-10
Settings
Section titled “Settings”- Settings window from a palette command (
Ctrl+,), with a page sidebar and search · SET-01, SET-02, SET-03 - Live apply with no Save button, a setting that waits for a restart saying so on its row, and a palette command for every setting the Settings window shows · SET-04, SET-06
- Config in
~/.<app>on Windows, macOS and Linux alike, unless a flag or, after it, the environment variable names another folder; versioned with migrations, a file newer than the build backed up and defaults loaded · SET-07, SET-09, SET-10 - Config read with suspicion: values clamped on load, an unreadable file kept as a backup and defaults loaded · SET-11
- A config file written whole or not at all: to a temporary file beside it, then moved into place · SET-22
- Export and import of the config folder · SET-12
- A secret the user gave the app, where the app keeps it, never in a config file: in the OS keychain, or in memory for the session where no keychain answers; a credential the app does not keep held in memory only, never written · SET-13, SET-14
- A secret in the wrong place refused (a sync URL with a password), and an option that weakens security only a config key · SET-15, SET-16
- Settings Sync in an app with user data worth carrying between computers, through a Git repository the user owns SHOULD · SYNC-01, SYNC-02
Diagnostics
Section titled “Diagnostics”Diagnostics and support · Message Log
- Message Log of the session’s echo-area messages · DIAG-01
- Debug Log with a session file in its own window, and an uncaught exception handler installed at the start of
mainthat posts an echo message · DIAG-02, DIAG-03, DIAG-04 - Daily update check, started at least three seconds after the first frame, a status-bar notice of a newer version, Check for Updates and an off switch · DIAG-05, DIAG-09, DIAG-10
- Report a Problem builds a report with the version, the OS, the runtime, a settings summary and the recent Debug Log · DIAG-06
- A problem report redacted before it is shown: home paths, user names, e-mail addresses, credentials, tokens · DIAG-11
- Report a Problem shows the report editable, copies it and opens a prefilled GitHub issue; nothing is uploaded · DIAG-12
- A report too long for the issue link (7,500 characters) is pasted from the clipboard · DIAG-13
Command line and languages
Section titled “Command line and languages”Command line · Internationalization
-
--help,--version,--config-dir,--devand--report, which writes its file in the current folder · CLI-01, CLI-02, CLI-05 - An unknown option stops the launch with a message and exit status 2; in an app that opens files named on its command line,
-and what follows--are files; a launcher’s own JVM options are skipped · CLI-12 -
-hfor help,-vand-Vfor the version SHOULD · CLI-13 - On Windows, a console launcher (or an attached console) so the flags print · CLI-11
- Single instance per config folder · CLI-07
- Six message catalogs, each with every key · INTL-01, INTL-08
- The language chosen, else the system’s, else English; dates, numbers and the catalog’s messages keep the system’s region · INTL-14
Repository
Section titled “Repository”-
README.mdas a landing page of at most 250 lines, with the badge row and the hero screenshot · REPO-01 -
CHANGELOG.mdin Keep a Changelog format · REPO-02 - MIT
LICENSE, andNOTICEwith every third-party license · REPO-03, REPO-04 -
AGENTS.md, with a shortCLAUDE.mdpointing to it · REPO-05, DOCS-14 -
CONTRIBUTING.md,docs/andbranding/· REPO-06, REPO-07, REPO-10 -
.github/ISSUE_TEMPLATE/bug_report.yml· REPO-09 - Scripts in Java, run by the JDK as source files, or in
shor bash SHOULD · REPO-11
Documentation
Section titled “Documentation”- User docs on the app’s website under
/docs/: Getting started, a page per feature area, the keyboard reference, Settings and an FAQ, and no page in the app’sdocs/with a section that tells the app’s user how to install or use something · DOCS-01, DOCS-02 - The
help.documentationcommand opens the user docs, with a Documentation row where the app has a Help menu · DOCS-06 - Release notes written for users, and in an app with a Welcome page, its What’s New opens this build’s release · DOCS-05
-
docs/README.mdindexes the contributor guides · DOCS-12 - Docs change with the code, the website’s in a pull request opened with it; when they disagree with the code, the code wins and the docs are fixed, as
AGENTS.mdanddocs/README.mdsay · DOCS-16, DOCS-17 - Where the app has a Help menu, its rows in the family’s order, Documentation first after the Command Palette, then the keyboard reference SHOULD · DOCS-07
- Every link from the app into its user docs opens the running version’s docs,
/docs/v-<version>/SHOULD · DOCS-03 - Command and keybinding references generated from the source, with a check that quoted ids and chords exist SHOULD · DOCS-04
Packaging and signing
Section titled “Packaging and signing”Packaging, signing and release
- jpackage installers for Linux x64 and arm64, macOS arm64 and x64 and Windows x64; JReleaser creates the GitHub release with every download · REL-01, REL-03, REL-11
- The version in
pom.xmlis the one source: avX.Y.Ztag releases it · REL-05 - macOS
.dmgsigned with Developer ID, notarized and stapled · REL-15 - Linux downloads with
.ascsignatures from the shared release key · REL-16 - Build provenance attestations for every download · REL-18
- Windows
.msiAuthenticode, once the certificate is chosen SHOULD · REL-17 - Homebrew cask in
adriandeleon/homebrew-tapand a winget packageAdrianDeLeon.<App>SHOULD · REL-12, REL-13
CI/CD (GitHub Actions)
Section titled “CI/CD (GitHub Actions)”- The CI workflow on every push to the default branch and every pull request: a format check and the build with its tests, both required checks · REL-19
- The release workflow on a version tag that matches the pom, with a
workflow_dispatchdry run · REL-21 - A release cut only from a commit whose tests passed: the release workflow runs them, or its preflight reads CI’s result · REL-30
- Every third-party action pinned to a commit SHA, with its version in a comment · REL-22
- Dependabot for
github-actionsandmaven, weekly · REL-23 -
permissions: contents: readby default, or none at all; write only in the jobs that need it · REL-24 -
timeout-minuteson every job that runs steps · REL-26 - A
concurrencygroup on every pull-request workflow that cancels a superseded pull-request run, and never a run on the default branch · REL-31 - Test and coverage reports uploaded; coverage totals in the job summary · REL-27
- Signing skipped without secrets, but a tag without them fails · REL-28
- A smoke launch of the packaged app on each OS before release · REL-29
- The tests on all three OSes, daily or on every pull request, and before every release · REL-20
Pauta 6.1.0 · · Changelog · This page in the latest edition