Set up a design system

A design system gives your screens shared building blocks. In pen.dev, components define reusable elements, variables hold values such as colors and spacing, themes provide different values for those variables, and slots make room for content inside component instances.

A design library packages components and variables in a .lib.pen file so other documents can use them. Start with the system you already have, or build one in a new file.

Choose a starting point

Import a Library Into a File

Open the document where you want to design screens, then open Libraries in the left sidebar.

• Choose a library under Libraries by pen.dev to use a bundled system
• Choose an existing library under Your Libraries
• To browse for a .lib.pen file, click + beside Imported Libraries (No imported libraries in an empty list)

Importing a library lets this document use its components and variables. Keep the source library available; the design document refers to it.

Use Design Library Assets

1. Open Components in the left sidebar
2. Search for a component by name, then click or drag it onto the canvas
3. Edit the instance’s text and other properties for this screen
4. Apply the library’s variables to supported properties and choose a theme
5. Add content to the component’s slots where needed

Choose the next guide for the change you want to make:

Create a Design Library

1. Create a new .pen file and save it in your project folder
2. Define the variables and themes your components will use
3. Create reusable components and add slots for content that varies by instance
4. Open Libraries, then click Turn this file into a library
5. Confirm Turn into a library

The file uses the .lib.pen suffix. Use a separate document for screens that consume the library. The Button and Card tutorial walks through this setup with downloadable example files.

Start from Figma

Import a Figma file or paste selected layers into a working .pen document. Check the imported layout, text, and images against the source before treating it as your library.

Identify the elements you want to reuse and check them in Components. Turn ordinary elements that should be reusable into components. Review their variables in Variables, define any missing tokens, and bind those variables to the relevant fills, spacing, and typography. See Bring in existing tokens.

Once the components and tokens are ready, save the file and convert it to a library. Import that .lib.pen file into the documents where you build screens.

Update a shared component or variable

Edit the origin or variable in the source library and save it. Close and reopen a document that imports the library to load the saved changes. Instance overrides still take precedence: a custom button label stays custom while an inherited font size follows the library.

For a change that belongs only to one screen, edit the instance instead of the source. See Overrides and detaching.

Copying between documents

When you copy a component origin from a .lib.pen file into a document that has not imported it, pen.dev asks whether to import the library. Choose Yes, import to preserve the link, or No, paste verbatim copies for independent copies.

Pasting from an ordinary .pen file copies the design without a link to the source document. Referenced variables and their themes travel with the copied content. If Variable conflicts appears, choose Use existing to use the destination’s value, or Add renamed to keep the incoming value as a separate variable, then click Paste.

Copying a layer does not install its custom fonts in the destination document. Import missing fonts through Custom Fonts. Keep referenced image files available too. Check text wrapping and image fills after moving a design.