Update docs

docs/Gemfile

@@ -19,4 +19,4 @@ gem "wdm", "~> 0.1.0", :platforms => [:mingw, :x64_mingw, :mswin]
 
 # see Jekyll serve fails on Ruby 3.0
 # https://github.com/jekyll/jekyll/issues/8523
-gem "webrick", "~> 1.7"
+gem "webrick", "~> 1.7"

docs/_config.yml

@@ -15,13 +15,14 @@ title: AtlantaFX
 description: >- # this means to ignore newlines until "baseurl:"
   Modern JavaFX CSS theme collection with additional controls.
 baseurl: "/" # the subpath of your site, e.g. /blog
-url: ""     # the base hostname & protocol for your site, e.g. http://example.com
+url: ""      # the base hostname & protocol for your site, e.g. http://example.com
 github_username:  mkpaz
 
 # Build settings
 markdown: kramdown
 remote_theme: just-the-docs/just-the-docs
 search_enabled: true
+logo: "/assets/images/logo.jpg"
 
 # The following items will not be processed, by default.
 # exclude:

docs/assets/images/project-structure.drawio

@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2022-09-09T09:18:20.858Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36" etag="f5aypTZzrxLzWiXsjLRM" version="20.3.0" type="device"><diagram id="07fea595-8f29-1299-0266-81d95cde20df" name="Page-1">7Vpbc5s4FP41ntl9cAaEufjRceJmd2Z303Gnmz7KIAMNIFbIt/76lUDCIEHsNrabTJ0HBx3d9X3nogMDa5puPxCYR3/hACUDYATbgXU3AMA0LI/945JdJbFdtxKEJA5Eo71gHn9DsqeQruIAFa2GFOOExnlb6OMsQz5tySAheNNutsRJe9YchkgTzH2Y6NJ/44BGQmo6433FA4rDSEztAbG/BfSfQ4JXmZhvAKxl+VdVp1COJTZaRDDAm4bIuh9YU4IxrZ7S7RQl/GzlsVX9Zj219boJyugxHYABqi5rmKyQXHO5MrqTp4ECdjiiWKAwZWPf70W3BSX4GU1xgknZ3gIz+9ad1jXyBC0miWiasEeTPaIsmHCoWHGRYP+5Es3iRDbQ9yK2V+AV8SVSrhDyRTZaie1+QDhFlOxYA0lOZ3RjV112cghPSjYNsA0BUdTAuRZCQbCwHr+e8hHHbL31fACo84FRPZ8cptqR6NmESxnMdo32UOp6KCQhotpA7KDhrtEs5w2K/kWr85iu8V3rUtqzh2oFstQAZi8qqdnDa4lyg6aCGCpZN1FM0TyHJUE2zDxxHkotM1hhiTPaIOus/BPyGUzjhO/hASVrRGMfigpJf6PN4bKqsl4mO8vbPIFxNsxXJO/QjAxnXLhkDG8qy9JeuD6ThwQGMdqvTTQv2FbiLGQCh5XWiPBVJZMkDjMmS+MgKKfqVRbeA20HR2iGbbZB9AxdKUCHUjgv6ESDAQcAtn8VO3S0jSEogTRet13S8YbH9DRDN/5hwwNGlzE86jym+bLh6VvXqQxP8M/Hu48P5vZTMTSeplmUovWnIQNbI+sCFuhqi5q2SDM8HTp0tC2q+XYJY9QDuqeBXsCUHS654n4y3L0+O/PzcJezvUHPhLYxfWo8f+HsYCa+Kt1tBVnKwk4WMnYqT81Coxcv7ruVJdmv07sddIsv28/KaRxWul66AFf1cRY4ZzDveAo9x8oQx/pTdSDLfq0/bZH8FE4O6CF3yfjiau5OZu5MlU9vwNy99YTAYRP082Jux+oOX7/bPoyNy8Tb6jyH4u2+dZ033gbW6TnpgYXlOCdzwXu3+6VR0+2CA1hEKBDNeOERUopIVkp4Rk6zWIGNvGB0Fi/ca5uGY0fxrSPzrIkyd9ymlmrjjr6rqkkydaAzJcksNdd6YF1K+3Ppzugd6A54d8pTv5Z4bQg7NF37snqmmvAf1bPR2LyIngElF2AdSEarPso6cTK6hxCOpmc+zvk+fZzmccI4C4zpfM5+lwSnA678zn8r/qLnVsbVsyAu6F6s6SkLNGlbx6AISn3GYEReilYJKuJvcFGH1OLU2bj27cC+42OtKC5EZH1MJC1Eg9eHwZahvCGRzGrQH3SFwdb5wmA9xbeB1I84fGz3DNUIZiEHzYBZsEe5BpniFsTCToDZzc0N+6URStGQojbcYugI0yoUxTD4dTigeUdX48DowhzQM37zCQf3PUDSvEKr92b7RLdXR7k82LrXci6L2FhD7E+4hkwyefyDaVrCcVowHXPCSuMqCT+bFqRSJXnFsDr8CWtgGvm26larbDXQby0bICz973J4tpdqBjnrlT+VOtsqf47MfqjJstMRSFKzQaA7lHJTPsnzK3Cigzs+rPid4er5NN/Ss5WPBH/lHwcxZcTZMg6v8MmLqxJujTrUzrosenrSMV1nvFtWUFgOMMwTiR4PutgxDx8DtOZn/YZwZddNx/fQYtlxDYXIW/oKojI7XmfBPyMSwAyeBmjggLaeeh166l4WaT2V14105wv1K7LSdQL1m7IjXecZkdUTTQqyDkz5q6FsUfB/w7+v8PbB66hpeaDDO74sunp6o7K/Vwz7vOxIeTNtOxqG9mUx1HMalYZ+ZXekJVv2hKyyvauVH7dcfe1RKqu+deiwyOBEMTEr7j8RrzKY++/wrfv/AQ==</diagram></mxfile>

