Hosted onhoraciodev.dev.hyper.mediavia theHypermedia Protocol

Embeds Design ProposalExploring alternative visual treatments for embedded content from other documents, replacing the current green left border approach.

Problem Statement

Our documents support embedding content from other documents (embeds). Currently, embeds are visually denoted with a green vertical bar on the left side of the content, similar to a blockquote style. This approach has three key problems:

  1. Looks like a blockquote — The green left border is visually identical to how blockquotes are styled across the web, confusing the semantic meaning of embedded content.

  2. Not informative about the source — There is no indication of where the content comes from. Users cannot see the source document title, author, or any attribution without interacting.

  3. Disrupts reading flow — The continuous left border, especially for longer embeds, creates visual noise and breaks the natural reading rhythm.

Constraints

  • Users can navigate to the source document and expand/collapse embeds

  • Visual treatment should be the same in both reading and editing modes

  • Embeds can be any length — from a single paragraph to an entire document

  • Three existing view modes: Content (inline), Card (summary), and Comments

Current Design

The current implementation uses a 3px green left border (border-l-primary border-l-3 in Tailwind) applied via the EmbedWrapper component.

The green bar provides a visual cue that content is different, but it fails to communicate what that content is or where it comes from. It also creates a visual pattern that's indistinguishable from blockquotes.

Proposed Alternatives

Option A — Attribution Header

Replace the green bar with a compact header bar above the embedded content, showing source document info.

How it works

  • A small header displays the source document's icon, title, author, and a collapse chevron

  • The header is clickable — navigates to the source document

  • The embedded content below has no border or special styling — it reads naturally

  • The container uses a very subtle background (#FAFAFA) with rounded corners to define boundaries

  • The expand/collapse chevron is integrated into the header

Pros

  • Clear source attribution — solves the "where is this from?" problem

  • Doesn't look like a blockquote — distinct visual pattern

  • Minimal reading disruption — content itself has no special styling

  • Familiar pattern (Notion synced blocks, GitHub embeds, Slack previews)

  • Natural home for the expand/collapse control

  • Works well for any embed length

Cons

  • Takes vertical space for the header row

  • Nested embeds could create visual clutter with stacked headers

Option B — Background Tint + Inline Attribution

Use a very subtle background color with a small source label to differentiate embedded content.

How it works

  • A very soft green tint (brand color at ~5% opacity) fills the embed area

  • A small "From: Document Title" label appears at the top in the brand color

  • A soft rounded border defines the embed boundaries

  • Content reads almost like normal text with just a hint of differentiation

Pros

  • Lightest visual weight of all options

  • Content reads very naturally — minimal disruption

  • The tint provides a subtle but persistent visual cue across any length

  • Source attribution is present but unobtrusive

Cons

  • May be too subtle for some users to notice at a glance

  • Background tint can clash with dark mode if not carefully calibrated

  • Less discoverable than a header approach

  • No natural place for expand/collapse controls

Option C — Margin Indicator + Hover Attribution

Place a small icon in the left margin with source info revealed on hover. Zero visual disruption to the content.

How it works

  • A small link/clip icon sits in the left gutter (where collapse chevrons already exist)

  • The embedded content has no border, no background — visually identical to regular text

  • Hovering over the margin icon reveals a dark tooltip showing: source title, author, and "Open source" link

  • Clicking the icon navigates to the source document

Pros

  • Zero reading disruption — content is indistinguishable from native text when scanning

  • Minimalist approach that respects the reading experience above all else

  • Uses existing gutter space (where collapse chevrons already live)

Cons

  • Low discoverability — users must know to look for or hover the icon

  • Not obvious that content is embedded until the user interacts

  • May cause confusion when users copy text without realizing it's from another document

  • Tooltip-based attribution is invisible to screen readers

Option D — Bookend Dividers with Source Tag

Use thin horizontal lines above and below the embed, with source attribution inline in the top divider.

How it works

  • A thin horizontal line appears above the embed with the source document title embedded inline

  • The content between the lines has no special styling

  • A simple thin closing line marks the end of the embed

  • Clicking the source title navigates to the source document

Pros

  • Very clean, editorial feel (similar to citations in academic papers)

  • Clear start and end boundaries without a continuous border

  • Source attribution is visible without interaction

  • Works well at any embed length — the lines don't create visual weight like a continuous bar

Cons

  • Horizontal lines add visual noise if many embeds are stacked consecutively

  • The editorial style may feel out of place in a more casual document

  • Less clear boundary for very short embeds (1-2 lines)

Recommendation

Option A (Attribution Header) offers the strongest balance across all

three problems:

  1. Clear source attribution (solves problem 2)

  2. Distinct visual pattern that's not a blockquote (solves problem 1)

  3. Content itself has no special styling, preserving reading flow (solves problem 3)

A possible hybrid approach (A + B) could combine the header for attribution with a very subtle background tint for longer embeds, making boundaries clearer when the content spans many paragraphs.

Next Steps

  1. Review mockups and gather team feedback on preferred direction

  2. Build a prototype of the top 1-2 options in the actual editor

  3. Test with real document content at various embed lengths

  4. Evaluate dark mode behavior

  5. Ship as an experiment behind a feature flag

Do you like what you are reading?. Subscribe to receive updates.

Unsubscribe anytime