Ui Refactor

UI Refactoring and Design

This skill applies tactical, logical rules to user interface design. It prioritizes clarity, hierarchy, and systems over "artistic talent."

Core Workflow

1. Feature First: Do not start by designing a "shell" (nav bars, sidebars). Start with the specific functionality (e.g., the search form, the contact card). 2. Low Fidelity: Ignore color, shadows, and fonts initially. Design in grayscale using a thick marker or basic wireframes to solve layout and spacing first. 3. Define Systems: Do not use arbitrary values. establishing restrictive systems for spacing, type, and color immediately. 4. Refine: Apply specific tactics for hierarchy, depth, and polish.

Domain-Specific Tactics

Consult these references for specific implementation rules:

• Making elements stand out/fit in: See hierarchy.md (Size, weight, contrast, semantics).
• Whitespace and alignment: See layout-spacing.md (Grids, spacing scales, density).
• Text and fonts: See typography.md (Type scales, line-height, fonts).
• Colors and palettes: See color.md (HSL, saturation, accessible contrast).
• Images, shadows, and polish: See depth-and-polish.md (Light sources, assets, finishing touches).

Quick Heuristics

• Limit Choices: If you can't decide between two options, you have too many choices. constrain your inputs (colors, font sizes, spacing) to a pre-defined scale.
• Personality:
• Serious/Elegant: Serif fonts, sharp corners, gold/blue colors, formal language.
• Playful/Friendly: Rounded sans-serifs, large border-radius, pink/orange, casual language.
• Complexity: Do not design for edge cases first. Design the "happy path" (simple version), then iterate for complexity.

Working with Color

Color Models

• Use HSL: Hue, Saturation, Lightness. It is intuitive.
• Hue: The "color" (0-360).
• Saturation: Vividness (0% grey, 100% pure).
• Lightness: 0% black, 100% white.

Palette Generation

Do not use "5 color generators." You need more colors than you think. 1. Greys: You need 8-10 shades. Tint them slightly blue (cool) or yellow (warm) to avoid "dead" greys. 2. Primary: 5-10 shades of your main brand color. 3. Accents: Semantic colors (Red/Destructive, Yellow/Warning, Green/Positive) need multiple shades for backgrounds vs text.

Creating Shades (The Curve)

Do not just lighten/darken the Lightness channel.

• Saturation Falloff: As lightness approaches 0% or 100%, perceived saturation drops. You must increase saturation for very light or very dark shades to prevent them from looking washed out.
• Hue Rotation: Rotate the hue slightly as you change lightness to mimic natural light.
• Darker: Rotate toward cool/dark colors (Blue/Purple/Red).
• Lighter: Rotate toward bright colors (Yellow/Cyan).

Accessibility & Contrast

• WCAG: 4.5:1 for normal text.
• Flip Contrast: If white text on a colored background is hard to read, do not darken the background until it looks black. Flip it: use dark text on a light colored background (e.g., a light red background with dark red text for errors).
• Rotating Hue: To increase contrast on colored text without making it black, rotate the hue toward a darker/brighter spectrum (e.g., darken yellow text by moving it toward orange).
• Color Blindness: Never rely on color alone. Use icons or text labels to accompany status colors (e.g., graphs, alerts).

Depth, Images, and Finishing Touches

Lighting and Shadows

Interfaces should emulate a physical light source (usually coming from the top).

• Raised Elements: Light top border (highlight), dark bottom shadow.
• Inset Elements (Wells): Dark top shadow (or inner shadow), light bottom border.
• Elevation System: Define 5 shadows.
• Small/Tight: Buttons (close to surface).
• Medium: Dropdowns.
• Large/Diffused: Modals (far from surface).
• Two-Part Shadows: Combine a large, soft, ambient shadow (general depth) with a tight, dark shadow (occlusion near the object).

Flat Design Depth

• Layers: Overlap elements to create depth (e.g., a card floating halfway off a colored header background).
• Color: Lighter feels closer; darker feels further away.

Images

• Text Overlay: Text on photos requires consistent contrast.
• Overlay: Semi-transparent black (for light text).
• Lower Contrast: Reduce the contrast of the background image itself.
• Colorize: Desaturate image + multiply blend mode with a brand color.
• Scaling:
• Do not scale up icons (they look blocky). Enclose small icons in a shape (circle/square) to fill space.
• Do not scale down screenshots (text becomes unreadable). Re-create simplified "illustration" versions of the UI, or crop to a detail view.
• User Content: Always control aspect ratios. Use background-size: cover or object-fit constraints. Prevent color bleed by adding a subtle inner shadow (inset) to user uploaded images.

Finishing Touches

• Supercharge Defaults: Replace standard bullets with checkmarks/icons. Style underlines on links.
• Accent Borders: Add a colorful 4px top-border to a bland card or alert to add personality without graphic design skills.
• Backgrounds: Use subtle repeating patterns or simple geometric shapes to break up large white backgrounds.
• Empty States: Never leave a container blank. Add an illustration and a primary call-to-action button (e.g., "Create your first project").

Hierarchy and Focus

