New app checklist
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 - The 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 tested helper, never stored · PAUTA-02
-
PautaConformanceTestcheckspauta.jsonand the README against the edition’srules.json· PAUTA-10, PAUTA-15 - About links the edition, Built to Pauta 4.3.0, read from
pauta.version, and shows the conformance · ABOUT-05, ABOUT-06, ABOUT-07, ABOUT-08, ABOUT-09 - A Pauta window,
help.pauta, in the palette, the Help menu and About’s link, listing every exception with fixed links · PAUTA-12, 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 JavaFX 27 or newer, with a jlinked runtime in every installer · PLAT-01, PLAT-02, PLAT-03 - One JPMS module,
com.<app>· 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 · PLAT-05, PLAT-06
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
Osclass readsos.name, and no other class does · OS-02 - A test runs as each OS and finds the same commands, menu rows and settings pages SHOULD · OS-03
Code quality
Section titled “Code quality”- Every package
@NullMarked; NullAway on Error Prone fails the build · PLAT-09 - Spotless with Palantir Java Format, checked in CI · PLAT-10
- JUnit 5 and headless FX tests (
-Dglass.platform=Headless), FX tests taggedfx· PLAT-11, QUAL-06 - JaCoCo check at 0.90 lines and 0.90 methods · PLAT-12
- Rules live in pure, unit-tested helpers; UI classes stay thin · 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; 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; streams delivered in batches; work only on what is visible and changed · PERF-06, PERF-07, PERF-08
- 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
CommandRegistry: every action is a command with an id, its title and description from the message catalogs · KBD-01, KBD-03 - One Command Palette per window,
M-xorCtrl+Shift+P, an in-scene overlay (not 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: searches as you type with a count, Enter and Shift+Enter step, Escape closes it; a list app filters instead · 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), 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 buttons whose command the keyboard reaches another way · KBD-15
- Every control a person can reach has an accessible name, rows drawn from graphics included · 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
- 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: the question names the thing, the button names the action in the
dangerstyle, Escape cancels; or the action can be taken back instead · CONF-01, CONF-02, CONF-03, CONF-04 - Dialog buttons in one order on every OS, Cancel to the left of the action · WIN-11
- About from Help,
help.aboutand the macOS application menu: version and build, runtime, license, links 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 “follow the system” choice, 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 hex in a component rule · 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 · ICON-10, ICON-11, ICON-12 - Icons in one family’s style class each, 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 pure contrast test over the stylesheets SHOULD · ICON-09, 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 (
Icons.button,Icons.name) · TBAR-01 - Toolbar buttons out of the Tab order; every tooltip names the command and its chord from the active keymap · TBAR-02, TBAR-03
- The toolbar never holds the only way to an action, and its right-click menu is one reused menu · TBAR-08, TBAR-10
- Groups separated by spacing on one chrome band, no hairlines; a toggle wears
:openwhile it is on SHOULD · TBAR-04, TBAR-06, TBAR-07
Tabs and panels
Section titled “Tabs and panels”- Every tab operation is a command · 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) · 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 command toggles each panel, and a panel’s content is built on first use (
ToolWindowManager) · TABS-13, TABS-14 - Panel side, order and divider positions restored on the next launch SHOULD · TABS-15
- Menu rows are commands: icon, title and chord from the registry and the active keymap, no
KeyCombinationaccelerators · MENU-01, MENU-02 - Every row of every menu, right-click menus and drop-downs included, has an icon that depicts it and its chord when bound · MENU-14, MENU-15
- Menus draw in Inter 14 px whatever they were opened from (
.context-menupins the font in pixels) · MENU-16 - Every row, tab and editor has a right-click menu with its own actions · 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 (
RowContextMenu) · MENU-09
Tray and background
Section titled “Tray and background”Tray and background (for an app that keeps working without its window)
- The shared
tray/package: StatusNotifierItem on Linux, AWT elsewhere, and the app fully usable without an icon · TRAY-01, TRAY-02 - Closing the window hides it only while an icon is up and the setting says so; Quit is explicit and one path · TRAY-03, TRAY-04
- Desktop notifications through one
Notifier, for what happened while the window was away, one switch per event · TRAY-09, TRAY-10 - Start at login writes the OS’s own entry (XDG autostart, LaunchAgent,
HKCURun), and--minimizedcomes up behind the icon SHOULD · TRAY-05, TRAY-06
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, and a palette command for every setting · SET-04, SET-06
- Config in
~/.<app>, 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
- Export and import of the config folder · SET-12
- No secret in a config file: keys and tokens in the OS keychain, a credential the app can ask for again in memory only · SET-13, SET-14
- A secret in the wrong place refused (a sync URL with a password, an unredacted problem report), and an option that weakens security only a config key · SET-15, SET-16
- Settings sync 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
main· DIAG-02, DIAG-03, DIAG-04 - Daily update check with an off switch · DIAG-05
- Report a Problem: a redacted, prefilled GitHub issue · DIAG-06
Command line and languages
Section titled “Command line and languages”Command line · Internationalization
-
--help,--version,--config-dir,--devand--report· CLI-01, CLI-02, CLI-05 - Single instance per config folder · CLI-07
- Six message catalogs, each with every key, held by a parity test · INTL-01, INTL-08
Repository
Section titled “Repository”-
README.mdas a landing page of about 200 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 one-lineCLAUDE.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
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 · DOCS-01, DOCS-02 - Help → Documentation as a command (
help.documentation) · DOCS-06 - A one-line
command.<id>.descfor every command, held by the parity test · DOCS-09 - Release notes written for users, and the Welcome page’s What’s New opens this build’s release · DOCS-05
-
docs/README.mdindexes the contributor guides · DOCS-12 - Docs change in the same PR as the code; when they disagree with the code, the code wins and the docs are fixed · DOCS-16, DOCS-17
- The Help menu in the family’s order, Documentation first after the Command Palette SHOULD · DOCS-07
- Deep links from the app open 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)”-
ci.ymlon every push and pull request: Format and Build & Test, both required checks formaster· REL-19 -
release.ymlon a version tag that matches the pom, with aworkflow_dispatchdry run · REL-21 - Every third-party action pinned to a commit SHA · REL-22
- Dependabot for
github-actionsandmaven· REL-23 -
permissions: contents: readby default; write only in publishing jobs · REL-24 -
timeout-minuteson every job; superseded pull-request runs canceled · REL-26 - 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
-
full-tests.ymldaily, on afull-cilabel and before every release SHOULD · REL-20
Pauta 4.5.0 · · Changelog · This page in the latest edition