Write Rules in a Frontend Rules Repository and Check Them Before Publishing

## Before Changing a Rule, Tell Editable Source Files from Generated Ones Treat a frontend rules repository as a product made of source content, schemas, APIs, review tools, rendered pages, and generated indexes. Before changing it, identify which layer owns the behavior and inspect that layer plus its direct consumers. - Map the content package, shared types and schemas, application surfaces, tool server, and generated outputs. - Use the repository's review and rule-search tools when available instead of inventing guidance from memory. - Review inspected code before recommending fixes, and search the rules corpus before making accessibility, performance, SEO, security, privacy, internationalization, or testing claims. - Use broad audits only when the task calls for a broad audit. - Distinguish editable sources from generated artifacts and rendered projections. Derive compatibility guidance from the declared browser policy and package-backed data. Do not rely on remembered support tables or silently treat a generated view as the source of truth. ## Set the Metadata Every Rule Must Have Every rule needs a stable metadata contract that supports parsing, search, scoring, review, and rendering. Keep the required set small enough to enforce consistently. Required metadata should include: - a quoted human-readable title and a one-sentence description; - an allowed category, priority, and difficulty; - an integer effort estimate with a declared unit; - actionable prompts for checking, fixing, and explaining the rule. Useful optional metadata includes subcategory, concise takeaways, user or business impact, evidence sources, supplementary resources, related rules, tools, tags, a code-review prompt, and context for automated review. Validate categories and enums against canonical allowlists. Quote values that contain syntax-significant punctuation. Do not add fields merely because they sound useful; add them only when the parser, UI, search layer, or generator consumes them. Prompts must name the object to inspect and the expected remediation. Reject placeholders such as “check this rule” that provide no executable review strategy. ## Keep Evidence, Extra Reading, and Related-Rule Links Apart Keep authoritative evidence in structured source metadata. Keep optional reading and tools in resource metadata, and keep cross-rule navigation in related-rule metadata. Do not substitute one role for another. - Give each rule at least 2 relevant sources with 2 distinct source roles and at least 1 primary authority. - Use stable identifiers for evidence when the pipeline supports them. - Keep generic “See also” and “Reference” lines out of the body. - Link a named tool on its first meaningful mention when it materially helps and already appears in resource or tool metadata. Inline links should support a specific claim or implementation choice. A useful default is 2–5 links per rule, with 0–1 in the introduction and 1–3 across the main guidance. Keep internal rule links at 0–1 in most cases and use 2 only for unusually interconnected topics. Prefer descriptive anchor text over labels such as “read more.” Let build tooling infer fields it can derive safely, but never use inference to excuse weak or irrelevant evidence. ## In Each Rule, Put Code Examples Before Reasons and Verification Last Write each rule in a stable order so people, agents, and validators can find the same information: 1. a short plain-language introduction; 2. a realistic code example or set of examples; 3. an explanation of why the rule matters; 4. any necessary implementation guidance; 5. a final verification section. Place examples before rationale and keep verification as the final top-level section. Put optional sections such as best practices, common mistakes, framework examples, tools, thresholds, exceptions, browser support, standards, and implementation notes between them. Add exceptions only when valid caveats or false positives exist. Split verification into automated and manual checks only when both are meaningful. Add a visible standards or support note when compatibility or compliance changes the implementation decision. Prefer pass/fail instructions over generic advice. State how an engineer can verify the rule, which evidence counts, and what condition makes the check fail. ## Give Frontend Rules Measurable Pass/Fail Thresholds Use measurable thresholds whenever a rule can be tested: - performance budgets such as `LCP <= 2.5s`, `CLS <= 0.1`, or asset-size limits; - accessibility criteria such as contrast ratios, target sizes, keyboard behavior, zoom, and reflow; - SEO states such as indexability, status codes, and canonical URL behavior; - security requirements such as transport and response-header conditions. Assign priority according to consequence: reserve the highest level for site-breaking, security, or legal failures; use lower levels for degraded experience, best practices, and optional polish. Examples must be realistic enough to reveal the failure mode. Include important exceptions and support constraints, but do not add every optional section to every rule. Treat verification as part of the rule, not a later editorial task. A recommendation without a reproducible check is incomplete. ## Keep Shared UI Pieces in the Design System, Not in Each Page Put typography, icons, semantic colors, reusable components, and other cross-application concerns in a shared design system. Applications should wire framework-specific integration while consuming the shared contract. - Reuse existing components before creating page-specific variants. - Apply a shared feature to every relevant surface, not only the first page that requested it. - Keep secondary controls operable when using stretched-link card patterns. - Centralize brand icons and framework icon exports; consumers should not bypass the design-system boundary. - Prefer semantic theme tokens at full intended contrast over arbitrary opacity modifiers. - Restore list markers explicitly when a CSS reset removes them from rich text. Do not suppress server/client hydration warnings to hide a mismatch. Fix the state boundary, such as by deferring client-only state until after mount. Keep browser-originated protection on browser mutations and forms. Do not apply client-side bot checks to programmatic API endpoints that cannot complete a browser challenge. ## Connect a New Tool All the Way from Definition to Tests A new tool or cross-package feature is complete only when its definition, export, registration, dispatch, implementation, tests, and documentation agree. For a callable tool: 1. define a specific name, description, and input schema; 2. export it at the package boundary; 3. register it in the server's tool catalog; 4. connect it to the dispatch path; 5. test discovery, validation, routing, and behavior. Use package-boundary barrels only; internal barrels add navigation hops and hide ownership. Keep shared dependency versions centralized when multiple packages consume them, and organize scripts by purpose with a maintained index. Respect version-specific library contracts. For example, use the installed validator's current error shape, create stateful query clients through the repository's approved factory, and keep asynchronous configuration wrappers in an order that preserves all returned properties. Restart services after changing startup-loaded configuration. A successful edit is not evidence until the running process has loaded it. ## Run Every Check Before Publishing, Without Skipping Any Run the repository's canonical quality chain after changing a rule or its infrastructure: - validate required metadata, category values, source quality, and rule structure; - score actionable prompts, evidence, examples, body depth, verification, thresholds, and applicable conditional sections; - run formatting, linting, type checks, package checks, focused tests, and the full build required by the changed surface; - regenerate indexes or skills and confirm generated output is synchronized. Do not bypass pre-commit checks. Fix documentation, unsafe casts, complexity, import-boundary, unused-code, and coverage failures instead of using a no-verify path. Treat automated scoring as a quality gate, not proof of semantic correctness. Review the rendered result and the tool-facing result as well as the source file. Before publication, confirm that required prompts are actionable, evidence is authoritative, examples match the recommendation, verification is last, and no generated diff remains. Publish only after the complete chain passes.