DEV Community: Yoshinori Ishii

Rethinking Vanilla CSS for the AI Era

Yoshinori Ishii — Tue, 08 Sep 2026 00:54:39 +0000

I love vanilla CSS and want to keep using it as the language evolves. These days, AI agents write most of it for me. As my work shifted toward reviewing their output, I felt it was time to rethink CSS conventions.

I want fewer naming decisions to make and review. Wherever a rule can settle a class name, the same HTML and component structure should lead to the same answer, whoever writes it. The choices that remain should be explicit, and a linter should check the result. I am happy with detailed rules if they mean less guesswork for both the agent and me.

HTML already carries meaning through its native elements and ARIA roles. Choosing appropriate elements and using ARIA where needed helps make the interface accessible and gives an agent reading the HTML clear information about each element's role and state. I wanted CSS naming to draw on that existing meaning, so there would be fewer names to invent and review.

The markup already has a structure, too. Frameworks can keep markup and scoped styles together in a component, and native CSS nesting lets nested CSS blocks visually reflect its parent-child relationships without a preprocessor. That suggested a way to make both naming and structure easier to review while continuing to use plain CSS.

I built Nagi CSS to put that idea into practice: ordinary component CSS, with naming and structural rules that ESLint can check. The plugin supports Vue, Nuxt, Svelte, and Astro.

Start with the HTML

Consider the formatting controls you might put in a text editor: a small component that toggles Bold and Italic and reports which formats are active. The source filename, excluding its framework-specific extension, is format-controls; the project uses the class prefix app-.

First, look just at the HTML the component renders with Bold active:

<section class="app-format-controls">
  <h2 class="title">Text formatting</h2>
  <div class="unit">
    <span class="text">Apply to the current selection</span>
    <div class="group" role="group" aria-label="Text formatting">
      <button class="button -bold" type="button" aria-pressed="true">
        Bold
      </button>
      <button class="button -italic" type="button" aria-pressed="false">
        Italic
      </button>
    </div>
    <span class="status" role="status" aria-atomic="true">
      Active formatting: Bold.
    </span>
  </div>
</section>

Change the Bold button's button class to control, and ESLint reports that Nagi requires the class button for a <button> element. The tag supplies the name, and the linter checks it. Here is how the names in the rest of the example are determined or chosen.

Where the names come from

The base class identifies the element or part. In class="button -bold", it is button; -bold is a variant that distinguishes the Bold control.

Class	Naming rule
`app-format-controls`	The component source filename, without its framework-specific extension, plus the configured `app-` prefix
`title`	The fixed mapping for heading elements, `h1` through `h6`
`button`	The native element's tag name
`group`, `status`	The identifying `role` on each `div` or `span`
`text`	A name chosen from the allowed vocabulary for common UI parts
`unit`	A `div` used only for layout, with no suitable role or UI part name; assigned from a predefined vocabulary explained below
`-bold`, `-italic`	Static variants chosen by the author to distinguish the two button roles

The base classes in the first four rows follow directly from the file, elements, roles, and project configuration. These mappings give CSS a consistent class vocabulary: a heading keeps title whether its tag is h2 or h3, while a role-based status message uses status.

For a div or span without an identifying role, two fallbacks remain.

UI anatomy supplies a small vocabulary for common parts that HTML has no specific element for. Here, the short instruction uses text. The default vocabulary is field, value, actions, media, icon, and text, and projects can configure it. Choosing the appropriate part still requires judgment, but does not require inventing a word.

Structural Tier Names (STN) cover divs that only arrange other elements and have no suitable role or UI part name. Instead of inventing names such as wrapper or inner, nested structural wrappers move from larger to finer parts through a fixed sequence: unit → seg (segment) → fr (fragment) → g (grain). This example has only one such div, so it uses unit.

Variants let the author name stable distinctions such as Bold versus Italic. Anatomy involves choosing from an existing vocabulary; variants allow new words. Here, -bold and -italic identify each button's function, while its on/off state lives in aria-pressed.

The order matters: choose the HTML for its meaning, use its element or identifying role where available, then fall back to anatomy and structural tiers. The existing role="status" determines status; it was not added just to obtain that class name.

Write CSS against that structure

Now use those names in the same component's stylesheet. Inside the component root, > follows the actual parent-child relationships: the buttons are inside .group, which is inside .unit.

You only need selector paths for the elements you style; unrelated DOM branches need no CSS blocks. The relevant styles are ordinary nested CSS:

