docs: Tailwind v4 usage guide + refresh stale config references - #5541
Merged
norman-abramovitz merged 1 commit intoJul 2, 2026
Merged
Conversation
Add docs/tailwind-usage.md covering the v4 CSS-first configuration (@theme in packages/theme/styles/tailwind.css), the cascade-layer interaction between unlayered SCSS and @layer utilities, the two dark-mode token rules (semantic singletons adapt via .dark-theme; numbered scales need explicit dark: pairing), the @apply/@reference build-only failure mode, and the transitive Sass partial HMR gotcha. Update theming-architecture.md and branding-architecture.md, which still documented tailwind.config.js — deleted in the v4 conversion — and sync the angular.json styles list with reality. Refs cloudfoundry#5539 cloudfoundry#5540
norman-abramovitz
merged commit Jul 2, 2026
713a7f2
into
cloudfoundry:develop
25 of 27 checks passed
This was referenced Jul 2, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
docs/tailwind-usage.md— how we expect Tailwind CSS v4 to be used in Stratos — and refreshes stale references in the existing theming/branding docs.The new doc covers:
tailwind.config.js; everything lives insrc/frontend/packages/theme/styles/tailwind.css(@theme,@plugin,@custom-variant,@source)@layer baseconvention for global element defaults (root cause of 24px line seems to enforce a consistent default icon size for the Material Icons font across the whole app conflicts with #5539)text-danger,bg-content-bg) adapt automatically via.dark-theme; numbered scales (*-50…*-900) are static and need explicitdark:pairing@applyin component SCSS — the@reference 'tailwindcss'requirement and the build-only failure mode for custom tokens that vitest cannot catchDoc refreshes (all verified against the current build):
theming-architecture.md: overview diagram, Key Files table,angular.jsonstyles list (was missingtailwind.css), add-a-variable step 6, cross-link to the new docbranding-architecture.md: staletailwind.config.jstable rowWhy
Issues #5539 and #5540 both traced back to Tailwind v4 mechanics that were undocumented: the cascade-layer interaction and the HMR limitation. The existing docs still described the v3
tailwind.config.jssetup.Refs #5539 #5540