Loomworks Engineering · Forge Specification

Companion Expertise Badge Display

Version
0.1
Date
2026-05-18
Status
Pre-induction
Total Build Days
1.2

Business Context

Domain Experts in the system have earned recognition through sustained contribution to a specific knowledge area. The badge system visualizes that recognition in the Operator Layer dashboard — both for the Domain Expert themselves and for others viewing engagement participants.

Scope

Render the Domain Expert badge on the dashboard surface. Surface domain name, recognition date, and current activity status.

Exclusions

  • Badge revocation flows — badges are persistent; activity dots handle dormancy
  • Multi-domain stacking UI — deferred to v1.1
  • Badge introspection — clicking a badge does not yet open a detail view

Tech Stack

Frontend:Next.js 14 / TypeScript
Styling:Tailwind CSS with letterpress palette tokens
Backend:FastAPI / Python (existing)
Database:PostgreSQL via SQLAlchemy (existing)

Non-Functional Requirements

Performance
Badge render must complete within 50ms of dashboard mount under standard load (P95).
Accessibility
Badge component meets WCAG 2.1 AA contrast requirements for the vellum/brass token pair.

Phase 1 — Display

Cycles 1–2

Cycle 1Badge Component

0.6 build days
REQ-001
Render a Badge component accepting domain name and recognition date as props.
0.1 days
Depends on
None
Acceptance
Component renders with given props. Visual matches the design token spec for vellum background, brass border, Plex Serif italic for the domain name.
REQ-002
Render activity dot in green when domain has activity in the last 14 days; absent otherwise.
0.2 days
Depends on
REQ-001
Acceptance
Given a domain_last_activity timestamp within 14 days of current time, the dot is present and the color matches #4A7C45. Outside that window, the dot is absent.
REQ-003
Surface recognition date in tooltip on hover, formatted "Recognized: Month YYYY".
0.1 days
Depends on
REQ-001
Acceptance
Hover on badge for more than 200ms displays a tooltip with the text "Recognized: " followed by the recognition date formatted as the full month name and 4-digit year.
REQ-004
Component accepts a size prop with values 'sm' and 'md', defaulting to 'md'.
0.2 days
Depends on
REQ-001
Acceptance
Component with size='sm' renders at 14px font and 4px padding. size='md' renders at 16px font and 8px padding. Absent size prop uses 'md'.
Cycle 1 total: 0.6 build days · 4 requirements (REQ-001 – REQ-004)

Cycle 2Dashboard Integration

0.6 build days
REQ-005
Fetch Domain Expert badges for the current user on dashboard mount.
0.2 days
Depends on
None
Acceptance
GET /api/v1/domain-experts/me returns array of {domain, recognized_at, last_activity_at}. The component receives the array as a prop.
REQ-006
Render fetched badges in the dashboard header, left of the room badges.
0.2 days
Depends on
REQ-001, REQ-005
Acceptance
Badges appear in the header span between the user avatar and the room badges. Up to 3 badges visible. The rest collapse into a "+N more" indicator.
REQ-007
Display "No domain expertise yet" message when no badges are returned.
0.1 days
Depends on
REQ-005
Acceptance
When the fetched array is empty, display the text "No domain expertise yet" in soft-gray Inter 12px in the badge slot.
REQ-008
Persist the badges fetched in a React Query cache with a 5-minute stale time.
0.1 days
Depends on
REQ-005
Acceptance
React Query devtools confirm the cache entry exists with queryKey ["domain-experts", "me"] and staleTime of 300000ms.
Cycle 2 total: 0.6 build days · 4 requirements (REQ-005 – REQ-008)