Solid design system: component architecture and implementation notes

Every component in Solid follows a three-layer architecture: the token layer defines visual properties like color, spacing, and typography; the structural layer defines the HTML pattern and responsive behavior; and the variant layer defines the named configurations that map to specific use cases. This separation is not theoretical. It has practical consequences for how teams customize, extend, and maintain the system over time.

The token layer is the foundation. Solid uses a tiered token architecture where global tokens define the raw palette (colors, spacing scale, type scale) and component tokens reference those globals through semantic aliases. A button does not reference "blue-600" directly. It references "button-primary-bg" which resolves to "brand-primary" which resolves to a specific color value. This indirection is what makes systematic theming possible: changing the brand color updates every component that references it without hunting through stylesheets for hex values.

The structural layer handles the HTML pattern for each component. Solid is opinionated about markup structure because consistent markup is what makes consistent styling possible. A card component always uses the same element hierarchy. A form group always wraps its label, input, and help text in the same container pattern. These conventions eliminate the guesswork that leads to inconsistent implementations when multiple developers build with the same system independently.

The variant layer is where named component configurations live. Rather than combining utility classes ad hoc to achieve a specific look, Solid defines named variants that correspond to specific contexts. A button can be "primary," "secondary," "outline," or "ghost." A card can be "default," "elevated," or "bordered." These variants are designed to be exhaustive enough that developers rarely need to invent custom combinations, but limited enough that the system does not become a utility framework with hundreds of modifier classes.

Design tokens are easy to talk about in the abstract and surprisingly difficult to implement well. The common failure mode is over-tokenization: creating a token for every conceivable property, resulting in a token file that is harder to navigate than the CSS it replaced. Solid avoids this by tokenizing only the properties that benefit from systematic management and leaving everything else as conventional CSS.

Colors, spacing, typography, border radius, and shadow depth are tokenized because these are the properties that need to stay consistent across components and change together when branding requirements shift. Properties like overflow behavior, display modes, position values, and z-index layering are not tokenized because they are component-specific concerns that do not benefit from global coordination.

The spacing token scale in Solid follows a deliberate progression. The scale is not linear and not purely mathematical. It is tuned by hand to produce spacing values that look correct at each size. The difference between spacing-2 and spacing-3 is not the same absolute value as the difference between spacing-8 and spacing-9, because visual perception of space is not linear. Small values need tighter increments. Large values need bigger jumps. The Solid spacing scale reflects this, and it produces layouts that feel balanced without requiring manual spacing adjustments.

Typography tokens follow a similar philosophy. The type scale defines size, weight, line height, and letter spacing as a coordinated set rather than independent properties. When you apply a heading style from the token system, you get not just a font size but a complete typographic treatment that is calibrated for readability at that specific size. This eliminates the common problem of applying a heading font size but forgetting to adjust line height, resulting in text that is technically the right size but visually crowded or loose.

Individual components solve individual problems. A button handles click interactions. A card presents grouped information. A modal manages focus trapping and overlay behavior. But assembling these components into a coherent page layout is a separate challenge that most design systems leave entirely to the developer.

Solid includes layout primitives that address page-level structure: page shells that define the relationship between navigation, sidebar, and main content areas; content containers that manage maximum width and horizontal padding consistently; and section rhythm systems that maintain vertical spacing relationships between page sections. These primitives are composable. A page shell can contain any combination of sidebars and content areas. A content container can live inside any page shell configuration. The primitives define spatial relationships, not visual appearance.

The value of layout primitives becomes clear in projects with more than a handful of pages. Without them, every new page requires ad hoc layout decisions: how wide should the content area be? How much padding should the sidebar have? What happens to the layout when the sidebar is absent? Layout primitives answer these questions once, at the system level, so that page-level development focuses on content and functionality rather than spatial negotiation.