align component styles with css layers and root class merging

Author: cn0809

spx-gui/AGENTS.md

@@ -94,6 +94,7 @@ When working with backend unique string identifiers such as `username`, project
 
 * Keep `src/app.css` limited to Tailwind entry setup, theme bridge, and rare project-wide utilities.
 * Keep `src/components/ui/global.css` and `src/components/ui/reset.css` as the base reset/foundation layer (Tailwind preflight stays disabled).
+* The global CSS layer order is `theme, base, naive-ui, components, utilities`, declared in `index.html`.
 * Keep `--ui-*` tokens as the source of truth.
 * In Tailwind classes, prefer bridged semantic tokens (for example `text-text`, `text-title`, `bg-primary-100`).
 * In local CSS, prefer direct `--ui-*` variables instead of bridged Tailwind variables.
@@ -119,7 +120,8 @@ When working with backend unique string identifiers such as `username`, project
 * For root-class overrides and utility conflicts:
 	- For business components, external root `class` overrides are allowed by default. If utility conflicts need an explicit winner, prefer adding Tailwind's important modifier at the usage site (for example `rounded-md!`, `w-32!`) instead of expanding the component API. This keeps intent explicit, usage concise, and matches the fact that business components rarely need nested override chains.
 	- For most UI components, `twMerge` and `@layer components` are set up so external utilities or custom classes can override root classes in the common case without special handling, though edge cases can still exist.
-	- For the Naive UI-root components listed in `src/components/ui/README.md`, avoid relying on external `class` for styling-critical overrides when possible; the final result is often hard to predict.
+	- For the Naive UI-root components listed in `src/components/ui/README.md`, Naive UI defaults live in the `naive-ui` layer and our authored UI styles live in the `components` layer, so component-layer rules have higher cascade priority on the same element/property pair.
+	- Even so, those Naive UI-root components still are not identical to DOM-root utility wrappers. Treat them as component-specific: simple root overrides are often fine, while deeper visual changes may still need wrapper layout control, explicit props, or Naive UI theme overrides.
 * Avoid non-equivalent Tailwind simplifications for flex values. In particular, `flex: 1 1 0` is not equivalent to Tailwind `flex-1` (`flex: 1 1 0%`), so do not simplify between them unless the layout behavior has been verified. Likewise, do not simplify `flex: 0 0 auto` to `shrink-0`; use the equivalent `flex-none` when that shorthand is desired.
 * Prefer `style` / `:style` for one-off values when clearer than Tailwind arbitrary utilities. For example, prefer `style="box-shadow: 0 24px 32px -16px rgba(0, 0, 0, 0.1)"` over a long arbitrary utility such as `shadow-[0_24px_32px_-16px_rgba(0,0,0,0.1)]`.
 * For important/non-obvious background assets, prefer TS imports and inline `backgroundImage` binding.

spx-gui/src/components/ui/README.md

@@ -22,13 +22,15 @@
   - For most non-Naive UI components, prefer Tailwind utilities for local structure, layout, and surface styling
   - Local authored style blocks in the UI package use plain CSS; do not reintroduce SCSS
   - Keep complex selectors, animations, third-party/global overrides, and other readability-sensitive rules in plain CSS
+  - The global CSS layer order is `theme, base, naive-ui, components, utilities` and is declared in `spx-gui/index.html`
 
 - Root class handling
 
-  - Current cases fall into three buckets: DOM-root components with merged utilities, single-root semantic wrappers that rely on inherited classes, and Naive UI-root wrappers whose final class priority can be harder to predict
-  - If the root is a normal DOM element and the component already owns root utility classes, use `cn(..., attrs.class)` so external root classes are merged with `tailwind-merge`
+  - Current cases fall into three buckets: DOM-root components with merged utilities, single-root semantic wrappers that rely on inherited classes, and Naive UI-root wrappers whose root-level styling behavior still needs component-specific judgment
+  - If the root is a normal DOM element and the component already owns root utility classes, prefer an explicit `class?: ClassValue` prop and merge it with `cn(..., props.class ?? null)` so external root classes participate in `tailwind-merge`
   - If the component is a single-root wrapper whose styling still depends on semantic hook classes in `@layer components`, prefer Vue's default root attr/class/style inheritance unless explicit root attr control is needed
-  - If the rendered root is primarily a Naive UI component, do not assume external root classes will override reliably. Naive UI's internal styles are not layered with our component styles, so their priority can be higher and the final visual result may be hard to predict
+  - If the rendered root is primarily a Naive UI component, remember that Naive UI styles live in the `naive-ui` layer while our authored UI styles live in `@layer components`, so component-layer rules have higher cascade priority than Naive UI defaults on the same element/property pair
+  - Even so, Naive UI-root components still do not behave exactly like DOM-root utility wrappers: some visual details live on internal child nodes, teleported content, or Naive UI theme tokens instead of the exposed root element
   - Current Naive UI-root components that need extra care are:
 
     - `UIDropdown` → `NPopover`
