Every app that handles user accounts needs a way to confirm who’s who. That’s what authentication is for, making sure the person using an app is the person they claim to be. But doing this securely is harder than it sounds.

Traditional methods often rely on server sessions and cookies. Those work, but they don’t always scale well, especially when you’re building APIs or mobile apps that talk to multiple services. This is why JWTs, or JSON Web Tokens, are useful. They’re small, self-contained tokens that can carry user data safely between a client and a server.

JWTs make it easy to verify users without constantly checking a database – but they also expire fast to reduce risk. To keep users logged in without forcing them to sign in again every few minutes, we use something called a refresh token. It’s a separate, long-lived token that can request new access tokens when the old ones expire.

In this guide, we’ll walk through how to build a secure authentication system using JWTs and refresh tokens. You’ll learn how to generate tokens, validate them, handle expiry, and keep everything safe from common security threats.

1. Understanding JWTs (JSON Web Tokens)

2. Setting Up the Project

3. How to Implement JWT Authentication

4. How to Verify JWTs and Protect Routes

5. Refresh Tokens and Rotation

6. Conclusion

Understanding JWTs (JSON Web Tokens)

A JWT, short for JSON Web Token, is a compact way to share information between a client and a server. It’s often used to prove that a user is who they say they are. The token is created on the server after a user logs in and is then sent back to the client. The client then includes this token with each request, so the server knows who is making the call.

A JWT has three parts: a header, a payload, and a signature.

• The header usually tells the system which algorithm was used to sign the token.

• The payload contains the data, such as the user’s ID or role.

• The signature is the part that keeps everything secure. It’s created by hashing the header and payload with a secret key.

Once created, a JWT looks like a long string of random characters separated by dots. When the client sends it back to the server, the server verifies the signature using the same secret key. If it matches, the request is trusted.

One of the main benefits of JWTs is that they are stateless. The server doesn’t need to store session data. Everything needed to verify the user is already inside the token. This makes them fast and easy to use in modern APIs and microservices.

JWTs do have a downside: they cannot be revoked easily once issued. If a token is stolen, the attacker can use it until it expires. This is why short token lifetimes matter. It’s also why refresh tokens exist.

In the next section, we’ll finish the basic JWT setup. After that, we’ll add refresh tokens in “Refresh Tokens and Rotation.” That part shows how to handle expiry without making users log in again.

Setting Up the Project

Before writing any code, let’s set up a simple backend where we can build and test our authentication system. For this guide, we’ll use Node.js with Express, since it’s lightweight and easy to follow. You can use any stack later once you understand the flow.

Prerequisites

Make sure you have:

• Node.js and npm installed

• A text editor (VS Code works great)

• Basic knowledge of JavaScript and APIs

1. Initialize the Project

Create a new folder and open it in your terminal.

mkdir jwt-auth-demo cd jwt-auth-demo npm init -y 

This creates a package.json file that will track your dependencies.

2. Install Dependencies

You’ll need a few packages to get started:

• express: the web framework

• jsonwebtoken: to create and verify tokens

• bcryptjs: to hash passwords

• dotenv: to manage environment variables

Install them all at once like this:

npm install express jsonwebtoken bcryptjs dotenv 

If you want auto-reloading while developing, install nodemon as a dev dependency:

npm install --save-dev nodemon 

3. Project Structure

Here’s a clean structure to keep things organized:

jwt-auth-demo/ │ ├── server.js ├── .env ├── package.json │ ├── config/ │ └── db.js │ ├── middleware/ │ └── auth.js │ ├── routes/ │ └── auth.js │ └── models/ └── user.js 

4. Basic Express Setup

In server.js, start with a minimal Express server.

require('dotenv').config(); const express = require('express'); const app = express(); app.use(express.json()); app.get('/', (req, res) => { res.send('JWT Auth API running'); }); const PORT = process.env.PORT || 5000; app.listen(PORT, () => console.log(`Server running on port ${PORT}`)); 

You can now run it using:

node server.js 

or, if you’re using nodemon:

npx nodemon server.js 

If everything is set up correctly, visiting http://localhost:5000 should display “JWT Auth API running”:

