Code Quality Review

JNTMTMTM7/6/26About 5 min

Code Quality Review

Info

This document outlines the frontend coding standards for the eIsland project. All frontend code must comply with these rules — no exceptions.

HTML Standards

Document Structure

All HTML documents must start with an HTML5 doctype declaration in lowercase, and include the required structural elements: <html>, <head>, and <body>.

<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <title>Page Title</title>
</head>
<body>
</body>
</html>

Language and Encoding

Specify the language attribute on the root HTML element and declare UTF-8 encoding explicitly.

<html lang="zh-CN">
<head>
  <meta charset="utf-8">
</head>

Formatting Rules

Use 2 spaces for indentation
All HTML tags use lowercase
All attribute values must use double quotes
Self-closing elements do not need a trailing slash in HTML5

Attribute Order

HTML attributes should follow this order:

class
id, name
data-*
src, for, type, href, value
title, alt
role, aria-*
tabindex
style

Semantic HTML

Ensure headings follow a logical hierarchy (h1 → h2 → h3) without skipping levels
All <img> tags must have an alt attribute
Avoid inline event handlers — use external JavaScript instead
A page must have only one <main> element

CSS Standards

Tailwind CSS

Class Order

Tailwind classes must follow a fixed order: layout → box model → typography → visual effects.

<button class="flex items-center justify-center w-full p-4 font-bold text-white bg-blue-500 rounded-lg hover:bg-blue-600">
  Click me
</button>

Important

Prefer Tailwind shorthand forms when available (e.g., mx-4 instead of ml-4 mr-4).

To enforce the utility-first approach, avoid adding custom semantic class names to components. All styles should be composed from atomic utility classes. If customization is truly needed, use @apply in CSS.

Arbitrary Values

For negative arbitrary values, the - sign must be placed outside the brackets.

<div class="-top-[-10px]">...</div>

General CSS Rules

Use 2 spaces for indentation
All code uses lowercase (except strings)
Use double quotes consistently
One blank line between rule sets; no trailing whitespace
Use kebab-case for class names, IDs, keyframes, and custom media queries

Selector Complexity Limits

Rule	Limit
ID selectors	Forbidden
Class selectors per selector	Max 4
Attribute selectors per selector	Max 2
Combinators per selector	Max 4
Universal selectors per selector	Max 1
Type selectors per selector	Max 2
Type selector prefixing a class/ID	Forbidden (e.g., `div.my-class`)

Color Rules

Prefer 3-digit hex shorthand
Color values must be lowercase
Color names are forbidden (use hex or HSL)
Hue values use angle units (deg)

.element {
  color: #fff;
  background-color: #f0c;
  border-color: hsl(270deg 60% 70%);
}

Numeric Rules

Omit units for zero values (padding: 0)
Omit leading zero for decimals below 1 (opacity: .5)
No trailing zeros

Property Declaration Order

Properties should be declared in this order:

Composition rules (composes)
all
Positioning (position, top, z-index, etc.)
Display mode (box-sizing, display)
Flexbox
Grid
Spacing (gap)
Alignment (align-*, justify-*)
Order
Box model (width, height, padding, margin, overflow)
Typography (font-*, color, text-*)
Interaction (cursor, pointer-events)
Background and border
Mask
SVG properties
Transitions and animations
Paged media

Caution

!important is strictly forbidden.

JavaScript / TypeScript Standards

Variables and Constants

Prefer const for constants, let for reassignable variables. Avoid var.
Declare one variable per const or let statement
Variables must be defined before use
Never delete variables
Avoid initializing to undefined

const name = 'Alice';
let age = 30;

Data Types

Use literals for primitive types
Use as const for read-only constants when the type is explicit
any type is forbidden unless absolutely necessary
Forbidden wrappers: Function, Object, String, Number, Boolean

const config = {
  host: 'localhost',
  port: 8080,
} as const;

Objects

Use object literals {}
Use shorthand method syntax
Use shorthand property syntax (placed at the beginning of the object)
Only quote invalid identifiers (e.g., 'data-test')
Use Object.hasOwn() instead of Object.prototype.hasOwnProperty
Prefer spread ... over Object.assign

Arrays

Use array literals []
Use Array.from() for array-like conversions
Callbacks must have a return statement (unless implicit)
Avoid for...in on arrays
Prefer higher-order functions (map, filter, reduce) over for loops

Strings

Use single quotes '' for strings
Prefer template literals for concatenation
Avoid unnecessary escape characters

const message = `Hello, ${name}!`;

Functions

Use function declarations or expressions, not new Function()
Do not declare functions inside non-function blocks (if, while)
Set default values in parameters, not in the function body
Parameters with defaults go at the end of the parameter list
Prefer rest parameters ... over arguments
No space before parentheses in function calls

Arrow Functions

Use for anonymous callbacks
Omit braces and return for single-expression bodies without side effects

const square = (x: number) => x * x;

Classes and Interfaces

