angular-material-custom v1.0.0

Advanced Design System Architecture: From Design Tokens to Themeable Components

Overview

Our design system implements a sophisticated, modular approach to styling, leveraging the power of Sass (SCSS) to create a flexible, maintainable, and themeable codebase. The architecture follows a clear hierarchy:

1. SCSS Variables (Design Tokens)
2. Theme Mixins
3. Component Styles
4. Theme Application

graph TD
    A[SCSS Variables] --> B[Theme Mixins]
    B --> C[Component Styles]
    C --> D[Theme Application]
    E[Light Theme] --> B
    F[Dark Theme] --> B

Detailed Breakdown

1. SCSS Variables (Design Tokens)

At the foundation of our system are SCSS variables, which serve as our design tokens. These variables store visual design attributes and are defined in a single file for easy management and updates.

// dist/scss/_variables.scss
$mat-color-primary: #3f51b5;
$mat-color-background: #fafafa;
$mat-color-background-dark: #121212;
$mat-typography-font-family-base: Roboto, 'Helvetica Neue', sans-serif;
$mat-spacing-md: 24px;
// ... more variables

2. Theme Mixins

We define Sass mixins for each theme, encapsulating all theme-specific styles. This approach allows for easy theme switching and maintains a clear separation of concerns.

// src/themes/_theme-mixins.scss
@mixin light-theme() {
  body {
    background-color: $mat-color-background;
    color: $mat-color-on-background;
  }
  // ... more light theme styles
}

@mixin dark-theme() {
  body {
    background-color: $mat-color-background-dark;
    color: $mat-color-on-background-dark;
  }
  // ... more dark theme styles
}

3. Component Styles

Component styles are written to consume the theme mixins, ensuring they respond to theme changes.

// src/components/_button.scss
@mixin button-theme() {
  .mat-button {
    color: $mat-color-on-surface;
    &:hover {
      background-color: $mat-color-hover-overlay;
    }
    &:focus {
      outline: 2px solid $mat-color-primary;
    }
  }
}

4. Theme Application

Themes are applied using a combination of Sass mixins and CSS classes. This approach offers both performance and flexibility.

// src/main.scss
@import '../dist/scss/variables';

// Global styles
body {
  font-family: $mat-typography-font-family-base;
  font-size: $mat-typography-font-size-base;
  line-height: $mat-typography-line-height-base;
  margin: 0;
  padding: 0;
}

// Import component styles
@import 'components/button';
@import 'components/input';
// ... more component imports

// Import theme mixins
@import 'themes/theme-mixins';

// Theme switching
.light-theme {
  @include light-theme();
}

.dark-theme {
  @include dark-theme();
}

Advanced Techniques

1. Modular Structure: Our file structure promotes modularity, with separate files for variables, mixins, and component styles, all brought together in the main stylesheet.

2. Theme Composition: Our mixin-based approach allows for easy theme composition:

   @mixin custom-theme() {
     @include light-theme();
     @include custom-button-theme();
   }

3. Scoped Theming: We use nested selectors to allow component-level theme overrides:

   .custom-theme {
     @include light-theme();
     
     .mat-button {
       background-color: $mat-color-primary;
     }
   }

4. Performance Optimization: By using SCSS variables and mixins, we optimize for performance while maintaining flexibility. The compiled CSS contains the specific values, reducing runtime calculations.

5. Maintainability: Centralizing our design tokens in the _variables.scss file makes it easy to update and maintain our design system. Changes to core design values can be made in one place and propagated throughout the system.

Implementation Details

• Variables File: Located at dist/scss/_variables.scss, this file contains all our design tokens as SCSS variables.
• Theme Mixins: Defined in src/themes/_theme-mixins.scss, these mixins encapsulate theme-specific styles.
• Component Styles: Each component has its own SCSS file in the src/components/ directory.
• Main Stylesheet: src/main.scss serves as the entry point, importing all necessary files and applying themes.

This architecture provides a robust, scalable, and maintainable approach to building a design system. It leverages the strengths of Sass, providing a powerful toolset for creating sophisticated, themeable user interfaces while maintaining performance and modularity.

Getting Started

To use this design system in your project:

1. Clone this repository:

   git clone https://github.com/your-repo/design-system.git

2. Install dependencies:

   npm install

3. In angular.json ass this

    "styles": [
     "node_modules/@your-org/design-system/dist/main.scss",
     "src/styles.scss"
   ]

4. In app-component.ts:

   import { Component, OnInit } from '@angular/core';

@Component({ selector: 'app-root', template: `

<div [class.dark-theme]="isDarkTheme" [class.light-theme]="!isDarkTheme">
  <!-- Your app content -->
  <button (click)="toggleTheme()">Toggle Theme</button>
</div>

`, }) export class AppComponent implements OnInit { isDarkTheme = false;

ngOnInit() { // Apply light theme by default document.body.classList.add('light-theme'); }

toggleTheme() { this.isDarkTheme = !this.isDarkTheme; document.body.classList.toggle('dark-theme'); document.body.classList.toggle('light-theme'); } }

5. To switch themes dynamically, you can toggle the class on the root element:
   ```javascript
   document.body.classList.toggle('dark-theme');

Contributing

We welcome contributions to our design system! Please read our CONTRIBUTING.md file for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.