DEV Community: Fin Chen

MCP Apps: When Interactive UI Grows Inside AI Conversations

Fin Chen — Wed, 25 Mar 2026 22:31:03 +0000

In January 2026, the MCP Apps spec landed. It lets MCP Servers embed interactive HTML UIs — charts, forms, dashboards, maps — directly inside conversations in Claude, VS Code, and other AI hosts.

As a frontend engineer, the moment I saw "interactive HTML inside AI chat," I was hooked. Text-only tool outputs always felt limiting. MCP Apps close the gap between what the LLM produces and what the user actually sees and touches.

I spent some time digging into the spec and built mermaid-mcp-app — an interactive Mermaid diagram tool I now use daily. This post walks through MCP Apps using that project as the running example.

What Are MCP Apps

Three Roles

The architecture has three actors:

MCP Server — The backend. Registers tools via registerAppTool and HTML resources via registerAppResource. A tool's _meta.ui.resourceUri field binds it to a specific UI.
Host — The AI interface — Claude Desktop, VS Code Copilot, etc. When the LLM calls a tool, the Host executes it, fetches the HTML from resourceUri, and renders it in a sandboxed iframe.
View — The frontend app running inside that iframe. It uses the App class to open a postMessage channel with the Host, receives tool results, and can call server tools or push messages back into the conversation.

All View ↔ Server communication goes through the Host through JSON-RPC 2.0 over postMessage.

Lifecycle

Four phases:

Discovery — The Host connects to the server, reads the tool list, and flags tools carrying _meta.ui metadata. It can pre-fetch HTML resources here for caching and security review.
Initialize — Once the LLM calls a tool, the Host spins up a sandboxed iframe, loads the HTML, and completes a handshake via ui/initialize. Both sides exchange capabilities: the View declares which display modes it supports; the Host provides theme, container dimensions, and other context.
Interactive — The Host pushes tool input and tool result into the View, which renders the UI. From here, the View can call server tools via callServerTool, send messages back to the conversation via sendMessage, or silently sync state to the LLM via updateModelContext.
Teardown — When the conversation ends or the user closes the UI, the Host sends ui/resource-teardown so the View can clean up.

Interactions

The spec provides two APIs for this:

sendMessage — Acts as if the user typed something in the chat box. The message shows up in the conversation immediately.

await app.sendMessage({
  role: "user",
  content: [{ type: "text", text: `I modified the diagram:\n\`\`\`mermaid\n${code}\n\`\`\`` }],
});

updateModelContext — A silent sync. No response is triggered, but the LLM will see the data the next time the user sends a message. Each call overwrites the previous — only the latest snapshot is kept.

await app.updateModelContext({
  content: [{ type: "text", text: `Current Mermaid source:\n\`\`\`mermaid\n${code}\n\`\`\`` }],
});

	sendMessage	updateModelContext
Triggers LLM response	Immediately	No
Visible in conversation	Appears as user message	Hidden
Multiple calls	Each one is independent	Last call wins
Best for	Completed actions that need the LLM to respond	Continuous state sync — the user decides when to ask

These two APIs change what an MCP App fundamentally is. It's not "a container for displaying LLM output" anymore. It's a full interactive component: input goes in, the user acts, output flows back to the LLM.

E.g. sendMessage after a user fills out a form to continue with the conversation with LLM. updateModelContext after the user selects a region on a map, silently syncing coordinates until they ask "what restaurants are nearby?" and LLM knows the context.

Beyond these two core APIs, the View also has access to callServerTool (invoke server-side tools), openLink (ask the Host to open external URLs), downloadFile (the iframe sandbox blocks direct downloads, so the Host handles it), and requestDisplayMode (switch between inline, fullscreen, or picture-in-picture).

Building One: The Mermaid MCP App

Enough theory. Let me walk through the mermaid-mcp-app I built — an interactive Mermaid tool that embeds diagrams directly in conversations, with drag-to-pan, scroll-to-zoom, and a split-view editor for live syntax editing.

30-Second Setup

First, check out what I built. Add this to your Claude Desktop or VS Code MCP config:

{
  "mcpServers": {
    "mermaid": {
      "command": "npx",
      "args": ["-y", "mermaid-mcp-app", "--stdio"]
    }
  }
}

Restart Claude Desktop and ask it to "draw a user authentication flowchart." The diagram appears inline — draggable, zoomable, with an editor for modifying the syntax on the spot.

There's also a packaged Desktop Extension (.mcpb) on GitHub Releases. Double-click to install — no terminal needed.

Server Side

The server handles three things:

Registers the main tool. registerAppTool defines render-mermaid, with _meta.ui.resourceUri binding it to the HTML resource:

registerAppTool(server, "render-mermaid", {
  title: "Render Mermaid Diagram",
  inputSchema: {
    code: z.string().describe("The Mermaid diagram syntax to render"),
    theme: z.enum(["default", "light", "dark", "forest", "neutral"]).optional(),
  },
  _meta: {
    ui: { resourceUri: "ui://mermaid/view.html" },
  },
}, async ({ code, theme }) => ({
  content: [{ type: "text" as const, text: JSON.stringify({ code, theme: theme ?? "default" }) }],
}));

Serves the HTML resource. registerAppResource exposes the Vite-bundled single HTML file as a ui:// resource. The server sends data only — all rendering happens client-side inside the iframe.

Internal tools for draft persistence. Two additional tools — save-mermaid-draft and get-mermaid-draft — let the View persist user edits to server memory and restore state when the iframe is recreated. These are internal; only the View calls them via callServerTool, not the LLM.

View Side

The View is a standard frontend app. It uses the App class to set up the postMessage channel:

const app = new App(
  { name: "MermaidViewer", version: "1.0.0" },
  {},
  { autoResize: true },
);

app.ontoolinput = (params) => {
  // LLM calls the tool — Host sends arguments before the server processes them
  handleMermaidData(params.arguments);
};

app.ontoolresult = (params) => {
  // Server finishes processing — Host sends the full result
  const data = JSON.parse(params.content[0].text);
  handleMermaidData(data);
};

await app.connect();

ontoolinput and ontoolresult fire at different moments. The former triggers when the LLM decides to call the tool (arguments are ready but the server hasn't processed yet); the latter fires after the server returns. For tools that don't need server-side computation — like mermaid-mcp-app — both carry essentially the same data, so you can use ontoolinput for early rendering. For tools that do compute on the server, the two payloads will differ.

There's also ontoolinputpartial. As the LLM streams tool arguments, the Host patches the incomplete JSON into a valid shape and pushes it to the View. Not useful for Mermaid (half-written syntax won't render), but great for text-heavy UIs that want progressive rendering.

Interactivity in Practice

When the user opens the split-view editor and modifies the Mermaid code, two things happen:

Auto context sync — Each edit triggers a debounced updateModelContext call, silently syncing the current source to the LLM. No immediate response, but the next time the user asks a question, the LLM already knows the latest diagram state.

  await mcpApp.updateModelContext({
    content: [{
      type: "text",
      text: `Current Mermaid diagram source (updated by user):\n\`\`\`mermaid\n${code}\n\`\`\``,
    }],
  });

Send to AI (⌘ Enter) — Calls sendMessage with the full modified source as a user message. The LLM sees it and responds right away.

await mcpApp.sendMessage({
    role: "user",
    content: [{
      type: "text",
      text: `I've updated the Mermaid diagram source:\n\`\`\`mermaid\n${code}\n\`\`\``,
    }],
  });

Lesson Learned During Development

Iframe Sandbox Restrictions

Every View runs inside a sandboxed iframe with a default CSP (Content Security Policy). Libraries that rely on eval() won't work out of the box. If your UI needs external resources, you have to declare them via connectDomains, resourceDomains, and frameDomains. The official map example hit exactly this wall — CSP blocked eval() calls used for binding parsing.

Viewport Size Management

The spec gives you two mechanisms for iframe dimensions:

autoResize — Pass autoResize: true to the SDK. It attaches a ResizeObserver to detect body changes, temporarily sets html.style.height to max-content to measure natural content height, then notifies the Host via ui/notifications/size-changed. Content drives height; the Host follows.
containerDimensions — Query the container constraints anytime via app.getHostContext()?.containerDimensions:

interface HostContext {
  containerDimensions?: (
    | { height: number }      // fixed: Host controls height, View should fill it
    | { maxHeight?: number }  // flexible: View decides height, but within a ceiling
  ) & (
    | { width: number }       // fixed: Host controls width
    | { maxWidth?: number }   // flexible: View decides width
  );
}

Wait for Layout to Settle Before Measuring

The iframe's dimensions shift for all kinds of reasons during loading. If you measure at that point for fit-to-container logic, you'll capture stale values. Use a ResizeObserver with a debounce — "wait until dimensions stop changing" — before reading the final size.

State Persistence Is Your Problem

The Host can destroy and recreate your iframe at any time — conversation scrolls out of view, user switches tabs, Host updates its UI. The Mermaid code your user spent five minutes editing? Gone. No warning.

My solution: register two internal tools on the server (save-mermaid-draft / get-mermaid-draft). The View calls callServerTool to persist state to server memory on every edit. When the iframe is recreated, it loads the last saved state automatically.

Where the Ecosystem Stands

Host support is still limited. Confirmed so far: Claude Desktop, VS Code Copilot, Goose, Postman, and MCPJam. The spec requires servers to provide a plain-text fallback, so Hosts that don't support MCP Apps fall back gracefully — the tool doesn't break.

The spec keeps moving. SEP-1865 was consolidated in November 2025 from the MCP-UI community and OpenAI Apps SDK experience. It's in Final status now but still has active PRs. Future additions on the table include external URL support, built-in state persistence, and View-to-View communication.

References

Awesome Frontend Agent Skills — A Curated List of SKILL.md for Frontend Dev

Fin Chen — Tue, 17 Mar 2026 13:42:39 +0000

AI coding agents don't know your framework's conventions out of the box. SKILL.md fixes that — it's a structured file that library authors publish to teach agents the right patterns for their tool.

The ecosystem is growing fast, though there's skills.sh, but it's a hassel to curate frontend related skills. So I built one for frontend.

awesome-frontend-skills — 70+ skills across 12 categories, all installable via npx skills add.

What's Covered

Frameworks — React, Angular, Vue, Next.js, Nuxt, Svelte, TanStack, Remix
UI — shadcn/ui, Tailwind v4 design systems
Testing — Playwright, Cypress, Selenium, E2E patterns
Build Tools — Vite, Nx, Turborepo, monorepo management
Animation — Three.js, Framer Motion, CSS animation
Auth — Clerk, Auth0, Better Auth
Database — Prisma, Supabase, Convex
Mobile — React Native, Expo
Video — Remotion

Many are official — published by the framework teams themselves (Angular, shadcn, Prisma, Supabase, Playwright, etc.).

Lists skills repo, description and installation commands. That's it.

Only SKILL.md files. No .cursorrules, CLAUDE.md, AGENTS.md, or llms.txt — those serve different purposes.

PRs welcome if you know a frontend repo with a SKILL.md that's missing.

→ github.com/finfin/awesome-frontend-skills

💥 The Day Emoji Caused a Mess : A Developer's 🚨🔍🐛🧪✅ Journey 👨‍💻

Fin Chen — Mon, 07 Jul 2025 13:13:55 +0000

The Problem: When Database Migration Breaks Frontend Display

One time we decided to add a 280-character constraint to our posts table, but there's a problem - existing content already contains posts longer than this limit.

So we write a Python migration script to clean up the existing data to fit in db column:

# Migration script: Clean up existing long posts
def truncate_existing_posts():
    long_posts = Post.objects.filter(content__length__gt=280)

    for post in long_posts:
        if len(post.content) > 280:
            post.content = post.content[:280]  # Truncate to 280 characters
            post.save()

    print(f"Truncated {long_posts.count()} posts to 280 characters")

# Example of what the migration does
original_post = "Amazing day with the family! 👨‍👨‍👦‍👦❤️ Can't wait for more adventures together! 🚀🎨 Life is beautiful when you're surrounded by love and joy!"
print(f"Original length: {len(original_post)}")  # 132 characters

truncated_post = original_post[:280]  # Well within the limit
print(f"Truncated length: {len(truncated_post)}")  # 132 characters ✅
print(f"Truncated content: {truncated_post}")