How to Implement JWT Authentication

Now that your server is up, let’s add real authentication. We’ll start with user registration, password hashing, and login. Each user will get a token after logging in, which they can use to access protected routes.

1. Set Up the User Model

We’ll store users in a simple database. For this demo, let’s use MongoDB with Mongoose, since it’s quick to set up and easy to scale later.

Install the required packages:

npm install mongoose 

Then create models/user.js:

const mongoose = require('mongoose'); const userSchema = new mongoose.Schema({ username: { type: String, required: true, unique: true }, email: { type: String, required: true, unique: true }, password: { type: String, required: true } }); module.exports = mongoose.model('User', userSchema); 

We store users with a unique email and a hashed password. The database never sees the raw password. Hashing makes stolen data harder to use.

2. Connect to MongoDB

Inside config/db.js:

const mongoose = require('mongoose'); const connectDB = async () => { try { await mongoose.connect(process.env.MONGO_URI); console.log('MongoDB connected'); } catch (err) { console.error(err.message); process.exit(1); } }; module.exports = connectDB; 

mongoose.connect reads the connection string from .env. If the connection fails, we exit the process so we don’t continue in a broken state.

Update your server.js to include the connection:

const connectDB = require('./config/db'); connectDB(); 

And don’t forget to add your MongoDB URI in the .env file:

MONGO_URI=mongodb+srv://yourusername:[email protected]/auth JWT_SECRET=your_jwt_secret_key 

3. Create Registration and Login Routes

In routes/auth.js:

const express = require('express'); const bcrypt = require('bcryptjs'); const jwt = require('jsonwebtoken'); const User = require('../models/user'); const router = express.Router(); // Register a new user router.post('/register', async (req, res) => { try { const { username, email, password } = req.body; const existingUser = await User.findOne({ email }); if (existingUser) return res.status(400).json({ message: 'User already exists' }); const hashedPassword = await bcrypt.hash(password, 10); const newUser = new User({ username, email, password: hashedPassword }); await newUser.save(); res.status(201).json({ message: 'User created successfully' }); } catch (err) { res.status(500).json({ message: 'Server error' }); } }); // Login and issue JWT router.post('/login', async (req, res) => { try { const { email, password } = req.body; const user = await User.findOne({ email }); if (!user) return res.status(400).json({ message: 'Invalid credentials' }); const isMatch = await bcrypt.compare(password, user.password); if (!isMatch) return res.status(400).json({ message: 'Invalid credentials' }); const payload = { id: user._id, email: user.email }; const token = jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: '15m' }); res.json({ token }); } catch (err) { res.status(500).json({ message: 'Server error' }); } }); module.exports = router; 

Add it to your server in server.js:

const authRoutes = require('./routes/auth'); app.use('/api/auth', authRoutes); 

4. Test It Out

You can now test these routes using Postman or Insomnia.

Send a POST request to /api/auth/register with a JSON body:

{ "username": "demoUser", "email": "[email protected]", "password": "mypassword" } 

The register route checks for an existing user by email. It hashes the password with a cost factor of 10 and then returns a 201 on success. We don’t log the password or include it in the response.

Then log in at /api/auth/login to receive a JWT.

The login route finds the user by email and compares the password with bcrypt.compare. If it matches, we sign a token with a small payload: the user ID and email. The JWT_SECRET signs the token so the server can verify it later. The expiresIn: ’15m’ setting keeps the token short-lived to limit risk. The response only includes the token. User data can be fetched from a protected route.

Once you get the token, copy it, you’ll use it to access protected routes later.

How to Verify JWTs and Protect Routes

Now that login returns a token, we should verify it on each request that needs auth. We will write a small middleware that checks the Authorization header, validates the token, and adds the user info to the request.

1. Create the Auth Middleware

Create middleware/auth.js:

const jwt = require('jsonwebtoken'); function auth(req, res, next) { const authHeader = req.headers.authorization || ''; const [scheme, token] = authHeader.split(' '); if (scheme !== 'Bearer' || !token) { return res.status(401).json({ message: 'Missing or invalid Authorization header' }); } try { const decoded = jwt.verify(token, process.env.JWT_SECRET); req.user = { id: decoded.id, email: decoded.email }; next(); } catch (err) { if (err.name === 'TokenExpiredError') { return res.status(401).json({ message: 'Access token expired' }); } return res.status(401).json({ message: 'Invalid token' }); } } module.exports = auth; 

