Architecture Overview

Turborepo Structure

This design system is built as Turborepo packages, enabling shared code and consistent tooling across all packages and applications.

Directory Structure

.
├── apps/
│   ├── curriculum-app/          # Main application (port 3000)
│   ├── design-system-docs/      # Design system documentation (port 4000)
│   ├── platform-content-app/    # Payload application (port 3001)
│   └── a11y/                    # Accessibility report generator cli
├── packages/
│   ├── integral/                # @im/integral (components + shared styles)
│   ├── integral-icons/          # @im/integral-icons (icon components + icons.css)
│   ├── integral-tokens/         # @im/integral-tokens (design token source + generated outputs)
│   └── @im/typescript-config    # Shared TS configs
└── turbo.json                   # Turborepo configuration
└── biome.json                   # Code formatting & linting

Key Design Decisions

Below are the major technical choices that shape the design system’s architecture.

1. Styling Architecture

• Foundations Styles: SCSS for design system styles
• Legacy Styles: Legacy SCSS for application-wide styles
• Mixins: SCSS Mixin utilites for within the design system package
• Styled Component Styles: SCSS with variables, mixins, and nesting (Overrides foundations, legacy, and primitives styles)
• Whimsical Styles: Optional SCSS animations
• Tailwind Config: Applies design token overrides to tailwind config
• Tailwind Utilities: App level tailwind overrides all CSS cascade layers

2. CSS Cascade Layers Architecture

We use CSS Cascade Layers to manage style precedence:

@layer tokens, resets, base, theme, legacy, integral, app, utilities;
@layer integral {
  @layer foundations, whimsical, icons, components.primitives, components.styled;
}

Layer Structure:

1. tokens: Design tokens (optional layer)
2. resets: Global CSS Resets
3. base: Fumadocs, Tailwind preflight (optional layer)
4. theme: Design tokens, Tailwind theme, Design System theme
5. legacy: Global styles for accessim.org
6. integral: Design system styles with sub-layers:
   • integral.foundations: System-wide styles
   • integral.whimsical: Animations
   • integral.icons: Icon base styles
   • integral.components.primitives: Primitive component styles
   • integral.components.styled: Styled component styles
7. app: app level styles (optional layer)
8. utilities: Tailwind utility classes

Why Cascade Layers?

• Predictable specificity without !important
• Mix SCSS, CSS, and Tailwind seamlessly
• Clear override hierarchy
• Performance optimizations (tree shaking, lazy loading)

3. Build Configuration

Hybrid Build Process

• Tokens: Compiled to CSS, SCSS, JS via style-dictionary CLI
• SCSS: Compiled to CSS via sass CLI, imported to layers at app level
• CSS: Exported directly, JIT compilation at app level
• Components: Export raw .tsx files, JIT compilation at app level

Design System Build Pipeline

Design Token Exports

"exports": {
    "./css/tokens.css": "./dist/css/tokens.css",
    "./scss/_tokens.scss": "./dist/scss/_tokens.scss",
    "./js/tokens.js": "./dist/js/tokens.js"
  }

Component Exports

"exports": {
    "./styles/resets.css": "./src/styles/foundations/resets.css",
    "./styles/themes.css": "./src/styles/legacy/b-baseline/b-themes.css",
    "./styles/legacy.css": "./dist/styles/legacy/styles.css",
    "./styles/payload/frontend.css": "./dist/styles/payload/frontend.css",
    "./styles/payload/admin.css": "./dist/styles/payload/admin.css",
    "./styles/foundations.css": "./dist/styles/foundations/styles.css",
    "./styles/components/primitives.css": "./src/styles/components/primitives/styles.css",
    "./styles/components/styled.css": "./dist/styles/components/styled/styles.css",
    "./styles/tailwind.css": "./dist/styles/tailwind/styles.css",
    "./styles/whimsical.css": "./dist/styles/whimsical/styles.css",
    "./components/primitives": "./src/components/primitives/index.ts",
    "./components/styled": "./src/components/styled/index.ts"
  },

Icon Exports

"exports": {
    ".": "./src/index.ts",
    "./icons.css": "./src/icons.css"
  }

Style Dictionary for Tokens

• JSON source → CSS variables + SCSS variables + JS variables
• Automated token generation
• Framework-agnostic output

4. Import Strategies

Style Imports (in app level global.css)

/* Import with cascade layers */
@layer tokens, base, theme, legacy, integral, app, utilities;
@import 'tailwindcss/preflight.css' layer(base);
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';
@import '@im/integral/styles/resets.css' layer(base);
@import '@im/integral/styles/themes.css' layer(theme);
@import 'tailwindcss/theme.css' layer(theme);
@import '@im/integral/styles/tailwind.css' layer(theme);
@import '@im/integral/styles/legacy.css' layer(legacy);
@import '@im/integral/styles/foundations.css' layer(integral.foundations);
@import '@im/integral/styles/whimsical.css' layer(integral.whimsical);
@import '@im/integral/styles/components/primitives.css'
  layer(integral.components.primitives);
@import '@im/integral/styles/components/styled.css'
  layer(integral.components.styled);
@import '@im/integral-icons/icons.css' layer(integral.icons);
@import 'tailwindcss/utilities.css' layer(utilities);

Component Imports

// Primitives
import { Button } from '@im/integral/components/primitives';

// Styled components (Design-aligned components)
import { Button as StyledButton } from '@im/integral/components/styled';

Icon Imports

// Icons
import { ChevronRightIcon } from '@im/integral-icons';

5. Styling Approach

Tailwind CSS v4

• PostCSS-based configuration
• Design tokens integration
• Component primitive utilities are manually converted via @apply (required for use in css cascade layer)

SCSS Integration

• Styled components use SCSS features:
  • Variables for theming
  • Mixins for reusable patterns
  • Nesting for component structure
  • Functions for calculations

Primitive Components

• Pure CSS only (no SCSS)
• Tailwind utilities via @apply
• Minimal specificity for brand and app level overrides

Development Workflow

Contributor implementation workflow (component creation, style wiring, exports, and package build commands) lives in the Contributing Guide.

Performance Optimizations

Tree Shaking

• sideEffects: false in package.json
• Direct imports avoid importing entire libraries

CSS Loading Strategy

• Cascade layers ensure proper specificity
• Split bundles for primitives vs branded components
• PostCSS optimization in production
• Selective imports for smaller bundles or non-branded apps

Development Speed

• Package builds are typically minimized during development
  • Turbo caches unchanged packages
  • Direct file exports are used for just in time (JIT) compilation at app level
• Hot reload works across package boundaries

Best Practices

Design System Guidelines

• Tokens: Use for all colors/spacing/typography
• Layers: Flexible cascade hierarchy
• Primitives: Pure CSS, no SCSS features, Use to collect styles included from external components like shadcn
• Styled Components: Use SCSS for complex styling
• Utilities: App level overrides using tailwind utilities

App Guidelines

• Import styles in correct layer order
• Use design tokens over hard-coded values
• Prefer local app level overrides with tickets to migrate to shared design system
• Test any package modifications across apps before committing

Summary

This architecture provides:

• Hybrid Styling: Supports CSS, SCSS, and Tailwind all in one ecosystem
• Cascade Control: CSS layers eliminate specificity issues
• Unified System: Tokens, components, and icons are split into focused packages
• Performance: Optimized builds with selective compilation
• Developer Experience: Clear patterns and fast iteration
• Flexibility: Mix styling approaches based on needs

The combination of Turborepo, CSS Cascade Layers, Tailwind CSS v4, and our hybrid CSS/SCSS approach creates a modern, performant foundation for building scalable applications with a consistent design language.