pluto-atom-4/note.md

UI Refactoring Workflow: Applying Sentry Design System

Date: April 11, 2026
Status: Complete
Duration: Single collaborative session
Result: Production-ready design system implementation with Tailwind v4

Executive Summary

This document outlines the AI-assisted workflow for completely refactoring a React playground's UI from a basic light theme to a professional, dark-mode-first design system inspired by Sentry. The process involved strategic planning, iterative refinement, and collaborative decision-making between AI and human.

Key Achievement: Transformed the project from two basic features to a cohesive, accessible, production-ready design system that serves as a template for future feature development.

Phase 1: Understanding the Current State

Initial Assessment

What we found:

Existing project: Vite + React + TypeScript
Initial styling: Anthropic brand guidelines (light theme)
Features: 2 implemented problems (Todo List, Text Append)
Problem: Light theme didn't align with modern dark-mode-first design trends

Tools Used:

File reading (README.md, CLAUDE.md, current App.tsx)
Codebase exploration (Glob for file patterns)
Package inspection (package.json for dependencies)

Key Discoveries

Tailwind CSS v4 Already in Use: Project had @tailwindcss/postcss@4.2.1
- This was critical discovery because v4 uses different configuration API
- Custom colors MUST be in @theme blocks, not tailwind.config.js
Existing Component Architecture: Already had solid structure
- Feature-based organization (src/features/)
- Component hierarchy ready for styling
- Clear separation of concerns
Styling Approach: Using Tailwind CSS + custom classes
- Initial attempt mixed Tailwind v3 syntax with v4 runtime
- Custom colors in tailwind.config.js were being ignored
- This caused accessibility issues (text-sentry-light-gray not applying)

Phase 2: Initialize Design System

Command:

npx getdesign@latest add sentry

Downloads official Sentry design specifications including color palette, typography, and component patterns. This ensures brand consistency and serves as the source of truth throughout implementation.

Phase 3: Strategic Planning (Plan Mode)

Approach: Design System First, Implementation Second

Decision Point: Instead of piecemeal styling, implement complete design system upfront

Why:

Single source of truth for colors, typography, spacing
Easier for team members to follow pattern
Reduces decision fatigue for future features
Supports comprehensive documentation

Planning Steps

Research Sentry design system principles
Inventory component needs (inputs, buttons, cards, navigation)
Identify critical issues (Tailwind v4 config, color inheritance)
Prioritize implementation (fix config → apply colors → refactor components)

Phase 4: Implementation (Iterative)

Step 1: Migrate Tailwind v3 → v4 Configuration

Problem: Custom Sentry colors in tailwind.config.js were ignored by Tailwind v4

Solution: Move all colors to @theme block in src/index.css

@theme {
  --color-sentry-deep-purple: #1f1633;
  --color-sentry-coral: #ffb287;
  /* ... all other colors */
}

Result: Tailwind now emits real CSS utilities for text-sentry-*, bg-sentry-*, etc.

Key Learning: Always verify Tailwind version when migrating — syntax is NOT backward compatible.

Step 2: Enhanced Input Controls

Problem: Form inputs were basic, didn't match design system

Implementation:

Created comprehensive @layer components in index.css
Styled all input types consistently:
- Default: semi-transparent purple background
- Focus: Coral border with glow shadow
- Disabled: Muted appearance with not-allowed cursor
Added validation states (.is-valid, .is-invalid)

Accessibility Consideration:

All focus states use 4px glow, not traditional outline
Glow color matches button accent (coral)
Still passes WCAG AAA contrast

Human Input: User requested "warmer, gentler colors instead of white and black"