What it does:

• Reads the Authorization header.

• Checks for the Bearer <token> format.

• Verifies the token with the secret.

• Attaches a simple user object to req for later use.

2. Create the Protected Route

Create a small profile route that returns the current user. Add routes/profile.js:

const express = require('express'); const auth = require('../middleware/auth'); const User = require('../models/user'); const router = express.Router(); router.get('/me', auth, async (req, res) => { try { const user = await User.findById(req.user.id).select('-password'); if (!user) { return res.status(404).json({ message: 'User not found' }); } res.json({ user }); } catch (err) { res.status(500).json({ message: 'Server error' }); } }); module.exports = router; 

Wire it in server.js:

const profileRoutes = require('./routes/profile'); app.use('/api/profile', profileRoutes); 

Now a GET /api/profile/me call will only work with a valid token.

3. Handle Token Expiry Clearly

Short access tokens reduce damage if they leak. We set expiresIn: '15m' during login. When a token expires, the middleware returns a 401 with Access token expired.

We won’t refresh the token here because refresh requires its own endpoint, storage, and rotation rules. You’ll add that in “Refresh Tokens and Rotation.” For now, the 401 proves that the expiry is enforced.

4. Testing the Flow

In this section, we’ll test that the server blocks requests without a valid token and allows requests with a valid token.

Log in at /api/auth/login and copy the token. Then call /api/profile/me with:

Authorization: Bearer <paste_token_here> 

You should see the current user without the password field.

Then remove the header or change the token and call again. You should get a 401.

Next, wait for the token to expire or change expiresIn to a very short value for a quick test. Call again and confirm you get Access token expired.

Tips for debugging

• 401 with “Missing or invalid Authorization header” means the header format is wrong. Use Authorization: Bearer <token>.

• 401 with “Invalid token” means the token string is wrong, signed with the wrong secret, or corrupted.

• 401 with “Access token expired” means the expiry check works. You will fix the client experience with the refresh endpoint later.

• If all calls fail, confirm your JWT_SECRET is set in .env and that the server was restarted after changes.

5. Optional Cookie Support

You can store tokens in HTTP-only cookies. The browser sends them automatically. Scripts cannot read HTTP-only cookies, which reduces the risk from XSS.

Install and enable cookies:

npm install cookie-parser 

// server.js const cookieParser = require('cookie-parser'); app.use(cookieParser()); 

Read the access token from a cookie as a fallback:

// middleware/auth.js const jwt = require('jsonwebtoken'); function auth(req, res, next) { const header = req.headers.authorization || ''; const [scheme, tokenFromHeader] = header.split(' '); const tokenFromCookie = req.cookies?.access_token; const token = scheme === 'Bearer' && tokenFromHeader ? tokenFromHeader : tokenFromCookie; if (!token) return res.status(401).json({ message: 'No token provided' }); try { const decoded = jwt.verify(token, process.env.JWT_SECRET); req.user = { id: decoded.id, email: decoded.email }; next(); } catch (err) { const msg = err.name === 'TokenExpiredError' ? 'Access token expired' : 'Invalid token'; return res.status(401).json({ message: msg }); } } module.exports = auth; 

How this works:

• The access token can live in a cookie named access_token.

• Mark the cookie as httpOnly and secure in production.

• Set sameSite: 'strict' to reduce CSRF risk.

• For APIs used by browsers, cookies simplify sending tokens. For SPAs that call many domains, an Authorization header may be simpler.

In the next section, we’ll use the same cookie approach for the refresh token. That section explains why refresh belongs in a cookie and how rotation blocks replay.

Refresh Tokens and Rotation

Access tokens are short-lived and used on every request. They prove the user identity quickly. Refresh tokens live longer and are used only to get new access tokens when the old ones expire. This split keeps day-to-day requests fast and limits the damage if a token leaks.

