@openzeppelin/contracts-ui-builder-styles

Centralized Styling System

This package contains the centralized styling system for the Contracts UI Builder monorepo. It uses Tailwind CSS 4.0 with OKLCH colors and follows the new-york style from shadcn/ui.

Package Structure

styles/
├── src/                        # Source stylesheets and utilities
├── global.css                  # Main CSS file with theme variables and base styles
├── tailwind.config.cjs -> ../../tailwind.config.cjs  # Symlink to root config
├── postcss.config.cjs -> ../../postcss.config.cjs    # Symlink to root config
├── components.json -> ../../components.json           # Symlink to root config
├── package.json                # Package configuration
├── tsconfig.json               # TypeScript configuration
├── tsup.config.ts              # Build configuration
└── README.md                   # This documentation

Key Files

• global.css - Main CSS file with theme variables and base styles that's shared across all packages.
• src/utils/ - Utility CSS files and styling functions (if any).
• Configuration symlinks ensure consistency across the monorepo.

Styling Approach

This monorepo utilizes a consistent styling approach driven by the consuming application:

• Centralized Theme: This @styles package provides the single source of truth for theme variables (colors, spacing, radius) and base styles in global.css.
• Centralized Configuration: Root-level tailwind.config.cjs, postcss.config.cjs, and components.json are used via symlinks in consuming packages (builder, exported apps).
• Consumer-Driven Build: The main application (packages/builder) or exported applications are responsible for the Tailwind CSS build process.
• Automatic Content Scanning: Tailwind v4 automatically scans the source code of the application and its dependencies (like @openzeppelin/contracts-ui-builder-ui and @openzeppelin/contracts-ui-builder-renderer) for utility class usage.
• CSS Generation: The consumer app's build generates the final CSS file, including base styles from global.css, theme variables, and all necessary utility classes used throughout the application and its dependencies.

Key Point: Library packages like renderer and ui do not build or ship their own CSS. Styling is entirely managed by the final application build, ensuring consistency and leveraging the shared theme from this @styles package.

Features

• Tailwind CSS 4.0: Using the latest Tailwind features including native cascade layers and OKLCH colors
• Direct OKLCH color values: Variables use OKLCH values directly without nested references for simplicity
• Unified theming: Consistent design tokens across all packages
• Dark mode support: Built-in dark mode with proper variable handling
• Shadcn/ui integration: Configured for the new-york style

CSS Variables

The system uses CSS variables for all theme colors and properties. These variables are defined directly with OKLCH values for better readability and maintenance:

:root {
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  /* ... other variables */
}

Form Component Spacing

Form components follow our design system with consistent spacing:

• flex flex-col gap-2 - Used for form fields to create proper spacing between label and input
• space-y-4 - Used for spacing between form fields in a group
• space-y-6 - Used for spacing between form sections

Adding New Components

When adding new shadcn/ui components, use the root components.json config:

pnpm ui:add button

This ensures all components follow the same unified styling approach.

Configuration Architecture

This package provides centralized styling utilities and components used across all packages in the monorepo. The project uses a symlink-based configuration approach for consistency:

Root Configuration Files

The root directory contains these key configuration files:

• tailwind.config.cjs: Shared Tailwind configuration with CSS variable-based theming
• postcss.config.cjs: Shared PostCSS configuration for processing
• components.json: Shared shadcn/ui component configuration

Package Integration

Each package that contains UI elements needing Tailwind processing (like builder, renderer, and the new ui package) has symbolic links to these root configurations, ensuring consistent styling and behavior:

packages/builder/tailwind.config.cjs -> ../../tailwind.config.cjs
packages/renderer/tailwind.config.cjs -> ../../tailwind.config.cjs
packages/ui/tailwind.config.cjs -> ../../tailwind.config.cjs

Exported Templates

During the export process:

• Template files in the builder package are used to create standalone projects
• Symlinks are resolved to create standalone configuration files
• The styles from this package are included in the exported project
• The result is a self-contained project with proper styling

Utilities

(Add details about any utility functions or components provided by this package if applicable)