sglavoie.com – Tag: Design

Reading notes: A Philosophy of Software Design, 2nd Edition

Sébastien Lavoie — Sun, 30 Mar 2025 11:18:00 -0600

Nature of complexity

“Change amplification: The first symptom of complexity is that a seemingly simple change requires code modifications in many different places.” (e.g., refactoring a project to inject dependencies in tests, because the system was hard to test in the first place)
“Cognitive load: The second symptom of complexity is cognitive load, which refers to how much a developer needs to know in order to complete a task.” (e.g., close a file where it is opened whenever possible, instead of leaking context and pushing the responsibility onto the caller)
“Unknown unknowns: The third symptom of complexity is that it is not obvious which pieces of code must be modified to complete a task, or what information a developer must have to carry out the task successfully.”
“One of the most important goals of good design is for a system to be obvious.”

Strategic vs. tactical programming

“it’s worth taking a little extra time to find a simple design for each new class; rather than implementing the first idea that comes to mind, try a couple of alternative designs and pick the cleanest one. Try to imagine a few ways in which the system might need to be changed in the future and make sure that will be easy with your design”

Modules should be deep

Modular design
- “In general, if a developer needs to know a particular piece of information in order to use a module, then that information is part of the module’s interface.”
Abstractions
- “The key to designing abstractions is to understand what is important, and to look for designs that minimize the amount of information that is important”
A deep module is one in which the interface is small and the implementation is large.
- “Deep modules such as Unix I/O and garbage collectors provide powerful abstractions because they are easy to use, yet they hide significant implementation complexity.”
Shallow modules
- “A shallow module is one whose interface is complicated relative to the functionality it provides.”

Information hiding

“If a piece of information is hidden, there are no dependencies on that information outside the module containing the information, so a design change related to that information will affect only the one module”
Information leakage
- “If the affected classes are relatively small and closely tied to the leaked information, it may make sense to merge them into a single class.”
- “When designing modules, focus on the knowledge that’s needed to perform each task, not the order in which tasks occur.”
- “it’s important to avoid exposing internal data structures as much as possible”
“The best features are the ones you get without even knowing they exist.”
“As a software designer, your goal should be to minimize the amount of information needed outside a module; for example, if a module can automatically adjust its configuration, that is better than exposing configuration parameters”
“think about the different pieces of knowledge that are needed to carry out the tasks of your application, and design each module to encapsulate one or a few of those pieces of knowledge. This will produce a clean and simple design with deep modules.”

General-Purpose Modules are Deeper

“specialization leads to complexity”
Generality leads to better information hiding
“Eliminate special cases in code”

Different Layer, Different Abstraction

“A pass-through method is one that does nothing except pass its arguments to another method, usually with the same API as the pass-through method. This typically indicates that there is not a clean division of responsibility between the classes.”

Pull Complexity Downwards

Figure out complexity in the library instead of pushing it up to the user.
"[…] you should avoid configuration parameters as much as possible. Before exporting a configuration parameter, ask yourself: will users (or higher-level modules) be able to determine a better value than we can determine here?"

Better Together Or Better Apart?

“Bring together if information is shared”
“Bring together if it will simplify the interface”
“Bring together to eliminate duplication”
- Use goto to exit nested code blocks early as long as it’s not too complex.
On Splitting long methods: “If you make a split of this form and then find yourself flipping back and forth between the parent and child to understand how they work together, that is a red flag (“Conjoined Methods”) indicating that the split was probably a bad idea.”
“If the caller has to invoke each of the separate methods, passing state back and forth between them, then splitting is not a good idea.”

Define Errors Out Of Existence

