diff --git a/.trellis/spec/hyb-oa/frontend-react-vite-design.md b/.trellis/spec/hyb-oa/frontend-react-vite-design.md index f2a29977..0c8c9470 100644 --- a/.trellis/spec/hyb-oa/frontend-react-vite-design.md +++ b/.trellis/spec/hyb-oa/frontend-react-vite-design.md @@ -12,6 +12,75 @@ This spec keeps hyb-oa-specific React/Vite, shared-component, business-boundary and verification contracts. Do not copy broad aesthetic guidance from `frontend-design` into this file; use the skill directly for design judgment. +## Scenario: PC Shell And Detail Breakpoint Coordination + +### 1. Scope / Trigger + +- Trigger: changing the desktop sidebar, app-shell content offset, topbar drawer entry, detail two-column grid or sticky detail action panel. +- Purpose: prevent the shell and detail workspace from expanding at the same narrow breakpoint and leaving the business main column unusably small. + +### 2. Signatures + +- Fixed sidebar: `.app-shell-sidebar` uses `xl:flex`. +- Main content offset: `.app-shell-main` uses `xl:ml-72` outside mobile routes. +- Topbar drawer trigger: `aria-label="打开菜单"` uses `xl:hidden`. +- Detail workspace and action panel remain `lg:grid-cols-*` and `lg:sticky` unless a later task changes the complete contract. + +### 3. Contracts + +- Sidebar visibility, main-content offset and drawer-trigger visibility switch at one shared breakpoint; never change only one of the three. +- Evaluate detail widths after subtracting the fixed sidebar and page padding, not as a fraction of the full viewport. +- At the narrowest viewport where the fixed sidebar appears, the main detail column is at least `560px`, the action column is at least `280px`, and the document has no horizontal overflow beyond a `2px` rendering tolerance. +- Business identifiers and normal company-time date strings use DOM line-count or geometry assertions; `position: sticky` alone is not proof that the layout is usable. +- A Playwright spec writes screenshots only to its own current output directory. Never reuse an archived Trellis task's evidence directory as a live test target. + +### 4. Validation & Error Matrix + +- Fixed sidebar visible while drawer trigger is also visible -> breakpoint contract failure. +- Main content has the sidebar offset while the sidebar is hidden -> breakpoint contract failure. +- Two columns exist but either column is below its minimum width -> layout failure, even if sticky CSS passes. +- `documentElement.scrollWidth > clientWidth + 2` -> horizontal-overflow failure. +- A routine test run modifies screenshots under another task's evidence directory -> output-contract failure; move the writer before regenerating any evidence. + +### 5. Good/Base/Bad Cases + +- Good: `1100px` uses the topbar drawer and keeps the detail grid; `1280px` shows the fixed sidebar and still meets both column-width thresholds. +- Base: mobile routes continue to use their existing mobile shell and sticky bottom actions. +- Bad: move the detail grid from `xl` to `lg` while leaving the 288px app sidebar and content offset at `lg`, then validate only `position: sticky`. + +### 6. Tests Required + +- A source-structure contract asserts the three shell classes use `xl`, while the shared detail grid and action panel retain `lg`. +- A focused Playwright regression at `1280px` measures both detail columns, horizontal overflow and representative identifier/date line counts using realistic-length fixtures. +- At least one synthetic workflow detail and one asset detail cover the shared layout; existing mobile regression remains green. +- After screenshot-producing tests, assert archived task evidence remains clean in `git status`; current-suite screenshots may be retained only under that suite's own output directory. + +### 7. Wrong vs Correct + +#### Wrong + +```tsx +