You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/develop/tailwind-css-migration.md
+110Lines changed: 110 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -301,6 +301,116 @@ Global foundation styling should remain even in a Tailwind-based hybrid model.
301
301
4. Delete helper SCSS files only after they have no remaining imports or mixin usages.
302
302
5. Keep editor, runner, markdown, and Naive UI wrapper styling outside the migration scope unless there is a separate reason to refactor them.
303
303
304
+
## Pilot Conventions And Preferences
305
+
306
+
The community and tutorials pilot clarified a few practical conventions that should guide follow-up migrations.
307
+
308
+
These are not abstract preferences. They reflect patterns that were already implemented and verified in the pilot components and pages.
309
+
310
+
### 1. Keep Tailwind As A Local Authoring Tool, Not A New Global Dumping Ground
311
+
312
+
The global entry file [spx-gui/src/app.css](../../spx-gui/src/app.css) should stay narrowly scoped.
313
+
314
+
It is the right place for:
315
+
316
+
- Tailwind entry setup such as `@import "tailwindcss"` and `@source`
317
+
- the theme bridge from existing `--ui-*` variables to Tailwind tokens
318
+
- rare project-wide utilities that are truly cross-feature and not page-specific
319
+
320
+
It is not the right place for:
321
+
322
+
- tutorials-only utilities
323
+
- page-local dimensions, transforms, or background colors
324
+
- feature-specific card or banner styles
325
+
326
+
Rule of thumb:
327
+
328
+
- if a class name would only make sense inside one page or one small feature area, keep it local to that component instead of promoting it into `app.css`
329
+
330
+
### 2. Bridge Global Tokens, Not Page-Specific Business Styling
331
+
332
+
The Tailwind theme bridge should cover stable design-system tokens from [spx-gui/src/components/ui/tokens/index.ts](../../spx-gui/src/components/ui/tokens/index.ts).
333
+
334
+
That includes:
335
+
336
+
- shared palette tokens
337
+
- semantic tokens such as `primary`, `danger`, `success`, `sprite`, `sound`, and `stage`
338
+
- typography, spacing, radius, and shadow tokens
339
+
340
+
It should not absorb page-specific visual decisions such as a tutorials-only banner color or one-off sizing tokens.
341
+
342
+
Rule of thumb:
343
+
344
+
- bridge values that belong to the whole product design language
345
+
- keep values that exist only for one feature in the feature itself
346
+
347
+
### 3. Prefer Tailwind For Straightforward Layout And Surface Styling
348
+
349
+
The pilot confirmed that Tailwind works well for the following kinds of changes:
350
+
351
+
- flex and grid layout
352
+
- spacing, width, height, alignment, and overflow
353
+
- simple typography application through bridged tokens
354
+
- simple hover transitions on authored template nodes
- write the style directly in the template when the utilities remain readable
365
+
- remove the local style block after the result is verified
366
+
367
+
### 4. Do Not Force Tailwind Where A Small Inline Style Is Clearer
368
+
369
+
Some values are technically expressible in Tailwind but are not a good fit for utility classes.
370
+
371
+
Examples from the pilot:
372
+
373
+
- special color expressions such as `rgb(from var(--ui-color-grey-1000) r g b / 0.2)`
374
+
- asset URLs that are clearer when imported through TypeScript
375
+
- one-off values that would otherwise require long arbitrary-value classes
376
+
377
+
Preferred style in this category:
378
+
379
+
- import the asset or compute the value in script when that makes the dependency explicit
380
+
- bind it through `:style` when the inline form is shorter and clearer than a custom utility or arbitrary class
381
+
382
+
This is the current preferred pattern for one-off backgrounds in migrated components such as [spx-gui/src/components/tutorials/CourseSeriesItem.vue](../../spx-gui/src/components/tutorials/CourseSeriesItem.vue).
383
+
384
+
### 5. Do Not Introduce Setup Variables For Single-Use Style Values Without A Payoff
385
+
386
+
During the pilot, a temporary setup variable was introduced for a single background image style and then removed.
387
+
388
+
Preferred style:
389
+
390
+
- if a style value is used only once and is still readable inline, bind it directly in the template
391
+
- only lift it into script when it is reused, computed, or meaningfully improves readability
392
+
393
+
### 6. Prefer Explicit Asset Imports Over Tailwind `url(...)` Classes When Readability Matters
394
+
395
+
Tailwind arbitrary `url(...)` classes do work correctly through Vite build and asset hashing.
396
+
397
+
However, the pilot showed that this form can still create review friction because the dependency path is less explicit in the template.
398
+
399
+
Preferred style:
400
+
401
+
- for important or non-obvious asset references, prefer `import stageBgUrl from '...'` plus `:style="{ backgroundImage: \`url(${stageBgUrl})\` }"`
402
+
- reserve Tailwind `bg-[url(...)]` for cases where the shorthand is clearly readable and unlikely to cause doubt
403
+
404
+
### 7. Keep Migration Decisions At The Responsibility Level, Not The File-Extension Level
405
+
406
+
The pilot reinforced the original migration strategy:
407
+
408
+
- Tailwind is a good fit for local page-shell and card layout concerns
409
+
- local CSS or SCSS should remain for deep selectors, generated content, third-party DOM overrides, and complex stateful widgets
410
+
- a file does not need to become "100% Tailwind" to count as successfully migrated
411
+
412
+
The goal is clearer and more maintainable code, not maximizing utility-class usage.
413
+
304
414
## Recommendation
305
415
306
416
Tailwind CSS is worth evaluating in `spx-gui`, but only as a constrained utility layer.
Copy file name to clipboardExpand all lines: spx-gui/AGENTS.md
+37Lines changed: 37 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -58,6 +58,43 @@ Keep import statements in order:
58
58
59
59
* Generate accessibility info for interactive elements using `v-radar` directive.
60
60
61
+
## Styling Preferences
62
+
63
+
This section records the current styling preferences established during the Tailwind migration pilot.
64
+
65
+
### Global vs Local Styling
66
+
67
+
* Keep [src/app.css](src/app.css) limited to Tailwind entry setup, the theme bridge, and rare project-wide utilities.
68
+
* Do not move page-local or feature-local styles into `src/app.css` just because they are written with Tailwind.
69
+
* Keep page-specific dimensions, transforms, colors, and card/banner styling local to the relevant page or component.
70
+
71
+
### Design Tokens
72
+
73
+
* Keep the existing `--ui-*` design token system as the source of truth.
74
+
* Bridge stable product-wide tokens into Tailwind theme tokens in `src/app.css`.
75
+
* Do not add page-specific or one-off business styling values to the global theme bridge.
76
+
77
+
### When to Prefer Tailwind
78
+
79
+
* Prefer Tailwind for straightforward layout and surface styling: flex, grid, spacing, sizing, alignment, overflow, simple typography, and simple hover states.
80
+
* When Tailwind classes stay readable, write them directly in the template and remove the local style block after verification.
81
+
82
+
### When to Keep CSS or SCSS
83
+
84
+
* Keep local CSS or SCSS for deep selectors, generated content, third-party DOM overrides, and complex stateful widgets.
85
+
* Do not force a file to become fully Tailwind if a small amount of CSS or SCSS remains the clearest expression.
86
+
87
+
### Inline Styles
88
+
89
+
* Use `:style` for one-off values that are clearer inline than as Tailwind arbitrary values or custom utilities.
90
+
* This is preferred for special expressions such as `rgb(from ...)` values or asset-backed backgrounds when the inline form is easier to review.
91
+
* Do not introduce setup variables for single-use style values unless they are reused, computed, or materially improve readability.
92
+
93
+
### Asset References
94
+
95
+
* For important or non-obvious background assets, prefer TypeScript imports plus inline `backgroundImage` binding over Tailwind `bg-[url(...)]` classes.
96
+
* This makes the dependency explicit in code review while still going through Vite's normal asset build pipeline.
97
+
61
98
### Menu Item Text Guidelines
62
99
63
100
When creating or modifying menu items, follow these UI guidelines for ellipses:
0 commit comments