@tcn/ui 0.16.0 → 0.18.0

package/src/themes/themes/ergo/ROADMAP.md

@@ -0,0 +1,116 @@
+# Ergo Theme — Part File Cascade
+
+Tracks the split of the monolithic `ergo_theme.css` into modular part files loaded in a strict cascade order via `buildStyleSheet()`.
+
+## Load Order & Status
+
+| # | File | Status | Contains |
+|---|------|--------|----------|
+| 1 | `tokens/theme_tokens.css` | Done | Ergo palette, spacing, sizing, shape tokens |
+| 2 | `tokens/system_tokens.css` | Done | Blackcat system tokens (maps palette to semantics) |
+| 3 | `parts/base.css` | Done | `.tcn-theme-root`, `.tcn-interactive`, `.material` |
+| 4 | `parts/actions.css` | Done | `.tcn-base-button`, `.tcn-button`, `.tcn-toggle`, `.tcn-fab`, `.tcn-mobile-button`, `.tcn-button-group`, `.tcn-select-group` |
+| 5 | `parts/inputs.css` | Done | `.tcn-entry`, `.tcn-control`, `.tcn-input`, `.tcn-textarea`, `.tcn-control-set`, `.tcn-checkbox`, `.tcn-switch-wrapper`, `.tcn-slider`, `.tcn-radio-label`, `.tcn-select-selected-label`, `.tcn-multiselect-*` |
+| 6 | `parts/form.css` | Done | `.tcn-field-set`, `.tcn-field-set-legend` |
+| 7 | `parts/navigation.css` | Done | `.tcn-tabs-bar`, `.tcn-tabs-list`, `.tcn-tab-item` (default + inline variants) |
+| 8 | `parts/tokens_display.css` | TODO | `.tcn-chip`, `.tcn-datum`, `.tcn-key`, `.tcn-value`, `.tcn-term` |
+| 9 | `parts/decorators.css` | TODO | `.tcn-draggable`, `.tcn-drag-handle`, `.tcn-resize-handle` (new theme coverage) |
+| 10 | `parts/layouts.css` | TODO | `.tcn-scaffold`, `.tcn-header`, `.tcn-footer`, `.tcn-utility-bar`, `.tcn-utility-strip`, `.tcn-bar`, `.tcn-group`, `.tcn-section`, `.tcn-heading`, `.tcn-detail`, `.tcn-caret`, `.tcn-columns`, `.tcn-rows`, `.tcn-divider-line` |
+| 11 | `parts/table.css` | TODO | `.tcn-table`, `.tcn-thead`, `.tcn-tbody`, `.tcn-tfoot`, `.tcn-tr`, `.tcn-td`, `.tcn-th` |
+| 12 | `parts/overlay.css` | TODO | `.tcn-tethered`, `.tcn-tooltip`, `.tcn-frame-dialog`, `.tcn-frame-veil` |
+| 13 | `parts/surfaces.css` | TODO | `.tcn-page`, `.tcn-panel`, `.tcn-aside`, `.tcn-card`, `.tcn-modal`, `.tcn-drawer`, `.tcn-window`, `.tcn-pop-confirm`, `.tcn-confirm`, `.tcn-list`, `.tcn-item` |
+| 14 | `parts/typography.css` | TODO | `.tcn-body-text`, `.tcn-headline`, `.tcn-title`, etc. (`[data-emphasis="faint"]`) |
+
+> Once all parts are extracted, `ergo_theme.css` is deleted and this file may be renamed to `LAYERS.md`.
+
+## Dependency Chain
+
+Each layer can reference CSS custom properties and class behaviors defined in layers above it. Reverse references (later layer depending on an earlier one's internals) are not allowed.
+
+```
+tokens/theme_tokens.css
+  Defines: --ergo-* palette, spacing, sizing, shape
+  Depends on: nothing
+
+tokens/system_tokens.css
+  Defines: --font-*, --gap-*, --padding-*, --status-color-*, --action-severity-*, --*-color-*
+  Depends on: theme_tokens (references --ergo-* variables)
+
+parts/base.css
+  Defines: --action, --on-action, --material, --on-material (on .tcn-theme-root)
+           --ink, --act, --mat, --act-down, --act-raised, --act-focus, --act-drag (on .tcn-interactive)
+           .material background/color
+  Depends on: theme_tokens (--ergo-primary, --ergo-white, --ergo-accent-blue)
+              system_tokens (--font-family, --font-color)
+
+parts/actions.css
+  Defines: --btn-*, --tgl-* button/toggle sizing and color system
+  Depends on: base (--action, --on-action, --material, --on-material, --ink, --act, --mat)
+              theme_tokens (--ergo-shape-radius-medium, severity colors)
+              system_tokens (--padding-small, --action-severity-*)
+
+parts/navigation.css
+  Defines: tab indicator positioning, variant styles
+  Depends on: base (--material, --on-material, interactive vocabulary)
+              actions (uses --mat, --ink, --act from interactive chain)
+              theme_tokens (--ergo-primary, --ergo-accent-blue, --ergo-material-divider)
+
+parts/inputs.css
+  Defines: form control chrome (border, focus, disabled states), multiselect containers
+  Depends on: base (--action, --material, --act, --mat)
+              theme_tokens (--ergo-grey, --ergo-sizing-action-md, --ergo-shape-radius-medium, --ergo-primary)
+              system_tokens (--ergo-text-size-input, --gap-small)
+
+parts/form.css
+  Defines: field-set layout, legend chrome, disabled entry within field-set
+  Depends on: theme_tokens (--ergo-sizing-bar-md, --ergo-material-divider, --ergo-material-disabled-outline, --ergo-text-color-disabled-outline)
+              system_tokens (--gap-medium, --padding-medium)
+
+parts/tokens_display.css
+  Defines: chip, datum, key/value/term display atoms
+  Depends on: base (--action, --on-material)
+              theme_tokens (--ergo-primary, --ergo-accent-blue, status colors)
+
+parts/decorators.css
+  Defines: drag handle cursors, resize handle indicators
+  Depends on: theme_tokens (--ergo-grey-light, --ergo-grey-dark, --ergo-shape-radius-medium)
+  Note: must precede layouts and surfaces since handles appear inside both
+
+parts/layouts.css
+  Defines: scaffold structure, section nesting depth system, bar/group dividers, columns/rows, caret, divider-line
+  Depends on: base (--material, --on-material)
+              theme_tokens (--ergo-sizing-bar-*, --ergo-material-border, section depth colors)
+              system_tokens (--padding-*, --gap-*)
+
+parts/table.css
+  Defines: table chrome (header/body/footer colors, alternating rows, sticky borders)
+  Depends on: base (--material, --on-material, --action, --on-action)
+              theme_tokens (--ergo-white, --ergo-accent-blue-light, --ergo-grey)
+              system_tokens (--padding-medium)
+              layouts (inherits --pad-inline concept from scaffold/surface context)
+
+parts/overlay.css
+  Defines: tethered positioning, tooltip chrome, frame-dialog border, veil backdrop
+  Depends on: base (--material, --on-material)
+              theme_tokens (--ergo-secondary-dark, --ergo-shape-triangle-medium)
+              system_tokens (--padding-medium)
+
+parts/surfaces.css — LAST
+  Defines: page/panel/card/modal/drawer/window/pop-confirm composition
+  Depends on: ALL previous layers
+  Note: surfaces are the final composition layer. They set --material, --on-material,
+        --divide-header, --pad-inline for their children (scaffold, sections, inputs,
+        actions). This is why surfaces must be last — they orchestrate all other layers.
+```
+
+### Why this order matters
+
+The cascade within `@layer tcn-theme` is determined by declaration order. Later declarations win on conflicts for equal specificity. This means:
+
+1. **Tokens first** — everything references them, nothing references back
+2. **Base before actions** — actions use `--ink`, `--act`, `--mat` defined by `.tcn-interactive` in base
+3. **Actions before navigation** — tabs extend the interactive/action vocabulary
+4. **Inputs independent** — form controls don't depend on actions or navigation
+5. **Decorators before layouts/surfaces** — handles appear inside both; their base styles must exist first
+6. **Layouts before surfaces** — surfaces set `--pad-inline`, `--divide-header` that scaffold/section read; layout structure rules must exist for surfaces to override them
+7. **Surfaces last** — they compose everything: inputs inside cards, actions inside modals, layout slots inside panels. Surface-specific overrides (e.g., `.tcn-card .tcn-section`) must win over base layout rules