The migration runs successfully. All posts are now 280 characters or fewer according to Python. We deploy the new schema with character validation on the frontend.

But then users start reporting that their post content becomes invalid when editing

The Investigation: When Character Counting Goes Wrong

After some digging we found out their is a weird different length between python and javascript, when using emojis.

# Python
text_with_emoji = "Hello 👨‍💻 World"
print(f"Python len(): {len(text_with_emoji)}")  # 15 characters

# Let's see what Python sees
for i, char in enumerate(text_with_emoji):
    print(f"{i}: {repr(char)}")
# 0: 'H', 1: 'e', 2: 'l', 3: 'l', 4: 'o', 5: ' ', 6: '👨', 7: '\u200d', 8: '💻', 9: ' ', 10: 'W', 11: 'o', 12: 'r', 13: 'l', 14: 'd'

// JavaScript
const textWithEmoji = "Hello 👨‍💻 World";
console.log(`JavaScript length: ${textWithEmoji.length}`); // 17 characters

// Let's see what JavaScript sees
console.log([...textWithEmoji]); 
// ['H', 'e', 'l', 'l', 'o', ' ', '👨', '‍', '💻', ' ', 'W', 'o', 'r', 'l', 'd']

It turns out that Python counts Unicode code points, while JavaScript counts UTF-16 code units. The same emoji is counted differently.

Three emojis, three lengths. Why???

The Curiosity Detour

At this point, the fix was obvious - just align the character counting methods between frontend and backend. Problem solved!

But another thing caught my eye:

// Simple emoji
const man = '👨';
console.log(man.length); // 2 in js, 1 in python

const developer = '👨‍💻';
console.log(developer.length); // 5 in js, 3 in python (?!)

const family = '👨‍👨‍👦‍👦';
console.log(family.length); // 11 in js, 7 in python (!!!)

Why was 👨‍👨‍👦‍👦 counting as 11 characters in JavaScript but only 7 in Python? What exactly was hiding inside that "single" family emoji?

That curiosity led me to study Unicode emoji specifications...

The Deep Dive: Unicode Emoji Specifications

So what's really happening under the hood? Let's examine the Unicode specifications that govern emoji behavior.

Zero-Width Joiners: The Invisible Glue

Some emojis are built with several base emojis, using Zero-Width Joiners (ZWJ U+200D*)* - invisible characters that glue base emojis together:

// Let's break down the developer emoji
const developer = '👨‍💻';
console.log(Array.from(developer));
// Output: ['👨', '‍', '💻']
// That's: man + ZWJ + computer

// The family emoji breakdown
const family = '👨‍👨‍👦‍👦';
console.log(Array.from(family));
// Output: ['👨', '‍', '👨', '‍', '👦', '‍', '👦']
// That's: man + ZWJ + man + ZWJ + boy + ZWJ + boy

Emoji Presentation Selector: The Style Controller

Another invisible character: U+FE0F VARIATION SELECTOR-16 (VS16), the emoji presentation selector. This forces a symbol to display in emoji style rather than text style:

// Medical symbol without emoji presentation selector
const textSymbol = '⚕';     // U+2695 only
console.log(textSymbol.length); // 1

// Medical symbol WITH emoji presentation selector  
const emojiSymbol = '⚕️';    // U+2695 + U+FE0F
console.log(emojiSymbol.length); // 2
console.log(Array.from(emojiSymbol)); // ['⚕', '️']

Many common emojis include this hidden selector:

// These look like single characters but aren't:
const heart = '❤️';         // U+2764 + U+FE0F
const warning = '⚠️';       // U+26A0 + U+FE0F

console.log(Array.from(heart));     // ['❤', '️'] - has VS16
console.log(Array.from(warning));   // ['⚠', '️'] - has VS16

From the Unicode specification:

2695 FE0F (fully-qualified) — ⚕️ medical symbol (emoji presentation)
2695 (unqualified) — ⚕ medical symbol (text presentation)

Emoji Modifiers: Skin tones

For people emojis, we can use modifiers for customization:

// Skin tone modifiers
const artist = '🧑🏻‍🎨'; // light skin tone
console.log(artist.length); // 7
console.log(Array.from(artist)); 
// ['🧑', '🏻', '‍', '🎨']
// That's: person + light skin tone + ZWJ + artist palette

// Professional emojis with skin tone modifiers
const lightDeveloper = '👨🏻‍💻'; // light skin male developer
console.log(lightDeveloper.length); // 7
console.log(Array.from(lightDeveloper));
// ['👨', '🏻', '‍', '💻']

The five skin tone modifiers are:

🏻 (Light skin tone - U+1F3FB)
🏼 (Medium-light skin tone - U+1F3FC)
🏽 (Medium skin tone - U+1F3FD)
🏾 (Medium-dark skin tone - U+1F3FE)
🏿 (Dark skin tone - U+1F3FF)

// Same base emoji, different lengths due to modifiers
const wave = '👋';           // 2 characters
const waveLight = '👋🏻';     // 4 characters  
const waveDark = '👋🏿';      // 4 characters

// Comparing different combinations
const doctor = '👩‍⚕️';       // 5 characters (woman + ZWJ + medical + VS16)
const lightDoctor = '👩🏻‍⚕️'; // 7 characters (+ skin tone modifier)

Flag Sequences: Countries Built from Letters

Here's where it gets really interesting. Country flags are actually sequences of two Regional Indicator characters:

// Flag examples - each is 2 Regional Indicator characters
const usFlag = '🇺🇸';        // U+1F1FA (🇺) + U+1F1F8 (🇸) = "US"
const taiwanFlag = '🇹🇼';     // U+1F1F9 (🇹) + U+1F1FC (🇼) = "TW"
const japanFlag = '🇯🇵';      // U+1F1EF (🇯) + U+1F1F5 (🇵) = "JP"

// All flags have length 4 in JavaScript
console.log(usFlag.length);     // 4
console.log(taiwanFlag.length); // 4
console.log(japanFlag.length);  // 4

// Breaking them down shows the Regional Indicators
console.log(Array.from(usFlag));     // ['🇺', '🇸']
console.log(Array.from(taiwanFlag)); // ['🇹', '🇼']

// You can even manually construct flags:
const manualTW = '🇹🇼';           
const constructedTW = '\u{1F1F9}\u{1F1FC}'; // Same thing!
console.log(manualTW === constructedTW);     // true

The Experiment: Interactive Exploration

At this point, I was fascinated by the complexity. How many different emoji combinations exist? What do they actually contain?

So I built "Emoji Architect" to explore these compositions interactively. With this tool you can:

Browse all ZWJ sequence emojis
See the real-time breakdown of any emoji (base emoji & modifiers)
See JavaScript length calculations live

🔗 https://www.thingsaboutweb.dev/en/emojiarchitect

The Solution: Synchronized Character Counting

Now that we understand the problem, let's fix our backend and frontend validation mismatch.

The Core Issue: Different Counting Methods

Our original problem stemmed from inconsistent character counting:

# Python: 
len("Hello 👨‍💻 World") # 15

# JavaScript
"Hello 👨‍💻 World".length # 17

My Initial Approach: Visual Character Counting

Initially, I was drawn to visual character counting because it felt like the right user experience. Why should users have to understand Unicode internals just to know if their post fits the character limit? Luckily Intl can help us…

JavaScript implementation:

function getVisualLength(str) {
    if (typeof Intl.Segmenter !== 'undefined') {
        const segmenter = new Intl.Segmenter('en', {granularity: 'grapheme'});
        return [...segmenter.segment(str)].length;
    }
    // Fallback for older browsers
    return [...str].length;
}

getVisualLength("Hello!! I am a developer 👨‍💻 who loves 🧋 and 🏃‍♂️!!") 
// Result: 46 
// what users actually see

For python..

import regex  # pip install regex

def get_visual_length(text):
    """Count grapheme clusters like JavaScript's Intl.Segmenter"""
    return len(regex.findall(r'\X', text))

get_visual_length("Hello!! I am a developer 👨‍💻 who loves 🧋 and 🏃‍♂️!!") 
# Result: 46
# consistent with frontend

This seemed perfect—users would see exactly what they expect, and complex emoji sequences would count as single characters regardless of their Unicode complexity.

Reality Check: Database Constraints

But when I wanted to save data to database….

// Frontend validation passes with visual counting
const bio = "Hello!! I am a developer 👨‍💻 who loves 🧋 and 🏃‍♂️!!";
console.log(`Visual length: ${getVisualLength(bio)}`);  // 46 characters ✅

But database insertion fails spectacularly

SELECT CHAR_LENGTH("Hello!! I am a developer 👨\U+200D💻 who loves \U+1F9CB and 🏃\U+200D♂️!!") 
/* 51! Which fails on VARCHAR(50) constraint! */

Since there’s no easy way to make database limit content by visual length, the most practical approach is to settle with code point counting.

Second Solution: count code points:

function codePointLength(text) {
    /**
     * Count Unicode code points like Python len() does
     * This matches Python's default string length behavior and database constraints
     */
    return [...text].length;
}


const text = "Hello!! I am a developer 👨‍💻 who loves 🧋 and 🏃‍♂️!!";
console.log(`Frontend: ${codePointLength(text)}`);     
// 51 (which matches Python & DB)

Code point counting might not be as user-friendly as visual counting, but it works reliably across your entire stack.

Key Takeaways

After diving deep into Unicode specifications and building production solutions, here's my learning:

Test Across Entire Stack Visual character counting seems ideal, but database constraints and ecosystem compatibility often force you toward Unicode code point counting. Choose the solution that works with your entire stack, not just the frontend.
Test with Complex Emoji Early Don't just test with simple emojis like 😀. Include ZWJ sequences (👨‍💻), skin tone modifiers (👋🏻), and flag emojis (🇹🇼) in your validation logic from day one. It’s fun to poke around on unicode / emoji, and hope my * Emoji Architect tool can be of some help on how emojis are built.*

TIL: Many emojis are actually multiple emojis combined together, not single characters

Fin Chen — Sat, 05 Jul 2025 07:18:06 +0000

Ever wondered why some emojis take up more character count than expected? (Especially when dealing with input character count) Turns out many emojis are actually combinations of simpler ones!

Examples of composite emojis:

👨‍👨‍👦‍👦 = 👨+👨+👦+👦 (family of four men)
👩‍💻 = 👩+💻 (woman technologist)
🏳️‍🌈 = 🏳️+🌈 (rainbow flag)
👨‍🍳 = 👨+🍳 (man cook)
🧑🏻‍🎨 = 🧑 + 🏻 + 🎨 (artist: light skin tone)

Developer gotcha: Different programming languages handle Unicode differently, so emoji length calculations can vary between frontend and backend. Always test your character limits with composite emojis.

JavaScript examples:

For javascript, Intl.Segmenter can be a great help

const family = '👨‍👨‍👦‍👦';

// Default length - counts UTF-16 code units
console.log(family.length); // 11

// Destructuring - counts grapheme clusters  
console.log([...family].length); // 7

// See the actual components
console.log(Array.from(family)); 
// ['👨', '‍', '👨', '‍', '👦', '‍', '👦']

// For accurate user-visible character count
const segmenter = new Intl.Segmenter('en', {granularity: 'grapheme'});
console.log([...segmenter.segment(family)].length); // 1

Playground

I got curious about all possible combinations, so I made "Emoji Architect" to explore these emojis, with this tool you can:

Browse all composite emojis
See the breakdown of any emoji
Filter combinations by base emoji components

🔗 https://www.thingsaboutweb.dev/en/emojiarchitect

More explanation and ways of building emojis coming soon...

Reference

Best reference is the spec

https://www.unicode.org/reports/tr51/

Things About Code Review: Balancing Code Quality and Development Speed

Fin Chen — Wed, 01 Jan 2025 12:54:55 +0000

After leading product teams for several years, I’ve come to deeply appreciate Code Review as an effective tool, though it comes with its fair share of pitfalls. Drawing from my experience and research, I’ve compiled some insights to share with you.

Common Challenges in Software Development

During the software development process, many of us encounter situations like these:

Team members taking leave or being absent: Development or review schedules get delayed due to unexpected absences.
Reduced code maintainability: As new features are added, code complexity increases, and development time gets prolonged.
Lower-than-expected output quality: Features often launch with bugs. QA, PMs, managers, clients, and users all ask the same question: “Why does our product have so many issues?”
Developers lacking confidence in their code: They might worry about missing requirements or potential system failures due to edge cases. This not only affects individual efficiency but can also slow down the entire team.

