I’ve been making games for 7 years at this point, and in that time, I’ve made over 20 games, many of which are various kinds of puzzle games. I want to talk about some of the principles that I’ve learned over the years about what makes good puzzles. I want to note that I am, of course, not authoritative on this subject. Game design is subjective in many ways, so you may find that you have different ideas on certain things, which is completely fine. But, I do think that I have a good amount of experience here, so I hope that you will find this useful in your own game development journeys.
The puzzle design tips we will be discussing are very broad. Your mileage may vary depending on what you are trying to make.
And with that all out of the way, lets get into it.

Part 1: The Spectrum of difficulty
Before we delve into the ‘do’s’ and ‘don’ts’ of puzzle design, we need to understand that puzzle difficulty lies on a spectrum. No difficulty on this spectrum is necessarily ‘good’ or ‘bad’. Rather, difficulty and the role it plays is dependent on the game you’re making, and your goals as a designer. In general, most games are going to want to fall in the medium range of the spectrum. However, some games may lean towards one side or the other depending on their goals in terms of the difficulty level of their game. Fore example, Riven makes puzzles that are very difficult, yet work within it’s world, and the story it’s trying to tell. Whereas The Room tends to be a little on the easier side, which lets players enjoy the experience of untangling the mechanical boxes the game presents to them. So keep in mind that puzzle and game difficulty will depend on your own personal goals as a designer, and what you want to do with your game. Many of the rules here still apply regardless of your games overall difficulty, but talented designers will understand when to bend or break these rules for the benefit of their games.

Part 2: Pacing Difficulty
Difficulty curves should never be purely linear. While a general upward trend is typical, the puzzles in a game should not simply get more difficult one after the other. Instead, it’s better to make your puzzles a bit more spread out, a bit like a rollercoaster. Rarely is it fun to be constantly going up high inclines and then back down, over and over and over again. We need to give people a little time to breath and process. In game design, this translates to spreading out your difficult puzzles among your medium puzzles. And when you do have a difficult puzzle, consider putting a few easier puzzles afterwards so the player has a little time to breath after solving something that required more brainpower. If you try to put one difficult puzzle after another, it gets really easier for players to tire out quickly.
Instead, difficulty curves should start off low, accelerate as the player leaves the intro/tutorial section of the game, and then mostly plateau for the rest of the game. Note that this is not an exact graph, but rather a general trend line. Players require time to breath after difficult puzzles, so often you will want to follow up harder challenges with easier ones. This gives players an opportunity to give their brain a break, and keeps them from burning out. In general, because we are working on a trend line, most puzzles will be relatively medium in difficulty, with small spikes and dips scattered throughout.

Part 3: Complex Puzzles
DO NOT EVER confuse complex with good. Puzzles with overly complex mechanics or that require mental gymnastics to understand should be avoided. Simplicity is the key in puzzle design. If there’s ever an extra step that feels unnecessary, try removing it. Too much complexity feels unfair, and makes players feel like the developer is padding out for time, which no one likes. If you do have to have a puzzle with some amount of complex mechanics, reuse those concepts in later puzzles, so the player doesn’t have to throw all that knowledge away.
Complex DOES NOT equal good. In fact, often times complex puzzles are poor design (with exceptions, because of course there are). If a puzzle has overly complex mechanics or requires mental gymnastics to understand, it is not good.
Once again, simplicity is often the key. This doesn’t mean making puzzles that are easy, but rather puzzles that have mechanics that are simple to understand. If a player is confused on what their actions are doing throughout solving a puzzle, or don’t understand what their goal is, then look to simplify a puzzle or explain it better. Often this can involve removing or simplifying lengthy or unnecessary steps that get in the way of solving the actual puzzle.

Part 4: Puzzles that make sense
Puzzles should follow an internal logic for the world in which they exist. This should be consistent within your game, and should be clearly communicated to the player. Players should not be left wondering what their goal is, instead they should be trying to figure out how to achieve that goal. If and when a player gets stuck on a puzzle, the reaction when they discover the solution (either by solving it or going to a walkthrough), should be ‘Why didn’t I think of that!’, and not ‘How could I have known to think that!’.

