From bc95a052ae80597a140e66a3a29c562053ed86c6 Mon Sep 17 00:00:00 2001 From: Vitor Vasconcellos Date: Thu, 30 Apr 2026 13:14:42 -0300 Subject: [PATCH 01/37] temp: add new layout mockup (AI-generated) Signed-off-by: Vitor Vasconcellos --- ecosystem-explorer-v1-design-brief.md | 173 ++++ ecosystem-explorer-v1-mockups.html | 1191 +++++++++++++++++++++++++ ecosystem-explorer/DESIGN.md | 655 ++++++-------- 3 files changed, 1657 insertions(+), 362 deletions(-) create mode 100644 ecosystem-explorer-v1-design-brief.md create mode 100644 ecosystem-explorer-v1-mockups.html diff --git a/ecosystem-explorer-v1-design-brief.md b/ecosystem-explorer-v1-design-brief.md new file mode 100644 index 00000000..c8715364 --- /dev/null +++ b/ecosystem-explorer-v1-design-brief.md @@ -0,0 +1,173 @@ +# v1 design proposal — Ecosystem Explorer + +> Brainstorm for [#84 — \[Explorer\] UI/UX Design](https://github.com/open-telemetry/opentelemetry-ecosystem-explorer/issues/84). Builds on `DESIGN.md` and **aligns the explorer to the existing visual language of [opentelemetry.io](https://opentelemetry.io)**. Mockup HTML is included alongside this doc as `ecosystem-explorer-v1-mockups.html` — it's a static prototype with a tab switcher across all four page types and a working light/dark theme toggle. + +--- + +## TL;DR + +The placeholder design felt like a separate microsite rather than part of the OTel project. **The fix is alignment, not redesign.** This proposal standardizes the explorer on the same visual grammar as opentelemetry.io: same dark navbar, same light/dark theme toggle, same OTel purple `#4f62ad` and orange `#f5a800`, same Bootstrap-flavored chrome (Docsy `td-*` patterns), same footer, same CNCF callout, same canonical stats numbers ("12+ Languages · 200+ Collector Components · 1005+ Integrations · 102+ Vendors"). + +On top of that shared scaffold, the explorer adds the things opentelemetry.io can't: real faceted filtering with URL state, a three-pane component detail page with version timeline + diff, density toggles (Cards / Compact / Table), and pipeline-anatomy diagrams. + +A user clicking from `opentelemetry.io/ecosystem/` to the Explorer should not feel they have left the site. + +--- + +## Why alignment first + +The previous iteration of this brief proposed a strong direction ("The Catalog") with thoughtful IA. What it didn't do was **lock the visual language to what opentelemetry.io already publishes**. Once you put the two side by side, the gap is obvious: + +| Element | opentelemetry.io | v0 placeholder | v1 (this proposal) | +|---|---|---|---| +| Theme support | Light + Dark + Auto (toggle in navbar, persisted to `td-color-theme` in `localStorage`) | Dark-only | **Light + Dark + Auto** (same key, same toggle) | +| Brand purple | `#4f62ad` (theme-color, mask-icon, primary stats band) | Not used | **`#4f62ad` adopted as `--color-secondary`** | +| Brand orange | `#f5a800` (logo gradient, kapa accent) | `38 95% 52%` HSL ≈ `#f5a800` | Already aligned ✓ | +| Topnav | Always-dark `td-navbar`: Docs · Ecosystem · Status · Community · Training · Blog · search · lang · theme | Custom 2-link bar | **Mirror full structure**, add Explorer entry | +| Stats numbers | "12+ · 200+ · 1005+ · 102+" | Made up our own | **Match canonical numbers** | +| Signals | Traces · Metrics · Logs · **Baggage** | Had Profiles | **Switch to Baggage** | +| Footer | Two clusters of Font Awesome social icons + centered copyright | Custom | **Mirror Docsy footer** | +| Hero | `td-cover-block` with bg image + dark overlay + centered content + `btn-lg btn-primary/btn-secondary` | Generic gradient | **Use cover-block** | +| CNCF callout | On every page (`td-box--secondary`) | Missing | **Add to every page** | +| Component pattern | Bootstrap `.card` with `border-success` etc. + `text-bg-*` badges | Custom | **Adopt** + extend with type stripe | +| Theme tokens | `data-bs-theme` attribute | Tailwind v4 only | **`data-bs-theme` honored alongside Tailwind** | + +This is now reflected in the updated `DESIGN.md` ("Alignment with opentelemetry.io" section) and visible in the mockup. + +--- + +## What's working in v0 that we keep + +- The OTel orange (`#f5a800`) was already aligned — kept as `--color-primary` +- The card hover state (subtle scale + shadow) feels right and translates cleanly into Bootstrap card patterns +- The gradient text treatment for hero headlines is a nice signature element worth keeping (now using `purple → orange` to match the OTel logo) +- The grid-pattern background overlay for hero sections is a low-cost depth cue worth keeping + +## What changes from v0 + +- **Visual chrome** entirely re-platformed onto Bootstrap 5 + Docsy `td-*` patterns to match opentelemetry.io +- **Light theme** added as the default (with dark + auto as toggle options) +- **Brand purple** introduced as `--color-secondary` and used for stats band, brand accents, breadcrumb active state +- **Stats** sourced from opentelemetry.io's canonical numbers +- **Signals** corrected to use `Baggage` instead of `Profiles` +- **CNCF incubating project** callout added to every page +- **Footer** restructured to two-cluster Font Awesome layout matching opentelemetry.io +- **Status pill mapping** locked to Bootstrap `text-bg-*` (success/info/warning/danger) for portability + +--- + +## Direction: "The Catalog" — unchanged in spirit, re-skinned + +The recommended direction remains "The Catalog" (treat the explorer like the npm/crates.io of OpenTelemetry — searchable, comparable, version-aware). The improvements borrowed from "Atlas" (pipeline diagrams) and "Dashboard" (version timeline + diff) are still in play. What's new is that all of it now lives inside the visual frame of opentelemetry.io. + +--- + +## Page-by-page spec + +### 1. Explorer home page + +**Goal:** answer "what is this site, and what's in it?" in five seconds. Look unmistakably like a sub-page of opentelemetry.io. + +**Layout (top to bottom):** +1. **Always-dark Docsy navbar** — Docs · Ecosystem (active) · Status · Community · Training · Blog · search · lang · theme toggle. +2. **Sub-nav** for the explorer (breadcrumb-only on the home page). +3. **Cover-block hero** — radial gradient + grid pattern background, OTel logo mark, "OpenTelemetry Ecosystem Explorer" gradient headline, lead copy, two CTAs (`btn-lg` primary orange + outline-light), and a glass-effect ⌘K-able global search input with chips. +4. **Stats band** (`box-primary`, OTel purple) — "12+ Languages · 200+ Collector Components · 1005+ Integrations · 102+ Vendors". Numbers link out to relevant pages, matching opentelemetry.io's pattern exactly. +5. **Ecosystems grid** — Collector and Java Agent as primary cards (with stability pill, count, latest version, "updated this week"), plus dashed "coming soon" cards for Python, Go, JS, .NET. +6. **Browse by signal** — four signal cards (Traces / Metrics / Logs / Baggage) matching opentelemetry.io's homepage. +7. **Recent activity** rail — last-30-days feed with status pills and ecosystem labels. +8. **CNCF callout** + Docsy footer. + +**Why this beats the placeholder:** the visitor sees scale (canonical numbers) and recency above the fold, plus a global search. The page chrome is indistinguishable from opentelemetry.io. + +### 2. Individual ecosystem landing + +**Goal:** orient a user to *this* project, then send them to the list with sensible defaults. + +**Layout:** +1. **Sub-nav with breadcrumbs**: `Explorer › Ecosystems › Collector`. +2. **Cover-block hero** — eyebrow, gradient title, description, three CTAs (Browse, Read overview, GitHub), and a "Latest release" card on the right with `+4 added · 12 changed · 2 deprecated` deltas. +3. **Pipeline anatomy** — five clickable stage cards (Receivers 98 → Processors 42 → Exporters 76 → Connectors 14 + Extensions 35), each as a one-click filter into the list. Color stripes on the indicator dots match the type-stripe taxonomy. +4. **Quick entry** — three cards (Most-used components · Core vs. Contrib · Diff across versions). +5. **CNCF + footer.** + +### 3. List pages + +**Goal:** make 200+ components actually browseable. + +**Layout:** +- **Sub-nav with breadcrumbs.** +- **Page header**: gradient title, result count, view toggle (Cards / Compact / Table — Compact is default), sort dropdown. +- **Active filter chips** as Bootstrap `badge text-bg-secondary rounded-pill` with × dismiss. +- **Left-rail facets** (Bootstrap form): Search · Type (with color-stripe indicators) · Signal · Stability · Distribution (core/contrib) · Version. Each facet shows count alongside the label. +- **Compact result list** in a `.card` with grid rows: `[type-stripe | name + slug + description | type | signals | stability pill]`, alternating row backgrounds, sticky header, Bootstrap pagination footer. +- **URL-persisted filter state** (`?type=receiver&signal=traces&distribution=contrib`). + +**Status-pill mapping (locked):** `stable=text-bg-success`, `beta=text-bg-info`, `alpha=text-bg-warning`, `unmaintained|deprecated=text-bg-danger`. + +**Type stripe (4px left edge):** receiver=info-blue, processor=purple, exporter=orange, connector=pink, extension=teal. + +### 4. Component detail page + +**Goal:** be the canonical page for a component — overview, configuration, and what changed across versions. + +**Layout (three-pane):** +- **Sub-nav with full breadcrumbs**: `Explorer › Collector › Receivers › Kafka Receiver`. +- **Left rail (sticky):** sibling navigator (98 receivers, with current highlighted in OTel orange) + on-page anchor links. +- **Center column:** + - Header card with type stripe + eyebrow + title + slug + stability pill + version + signal badges + GitHub/Docs links. + - **"Where this fits"** mini-pipeline diagram showing the component placed inside a typical pipeline. + - Tabbed content area (Bootstrap `nav-tabs`): **Configuration** (Bootstrap striped table with Key/Type/Default/Description), **README**, **Emitted attributes**, **Examples**. +- **Right rail (sticky):** + - **Version history timeline** — vertical timeline with current version highlighted in green, per-version changes summarized, with a `Compare` selector and a "Diff →" link. + - **Compatibility card** — Min collector, Min Go, Distribution, License. + +**Empty/error states:** spec four — *not yet released for this version*, *deprecated/removed*, *missing data*, *no docs yet*. Each gets a designed empty state, not a stack trace. + +--- + +## Cross-cutting principles + +1. **Continuity with opentelemetry.io is the spine.** Every component should look at home if dropped into the parent site. +2. **Light + dark parity.** No dark-only components. No light-only components. The theme toggle (persisted to `td-color-theme` in `localStorage`) flips both. +3. **Density toggles, not redesigns.** Every list view remembers the user's last density choice. +4. **URL is the state.** Every filter, sort, and tab is reflected in the URL so links are shareable. +5. **Status legibility before everything else.** Stability and distribution should be perceivable in <300ms scanning. +6. **One small diagram beats one paragraph.** Pipeline diagrams on the ecosystem landing and detail pages do more than 200 words of intro copy. +7. **Empty states are first-class.** "Component missing in this version" is information, not an error. +8. **CNCF on every page.** Non-negotiable — opentelemetry.io shows it everywhere and we need to match. + +--- + +## Suggested sub-issues to break out of #84 + +If this lands well, the work splits naturally: + +- [ ] Theme system — port to `data-bs-theme` with light/dark/auto, persist to `td-color-theme`, write contrast tests for both themes +- [ ] Navbar component — match opentelemetry.io structurally and visually; add explorer-specific sub-nav +- [ ] Footer component — Docsy two-cluster pattern with Font Awesome icons +- [ ] CNCF callout — reusable component on every route +- [ ] Stats band — fed from a single source of truth synced with the canonical numbers on opentelemetry.io +- [ ] Home page — hero (cover-block) + global search + recent activity +- [ ] Ecosystem landing — pipeline anatomy diagram (reusable component) +- [ ] List page — facet rail + density toggle + URL state + chip system +- [ ] Detail page layout — three-pane shell + sibling navigator +- [ ] Detail page — embedded README/config-table renderer (Bootstrap striped tables) +- [ ] Detail page — version timeline + diff view +- [ ] Status-pill / type-stripe mapping spec → already added to `DESIGN.md` +- [ ] Empty/error state library (4 patterns) + +Each is small enough for one contributor to own. + +--- + +## Mockup + +A static, clickable HTML prototype with all four pages (Home / Ecosystem / List / Detail) and a top-bar switcher is included as `ecosystem-explorer-v1-mockups.html`. It uses Bootstrap 5 + Font Awesome (matching opentelemetry.io's stack) and supports the same theme toggle pattern. Open in a browser, click between the four tabs, and toggle the theme to see both modes. + +## Open questions + +- Should the explorer's home-page **search bar** actually search across ecosystems, or just be a launcher into per-ecosystem search? +- For the **detail page version diff**, do we have the underlying data (per-version config schemas, deprecation markers) in `ecosystem-registry`/`ecosystem-automation` already, or is that a data-pipeline prerequisite? +- Status terminology in the data is currently mixed (`alpha`/`beta`/`development`/`unmaintained`). Worth aligning to one taxonomy before locking pill colors. +- Will the explorer eventually live at `opentelemetry.io/ecosystem/explorer/` or as a separate domain? That decision affects how literally we mirror the navbar (sibling vs. linked-out). diff --git a/ecosystem-explorer-v1-mockups.html b/ecosystem-explorer-v1-mockups.html new file mode 100644 index 00000000..6474f012 --- /dev/null +++ b/ecosystem-explorer-v1-mockups.html @@ -0,0 +1,1191 @@ + + + + + + OTel Ecosystem Explorer — v1 Mockups (aligned with opentelemetry.io) + + + + + + +
+ v1 Mockups + aligned with opentelemetry.io · for issue #84 +
+ + + + +
+
+ + +
+ +
+ + +
+ +
+
+
+

