Skip to content
Pauta4.4.0

Icons and color

One typeface pair, one palette, one color vocabulary and one way of drawing icons, so a tab, a status segment, a tree row and a Settings row say the same thing in the same way in every app. Reference: Editora’s styles/ui-font.css and ui/Fonts.java (type), styles/atlantafx-themes/editora-light.css and editora-dark.css (the Caret & Ink palette, which Torrenta and Termina vendor), the .root block at the top of styles/app.css (the state vocabulary), ui/Themes.java and ui/EditorThemes.java (themes), ui/Icons.java, ui/FileIcons.java, ui/MenuBarIcons.java and editor/MenuIcons.java (icons), and StyleContrastTest, which pins the color rules.

Rules on this page 21
IDLevelRule
Type
ICON-01MUST
Inter is attached by a scene stylesheet on every window’s scene, dialogs, popups and tooltips included, not by a rule in the app stylesheet.
ICON-02MUST
The app bundles Inter’s four faces and registers them before any CSS is applied; it never maps the platform’s own UI font.
The palette: Caret & Ink
ICON-04SHOULD
A theme file follows the vendored AtlantaFX community themes: a .root block of -color-* tokens, then component rules that reference only those tokens.
ICON-05SHOULD
A new app ships the Caret & Ink pair as its default theme, with editora-light.css and editora-dark.css copied unchanged into its own styles/.
ICON-06SHOULD
Brace (-state-key) is a ladder() over -color-bg-default that picks a deep ink on a light ground and a lighter periwinkle the darker the ground gets, and reads at 4.5:1 or more on every bundled theme’s default and subtle surfaces.
State colors
ICON-07MUST
Each state color is named once, as a -state-* token on .root that chains to one of the theme’s roles (or a ladder() of its ground), and component rules use the token.
ICON-08MUST
No fixed hex in a component rule.
ICON-09SHOULD
Readable text uses -color-fg-muted or stronger, which is 4.5:1 on the default, subtle and overlay grounds in both flagship themes: a line of UI text is -color-fg-default and secondary text -color-fg-muted. -color-fg-subtle (about 3:1) is for disabled or decorative text only.
ICON-10MUST
Tinted text (-color-<role>-fg) reaches 4.5:1 on its own subtle fill and on both grounds.
ICON-11MUST
Ink on an emphasis fill is -color-fg-emphasis, never white.
ICON-12MUST
One focus ring, -focus-ring: -color-accent-emphasis, drawn by the :focus-visible block at the end of app.css, at 3:1 or better on every surface (see Keyboard first).
ICON-13SHOULD
A brand hue the theme has no role for (periwinkle, olive, violet) is a ladder() of -color-bg-default, never a fixed pair.
ICON-14SHOULD
A pure test reads the stylesheets and does the WCAG arithmetic.
Themes
ICON-15MUST
The app has light and dark themes and switches between them at run time, without a restart (see Window shell).
ICON-16MUST
A “follow the system” choice applies the light or dark theme to match the system’s color scheme, and changes with it.
ICON-17MUST
A theme name the app does not know falls back to the first-run default theme.
ICON-18SHOULD
Semantic colors never decorate: a theme may change the teal, the ground and the ink, but amber still means “not durable yet”, red “broken” and green “verified”.
Icons
ICON-19MUST
A glyph node carries one family’s style class, icon-line or toolbar-icon, never both.
ICON-20MUST
The same action wears the same glyph wherever it is reached: Save is one floppy on the toolbar, in the File menu and in a tab’s menu.
ICON-23SHOULD
A file’s icon comes from a pure function from file name to icon key, unit-tested without the toolkit, and any type it does not know gets the generic document glyph, so a new type never regresses the look.
ICON-24MUST
Every glyph set and font the app ships is credited in NOTICE with its license.

Inter speaks, JetBrains Mono works. Inter is the chrome: menus, buttons, settings, pickers, status bar. The monospace face is for text that is code or output: the editor, a terminal, the environment block in About, log timestamps.

