The wordmark is the only place where the V is rendered as a custom SVG brand mark instead of a typeset letter. By styling the V as a refined wider-stance geometry inline with "ecreal" typeset in Inter Semibold, the wordmark reads as one continuous word while the V and dot both function as brand-color anchors. The result: a distinctive but quiet brand presence — not a logo bolted onto text, but a typographic system where the brand color appears at two points (V at the start, dot at the end) in a way that reinforces "this is a wordmark" rather than "this is decoration around a name."

Clay Light (#A05847) is the locked accent for white surfaces — warm and lifted, retaining construction-materials earthiness without the heaviness of deeper Clay variants. Clay Bright (#C68070) on dark surfaces preserves legibility while keeping the same warmth. Clay Dark (#7A3D32) stays in the palette as a deeper accent for high-emphasis brand moments only — it's not the default.

Refinement of exact letterform proportions and kerning belongs to a real designer pass for v1+. The current geometry holds at every locked size (96 to 18px) and works in both light and dark themes via a single token swap.

One mark, two presentations. The monogram is the tight context expression — favicon, mobile, app icon, social avatar — where space won't fit the wordmark. The wordmark is the full presence expression — marketing surfaces, document headers, dashboard branding — where Vecreal needs to be named explicitly.

The V geometry, dot color, and dot proportion (∼32% of V height) are shared by reference: the monogram uses the same SVG path as the wordmark's .bk-v. Update the path in one place and both surfaces inherit the change.

Selection rule: use the wordmark whenever there is room for it to read at ≥ 18px. Below that — or in dense UI contexts where text would compete — use the monogram.

Warm near-blacks and warm near-whites instead of cool blue-grays. Construction is a tactile industry — concrete, wood, drywall, steel. The palette grounds the brand in those materials without literally referencing them.

Clay is the singular brand accent. Used sparingly on the wordmark, citations, references, and key chrome moments. The semantic palette (success, warning, error, info) handles functional UI state, distinct from the brand. This separation is intentional — clay is a brand mark, not a status indicator.

Backgrounds are mostly white with subtle warmth (#FAFAF8) rather than pure white. Production tool, not editorial publication.

Two families, no exceptions. Inter for narrative content (headings, body, UI labels), JetBrains Mono for technical metadata (citations, IDs, timestamps, code). This split makes the technical layer visually distinct without needing a color or weight cue — the typeface itself signals "this is data, not prose."

Both fonts are free, well-supported, and load quickly via Google Fonts. Inter is the de-facto standard for B2B SaaS (Stripe, Linear, Vercel, Notion); JetBrains Mono is widely respected in technical contexts. Choosing them prioritizes familiarity and craft over novelty.

Letter-spacing tightens at display sizes (-0.03em) and loosens at mono (+0.04em) — an old typographic rule that keeps each context comfortable to read.

Tokens are the system's contract with engineering. Every spacing, radius, duration, and shadow value lives in :root as a CSS variable; components consume var(--token). A future repaint of, say, "all 8px gaps to 6px" is a single-line change.

The 4px base (with a 2px hairline at sp-1) snaps everything to a clean rhythm. Stripe, Linear, and Atlassian Polaris all use this scale — it's the de-facto standard for B2B density.

Motion is intentionally restrained: 4 durations, 2 easings. No bounce. Vecreal is professional infrastructure, not a consumer app.

Stroke-based on a 14×14 viewBox. The 1.4 stroke-width reads consistent across all sizes (14, 16, 18, 20px) without requiring optical adjustments per size. Single-layer paths keep the SVG output small enough that inlining 42 icons doesn't bloat HTML.

Lucide / Tabler / Phosphor are the reference set — clean geometric shapes, calm visual presence. The first 42 cover navigation, status, action, communication, file, and time. The library grows as new product surfaces require it — we don't pre-build icons for use cases that haven't shipped yet.

Color inheritance via currentColor means engineering can drop an icon next to any text and have it adopt the surrounding color — no per-icon variants required.

Reference set: Linear, Vercel Dashboard, Stripe. These products are the gold standard for B2B power tools — tight density, high-contrast borders, restrained accent, mono prominent in metadata. The look telegraphs "this is professional infrastructure" without needing to say it.

Sharp radii (4–6px) keep the surface feeling precise. Soft pillowy 12–16px radii read as consumer; we're building for the operator. Black primary CTA keeps the visual hierarchy on actions, not on the brand — clay stays the brand moment.

This direction is the locked default. Section 16 below shows it applied to both dark and light surfaces with the same component vocabulary.

Two streams is the operating principle: dark sidebar always as the brand anchor, with the main canvas swapping between dark and light depending on theme. The dark sidebar carries Vecreal's identity across both themes — it's the consistent visual moment regardless of which theme the user prefers for their main canvas.

This baseline merges the strongest elements of two earlier explorations: V1's surface depth (clear card boundaries, off-white #f7f8f8 text on dark) and V3's power density (16px card padding, 8px radii, tight component spacing). V2 (editorial) was rejected and archived.

Component refinements applied (Direction A): status-dot eyebrow + colored label + muted type, chevron-prefixed reference pills, 70px confidence track with paired "HIGH · 0.86", priority-coded action rows, outline sidebar icons + count badges, live indicator in topbar.

Section 21 is the canonical component catalog — the locked base patterns. Subsequent sections (24, 25, 26, 27, 28) extend these baselines with additional variants and use cases.

Every component shown on both dark and light surfaces. The locked styling applied here is what every product surface composes from. New surfaces must compose existing components; new components require an explicit catalog update.

This catalog plus Sections 22 (Foundations) and 23 (Iconography) form the "raw material" layer. Everything in the product is built from this vocabulary.

The button system extends the locked Section 21.1 base with six common B2B patterns. Each pattern fits a specific role: segmented for view toggles, split for "primary + variants," badge for "count of pending," loading-success for action confirmation, inline chips for AI/cited content actions.

Black solid for the primary CTA, not clay. This keeps the visual hierarchy on actions and the brand on chrome. Clay is reserved for moments where Vecreal is identifying itself (wordmark, citations, sources) — never on the action surface.

The icon-in-CTA rule (clay-bright icon + soft white text on dark primary) is the one place clay appears on an action. It's a deliberate brand moment within the action layer.

Forms are the spine of any data-entry surface (RFI/submittal creation, settings, filters, drafts). The library covers every common control with locked sizing, focus state, and error patterns — so PMs experience consistent affordances across every form they touch.

Focus state uses a 3px clay-tinted ring at 18% opacity. Heavier than the button focus ring (2px / 45%) because forms are read more carefully — the ring needs to clearly mark which field has focus when the user is mid-flow.

Validation on blur, errors inline. Validating on every keystroke creates noisy UX during normal typing. Inline errors keep the user in context vs. a toast that requires re-reading.

Construction data is dense — RFI logs run hundreds of rows, cost rolls span 20+ columns. The table system has to handle that density without becoming an eye chart. Mono header + sans body + right-aligned numbers + 1px row dividers do most of that work.

Sticky header on scroll. Users lose context fast in long tables — the column headers must stay visible while scrolling row 200 of 800.

Filter pills are outlined clay (not filled). Filled clay would over-color the surface; outlined keeps the table dominant while still showing "you have filters applied."

One surface treatment, five internal structures. The shared treatment (gradient + inset highlight + soft shadow + 7px radius + 16px padding) keeps cards visually cohesive across the dashboard. The internal structure tells the user what kind of action the card affords.

Action ends with a CTA. Stat is a metric + trend. Info is passive disclosure (no action). Link is fully clickable with chevron. Summary is bullet content + secondary actions. Pick by intent, not by visual preference.

Two tab styles for two purposes. Underline tabs filter within a single surface (Open / In review / Closed) — the underline is light, the data persists. Filled segmented tabs toggle between view modes (List / Kanban / Timeline) — visually heavier because they swap the entire surface.

Breadcrumbs use chevron separators with current location bolder. Pagination uses clay-tinted background on the active page and ellipses for skipped ranges. The page numbers are mono so widths align.

Five overlay patterns covering the full disclosure spectrum: modal (focused decision), popover (inline source disclosure), tooltip (brief hint), dropdown (selectable menu), context menu (right-click). Each has a distinct role and rules — mixing them collapses the affordance vocabulary.

The modal gets two new affordances: a hyperlinked title (jumps to the full source/route) and a full-screen expand button (opens the modal contents as a dedicated route). This matches Linear and Stripe modal patterns.

Source citation popovers are the Vecreal-specific pattern — clicking an inline citation opens a popover with the verbatim source text. This is what makes "show your work" visible at the surface level.

Avatars show initials only, no photos, no presence indicators. Vecreal is a passive synthesis tool, not a collaboration space — we don't track presence and we don't collect user photos. The avatar marks who something is attributed to (assignee, RFI author, document uploader) without performing presence theater.

Avatar groups stack with z-index layering + 2px surface-colored ring around each circle so the overlap is visible without colors bleeding through. Stack max 4 visible; show +N for the rest.

Chips have three roles: filter (selected/unselected toggle), removable (dismissable filter pill), assignee picker (with embedded avatar). Their visual differences signal their behavior.

Search spans every project source: RFIs, drawings, emails, meetings, submittals, COs, photos. Results group by source type so the user immediately sees "3 RFIs match, 1 drawing matches" rather than a flat unsorted list.

Match highlighting uses amber, not clay. Clay is brand; amber is functional ephemeral highlighting that disappears once the user has read the result. Mixing the two would confuse the brand semantic.

Recent searches surface below results so the PM can jump back to a prior query — investigation flows often loop. Footer shows the total searchable corpus so the user knows the search scope.

Time is shown three ways depending on context. Relative prose ("14 minutes ago") for human-friendly contexts where the user just needs to know roughly when. Compact mono ("14m ago") for chrome and tables where space is tight and density matters. Absolute formal ("April 30, 2026 · 14:23 EST") for audit trails and citations where exact time is the record.

Aging colors signal urgency without requiring a separate badge: green for fresh, neutral for older, amber for aging, red for overdue. The color encoding lets the user scan a column of dates and see priority instantly.

Multi-step flows fall into two visual patterns. Horizontal stepper when steps are discrete and named (Connect → Index → Sync → Generate) — the user sees the whole journey upfront. Linear progress wizard when steps are sequential but the count or names matter less — just "Step 3 of 7, 42% complete."

Both share the same color logic for state: green check for done, clay-tinted ring for active, neutral number for pending. Consistent semantics across variants prevent confusion when a flow uses both within a deeper subprocess.

File patterns are the spine of Document Library, Drawings, Submittal Log, and Photo Gallery surfaces. Folder rows are minimal: name + count + chevron. File rows are tabular with consistent metadata columns: type icon + name + extension + size + modified + owner + actions menu.

Mono everywhere there are numerics or codes — size, date, type extension — so columns align cleanly even across row sizes. The kebab/ellipsis menu uses the dropdown overlay pattern from Section 25.

Three feedback patterns: toasts (transient, low-stakes), banners (persistent, requires attention), inline validation (field-level, contextual). They have distinct lifecycles and shouldn't be interchangeable.

Sync failures use the global banner level (top of surface) rather than per-component error states — one banner explains "Procore sync paused" once, instead of every card showing a stale-data warning.

Toasts auto-dismiss in 5s. Banners persist until the user dismisses or the underlying state resolves.

Notifications surface async events: a teammate left a comment, a sync completed, a draft is ready for review. The bell + badge in the topbar is the persistent affordance; the panel opens as a popover-style surface with grouped, scannable list rows.

Unread items get a subtle clay-tinted background + bold title + leading dot. Read items fade to neutral. Mark-all-read clears the visual emphasis but keeps history accessible — we never delete notification history without explicit user action.

An empty state is not a single thing. First-time empty (zero state) is hopeful — the system has never had data, the user just arrived. The copy explains what the surface is for and offers a path to first value. No-data-yet is a steady-state — sources are connected, the system is watching, but nothing has triggered yet. The copy reassures the user that the system is working. Filtered-to-nothing is a recovery scenario — the user has narrowed too far. The copy points back to clearing filters.

Microcopy carries most of the weight. The first-time state is the one place we use a soft brand moment (the small clay V badge in the icon). Variants B and C use neutral stroke icons — they're recurring states, not landing moments.

Construction PMs use these surfaces under time pressure on real projects. Empty states must answer two questions instantly: why is this empty, and what do I do next?

Each error has a different recovery path. 404 is "the thing you asked for isn't here" — the user navigates back. 500 is "our side broke" — the user retries or works in the source system. Network failure is "the connection is the problem" — the user waits or moves to offline-capable tools.

Microcopy is calm and specific. We own the failure ("on our side") rather than apologize. We tell the user what failed, when we last had good data, and how to keep working. Construction PMs don't have time for "Oops!"

The network-failure pattern has two presentations. Inline banner when partial data is still usable (showing last sync, allowing actions to queue). Full-page when nothing useful is reachable. Choose by severity, not by aesthetic preference.

Coordination layer principle in error UX: when Vecreal fails, the user's data is still in Procore / BIM 360 / their email. Every error variant offers a fallback to the source system — the user doesn't lose access to their own data when our layer hiccups.

Three loading contexts, three visual treatments. Skeleton when the surface has rendered but data is in flight — the user sees layout-as-placeholder so the eventual content has no jarring shift. Full-page boot only for cold app start — the only place we surface the wordmark in a loading context (it's the "Vecreal is starting" brand moment). Initial data loading shows named steps because the user just connected sources and wants to see specifically what's happening ("indexed 1,247 documents").

Skeletons mirror the final layout precisely — widths, heights, gaps. This is what makes the transition from skeleton to content feel cohesive instead of jarring. A generic gray rectangle skeleton is decoration; a skeleton that matches the eventual stat-card grid is preparation.

No spinners. The streaming-dot pattern from Section 26 covers cases where work is happening; the named-step pattern in Variant C covers progress. Spinners say "something is loading" without saying what — we always say what.

The toolbar replaces the filter bar (vs. floating below it or appearing as a separate strip) because the user is now in "act on these" mode, not "refine these" mode. One control surface at a time keeps the visual hierarchy clear.

Clay-soft background with a clay border makes the toolbar feel like an active brand moment without overpowering the table. The selected count badge in solid clay anchors the user's attention. Action buttons stay neutral (secondary style) because the brand emphasis is on selection, not on each individual action.

Destructive actions (Dismiss, Delete) are grouped to the right with a separator and use the error color in outline form — not filled, because filled red competes too aggressively with the selection-clay focus.

Filter pills (Section 30) are the lightweight path: one or two filters, applied directly. The drawer is the heavy path: many filters, multiple categories, custom date range. They're complementary — the user picks the affordance that matches their intent.

The live count subtitle ("3 active · affects 142 rows") is the most important detail. It updates as the user toggles filters so the consequence is visible before they Apply. No commit-then-discover.

Filters do not auto-apply on every change. The user composes their filter set, sees the count update, then Apply commits. This is how Stripe, Linear, and Notion handle filter drawers — consistent with B2B power-tool conventions.

Three DnD contexts, three visual languages. File drop is the simplest — idle dashed border becomes clay dashed border on dragenter. Reorder needs a grip handle (so user knows which element is draggable) and a clear drop indicator line. Kanban uses the entire column as the drop target with clay-soft tinting and a clay header label.

The ghost (the floating dragged element) gets a slight rotation (-0.5 to -1 degree) and shadow-3. This is the standard convention from Trello, Linear, Notion — the rotation signals "this is in motion."

Every DnD operation has a non-gesture path. Keyboard reorder via Space + arrow keys. Touch via long-press. Tap-menu > "Move to In Review." The DnD is a speed-up for power users, not a barrier for everyone else.

The locked rule from Section 53 stands — no generic spinners, always say what's loading. These five additions don't replace that; they fill specific micro-gaps where the existing patterns are too heavy or too verbose. Quarter-ring is a button-level inline loader (skeleton can't live inside a button). Dash-ring is for ongoing chrome state like topbar sync (pulse-dot says "live", not "actively pulling"). Bars is for "analyzing" states unique to Vecreal (synthesis across sources). Shimmer is for streaming LLM-style output. Terminal cursor is for technical surfaces only.

Each loader is paired with a text caption. The caption is the contract; the loader is the visual reinforcement. Bars + "Analyzing 12 emails" tells the user both that Vecreal is busy AND what specifically. The same bars without a caption would violate the locked rule.

Color application follows the locked clay treatment exactly: clay-light on light, clay-bright on dark, status colors only when the operation has known semantic state (e.g., warning amber for slow sync, error red for failed retry). No fills — all loaders are stroke-based or wireframe, matching how clay shows up everywhere else in the system (outlined chips, accent borders, never solid clay backgrounds).

Motion specs are continuous loops outside the named --motion-* tokens (which describe transitions, not loops). All within Section 22's "no bounce" rule. Reduced-motion mode disables every animation and shows a static fallback at the same size.

The system communicates "this is happening right now" through five quiet signals: streaming dots (work in progress), phased progress (multi-step task with checkmarks), flash (a row just updated), animated counter (number changed), activity feed (vertical timeline of changes).

Each pattern is restrained on purpose. The pulse is meaningful when it correlates with real activity. If everything pulses, nothing reads as live — pulse loses signal.

All animations honor prefers-reduced-motion — the dot remains static when reduced motion is requested.

Four lightweight data-viz patterns. Use these before reaching for a full chart library. Sparkline for "trend over time" next to a number. Multi-segment bar for "parts of a whole." Comparison block for two metrics side-by-side. Histogram for distribution.

All four use the same color tokens (success / warning / error / accent / neutral). The semantic of color stays consistent across patterns — green = good direction, red = bad direction, neutral for context.

Status colors and trend colors are distinct. Status describes the state of a thing (open, blocked); trend describes direction of change (up, down). They share some hex values but represent different roles.

Citations work in two layers. The popover (Section 25) shows a snippet preview; clicking any source in the popover opens the full source modal with verbatim content — whole email thread or full meeting transcript — no agent rewriting.

This is the "show your work" principle in action: the user can drill from a synthesized claim → popover preview → full source — and trust each layer.

Each modal has a footer "Quote in brief" CTA so the PM can pull a specific message or transcript moment back into the brief as a citation. Vecreal augments the workflow without owning the source data.

When a brief item references many sources across multiple categories, a flat citation list becomes hard to navigate. The tree visualizes the graph: central node (the item being investigated) connected to category nodes (Drawings, Emails, Meetings, RFIs, Addendums) which expand to show their items.

All nodes are opaque. Lines never bleed through. This was a real bug we caught in iteration — transparent nodes broke legibility when graph density increased.

Two layouts are locked: vertical tree (portrait monitors, dialog views) and horizontal flow (widescreen default, reads left-to-right). Most PM monitors are widescreen, so horizontal is the default in dashboard contexts.

Coordination layer: Vecreal does not host or render source content. We synthesize and navigate; source-of-truth lives in Procore / Outlook / etc. Click an item leaf → opens in source.

Saved for future use. The current product is passive synthesis without multi-party collaboration — we don't track presence and don't host conversations. But the pattern is documented now so it's ready when collaborative features arrive: internal team comments on briefs, RFI back-and-forth, document review discussions.

One level of nesting only. Deeper conversations belong in a dedicated decision view, not threaded comments.

The send button uses the locked icon-in-CTA pattern (clay icon + soft white text on black bubble) — the only place clay appears on an action surface.

Construction's most common diff target isn't code — it's drawings, contracts, specs, cost estimates. The pattern still works (line-level adds/removes/changes) but the visual treatment matters: bright GitHub red/green collides with the warm clay palette. We use warm-tuned variants — the same #5DA17D / #c95151 semantic tokens as the rest of the system, paired with low-opacity backgrounds for the line-level wash.

Side-by-side is the default. When the file gets long enough that scrolling-in-sync becomes painful, the inline toggle lets the user switch. Either view runs the same change-detection — no information is lost in the toggle.

Version history is a rail below the diff. The current version (as of comparison) gets a clay-tinted bg so the user always knows their orientation. Clicking any history row swaps the comparison without leaving the surface.

Two annotation patterns coexist. Threaded discussions (Section 42) for free-floating conversations attached to a brief or RFI. Anchored comments for precision — the user is asking about a specific clause, dimension, or sentence. The visual treatment makes the role clear: anchored comments live in a margin rail with line-of-sight to their target text.

Default highlights are warm amber (the same #A87A2E / #d4a960 warning palette used for "flagged" states elsewhere). Clay is reserved for the active / selected comment — the one the user is currently reading or replying to. This preserves the locked rule: clay is brand, not annotation.

The quoted snippet at the top of every comment card is non-negotiable. It anchors the conversation in the original text, so a user joining the thread late can read the comment without scrolling back to find what was annotated.

Schedules are read-only in Vecreal. We ingest from Procore / MS Project / Primavera but never edit. The reason is the coordination-layer principle: the source-of-truth for schedule lives in the scheduler tool (P6, MSP) and the GC's scheduler maintains it. We surface it for context.

The strip is built in SVG, not CSS Grid. Grid had alignment glitches at certain widths; SVG with preserveAspectRatio stretches cleanly without sub-pixel issues.

Today marker is the visual anchor — clay-bright vertical line with halo at the current week. The user can scan past phases to see where today sits in the project arc.

The subcontractor profile is a summary surface, not a CRM. We surface project-relevant data only: this firm's presence on this project, their open SOW value, RFI velocity, submittal cycle time. We do not duplicate the firm-wide data that lives in the GC's subcontractor management system.

Coordination links section is the centerpiece. Every artifact (subcontract, change orders, RFIs, submittals) is hyperlinked to where it actually lives in Procore. Vecreal augments the navigation; the source-of-truth stays in the source system.

Stats strip uses 4 reliability metrics: contract value, change orders ($ delta), on-time rate (YoY trend), RFI volume (response avg). Mono numerics with right alignment for scannability.

Cost tables read like financial statements. Every number tabular-aligned (mono with tabular-figures), currency comma-formatted, variance color-coded with leading arrow icon, and the row tinted subtly to match.

Subtle row tint is intentional — the eye catches risk at a glance without the table feeling alarmist. A bright red row across hundreds of cost codes would be noise; subtle wash + colored cell is signal.

CSI division code in mono left column. Summary row at bottom with 2px border-top and bold totals — the standard accounting visual cue.