fourge-portal/layout.md

# Fourge Portal Layout System

This is the single source of truth for dashboard/profile visual structure and UI geometry.

## 1) Global Frame
- Viewport app shell: `height: 100vh`, `overflow: hidden`
- Main content gutter: `24px` all sides
- Sidebar: `width: 76px`, `top: 24px`, `left: 24px`, `height: calc(100vh - 48px)`, `border-radius: 8px`
- Main wrapper offset from sidebar: `margin-left: 100px`
- Page rhythm unit: `24px` (header spacing, card gaps, section gaps)

## 2) Theme + Background
- Background ownership is `body` via `background: var(--bg)`.
- Dark base token `--bg` is full gradient:
  - radial glow + vertical dark gradient.
- Light base token `--bg` is full gradient:
  - gray radial glow + white vertical gradient.
- Do not use `html` theme-gradient scripting for Safari chrome behavior.

## 3) Tokens
- Accent: `#F5A523`
- Card bg dark: `rgba(255,255,255,0.02)`
- Card bg light: `rgba(0,0,0,0.02)`
- Sidebar/menu shell uses the same transparent card background token as cards
- Secondary card tone dark: `rgba(255,255,255,0.08)`
- Secondary card tone light: `rgba(0,0,0,0.08)`
- Border dark: `rgba(245,165,35,0.15)`
- Border light: `rgba(0,0,0,0.1)`
- Text primary dark/light: `#ffffff / #0d0d0d`
- Text secondary dark/light: `#a8a8a8 / rgba(0,0,0,0.6)`
- Text muted dark/light: `#666666 / rgba(0,0,0,0.38)`

## 4) Typography
- Font family: `Fourge`, then `-apple-system`, `BlinkMacSystemFont`, `'Segoe UI'`, `sans-serif`
- Base font size: `14px`
- Header title: `28px`, `500`, `line-height: 1.2`
- Header subtitle: `13px`
- Widget title: `11px`, `500`, uppercase, `letter-spacing: 0.8px`
- Section header (new standard): `18px`, `500`, Title Case, `letter-spacing: 0.2px`, `line-height: 1.1`
- Body table text: `12px/13px` by column importance

## 5) Card System
- Default widget shell:
  - `background: var(--card-bg)`
  - `border: 1px solid var(--border)`
  - `border-radius: 8px`
  - `padding: 18px 21px`
  - `backdrop-filter: blur(12px)` + `-webkit-backdrop-filter`
- Card width is not an intrinsic card token.
  - Width is owned by the page/grid/container the card lives in.
  - Cards should fill the slot provided by that page layout unless a page-level rule explicitly fixes a track.
- Compact card radius (legacy generic `.card`): `4px` (do not use for new dashboard widgets)

## 6) Header + Top Right Controls
- Site header: `padding-top: 24px`, `padding-bottom: 24px`
- Right control row:
  - Search icon button: `32x32`
  - Search button to theme toggle space: `7px` (`search-wrap margin-right`)
  - Theme toggle: `32x32`
  - Theme toggle to avatar: `14px` (`avatar-wrap margin-left`)
  - Avatar button: `49x49`, circle, `2px` inner ring + `2px` accent outline

## 6.5) Section Control Bars (Tabs + Actions)
- For page-level card controls (ex: Tasks/Projects, Finances tabs):
  - container uses: `display: flex`, `align-items: center`, `gap: 4`, `margin-bottom: 10`, `flex-shrink: 0`
  - **`margin-bottom: 10` is the site-wide standard gap between any tab/control bar and the card(s) below — use this everywhere, no exceptions**
  - tab bar row must always be `min-height: var(--btn-height)` so the gap to the card never shifts when action buttons appear/disappear
  - tabs stay on the left in source order
  - action buttons group sits on the right using: `margin-left: auto`, `display: flex`, `align-items: center`, `gap: 8`
  - do not use hardcoded spacer blocks (`width` filler divs) to force alignment
  - icon-only filter/action buttons share the same row and align vertically with add buttons
  - filter button wrapper: `<div style={{ position: 'relative', display: 'flex', alignItems: 'center' }}>` — `display: flex` prevents block stretching that misaligns the button vertically
  - filter button: `className="btn btn-outline"` + `style={{ display: 'inline-flex', alignItems: 'center', gap: 6 }}`, icon only (no label), funnel SVG `<path d="M2 4h12M4 8h8M6 12h4" />` at `13×13`; dropdown uses `site-header-avatar-menu` + `site-header-avatar-item` classes
  - when the control bar uses a multi-column grid (to align with split-card layouts below), add `align-items: center` to the grid and `min-height: var(--btn-height)` to every column so row height is stable across all tab states