+ OpenTelemetry Ecosystem Explorer +

+

+ Navigate every receiver, processor, exporter, and instrumentation across the OpenTelemetry project — searchable, comparable, version-aware. +

+
+ Browse components + Read the overview +
+ +
+
+ + + ⌘K +
+
+ Try: + otlp exporter + redis instrumentation + kafka receiver + trace sampling +
+
+
+
+ + +
+
+

The OpenTelemetry Ecosystem

+
+
+
12+
+
Languages
+
+
+
200+
+
Collector Components
+
+
+
1005+
+
Integrations
+
+
+
102+
+
Vendors
+
+
+
+
+ + +
+
+
+
+

Ecosystems

+

Browse the projects that make up OpenTelemetry.

+
+ View all projects → +
+
+
+ +
+
+
+ +
+
+

OpenTelemetry Collector

+ Vendor-agnostic agent +
+
+ stable +
+

Receive, process, and export telemetry data. 200+ receivers, processors, exporters, connectors and extensions.

+
+ 200+ components + v0.150.0 latest + 12 updated this week +
+ +
+
+ +
+
+
+ +
+
+

OpenTelemetry Java Agent

+ Auto-instrumentation +
+
+ stable +
+

Discover supported libraries, configuration options, and emitted telemetry for the Java auto-instrumentation agent.

+
+ 187 instrumentations + v2.10.0 latest + 8 updated this week +
+ +
+
+
+
+ +
Python SDK
+ Coming soon +
+
+
+
+
+
+ +
Go SDK
+ Coming soon +
+
+
+
+
+
+ +
JS / Node
+ Coming soon +
+
+
+
+
+
+ +
.NET
+ Coming soon +
+
+
+
+
+
+ + +
+
+
+
+

Browse by signal

+

Cuts across ecosystems. Match opentelemetry.io's canonical signal taxonomy.

+
+
+ + +
Traces
+
Distributed traces · 312 components
+ +
+
+ + +
Metrics
+
Measurements over time · 218
+ +
+
+ + +
Logs
+
Timestamped records · 147
+ +
+
+ + +
Baggage
+
Contextual metadata
+ +
+
+
+
+

Recent activity

+

What changed in the last 30 days, across all ecosystems.

+
+ +
+
+
+
+
+
+ + +
+ +
+
+ +
+
+ + +
+
+
+
+ Infrastructure · Vendor-agnostic agent +

+ OpenTelemetry Collector +

+

+ Receive, process, and export telemetry data without locking into a single vendor. Compose pipelines from receivers, processors, exporters, connectors, and extensions. +

+
+ Browse all 200+ components → + Read overview + GitHub +
+
+
+
+
+ Latest release +
+ v0.150.0 + 2 days ago +
+
+
+4
added
+
12
changed
+
2
deprecated
+
+
+
+
+
+
+
+ + +
+
+
+

Pipeline anatomy

+ Click any stage to filter components +
+
+ +
+ + Receivers +
+
98
+ Pull or accept telemetry + + → + +
+ + Processors +
+
42
+ Filter, batch, transform + + → + +
+ + Exporters +
+
76
+ Send to backends + + → + +
+ + Connectors +
+
14
+ Bridge pipelines + + + + +
+ + Extensions +
+
35
+ Auth, health, monitoring + +
+
+
+ + +
+
+
+
+ + Get started +

Most-used components

+

otlp · batch · resource · prometheus

+ +
+
+ + By distribution +

Core vs. Contrib

+

35 core components · 230 contrib

+ +
+
+ + Compare +

Diff across versions →

+

See what changed between any two releases

+ +
+
+
+
+
+ + +
+
+
+ +
+
+ +
+
+
+

Collector Components

+

Showing 42 of 200+ components

+
+
+ View: +
+ + + +
+ Sort: + +
+
+ + +
+ Active filters: + Type: receiver + Signal: traces + Distribution: contrib + +
+ +
+ + + + +
+
+ +
+
+
Name
+
Type
+
Signals
+
Stability
+
+ + + + +
+
Kafka Receiver kafkareceiver
+ Reads telemetry data from Kafka topics. Supports OTLP, Jaeger, and Zipkin payloads. +
+ Receiver + traces · metrics · logs + beta + + + + +
+
OTLP Receiver otlpreceiver
+ Accepts OTLP traces, metrics, and logs over gRPC and HTTP. +
+ Receiver + traces · metrics · logs + stable + + + + +
+
Prometheus Receiver prometheusreceiver
+ Scrapes Prometheus metrics from configured targets. +
+ Receiver + metrics + beta + + + + +
+
Jaeger Receiver jaegerreceiver
+ Receives traces in Jaeger formats over gRPC, HTTP, and Thrift. +
+ Receiver + traces + stable + + + + +
+
Zipkin Receiver zipkinreceiver
+ Receives spans from Zipkin clients in JSON or Thrift. +
+ Receiver + traces + stable + + + + +
+
Filelog Receiver filelogreceiver
+ Tails log files and parses them into OTel logs. +
+ Receiver + logs + beta + + + + +
+
Aerospike Receiver aerospikereceiver
+ Collects performance metrics from one or more Aerospike nodes. +
+ Receiver + metrics + alpha + + + +
+ Showing 1–8 of 42 + +
+
+
+
+
+
+ + +
+
+
+ +
+
+ +
+
+ + + + +
+ +
+
+ +
+
+ Receiver · contrib +
+ beta + v0.150.0 +
+
+

Kafka Receiver

+ kafkareceiver +

Reads telemetry data from Kafka topics. Supports OTLP, Jaeger, and Zipkin payloads. Configurable consumer groups, encoding, and TLS.

+
+ traces + metrics + logs + · + GitHub + Docs +
+
+
+
+ + +
+
+

Where this fits — in a typical pipeline

+
+ Kafka Receiver + → + batch + → + resource + → + otlp exporter +
+
+
+ + +
+
+ +
+
+

All configuration keys for kafkareceiver in v0.150.0.

+
+ + + + + + + + + + + +
KeyTypeDefaultDescription
brokers[]string["localhost:9092"]Kafka broker addresses.
topicstring"otlp_spans"Topic to subscribe to.
encodingenum"otlp_proto"Encoding of incoming records.
group_idstring"otel-collector"Consumer group identifier.
client_idstring"otel-collector"Sets the client ID for kafka.
+
+
+
+
+ + + +
+
+
+ + +
+
+

