Harness GUI development

Start with the existing product, not a new visual system. Read the target page and adjacent consumers, then GUI package guidance at packages/gui/README.md (relative to the product repository root) and the actual shared component source under packages/gui/src/renderer/components/primitives. The runnable packages/gui/component-catalog.html imports production primitives and demonstrates their contract; inspect its source for real imports and supported states. Consult the project’s authored GUI design standard when the workspace supplies one. User-approved interaction changes take precedence over older examples.

Choose the shared boundary

Before writing JSX, identify the existing component that owns the behavior. A page composes domain data and actions; shared primitives own sizing, overflow, focus and motion. Fix a repeated problem at that boundary and migrate real consumers in the same change. Do not retain a second implementation or turn a domain-specific card into a generic framework merely to reduce a file’s size.

• Addressable entities use EntityRefLink and the actual navigation callback. Keep the complete canonical reference available when the visible label is shortened. Do not infer entity kinds for arbitrary IDs.
• Non-addressable IDs use the shared ID display; records combine ID/state/prose/time/actions through the shared record layout. Check every supplied field, including non-null receipts and mixed-language long prose. Removing overlap is necessary but insufficient: give reading text enough width instead of squeezing it between metadata columns.
• Reuse status vocabulary, time formatting and interaction controls from the existing sources. Do not create page-local colors, raw timestamp formatting or duplicate button/switch implementations.
• Treat empty results as product information: explain absence and the next relevant action where needed. Do not fill dashboards with unrelated totals or decorative ratios. Each number needs a question, scope and actionable meaning.

Fit density to the task

Optimize this functional GUI for readable work and efficient navigation. Shared components unify behavior, not dimensions: choose supported density, fill and layout options for the content and available space. Give documents reading width, directories scanning density, and controls only the space they need; do not copy one fixed ratio to every consumer. Respect user-adjusted region proportions.

Distinguish parent task headers from child session rounds through hierarchy and continuous grouping. Make the round identifier primary and repeated agent metadata secondary. Remove repeated information and nested padding before squeezing text; neither crowded single-line records nor oversized cards and decorative gaps are acceptable. Do not shrink typography to claim higher density.