“The key overall lesson from this chapter is to reduce the number of places where exceptions must be handled; in some cases the semantics of operations can be modified so that the normal behavior handles all situations and there is no exceptional condition to report […].”
“The best way to eliminate exception handling complexity is to define your APIs so that there are no exceptions to handle: define errors out of existence”
E.g., the Java substring method could remove its IndexOutOfBoundsException by automatically rounding the index to the nearest valid value.
"Exception masking doesn’t work in all situations, but it is a powerful tool in the situations where it works. It results in deeper classes, since it reduces the class’s interface (fewer exceptions for users to be aware of) and adds functionality in the form of the code that masks the exception. Exception masking is an example of pulling complexity downward."
“The idea behind exception aggregation is to handle many exceptions with a single piece of code; rather than writing distinct handlers for many individual exceptions, handle them all in one place with a single handler.” (e.g., a web server dispatching different types of requests and catching all sorts of errors).
“In most applications there will be certain errors that are not worth trying to handle. Typically, these errors are difficult or impossible to handle and don’t occur very often. The simplest thing to do in response to these errors is to print diagnostic information and then abort the application.” (e.g., out-of-memory errors).

Design it Twice

“The initial design experiments will probably result in a significantly better design, which will more than pay for the time spent designing it twice”
“The process of devising and comparing multiple approaches will teach you about the factors that make designs better or worse. Over time, this will make it easier for you to rule out bad designs and hone in on really great ones.”

Why Write Comments? The Four Excuses

Good code is self-documenting. Comments serve as precisions on abstractions.
I don’t have time to write comments. The benefits of having documentation quickly offset the cost of writing it.
Comments get out of date and become misleading. Keep the documentation close to where it needs to be, so you update it.
All the comments I have seen are worthless. Be the change you want to see.
Benefits of well-written comments
- “The overall idea behind comments is to capture information that was in the mind of the designer but couldn’t be represented in the code.”
- “One of the purposes of comments is to make it it unnecessary to read the code.”

Comments Should Describe Things that Aren’t Obvious from the Code

Don’t repeat the code
“Lower-level comments add precision”
- Focus on what the variable represents, not how it is modified (the latter is explained by the code).
“Higher-level comments enhance intuition”
- “What is the simplest thing you can say that explains everything in the code? What is the most important thing about this code?”
Interface documentation
“Implementation comments: what and why, not how”
- Describe at a more abstract level to help understand what is happening and why. The code tells the how.
Cross-module design decisions
- One possible solution is to use a designNotes.md file or similar to jot down all major decisions, and point to it from the code (e.g., See topic in designNotes).

Choosing names

Great names are “precise, unambiguous, and intuitive.”
Use names consistently: make it so that a concept is expressed in the same words regardless of the context in which it is found if it makes sense to do so.
Avoid extra words: no more Hungarian Notation with modern IDEs.

Use comments as part of the design process

Delayed comments are bad comments
- You won’t remember exactly what you had in mind and why you did things if you delay writing documentation: design decisions will get lost.
Write the comments first
- No backlog of unwritten comments.
- “it produces better comments.”
Comments are a design tool
- Writing them at the beginning “improves the system design.”
- “If a method or variable requires a long comment, it is a red flag that you don’t have a good abstraction.”
Early comments are fun comments
- “If you are programming strategically, where your main goal is a great design rather than just writing code that works, then writing comments should be fun, since that’s how you identify the best designs.”
- “I’m looking for the design that can be expressed completely and clearly in the fewest words. The simpler the comments, the better I feel about my design.”
Are early comments expensive?
- “Writing the comments first will mean that the abstractions will be more stable before you start writing code.”
- “In contrast, if you write the code first, the abstractions will probably evolve as you code, which will require more code revisions than the comments-first approach.”

Modifying existing code

“Whenever you modify any code, try to find a way to improve the system design at least a little bit in the process. If you’re not making the design better, you are probably making it worse.”
Maintaining comments: keep the comments near the code
- “The farther a comment is from its associated code, the less likely it is that it will be updated properly.”
- “In general, the farther a comment is from the code it describes, the more abstract it should be (this reduces the likelihood that the comment will be invalidated by code changes).”
Comments belong in the code, not the commit log
- “An example is a commit message describing a subtle problem that motivated a code change. If this isn’t documented in the code, then a developer might come along later and undo the change without realizing that they have re-created a bug.”
Maintaining comments: avoid duplication
Maintaining comments: check the diffs
- Review changes during the pre-commit phase to make sure documentation stays up-to-date with the code changes.
Higher-level comments are easier to maintain
- Most helpful comments do not repeat the code, they provide an abstraction that can’t be expressed easily by the code alone.

Consistency

