Basalt Design System Development

Use these guidelines when making changes to the Basalt design system itself (not when using Basalt to build UI—those guidelines are in CLAUDE.md).

Component Organization

• •Each component lives in its own file in packages/basalt/components/
• •Components are styled with CSS Modules (.module.css) and PostCSS mixins
• •Stories (.stories.tsx) live alongside their components
• •All components must be exported through packages/basalt/index.ts

CSS Cascade Layers

Basalt uses CSS cascade layers to control style precedence. Basalt's CSS is wrapped in two layers:

• •basalt-reset — CSS reset (lowest priority)
• •basalt-styles — tokens and Basalt component CSS Modules

Fonts are unlayered (@font-face is layer-agnostic). The consuming app is responsible for declaring the layer order.

All Basalt component CSS Modules must be wrapped in @layer basalt-styles { ... }.

Styling

• •Use CSS Modules (.module.css) for component styles
• •Use --basalt-* CSS custom properties for all token values
• •Use PostCSS mixins for responsive breakpoints, theming, text presets, and font stacks
• •Use clsx to concatenate class names
• •Never use inline styles or !important

PostCSS Mixins

Mixins are defined in packages/basalt/css/mixins.css and loaded via postcss-mixins. They are designed to work in CSS Modules (class selectors for theming are wrapped in :global()).

Font stacks

Set font family and OpenType feature settings:

Text sizing

Responsive font size and line height (mobile → desktop):

Responsive breakpoints

Wrap content in a media query:

Theme

Scope styles to light or dark theme:

Interaction

CSS Custom Properties

Tokens are defined in packages/basalt/css/tokens.css on :root. Naming convention:

Transition workaround

lightningcss strips var() from comma-separated transition shorthand (parcel-bundler/lightningcss#194). When combining multiple transitions, use longhand properties with the primitive tokens (--basalt-motion-transition-*-property, -duration, -timing). See Pill.module.css for an example.

Key Files

Storybook

• •Run with yarn storybook from the basalt package
• •Token documentation stories: packages/basalt/css/stories/*.stories.tsx
• •Component stories: alongside their components
• •Custom viewports match Basalt breakpoints (Phone, Tablet, Desktop)
• •Theme toggle available for light/dark mode testing

Adding a New Component

1. •Create packages/basalt/components/MyComponent.tsx
2. •Create packages/basalt/components/MyComponent.module.css for styles, wrapped in @layer basalt-styles { ... }
3. •Export from packages/basalt/index.ts
4. •Create packages/basalt/components/MyComponent.stories.tsx
5. •Run yarn typecheck and yarn format:all

Checklist

When making changes to Basalt:

• • Use CSS Modules + PostCSS mixins for styling
• • Wrap CSS Module contents in @layer basalt-styles { ... }
• • Use --basalt-* tokens for all design values
• • Export new components from index.ts
• • Add or update stories for documentation
• • Test in both light and dark modes
• • Test at all breakpoints (Phone, Tablet, Desktop)
• • Run yarn typecheck
• • Run yarn format:all