docs(rules): correct what the unit suite can see, and name the dead-shorthand trap - #888
Merged
Merged
Conversation
…horthand trap testing.md claimed `setup.ts` imports `@aziontech/theme/globals.css` and that a styled DOM makes axe contrast real. The opposite is true, deliberately: the file loads no CSS and says why, because the env runs no Tailwind. Anyone trusting the rule would write a contrast or computed-style assertion that silently proves nothing — the precise false positive browser mode exists to eliminate. So the CSS boundary is now stated where it matters: never assert a computed style (unstyled DOM returns the same value whether the style is right or absent), axe covers semantics not pixels, and contrast lives in Storybook plus the visual gate. The stack list now describes what `setup.ts` actually does. styling.md gains the malformed-shorthand trap: whitespace inside the parens emits nothing, an inverted bracket/paren form emits a value the browser discards, and a visual baseline generated from the broken render encodes the bug as correct. Both spellings shipped — chip's fill and popover-header's min-height — so the section names the `dead-token-shorthand` check that now blocks them, and points at probing the class rather than the cascade. Only the sections touched are reformatted; styling.md predates the current prettier config and is left otherwise as found.
herbert-julio-azion
approved these changes
Aug 12, 2026
isaque-bock-azion
approved these changes
Aug 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
testing.mdclaimedsetup.tsimports@aziontech/theme/globals.cssand that "styled DOM ⇒ axe contrast is real". The file loads no CSS, deliberately, because the env runs no Tailwind — so the rule was steering authors toward contrast and computed-style assertions that silently prove nothing. The CSS boundary is now stated: never assert a computed style, axe covers semantics not pixels, contrast lives in Storybook + the visual gate.styling.mdgains the malformed-shorthand trap — whitespace inside the parens emits nothing; an inverted[--(token)]emits a value the browser discards; a visual baseline generated from the broken render encodes the bug as correct. Names thedead-token-shorthandcheck that blocks it (fix(webkit): catch malformed token shorthands, and restore the popover header min-height #887) and the probe-the-class habit.How to test
.claude/rules/testing.md§ "What a real browser does NOT give this suite: CSS" againstpackages/webkit/src/test/setup.ts— the rule now matches the file's own comment, including why re-adding the CSS would buy no signal.npx prettier --check .claude/rules/testing.md→ passes.styling.mdpredates the current prettier config and still fails onmain; it is left otherwise as found so the diff stays reviewable.cd packages/webkit && node --test test/standards/invariant.test.mjs→ 12 pass (rule ↔ gate pairing intact), andnode scripts/check-authoring-docs.mjs→0 new.Notes
docsdoes not bump).styling.mdreferences thedead-token-shorthandcheck added in fix(webkit): catch malformed token shorthands, and restore the popover header min-height #887; land that one first (or together) so the doc does not name a checkmainlacks.