We will store the refresh token in an HTTP-only cookie. This reduces exposure to scripts and keeps the flow smooth.

1. Install and Setup

We already have cookie-parser. We won’t add anything new for now, but we will use Node’s built-in crypto module to hash the refresh token before storing it. As a reminder, hashing means the raw token is never saved. If the database leaks, attackers cannot use the hashes to log in.

Create models/refreshToken.js:

const mongoose = require('mongoose'); const refreshTokenSchema = new mongoose.Schema({ user: { type: mongoose.Schema.Types.ObjectId, ref: 'User', index: true }, tokenHash: { type: String, required: true, unique: true }, jti: { type: String, required: true, index: true }, expiresAt: { type: Date, required: true, index: true }, revokedAt: { type: Date, default: null }, replacedBy: { type: String, default: null }, // new jti when rotated createdAt: { type: Date, default: Date.now }, ip: String, userAgent: String }); module.exports = mongoose.model('RefreshToken', refreshTokenSchema); 

2. Token Helpers

Create utils/tokens.js for clean, reusable logic.

const jwt = require('jsonwebtoken'); const crypto = require('crypto'); const RefreshToken = require('../models/refreshToken'); const ACCESS_TTL = '15m'; const REFRESH_TTL_SEC = 60 * 60 * 24 * 7; // 7 days function hashToken(token) { return crypto.createHash('sha256').update(token).digest('hex'); } function createJti() { return crypto.randomBytes(16).toString('hex'); } function signAccessToken(user) { const payload = { id: user._id.toString(), email: user.email }; return jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: ACCESS_TTL }); } function signRefreshToken(user, jti) { const payload = { id: user._id.toString(), jti }; const token = jwt.sign(payload, process.env.REFRESH_TOKEN_SECRET, { expiresIn: REFRESH_TTL_SEC }); return token; } async function persistRefreshToken({ user, refreshToken, jti, ip, userAgent }) { const tokenHash = hashToken(refreshToken); const expiresAt = new Date(Date.now() + REFRESH_TTL_SEC * 1000); await RefreshToken.create({ user: user._id, tokenHash, jti, expiresAt, ip, userAgent }); } function setRefreshCookie(res, refreshToken) { const isProd = process.env.NODE_ENV === 'production'; res.cookie('refresh_token', refreshToken, { httpOnly: true, secure: isProd, sameSite: 'strict', path: '/api/auth/refresh', maxAge: REFRESH_TTL_SEC * 1000 }); } async function rotateRefreshToken(oldDoc, user, req, res) { // revoke old oldDoc.revokedAt = new Date(); const newJti = createJti(); oldDoc.replacedBy = newJti; await oldDoc.save(); // issue new const newAccess = signAccessToken(user); const newRefresh = signRefreshToken(user, newJti); await persistRefreshToken({ user, refreshToken: newRefresh, jti: newJti, ip: req.ip, userAgent: req.headers['user-agent'] || '' }); setRefreshCookie(res, newRefresh); return { accessToken: newAccess }; } module.exports = { hashToken, createJti, signAccessToken, signRefreshToken, persistRefreshToken, setRefreshCookie, rotateRefreshToken }; 

In this code,

• signAccessToken creates a short token with the user ID and email.

• signRefreshToken creates a long-lived token with a jti value. The jti lets us rotate and track tokens.

• persistRefreshToken hashes the refresh token and stores metadata like expiry and device info.

• setRefreshCookie writes the HTTP-only cookie so the browser sends it to the refresh endpoint automatically.

• rotateRefreshToken revokes the old token, issues a new pair, and saves the new record. Rotation blocks replay if an old refresh token is stolen.

3. Issue Refresh Token on Login

Update your routes/auth.js login handler to create and store a refresh token, then set the cookie.

const express = require('express'); const bcrypt = require('bcryptjs'); const jwt = require('jsonwebtoken'); const User = require('../models/user'); const RefreshToken = require('../models/refreshToken'); const { createJti, signAccessToken, signRefreshToken, persistRefreshToken, setRefreshCookie } = require('../utils/tokens'); const router = express.Router(); router.post('/login', async (req, res) => { try { const { email, password } = req.body; const user = await User.findOne({ email }); if (!user) return res.status(400).json({ message: 'Invalid credentials' }); const isMatch = await bcrypt.compare(password, user.password); if (!isMatch) return res.status(400).json({ message: 'Invalid credentials' }); const accessToken = signAccessToken(user); const jti = createJti(); const refreshToken = signRefreshToken(user, jti); await persistRefreshToken({ user, refreshToken, jti, ip: req.ip, userAgent: req.headers['user-agent'] || '' }); setRefreshCookie(res, refreshToken); res.json({ accessToken }); } catch (err) { res.status(500).json({ message: 'Server error' }); } }); module.exports = router; 

On login, we issue both tokens. The access token goes to the JSON response. The refresh token goes to an HTTP-only cookie scoped to /api/auth/refresh. This keeps the refresh token away from frontend code while still letting the browser send it to the refresh endpoint.

4. The Refresh Endpoint

Create an endpoint that reads the refresh cookie, verifies it, checks the database entry, and rotates it. If all checks pass, it returns a new access token and sets a new refresh cookie.

Add to routes/auth.js:

const { hashToken, rotateRefreshToken } = require('../utils/tokens'); router.post('/refresh', async (req, res) => { try { const token = req.cookies?.refresh_token; if (!token) return res.status(401).json({ message: 'No refresh token' }); let decoded; try { decoded = jwt.verify(token, process.env.REFRESH_TOKEN_SECRET); } catch (err) { return res.status(401).json({ message: 'Invalid or expired refresh token' }); } const tokenHash = hashToken(token); const doc = await RefreshToken.findOne({ tokenHash, jti: decoded.jti }).populate('user'); if (!doc) { return res.status(401).json({ message: 'Refresh token not recognized' }); } if (doc.revokedAt) { return res.status(401).json({ message: 'Refresh token revoked' }); } if (doc.expiresAt < new Date()) { return res.status(401).json({ message: 'Refresh token expired' }); } const result = await rotateRefreshToken(doc, doc.user, req, res); return res.json({ accessToken: result.accessToken }); } catch (err) { res.status(500).json({ message: 'Server error' }); } }); 

The refresh endpoint verifies the cookie, checks the database record, confirms it is not expired or revoked, then rotates it. Rotation sets revokedAt on the old record and creates a new one with a fresh jti. The response returns a new access token and sets a new refresh cookie.

5. Logout and Revoke

On logout, revoke the current refresh token and clear the cookie.

router.post('/logout', async (req, res) => { try { const token = req.cookies?.refresh_token; if (token) { const tokenHash = hashToken(token); const doc = await RefreshToken.findOne({ tokenHash }); if (doc && !doc.revokedAt) { doc.revokedAt = new Date(); await doc.save(); } } res.clearCookie('refresh_token', { path: '/api/auth/refresh' }); res.json({ message: 'Logged out' }); } catch (err) { res.status(500).json({ message: 'Server error' }); } }); 

Logout revokes the matching refresh token if present and clears the cookie. This ends the session cleanly on the server side and the client side.

6. Client Flow

Here is how the browser app should behave:

• Keep the access token in memory. Do not put it in localStorage.

• Call protected APIs with the Authorization header or let cookies handle it if you chose the cookie approach for access.

• If a call fails with Access token expired, call /api/auth/refresh. The browser sends the refresh cookie automatically.

• Replace the in-memory access token with the new one.

• Retry the original request.

• On logout, call /api/auth/logout and clear any local state.

7. Security Notes

There are some key steps you can take to make sure everything is secure:

Separate secrets

Use a different secret for access and refresh tokens. If the access secret leaks, refresh tokens still use a different key. Set JWT_SECRET and REFRESH_TOKEN_SECRET in .env.

HTTPS only

Serve production traffic over HTTPS. Cookies marked secure: true only travel over HTTPS. This protects tokens in transit.

Rotate on every refresh

Issue a new refresh token and revoke the old one each time you refresh. Rotation makes a stolen old token useless after the next refresh.

Hash refresh tokens in the database

Store a SHA-256 hash, not the raw token. This way a database leak does not give attackers the actual token string.

Scope and flags for cookies

Use httpOnly: true, secure: true in production, sameSite: 'strict', and a narrow path such as /api/auth/refresh. These flags reduce XSS and CSRF risk and limit where the cookie is sent.

Short access TTL and moderate refresh TTL

Keep access tokens short, such as 15 minutes. Use a refresh lifetime like 7 days. This keeps risk low without annoying users.

Device awareness

Store ip and userAgent. If patterns change in a suspicious way, you can revoke or challenge the session.

Auditing and limits

Log refresh events and consider rate limits on the refresh endpoint. This helps detect abuse.’

Add to .env:

REFRESH_TOKEN_SECRET=your_refresh_secret_key 

Conclusion

You now have a working authentication system that uses JWTs and refresh tokens to keep users logged in safely. The access token handles quick verification. The refresh token quietly renews access when it expires. Together, they strike a balance between security and convenience.

You built user registration, login, protected routes, and a full refresh flow. You also learned how to rotate refresh tokens, store them securely, and handle logout cleanly. Each step adds another layer of safety that keeps your app and users protected.

From here, you can expand this setup to match your real project. You can add role-based permissions, track user sessions by device, or move the logic into a dedicated authentication service. What matters most is understanding the flow and keeping tokens short-lived and well-guarded.

Source: freeCodeCamp Programming Tutorials: Python, JavaScript, Git & More.

Flexbox is a powerful CSS feature that lets you build user interfaces that fit any screen size. freeCodeCamp just published a Flexbox for beginners course where you’ll learn the concepts and code syntax by building your own website navigation bar.

If you’ve ever struggled to center something with CSS or tried to make columns line up nicely, Flexbox simplifies this dramatically. With just a few properties, you can build modern layouts that “flex” to different screen sizes, without needing to write a bunch of custom media queries.

Developer and teacher Indra (CodeWithIndra) will walk you through every Flexbox property step by step. You’ll learn how to align items along the main and cross axis, reorder elements without changing the HTML, control how items grow and shrink, and finally understand what flex-grow, flex-shrink, and flex-basis are really doing. He also shows real examples from sites like GitHub and DataDog, then demonstrates how to recreate pieces of their layout.

The course ends with two small projects: centering an element vertically and horizontally (the thing everyone Googles at some point) and building a clean navigation bar using only Flexbox.

If you want to improve your front end development skills, this course is a good way to invest a couple hours of your weekend. [2 hour YouTube course]:

Source: freeCodeCamp Programming Tutorials: Python, JavaScript, Git & More.

This article is a sponsored by Maturing Design Systems

Design systems have become an integral part of our everyday work, so much that the successful growth and maturation of a design system can make or break a product or project. Great tokens, components and organization aren’t enough — it is most often the culture and curation that creates a sustainable, widely-adopted system. It can be hard to determine where to invest our time and attention. How do we build and maintain design systems that support our teams, enhance our work, and grow along with us?

Excerpt: Design System Culture

Culture is a funny thing. We all have some intuition about how important it is—at least we know we want to work in a great culture and avoid the toxic ones. But culture is notoriously difficult to define, and changing it can feel more like magic than reality. One company culture can be inspiring for some and boring for others, a place of growth for some and stifling for others.

Adding to the nuance, not only does your company have a culture as a whole, but it has many subcultures. That’s because culture is not created by any individual. Culture is something that happens when the same group of people gather together repeatedly over time. So, as a company grows, adding hierarchy and structure, the teams formed around specific goals, products, features, disciplines, and so on, all develop their own subcultures.

You probably have a design subculture. You probably have a product ownership subculture. You probably even have a subculture forming around those folks who get on a Zoom call every Tuesday at lunch to knit and chat. There are hundreds or more subcultures at most good-sized organizations. It’s complicated, nuanced, and immensely important.

When an individual is struggling with the way they are managed, one culture enables them to offer authentic feedback to their boss, while another leads them to look for a new job. When a company provides free lunch on Fridays, one culture creates a sense of gratitude for this benefit; another makes you feel like this free lunch comes with the expectation that you can’t ever leave work. One culture prioritizes financial results over respectful interactions. One culture encourages competition between teams, while another emphasizes collaboration with coworkers.

Why Culture?

At the beginning of 2021, my company was asked to help a large organization plan, design, and build a design system alongside the minimum viable product of a new product idea. This is the kind of work we truly love, so the team was excited to jump in.

As an author of a book about design systems, I want nothing more than to tell you how amazingly this engagement went. Instead, it was a tremendous struggle. Despite this being the perfect kind of work for my team and I on paper, we had to make the hard decision to walk away from our client at the end of that year. Not because we couldn’t do the work. Not because of any technical challenges or budget concerns. The reason we gave was “cultural incompatibility.” In almost twenty years of running my own businesses, this had never happened to me. After all, our clients don’t come to us because they have everything figured out — they come because they know they need help. If we couldn’t guide them through a difficult season, why did we even exist!?

Needless to say, it didn’t sit well with me. So, after following a few useless threads of fear that we just couldn’t cut it, I spent the next year diving down a rabbit hole of research on organizational culture. This next section is a summary of what I learned in that year and how I’ve been putting that to use since. To start, let’s find a common understanding of what culture is.

What Is Culture?

Over the last few decades, a lot has been said about workplace culture. From understanding why it matters and how it impacts the ways we lead, to offering methodologies for changing it. I’ve found tremendous value in the research and writings of Edgar Schein, a business theorist and psychologist. Schein offers a simple model to explain what culture is, breaking it down into three levels:

Artifacts

Artifacts are the top level of Schein’s model. These are the things people think of when you say “culture” — the visible perks a company offers. I once worked at a place where we could expense bringing in donuts for the team. Another job I had provided a foosball table. One company encouraged us to cook lunch together each week. These kinds of things, along with the company swag, the channel in Slack where you get to brag about your peers, and the company retreat are all “artifacts” of your company culture.

Espoused Values And Beliefs

The next layer down is called “espoused values and beliefs.” This is what people inside the culture say they believe. It’s the list of values, the mission statement, the vision. It’s the content on the website and plastered on the walls. It’s the stuff you expect to get when you accept the job because it’s how people answered all your questions throughout the interview process.

Basic Underlying Assumptions

The deepest layer is called “basic underlying assumptions.” This is what people inside the organization actually believe. It’s the way the leadership and employees behave, most notably

in the face of a difficult decision. This layer is the root of your culture. And no matter what you show (artifacts), no matter what you say (espoused beliefs), the things you believe (underlying assumptions) will come out eventually.

It Starts At The Bottom

As an employee, you will experience these things from the top down. On your first day, you observe what’s happening around you — you see the artifacts of the culture. Eventually, you get to know a few folks. As you have more and more conversations with them, you’ll begin to hear how they talk about the culture — their espoused beliefs. At some point, people inside your culture will be faced with some tough situations. This is where the rubber meets the road and when you’ll learn what those individuals’ basic underlying assumptions are.

Unhealthy organizations don’t have a process for surfacing and valuing those underlying assumptions. Healthy organizations know that culture starts with the basic underlying assumptions of every individual at the company.

Unhealthy organizations try to create culture with perks and mission statements. Healthy organizations allow the top two layers to emerge naturally from the bottom layer.

When the basic underlying assumptions don’t line up with the espoused beliefs and artifacts, the disconnect is strong. It’s often hard to articulate the problem, but people will feel it. This is the company with a core value of “family first” that requires you to travel all the time with no recognition of the impact it has on your actual family. The espoused belief to prioritize family is not actively supported in the decisions being made.

Strength And Weakness

We all subconsciously know these things, and that is reflected in the language we use as we talk about the culture of an organization. We tend to use the words “strong” and “weak” to describe culture. You might say, “That company has a strong culture.” This statement is an indication that the layers are aligned, and that means the culture itself serves as a way of guiding decisions. If we all have shared values, we can trust one another’s ability to make decisions that will align with those values.

Conversely, an organization with a weak culture is missing the alignment between the things they say and the decisions they make. These cultures often continually add policies and procedures in order to police the behavior of individuals. In this scenario, the culture is weak because it doesn’t offer the organic guidance a stronger culture does — the misalignment means the things we choose to do differ from the things we say.

That is not to say policies and procedures are bad. As companies grow, there is a need to document the expectations for people. The proactive nature of a strong culture means these documents are often a formalization of what has emerged organically, whereas a weak culture reacts to negative situations in hopes to prevent the bad from happening again.

Editor’s Note

Do you like what you’ve read so far? This is just an excerpt of Ben’s upcoming book, Maturing Design Systems, in which he explores the anatomy of a design system, explains how culture shapes outcomes, and shares practical guidance for the challenges at each stage — from building v1 and growing healthy adoption to navigating “the teenage years” and ultimately running a stable, influential system.

Table of Contents

• Context
  An introduction to the context of design systems, understanding where they live in your organization, what feeds them, and whether you should build one.
• Design System Culture
  A deep dive into what culture is, why it’s important for design system teams to understand, and how it unlocks the ability for you to deliver real value.
• The Anatomy of a Design System
  An exploration of the layers and parts that make up a design system based on the evaluation of hundreds of design systems over many years.
• Maturity
  An over view of the design system maturity model including the fours stages of maturity, origin stories, a framework for maturing in a healthy way, and a framework for creating design system stability.
• Stage 1, Building Version One
  A dive into what it means to be in stage 1 of the design system maturity and a few mental models to keep you focused on the right things in this early stage.
• Stage 2, Growing Adoption
  Unpacking stage 2 of the design system maturity model and a deep dive into adoption: broadening your perspective on adoption, the adoption curve, and how to create sustainable adoption.
• Stage 3, Surviving the Teenage Years
  Understanding the relevant concerns for stage 3 of the design system maturity model and how to address the more nuanced challenges that come with this level of maturity.
• Stage 4, Evolving a Healthy Program
  Exploring what it means to be in stage 4 of the design system maturity model, when you’ve become an influential leader in the eyes of the rest of your organization.

About The Author

Ben Callahan is an author, design system researcher, coach, and speaker. He founded Redwoods, a design system community, and The Question, a weekly forum for collaborative learning. As a founding partner at Sparkbox, he helps organizations embed human-centered culture into their design systems. His work bridges people and systems, emphasizing sustainable growth, team alignment, and meaningful impact in technology. He believes every interaction is an opportunity to learn.

Reviewers’ Testimonials

“This book is a clear and insightful blueprint for maturing design systems at scale. For well-supported teams, it offers strategy and clarity grounded in real examples. For smaller teams like mine, it serves as a North Star that helps you advocate for the work and find solutions that fit your team’s maturity. I highly recommend it to anyone building a design system.”

— Lenora Porter, Product Designer

“Ben draws connections between process, collaboration, and identity in ways that feel both intuitive and revelatory. Many design system books live comfortably in the tactical and technical, but this one moves beyond the how and into the why — inviting readers to reflect on their roles not just as product owners, designers or engineers, but as stewards of shared understanding within complex organisations. This book doesn’t prescribe rigid solutions. Instead, it encourages self-inquiry and alignment, asking readers to consider how they can bring intentionality, empathy, and resilience into the systems they touch.”

— Tarunya Varma, Product Design Manager, Tide

“Ben Callahan’s Maturing Design Systems puts language to the struggles many of us feel but can’t quite explain. It unpacks the hidden influence of culture, setup, and leadership, providing you with the clarity, tools, and frameworks to course-correct and move your system work forward, whether you’re navigating a growing startup or a scaling enterprise.”

— Ness Grixti, Design Lead, Wise, and Author of “A Practical Guide to Design System Components”

Don’t Miss Out!

Through years of interviews, coaching, and consulting, Ben has discovered a model for how design systems mature. Understanding how systems tend to mature allows you to create a sustainable program around your design system — one that acknowledges the human and change-management side of this work, not just the technical and creative.

This book will be a valuable resource for anyone working with design systems!

Spread The Word

Sign up to our Smashing newsletter and be one of the first to know when Maturing Design Systems is available for preorder. We can’t wait to share this book with you!

Source: Articles on Smashing Magazine — For Web Designers And Developers.