diagnose-errors

name

diagnose-errors

description

Diagnostic workflow for build, lint, CI, and test errors in OUDS Web. Use this skill when encountering any error — Stylelint violations (border-radius, border:none, !default), ESLint failures (semicolons, console), Sass build errors (undefined variables, missing imports), CI job failures, JS test failures, or Pa11y accessibility violations. Provides a decision tree to identify the error category and step-by-step fix instructions.

Workflow: Diagnose Errors

Decision tree

Error signal	Category	Fix
Unexpected property "border-radius"	Stylelint	Use @include border-radius()
Unexpected value "none" for "border"	Stylelint	Use border: 0
Expected variable to have default	Stylelint	Add !default
/* stylelint */ in CSS output	Comment leak	Use // not /* */
Extra semicolon	ESLint	Remove ;
Trailing comma	ESLint	Remove trailing ,
Unexpected console statement	ESLint	Remove from js/src/
Can't find stylesheet to import	Sass build	Run npm install, check @ouds/web-common/scss/ path
Undefined variable "$ouds-..."	Token error	Check brand _component.scss/_semantic.scss, verify import order
AssertionError	JS test	Check changed ARIA attrs or class names
Violation: (URL + rule)	Pa11y	Missing role/aria-*, contrast, focus

---

Stylelint fixes

Forbidden properties → use mixins

// ✗ → ✓
border-radius: 4px        → @include border-radius($ouds-border-radius-default)
transition: X             → @include transition(X)
border-top-left-radius: X → @include border-top-start-radius($val)

lighten()/darken() → use token variant

Stylelint comment leaking → use // comments

// stylelint-disable property-disallowed-list
border-radius: 0;
// stylelint-enable property-disallowed-list

---

Token errors

1. Search variable in packages/<brand>/scss/tokens/_component.scss and _semantic.scss
2. If absent → add to _composite.scss (only hand-editable file)
3. Verify import order: _raw → _semantic → _semantic-colors-custom-props → _composite → _component-colors-custom-props → _component

---

ESLint fixes

Error	Fix
Extra semicolon	Remove ;
Trailing comma	Remove ,
Console statement	Remove from js/src/
String concatenation	Use template literal
Missing extension	Add .js to import

---

Validation

npm run lint       # All rules pass
npm run dist       # Build succeeds
npm run js-test    # Tests pass

Stale cache

rm -rf node_modules && npm install
npm run clean && npm run dist