Feature/26 2 new fluent theme with design tokens merge commit test

.claude/skills/fluent-next-tier/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: fluent-next-tier
+description: How the fluent-next public `--dx-*` component tier is generated and guarded in packages/devextreme-scss — derive-registries, publish, reachability and tokens:update. Use whenever work touches `registries.json`, `OVERRIDES`/`rootSelectors`, a generated `_public.scss` / `_public-tier.scss`, `_public-links.scss`, `nested-scopes.json`, `unread-tier.json`, a renamed or new fluent-next SCSS variable, a retired `--dx-*` name or `public-renames.json`, a design-token package bump (`@devexpress/design-tokens-internal`, Renovate), or when CI fails in "Check naming registries" / `naming:check` with "stale", "has no rootSelectors", "scope outside the roots", "portal", "declared and never read", "cross-scope duplicate" or "read and never declared" — even if the user names only the symptom.
+---
+
+# fluent-next component tier
+
+fluent-next publishes its SCSS variables as public custom properties (`--dx-button-bg`, …). They are a
+contract from the first release: a published name cannot be withdrawn or renamed silently. Four
+scripts in `packages/devextreme-scss` produce and guard that layer. Run them from that package.
+
+## The pipeline
+
+```
+token package + theme folders + OVERRIDES
+        │  tools/naming/derive-registries.ts
+        ▼
+tools/naming/registries.json            (generated, committed — never edit by hand)
+        │  tools/naming/publish.ts (rules in tools/naming/tier.ts)
+        ▼
+fluent-next/<folder>/_public.scss       (generated, committed, header "// GENERATED by …")
+fluent-next/_public-tier.scss           (generated collector: which root selectors carry which tier)
+fluent-next/<folder>/_public-links.scss (hand-written relations, included by the generated file)
+        │  nx build:themes
+        ▼
+devextreme/artifacts/css/dx.fluent-next.blue.light.css
+        │  tools/review/reachability.ts
+        ▼
+does every --dx-* actually reach the elements that read it?
+```
+
+`tokens:update` sits beside this: it bumps the token package and reports what moved.
+
+## Commands
+
+| Command | What it does | Details |
+|---|---|---|
+| `pnpm run naming:registries` | regenerate `registries.json` (needs built themes) | [derive-registries.md](derive-registries.md) |
+| `pnpm run naming:publish` | regenerate every `_public.scss` and `_public-tier.scss` | [publish.md](publish.md) |
+| `node tools/review/reachability.ts [--report] [--update-scopes] [--update-unread]` | check the built bundle | [reachability.md](reachability.md) |
+| `pnpm run tokens:update [<version>] [--report]` | bump the token package and report | [tokens-update.md](tokens-update.md) |
+| `pnpm run naming:check` | what CI runs: `derive-registries --check` → `publish --check` → `reachability` | — |
+| `pnpm run naming:baseline` | rewrite `tests/fluent-next-naming.baseline.json` | — |
+
+## In CI
+
+`.github/workflows/styles.yml` runs, in one job, `nx test devextreme-scss` and then
+`nx naming:check devextreme-scss` (step "Check naming registries"). `naming:check` depends on
+`build:themes`, so reachability always sees a fresh bundle there. Locally, rebuild the themes first
+(`pnpm nx build:themes devextreme-scss`) — reachability silently skips when no bundle exists.
+
+## A failure, and where to look
+
+| Message | Read |
+|---|---|
+| `registries.json is stale` | [derive-registries.md](derive-registries.md) |
+| `STATES and PARTS overlap…` / `sub-elements of X collide with a state name` | [derive-registries.md](derive-registries.md) |
+| `rootSelectors[x]: "…" does not occur in the built bundle` | [derive-registries.md](derive-registries.md) |
+| `… is stale … run pnpm naming:publish` | [publish.md](publish.md) |
+| `X publishes from folder/ but has no rootSelectors` | [publish.md](publish.md) |
+| `read and never declared`, `cross-scope duplicate`, `scope outside the roots`, `portal:`, `declared and never read`, `pinned name(s) are read now` | [reachability.md](reachability.md) |
+| a token bump turned something red | [tokens-update.md](tokens-update.md) |
+
+## Rules that hold everywhere
+
+- Generated files (`registries.json`, `_public.scss`, `_public-tier.scss`) are only ever changed by
+  re-running their script. A hand edit is caught by `--check` and lost on the next run.
+- Judgment calls live in `OVERRIDES` inside `derive-registries.ts` and are reviewed as code;
+  everything else in `registries.json` is derived.
+- Renaming a fluent-next SCSS variable retires its public `--dx-*` name. Record the old name in
+  `tools/naming/public-renames.json` in the same PR; `tests/public-renames.test.ts` stops it from
+  coming back. Only names that shipped in a release are journaled — see the journal section of
+  [tokens-update.md](tokens-update.md) for when an entry is due and how to write it.
+- `tests/fluent-next-naming.test.ts` reads the same rules as `publish.ts` (both import `tier.ts`):
+  the tier composition, links, the collector and the name grammar for new variables. Its baseline
+  sections fail on any change; after a deliberate one run `pnpm run naming:baseline` and review the
+  diff.

