Skip to content

DESIGN.md

Latest commit

 

History

History
200 lines (149 loc) · 4.56 KB

DESIGN.md

File metadata and controls

200 lines (149 loc) · 4.56 KB
Raw

DESIGN.md

Purpose

This document captures the implemented visual design of RAGU and the intended design direction for future work.

The frontend is still mostly native Streamlit, but the product now has a clearer functional surface:

  • upload and ask workflow
  • streamed answer display
  • optional TTS status and playback
  • PDB-driven Mol* structure visualization
  • retrieval debug views

Current UX structure

Main regions

  • Sidebar:
    • PDF upload
    • process button
    • delete embeddings button
  • Main content:
    • session identifier
    • app title
    • TTS availability status
    • question input
    • ask button
    • streamed answer
    • optional audio player
    • optional Mol* viewer
    • retrieval debug expanders

Current UX principles already present

  • progressive disclosure through expanders
  • streamed output instead of blocking full-response rendering
  • visible TTS availability feedback
  • evidence-grounded answer framing

Visual identity

Product name

RAGU

Product tone

The application should feel:

  • scientific
  • clear
  • grounded
  • deliberate
  • tool-like, not chatbot-like

Current branding elements

  • project logo through st.logo
  • page icon/favicon from the same logo
  • large app title emphasizing the local-first scientific workflow

Current custom frontend implementation

Most UI elements use native Streamlit rendering.

The primary custom HTML/CSS block is the Mol* structure viewer embed.

Current Mol* structure

<div class="structure-viewer-shell">
  <div
    id="entry-structure-viewer"
    class="molstar-viewer"
    aria-label="3D protein structure viewer"
  ></div>
</div>

Current Mol* CSS

.molstar-viewer {
    position: relative;
    width: 100%;
    height: 100%;
    overflow: hidden;
    background: var(--bg);
}

.molstar-viewer .msp-plugin,
.molstar-viewer .msp-plugin-content,
.molstar-viewer .msp-layout-state,
.molstar-viewer .msp-layout-root {
    width: 100%;
    height: 100%;
}

.viewer-placeholder {
    display: grid;
    gap: 0.65rem;
    min-height: 18rem;
    place-content: center;
    text-align: center;
    border: 1px dashed var(--border-strong);
    border-radius: var(--radius-sm);
    background:
        linear-gradient(180deg, rgba(10, 77, 122, 0.04), rgba(17, 167, 163, 0.01)),
        var(--surface-muted);
    padding: 1.5rem;
}

.structure-viewer-shell {
    height: 500px;
}

Current design constraints

  • Streamlit still controls most layout, typography, and spacing.
  • There is no dedicated CSS file or theme token layer.
  • The Mol* embed still uses inline CSS.
  • Responsiveness is mostly inherited from Streamlit.
  • The viewer height is still fixed.

Current UX notes for TTS

TTS is intentionally not silent anymore.

Current behavior:

  • if Piper is available, the UI says so
  • if Piper is unavailable, the UI shows a visible status message
  • if synthesis succeeds, a browser audio player is rendered
  • if synthesis fails, the user still gets the text answer plus a warning

This is the correct design direction: optional features should be explicit, not invisible.

Desired future design direction

Overall direction

RAGU should feel like a scientific workstation rather than a generic AI chat surface.

Prefer:

  • compact information density
  • strong typographic hierarchy
  • obvious separation between answer, evidence, structure, and operational status
  • restrained colors

Avoid:

  • consumer-chat styling
  • ornamental gradients across the full UI
  • oversized decorative cards
  • hidden system state

Recommended layout evolution

flowchart TD
    Header[Brand + service state]
    Query[Question composer]
    Answer[Answer panel]
    Audio[Optional TTS panel]
    Viewer[Optional structure viewer]
    Evidence[Evidence + reranking panels]

    Header --> Query --> Answer
    Answer --> Audio
    Answer --> Viewer
    Answer --> Evidence
Loading

Design priorities

  1. Make evidence provenance more visually explicit.
  2. Separate answer content from debugging content.
  3. Improve empty, loading, and failure states.
  4. Make the structure viewer responsive.
  5. Add service status indicators for Ollama, Chroma, and optional TTS.

Accessibility guidance

  • Keep labels visible.
  • Do not rely on color alone for state.
  • Preserve keyboard accessibility.
  • Keep status feedback explicit.
  • Keep the audio functionality discoverable without hiding it behind unsupported controls.

Design debt

  • no central theme or token system
  • mostly default Streamlit styling
  • fixed Mol* height
  • limited layout customization
  • monitoring surfaces are outside the app rather than integrated into the UI