Designilo

Introduction: Broken Buttons Break Trust

Buttons are small but mighty. When they don’t behave as expected—padding collapses, text clips, hover states disappear—users and developers lose confidence in your design system.

This guide covers the most common reasons components break in Figma (especially buttons) and walks you through how to debug and fix them, one layer at a time.

1. First, What Does “Breaking” Actually Mean?

In Figma, a component is considered “broken” when:

• Auto Layout behaves unexpectedly
• Text overrides don’t fit or wrap
• Hover/disabled states don’t work
• Components don’t resize correctly
• Tokens or variables don’t update across modes
• Layers shift or misalign on interaction

🛠 These aren’t always visible in the default state—but they surface in real-world usage and dev handoff.

2. Check for Auto Layout Misuse

Most button issues stem from misconfigured Auto Layout.

🔍 Common Mistakes:

• Mixed manual and Auto Layout resizing
• Incorrect padding values
• Misaligned text layers
• Auto Layout direction not matching the design intent

✅ Fix It:

• Apply Auto Layout to the container frame
• Set horizontal direction
• Use Hug contents for width, Fixed height or Hug for vertical
• Add equal padding on all sides (e.g. 12px)

💡 Use “Distribute spacing” if you have multiple elements (like icon + text).

3. Inspect Resizing Constraints

Inconsistent constraints break components when resized.

🔍 Check:

• Is the text set to “Fixed” when it should be “Hug”?
• Is the parent container using “Fill container” too aggressively?
• Do nested icons stretch unexpectedly?

✅ Fix It:

• Set text layers to Hug contents
• Use Center constraints for inline icons
• Keep nesting simple; deep nests cause unexpected results

🧪 Test by typing long labels like “Continue to Payment Portal.”

4. Debug Variants That Don’t Behave

Variants allow states like hover/pressed/disabled—but can fall apart if:

• One variant lacks Auto Layout
• Layer order isn’t consistent across variants
• A property (e.g. icon-left) is missing in a variant
• You forgot to apply variables to all states

✅ Fix It:

• Use the Component Properties panel to verify all variants have consistent properties
• Apply variables (e.g. colors, text styles) in every variant
• Match layer structure across all variants

💡 If hover state breaks, check for a mismatched background layer or missing color token.

5. Clean Up Style Overrides

When buttons are used in projects, designers may:

• Detach instances
• Override padding manually
• Change fill colors directly

Over time, this leads to chaos.

✅ Fix It:

• Lock layers that shouldn’t be edited
• Use Figma Variables instead of hardcoded styles
• Mark non-editable text layers as “non-editable” in the property panel

📌 Add documentation in the component to remind users how to safely customize.

6. Use Instance Swaps and Props Correctly

Modern Figma components use:

• Component properties (like iconLeft, hasShadow)
• Instance swaps (for icon or avatar slots)

🔍 Debug When:

• Icons disappear when swapping
• Props don’t trigger visibility changes
• Buttons show the wrong variant when used

✅ Fix It:

• Ensure all variants expose the same swap layers
• Double-check your boolean and instance properties in the right panel
• Preview behavior in the Assets > Instances menu

🧩 Great for “Icon only” vs “Text + Icon” button variants.

7. Simulate Real-World Use Cases

Before publishing a button, try:

Test	Why It Matters
Long label (30+ characters)	Exposes wrapping/padding bugs
Resize container frame	Tests responsive behavior
Switch to dark mode	Catches missing variable tokens
Swap in real icons or emojis	Checks for alignment & visual balance
Use in prototype	Confirms interactions and hover states

🎯 If it breaks here—it will break in production.

8. Use Plugins to Spot Breakage

Helpful plugins:

• Design Lint – spot style overrides and inconsistencies
• Instance Finder – locate broken variants
• Similayer – bulk select layers with the same issue
• Figma Tokens – verify if your color/spacing tokens are applied properly

✅ Fix once → apply everywhere.

9. Build a Debug Checklist

Create a QA checklist for every new component:

• Auto Layout applied and correct
• Text wraps without clipping
• Works with long/short labels
• Variants are consistent
• Variables used for all styles
• Resizes gracefully
• Dev Mode exposes tokens and specs

Use a page in your design system file titled: 🔎 Component QA Checks

Conclusion: Debug Early, Publish Confidently

A great button works in every state, screen, and theme. By debugging your components thoroughly, you reduce tech debt, avoid visual bugs, and empower developers with rock-solid design specs.

Next up: “Smart Component Properties: The Secret to Cleaner Figma Libraries” — where we dive into how properties transform component reuse and customization.