Similar things are done in a similar way.
“Consistency creates cognitive leverage: once you have learned how something is done in one place, you can use that knowledge to immediately understand other places that use the same approach.”
Ensuring consistency
- Document most important conventions.
- “the value of consistency over inconsistency is almost always greater than the value of one approach over another.”

Code should be obvious

“the best way to determine the obviousness of code is through code reviews”
“If someone reading your code says it’s not obvious, then it’s not obvious, no matter how clear it may seem to you”
Things that make code more obvious
- Good names
- Consistency
- Judicious use of white space
- Blank lines
- Comments
Things that make code less obvious
- Event-driven programming
- Generic containers
- Different types for declaration and allocation

Software trends

Object-oriented programming and inheritance
- “In order for an interface to have many implementations, it must capture the essential features of all the underlying implementations while steering clear of the details that differ between the implementations; this notion is at the heart of abstraction.”
- “Class hierarchies that use implementation inheritance extensively tend to have high complexity.”
- “Before using implementation inheritance, consider whether an approach based on composition can provide the same benefits.”
Agile development
- May encourage a more tactical approach to programming. Balance is required.
Test-driven development
- “it focuses attention on getting specific features working, rather than finding the best design”
- “One place where it makes sense to write the tests first is when fixing bugs. Before fixing a bug, write a unit test that fails because of the bug.”
Design patterns
- “As with many ideas in software design, the notion that design patterns are good doesn’t necessarily mean that more design patterns are better.”
Getters and setters
- “It’s better to avoid getters and setters (or any exposure of implementation data) as much as possible.”

Designing for performance

How to think about performance
- “The key is to develop an awareness of which operations are fundamentally expensive.”
Measure before (and after) modifying
- “the goal is to identify a small number of very specific places where the system is currently spending a lot of time, and where you have ideas for improvement.”
- “If the changes didn’t make a measurable difference in performance, then back them out (unless they made the system simpler).”
Design around the critical path
- “When redesigning for performance, try to minimize the number of special cases you must check.”
“Complicated code tends to be slow because it does extraneous or redundant work.”

Decide what matters

Minimize what matters
How to emphasize things that matter
- “important things should appear in places where they are more likely to be seen, such as interface documentation, names, or parameters to heavily used methods.”
- “repetition: key ideas appear over and over again.”
- “The things that matter the most should be at the heart of the system, where they determine the structure of things around them.”
Mistakes
- “treat too many things as important. When this happens, unimportant things clutter up the design, adding complexity and increasing cognitive load.”
- “fail to recognize that something is important. This mistake leads to situations where important information is hidden, or important functionality is not available so developers must continually recreate it.”
Thinking more broadly
- “the best way to make a document easy to read is to identify a few key concepts at the beginning and structure the remainder of the document around them. When discussing the details of a system, it helps to tie them back to the overall concepts.”
- “Focusing on what is important is also a great life philosophy: identify a few things that matter most to you, and try to spend as much of your energy as possible on those things.”

Conclusion

“The reward for being a good designer is that you get to spend a larger fraction of your time in the design phase, which is fun. Poor designers spend most of their time chasing bugs in complicated and brittle code.”

Book summary: Refactoring UI

Sébastien Lavoie — Sat, 09 Sep 2023 17:56:00 -0600

Introduction

It covers core principles like establishing consistent systems for recurring elements such as spacing and typography.
It advises generous use of white space and thoughtful visual hierarchy.
Steps for adding depth through lighting, shadows, and layers are outlined.
Recommendations are provided for working with images and illustrations effectively.
Tips on elevating default elements and breaking conventions to avoid typical, cookie-cutter designs are included.
Studying other designers’ work and unintuitive decisions is encouraged to expand one’s skills.
The goal is to equip readers with knowledge to thoughtfully craft interfaces that appear purposefully designed without simply mimicking common graphical tropes.
By learning fundamental visual design concepts tailored to user interfaces, anyone can create clean, functional, and visually engaging digital experiences.

Starting from scratch