+ OpenTelemetry is a CNCF incubating project.
+ Formed through a merger of the OpenTracing and OpenCensus projects. +

+
+ [CNCF logo placeholder] +
+
+
+ + +
+
+
+
+
    +
    • +
    • +
    • +
    • +
    • +
    • +
    • +
+
+
+ © 2019–present OpenTelemetry Authors
+ Docs CC BY 4.0 · All Rights Reserved +
+
+
    +
    • +
    • +
    • +
    • +
    • +
    • +
+
+
+
+
+ + + + diff --git a/ecosystem-explorer/DESIGN.md b/ecosystem-explorer/DESIGN.md index cee1da78..02428e7a 100644 --- a/ecosystem-explorer/DESIGN.md +++ b/ecosystem-explorer/DESIGN.md @@ -1,298 +1,341 @@ # Design System -This document outlines the design principles, patterns, and tokens used in the OpenTelemetry Ecosystem Explorer. It -serves as a guide for AI agents and developers working on UI elements to ensure visual consistency and quality. +This document outlines the design principles, patterns, and tokens used in the OpenTelemetry Ecosystem Explorer. It serves as a guide for AI agents and developers working on UI elements to ensure visual consistency and quality. + +> **v1 update (2026-04):** the explorer is being aligned with [opentelemetry.io](https://opentelemetry.io). The site should feel like a sub-product of the OTel project, not a separate microsite. This guide reflects that alignment — see "Alignment with opentelemetry.io" at the bottom for the source-of-truth references. ## Overview -The Ecosystem Explorer uses a **dark-first design system** optimized for readability and visual hierarchy. The design -emphasizes: +The Ecosystem Explorer mirrors the visual language of opentelemetry.io: a Bootstrap-5-flavored layout with light + dark theming, an always-dark navbar, OTel brand purple/orange/yellow accents, and the Docsy-derived chrome (`td-*` patterns) translated into our Tailwind v4 stack. + +The design emphasizes: -- **Depth through subtlety** - Layered backgrounds, soft shadows, and ambient glows -- **Clarity first** - Clear information hierarchy through color, spacing, and typography -- **Consistent motion** - Unified animation timing and easing -- **Accessibility** - WCAG AA compliance with proper contrast and semantic markup +- **Continuity with opentelemetry.io** — same nav, footer, hero, type, and brand colors so visitors feel they're inside the same project +- **Light and dark parity** — every component must work in both themes; the theme toggle is part of the navbar +- **Clarity first** — clear information hierarchy through color, spacing, and typography +- **Consistent motion** — unified animation timing and easing +- **Accessibility** — WCAG AA compliance with proper contrast and semantic markup --- ## Design Principles -### 1. Depth Through Subtlety +### 1. Stay Visually Continuous With opentelemetry.io + +A user clicking from `opentelemetry.io/ecosystem/` to the Explorer should not feel they have left the site. That means: same logo lockup, same dark navbar, same primary buttons, same footer layout, same purple `#4f62ad` accent. Diverge only where the explorer needs richer interactivity (filters, three-pane detail) than the static Hugo site supports. -Create visual depth without overwhelming the interface: +### 2. Light + Dark Parity -- Use layered backgrounds (base -> pattern -> content -> overlay) -- Apply soft shadows and glows to establish elevation -- Employ subtle gradients for ambient lighting effects -- Keep depth cues understated - they should guide the eye, not dominate +Every page must render correctly in both light and dark themes. The navbar is always dark (matching opentelemetry.io). The body switches between a light surface (`#ffffff` / `#f8f9fa`) and a dark surface (`#0b0d12` / `#11141b`) based on `data-bs-theme`. Pick tokens, not hardcoded colors. -### 2. Clarity First +### 3. Clarity First Information hierarchy guides users naturally: -- Primary actions use the vibrant orange (`--color-primary`) -- Secondary information uses the blue accent (`--color-secondary`) +- Primary actions use OTel orange/yellow (`--color-primary`) +- Secondary or branding accents use OTel purple (`--color-secondary`) - Background elements recede through lower contrast - Whitespace provides visual breathing room -### 3. Consistent Motion +### 4. Consistent Motion All animations follow a unified timing system: -- Default transition: `300ms ease-in-out` -- Micro-interactions: `200ms ease-out` -- Complex animations: `400ms ease-in-out` +- Default transition: `200ms ease-in-out` (matches Bootstrap defaults) +- Micro-interactions: `150ms ease-out` +- Complex animations: `300ms ease-in-out` - Use `transform` and `opacity` for performant animations +- Honor `prefers-reduced-motion` -### 4. Dark-First Design +--- -Optimized for extended viewing in low-light environments: +## Color System -- Deep navy base (`--color-background`) -- Bright, high-contrast text (`--color-foreground`) -- Reduced blue light through warm accent colors -- Subtle glows instead of harsh borders +### Brand Tokens (aligned with opentelemetry.io) ---- +opentelemetry.io exposes these colors via meta tags and stylesheets: -## Color System +| Token | Source | Hex | +|---|---|---| +| OTel Purple (brand) | ``, `mask-icon`, `msapplication-TileColor` | `#4f62ad` | +| OTel Orange/Yellow (accent) | Logo gradient end stop, kapa `data-project-color` | `#f5a800` | +| Light surface | Default page bg | `#ffffff` | +| Dark surface | `prefers-color-scheme: dark` page bg | `#0b0d12` | +| Light text | Default | near-black | +| Dark text | dark mode | `#e6e6e6` | -### HSL Token Reference +### CSS Custom Properties -All colors are defined using HSL values in `src/themes.ts`. They are applied via CSS custom properties: +All colors are defined in `src/themes.ts` and applied as CSS custom properties. **HSL is preferred** so we can derive variants with opacity: ```css ---color-primary: 38 95% 52%; /* Vibrant orange */ ---color-secondary: 228 60% 55%; /* Brighter blue */ ---color-background: 232 38% 15%; /* Deep navy */ ---color-foreground: 210 45% 99%; /* Bright white with blue hint */ ---color-card: 232 35% 19%; /* Card background */ ---color-card-secondary: 232 32% 23%; /* Card hover state */ ---color-muted: 232 30% 17%; /* Darker background for code/badges */ ---color-muted-foreground: 220 22% 65%; /* Muted text */ ---color-border: 232 28% 26%; /* Borders */ +/* Brand */ +--color-primary: 38 95% 52%; /* OTel orange/yellow #f5a800 */ +--color-primary-foreground: 0 0% 0%; +--color-secondary: 230 38% 49%; /* OTel purple #4f62ad */ +--color-secondary-foreground: 0 0% 100%; + +/* Light theme (default) */ +--color-background: 0 0% 100%; /* #ffffff */ +--color-foreground: 220 13% 15%; /* near-black */ +--color-card: 210 17% 98%; /* #f8f9fa surface */ +--color-card-secondary: 210 14% 95%; +--color-muted: 210 14% 92%; +--color-muted-foreground: 220 9% 40%; +--color-border: 210 14% 88%; + +/* Dark theme — applied via [data-bs-theme="dark"] */ +[data-bs-theme="dark"] { + --color-background: 222 25% 6%; /* #0b0d12 */ + --color-foreground: 0 0% 90%; /* #e6e6e6 */ + --color-card: 222 23% 9%; /* #11141b */ + --color-card-secondary: 222 22% 13%; + --color-muted: 222 22% 11%; + --color-muted-foreground: 220 14% 65%; + --color-border: 222 18% 22%; +} + +/* Always-dark navbar — matches opentelemetry.io */ +.navbar-otel { + --color-background: 222 25% 6%; + --color-foreground: 0 0% 95%; +} +``` + +### Semantic Tokens + +```css +--color-success: 145 63% 42%; /* stable */ +--color-info: 200 85% 45%; /* beta / informational */ +--color-warning: 38 95% 52%; /* alpha — uses brand orange */ +--color-error: 0 70% 50%; /* deprecated / unmaintained */ ``` ### Usage Guidelines -#### Primary (Orange) +#### Primary (OTel Orange/Yellow `#f5a800`) -- Primary CTAs and important actions -- Links and interactive elements -- Accent highlights and focus states -- Sparingly used to draw attention +- Primary CTAs (matches `btn btn-primary` in opentelemetry.io) +- The "alpha" stability pill +- Highlight accents in stats and gradient text -#### Secondary (Blue) +#### Secondary (OTel Purple `#4f62ad`) -- Secondary actions and information -- Decorative accents and gradients -- Category indicators -- Complements primary without competing +- Branded surfaces (the `td-box--primary` stats band on opentelemetry.io is purple — we should match) +- Hero background tint and gradient stops +- Secondary buttons in dark mode (`btn btn-secondary`) +- Iconography for ecosystem cards #### Background Layers -- `background` - Page base -- `card` - Elevated surfaces (cards, panels) -- `card-secondary` - Hover states and nested cards -- `muted` - Darker backgrounds for inline code, type badges, and subtle UI elements -- `border` - Dividers and outlines +- `background` — page base (light or dark depending on theme) +- `card` — elevated surfaces +- `card-secondary` — hover states and nested cards +- `muted` — table-row striping, code chips, type badges +- `border` — dividers and outlines #### Text Hierarchy -- `foreground` - Primary text (headings, body) -- `muted-foreground` - Secondary text (captions, labels) -- Lower opacity variants - Tertiary text +- `foreground` — primary text (headings, body) +- `muted-foreground` — secondary text (captions, labels) +- Lower opacity variants — tertiary text --- -## Depth and Elevation +## Typography -### Shadow Scale +### Font Stack -Shadows establish elevation and focus: +Match opentelemetry.io: a sans serif for UI, mono for code. The site uses the Bootstrap/Docsy default (system stack), so we use the same: ```css ---shadow-sm: 0 1px 2px 0 hsl(0 0% 0% / 0.05); ---shadow-md: 0 4px 6px -1px hsl(0 0% 0% / 0.1); ---shadow-lg: 0 10px 15px -3px hsl(0 0% 0% / 0.1); +font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; +font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; /* code */ ``` -### Glow Effects +### Size Scale -Glows create ambient lighting and highlight interactive elements: +Use the Bootstrap display scale for hero text, then a tighter Tailwind scale for body. Don't invent new sizes. -```css ---glow-primary: 0 0 40px hsl(var(--primary-hsl) / 0.15); ---glow-secondary: 0 0 40px hsl(var(--secondary-hsl) / 0.15); -``` +| Use | Size | Weight | +|---|---|---| +| Hero headline (matches `display-4` / `display-6`) | 3rem–3.75rem | 600 | +| Page title (matches `h1`) | 2.25rem | 700 | +| Section heading (`h2`) | 1.75rem | 700 | +| Subsection (`h3`) | 1.25rem | 600 | +| Body | 1rem | 400 | +| Small / muted (`small`) | 0.875rem | 400 | +| Eyebrow / pill | 0.75rem uppercase tracking-widest | 600 | -**Usage patterns:** +### Weight Conventions -- Primary glow: Hero elements, important features -- Secondary glow: Decorative accents, section transitions -- Hover states: Increase opacity to 0.25 for prominence +- `font-normal` (400): Body text +- `font-medium` (500): Emphasized text, labels +- `font-semibold` (600): Subheadings, buttons +- `font-bold` (700): Primary headings -### Layering Strategy +--- -Visual layers from back to front: +## Layout Primitives (mirroring Docsy) -1. **Background** - Solid color or subtle gradient -2. **Pattern** - Grid or texture overlay (low opacity) -3. **Content** - Cards, text, images -4. **Overlay** - Glows, shadows, focus rings +The Hugo Docsy theme on opentelemetry.io uses these structural classes. We re-implement them in Tailwind so that templates feel familiar to anyone moving between codebases. ---- +| Docsy class | Our equivalent | Purpose | +|---|---|---| +| `td-navbar` | `
` | Always-dark top navbar with logo + nav + search + lang + theme toggle | +| `td-cover-block` | `
` | Hero with dark overlay over a background image | +| `td-box td-box--white` | `
` | Light-surface section | +| `td-box td-box--primary` | `
` | OTel purple-tinted feature band (e.g. ecosystem stats) | +| `td-box td-box--secondary` | `
` | Subtle gray section (e.g. CNCF callout) | +| `td-footer` | `
- - -
-
-