@@ -42,12 +44,14 @@
     - `UIRadio` → `NRadio`
     - `UIRadioGroup` → `NRadioGroup`
     - `UIForm` → `NForm`
+    - `UITextInput` → `NInput`
+    - `UINumberInput` → `NInputNumber`
     - `UITimeline` → `NTimeline`
     - `UITimelineItem` → `NTimelineItem`
 
-  - For all UI components, an external `class` can still be passed, but do not rely on it for styling-critical behavior. Prefer an outer layout wrapper, explicit component props, or a dedicated API extension when finer control is needed
-  - For the Naive UI-root components listed above, root-level visual overrides from an external `class` are especially hard to predict. Prefer an outer layout wrapper or Naive UI theme overrides instead of assuming the component root will restyle reliably
-  - `UIDivider`, `UIFormItem`, `UILoading`, `UITextInput`, and `UINumberInput` also use Naive UI internally, but they expose a wrapper DOM root; external `class` lands on that wrapper instead of the inner Naive UI control
+  - For all UI components, an external `class` can still be passed, but prefer explicit component props or a dedicated API extension for styling-critical behavior
+  - For the Naive UI-root components listed above, simple root-level overrides are generally workable because the `components` layer sits above `naive-ui`, but do not assume every visual change should come from the root `class`. For deeper visual changes, prefer an outer layout wrapper, explicit props, or Naive UI theme overrides
+  - `UIDivider`, `UIFormItem`, and `UILoading` also use Naive UI internally, but they expose a wrapper DOM root; external `class` lands on that wrapper instead of the inner Naive UI control
   - This is primarily a component authoring/maintenance concern. The long-term goal is to keep these wrappers easy to consume so business code does not need to carry much Naive UI-specific styling knowledge
 
 ### Usage

spx-gui/src/components/ui/UIButton.vue

