# Harmony Design System

Harmony is **Deltek's multi-product design system**, spanning four product themes —
**CP** (Costpoint), **VP** (Vantagepoint), **PPM** (Project & Portfolio Management, the
default), and **Maconomy** — each with coordinated **light and dark** modes. It is the
visual and interaction foundation for Deltek's enterprise project-management and
financial-operations products, used by AEC firms, government contractors, and
consulting organizations.

This project packages Harmony so a design agent can produce well-branded interfaces,
prototypes, slides, and assets without drifting from the real product.

---

## Sources

This design system was distilled from the following inputs (read-only from the agent's
perspective — don't assume a reader has access to them):

- **Codebase:** `harmony-designer-starter/` — Vite + React preview shell, vendored CSS
  tokens, icon manifest, full Cursor skills bundle. Specifically:
  - `harmony-designer-starter/harmony-styles/tokens.css` — canonical tokens for all 4
    themes × light/dark.
  - `harmony-designer-starter/harmony-styles/components.css` — ~7700 lines of
    component CSS.
  - `harmony-designer-starter/src/components/harmony/*` — ~40 React component sources
    (Button, Card, ShellLayout, ShellHeader, LeftSidebar, RightSidebar, Kanban,
    Table, Input, etc.).
  - `harmony-designer-starter/HARMONY_DESIGNER_HANDBOOK.md` — kit-level doc.
  - `harmony-designer-starter/icons/` — on-disk Tabler + custom SVG library.
- **Uploaded assets:** Dela AI brand marks (`RS_Dela_Active.svg`, `RS_DelaDefault.svg`,
  `DelaChat.svg`, `Dela D in dark circle 1.svg`, `DStar_LM.svg`, `Stars.svg`), the
  PPM product logo (`PPMLogo.svg`), the header avatar (`Header Avatar.svg`), and
  Figtree webfont CSS at weights 200/300/400/500/600/700 (regular + italics).

No Figma file was provided. The ground truth is the code.

---

## Products represented

Harmony is the shared skin for **four Deltek products**, toggled by a class on
`<html>`:

| Theme class       | Product                        | Primary colour  | Notes |
|-------------------|--------------------------------|-----------------|-------|
| `theme-ppm`       | Project & Portfolio Mgmt       | `#4C92D9` blue  | Default in this kit. Has a "Command Center" surface, risk/resource/portfolio tooling, and the Dela AI assistant built in. |
| `theme-cp`        | Costpoint                      | `#4C92D9` blue  | Adds a floating action nav (Save/Execute), a dense Kanban board, and CP-specific sidebar sections. |
| `theme-vp`        | Vantagepoint                   | `#4C92D9` blue  | Largely shares PPM layout; has VP-only documentation demos gated by `.ds-demo-only-theme-vp`. |
| `theme-maconomy`  | Maconomy                       | `#4C92D9` blue  | Shares the shell; very minor token-level differences. |

All four themes share the same **blue primary** (`#4C92D9` light / `#59ACFF` dark).
The differentiator is shell chrome, sidebar sections, and a few surface colors —
**not** brand hue. Layer `dark` alongside the theme class for dark mode
(e.g. `class="theme-ppm dark"`).

**Dela AI** is a cross-product feature, not a separate theme. It's the conversational
assistant that lives in the right sidebar of every product. Its signature
purple→indigo gradient (`#8A33C2 → #423FE2`) is the one place the brand escapes the
blue palette.

---

## Index — where to find things

| Path                              | Purpose |
|-----------------------------------|---------|
| **`README.md`**                   | This file. Content fundamentals, visual foundations, iconography. |
| **`SKILL.md`**                    | Skill manifest — also used by Claude Code as an Agent Skill. |
| **`colors_and_type.css`**         | Self-contained color + type tokens (PPM light default). Import this in throwaway HTML. |
| **`harmony-styles/`**             | Full vendored Harmony CSS (tokens, reset, layout, components, utilities). Import `global.css` for full multi-theme support. |
| **`harmony-data/icon-manifest.json`** | Per-theme icon map with inline SVGs. |
| **`assets/logos/`**               | Product + brand marks (PPMLogo, Dela, DStar, Stars, Header Avatar, etc.). |
| **`assets/icons/custom/`**        | Project-specific SVG icons (Risk Shield, Report, Resource, DelaChat, related, template, gantt-chart, Network Graph, etc.). |
| **`fonts/`**                      | Reference CSS for Figtree webfont weights. Fonts themselves load from Google Fonts. |
| **`preview/`**                    | Design-system card previews shown in the Design System tab. |
| **`ui_kits/ppm/`**                | PPM product UI kit (shell, command center, Dela panel, kanban). |
| **`harmony-designer-starter/`**   | (External, read-only) Original source of truth. |

---

## Content Fundamentals

Harmony is the skin over **enterprise project-management software** for finance,
project delivery, and resource planning. Voice, casing, and copy density all follow
from that.

### Voice & tone

- **Plainspoken, not salesy.** Copy names what a control does. Labels are nouns or
  imperative verbs, never promotional. Examples from the code:
  - Page titles: "Command Center", "Programs", "Portfolios", "Projects", "Resources",
    "Risk", "Reports", "Calendars", "Codes", "Rates", "Settings".
  - Buttons: "Primary" / "Secondary" (defaults), "Add Menu", "Execute", "Save",
    "Upload", "Download", "Share".
  - Tab defaults: "Home", "Projects", "Reports".
- **Second person, when it appears.** Microcopy addresses "you", not "the user".
  Example: the default Card body reads "This is where **your** application content
  lives. The shell provides the structure, and **you** provide the content."
- **No marketing adjectives.** There are no "powerful", "intelligent", "seamless"
  anywhere in the product surface. Dela AI is called "Dela AI", not "AI-powered
  insight engine".
- **Professional but warm.** The Dela assistant is named (a proper noun) and has its
  own gradient identity — the product is willing to personify its AI instead of
  hiding it behind "Assistant".

### Casing

- **Title Case for navigation and page titles.** "Command Center", "Dark Mode",
  "Resource Planning", "Dela AI". Every significant word capitalized.
- **Sentence case for body copy and descriptions.** "This is where your application
  content lives."
- **UPPERCASE** is reserved for the `overline` type style (10px, letter-spaced 0.08em).
  Don't otherwise shout.
- **Acronyms ship as-is.** "CP", "VP", "PPM", "API Schema", "MS Project".

### Density

Enterprise software. Expect **dense tables, dense sidebars, and tight cards**. The
app has a 52px sidebar with icon-only nav, a 56px header, and a 48px tab footer —
there's not a lot of slack. Cards sit on a ~16px padding grid and headings compress
hard (`--leading-tight: 1.25`).

### Emoji, symbols

- **No emoji** anywhere in the product copy, button labels, empty states, icon set,
  or toasts. Tabler icons carry the semantic weight. Don't introduce emoji.
- **Unicode symbols are not used as icons.** If it needs a glyph, it uses an SVG.
- The only pictorial accent is the **Dela "Stars" mark** (`Stars.svg`) — it appears on
  Dela-specific buttons and headers as a small flourish.

### Example microcopy in the product voice

> "Page Content Area"
> "This is where your application content lives. The shell provides the structure, and you provide the content."
> "Browse components"
> "Company name"
> "More options"
> "Settings"
> "Dark Mode"

Short. Declarative. No exclamation points. No "Welcome!".

---

## Visual Foundations

### Color

- **Blue-forward.** The primary accent across every product theme is the same mid-blue
  (`#4C92D9` light / `#59ACFF` dark). Harmony does NOT differentiate products by
  primary hue.
- **Cool neutrals.** Page background is a cool desaturated grey (`#E2E4E9`), cards sit
  a single step brighter (`#F7F8FA`), elevated surfaces go to pure white. Text neutrals
  skew cool too — `#373F4E` primary, `#525969` secondary. Dark mode drops to
  near-black `#15171A` with `#1F2124` cards.
- **Page-header CTAs go navy, not brand blue.** Primary actions in the
  `ShellPageHeader` use `#043852` (a deep navy) on a light card. Body-level CTAs use
  a different navy, `#2D5A9F`. This is deliberate — it makes the "save this page"
  action look heavier than any inline action.
- **Semantic colors are flat, not gradient.** Success `#17A871`, Warning `#FFB020`,
  Error `#D83148`, Info `#3366FF`. Used sparingly — chips get light-tinted
  backgrounds with matching dark text (`--chip-error-bg #ffecef` over
  `--chip-error-fg #c1253a`). No red buttons, no green callouts by default.
- **The one accent gradient is Dela's** (`#8A33C2 → #423FE2`). Reserved for the AI
  panel, the `btn--dela` button variant, and Dela section headers. Using this
  gradient anywhere else breaks the brand.
- **Company pickers are color-coded.** Each company/workspace in the header picker
  carries an indicator pill in one of a fixed palette (`#FF507B` Acme, `#285F8C`
  Ocean, `#DC50FF` Violet, `#5077FF` Azure, `#FFAF50` Sunset). Use those, don't
  invent new ones.

### Type

- **Three families, three roles.**
  - **Figtree** — body (`--font-sans`). Humanist sans. Weights 300–900 supported;
    400/500/600/700 cover 95% of UI needs.
  - **Lexend** — display (`--font-display`). Used on ALL headings h1–h6 via the
    reset. Tighter than Figtree — designed for reading speed.
  - **JetBrains Mono** — code (`--font-mono`). Only in `<code>`, `<pre>`, and explicit
    mono contexts.
- **Headings are tight, bold, and slightly negative-tracked.** `line-height: 1.25`,
  weight 700, letter-spacing: -0.01em. Lexend already optically adjusts, so don't
  pile on more tracking.
- **Body gets `line-height: 1.625`** (`--leading-relaxed`) — enterprise screens have
  long runs of copy and this keeps them scannable.
- **Size scale is rem-based 4-px grid**, 12/14/16/18/20/24/30/36/48/60px. Designs
  should pick rungs of this ladder, not arbitrary sizes.

### Backgrounds & texture

- **Flat. Cool. Unmodulated.** No hand-drawn illustrations in the product, no grain,
  no textures, no full-bleed photography. Backgrounds are single flat color tokens.
- **One gradient, used structurally:** the header gets a thin "company color" gradient
  strip (`linear-gradient(to right, {color}05, {color} 50%, {color}05)`) keyed off
  the selected company's indicator color. It's a hairline of brand energy, not a
  background fill.
- **No background images** are shipped in the product. If a kit needs full-bleed
  imagery (marketing pages, empty-state illustrations), the project will add them
  as a `<BrandImage>` placeholder — see `ui_kits/ppm/` for how we mark this.

### Spacing

- **4px base, 4/8/12/16/24/32/48/64 are the most-used rungs.** `--space-1..24`
  tokens; stick to them.
- **Shell geometry is fixed:** header 56px, left sidebar 52px (compact 44px), right
  sidebar matching, footer 48px (compact 40px). Main content sits on a 52px/side
  padding grid (32px on tablet, 16px on mobile).
- **Cards breathe at 16–24px.** Inner padding is typically `--space-4` to `--space-6`.

### Borders

- **Hairlines everywhere.** `--border-color: #BFC6D4` is the default; lighter
  `#E2E8F0` for subdivided rows. Width is 1px unless it's a focus ring.
- **Border-radius defaults to 8px (`--radius-08`, alias `--radius-lg`).** Buttons
  and cards share it. Tiny controls use 3–4px; pills use `--radius-full`.
- **No "rounded corner + colored left-border accent" pattern.** It doesn't appear
  anywhere in the real product — don't introduce it.

### Shadows & elevation

- **Two regimes: soft-everywhere (light) and deeper-but-black (dark).** Light mode
  uses slate-tinted shadows; dark mode uses black shadows at higher opacity. Both
  come in `sm / md / lg / xl / 2xl` rungs.
- **Elevated cards get `--shadow-sm`**, dropdowns `--shadow-dropdown`, modals
  `--shadow-xl`.
- **Pressed states use an inset shadow**, not a color change. `.btn:active` applies
  `--shadow-inset-sm` (or `-md` for primary) — a subtle darkening from inside.
  This is a fingerprint of the system.
- **Focus rings are two-ring:** a 3px halo in the accent color + a 1px card-bg outline.
  `--focus-ring-primary: 0 0 0 3px var(--theme-primary-light), 0 0 0 4px var(--card-bg);`

### Hover / press / focus language

- **Hover = darker, not lighter.** Primary buttons step from `#4C92D9` to `#3D7BC4`;
  secondary buttons get a tint background `#eaeff5`. Hover does not use opacity
  tricks.
- **Press = inset shadow + no position change.** Nothing translates, nothing scales.
  It's a flat design that signals press via elevation reversal.
- **Focus-visible = branded double ring** (see above). Focus is always highly
  visible — enterprise accessibility.
- **Links underline on hover**, never by default.

### Motion

- **150/200/300ms ease.** Three speeds — `--transition-fast` (hover flips),
  `--transition-base` (panels), `--transition-slow` (page transitions).
- **Fades and 2D position/size only.** No bounces, no springs, no 3D transforms,
  no scale-then-rotate. Enterprise restraint.
- **The company-picker menu, Dela panel, and dropdowns** are the main animated
  surfaces. They fade + small translate-Y.

### Transparency & blur

- **Transparency is for tints, not frosted glass.** Semantic colors have `-light`
  variants at 10% (e.g. `rgba(23, 168, 113, 0.1)`) used as chip backgrounds and
  hover states.
- **No `backdrop-filter: blur()` in the product.** If a modal overlay exists, it's
  a 50% black backdrop (`--overlay-backdrop-opacity: rgba(0, 0, 0, 0.5)`).

### Cards

- **Flat surface + 1px border OR faint shadow — never both heavy.** Default:
  `background: var(--card-bg)`, 8px radius, no border, `--shadow-sm` on
  `.card--elevated`. When cards need to group without elevation, they use
  `border: 1px solid var(--border-light)` and no shadow.
- **Header + body + optional footer structure.** Header can carry icon-buttons
  on the right (3 slots: close / more / settings).

### Layout rules

- **Fixed chrome, scrolling content.** Header, left sidebar, right sidebar, and
  footer are position-fixed; only the `<main>` scrolls.
- **`ShellPageHeader` first, button bar last.** Page structure is: shell →
  `ShellPageHeader` → content cards → (optional) button bar at the bottom of the
  scroll region. Rule enforced by `layout-composition.mdc`.
- **No Card-in-Card.** Nesting elevated cards is explicitly prohibited. Group
  with spacing or a divider instead.

---

## Iconography

Harmony uses **Tabler Icons (outline)** as its primary set, supplemented by **Heroicons
outline** (24px) fallbacks for shell-specific icons, and a library of custom project
SVGs for domain-specific concepts (Risk Shield, Resource, Report, DelaChat, etc.).

### Resolution path (how `<Icon name>` finds its SVG)

1. Look up `name` in `harmony-data/icon-manifest.json` — per-theme map of inline SVG
   strings. All 4 themes are merged at load time, so icons defined for CP resolve in
   PPM too.
2. Fall back to the Heroicons-outline dictionary inside `src/components/harmony/Icon.tsx`
   (user, chevron-down, x-mark, calendar, clock, etc. — ~40 icons).
3. If still unresolved, render a red "?" chip (`#ffecef` bg, `#c1253a` text, 2px
   radius). **That red chip is a real UI signal** — it means "you referenced an icon
   that isn't in this theme's manifest, fix it." Leave it visible during design.

### Sizes

`xs 12 · sm 16 · md 20 · lg 24 · xl 32`. Stroke width 1.5px (via `--icon-stroke-width`).
Icons inherit `currentColor`, so they recolor from their container.

### What's on disk

- **`assets/icons/custom/`** — custom SVGs copied into this project:
  Risk_Shield, Report, Resource, related, template, Contract, Calculator, DelaChat,
  gantt-chart, pin, Network_Graph, bullseye. Copy more out of the starter on demand.
- **Tabler outline** — not copied wholesale (thousands of files). The icon manifest
  inlines the ones the product actually uses. If you need a new Tabler icon, add its
  SVG inline or reference it by CDN:
  `https://unpkg.com/@tabler/icons@latest/icons/outline/<name>.svg`.

### Brand / logo marks

- **`PPMLogo.svg`** — the PPM product lock-up.
- **Dela suite** — `RS_DelaDefault.svg` (right-sidebar default), `RS_Dela_Active.svg`
  (active), `DelaChat.svg` (chat bubble mark), `Dela_D_Dark_Circle.svg` (standalone
  dark badge), `DStar_LM.svg` (wordmark with star), `Stars.svg` (the flourish used
  on `btn--dela`).
- **`Header_Avatar.svg`** — a default user avatar placeholder.

### Rules

- **Don't draw new icons.** If something's missing, copy from `harmony-designer-starter/icons/tabler/outline/` (in the starter) or link Tabler via CDN. Never
  hand-roll an SVG icon to "match" Tabler — the stroke weight and curves won't line
  up.
- **No emoji as icons. Ever.**
- **Dela's marks are not generic AI icons.** Don't use them for search, settings,
  or anything else. If you need a generic "AI" icon, use Tabler's `sparkles`.

---

## Substitutions & notes

- **Fonts are loaded from Google Fonts**, not from the uploaded weight CSS files.
  The uploaded `400.css`, `500.css`, etc. reference `./files/*.woff2` paths that
  weren't included. Google Fonts CDN gives us the same Figtree family at the same
  weights. **If you need offline/self-hosted fonts, re-upload the `files/` folder
  referenced by those CSS files and I'll switch to local.**
- **No Figma file was provided.** All component behavior is reverse-engineered from
  the React source. If Figma access opens up, we can tighten spacing/component
  geometry further.
- **Marketing pages, empty-state illustrations, and full-bleed imagery are not part
  of the product.** If you're designing those, ask the user for brand illustrations
  or we'll flag them as placeholders.