- OpenTelemetry is a CNCF incubating project.
- Formed through a merger of the OpenTracing and OpenCensus projects. -

-
- [CNCF logo placeholder] -
-
-
- - -
-
-
-
-
    -
    • -
    • -
    • -
    • -
    • -
    • -
    • -
-
-
- © 2019–present OpenTelemetry Authors
- Docs CC BY 4.0 · All Rights Reserved -
-
-
    -
    • -
    • -
    • -
    • -
    • -
    • -
-
-
-
-
- - - - diff --git a/projects/84-ui-ux-design/ecosystem-explorer-v1-design-brief.md b/projects/84-ui-ux-design/ecosystem-explorer-v1-design-brief.md new file mode 100644 index 00000000..e97fa969 --- /dev/null +++ b/projects/84-ui-ux-design/ecosystem-explorer-v1-design-brief.md @@ -0,0 +1,253 @@ +--- +title: "v1 design proposal — Ecosystem Explorer" +issue: 84 +type: brief +phase: meta +status: complete +last_updated: "2026-05-08" +--- + +# v1 design proposal — Ecosystem Explorer + +> Brainstorm for +> [#84 — \[Explorer\] UI/UX Design](https://github.com/open-telemetry/opentelemetry-ecosystem-explorer/issues/84). +> Builds on `DESIGN.md` and **aligns the explorer to the existing visual language of +> [opentelemetry.io](https://opentelemetry.io)**. Mockup HTML is included alongside this doc as +> `ecosystem-explorer-v1-mockups.html` — it's a static prototype with a tab switcher across all four +> page types and a working light/dark theme toggle. + +--- + +## TL;DR + +The placeholder design felt like a separate microsite rather than part of the OTel project. **The +fix is alignment, not redesign.** This proposal standardizes the explorer on the same visual grammar +as opentelemetry.io: same dark navbar, same light/dark theme toggle, same OTel purple `#4f62ad` and +orange `#f5a800`, same Bootstrap-flavored chrome (Docsy `td-*` patterns), same footer, same CNCF +callout, same canonical stats numbers ("12+ Languages · 200+ Collector Components · 1005+ +Integrations · 102+ Vendors"). + +On top of that shared scaffold, the explorer adds the things opentelemetry.io can't: real faceted +filtering with URL state, a three-pane component detail page with version timeline + diff, density +toggles (Cards / Compact / Table), and pipeline-anatomy diagrams. + +A user clicking from `opentelemetry.io/ecosystem/` to the Explorer should not feel they have left +the site. + +--- + +## Why alignment first + +The previous iteration of this brief proposed a strong direction ("The Catalog") with thoughtful IA. +What it didn't do was **lock the visual language to what opentelemetry.io already publishes**. Once +you put the two side by side, the gap is obvious: + +| Element | opentelemetry.io | v0 placeholder | v1 (this proposal) | +| ----------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------- | ----------------------------------------------- | +| Theme support | Light + Dark + Auto (toggle in navbar, persisted to `td-color-theme` in `localStorage`) | Dark-only | **Light + Dark + Auto** (same key, same toggle) | +| Brand purple | `#4f62ad` (theme-color, mask-icon, primary stats band) | Not used | **`#4f62ad` adopted as `--color-secondary`** | +| Brand orange | `#f5a800` (logo gradient, kapa accent) | `38 95% 52%` HSL ≈ `#f5a800` | Already aligned ✓ | +| Topnav | Always-dark `td-navbar`: Docs · Ecosystem · Status · Community · Training · Blog · search · lang · theme | Custom 2-link bar | **Mirror full structure**, add Explorer entry | +| Stats numbers | "12+ · 200+ · 1005+ · 102+" | Made up our own | **Match canonical numbers** | +| Signals | Traces · Metrics · Logs · **Baggage** | Had Profiles | **Switch to Baggage** | +| Footer | Two clusters of Font Awesome social icons + centered copyright | Custom | **Mirror Docsy footer** | +| Hero | `td-cover-block` with bg image + dark overlay + centered content + `btn-lg btn-primary/btn-secondary` | Generic gradient | **Use cover-block** | +| CNCF callout | On every page (`td-box--secondary`) | Missing | **Add to every page** | +| Component pattern | Bootstrap `.card` with `border-success` etc. + `text-bg-*` badges | Custom | **Adopt** + extend with type stripe | +| Theme tokens | `data-bs-theme` attribute | Tailwind v4 only | **Keep existing `data-theme` attribute, extend to light/dark/auto** (decided 2026-05-08; explorer isn't on Bootstrap, so `data-bs-theme` would be misleading) | + +This is now reflected in the updated `DESIGN.md` ("Alignment with opentelemetry.io" section) and +visible in the mockup. + +--- + +## What's working in v0 that we keep + +- The OTel orange (`#f5a800`) was already aligned — kept as `--color-primary` +- The card hover state (subtle scale + shadow) feels right and translates cleanly into Bootstrap + card patterns +- The gradient text treatment for hero headlines is a nice signature element worth keeping (now + using `purple → orange` to match the OTel logo) +- The grid-pattern background overlay for hero sections is a low-cost depth cue worth keeping + +## What changes from v0 + +- **Visual chrome** entirely re-platformed onto Bootstrap 5 + Docsy `td-*` patterns to match + opentelemetry.io +- **Light theme** added as the default (with dark + auto as toggle options) +- **Brand purple** introduced as `--color-secondary` and used for stats band, brand accents, + breadcrumb active state +- **Stats** sourced from opentelemetry.io's canonical numbers +- **Signals** corrected to use `Baggage` instead of `Profiles` +- **CNCF incubating project** callout added to every page +- **Footer** restructured to two-cluster Font Awesome layout matching opentelemetry.io +- **Status pill mapping** locked to Bootstrap `text-bg-*` (success/info/warning/danger) for + portability + +--- + +## Direction: "The Catalog" — unchanged in spirit, re-skinned + +The recommended direction remains "The Catalog" (treat the explorer like the npm/crates.io of +OpenTelemetry — searchable, comparable, version-aware). The improvements borrowed from "Atlas" +(pipeline diagrams) and "Dashboard" (version timeline + diff) are still in play. What's new is that +all of it now lives inside the visual frame of opentelemetry.io. + +--- + +## Page-by-page spec + +### 1. Explorer home page + +**Goal:** answer "what is this site, and what's in it?" in five seconds. Look unmistakably like a +sub-page of opentelemetry.io. + +**Layout (top to bottom):** + +1. **Always-dark Docsy navbar** — Docs · Ecosystem (active) · Status · Community · Training · Blog · + search · lang · theme toggle. +2. **Sub-nav** for the explorer (breadcrumb-only on the home page). +3. **Cover-block hero** — radial gradient + grid pattern background, OTel logo mark, "OpenTelemetry + Ecosystem Explorer" gradient headline, lead copy, two CTAs (`btn-lg` primary orange + + outline-light), and a glass-effect ⌘K-able global search input with chips. +4. **Stats band** (`box-primary`, OTel purple) — "12+ Languages · 200+ Collector Components · 1005+ + Integrations · 102+ Vendors". Numbers link out to relevant pages, matching opentelemetry.io's + pattern exactly. +5. **Ecosystems grid** — Collector and Java Agent as primary cards (with stability pill, count, + latest version, "updated this week"), plus dashed "coming soon" cards for Python, Go, JS, .NET. +6. **Browse by signal** — four signal cards (Traces / Metrics / Logs / Baggage) matching + opentelemetry.io's homepage. +7. **Recent activity** rail — last-30-days feed with status pills and ecosystem labels. +8. **CNCF callout** + Docsy footer. + +**Why this beats the placeholder:** the visitor sees scale (canonical numbers) and recency above the +fold, plus a global search. The page chrome is indistinguishable from opentelemetry.io. + +### 2. Individual ecosystem landing + +**Goal:** orient a user to _this_ project, then send them to the list with sensible defaults. + +**Layout:** + +1. **Sub-nav with breadcrumbs**: `Explorer › Ecosystems › Collector`. +2. **Cover-block hero** — eyebrow, gradient title, description, three CTAs (Browse, Read overview, + GitHub), and a "Latest release" card on the right with `+4 added · 12 changed · 2 deprecated` + deltas. +3. **Pipeline anatomy** — five clickable stage cards (Receivers 98 → Processors 42 → Exporters 76 → + Connectors 14 + Extensions 35), each as a one-click filter into the list. Color stripes on the + indicator dots match the type-stripe taxonomy. +4. **Quick entry** — three cards (Most-used components · Core vs. Contrib · Diff across versions). +5. **CNCF + footer.** + +### 3. List pages + +**Goal:** make 200+ components actually browseable. + +**Layout:** + +- **Sub-nav with breadcrumbs.** +- **Page header**: gradient title, result count, view toggle (Cards / Compact / Table — Compact is + default), sort dropdown. +- **Active filter chips** as Bootstrap `badge text-bg-secondary rounded-pill` with × dismiss. +- **Left-rail facets** (Bootstrap form): Search · Type (with color-stripe indicators) · Signal · + Stability · Distribution (core/contrib) · Version. Each facet shows count alongside the label. +- **Compact result list** in a `.card` with grid rows: + `[type-stripe | name + slug + description | type | signals | stability pill]`, alternating row + backgrounds, sticky header, Bootstrap pagination footer. +- **URL-persisted filter state** (`?type=receiver&signal=traces&distribution=contrib`). + +**Status-pill mapping (locked):** `stable=text-bg-success`, `beta=text-bg-info`, +`alpha=text-bg-warning`, `unmaintained|deprecated=text-bg-danger`. + +**Type stripe (4px left edge):** receiver=info-blue, processor=purple, exporter=orange, +connector=pink, extension=teal. + +### 4. Component detail page + +**Goal:** be the canonical page for a component — overview, configuration, and what changed across +versions. + +**Layout (three-pane):** + +- **Sub-nav with full breadcrumbs**: `Explorer › Collector › Receivers › Kafka Receiver`. +- **Left rail (sticky):** sibling navigator (98 receivers, with current highlighted in OTel + orange) + on-page anchor links. +- **Center column:** + - Header card with type stripe + eyebrow + title + slug + stability pill + version + signal + badges + GitHub/Docs links. + - **"Where this fits"** mini-pipeline diagram showing the component placed inside a typical + pipeline. + - Tabbed content area (Bootstrap `nav-tabs`): **Configuration** (Bootstrap striped table with + Key/Type/Default/Description), **README**, **Emitted attributes**, **Examples**. +- **Right rail (sticky):** + - **Version history timeline** — vertical timeline with current version highlighted in green, + per-version changes summarized, with a `Compare` selector and a "Diff →" link. + - **Compatibility card** — Min collector, Min Go, Distribution, License. + +**Empty/error states:** spec four — _not yet released for this version_, _deprecated/removed_, +_missing data_, _no docs yet_. Each gets a designed empty state, not a stack trace. + +--- + +## Cross-cutting principles + +1. **Continuity with opentelemetry.io is the spine.** Every component should look at home if dropped + into the parent site. +2. **Light + dark parity.** No dark-only components. No light-only components. The theme toggle + (persisted to `td-color-theme` in `localStorage`) flips both. +3. **Density toggles, not redesigns.** Every list view remembers the user's last density choice. +4. **URL is the state.** Every filter, sort, and tab is reflected in the URL so links are shareable. +5. **Status legibility before everything else.** Stability and distribution should be perceivable in + <300ms scanning. +6. **One small diagram beats one paragraph.** Pipeline diagrams on the ecosystem landing and detail + pages do more than 200 words of intro copy. +7. **Empty states are first-class.** "Component missing in this version" is information, not an + error. +8. **CNCF on every page.** Non-negotiable — opentelemetry.io shows it everywhere and we need to + match. + +--- + +## Suggested sub-issues to break out of #84 + +If this lands well, the work splits naturally: + +- [ ] Theme system — extend the existing `data-theme` attribute to light/dark/auto, persist to + `td-color-theme`, write contrast tests for both themes +- [ ] Navbar component — match opentelemetry.io structurally and visually; add explorer-specific + sub-nav +- [ ] Footer component — Docsy two-cluster pattern with Font Awesome icons +- [ ] CNCF callout — reusable component on every route +- [ ] Stats band — fed from a single source of truth synced with the canonical numbers on + opentelemetry.io +- [ ] Home page — hero (cover-block) + global search + recent activity +- [ ] Ecosystem landing — pipeline anatomy diagram (reusable component) +- [ ] List page — facet rail + density toggle + URL state + chip system +- [ ] Detail page layout — three-pane shell + sibling navigator +- [ ] Detail page — embedded README/config-table renderer (Bootstrap striped tables) +- [ ] Detail page — version timeline + diff view +- [ ] Status-pill / type-stripe mapping spec → already added to `DESIGN.md` +- [ ] Empty/error state library (4 patterns) + +Each is small enough for one contributor to own. + +--- + +## Mockup + +A static, clickable HTML prototype with all four pages (Home / Ecosystem / List / Detail) and a +top-bar switcher is included as `ecosystem-explorer-v1-mockups.html`. It uses Bootstrap 5 + Font +Awesome (matching opentelemetry.io's stack) and supports the same theme toggle pattern. Open in a +browser, click between the four tabs, and toggle the theme to see both modes. + +## Open questions + +- Should the explorer's home-page **search bar** actually search across ecosystems, or just be a + launcher into per-ecosystem search? +- For the **detail page version diff**, do we have the underlying data (per-version config schemas, + deprecation markers) in `ecosystem-registry`/`ecosystem-automation` already, or is that a + data-pipeline prerequisite? +- Status terminology in the data is currently mixed (`alpha`/`beta`/`development`/`unmaintained`). + Worth aligning to one taxonomy before locking pill colors. +- Will the explorer eventually live at `opentelemetry.io/ecosystem/explorer/` or as a separate + domain? That decision affects how literally we mirror the navbar (sibling vs. linked-out). diff --git a/projects/84-ui-ux-design/ecosystem-explorer-v1-mockups.html b/projects/84-ui-ux-design/ecosystem-explorer-v1-mockups.html new file mode 100644 index 00000000..80b1a6eb --- /dev/null +++ b/projects/84-ui-ux-design/ecosystem-explorer-v1-mockups.html @@ -0,0 +1,1859 @@ + + + + + + OTel Ecosystem Explorer — v1 Mockups (aligned with opentelemetry.io) + + + + + + +
+ v1 Mockups + aligned with opentelemetry.io · for issue #84 +
+ + + + +
+
+ + +
+ +
+ + +
+ +
+
+
+