.claude/skills/fluent-next-tier/derive-registries.md

@@ -0,0 +1,68 @@
+# derive-registries.ts
+
+`tools/naming/derive-registries.ts` writes `tools/naming/registries.json`, the single source of truth
+for the fluent-next naming standard.
+
+```
+node tools/naming/derive-registries.ts          # writes registries.json   (pnpm run naming:registries)
+node tools/naming/derive-registries.ts --check  # fails if the committed file is stale
+```
+
+## Where the data comes from
+
+- **The token package** (`@devexpress/design-tokens-internal/tokens.flat.json`, the
+  `components/core/theme/fluent` tokens). From it come the colour `parts` (the last word of every
+  colour token: `bg`, `border`, `content`, `icon`…). The vocabulary is read from the package's flat
+  index, not from generated output, so the script needs no build for this part and cannot drift
+  from the package.
+- **The theme folders** in `scss/widgets/fluent-next/`: each folder becomes a component, its name in
+  kebab case (`dateBox` → `date-box`) unless `OVERRIDES.components` says otherwise.
+- **`OVERRIDES`** at the top of the script — every judgment call, reviewed as code, with the reason
+  next to each entry: folder ↔ component exceptions (`gridBase` → `grid`), `systemFolders` /
+  `systemTier`, `declarationHome`, `chassis` (who renders the grid / menu chassis), `embeds`,
+  `rootSelectors`, `migrated`, `sassOnly`, and the grammar vocabularies (`states`, `modifiers`,
+  `sizeSlots`, `subElements`, `systemConcerns`, `themeIdentity`, `partExclude` / `partsAdd` /
+  `partsRemove`).
+
+`rootSelectors` defaults to `.dx-<component without dashes>` for every migrated and system-tier
+component; an override replaces it, for example when a widget paints outside its own element (a
+dialog rendered into `body`, a toolbar menu inside a popup). Add the reason beside the entry.
+
+## The name grammar it describes
+
+```
+$<component>(-<sub-element>)*(-<modifier>)*-<slot>(-<state>)
+```
+
+Parsed right to left with longest match: the trailing state, then the slot (a colour `part` in
+`_colors.scss`, a `sizeSlot` in `_sizes.scss`), then the middle words. Overlaps between vocabularies
+that compete for different positions are fine (`text` is both a part and a modifier); two are fatal
+and the script refuses them:
+
+- a state that is also a part;
+- a sub-element of a component that is also a state.
+
+## Who reads which field
+
+| Fields | Read by |
+|---|---|
+| `components`, `declarationHome`, `systemTier`, `rootSelectors`, `exemptFolders`, `migrated`, `sassOnly` | `tools/naming/tier.ts` → `publish.ts` (the generator) |
+| `rootSelectors` | `tools/review/reachability.ts` |
+| `systemFolders` | `tests/disabled-paint.test.ts` |
+| the grammar vocabularies, `chassis`, `embeds`, `systemConcerns`, `themeIdentity` | `tests/fluent-next-naming.test.ts` |
+
+## Failures
+
+- **`registries.json is stale — run node tools/naming/derive-registries.ts`** — the committed file
+  differs from what the script builds now: `OVERRIDES` changed, a theme folder was added or removed,
+  or a token package bump changed the colour `parts`. Regenerate with `pnpm run naming:registries` (build the themes
+  first, see below) and review the JSON diff.
+- **`STATES and PARTS overlap, the grammar would be undecidable`** / **`sub-elements of X collide with
+  a state name`** — an `OVERRIDES` edit (or a new part from the package) made a word ambiguous. Pick
+  another word or remove it from `partsAdd` / add it to `partExclude`.
+- **`rootSelectors for non-migrated components: …`** — a `rootSelectors` override for a component that
+  is neither in `migrated` nor in `systemTier`.
+- **`rootSelectors[x]: "…" does not occur in the built bundle`** / **`is not a single .dx-* class or
+  :root`** — a typo in a root selector, or the themes were not rebuilt. Regenerating needs the built
+  bundle at `packages/devextreme/artifacts/css/dx.fluent-next.blue.light.css`; `--check` skips this
+  gate when the bundle is absent (it only compares bytes).