@@ -305,13 +305,15 @@ defineExpose({
   </button>
 </template>
 
-<style scoped>
-.ui-button-root:hover:enabled:not(:active) .ui-button-content {
-  background-color: var(--ui-button-hover-bg-color);
-}
+<style>
+@layer components {
+  .ui-button-root:hover:enabled:not(:active) .ui-button-content {
+    background-color: var(--ui-button-hover-bg-color);
+  }
 
-.ui-button-root[data-variant='shadow']:enabled:active .ui-button-content,
-.ui-button-root[data-variant='shadow'][data-loading='true'] .ui-button-content {
-  box-shadow: none;
+  .ui-button-root[data-variant='shadow']:enabled:active .ui-button-content,
+  .ui-button-root[data-variant='shadow'][data-loading='true'] .ui-button-content {
+    box-shadow: none;
+  }
 }
 </style>

spx-gui/src/components/ui/UINumberInput.vue

@@ -1,37 +1,28 @@
 <template>
-  <div :class="rootClass" :style="rootStyle">
-    <NInputNumber
-      ref="nInput"
-      v-bind="inputAttrs"
-      class="ui-number-input w-full min-w-0"
-      :placeholder="placeholder || ''"
-      :show-button="false"
-      :value="value"
-      :disabled="disabled"
-      :min="min"
-      :max="max"
-      @update:value="(v) => emit('update:value', v)"
-    >
-      <template v-if="slots.prefix != null" #prefix>
-        <slot name="prefix"></slot>
-      </template>
-      <template v-if="slots.suffix != null" #suffix>
-        <slot name="suffix"></slot>
-      </template>
-    </NInputNumber>
-  </div>
+  <NInputNumber
+    ref="nInput"
+    class="ui-number-input"
+    :placeholder="placeholder || ''"
+    :show-button="false"
+    :value="value"
+    :disabled="disabled"
+    :min="min"
+    :max="max"
+    @update:value="(v) => emit('update:value', v)"
+  >
+    <template v-if="!!slots.prefix" #prefix>
+      <slot name="prefix"></slot>
+    </template>
+    <template v-if="!!slots.suffix" #suffix>
+      <slot name="suffix"></slot>
+    </template>
+  </NInputNumber>
 </template>
 
 <script setup lang="ts">
-import { computed, onMounted, ref, type StyleValue, useAttrs, useSlots } from 'vue'
+import { onMounted, ref, useSlots } from 'vue'
 import { NInputNumber } from 'naive-ui'
 
-import { cn, type ClassValue } from './utils'
-
-defineOptions({
-  inheritAttrs: false
-})
-
 const props = defineProps<{
   value: number | null
   disabled?: boolean
@@ -45,14 +36,7 @@ const emit = defineEmits<{
   'update:value': [number | null]
 }>()
 
-const attrs = useAttrs()
 const slots = useSlots()
-const rootClass = computed(() => cn('w-full min-w-0 rounded-md', attrs.class as ClassValue))
-const rootStyle = computed(() => attrs.style as StyleValue)
-const inputAttrs = computed(() => {
-  const { class: _class, style: _style, ...rest } = attrs
-  return rest
-})
 
 // It's wierd that the prop `autofocus` of `NInput` does not work as expected, so we handle it manually.
 const nInput = ref<InstanceType<typeof NInputNumber> | null>(null)

spx-gui/src/components/ui/UITextInput.vue

@@ -1,50 +1,42 @@
+<!-- TODO: Wrap it with a native node ? -->
 <template>
-  <div :class="rootClass" :style="rootStyle">
-    <NInput
-      ref="nInput"
-      v-bind="inputAttrs"
-      class="ui-text-input w-full min-w-0"
-      :class="[`color-${color}`, `ui-input-size-${size}`]"
-      :placeholder="placeholder || ''"
-      :value="value"
-      :type="type"
-      :disabled="disabled"
-      :readonly="readonly"
-      :resizable="false"
-      @update:value="(v) => emit('update:value', v)"
-    >
-      <template v-if="slots.prefix != null" #prefix>
-        <slot name="prefix"></slot>
-      </template>
-      <template v-if="(value && clearable) || slots.suffix != null" #suffix>
-        <div
-          v-if="value && clearable"
-          class="-mr-1 flex h-5 w-5 cursor-pointer items-center justify-center rounded-full text-grey-800 transition-colors duration-200 hover:bg-grey-400 active:bg-grey-500"
-          @click="emit('update:value', '')"
-        >
-          <svg width="12" height="12" viewBox="0 0 12 12" fill="none" xmlns="http://www.w3.org/2000/svg">
-            <path
-              d="M6.70713 5.99999L9.35363 3.35347C9.54913 3.15847 9.54913 2.8415 9.35363 2.6465C9.15813 2.451 8.84212 2.451 8.64663 2.6465L6.00013 5.29299L3.35363 2.6465C3.15813 2.451 2.84212 2.451 2.64662 2.6465C2.45112 2.8415 2.45112 3.15847 2.64662 3.35347L5.29312 5.99999L2.64662 8.6465C2.45112 8.8415 2.45112 9.15847 2.64662 9.35347C2.74412 9.45097 2.87213 9.49999 3.00013 9.49999C3.12813 9.49999 3.25613 9.45097 3.35363 9.35347L6.00013 6.70699L8.64663 9.35347C8.74412 9.45097 8.87213 9.49999 9.00013 9.49999C9.12813 9.49999 9.25613 9.45097 9.35363 9.35347C9.54913 9.15847 9.54913 8.8415 9.35363 8.6465L6.70713 5.99999Z"
-              fill="currentColor"
-            />
-          </svg>
-        </div>
-        <slot name="suffix"></slot>
-      </template>
-    </NInput>
-  </div>
+  <NInput
+    ref="nInput"
+    class="ui-text-input"
+    :class="[`ui-text-input-color-${color}`, `ui-text-input-size-${size}`]"
+    :placeholder="placeholder || ''"
+    :value="value"
+    :type="type"
+    :disabled="disabled"
+    :readonly="readonly"
+    :resizable="false"
+    @update:value="(v) => emit('update:value', v)"
+  >
+    <template v-if="!!slots.prefix" #prefix>
+      <slot name="prefix"></slot>
+    </template>
+    <template v-if="(value && clearable) || !!slots.suffix" #suffix>
+      <div
+        v-if="value && clearable"
+        class="-mr-1 flex h-5 w-5 cursor-pointer items-center justify-center rounded-full text-grey-800 transition-colors duration-200 hover:bg-grey-400 active:bg-grey-500"
+        @click="emit('update:value', '')"
+      >
+        <svg width="12" height="12" viewBox="0 0 12 12" fill="none" xmlns="http://www.w3.org/2000/svg">
+          <path
+            d="M6.70713 5.99999L9.35363 3.35347C9.54913 3.15847 9.54913 2.8415 9.35363 2.6465C9.15813 2.451 8.84212 2.451 8.64663 2.6465L6.00013 5.29299L3.35363 2.6465C3.15813 2.451 2.84212 2.451 2.64662 2.6465C2.45112 2.8415 2.45112 3.15847 2.64662 3.35347L5.29312 5.99999L2.64662 8.6465C2.45112 8.8415 2.45112 9.15847 2.64662 9.35347C2.74412 9.45097 2.87213 9.49999 3.00013 9.49999C3.12813 9.49999 3.25613 9.45097 3.35363 9.35347L6.00013 6.70699L8.64663 9.35347C8.74412 9.45097 8.87213 9.49999 9.00013 9.49999C9.12813 9.49999 9.25613 9.45097 9.35363 9.35347C9.54913 9.15847 9.54913 8.8415 9.35363 8.6465L6.70713 5.99999Z"
+            fill="currentColor"
+          />
+        </svg>
+      </div>
+      <slot name="suffix"></slot>
+    </template>
+  </NInput>
 </template>
 
 <script setup lang="ts">
-import { computed, onMounted, ref, type StyleValue, useAttrs, useSlots } from 'vue'
+import { onMounted, ref, useSlots } from 'vue'
 import { NInput } from 'naive-ui'
 
-import { cn, type ClassValue } from './utils'
-
-defineOptions({
-  inheritAttrs: false
-})
-
 type Type = 'textarea' | 'text' | 'password'
 type Color = 'default' | 'white'
 type Size = 'medium' | 'large'
@@ -73,14 +65,7 @@ const emit = defineEmits<{
   'update:value': [string]
 }>()
 
-const attrs = useAttrs()
 const slots = useSlots()
-const rootClass = computed(() => cn('w-full min-w-0 rounded-md', attrs.class as ClassValue))
-const rootStyle = computed(() => attrs.style as StyleValue)
-const inputAttrs = computed(() => {
-  const { class: _class, style: _style, ...rest } = attrs
-  return rest
-})
 
 // It's weird that the prop `autofocus` of `NInput` does not work as expected, so we handle it manually.
 const nInput = ref<InstanceType<typeof NInput> | null>(null)
@@ -89,6 +74,29 @@ onMounted(() => {
 })
 </script>
 
+<style>
+@layer components {
+  /* color */
+  .ui-text-input-color-default {
+    --ui-text-input-bg-color: var(--ui-color-grey-300);
+    --ui-text-input-bg-color-hover: var(--ui-color-grey-400);
+  }
+
+  .ui-text-input-color-white {
+    --ui-text-input-bg-color: var(--ui-color-grey-100);
+    --ui-text-input-bg-color-hover: var(--ui-color-grey-100);
+  }
+
+  /* size */
+  .ui-text-input-size-medium {
+    --ui-text-input-height: 32px;
+  }
+  .ui-text-input-size-large {
+    --ui-text-input-height: 40px;
+  }
+}
+</style>
+
 <style scoped>
 /* it's not possible to control input's hovered-bg-color with themeOverrides, */
 /* so we do background color control here */
@@ -107,23 +115,4 @@ onMounted(() => {
 .ui-text-input :deep(.n-input__prefix) {
   margin-right: 8px;
 }
-
-/* color */
-.color-default {
-  --ui-text-input-bg-color: var(--ui-color-grey-300);
-  --ui-text-input-bg-color-hover: var(--ui-color-grey-400);
-}
-
-.color-white {
-  --ui-text-input-bg-color: var(--ui-color-grey-100);
-  --ui-text-input-bg-color-hover: var(--ui-color-grey-100);
-}
-
-/* size */
-.ui-input-size-medium {
-  --ui-text-input-height: 32px;
-}
-.ui-input-size-large {
-  --ui-text-input-height: 40px;
-}
 </style>

spx-gui/src/components/ui/UITooltip.vue

@@ -52,12 +52,10 @@ const attachTo = usePopupContainer()
 </script>
 
 <style>
-/*
-  Now the style is broken with scoped <style>, the `data-v-xxx` is not correctly applied on `NTooltip` element
-  TODO: use scoped style
-*/
-.ui-tooltip {
-  font-size: 12px; /* TODO: some text-size related var? */
-  line-height: 1.5;
+@layer components {
+  .ui-tooltip {
+    font-size: 12px; /* TODO: some text-size related var? */
+    line-height: 1.5;
+  }
 }
 </style>

spx-gui/src/components/ui/form/UIFormItem.vue

@@ -76,15 +76,13 @@ const handleContentInput = debounce(() => {
   .ui-form-item + .ui-form-item {
     margin-top: 24px;
   }
-}
-</style>
 
-<style scoped>
-.ui-form-item :deep(.n-form-item-feedback-wrapper) {
-  line-height: 1.57143;
-}
+  .ui-form-item :deep(.n-form-item-feedback-wrapper) {
+    line-height: 1.57143;
+  }
 
-.ui-form-item :deep(.n-form-item-feedback-wrapper):empty {
-  display: none;
+  .ui-form-item :deep(.n-form-item-feedback-wrapper):empty {
+    display: none;
+  }
 }
 </style>