|
1 | | -# Ultracite Code Standards |
| 1 | +# Marx |
2 | 2 |
|
3 | | -This project uses **Ultracite**, a zero-config preset that enforces strict code quality standards through automated formatting and linting. |
4 | | - |
5 | | -## Quick Reference |
6 | | - |
7 | | -- **Format code**: `npm exec -- ultracite fix` |
8 | | -- **Check for issues**: `npm exec -- ultracite check` |
9 | | -- **Diagnose setup**: `npm exec -- ultracite doctor` |
10 | | - |
11 | | -Biome (the underlying engine) provides robust linting and formatting. Most issues are automatically fixable. |
12 | | - |
13 | | ---- |
14 | | - |
15 | | -## Core Principles |
16 | | - |
17 | | -Write code that is **accessible, performant, type-safe, and maintainable**. Focus on clarity and explicit intent over brevity. |
18 | | - |
19 | | -### Type Safety & Explicitness |
20 | | - |
21 | | -- Use explicit types for function parameters and return values when they enhance clarity |
22 | | -- Prefer `unknown` over `any` when the type is genuinely unknown |
23 | | -- Use const assertions (`as const`) for immutable values and literal types |
24 | | -- Leverage TypeScript's type narrowing instead of type assertions |
25 | | -- Use meaningful variable names instead of magic numbers - extract constants with descriptive names |
26 | | - |
27 | | -### Modern JavaScript/TypeScript |
28 | | - |
29 | | -- Use arrow functions for callbacks and short functions |
30 | | -- Prefer `for...of` loops over `.forEach()` and indexed `for` loops |
31 | | -- Use optional chaining (`?.`) and nullish coalescing (`??`) for safer property access |
32 | | -- Prefer template literals over string concatenation |
33 | | -- Use destructuring for object and array assignments |
34 | | -- Use `const` by default, `let` only when reassignment is needed, never `var` |
35 | | - |
36 | | -### Async & Promises |
37 | | - |
38 | | -- Always `await` promises in async functions - don't forget to use the return value |
39 | | -- Use `async/await` syntax instead of promise chains for better readability |
40 | | -- Handle errors appropriately in async code with try-catch blocks |
41 | | -- Don't use async functions as Promise executors |
42 | | - |
43 | | -### React & JSX |
44 | | - |
45 | | -- Use function components over class components |
46 | | -- Call hooks at the top level only, never conditionally |
47 | | -- Specify all dependencies in hook dependency arrays correctly |
48 | | -- Use the `key` prop for elements in iterables (prefer unique IDs over array indices) |
49 | | -- Nest children between opening and closing tags instead of passing as props |
50 | | -- Don't define components inside other components |
51 | | -- Use semantic HTML and ARIA attributes for accessibility: |
52 | | - - Provide meaningful alt text for images |
53 | | - - Use proper heading hierarchy |
54 | | - - Add labels for form inputs |
55 | | - - Include keyboard event handlers alongside mouse events |
56 | | - - Use semantic elements (`<button>`, `<nav>`, etc.) instead of divs with roles |
57 | | - |
58 | | -### Error Handling & Debugging |
59 | | - |
60 | | -- Remove `console.log`, `debugger`, and `alert` statements from production code |
61 | | -- Throw `Error` objects with descriptive messages, not strings or other values |
62 | | -- Use `try-catch` blocks meaningfully - don't catch errors just to rethrow them |
63 | | -- Prefer early returns over nested conditionals for error cases |
64 | | - |
65 | | -### Code Organization |
66 | | - |
67 | | -- Keep functions focused and under reasonable cognitive complexity limits |
68 | | -- Extract complex conditions into well-named boolean variables |
69 | | -- Use early returns to reduce nesting |
70 | | -- Prefer simple conditionals over nested ternary operators |
71 | | -- Group related code together and separate concerns |
72 | | - |
73 | | -### Security |
74 | | - |
75 | | -- Add `rel="noopener"` when using `target="_blank"` on links |
76 | | -- Avoid `dangerouslySetInnerHTML` unless absolutely necessary |
77 | | -- Don't use `eval()` or assign directly to `document.cookie` |
78 | | -- Validate and sanitize user input |
79 | | - |
80 | | -### Performance |
81 | | - |
82 | | -- Avoid spread syntax in accumulators within loops |
83 | | -- Use top-level regex literals instead of creating them in loops |
84 | | -- Prefer specific imports over namespace imports |
85 | | -- Avoid barrel files (index files that re-export everything) |
86 | | -- Use proper image components (e.g., Next.js `<Image>`) over `<img>` tags |
87 | | - |
88 | | -### Framework-Specific Guidance |
89 | | - |
90 | | -**Next.js:** |
91 | | -- Use Next.js `<Image>` component for images |
92 | | -- Use `next/head` or App Router metadata API for head elements |
93 | | -- Use Server Components for async data fetching instead of async Client Components |
94 | | - |
95 | | -**React 19+:** |
96 | | -- Use ref as a prop instead of `React.forwardRef` |
97 | | - |
98 | | -**Solid/Svelte/Vue/Qwik:** |
99 | | -- Use `class` and `for` attributes (not `className` or `htmlFor`) |
100 | | - |
101 | | ---- |
102 | | - |
103 | | -## Testing |
104 | | - |
105 | | -- Write assertions inside `it()` or `test()` blocks |
106 | | -- Avoid done callbacks in async tests - use async/await instead |
107 | | -- Don't use `.only` or `.skip` in committed code |
108 | | -- Keep test suites reasonably flat - avoid excessive `describe` nesting |
109 | | - |
110 | | -## When Biome Can't Help |
111 | | - |
112 | | -Biome's linter will catch most issues automatically. Focus your attention on: |
113 | | - |
114 | | -1. **Business logic correctness** - Biome can't validate your algorithms |
115 | | -2. **Meaningful naming** - Use descriptive names for functions, variables, and types |
116 | | -3. **Architecture decisions** - Component structure, data flow, and API design |
117 | | -4. **Edge cases** - Handle boundary conditions and error states |
118 | | -5. **User experience** - Accessibility, performance, and usability considerations |
119 | | -6. **Documentation** - Add comments for complex logic, but prefer self-documenting code |
120 | | - |
121 | | ---- |
122 | | - |
123 | | -Most formatting and common issues are automatically fixed by Biome. Run `npm exec -- ultracite fix` before committing to ensure compliance. |
| 3 | +See [AGENTS.md](../AGENTS.md) for everything: what Marx is, commands, CSS architecture conventions, and the release flow. |
0 commit comments