.app-format-controls {
  > .title { margin: 0; }

  > .unit {
    display: grid;
    gap: var(--space-4);

    > .text { color: var(--color-text-muted); }

    > .group {
      display: flex;
      gap: var(--space-3);

      > .button {
        &.-bold { font-weight: 700; }
        &.-italic { font-style: italic; }

        &[aria-pressed="true"] {
          background: var(--color-accent);
          color: var(--color-accent-text);
        }
      }
    }

    > .status { color: var(--color-text-muted); }
  }
}

If that looks like a lot of CSS to type, that is the part I usually delegate to an AI agent. I still have to read and maintain the result. Following the same naming and nesting rules gives me a consistent structure to review, while the linter checks the names and paths against the markup.

The buttons keep the same button -bold and button -italic classes as their state changes. The component updates aria-pressed, and CSS reads that attribute directly. The same state is exposed to assistive technology and used to style the active format.

The custom properties supply the project's design values. Nagi checks the contract; you choose the colors, spacing, and appearance.

Let the linter check the connection

Once names and selector paths follow rules, the linter can compare them with the source.

For example, rename the component root to .app-toolbar in both the markup and stylesheet. The styles can still work in the browser, but the lint rule named nagi-css/surface-root-name reports that a component source named format-controls requires .app-format-controls. The expected name no longer depends on what an author happens to choose.

It also checks relationships between otherwise valid names. This selector skips the group around the buttons:

.app-format-controls {
  > .unit {
    > .button { color: var(--color-accent); }
  }
}

Both unit and button exist in the template, but .unit > .button does not. Another lint rule, nagi-css/selector-mirrors-template, reports the mismatch. The correct path is .unit > .group > .button.

This matters during edits: when markup moves, a selector that still describes the old structure becomes a lint error. An agent and a human reviewer can check that relationship with the same command.

The repository includes passing and failing fixtures, exercised by ESLint tests, so these checks can be run against actual component source.

Keep each component's internals inside its boundary

That structure check stops at another component's root. To see why, place the format-controls component inside an editor-panel component:

<main class="app-editor-panel">
  <format-controls></format-controls>
</main>

The component tag is framework-neutral shorthand here. At that position, the child renders the .app-format-controls root shown earlier.

.app-editor-panel {
  display: grid;

  > .app-format-controls { inline-size: min(100%, 44rem); }
}

The parent controls the child's placement and available width. The child controls its internal layout and appearance. Because the child already has its file-derived app-format-controls root, the parent can select that root without passing another base class.

Reaching inside the child breaks that division:

.app-editor-panel {
  > .app-format-controls {
　  /* Invalid: .unit belongs to format-controls */
    > .unit { padding: 0; }
  }
}

The nagi-css/owned-surface-reach-in rule reports the attempt to style the child's private DOM. To change its internals, edit the child's CSS or use an input it explicitly exposes, such as a prop or CSS custom property.

Owning both source files does not give the parent a spare key to the child's DOM.

This is also why I agree with Tailwind's recommendation to reuse complex UI through components. In Nagi, the markup and its styles travel together, while the parent depends only on the child's root and exposed inputs.

How much naming remains?

This small example needed no new words for its base classes. To see how much vocabulary a broader set of UI components would need, I examined Nagi UI, an experimental library of common UI components I built under the Nagi CSS contract. I chose Vue because its templates keep the HTML directly visible.

Using Nagi CSS 0.4.0, I measured 31 component source files in Nagi UI's documentation site. All 555 explicit base-class occurrences required no new vocabulary. Their names either followed directly from the contract or came from its bounded anatomy vocabulary:

How the base class was named	Occurrences	Share of base classes
Derived directly from the contract	426	76.8%
Selected from the anatomy vocabulary	129	23.2%
Total requiring no new vocabulary	555	100.0%

The anatomy choices used just four words: actions, icon, text, and value.

Alongside the 555 base-class occurrences were 115 author-named variant occurrences, making up 17.2% of the 670 class occurrences in total. Like -bold and -italic in the opening example, these name stable distinctions. Nagi checks their form, ordering, and placement, but the author chooses the words.

The methodology and source data are public.

Let the agent write; review the decisions

In this workflow, an AI agent writes most of the markup and CSS, following the repository's agent skill. When moving an element changes its selector path, the agent updates that path too, then runs the linter to check conformance. The structural coupling remains, but maintaining those paths becomes part of the agent's work.

The human review can then concentrate on the decisions a rule cannot settle: whether the HTML semantics are correct, whether the component boundary makes sense, whether an anatomy or variant word expresses the intended role, and whether the result is accessible and visually correct.

Run the example, then change it

To make the example executable, the repository includes a concrete Vue implementation in examples/vue-minimal, with state, click handlers, a parent component, and design-token values.

