toml updates

2026-08-07 23:59:03 -05:00
parent b5d6e60d45
commit a157489634
4 changed files with 108 additions and 2 deletions
@@ -54,6 +54,7 @@ Load [styling and customization](./references/styling-and-customization.md) for:

 - progressive discovery through NiceGUI docs, constructors, and Quasar docs
 - Quasar props, slots, events, and NiceGUI customization methods
+- app-wide and page-level color themes, dark mode, and semantic CSS tokens
 - Tailwind for structural styling and static stylesheets for fine tuning
 - responsive layout and static asset conventions
 - Tailwind and Quasar breakpoint scales, container queries, and responsive testing
@@ -71,6 +71,106 @@ with ui.select(

 Prefer constructor arguments when NiceGUI exposes the behavior directly. Use `.props()` for supported Quasar features that are not constructor parameters. Use slots when the Quasar docs define a semantic insertion point; do not reproduce that content with absolute positioning.

+## Application Themes With NiceGUI And Quasar
+
+Treat a theme as three related layers with different owners:
+
+1. Configure Quasar's named color roles through NiceGUI.
+2. Let Quasar own light, dark, and automatic mode state.
+3. Define application semantic tokens for surfaces and content not covered by Quasar components.
+
+Do not implement a parallel theme switch by replacing Quasar classes or directly restyling each component. NiceGUI's color APIs set the supported Quasar `--q-*` custom properties, so Quasar components, `color=` arguments, and classes such as `text-primary` and `bg-positive` stay aligned.
+
+### Set The App-Wide Palette Once
+
+Use [`app.colors()`](https://nicegui.io/documentation/colors#app-wide-colors) in the composition layer for the default palette. Prefer Quasar's semantic roles over shade names: `primary`, `secondary`, `accent`, `positive`, `negative`, `info`, and `warning`. The `dark` and `dark_page` arguments configure dark surface colors; they do not enable dark mode.
+
+```python
+from nicegui import app, ui
+
+app.colors(
+    primary="#176b5b",
+    secondary="#52645f",
+    accent="#c05a32",
+    dark="#202523",
+    dark_page="#151917",
+    positive="#2e7d32",
+    negative="#b3261e",
+    info="#276b8e",
+    warning="#a86600",
+    brand="#176b5b",
+)
+
+
+@ui.page("/")
+def index() -> None:
+    ui.button("Save")
+    ui.label("Current workspace").classes("text-brand")
+
+
+ui.run()
+```
+
+Custom names such as `brand` become Quasar color names and can be used through `color="brand"`, `text-brand`, or `bg-brand`. Register them before any component uses them. `app.colors()` was added in NiceGUI 3.6.0; for an older pinned version, centralize the same `ui.colors(...)` call in a shared page shell.
+
+Use [`ui.colors()`](https://nicegui.io/documentation/colors) only when one page intentionally overrides the app palette. It is page-scoped and takes precedence over `app.colors()`:
+
+```python
+@ui.page("/operations")
+def operations_page() -> None:
+    ui.colors(primary="#8f3d2c")
+    ui.button("Operations action")
+```
+
+Avoid scattering `ui.colors()` calls among reusable components. A component should consume semantic roles from its owning page rather than silently changing the palette for the whole page.
+
+### Let Quasar Control Light And Dark Mode
+
+Use [`ui.dark_mode()`](https://nicegui.io/documentation/dark_mode) for page mode. Its value is tri-state: `True` enables dark mode, `False` disables it, and `None` follows the client's `prefers-color-scheme` setting. It overrides the `dark` default supplied to `ui.run()` or `@ui.page` for that page.
+
+```python
+dark_mode = ui.dark_mode(None)
+
+with ui.button_group():
+    ui.button("System", on_click=dark_mode.auto)
+    ui.button("Light", on_click=dark_mode.disable)
+    ui.button("Dark", on_click=dark_mode.enable)
+```
+
+Quasar applies `body--light` or `body--dark`, updates its dark-aware components, and tracks system changes while mode is automatic. Use the NiceGUI element instead of invoking Quasar's JavaScript Dark plugin directly. Persist an explicit user preference separately when it must survive navigation or a new browser session.
+
+### Add Semantic Tokens For Application Surfaces
+
+Quasar's brand roles cover framework components, not every application-specific surface. Define a small set of semantic CSS variables in the static stylesheet and change their values under Quasar's documented `.body--dark` class:
+
+```css
+:root {
+    --app-page: #f6f8f7;
+    --app-surface: #ffffff;
+    --app-text: #202623;
+    --app-border: #cbd4d0;
+}
+
+.body--dark {
+    --app-page: var(--q-dark-page);
+    --app-surface: var(--q-dark);
+    --app-text: #eef3f0;
+    --app-border: #46504b;
+}
+
+body {
+    background: var(--app-page);
+    color: var(--app-text);
+}
+
+.app-panel {
+    background: var(--app-surface);
+    border: 1px solid var(--app-border);
+}
+```
+
+Name tokens by purpose, such as `--app-surface` or `--app-muted-text`, rather than by a fixed color such as `--app-gray-100`. Reuse `--q-primary` and the other Quasar variables when the meaning matches. Check text, icon, border, focus, hover, disabled, positive, warning, and negative contrast in both modes; a palette is not complete merely because the page background changes.
+
 ## Structural Styling With Tailwind

 Use standard [Tailwind utility classes](https://tailwindcss.com/docs/utility-first) for page and component structure:
@@ -327,7 +427,11 @@ Confirm that page sections do not overlap, toolbars wrap on mobile, desktop pane
 !!! info "Primary sources"
    - [NiceGUI element styling and props](https://nicegui.io/documentation/element)
    - [NiceGUI binding properties](https://nicegui.io/documentation/section_binding_properties)
+    - [NiceGUI color theming](https://nicegui.io/documentation/colors)
+    - [NiceGUI dark mode](https://nicegui.io/documentation/dark_mode)
    - [Quasar components](https://quasar.dev/vue-components)
+    - [Quasar color palette and runtime brand variables](https://quasar.dev/style/color-palette)
+    - [Quasar dark mode](https://quasar.dev/style/dark-mode)
    - [Quasar field](https://quasar.dev/vue-components/field/)
    - [Quasar select](https://quasar.dev/vue-components/select/)
    - [Tailwind responsive design](https://tailwindcss.com/docs/responsive-design)