# Cost Volume Pro — Design System

A design system for **Deltek Cost Volume Pro (CVP)**, the proposal-development application used by government contractors to author, manage, and produce compliant cost-volume submissions (DoD, DoE, NASA, GSA, etc.). This document and the files alongside it capture the visual language, content rules, and component vocabulary used in the product so future designs feel native.

## What CVP is

CVP is an enterprise web app for **building, structuring, and submitting cost volumes** — the cost portion of a federal proposal. Customers build a hierarchical proposal (PBS / WBS / Tasks), assign resources, generate Basis of Estimate (BOE) narrative, run compliance checks, and export a final compliant document. The UI is grid-and-form-heavy, dense, multi-user, and permission-aware (access tags, roles, audit logs).

Surfaces include:

- **Cost Volumes list** — the main landing grid. Hierarchical (tree-data) ag-grid, hover-menu actions, right-rail summary.
- **Sections View** — visual document editor (header / sections / footer).
- **RAM** (Responsibility Assignment Matrix) — task × resource grid.
- **Sections List View** — flat list editor for content.
- **Compliance Report** — pass/fail checklist against requirements.
- **Settings drawer** — a top-anchored 80vw drawer with tabs for Notes, Header, Footer, Workflow, Section defaults.
- **Admin** — Roles, Users, Audit Logs, Access Tags, Active Sessions, Licensing, Settings, Document Templates, Classified Tags.
- **Libraries** — reusable images and text snippets.
- **Dashboards** — Home and System.

## Sources used to build this system

The system is grounded in a read-only codebase mount the user provided:

- `cvp-design-system/` — a slice of the production React/TypeScript codebase.
  - `@fuse/` — the Fuse React Admin template scaffolding (`FuseLayout`, `FusePageSimple`, color palettes `fuseDark`, `skyBlue`).
  - `app/configs/themesConfig.ts` — Material-UI theme definitions for ~30 light/dark variants. **`default` is the canonical light theme**.
  - `app/components/` — production components (badges, breadcrumbs, dialogs, menus, page chrome).
  - `app/main/apps/costVolumes/` — the Cost Volumes feature itself (list, sidebar widgets, settings drawer, operations).
  - `styles/*.css` — global CSS (`main.css`, `app-base.css`, `tables.css`, `matrix.css`, `print.css`, `prism.css`, `agGrid.css`).

No Figma or design files were attached. The visual recreations in this kit are reconstructed from code (themes, MUI defaults, Tailwind utility classes, inline `clsx` patterns) and **not** from production screenshots.

## Tech stack the system targets

- **React** + **TypeScript**
- **Material-UI v5** (MUI) — `@mui/material`, `@mui/styles`, `@mui/icons-material`
- **Tailwind CSS** — utility classes (`flex`, `px-16`, `text-16`, `rounded-8`, `font-bold`, `text-orange-400`, etc.). Note: in this codebase `text-16` means 16px, `px-16` is 1.6rem (because base font-size is set to 62.5% so 1rem = 10px). Heads up when porting.
- **ag-Grid** for data grids (with custom hover menus + cell renderers)
- **Material Icons** font (`<Icon>folder</Icon>` syntax) — the dominant icon vocabulary
- **clsx** for class composition
- **Fuse Admin template** layout primitives

---

## CONTENT FUNDAMENTALS

Copy in CVP is **terse, neutral, and procedural** — written for proposal managers and compliance leads, not consumers. There is no marketing tone in the product. Sentence-case for body, **Title Case for menu/button labels**.

### Voice

- **Third-person / imperative.** "Select a cost volume.", "Add Cost Volume", "Process Document". Never "you" or "we".
- **No personality**, no humor, no exclamation marks. The app is a work surface; the words stay out of the way.
- **Domain-correct vocabulary, used verbatim:** Cost Volume, Proposal, PBS, WBS, Task, Section, BOE (Basis of Estimate), RAM (Responsibility Assignment Matrix), Compliance, Workflow, Access Tag, Audit Log, Classified Tag, Template, Section Default. Capitalize these as proper nouns.
- **Acronyms stay in caps** (PBS, WBS, BOE, RAM, GSA). Don't expand them in UI; expand only in tooltips/help.