+ OpenTelemetry Ecosystem Explorer +

+

+ Navigate every receiver, processor, exporter, and instrumentation across the + OpenTelemetry project — searchable, comparable, version-aware. +

+
+ Browse components + Read the overview +
+ +
+
+ + + ⌘K +
+
+ Try: + otlp exporter + redis instrumentation + kafka receiver + trace sampling +
+
+
+
+ + +
+
+

The OpenTelemetry Ecosystem

+
+
+
12+
+
Languages
+
+
+
200+
+
Collector Components
+
+
+
1005+
+
Integrations
+
+
+
102+
+
Vendors
+
+
+
+
+ + +
+
+
+
+

Ecosystems

+

Browse the projects that make up OpenTelemetry.

+
+ View all projects → +
+
+
+ +
+
+
+ +
+
+

OpenTelemetry Collector

+ Vendor-agnostic agent +
+
+ stable +
+

+ Receive, process, and export telemetry data. 200+ receivers, processors, + exporters, connectors and extensions. +

+
+ 200+ components + v0.150.0 latest + 12 updated this week +
+ +
+
+ +
+
+
+ +
+
+

OpenTelemetry Java Agent

+ Auto-instrumentation +
+
+ stable +
+

+ Discover supported libraries, configuration options, and emitted telemetry for the + Java auto-instrumentation agent. +

+
+ 187 instrumentations + v2.10.0 latest + 8 updated this week +
+ +
+
+
+
+ +
Python SDK
+ Coming soon +
+
+
+
+
+
+ +
Go SDK
+ Coming soon +
+
+
+
+
+
+ +
JS / Node
+ Coming soon +
+
+
+
+
+
+ +
.NET
+ Coming soon +
+
+
+
+
+
+ + +
+
+
+
+

Browse by signal

+

+ Cuts across ecosystems. Match opentelemetry.io's canonical signal taxonomy. +

+
+
+ + +
Traces
+
Distributed traces · 312 components
+ +
+
+ + +
Metrics
+
Measurements over time · 218
+ +
+
+ + +
Logs
+
Timestamped records · 147
+ +
+
+ + +
Baggage
+
Contextual metadata
+ +
+
+
+
+

Recent activity

+

+ What changed in the last 30 days, across all ecosystems. +

+
+ +
+
+
+
+
+
+ + +
+ +
+
+ +
+
+ + +
+
+
+
+ Infrastructure · Vendor-agnostic agent +

+ OpenTelemetry Collector +

+

+ Receive, process, and export telemetry data without locking into a single vendor. + Compose pipelines from receivers, processors, exporters, connectors, and extensions. +

+
+ Browse all 200+ components → + Read overview + GitHub +
+
+
+
+
+ Latest release +
+ v0.150.0 + 2 days ago +
+
+
+
+
+4
+ added +
+
+
+
+
12
+ changed +
+
+
+
+
2
+ deprecated +
+
+
+
+
+
+
+
+
+ + +
+
+
+

Pipeline anatomy

+ Click any stage to filter components +
+
+ +
+ + Receivers +
+
98
+ Pull or accept telemetry + + → + +
+ + Processors +
+
42
+ Filter, batch, transform + + → + +
+ + Exporters +
+
76
+ Send to backends + + → + +
+ + Connectors +
+
14
+ Bridge pipelines + + + + +
+ + Extensions +
+
35
+ Auth, health, monitoring + +
+
+
+ + +
+
+
+
+ + Get started +

Most-used components

+

otlp · batch · resource · prometheus

+ +
+
+ + By distribution +

Core vs. Contrib

+

35 core components · 230 contrib

+ +
+
+ + Compare +

Diff across versions →

+

See what changed between any two releases

+ +
+
+
+
+
+ + +
+
+
+ +
+
+ +
+
+
+

+ Collector Components +

+

+ Showing 42 of 200+ components +