Visual hierarchy is how important elements appear in relation to one another. It is the most effective tool for making a design feel "professional."

Strategies for Hierarchy

1. Size Isn't Everything

Do not rely solely on font size to denote importance.

• Weight: Make primary elements bolder (600/700) and secondary elements lighter (400). Avoid weights <400 for UI.
• Color: Use dark colors for primary content, grey for secondary, lighter grey for tertiary.
• Example: Instead of a tiny font size for a date, keep the size readable but make the color light grey.

2. De-emphasize to Emphasize

If a primary element doesn't stand out, do not make it louder. Instead, weaken the competing elements.

• Backgrounds: Remove background colors from secondary sidebars/containers so the main content pops.
• Soft colors: Turn valid but inactive navigation items into a soft grey rather than black.

3. Labels

Avoid Label: Value formats where possible.

• Combine: Instead of "In Stock: 12", use "12 left in stock".
• Context: If the format is obvious (email, phone, price), remove the label entirely.
• Secondary: If labels are required (e.g., data dashboards), treat them as supporting content (smaller, lighter weight, uppercase with letter-spacing) and emphasize the data.

4. Visual vs. Document Hierarchy

Web semantics (h1, h2, h3) should not dictate visual style.

• Section titles (like "Manage Account") are often just labels for the content below them. They should be small and subtle, not giant h1 styled headers.

5. Balancing Weight and Contrast

• Icons: Icons are visually "heavy" (solid surface area). To balance an icon next to text, give the icon a softer color (lower contrast).
• Borders: If a hairline border (1px) is too subtle, do not just darken the color (which adds noise). Increase the width (2px) instead to add weight.

6. Semantics are Secondary

Design buttons based on hierarchy, not just semantics.

• Primary: Solid, high contrast background.
• Secondary: Outline style or low contrast background.
• Tertiary: Link style (no container).
• Destructive: If a "Delete" button is not the primary action, do not make it big and red. Make it a secondary/tertiary link. Use the red/bold styling only for the confirmation modal where it is the primary action.

Layout and Spacing

Spacing Systems

Do not use arbitrary values (e.g., 123px).

• Linear scales fail: The difference between 12px and 16px is huge; the difference between 100px and 104px is invisible.
• The System: Start with a base (e.g., 16px). Create a scale where no two values are closer than ~25%.
• Example Scale: 4, 8, 12, 16, 24, 32, 48, 64, 96, 128.
• Workflow: Need space? Grab the next value on the scale. Not enough? Jump two steps.

White Space

• Start with too much: Give elements too much room, then remove until it looks "not bad."
• Separate groups: Ensure space between groups is larger than space within groups.
• Ambiguity: If a label's bottom margin equals the input's bottom margin, the relationship is unclear. Double the space between the input and the next label.

Sizing and Grids

• Shrink the Canvas: Do not fill the screen just because you have 1400px. If a form needs 600px, use 600px.
• Grids are Overrated: Do not force everything into percentage-based columns (e.g., 12-column grids).
• Sidebars: Should usually be fixed width (optimized for their content), while the main content flexes.
• Responsive Design:
• Use max-width rather than percentages. Only shrink elements when the screen gets smaller than the element's ideal size.
• Relative sizing fails: Do not use em for layout widths. Elements large on desktop should shrink faster than small elements on mobile. Sizing relationships are not linear across viewports.

Density

• Refactoring: Dense UIs (dashboards) are valid, but must be a deliberate choice.
• Columns: If a form feels too narrow/empty, split supporting text into a side column rather than widening the input fields.

Typography

Type Scales

Do not use linear pixel increments or mathematical ratios (Golden Ratio) that result in fractional pixels (33.14px).

• Hand-picked scale: Select a set of sizes that work well.
• Example: 12, 14, 16, 18, 20, 24, 30, 36, 48, 60, 72.
• Avoid ems for size: Use px or rem for font-size to guarantee you stay on the system. em compounds deeply nested sizes unpredictably.

Font Selection

• Safe Bet: Neutral sans-serifs (system stack, Helvetica, Roboto).
• Criteria:
• Choose fonts with 5+ weights (indicates quality).
• Avoid condensed fonts with short x-heights for UI body text.
• Trust popular fonts (Google Fonts sort by popularity).

Line Height

Line height is inversely proportional to font size and line length.

• Body text: Needs taller line height (~1.5 to 1.7).
• Headings: Large text needs tighter line height (~1.0 to 1.2).
• Line Length: Wide paragraphs need more line height to help the eye track back. Narrow columns can use tighter spacing.
• Optimal Length: 45-75 characters per line.

Alignment

• Left Align: The standard for readability.
• Justified: Avoid on web unless hyphenation is enabled; creates ugly "rivers" of white space.
• Center: Only for headlines or very short text blocks (2-3 lines max).
• Numbers: Always right-align tabular numbers/prices for comparison.
• Baseline: When mixing font sizes on a single row (e.g. "Price" and "$19"), align by baseline, not vertical center.

Letter Spacing

• Headlines: Tighten spacing slightly for large, display text.
• All Caps: Increase spacing (tracking) to improve readability.