### Casing

- **UI labels & buttons:** Title Case. *Add Cost Volume*, *Sections View*, *Compliance Report*, *Quick Link*, *Selected Cost Volumes*.
- **Section / dashboard / nav headers:** SCREAMING CAPS — `MENU`, `DASHBOARDS`, `COST VOLUMES`, `LIBRARIES`, `ADMIN`, `HOME`, `SYSTEM`. (This is wired into the breadcrumb component itself via `!uppercase`.)
- **Table headers:** Title Case (`Created By`, `Last Modified`, `Last Access By`).
- **Status / inline text:** sentence case (`Select a cost volume.`).
- **Dialog titles:** Title Case (`Delete Cost Volume`, `Add Cost Volume From Template`).

### Microcopy patterns

- **Empty state:** one line, sentence case, period included. *"Select a cost volume."* placed under a 128px Material icon at low opacity.
- **Counts:** "Selected Cost Volumes: 4" — label, colon, value. Never "(4)" or "x4".
- **Confirm actions:** verb + entity. *"Delete Cost Volume"*, *"Restore Cost Volume"*, *"Copy Cost Volume"*. Disabled with tooltips like *"Select items to delete"* or *"Not allowed"*.
- **Permissions:** when an action is gated, the button stays visible but disabled with a tooltip explaining `Not allowed` rather than hiding.
- **Tooltips** are short noun phrases (*"Go to Sections View"*, *"Process Document"*, *"Compliance Checklist Report"*) — no full sentences.

### Emoji & decoration

**None.** Emoji never appear in product chrome. Iconography is exclusively Material Icons (the font set). If you need an "icon" inline, it's a Material Icon glyph, not an emoji.

### Example strings (verbatim from code)

> Add Cost Volume · Add Cost Volume From Template · See all · (default) · Delete · Restore · Process Document · Quick Link · Summary · Selected Cost Volumes: 4 · Select a cost volume. · Sections View · RAM · Sections List · Compliance Report · MENU · DASHBOARDS · COST VOLUMES · LIBRARIES · ADMIN

---

## VISUAL FOUNDATIONS

CVP's visual language is **utilitarian enterprise** — Fuse-template DNA tightened up with one electric-blue accent. Information density is high, decoration is minimal, and the workspace reads like a tool, not a marketing page.

### Color

- **Default theme is light.** Background paper `#FFFFFF`, background default `#f1f5f9` (Tailwind slate-100).
- **Primary is dark slate**, not blue: `#2D313C` main, `#0f172a` dark, `#64748b` light. Primary is used for the AppBar/header strip and contained primary buttons (the breadcrumb pills).
- **Secondary is sky blue**: `#05A2F3` (light theme) / `#1CA7FC` (a slightly lighter variant used in `.styledButtons` and the Sections-View collapse handle). The hyperlink color is `#05a6f0`. Treat these as a single "CVP blue" family.
- **Folder/file accents are warm orange** (`text-orange-400` = `#fb923c`) inside ag-grid rows. Used sparingly on tree-data folder icons.
- **Status colors are pastel** (Material 100s): BOE add `#c8e6c9`, BOE diff `#ffccbc`, BOE delete `#ffcdd2`. Errors: `#f44336` main, `#ffebee` background, `#BD362F` for matrix errors.
- **Notifications yellow:** `#ffc800` (sidebar "has notifications" icon). **Pulse green:** `#44b700` (StyledBadge online dot with a `ripple` keyframe animation).
- Dividers are `#e2e8f0` (light) or `rgba(241,245,249,.12)` (dark). Never solid 1px black.

### Typography

- **Font stack:** `'Inter var', Roboto, Helvetica Neue, Arial, sans-serif`. `font-feature-settings: "salt"` is enabled globally for Inter's alternate stylistic set.
- **Base size is 14px** body, 1.4 line-height. **`html` is set to `62.5%`** so 1rem = 10px and Tailwind `text-16` = 16px.
- **Heading scale (small):** h1 24, h2 20, h3 16, h4 15, h5 13, h6 12 — much tighter than marketing scales because this is a tool.
- **Weights used:** 400 regular, 500 medium (table heads, MUI buttons), 600 SemiBold (sidebar labels), 700 bold (selected-list headers).
- **Accent face:** `Montserrat 24/300` — appears once for the `.montserrat` decorative caption. Use sparingly.
- **No serif faces, no display faces, no monospace** in product chrome. Code blocks use Prism's default monospace.