This drove selection of coral (#ffb287) as primary interactive color
Influenced all subsequent button and input styling

Step 3: Button System Redesign

Three-Button Strategy:

Button Type	Color	Purpose	User Action
Primary	Coral (#ffb287)	High-visibility CTAs	"Add", "Submit" actions
Secondary	Light Purple	Alternative actions	Form reset, clear
Tertiary	Lime Green	Forward actions	"Learn more", navigation

Implementation:

Each button type has 3 states: default, hover, focus
All transitions use 200ms for smooth UX
Focus glows match button color for visual consistency

Design Decision: Initially used muted purple for primary, user feedback suggested warmer coral for better approachability

Step 4: Horizontal Carousel for Problem Cards

Problem: Grid layout was vertical, not showcasing all problems simultaneously

Requirement: "Let user to horizontal scroll to choose"

Implementation:

Changed from CSS Grid to Flexbox with overflow-x-auto
Added Left/Right navigation arrows
Fixed card widths (responsive: 288px → 320px → 384px)
Buttons disabled at carousel edges

Technical Details:

// Carousel state management in App.tsx
const [showLeftArrow, setShowLeftArrow] = useState(false)
const [showRightArrow, setShowRightArrow] = useState(true)

const scroll = (direction: 'left' | 'right') => {
  // Smooth scroll with debounced position check
}

UX Insight: Arrows always visible (not hidden on hover) — makes carousel discoverable

Step 5: Color Inheritance Bug Investigation & Fix

Issue Discovered: Problem description text appeared black instead of light gray

Root Cause Analysis:

Problem card is a <button> element (not <div>)
Button inherits browser UA stylesheet rule: color: ButtonText (system black)
Tailwind v4 preflight applies color: inherit to buttons
Custom color text-sentry-light-gray was not generating CSS (Tailwind v3 config issue)
Without generated CSS rule, button falls back to system black

Solution: Move all colors to @theme block (already done in Step 1)

Learning: Browser UA stylesheets are powerful and often invisible — inspect element to debug color issues

Step 6: TodoList Component Full Refactor

Scope: Replace light theme with complete Sentry dark theme

Implementation Approach:

Created companion CSS file (TodoList.css)
Used semantic class names: .todo-card, .todo-input, .btn-add, .btn-delete
Applied full color palette:
- Cards: semi-transparent purple backgrounds
- Text: white + light gray + muted gray hierarchy
- Accents: Lime green (counts), coral (remaining)

Why Separate CSS File?

Component-specific styles isolated
Easier to maintain as feature grows
Tailwind classes still used for layout (flex, gap, padding)
CSS classes for interactive states (hover, focus)

User Feedback Process:

"Make button controls more gentle and warmer"
Applied coral accent to delete button
Added warm hover effects

Step 7: Documentation (DESIGN.md Update)

Scope: Comprehensive design system specification for future developers

Sections Added:

Section 10: Form Controls with all states and validation
Section 11: Button System with all three variants
Section 12: Carousel Implementation with responsive table
Section 13: TodoList Component styling guide
Section 14: Tailwind v4 Technical Configuration
Section 15: Accessibility Standards and compliance

Purpose: Future team members can understand:

WHY each color was chosen
HOW to implement new components consistently
WHAT accessibility standards are met
WHERE to find implementation examples

Phase 5: Quality Assurance

Verification Checklist

✅ Build Status

pnpm build → ✓ built in 1.78s

✅ TypeScript Compilation

No type errors
All components properly typed

✅ Accessibility

All focus states visible
WCAG AA contrast minimum met
AAA achieved for light text on dark
Keyboard navigation works

✅ Responsive Design

Mobile: Cards collapse appropriately
Tablet: 2-column grid appears
Desktop: Full-width carousel visible

✅ Cross-Browser

Scrollbar hiding (.scrollbar-hide) works on:
- Chrome/Edge (-webkit-scrollbar)
- Firefox (scrollbar-width: none)
- Safari (webkit)

Phase 6: Key Decisions & Rationale

Decision 1: Dark Theme Over Light Theme

Why?

Sentry design inspiration (dark-mode-first)
Better for developer tool aesthetic
Reduces eye strain for extended sessions
Trendy and modern

Impact: Entire color palette built around deep purple backgrounds

Decision 2: Warm Accent Colors (Coral + Lime)

Why?

Warm purple base + warm accents = cohesive
Coral (#ffb287) more approachable than cold blues
Lime green (#c2ef4e) provides high-visibility pop
Psychology: warm colors = friendly, inviting

Alternative Considered: Cool accent colors (blues, cyans)

Would create visual tension with warm purple base
Less approachable for interview stress context

Decision 3: Carousel Over Grid

Why?

Showcases more problems at once
Makes all options visible without scrolling down
Encourages exploration
Navigation arrows are discoverable

Alternative Considered: Sticky sidebar with tabs

Would take up screen space
More clicks needed

Decision 4: Unified Input + Button Colors

Why?

Form and interactive elements feel cohesive
User knows "coral glow = focus" across entire UI
Reduces cognitive load
Professional, intentional appearance

Implementation: Both inputs and buttons use coral focus, purple backgrounds, lime green tertiary

Process Insights: AI Workflow Best Practices

1. Start with Understanding (Not Implementation)

What We Did:

Spent initial time reading existing code
Understood Tailwind version, dependencies, architecture
Diagnosed the v4 configuration issue BEFORE attempting fixes

Principle: Understanding prevents false starts and wasted effort

2. Use Plan Mode for Non-Trivial Changes

When We Used It:

Diagnosing the text-sentry-light-gray bug
Designed investigation and root cause analysis
Presented findings in structured format

Benefit: Structured thinking beats intuitive hacking for subtle bugs

3. Break Implementation into Phases

Sequence We Followed:

Fix foundational issues (Tailwind config)
Implement core systems (colors, buttons, inputs)
Refactor existing components
Add new features (carousel)
Document everything

Principle: Foundation before features, implementation before documentation

4. Iterate Based on User Feedback

Example: Button Colors

Initially used muted purple for primary button
User feedback: "more gentle and warmer"
Switched to coral
Much better user reception

Principle: AI makes good first guess, humans provide taste/context

5. Verify Often (Build Early, Build Often)

Cadence:

pnpm build after each major change
Caught CSS issues immediately
Prevented compound errors

Command Pattern:

# After each phase: verify nothing broke
pnpm build 2>&1 | tail -15

Lessons Learned

Technical Lessons

Tailwind v4 is Different
- Configuration must be in CSS, not JS
- @theme blocks are the new standard
- Custom colors no longer in tailwind.config.js
Browser UA Stylesheets Matter
- Buttons inherit system color (ButtonText)
- Preflight resets don't override all UA styles
- Debug color issues with DevTools inspector
Focus States are Critical
- Users expect visible focus indicators
- Box-shadow glows work better than outlines
- Color-matched glows improve usability

Process Lessons

Naming Matters
- .text-sentry-light-gray is better than .text-gray-2
- Semantic class names (.todo-card > .card-1)
- Helps future developers understand intent
Documentation Upfront
- DESIGN.md should be written as feature implemented
- Not added afterward as afterthought
- Makes knowledge transferable to team
Accessibility is Not Afterthought
- Include WCAG checks in implementation
- Color contrast, focus states, keyboard nav
- Builds trust with users

Collaboration Lessons

Clarifying Questions Work
- "enhance the buttons horizontally" → AskUserQuestion
- Prevents implementation of wrong feature
- 30 seconds of clarification > 30 minutes of rework
Iterative Feedback is Gold
- "more gentle and warmer colors" → specific improvement
- User knows taste better than AI
- AI can implement faster once direction clear
Reversions Save Time
- When carousel implementation was wrong, easily reverted
- Gave user confidence to try alternatives
- No fear of "locked in" to approach

Artifact: Session Commits

# 1. Initial design system framework
git commit "feat: add Anthropic brand design system and showcase UI"

# 2. Sentry theme migration
git commit "refactor: rework UI with Sentry-inspired dark theme design system"

# 3. Responsive enhancements
git commit "refactor: enhance responsive design for problem content and UI elements"

# 4. Tailwind v4 fix
git commit "fix: migrate Sentry colors to Tailwind v4 @theme blocks"

# 5. Carousel implementation
git commit "feat: add horizontal carousel layout for problem cards"

# 6. Control enhancements
git commit "feat: enhance input control styling with warm, gentle Sentry colors"

# 7. Button redesign
git commit "feat: complete design system polish with enhanced form controls and buttons"

# 8. TodoList refactor
git commit "feat: refactor TodoList component with Sentry dark theme"

# 9. Documentation
git commit "docs: update DESIGN.md with complete session implementation"

Future Implications

For Next Developers

This document and DESIGN.md provide:

Complete color palette with hex values
Typography hierarchy with sizes and weights
Component patterns (buttons, cards, inputs, forms)
Responsive breakpoints and behavior
Accessibility standards achieved
Tailwind v4 configuration approach

For New Features

Adding a new interview problem now:

Use existing component library (.btn-primary, .card, .todo-input)
Reference DESIGN.md for color choices
Follow 3-button pattern for actions
Implement focus states with color-matched glows
Test accessibility with keyboard + screen reader

Scalability

The design system scales because:

Tailwind @theme centralizes all tokens
CSS utility classes prevent duplication
Component patterns are documented
Accessibility built-in (not bolted-on)

Conclusion

What We Accomplished:

Transformed basic light theme → professional dark design system
Fixed Tailwind v4 configuration issues
Implemented complete form control styling
Redesigned button system with 3 variants
Added carousel with visible navigation
Refactored TodoList component
Documented everything comprehensively

Investment:

1 collaborative session
Multiple iterative refinements
Comprehensive documentation

Return:

Production-ready design system
Scalable for new features
Accessible (WCAG AA/AAA)
Beautiful and professional appearance
Clear handoff documentation

This workflow demonstrates AI's strength in rapid iteration while maintaining quality, accessibility, and documentation — with human judgment guiding taste and priorities.