@maltjoy/stylelint-config

Shareable Stylelint config for the Maltjoy design system.

This package is ESM-only ("type": "module"). Use it from stylelint.config.js.

The default export is only the Maltjoy token rules (warnings). It does not extend stylelint-config-standard-*, so an app can keep its own Stylelint baseline. Optional full presets add a standard baseline for DS packages.

| Export | Use when | Extends | | --- | --- | --- | | @maltjoy/stylelint-config | You already have a Stylelint config (Malt apps) | nothing — token overlay, warnings | | @maltjoy/stylelint-config/vue | Vue SFCs + SCSS (@maltjoy/core-vue) | stylelint-config-standard-scss + stylelint-config-standard-vue/scss | | @maltjoy/stylelint-config/scss | SCSS only (@maltjoy/themes) | stylelint-config-standard-scss | | @maltjoy/stylelint-config/strict | You want token rules to break the build | nothing — same overlay, errors |

strict.js lists one severity per rule: flip a line back to warning when the codebase is not ready to enforce that rule yet.

Install

npm install --save-dev stylelint @maltjoy/stylelint-config

stylelint >=17 is a peer dependency.

Usage

Apps that already have Stylelint (Malt monorepo). Keep your baseline, add the token overlay:

/** @type {import('stylelint').Config} */
export default {
  extends: [
    'stylelint-config-standard-scss', // or your existing config
    '@maltjoy/stylelint-config',
  ],
};

Vue + SCSS (packages/core-vue), full DS preset:

/** @type {import('stylelint').Config} */
export default {
  extends: ['@maltjoy/stylelint-config/vue'],
};

SCSS only (packages/themes):

/** @type {import('stylelint').Config} */
export default {
  extends: ['@maltjoy/stylelint-config/scss'],
};

Strict. Append the overlay to raise token-rule severities. It works on the default overlay or either full preset:

/** @type {import('stylelint').Config} */
export default {
  extends: ['@maltjoy/stylelint-config/vue', '@maltjoy/stylelint-config/strict'],
};

/vue and /scss disable selector-class-pattern: BEM (__, --) is the public class API. The Vue preset also allows :deep, :global, and :slotted in extracted .scss files (not only in *.vue).

Token rules

Rules under rules/ enforce Joy design tokens instead of hardcoded CSS values. They are warnings on the default overlay and both full presets, so an app can adopt them without breaking its build, and errors with /strict. @maltjoy/core-vue and @maltjoy/themes both run /vue or /scss plus /strict. Storybook documents each rule under Stylelint Plugin, with its severity in each preset.

• maltjoy/no-hardcoded-hex-colors: disallow hex colors such as #fff.

Message:

Avoid hardcoded hex colors. Use @maltjoy/themes design tokens such as var(--joy-color-*).

• maltjoy/no-hardcoded-rgb-colors: disallow rgb() / rgba().

Message:

Avoid hardcoded rgb/rgba colors. Use @maltjoy/themes design tokens such as var(--joy-color-*).

• maltjoy/no-hardcoded-color-names: disallow CSS color names such as red or white. transparent, inherit, and currentcolor are allowed.

Message:

Avoid hardcoded CSS color names. Use @maltjoy/themes design tokens such as var(--joy-color-*) or joy-color-* classes.

• maltjoy/no-arbitrary-font-size: disallow px / rem / em font sizes. Allows var(--joy-font-size-*), var(--joy-text-size-*), and Sass locals such as $font-size.

Message:

Avoid arbitrary font-size values. Use @maltjoy/themes tokens such as var(--joy-font-size-primary-400) or typography classes like joy-font-primary-400.

• maltjoy/no-hardcoded-hsl-colors: disallow hsl() / hwb() / oklch() (and oklab / lab / lch).

Message:

Avoid hardcoded hsl/hwb/oklch colors. Use @maltjoy/themes design tokens such as var(--joy-color-*).

• maltjoy/no-arbitrary-font-weight: disallow numeric weights such as 700. Allows var(--joy-font-weight-*), normal, and bold.

• maltjoy/no-arbitrary-font-family: disallow hardcoded families such as Verdana. Allows var(--joy-font-family-base|title) and inherit.

• maltjoy/no-arbitrary-letter-spacing: disallow px / em tracking. Allows var(--joy-font-letter-spacing-*), normal, and 0.

• maltjoy/no-arbitrary-elevation: disallow hardcoded box-shadow. Allows var(--joy-core-elevation-*), var(--joy-form-field-focus-shadow), and none.

New scale rules stay warning even with /strict until core-vue and themes are clean. Flip them to error in token-rules.js when ready.

• maltjoy/no-deprecated-token: disallow deprecated Joy aliases such as --joy-color-text-body or --joy-color-state-hover. The message includes the replacement token, for example --joy-color-text-default or --joy-color-border-hover.

• maltjoy/token-role-mismatch: disallow semantic color tokens on the wrong property. color expects --joy-color-text-* or --joy-link-*-color-*. background / background-color expect --joy-color-background-* or --joy-color-overlay. If no semantic token fits, use a primitive (--joy-color-neutral-*, --joy-color-primary-*, …). box-shadow is out of scope.

Message:

Token --joy-color-border-hover is a border role. Property color expects --joy-color-text-* or --joy-link-*-color-*. If no semantic token fits, use a primitive such as var(--joy-color-neutral-50).

Template-only rules (no-inline-style-colors, prefer-joy-color-classes) stay in @maltjoy/eslint-rules.

Override rules after the preset:

/** @type {import('stylelint').Config} */
export default {
  extends: ['@maltjoy/stylelint-config/vue'],
  rules: {
    'scss/dollar-variable-pattern': null,
  },
};