sv

Author: nighca

docs/develop/index.md

@@ -14,4 +14,4 @@ See `package.json` or `go.mod` files in subdirectories for details.
 
 ### Architecture Design
 
-TODO.
+- [Tailwind CSS Migration Assessment for spx-gui](./tailwind-css-migration.md)

docs/develop/tailwind-css-migration.md

@@ -0,0 +1,255 @@
+# Tailwind CSS Migration Assessment for spx-gui
+
+This document investigates whether XBuilder frontend styling in `spx-gui` should migrate to Tailwind CSS.
+
+Issue: `goplus/builder#2981`
+
+## Conclusion
+
+Tailwind CSS is technically feasible in `spx-gui`, but a full migration is not a good near-term tradeoff.
+
+The current frontend already has a working design-token layer, a custom UI component library, and deep integration with Naive UI theme overrides. Because of that, Tailwind would mainly change the authoring model for layout and simple component styling. It would not replace major parts of the existing styling system unless the project also commits to a broader UI-layer refactor.
+
+The recommended direction is an incremental hybrid approach:
+
+- keep the existing `--ui-*` design tokens and Naive UI theme layer
+- add Tailwind only as an optional utility layer
+- validate it on a small set of low-risk pages or self-contained components first
+- only expand usage if the pilot materially improves development speed and code review quality
+
+## Current Styling Architecture
+
+The current frontend styling model is centered around Vue SFC scoped SCSS plus shared CSS variables.
+
+- `spx-gui` uses Vite + Vue 3 and already includes `sass`, but has no Tailwind or PostCSS setup in [spx-gui/package.json](../../spx-gui/package.json)
+- the app loads global styling through [spx-gui/src/App.vue](../../spx-gui/src/App.vue) and [spx-gui/src/components/ui/global.scss](../../spx-gui/src/components/ui/global.scss)
+- design tokens are defined in TypeScript under [spx-gui/src/components/ui/tokens/index.ts](../../spx-gui/src/components/ui/tokens/index.ts) and related files
+- the token objects are converted into `--ui-*` CSS variables and injected globally by [spx-gui/src/components/ui/UIConfigProvider.vue](../../spx-gui/src/components/ui/UIConfigProvider.vue)
+- Naive UI theme overrides are also defined in [spx-gui/src/components/ui/UIConfigProvider.vue](../../spx-gui/src/components/ui/UIConfigProvider.vue), so the token system serves both custom CSS and third-party components
+- most component styles live inside local `<style scoped lang="scss">` blocks, for example [spx-gui/src/components/ui/UIButton.vue](../../spx-gui/src/components/ui/UIButton.vue) and [spx-gui/src/components/editor/navbar/EditorNavbar.vue](../../spx-gui/src/components/editor/navbar/EditorNavbar.vue)
+
+Measured footprint in `spx-gui/src`:
+
+- 411 Vue files total
+- 325 Vue files contain a `<style>` block
+- 322 Vue files use SCSS in the SFC
+- 115 `:deep(...)` usages override descendants or third-party internals
+- 22 direct imports from `naive-ui`
+- 5 standalone stylesheet files under `src`, with most styling still embedded in Vue SFCs
+
+Representative styling patterns:
+
+- token-driven custom components: [spx-gui/src/components/ui/UIButton.vue](../../spx-gui/src/components/ui/UIButton.vue)
+- app-wide token and theme bridge: [spx-gui/src/components/ui/UIConfigProvider.vue](../../spx-gui/src/components/ui/UIConfigProvider.vue)
+- responsive SCSS mixins: [spx-gui/src/components/ui/responsive.scss](../../spx-gui/src/components/ui/responsive.scss) and [spx-gui/src/components/community/CenteredWrapper.vue](../../spx-gui/src/components/community/CenteredWrapper.vue)
+- complex page-level nested styling: [spx-gui/src/pages/community/project.vue](../../spx-gui/src/pages/community/project.vue)
+- content-renderer deep selectors: [spx-gui/src/components/copilot/MarkdownView.vue](../../spx-gui/src/components/copilot/MarkdownView.vue)
+
+## Tailwind Fit Assessment
+
+Tailwind fits part of the project well, but not all of it.
+
+Good fit:
+
+- layout-heavy pages using flex, grid, spacing, width, and alignment utilities
+- simple presentational components with limited state combinations
+- new pages or isolated features where templates are already the main source of UI structure
+- responsive layout rules, because the current breakpoint usage is limited and can be mapped into a custom Tailwind config
+
+Weak fit:
+
+- components with many styling states encoded through local CSS variables and nested selectors
+- custom wrappers around Naive UI that rely on theme overrides plus `:deep(...)` selectors
+- content renderers and editor surfaces that style generated DOM, not just authored template nodes
+- components with runtime geometry or inline styles, such as sliders, image previews, waveform editors, or draggable/resizable panes
+
+Poor or no fit:
+
+- Monaco editor integration and other third-party DOM that already depends on custom CSS
+- Konva or canvas-rendered surfaces where styling is not driven by CSS utility classes
+
+## Migration Cost Estimate
+
+Estimated cost if the goal is only to introduce Tailwind as an optional utility layer:
+
+- setup and token mapping: 1 to 2 engineer-days
+- pilot migration for 1 small feature area: 2 to 5 engineer-days
+- documentation and team conventions: 1 engineer-day
+
+Estimated cost for a meaningful incremental rollout across layout-heavy areas:
+
+- 2 to 4 engineer-weeks
+- includes Tailwind setup, token mapping, conventions, 10 to 20 component/page migrations, and cleanup of duplicated styling patterns
+
+Estimated cost for a broad migration that tries to make Tailwind the dominant styling approach in `spx-gui`:
+
+- 6 to 10 engineer-weeks at minimum
+- likely more if the scope includes reworking Naive UI wrappers, complex editor surfaces, and duplicated `:deep(...)` customizations
+
+Estimated cost for a true full migration away from the current SCSS-plus-token approach:
+
+- high risk and not currently justified
+- would effectively become a UI architecture refactor, not just a styling migration
+
+## Major Risks And Constraints
+
+### 1. Existing token system already solves part of the problem
+
+The project already has a centralized token system and shared CSS variables. Tailwind would not replace that cleanly unless the team rewrites token consumption across both custom components and Naive UI overrides.
+
+### 2. Tailwind does not remove the Naive UI dependency
+
+Naive UI is embedded in the app theme model via [spx-gui/src/components/ui/UIConfigProvider.vue](../../spx-gui/src/components/ui/UIConfigProvider.vue). Even after adding Tailwind, the project would still need to maintain Naive UI theming and style overrides.
+
+### 3. Scoped SCSS is currently aligned with component boundaries
+
+A large share of the codebase keeps style logic close to each Vue component. Tailwind can improve speed for simple cases, but moving every component to class-heavy templates would be noisy and produce uneven code style if done inconsistently.
+
+### 4. `:deep(...)` usage is a real migration brake
+
+There are 115 `:deep(...)` usages. These target generated content, child internals, or third-party component markup. Tailwind utilities do not eliminate that category of styling work.
+
+### 5. Complex editor UI gets limited value from utility classes
+
+Several editor surfaces rely on runtime positions, inline CSS variables, drag behavior, SVG, or canvas-like rendering. Those areas already need custom CSS or programmatic styling, so Tailwind adds little leverage there.
+
+### 6. Design consistency can regress during mixed migration
+
+If the team starts using raw Tailwind classes without a token bridge and a small set of conventions, the result will drift away from the existing `--ui-*` design language.
+
+### 7. Maintenance cost can increase before it decreases
+
+During the transition, the project would have to maintain:
+
+- scoped SCSS
+- CSS variables
+- Naive UI theme overrides
+- Tailwind config and utilities
+
+That is acceptable only if the migration remains intentionally narrow at first.
+
+## Strategy Comparison
+
+### Full Migration
+
+Pros:
+
+- one dominant styling model after the migration finishes
+- potentially faster AI-assisted markup styling in the long run
+
+Cons:
+
+- high rewrite cost
+- high risk of regressions in editor surfaces and custom UI components
+- still does not remove the need for custom CSS in several critical areas
+- poor short-term return on effort
+
+Assessment: not recommended.
+
+### Incremental Migration
+
+Pros:
+
+- low risk
+- easy to stop if the benefits are smaller than expected
+- preserves current design tokens and Naive UI integration
+- lets the team learn where Tailwind actually helps
+
+Cons:
+
+- mixed styling models for some time
+- requires discipline to avoid ad hoc utility usage
+
+Assessment: viable.
+
+### Hybrid Approach With Guardrails
+
+This means Tailwind is introduced only for selected categories of work while SCSS remains the default for the rest.
+
+Recommended usage boundaries:
+
+- use Tailwind for page layout, spacing, simple cards, and simple wrappers
+- keep SCSS for complex stateful widgets, `:deep(...)` overrides, editor internals, animation-heavy UI, and third-party DOM styling
+- keep the existing token system as the source of truth
+
+Assessment: best option.
+
+## Recommended Plan
+
+### Phase 1: Proof Of Fit
+
+- add Tailwind to `spx-gui` without changing existing styling
+- map Tailwind theme values to the current `--ui-*` tokens where practical
+- define custom breakpoints that match current responsive behavior
+- document when Tailwind is allowed and when local SCSS should remain the default
+
+Success criteria:
+
+- build works cleanly with Vite
+- no conflicts with current global styles or Naive UI theme overrides
+- a pilot page can use Tailwind without introducing duplicated design values
+
+### Phase 2: Pilot Migration
+
+Choose one small, layout-oriented area first. Good candidates are community or tutorial pages, not the editor core.
+
+Suggested pilot targets:
+
+- [spx-gui/src/components/community/CenteredWrapper.vue](../../spx-gui/src/components/community/CenteredWrapper.vue)
+- community listing or detail sections with mostly layout styling
+- simple UI wrappers that do not depend heavily on `:deep(...)`
+
+Avoid as first pilots:
+
+- editor navbar and editor panels
+- Monaco-related UI
+- waveform, drag-and-drop, or resize-heavy components
+- components that mainly customize Naive UI internals
+
+Success criteria:
+
+- the converted code is shorter or clearer than the current SCSS
+- design stays visually identical
+- AI-assisted edits become easier in practice, not just in theory
+
+### Phase 3: Decide Whether To Expand
+
+After the pilot, compare:
+
+- implementation speed
+- readability in code review
+- consistency with existing design tokens
+- regression rate
+- amount of residual SCSS still required
+
+If the pilot does not show a clear gain, stop and keep the current styling model.
+
+If the pilot is successful, expand only into other layout-heavy areas.
+
+## Recommendation
+
+Tailwind CSS is worth evaluating in `spx-gui`, but only as a constrained utility layer.
+
+It is not worth pursuing as a near-term full migration target because the project already has:
+
+- a functioning token system
+- a custom UI component layer
+- Naive UI theme integration
+- many component-local scoped SCSS blocks
+- a meaningful number of deep selectors and complex editor surfaces
+
+The practical recommendation for issue `#2981` is:
+
+- conclude that Tailwind is feasible
+- reject full migration for now
+- recommend a hybrid incremental pilot
+- make the pilot target a simple community or tutorial area before touching editor internals
+
+## Suggested Next Step
+
+If the team wants to continue after this assessment, the next task should be a small proof-of-concept PR that:
+
+- installs Tailwind in `spx-gui`
+- defines the minimal theme bridge to current tokens
+- converts one low-risk page or wrapper component
+- records what became simpler and what still required SCSS