PropertyValueReference
UI familyInter, in four faces, bundled in the app’s resources and registered before any CSS is appliedFonts.UI, Fonts.loadForFirstPaint, resources/com/editora/fonts/inter/
Root size14 px, the AtlantaFX theme’s root size; popups pin absolute pixels where an owner’s font would leak (see Menus)MainMenuBar.UI_FONT_SIZE
How it is attachedA scene stylesheet (ui-font.css, one .root rule whose -fx-font-family names Inter) on every window’s scene, dialogs and popups includedApp.installUiFont
MonospaceJetBrains Mono by default; Cascadia Code, Fira Code, IBM Plex Mono and Source Code Pro are bundled as editor choicesFonts.DEFAULT, Fonts.BUNDLED
  • ICON-01 MUST Inter is attached by a scene stylesheet on every window’s scene, dialogs, popups and tooltips included, not by a rule in the app stylesheet.
    • Why: dialogs, the Settings window, the palette, context menus and tooltips each live in a scene of their own that does not share app.css, and a scene sheet is re-applied cleanly when the theme switches at run time (setUserAgentStylesheet). AtlantaFX neither bundles nor names Inter, and JavaFX does not fall through a font-family list, so without the sheet the whole interface renders in the platform’s “System” face.
    • Check (code): a listener on Window.getWindows() adds ui-font.css to each window’s scene, and to a new scene when the window’s scene changes; no .root rule in app.css sets -fx-font-family.
    • Reference: Editora App.installUiFont, styles/ui-font.css. Termina and Torrenta carry the same sheet.
  • ICON-02 MUST The app bundles Inter’s four faces and registers them before any CSS is applied; it never maps the platform’s own UI font.
    • Why: an earlier macOS-only sheet used San Francisco, which JavaFX faux-bolds; Inter has a real bold on every platform.
    • Check (code): Inter-Regular, Inter-Bold, Inter-Italic and Inter-BoldItalic .ttf are under the app’s fonts/inter/ with their OFL.txt, and Font.loadFont runs on them before the first window is shown.
    • Reference: Editora src/main/resources/com/editora/fonts/inter/, ui/Fonts.java (loadForFirstPaint, called from App). Termina and Torrenta bundle the same four faces.

Modula is the stated exception to ICON-01 and ICON-02: IBM Plex Mono everywhere, because every reading on a radio is a number (see Before adding a setting in Settings).

The flagship theme pair, “Editora Light” and “Editora Dark”, is authored (not vendored) and derived from Editora’s icon: a caret teal accent, ink navy as the text in light and the surface in dark, porcelain and abyss grounds, and brace periwinkle reserved for the keyboard. Amber, red and green are semantic and never decorate.

  • ICON-04 SHOULD A theme file follows the vendored AtlantaFX community themes: a .root block of -color-* tokens, then component rules that reference only those tokens.
  • ICON-05 SHOULD A new app ships the Caret & Ink pair as its default theme, with editora-light.css and editora-dark.css copied unchanged into its own styles/.
    • Why: the palette is the family’s, not the editor’s.
    • Check (code): the app’s two files are identical to Editora’s.
    • Reference: Torrenta and Termina styles/. Both copies of editora-dark.css match Editora’s; both copies of editora-light.css still have the earlier -color-accent-fg, -color-warning-fg and -color-success-fg, which Editora has since darkened.
  • ICON-06 SHOULD Brace (-state-key) is a ladder() over -color-bg-default that picks a deep ink on a light ground and a lighter periwinkle the darker the ground gets, and reads at 4.5:1 or more on every bundled theme’s default and subtle surfaces.

A color is a meaning, named once on .root and referenced everywhere. The same state wears the same color in a tab, a status segment, a tree row, a picker and a Settings row.

TokenChains toMeaningWhere it appears
-state-amber-color-warning-fgNot durable yetAn unsaved tab, a read-only file, a narrowed view, a snapshot build
-state-red-color-danger-fgBrokenErrors in the echo area and the Message Log, breakpoints, a recording
-state-green-color-success-fgVerifiedFound, added, passing, running
-state-accent-color-accent-fgThe app is offering somethingAn update, a link, the current branch, a selected row’s bar
-state-olive, -state-violetA ladder of the groundGit only: untracked, renamedThe Project tree and tabs, the Map’s structure columns
-state-keyA ladder of the groundThe keyboard, and nothing elseChord chips, the menu chord column, brace matching
-state-sel-color-accent-subtleThe selected overlay rowThe palette, pickers, the Message Log (about a 13 % accent wash)

