[gethinwebster]

AI coding assistants are great at producing working code, but in this repo they tend to drift from our undocumented team conventions: how components are structured, how props flow through index/internal/interfaces, the voice of our API docs, not breaking the public API. This risks coming up in review again and again. It can be mitigated to some extent by AGENTS.md, but this can often end up getting ignored.

This PR makes an attempt to crystallize some of those rules, and give them as additional context to copilot as a more reliable way of ensuring the rules are followed.

What's here

• .github/copilot-instructions.md — the repo-wide stuff: comment discipline, reuse and preferring one shared implementation over parallel ones, types over runtime checks, naming, i18n, keeping PRs focused, and treating the public API as a contract we don't break lightly.
• .github/instructions/*.instructions.md — the per-area detail, applied automatically by tools that understand these files:
  • component-structure — the index/internal/interfaces split and the public↔internal contract (forwardRef⇔Ref, getBaseProps, __internalRootRef, __-prefixed internals), public-API compatibility, interface typing, and doc voice & tone.
  • plus tests, styles, dev-pages, and test-utils.
• A small AGENTS.md tweak — it now points at these files, and I corrected the title note to say “PR titles only” (we don't actually check individual commit messages, since they're squashed away).

How do we know it helps?

• Does it catch the things we actually comment on? Took ~30 recent merged PRs, showed the rules to a dry-run review agent, and compared what it flagged against what our human reviewers had said. It re-surfaced roughly three-quarters of the convention-type feedback we'd given — the structural, naming, reuse, dev-page and doc-style points — and it did that without inventing problems that weren't there.
• Does it nag about code that's already fine? I also pointed it at a set of existing, already-merged components. On code that already follows our conventions it stayed quiet — no false alarms on the core structural rules — which is the important half: a checker that cries wolf gets muted fast.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.69%. Comparing base (839ce39) to head (6aff0f9).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5047   +/-   ##
=======================================
  Coverage   97.69%   97.69%           
=======================================
  Files         966      966           
  Lines       31575    31575           
  Branches    11669    11669           
=======================================
  Hits        30846    30846           
  Misses        722      722           
  Partials        7        7           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Copilot review overview

🟡 Changes recommended

Some instructions exclude relevant implementation files or inaccurately describe established architectural and styling patterns.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 2

Open (3)

• Include implementation.tsx and internal-interfaces.ts in scope · New
• Correct inaccurate widgetized component guidance and examples · New
• Allow documented exceptions for necessary SCSS selectors · New

What changed in this PR

Adds coding-convention guidance for AI assistants and contributors.

Changes:

• Defines repository-wide engineering conventions.
• Adds scoped guidance for components, tests, styles, dev pages, and test utilities.
• Updates AGENTS.md references and PR-title guidance.

File	Description
AGENTS.md	Links convention files and clarifies title checks.
.github/​copilot-instructions.md	Defines repository-wide conventions.
.github/​instructions/​component-structure.instructions.md	Documents component architecture and API conventions.
.github/​instructions/​tests.instructions.md	Defines testing conventions.
.github/​instructions/​test-utils.instructions.md	Defines test-utils contract conventions.
.github/​instructions/​styles.instructions.md	Defines SCSS conventions.
.github/​instructions/​dev-pages.instructions.md	Defines demo-page conventions.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟢 Approval recommended

The documentation-only changes are coherent, correctly scoped, and consistently linked.

Review effort: Balanced
Findings: None

Resolved since last review (3)

• Include implementation.tsx and internal-interfaces.ts in scope
• Allow documented exceptions for necessary SCSS selectors
• Correct inaccurate widgetized component guidance and examples

[NathanZlion]

nit: After the copyright/liscense header?