Design vector sizing calculator UI

[KOTungseth]

Summary

Design review and sign-off for the vector sizing calculator before it ships in docs-content.

Implementation (for review): #2736

Status

Item	Status
Interactive UI implemented (React + EUI)	Done in PR #2736
UX polish (layout, typography, advanced section, formulas panel)	Done
Design review	Pending
Sign-off	Pending

Preview

• PR preview (calculator): https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2736/syntax/vector-sizing-calculator
• Local: dotnet run --project src/tooling/docs-builder -- serve → /syntax/vector-sizing-calculator

UI surfaces to review

• Configuration panel — vectors/dimensions inputs, element type, index type, quantization, replicas; collapsible advanced settings (HNSW, DiskBBQ, off-heap %)
• Results panel — per-replica disk/RAM hero, cluster totals, detail lines, disclaimer and doc link
• Formulas panel — collapsible disk / RAM / cluster formula breakdown
• Responsive / docs chrome — behavior inside Elastic Docs layout (not standalone app chrome)

Scope

• Review against Elastic Docs design standards (spacing, typography, color, EUI usage, accessibility)
• Note required changes or approve as-is
• Hand off any follow-up implementation to Docs Eng (same PR or follow-up)

Out of scope

• Directive / build plumbing (Add {vector-sizing-calculator} directive #3051)
• Formula accuracy (BBQ constant) — docs-content-internal#1031
• Embed placement in docs-content — docs-content-internal#1030

Prerequisites for embed (#1030)

• Design sign-off recorded on this issue

Acceptance criteria

• Configuration, results, and formulas panels reviewed
• Mobile / narrow viewport checked
• Sign-off comment added (approve or list of changes)
• Any blocking design changes tracked (issue comment or linked follow-up)

Owner

@itsalexcm

Coordination: @KOTungseth

[itsalexcm]

For design review: there is now a stable-ish preview surface on the docs-builder docset:

• URL path when running isolated serve: /syntax/vector-sizing-calculator (includes a live :::{vector-sizing-calculator} block next to the syntax notes).
• Widget implementation remains under src/Elastic.Documentation.Site/Assets/web-components/VectorSizingCalculator/ (React + EUI).

No visual redesign has been done yet, this is intentionally an engineering baseline so design can review the current UI in real doc chrome. Blocker called out in this issue (“stable web component”) should be unblocked for preview purposes; any UI change requests can be tracked as follow-ups after sign-off.

[itsalexcm]

Status update (design)

The calculator UI in docs-builder has evolved since the issue was opened; worth a fresh design pass against the current embed.

What changed in the UI (high level)

• Two-column layout (config vs results) with responsive behavior.
• Results panel focused on RAM hero + key metrics; cluster totals / formulas panel / breakdown chart called out in this issue are no longer present in the current component — scope for design review should match the current UI, not the older description.
• Graph connections (m) slider restyled (track/thumb) for closer match to target visuals.
• Quantization row is hidden when there is only one option (e.g. only None, or DiskBBQ’s single built-in mode).
• Replicas field allows clearing while focused; blur normalizes empty input to 1 (clamped 1–99).
• Number of vectors preset list includes 1.000.
• CTA (“Get started free”) has a short transition on hover/focus states.

Ask for design

• Review for Elastic Docs consistency (typography, spacing, EUI usage, callouts, CTAs).
• Confirm whether the simplified results experience needs any spec updates (vs the older panels listed in this issue).

cc @KOTungseth

[itsalexcm]

Update (design / UI)

Calculator UI continues to evolve on PR #2736: #2736

Changes relevant to design review

• No bottom CTA row in the calculator embed anymore (removed primary “Get started” button and “Contact us” link from the component).
• Results column is intentionally lean (RAM hero + key metrics + optional info callout); there is no cluster-totals strip, formulas panel, or breakdown chart in the current embed — please review what is on the page today, not only the older bullet list in this issue.

For design sign-off

• Focus on Elastic Docs consistency (typography, spacing, EUI controls, callout styling, slider + numeric field alignment).
• If anything still feels “marketing heavy” or off-brand after the CTA removal, note it on the PR for a quick follow-up.

cc @KOTungseth

[itsalexcm]

Updated the issue body with UI status, PR preview link, and review/sign-off checklist.

If you prefer to keep the original text and track progress via comments only, let me know and I can revert the body changes.

[itsalexcm]

Design feedback — point-by-point status (iteration 1 → PR #2736)

Tracking responses to the first-round review (Google Doc). Preview: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2736/syntax/vector-sizing-calculator

#	Feedback	Status	Notes
1	Graph connections (m) in Advanced	Done	Unchanged
2	DiskBBQ — disk and RAM at same level	Done	Hero shows Disk + RAM side by side
3	Off-heap RAM labeling / % in Advanced	Done	Hero stays RAM (by design). Off-heap % below Index structure for DiskBBQ; contextual helpText for HNSW and DiskBBQ on Index structure. Formulas use “Total off-heap RAM (per replica)”.
4	Vectors / dimensions — free numeric entry	Done (by design)	EuiComboBox with common presets plus custom values (onCreateOption) — not a plain dropdown-only control. en-US comma grouping.
5	Vectors ≠ documents	Done	Tooltip on “Number of vectors”
6	Replicas looked tied to quantization	Done	Replica shards is its own row in Advanced (not beside Quantization).
7	Element types: float32, bfloat16, int8, bit	Done
8	Replicas field / per-replica vs cluster math	Done	Replica shards input (0–99; excludes primary). Hero = cluster totals (× (1 + replicas)). Detail = per replica. Header: Cluster total (1 primary + N replicas). Tooltip explains primary + replica shards.
9	Formulas panel	Done
10	Remove quantization marketing copy	Done	Not shown in UI
11	Co-locate or cross-link static sizing docs	Partial	Footer links to approximate-knn-search (memory). Same-page embed = docs-content-internal#1030
12	Vectors per cluster in Advanced	Done
13	Binary units / exact bytes	Done	Footer line: “Sizes use binary units (1 GB = 1,024 MB).” (no per-value byte tooltips in hero — intentional)
14	DiskBBQ RAM range in UI	Done	Min–max range per reviewer formulas: min = centroids + 5% of quantized vectors; max = centroids + 50%. Hero cluster RAM and detail “RAM per replica” show the range; Formulas panel includes min/max and cluster totals in range. % allocated to off-heap RAM slider picks a point within 5–50% (default 50% = high end of practical range). Hero label stays RAM (not “off-heap”) by design.

Point 11 — what the reviewer meant

Put the calculator on the same page as the static sizing table in approximate-knn-search.md, or at least link both ways. We have a one-way “More info” link to the doc page; embedding on that page is tracked in docs-content-internal#1030.

---

Happy to adjust anything before we call design sign-off complete.

[cotti]

AI triage

Automated investigation against the current codebase. A human still needs to confirm before any code change.

Original concern

Design-review and sign-off the vector sizing calculator UI/UX before it ships, against Elastic Docs design standards.

Findings

• This is a design deliverable (review + recorded sign-off), not a code change — the acceptance criteria are "panels reviewed", "mobile checked", "sign-off comment added", all of which require a human design reviewer.
• The calculator UI does not exist on main: a tree-wide search for vector-sizing-calculator / VectorSizingCalculator returns nothing on the working tree, and no calculator wiring is present under src/Elastic.Markdown/.
• It lives only on the PR branch origin/feat/vector-sizing-calculator → open PR #2736 ("Add Vector Sizing Calculator", not draft, base main). The React + EUI component sits under src/Elastic.Documentation.Site/Assets/web-components/VectorSizingCalculator/ and the directive is wired in Elastic.Markdown (commit 9b0ca4c4, 2026-04-13). None of this is on main yet.
• Design iteration is in progress: the thread records iteration-1 feedback (14 points) addressed on PR Add Vector Sizing Calculator #2736 and a preview surface at /syntax/vector-sizing-calculator, but the issue body status table still shows Design review: Pending and Sign-off: Pending.

Verdict

Needs stakeholder input

The implementation work this issue reviews is already in flight on open PR #2736 and has gone through at least one design-feedback round, but the issue's actual deliverable — a recorded design sign-off — is a human decision that has not happened. Resolution depends on a UX/design reviewer signing off on the current embed (typography, spacing, EUI usage, slider/numeric-field alignment, accessibility, narrow-viewport behavior) and on product/scope confirmation that the intentionally lean results experience (RAM hero + key metrics, no cluster-totals strip / formulas panel / breakdown chart) matches intent versus the older panel list in the issue body. Nothing here is a docs-builder code task for triage to action.

Proposal

Open questions, grouped by audience:

• UX / design (ai:ux-question): Does the current PR Add Vector Sizing Calculator #2736 embed meet Elastic Docs design standards at the preview URL (typography, spacing, EUI controls, callout styling, slider + numeric-field alignment, accessibility, narrow/mobile viewport)? Approve as-is or list blocking changes.
• Product / scope (ai:product-question): Is the simplified results experience (RAM hero + key metrics, no cluster-totals / formulas panel / breakdown chart) the intended scope, superseding the older panel description in the issue body? Confirm so the spec and acceptance criteria can be updated to match what's actually on the page.

Related issues

• #3051 (open) — sibling implementation issue, "Add {vector-sizing-calculator} directive"; same PR Add Vector Sizing Calculator #2736 is its impl. Already AI-triaged.
• #2736 (open PR) — the implementation under review here.
• Out-of-repo trackers named in the issue body: docs-content-internal#1030 (embed placement) and docs-content-internal#1031 (BBQ formula accuracy, owned by Search Engineering). Noted, not investigated.

Notes

• The two docs-content-internal references and any Figma/spec artifacts are outside this repo; sign-off coordination is owned by the assignee (@itsalexcm) and @KOTungseth, not docs-builder eng triage.
• Labels added: ai-triaged, ai:ux-question, ai:product-question. This is a design/coordination issue rather than a code task, so no ai:quick-fix or ai:eng-question.