Logging: Record Component Errors, Warnings, and Build Failures So Teams Can Fix Them
Learn what a design system should record, how to write each log entry so it helps, and how teams read the logs to find and fix problems.
In short
Logging in a design system means recording component errors, warnings and build failures with enough context that teams can find and fix problems.
13 min readFree
What you will learn
Logging is how a design system keeps a written record of what its parts and tools do. Some records describe normal work. Others describe problems. In this lesson you will learn what a design team should log, how to write each entry so it helps, and how teams read the record to find and fix issues.
Logging matters more in a design system than in a single app. One shared Button or Modal can be used by many product teams. A fault can appear in many places at once, and a good log can show where it started.
Key words
- Design system
- A shared set of parts, rules, and tools that product teams reuse instead of building their own.
- Component
- One reusable part, such as a button, a modal window, or a text field.
- Log
- A written record of one event, kept so people can read it later.
- Event
- Anything that happens in a component or tool, such as opening, failing, or being used.
- Log level
- A label that shows how serious a log entry is, such as error or info.
- Deprecated
- Marked as old. It still works for now, but it is planned for removal.
- Build
- The automatic process that packages the design system into a form product teams can use.
- Release
- A published version of the design system that product teams can install.
- Consumer
- A product team that uses the design system in its own app or website.
- Context
- Extra facts stored with a log entry, such as the component name, its version, and where it ran.
- Environment
- The place where the code runs, such as a developer's computer, a test site, or the live product.
- Sensitive data
- Private facts about a person or account, such as passwords, login tokens, or email addresses.
- Triage
- Sorting issues by how serious they are and deciding who should act first.
What does logging mean in this course?
In this course, logging means recording events and errors from a design system's components and tools. Examples include a component that fails to show on screen, a product that uses an old setting, or a build that stops before it finishes. The log is the raw record of what happened. Later, teams can use that record to count trends and judge health. Those uses belong to other lessons. This one stays on the record itself.
Logging is different from testing. Testing checks parts before a release, so problems are caught early. Logging records what still happens after the parts reach real people and real products. A good design system uses both, because no test can predict every situation a product team will create.
What should you log?
A design system should log events that help someone act. Four groups matter most: component errors, deprecation warnings, build and release failures, and tooling issues. Each group is explained below. Logging everything is not the goal. Logs that capture useful, actionable facts are the goal, because too much detail hides the real problems.
Component errors
A component error happens when a part does not behave as designed. A Modal might fail to open, a Dropdown might show an empty list, or a Text Input might crash when a product passes an unexpected value. These are the events a team most needs to see, because a user is usually blocked. Log the failure at the moment it happens, and record which component failed and what it was doing at that time.
Deprecation warnings
A deprecation warning is a log entry that tells a product team it is using something marked as old. The old part still works, but it will be removed later. Some design systems show these warnings in the developer console, which is the panel in a browser where builders see messages while they work. Some design systems add development-mode runtime warnings to deprecated components.
Build and release failures
A build failure happens when the automatic process that packages the system stops early. A release failure happens when a new version does not publish correctly. Both affect every consumer at once, so the log should say which step failed, which version was being built, and what the error message says. A clear record here saves hours of guessing across the whole team.
Tooling issues
Tooling is the software that helps the team work, such as a design file plug-in, a documentation site, or an automatic checker. When a tool fails, designers and builders may not know why their work stopped. A tooling log should record the tool's name, the action that failed, and the environment. This lets the team tell a broken tool from a mistake in someone's file.
What context does every entry need?
A message alone is rarely enough. Context is the set of extra facts that tells the reader where and when something happened. Good context lets someone find the same problem again, and it lets them tell whether it affects one product or many.
Component name
The exact part involved, such as Button or Modal, so the team can search for every entry about it.
Version
The release of the design system that was running.
Environment
Where it ran, such as a developer's computer, a test site, or the live product. A warning in development is not the same as a failure in production.
What happened and when
A short description of the action and a timestamp, which is the exact time the event occurred.
Tip
Add context that names the problem, not the person. A component name and version are useful. A user's name or email address is not.
How do you log well?
Good logs share three habits. They use clear levels, they write messages that read the same way every time, and they leave out private information. Following these habits turns the log from noise into a useful record.
What are the log levels: error, warn, info, and debug?
A log level tells the reader how serious an entry is. Logging systems commonly define six levels, from TRACE, the most detailed, to FATAL, the most serious. Sticking to a small set keeps the record easy to sort.
Error
A failure that needs attention. Something did not work, and a person may be blocked. Example: a Modal cannot open at all.
Warn
An unexpected event that does not stop work yet but may cause trouble later. Example: a product uses a deprecated setting.
Info
A normal, meaningful event. Example: a new version of the system was published.
Debug
Detailed notes that help a builder trace a problem. Example: the steps a component took before it failed.
Levels also depend on the environment. Many teams keep the detailed levels on in development, when builders are working. They keep only the important levels on in the live product, because too many entries slow things down and bury the real errors. Some sources warn that excessive logging can hurt performance and increase storage costs.
Tip
Do not mark everything as info. If every entry looks the same, nobody can tell a failure from a routine event. Pick the level that matches the seriousness, not the level you used last time.
Writing clear, consistent messages
A log message should be short, plain, and written the same way across the system. When two components describe the same kind of problem in different words, search and counting become hard. Use one pattern for each kind of entry.
- 1
Name the part
Start with the component or tool, such as Button or the build process.
- 2
Say what happened
Describe the event in one plain sentence, such as the setting being used is deprecated.
- 3
Say what to do
Name the next step or the replacement, such as use the newer setting instead.
- 4
Attach the context
Add the version, environment, and time so the entry can stand on its own.
Keeping private data out
Logs are often copied, shared with support staff, or sent to outside monitoring services. Any private fact written into a log can travel with it. Sources agree that passwords, access tokens, payment details, and personal identifiers should stay out of logs. If a value is needed for debugging, it can be masked, hidden, or replaced with a code that stands for it.
Tip
Before you add a value to a log, ask whether someone could use it to find a real person or get into an account. If yes, leave it out or mask it.
Worked example: a deprecated Button setting
This example is made up for teaching, but it follows the pattern many real design systems use. Imagine a Button component that once used a setting called type to choose its style. The team has added a newer setting called variant, and it plans to remove type in the next major release. Here is how the Button should log the old setting.
- 1
Mark the old setting
The team marks type as deprecated in its documentation, so builders know it is on the way out. The old setting keeps working so products are not broken on the spot.
- 2
Detect the old use
When a product team's screen uses type, the Button checks for it while the product runs in development.
- 3
Write one warn entry
The Button records a warn-level entry that names the Button component, the version number that is running, and the environment. The message says that type is deprecated and that variant should be used instead.
- 4
Warn once, not on every draw
Some design systems show the warning once per component per session, so the console does not fill up with the same line.
- 5
Keep it silent in the live product
The warning appears in development. The live product build should keep warn-level entries on, because they flag trouble that may cause problems later.
- 6
Gather the entries
Across many products, the team reviews the entries and sees which teams still use type and how often the warning appears. That list shows where help is needed before removal.
- 7
Plan the removal
Because the entries show the old setting is still in use, the team can send a migration notice and set a removal plan for the next major release. The actual versioning rules are covered in another lesson.
Tip
Notice that the log did not make any decision. It gave the team the facts. Deciding what to remove and when is a separate job, done by people who read the log.
How teams use the logs
A log that nobody reads is wasted effort. Teams review their logs on a regular schedule, sort what they find, and turn important patterns into work. The steps below show the usual path from a raw entry to a fix.
- 1
Collect
Gather entries from the places where they are stored, such as build reports, the developer console notes from testing, or the feedback that reaches the team.
- 2
Group
Put similar entries together. Ten copies of one warning are one issue, not ten.
- 3
Triage
Decide how serious each group is and which part of the system it touches. A failing build blocks everyone, so it comes first.
- 4
Act
Choose the response. A rare crash may need a quick fix. A repeated warning may need a migration notice for consumers. A new fault may need a ticket so someone owns it.
Teams often review log levels too.
From a repeated warning to a migration notice
Repeated warnings are a signal. If many product teams see the same deprecation warning, the old part is still in active use and needs a plan. A design team can respond by writing a migration notice. That notice should explain what changed, why, and how to move, often with a short before and after example.
Common mistakes to avoid
Logging everything
Too many entries hide the important ones. Log events that someone can act on.
Marking everything as error
When every entry is an error, the team stops reading them. Save error for real failures.
Leaving out the version
Without a version, nobody can tell whether a problem is old, new, or already fixed.
Writing private data
Tokens do not belong in a design system log, and names and email addresses may need anonymizing, hashing, or encrypting before they are logged.
Never reviewing the logs
A record that nobody reads cannot improve the system. Set a regular review time.
Check yourself
Try these short scenarios. Each one needs the ideas from this lesson to answer.
Quick check
Your Modal component sometimes fails to open inside a product. Users report nothing specific, and the team cannot reproduce the problem. What should the Modal log when it fails, and at what level?
Quick check
A product team's screen still uses an old setting in a Card component. It still works, but the design system plans to remove that setting in the next major release. Which log level fits the warning?
Key takeaways
Logging is the raw record of events and errors in a design system's components and tools. Log the things that help someone act: component errors, deprecation warnings, build and release failures, and tooling issues. Give every entry clear context, including the component name, version, and environment. Use a small set of levels, write messages the same way every time, and keep private data out. Then review the record, group what repeats, and turn it into a fix or a migration notice.
Tip
When you are unsure whether to log something, ask: will a person use this entry to find or fix a problem? If not, skip it or use debug.
Sources
- AWS Prescriptive Guidance: Logging best practices
- TEDI Design System issue 241: Add dev-mode runtime warnings to deprecated components
- Tricentis: Error logs, definition, types and best practices
- Odown: Logging Levels Explained, TRACE to FATAL
- Wikipedia: Java logging framework (log level descriptions)
- DeepWiki: Ant Design, Deprecation and Migration Strategies
- Magic Patterns: Design System Maintenance, How to Prevent Drift and Decay
- Murphy Trueman: Component retirement, and the decisions that keep systems alive
- Bugfender: Debug logging for web and mobile apps
- Workshelve: Log Levels, When to Use Debug, Info, Warn, and Error
- EightShapes: Versioning Design Systems
- Jakub Krajewski: Error Logging Best Practices
- Better Stack: Logging Best Practices, 12 Dos and Don'ts
- Daily.dev: Logging Best Practices for Developers
- DEV Community: Logging Best Practices, Understand in 3 Minutes
- Salesforce design-system-react issue 2348: Remove console warnings from CI
Last updated on 17 November 2026
Related lessons
Learn with me
Every lesson is free. I add new ones as I learn. Have a question, or want help with your own work? Book a short call.