Start with a feature, not a layout
- Design the shell and navigation later once you know what features you need.
Detail comes later
- Design with a big sharpie.
- Design in grayscale to use spacing, contrast and size to do the heavy lifting.
Don’t over-invest
- Go with low-fidelity sketches and wireframes first to move fast. Don’t get bogged down with details like fonts and colors early on.
Don’t design too much
- Work in cycles: design a feature simply, build it, fix errors.
- Be a pessimist: expect it to be hard to build, and postpone building it (e.g., commenting system without attachments at first).

Choose a personality

Font choice
- Elegant/classic: serif
- Playful: Sans-serif
- Plain: neutral sans-serif
Color
- Blue: safe and familiar, good overall pick.
- Gold: expensive, sophisticated.
- Pink: more fun, less serious.
Border radius
- Small – neutral, not much personality.
- Large – more playful.
- None – more serious/formal.
- Stay consistent – either rounded or not, same everywhere.
Language
- Choose the right words for the desired tone.
Decide what you actually want
- Look at the websites your expected customers use? Serious, then that’s the feel. Playful? Then that.

Limit your choices

Define systems in advance
- Have a working palette color and limit yourself to it.
- Use a type scale to avoid picking specific font sizes.
Designing by process of elimination.
Systematize as much as possible to avoid repetitive low-level decisions.

Hierarchy

Visual hierarchy refers to how elements appear in importance relative to one another.
Don’t let HTML semantics dictate visual styling – style based on visual hierarchy.
Size isn’t everything. Bold font communicates importance. De-emphasize secondary/tertiary information to highlight the most important elements.
Rely on font weight and color, not just font size, to create hierarchy.
Limit yourself to 2-3 colors and font weights to define hierarchy.
On colored backgrounds, pick a color with similar hue but lower saturation/lightness rather than just making text gray.
Avoid label: value formats – use formats, context, and combined labels/values for clarity without labels.
Treat labels as secondary content when needed – smaller, lower contrast, lighter weight.
De-emphasize competing elements instead of just emphasizing the key element.
Combine labels and values: e.g., instead of “In stock: 12”, use “12 left in stock”.
Treat labels as supporting content.
Design buttons based on hierarchy, not just semantics. Primary/destructive actions don’t always need prominence.

Layout and spacing

Start with too much white space, then remove until happy – often ends up being “just enough”.
Compact layouts have their place but should be a deliberate choice, not the default.
Establish a spacing and sizing system
- A linear scale won’t work
- Create a constrained spacing/sizing system based on a base unit (like 16px) to work faster with more consistency.
Don’t feel the need to fill the whole screen – give elements only the space they need.
Grids are overrated
- Not all elements should be fluid
- Don’t shrink an element until you need to.
- Grids can bring order but don’t have to dictate every layout decision.
Balance layouts in columns instead of just making things wider.
Relative sizing doesn’t scale.
- Fix element widths when flexibility isn’t needed.
- Scale elements independently – don’t rely on relative units like em.
Avoid ambiguous spacing: increase spacing between groups and reduce spacing within groups to show relationships.

Text

Establish a constrained type scale to speed up font size decisions and add consistency. Avoid strict modular scales.
Use pixel or rem units – not em – to guarantee sizes match the scale.
For UI design, pick scale values by hand instead of using a mathematical ratio.
Use high quality fonts – safe bets are neutral sans-serifs and system fonts.
Use the system stack if not sure: -apple-system, Segoe UI, Roboto, Noto Sans, Ubuntu, Cantarell, Helvetica Neue;
Favor fonts with 5+ weights and optimized for legibility.
Keep line length between 45-75 characters (20-35 em) for optimal readability.
Align mixed font sizes by their baselines, not centers.
Use taller line-heights for small text and shorter line-heights for large text.
Subtly emphasize links in UIs, no need for high contrast colors.
Left align most text, right align numbers in tables. Justify only with hyphenation.
Don’t center long form text.
Tighten letter-spacing for headlines set in text faces. Loosen letter-spacing for all-caps.
Not all links need to be emphasized boldly, especially in UIs where there is plenty of interactivity.

Colors

