Skip to content

docs: document theme cascade layers, add stylelint to frontend pre-commit (@fehmer) - #8605

Open
fehmer wants to merge 1 commit into
masterfrom
docs/theme-cascade-stylelint
Open

fehmer wants to merge 1 commit into
masterfrom
docs/theme-cascade-stylelint

Conversation

@fehmer

@fehmer fehmer commented Nov 20, 2026

Copy link
Copy Markdown
Member

Summary

  • docs/THEMES.md: new "How your CSS interacts with the core styles" section — core styles compile into @layer custom-styles (frontend/src/styles/index.scss) while theme files are unlayered, so any theme rule wins over the core regardless of specificity. Error-display rules must therefore self-guard with :not([data-ui-blind]) (worked example + the data-ui-* hooks #words/words/letters expose).
  • docs/CONTRIBUTING.md: one Theme Guidelines bullet — safe in blind mode.
  • frontend/package.json: lint-staged now runs pnpm exec stylelint on staged *.scss/css. The root lint-staged config already has this entry, but husky runs the hook from the directory git commit is invoked in, and lint-staged picks the nearest config — so commits made from frontend/ (where agents work) used the frontend config, which lacked it, and stylelint was silently skipped.
  • AGENTS.md: pointer to pnpm lint-styles.

Evidence

  • fix(test): hide error border in blind mode (@fehmer) #8603 session: an unlayered theme rule overrode the layered core blind guard; the layering relationship was written nowhere, so deriving it took most of the session. This doc is the fix for that class of confusion.
  • New pre-commit entry verified end-to-end on a scratch branch committing from frontend/: the task ran (*.{scss,css} — 1 file → pnpm exec stylelint), a formatter-unfixable violation (no-duplicate-properties) failed it and aborted the commit, and an oxfmt-fixable one (property-case) was auto-fixed before it ran. Scratch branch deleted after the test.
  • pnpm lint-styles passes on master (exit 0), so the entry adds no new failures.

Merge Danger

Two-way. Docs plus one lint-staged entry; the entry runs the same stylelint config CI already enforces, so it can only surface earlier what CI would catch.

@monkeytypegeorge monkeytypegeorge added frontend User interface or web stuff docs Related to Markdown files and documentation labels Nov 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Related to Markdown files and documentation frontend User interface or web stuff

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants