refactor(forms)!: stop auto-colouring fields on native :user-invalid/:user-valid

[jackgranatowski]

Why

Follow-up to #602 (removing the .sf-card/.sf-btn auto-shrink). An audit of the whole framework for "the component silently decides something for you" patterns turned up one more: optional/forms.css flipped --sf-field-border-color to --sf-color-danger / --sf-color-success automatically whenever the browser's own constraint validation (:user-invalid / :user-valid) fired.

That means a required or pattern-constrained field could render "broken" (red border) as soon as it was touched — before the user submitted anything, and before the app ran its own validation logic. Same category of surprise as the card/button rule: the framework overriding an element's appearance based on browser-internal state the consumer never opted into.

What

• Delete the input/select/textarea :user-invalid / :user-valid rules in optional/forms.css (13 lines).
• Unaffected: the --sf-field-border-color token itself and all its consumers (resting border, focus, autofill), and the explicit state classes in core/states.css — .sf-is-invalid / .sf-is-error, .sf-is-valid / .sf-is-success, .sf-is-warning, .sf-is-info, .sf-is-danger. These remain the one way to colour a field's validation state — add the class when your code decides the field is invalid.
• No registry/docs/demos regeneration needed: --sf-field-border-color was never declared as a :root token (pure var()-fallback hook, only ever set by the removed rule and by the state classes), so removing the automatic trigger doesn't change the public token surface at all. Confirmed: 755 tokens / registry +0/-0 before and after.
• Update stale test comments in tests/forms.spec.js that referenced the removed mechanism.
• Document the break in docs/migration.md and CHANGELOG.md.

On testing this

I did not add a Playwright assertion asserting the removal directly: :user-invalid doesn't reliably match via synthetic focus()/blur() in headless automation (verified in Chromium — it didn't even match before this change, so a test built on that trigger would be flaky by construction, not a real regression guard). The explicit path already has solid, non-flaky coverage in tests/states-full.spec.js (.sf-is-invalid/.sf-is-valid/etc. → correct --sf-field-border-color), which is untouched by this PR.

Verification

Full node --test unit suite (109/109) and all 10 CSS gates pass, confirming no token-surface drift.

Notes

• Breaking change (! commit + BREAKING CHANGE: footer); docs/migration.md updated so the migration-docs CI gate passes.
• Branch restarted from current main (includes refactor(components)!: drop the .sf-card auto-shrink of nested button labels #602) — fresh PR, isolated 4-file diff.

🤖 Generated with Claude Code

---

Generated by Claude Code

Summary by CodeRabbit

• Breaking Changes
  • Form fields no longer automatically change border color based on native browser validation states.
  • Use explicit validation classes such as .sf-is-invalid and .sf-is-valid to control field styling.
  • See the migration guide for upgrade details.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: fe4d2849-6594-4539-9748-e4ef1c3ddd3d

📥 Commits

Reviewing files that changed from the base of the PR and between d4cf4d6 and b259ce0.

📒 Files selected for processing (4)

• CHANGELOG.md
• docs/migration.md
• optional/forms.css
• tests/forms.spec.js

💤 Files with no reviewable changes (1)

• optional/forms.css

---

📝 Walkthrough

Walkthrough

The forms stylesheet no longer auto-colours fields from native :user-invalid and :user-valid states. Explicit .sf-is-* classes remain the validation colouring mechanism, with changelog, migration documentation, and test comments updated accordingly.

Changes

Form validation styling

Layer / File(s)	Summary
Explicit validation colour contract optional/forms.css, CHANGELOG.md, docs/migration.md, tests/forms.spec.js	Removed native pseudo-class border-colour overrides, documented the breaking change, and clarified that explicit validation state classes continue to drive --sf-field-border-color.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• codeslash-dev/SLASHED#55: Previously wired forms border and validation-state integration around --sf-field-border-color.
• codeslash-dev/SLASHED#234: Added the native :user-invalid / :user-valid styling that this change removes.

Suggested labels: codex

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the breaking change to stop native validation states from auto-colouring form fields.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/button-size-visibility-issue-40xlwy

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR removes the :user-invalid / :user-valid auto-coloring rules from optional/forms.css, eliminating a "surprise" UX pattern where constrained fields would show a red or green border the instant they were touched — before any app-level validation ran. After this change, --sf-field-border-color is only set via the explicit .sf-is-invalid / .sf-is-valid (and related) state classes in core/states.css.

• optional/forms.css: 13 lines of :user-invalid/:user-valid rules deleted; the --sf-field-border-color token and all its other consumers (resting border, focus, autofill) are untouched.
• tests/forms.spec.js: Two stale comments updated to point to core/states.css and the explicit state classes; no test logic changed.
• CHANGELOG.md / docs/migration.md: Breaking change documented with a clear upgrade path using the explicit .sf-is-invalid class and aria-invalid pattern.

Confidence Score: 5/5

Safe to merge — a clean, targeted deletion of 13 CSS lines with no effect on the remaining token surface, consumers, or test logic.

The CSS removal is minimal and surgical: only the two :user-invalid/:user-valid rule blocks are gone, every other use of --sf-field-border-color (resting border, focus, autofill) is untouched. A repo-wide search confirms no stale references to the removed pseudo-classes remain outside the new migration guide and changelog entry. The llm-guide description for --sf-field-border-color remains accurate because the explicit state classes still set it. Test comments are updated to match; no test logic is changed. Breaking-change documentation is complete and accurate.

No files require special attention.

Important Files Changed

Filename	Overview
optional/forms.css	Removes 13 lines of :user-invalid/:user-valid auto-coloring rules; remaining CSS is unaffected and still consumes --sf-field-border-color via the explicit var() fallback chain
tests/forms.spec.js	Updates two inline comments to reference the explicit .sf-is-invalid/.sf-is-valid state classes instead of the removed :user-invalid/:user-valid pseudo-classes; test logic is unchanged
docs/migration.md	Adds a clear migration guide section explaining the breaking change, what was removed, what remains, and an upgrade example — accurate and complete
CHANGELOG.md	Adds breaking change entry for the forms auto-coloring removal under the Unreleased section, consistent in style with the sibling components entry above it

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User interacts with field] --> B{Validation trigger}

    B -->|BEFORE this PR| C[Browser fires :user-invalid / :user-valid]
    C --> D[forms.css auto-sets --sf-field-border-color to danger / success]
    D --> E[Field border changes immediately on first touch]

    B -->|AFTER this PR| F[Browser fires :user-invalid / :user-valid]
    F --> G[No CSS rule matches — border unchanged]

    B --> H[App adds .sf-is-invalid / .sf-is-valid]
    H --> I[core/states.css sets --sf-field-border-color]
    I --> J[Field border changes on app's own terms]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[User interacts with field] --> B{Validation trigger}

    B -->|BEFORE this PR| C[Browser fires :user-invalid / :user-valid]
    C --> D[forms.css auto-sets --sf-field-border-color to danger / success]
    D --> E[Field border changes immediately on first touch]

    B -->|AFTER this PR| F[Browser fires :user-invalid / :user-valid]
    F --> G[No CSS rule matches — border unchanged]

    B --> H[App adds .sf-is-invalid / .sf-is-valid]
    H --> I[core/states.css sets --sf-field-border-color]
    I --> J[Field border changes on app's own terms]

Loading

_{Reviews (1): Last reviewed commit: "refactor(forms)!: stop auto-colouring fi..." | Re-trigger Greptile}