Adding a Gatekeeper: Code Review

To address these challenges, many teams choose to implement Code Review. Here’s what most people expect Code Review to achieve:

What We Hope Code Review Can Accomplish

Foster teamwork and knowledge sharing:
- Increase the team’s bus factor by ensuring more members are familiar with critical code.
- Help new developers quickly adapt to the team’s style and best practices.
Improve code quality and maintainability:
- Ensure code adheres to team standards.
- Reduce technical debt, making future maintenance easier.
Ensure specifications are met and reduce bugs:
- Verify that implementations align with requirements, avoiding missed details.
- Identify potential issues through multiple sets of eyes.
Boost deployment confidence:
- With team-wide endorsement, deployments become more reassuring.
- Especially in cross-departmental collaborations, Code Review helps minimize iterative fixes caused by oversight, strengthening team trust.

The Current State and Challenges of Code Review

While the idea is appealing, the reality is often much tougher. Here are some common challenges:

Time-Consuming

Code Review is an extremely time-intensive task. For most teams, it takes an average of 6 hours per developer per week, and my personal record was spending over 30 hours in a week just on reviews. This means dedicating several hours every workday to reviewing others’ code, leaving little time to focus on one’s own development progress.

PRs Take Days to Merge

Due to the time-consuming nature of reviews, the entire Pull Request (PR) process often stretches out over several days or more. This is particularly true for large and complex PRs. As the time from opening to merging a PR increases, the rhythm of development iterations slows down as well.

Limited Effectiveness in Identifying Issues

Research shows that only 14% of review feedback addresses actual issues. This indicates that while a significant amount of time is spent on Code Review, its direct impact on reducing errors is limited.

At this point, let’s pause and reflect on an important question:

What Is the Essence of Code Review?

Here’s my answer:

The essence of Code Review is to enhance output quality and the team’s technical level through the exchange of knowledge and perspectives.

This sounds ideal. Developers hope that reviews can genuinely improve code quality. However, on the other hand, the resources invested in Code Review pose a significant burden on development teams.

Balancing Code Quality and Development Efficiency in Code Review

Now, let’s return to the core topic of this article: improving code quality through Code Review while minimizing its impact on development efficiency. Here, we’ll break Code Review down into three levels:

Review Execution: This focuses on how Code Review is conducted, including choosing the right format, balancing synchronous and asynchronous methods, defining the scope of reviews, and identifying key review points.
Knowledge Exchange: Beyond execution, Code Review is a process that fosters interaction and knowledge transfer between reviewers and developers. At this level, we need to consider how to improve efficiency in communication and ensure smooth knowledge flow.
Overall Development Process: From a broader perspective, this level examines Code Review within the context of the entire development workflow, identifying areas for optimization. This might include shifting tasks earlier in the process, working with smaller task units, or leveraging automation tools to streamline reviews.

These three levels decompose Code Review into points, lines, and planes. The review execution level is the point, the knowledge exchange level connects the points into lines, and the overall development process forms the complete plane. In the following sections, we’ll explore the key aspects and implementation strategies for each of these levels.

Review Execution

The way Code Review is conducted directly impacts its efficiency and effectiveness. It can be further broken down into review formats and review focus areas.

Different Review Formats

The execution of Code Review can be broadly categorized into synchronous and asynchronous approaches, each suited for specific scenarios and offering unique characteristics.

Synchronous Formats

Synchronous Code Reviews are conducted in real-time, requiring the simultaneous participation of two or more people:

Pair Programming: Two people work together in real-time, with one writing the code and the other reviewing and providing feedback on the spot.
Live Review: A real-time session where the developer and reviewer collaborate to review and discuss the code, quickly resolving issues and ensuring code quality through immediate interaction.
Code Review Meeting: A team-wide review meeting where key code changes are discussed in-depth to gather multiple perspectives and improve the overall quality of outputs.
Code Walkthrough: A more knowledge-sharing-oriented activity, where the developer explains the code’s logic and functionality step-by-step. Team members mainly observe and ask questions to enhance their understanding and learn from the code.

Synchronous reviews are characterized by their immediacy and interactivity, making them ideal for quickly resolving issues or engaging in deep discussions. However, they require participants to align their schedules, increasing time costs.

Asynchronous Formats

Asynchronous Code Reviews don’t require participants to be present at the same time. All reviews and feedback are conducted through digital mediums, such as:

PR Review: Developers submit a Pull Request (PR), and reviewers can examine the code changes, leave comments, and discuss at their convenience.

Asynchronous reviews offer high flexibility, making them suitable for distributed teams and cross-time-zone collaborations. However, the lack of real-time interaction can limit discussions, especially for complex changes.

The Core Difference Between Synchronous and Asynchronous Reviews

Synchronous formats emphasize real-time interaction, making them suitable for complex or urgent changes. Asynchronous formats, on the other hand, focus on flexibility, allowing participants to complete reviews at their own pace. Both have their specific use cases. Below is a comparison table outlining the characteristics and applications of various review formats.

Comparison Table: Features and Applications of Different Code Review Formats

Format	Core Characteristics	Use Cases	Advantages	Disadvantages
Pair Programming	Synchronous collaboration where two developers work together, with one writing code and the other reviewing and providing feedback in real-time.	- Complex feature development - High-risk code implementation - Onboarding new developers	- Instant feedback for quick problem resolution - Reduces code defects - Promotes knowledge sharing	- Requires synchronized schedules - High demands on time and manpower
Live Review	Real-time code review where the reviewer and developer discuss code details directly.	- Urgent changes, quick validation - Complex code requiring detailed discussion - Mentorship for newcomers	- Immediate interaction reduces communication overhead - Ideal for addressing high-complexity issues - Builds team trust	- Consumes time for multiple participants
Code Review Meeting	A formal code review involving the entire team, focusing on critical code changes for in-depth discussion.	- Significant architectural or design changes - High-risk features - Team knowledge sharing	- Multiple perspectives for comprehensive checks - Encourages team learning - Enhances design transparency	- Very high time costs
Code Walkthrough	A synchronous activity where developers explain the code’s logic and design step-by-step while reviewers ask questions and provide suggestions.	- Mentorship for newcomers - Understanding complex code - Familiarizing team members with new system modules	- Supports growth of new team members - Helps the team understand complex system logic - Encourages developers to reflect on their code design	- More teaching-focused, less efficient than targeted code reviews - Can consume significant time
PR Review	Asynchronous code review conducted via tools (e.g., GitHub/GitLab), where reviewers examine changes and leave comments.	- Reviewing routine development changes - Distributed or cross-time-zone teams	- Flexible timing - Review records available for future reference - Can integrate with automation tools (e.g., CI/CD) for higher efficiency	- Lack of real-time interaction may hinder communication - Complex changes may be harder to understand

Choosing the Right Format

When conducting Code Reviews, you can determine the most suitable review format based on the "complexity" and "urgency" of the development task. These tasks can be categorized into four quadrants to guide the decision-making process.

The more complex the change, the greater the need for direct human involvement to ensure thorough discussion and examination. Conversely, the more urgent the task, the faster the review needs to proceed. For simpler tasks that have passed testing and are deemed reliable, why not skip the review and deploy directly?

Review Layers and Key Focus Areas

Code Review encompasses multiple layers. Below is an overview of the different layers and their key review points.

Coding Guideline

Coding guideline is aimed at maintaining project consistency so all developers can quickly understand and extend the code. Key points include:

Follow project code style and naming conventions: Ensure code is cleanly formatted and consistent.
Readability: Code should be clear and simple, enabling others to understand it quickly. This includes naming variables in a way that clearly reflects their purpose or intent.

Code style rules can largely be automated using static code analysis tools to check formatting and simple naming conventions, such as ensuring variables are named in CamelCase. However, readability often requires manual review. The good news is that some of this work can be offloaded to AI tools like Copilot, Cursor, or Windsurf. For instance, the following image shows how I used Cursor Chat to "check the readability of code within a file."

Testing

Testing is a form of self-review and includes the following key focus areas:

Ensuring tests align with requirements and cover all specified aspects.
Verifying that all tests pass, particularly for reasonable tests targeting new features.
Checking edge-case tests to ensure extreme or abnormal scenarios are handled correctly.
Addressing non-functional requirements (NFRs), such as performance, stability, and security testing.

Testing is typically integrated with CI/CD tools for automation.

Documentation

Good documentation is essential for team knowledge sharing:

Thorough documentation of new features: Background, purpose, design logic, and implementation details should be clearly recorded.
Relating documentation updated: This includes README files, API documentation, user guides, etc., ensuring they reflect the current state.
Readability and accessibility of documentation: Documentation should be understandable and searchable when needed.

Code is often the single source of truth for engineers, but documentation may be scattered across different locations. Thus, it’s crucial to ensure documentation is both comprehensive and easy to find and up-to-date. Missing documents provide no value, and outdated information can lead to incorrect development directions. While automation for documentation is limited, AI combined with document templates can help generate drafts.

Implementation

Implementation is naturally a focal point of Code Review, with the following key areas of focus:

Fulfilling functional requirements: Ensuring all specified needs are met without omissions.
Correct and concise logic: Avoid unnecessary complexity.
Robustness: Handle unexpected inputs, edge cases, and failures gracefully without crashing.
Secure: Considered risks such as SQL injection, XSS, etc.
Observability: Including sufficient logs, traces, or metrics to support maintenance and status monitoring.

Implementation have various levels of complexity, thus manual involvement is often required. The good news is that AI review tools (or simple prompts) can handle reviews of lower complexity.

Boundaries

Boundaries refer to the areas outside the scope of the current changes that might be affected by them — this includes systems, external resources, or users. For instance, changing a database attribute affects the database table, its associated data model, anyone using the model, and any other areas interacting with the database attribute. Changing a button affects the page and users interacting with it. Review focus areas include:

Minimizing impact: Ensure the boundaries are simplified and dependencies are reduced while meeting requirements.
Consistency and the Principle of Least Surprise: Ensure developers interacting with the boundaries can quickly understand their behavior.
Hiding internal implementation details: Expose only the necessary functions or interfaces to the outside.
Existing systems working properly: Ensure all affected parts function correctly.

Think of adding a subway line to a metropolis. The construction scope, integration with existing structures, coordination with current roads, and even the connection between stations and traffic flow are all boundary issues. The more complex the functionality and changes, the more intricate the boundaries become. Fortunately, much of this complexity can be shifted left(earlier) in the development process, which will be further discussed in the "Development Process" section.

The higher layers of these five aspects are easier to automate. Ideally, we should automate the top layers as much as possible and focus our efforts on the last two: implementation and boundary reviews.

AI Code Review Tools

Recently, I started using a tool called Code Rabbit AI. It's a cool AI Code Review tool, and very easy to integrate. Tools like this can improve the efficiency of Code Reviews and are particularly helpful for finding foundational issues.

There’s so much to discuss about AI tools that it’s worth dedicating an entire article to the topic. Here are some key observations and tips for using AI tools:

Thorough but Junior-Level Reviews AI can efficiently and instantly help detect syntax errors, semantic issues, simple logical mistakes, and API usage inconsistencies. These alone can elevate the basic quality of the code.
Clear Specifications Are Key Like humans, AI tools perform better when given clear specifications. Well-defined spec sheets or requirement documents significantly enhance the relevance and quality of AI output.
Don’t Expect a SENIOR AI to Save You AI typically struggles with complex functionalities, architectural designs, or system-level problems. For core architecture-related reviews, manual input is still essential.
Control Scope When the number of files or the scope of changes is too large, the quality of AI suggestions may decrease. Setting reasonable change boundaries ensures the tool remains effective.

AI can save time by handling minor issues, which is one of its key benefits — it takes on the burden of highlighting small, tedious details that might seem nitpicky if pointed out by human reviewers.

Improving Review Execution Efficiency

Here’s a summary of actionable steps for improving execution efficiency:

