New design demo

spx-gui/.vscode/extensions.json

@@ -1,7 +1,8 @@
 {
   "recommendations": [
-    "Vue.volar",
+    "vue.volar",
     "dbaeumer.vscode-eslint",
-    "esbenp.prettier-vscode"
+    "esbenp.prettier-vscode",
+    "bradlc.vscode-tailwindcss"
   ]
 }

spx-gui/AGENTS.md

@@ -80,6 +80,53 @@ When working with backend unique string identifiers such as `username`, project
 
 * Generate accessibility info for interactive elements using `v-radar` directive.
 
+## Styling Preferences
+
+### Defaults
+
+* Outside `src/components/ui/`, use Tailwind as the default for local layout and surface styling.
+* Keep styles local to the page/feature/component. Do not move local styles into `src/app.css`.
+* Prefer readable template utilities and remove redundant local style blocks after migration.
+* If local authored styles are still needed, prefer plain CSS over SCSS.
+
+### Boundaries and Source of Truth
+
+* 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).
+* 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/SCSS, prefer direct `--ui-*` variables instead of bridged Tailwind variables.
+
+### Responsive and Theme Rules
+
+* Keep breakpoints in `src/app.css` aligned with `src/components/ui/responsive.ts`.
+* Use only `tablet`, `desktop`, and `desktop-large` responsive names.
+* Prefer responsive CSS/Tailwind variants over `useResponsive()`; keep `useResponsive()` for non-style runtime logic.
+* Keep Tailwind theme namespaces reset to project tokens only (color, shadow, font, text, radius, etc.).
+
+### When Local CSS/SCSS Is Better
+
+* Keep local CSS/SCSS for `:deep(...)`, generated content, third-party DOM overrides, and complex stateful widgets.
+* Prefer plain local CSS over complex Tailwind descendant/arbitrary selectors for cross-component or slot-content styling.
+* Preserve semantic hook classes used by parent selectors or slots (for example `.corner-menu`, `.course-item-mini`).
+* For newly added components, avoid introducing `:deep(...)` selectors and cross-file hook classes when possible, since they increase maintenance cost.
+* Do not force full Tailwind conversion when a small local style block is clearer.
+
+### Practical Migration Notes
+
+* Preserve exact `flex: <grow> <shrink> <basis>` semantics with `flex-[<grow>_<shrink>_<basis>]`.
+* Prefer `:style` for one-off values when clearer than Tailwind arbitrary utilities.
+* For important/non-obvious background assets, prefer TS imports and inline `backgroundImage` binding.
+* For `UIImg`, `UIIcon`, and similar wrappers, verify root-style conflicts; use an outer layout wrapper if needed.
+* In plain `<style scoped>`, flatten `:deep(...)` selectors (for example `.preview :deep(svg)`).
+* Keep single-use values local; only add setup variables when reused/computed or clearly improving readability.
+* Preserve meaningful existing comments/TODOs. For exact local non-token values, keep them local and add a nearby `TODO` for later tokenization review.
+
+### UI Package Transitional Rule
+
+* In `src/components/ui/`, the long-term direction is still Tailwind/plain CSS, but local SCSS is allowed temporarily when it is clearly the most readable option.
+* Do not add or keep business-code imports of SCSS helpers from `src/components/ui/`.
+
 ### Menu Item Text Guidelines
 
 When creating or modifying menu items, follow these UI guidelines for ellipses: