# OpenSpec Spec: Web UI Consolidation & Polish — Modals, Cards, Breakpoints

## Change
`web-ui-spacing-typography-rework` — Pass 3: Consolidation & Polish

## Parent Proposal
`openspec/proposals/web-ui-spacing-typography-rework.md`

## Parent Specs
- `openspec/specs/web-ui-spacing-typography-rework.md`
- `openspec/specs/web-ui-spacing-typography-rework-pass2.md`

## Status
spec

---

## 1. Scope of This Spec

This spec covers **Pass 3 (Consolidation & Polish)** only:

- Unify the two modal/dialog systems (`.modal-*` and `.dialog-*`).
- Consolidate duplicated card patterns across page CSS files into `global.css` modifiers.
- Standardize responsive breakpoints to the existing token scale (`--bp-sm`, `--bp-md`, `--bp-lg`, `--bp-xl`).
- Add design-system documentation to `tokens.css`.
- Add a lightweight code-review checklist to prevent new inline `style={{...}}` layout declarations and undefined class names.

Out of scope for Pass 3:
- Token additions (Pass 1, done).
- Inline-style refactor in editor components (Pass 2, done).
- Behavior changes or new features.

---

## 2. Modal/Dialog Unification

### Current state

Two separate modal implementations exist:

1. `.dialog-overlay` + `.dialog` / `.dialog-lg` (rounded, centered, responsive)
2. `.modal-overlay` + `.modal-content` (older, square, fixed `min-width: 400px`)

Callers mix both:
- `.modal-overlay` / `.modal-content`: `WorkspacesPage`, `SessionsPage`, `workspace-tools-panel`, `merge-dialog`, `start-tool-modal`, `start-tool-fab`
- `.dialog-overlay` / `.dialog`: `instance-list`, `commit-dialog`, `ProjectDialog`, `repository-create-dialog`

### Target state

Deprecate `.modal-*` and make it a backward-compatible alias to `.dialog-*`.

```css
.modal-overlay {
  /* alias */
  composes: dialog-overlay; /* plain CSS fallback: duplicate the rule */
}

.modal-content {
  /* alias */
  composes: dialog; /* plain CSS fallback: duplicate the rule */
}
```

Because plain CSS does not support `composes`, the worker must:

1. Keep `.dialog-overlay` and `.dialog` as the canonical implementation.
2. Make `.modal-overlay` and `.modal-content` duplicate or wrap the same rules.
3. Migrate callers incrementally:
   - For components being touched anyway in this pass, replace `.modal-overlay` → `.dialog-overlay` and `.modal-content` → `.dialog`.
   - For components not being touched, leave the old class names; the aliases keep them working.

### Canonical dialog styles

Ensure `.dialog-overlay` and `.dialog` already in `global.css` cover:

```css
.dialog-overlay {
  position: fixed;
  inset: 0;
  z-index: 100;
  display: flex;
  align-items: center;
  justify-content: center;
  padding: var(--space-4);
  background: rgba(0, 0, 0, 0.45);
  backdrop-filter: blur(2px);
}

.dialog {
  width: 100%;
  max-width: 32rem;
  max-height: calc(100vh - var(--space-8));
  display: flex;
  flex-direction: column;
  overflow: hidden;
  background: var(--panel);
  border: 1px solid var(--border);
  border-radius: var(--radius-lg);
  box-shadow: var(--shadow-xl);
}

.dialog-lg {
  max-width: 48rem;
}

.dialog-header {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: var(--space-3);
  padding: var(--space-4);
  border-bottom: 1px solid var(--border);
}

.dialog-header h2,
.dialog-header h3 {
  margin: 0;
  font-size: var(--font-size-lg);
  line-height: var(--line-height-tight);
}

.dialog-body {
  flex: 1;
  overflow: auto;
  padding: var(--space-4);
}

.dialog-footer,
.dialog-actions {
  display: flex;
  align-items: center;
  justify-content: flex-end;
  gap: var(--space-3);
  padding: var(--space-4);
  border-top: 1px solid var(--border);
}

.dialog-close {
  display: flex;
  align-items: center;
  justify-content: center;
  width: var(--touch-target);
  height: var(--touch-target);
  padding: 0;
  background: transparent;
  border: none;
  border-radius: var(--radius-md);
  color: var(--muted);
  cursor: pointer;
}

.dialog-close:hover {
  background: var(--bg);
  color: var(--ink);
}
```

### Mobile dialog behavior

On viewports narrower than `--bp-md`:

```css
@media (max-width: 767px) {
  .dialog-overlay {
    align-items: flex-end;
    padding: 0;
  }

  .dialog {
    max-width: 100%;
    max-height: calc(100vh - var(--space-6));
    border-radius: var(--radius-lg) var(--radius-lg) 0 0;
  }
}
```

Note: this breakpoint will be standardized to `--bp-md` in §4.

---

## 3. Card Consolidation

### Current state

Each page CSS file redeclares card-like containers:

- `.repo-block`, `.workspace-chip`, `.instance-card`, `.settings-section`, `.project-card`, `.session-card`, `.config-profile-card`, etc.
- Common pattern: `background: var(--panel); border: 1px solid var(--border); border-radius: 10/12/14px;`.

### Target state

Consolidate into `global.css` card modifiers:

```css
.card {
  background: var(--panel);
  border: 1px solid var(--border);
  border-radius: var(--radius-md);
}

.card-sm {
  padding: var(--space-3);
}

.card-md {
  padding: var(--space-4);
}

.card-lg {
  padding: var(--space-5);
}

.card-elevated {
  box-shadow: var(--shadow-sm);
}

.card-borderless {
  border-color: transparent;
}
```

