|
| 1 | +# Workbench Layout Spec |
| 2 | + |
| 3 | +This document defines the layout contract for the workbench dashboard. The goal is to keep the dashboard visually stable, organized, and readable across desktop and narrow windows without treating the whole UI as a single scaled image. |
| 4 | + |
| 5 | +## Principles |
| 6 | + |
| 7 | +- Keep layout structure stable within each breakpoint. |
| 8 | +- Use shared layout tokens for spacing, card radius, card heights, and page width. |
| 9 | +- Change layout mode only at breakpoints; do not rewrite many component-level sizes inside a breakpoint. |
| 10 | +- Align cards only within the same visual row. |
| 11 | +- Prefer outer card stability with inner content scrolling on desktop. |
| 12 | +- Let narrow layouts use natural height instead of fixed card heights. |
| 13 | +- Cap the workbench content width on wide displays so the page does not stretch into sparse columns. |
| 14 | + |
| 15 | +## Layout Modes |
| 16 | + |
| 17 | +### Desktop: `min-width: 1121px` |
| 18 | + |
| 19 | +- Use a two-column dashboard: main content plus side rail. |
| 20 | +- Main and side columns use a stable `3fr / 1fr` relationship. |
| 21 | +- The full workbench content is capped by `--workbench-layout-max-width`. |
| 22 | +- Desktop placement is controlled by parent grid areas, not by two independent natural-height columns. |
| 23 | +- `main` and `aside` remain semantic wrappers, while their direct cards participate in the desktop parent grid. |
| 24 | +- The hero, overview metrics, recent panels, and smart recommendations stay in the main column. |
| 25 | +- Today stats, growth, active tags, and topic heat stay in the side rail. |
| 26 | +- Fixed card heights are allowed only for desktop row alignment. |
| 27 | + |
| 28 | +Desktop grid areas: |
| 29 | + |
| 30 | +```text |
| 31 | +hero stats |
| 32 | +hero growth |
| 33 | +overview growth |
| 34 | +recent tags |
| 35 | +smart topic |
| 36 | +``` |
| 37 | + |
| 38 | +### Tablet: `max-width: 1120px` |
| 39 | + |
| 40 | +- Collapse the workbench into one main column. |
| 41 | +- Move the side rail below the main content. |
| 42 | +- Side cards may use a two-column grid. |
| 43 | +- Topic heat and active tags can span the full width when their content benefits from room. |
| 44 | +- Fixed desktop row heights are disabled. |
| 45 | + |
| 46 | +### Compact: `max-width: 900px` |
| 47 | + |
| 48 | +- Use a single-column flow. |
| 49 | +- Recent panels stack vertically. |
| 50 | +- Smart recommendations stack internally. |
| 51 | +- Side cards stack vertically. |
| 52 | +- Cards use natural height. |
| 53 | + |
| 54 | +### Small: `max-width: 620px` |
| 55 | + |
| 56 | +- Metrics become single-column. |
| 57 | +- Action buttons can become full width. |
| 58 | +- Time labels can be hidden in dense feed rows. |
| 59 | + |
| 60 | +## Row Alignment |
| 61 | + |
| 62 | +Desktop row alignment is limited to these groups: |
| 63 | + |
| 64 | +- Recent activity, recent questions, and active tags use `--workbench-feed-card-height`. |
| 65 | +- Smart recommendations and topic heat use `--workbench-recommendation-card-height`. |
| 66 | + |
| 67 | +Other cards keep natural height. This avoids unnecessary internal scrollbars and prevents unrelated modules from forcing each other into awkward dimensions. |
| 68 | + |
| 69 | +## Token Ownership |
| 70 | + |
| 71 | +Workbench layout tokens live on `.workbench-dashboard`: |
| 72 | + |
| 73 | +- `--workbench-layout-max-width` |
| 74 | +- `--workbench-page-padding` |
| 75 | +- `--workbench-gap` |
| 76 | +- `--workbench-card-radius` |
| 77 | +- `--workbench-sidebar-min` |
| 78 | +- `--workbench-hero-min-height` |
| 79 | +- `--workbench-feed-card-height` |
| 80 | +- `--workbench-recommendation-card-height` |
| 81 | +- `--workbench-panel-header-padding` |
| 82 | +- `--workbench-panel-body-padding` |
| 83 | + |
| 84 | +Breakpoints should adjust these tokens first. Component-level overrides should be reserved for true layout-mode changes, such as switching from two columns to one column. |
0 commit comments