How do you document design system?

over 2 years ago from , Product Designer

I am working on creating a design system for my company. I have been following many articles on medium, posts about atomic design but cannot get the good process of working, documenting, setting up a naming convention etc.. What is your ideal process of documenting a design system?


  • Jennifer Nguyen, over 2 years ago

    Someone else posted a similar question recently and a few comments came back with https://zeroheight.com/. I've been working on our Design system for over a year now and once I played around with Zero Height, I wish I had found out about this tool sooner.

    3 points
    • , over 2 years ago

      I have been working on zeroheight also and found its sketch import feature very useful.

      1 point
    • Mattan IngramMattan Ingram, over 2 years ago

      Hmmm, it's unclear if this works with Figma. I really like the look of ZeroHeight, but without Figma integration probably not worth the investment.

      0 points
      • Jennifer Nguyen, over 2 years ago

        I use Figma 80% of the time and Sketch the rest (slowly but surely transitioning over). Zero Height does not currently support a Figma integration but that's one of the known shortcomings with any application that is not Sketch. Sketch has been the industry standard for awhile so it makes sense that they have more support and integrations at the moment. I haven't heard of any tools that integrate with Figma besides Zeplin, nevertheless, a Design System Documentation tool integrating with Figma.

        With that said, it's quite simple to transfer Figma -> Sketch although cumbersome depending on how many components you're trying to transfer.

        1 point
      • Jerome de Lafargue, 2 years ago

        Hey, zeroheight founder here :) Figma integration is coming soon!

        1 point
        • Mattan IngramMattan Ingram, 2 years ago

          Awesome! I'll give it another look when that's released.

          1 point
          • Jerome de Lafargue, almost 2 years ago

            Hey Mattan, just wanted to let you know that our zeroheight <> Figma integration is now ready for early access! Would you be interested in trying out?

            If so, just email jerome@zero...com from your zeroheight account’s email address and I will enable you :)

            0 points
  • Zhaoli Jin, over 2 years ago

    have you checked this series of posts? https://medium.com/eightshapes-llc/documenting-components-9fe59b80c015

    2 points
  • Poyi ChenPoyi Chen, over 2 years ago

    Some of the tools I've considered/used at my companies are Frontify, Invision Design System Manager, and ZeroHeight.

    1 point
  • Jason FestaJason Festa, over 2 years ago

    Great thread! I am working on something in this space. DM me!

    1 point
  • Anastasia Churazova, over 2 years ago

    Have you tried Nuclino? https://www.nuclino.com/

    It's a lightweight documentation tool similar to Confluence that integrates with a number of other tools, including Figma.

    1 point
  • Andrew C, over 2 years ago

    My team used this article as a guideline to great success: https://novemberfive.co/blog/symbols-guidelines-in-sketch/

    We also have a front-end component library for developers to use / us to reference. And to bridge the two we use Zeplin (for new arrivals from Sketch to the FElib).

    1 point
  • Rick MesserRick Messer, over 2 years ago

    +1 that it's different for everyone, but what's important is that you just start it somewhere and commit to continually updating it. I've used dropbox paper for ours a HomeAway while we work behind the scenes creating our own site that combines design and dev implementation.

    The hardest part is not starting it, or completing a first draft, but maintaining it consistently over time. So do what ever it takes to make it simple to keep it going no matter what. Best of luck!

    1 point
  • Grover RamseyGrover Ramsey, over 2 years ago

    It is so standard, I am old-fashioned, I use folders, it really helps me, in each folder I know what is inside.

    1 point
  • Timo Nagel, over 2 years ago

    This is a very interesting topic. The way I see it is that a design system is split up into to levels of documentation.

    1. Documentation for really building the design system. So basically a typical designer -> developer hand-off.

    2. Documentation for using the design system to build stuff.

    For the first documentation level I would recommend to use a combination of Confluence, Jira, and a hand-off tool like Abstract (Inspect) or Zeplin. Why not only Jira? Because we for example build a design system for multiple frontend frameworks. And tickets get closed, that's why I would recommend having a general documentation in confluence and move them to Jira when the dev team of each framework need them.

    For the second level of documentation I would recommend to use something like Zeroheight.io, InVision DSM or things like that.

    In addition to that you should also maintain a Sketch Library and have it available for everyone to use and link it. We use abstract for that but you could also use Sketch Cloud or something else. Key is to make it available and easy to update.

    1 point
  • TJ Dhillon, over 2 years ago

    Hey Amrit! You can also use Sketch when you're starting out and then expand slowly to a self hosted solution!

    The most important thing I've learnt with design systems is that they take time and as they grow you'll need to dedicate more time and personnel to maintaining them. Most large companies have entire teams dedicated to maintaining their styleguides.

    You can check out my case studyor you can just check out my image exports of my primitives and generic components here.

    Any further questions, just ask and I'll be happy to clarify further!

    1 point
  • Thomas Ruehr, over 2 years ago

    In my experience, it really depends on what technology you are working with. Ask your dev how they want the documentation structured. I currently work on a design system for React native and I structured everything based on the file structure in production. Foundation components (colors, typography, etc.) Unit component (simple and heavily reusable components, toggle, images, fields, button) and Structural components (Structural blocs build from foundation and unit component that are used directly to build pages)

    Check out what the airbnb team is doing, very interesting. For documentation we use Notion (we used confluence but it was way to heavy) we also use abstract for everything (inspect, design presentation, naming conventions) I'm thinking of giving zeroheight a shot it looks great.

    For inspiration just download design systems on sketch like material design or the base UI kit from apple on sketch it can give you clues on how to name your things.

    Also just check out other design systems: https://adele.uxpin.com/

    Hope this helps :)

    TLDR: you should ask your dev and PM. They are the one that will rely on it to work :)

    1 point
  • Robbert EsserRobbert Esser, over 2 years ago


    1 point
    • , over 2 years ago

      I started working on confluence now. It is great for documenting but i am not sure if i will be able to import sketch components, inspect inside it using confluence.

      0 points
  • Jerome de Lafargue, almost 2 years ago

    Hey everyone! Our Figma integration is now live on Product Hunt :) https://www.producthunt.com/posts/zeroheight-for-figma-2

    0 points