Using Solid in a real project
Installing the files is the easy part. The harder question is how you actually integrate a design system into a codebase that already has opinions. This guide covers practical usage patterns, common mistakes, and a realistic path from initial setup to full system adoption.
Solid ships as a structured set of CSS, component markup, and layout primitives. You are not locking into a JavaScript framework. The system works with React, Vue, plain HTML, or any templating engine that outputs markup. That flexibility is intentional, but it does mean you need to understand the class naming conventions and structural expectations rather than just importing a component and hoping for the best.
Before you start dropping components into templates, take twenty minutes to read through the class structure. Solid uses a flat naming pattern rooted in BEM conventions but adapted for practical use in projects that grow beyond a handful of pages. The naming is predictable once you understand the pattern, but unfamiliar if you are used to utility first frameworks where everything is composed inline.
The core expectation is this: components in Solid are self contained. A card component carries its own spacing, typography scale, and responsive behavior. You do not need to wrap it in a utility container or add external margin classes to make it sit correctly in a layout. This is a deliberate design choice. It reduces the number of decisions you make per component and keeps the output consistent across different pages and contexts.
Starting with layout primitives
The most effective entry point is the layout system, not individual components. Start by setting up the grid, container widths, and section spacing. Once the page level structure is right, individual components will land in predictable positions without manual adjustment. Teams that skip this step and start with buttons and cards end up fighting alignment issues that the layout primitives solve automatically.
Layout primitives in Solid include container classes, column grids, and vertical rhythm helpers. These are intentionally minimal. The grid is not a 24 column monstrosity. It gives you enough flexibility for real layouts without encouraging the kind of column nesting that makes responsive breakpoints unpredictable.
Working with component states
Every interactive component in Solid supports a set of states: default, hover, focus, active, and disabled at minimum. More complex components like accordions and tabs include open, closed, and transitioning states. The class naming for states follows a consistent suffix pattern across every component, so once you learn how buttons handle states, you already know how navigation items, form inputs, and card actions work.
The most common mistake teams make with state handling is mixing Solid state classes with custom CSS that targets the same property. If a button component has a defined focus ring style and you add your own focus outline through a global stylesheet, you get conflicting rules. The fix is straightforward: if you need to customize a state, override the Solid variable for that state rather than adding a competing rule. The token system is designed to absorb customization cleanly.
Component composition
Solid components are designed to be composed. A card can contain a button. A navigation bar can contain form inputs. A modal can contain a full form layout. The CSS specificity is managed so that nested components do not break each other. This is harder than it sounds and is one of the main things that separates a design system from a loose collection of styled elements.
When you compose components, the outer component controls spacing and the inner component controls its own appearance. A button inside a card does not get different padding just because it is inside a card. It gets the same padding it always has. The card controls how much space exists around the button, not the button itself. Understanding this boundary is essential.
These are the errors that come up most often when teams start using Solid, based on support conversations and code reviews across real projects.
Inventing modifier classes
Every supported modifier is documented. If you need a large button, the modifier class exists and is named predictably. If you find yourself inventing a modifier name that seems logical but is not in the documentation, it will not work. Solid does not use dynamic class matching. Every class is explicitly defined. Check the docs before creating custom modifiers.
Nesting BEM elements too deeply
Solid keeps element nesting to two levels maximum. You will see patterns like component-name__element, but you will not see component-name__element__sub-element. If you find yourself writing deeply nested element classes, you have likely missed a simpler pattern. Deep nesting creates specificity problems and makes overrides unpredictable.
Overriding tokens at the wrong scope
Design tokens in Solid cascade intentionally. A color token set at the root level applies everywhere. A token set on a specific component applies only there. The mistake is setting tokens at an intermediate scope, like on a section wrapper, and expecting them to cascade predictably through all nested components. Token overrides work best when applied either globally or on the specific component instance you want to change.
Mixing spacing approaches
Solid includes a spacing scale. If you use that scale for some components and arbitrary pixel values for others, the visual rhythm breaks. The spacing scale exists precisely so that vertical and horizontal spacing feels consistent without manual calculation. Commit to the scale or override it globally, but do not mix approaches within the same page.
Week one: layout and typography
Start with the grid system and typographic scale. Get your page containers, section spacing, and heading hierarchy set up using Solid classes. Do not touch individual components yet. If the layout structure is correct, everything else slots in more easily later.
Week two: core components
Introduce buttons, form elements, and cards. These are the highest frequency components in most applications and the ones where consistency matters most immediately. Pay attention to state classes during this phase. Get hover, focus, and disabled states wired up correctly from the start rather than patching them later.
Week three: navigation and layout components
Add navigation bars, sidebars, footers, and any layout level components your application needs. These components interact with the grid system, so having the layout primitives already in place from week one makes this integration significantly smoother.
Week four: custom theming and tokens
Once the core system is in place and working, begin customizing through the token system. Adjust colors, spacing values, border radius, and typography to match your brand. The token system is designed to handle this without requiring changes to the component markup. If you find yourself editing component HTML to achieve a visual change, you are probably doing something the token system already supports.
Beyond week four
After the initial adoption period, the system should be running without friction. Ongoing work shifts to extending the system with project specific components that follow the same naming conventions and structural patterns. The goal is that new components feel like natural extensions of the system rather than custom additions that sit outside it.
See the full component showcase in the Solid demo to understand how individual components look and behave in context. The Solid overview covers the system architecture and design philosophy. If you are evaluating Solid for a project, the Solid Design System product page has pricing and package details.
The most productive approach is to work through the demo page with the class documentation open, matching each visual component to its markup. That hands on walkthrough will do more for your understanding than reading documentation alone.