Choose the Right Code Review Format For urgent and complex tasks, synchronous formats like Live Reviews or Pair Programming are ideal, while for routine changes, asynchronous PR Reviews offer more flexibility.
Utilize Automation Tools Incorporate automated processes like static code analysis, unit testing, and integration testing into CI/CD pipelines to ensure basic code quality is verified before submission.
Leverage AI-Assisted Reviews AI serves as a versatile assistant, reducing the time engineers spend on straightforward logic and allowing them to focus on discussing more complex and valuable functionalities.
Focus on Implementation and Boundary Reviews Reviewers should concentrate on assessing the implementation and boundaries, especially areas that are too complex for automated tools to handle.

Knowledge Exchange

Now that we’ve covered Review Execution, let’s shift our focus to Knowledge Exchange — the critical interactions between developers and reviewers.

Correct understanding leads to effective feedback.

The greatest challenge in Code Review is understanding the content and the reasons behind the changes.

The essence of Code Review lies in enhancing the team's technical capabilities and output quality through knowledge exchange. However, this exchange is inherently challenging. Research shows that reviewers often spend significant time digesting the background information of a PR (Pull Request), especially when changes involve complex logic or multiple modules. A lack of sufficient context can easily lead to misplaced review focus or unconstructive feedback. This is particularly true in large teams or long-term projects where reviewers have varying levels of background knowledge, making clear and specific descriptions crucial for understanding.

Here are some practical actions reviewers can take:

Read PR Descriptions and Commit Histories\ Ensure you understand the goals and scope of the changes, focusing on valuable aspects of the review to avoid wasting time on irrelevant details.
Refer to Tests and Related Documentation\ Use test cases and specification documents to understand the design objectives and expected behavior of the changes.
Ask Questions and Request Additional Context\ When encountering unclear or hard-to-understand areas, reviewers should ask questions and request clarification instead of making assumptions or skipping over details.
Choose Effective Methods for Gaining Information\ Depending on the complexity of the changes, use appropriate review formats — for instance, asynchronous methods for smaller changes, and synchronous formats like Live Reviews or Code Walkthroughs for complex changes.
Document Key Information During Discussions\ Record important background information or decision rationale during the review process for future reference. This benefits not only the reviewer but also helps other team members understand the considerations behind the changes.

These practices help reviewers quickly obtain accurate context within limited time, improving the quality of their feedback.

Key Point 1: More Efficient Information Sharing

Visuals > Spoken > Text\ Code Review doesn’t need to rely solely on text feedback. For especially complex changes, invite the developer to conduct a Code Walkthrough, explaining logic line by line or illustrating the entire functionality flow.
Face-to-Face > Online\ Face-to-face communication is more efficient, as it captures body language and physical nuances, enabling immediate feedback and interaction, reducing misunderstandings.
Synchronous > Asynchronous\ Synchronous methods like Live Reviews or Pair Programming enable more precise and immediate information exchange, avoiding delays or information gaps often caused by asynchronous communication.
Positive Tone > Negative\ Using a positive or constructive tone enhances the acceptance of reviews and improves communication outcomes. Instead of merely pointing out problems, suggest alternatives or highlight learning opportunities. Research shows that reviews with positive or neutral tones are considered effective 80% of the time, compared to only 57% for reviews with negative tones.
Link Code to Related Documentation\ This aligns with the "findability" principle mentioned earlier. The faster reviewers can locate relevant information, the quicker they can make informed judgments.

Key Point 2: The API Principle

API here stands for Assume Positive Intent. This principle encourages us to assume that everyone wants to do their best and to interpret their actions or intentions in a positive light. This is especially critical in text-heavy asynchronous Code Reviews, where the lack of tone or context can lead to misunderstandings.

When we assume others have good intentions, we are more inclined to help them achieve their goals, leading to more constructive feedback. For example, we naturally help children explore the world, such as learning to walk (goal), by offering support and encouragement. In contrast, if we view someone as an adversary, we’re more likely to hope for their failure and withhold assistance.

The API Principle builds trust within teams, making Code Review communications smoother and reducing conflicts caused by tone or misunderstandings.

Key Point 3: Be Clear and Actionable

Suggestions should clearly identify problems while guiding actionable solutions. However, what’s considered "clear and actionable" varies by individual. Consider these two pieces of feedback:

"Consider addressing some edge cases."
"In the calculateCAGR function, consider adding checks for whether starting_value and ending_value are zero. Currently, the function throws a ZeroDivisionError when inputs are zero."

For experienced developers, feedback like #1 may suffice. However, for newcomers or colleagues unfamiliar with the code, feedback like #2, with more details, is necessary. Effective reviews should adapt to the audience, helping team members of varying experience levels better understand and apply the suggestions.

Case Analysis

At this point, let’s use the well-known case as an example in our discussion.

Let’s evaluate this Code Review comment using the points we discussed earlier:

Efficient Information Sharing: The reviewer is the creator.
API Principle: Extremely aggressive in tone.
Clear and Actionable: The feedback provides explicit steps for improvement.

Now, here’s the question: from a Code Review perspective, is this type of feedback good or bad? How does it impact code quality and the team dynamic — positively or negatively?

Development Process Perspective

Previously, we discussed what reviewers can do, including the execution of reviews and knowledge exchange between reviewers and developers. Now, let’s zoom out and look at the overall development process — what optimizations can be made from this broader perspective?

Clearly Define and Document Specifications During the Planning Phase

Both the execution and knowledge exchange sections emphasized the importance of specifications. The planning phase is a critical stage for influencing development efficiency and quality. If requirements are clearly defined and specifications are thoroughly documented during this phase, unnecessary discussions and revisions during Code Review can be minimized. For example, if the specifications already detail the API input/output formats, error-handling logic, and performance requirements, reviewers can focus on validating the implementation against these requirements instead of debating the details of the requirements themselves.

Defining specifications early has another benefit: it helps identify unnecessary features. If a feature is deemed non-essential during the planning phase, it won’t be implemented, and there’s no need to spend time reviewing it.

The Best Code is No Code At All.

As a reminder, documentation findability is crucial. During development, ensure that code, documents, and specifications are tightly linked. This not only facilitates the current Code Review process but also helps team members better understand the system in the future. This can include linking related documents directly in the code or converting specifications into test cases. Doing so allows reviewers and developers to quickly reference the context and rationale behind changes, greatly improving communication efficiency and confidence.

Next, let’s examine two statistical charts to understand the relationship between change size and review efficiency.

PR Size vs. Review Effectiveness

This chart shows that there is a negative correlation between the number of files changed and its review effectiveness density. As the number of files increases, the effectiveness of the review decreases. A reasonable explanation is that large scope overwhelm reviewers, making it harder for them to fully understand the changes and reducing the value of their feedback.

PR Size vs. Review Duration

Now let's see the second chart, the PR merge time peaks at around 2,000. When the number of modified lines in a PR is under 2,000, the more lines modified, the longer the review and merge process takes. For PRs with fewer than 50 lines, the average merge time is less than 2 days (about 36 hours). However, for PRs with 500-1,000 lines, the average time climbs to nearly 4 days. Interestingly, when the number of lines exceeds 2,000, the merge time stops increasing. This could be due to several reasons:

Large PRs might involve formatting changes, requiring minimal review.
PRs with over 2,000 lines might be too challenging to review thoroughly, leading reviewers to skip them altogether.

Ask a programmer to review 10 lines of code, he'll find 10 issues.
Ask him to do 500 lines and he'll say it looks good.

Overall, for changes exceeding 100 lines, the average merge time rises to 4 days — a concerning statistic for development speed.

Reduce Pull Requests Size

The larger the scope of changes, the bigger the PR becomes. This often requires more complex architecture, detailed specifications, and significantly more time to understand and review. So, can we reverse this trend? By breaking down features into smaller tasks and PRs, we can reduce the scope of changes, simplify the architecture and specifications, and shorten the time needed for reviews.

Follow these steps to reduce PR size:

Make Specifications and Documentation Clear\ Reiterating the importance of proper planning: clear and detailed planning ensures that subsequent implementation has a solid foundation and is easier to split into smaller tasks and delegate.
Break Requirements into Simple Tasks\ Divide requirements into small, manageable development tasks that can be completed in half a day. This helps developers stay focused and avoids submitting large-scale changes all at once. For example, a feature could be broken down into separate PRs for the UI, API integration, and backend implementation. This approach not only simplifies reviews but also makes the context of each PR more explicit.
Clarify Task Dependencies\ Clearly define the dependencies between tasks to ensure the sequence of execution is logical and efficient. For example, if the backend API implementation is a prerequisite for frontend development, the backend PR must be prioritized and completed first. This ensures that the frontend team can proceed without unnecessary delays caused by waiting for backend changes.
Implement: One Task, One PR\ Follow the "one task, one PR" principle to keep each PR’s scope manageable and clear. This approach reduces the cognitive load for each review and minimizes the risk of errors or misunderstandings caused by intertwined tasks. Consider leveraging Stacked PRs for better task separation.
Target: LOC < 500\ Studies show that when a PR’s lines of code (LOC) are fewer than 500, reviewers are most efficient and accurate. Therefore, we should aim to limit each PR’s changes to this range. This constraint can reduce the reviewer’s workload and ensure higher-quality reviews.

Self Review: Pre-Review Preparation

The person who understands a PR best is its author. Self Review, in theory, costs less than having a Reviewer perform the audit. Therefore, consider conducting a Self Review before submitting your code for Code Review. This not only improves the quality of the PR but also reduces the workload for the Reviewer.

There are two approaches to Self Review:

Act as if you are the Reviewer and carefully review your own PR.
Use AI coding tools to assist with the review:\ Tools like Copilot, Cursor, or Windsurf now offer chat functionalities. You can use these tools to have AI review your code or even suggest real-time modifications.

Here are some sample prompts for reviewing implementation and boundaries:

I want you to perform a code review, ensuring the following checklist is satisfied:

1. **Fulfilling functional requirements**: Ensuring all specified needs are met without omissions.
2. **Correct and concise logic**: Avoid unnecessary complexity.
3. **Robustness**: Handle unexpected inputs, edge cases, and failures gracefully without crashing.
4. **Secure**: Considered risks such as SQL injection, XSS, etc.
5. **Observability**: Including sufficient logs, traces, or metrics to support maintenance and status monitoring.

Boundary Review Prompt

I want you to perform a code review, ensuring the following checklist is satisfied:

1. **Minimizing impact**: Ensure the interface are simplified and dependencies are reduced while meeting requirements.
2. **Consistency and the Principle of Least Surprise**: Ensure developers interacting with the interface can quickly understand their behavior.
3. **Hiding internal implementation details**: Expose only the necessary functions or interfaces to the outside.
4. **Existing systems working properly**: Ensure all affected parts function correctly.

Note: In these prompts, the term *interface** is used to describe boundaries because it is easier to identify and assess within the editor. Making "interface" a more practical term for this context.*

Other Ways AI Tools Can Help

Beyond assisting with Self Review, AI tools can contribute to other stages of development and Code Review, making the process more efficient:

Generate PR Descriptions (GitHub Copilot):
Generate Specifications / Test Cases: Engineers can use AI to produce artifacts such as API documentation, mock data, or even test cases to assist with testing or validation.
Create Explanations: Visualize code workflows, explain complex logic, and provide additional context to make understanding easier.

Final Thoughts

You Don’t Always Need Code Review

While Code Review is an essential practice for improving code quality, it’s not always necessary to invest resources in it. Here are scenarios where skipping or simplifying Code Review might be appropriate:

High Confidence, High Test Coverage: If the project has comprehensive test coverage and there’s confidence in the deployment process, reliance on Code Review can be reduced.
Small-Scale, Low-Risk Changes: Changes such as modifying text, configuration files, or non-critical parts of the codebase can be self-reviewed and deployed directly by developers.
Experimental Features: Some experimental features may be short-lived or rewritten soon. In such cases, Code Review may not be a worthwhile investment.

To summarize, here are some key points about Code Review:

Choose the Right Format: For complex changes, opt for synchronous reviews to maximize effectiveness. For routine changes, asynchronous PR Reviews allow team members to work at their own pace.
Leverage Automation: Tools like static code analysis, automated testing, and CI/CD pipelines are standard in modern development. Additionally, AI-assisted Code Review can help detect basic issues.
Focus on High-Value Areas: Direct review efforts toward the architecture, boundaries, and core logic of the code. Simple issues, such as coding style, can be handled by automation tools.
Define Clear Specifications and Requirements: During the planning phase, clearly define requirements and create supporting documentation. A well-defined goal reduces misunderstandings, minimizes non-compliant behaviors (bugs), and helps reviewers focus on whether changes meet the requirements.
Reduce Task Scope and PR Size: Break tasks into manageable units and limit each PR to fewer than 500 lines of code. This reduces review time and improves review quality.
Self Review First: Conduct a self-check before submission, using AI tools if needed, to ensure the PR meets basic quality standards.