Each of the first four also has a -bg (the role’s -subtle) and a -hover (the role’s -muted) variant, so a pill, a row tint and a hover state come from the same place. .state-pill is the shape (bold, radius 999, padding 1 × 8); the color variant beside it carries the meaning.

  • ICON-07 MUST Each state color is named once, as a -state-* token on .root that chains to one of the theme’s roles (or a ladder() of its ground), and component rules use the token.
    • Check (code): the -state-* tokens are declared only in the .root block at the top of app.css, each chaining to a -color-* role or a ladder().
    • Reference: Editora styles/app.css (.root).
  • ICON-08 MUST No fixed hex in a component rule.
    • Why: a hex suits one theme; the roles track every theme for free.
    • Check (code): outside the .root token block, app.css holds no # hex. A test fails a severity or debug color that is not a state token.
    • Reference: Editora StyleContrastTest.severityAndDebugColoursComeFromTheStateTokens. Editora doesn’t yet pass the whole check: .breakpoint-marker, .exec-arrow, .view-mode-bar, .recent-remove, .personal-note-tooltip-content, the fold-gutter markers and the default editor and Markdown preview palettes in app.css still carry fixed hexes.
  • ICON-09 SHOULD Readable text uses -color-fg-muted or stronger, which is 4.5:1 on the default, subtle and overlay grounds in both flagship themes: a line of UI text is -color-fg-default and secondary text -color-fg-muted. -color-fg-subtle (about 3:1) is for disabled or decorative text only.
  • ICON-10 MUST Tinted text (-color-<role>-fg) reaches 4.5:1 on its own subtle fill and on both grounds.
  • ICON-11 MUST Ink on an emphasis fill is -color-fg-emphasis, never white.
  • ICON-12 MUST One focus ring, -focus-ring: -color-accent-emphasis, drawn by the :focus-visible block at the end of app.css, at 3:1 or better on every surface (see Keyboard first).
  • ICON-13 SHOULD A brand hue the theme has no role for (periwinkle, olive, violet) is a ladder() of -color-bg-default, never a fixed pair.
  • ICON-14 SHOULD A pure test reads the stylesheets and does the WCAG arithmetic.
    • Why: a contrast regression is invisible in a code diff.
    • Check (code): a test class reads the app’s .css resources and computes contrast ratios without starting the toolkit.
    • Reference: Editora StyleContrastTest. Mirada’s AccentTest checks that the accent reads as text on both grounds; Termina’s ThemeTest keeps every chromatic color of its terminal schemes legible.
  • ICON-15 MUST The app has light and dark themes and switches between them at run time, without a restart (see Window shell).
    • Check (code): picking a theme calls Application.setUserAgentStylesheet in the running app.
    • Reference: Editora ui/Themes.java (applyAppTheme).
  • ICON-16 MUST A “follow the system” choice applies the light or dark theme to match the system’s color scheme, and changes with it.
    • Check (code): the theme setting has a system value, and a listener on Platform.getPreferences().colorSchemeProperty() re-applies the theme.
    • Reference: Mirada settings/Settings.java (ThemeChoice.SYSTEM), ui/Theme.java; nux config/Advanced.java (THEME_SYSTEM), ui/Theme.java. Editora, Torrenta, Termina and Modula don’t yet: their pickers list named themes only.
  • ICON-17 MUST A theme name the app does not know falls back to the first-run default theme.
    • Check (code): the lookup from a saved name to a theme ends in the default, not an exception.
    • Reference: Editora Themes.themeFor, falling back to Themes.DEFAULT (Editora Light).
  • ICON-18 SHOULD Semantic colors never decorate: a theme may change the teal, the ground and the ink, but amber still means “not durable yet”, red “broken” and green “verified”.
    • Check (code): every rule that uses -state-amber, -state-red or -state-green marks one of the meanings in the State colors table.
    • Reference: Editora app.css.

Editora lists 28 app themes: the Caret & Ink pair, AtlantaFX’s Primer, Nord, Cupertino and Dracula, and 19 community themes (Army, Autumn, Blacky, Blue, Browny, Fall, Navy, News, Spring, Summer, Winter, Yacht, several with light and dark variants) vendored unmodified from the MIT-licensed dlsc atlantafx-themes collection. User themes under <config>/themes/ join the list (Themes.names()).

Editor themes are separate (EditorThemes). The flagship pair carries its own editor stylesheet; every community theme is served by one adaptive editor theme whose syntax palette is expressed in the theme’s own -color-* tokens, so it follows whatever ground the theme has.

Editora's Settings page for themes and fonts
Settings: the theme picker with the Caret & Ink pair first, and the UI and editor fonts.