### Spacing & layout

- Tailwind `px-N` / `pt-N` where N is in 0.1rem units (because of the 62.5% root). The codebase uses `px-16` (1.6rem = 16px), `pt-16`, `pb-24`, `mt-24`, `mx-8`, `p-12` — these are pixel-equivalents to 8/12/16/24px.
- Top toolbar height: **74px**. Header (sidebar header): **120px**. Fab buttons: **38×38**.
- Right rail width: **400px** (Cost Volume context rail). Persistent right sidebar with a `borderLeft: 1px divider`.
- Settings drawer takes **80vw**, centered, top-anchored, with **64px** offset from the app top.
- Grids fill viewport: `height: calc(100vh - 155px)`.

### Backgrounds

- **Solid colors only.** No gradients in production chrome (the one exception is a `linear-gradient(-45deg, #bebebe, lightgray, white)` shimmer on a single header-checkbox hover state, which is legacy).
- **No imagery, no hero photos, no textures, no patterns.** The product is purely composed of cards, grids, and chrome.
- Page default background is `#f1f5f9`; surfaces are `#FFFFFF` paper. Sidebar header is `primary.dark` (`#0f172a`).

### Shadows / elevation

- **Almost no shadows.** Cards use `shadow-none` (`Paper shadow="none"`) and rely on borders for separation. The only place a `box-shadow` is used heavily is the floating sidebar panel (`theme.shadows[5]`) and the StyledBadge ring `0 0 0 2px paper`.
- When elevation is needed, use the MUI shadow scale (1–5) sparingly. Prefer `1px solid theme.palette.divider`.

### Borders & radii

- **Default radius: 0 to 8px.** Cards: `rounded-8` (8px). Buttons/Fab: `25%` (corner-rounded squares, not pills). Breadcrumb buttons: `rounded-full` (pills) + `!uppercase`. Avatars / chips: MUI default (16px / pill).
- Hairline borders `1px solid #e2e8f0` mark sidebars, table rows, and cards.
- **Focus ring:** 1–2px outline in `#818285` (mid-grey). The `*:focus { outline: none }` is global, and components opt into `.focused` / `.focusedThick` explicitly.

### Hover & press states

- **Hover** is a subtle background tint:
  - Buttons/fabs: `rgba(0, 0, 0, 0.04)` background.
  - Table rows: `rgba(0, 0, 0, 0.03)` background.
  - Menu items: `rgba(255, 255, 255, .08)` on dark surfaces.
  - The custom `.styledButtons` class inverts on hover (`background-color: #fff; color: #1CA7FC; cursor: pointer`).
- **Active / press** doesn't get a special state — MUI defaults apply.
- **Disabled** uses `pointer-events: none; opacity: 0.9; user-select: none;` (see `.disabled`).

### Animation

- **Minimal.** Page-level transitions use MUI's defaults (`theme.transitions.create('margin', { easing: sharp, duration: leavingScreen })`) for sidebar slide.
- One bespoke keyframe: `@keyframes ripple` on `StyledBadge*` (online-dot pulse) — `scale(.8) opacity(1)` → `scale(2.4) opacity(0)` over **1.2s infinite ease-in-out**.
- ag-Grid `animateRows` is on. No bouncing, no spring physics, no scroll-jacking. The `body.no-animate` class disables all transitions globally for testing.

### Transparency & blur

- **No backdrop-filter blur, no glass effects.** Where translucency exists it's `rgba(0,0,0,0.04)` hovers or `rgba(149,156,169,0.4)` modal overlays. Drawer ModalProps include `disableEnforceFocus` to keep deep dialogs usable.

### Cards

- White paper, `rounded-8`, **no shadow**. Internal padding `pt-16 px-4 mx-8`. Section title is `text-16 font-bold`, left-aligned. Below the title, content is centered in widget cards (e.g. `Summary`, `Quick Link` in the right rail).
- Tables inside cards use `table.simple` (24px outer padding, 12px row padding, bottom border).