## 7) Dashboard Grids (Team)
- Stat row: `grid-template-columns: 1fr 1fr 1fr 1.5fr`, `gap: 24`, `margin-bottom: 0`
- Row 2: `grid-template-columns: 1fr 1fr 280px`, `gap: 24`, `margin-top: 24`
  - Order: Recent Activity (left), Tasks In Progress (center), Calendar (right, fixed width)
- Row 3: `grid-template-columns: 1fr 1fr`, `gap: 24`, `margin-top: 24`
- Row 4 full-width: `margin-top: 24`

## 8) Stat Cards
- Card min height: `120px`
- Internal row gap: `21px`
- Label/value/sub spacing:
  - Label: `margin-bottom: 5px`
  - Value: `30px`, `400`, `letter-spacing: -0.5`, `line-height: 1.1`
  - Sub: `12px`, `margin-top: 5px`
- Icon badge: `27x27`, circle
- Icon glyph: `13x13`

## 9) Calendar
- Card uses widget shell
- Header-to-grid gap: `14px`
- Weekday label: `10px`, `600`, `letter-spacing: 0.5`
- Day cell button: `28x28`, circular
- Day number: `12px`
- Today style: bg `#F5A523`, text `#0d0d0d`, `700`
- Dots: up to 3, each `3x3`, gap `2`
- Popover:
  - Anchored left of cell: `right: calc(100% + 8px)`, vertical centered
  - `width: 210px`, `padding: 10px 12px`, `border-radius: 8px`
  - shadow `0 12px 32px rgba(0,0,0,0.45)`
  - row dot `6x6`, row text `12px`

## 10) Activity + Performance Rows
- Visible rows target: 5
- Row layout: `display:flex`, `align-items:center`, `gap:10px`
- Row spacing: `margin-top: 10px` from second row onward
- Name text: `13px`
- Meta/date text: `11px`
- Progress track: `height: 4px`, `radius: 2px`
- Percentage width slot: `min-width: 28px`
- Empty states in all cards (dashboard, profile, tasks, projects, file sharing, etc.):
  - any `No ...` message is centered in the card body (`display:flex`, `align-items:center`, `justify-content:center`)
  - use shared class treatment (`.card-empty-center`) for consistency
  - avoid top-offset-only placement for empty text

## 11) Tables
- General table layout in dashboard cards: `table-layout: fixed`, `border-collapse: collapse`
- Column widths are table-specific, not universal tokens.
  - Widths belong to the individual table/view that defines them.
  - Reuse widths only when the same table pattern is intentionally repeated.
- Header cells:
  - `font-size: 10px`, `font-weight: 500`, uppercase, `letter-spacing: 0.6px`
  - bottom spacing: `padding-bottom: 12px`
  - sticky behavior for scrollable tables:
    - table headers stay fixed while body scrolls
    - use shared sticky-head treatment for all app tables (`position: sticky; top: 0`)
  - table scrollbars are visually hidden for table scroll containers; wheel/trackpad scrolling remains active
- Body cells:
  - primary text: `13px`
  - secondary/metrics text: `12px`
  - row vertical spacing via cell padding: typically `5px`
- Hot Tasks column widths:
  - check `10%`, task `40%`, requested by `35%`, due by `15%`
- Client Highlight column widths:
  - icon `5%`, company `22%`, contact `23%`, projects `13%`, open `13%`, outstanding `12%`, paid `12%`
- Sorting rule:
  - Every visible data column header must be sortable.
  - Use clickable header controls (`SortTh`) with ascending/descending indicator.
  - Exclude only non-data utility/action columns (checkbox-only, icon-only status marker, action buttons).