Open it in StackBlitz, or run it locally with Node.js 22.18+ and the example's pinned pnpm version, 11.1.3:

git clone --depth 1 https://github.com/nagi-labs/nagi-css.git
cd nagi-css/examples/vue-minimal
pnpm install --frozen-lockfile
pnpm lint
pnpm dev

This is an independent project that installs the published plugin. You do not need to build Nagi CSS itself.

Toggle the buttons and watch their appearance and status message change. Then try one intentional mistake. In src/format-controls.vue, find the Bold button and change button to control in its class attribute, keeping -bold:

- class="button -bold"
+ class="control -bold"

Run pnpm lint. The <button> tag determines the class button, so Nagi reports the mismatch. Change control back to button to restore the passing example.

Use the same checks in your project

The package is the same across the supported integrations. Install the plugin first:

pnpm add -D @nagi-labs/eslint-plugin-nagi-css

Keep your framework's ESLint configuration and append Nagi CSS. The minimal configuration below uses Vue because it matches the runnable example:

import pluginVue from "eslint-plugin-vue"
import nagiCss from "@nagi-labs/eslint-plugin-nagi-css"

export default [
  ...pluginVue.configs["flat/essential"],
  ...nagiCss.configs.recommended({
    surfaceRootPrefixes: ["app-"],
  }),
]

The prefix is the same app- used throughout the article. Preserve any additional TypeScript and framework-specific settings in your project. There are setup guides for Vue, Nuxt, Svelte, and Astro.

To give your coding agent the Nagi CSS workflow, install the skill from your application repository's root with the skills CLI:

npx skills add nagi-labs/nagi-css --skill nagi-css

The installer detects supported coding agents and installs the skill for the current project. Restart the agent session after installation so it can discover the new instructions. If your agent does not support Agent Skills, use Nagi CSS's AGENTS.md as the compact fallback.

For the complete rules and their scope, see the full contract.

I would like to hear where this helps in your own components, and where it gets in the way. In particular: which naming choices would it remove for you, and which real refactor would make the structural rules too costly?

Acknowledgements

Nagi CSS would not exist in its current form without RSCSS by Rico Sta. Cruz.

RSCSS showed me that a small set of conventions—thinking in components, naming elements locally, and using direct-child selectors to protect component boundaries—could make CSS dramatically easier to reason about.

Nagi CSS takes those ideas in a more mechanically enforceable direction, deriving names from HTML and checking ownership boundaries statically. But its starting point is unmistakably RSCSS.

Thank you, Rico, for publishing an approach that has shaped how I think about CSS for years.

How close can explicit HTTP endpoints get to server-function DX?

Yoshinori Ishii — Sat, 05 Sep 2026 19:55:43 +0000

Next.js, SolidStart, TanStack Start, and SvelteKit all offer some form of server or remote functions. The integrations differ, but being able to connect server code to forms and data fetching is appealing.

I've used Nuxt since its early releases, and I like Nuxt 5's work on typed HTTP routes. Seeing those approaches develop made me wonder:

How much of that DX can we get while keeping an explicit HTTP endpoint as the starting point?

I'm trying this in Nuxt Endpoints. Routes keep their files, URLs, and HTTP methods. NE's defineRouteHandler() builds on the validated-routing design being discussed in H3 RFC #1437: request and response schemas alongside the handler, with a contract that other tools can read. NE implements and extends that design to connect it to client behavior, including pagination and forms. The upstream design is still under discussion; these examples use NE's implementation.

The closest existing comparison is oRPC, which already combines type-safe procedures, explicit OpenAPI routing, and Pinia Colada integration across frameworks. Nuxt Endpoints explores a more Nuxt-native trade-off: keeping file-based routes as the source of truth, avoiding a parallel procedure router, and deriving behavior such as cursor pagination directly from semantic HTTP contracts.

The idea is that a server contract should do more than type the response. It should constrain the handler and let the client use features that depend on that contract. A pagination adapter, for instance, should require a route that declares pagination.

Pagination: what the declaration buys you

Cursor pagination is a small example of the idea:

// server/api/articles.get.ts
import { z } from 'zod'
import { defineRouteHandler } from 'nuxt-endpoints/runtime'
import { listArticles } from '../utils/articles' // your database code

const Article = z.object({
  id: z.number(),
  title: z.string(),
})

export default defineRouteHandler({
  pagination: { kind: 'cursor', item: Article },
  handler: (event) => listArticles(event.validated.query),
})

This defines GET /api/articles. The database query and cursor encoding are your code. NE supplies the rest of the pagination contract:

the request has validated cursor and limit query fields;
the 200 response is { items: Article[], nextCursor?: string };
the handler's successful return must match that shape;
the generated OpenAPI document exposes those fields;
the client can use an adapter that requires this contract.

Returning { nextCursor } without items, for example, is a server-side type error. This page format is NE's convention, not an HTTP standard. The contract checks the shape; it cannot prove that your database query returns the right next page.

The client can pass the same typed request to Pinia Colada:

import { useInfiniteQuery } from '@pinia/colada'
import { infiniteQueryOptions } from '#endpoints/colada'

const articles = useInfiniteQuery(
  infiniteQueryOptions(
    $endpoint('/api/articles', { method: 'get' }),
  ),
)

infiniteQueryOptions() rejects an endpoint without the cursor-pagination contract at compile time. Nuxt Endpoints connects nextCursor to the next HTTP request; Pinia Colada owns the page cache, reactive state, and refetch lifecycle.

Handle responses by status

For a detail route declaring 200 with an article and 404 with a message, checking the status narrows the body type:

const result = await $endpoint('/api/articles/:id', {
  method: 'get',
  params: { id: '42' },
})

if (result.status === 200) {
  result.body.title
}

if (result.status === 404) {
  result.body.message
}

The 404 is a result you can handle, not a thrown fetch error. Network failures still reject the request. These types describe the declared responses; they cannot account for every response a proxy or other infrastructure might return.

The same route is callable from another service or with curl. Its HTTP interface is documented in the generated OpenAPI, so callers don't need NE to use it.

Forms, from the same contract

The experimental Nuxt 5 prototype applies the same idea to progressively enhanced forms. The server is still an explicit POST route:

// server/api/users.post.ts
import { z } from 'zod'
import { defineRouteHandler, formOf } from 'nuxt-endpoints/runtime'

const UserInput = z.object({
  name: z.string().min(1),
})

export default defineRouteHandler({
  form: {
    action: '/users/new',
    redirect: '/users/{id}',
  },
  validate: {
    body: {
      'application/json': UserInput,
      'application/x-www-form-urlencoded': formOf(UserInput),
    },
    response: {
      201: z.object({ id: z.number(), name: z.string() }),
    },
  },
  handler: (event) =>
    event.respond(201, {
      id: 1,
      name: event.validated.body.name,
    }),
})

On the Vue page:

<script setup lang="ts">
const form = useEndpointForm('/api/users', {
  method: 'post',
  body: { name: '' },
})
</script>

<template>
  <form v-bind="form.attrs" @submit="form.enhance">
    <label>
      Name
      <input v-bind="form.fields.name" />
    </label>

    <p v-for="issue in form.issues.name" :key="issue.message">
      {{ issue.message }}
    </p>

    <button>Create</button>
  </form>
</template>

useEndpointForm requires a compatible form contract. It checks body values and field names against the input schema, so a field such as form.fields.email would be a type error here. Build-time checks reject requirements that a native form cannot satisfy, such as a mandatory custom request header.

NE generates the form attributes and connects server validation issues to form.issues. The progressive-enhancement documentation covers the generated submission route and the browser tests with and without JavaScript.

What is available today?

The published Nuxt 4 version includes pagination, status-aware requests, Pinia Colada adapters, OpenAPI generation, and idempotency. These are ported into the module using its own implementation.

The Nuxt 5 branch is where I'm experimenting with upstream integration and progressive enhancement. It requires prototype forks. The extensions in those forks have not been accepted upstream.

I'm following Nuxt's merged fetchdts route-typing PR, which generates $fetch and useFetch types from reported server routes, Nitro's removal of its previous typed-fetch implementation, and the September Nitro 3 beta. I'd like to contribute the contract introspection and type-inference pieces that downstream tools need, and reuse them in NE. The aim is less duplicated code while keeping NE's application APIs as stable as practical.

You can see the current split and setup instructions on the Nuxt 5 progress page.

Why not make every remote operation a function?

Server functions can expose HTTP controls, and these frameworks also support explicit API routes. I prefer starting with the route itself.

For a simple GET, I want to write a simple GET. When I need pagination or form integration, I want to opt into that abstraction for that purpose. I can see the extra requirements in the declaration and inspect the resulting HTTP interface in OpenAPI.

NE still introduces conventions: pagination and form are examples. That's fine with me as long as I can see what they add and call the endpoint without the generated client.

These examples don't cover everything server functions offer. NE doesn't yet provide automatic cache revalidation after a mutation, for example. What I've been able to build so far makes me want to keep exploring this approach.

What part of server-function DX would be hardest—or most valuable—to reproduce this way?