Always use class — avoid direct prototype manipulation
Call super() in non-empty constructors
One class per file
Prefer interface over type for object shapes; use type for unions and tuples

Modules

Use ES6 modules (import/export) exclusively
No file extensions in import paths
Use export default for single-export modules
Imports at the top of the file, ordered: builtins → external → internal (absolute) → parent relative → sibling relative

Comparison and Equality

Always use === and !==
No explicit comparison of booleans to true/false

const isAdult = age >= 18;       // ✅
const isAdult = age >= 18 ? true : false; // ❌

Naming Conventions

Element	Convention	Example
Variables, functions	camelCase	`userName`, `getUser()`
Classes, interfaces, types, enums	PascalCase	`UserProfile`, `StatusEnum`
Constants	UPPER_SNAKE_CASE	`MAX_RETRY_COUNT`
No leading/trailing underscores	—	—
File names	camelCase or kebab-case	`userProfile.ts` or `user-profile.ts`

Promises and Async

Prefer async/await
reject reasons should be Error objects
Always include .catch() or try...catch
Avoid return/throw/break/continue in finally blocks
Avoid unnecessary await
Avoid await in loops — use Promise.all for parallelism

async function fetchData() {
  return fetch('/api/data'); // ✅ Direct return
}

React component files use .tsx extension
Prefer function declarations for named components
Anonymous components may use arrow functions
Do not import React (React 17+ JSX transform handles this)

JSX Rules

JSX attributes use double quotes; JS/TS strings use single quotes
Boolean true values are omitted: <Checkbox checked />
Self-closing tags have a space before the slash: <MyComponent />
Multi-line JSX must be wrapped in parentheses
No spaces inside JSX curly braces: name={userName} not name={ userName }

Props

Destructure props in the function parameter
Use default parameters for optional props
Avoid props spreading — pass each prop explicitly
Never use array index as key — use stable unique identifiers

items.map((item) => <ListItem key={item.id} item={item} />); // ✅
items.map((item, index) => <ListItem key={index} item={item} />); // ❌

Hooks Rules

Only call Hooks at the top level — never in loops, conditions, or nested functions
Only call Hooks in React functions — components or custom Hooks
useEffect, useCallback, useMemo must include all external dependencies
Use symmetric naming: [count, setCount]

React Compiler Compatibility

Never mutate State during rendering — update in event handlers only
Treat Props and State as immutable — use functional updates

setUser(currentUser => ({ ...currentUser, age: currentUser.age + 1 })); // ✅

Performance

Avoid creating new objects/arrays/functions in render — define externally or memoize
Never define nested components inside another component's render function

Accessibility

All <img> tags must have alt (empty string "" for decorative images)
<a> tags must have content and a valid href
Interactive non-button elements need role and keyboard handlers — prefer <button> directly

Next.js Standards

Server vs. Client Components

Default to Server Components — add 'use client' only when hooks, browser APIs, or event listeners are needed
Client Components cannot be async functions

'use client';

import { useState } from 'react';

export default function SubmitButton() {
  const [loading, setLoading] = useState(false);
  return (
    <button onClick={() => setLoading(true)}>
      {loading ? 'Loading...' : 'Submit'}
    </button>
  );
}

Image Optimization

Important

Must use next/image — HTML <img> tags are forbidden. LCP images require the priority attribute. Always specify width and height (or fill).

import Image from 'next/image';

<Image src={heroImage} alt="Hero Banner" priority width={1200} height={600} />

Script Loading

Must use next/script — synchronous <script> tags are forbidden
Inline scripts must have an id attribute
Do not place <Script> inside <head> or Metadata

Metadata and SEO

Use the Metadata API (metadata object or generateMetadata)
Never use <head> tags or next/head

Fonts

Must use next/font — importing Google Fonts via <link> is forbidden

Internal links: Must use <Link> — <a> for internal pages is forbidden
External links: Use <a> with rel="noopener noreferrer" when target="_blank"
Programmatic navigation: Use useRouter from next/navigation (never next/router)

Forbidden Patterns Summary

Pattern	Reason	Alternative
`var`	Function scope, causes bugs	`const` / `let`
`any`	Bypasses type checking	Explicit type or `unknown`
`==` / `!=`	Implicit coercion	`===` / `!==`
`eval()`	XSS security risk	Redesign
`javascript:` URL	Security risk	`onClick` or `Link`
Inline event handlers	Hard to maintain	External JS or event delegation
HTML `<img>`	Performance	`next/image`
Plain `<script>`	Blocks rendering	`next/script`
`<a>` for internal navigation	Full page refresh	`<Link>` component
CSS `!important`	Breaks specificity	Reorganize selectors
Array index as `key`	List update bugs	Stable unique ID
Props spreading `...props`	Unmaintainable	Pass each prop explicitly
`innerHTML` / `outerHTML`	XSS risk	Direct text rendering or sanitization

Changelog

7/6/26, 10:37 AM

View All Changelog

4f6b6-Merge pull request #129 from JNTMTMTM/devon 7/6/26