Skip to content

Latest commit

 

History

History
219 lines (170 loc) · 7.63 KB

README.md

File metadata and controls

219 lines (170 loc) · 7.63 KB

Design System Quality Plugin

The goal of this plugin is to maintain the quality of design system components. For more details on how the design system is set up read the design-system docs

The major part of CSS variables is automatically generated by the FigmaExporter. If variables change in Figma, the exporter will generate new variables. The plugin checks if the generated variables are used in the design system components. Any old variable that is still used in the sourcecode will be marked as deprecated.

The plugin also checks if the generated mixins are used in the design system components. Any old mixin that is still used in the sourcecode will be marked as deprecated.

Typically, the plugin is configured to checks the design-system/generated folder for deprecated variables and mixins.

The following audits are included in the plugin:

  • deprecated-variable-usage - Tracks usage of deprecated CSS variable usage
  • deprecated-mixin-usage - Tracks usage of deprecated CSS mixin usage

Setup

code-pushup.config.ts

import { dsQualityPluginCoreConfig } from './src/index.ts';

export default dsQualityPluginCoreConfig({
  directory: 'angular-project/src',
  deprecatedVariables: [
    {
      deprecatedEntity: 'semantic-color-ds-deprecated-primary',
      replacement: 'semantic-color-ds-primary'
    }
  ],
  deprecatedMixins: [
    {
      deprecatedEntity: 'ds-button.shared-deprecates',
      replacement: 'shared'
    }
  ],
})

In the folder where the config is run npx @code-pushup/cli.

Deprecated Variable Usage Audit - deprecated-variable-<variable-name>

This audit checks all design system component's style's for the usage of deprecated mixins. It generates issues for every usage of deprecated variables in a design system component.

Audit Slug: deprecated-variable-<variable-name> - e.g. deprecated-variable-semantic-color-ds-deprecated-primary Score: The score is binary and indicates if all definitions of legacy classes are removed from the codebase. Issue Severity: Warning

Examples

Plugin Config Example

import dsQualityPlugin from './ds-qualtiy.plugin';

export default {
  plugins: [
    dsQualityPlugin({
      directory: 'my-app/src',
      deprecatedVariables: [
        {
          deprecatedEntity: 'semantic-color-ds-deprecated-primary',
          repolacement: 'semantic-color-ds-primary'
        },
        {
          deprecatedEntity: 'semantic-color-ds-deprecated-secondary',
          repolacement: 'semantic-color-ds-secondary'
        }
      ]
    })
  ]
};

Checked Files Example

root
┇
┣━━ 📂packages/design-system/ui
┇   ┣━━ accordion/src/accordion.component.scss
    ┣━━ button/src/button.component.ts
    ┣━━ button/src/button-dropdown.component.ts
    ┣━━ progress-bar/src/progress-bar.component.css
    ┇

Deprecated Variable Usage in DS Component Example

This example showcases the usage of a deprecated variables in button/src/button.component.ts.

button.component.ts

@Comment({
  selector: 'ds-button',
  styles: [`
    .score-primary {
      /* ❌ usage of deprecated variable 'semantic-color-ds-deprecated-primary' use 'semantic-color-ds-primary' component instead */
      background: linear-gradient(var(--semantic-color-ds-deprecated-primary), var(--semantic-color-ds-deprecated-secondary), var(--semantic-color-ds-deprecated-accent));
    }
 `],
  template: `...`
})

button-dropdown.component.ts

@Comment({
  selector: 'button-dropdown',
  styles: [`./button-dropdown.component.scss`],
  template: `...`
})

button-dropdown.component.scss

.btn-dropdown {
  /* ❌ usage of deprecated variable 'semantic-color-ds-deprecated-primary' use 'semantic-color-ds-primary' component instead */
  color: var(--semantic-color-ds-deprecated-primary);
}

Deprecated Variable Usage in Issues Example

|  Severity  | Message                                                                                                                                               | Source file                                                                                                                                                                                                          | Line(s) |
| :--------: | :---------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----: |
| 🚨 _error_ | 🎨 CSS variable <code>semantic-color-ds-deprecated-primary</code> on <code>color</code> of selector btn-dropdown is deprecated.                       | [`./design-system/ui/button-dropdown/src/button-dropdown.component.scss`](./design-system/ui/button-dropdown/src/button-dropdown.component.scss) |  4-20   |

Deprecated Mixin Usage Audit - deprecated-mixin-<mixin-name>

This audit checks all design system component style's for the usage of deprecated mixins. It generates issues for every usage of deprecated mixin in a design system component.

Audit Slug: deprecated-mixin-<mixin-name> - e.g. deprecated-mixin-ds-button.deprecated-shared Score: The score is binary and indicates if all definitions of legacy classes are removed from the codebase. Issue Severity: Warning

Examples

Plugin Config Example

import dsQualityPlugin from './ds-qualtiy.plugin';

export default {
  plugins: [
    dsQualityPlugin({
      directory: 'my-app/src',
      deprecatedVariables: [
        {
          deprecatedEntity: 'button.shared-deprecated',
          repolacement: 'shared'
        },
        {
          deprecatedEntity: 'button-dropdown.special-deprecated',
          repolacement: 'special'
        }
      ]
    })
  ]
};

Checked Files Example

root
┇
┣━━ 📂packages/design-system/ui/generated
┇   ┣━━ accordion.scss
    ┣━━ button.css
    ┣━━ button-dropdown.css
    ┣━━ progress-bar.css
    ┇

Deprecated Mixin Usage in DS Component Example

This example showcases the usage of a deprecated variables in button/src/button.component.ts.

button.component.ts

@Comment({
  selector: 'button',
  styles: [`./button.component.scss`],
  template: `...`
})

button.component.scss

@use './button' as ds-button;

button {
  /**
   * ❌ Bad: Deprecated mixin usage `single-mixin.mixin-name`
  **/
  @include ds-button.shared-deprecated;
}

Deprecated Variable Usage in Issues Example

|  Severity  | Message                                                                                                                                               | Source file                                                                                                                                                                                                          | Line(s) |
| :--------: | :---------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----: |
| 🚨 _error_ | 🎨 Mixin <code>ds-button.shared</code> included in selector <code>button</code> is deprecated.               | [`./ui/accordion/src/button.component.scss`](./ui/button/src/button.component.scss) |  13-19  |