## 12) Profile Page
- Container: full available content width, column, `gap: 24`
- Top row: `grid-template-columns: 60fr 40fr`, `gap: 24`
- At `<=1200px`: top row stacks to one column
- Main profile card uses widget shell
- Profile card width is determined by the profile page grid, not by the card itself.
- Internal card layout:
  - row `gap: 20px`
  - portrait max `140x140`, circle
  - portrait aligns flush in the row without extra wrapper padding/side space
  - detail grid `140px 1fr`, `row-gap: 8`, `column-gap: 12`, `margin-top: 14`
  - profile name/title: `18px`, `500`, `line-height: 1.2`
  - company subtitle: `13px`, secondary text
  - contact/detail rows: `13px`, primary text
  - social row `margin-top: 14`, `gap: 8`
  - company line under title is always visible; fallback display is `—` when no company is assigned
  - right-side meta labels (`Member Since`, `Role`) use widget-title sizing: `11px`, `500`, uppercase, `letter-spacing: 0.8px`
  - right-side meta values use body sizing: `13px`
  - self-only edit button: `position: absolute`, `top: 18px`, `right: 21px` (aligns to card padding), `border-radius: 8px` (matches card), `height: 22px`, `font-size: 12px`, `padding: 0 12px`
  - default outline button hover/focus fills with accent gold and uses dark text
- Right calendar card shows only tasks/events assigned to the viewed profile user
- Profile page left column includes a `Tasks In Progress` card above `Recent Activity`
- Profile `Tasks In Progress` follows the dashboard table/card pattern:
  - same widget shell and header treatment
  - same show-all behavior (5 visible by default)
  - profile-specific filter is tasks assigned to the viewed user with statuses `in_progress`, `on_hold`, or `client_review`
  - columns are `Task` and `Status`
- Profile activity feed action text pattern: `Task started`, `Task submitted`, `Task approved`, `Task rejected` (sentence title case)
- Activity feed includes:
  - actions performed by the viewed user
  - `Task approved` and `Task rejected` entries for tasks assigned to that viewed user (even if actioned by someone else)
## 12.5) File Sharing
- Main split: `grid-template-columns: minmax(0, 1fr) minmax(0, 3fr)` for an effective `25 / 75` layout, `gap: 24`
- Left stacked cards (`Pinned`, `Navigation`): `gap: 24`
- Canonical folder structure:
  - team and subcontractor profile folders live at `Team/<User Name>`
  - company folders live at `Clients/<Company Name>`
  - project folders live at `Clients/<Company Name>/Projects/<Project Name>`
  - every project auto-creates `00 Project Files`
  - task folders live at `Clients/<Company Name>/Projects/<Project Name>/<Task Name>`
  - every task auto-creates `Request Info`, `Working Files`, and `Old Books`
  - request submission files are copied into `Request Info/R00`, `R01`, and higher revision folders
  - renaming a team user, subcontractor user, company, project, or task must rename the matching filesystem folder
  - folder repair/backfill is additive only: create missing folders, leave existing folders untouched
  - request-info backfill must skip files that already exist and must not overwrite added working files or user-managed files
  - deleting a task in the portal moves its task folder into `Archive/Clients/<Company Name>/Projects/<Project Name>/<Task Name>` instead of deleting it
  - deleting a project in the portal moves its project folder into `Archive/Clients/<Company Name>/Projects/<Project Name>` instead of deleting it
  - orphan reconciliation may move folders into archive when they no longer map to portal records
  - orphan team folders move to `Archive/Team/<Folder Name>` when no team or subcontractor profile matches that folder name
  - orphan project folders move to `Archive/Clients/<Company Name>/Projects/<Project Name>` when no portal project matches that folder name under that company
  - orphan reconciliation does not remove company roots or overwrite archived content; it merge-moves into archive
- Access/home rules:
  - team members have full file access
  - client users with exactly one tied company use that company folder as home: `/Clients/<Company Name>`
  - client users tied to multiple companies use `/Clients` as home and only see company folders they are tied to
  - `/Clients` acts as a virtual parent for multi-company client users and must not expose unrelated company folders
  - subcontractor users use virtual home `/`
  - subcontractor virtual home shows `Team` plus only the project folders they are assigned to
  - subcontractor users skip all other root folders and must not see unrelated client or internal roots
  - subcontractor `Team` maps to the real shared `Team` folder
  - each subcontractor project folder is a virtual root that maps to the real client project path `/Clients/<Company>/Projects/<Project>`
- Right card header:
  - title label is `File Browser`
  - drag/drop note sits directly under the title and uses subtext sizing: `12px`
  - current file path uses the same `11px` uppercase label treatment as the title row family
  - toolbar does not show `+ Folder` or `Upload` buttons
  - upload happens by dragging and dropping files or folders into the right card
  - delete action uses the same geometry as the profile edit button (`top: 18px`, `right: 21px`, `8px` radius, `22px` height, `12px` text, `0 12px` padding) but uses danger styling with red hover/fill