docs/build.md

@@ -0,0 +1,44 @@
+---
+title: Build
+nav_order: 2
+---
+
+## Project structure
+
+![Project structure](/assets/images/project-structure.png)
+
+| Directory    | Description                             |
+|--------------|-----------------------------------------|
+| .github      | GitHub Actions workflows                |
+| base         | Additional Controls and Java API        |
+| docs         | GitHub Pages project website            |
+| sampler      | Sampler application                     |
+| styles       | Theme sources (SASS)                    |
+
+## Instructions
+
+To build and run the whole project, including packaged Sampler image:
+
+```sh
+mvn install
+mvn javafx:run -pl sampler
+```
+
+If you want to use hot reload (update CSS without restarting the Sampler app) you have to start app in development mode:
+
+```sh
+# start watching for SASS source code changes
+mvn compile -pl styles -Pdev
+
+# run sampler in dev mode
+mvn javafx:run -pl sampler -Pdev
+```
+
+You can also build each Maven module individually:
+
+```sh
+mvn install -N
+mvn install -pl styles
+mvn install -pl base
+mvn javafx:run -pl sampler
+```

docs/colors/color-contrast.md

@@ -0,0 +1,24 @@
+---
+title: Color Contrast
+parent: Colors
+nav_order: 3
+---
+
+If you want to develop a good theme, there are some accessibility rules.
+
+Color contrast between text and its background must meet required [WCAG standards](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html).
+
+The contrast requirements are:
+
+* 4.5:1 for normal text
+* 3:1 for large text (>24px)
+* 3:1 for UI elements and graphics
+* No contrast requirement for decorative and disabled elements
+
+You can check and modify color contrast directly in the Sampler app.
+
+![Color Contrast](/assets/images/color-contrast.png)
+
+Click on any block to run contrast checker and get more detailed info.
+
+![Contrast Checker](/assets/images/contrast-checker.png)

docs/colors/global-variables.md

