Patterns

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/ui
    View demoWork surfaces

    The 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/ui
    View demoWork surfaces

    A 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/ui
    View demoApp shell

    The page owns the H1: eyebrow, title, description, actions.

    Do not Put the page title in the topbar.

  • TopbarFrame@evalgist/design-system/ui
    View demoApp shell

    The 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/ui
    View demoApp shell

    Body content must use the same max-width as the topbar column.

    Do not Invent a second page width.

  • WizardContentColumn@evalgist/design-system/ui
    View demoWork surfaces

    A 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/ui
    View demoChrome

    The app shell needs the shared sidebar frame.

    Do not Fork a local sidebar primitive.

  • SidebarNavLink@evalgist/design-system/ui
    View demoChrome

    A 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/ui
    View demoPage help

    The screen has topic-rail help under the topbar.

    Do not Open a separate help page for workflow-first screen help.

  • BalancePill@evalgist/design-system/ui
    View demoApp shell

    The topbar shows the current credit balance.

    Do not Use a traffic-light color for the balance.

  • StickyActionBar@evalgist/design-system/ui
    View demoSticky action bar

    A 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/ui
    View demoEvidence review

    A 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/ui
    View demoEvidence review

    A 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/ui
    View demoWorkflow primitives

    One judgment that must show the quote it rests on.

    Do not State a verdict with no source quote.

  • EvidenceQuote@evalgist/design-system/ui
    View demoWorkflow primitives

    A 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/ui
    View demoWorkflow primitives

    A source region, including parsed document text.

    Do not Paste source text as an unstyled block.

  • BandBadge@evalgist/design-system/ui
    View demoWorkflow primitives

    A 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/ui
    View demoWorkflow primitives

    The human records a decision, separate from the AI suggestion.

    Do not Treat the suggestion as the decision.

  • EvidenceComparisonTable@evalgist/design-system/ui
    View demoEvidence review

    Compare selected objects by evidence, criterion by criterion.

    Do not Sort a comparison by a single raw score.

  • EvidenceMatrix@evalgist/design-system/ui
    View demoEvidence review

    A criteria overview across several objects.

    Do not Rebuild the grid with one-off table markup.

  • CriteriaBreakdownBar@evalgist/design-system/ui
    View demoWorkflow primitives

    A review header summarizes met, partial, unmet, and unknown criteria.

    Do not Replace criterion counts with a single match score.

  • DetailSheet@evalgist/design-system/ui
    View demoWorkflow primitives

    Supporting detail or source text needs a focused side panel.

    Do not Move the main review task into a secondary sheet.

  • MarkdownContent@evalgist/design-system/ui
    View demoMarkdown content

    Trusted, user-owned document text contains Markdown structure.

    Do not Render untrusted third-party Markdown.

  • Timeline@evalgist/design-system/ui
    View demoTimeline

    An audit or processing record has ordered events.

    Do not Use it for unordered status labels.

  • DataTable@evalgist/design-system/ui
    View demoData table

    Tabular 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/ui
    View demoWorkflow primitives

    A 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/ui
    View demoEmpty states

    A 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/ui
    View demoDanger zone

    A destructive setting states what is removed and what is not.

    Do not Hide deletion behind an unlabeled button.

  • CostPreviewPanel@evalgist/design-system/ui
    View demoWorkflow patterns

    Show credits or cost before a paid run.

    Do not Start a paid run with no preview.

  • AnalysisProgressPanel@evalgist/design-system/ui
    View demoWorkflow primitives

    Show batch progress during a run, with per-file rows.

    Do not Reuse the cost preview as a progress readout.

  • UploadQueue@evalgist/design-system/ui
    View demoWorkflow patterns

    A 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/ui
    View demoPrimitives

    The screen is an example. Persistence and paid actions stay off.

    Do not Let a sample write real product data.

  • StatusNotice@evalgist/design-system/ui
    View demoStatus notice

    A 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/ui

    Related questions need a compact disclosure list.

    Do not Use it for the primary steps of a workflow.

  • SelectedFilePanel@evalgist/design-system/ui
    View demoWorkflow primitives

    A 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/ui
    View demoPrimitives

    Source 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/ui
    View demoWorkflow primitives

    Reviewers 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/ui
    View demoWorkflow patterns

    A 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/ui
    View demoWorkflow patterns

    UploadQueue or AnalysisProgressPanel needs a row with file status, warning, or action.

    Do not Render per-file status as an unlabelled spinner.