- Right card table:
  - uses dashboard table styling (`table-layout: fixed`, transparent header row, `10px` uppercase headers, `13px/12px` body text)
  - card padding matches dashboard widget shell (`18px 21px`)
  - clickable text inside the table highlights in accent; rows do not use block hover fill
  - body cells are borderless like dashboard card tables
  - body cell padding matches dashboard tables exactly: `5px`
  - visible headers (`Name`, `Size`, `Modified`) use shared sortable header controls
  - file/folder icon footprint is compact so row height stays on the same cadence as dashboard tables
  - alternating rows use a very subtle theme-aware tint for scanability
- Navigation tree:
  - `Home` aligns to the first arrow column
  - connector line runs through the arrow center column
  - pinned folders are user-specific and must not be shared across users on the same device/browser session
  - hover is text-only accent color, no row fill

## 13) Radius + Geometry Rules
- Dashboard/profile widgets: `8px` radius
- Sidebar: `8px` radius
- Standard app buttons use the `Edit Profile` geometry:
  - geometry is tokenized globally in CSS vars and must be reused (no per-page hardcoded button geometry):
    - `--btn-height`
    - `--btn-padding-x`
    - `--btn-radius`
    - `--btn-font-size`
    - `--btn-font-weight`
    - `--btn-letter-spacing`
    - `--btn-line-height`
  - height: `22px`
  - horizontal padding: `0 12px`
  - border-radius: `8px`
  - font-size: `11px`
  - font-weight: `500`
  - letter-spacing: `0.8px`
  - text-transform: uppercase
  - line-height: `1`
  - label color follows theme text roles:
    - dark mode: primary button labels use dark text on accent fill; outline labels use primary text on transparent surface
    - light mode: outline labels use light-theme primary text; danger labels use danger text
  - outline button border uses the same `var(--border)` token as card outlines unless a button role explicitly overrides it
  - keep existing button role styling intact (`outline`, `primary`, `danger`); geometry changes, not role colors
- Inputs/dropdowns may use their own control radius unless a page-specific rule says otherwise
- Circular elements (avatar/day/icon badges): `50%`

## 14) Z-Index Stack
- Sidebar: `200`
- Header dropdowns/tooltips: `300`
- Calendar hover popover: `1002` within card context (`card can be 1001 active`)
- Modal overlay: `1200`

## 14.5) Loading Popup
- Use shared `PageLoader` component for loading overlays instead of page-specific popup implementations.
- Loading popups/overlays, including shared site-wide page loaders and file-sharing loading states, use the same widget shell as dashboard cards:
  - `background: var(--popup-bg)`
  - `border: 1px solid var(--border)`
  - `border-radius: 8px`
  - `padding: 18px 21px`
  - `backdrop-filter: blur(12px)` + `-webkit-backdrop-filter`
- Popup surface is theme-aware:
  - dark mode: deep translucent dark surface
  - light mode: bright translucent white surface
- Loading overlay scrim is theme-aware:
  - dark mode: `rgba(0,0,0,0.58)`
  - light mode: soft light scrim via `--overlay-scrim`
- Loading title uses widget header treatment: `11px`, `500`, uppercase, `letter-spacing: 0.8px`, secondary text
- Progress track:
  - height: `4px`
  - radius: `2px`
  - track color: secondary card tone (`var(--card-bg-2)`)
  - progress fill: accent
- Progress/meta text under the bar uses subtext sizing (`12px`) and secondary text

## 14.6) Modal Form Fields
- Modal forms that follow `Edit Profile` styling (including `Add Task`/`New Task`) share the same field typography and theme tokens:
  - modal surface transparency matches `Edit Profile` card shell (`background: var(--card-bg)`), not a denser popup-specific override
  - field labels: `11px`, `500`, uppercase, `letter-spacing: 0.8px`, color `var(--text-secondary)`
  - input/select text: `13px`, color `var(--text-primary)`, left aligned
  - textarea text: `13px`, color `var(--text-primary)`
  - field surfaces and borders use global theme tokens (`var(--card-bg-2)` + `var(--border)`) for dark/light parity
  - modal form action buttons use the standard outline geometry/style (`btn btn-outline`) unless a page explicitly defines a different role