HSL (hue, saturation, lightness) is more intuitive to the human eye: use it instead of HEX and RGB.
- Hue is the color position on the color wheel. 0° is red, 120° is green, and 240° is blue.
- Saturation represents the vividness. 0% is grey while 100% is vibrant and intense.
- Lightness measures how close a closer is to black (0%) or white (100%), where 50% is the pure color.
HSL is not the same as HSB (lightness != brightness). In HSB, 0% brightness is always black but 100% brightness is white when saturation is set to 0%.
- With 100% saturation in both HSL and HSB, 100% brightness is equivalent to 50% lightness (pure color).
Don’t rely solely on color to convey information - support it with other indicators.

A good color palette

You need more colors than you think - aim for 10+ shades of greys, primary colors, and accent colors.
Grey
- There is a lot of grey in UIs: between 8-10 shades of grey is a good array of options to pick from. Use very dark grey instead of true black so it looks more natural.
Primary colors
- 1 or 2 is great, with 5-10 different shades (e.g., Facebook is basically blue). A very light shade is good for a tinted background (e.g., alerts), darker shades work great for text.
Accent colors
- Use sparingly.
- Needed to bring semantic meaning, such as red for danger, yellow for warnings and green for positive trends.
- For a complex UI, can be as many as 10 different colors, each with 5-10 shades.

Building a color palette

Define color shades upfront instead of generating on the fly. Pick base, darkest, lightest, then fill in gaps.
Don’t rely purely on math to generate shades - trust your eyes and tweak if needed.
Choose the base color first. This is the color in the middle that light and dark shades are derived from.
Center: pick a shade that would work well as a button background.
Extremes: pick the lightness color to work as a background and the darkest to work on top as text to get enough contrast.
Repeat the process to pick the remaining colors in between. 9 shades is a good sweet spot as it divides cleanly.
For grays, the base color doesn’t matter nearly as much: same process.

Perceived brightness

In the HSL system, the further away a color is from 50% lightness, the more saturated it should be so it doesn’t look washed out.
The perceived brightness of a color to the human eye can be calculated as follows:

brightness = √(0.299·r² + 0.587·g² + 0.114·b²) / 255

Green is perceived as more bright than red, which in turn is perceived as more bright than blue. With this data point, we can tweak the perceived brightness of a color by rotating the color wheel towards the desired perceived brightness.
Grays aren’t usually totally desaturated.
- To make them feel “cool” saturate them with some blue.
- To make them feel “warm”, saturate them with yellow or orange.
- The same “saturation curve” applies to grays: the further away from 50% brightness, the more they should be saturated to avoid looking washed out.

A word on accessibility

Instead of having elements like dark-colored pills with a white foreground color, flip the contrast by having light-colored pills with a dark version of the color in the foreground so they won’t grab too much attention.
Rotate the hue to make the color pop more. For instance, instead of cranking up the lightness to meet ideal contrast ratios, rotate the hue and possibly keep the saturation high for a vibrant contrast.
Don’t rely on color alone
- Add visual cues (like arrows for upward/downward trends). Designing in grayscale first will help spot these kinds of issues.
- For things like a graph, playing with contrast will produce clearer results.

Depth

Mimic how light works in the real world.
- Emulate a light source coming from above to make elements appear raised or inset.
- For instance, with a button, if light comes from above, then the top should be lighter (e.g., box-shadow inset) than the bottom (box-shadow, casting shadow only below).
- For elements that are “inset” (I.e., more depth in the center), the opposite effect should happen: more light reaches the bottom part (vertical box-shadow, going up) than the top part (box-shadow inset such that it casts some shadow towards the bottom).
Don’t overdo it.

Shadows

Use shadows to convey elevation
- When something appears to be raised from the background (e.g., bigger drop-shadow), it attracts the user’s focus.
- Small shadows are useful to attract attention to the primary action to be performed.
- Medium shadows are useful for things like a dropdown so it looks separate from the background.
- Large shadows are great for modals.
- 5 options is usually plenty.
- Can be used for interactivity, like when dragging a row from a table.
- A button can feel like it’s being “pressed” by reducing its shadow on click (i.e., it gets closer to the page or farther away from the user).
- Casting shadows
  - To simulate a shadow cast by direct light (e.g., a long shadow behind a plant getting some sunlight), use a larger, more diffuse and subtle shadow.
  - To simulate a shadow cast by ambient light (e.g., the shadow right below the plant’s pot where light can’t hardly reach), use a narrow and darker shadow.
  - Apply both types of shadow casting at once to create visually compelling effects.
