Marcus Andrey Study
Ler em português Library

Design Systems · 9 min read

Design Systems in Practice

Tokens, components, documentation and governance: how to build a design system people actually use, from Figma to code. With labs.

Seven steps in order, then five labs and a part for people who lead design teams. One fictional system, Harbour, runs through every lesson, side by side with public systems you can open.

Start with Step 1 →

  1. Step 1 · Why a design system

    • What a design system solvesA design system solves one problem that grows with every team: the same decision made again and again, slightly differently. What that costs, what a system gives back, what it doesn't solve, and the fictional ferry company whose system, Harbour, runs through this course.
    • When you don't need one yetA design system costs a team, time and patience, and it only pays back when work repeats for years. The signals that say not yet, start small or invest, what to do at each stage, and why the smallest useful system is usually a set of tokens and five components.
    • Anatomy of a design systemTokens, components, patterns, guidelines and the people around them: the layers of a design system, what lives in each, the rule that holds them together, and how Brad Frost's ecosystem adds framework code, recipes and smart components on top. Mapped onto Harbour.
    • The interface inventoryBefore you design a system, collect what already exists: one screenshot of every unique button, field, colour and message across your products. How Brad Frost's interface inventory works, how Tidewater ran one across two products, and how the result becomes the first draft of Harbour and the argument for it.
  2. Step 2 · Foundations and tokens

    • Token tiersPrimitive tokens say what a value is, semantic tokens say what it's for, component tokens say where it goes. Why most systems use these three tiers, how aliases link them, how Material, Carbon and Spectrum name the same idea, and how many tiers a system really needs.
    • Naming tokensA token name is a tiny piece of documentation people read hundreds of times a day. How to build names from general to specific, name primitives by what they are and semantics by what they're for, pick a scale people can extend, and keep one name across Figma, JSON, CSS and native code.
    • Colour, type and spacing as tokensThe foundations of a system, turned into tokens: colour roles designed in measured pairs, a type scale in rem that survives zoom, and a spacing scale with names for inside and between. Harbour's real values and contrast ratios, and what to document next to each token.
    • Themes and modesLight and dark, comfortable and compact: a mode is a second set of answers for the same semantic tokens. How Harbour switches modes and density without touching a component, the exact CSS behind a live demo, why dark mode is measured and not inverted, and how Figma and the DTCG resolver handle the same idea.
    • Tokens from Figma to codeTokens are only useful if design and code read the same ones. Where the source of truth should live, how Figma variables, DTCG token files and a build tool like Style Dictionary fit together, what a Harbour token file looks like, and what's stable in the standard today.
  3. Step 3 · Components

    • Anatomy and API of a componentA component is a promise: these parts, these options, these rules, the same in Figma and in code. How to take a component apart into named parts, how to write its API before you draw it, and why the props table is the most useful page in the system.
    • Variants, properties and slotsThere are three ways to make one component cover many cases: variants for a fixed set of looks, properties for small switches, slots for open areas. When to use each, how they multiply, and how to name them the same in Figma and in code.
    • States and edge casesA component isn't finished when the happy version looks right. Every Harbour component has interaction states the browser sets and data states the product sets, plus the edge cases real content brings: long names, translations, missing data, errors. A live button with the exact CSS, the contrast numbers, and a list to design against.
    • Composition over configurationA component with a prop for every case gets harder to use with each request. Composition gives teams small parts that fit together instead. Why props pile up, how Harbour's Ticket card is built from parts, Brad Frost's components, recipes and snowflakes, and where configuration is still the right answer.
    • Accessible componentsAccessibility built into a component reaches every screen that uses it; a mistake in one reaches them too. Start from native HTML, follow the WAI-ARIA Authoring Practices patterns where they exist, and write down what the component guarantees and what the product still owns. With Harbour's Button, Text field and Ticket card.
  4. Step 4 · Patterns and content

    • From components to patternsComponents are the parts; patterns are how the parts solve a task. What a pattern is in a design system, how Harbour's "Book a crossing" pattern is built from eight components, what a pattern's doc page needs, and why patterns change more slowly than components.
    • Content and voice in the systemThe words in a component are part of the component. How a design system holds a voice that stays the same and a tone that changes, content rules for buttons, errors and labels, strings stored with keys, translations and length budgets, and who owns them.
    • Icons and illustration in the systemIcons are a component family with their own grid, sizes and names; illustrations are a voice in pictures. How Harbour draws icons on one grid, picks three sizes, names them by meaning, marks them up for screen readers, and keeps illustration for the moments that need it.
  5. Step 5 · Figma and code

    • Building a Figma libraryA Figma library is the design half of the system: the file other files pull components, styles and variables from. How to split it into files and pages, how Harbour's tokens become variables with modes, how components get properties that match code, and what publishing needs and which plan it takes.
    • Code Connect and the design-code bridgeA Figma component and a code component are two things that are meant to be one. How to keep them together: shared names, a written mapping from Figma properties to code props, and Figma's Code Connect, which shows the real code in Dev Mode. What it needs, which plans have it, and where it stops.
    • Storybook and living documentationDocumentation that is written once goes stale. Documentation that renders the real component can't. What Storybook is, what a story is, how stories become docs, accessibility checks and visual tests, and how it links to Figma, so designers can see what's really built.
    • Versioning and releasesA design system is something other teams depend on, so every change is a change to their product. How Semantic Versioning works and what counts as breaking for a design system, how to keep the Figma library and the code package on one number, how to write a changelog people read, and a release rhythm teams can plan around.
  6. Step 6 · Documentation and adoption

    • Component docs people useMost design system docs are written for the people who built the system, not for the person with a deadline. What a component doc page should answer, in which order, where each part lives (doc site, Figma, Storybook), how the best public systems structure theirs, and how to keep docs true.
    • Bringing teams onto the systemA design system nobody uses is a very well-organised Figma file. How teams actually move onto a system: treating it as a product with users, a pilot before a mandate, migration screen by screen, the help that makes the right thing easy, and what to do when a team says no.
    • Measuring adoptionSaying everyone uses the system isn't a measure. What to count in design and in code, what Figma's library analytics show and which plans have them, why detaches matter more than inserts, how far behind teams are on versions, and how to read the numbers together with what people tell you.
  7. Step 7 · Governance and scale

    • Contribution modelsWho can change a design system, and how. The three team models behind most systems, a contribution path with a bar people know in advance, and how to say no without losing the person who asked.
    • Deprecation and breaking changesHow to change or remove something in a design system without breaking the products that use it. What counts as a breaking change, how Semantic Versioning orders deprecation and removal, and the warnings, migration help and changelog lines that get teams across.
    • Multi-brand and multi-product systemsOne system for several brands and products, without forking it. What a brand is allowed to change and what it never touches, how a brand layer of tokens works next to modes, and how to split a shared core from what belongs to one product.
  8. Labs

    • Run an interface inventoryA guided lab: screenshot every distinct button, field, colour and spacing value in one or two products, group them by category, count the variations, and turn the count into a short proposal. About two hours, with a slide or whiteboard tool.
    • Build a token set with modesA guided lab: write a small Harbour token set in the DTCG format, with primitives, semantic tokens for light and dark, a density axis and a resolver file, then check every pair's contrast and mirror it in Figma variables. About two hours, with a text editor and Figma.
    • Design a component with variants in FigmaA guided lab: design the Harbour button as a Figma component set, starting from its API. Write the props table, build one base with auto layout and variables, add variant, boolean, instance swap and text properties, and test it the way people will break it. About two hours in Figma.
    • Write a component doc pageA guided lab: write the doc page for one component, in the order people ask their questions. Collect the real questions, fill in a template, write usage rules with reasons, and test the page with a designer and an engineer who have never used the component. About two hours.
    • Run a contribution reviewA guided lab: take one contribution through triage and review. Read a request, decide if it's useful and unique, review the built work against a published checklist, and write a decision the contributor can act on. About two hours, alone or with two colleagues playing the roles.
  9. For leads

    • Funding and staffing a design system teamFor leads: how to get a design system the people and time it needs. Why it has to be funded like a product, which roles it needs at each stage, the ways teams pay for it, and how to write the ask without inventing numbers.
    • A roadmap for the systemFor leads: how to plan a design system's work so product teams can plan around it. Roadmap items as outcomes for products, the inputs that decide the order, a balance between new work and upkeep, and how to publish it and keep it honest.
    • Showing the value of a design systemFor leads: how to show what a design system is worth with numbers you can defend. What the one public timed study found and what it didn't, how to measure speed, quality and consistency in your own team, and how to report it without inventing ROI.
  10. Reference

    • Glossary139 terms defined in this course's lessons, A to Z.
    • Frameworks15 frameworks and techniques this course's lessons use, by area.
    • Library117 books, articles, videos and courses cited in this course, grouped by the step they appear in.
Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close