# Go Backend Semantic CSS Color Tokens Implementation Plan

> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Replace hardcoded color literals across the co-located Go backend CSS sources with semantic tokens defined in `go-backend/internal/web/ui/base.css`.

**Architecture:** Extend `base.css` into the single shared visual token layer for colors, overlays, gradients, and shadows. Then update every co-located CSS file under `internal/web/ui` and `internal/web/ui/catalog` to consume those tokens, keeping the existing selector API and single generated `go-backend/static/styles.css`.

**Tech Stack:** CSS custom properties, Go, `cmd/buildstyles`, `just`, Go `testing`

---

## Chunk 1: Token Contract

## Task 1: Define The Token Contract In Tests

**Files:**
- Modify: `go-backend/internal/web/ui/ui_test.go`
- Modify: `go-backend/cmd/buildstyles/main_test.go`

- [ ] **Step 1: Extend the stylesheet contract test with representative semantic tokens**

Update `TestSharedSemanticClassesExistInStylesheet` in `go-backend/internal/web/ui/ui_test.go` so it asserts token presence in addition to selector presence.

Add checks like:

```go
for _, want := range []string{
	`--color-text-primary`,
	`--color-surface-default`,
	`--color-status-warning-soft-bg`,
	`--shadow-surface-md`,
	`--overlay-backdrop-default`,
	`.ui-button-solid.ui-button-default`,
	`.ui-badge-warning`,
	`.ui-modal-panel`,
	`.catalog-page`,
} {
	if !strings.Contains(css, want) {
		t.Fatalf("expected stylesheet to contain %q", want)
	}
}
```

- [ ] **Step 2: Keep the buildstyles generator test format-stable**

Ensure `go-backend/cmd/buildstyles/main_test.go` still only verifies ordered concatenation and generated headers. Do not add token semantics there; that belongs in the stylesheet contract test.

- [ ] **Step 3: Run the focused contract tests and confirm failure if tokens are not present yet**

Run: `cd go-backend && go test ./cmd/buildstyles ./internal/web/ui -run 'TestGenerateStylesConcatenatesSourcesInOrder|TestSharedSemanticClassesExistInStylesheet' -count=1`

Expected: FAIL in `TestSharedSemanticClassesExistInStylesheet` until `base.css` defines the new semantic tokens and `styles.css` is rebuilt.

- [ ] **Step 4: Commit the failing contract tests**

```bash
git add go-backend/internal/web/ui/ui_test.go go-backend/cmd/buildstyles/main_test.go
git commit -m "test: define semantic css token contract"
```

## Chunk 2: Base Tokens

## Task 2: Introduce Semantic Color And Effect Tokens In `base.css`

**Files:**
- Modify: `go-backend/internal/web/ui/base.css`

- [ ] **Step 1: Group the existing core variables into a clearer semantic structure**

Keep the existing root block, but reorganize it into sections for:
- core neutrals
- borders and surfaces
- brand/action
- semantic statuses
- overlays and shadows
- runtime fallbacks

- [ ] **Step 2: Add semantic text, surface, and border tokens**

Define tokens such as:

```css
--color-text-primary: hsl(0 0% 9%);
--color-text-muted: hsl(0 0% 43.5%);
--color-surface-page: hsl(0 0% 100%);
--color-surface-default: #ffffff;
--color-surface-subtle: hsl(0 0% 96.1%);
--color-border-default: hsl(0 0% 90.9%);
--color-border-strong: #d1d5db;
```

Use the existing values already present in the repo unless there is a documented reason to consolidate.

- [ ] **Step 3: Add semantic brand/action tokens**

Define tokens such as:

```css
--color-brand-primary: #804eec;
--color-brand-primary-hover: #6d28d9;
--color-brand-primary-active: #5b21b6;
--color-focus-ring: rgba(124, 58, 237, 0.2);
--color-brand-foreground: #ffffff;
```

- [ ] **Step 4: Add semantic status token triplets**

