Why your web app looks different from the design

1. A design shows one screen size; a browser shows hundreds

Designs are usually drawn on a few fixed frames, for example a 1440-pixel desktop and a 390-pixel phone. Real visitors use laptops at 1280 pixels, tablets, large monitors and browser windows resized to half the screen. The developer has to decide what happens between those frames. If the design does not say, the layout will be interpreted.

Specify how each layout behaves as space changes. Which columns stack first? Does the content area stretch or stop at a maximum width? Does a table scroll horizontally, hide columns, or turn into cards on a phone? Design tools can express much of this through auto layout and constraints, but behavior that matters should be written down.

• The breakpoints the product supports.
• The maximum content width on large screens.
• How navigation, tables and forms adapt on small screens.
• Which elements may wrap, shrink, truncate or hide.

2. Real content is longer, shorter and messier than the mockup

Mockups often use a short name, a perfectly cropped photo and a round number. Production data includes 40-character company names, empty descriptions, portrait photos where the design expected landscape, and prices with several digits. A card that looked balanced with "Jane Doe" can break with a long hyphenated surname.

Translation makes this more visible. German text is often around 30 percent longer than English, and short labels can expand far more. Right-to-left languages such as Arabic and Urdu reverse the layout direction and need their own typographic testing.

Design with realistic content from the start. Use real or representative data, include the longest and shortest expected values, and decide what happens when content is missing. For example, should a long title wrap to two lines or be shortened with an ellipsis? Should a missing image show a placeholder, initials or nothing? Code Huddle's QOM News case study describes an English–Urdu publication with right-to-left layouts and Nastaliq typography, the kind of product where content-driven design decisions shape the whole interface.

3. Undesigned states get improvised

Many design files show only the ideal moment: the form filled in correctly, the list full of results, the dashboard loaded. Developers also have to build what happens before, after and around that moment. When those states are missing, each developer invents them, and the product starts to feel inconsistent.

Every interactive element and every data-driven screen needs its states defined. A button has default, hover, keyboard focus, pressed, disabled and loading states. A list has loading, empty, error and "no search results" states. A form needs inline validation messages and a clear way to recover from a server error.

• Loading and skeleton states.
• Empty states for new accounts and filtered lists.
• Error messages and recovery actions.
• Hover, focus, active and disabled states.
• Success confirmations and their duration.

A shared component library helps. Once a button or input has all its states designed and built, every new screen inherits them instead of reinventing them.

4. Text, fonts and color render differently in a browser

Design tools and browsers do not render text identically. Line height, letter spacing and font smoothing can differ slightly, and Windows and macOS render the same font differently. A heading that fits on one line in the design file may wrap in the browser at the same width.

Fonts also need a licence that covers web use. If a font is not available or still loading, the browser displays a fallback font with different proportions, which can shift the layout. Choose fonts early, confirm the licence, and define a fallback with similar metrics.

Color varies by screen as well. Displays differ in brightness and color range, so the same value can look warmer on one monitor than another. Judge color on more than one real device rather than comparing a screenshot with the design file side by side.

5. One-off values make the build drift

A design that uses 14 slightly different grays, spacing of 13, 15 and 18 pixels, and four font sizes for the same kind of heading is hard to build accurately. Developers usually round these values to the nearest consistent one. The result is close to the design, but not identical, and neither side may notice until a pixel comparison.

Define design tokens: a named set of colors, spacing steps, font sizes, corner radii and shadows. Use them in the design file and in the code. When the product team wants something outside the system, treat it as a deliberate decision to add a new token, not a one-off adjustment. This keeps future screens consistent without needing a designer to check every margin.

If the product uses an existing component library, design within its capabilities or budget for customizing it. A design that ignores the library's structure may require rebuilding components the client assumed were included.

6. Some differences are deliberate, and they should be

Not every difference is a defect. Accessibility requirements can change the visual result. The Web Content Accessibility Guidelines (WCAG) 2.2 require a contrast ratio of at least 4.5:1 for normal-size text at level AA. A pale gray label that looked elegant in the mockup may need to be darker. Keyboard users need a visible focus indicator, and small icons need enough space around them to be tapped reliably.

Technical constraints can also justify a change, such as how a third-party payment form or map is embedded, or what data the system can return on one screen. The important point is that these decisions are discussed and recorded. A developer should not silently change a design, and a designer should not reject a necessary change without understanding the reason.

7. Review the build like a designer before release

Schedule a design review of the working build, not only of screenshots. Test on real devices and browsers, at awkward widths, with real data, using the keyboard as well as the mouse. Compare against the agreed rules: tokens, components, states and responsive behavior.

Sort findings into three groups. Broken items stop someone from completing a task or reading content. Inconsistent items depart from the design system without a reason. Acceptable differences are small rendering variations that users will not notice. Fix the first group before launch, schedule the second, and record the third so it is not reported again.

Common mistakes to avoid

Most design and build mismatches can be predicted. They appear when a design is handed over as a set of pictures rather than a description of how the product should behave.

• Designing only desktop and phone frames with nothing in between.
• Using perfect sample content instead of realistic data.
• Leaving out loading, empty, error and focus states.
• Choosing fonts without checking web licensing and fallbacks.
• Using one-off colors and spacing instead of a shared system.
• Judging the build from screenshots instead of real devices.
• Treating every pixel difference as a defect.

What to agree before design and development start

Agree the supported browsers, devices and screen widths, the languages the product will support, and the accessibility level it must meet. Decide whether the project uses an existing component library or a custom design system, and who approves changes to it.

Ask for a handoff that includes components with all their states, design tokens, responsive behavior notes and realistic content examples. Plan time for designers and developers to review the build together during development, not only at the end. When everyone works from the same rules, the finished product looks like the design because both were built from the same decisions.