I cannot stress this enough: Code Review is more than just a quality improvement tool — it’s a powerful process for building team cohesion and facilitating knowledge sharing. I hope these insights have given you new perspectives and practical approaches to enhance your Code Review practices. If you’d like to continue the conversation, feel free to connect with me on social media!

References

Things About Nonce & CSRF Token: Differences, Use Cases, and How They Work

Fin Chen — Sat, 21 Dec 2024 00:46:41 +0000

To prevent web attacks, Nonce (Number Used Once) and CSRF Token (Cross-Site Request Forgery Token) are two common and important security mechanisms for modern websites. Although both are related to web security, their design goals, problems addressed, and application scenarios are distinct. This article introduces the workings of these two mechanisms, their differences, and their appropriate use cases.

What is a Nonce? Why do we need it?

A nonce is a randomly generated string used only once to ensure the uniqueness of each request or operation. It is typically generated by the server and included with each request. By storing and validating the nonce on the server, it can effectively prevent attackers from intercepting and re-executing requests, ensuring each request is executed only once.

For instance, when users accidentally click the submit button multiple times in a web form, it could result in multiple orders being created. The nonce mechanism prevents the server from processing duplicate requests. It also safeguards against replay attacks, which attempt to exploit intercepted legitimate requests to perform multiple actions, leading to unauthorized operations.

A good analogy for a nonce is an event ticket. Each ticket has a unique number and can only be used once to gain entry to the event. Once scanned at the entrance, the system marks it as used, ensuring the same ticket cannot be reused to enter again. Similarly, a nonce ensures that each request is unique and cannot be duplicated or reused maliciously.

Use Cases for Nonce

Scenario 1: Prevent Duplicate Form Submissions

In scenarios requiring order submissions, users might accidentally click the submit button multiple times, resulting in multiple requests. Without a verification mechanism, the server could process these duplicate requests, causing multiple orders or tasks to be executed repeatedly.

To solve this issue, a nonce can be used to ensure the uniqueness of each form submission. The server generates a random nonce and embeds it in the form. When the user submits the form, the server verifies whether the nonce has already been used. If it has, the request is rejected.

Consider a shopping website, a user may unintentionally click the "Submit" button multiple times after submitting an order. The server uses a nonce to validate each request's uniqueness, ensuring the order is not submitted multiple times.

Secnario 1 Implementation

Form:

<form method="POST" action="/submit-order">
  <input type="hidden" name="nonce" value="123456789abcdef">
  <input type="text" name="orderDetails">
  <button type="submit">Submit Order</button>
</form>

Server Validation:

if (isNonceValid(request.body.nonce)) {
    processOrder();
    invalidateNonce(request.body.nonce);
} else {
    throw new Error("Invalid nonce!");
}

Scenario 2: Prevent Replay Attacks

Attackers may intercept legitimate API requests and send identical requests multiple times for malicious purposes. To prevent such replay attacks, a nonce can ensure each request is unique. The server checks whether the nonce has already been used to determine the request's validity.

A RESTful API for executing deductions could be maliciously exploited by repeatedly sending the same deduction request. A nonce ensures that the request is executed at most once.

Secnario 2 Implementation

Request:

POST /transactions HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer <access_token>

{
    "nonce": "abcdef123456",
    "amount": 100.00,
    "account_id": "1234567890",
    "transaction_type": "deduction"
}

Server Validation:

if (isNonceValid(request.body.nonce)) {
    executeTransaction(request.body.amount, request.body.account_id, request.body.transaction_type);
    invalidateNonce(request.body.nonce);
} else {
    throw new Error("Invalid or reused nonce!");
}

Special Scenario: Content Security Policy (CSP)

There is a specific use of nonces under Content Security Policy (CSP) that provides robust protection for web applications. A CSP nonce is a randomly generated string, used only once, to control the execution of inline scripts or styles. It is generated by the server and included in both the CSP header and authorized <script> or <style> tags. The process is similar to the previously introduced nonce mechanism, but here, validation happens in the browser. The browser enforces CSP rules, ensuring only scripts or styles with the correct nonce are executed, blocking unauthorized ones.

For example, a webpage displaying user-specific data may require dynamically generated inline JavaScript. By embedding a nonce in the server-generated CSP header and the authorized scripts, only the intended scripts are executed, while unauthorized ones are blocked. This ensures critical inline scripts can run safely without exposing the page to malicious script injections.

Special Scenario Implementation

Server-Set CSP Header:

Content-Security-Policy: script-src 'self' 'nonce-abcdef123456';

HTML Page:

<script nonce="abcdef123456">
  console.log('This is a secure script.');
</script>

<script>
  console.log('This script will be blocked by CSP.');
</script>

Result:

Only embedded scripts with the correct nonce will execute.
Other embedded or injected external scripts will be blocked by CSP.
The console of this page will show This is a secure script.

What is a CSRF Token? Why do we need it?

A CSRF Token (Cross-Site Request Forgery Token) is a security measure designed to prevent cross-site request forgery (CSRF) attacks. Its purpose is to verify that each request comes from the user's legitimate operation rather than a malicious site's induced request.

A typical CSRF attack exploits the victim's logged-in state to send malicious requests to a trusted website without the victim's authorization or knowledge. For example, an attacker might forge a request to transfer funds, change passwords, or delete user accounts.

The CSRF Token is usually generated by the server and bound to the session. The server sends the token to the user's browser and requires the user to include this token in every request. Upon receiving the request, the server verifies whether the token matches the value stored in the user's session. If the token is invalid or missing, the request is rejected.

This mechanism verifies the legitimacy of requests, preventing attackers from impersonating users through cross-site methods to perform sensitive operations, thus enhancing application security.

Use Cases for CSRF Tokens

Scenario: Enhance Security for Sensitive Actions

Attackers may exploit a user's logged-in state to initiate high-risk actions like transferring funds. To prevent such situations, a CSRF Token serves as an effective validation method.

Users must include a CSRF Token to protect fund transfer requests.

Implementation

Form:

<form method="POST" action="/transfer-funds">
  <input type="hidden" name="csrf_token" value="abcd1234efgh">
  <input type="number" name="amount" placeholder="Transfer Amount">
  <input type="text" name="to_account" placeholder="Recipient Account">
  <button type="submit">Submit Transfer</button>
</form>

Server Validation:

if (request.body.csrf_token === session.csrf_token) {
    processTransfer(request.body.amount, request.body.to_account);
} else {
    throw new Error("Invalid CSRF token!");
}

Summary

Differences Between Nonce and CSRF Token

Feature	Nonce	CSRF Token
Main Purpose	Prevent replay attacks, duplicate submissions	Prevent cross-site request forgery
Usage	Ensure request uniqueness	Validate request legitimacy
Implementation Level	Commonly used in APIs or form submissions	Commonly used in APIs or form submissions
Reuse	Single-use (non-reusable)	May be reused (e.g., within a session)

Nonce ensures request uniqueness to avoid duplicates and works with CSP to allow only authorized scripts to execute.
CSRF Token prevents Cross-Site Request Forgery by verifying the random string included in each request matches the server-generated token, ensuring the request originates from a legitimate user.

Can Nonce and CSRF Tokens Be Used Together?

Yes, these mechanisms address different issues and can be used together without conflict. Implementation depends on the specific problem you aim to solve.

References:

Flowchart Components and Examples

Fin Chen — Tue, 17 Dec 2024 00:59:57 +0000

Flowcharts are a powerful form of diagram that use a few simple elements to illustrate the sequence of events, possible branches, and more. They help readers focus on "what will happen next and the sequential relationships between each part of the process."

Flowcharts can be applied in various scenarios, such as reviewing incidents, planning system functionalities, or even organizing trips and events.

Basic Symbols of a Flowchart

Here is an introduction to the basic elements commonly found in flowcharts:

Start and End (Start/End):
Used to mark the beginning or end of a process.
Process:
Represents a single step within the process.
Predefined Process:
Indicates a subprocess or detailed flow defined elsewhere.
Delay:
A step that requires waiting.
Decision:
Represents a decision or branching point, leading to different paths.
Preparation/Initialization:
A step involving preparation or initialization.
Input/Output:
Marks the input or output of data.
Manual Input:
Indicates a step requiring human interaction, such as manual input or operation.
AND/OR:
Logical operators used to combine or branch process flows.
Document/Multiple Documents:
Represents a document or a set of documents.
Database:
Denotes a system used for storing data, especially in software contexts.
Connector/Off-page Connector:
Used when there isn’t enough space to continue the flow.
- Connector: Used for connections on the same page.
- Off-page Connector: Used for linking to a flow on a different page.
Arrow:
The core of a flowchart, showing the next step in the process. Typically, arrows point forward. Dotted lines may be used for annotations or indirect references to another symbol or explanatory block.

With these symbols, you can create clear and effective flowcharts for a variety of purposes!

Usage Examples

Here are two examples showcasing how these icons can be applied:

Login Process

Recruitment Process

Flowchart for Better Problem-Solving

Powerful tools like draw.io offer built-in flowchart symbols, making them feature-rich but often accompanied by a steeper learning curve. In contrast, simpler and more intuitive tools like Whimsical and Excalidraw require users to create their own symbol libraries, offering greater flexibility but requiring a bit of setup.

Since I personally rely on Excalidraw for creating flowcharts, all the symbols featured in this article were drawn using it. If you’re an Excalidraw user as well, I’ve created a Flow Chart Symbols library that you can explore. Give it a try, and I’d love to hear your feedback to make it even better!

Flowcharts make it easier to visualize the entire picture, and Excalidraw’s intuitive design simplifies the process of creating and refining these visualizations. By clearly mapping out processes, we can quickly identify and focus on areas that require improvement or fixing, leaving more time for deeper problem-solving and generating insights. This makes it an invaluable tool for enhancing clarity and driving effective solutions.

Naming with Acronyms in PascalCase and camelCase

Fin Chen — Sat, 07 Dec 2024 03:02:07 +0000

Naming is hard, really. There is a famous browser API XMLHttpRequest, it’s famous in part for its mixed naming strategy. Here, "XML" is fully capitalized, while "Http" follows a capitalized first letter, leading to an inconsistent and somewhat perplexing naming style.

…until you bumped into it yourself. See how you will name these:

xml http request, new customer id, supports IPv6 on iOS, YouTube importer

Handling Acronyms in Naming Conventions

When incorporating acronyms into identifiers, developers generally adopt one of two approaches:

Preserve Original Capitalization: Maintain the acronym's original uppercase letters.
Treat Acronyms as Words: Apply standard naming conventions, capitalizing only the first letter in PascalCase or the first letter of subsequent words in camelCase.

For instance, consider the term "XML HTTP request":

Preserving Original Capitalization:
- PascalCase: XMLHTTPRequest
- camelCase: xMLHTTPRequest or xmlHTTPRequest (both appear awkward and conflict with camelCase norms)
Treating Acronyms as Words:
- PascalCase: XmlHttpRequest
- camelCase: xmlHttpRequest

The second approach aligns better with naming conventions, ensuring consistency and readability.

Challenges with Special Cases

Certain names, like "iOS," intentionally start with a lowercase letter. In such cases, adhering strictly to original capitalization can clash with naming conventions. For example, in PascalCase, "iOS Adapter" would become IOSAdapter, which alters the intended capitalization.

Similarly, names containing numbers, such as "IPv6," present challenges. Deciding whether to treat "IPv6" as a single word or split it into "IpV6" affects the final identifier.

Google's Guidelines

Fortunately, Google offers a systematic approach to handle these scenarios:

Convert to ASCII and Remove Apostrophes: For example, "Müller's algorithm" becomes "Muellers algorithm."
Split into Words: Divide based on spaces and remaining punctuation.
Apply Common Conventions: If a word has a conventional camelCase form, use it (e.g., "AdWords" becomes "adWords").
Combine According to Naming Rules: Assemble the words following the desired naming convention.

