Copilot instructions

1---
2applyTo: "**/*.{ts,tsx,js,jsx}"
3---
4 
5# Project Context
6 
7Ultracite enforces strict type safety, accessibility standards, and consistent code quality for JavaScript/TypeScript projects using Biome's lightning-fast formatter and linter.
8 
9## Key Principles
10 
11- Zero configuration required
12- Subsecond performance
13- Maximum type safety
14- AI-friendly code generation
15 
16## Before Writing Code
17 
181. Analyze existing patterns in the codebase
192. Consider edge cases and error scenarios
203. Follow the rules below strictly
214. Validate accessibility requirements
22 
23## Rules
24 
25### Accessibility (a11y)
26 
27- Don't use `accessKey` attribute on any HTML element.
28- Don't set `aria-hidden="true"` on focusable elements.
29- Don't add ARIA roles, states, and properties to elements that don't support them.
30- Don't use distracting elements like `<marquee>` or `<blink>`.
31- Only use the `scope` prop on `<th>` elements.
32- Don't assign non-interactive ARIA roles to interactive HTML elements.
33- Make sure label elements have text content and are associated with an input.
34- Don't assign interactive ARIA roles to non-interactive HTML elements.
35- Don't assign `tabIndex` to non-interactive HTML elements.
36- Don't use positive integers for `tabIndex` property.
37- Don't include "image", "picture", or "photo" in img alt prop.
38- Don't use explicit role property that's the same as the implicit/default role.
39- Make static elements with click handlers use a valid role attribute.
40- Always include a `title` element for SVG elements.
41- Give all elements requiring alt text meaningful information for screen readers.
42- Make sure anchors have content that's accessible to screen readers.
43- Assign `tabIndex` to non-interactive HTML elements with `aria-activedescendant`.
44- Include all required ARIA attributes for elements with ARIA roles.
45- Make sure ARIA properties are valid for the element's supported roles.
46- Always include a `type` attribute for button elements.
47- Make elements with interactive roles and handlers focusable.
48- Give heading elements content that's accessible to screen readers (not hidden with `aria-hidden`).
49- Always include a `lang` attribute on the html element.
50- Always include a `title` attribute for iframe elements.
51- Accompany `onClick` with at least one of: `onKeyUp`, `onKeyDown`, or `onKeyPress`.
52- Accompany `onMouseOver`/`onMouseOut` with `onFocus`/`onBlur`.
53- Include caption tracks for audio and video elements.
54- Use semantic elements instead of role attributes in JSX.
55- Make sure all anchors are valid and navigable.
56- Ensure all ARIA properties (`aria-*`) are valid.
57- Use valid, non-abstract ARIA roles for elements with ARIA roles.
58- Use valid ARIA state and property values.
59- Use valid values for the `autocomplete` attribute on input elements.
60- Use correct ISO language/country codes for the `lang` attribute.
61 
62### Code Complexity and Quality
63 
64- Don't use consecutive spaces in regular expression literals.
65- Don't use the `arguments` object.
66- Don't use primitive type aliases or misleading types.
67- Don't use the comma operator.
68- Don't use empty type parameters in type aliases and interfaces.
69- Don't write functions that exceed a given Cognitive Complexity score.
70- Don't nest describe() blocks too deeply in test files.
71- Don't use unnecessary boolean casts.
72- Don't use unnecessary callbacks with flatMap.
73- Use for...of statements instead of Array.forEach.
74- Don't create classes that only have static members (like a static namespace).
75- Don't use this and super in static contexts.
76- Don't use unnecessary catch clauses.
77- Don't use unnecessary constructors.
78- Don't use unnecessary continue statements.
79- Don't export empty modules that don't change anything.
80- Don't use unnecessary escape sequences in regular expression literals.
81- Don't use unnecessary fragments.
82- Don't use unnecessary labels.
83- Don't use unnecessary nested block statements.
84- Don't rename imports, exports, and destructured assignments to the same name.
85- Don't use unnecessary string or template literal concatenation.
86- Don't use String.raw in template literals when there are no escape sequences.
87- Don't use useless case statements in switch statements.
88- Don't use ternary operators when simpler alternatives exist.
89- Don't use useless `this` aliasing.
90- Don't use any or unknown as type constraints.
91- Don't initialize variables to undefined.
92- Don't use the void operators (they're not familiar).
93- Use arrow functions instead of function expressions.
94- Use Date.now() to get milliseconds since the Unix Epoch.
95- Use .flatMap() instead of map().flat() when possible.
96- Use literal property access instead of computed property access.
97- Don't use parseInt() or Number.parseInt() when binary, octal, or hexadecimal literals work.
98- Use concise optional chaining instead of chained logical expressions.
99- Use regular expression literals instead of the RegExp constructor when possible.
100- Don't use number literal object member names that aren't base 10 or use underscore separators.
101- Remove redundant terms from logical expressions.
102- Use while loops instead of for loops when you don't need initializer and update expressions.
103- Don't pass children as props.
104- Don't reassign const variables.
105- Don't use constant expressions in conditions.
106- Don't use `Math.min` and `Math.max` to clamp values when the result is constant.
107- Don't return a value from a constructor.
108- Don't use empty character classes in regular expression literals.
109- Don't use empty destructuring patterns.
110- Don't call global object properties as functions.
111- Don't declare functions and vars that are accessible outside their block.
112- Make sure builtins are correctly instantiated.
113- Don't use super() incorrectly inside classes. Also check that super() is called in classes that extend other constructors.
114- Don't use variables and function parameters before they're declared.
115- Don't use 8 and 9 escape sequences in string literals.
116- Don't use literal numbers that lose precision.
117 
118### React and JSX Best Practices
119 
120- Don't use the return value of React.render.
121- Make sure all dependencies are correctly specified in React hooks.
122- Make sure all React hooks are called from the top level of component functions.
123- Don't forget key props in iterators and collection literals.
124- Don't destructure props inside JSX components in Solid projects.
125- Don't define React components inside other components.
126- Don't use event handlers on non-interactive elements.
127- Don't assign to React component props.
128- Don't use both `children` and `dangerouslySetInnerHTML` props on the same element.
129- Don't use dangerous JSX props.
130- Don't use Array index in keys.
131- Don't insert comments as text nodes.
132- Don't assign JSX properties multiple times.
133- Don't add extra closing tags for components without children.
134- Use `<>...</>` instead of `<Fragment>...</Fragment>`.
135- Watch out for possible "wrong" semicolons inside JSX elements.
136 
137### Correctness and Safety
138 
139- Don't assign a value to itself.
140- Don't return a value from a setter.
141- Don't compare expressions that modify string case with non-compliant values.
142- Don't use lexical declarations in switch clauses.
143- Don't use variables that haven't been declared in the document.
144- Don't write unreachable code.
145- Make sure super() is called exactly once on every code path in a class constructor before this is accessed if the class has a superclass.
146- Don't use control flow statements in finally blocks.
147- Don't use optional chaining where undefined values aren't allowed.
148- Don't have unused function parameters.
149- Don't have unused imports.
150- Don't have unused labels.
151- Don't have unused private class members.
152- Don't have unused variables.
153- Make sure void (self-closing) elements don't have children.
154- Don't return a value from a function with the return type 'void'
155- Use isNaN() when checking for NaN.
156- Make sure "for" loop update clauses move the counter in the right direction.
157- Make sure typeof expressions are compared to valid values.
158- Make sure generator functions contain yield.
159- Don't use await inside loops.
160- Don't use bitwise operators.
161- Don't use expressions where the operation doesn't change the value.
162- Make sure Promise-like statements are handled appropriately.
163- Don't use **dirname and **filename in the global scope.
164- Prevent import cycles.
165- Don't use configured elements.
166- Don't hardcode sensitive data like API keys and tokens.
167- Don't let variable declarations shadow variables from outer scopes.
168- Don't use the TypeScript directive @ts-ignore.
169- Prevent duplicate polyfills from Polyfill.io.
170- Don't use useless backreferences in regular expressions that always match empty strings.
171- Don't use unnecessary escapes in string literals.
172- Don't use useless undefined.
173- Make sure getters and setters for the same property are next to each other in class and object definitions.
174- Make sure object literals are declared consistently (defaults to explicit definitions).
175- Use static Response methods instead of new Response() constructor when possible.
176- Make sure switch-case statements are exhaustive.
177- Make sure the `preconnect` attribute is used when using Google Fonts.
178- Use `Array#{indexOf,lastIndexOf}()` instead of `Array#{findIndex,findLastIndex}()` when looking for the index of an item.
179- Make sure iterable callbacks return consistent values.
180- Use `with { type: "json" }` for JSON module imports.
181- Use numeric separators in numeric literals.
182- Use object spread instead of `Object.assign()` when constructing new objects.
183- Always use the radix argument when using `parseInt()`.
184- Make sure JSDoc comment lines start with a single asterisk, except for the first one.
185- Include a description parameter for `Symbol()`.
186- Don't use spread (`...`) syntax on accumulators.
187- Don't use the `delete` operator.
188- Don't access namespace imports dynamically.
189- Don't use namespace imports.
190- Declare regex literals at the top level.
191- Don't use `target="_blank"` without `rel="noopener"`.
192 
193### TypeScript Best Practices
194 
195- Don't use TypeScript enums.
196- Don't export imported variables.
197- Don't add type annotations to variables, parameters, and class properties that are initialized with literal expressions.
198- Don't use TypeScript namespaces.
199- Don't use non-null assertions with the `!` postfix operator.
200- Don't use parameter properties in class constructors.
201- Don't use user-defined types.
202- Use `as const` instead of literal types and type annotations.
203- Use either `T[]` or `Array<T>` consistently.
204- Initialize each enum member value explicitly.
205- Use `export type` for types.
206- Use `import type` for types.
207- Make sure all enum members are literal values.
208- Don't use TypeScript const enum.
209- Don't declare empty interfaces.
210- Don't let variables evolve into any type through reassignments.
211- Don't use the any type.
212- Don't misuse the non-null assertion operator (!) in TypeScript files.
213- Don't use implicit any type on variable declarations.
214- Don't merge interfaces and classes unsafely.
215- Don't use overload signatures that aren't next to each other.
216- Use the namespace keyword instead of the module keyword to declare TypeScript namespaces.
217 
218### Style and Consistency
219 
220- Don't use global `eval()`.
221- Don't use callbacks in asynchronous tests and hooks.
222- Don't use negation in `if` statements that have `else` clauses.
223- Don't use nested ternary expressions.
224- Don't reassign function parameters.
225- This rule lets you specify global variable names you don't want to use in your application.
226- Don't use specified modules when loaded by import or require.
227- Don't use constants whose value is the upper-case version of their name.
228- Use `String.slice()` instead of `String.substr()` and `String.substring()`.
229- Don't use template literals if you don't need interpolation or special-character handling.
230- Don't use `else` blocks when the `if` block breaks early.
231- Don't use yoda expressions.
232- Don't use Array constructors.
233- Use `at()` instead of integer index access.
234- Follow curly brace conventions.
235- Use `else if` instead of nested `if` statements in `else` clauses.
236- Use single `if` statements instead of nested `if` clauses.
237- Use `new` for all builtins except `String`, `Number`, and `Boolean`.
238- Use consistent accessibility modifiers on class properties and methods.
239- Use `const` declarations for variables that are only assigned once.
240- Put default function parameters and optional function parameters last.
241- Include a `default` clause in switch statements.
242- Use the `**` operator instead of `Math.pow`.
243- Use `for-of` loops when you need the index to extract an item from the iterated array.
244- Use `node:assert/strict` over `node:assert`.
245- Use the `node:` protocol for Node.js builtin modules.
246- Use Number properties instead of global ones.
247- Use assignment operator shorthand where possible.
248- Use function types instead of object types with call signatures.
249- Use template literals over string concatenation.
250- Use `new` when throwing an error.
251- Don't throw non-Error values.
252- Use `String.trimStart()` and `String.trimEnd()` over `String.trimLeft()` and `String.trimRight()`.
253- Use standard constants instead of approximated literals.
254- Don't assign values in expressions.
255- Don't use async functions as Promise executors.
256- Don't reassign exceptions in catch clauses.
257- Don't reassign class members.
258- Don't compare against -0.
259- Don't use labeled statements that aren't loops.
260- Don't use void type outside of generic or return types.
261- Don't use console.
262- Don't use control characters and escape sequences that match control characters in regular expression literals.
263- Don't use debugger.
264- Don't assign directly to document.cookie.
265- Use `===` and `!==`.
266- Don't use duplicate case labels.
267- Don't use duplicate class members.
268- Don't use duplicate conditions in if-else-if chains.
269- Don't use two keys with the same name inside objects.
270- Don't use duplicate function parameter names.
271- Don't have duplicate hooks in describe blocks.
272- Don't use empty block statements and static blocks.
273- Don't let switch clauses fall through.
274- Don't reassign function declarations.
275- Don't allow assignments to native objects and read-only global variables.
276- Use Number.isFinite instead of global isFinite.
277- Use Number.isNaN instead of global isNaN.
278- Don't assign to imported bindings.
279- Don't use irregular whitespace characters.
280- Don't use labels that share a name with a variable.
281- Don't use characters made with multiple code points in character class syntax.
282- Make sure to use new and constructor properly.
283- Don't use shorthand assign when the variable appears on both sides.
284- Don't use octal escape sequences in string literals.
285- Don't use Object.prototype builtins directly.
286- Don't redeclare variables, functions, classes, and types in the same scope.
287- Don't have redundant "use strict".
288- Don't compare things where both sides are exactly the same.
289- Don't let identifiers shadow restricted names.
290- Don't use sparse arrays (arrays with holes).
291- Don't use template literal placeholder syntax in regular strings.
292- Don't use the then property.
293- Don't use unsafe negation.
294- Don't use var.
295- Don't use with statements in non-strict contexts.
296- Make sure async functions actually use await.
297- Make sure default clauses in switch statements come last.
298- Make sure to pass a message value when creating a built-in error.
299- Make sure get methods always return a value.
300- Use a recommended display strategy with Google Fonts.
301- Make sure for-in loops include an if statement.
302- Use Array.isArray() instead of instanceof Array.
303- Make sure to use the digits argument with Number#toFixed().
304- Make sure to use the "use strict" directive in script files.
305 
306### Next.js Specific Rules
307 
308- Don't use `<img>` elements in Next.js projects.
309- Don't use `<head>` elements in Next.js projects.
310- Don't import next/document outside of pages/\_document.jsx in Next.js projects.
311- Don't use the next/head module in pages/\_document.js on Next.js projects.
312 
313### Testing Best Practices
314 
315- Don't use export or module.exports in test files.
316- Don't use focused tests.
317- Make sure the assertion function, like expect, is placed inside an it() function call.
318- Don't use disabled tests.
319 
320## Common Tasks
321 
322- `npx ultracite init` - Initialize Ultracite in your project
323- `npx ultracite format` - Format and fix code automatically
324- `npx ultracite lint` - Check for issues without fixing
325 
326## Example: Error Handling
327 
328```typescript
329// ✅ Good: Comprehensive error handling
330try {
331  const result = await fetchData();
332  return { success: true, data: result };
333} catch (error) {
334  console.error("API call failed:", error);
335  return { success: false, error: error.message };
336}
337 
338// ❌ Bad: Swallowing errors
339try {
340  return await fetchData();
341} catch (e) {
342  console.log(e);
343}
344```
345