Configuration: traceless-style.config.js

Optional file at the project root. CommonJS only — traceless-style.config.js, not .mjs or .ts.

Full shape

// traceless-style.config.js
module.exports = {
  /* Source roots to scan. Default: union of `src/` and `app/` if either exists. */
  srcDir: "src",                            // string or string[]

  /* Lint configuration. Default: all rules ON (strict). */
  lint: {
    noInlineStyles: true,                   // cannot be disabled fully
    noClassString:  true,
    noCSSModules:   true,
    noTailwind:     true,
    ignore:         ["**/__tests__/**"],
  },
  // …or `lint: false` to disable noClassString/noCSSModules/noTailwind
  //   (noInlineStyles stays on).

  /* Auto dark-mode derivation. Default: true. */
  autoDarkMode: true,

  /* Auto RTL physical → logical rewriting. Default: true. */
  autoRtl: true,

  /* WCAG contrast validation. Default: AA enforced, strict by default
     (build fails on errors). Set strict: false to demote to warnings. */
  contrast: {
    level:               "AA",          // "AA" | "AAA" | "off"
    strict:              true,          // AA failures → build errors (default true)
    strictAAA:           false,         // AAA failures → build errors
    surfaceLight:        "#fafafa",
    surfaceDark:         "#0a0a0f",
    largeTextSize:       18,            // px threshold for "large text"
    auditUiComponents:   true,          // §1.4.11 — borders, caret, accent, etc.
    auditPlaceholder:    true,          // §1.4.3 for &::placeholder selectors
    gradientSampleCount: 5,             // midpoints between adjacent gradient stops
    suggestionSpace:     "oklch",       // "oklch" | "hsl" — fix-color search space
    auditPeerSurfaces:   false,         // opt-in: cross-validate against sibling bgs
  },

  /* Custom variants — also detected from `tl.extend({ variants })` calls.
     Putting them here is optional; useful when you want them centralized. */
  variants: {
    _tablet: "@media (min-width: 900px)",
  },
};

Key reference

srcDir: string | string[]

Source root(s) to scan. If unset, the CLI scans both src/ and app/ (whichever exist) plus the project root as a final fallback.

lint

See Linting for the full rule list.

autoDarkMode: boolean

When true (default), the compiler derives a dark-mode variant of every color value in your styles. See Dark mode. Disable via _autoDark: false per group, or globally with autoDarkMode: false.

autoRtl: boolean

When true (default), the compiler rewrites physical CSS properties (marginLeft, paddingRight, etc.) to their logical equivalents. See RTL. Disable per group with _autoRtl: false.

contrast

WCAG 2.1 + 2.2 audit settings. The full feature set is documented in WCAG contrast validation.

variants

Optional pre-registered custom variants. Same format as tl.extend({ variants: ... }). Most projects prefer the tl.extend form (variant definitions colocated with code).

Environment variables

Loading order

The CLI (src/cli/extract.ts) loads config in this order:

1. Resolve traceless-style.config.js from process.cwd().
2. If it exists, require() it (with cache-busted re-read for watch mode).
3. Apply srcDir → CLI SRC_DIRS.
4. Apply lint → CLI lint runner.
5. Apply autoDarkMode → setAutoDarkMode(false) if false.
6. Apply contrast → setContrastOptions(cfg.contrast).

If the config file is missing or malformed, defaults are used silently.

ESM project notes

If your project uses "type": "module" in package.json, name the config explicitly:

• ✅ traceless-style.config.cjs (CommonJS)
• ❌ traceless-style.config.mjs (not currently supported — require() cannot load ESM)
• ❌ traceless-style.config.ts (not currently supported)

The CLI uses Node's require() to load the config — see createRequire(import.meta.url) in src/cli/extract.ts.

See also

• CLI
• Linting
• Dark mode
• WCAG contrast validation