# Phase 13: Design System Foundation - Discussion Log

> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.

**Date:** 2026-05-16
**Phase:** 13-design-system-foundation
**Areas discussed:** Token values, app.css scope, Catalog route, Component API

---

## Token Values

| Option | Description | Selected |
|--------|-------------|----------|
| Port verbatim | Copy go-backend/base.css token values as-is. Adjust later after seeing catalog. | ✓ |
| Adjust first | User has specific color/style changes in mind before tokens are baked in. | |
| You decide | Claude ports verbatim and notes obviously unfinished token groups. | |

**User's choice:** Port verbatim

---

| Option | Description | Selected |
|--------|-------------|----------|
| Port all tokens | Full 223-line base.css copied to backend. | ✓ |
| Component-referenced only | Only port tokens that component CSS actually consumes. | |
| You decide | Claude ports all tokens. | |

**User's choice:** Port all tokens

---

| Option | Description | Selected |
|--------|-------------|----------|
| Replace entirely | go-backend's base.css already includes the same resets. | ✓ |
| Merge carefully | Keep existing resets, add :root block below. | |
| You decide | Claude replaces entirely. | |

**User's choice:** Replace entirely

---

| Option | Description | Selected |
|--------|-------------|----------|
| Token consumption required | Component CSS must use var(…). | |
| Tokens sufficient for Phase 13 | Port token vocabulary now; wire component CSS in Phases 14–17. | ✓ |
| You decide | Claude wires component CSS to tokens. | |

**User's choice:** Tokens sufficient for Phase 13

---

## app.css Scope

| Option | Description | Selected |
|--------|-------------|----------|
| Foundation — Phase 13 | Port app.css now as the app shell. | |
| Per-surface — Phases 14–17 | Phase 13 ships component-level CSS only. | ✓ |
| Split it | Port shell skeleton in Phase 13; surface decoration in 14–17. | |

**User's choice:** Per-surface — Phases 14–17

---

| Option | Description | Selected |
|--------|-------------|----------|
| Component files only | tailwind.input.css imports base.css + component CSS. No app shell. | ✓ |
| Minimal shell too | Add a thin app.css with layout primitives only. | |

**User's choice:** Component files only

---

| Option | Description | Selected |
|--------|-------------|----------|
| Strip page-level rules | Component CSS stays .ui-* scoped. Page rules wait for Phase 14. | ✓ |
| Include if needed | Keep page-level rules if a component needs them. | |

**User's choice:** Strip page-level rules

---

| Option | Description | Selected |
|--------|-------------|----------|
| Plain page, no shell | Components in isolation on minimal layout. | |
| Fake shell | Catalog mimics app layout (sidebar + content area). | ✓ |

**User's choice:** Fake shell

---

## Catalog Route

| Option | Description | Selected |
|--------|-------------|----------|
| Env var check (DEV_MODE=true) | Handler checks env. Routes registered but 404 in production. | |
| Build tag | //go:build catalog gates the handler. Zero attack surface in prod. | ✓ |
| Config flag (APP_ENV=development) | Reads existing APP_ENV config. | |

**User's choice:** Build tag

---

| Option | Description | Selected |
|--------|-------------|----------|
| Single long-scroll page | One page, all components visible when scrolling. | |
| Sidebar/anchor nav | Left nav with #buttons, #badges, #cards etc. section links. | ✓ |

**User's choice:** Sidebar/anchor nav

---

| Option | Description | Selected |
|--------|-------------|----------|
| Rendered only | Visual inspection only. | |
| Rendered + templ call | Shows templ call used to produce each variant. | ✓ |

**User's choice:** Rendered + templ call

---

| Option | Description | Selected |
|--------|-------------|----------|
| Static HTML only | No JS. All variants pre-rendered. | ✓ |
| Simple variant toggles | JavaScript toggles for size/tone variants. | |

**User's choice:** Static HTML only

---

## Component API

| Option | Description | Selected |
|--------|-------------|----------|
| Keep existing variants only | DS-02 covered by current Variant+Tone. | |
| Add Ghost variant | Ghost explicitly listed in DS-02. Add ButtonVariantGhost. | ✓ |
| You decide | Claude maps DS-02 to existing surface, adds Ghost only if missing. | |

**User's choice:** Add Ghost variant

---

| Option | Description | Selected |
|--------|-------------|----------|
| Add BadgeVariantPrimary | Brand-colored badge variant. Matches DS-05 exactly. | ✓ |
| Keep existing | Info already maps to blue/brand. Primary can be added in Phase 14. | |
| You decide | Claude adds Primary if go-backend badge has it. | |

**User's choice:** Add BadgeVariantPrimary

---

| Option | Description | Selected |
|--------|-------------|----------|
| Fill CSS, leave Props unchanged | If a component compiles, don't touch the API. | |
| Align Props with go-backend | Review each component's Props against go-backend version. | ✓ |
| You decide | Claude extends Props only where DS requirement clearly needs a new prop. | |

**User's choice:** Align Props with go-backend

---

| Option | Description | Selected |
|--------|-------------|----------|
| Extend tests for all components | Each component gets at least a smoke test for class-generation logic. | ✓ |
| Catalog + regression only | Verify catalog route works and existing tests stay green. | |

**User's choice:** Extend tests for all components

---

## Claude's Discretion

- Exact CSS class naming: match go-backend class names exactly
- Order of anchor sections in catalog sidebar
- Exact fake-shell HTML structure in catalog
- Test coverage depth beyond the happy-path smoke test per component

## Deferred Ideas

- `app.css` shell port — deferred to Phases 14–17
- Wiring component CSS to CSS custom properties — deferred to Phases 14–17
- Dark mode tokens — future requirement DARK-01
- Responsive layout — future requirements RESP-01..03
