Upgrading
Upgrading libraries in general
Updating Figma libraries is notoriously difficult. Figma doesn’t provide an overarching upgrade mechanism, so in order to know what kind of changes we make over time, we diligently keep a detailed changelog where we document all changes to the kit.
Our advice for when you are considering to upgrade or not is to first read our blog post about upgrading the kit. It’s our honest take about whether you would even go on this path or not.
We are working designers too and understand that it’s not always possible to start fresh. If you decide that you want to upgrade or perform a surgical upgrade for a specific part of the kit, this page is for you.
Updating the Figma Obra shadcn/ui kit
The exact ways to update your Obra shadcn/ui library are rather difficult to explain, but in this part of the docs we will give some pointers to the adventurous.
We hope to improve this section over time, and strike a balance between improving the kit and introducing breaking changes. Any comments are welcome. Please e-mail us at [email protected]!
In general, instead of trying to upgrade the kit exactly to what the latest version is, it might be worthwhile to understand where the library is moving rather than doing the exact changes in your copy of the file. You can then decide on a case-by-case basis whether you want to perform an upgrade or not.
We have several plugins to help you on your way. We welcome bug reports if you run into issues with them.
Here’s our upgrade guides, sorted by recency.
This is a significant update that aligns the kit much more closely with official shadcn/ui variables. The main areas of change:
Unofficial variables removed
Many unofficial variables have been removed and mapped to official shadcn equivalents. If you customized any of these, you’ll need to remap them:
body background→ mapped tobackgroundaccent 0,accent 2,accent 3→ mapped toaccentborder 0,border 1,border 3,border 4,border 5→ mapped toborderforeground alt→ mapped toforeground muteddestructive text,destructive subtle,destructive border→ mapped todestructivesidebar muted→ mapped toforeground mutedmid alt→ mapped tobrand-neutrals-500obra shadcn ui docs 1,obra shadcn ui docs 2→ mapped tobackground
Chart colors simplified
Unofficial chart variables (unofficial/categorical, unofficial/sentiment, unofficial/shades) have been removed. Chart colors now use flat chart 1-5 variables. We also added a dedicated collection documenting all 18 shadcn themes with 5 shades each, which serve as the source for chart colors.
Alpha collection changes
- Added
alpha-85for both black and white - Added
shadcn-darkmode to alpha collection - Alpha collection moved into semantic colors. If you want to do this in your own kit, use Obra Variable Collection Manager.
Input variable fix
The input variable was incorrectly used for input backgrounds. It now correctly maps to the border of inputs (matching shadcn/ui). Input backgrounds now use the regular background variable.
Icons: Lucide 1.0
- Lucide 1.0 replaces the previous beta version (~300 new icons, some brand icons removed)
- Brand icons re-added via Obra Icons
- Default stroke changed from 1.5px to 2px
Component and slot improvements
Improved slot usage across 15+ components (Breadcrumb, Card, Chart, Command, Empty, Item, Pagination, Radio, Checkbox, Rich Radio, Rich Checkbox, Tabs, Drawer, Dialog). Notably, Rich Radio, Rich Checkbox and Rich Switch now have slots to add extra content inside the box.
Decorative icon colors removed
We removed specific colors from the decorative icon component, as not to make design choices for you. Similarly, the todo marker now binds to primary instead of green.
New OC component: Backdrop
We added a new Obra Custom component — Backdrop — which you could backport to your 1.7.0 kit.
Colors
Added Taupe, Mauve, Mist and Olive (Tailwind 4.2 colors).
Border scoping
Borders are now scoped to Frame, Shape and Stroke (previously Stroke only).
Slots for wrapper components
The main change is the introduction of Figma Slots for wrapper components (Card, Drawer, Dialog, Hover Card, Sheet, Empty). To upgrade, you’d have to add slots to these components yourself in your copy of the kit.
Pro Blocks and OC components
1.7.0 added Pro Blocks and 8 Obra Custom (OC) components. These are new additions — you can copy them from the new kit version into your file if needed. Note: when copying from a newer file into an older one, layers will not automatically sync. You’ll have to resync with your library to make sure color and type logic is connected if you want to use these pro blocks.
Shadow bug fix
shadow-xs-2 and shadow-xs had the wrong black alpha value applied. Check and correct these values in your shadow collection.
From 1.6.0: Documentation and spacing
If you’re still on a pre-1.6.0 version, note that 1.6.0 moved all documentation from Propstar to Obra Autodocs, added 6xl through 10xl spacing variables, and fixed a bug with the Empty component not having auto layout.
Documentation moved to Obra Autodocs
All Propstar documentation was replaced with Obra Autodocs. If you had custom Propstar docs in your kit, you’ll want to regenerate them using Obra Autodocs instead.
Spacing additions
Added 6xl through 10xl variables for spacing. You can add these to your own spacing collection if needed.
Bug fix
Fixed a bug with the Empty component not having auto layout.
New variable collections
Introduced branded neutrals, branded shades and brand-combinations collections. These are new additions — you can set them up in your own kit following the same pattern.
Alpha color collection
New collection with variables for various opacities of black and white. Used for layering fills to simulate opacity, and for branding shadows.
Typography additions
Added large paragraph style, caption style and corresponding variables. Added medium and bold variants for all paragraph styles.
Component improvements
- Avatar Stack: ability to show/hide 3rd, 4th or 5th avatar
- Button: added extra large variant
- Input: vastly improved to support appended/prepended text and icons on both sides
- New: Popover component added
- New: bordered Accordion variant
Deprecated variables removed
- Removed deprecated
midcolor variable (was mapped to neutral 500) - Removed deprecated
contrastvariable (was mapped to black/white) - Removed deprecated chart variants
Bug fixes
Multiple bug fixes across avatars, inputs, destructive menu items, and spacing/scoping improvements. All component docs were regenerated with the newest Propstar grid format.
Icon hack treatment
- The icon hack was removed
- To solve this: take the icons from 1.5.0
- Remove the icon hack from all components
- Re-link all icons in all components
- Interesting to understand the underlying problem
- We removed the hack because it was difficult for some users to understand
- We also had several discussions about the scalability of icons
- We landed on a simpler solution where icons are outlined and the hacks are removed; but, is this where you want to take your own icon strategy?
Notable variable changes (easy)
- Bugs have been fixed in the shadow collection
- The treatment of the destructive foreground is different
Components v2 (difficulty: moderate)
- Some components got an update
- Item
- Empty
- Breadcrumb
- We recommend flagging already used components with a red background color
- Then, publishing the system so you can see components that should receive an update
Re-linking libraries
- When you copy paste a new component into your existing library, it won’t be linked with your library
- You will have to re-link it to your library: this manual process is annoying
- We have tools for this: Obra Remote Library Scanner
- Improvements to typography mostly
- Interesting to understand the underlying pattern: we provided more options for paragraphs. Do you need them or not in your own system?
- Use a similar logic as for border radius above (1.1.5 to 1.2.0), but for spacing.
- Optional: Go through the file with the Obra Spacing Variable Fixer plugin to re-attach to components.
All components were moved to separate pages.
- To fix this:
- Create a page per component
- Move every component to its corresponding page
- To fix this:
Theme collection was renamed to Semantic colors
- To fix this: rename the relevant collection
The way border radii and spacing was treated, was changed
To fix this
- Split up the Border radii collection in 2 collections: 1. Border Radii and 2. Border radii (absolute).
- Note that, in your file, variables are bound to corners already. As such, a non-destructive variable move has to be made to make this happen.
- What you would do is first re-name the absolute values (e.g. “rounded-4” tied to “4” to the t-shirt sizing logic; in this case rename rounded-4 to rounded-sm. Reference the 1.4.0 variables to do so.
- Then, create the absolute values as a standalone collection. Reference the 1.4.0 variables to do so.
- Set up the Border radii (absolute) collection variables to not be published.
- Now attach the Border radii (t-shirt sized e.g. xs, sm…) to your newly created absolute variables
- Optional: Go through the file with the Obra Border Radius Variable Fixer to re-attach to components.
! Important: We provide a plugin called Obra Variable Collection Manager which allows to merge, split and move collections. Do not use use “move” in the Obra Variable Collection Manager plugin, do the move yourself manually; otherwise, you might end up with a file full of unbound variables.