Define a fixed set of shadows as an elevation system for consistency.
Even flat designs can have depth
- Flat design does not convey depth with shadows and gradients.
- Create depth with color: lighter colors feel closer.
- Can use short, offset shadows with no blur at all.
Overlap elements to create layers
- E.g., position a block with a negative margin so it appears on top of two different sections.
- For smaller elements like avatars, an invisible border around it can make it pop better.

Images and contrast

Images
- Use high quality photos - hire a pro or use stock sites for generics. Don’t expect good results from phone pics.
Text needs consistent contrast
- Add an overlay to background images to get readable headlines.
- Lower the image contrast. Adjust the brightness to compensate.
- Colorize the image with a single color.
- Use text shadows instead of overlays to preserve image dynamics.

Scale

Don’t scale up icons
Even for SVGs, they will lack detail if they were designed correctly at a smaller scale: use a more detailed icon instead.
If updating the icon is not an option, enclose it inside another shape (e.g., a circle with a background color) to occupy more space.
Don’t scale down screenshots
Details will be distorted and hard to read.
Either use a presentation from a smaller device (e.g., the tablet version on a desktop) or take a partial screenshot (e.g., “zoom in” effect with a circle or simply crop the original image).
If a more complex UI needs to be presented, simplify the original image so the user doesn’t try to read a 4px font size but instead sees simpler shapes.
Don’t scale down icons
E.g. for a favicon, redraw a simplified version instead: details will look fuzzy at a small size.
User-submitted content (e.g., Instagram feed)
Control the size and shape: crop images to keep the aspect ratio of containers so they don’t disturb layout (e.g., background-size: cover).
Add inner shadows or borders to user images to prevent background bleed.

Finishing touches

Use icons instead of bullets in a bulleted list.
Play with size and colors. E.g., you can have huge quotes around the block of text representing a testimonial.
Links deserve special styling.
Use custom checkboxes and radio buttons in forms: integrate the brand’s primary color(s).
Add color with accent borders, e.g. across the top of a card element, when highlighting active elements in the UI or to the left of alert messages.
Decorate backgrounds
- Change the background color. Works great for different page sections.
- Can use gradients: use two hues that are within 30˚ of each other.
- Use repeating patterns.
Consider the empty state carefully, especially when the user is meant to fill the UI with data.
- Prioritize empty states with illustrations and clear calls to action.
- I.e., a contact page with no contacts should feel welcoming, with some icon and button to add a contact instead of a blank page with an error-like statement.
- Similarly, things like dashboard may present a bunch of options that won’t apply until there is something to show: simplify the user experience.
Use less borders
- Use box shadows, spacing, and color instead of borders to distinguish elements.
- Have two background colors for containers (e.g., darker footer that looks separate from the main content).
- Replace borders with additional spacing.
Make components more exciting
- E.g., a table may not need all its columns if a particular column does not need to be sorted and could instead be part of another one (e.g., combining a dollar amount with a plan type or a person’s name with its title).
- Radio buttons could be cards instead if they are an important part of the UI.

Next level

Look for unintuitive decisions in designs you admire to find new ideas.
Rebuild interfaces you love to discover small details that make them exceptional.
Study others to build a solid foundation.

Conclusion

The concepts covered in this book demonstrate that effective visual design does not require innate artistic talent or formal training. By approaching interfaces methodically, establishing constraints through systems for recurring elements, and learning to strategically apply principles like visual hierarchy, white space, and depth cues, anyone can create designs that appear polished and purposeful. While internalizing these fundamentals does take practice, the ideas presented remove much of the subjective, nuanced expertise needed for things like picking complementary colors or balancing composition in illustrations.

By focusing on interfaces rather than free-form graphical work, the required skills become more structured and intentional choices drive outcomes. While studying formally can provide more breadth, the core principles in this text are enough to equip non-designers with the ability to build clean, intuitive, and aesthetically pleasing digital products. By implementing the recommendations covered, engineers and others new to design can gain confidence in their interface design skills. A great, concise read!