### Imagery

- The product has **no decorative imagery**. Logos and user avatars are the only raster assets.

### Iconography (see ICONOGRAPHY section)

- Material Icons font (`<Icon>folder</Icon>` syntax) drives 100% of UI icons.

---

## ICONOGRAPHY

CVP uses **Material Icons (filled)** for the entire product. There is no SVG icon set, no Lucide, no custom glyph library — the codebase ships `@mui/icons-material` and `<Icon>name</Icon>` (which renders the Material Icon font ligature).

**How it's used in code:**

```tsx
import { Icon } from '@mui/material';
import FolderIcon from '@mui/icons-material/Folder';
import ArrowForwardIosIcon from '@mui/icons-material/ArrowForwardIos';

<Icon>folder</Icon>
<Icon>library_books</Icon>
<Icon>account_tree</Icon>
<Icon>insert_drive_file</Icon>
<Icon>assignment_ind</Icon>
<Icon>list_alt</Icon>
<Icon>check</Icon>
<Icon>add</Icon>
<Icon>keyboard_arrow_right</Icon>
```

**Common icons actually used in the codebase:**

| Icon name | Where |
|---|---|
| `folder` | Tree-data row group icon (orange, text-orange-400) |
| `library_books` | Empty-state in right rail (128px, disabled color) |
| `add` | Add Cost Volume, Restore, breadcrumbs add menus |
| `delete` | Delete menu |
| `account_tree` | Quick Link → Sections View |
| `insert_drive_file` | Quick Link → Process Document |
| `assignment_ind` | Quick Link → RAM |
| `list_alt` | Quick Link → Sections List |
| `check` | Quick Link → Compliance Report |
| `keyboard_arrow_right` | Submenu indicator |
| `apps` | Menu root |
| `arrow_forward_ios` | Breadcrumb separator (16px) |
| `more_vert` / `more_horiz` | Hover menu triggers |

**Sizing:** icons inherit `font-size` from their parent. Common classes: `text-128` (empty-state hero icon), `iconSize` (20px utility), default 24px MUI button icon, `text-[16px]` for the breadcrumb separator.

**Emoji:** **never used** in product chrome. Don't introduce them in mocks.

**Unicode pseudo-icons:** none. Everything is a Material glyph.

**Asset format:** Material Icons is loaded as a **web font** via Google Fonts (`https://fonts.googleapis.com/icon?family=Material+Icons`). Mocks in this kit reference the same CDN — no PNG/SVG sprites are bundled.

**Brand logo:** No logo file was shipped in the codebase mount. We render a text-based wordmark (`Cost Volume Pro`) with the Deltek-style charcoal/blue palette as a placeholder. **If you have an official CVP/Deltek SVG logo, drop it into `assets/` and update the UI kit `BrandMark` component.**

---

## ⚠️ Caveats & known substitutions

- **Font:** No Inter font files were included in the codebase. We load **Inter** from Google Fonts (variable). Inter var is a paid font; the Google Fonts variable build is a near-identical free substitute and is what most teams use anyway.
- **Logo:** No CVP/Deltek logo asset was found. We render a wordmark placeholder. Please drop a real logo into `assets/logo.svg`.
- **Imagery:** the product ships no decorative imagery, so none was added.
- **No Figma source:** all recreations are from code. If a Figma library exists, attach it and the UI kit will be sharpened against it.

---

## Index — what's in this folder

- `README.md` — this file.
- `SKILL.md` — Agent Skill manifest, for use as a `claude-skill` in Claude Code.
- `colors_and_type.css` — CSS custom properties for the entire token system (raw + semantic).
- `fonts/` — webfont loaders (Inter, Material Icons).
- `assets/` — logos, brand marks, illustrations.
- `preview/` — Design System cards (one HTML file per token group / component cluster).
- `ui_kits/cost-volume-pro/` — interactive UI kit recreating the product:
  - `index.html` — clickable Cost Volumes list with right rail, breadcrumbs, hover menus.
  - `*.jsx` — component files (TopBar, Breadcrumbs, CostVolumesGrid, RightRail, ButtonTooltip, HoverMenu, etc.).