Notably, Google's guidelines don't specify exact treatments for acronyms, but the process of splitting into words typically treats acronyms as individual words, leading to identifiers like XmlHttpRequest or xmlHttpRequest.

Advantages of Treating Acronyms as Words

This method simplifies transitions between different naming conventions (e.g., camelCase to snake_case) and ensures consistency across various codebases. For instance, converting XmlHttpRequest to snake_case results in xml_http_request, which is straightforward. In contrast, preserving original capitalization can complicate such conversions.

Conclusion

When dealing with acronyms in naming conventions:

Split the term into individual words or components.
Apply the standard naming convention rules to each component.

This approach promotes clarity and consistency, though it may require adjusting to seeing acronyms like "ID" rendered as "Id" or "URL" as "Url."

Adhere to the convention, the naming from first section would be:

"XML HTTP request" → XmlHttpRequest
"new customer ID" → NewCustomerId
"supports IPv6 on iOS" → SupportsIpv6OnIos
"YouTube importer" → YouTubeImporter

By adopting this strategy, developers can maintain a consistent and readable codebase, even when faced with complex naming scenarios.

Reference

Implementing Dark Mode and Theme Switching using Tailwind v4 and Next.js

Fin Chen — Fri, 29 Nov 2024 23:37:59 +0000

Dark mode support has become a fundamental aspect of modern web applications, and I recently tackled this feature for my personal blog using Tailwind CSS v4 beta with Next.js 15. In this article, I'll walk through my journey of implementing a dynamic theme toggle, share my learnings of both frameworks.

My Goal: Customizable Website Appearance

Before diving into the implementation details, let's examine what we're building. The goal is to create a theme selection feature that provides a seamless experience while respecting user preferences. When visiting the site, users will have three theme options available: Light, Dark, and Auto (System setting). This behavior mirrors Stack Overflow's theme selection system, which provides an intuitive and well-tested approach to theme management.

This mechanism use Auto mode as default, which adapts to the user's device theme preferences. Users can then override this by selecting either Light or Dark mode, and their choice will persist across visits to provide a consistent experience. This combination of intelligent defaults and preserved user preferences ensures the site remains comfortable to use across different viewing conditions.

Getting Started with Tailwind v4

To begin experimenting with Tailwind v4, I first needed to set up the framework in my project. The installation process proved remarkably straightforward, even simpler than its predecessor, version 3.

Working with Next.js, the setup process consisted of just three simple steps. The first step was installing the required packages through npm: reference

npm install tailwindcss@next @tailwindcss/postcss@next

Next, update postcss configuration to use Tailwind's new PostCSS plugin. The configuration is notably simpler compared to previous versions, requiring just a single plugin:

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

Finally, imported Tailwind into main CSS file using a straightforward import statement:

@import "tailwindcss";

Step 0: Leveraging Tailwind's Default Dark Mode

Tailwind provides built-in support for dark mode through its dark variant. When we use utility classes like text-black dark:text-white, Tailwind will automatically switch between these styles based on the user's system preferences.

Let's look at a simple blog post card component and understand how Tailwind handles its dark mode styling:

function BlogCard({ title, content }) {
  return (
    <article className="text-black bg-white dark:text-white dark:bg-black p-4 rounded-lg">
      <h2 className="text-xl text-gray-900 dark:text-gray-100">{title}</h2>
      <p className="text-gray-600 dark:text-gray-300">{content}</p>
    </article>
  );
}

When Tailwind processes our utility classes, it generates CSS that uses the prefers-color-scheme media query. For example, the dark:text-white class gets transformed into:

.dark\:text-white {
    @media (prefers-color-scheme: dark) {
        color: var(--color-white);
    }
}

This CSS transformation reveals two important aspects of how Tailwind v4 works. First, it uses the prefers-color-scheme media query to detect system theme preferences. When a user's system is set to dark mode, any styles within this media query automatically activate. Second, and notably in v4, it leverages CSS variables for colors. Instead of hardcoding color values, Tailwind now uses CSS custom properties (like var(--color-white)), making the entire theming system more flexible and performant. These variables are defined at the root level of your CSS, allowing for easy theme customization and manipulation.

Step 1: Custom Theme Control

Now, we'll enhance our setup to support explicit theme selection through a dropdown select. This involves three key pieces: configuring Tailwind to respect our custom theme attribute, creating a theme management system, and an user interface for theme selection.

One of the most significant changes when implementing dark mode in v4 is the shift in how dark variants are configured. In Tailwind v3, dark mode configuration was managed through the tailwind.config.js file:

/** For Tailwind v3 */
/** @type {import('tailwindcss').Config} */
module.exports = {
  darkMode: ['variant', '&:not(.light *)'],
  // ...
}

In v4, we define our dark variant behavior alongside our Tailwind import, in the main css file:

@import "tailwindcss";
@variant dark (&:where([data-theme="dark"]));

