Glossary
All Gloss UI terminology in one place. Hover any dotted-underline term throughout the docs to see its definition.
Architecture Model
- Left/Right Model
The organizing principle of Gloss UI, introduced in v2.0. The left side contains hidden infrastructure (Dictionary, Base Primitives, Variants). The right side is the consumer-facing UI.* catalog.
- Design Dictionary
Ten TypeScript modules that export typed CSS variable references (Color, Spacing, Typography, etc.). All visual decisions flow from the Dictionary rather than raw hex or pixel values.
- Base Primitive
A raw, highly-configurable component chassis that accepts a Definition object with every structural and visual prop. Base Primitives live on the left side and are never imported by consumers directly.
- Definition Object
A plain object that configures a Base Primitive's visual properties — background, color, padding, radius, hover state, etc. Variant Recipes are pre-built Definition bundles.
- Variant Recipe
A pre-built Definition bundle that configures a Base Primitive for a specific use case. For example, a "primary button" recipe bundles bg, color, padding, and hover state into one reusable Definition.
Consumer Tiers
- Preset Primitive
A locked-down wrapper around a Base Primitive that exposes only semantic props (size, variant). Preset Primitives are the smallest building blocks available to consumers. There are 39 in the catalog.
- Composite
A single-purpose, data-driven component. Composites have no generic children prop — instead they expose Slots for safe content injection. There are 24 Composites in the catalog.
- Composition
A layout orchestrator that combines multiple Composites into a cohesive UI pattern. Form-based Compositions bind to Zod validation schemas. There are 11 Compositions in the catalog.
Cross-Cutting
- Context Container
A structural wrapper that propagates a UIContext value (region + density) to all children via React Context. Children automatically adapt their styling based on where they are rendered — no prop drilling required.
UIContextThe React Context that carries region and density information through the component tree. Components call useUIContext() to adapt their styling based on where they sit (e.g., card-header vs card-body).
UIRegionA string literal identifying where a component sits in the layout — card-header, card-body, dialog-header, toolbar, form-section, table, etc. Context Containers set the region; children read it from UIContext.
- Functional Wrapper
An invisible behavioral layer that separates visuals from behavior. Five of the eleven Wrappers are behavioral: Actionable, Sortable, Selectable, Dismissible, and Expandable. They add interaction patterns without rendering visible UI.
Facade & Imports
UI.*NamespaceThe consumer-facing facade that re-exports all 111 components under a single tree-shakeable namespace. Import as
import * as UI from '@so.boss/gloss-ui/catalog'and use as<UI.Button>.- Sub-Barrel
One of six category files inside the facade directory — typography, inputs, display, overlay, layout, feedback. Each sub-barrel groups related component re-exports that roll up into the UI.* namespace.
- Compound Static Properties
A pattern where sub-components are attached as static properties on a parent: UI.Card.Header, UI.Dialog.Body, UI.Menu.Item. Four components use this pattern: Card, Accordion, Dialog, and Menu.
@so.boss/gloss-ui/ catalog The recommended entry point for all consumers. Exports 111 tree-shakeable components under the UI.* namespace. This is the only import path most developers need.
@so.boss/gloss-ui/ internals An advanced entry point that exposes Base Primitives, Dictionary values, and utility functions. Reserved for dashboard complex internals or library maintainers who need to work below the Preset layer.
Patterns
- Slot
A safe injection zone on a Composite component. Instead of a generic children prop, Composites expose named Slots (headerSlot, rowActionSlot, emptySlot) that constrain where custom content can appear.
asProp (Polymorphism)All Preset Primitives support the
asprop to change the rendered HTML element while keeping the component's styling. For example,<UI.Button as="a" href="/home">renders a styled anchor tag.- Density
A UIContext property ('default' | 'compact' | 'comfortable') that controls spacing tightness. Context Containers propagate density to children, allowing toolbar-style compact layouts without per-component props.
Design System
- Design Tokens
SCSS variables and CSS custom properties that encode the design system's visual decisions — colors, spacing, typography, shadows, radii. Published as @so.boss/gloss-tokens and consumed via @so.boss/gloss-styles.
- BEM Naming
Block-Element-Modifier naming convention used for all Gloss UI CSS classes: .gloss-{component}__element--modifier. Ensures flat specificity and predictable styling with no CSS modules.