+
+
+ View: +
+ + + +
+ Sort: + +
+
+ + +
+ Active filters: + Type: receiver + Signal: traces + Distribution: contrib + +
+ +
+ + + + +
+
+ +
+
+
Name
+
Type
+
Signals
+
Stability
+
+ + + + +
+
+ Kafka Receiver kafkareceiver +
+ Reads telemetry data from Kafka topics. Supports OTLP, Jaeger, and Zipkin + payloads. +
+ Receiver + traces · metrics · logs + beta + + + + +
+
+ OTLP Receiver otlpreceiver +
+ Accepts OTLP traces, metrics, and logs over gRPC and HTTP. +
+ Receiver + traces · metrics · logs + stable + + + + +
+
+ Prometheus Receiver + prometheusreceiver +
+ Scrapes Prometheus metrics from configured targets. +
+ Receiver + metrics + beta + + + + +
+
+ Jaeger Receiver jaegerreceiver +
+ Receives traces in Jaeger formats over gRPC, HTTP, and Thrift. +
+ Receiver + traces + stable + + + + +
+
+ Zipkin Receiver zipkinreceiver +
+ Receives spans from Zipkin clients in JSON or Thrift. +
+ Receiver + traces + stable + + + + +
+
+ Filelog Receiver filelogreceiver +
+ Tails log files and parses them into OTel logs. +
+ Receiver + logs + beta + + + + +
+
+ Aerospike Receiver aerospikereceiver +
+ Collects performance metrics from one or more Aerospike nodes. +
+ Receiver + metrics + alpha + + + +
+ Showing 1–8 of 42 + +
+
+
+
+
+
+ + +
+
+
+ +
+
+ +
+
+ + + + +
+ +
+
+ +
+
+ Receiver · contrib +
+ beta + v0.150.0 +
+
+

Kafka Receiver

+ kafkareceiver +

+ Reads telemetry data from Kafka topics. Supports OTLP, Jaeger, and Zipkin + payloads. Configurable consumer groups, encoding, and TLS. +

+
+ traces + metrics + logs + · + GitHub + Docs +
+
+
+
+ + +
+
+

+ Where this fits + — in a typical pipeline +

+
+ Kafka Receiver + → + batch + → + resource + → + otlp exporter +
+
+
+ + +
+
+ +
+
+

+ All configuration keys for kafkareceiver in v0.150.0. +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KeyTypeDefaultDescription
brokers[]string["localhost:9092"]Kafka broker addresses.
topicstring"otlp_spans"Topic to subscribe to.
encodingenum"otlp_proto"Encoding of incoming records.
group_idstring"otel-collector"Consumer group identifier.
client_idstring"otel-collector"Sets the client ID for kafka.
+
+
+
+
+ + + +
+
+
+ + +
+
+

+ OpenTelemetry is a + CNCF + incubating project.
+ Formed through a merger of the OpenTracing and OpenCensus projects. +

+
[CNCF logo placeholder]
+
+
+ + +
+
+
+
+
    +
  • + +
    • +
  • + +
    • +
  • + +
    • +
  • + +
    • +
  • + +
    • +
  • + +
    • +
  • + +
    • +
+
+
+ © 2019–present OpenTelemetry Authors
+ Docs CC BY 4.0 · All Rights Reserved +
+
+
    +
  • + +
    • +
  • + +
    • +
  • + +
    • +
  • + +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+
