Pick the composition, not a one-off layout.
Each row is the contract from PATTERNS.md: when to import it, what to avoid, and where the live demo lives. Compare patterns here; View demo opens the live specimen with the same contract above it.
Shell
RouteShell@evalgist/design-system/uiView demoWork surfacesThe page needs the shared content width, its own H1, and an optional help or banner slot.
Do not Derive the title from the URL, or repeat the H1 in the topbar.
WorkSurfaceShell@evalgist/design-system/uiView demoWork surfacesA block of work sits inset on the page, with or without a border.
Do not Build a one-off padded card stack for the same role.
PageHeader@evalgist/design-system/uiView demoApp shellThe page owns the H1: eyebrow, title, description, actions.
Do not Put the page title in the topbar.
TopbarFrame@evalgist/design-system/uiView demoApp shellThe topbar aligns utility and route context to the shared content column.
Do not Read the path to invent a breadcrumb label.
ShellContentColumn@evalgist/design-system/uiView demoApp shellBody content must use the same max-width as the topbar column.
Do not Invent a second page width.
WizardContentColumn@evalgist/design-system/uiView demoWork surfacesA setup wizard's body is narrower than the full work surface.
Do not Stretch a short form to the full shell width.
Sidebar@evalgist/design-system/uiView demoChromeThe app shell needs the shared sidebar frame.
Do not Fork a local sidebar primitive.
SidebarNavLink@evalgist/design-system/uiView demoChromeA sidebar item. Active state is font weight and foreground color.
Do not Use a pill, a left bar, or a rounded highlight for the active item.
PageHelpBand@evalgist/design-system/uiView demoPage helpThe screen has topic-rail help under the topbar.
Do not Open a separate help page for workflow-first screen help.
BalancePill@evalgist/design-system/uiView demoApp shellThe topbar shows the current credit balance.
Do not Use a traffic-light color for the balance.
StickyActionBar@evalgist/design-system/uiView demoSticky action barA page needs persistent status and actions while work continues.
Do not Place the primary action out of reach below a long work surface.
Evidence and review
ReviewSplitWorkspace@evalgist/design-system/uiView demoEvidence reviewA review desk: queue or matrix on one side, detail on the other.
Do not Stack the queue and the detail as unrelated pages.
ReviewQueue@evalgist/design-system/uiView demoEvidence reviewA grouped list of items waiting for review. Selected rows use the neutral left bar (same classes as Shortlist review list).
Do not Invent a different selected-row treatment or put a left bar on non-list surfaces.
EvidenceCard@evalgist/design-system/uiView demoWorkflow primitivesOne judgment that must show the quote it rests on.
Do not State a verdict with no source quote.
EvidenceQuote@evalgist/design-system/uiView demoWorkflow primitivesA quoted passage in the Shortlist evidence card shell (bordered figure, blockquote left rule).
Do not A second quote style (muted border-only block, highlight band only, or left rule on the outer card).
SourceExcerpt@evalgist/design-system/uiView demoWorkflow primitivesA source region, including parsed document text.
Do not Paste source text as an unstyled block.
BandBadge@evalgist/design-system/uiView demoWorkflow primitivesA match band: strong, review, or low.
Do not Show a percentage or decimal score in primary match summaries (lists, headers, exports). Shortlist's audit sheet may show a numeric score and its calculation.
DecisionGroup@evalgist/design-system/uiView demoWorkflow primitivesThe human records a decision, separate from the AI suggestion.
Do not Treat the suggestion as the decision.
EvidenceComparisonTable@evalgist/design-system/uiView demoEvidence reviewCompare selected objects by evidence, criterion by criterion.
Do not Sort a comparison by a single raw score.
EvidenceMatrix@evalgist/design-system/uiView demoEvidence reviewA criteria overview across several objects.
Do not Rebuild the grid with one-off table markup.
CriteriaBreakdownBar@evalgist/design-system/uiView demoWorkflow primitivesA review header summarizes met, partial, unmet, and unknown criteria.
Do not Replace criterion counts with a single match score.
DetailSheet@evalgist/design-system/uiView demoWorkflow primitivesSupporting detail or source text needs a focused side panel.
Do not Move the main review task into a secondary sheet.
MarkdownContent@evalgist/design-system/uiView demoMarkdown contentTrusted, user-owned document text contains Markdown structure.
Do not Render untrusted third-party Markdown.
Timeline@evalgist/design-system/uiView demoTimelineAn audit or processing record has ordered events.
Do not Use it for unordered status labels.
DataTable@evalgist/design-system/uiView demoData tableTabular records need a shared surface with an optional toolbar or footer.
Do not Put toolbar controls inside the scrolling table body.
Workflow
FlowRailMini@evalgist/design-system/uiView demoWorkflow primitivesA Shortlist or Grade setup flow shows its numbered lifecycle in the page: static before creation, linked back to reached steps after.
Do not Put setup steps in the topbar, drop `numbered`, or build a separate rail style.
EmptyState@evalgist/design-system/uiView demoEmpty statesA section has no items, or its data is unavailable. Use a short title and description; add an action when there is a useful next step.
Do not Use a mascot, "Oops", or an exclamation.
DangerZoneCard@evalgist/design-system/uiView demoDanger zoneA destructive setting states what is removed and what is not.
Do not Hide deletion behind an unlabeled button.
CostPreviewPanel@evalgist/design-system/uiView demoWorkflow patternsShow credits or cost before a paid run.
Do not Start a paid run with no preview.
AnalysisProgressPanel@evalgist/design-system/uiView demoWorkflow primitivesShow batch progress during a run, with per-file rows.
Do not Reuse the cost preview as a progress readout.
UploadQueue@evalgist/design-system/uiView demoWorkflow patternsA file queue needs a shared frame. Compose FileRow children for per-file status, warnings, and actions.
Do not Show a spinner with no file-level state.
SampleBanner@evalgist/design-system/uiView demoPrimitivesThe screen is an example. Persistence and paid actions stay off.
Do not Let a sample write real product data.
StatusNotice@evalgist/design-system/uiView demoStatus noticeA state that is already true and does not ask for an action.
Do not Use it as a form field or a primary call to action.
Faq@evalgist/design-system/uiView demoFAQRelated questions need a compact disclosure list.
Do not Use it for the primary steps of a workflow.
SelectedFilePanel@evalgist/design-system/uiView demoWorkflow primitivesA chosen file needs its name, status, and replacement or removal actions before processing.
Do not Hide the selected file behind the upload control.
ProcessingPanel@evalgist/design-system/uiView demoPrimitivesSource text or a file is being processed before the next workflow step.
Do not Use a static notice when progress or active work matters.
SuggestionsBlock@evalgist/design-system/uiView demoWorkflow primitivesReviewers can inspect and choose which proposed criteria to add.
Do not Add suggestions to the owner's list without a choice.
UploadDropzone@evalgist/design-system/uiView demoWorkflow patternsA user needs to select or drop files before they enter UploadQueue.
Do not Use the dropzone as the per-file status list.
FileRow@evalgist/design-system/uiView demoWorkflow patternsUploadQueue or AnalysisProgressPanel needs a row with file status, warning, or action.
Do not Render per-file status as an unlabelled spinner.