@@ -0,0 +1,90 @@
+---
+title: Global variables
+parent: Colors
+nav_order: 2
+---
+
+Global variables are defined at the Scene root level. You can preview all of the them in the Sampler app.
+
+AtlantaFX is based on GitHub Primer color system. You can check [GitHub Primer interface guidelines](https://primer.style/design/foundations/color) for more detailed instructions. There'are functional color variables and color scale variables.
+
+## Functional colors
+
+Foreground colors.
+
+| Color | Usage |
+|-------|-------|
+| `-color-fg-default`  | Primary color for text and icons. It should be used for body content, titles and labels. |
+| `-color-fg-muted`    | For content that is secondary or that provides additional context but is not critical to understanding the flow of an interface. |
+| `-color-fg-subtle`   | For placeholders or decorative foregrounds. |
+| `-color-fg-emphasis` | The text color designed to combine with `*-emphasis` backgrounds for optimal contrast. |
+
+Background colors.
+
+| Color | Usage |
+|-------|-------|
+| `-color-bg-default`| Primary background color.                                          |
+| `-color-bg-overlay`| Background color for popup controls such as popovers and tooltips. |
+| `-color-bg-subtle` | Provides visual rest and contrast against the default background.  |
+| `-color-bg-inset`  | For a focal point, such as in conversations or activity feeds.     |
+
+Border colors.
+
+| Color | Usage |
+|-------|-------|
+| `-color-border-default`| Default color to create bounds around content.                                   |
+| `-color-border-muted`  | For dividers to emphasize the separation between items, columns or sections.     |
+| `-color-border-subtle` | Faint border color.                                                              |
+
+The below colors are all accent colors. Use them according to their role. The variable names are self-explaining.
+
+Neutral colors. Use to highlight content without any added meaning.
+
+* `-color-neutral-emphasis-plus`
+* `-color-neutral-emphasis`
+* `-color-neutral-muted`
+* `-color-neutral-subtle`
+
+Accent (or primary) color. Use to draw attention to the particular area or component.
+
+* `-color-accent-fg`
+* `-color-accent-emphasis`
+* `-color-accent-muted`
+* `-color-accent-subtle`
+
+Success colors. Use to express the completion or positive outcome of a task.
+
+* `-color-success-fg`
+* `-color-success-emphasis`
+* `-color-success-muted`
+* `-color-success-subtle`
+
+Attention colors. Use to warn of pending tasks or highlight active content.
+
+* `-color-warning-fg`
+* `-color-warning-emphasis`
+* `-color-warning-muted`
+* `-color-warning-subtle`
+
+Danger colors. Use to inform of error or another negative message.
+
+* `-color-danger-fg`
+* `-color-danger-emphasis`
+* `-color-danger-muted`
+* `-color-danger-subtle`
+
+*Note that a functional color values is not always picked from the corresponding color palette. It can have its own unique value, e.g. to add opacity.*
+
+## Scale variables
+
+Generally, scale variables only supposed to be used by theme devs as replacement of dynamic brightness calculation functions. Avoid referencing them directly when building UI that needs to adapt to different color themes. Instead, use the functional variables listed above. All legitimate functional color combinations are guaranteed to look good in all color themes, because they need to maintain a certain amount of contrast. If you're using scale variable as a part of that combination it may break in another theme. In rare cases, you may need to use scale variables to define custom functional variables in your application.
+
+Each color scale consists of 10 shades from 0 to 9.
+
+* `-color-dark`
+* `-color-light`
+* `-color-base-[0-9]`
+* `-color-accent-[0-9]`
+* `-color-success-[0-9]`
+* `-color-warning-[0-9]`
+* `-color-danger-[0-9]`

docs/colors/index.md

@@ -0,0 +1,9 @@
+---
+title: Colors
+has_children: true
+nav_order: 3
+---
+
+AtlantaFX as well as uses standard JavaFX themes [looked-up colors](/colors/looked-up-colors), but unlike them, in AtlantaFX all color variables start with `-color-` prefix.
+
+There're [global variables](/colors/global-variables), that are defined at the Scene root level and individual control variables. The latter defined for each individual control. Check corresponding control reference for the info.

docs/colors/looked-up-colors.md

@@ -0,0 +1,46 @@
+---
+title: Looked-up colors
+parent: Colors
+nav_order: 1
+---
+
+JavaFX has limited CSS 2.1 support, but the good news is that it supports color variables that are called as looked-up colors in the [JavaFX CSS reference](https://openjfx.io/javadoc/17). The second important thing is that looked-up colors as any other CSS property are resolved according to CSS specificity rules.
+
+If you imagine the following hierarchy:
+
+```text
+Scene [class = root]
+    Region [class = r1]
+        Region [class = r2]
+            Region [class = r3]
+```
+
+You can manipulate the background color of each descending node with the following CSS rules (most specific wins):
+
+```css
+.root {
+    -color-background: transparent;
+}
+
+.r1, .r2, .r3 {
+    -fx-background-color: -color-background;
+}
+
+.r2 {
+    -color-background: red; /* applied to the r2 and below */
+}
+
+.r2 > .r3  {
+    -color-background: green;
+}
+```
+
+JavaFX will try to resolve color variable value starting from the most to the least specific rule, which is always the root of the Scene hierarchy.
+
+Result:
+
+```text
+r1 - transparent
+r2 - red
+r3 - green
+```

docs/controls/button.md

@@ -0,0 +1,19 @@
+---
+title: Button
+parent: Controls
+---
+
+## Looked-up colors
+
+* `-color-button-bg`
+* `-color-button-fg`
+* `-color-button-border`
+* `-color-button-bg-hover`
+* `-color-button-fg-hover`
+* `-color-button-border-hover`
+* `-color-button-bg-focused`
+* `-color-button-fg-focused`
+* `-color-button-border-focused`
+* `-color-button-bg-pressed`
+* `-color-button-fg-pressed`
+* `-color-button-border-pressed`

docs/controls/date-picker.md

@@ -0,0 +1,23 @@
+---
+title: DatePicker
+parent: Controls
+---
+
+## Looked-up colors
+
+- `-color-dp-bg`
+- `-color-dp-border`
+- `-color-dp-month-year-bg`
+- `-color-dp-month-year-fg`
+- `-color-dp-day-bg`
+- `-color-dp-day-bg-hover`
+- `-color-dp-day-bg-selected`
+- `-color-dp-day-fg`
+- `-color-dp-day-fg-hover`
+- `-color-dp-day-fg-selected`
+- `-color-dp-week-bg`
+- `-color-dp-week-fg`
+- `-color-dp-today-bg`
+- `-color-dp-today-fg`
+- `-color-dp-other-month-fg`
+- `-color-dp-chrono-fg`

docs/controls/index.md

@@ -0,0 +1,8 @@
+---
+title: Controls
+has_children: true
+---
+
+Here you will find a short reference of supported CSS classes and looked-up color for every control.
+
+This work is still in progress.

docs/controls/slider.md

@@ -0,0 +1,11 @@
+---
+title: Slider
+parent: Controls
+---
+
+## Looked-up colors
+
+- `-color-slider-thumb`
+- `-color-slider-thumb-border`
+- `-color-slider-track`
+- `-color-slider-tick`

docs/controls/split-pane.md

@@ -0,0 +1,11 @@
+---
+title: SplitPane
+parent: Controls
+---
+
+## Looked-up colors
+
+- `-color-divider`
+- `-color-divider-pressed`
+- `-color-grabber`
+- `-color-grabber-pressed`

docs/controls/virtualized-contols.md

@@ -0,0 +1,17 @@
+---
+title: Virtualized Controls
+parent: Controls
+---
+
+This file belongs to the `ListView`, `TreeView`, `TableView` and `TreeTableView`.
+
+## Looked-up colors
+
+- `-color-cell-bg`
+- `-color-cell-fg`
+- `-color-cell-bg-selected`
+- `-color-cell-fg-selected`
+- `-color-cell-bg-odd`
+- `-color-cell-border`
+- `-color-header-bg`
+- `-color-header-fg`

docs/index.md

@@ -1,6 +1,30 @@
 ---
 # To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults
 layout: home
+title: Home
+nav_order: 1
 ---
 
-In progress...
+## Getting started
+
+Add project to the dependencies:
+
+```xml
+<dependency>
+    <groupId>io.github.mkpaz</groupId>
+    <artifactId>atlantafx-base</artifactId>
+    <version>1.0.0</version>
+</dependency>
+```
+
+If you don't want to include additional dependencies into your project classpath, you can download compiled CSS themes from the [GitHub Releases](https://github.com/mkpaz/atlantafx/releases).
+
+Set CSS theme:
+
+```java
+// find more themes in 'atlantafx.base.theme' package
+Application.setUserAgentStylesheet(new PrimerLight().getUserAgentStylesheet());
+Application.setUserAgentStylesheet(new PrimerDark().getUserAgentStylesheet());
+// or
+Application.setUserAgentStylesheet(/* path to the CSS file in your project classpath */);
+```

docs/themization.md

@@ -0,0 +1,62 @@
+---
+title: Themization
+nav_order: 4
+---
+
+AtlantaFX stylesheet is written in SASS. You don't have to learn it, though it's a very simple language, if you're already familiar with CSS. You can find a very good doc at [sass-lang.com](https://sass-lang.com/documentation/).
+
+To compile SASS to CSS, AtlantaFX uses the Dart SASS library and very handy [`sass-cli-maven-plugin`](https://github.com/HebiRobotics/sass-cli-maven-plugin) by **@ennerf**.
+
+Note, that theme is not limited by colors. If you only want to change colors, all you need is to override default looked-up [color variables](/colors/global-variables). The easiest way is to utilize pseudo-class, so you can always return to the default color scheme.
+
+```css
+.root:custom-theme {
+    -color-bg-default: #123456;
+    /* ... and so on */
+}
+```
+
+```java
+static PseudoClass CUSTOM_THEME = PseudoClass.getPseudoClass("custom-theme");
+getScene().getRoot().pseudoClassStateChanged(CUSTOM_THEME, true);
+```
+
+## Custom theme compilation
+
+You can find ready to use custom theme template in the [`atlantafx-sample-theme`](https://github.com/mkpaz/atlantafx-sample-theme).
+
+Compile it and grab resulting CSS from `dist/` directory:
+
+```sh
+# you can also (optionally) watch for changes
+mvn compile [-Pwatch]
+```
+
+Every SCSS file in the source directory is nothing but separate SASS module. You can find a bunch of SASS variables at its top. If a variable is marked as `default` it can be changed during theme compilation. In fact, any AtlantaFX theme can be used as an example. They're all share common sources and use SASS variable modification to compile different stylesheets.
+
+**If you want to customize a style property that is not exposed as SASS variable don't hesitate to open an [issue](https://github.com/mkpaz/atlantafx/issues) or send a [PR](https://github.com/mkpaz/atlantafx/pulls).**
+
+Note that SASS is only loading any module just once, so customization order does matter. E.g. if A module uses B and B use C then we should override C variables first, then B, then A. Otherwise, there will be an exception that we are attempting to change a variable in a module that has been already loaded.
+
+```sass
+// Color customization.
+@forward "relative/path/to/settings/color-vars" with (
+    //   ...
+);
+
+// Shared property customization.
+@forward "relative/path/to/settings/config" with (
+    //   ...
+);
+
+// This should precede controls customization, as it guarantees
+// that .root styles will precede components styles.
+@use "general";
+
+// Individual component property customization.
+// Use "as name-*" to avoid conflicts if two or more SASS modules
+// contain variables with the same name.
+@forward "relative/path/to/components/split-pane" as split-pane-*  with (
+    //   ...
+);
+```