+ + + + From af5341e740d502764d923060fce4b2fed01841d5 Mon Sep 17 00:00:00 2001 From: Vitor Vasconcellos Date: Wed, 6 May 2026 07:42:49 -0300 Subject: [PATCH 04/37] docs: initialize project overview documentation Signed-off-by: Vitor Vasconcellos --- .../84-ui-ux-design/00-foundation-audit.md | 479 ++++++++++++++++++ projects/84-ui-ux-design/00-foundation.md | 108 ++++ 2 files changed, 587 insertions(+) create mode 100644 projects/84-ui-ux-design/00-foundation-audit.md create mode 100644 projects/84-ui-ux-design/00-foundation.md diff --git a/projects/84-ui-ux-design/00-foundation-audit.md b/projects/84-ui-ux-design/00-foundation-audit.md new file mode 100644 index 00000000..b9a4f39f --- /dev/null +++ b/projects/84-ui-ux-design/00-foundation-audit.md @@ -0,0 +1,479 @@ +--- +title: "Phase 1 — Foundation: Codebase audit" +issue: 84 +type: audit +phase: 1 +status: planning +last_updated: "2026-05-08" +--- + +> [!NOTE] +> +> This file was drafted in collaboration with Claude Opus 4.7. Corrections are welcome. + +# Phase 1 — Foundation: Codebase Audit + +Companion to [`00-foundation.md`](./00-foundation.md). This is the "state of the explorer today": +what's already in `ecosystem-explorer/src/`, what we can reuse, and the concrete delta per +foundation task before we open the first PR. + +--- + +## TL;DR + +The codebase is in **much better shape than the placeholder screenshots suggested**. It's a real +React 19 + TypeScript 6 + Vite 8 + Tailwind v4 app with a feature-organized `src/features//` +layout, a typed feature-flag system already in production use, a theme provider, an API + IDB cache +layer, and a substantial UI primitive library (`components/ui/*`). + +That changes Phase 1 from "build foundation" to **"extend and align an existing foundation"**. Most +of the 11 tasks in `00-foundation.md` already have partial implementations we can build on instead +of replacing. + +The migration plan is now concrete: add a `V1_REDESIGN` flag to the existing `lib/feature-flags.ts` +and use the same `isEnabled(...)` pattern that already gates `JAVA_CONFIG_BUILDER` and +`COLLECTOR_PAGE`. No new infrastructure. + +--- + +## Stack snapshot + +| Layer | What's there | +| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Framework | React 19, TypeScript 6, Vite 8 (`@vitejs/plugin-react-swc`) | +| Routing | `react-router-dom@7` with `BrowserRouter` | +| Styling | Tailwind v4 via `@tailwindcss/postcss`. **No `tailwind.config.*` file** — Tailwind v4 uses an `@theme` block inside `src/index.css` | +| UI primitives | Radix UI (`react-hover-card`, `react-tabs`, `react-tooltip`), Lucide React icons, custom UI library at `src/components/ui/*` | +| Markdown | `react-markdown` + `remark-gfm` | +| Data | `idb` (IndexedDB) with custom cache (`lib/api/idb-cache.ts`); typed fetchers per ecosystem (`javaagent-data`, `collector-data`, `configuration-data`); custom `fetch-with-cache` | +| Telemetry | Grafana Faro (`@grafana/faro-react`, `@grafana/faro-web-tracing`) | +| Testing | Vitest 4 (unit, co-located `*.test.tsx`), separate integration suite (`vitest.integration.config.ts`), Testing Library, `fake-indexeddb`, **Playwright 1.59 installed but not yet configured for visual regression** | +| Lint/format | ESLint 10, Prettier 3 with `prettier-plugin-tailwindcss` | +| Build | `tsc -b && vite build`; deployed via Netlify (`netlify-build:preview`, `netlify-build:production`) | + +## File layout + +```text +src/ +├── App.tsx ← BrowserRouter + Routes; some routes are flag-gated +├── main.tsx ← entry; ThemeProvider lives here +├── index.css ← Tailwind import + @theme block + global styles +├── themes.ts ← Theme definitions (currently: only "dark-blue") +├── theme-context.tsx ← React context that injects HSL custom properties +├── faro.ts ← Telemetry init +├── components/ +│ ├── icons/ ← OtelLogo, GitHubIcon, JavaIcon, CompassIcon, … +│ ├── layout/ ← Header, Footer, PageContainer (CURRENT shell) +│ └── ui/ ← GlowBadge, StabilityBadge, Tabs, Tooltip, NavigationCard, SegmentedTabs, … +├── features/ +│ ├── home/ ← HomePage + HeroSection + ExploreSection +│ ├── collector/ ← CollectorPage + CollectorDetailPage (the broken one) +│ ├── java-agent/ ← Java agent ecosystem (large; has full config builder) +│ ├── about/ ← About page +│ └── not-found/ ← 404 +├── hooks/ ← Data hooks: use-collector-data, use-javaagent-data, use-configuration-data +├── lib/ +│ ├── feature-flags.ts ← Typed flag system (used by App.tsx) +│ ├── api/ ← Data fetchers + IDB cache +│ └── … ← yaml-generator, schema-defaults, validation, etc. +├── types/ ← Domain types (collector, javaagent, configuration) +└── test/integration/ ← Integration test suite + helpers +``` + +--- + +## What we can reuse (don't rebuild) + +| Foundation task | Already exists | Path | Status | +| ----------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| Theme system | `ThemeProvider` + HSL custom properties | `src/theme-context.tsx`, `src/themes.ts`, `src/index.css` | **Extend** to support light + dark + auto | +| NavBar | Sticky header with logo + 2 nav links | `src/components/layout/header.tsx` | **Replace** with opentelemetry.io-style navbar (gated by V1_REDESIGN) | +| Footer | 3-column footer with OTel branding | `src/components/layout/footer.tsx` | **Replace** with two-cluster Docsy-style footer (gated) | +| StatusPill | `` + `` | `src/components/ui/stability-badge.tsx`, `src/components/ui/glow-badge.tsx` | **Add new `` primitive** in PR 4 — covers all six OTel stability levels (development / alpha / beta / stable / deprecated / unmaintained). Leaves `` alone for now; migration is a follow-up cleanup PR after Phase 1. `GlowBadge` gains a `secondary` variant for `development` and an `error/danger` variant for `deprecated/unmaintained`. | +| Card primitive | ``, `` | `src/components/ui/navigation-card.tsx`, `src/components/ui/detail-card.tsx` | **Audit + extend** — see if either is general enough to host the type-stripe slot | +| TypeStripe | — | — | **New primitive** | +| CncfCallout | — | — | **New primitive** | +| Feature flagging | `lib/feature-flags.ts` with typed `FEATURE_FLAGS` array | `src/lib/feature-flags.ts` | **Reuse as-is** — add `V1_REDESIGN` to the array | +| OtelLogo | Local SVG component | `src/components/icons/otel-logo.tsx` | **Reuse as-is** — answers the "logo source" open question | +| Visual regression | Playwright installed | `package.json`, no config yet | **Configure** — first time anyone wires it up | + +## What's incomplete or drifting today + +| Issue | Where | Impact | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Color drift between `index.css` and `themes.ts`.** `index.css` `@layer theme` has cyan values (`--primary-hsl: 185 85% 70%`) but `themes.ts` defines orange (`38 95% 52%`). `ThemeProvider` overwrites the CSS values on mount, but there's a flash of wrong-color-theme on first paint. | `src/index.css` lines 13–30 vs `src/themes.ts` lines 50–67 | Needs reconciling as part of theme work. The CSS defaults should match the default theme so first paint is correct. | +| **Single theme.** `ThemeId = "dark-blue"` only — no light, no dark, no auto. | `src/themes.ts:17` | Foundation task #1 must extend this. Light + dark + auto with `prefers-color-scheme`. | +| **`data-theme` attribute, not `data-bs-theme`.** | `src/theme-context.tsx:53` | Keeping `data-theme` (decided 2026-05-08, see Q1). The codebase isn't on Bootstrap, so `data-bs-theme` would be misleading. | +| **`StabilityBadge` only handles `"development"`.** Returns `null` for everything else. | `src/components/ui/stability-badge.tsx:27` | Foundation task #7 needs to extend this OR introduce a separate `` and migrate `StabilityBadge` callers over time. | +| **`GlowBadge` missing `error/danger` variant.** Has primary/success/info/warning/muted. | `src/components/ui/glow-badge.tsx:18` | One-line addition. | +| **Header has only Java Agent + Collector links.** | `src/components/layout/header.tsx:27–40` | The new navbar replaces this entirely. The current Header keeps shipping behind the flag. | +| **No theme toggle UI anywhere.** `ThemeProvider` exposes `setThemeId` but nothing calls it. | — | New work in foundation task #2. | +| **CollectorDetailPage is broken.** "Unexpected token '<', '` keyed by `"light" | "dark"` (or whatever ID convention we land on). The +`@theme` block in `index.css` adds the OTel purple secondary (`#4f62ad`) and locks defaults that +match the actual default theme on first paint. + +**Concrete delta:** + +- `themes.ts`: extend `ThemeId` union, add `light` + `dark` theme entries. Keep `dark-blue` as an + alias if we don't want to break existing references. +- `index.css`: rewrite `@layer theme` defaults to match the **dark** theme exactly (since dark is + closer to the placeholder users see today). Add `[data-theme="light"]` overrides. +- `theme-context.tsx`: read initial theme from `localStorage["td-color-theme"]` (matching + opentelemetry.io's key), fall back to `prefers-color-scheme`. Honor `auto` mode by listening to + `matchMedia` changes. +- New: a no-flash inline script in `index.html` that reads the stored theme and applies the + attribute before React hydrates (mirrors opentelemetry.io's `data-theme-init` pattern). + +### 2. Theme toggle UI + +**Today:** None. + +**Target:** A button in the new navbar that cycles `light → dark → auto`. Persists choice. ARIA +label and `aria-pressed` state. + +**Concrete delta:** New `` component in `components/ui/`. Consumes `useTheme()` from +`theme-context.tsx`. Lucide icons (`Sun`, `Moon`, `Monitor`). + +### 3. NavBar + +**Today:** `Header` at `components/layout/header.tsx`. Sticky, h-16, OTel logo + 2 nav links (Java +Agent, Collector). + +**Target:** opentelemetry.io-style: logo lockup + Docs · Ecosystem · Status · Community · Training · +Blog · **Explorer** · search · language · theme toggle. Always-dark even in light mode (matches +opentelemetry.io). + +**Concrete delta:** New `` at `components/layout/nav-bar.tsx`. App.tsx swaps based on +`isEnabled("V1_REDESIGN") ? :
`. Old `Header` keeps existing tests passing +during transition. + +### 4. SubNav + +**Today:** None — there's no breadcrumb pattern in the codebase. + +**Target:** Component with breadcrumb trail + optional right-side action slot. Used on every inner +page (ecosystem landing, list, detail). + +**Concrete delta:** New `` at `components/layout/sub-nav.tsx`. Probably just consumes React +Router's location and an array of crumbs from a route config. + +### 5. Footer + +**Today:** `Footer` at `components/layout/footer.tsx`. 3-column: branding + tagline + nav links. + +**Target:** Two-cluster Docsy-style: 7 social/info icons left, copyright center, 7 GitHub/community +icons right. Uses Lucide for consistency (avoid adding Font Awesome — see open question). + +**Concrete delta:** New `` (name TBD). Same flag swap pattern as NavBar. Footer test +(`footer.test.tsx`) gets a sibling test for the new version. + +### 6. CncfCallout + +**Today:** None. + +**Target:** Component rendering: "OpenTelemetry is a CNCF incubating project. Formed through a +merger of the OpenTracing and OpenCensus projects." + CNCF logo. Sits above the footer on every +route when `V1_REDESIGN` is on. + +**Concrete delta:** New `` at `components/layout/cncf-callout.tsx`. CNCF logo SVG in +`components/icons/`. Optional layout slot in `App.tsx` (within the `V1_REDESIGN` branch). + +### 7. StatusPill + +**Today:** Two related primitives: + +- `StabilityBadge` — only handles `"development"`, returns `null` otherwise. +- `GlowBadge` — variants `primary | success | info | warning | muted`, no `error/danger`. + +**Target:** `` +with the locked color mapping from the OTel collector stability spec +(secondary / warning / info / success / danger / danger). See Q5 in "Open questions" above for +the full table. + +**Concrete delta:** + +- New `` at `components/ui/status-pill.tsx`. Internally uses `GlowBadge` with the right + variant. +- Add + `error: { base: "bg-red-500/10 border-red-500/30 text-red-600 dark:text-red-400", glow: "shadow-sm shadow-red-500/20" }` + to `GlowBadge`'s `variantStyles`. +- Decide whether `StabilityBadge` becomes a thin wrapper over `StatusPill` for backward + compatibility, or gets deprecated. + +### 8. TypeStripe primitive + +**Today:** None — current cards have no left-edge color stripe. + +**Target:** A 4px left-edge stripe component that callers can compose into rows and cards. Five +colors mapped to receiver / processor / exporter / connector / extension. + +**Concrete delta:** New `` at `components/ui/type-stripe.tsx`. +Pure CSS — no logic — but typed so consumers don't pass arbitrary strings. Color tokens added to +`themes.ts` and `index.css` `@theme` block. + +### 9. Card primitive + +**Today:** Two card-shaped components: + +- `NavigationCard` — for landing-page navigation tiles +- `DetailCard` — for detail pages + +**Target:** Audit both. If one is general enough, extend it with an optional `typeStripe` slot. +Otherwise introduce a small `` primitive with `typeStripe` prop and migrate later. + +**Concrete delta:** Read both files fully, decide. Likely a small generalization rather than a new +primitive. + +### 10. DESIGN.md update + +**Today:** DESIGN.md exists at `ecosystem-explorer/DESIGN.md` and represents the original dark-first +version. The longer alignment-focused version is captured in +[`./ecosystem-explorer-v1-design-brief.md`](./ecosystem-explorer-v1-design-brief.md). + +**Target:** When the foundation lands, update `DESIGN.md` to describe the as-built tokens, +primitives, and the `data-theme` contract. We don't need the full alignment brief +there — that's what `ecosystem-explorer-v1-design-brief.md` is for. + +**Concrete delta:** A documentation-only PR after the foundation primitives merge. Out of scope for +the first foundation PR. + +### 11. Visual regression baseline + +**Today:** Playwright is in `devDependencies` but no `playwright.config.*` and no `e2e/` or +`tests/visual/` directory. + +**Target:** Playwright config + a small suite that snapshots NavBar, Footer, StatusPill (each +variant), Card, and TypeStripe in both themes. + +**Concrete delta:** + +- Add `playwright.config.ts`. +- Create a Storybook-lite route in dev mode (`/_dev/components`) that renders each primitive in both + themes against fixtures. Or use Playwright's `componentTesting`. Decide which. +- Add `pnpm test:visual` (or `bun run test:visual`) script. + +--- + +## Migration strategy: feature-flagged side-by-side + +The existing flag system at `src/lib/feature-flags.ts` is exactly what we need. + +### Add the flag + +```ts +// src/lib/feature-flags.ts +const FEATURE_FLAGS = [ + "JAVA_CONFIG_BUILDER", + "COLLECTOR_PAGE", + "V1_REDESIGN", // ← new: gates NavBar + Footer + CncfCallout + theme toggle +] as const; +``` + +### Use the flag (App.tsx pattern) + +```tsx +import { isEnabled } from "@/lib/feature-flags"; + +const v1Redesign = isEnabled("V1_REDESIGN"); + +return ( + +
+ {v1Redesign ? :
} +
+ {/* unchanged */} +
+ {v1Redesign && } + {v1Redesign ? :
} +
+ +); +``` + +### Enable locally + +```bash +# .env.local (gitignored) +VITE_FEATURE_FLAG_V1_REDESIGN=true +``` + +### Enable in Netlify previews + +Already wired in `netlify.toml`: the build command pattern-matches the source branch (`$HEAD` for PR +previews, `$BRANCH` for branch deploys) and sets `VITE_FEATURE_FLAG_V1_REDESIGN=true` for any branch +starting with `feat/84-`. Production stays off until the cleanup PR flips it. + +```toml +[build] +base = "ecosystem-explorer" +publish = "dist" +command = """ + if [[ "$HEAD" == feat/84-* || "$BRANCH" == feat/84-* ]]; then + export VITE_FEATURE_FLAG_V1_REDESIGN=true + fi + npm run netlify-build:preview +""" +``` + +Practical effect: any PR opened from a `feat/84-*` branch — and any direct deploy of such a branch — +gets the redesign chrome on automatically. Other contributors' PRs see the placeholder unchanged. + +### Cleanup, when ready + +When all foundation tasks land + maintainers approve, a single PR removes the flag and deletes the +legacy `Header` / `Footer`. That's the "go-live" moment for Phase 1. + +### Why not in-place replacement + +- The current site is shipping. Replacing `Header` directly means `main` looks broken until + everything lands. +- Side-by-side gives Netlify previews per PR with the flag on, so reviewers can see the diff + visually. +- The cleanup PR is small and surgical, lowering review friction for the final swap. + +--- + +## Testing infrastructure plan + +| Layer | Today | Target | +| ----------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Unit | Vitest, co-located `*.test.tsx`, `src/test/setup.ts` | Same. New components ship with co-located tests. | +| Integration | Separate config (`vitest.integration.config.ts`), helpers under `src/test/integration/helpers/` | Add integration tests for: theme persistence across reloads, flag-gated rendering, breadcrumb behavior. | +| Visual regression | Playwright installed, **no config yet** | Add `playwright.config.ts`, set up a `/_dev/components` route or component-test mode, snapshot each primitive in light + dark. Baseline locked at the end of foundation. | +| A11y | Nothing automated today | Add `axe-core` integration in Playwright runs. Catches contrast and aria-attribute regressions. | + +--- + +## Open questions (must resolve — flagged for maintainer discussion) + +These were carried over from `00-foundation.md`. + +1. **`data-theme` vs. `data-bs-theme`.** The codebase uses `data-theme` already. Do we keep it (less + churn, slight divergence from opentelemetry.io's Bootstrap-flavored chrome) or migrate to + `data-bs-theme` (full alignment, requires updating `theme-context.tsx` and any CSS that reads + it)? + - **Why this matters now:** the theme task is the first PR. Choose before opening it. + - **Decision (2026-05-08):** Keep `data-theme`. opentelemetry.io uses `data-bs-theme` because + Hugo Docsy is Bootstrap-based; the explorer is on Tailwind v4 with no Bootstrap, so + `data-bs-theme` would be misleading. Visual alignment with opentelemetry.io is driven by + colors, layout, and component patterns — not the HTML attribute name. Smaller PR diff, more + honest naming. + +2. **Logo source.** Local `OtelLogo` SVG already exists at `src/components/icons/otel-logo.tsx`. + Stick with it (recommended), or fetch the canonical SVG from `opentelemetry.io/img/logos/`? + - **Why this matters now:** affects the NavBar PR. + - **Decision (2026-05-08):** Stick with the current local `OtelLogo` component. Self-contained, + no extra fetch dependency, already used elsewhere in the codebase. If the upstream SVG + changes meaningfully later, we can revisit. + +3. **Icon library: Lucide-only vs. add Font Awesome.** opentelemetry.io's footer uses Font Awesome + heavily (Bluesky, Mastodon, Stack Overflow, etc.). The explorer uses Lucide. Mixing libraries + adds bundle weight. Options: + - **(a)** Stick with Lucide for the new footer; some icons (Bluesky, Mastodon) don't exist in + Lucide and need custom SVGs. + - **(b)** Add Font Awesome (~75kb minified) for footer parity. + - **(c)** Inline SVGs for the missing brand marks; keep Lucide for everything else. + - Recommended: **(c)** — minimal weight, full control. + - **Decision (2026-05-08):** Option (c). Inline SVGs for the brand marks Lucide doesn't ship + (Bluesky, Mastodon, Stack Overflow); use Lucide for everything else. Avoids adding ~75kb of + Font Awesome for a handful of footer icons; keeps the bundle lean. Inline SVGs live alongside + existing icon components under `src/components/icons/`. + +4. **`StabilityBadge` deprecation path.** Does the new `` replace `StabilityBadge` + outright (one PR migrates all callers), or does `StabilityBadge` become a thin wrapper for + backward compatibility? + - **Why this matters now:** affects scope of the StatusPill PR. + - **Recommended:** keep both, target different uses initially, migrate later in a separate + cleanup PR. The current `StabilityBadge` is narrow (one state — `"development"` — rendered as + a yellow "dev" pill, used inside the Java configuration builder). The new `` is + general-purpose with six states. They're different primitives with overlapping concerns. + Building `` in PR 4 without touching `StabilityBadge` keeps PR 4 small and + focused, and decouples the configuration-builder visual from the foundation work. Migration + becomes a follow-up cleanup PR after Phase 1 lands. + - **Decision (2026-05-08):** Adopt the recommendation above. Add `` in PR 4 as a + new primitive; leave `` callers unchanged for now. Migrate the configuration + builder to `` in a follow-up PR after Phase 1 cleanup. + +5. **Stability terminology in data.** The data uses `alpha | beta | development | unmaintained`. + Visually we map to four colors (success/info/warning/danger). The `development` ↔ `alpha` overlap + and `unmaintained` ↔ `deprecated` synonym need locking before pill colors ship. + - **Maintainer call** — needs alignment with `ecosystem-registry` maintainers. + - **Decision (2026-05-08):** Adopt the [OpenTelemetry Collector stability + spec](https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md) + verbatim. **Six** stability levels — Development, Alpha, Beta, Stable, Deprecated, + Unmaintained — with this color mapping: + + | Level | Semantic | Pill variant | + | ----------------- | ---------------------------------------------- | ----------------------- | + | `development` | Not all pieces in place; not for production | `secondary` (gray) | + | `alpha` | Limited non-critical workloads | `warning` (orange) | + | `beta` | Configs deemed stable; broader usage | `info` (blue) | + | `stable` | General availability; production-ready | `success` (green) | + | `deprecated` | Planned removal; no further support | `danger` (red) | + | `unmaintained` | No active code owner; will be removed soon | `danger` (red) | + + `deprecated` and `unmaintained` share the red color but show different labels — both signal + "avoid" but for different reasons. This mirrors the collector's own stability ladder so + anyone reading both sources sees the same vocabulary. `` props update from + `'stable' | 'beta' | 'alpha' | 'deprecated'` to the six values above. + +--- + +## Action checklist before the first PR + +- [x] Decide on `data-theme` vs. `data-bs-theme` (Q1) — locked: keep `data-theme`. +- [x] Decide on logo source (Q2) — locked: keep the local `OtelLogo` component. +- [x] Decide on icon library strategy (Q3) — locked: option (c), inline SVGs for missing brand + marks; keep Lucide for everything else. +- [x] Decide on `StabilityBadge` deprecation path (Q4) — locked: keep both, target different + uses; migrate in a follow-up cleanup PR after Phase 1. +- [x] Pin the stability-terminology mapping (Q5) — locked: six-level OTel collector spec + (development / alpha / beta / stable / deprecated / unmaintained). +- [ ] Reconcile color drift: rewrite `index.css` defaults to match the actual default theme. +- [ ] Add `V1_REDESIGN` to `FEATURE_FLAGS` (one-line PR — can ship first as a no-op). The + `netlify.toml` build command already pattern-matches `feat/84-*` to enable the flag, so + previews on those branches will pick it up immediately once the flag exists in + `lib/feature-flags.ts`. + +Once these are done, the first PR is **"Add light + dark + auto theme system + theme toggle in +navbar"** — small, visible, low-risk, gated by `V1_REDESIGN` so it can land without disrupting +`main`. + +--- + +## Recommended PR sequence (preview) + +This is _next_ — Project 00's "break Phase 1 into PRs" track. Listed here as a preview so the audit +feels complete: + +1. **PR 0: Add V1_REDESIGN flag** (1-line in `lib/feature-flags.ts` — unblocks everything; + `netlify.toml` already pattern-matches `feat/84-*` so previews pick it up automatically). +2. **PR 1: Theme system** — extend themes, no-flash init, theme toggle in a stub navbar. +3. **PR 2: NavBar v1** — full opentelemetry.io-style navbar; theme toggle moves into it. +4. **PR 3: SubNav** — breadcrumb component used by inner pages. +5. **PR 4: StatusPill + GlowBadge `error` variant** — locks status mapping. +6. **PR 5: TypeStripe + Card primitive update** — unblocks list and detail page projects. +7. **PR 6: FooterV1 + CncfCallout** — closes the chrome. +8. **PR 7: Playwright visual regression baseline** — locks the look. +9. **PR 8: Cleanup** — remove `V1_REDESIGN` flag, delete legacy `Header`/`Footer`, update + `DESIGN.md`. + +Each PR is small enough for one contributor and one reviewer; each can ship independently behind the +flag. diff --git a/projects/84-ui-ux-design/00-foundation.md b/projects/84-ui-ux-design/00-foundation.md new file mode 100644 index 00000000..490c428a --- /dev/null +++ b/projects/84-ui-ux-design/00-foundation.md @@ -0,0 +1,108 @@ +--- +title: "Phase 1 — Foundation" +issue: 84 +type: plan +phase: 1 +status: planning +last_updated: "2026-05-08" +--- + +> [!NOTE] +> +> This file was drafted in collaboration with Claude Opus 4.7. Corrections are welcome. + +# Project 00 — Foundation + +> Shared building blocks every page reuses. **Land this first** — every other project (home, +> ecosystem landing, list, detail) depends on it. + +Tracks: [#84](https://github.com/open-telemetry/opentelemetry-ecosystem-explorer/issues/84) +References: [`ecosystem-explorer-v1-mockups.html`](./ecosystem-explorer-v1-mockups.html) · +[`ecosystem-explorer-v1-design-brief.md`](./ecosystem-explorer-v1-design-brief.md) · +[`ecosystem-explorer/DESIGN.md`](../../ecosystem-explorer/DESIGN.md) + +--- + +## TL;DR + +Port the explorer onto the same visual chrome opentelemetry.io uses: light/dark/auto theme system +(`data-theme` + persisted to `localStorage` under `td-color-theme`), an always-dark Docsy-style +navbar, the two-cluster footer, and the CNCF callout. Lock the canonical color/badge mappings so +every later page can compose against a stable foundation. + +## Goal + +When a contributor starts the next project (home page), they should be able to drop content into a +`
` slot and inherit nav, footer, theme switching, brand colors, status pills, and type stripes +without writing any of that themselves. + +## Scope (in) + +- Theme system: `data-theme="light|dark"`, persisted to `localStorage` key `td-color-theme`, + honors `prefers-color-scheme` for the "auto" option, with a navbar toggle. No flash of wrong theme + on first paint. +- CSS custom properties exposed for both themes (see DESIGN.md "CSS Custom Properties" section). +- `` component matching opentelemetry.io: always-dark, full-width, sticky. Includes logo + lockup, primary nav (Docs · Ecosystem · Status · Community · Training · Blog · **Explorer**), + search input (placeholder Ask AI / ⌘K), theme toggle. +- `` component for the explorer (breadcrumb-only on home, breadcrumb + page actions on + inner pages). +- `