Library Setup

Overview

Setting up the Chassis Figma library in your workspace involves obtaining the library files, publishing them to your Figma organization, and configuring library settings for your team. This guide walks you through the complete setup process from initial file acquisition to enabling the library for your design team.

Prerequisites

Before setting up Chassis Figma, ensure you have:

• Figma Account: Professional or Organization plan (required for libraries)
• Edit Access: Permission to publish libraries in your organization
• Familiarity with Figma: Basic understanding of Figma components and styles

Getting Figma Files

There are multiple ways to obtain Chassis Figma library files depending on your needs and preferences.

Figma Community

The easiest way to get started is through Figma Community.

1. Visit Chassis Figma Community page
2. Click "Duplicate" on the library file
3. Files will be added to your Drafts
4. Move files to appropriate team/project folder

Figma Files

• cx.tokens.*: Contain all design tokens and variable collections
• cx.asset.*: Components that serve as content layers for UI components (e.g., text, icons, backgrounds)
• cx.comp.*: Individual files for each component category (e.g., Buttons, Forms, Cards)
• cx.guide.*: Guidelines and best practices for using the library
• cx.template.*: Pre-built templates for common design patterns
• cx.file.*: Example files demonstrating component usage and design patterns

Library Dependencies

Chassis Figma files have interdependencies that require a specific publishing workflow:

• Token Dependencies: All component files reference cx.tokens.* for variables and styles
• Asset Dependencies: All component files use cx.asset.* components for text, icons, backgrounds, and other content layers
• Component Dependencies: Some components reference other components (e.g., Buttons contain Badge components, Notifications contain Buttons)

These interdependencies mean you cannot publish files in a single step—you need an iterative publishing process.

Setting Up Libraries

Due to library interdependencies, publishing Chassis Figma requires three publishing iterations to properly resolve all library references.

• Step 1: Initial Publish creates the libraries in your organization, but they reference each other circularly (components need tokens/assets, which need to exist as libraries first).
• Step 2: Replace Missing Libraries establishes the connections between missing libraries now that they all exist.
• Step 3: Final Update & Publish ensures all libraries are using the latest published versions of their dependencies, preventing version mismatches.

Initial Publish

Publish all files as is to make them available as libraries, even though they'll have missing library references.

1. Open each library file one by one (tokens, assets, all component files)
2. Click the library icon in the toolbar (book icon)
3. Click "Publish..." button in the library modal
4. Add description: "Initial publish" or similar (optional)
5. Click "Publish" to make available to team

Files will publish successfully but will contain "missing library" warnings since they reference libraries that didn't exist yet.

Replace Missing Libraries

Replace missing library references with the published libraries from Step 1.

1. Open each library file again (in order described at Best Practices below).
2. Click Library icon to open the Libraries modal (book icon in panel header).
3. Scroll down and click View missing libraries at the bottom of the modal.
4. Select a missing library to view the affected styles and components.
5. Use the Choose library dropdown to find and select a replacement library.
6. Use the checkboxes on the left to choose which assets to swap.
7. Uncheck the "Swap default styles in instances" setting if prompted.
8. Click Swap library to replace affected instances with instances from your selected library.
9. Verify all references are connected (no missing library)
10. Publish again with description: "Updated library references"

Files will now be connected to the correct libraries, but they may still reference older versions of those libraries.

Final Update & Publish

Ensure all files have the latest versions of dependencies and are ready for team use.

1. Open each library file one final time
2. Click Library icon to open the Libraries modal (book icon in panel header).
3. Select the Updates tab. By default, the Updates tab displays assets on the current page.
4. Use the Show updates for all pages toggle to see all available updates.
5. Click Update all to apply all updates.
6. Publish again with description: "Ready for use"

All library files are now properly cross-referenced and ready for team consumption.

Best Practices

Following these best practices will help ensure a smooth setup and ongoing maintenance of your Chassis Figma library:

Initial Publish Order

When setting up Chassis libraries, the order in which you publish files matters significantly. Follow this sequence to ensure all dependencies are properly established:

1. Tokens: Publish all token files first to establish the design foundation
2. Assets: Publish asset files next since components depend on them
   • text, icon and background first
3. Components: Publish component files after tokens and assets are available
   • badges, then buttons, then forms, etc.
4. Guides: Publish guidelines and templates last since they reference components

Enable Libraries for Teams

Administrators can pre-enable libraries:

1. Select All projects in Figma file browser
2. Click dropdown icon next to the team name and select View settings.
3. Under Libraries or Shared, click the View team's libraries option.
4. Choose which files to make the library available in by using the dropdown menu next to each library file.

Version Strategy

Semantic Versioning: Chassis follows semver (X.Y.Z)

• Major (X): Breaking changes, component restructuring
• Minor (Y): New features, new components, non-breaking changes
• Patch (Z): Bug fixes, small improvements

Update Frequency Recommendations:

• Patches: Update immediately for bug fixes
• Minor: Update monthly or per sprint
• Major: Plan migration, test thoroughly, update quarterly

Troubleshooting

Even with careful setup, you may encounter issues during the library publishing process or when using Chassis Figma in your projects. This section covers common problems and their solutions to help you resolve issues quickly and get your library working smoothly.

Missing Library Persist

Issue: Can't find published library when trying to replace missing references

Solutions:

1. Verify all library files were published in Step 1
2. Check that libraries are enabled in Assets panel
3. Look for exact library name matches (including version suffixes)
4. Try disabling and re-enabling the library
5. Refresh Figma (Cmd/Ctrl + R)
6. Close and reopen the file
7. Repeat Step 2 for that specific file

Library Not Appearing

Issue: Can't find Chassis library in Assets panel

Solutions:

1. Verify library is published
2. Check team membership
3. Refresh Figma (Cmd/Ctl + R)
4. Check library permissions
5. Close and reopen the file
6. Contact team admin

Components Not Loading

Issue: Components show as missing or broken

Solutions:

1. Check internet connection
2. Verify library is enabled
3. Update to latest version
4. Clear Figma cache
5. Re-enable library

Variable Errors

Issue: Variables not applying correctly

Solutions:

1. Verify Variables file is published
2. Check variable collection names
3. Ensure modes are properly configured
4. Re-link variable references
5. Contact support with file example

Performance Issues

Issue: Library making file slow

Solutions:

1. Limit enabled libraries to needed ones
2. Use components over instances where possible
3. Avoid excessive nesting
4. Optimize large asset files
5. Consider splitting into focused libraries

Next Steps

Now that your library is set up:

1. Learn about Component Assets - Understand the asset system
2. Explore Variables & Styles - Configure tokens and theming
3. Read Design Guidelines - Best practices
4. Browse Components - Explore available components

Getting Help

• Documentation: chassis-ui.com/figma
• Issues: GitHub Issues
• Community: Figma Community
• Email: support@chassis-ui.com