{"id":"9a5d16a2-899c-45f8-a6b6-19057c6f50eb","shortId":"7fp6m8","kind":"skill","title":"refactoring-ui","tagline":"Comprehensive UI design guidance based on Refactoring UI principles covering visual hierarchy, color theory, typography, spacing, and mobile-first responsive design. Use this skill whenever the user is creating new pages, building components, making design additions or changes, r","description":"# Refactoring UI Design System\n\n## Core Philosophy\n\nDesign decisions should be made with intention, not decoration. Every visual choice—color, size, spacing, weight—communicates hierarchy and guides the user's attention. Start with too much whitespace, then remove it. Start with less contrast, then add it where needed.\n\n---\n\n## Visual Hierarchy\n\nHierarchy is the foundation of good UI. Users should immediately understand what's important.\n\n### The Hierarchy Toolkit\n\nYou have three primary tools to establish hierarchy:\n\n1. **Size** — Larger elements draw more attention\n2. **Weight** — Bolder text feels more important\n3. **Color** — Higher contrast elements stand out\n\nThe key insight: **don't rely on size alone**. A common mistake is making primary content huge and secondary content tiny. Instead, use all three tools together.\n\n### De-emphasize by Reducing Contrast\n\nInstead of making important things bigger, try making unimportant things less prominent:\n- Use lighter colors for secondary text (not smaller sizes)\n- Reduce font weight for supporting information\n- Use muted colors for metadata (dates, labels, counts)\n\n### Semantic Color vs Visual Hierarchy\n\nDon't let semantics override hierarchy. A \"danger\" action that's rarely used shouldn't be bright red if it competes with the primary action. Use muted reds for destructive secondary actions.\n\n```css path=null start=null\n/* Primary destructive action - prominent */\n.btn-danger-primary { @apply bg-red-600 text-white; }\n\n/* Secondary destructive action - muted */\n.btn-danger-secondary { @apply text-red-600/70 bg-transparent; }\n```\n\n### Labels and Data\n\nWhen showing label-value pairs, the data is usually more important than the label:\n- De-emphasize labels (lighter color, smaller size, or all caps with letter-spacing)\n- Let the values stand out naturally\n\n```html path=null start=null\n\n
\n Status\n Active\n
\n```\n\n---\n\n## Typography\n\n### Font Size Scale\n\nUse a modular scale with intentional jumps. Avoid arbitrary sizes.\n\nRecommended scale (based on a ~1.25 ratio):\n- **xs**: 12px — Fine print, captions\n- **sm**: 14px — Secondary text, metadata \n- **base**: 16px — Body text (minimum for readability)\n- **lg**: 18px — Emphasized body, lead paragraphs\n- **xl**: 20px — Subheadings\n- **2xl**: 24px — Section headings\n- **3xl**: 30px — Page headings\n- **4xl**: 36px — Hero text\n- **5xl+**: 48px+ — Display text, marketing\n\n### Line Height\n\nLine height should decrease as font size increases:\n- **Small text (12-14px)**: 1.5-1.75 (needs more breathing room)\n- **Body text (16-18px)**: 1.5-1.65\n- **Headings (24px+)**: 1.2-1.35 (tighter feels more refined)\n\n### Letter Spacing\n\n- **All-caps text**: Add 0.05-0.1em tracking (uppercase needs room)\n- **Large headings**: Consider slight negative tracking (-0.02em)\n- **Body text**: Leave default\n\n### Font Weight Strategy\n\nAvoid using too many weights. Pick 2-3:\n- **Normal (400)**: Body text\n- **Medium (500)**: Emphasis, UI elements\n- **Semibold/Bold (600-700)**: Headings, strong emphasis\n\nUsing medium (500) for UI text often looks more refined than jumping straight to bold.\n\n### Line Length\n\nOptimal reading: **45-75 characters** per line. For a 16px font, that's roughly 20-35em or 320-560px.\n\n```css path=null start=null\n.prose { max-width: 65ch; } /* ch unit = width of '0' character */\n```\n\n---\n\n## Color\n\n### Building a Color Palette\n\nEvery color needs a full range of shades (typically 9-10):\n- **50-100**: Backgrounds, subtle fills\n- **200-300**: Borders, disabled states\n- **400-500**: Icons, secondary text\n- **600-700**: Primary text, buttons\n- **800-900**: Headings, high-emphasis text\n\n### Defining Colors with HSL\n\nHSL (Hue, Saturation, Lightness) is more intuitive for building palettes:\n\n```css path=null start=null\n/* Base color */\n--primary-600: hsl(220, 65%, 50%);\n\n/* Lighter (increase lightness, slightly decrease saturation) */\n--primary-100: hsl(220, 60%, 95%);\n\n/* Darker (decrease lightness, can increase saturation slightly) */\n--primary-800: hsl(220, 70%, 30%);\n```\n\nKey insight: **perceived brightness changes with hue**. Yellow appears brighter than blue at the same lightness. Adjust accordingly.\n\n### Color for UI States\n\n- **Hover**: Darken by one shade (500 → 600) or reduce lightness by 5-10%\n- **Active/Pressed**: Darken another shade (600 → 700)\n- **Disabled**: Reduce saturation significantly, increase lightness\n- **Focus**: Use a ring/outline, don't change the element's color\n\n### Grays Aren't Truly Gray\n\nAdd a hint of color to your grays for warmth or coolness:\n- **Warm grays**: Add a touch of yellow/orange (better for friendly, approachable UIs)\n- **Cool grays**: Add a touch of blue (better for professional, technical UIs)\n\n```css path=null start=null\n/* Cool gray (slight blue) */\n--gray-600: hsl(215, 15%, 40%);\n\n/* Warm gray (slight yellow) */\n--gray-600: hsl(40, 10%, 40%);\n```\n\n### Accessible Color Contrast\n\n- **Body text**: Minimum 4.5:1 contrast ratio (WCAG AA)\n- **Large text (18px+ bold or 24px+)**: Minimum 3:1\n- **UI components**: Minimum 3:1 against adjacent colors\n- **Don't rely on color alone**: Use icons, text, or patterns alongside\n\n### Don't Use Pure Black\n\nPure black (#000) feels harsh and unnatural. Use a very dark gray instead:\n\n```css path=null start=null\n/* Too harsh */\ncolor: #000;\n\n/* Better - dark but not absolute */\ncolor: #1a1a1a; /* or hsl(0, 0%, 10%) */\n```\n\n---\n\n## Spacing\n\n### Spacing Scale\n\nUse a consistent scale based on a base unit (typically 4px or 8px):\n\n```\n4, 8, 12, 16, 24, 32, 48, 64, 96, 128...\n```\n\nAvoid arbitrary values like 13px or 27px. Constraints create consistency.\n\n### Spacing Relationships\n\n- **Related items**: Closer together (8-12px)\n- **Grouped but distinct**: Medium spacing (16-24px)\n- **Separate sections**: Larger gaps (32-64px)\n\nThe principle: **proximity implies relationship**. Group related items tightly; separate unrelated items clearly.\n\n### Start with Too Much Space\n\nIt's easier to remove whitespace than to add it later. Start generous, then tighten only where needed. Most designs are too cramped, not too airy.\n\n### Padding Consistency\n\nButtons and inputs should have consistent internal proportions:\n- Horizontal padding: 1.5-2x vertical padding\n- Maintain aspect ratio across sizes\n\n```css path=null start=null\n/* Small */\n.btn-sm { @apply px-3 py-1.5; }\n\n/* Medium */ \n.btn-md { @apply px-4 py-2; }\n\n/* Large */\n.btn-lg { @apply px-6 py-3; }\n```\n\n---\n\n## Layout\n\n### Don't Fill the Whole Width\n\nContent shouldn't span edge-to-edge on large screens. Use max-width constraints:\n\n```css path=null start=null\n.container { \n max-width: 1200px; \n margin-inline: auto;\n padding-inline: 1rem;\n}\n```\n\n### Grids Aren't Always the Answer\n\nNot everything needs a 12-column grid. Simple layouts often work better with:\n- Max-width containers\n- Flexbox for alignment\n- Natural content flow\n\n### Give Elements Room to Breathe\n\nTight layouts feel cheap. Add generous padding to:\n- Cards and panels (24-32px minimum)\n- Sections (48-96px vertical)\n- Page margins (16-24px on mobile, more on desktop)\n\n### Alignment\n\n- **Left-align most text** (easier to scan)\n- **Center short headings and CTAs** (draws focus)\n- **Right-align numbers in tables** (decimal alignment)\n\n---\n\n## Mobile-First Responsive Design\n\n### Why Mobile-First\n\nStart with the mobile layout, then add complexity for larger screens. Benefits:\n- Forces prioritization of content\n- Simpler base styles\n- Progressive enhancement (works everywhere, better on larger screens)\n\n### Breakpoint Strategy\n\nDon't design for specific devices. Use content-based breakpoints:\n- Add a breakpoint when the layout breaks, not at arbitrary screen sizes\n- Common ranges: ~640px (sm), ~768px (md), ~1024px (lg), ~1280px (xl)\n\n### Mobile-First Patterns\n\n**Start simple, enhance up:**\n\n```css path=null start=null\n/* Mobile: stack vertically */\n.card-grid {\n display: grid;\n gap: 1rem;\n}\n\n/* Tablet+: 2 columns */\n@media (min-width: 768px) {\n .card-grid { grid-template-columns: repeat(2, 1fr); }\n}\n\n/* Desktop: 3 columns */\n@media (min-width: 1024px) {\n .card-grid { grid-template-columns: repeat(3, 1fr); }\n}\n```\n\n### Touch Targets\n\nMobile buttons and interactive elements need adequate tap targets:\n- **Minimum**: 44×44px (Apple HIG) or 48×48px (Material)\n- Add padding to small elements to increase hit area without visual bulk\n\n### Typography Scaling\n\nReduce heading sizes on mobile—there's less room for drama:\n\n```css path=null start=null\nh1 {\n font-size: 1.875rem; /* 30px mobile */\n}\n\n@media (min-width: 768px) {\n h1 { font-size: 2.5rem; } /* 40px tablet+ */\n}\n\n@media (min-width: 1024px) {\n h1 { font-size: 3rem; } /* 48px desktop */\n}\n```\n\n---\n\n## Depth and Shadows\n\nShadows create depth and separate layers. Use them intentionally:\n\n### Shadow Elevation System\n\nBuild a scale of shadows for different elevations:\n- **sm**: Subtle, for cards and slight lifts\n- **md**: Default, for dropdowns and popovers \n- **lg**: Prominent, for modals and dialogs\n- **xl**: Dramatic, rarely needed\n\n### Natural Shadow Direction\n\nLight comes from above. Shadows should:\n- Fall downward (positive Y offset)\n- Be slightly diffused (blur radius)\n- Use semi-transparent black, not gray\n\n```css path=null start=null\n/* Natural shadow */\nbox-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1);\n\n/* Unnatural (shadow going up) - avoid */\nbox-shadow: 0 -4px 6px rgb(0 0 0 / 0.1);\n```\n\n### Combining Shadows\n\nLayered shadows look more realistic:\n\n```css path=null start=null\n/* Two shadows: soft ambient + sharper direct */\nbox-shadow: \n 0 1px 3px rgb(0 0 0 / 0.1),\n 0 10px 20px rgb(0 0 0 / 0.05);\n```\n\n*Note: If your design system avoids shadows, use borders or background color differences to create separation.*\n\n---\n\n## Images and Icons\n\n### Icon Sizing\n\nIcons should feel balanced with adjacent text:\n- For inline icons: slightly smaller than text line-height\n- For standalone icons: size proportional to touch target\n\n```html path=null start=null\n\n\n```\n\n### Icon Stroke Width\n\nThinner strokes feel more refined, thicker strokes feel friendlier:\n- **1.5-2px**: Modern, elegant\n- **2-2.5px**: Balanced, versatile \n- **3px+**: Bold, playful\n\nMatch stroke weight to your typography weight.\n\n---\n\n## Empty States\n\nDon't leave empty states blank. They're an opportunity:\n- Explain what will appear here\n- Guide the user to take action\n- Use illustrations or icons to soften the emptiness\n\n```html path=null start=null\n
\n ...\n

No projects

\n

Get started by creating a new project.

\n \n
\n```\n\n---\n\n## Dark Mode Design\n\nDark mode isn't just inverting colors. It requires a different approach:\n\n### Reduce Contrast, Not Invert\n\n- **Don't use pure white text** on dark backgrounds—it's too harsh. Use `gray-100` or `gray-200`\n- **Don't use pure black backgrounds**—use `gray-900` or `gray-950` (e.g., `#0f172a`)\n- **Reduce elevation shadows**—they're less visible on dark; use subtle borders or lighter backgrounds instead\n\n### Color Adjustments\n\n```css path=null start=null\n/* Light mode */\n--bg-primary: #ffffff;\n--text-primary: #111827; /* gray-900 */\n--text-secondary: #6b7280; /* gray-500 */\n\n/* Dark mode - not just inverted */\n--bg-primary: #0f172a; /* slate-900 */\n--text-primary: #f1f5f9; /* slate-100 */\n--text-secondary: #94a3b8; /* slate-400 */\n```\n\n### Saturation Shifts\n\nColors appear more vibrant on dark backgrounds. **Reduce saturation** slightly for primary colors in dark mode to avoid overwhelming the user.\n\n### Surface Hierarchy\n\nUse lighter surfaces (not shadows) to indicate elevation:\n- **Base**: `bg-gray-900`\n- **Raised card**: `bg-gray-800`\n- **Modal/dropdown**: `bg-gray-700`\n\n---\n\n## Form Design Patterns\n\nForms are where users do work. Make them effortless:\n\n### Input Styling\n\n```css path=null start=null\n/* Well-designed input */\n.input {\n @apply w-full px-3 py-2\n text-gray-900 placeholder-gray-400\n bg-white border border-gray-300 rounded-lg\n focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent\n transition-shadow duration-150;\n}\n```\n\n### Label Placement\n\n- **Above the input** (not inline) for most forms—clearer scanning\n- **Floating labels** only if space is extremely tight\n- **Required indicators**: Use `*` after the label, not before\n\n### Error States\n\n- Change border to `border-red-500`\n- Add error icon inside input (right side)\n- Show error message below input in `text-red-600 text-sm`\n- Don't just rely on color—add an icon or text\n\n### Field Grouping\n\n```html path=null start=null\n\n
\n Billing Address\n \n
\n\n\n
\n Payment Method\n \n
\n```\n\n### Button Placement\n\n- Primary action on the **right** (or bottom-right for forms)\n- Secondary/cancel action on the **left** with less visual weight\n- Destructive actions should require confirmation\n\n---\n\n## Accessibility Beyond Contrast\n\nAccessibility is design quality, not a checkbox:\n\n### Focus States\n\n**Every interactive element needs a visible focus state.** Don't remove outlines without replacing them:\n\n```css path=null start=null\n/* Bad - removes accessibility */\n:focus { outline: none; }\n\n/* Good - replaces with visible ring */\n:focus {\n outline: none;\n ring: 2px;\n ring-color: blue-500;\n ring-offset: 2px;\n}\n\n/* Tailwind shorthand */\n.btn { @apply focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2; }\n```\n\n### Motion Sensitivity\n\nRespect `prefers-reduced-motion`:\n\n```css path=null start=null\n@media (prefers-reduced-motion: reduce) {\n *, *::before, *::after {\n animation-duration: 0.01ms !important;\n transition-duration: 0.01ms !important;\n }\n}\n```\n\n### Interactive Element Sizing\n\n- **Minimum touch target**: 44×44px (48×48px preferred)\n- **Adequate spacing** between clickable elements (at least 8px gap)\n- **Large enough text** in buttons—minimum 14px\n\n### Semantic HTML\n\n- Use `