Every icon is an SVG path drawn in code, colored by the stylesheet so it follows the theme, and returned as a fresh node per call (a JavaFX node has one parent). There are two families, mid-migration to the UI Kit, and they are not interchangeable.

PropertyLine familyFilled familyReference
SourceThe UI Kit’s 16-unit outline glyphs, drawn for the kitMaterial Design 24 dp single-path glyphs (Apache-2.0), plus Simple Icons brand marks (CC0)Icons.line, Icons.of, NOTICE
Style classicon-linetoolbar-iconapp.css
Color-fx-stroke: -color-fg-muted, stroke width 1.3, round caps and joins, fill transparent-fx-fill: -color-fg-muted.icon-line, .toolbar-icon
Hover, disabled-color-fg-default on hover, -color-fg-subtle disabled; every context mirrors the matching rule of the other familyThe same.button:hover .icon-line, .button:hover .toolbar-icon
Drawn size16 × 1.2 = 19.2 px (LINE_SCALE = ICON_SCALE × 24 ÷ 16)24 × 0.8 = 19.2 px (ICON_SCALE)Icons
Used forThe chrome the kit draws: toolbar, tool stripe, tabs, and every action that has a kit glyphEverything the kit specifies no glyph for: file types, context-menu rows, build-tool and browser brand marksIcons, FileIcons
  • ICON-19 MUST A glyph node carries one family’s style class, icon-line or toolbar-icon, never both.
    • Why: a line glyph is colored by its stroke, and any X .toolbar-icon fill rule (there are dozens) would paint its outline solid. A glyph that moves family moves its CSS with it.
    • Check (test): a test builds every line glyph and fails when one also carries toolbar-icon.
    • Reference: Editora ui/Icons.java (line, of), MenuIconFamilyFxTest.aLineGlyphIsNeverAlsoTaggedAsAFilledOne.
  • ICON-20 MUST The same action wears the same glyph wherever it is reached: Save is one floppy on the toolbar, in the File menu and in a tab’s menu.
  • ICON-23 SHOULD A file’s icon comes from a pure function from file name to icon key, unit-tested without the toolkit, and any type it does not know gets the generic document glyph, so a new type never regresses the look.
    • Check (test): a unit test resolves names to keys, an unknown one to the generic key.
    • Reference: Editora ui/FileIcons.java: iconKeyFor(name) resolves the key, forFileName turns it into a node; brand logos from Simple Icons, category glyphs (image, archive, PDF, table, lock, JSON, settings) from Material. FileIconsTest.unknownAndNullFallBackToGeneric.
  • ICON-24 MUST Every glyph set and font the app ships is credited in NOTICE with its license.
    • Check (code): each icon source named in the icon classes and each family under fonts/ has an entry in NOTICE.
    • Reference: Editora NOTICE: Material Design Icons (Apache-2.0), Simple Icons (CC0; the logos stay their owners’ trademarks), Inter and the monospace faces (OFL), and the glyph sets inside the bundled Symbols Nerd Font, Octicons and Seti UI (MIT) among them.

An icon-only control gets its tooltip and its accessible name from one helper (Icons.button, Icons.toolbarButton, Icons.name): TBAR-01.

AppIconsSize
EditoraBoth families, ui/Icons, FileIcons, MenuBarIcons, editor/MenuIcons19.2 px on the toolbar and in menus
TorrentaBoth families, copied from Editora as Icons.Glyph, which knows its box and resizes with at(px); the toolbar is all line glyphs (stroke 1.5, -torrenta-icon)17 px toolbar, 16 px menu and tab (MENU_SIZE), 13 px sidebar
TerminaMaterial filled, ui/MenuIcons, colored by .menu-icon (-color-fg-muted; -color-fg-default focused; subtle and half opacity disabled)24 × 0.7 = 16.8 px, menus only
MiradaHand-drawn stroked paths on a 24-unit grid, two-unit strokes, round caps, in GNOME’s symbolic style, so nothing carries a license; .icon strokes -color-fg-default16 px, centered in a 16 px box
ModulaGlyphs: the transport symbols (tune, seek, star) as shapes, because the characters are missing from most faces and render differently on every platform11 px
nuxNo in-window icons; the tray icon is rendered as a bitmap by severity (TrayIconRenderer)Tray only

Pauta 4.4.0 · · Changelog · This page in the latest edition