For each status family, define soft backgrounds, borders, foregrounds, and stronger action values where the current CSS needs them.

Representative examples:

```css
--color-status-info-soft-bg: #eff6ff;
--color-status-info-soft-border: #bfdbfe;
--color-status-info-foreground: #2563eb;

--color-status-warning-soft-bg: #fff4e2;
--color-status-warning-soft-border: #db9729;
--color-status-warning-foreground: #db9729;
--color-status-warning-strong: #db9729;
--color-status-warning-strong-hover: #c37f12;
--color-status-warning-strong-active: #a9670c;
```

Add equivalent success and danger tokens using the current CSS values.

- [ ] **Step 5: Add shadow, overlay, and fallback tokens**

Define shared tokens used repeatedly across the UI layer, for example:

```css
--shadow-surface-sm: 0 10px 30px rgba(15, 23, 42, 0.05);
--shadow-surface-md: 0 10px 30px rgba(15, 23, 42, 0.06);
--shadow-surface-lg: 0 24px 48px rgba(15, 23, 42, 0.18);
--overlay-backdrop-default: rgba(17, 24, 39, 0.52);
--color-project-fallback: #3b82f6;
```

- [ ] **Step 6: Run the focused contract test**

Run: `cd go-backend && go test ./internal/web/ui -run TestSharedSemanticClassesExistInStylesheet -count=1`

Expected: still FAIL until the rest of the CSS files consume the tokens and `styles.css` is regenerated.

- [ ] **Step 7: Commit the token vocabulary**

```bash
git add go-backend/internal/web/ui/base.css go-backend/internal/web/ui/ui_test.go
git commit -m "feat: add semantic css token vocabulary"
```

## Chunk 3: Primitive And Catalog Adoption

## Task 3: Replace Hardcoded Literals In Primitive And Catalog CSS

**Files:**
- Modify: `go-backend/internal/web/ui/button.css`
- Modify: `go-backend/internal/web/ui/badge.css`
- Modify: `go-backend/internal/web/ui/icon-button.css`
- Modify: `go-backend/internal/web/ui/input.css`
- Modify: `go-backend/internal/web/ui/textarea.css`
- Modify: `go-backend/internal/web/ui/form-field.css`
- Modify: `go-backend/internal/web/ui/modal.css`
- Modify: `go-backend/internal/web/ui/card.css`
- Modify: `go-backend/internal/web/ui/empty-state.css`
- Modify: `go-backend/internal/web/ui/catalog/catalog.css`

- [ ] **Step 1: Convert button variants to semantic tokens**

In `button.css`, replace all hardcoded foreground, background, hover, and active values with tokens from `base.css`.

Examples:

```css
.ui-button:focus-visible {
	box-shadow: 0 0 0 3px var(--color-focus-ring);
}

.ui-button-solid.ui-button-default {
	background: var(--color-brand-primary);
	color: var(--color-brand-foreground);
}
```

- [ ] **Step 2: Convert badges to semantic status tokens**

In `badge.css`, replace each family with status tokens:

```css
.ui-badge-warning {
	background: var(--color-status-warning-soft-bg);
	border-color: var(--color-status-warning-soft-border);
	color: var(--color-status-warning-foreground);
}
```

- [ ] **Step 3: Convert shared control styles**

In `input.css`, `textarea.css`, and `form-field.css`, replace hardcoded text, placeholder, border, and focus values with semantic tokens.

- [ ] **Step 4: Convert modal, card, and empty-state files**

Use semantic surface, border, text, shadow, and overlay tokens in:
- `modal.css`
- `card.css`
- `empty-state.css`

- [ ] **Step 5: Convert icon button and catalog styling**

Replace hardcoded muted text, hover backgrounds, snippet backgrounds, and accent colors in:
- `icon-button.css`
- `catalog/catalog.css`

- [ ] **Step 6: Rebuild the generated stylesheet**

Run: `cd go-backend && go run ./cmd/buildstyles`