## 14.7) Status Tags
- Shared status tags use `StatusBadge` (`.badge.badge-status`).
- Rule: any workflow/state value (`not_started`, `in_progress`, `on_hold`, `client_review`, `client_approved`, `invoiced`, `paid`, `active`, `completed`, etc.) must render through `StatusBadge` only.
- Do not use raw `span.badge badge-*` for statuses.
- Base badge geometry:
  - `display: inline-flex`
  - `align-items: center`
  - `gap: 4px`
  - `padding: 3px 10px`
  - `border-radius: 4px`
  - `font-size: 11px`
  - `font-weight: 400`
  - `letter-spacing: 0.3px`
  - `white-space: nowrap`
- Status badge geometry override (`.badge-status`):
  - `display: inline-flex`
  - `align-items: center`
  - `justify-content: center`
  - `min-width: 78px`
  - `height: 20px`
  - `padding: 0 8px`
  - `font-size: 10px`
  - `line-height: 1.05`
  - `box-sizing: border-box`
  - `padding-top: 1px` (optical vertical-centering correction for current font metrics)
- Status colors are variant classes (`.badge-not_started`, `.badge-in_progress`, etc.) and are theme-aware.
- Non-status chips (example: invoice line-item type `Initial`/`Revision`, or service-type labels) may use `.badge` variants directly.
- When a non-status chip should visually align with status pills, add `.badge-status` to match geometry.
- Exception: compact urgent tag (`.badge-needs_revision`) uses tighter geometry:
  - `min-width: 28px`
  - `padding: 3px 4px`
  - `border-radius: 4px`
  - fixed red treatment in both dark/light themes.

## 15) Motion
- Motion vars:
  - fast `160ms`
  - base `220ms`
  - easing `cubic-bezier(0.22, 1, 0.36, 1)`
- Dropdown animation: `ui-fade-up` from `translateY(4px)` + opacity 0 -> 1

## 17) Hover Interaction Contract
- Sidebar, header icon buttons, dropdown items, and avatar menu items must show a visible hover surface before click.
- Single hover source-of-truth block controls these elements.
- Dark hover surface baseline: `#1f1f1f`.
- Light hover surface baseline: `rgba(0,0,0,0.08)`.
- Nav icon opacity must lift from muted to full on hover (`opacity: 1`).
- Clickable text links use text-only highlight on hover/focus (`color: var(--accent)`), not whole-row/background fill.
- Hover and active must be visually distinct:
  - hover uses stronger temporary contrast (`bg` + thin border),
  - active remains persistent selected-state background.
- File Sharing left navigation exception:
  - `Pinned` + `Navigation` tree rows use text-only hover highlight (`color: var(--accent)`).
  - Do not apply row background fill for hover in this section.

## 17.5) Link Interaction Standard
- Use shared link classes only; do not hand-roll page-specific link hover styles:
  - table/text links inside cards and tables: `table-link`
  - inline action links/buttons in cards/feeds: `dashboard-inline-link`
- Hover behavior for both classes:
  - color changes to accent gold (`var(--accent)`)
  - no underline on hover/focus
  - cursor remains pointer
- For table-heavy rows where hit targets are tight, row hover may also promote link color to accent; still keep text-only link treatment (no full-row fill just for links).
- Do not rely on inline style color overrides for hover behavior; if a variant is needed, add/extend a shared class in `index.css`.

## 16) Non-Negotiable Implementation Rules
- Keep gradient backgrounds on `html`, not `body`
- Keep widget shell values (`18px 21px`, `8px`, blur 12, border token) consistent
- Maintain global `24px` spacing rhythm for page/frame/grid gaps
- Keep team dashboard card order:
  1. Open Tasks
  2. Active Projects
  3. Net Profit
  4. Revenue (wide)
- Keep row 2 order: Recent Activity (left), Tasks In Progress (center), Calendar (right fixed at `280px`)

## 18) Invoice Rules
- New work (`R00`) is billed at the new-service rate.
- Revision `R01` is free.
- Revisions `R02+` are billed incrementally: each uninvoiced revision entry contributes exactly `1x` revision charge.
- Previously invoiced revisions are excluded; later invoices only charge newly uninvoiced revisions (e.g. if `R02` was already invoiced, at `R04` only `R03` + `R04` are billed).