docs/superpowers/specs/2026-05-10-go-backend-css-sources-per-primitive-design.md

@@ -4,15 +4,15 @@
 
 **Goal**
 
-Refactor the Go backend design-system CSS so each UI primitive owns its own source stylesheet while the app and generated catalog continue shipping a single compiled `go-backend/static/styles.css`.
+Refactor the Go backend design-system CSS so each UI primitive owns its own source stylesheet beside its UI code while the app and generated catalog continue shipping a single compiled `go-backend/static/styles.css`.
 
 **Chosen Approach**
 
-Split CSS at the source level by primitive and aggregate those source files into the existing `styles.css` output during the build. This keeps runtime behavior unchanged while making the CSS easier to scale, review, and extend.
+Split CSS at the source level by primitive and co-locate those source files with the UI primitives that own them, then aggregate them into the existing `styles.css` output during the build. This keeps runtime behavior unchanged while making the CSS easier to scale, review, and extend.
 
 **Scope**
 
-- Move shared design-system CSS rules into source files organized by primitive.
+- Move shared design-system CSS rules into source files organized by primitive and stored beside the primitive code.
 - Keep one final shipped stylesheet: `go-backend/static/styles.css`.
 - Keep app templates and generated design-system pages linking the same single output file.
 - Add a small verification layer that proves the final built stylesheet still contains representative selectors for the primitives.
@@ -31,6 +31,7 @@ The design-system CSS should have two layers:
 
 1. **Primitive source files**
    - one file per UI primitive or catalog responsibility
+   - stored beside the owning primitive or catalog code
    - these files are the new source of truth for design-system styling
 
 2. **Aggregate build entry**
@@ -44,29 +45,28 @@ This preserves the current runtime contract:
 
 **Source File Structure**
 
-Recommended source directory:
+Recommended source locations:
 
-- `go-backend/static/css/catalog.css`
-- `go-backend/static/css/button.css`
-- `go-backend/static/css/badge.css`
-- `go-backend/static/css/icon-button.css`
-- `go-backend/static/css/input.css`
-- `go-backend/static/css/form-field.css`
-- `go-backend/static/css/modal.css`
-- `go-backend/static/css/table.css`
-- `go-backend/static/css/empty-state.css`
-- `go-backend/static/css/card.css`
-- `go-backend/static/css/spacing.css`
+- `go-backend/internal/web/ui/base.css`
+- `go-backend/internal/web/ui/button.css`
+- `go-backend/internal/web/ui/badge.css`
+- `go-backend/internal/web/ui/icon-button.css`
+- `go-backend/internal/web/ui/input.css`
+- `go-backend/internal/web/ui/textarea.css`
+- `go-backend/internal/web/ui/form-field.css`
+- `go-backend/internal/web/ui/modal.css`
+- `go-backend/internal/web/ui/table.css`
+- `go-backend/internal/web/ui/empty-state.css`
+- `go-backend/internal/web/ui/card.css`
+- `go-backend/internal/web/ui/spacing.css`
+- `go-backend/internal/web/ui/app.css`
+- `go-backend/internal/web/ui/catalog/catalog.css`
 
-Recommended aggregate entry:
-
-- `go-backend/static/css/styles.css`
-
-The aggregate entry should import the primitive files in a stable order so later files can intentionally override earlier shared primitive rules where needed.
+The build should read those files in a stable explicit order so later files can intentionally override earlier shared rules where needed.
 
 **Responsibility Boundaries**
 
-`catalog.css`
+`catalog/catalog.css`
 
 - catalog page chrome
 - catalog example wrappers
@@ -82,7 +82,7 @@ Primitive CSS files
   - `card.css` owns `.ui-card*`
   - `spacing.css` owns `.ui-space-*`
 
-Shared non-design-system app selectors such as dashboard-only `.project-*` styles should not be mixed into primitive CSS just because they are nearby in the current file. If they must remain in this refactor slice, they should be isolated intentionally rather than silently attached to a primitive that does not own them.
+Shared non-design-system app selectors such as dashboard-only `.project-*` styles should not be mixed into primitive CSS just because they are nearby in the current file. They should live in an explicit `internal/web/ui/app.css` source file so ownership stays within the UI layer without falsely attaching them to a primitive.
 
 **Build Contract**
 
@@ -92,19 +92,20 @@ The build should continue producing:
 
 Preferred shape:
 
-- the build reads the new aggregate source entry
+- the build reads an explicit ordered list of co-located source files
 - the output path remains unchanged
 
-If the current tooling expects a specific input file location, update that input path rather than changing all HTML consumers.
+The builder should not rely on a single `static/css` source directory anymore. HTML consumers stay unchanged.
 
 **Ordering Rules**
 
 Import order should be explicit and stable:
 
-1. catalog layout and wrappers
-2. low-level primitives used broadly
-3. higher-level primitives
-4. any intentionally shared compatibility rules last
+1. base and global UI-layer rules
+2. catalog layout and wrappers
+3. low-level primitives used broadly
+4. higher-level primitives
+5. app-only UI-layer rules last
 
 This avoids accidental cascade regressions during future additions.
 
@@ -112,8 +113,8 @@ This avoids accidental cascade regressions during future additions.
 
 Refactor incrementally but land as one coherent slice:
 
-- create the new source directory and aggregate entry
-- move selectors from the monolithic stylesheet into primitive files without renaming selectors
+- create the new co-located source files beside UI primitives and catalog code
+- move selectors from the monolithic stylesheet into those files without renaming selectors
 - regenerate `go-backend/static/styles.css`
 - verify component tests and catalog generation still pass
 
@@ -155,8 +156,8 @@ Mitigation:
 
 This work is complete when:
 
-- each design-system primitive has its own source CSS file
-- catalog-specific CSS is separated from primitive CSS
+- each design-system primitive has its own source CSS file beside its UI code
+- catalog-specific CSS is separated from primitive CSS and stored beside catalog code
 - the app still ships one `go-backend/static/styles.css`
 - app and catalog HTML consumers remain unchanged
 - tests and generated catalog output still pass