Expected: `go-backend/static/styles.css` now contains the semantic token names and no longer relies on hardcoded values in these source files.

- [ ] **Step 7: Run focused UI and catalog verification**

Run: `cd go-backend && go test ./internal/web/ui ./internal/web/ui/catalog ./cmd/buildstyles -count=1`

Expected: PASS.

- [ ] **Step 8: Commit primitive/catalog adoption**

```bash
git add go-backend/internal/web/ui/*.css go-backend/internal/web/ui/catalog/catalog.css go-backend/static/styles.css
git commit -m "refactor: replace primitive css colors with semantic tokens"
```

## Chunk 4: App Layer Adoption

## Task 4: Replace Hardcoded Literals In `app.css`

**Files:**
- Modify: `go-backend/internal/web/ui/app.css`
- Modify: `go-backend/internal/web/ui/base.css`

- [ ] **Step 1: Identify repeated app-only literals and map them to existing tokens first**

Before adding any new token, check whether an existing semantic token already fits. Reuse it unless the app needs a distinct visual meaning.

- [ ] **Step 2: Add only the additional semantic tokens that `app.css` truly needs**

Examples likely needed:
- app panel surface variants
- sidebar/background translucency variants
- stronger app-specific shadow tokens
- gradient stop tokens
- project accent fallback tokens

Do not add raw-value-named variables.

- [ ] **Step 3: Replace hardcoded app colors section by section**

Update:
- auth/login surfaces and gradients
- sidebar surfaces, text, borders, shadows
- overview/project/task status styling
- not-found and hero surfaces
- task widgets and quick-action cards

Preserve the current rendered appearance.

- [ ] **Step 4: Keep runtime variables semantic**

Update patterns like:

```css
background: var(--project-color, var(--color-project-fallback));
```

instead of falling back to raw hex values.

- [ ] **Step 5: Rebuild the generated stylesheet**

Run: `cd go-backend && go run ./cmd/buildstyles`

Expected: `static/styles.css` reflects the tokenized app layer.

- [ ] **Step 6: Run broader verification**

Run: `cd go-backend && go test ./internal/web/... ./cmd/designsystem ./cmd/buildstyles -count=1`

Expected: PASS.

- [ ] **Step 7: Commit app-layer token adoption**

```bash
git add go-backend/internal/web/ui/app.css go-backend/internal/web/ui/base.css go-backend/static/styles.css
git commit -m "refactor: replace app css colors with semantic tokens"
```

## Chunk 5: Final Audit

## Task 5: Prove The Refactor Removed Hardcoded Color Drift

**Files:**
- Verify: `go-backend/internal/web/ui/*.css`
- Verify: `go-backend/internal/web/ui/catalog/catalog.css`
- Verify: `go-backend/static/styles.css`

- [ ] **Step 1: Search for remaining hardcoded colors in the co-located CSS sources**

Run: `cd go-backend && rg -n "#[0-9a-fA-F]{3,8}|rgba\\(|hsl\\(" internal/web/ui/*.css internal/web/ui/catalog/*.css`

Expected: only intentional token definitions remain in `base.css`, plus any explicitly justified one-off literals that were consciously retained.

- [ ] **Step 2: Search the generated stylesheet for representative token names**

Run: `cd go-backend && rg -n -- '--color-text-primary|--color-surface-default|--color-status-warning-soft-bg|--shadow-surface-md|--overlay-backdrop-default' static/styles.css`

Expected: matching lines exist.

- [ ] **Step 3: Re-run the full verification set fresh**

Run: `cd go-backend && go test ./internal/web/... ./cmd/designsystem ./cmd/buildstyles -count=1`

Expected: PASS.

- [ ] **Step 4: Commit any final cleanup needed after audit**

```bash
git add go-backend/internal/web/ui/*.css go-backend/internal/web/ui/catalog/catalog.css go-backend/static/styles.css go-backend/internal/web/ui/ui_test.go
git commit -m "chore: finalize semantic css token refactor"
```