.claude/skills/fluent-next-tier/publish.md

@@ -0,0 +1,50 @@
+# publish.ts
+
+`tools/naming/publish.ts` regenerates the fluent-next component tier:
+
+- every `fluent-next/<folder>/_public.scss` — the `--dx-*` projections of the component's eligible
+  variables, in alphabetical order;
+- the collector `fluent-next/_public-tier.scss` — which root selectors (`registries.rootSelectors`)
+  carry which component's tier.
+
+```
+node tools/naming/publish.ts          # regenerates the tier files   (pnpm run naming:publish)
+node tools/naming/publish.ts --check  # exit 1 when a committed file is stale or a rule is broken
+```
+
+It needs no built bundle. The rules live in `tools/naming/tier.ts`, which
+`tests/fluent-next-naming.test.ts` reads too, so the emitter and the test can never disagree.
+
+## What is generated and what is not
+
+- `_public.scss` and `_public-tier.scss` carry `// GENERATED by tools/naming/publish.ts`. Never edit
+  them; change the SCSS variable (or `registries.json` via `OVERRIDES`) and re-run.
+- `<folder>/_public-links.scss` is hand-written and never touched by the script; the generated file
+  includes it. A relation between two names goes there as a link, the whole value being
+  `--dx-a: var(--dx-b);`, so it stays live when `--dx-b` is overridden. The naming test checks that a
+  link points at a name declared by the same component or published on `:root`, keeps the state
+  (`-hover` → `-hover`), and that an alias reaching another component's root is published as a value,
+  not a link.
+- Not every variable is eligible: `sassOnly` entries, values a custom property cannot carry (CSS-wide
+  keywords, `null`, data-uri images and what they feed), and base-layer wiring are excluded.
+
+## Renames retire public names
+
+The published name is derived from the SCSS variable, so renaming a variable retires a public
+`--dx-*` name, and the diff looks like plain regeneration. Record the retirement in
+`tools/naming/public-renames.json` in the same pull request; `tests/public-renames.test.ts` keeps a
+retired name from reappearing, as an alias or otherwise. Whether an entry is due (only names that
+shipped) and how to write it: the journal section of [tokens-update.md](tokens-update.md).
+
+## Failures
+
+- **`fluent-next/<folder>/_public.scss is stale` … `run pnpm naming:publish`** — a declaration file
+  changed and the tier was not regenerated, or a generated file was edited by hand. Run
+  `pnpm run naming:publish` and commit the result.
+- **`X publishes from folder/ but has no rootSelectors — add it to derive-registries.ts
+  OVERRIDES`** — only the components in `migrated` and `systemTier` publish, and the generator gives
+  each of them a root, so this means `registries.json` is stale or was edited by hand. Make the change
+  in `OVERRIDES` (add `rootSelectors` there if the default `.dx-<component>` is wrong), then
+  `pnpm run naming:registries` and `pnpm run naming:publish`.
+- The naming test reports `not published — run pnpm naming:publish` or `the variable is excluded from
+  the tier` for the same causes.

.claude/skills/fluent-next-tier/reachability.md

