feat(web/ui): consolidate dialogs, cards, and breakpoints (Pass 3)
- Unify modal/dialog system; .modal-* are now aliases of .dialog-* - Migrate WorkspacesPage, start-tool-modal, merge-dialog, workspace-tools-panel to .dialog-* - Add .card-sm/.card-md/.card-lg/.card-elevated/.card-borderless modifiers - Apply card utilities across workspaces, projects, ssh-keys, workspace-detail, git-history - Remove duplicated card-like background/border/padding from page CSS - Remove 860px breakpoint; standardize on 767px/768px mobile split - Add docs/development/ui-review-checklist.md - Archive web-ui-spacing-typography-rework OpenSpec change
This commit is contained in:
Developer
+375
@@ -0,0 +1,375 @@
|
||||
# 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.
|
||||
+84
@@ -0,0 +1,84 @@
|
||||
# OpenSpec Tasks: Web UI Consolidation & Polish — Modals, Cards, Breakpoints
|
||||
|
||||
## Change
|
||||
`web-ui-spacing-typography-rework` — Pass 3: Consolidation & Polish
|
||||
|
||||
## Parent Spec
|
||||
`openspec/specs/web-ui-spacing-typography-rework-pass3.md`
|
||||
|
||||
## Status
|
||||
tasks
|
||||
|
||||
---
|
||||
|
||||
## Implementation Tasks
|
||||
|
||||
- [x] 1. Unify modal/dialog system in `apps/web/src/styles/global.css`
|
||||
- Ensure `.dialog-overlay`, `.dialog`, `.dialog-lg`, `.dialog-header`, `.dialog-body`, `.dialog-footer`, `.dialog-actions`, `.dialog-close` are canonical
|
||||
- Add `.modal-overlay` and `.modal-content` as aliases/wrappers
|
||||
- Add mobile dialog slide-up behavior at `767px`
|
||||
|
||||
- [x] 2. Migrate at least two `.modal-*` callers to `.dialog-*`
|
||||
- Candidates: `components/features/tool/start-tool-modal.tsx`, `components/features/workspace/workspace-tools-panel.tsx`, `components/features/git/merge-dialog.tsx`, `pages/WorkspacesPage.tsx`, `pages/SessionsPage.tsx`, `components/features/tool/start-tool-fab.tsx`
|
||||
|
||||
- [x] 3. Consolidate card patterns in `apps/web/src/styles/global.css`
|
||||
- `.card`, `.card-sm`, `.card-md`, `.card-lg`, `.card-elevated`, `.card-borderless`
|
||||
|
||||
- [x] 4. Remove duplicated card rules from page CSS files
|
||||
- `styles/pages/workspaces.css`
|
||||
- `styles/pages/sessions.css`
|
||||
- `styles/pages/ssh-keys.css`
|
||||
- `styles/pages/workspace-detail.css`
|
||||
- `styles/pages/projects.css`
|
||||
- `styles/pages/git-history.css`
|
||||
|
||||
- [x] 5. Standardize breakpoints
|
||||
- Remove `860px` breakpoint from `global.css`
|
||||
- Make `global.css` line 779 use `767px` instead of `768px`
|
||||
- Ensure all `@media` queries use `480px`, `767px`, `768px`, `1024px`, or `1280px`
|
||||
- Prefer mobile-first `min-width: 768px` for refactored rules
|
||||
|
||||
- [x] 6. Add token documentation header to `apps/web/src/styles/tokens.css`
|
||||
|
||||
- [x] 7. Create `docs/development/ui-review-checklist.md`
|
||||
|
||||
- [x] 8. Verification
|
||||
- Run `cd apps/web && npm run typecheck`
|
||||
- Run `cd apps/web && npm run lint`
|
||||
- Search for `860px` in `apps/web/src`; confirm zero matches
|
||||
- Search for `.modal-overlay` / `.modal-content`; confirm they are aliases or have fewer direct callers
|
||||
- Open a dialog on desktop and mobile viewport and verify behavior
|
||||
- Confirm `tokens.css` documentation header exists
|
||||
- Confirm `docs/development/ui-review-checklist.md` exists
|
||||
|
||||
- [x] 9. Update OpenSpec artifacts
|
||||
- Mark tasks in `openspec/tasks/web-ui-spacing-typography-rework-pass3.md` complete
|
||||
- Add final report note
|
||||
|
||||
- [x] 10. Archive OpenSpec change
|
||||
- Move `openspec/proposals/`, `openspec/specs/`, `openspec/tasks/` files for this change to `openspec/changes/archive/web-ui-spacing-typography-rework/` (or current archive structure)
|
||||
- Update `progress.md` if applicable
|
||||
|
||||
---
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- All tasks above are completed.
|
||||
- `npm run typecheck` passes.
|
||||
- `npm run lint` passes.
|
||||
- `.modal-overlay` and `.modal-content` are aliases/wrappers of `.dialog-*`.
|
||||
- At least two `.modal-*` callers migrated to `.dialog-*`.
|
||||
- `.card` family exists and is used by at least two page CSS files.
|
||||
- `860px` breakpoint removed.
|
||||
- `tokens.css` has documentation header.
|
||||
- `docs/development/ui-review-checklist.md` exists.
|
||||
- OpenSpec change archived.
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- Keep aliases for backward compatibility; do not delete `.modal-*` classes if other callers remain.
|
||||
- Do not change behavior of dialogs; only visual unification.
|
||||
- Do not remove page-specific layout grids; only remove duplicated card-like background/border/padding.
|
||||
- Prefer one commit per major area (modals, cards, breakpoints, docs).
|
||||
Reference in New Issue
Block a user