phantomknight287/saturn

public

The operating system for your freelance business.

feat: here comes the money442302e7 months ago119 lines · 4.7 KB

1	# Ultracite Code Standards
2
3	## Core Principles
4
5	Write code that is accessible, performant, type-safe, and maintainable. Focus on clarity and explicit intent over brevity.
6
7	## Type Safety & Explicitness
8
9	- Use explicit types for function parameters and return values when they enhance clarity
10	- Prefer `unknown` over `any` when the type is genuinely unknown
11	- Use const assertions (`as const`) for immutable values and literal types
12	- Leverage TypeScript's type narrowing instead of type assertions
13	- Use meaningful variable names instead of magic numbers — extract constants with descriptive names
14
15	## Modern JavaScript/TypeScript
16
17	- Use arrow functions for callbacks and short functions
18	- Prefer `for...of` loops over `.forEach()` and indexed
19	- Use optional chaining (`?.`) and nullish coalescing (`??`) for safer property access
20	- Prefer template literals over string concatenation
21	- Use destructuring for object and array assignments
22	- Use `const` by default, `let` only when reassignment is needed, never
23
24	## Async & Promises
25
26	- Always `await` promises in async functions — don't forget to use the return value
27	- Use `async/await` syntax instead of promise chains for better readability
28	- Handle errors appropriately in async code with try-catch blocks
29	- Don't use async functions as Promise executors
30
31	## React & JSX
32
33	- Use function components over class components
34	- Call hooks at the top level only, never conditionally
35	- Specify all dependencies in hook dependency arrays correctly
36	- Use the `key` prop for elements in iterables (prefer unique IDs over array indices)
37	- Nest children between opening and closing tags instead of passing as props
38	- Don't define components inside other components
39	- Use semantic HTML and ARIA attributes for accessibility:
40	- Provide meaningful alt text for images
41	- Use proper heading hierarchy
42	- Add labels for form inputs
43	- Include keyboard event handlers alongside mouse events
44	- Use semantic elements (`<button>`, `<nav>`
45
46	## Error Handling & Debugging
47
48	- Remove `console.log`, `debugger`, and
49	- Throw `Error` objects with descriptive messages, not strings or other values
50	- Use `try-catch` blocks meaningfully — don't catch errors just to rethrow them
51	- Prefer early returns over nested conditionals for error cases
52
53	## Code Organization
54
55	- Keep functions focused and under reasonable cognitive complexity limits (max 20)
56	- Extract complex conditions into well-named boolean variables
57	- Use early returns to reduce nesting
58	- Prefer simple conditionals over nested ternary operators
59	- Group related code together and separate concerns
60
61	## Security
62
63	- Add `rel="noopener"` when using `target="_blank"` on links
64	- Avoid `dangerouslySetInnerHTML` unless absolutely necessary
65	- Don't use `eval()` or assign directly to `document.cookie`
66	- Validate and sanitize user input
67
68	## Performance
69
70	- Avoid spread syntax in accumulators within loops
71	- Use top-level regex literals instead of creating them in loops
72	- Prefer specific imports over namespace imports
73	- Avoid barrel files (index files that re-export everything)
74	- Use proper image components (e.g., Next.js `<Image>`) over `<img>` tags
75
76	## Formatting
77
78	- 2-space indentation
79	- LF line endings
80	- 80-character line width
81	- Semicolons always
82	- Double quotes (single quotes in JSX)
83	- ES5 trailing commas
84	- Arrow parentheses always
85	- Bracket spacing enabled
86
87	## Style Rules
88
89	- No enums — use objects with `as const`
90	- No nested ternary operators
91	- No non-null assertions (`!`)
92	- Kebab-case filenames enforced
93	- `useImportType` for type-only imports
94	- Readonly class properties by default
95	- Sorted imports, JSX attributes, interface members, and object properties
96
97	## Framework-Specific
98
99	Next.js: Use `<Image>
100
101	React 19+: Use ref as a prop instead of `React.forwardRef
102
103	Solid/Svelte/Vue/Qwik: Use `class
104
105	## Testing
106
107	- Write assertions inside `it()` or `test()` blocks
108	- Avoid done callbacks in async tests — use async/await instead
109	- Don't use `.only` or `.skip` in committed code
110	- Keep test suites reasonably flat — avoid excessive `describe` nesting
111
112	## Overrides
113
114	Ultracite relaxes rules in specific contexts:
115	- Config files (
116	- Test files (
117	- Scripts/bin files:
118	- Storybook files: Unused variable/import rules relaxed
119	- Build output (