Then update page CSS files to:

1. Use `.card` / `.card-md` / `.card-lg` where the structure is generic.
2. Keep only page-specific layout (e.g. `.history-container` two-column grid, `.sessions-grid` column config).
3. Remove duplicate background/border/border-radius/padding declarations.

### Migration order

Start with the page files that have the most duplication:

1. `styles/pages/workspaces.css`
2. `styles/pages/sessions.css`
3. `styles/pages/ssh-keys.css`
4. `styles/pages/workspace-detail.css`
5. `styles/pages/projects.css` (if it has card-like patterns)
6. `styles/pages/git-history.css`

Leave `styles/pages/sessions.css` option-menu styles untouched; they are component-specific, not card patterns.

---

## 4. Breakpoint Standardization

### Current state

Breakpoints are inconsistent:

- `767px` (max-width)
- `768px` (min-width)
- `860px` (max-width, one-off in `.shell-body`)
- `1024px` (min-width)

The token scale already defines:

```css
--bp-sm: 480px;
--bp-md: 768px;
--bp-lg: 1024px;
--bp-xl: 1280px;
```

### Target state

1. Remove the `860px` one-off breakpoint.
2. Standardize all media queries to use `--bp-md` (`768px`) for mobile/desktop split.
3. Prefer mobile-first `min-width` queries for new/refactored rules.
4. For existing `max-width: 767px` rules, convert to `max-width: 767px` (equivalent to `--bp-md - 1px`) or refactor to mobile-first `min-width: 768px` where the logic is clearer.

Because CSS custom properties cannot be used directly in `@media` queries, document the pixel values in a comment and use the literal values `480px`, `768px`, `1024px`, `1280px`.

### Specific changes

- `global.css` line 554: remove `@media (max-width: 860px)` and make `.shell-body` collapse at `767px` only.
- `global.css` line 779: change `max-width: 768px` to `max-width: 767px` for consistency.
- Page CSS files: update any `767px`/`768px` queries to be consistent with the chosen direction.

### Recommended mobile-first pattern

For refactored rules, prefer:

```css
.my-component {
  /* mobile first */
  padding: var(--space-3);
}

@media (min-width: 768px) {
  .my-component {
    padding: var(--space-4);
  }
}
```

For existing rules that are desktop-first, keep `max-width: 767px` with a comment linking to `--bp-md`.

---

## 5. Token Documentation

Add a documentation block at the top of `apps/web/src/styles/tokens.css`:

```css
/*
 * Headquarter Design Tokens
 *
 * Naming convention:
 *   --space-*    : 4px-based spacing scale (1 = 4px, 2 = 8px, ...)
 *   --font-size-*: fluid type scale from xs to 2xl
 *   --radius-*   : border radius (sm/md/lg/xl/full)
 *   --shadow-*   : elevation shadows (sm/md/lg/xl)
 *   --line-height-*: text line heights
 *   --bp-*       : responsive breakpoints (use literal px in @media)
 *
 * Prefer these tokens over hardcoded px/rem values in all new CSS.
 */
```

---

## 6. Code Review Checklist

Add a lightweight markdown file at `docs/development/ui-review-checklist.md`:

```markdown
# UI Change Review Checklist

When changing styles or components in `apps/web/src`:

- [ ] New layout/spacing uses `--space-*` tokens, not hardcoded px/rem.
- [ ] New type sizes use `--font-size-*` tokens.
- [ ] New radii use `--radius-*` tokens.
- [ ] New shadows use `--shadow-*` tokens.
- [ ] No new inline `style={{...}}` blocks for static layout (computed values are OK).
- [ ] Interactive controls meet `min-height: var(--touch-target)`.
- [ ] `:focus-visible` states are visible and use `--brand`.
- [ ] Mobile layouts are tested down to 375px wide.
- [ ] New class names are defined in a stylesheet before being referenced.
- [ ] Breakpoints use the literal values from `tokens.css` (`480px`, `768px`, `1024px`, `1280px`).
```

---

## 7. Acceptance Criteria

- [ ] `.modal-overlay` and `.modal-content` are aliases/wrappers of `.dialog-overlay` and `.dialog`.
- [ ] At least two `.modal-*` callers are migrated to `.dialog-*`.
- [ ] Dialog mobile behavior (slide-up sheet) is implemented.
- [ ] `.card`, `.card-sm`, `.card-md`, `.card-lg`, `.card-elevated` exist in `global.css`.
- [ ] At least two page CSS files have duplicated card rules removed.
- [ ] The `860px` breakpoint is removed.
- [ ] All media queries use `480px`, `768px`, `1024px`, or `1280px` consistently.
- [ ] `tokens.css` has a documentation header.
- [ ] `docs/development/ui-review-checklist.md` exists.
- [ ] `npm run typecheck` passes in `apps/web`.
- [ ] `npm run lint` passes in `apps/web`.

---

## 8. Verification Plan

1. Run `cd apps/web && npm run typecheck`.
2. Run `cd apps/web && npm run lint`.
3. Search for `.modal-overlay` and `.modal-content` in `apps/web/src`; confirm they are aliases or have fewer direct callers.
4. Search for `860px`; confirm zero matches.
5. Search for card-like duplicated rules in page CSS; confirm reductions.
6. Open a dialog on desktop and mobile viewport and verify behavior.
7. Confirm `tokens.css` has documentation header.
8. Confirm `docs/development/ui-review-checklist.md` exists.

---

## 9. Next Phase

After this spec is approved, create **tasks** for Pass 3 implementation, then delegate to `sdd-apply`. After Pass 3 is complete, archive the OpenSpec change.