And to go along with this, we also want to avoid moon logic. Moon logic refers to when the solution for a puzzle is foreign enough that it is nearly impossible for most players to understand what to do. We want to avoid puzzles that contain moon logic, as they make for a poor experience for players. In general, the best way to avoid moon logic is to give the player plenty of clues so they understand what they’re doing. Make sure to playtest and get feedback on puzzles! And be open to changing puzzles when necessary.

Similarly, avoid solutions that only make sense through wordplay or puns. It is almost never obvious, because players are looking for solutions that make logical sense. Also, if you want to localise your game to other languages, than chances are any kind of puzzle that relies on wordplay just won’t work in another language (see: monkey island 2).

Part 5: Real world knowledge
Assuming your players will have the real-world context to solve puzzles is poor design. Whether they’ve come from a different culture, had a different level of education, or simply just don’t know about the reference you want to make, it can make puzzles impossible to solve without looking up information, which feels really bad for players. SIMPLE Addition and Subtraction in my opinion are really the only things that get a pass here. If you want to use real-world knowledge for a puzzle in-game, ALWAYS make sure that there is a way to learn that information in the game, assuming a player has never heard about whatever knowledge you are referencing.

Part 6: Puzzles and story
Many games in this genre have a strong focus on story. By combining story with gameplay, we open up interesting opportunities to tell stories. As often as possible, tie your puzzles into the games story or lore. Use them to convey information about the story. This helps reinforce your game’s story with the player, and can open up interesting storytelling opportunities.Think about what in-universe reason a puzzle would have to exist. How does it affect the characters? What can it tell about the world it exists in? Storytelling through puzzles is extremely satisfying, as it allows for players to learn about the games lore while solving puzzles. It is engaging, and enhances the storytelling and puzzles simaltaniosley.

Part 7: Avoiding repetition
Probably one of the most difficult things when designing puzzles is making them interesting, and avoiding repeating puzzles thorough your game. A variety of different puzzles, playing into different actions can keep a player engaged. Interesting puzzles are all about interaction. When puzzles can keep a player engaged, they’ll usually be interesting to a player. Don’t reuse the same idea too many times, and when you do reuse ideas, try to put a new spin on it. Where possible, add little interactions to a puzzle. Instead of just letting stuff happen, give the player an opportunity to push and pull stuff to make stuff happen. Try to come up with interesting locations and settings, and then think about what kinds of puzzle concepts that are specific to that particular kind of location (for example, mixing chemicals in a laboratory, or fixing some machinery in a factor, etc.) Take breaks! If you start to feel like you’re running out of ideas for puzzles, step away from puzzle design for a few days and come back to it later. You’ll often find new ideas and perspectives on things.

Part 8: Accessibility
It’s too often that I see games incorporate puzzles that don’t accommodate for the two biggest impairments for games: colourblindness, and deafness. Puzzles that include colour and sound are fun to make, and fun to play. I get it. I’ve made several colour-based puzzles in my time. However, there are certain consideration that we must make when designing puzzles to allow for more people to enjoy our games.
When it comes to colours, ALWAYS incorporate some sort of symbol or shape into the puzzle. Ideally, the puzzle should be aided by colour, but should still be 100% solvable without it. This way, someone who is colourblind can still solve the puzzle just fine, but those who can see the full range of colours can use that to help with the puzzle.

And when it comes to sound… Well, like colour, there should ALWAYS be some sort of visual element that can be deciphered without sound. This is not only important to those who are fully deaf or just tone deaf, but is also important for people who happen to be playing your game with the sound turned off. This is especially important if you’re developing for mobile. It’s not at all uncommon for players to just have their sound turned off when in public spaces, like a train or bus stop.
There are lots of other smaller accessibility considerations that can be made of course, but those are the main ones in terms of puzzle design.