Refining the Review Experience: How CSS Grid and Iterative Feedback Transformed Our Workflow Panel

As developers, we often build complex systems that generate equally complex data. Presenting that data to users in an intuitive, actionable way is a perpetual challenge. Recently, our team faced this head-on while refining the "review key points panel" – a critical component in our workflow that summarizes findings and provides actionable insights.

Our goal was clear: create a panel that was not only visually clean and aligned but also enabled users to iterate on their work seamlessly. This meant moving beyond a static review to a dynamic, iterative feedback loop.

The Challenge: Taming Tabular Data in a Dynamic UI

Initially, our review key points panel used a card-based layout. Each key point was an independent card, which felt visually distinct but quickly led to a common UI headache: misalignment.

Imagine a list of items, each with a severity badge, a category, and a finding title. With a flexible card layout, these elements would often refuse to line up neatly across different rows. The severity badge in row 1 might be a few pixels off from the badge in row 2, creating a messy, disjointed feel.

// Initial thought: using flexbox for each row
// <div className="flex items-center">
//   <Chevron />
//   <SeverityBadge />
//   <Category />
//   <FindingTitle />
//   <StatusIcon />
// </div>
// Problem: Each row's internal flex layout is independent,
// leading to column misalignment across rows if content varies.

We tried various flexbox configurations, but the fundamental issue remained: each card was its own layout context. What we needed was a global grid system that dictated column widths for all rows simultaneously, ensuring perfect vertical alignment.

The CSS Grid Solution: Precision and Clarity

The answer, as it often is for true tabular layouts, was CSS Grid. By transforming our panel into a grid-based structure, we could define explicit column tracks that would apply uniformly to every single key point.

We refactored src/components/workflow/review-key-points-panel.tsx to use a CSS Grid with carefully chosen column widths:

/* Applied via Tailwind CSS utility classes */
.grid-cols-\[16px_72px_90px_1fr_auto\] {
  grid-template-columns: 16px 72px 90px 1fr auto;
}

This specific setup breaks down as:

• 16px: For a small chevron icon (for collapsing/expanding details).
• 72px: A fixed width for our severity badge.
• 90px: A fixed width for the category text.
• 1fr: A flexible column for the main finding title, taking up remaining space.
• auto: For status icons or action buttons on the far right.

The result was immediately satisfying: perfectly aligned columns, transforming a cluttered list into a clean, readable table-like interface.

User Feedback in Action: Collapsing Verbosity

Another critical piece of feedback emerged during early testing: while the detailed analysis for each key point was valuable, it was also incredibly verbose. When multiple key points were expanded, the panel became a wall of text, obscuring the primary interaction surface.

Our initial instinct was to show everything by default, assuming more information is always better. However, user feedback quickly taught us that context matters. The key points panel is for overview and action; the detailed analysis is for deep dive.

The Solution: Default Collapsed with Smart Headers

We adjusted src/app/(dashboard)/dashboard/workflows/[id]/page.tsx to make the review analysis output default collapsed. This significantly improved the panel's readability and focus.

Crucially, we didn't hide the metadata entirely. Key information like tokens, cost, and duration of the analysis was moved inline into the collapse header. This provides essential context at a glance without overwhelming the user with the full text.

// Simplified state management for collapsed state
const [expandedPrompts, setExpandedPrompts] = useState<{ [key: string]: boolean }>({});
// ...
// In the render logic for a key point:
const isAnalysisExpanded = expandedPrompts[step.id + '-analysis'] ?? false;
// ... render header with metadata, then conditionally render full analysis

Empowering Iterative Reviews: The "Recreate" Loop

Beyond presentation, we wanted to enable a truly iterative review process. Sometimes a finding isn't quite right, or the underlying generation needs a tweak. Instead of discarding and starting over, users should be able to refine.

To achieve this, we introduced a per-item "Recreate" button for each key point.

When clicked, this button triggers an onRecreateItem(keyPointId) action, which in turn calls a recreateFromKeyPoint mutation with mode: "recreate_with_hints". What does this mean in practice?

1. Reset: The system resets the relevant preceding step (e.g., "Design Features").
2. Hint Injection: It injects specific hints derived from the problematic key point into the re-run.
3. Re-run: The workflow re-executes that step.
4. New Review: A new review step is automatically generated, extracting fresh key points based on the revised output.

This creates a powerful iteration loop: recreate → re-run → new review → new key points → address each → approve when all resolved.

We also added other action buttons per finding: "Keep," "Edit," and "Discard," with their status clearly indicated by an icon in the rightmost column. For visual clarity, the expanded detail panel now features a border-l-2 left border, and edit mode uses a distinct border-nyx-accent/30.

Lessons Learned and Immediate Next Steps

This session brought some valuable insights:

• Choose the Right Tool for the Job: While Flexbox is incredibly versatile, for truly tabular, column-aligned data, CSS Grid often provides a more robust and predictable solution. Don't force Flexbox where Grid excels.
• Listen to Your Users: User feedback is gold. What seems logical to a developer (e.g., showing all information by default) might not be what's best for user experience. Prioritize primary interactions and offer secondary details on demand.
• Enable Iteration: Complex workflows benefit immensely from built-in mechanisms for iteration and refinement. Making it easy for users to "try again" with focused adjustments reduces friction and improves outcomes.

Our immediate next steps involve thorough browser testing of the new layout and the "Recreate" functionality to ensure everything works as expected across our test workflow. We'll also be tidying up some technical debt, such as consolidating duplicated ReviewKeyPoint types and extracting the now-complex review panel into a standalone component to improve maintainability.

Refining a UI component like this isn't just about aesthetics; it's about fundamentally improving how users interact with and achieve their goals within the system. By combining thoughtful layout choices with iterative feedback loops, we're making our workflows more efficient and user-friendly, one key point at a time.