Instead of relying heavily on the JavaScript configuration file, v4 moves configuration options directly into CSS. For example, we can now define custom colors as CSS variables (--color-primary: #ff0000;), configure variants using @variant directives.

Now our configuration tells Tailwind to apply dark styles when it finds a data-theme="dark" attribute, rather than relying on system preferences.

Then, we need a place to manage this data-theme attribute. Hence, let’s create our theme management system:

// ThemeProvider.jsx
import { createContext, useContext, useState, useEffect } from 'react';

const ThemeContext = createContext();

export function ThemeProvider({ children }) {
  const [theme, setTheme] = useState('light');

  // Synchronize theme state with HTML data attribute
  useEffect(() => {
    document.documentElement.dataset.theme = theme;
  }, [theme]);

  // Provide theme context to children
  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

// Custom hook for easy theme access
export function useTheme() {
  const context = useContext(ThemeContext);
  if (context === undefined) {
    throw new Error('useTheme must be used within a ThemeProvider');
  }
  return context;
}

Then, we create a select component that gives users explicit control over their theme choice:

// ThemeSelect.jsx
export function ThemeSelect() {
  const { theme, setTheme } = useTheme();

  return (
    <select 
      value={theme}
      onChange={(e) => setTheme(e.target.value)}
      className="bg-white dark:bg-gray-800 text-black dark:text-white p-2 rounded border border-gray-300 dark:border-gray-600"
    >
      <option value="light">Light</option>
      <option value="dark">Dark</option>
    </select>
  );
}

Finally, we wrap our application with the ThemeProvider and place the ThemeSelect component where we want the theme controls to appear:

// App.jsx
function App() {
  return (
    <ThemeProvider>
      <div className="min-h-screen bg-white dark:bg-gray-900">
        <nav className="p-4">
          <ThemeSelect />
        </nav>
        {/* Rest of your application */}
      </div>
    </ThemeProvider>
  );
}

Now user can change the theme by selecting instead of changing system setting. Next, we'll extend this feature to support an "auto" option that respects system preferences , just like phase 0.

A Note About Generated CSS and Browser Compatibility

Tailwind v4 beta generates dark mode utilities using modern CSS nesting syntax:

.dark\:text-white {
    &:where([data-theme="dark"], [data-theme="dark"] *) {
        color: var(--color-white);
    }
}

As CSS nesting is a relatively new feature, there are ongoing discussions about browser compatibility in the Tailwind community (see GitHub issue #14753). Since v4 is in beta, this implementation might change based on community feedback and compatibility concerns.

Step 2: System-Aware Theme Switching

After setting up manual theme selection in Phase 1, we're now ready to add system preference detection.

The centerpiece of this enhancement is the window.matchMedia('(prefers-color-scheme: dark)') API. This gives us a way to not only check the current system theme but also respond when it changes. Think of it like subscribing to your system's theme announcements - whenever the user toggles their system theme, our site will hear about it and react accordingly. It’s an javascript equivalent of @media (prefers-color-scheme: dark) .

First, let's update our theme management to react to system preferences:

// ThemeProvider.jsx
import { createContext, useContext, useState, useEffect } from 'react';

const ThemeContext = createContext();

export function ThemeProvider({ children }) {
  const [theme, setTheme] = useState('auto');

  useEffect(() => {
    // Update data-theme accordingly if user selects light or dark
    if (theme !== 'auto') {
      document.documentElement.dataset.theme = theme;
      return;
    }

    // For auto mode, we need to watch system preferences
    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');

    // Set initial theme based on system preference
    document.documentElement.dataset.theme = mediaQuery.matches ? 'dark' : 'light';

    // Update theme when system preference changes
    function handleChange(e) {
      document.documentElement.dataset.theme = e.matches ? 'dark' : 'light';
    }

    mediaQuery.addEventListener('change', handleChange);
    return () => mediaQuery.removeEventListener('change', handleChange);
  }, [theme]);

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

Now we expand our select component to include the auto option:

export function ThemeSelect() {
  const { theme, setTheme } = useTheme();

  return (
    <select 
      value={theme}
      onChange={(e) => setTheme(e.target.value)}
    >
      <option value="light">Light</option>
      <option value="dark">Dark</option>
      <option value="auto">Auto</option>
    </select>
  );
}

Users can now choose between explicit light/dark themes or let their system preferences automatically control the theme. When in auto mode, the site smoothly transitions between themes as system preferences change, creating a seamless experience that respects both user choice and system settings.

Step 3: Persisting Theme Preferences

Our theme system works well, but it resets to 'auto' whenever the user refreshes the page. Let's improve the user experience by remembering their theme preference using localStorage. This way, when users return to our site, they'll see their chosen theme immediately.

We'll modify our ThemeProvider to read and write to localStorage:

// ThemeProvider.jsx

const getInitialTheme = () => {
  // Handle server-side rendering scenario
  if (typeof window === 'undefined') return 'auto';

  // Get theme from localStorage, defaulting to 'auto' if not found
  return localStorage.getItem('theme') || 'auto';
}

export function ThemeProvider({ children }) {
  // Initialize state with the result of getInitialTheme()
  const [theme, setTheme] = useState(getInitialTheme);

  // Rest of the provider implementation...
  useEffect(() => {
    localStorage.setItem('theme', theme);
  }, [theme]);

  useEffect(() => {
    if (theme !== 'auto') {
      document.documentElement.dataset.theme = theme;
      return;
    }

    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
    document.documentElement.dataset.theme = mediaQuery.matches ? 'dark' : 'light';

    function handleChange(e) {
      document.documentElement.dataset.theme = e.matches ? 'dark' : 'light';
    }

    mediaQuery.addEventListener('change', handleChange);
    return () => mediaQuery.removeEventListener('change', handleChange);
  }, [theme]);

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

A critical aspect is ensuring we have a valid theme value before the component even mounts by separating the initial theme logic into getInitialTheme, and pass it directly to useState. This prevents any potential flash of incorrect theme during the initial render.

Now user preferences can persist across browser sessions, creating a more consistent and personalized experience. Whether a user prefers explicit light/dark modes or automatic system-based switching, their choice will be remembered the next time they visit our site.

A Note About System Preferences and Browser Behavior

Our matchMedia implementation detects theme preferences as reported by the browser, not directly from the operating system. Some browsers, like Arc, have their own theme settings that can override the system preferences. This means in 'auto' mode, the theme will respond to whatever the browser reports as the current preference, which might come from either the system or browser-specific settings.

Bonus Step: Using next-themes Library

While building a custom theme implementation has been instructive, in real world we might want a shortcut, this is where you may consider using the next-themes library.

To switch to next-themes, we first install the package:

npm install next-themes

Then we can replace our custom ThemeProvider with the one from next-themes:

import { ThemeProvider } from 'next-themes'

function App({ Component, pageProps }) {
  return (
    <ThemeProvider attribute="data-theme">
      <Component {...pageProps} />
    </ThemeProvider>
  )
}

next-themes replaces the ThemeProvider we just created, with the same useTheme hook:

import { useTheme } from 'next-themes'

export function ThemeSelect() {
  const { theme, setTheme } = useTheme();

  return (
    <select 
      value={theme}
      onChange={(e) => setTheme(e.target.value)}
    >
      <option value="light">Light</option>
      <option value="dark">Dark</option>
      <option value="auto">Auto</option>
    </select>
  );
}

Why do I get server/client mismatch error?

When using useTheme, you will use see a hydration mismatch error when rendering UI that relies on the current theme. This is because many of the values returned by useTheme are undefined on the server, since we can't read localStorage until mounting on the client. Add a suppressHydrationWarning to the html tag to ignore this. See ++example++.

https://github.com/pacocoursey/next-themes/tree/main?tab=readme-ov-file#faq

In this implementation, we've actually built several core features that mirror next-themes:

Theme management through ThemeProvider
Automatic handling of browser storage synchronization
Protection against flash of wrong theme on page load
Support for system theme changes across all modern browsers

While next-themes provides additional fine-grained features, understanding how to build a theme system from scratch, as we did in the previous steps, gives valuable insights into how theme switching works under the hood.

Conclusion

Through this implementation journey, I've learned a lot: from Tailwind v4's elegant CSS-based approach and leveraging the matchMedia API for system preferences, to solving the flash of wrong theme challenge. Hope this article helps you understand the nuances of implementing dark mode and inspires you to create more accessible and user-friendly web applications.

References

Thing You May Not Know About CSS Variables - 2. Using var() and Cool Examples

Fin Chen — Wed, 13 Nov 2024 10:36:00 +0000

This is the second half of my CSS Variable post, the first half is here.
In this article we'll look into the details of var(). And two cool examples:

Using `var()`

The var() accesses custom property values (CSS variables). Its syntax is as follows:

var( <custom-property-name>, <fallback-value>? )

Basic Rules

The first parameter must be a CSS variable: Direct values, such as var(20px), will result in an error, as var() only accepts custom property names.
var() cannot replace property names: In other words, you cannot write something like var(--prop-name): 20px; because var() is limited to use in property values only.

.foo {
  margin: var(20px); /* Error, 20px is not a CSS variable */

  --prop-name: margin-top;
  var(--prop-name): 20px; /* Error, cannot use var() this way */
}

Detailed Behaviors

var(--b, fallback_value) Fallbacks: The second parameter acts as a fallback value, used when --b is invalid.
var(--c,) Syntax with an Empty Fallback: If the fallback value is left empty, the syntax remains valid and will default to an empty value if --c is invalid.
Multiple Comma: In var(--d, var(--e), var(--f), var(--g)), everything after the first comma is treated as fallback, so if --d is invalid, the var() expression evaluates var(--e), var(--f), var(--g) as one fallback, to determine the result.
var() as a Complete CSS Token: The function acts as a complete CSS token, like 20px would. Therefore, var(--size)var(--unit) will not create 20px and is considered invalid.
Using initial with CSS Variables: Assigning initial to a CSS variable means it is invalid. To display initial as a value, it must be placed in the fallback.
url() and var() Usage: Since url() is treated as a complete CSS token, you need to define the full url() within the variable.

:root {
  /* 1. */
  margin: var(--b, 20px); /* Uses 20px if --b is invalid */

  /* 2. */
  padding: var(--c,) 20px; /* Falls back to 20px if --c is invalid */

  /* 3. */
  font-family: var(--fonts, "lucida grande", tahoma, Arial); /* Uses fallback font stack if --fonts is invalid */

  /* 4. */
  --text-size: 12;
  --text-unit: px;
  font-size: var(--text-size)var(--text-unit); /* Invalid, as it does not resolve to 12px */

  /* 5. */
  --initialized: initial;
  background: var(--initialized, initial); /* Results in background: initial */

  /* 6. */
  --invalid-url: "https://useme.medium.com";
  background: url(var(--invalid-url)); /* Invalid, as url() cannot parse var() */

  --valid-url: url(https://useme.medium.com);
  background: var(--valid-url); /* Correct usage */
}

Variable Resolution and Scope

CSS variables, like other CSS properties, follow CSS-specific rules for scope and specificity. Understanding how these factors affect CSS variables allows for more precise control.

Global and Scoped Variables:
Variables defined in :root are applied globally, while those defined in selectors have a more limited scope.

   :root {
     --main-color: blue; /* Globally applied */
   }

   .container {
     --main-color: green; /* Scoped, applies only within .container */
   }

Priority by Specificity:
Higher specificity will override lower specificity for CSS variables.

   :root {
     --main-color: blue;
   }

   .section {
     --main-color: green; /* Overrides :root definition */
   }

   .section p {
     color: var(--main-color); /* Shows green */
   }

   p {
     color: var(--main-color); /* Shows blue */
   }

   <div class="section">
     <p>This text will use .section's --main-color and be green.</p>
   </div>

   <p>This text will use :root's --main-color and be blue.</p>

Calculating Values Based on Specificity Order:
Like CSS properties, variables are resolved based on specificity in ascending order.

   :root {
     --red: 255;
     --green: 255;
     --blue: 255;
     --background: rgb(var(--red), var(--green), var(--blue));
   }

   .box {
     --green: 0;
     background: var(--background); 
   }

In this example, the background color of .box remains white, as --background was resolved to rgb(255, 255, 255) before .box redefined --green: 0.

Reevaluating Variables with Pseudo-Classes:
Variables change based on pseudo-class states when defined at the same level.

   :root {
     --red: 255;
     --green: 255;
     --blue: 255;
   }

   .box {
     --background: rgb(var(--red), var(--green), var(--blue));
     background: var(--background);
   }

   .box:hover {
     --green: 0; /* Changes background color on hover */
   }

Next, let’s explore some advanced use cases for CSS variables:

Usage Example A: Animations

CSS variables cannot be directly animated because the browser cannot infer the data type. To resolve this, use @property to define the variable's type and initial value, enabling the browser to understand how to animate the variable.

@property --green {
  syntax: "<number>";
  initial-value: 255;
  inherits: false;
}

.section {
  padding: 5em;
  background: rgb(50, var(--green), 50);
  transition: --green 0.5s;
}

.section:hover {
    --green: 50;
}

<div class="section">
  <p>Hover to see CSS variables + animation in action.</p>
</div>

In this example, @property is used to declare --green as a <number> type with an initial value of 255. When hovering over .section, --green changes to 50, creating a smooth color transition effect.

CodePen example

Usage Example B: Light/Dark Mode Toggle

If you want to implement theme switching for light and dark modes, it’s helpful to extract color values into variables that adjust automatically based on the prefers-color-scheme setting. Here’s how you can manage this using CSS variables.

:root {
  --background-color: #FBFBFB;
  --container-background-color: #EBEBEB;
  --headline-color: #0077EE;
  --text-color: #333333;
}

@media (prefers-color-scheme: dark) {
  :root {    
    --background-color: #121212;
    --container-background-color: #555555;
    --headline-color: #94B2E6;
    --text-color: #e0e0e0;
  }
}

Adding a Manual Toggle that Aligns with System Preferences

While the system setting controls the theme by default, we may want to give users the option to manually toggle between light and dark themes. To achieve this, we can add a checkbox to toggle the state. Ideally, when the checkbox is selected, it indicates dark mode, and when unselected, it represents light mode.

However, CSS cannot automatically detect system settings and change the checkbox state accordingly, especially in dark mode. To handle this limitation, we can use CSS variables and the :has() selector to control theme switching based on the checkbox state.

I wanted to try achieving this entirely with CSS, but since a user’s system may be set to either light or dark mode, CSS alone can’t automatically check the checkbox in dark mode.

If we can’t move the mountain, we’ll route the path. Here’s the workaround:

We’ll use CSS to create a toggle switch, where the visual “OFF” state represents light mode, and “ON” represents dark mode.

When system sets to light mode: When the checkbox is unselected, it corresponds to the “OFF” state (light mode). When selected, it corresponds to the “ON” state (dark mode).
When system sets to dark mode: Since the system preference is reversed, the visual state also inverts. When the checkbox is unselected, it corresponds to “ON” (dark mode). When selected, it corresponds to “OFF” (light mode).

To achieve this effect, we need two main elements:

First: Variables that Change Based on System Setting and Checkbox State

:root {
  --background-color: #FBFBFB;
  --container-background-color: #EBEBEB;
  --headline-color: #0077EE;
  --text-color: #333333;
}

:root:has(input[type="checkbox"]:checked) {
  --background-color: #121212;
  --container-background-color: #555555;
  --headline-color: #94B2E6;
  --text-color: #e0e0e0;
}

@media (prefers-color-scheme: dark) {
  :root {    
    --background-color: #121212;
    --container-background-color: #555555;
    --headline-color: #94B2E6;
    --text-color: #e0e0e0;
  }

  :root:has(input[type="checkbox"]:checked) {
    --background-color: #FBFBFB;
    --container-background-color: #EBEBEB;
    --headline-color: #0077EE;
    --text-color: #333333;
  }
}

Second: Toggle Behavior Based on System Settings for checked State and ON/OFF Representation

The light and dark mode CSS properties are reversed depending on the system setting.

/* Toggle Switch Styles */
.switch {
  position: relative;
  display: inline-block;
  width: 60px;
  height: 34px;
}

/* Hide the checkbox element to style a custom switch */
.switch input {
  opacity: 0;
  width: 0;
  height: 0;
}

/* Slider styling for the switch background */
.slider {
  position: absolute;
  cursor: pointer;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  background-color: var(--slider-bg, #ccc);
  transition: 0.4s;
  border-radius: 34px;
}

/* Slider knob styling */
.slider:before {
  position: absolute;
  content: "";
  height: 26px;
  width: 26px;
  left: 4px;
  bottom: 4px;
  background-color: white;
  transition: 0.4s;
  border-radius: 50%;
}

/* Dark mode styles: make the switch look "checked" by default */
@media (prefers-color-scheme: dark) {
  .slider {
    background-color: #94b2e6;
  }
  .slider:before {
    transform: translateX(26px); /* Move knob to the right */
  }

  /* Invert checked state in dark mode to look "unchecked" */
  input:checked + .slider {
    background-color: #ccc;
  }
  input:checked + .slider:before {
    transform: translateX(0); /* Move knob to the left */
  }
}

/* Light mode styles: make the switch look "unchecked" by default */
@media (prefers-color-scheme: light) {
  .slider {
    background-color: #ccc;
  }
  .slider:before {
    transform: translateX(0); /* Knob on the left */
  }

  /* Invert checked state in light mode to look "checked" */
  input:checked + .slider {
    background-color: #94b2e6;
  }
  input:checked + .slider:before {
    transform: translateX(26px); /* Move knob to the right */
  }
}

Simplifying Variable Setup with CSS Variable Tricks

Here we’ll use Space Toggle technique to simplify variable settings. Here’s the code, followed by an explanation of how it works:

:root {
  --ON: initial; /* Default state variable to use for switching colors */
  --OFF: ; /* Alternative state variable for switching colors */

  /* Set default color variables based on light mode */
  --light: var(--ON);
  --dark: var(--OFF);

  /* Define custom properties for colors used in light and dark modes */
  --background-color: var(--light, #fbfbfb) var(--dark, #121212);
  --container-background-color: var(--light, #ebebeb) var(--dark, #555555);
  --headline-color: var(--light, #0077ee) var(--dark, #94b2e6);
  --text-color: var(--light, #333333) var(--dark, #e0e0e0);
}

:root:has(input[type="checkbox"]:checked) {
  --light: var(--OFF);
  --dark: var(--ON);
}

The key here is in the line --background-color: var(--light, #fbfbfb) var(--dark, #121212);. Here, the background color depends on the values of --light and --dark, effectively simulating an if/else in the property.

How does it work? Initially, --light: var(--ON); and --ON: initial; make --ON an invalid state. Meanwhile, --OFF is set as an empty string. When applied to var(--light, #fbfbfb) var(--dark, #121212), the invalid --light variable will default to #fbfbfb, and the valid --dark variable (empty) allows --background-color to equal #fbfbfb.

All the other color variables follow the same logic, adjusting based on the state of --light and --dark. This way, each color variable only needs to be defined once.

Switching states becomes simple. If dark mode is active, use --light: var(--OFF); and --dark: var(--ON);. In light mode, reverse them. Though not immediately intuitive, this method is currently the most effective with CSS. If there are better solutions, they are worth exploring.

Complete example: CodePen Example

Summary

CSS continues to evolve, with CSS variables available in major browsers since 2016. New features like @property and :has() are expanding CSS variables’ flexibility even further. Combined with other new tools, CSS variables are becoming more powerful—for instance, they can now enhance scroll-driven animations to create visually dynamic effects. As a core element for storing state in CSS, much like variables in any programming language, a solid understanding of CSS variables will prove invaluable for more sophisticated styling and design down the road.

References

Thing You May Not Know About CSS Variables - 1. Naming Rules and Value Assignments

Fin Chen — Thu, 07 Nov 2024 04:39:50 +0000

In my exploration of CSS variables, I discovered a lot of exciting potential and subtle details that aren’t always apparent at first glance. Like many developers, I initially used CSS variables in simple, straightforward ways, rarely encountering edge cases. This approach is common and effective for many purposes, but it means there’s a lot more to explore and experiment with. In my view, gaining a deeper understanding of CSS variable naming rules and valid value assignments can significantly expand the range and flexibility of their applications.

I’ve compiled my research and insights here, aiming to provide a more thorough and comprehensive look at CSS variables. My hope is that this article will be a resource to help both you and myself unlock the full potential of CSS variables and discover new possibilities in styling.

This series assumes you’re already familiar with the basics of CSS variables, such as the --name: value syntax and the var(--name) function, or that you’re comfortable with the foundational concepts covered in the first third of this CSS Variables Introduction.

Naming Rules

When using CSS variables, naming is the first essential step. Here are some key guidelines for naming CSS variables:

Basic Prefix

All custom property names must begin with two hyphens (--), for example, --main-color. This prefix helps the browser distinguish custom properties from native CSS properties, reducing the chance of conflicts.

Case Sensitivity

CSS custom property names are case-sensitive, meaning --main-color and --Main-Color are treated as two entirely different variables. It's important to maintain consistent casing throughout your code to avoid mistakenly referencing variables with mismatched cases, which can lead to parsing errors.

Example:

   :root {
     --main-color: blue;
     --Main-Color: red; /* Case difference, treated as a separate property */
   }

   .box1 {
     color: var(--main-color); /* Refers to --main-color, resulting in blue */
   }

   .box2 {
     color: var(--Main-Color); /* Refers to --Main-Color, resulting in red */
   }

Reserved Words:

A standalone -- is reserved and may have specific purposes in future specifications. Therefore, avoid using it as a custom property name.
Example:

   :root {
     --: green; /* Invalid: a standalone -- is reserved */
     --custom-color: green; /* Valid: custom property avoids reserved name */
   }

   .text {
     color: var(--custom-color); /* Uses the custom property */
   }

Naming Restrictions:

When naming CSS variables, it’s crucial to consider allowed characters and conventions, which improve readability and prevent conflicts.

Allowed Characters:
- Alphabetic Characters: Uppercase and lowercase English letters (A-Z, a-z)
- Numbers: 0-9
- Hyphens: -
- Underscores: _
- Unicode Characters: Emojis or non-Latin characters (Unicode range U+0080 and above)
Escaping Special Characters: If a variable name includes special characters (such as & or ?), it can be represented using escape characters (\) or Unicode codes. For example, & can be written as \26. (Refer to Syntax and basic data types - Characters and case for more details).
Variable Length: While there are no strict limits on variable name length, for readability, it’s recommended to keep names under 50 characters. I did some experiment with Chromium, it can supports variable name length up to 1 million characters.

Example
The following example demonstrates the flexibility of CSS variable naming and how to handle special characters properly:

   :root {
     /* Naming with Unicode characters */
     --primary-color: #3498db;
     --secondary-color: #e74c3c;

     /* Using an Emoji as a variable name */
     --😺: #2ecc71;

     /* Special characters with escape sequences, resulting in --B&W? */
     --B\&W\?: #2ecc72;

     /* Using Unicode escape codes, equivalent to --B&W? */
     --B\26W\3F: #abcdef;
   }

   .container {
     color: var(--B\26W\3F); /* Result is #abcdef */
   }

   .container-alt {
     color: var(--B\&W\?); /* Result is #abcdef */
   }

Assigning Values

CSS variables can hold various types of values, but they also need to follow specific syntax rules. Let’s look at some examples of valid value assignments:

:root {
  --foo: if(x > 5) this.width = 10;
  --string-with-semicolon: "font-size: 16px;"; /* Strings can include semicolons */
  --complex-calc: calc(100% / 3 + 20px);       /* Complex calculations with calc() */
  --negative-value: -10px;                     /* Negative values */
  --multiple-values: 10px 20px 30px 40px;      /* Multiple values, e.g., for margin or padding */
  --unitless-number: 1.5;                      /* Unitless numbers */
  --nested-var: var(--string-with-semicolon);  /* Nested variables using var() */
  --empty-string: ;                            /* Empty string */
  --color: rgba(255, 0, 0, 0.5);               /* Color functions */
  --special-chars: "Content: \"Hello\"";       /* Strings with special characters */
}

As these examples show, CSS variables support a wide range of values. However, since CSS variables are part of CSS properties, they must follow general CSS syntax, such as matching quotes and parentheses. Let’s explore some values that don’t meet these requirements.

Invalid Values

Assigning invalid values to CSS variables can cause parsing errors, which may lead to issues in subsequent styles. Here are some examples of invalid value assignments:

:root {
  --incomplete-string: "Hello;           /* Invalid: missing closing quote */
  --incomplete-url: url(http://example.com/image.png; /* Invalid: missing closing parenthesis */
  --unmatched-parenthesis: calc(100% - 50%; /* Invalid: unclosed parenthesis in calc() */
  --invalid-exclamation: 50px !;          /* Invalid: only valid exclamation use is !important */
  --invalid-var: var(--undefined-variable); /* Invalid: var() references an undefined variable with no fallback */
}

Using `!important`

CSS variables, like other CSS properties, support the !important flag, which affects priority. Here’s an example showing how !important impacts variable precedence:

div {
  color: var(--text-color); 
}

.cls {
  --text-color: green !important;
}

#target {
  --text-color: red;
}

In this example, both #target and .cls affect the --text-color variable on the div. By selector specificity, #target should override .cls. However, because --text-color in .cls uses !important, the final color applied to div will be green. It’s important to note that !important only impacts priority among variables and does not propagate to the property referencing the variable. The resulting color is simply green, not green !important.

Using `initial`

:root {
  --invalid: initial;
}

Using initial as a CSS variable value is a unique behavior. When assigned to a variable, initial makes the variable invalid, causing it to fail when accessed with var(). This differs from an empty value (--empty: ;), which won’t cause a property to become invalid. Using initial effectively “resets” a variable, canceling its definition. (Reference)

Dependency Cycles

CSS variables support referencing other variables, but if a dependency cycle occurs, all variables in the cycle become invalid. Here’s an example of a dependency cycle:

:root {
  --one: calc(var(--two) - 1);
  --two: calc(var(--three) - 1);
  --three: calc(var(--one) + 2);
}

In this example, --one, --two, and --three reference each other, creating a cycle. As a result, all three variables become invalid due to the circular dependency, which prevents them from resolving. (Reference)

Conclusion

In this article, we’ve taken a deep dive into the rules of naming and value assignments for CSS variables, covering how to properly define and manage these variables while avoiding common parsing errors. With this foundational knowledge, you should be able to use CSS variables more effectively in your future development projects.

The next article will explore how to use var() to retrieve CSS variable values, along with specific application scenarios to make your use of CSS variables even more flexible and powerful.

A cursor trailing effect library for this Christmas

Fin Chen — Sat, 25 Dec 2021 00:22:54 +0000

We did a cursor trailing effect on our website. Learned how to do holiday effects the right way, experimented with Canvas and Transition, built a NPM library cursor-effect.
Here's our story...

How it started

I saw an ancient HTML spell the other day:

<MARQUEE><BLINK>
  How would you suppose this element behave?
</BLINK></MARQUEE>

Surprised by the fact it still works

Good job safari

It reminds me of the old days where cursor trail is a sexy effect. So I went googling but most result are telling you how to set cursor trail on Windows

Luckily there's Cursor Effects (tholman.com) , which seem to be used on StackOverflow before. So we implemented the same effect on our site: Yourator, with some customization tweaks. This post is what we've learned from implementing this effect, and we also published the effect as an npm library:

Cursor Trails: https://github.com/yourator/cursor-trails

the effect is up on production site til this weekend

Learn from the original cursor-effect library

src: https://github.com/tholman/cursor-effects/blob/master/src/snowflakeCursor.js

skeleton of init method

We only needed snowflake effect, so this is what we'll be talking about. The main flow of starts from init, which contains the basic working flow of this effect:

Initialize environment (canvas) for snowflakes
Draw emoji character (possibleEmoji) on canvas
bindEvents listens for mouse & touch event
loop updates snowflake continuously

`bindEvents` listens for mouse & touch event

We're doing the same thing in onMouseMove and onTouchMove : call addParticle upon the event and create a snowflake at where cursor is.

onWindowResize is responsible for adjusting canvas size.

Why not use CSS width: 100%, height: 100% ?

Since canvas is a canvas with assigned resolution, CSS can only adjust its visual size. If you create a canvas with 100px x 100px and stretch it to 200px x 1000px, then you'll have a 100px x 100px canvas (and pixels in it) which it stretched 2x wide and 10x long. So we need to adjust size of canvas according to window size.

The last line of init was a loop() call, to create an infinite loop using requestAnimationFrame. This loop is responsible to update snowflake position and behaviors, it will call update on each snowflake (particles), or clean up expiring snowflakes. This is the most CPU intensive part.

More detail on particle update: manage its own lifespan, position, rotating and draw snowflake emoji on canvas accordingly

Improvements

The original cursor-effect repo is a effect we need. But to be used on our site we have to add some improvements:

Use image arrays to render customizable images
We want to have more control over snowflake's behavior such as: appearing frequency, it's speed and life, etc.
Touch event on touch device will trigger mousemove and touchstart at the same time, generating two (almost overlapping) snowflakes at once.
We want to import this library through npm for easier maintainence

What we do

Use image arrays to render customizable images

Change the fillText with drawImage, also add calculation for snowflake opacity: globalAlpha . Since there are several canvas context manipulation, we use save & restore to prevent polluting original context.

And since image loading is async, we need loadImage handles the image url array

With the help of promise all (or Promise.allSettled) , to load image before init() call

Control snowflake's behavior over initialization options

Main benefit is this boosts prototyping and discussion productivity, you can live-tweak and quickly show the result, or even hand the prototype to stakeholders and let them decide the behaviors.

This part is simple, just don't forget the option defaults

Touch event on touch device will trigger mousemove and touchstart

bindEvent method listens for mousemove touchstart touchmove , but Touch event on touch device will trigger mousemove and touchstart on user touch, causing excess particle creation, you can see touch event order it on MDN. To prevent this we need to detect if this device is touch device or not

NPM-ify for easier maintainence

Uses ESM and published on NPM, use when in need.

npm install cursor-trails

Something learned about Canvas and Transition

Which we adjust cursor-effect to deal with image loading, FPS drops significantly, thought it was because we throw too many image creating at a short time. Even rewrite one version using CSS Transition, just to find out it was because mass creating of SVG element consumes a lot of CPU.

Canvas is very effective with drawing bitmap image in a fixed space. While CSS Transition suits animating DOM elements on the page. So creating lots of image element on canvas is more smooth then creating and transform it.

I must highlight chrome's devtool's "rendering" tab (edge has it also), especially two checked in this image

it shows fps and paint areas, as gif below

This was a version where we use CSS Transition, you can see image repaint areas

Other considerations

The effect is sexy (in a retro 90s way), but we shouldn't forgot this is not the main purpose of users on our site (they are here for job searching and career development). So after some discussion we decided to let this sexy feature reside only in the main search section at home page. It's spacey, it is what users first sees, it wont interfere with other thing users want to do. Hope this gets some balance with Christmas ambient and user's opration.

We we're planning to use prefers-reduced-motion to deal with low-end devices, but due to time limitation, that will be put on the roadmap.

This library now only have snow falling effect, hope we can have more strategies on particle behavior. Maybe even customizable strategy, ex: fixed, floating, fadeout of cursor trailing effects.

That's about it.
🎄❄️🧑‍🎄 Merry Christmas 🎄❄️🧑‍🎄

Here's our repo (again): https://github.com/yourator/cursor-trails

References

stackoverflow's april fools day effect
Mouse Trail - Noah Yamamoto (archive.org)
The technology of nostalgia (humphd.org)
When to Use SVG vs. When to Use Canvas - CSS-Tricks