@@ -0,0 +1,62 @@
+# reachability.ts
+
+`tools/review/reachability.ts` checks, on the **built** fluent-next bundle, that every `--dx-*` name
+reaches the elements that read it. A custom property exists only on the element that declares it
+and its descendants; a `var()` that finds nothing makes the browser drop the whole declaration, with
+no compile error, no lint error and nothing in the console.
+
+```
+node tools/review/reachability.ts                   # the gate (last step of pnpm run naming:check)
+node tools/review/reachability.ts --report          # also list every read outside the root text
+node tools/review/reachability.ts --update-scopes   # rewrite nested-scopes.json from what it sees now
+node tools/review/reachability.ts --update-unread   # rewrite the names list in unread-tier.json
+```
+
+It reads `packages/devextreme/artifacts/css/dx.fluent-next.blue.light.css`; without that file it
+prints a note and exits 0, so rebuild the themes (`pnpm nx build:themes devextreme-scss`) before
+trusting a local green. Inputs besides the bundle: `registries.rootSelectors`, its two lists
+`tools/review/nested-scopes.json` and `tools/review/unread-tier.json`, and the runtime contracts
+`tools/naming/runtime-reads.json` (lengths JS reads back with `getComputedStyle`) and
+`tools/naming/viz-contract.json` (names the charts write into SVG).
+
+## The five checks — each one fails the run
+
+1. **`read and never declared`** — a `var(--dx-foo)` with no `--dx-foo` declared anywhere: a typo or
+   a removed name. Fix the name or publish it on the scope that reads it. Names set at runtime by
+   another layer (CardView card sizes, the scheduler animation, the accent colour) are listed in
+   `SET_ELSEWHERE` in the script; add one there only when another layer really sets it.
+2. **`cross-scope duplicate`** — the same selector and property are declared more than once and the
+   copies read variables of different components. The last copy wins everywhere, and inside the other
+   widget its variable is empty, so the property vanishes. In the legacy themes such duplicates were
+   harmless (equal literals); the tier splits them across roots. Real case: base/dataGrid and
+   base/treeList drew the same unscoped `.dx-command-ai-header-button .dx-button.dx-state-focused` and
+   the AI column button lost its focus ring in DataGrid. Fix: read a shared-layer name
+   (`gridBase`/`menuBase`, e.g. `$grid-outline-focused`), not one widget's.
+3. **`scope outside the roots of X`** — a rule reads `--dx-X-…` but its selector text contains no root
+   of X. Usually harmless (the element is nested in the widget and the selector is just short), but
+   if JS mounts that element outside the widget — a portal: popup, drag preview, sortable clone,
+   dialog in `body` — the variable is missing there. The text cannot tell the two apart, so this is a
+   prompt to check: open the widget in that state and confirm in the DOM that the element sits inside
+   the root. Then either add the scope to `nested-scopes.json["X"]`, or, if it is a portal, add its
+   class to `OVERRIDES.rootSelectors` in `derive-registries.ts` (the tier is then declared on it too)
+   or read a Sass twin / `:root` value in that branch. `--update-scopes` writes every current scope in
+   one go — use it only after the checks, never as a way to turn CI green.
+4. **`portal: .<scope> is another widget's overlay`** — a scope named after another widget's overlay
+   (`-popup`, `-popup-wrapper`, `-overlay`, `-overlay-wrapper`, `-overlay-content`, `-popover`,
+   `-popover-wrapper`, `-tooltip`, `-tooltip-wrapper`) is a portal by construction and cannot be
+   nested. Fires whether or not the scope is listed, and `--update-scopes` refuses to list it. This
+   is how the diagram toolbar's overflow menu was found: its scope had been listed by a bulk update and
+   the icons had lost their margins.
+5. **`declared and never read`** / **`pinned name(s) are read now`** — liveness: a name is live when an
+   ordinary declaration reads it, a `@container style(--dx-…)` query names it, it is in the runtime or
+   viz contract, or a live name reads it (computed to a fixpoint). The dead set is pinned in
+   `unread-tier.json` by exact equality. A **new** dead name is public API that moves nothing — usually
+   a rule switched from `var(--dx-x)` to `$x` or a literal, or the generator published a Sass helper.
+   Read it where it belongs (or stop publishing it before release); after release, a published knob
+   must keep working. A name that **revived** just needs `--update-unread`. The list counts only reads
+   inside the bundle: about half of it is read by demos and application CSS by design.
+
+## Known gap
+
+A name that is read by a declaration that never wins the cascade (overwritten in the same rule, or
+beaten by a more specific selector) passes. Deciding that needs the cascade, not the text.