Story page migration + Design System, Medium

Any company that wants to innovate quickly needs the best technology to support it. When I began leading design efforts of the migration, Medium’s story page - the heart of the platform, had been built on years of legacy code, ultimately slowing down innovation. Our goal was to position and power our platform for swift iteration, developer productivity, and a space to innovate.

Read my original Medium story on my process here

Designing for a tech-stack migration

Up until this project, my role as a product designer had been fairly straight-forward. This project presented a new challenge. I had never been through a migration before, so I was discovering and defining my role in all of this along the way. I’m not rewriting code, so what’s my role here?

I broke it down into the following objectives:

Ensure that the new story page looks and feels identical to the original
Identify where we can make improvements
Unify and consolidate where possible; be intentional about differences
Advance and integrate design system components

Designing a Design System through a migration

When this project began, we needed a design system using the updated code stack. This meant I was simultaneously designing a system while we were building it.

Typography

I began a comprehensive type style audit in advance of the migration to determine if we had an opportunity to improve our type system. After assessing my audit, I proposed a new model for organizing our type styles and collaborated with our design system committee to refine and stress-test it.

The difference is in its organization: the old system is scale-first, and the new is function-first. This makes choosing type more intuitive. In addition, we carefully considered naming type components to better serve the content. For example: ‘Title’ is primarily used for titles and ‘subtitle’ always accompanies the title. These components are reserved for content written by authors.

Here’s a visual conglomeration of that journey:

Documentation and setting up our team for success

One of my goals with the migration was to advance and integrate design system components. A large part of that is creating documentation and resources for all users of the components: both engineers and designers.

I took the initiative to set up a comprehensive Figma design library for our team and work with engineers to create corresponding documentation for engineers.

2. Components

Before the migration, we were using 15 avatar scales and multiple author byline components that, depending on the page, varied in avatar size, spacing, and type treatment. I created a system for how we apply certain author bylines, documented where they’re used, what their variants are, and applied consistent spacing / type treatments.

Additionally, I worked with an engineer to implement the system so it could be made accessible for our product org:

3. Grid system

Before the grid update, most pages on Medium didn’t follow a cohesive grid system. We know that an intentional grid system offers a foundation as we continue to improve and rewrite Medium surfaces.

Awhile back, I did an audit on all of our major pages to get a sense of what patterns exist as far as content width, grid, and global layouts. As it turns out, there are indeed some patterns, but there’s still some work to be done (always).

Goals of the new system:

Establish a framework that is optimized for our highest-traffic surface (the post- page) and can be used as we migrate other surfaces to react.

Create more space and breathing-room for UI such as pub sidebar, showcasing images, and a wider canvas for future features
Carefully consider responsiveness and serving content across all breakpoints

Key takeaways

I’m going to share some key takeaways from the 4 month process and then walk you through a few major (largely invisible) changes that emerged on the other side of this project.

Migrating a page on the internet is not simply replicating the original–and that’s a good thing.

After this project, I could maybe write a dissertation on specs. There are certainly tools for this, but they come with limitations and, more importantly, we didn’t have an existing design system in react yet.

Why not just use the current post-page as a spec? It’s already built — make it look like that.

I wish it was that easy. Actually, I’m glad it’s not. Something kind of nice happens when you create ~20 anatomical blueprints for a page on the internet: you become intimately familiar with it. It forces you to observe the thing from all angles — hold it up to the light with a magnifying glass to examine its purpose, turn it inside out with tweezers, and then inspect it with the minds of your colleagues. Rinse and repeat.

Lastly, From a design perspective, I viewed this project as not only an update to our code language, but as a clear channel for introducing new design system components. I worked closely with our platform engineers to represent these styles in Storybook — our source of truth for Medium’s design system.

2. Establishing clear design standards is essential, especially when working in Agile.

Medium uses Agile for software development. Working within this method as a designer 1. is not a straight-forward task because it was not designed for designers and 2. means constantly asking myself these questions:

Does this implementation meet our design standard?
What exactly is our design standard and how do we preserve its integrity while working within sprints?
At what point is a design requirement blocking?

I know that moving forward and rapid iteration mean making compromises and that sometimes those compromises are ‘design polish’. That’s alright, the important part is to align on a shared understanding of what our design standard is and an established plan to meet it. The best part about the migration is that by the end, we had built a foundation to iterate faster and a space for design to thrive 🌈.

3. People feel more invested when you involve them early.

As our updated design system started to take on a firmer shape, I encouraged engineers to participate in its formation — as they are also users of the system.

Engineers would join our design system syncs and offer their input for typographic nomenclature, logic, or architecture in order to make the system more user friendly for both design and engineering. This may seem trivial, but their input and involvement led to more clarity and ultimately a stronger framework. People involved in these contributions said that they felt invested in the collective system we were working towards. I believe this sentiment and shared understanding positions us well for future development.