l-writing

Writing and formatting rules for MDX articles in zcss. Use when: (1) Writing or editing MDX docs in src/content/docs/, (2) Creating new articles, (3) User says 'writing rules' or 'article format'. Aut...

Writing & MDX Rules for zcss Articles

Rules for writing CSS Best Practices articles. Follow these to keep every article consistent, direct, and useful for AI agents.

Audience

Primary readers are AI agents that consume these articles to learn CSS patterns. Human developers also read and maintain the docs. Write for both: precise enough for machines, clear enough for humans.

Tone

Professional, educational, and direct
No filler words, unnecessary hedging, or conversational padding
Active voice over passive voice
Short sentences over long ones
State facts; do not editorialize

OK/NG: Tone

OK (direct):

Flexbox centering requires a defined height on the parent container.

NG (hedging, filler):

It’s worth noting that you might want to consider setting a defined height on the parent container when using flexbox centering.

OK (active voice):

Use margin-inline: auto to center block elements horizontally.

NG (passive voice):

Block elements can be horizontally centered by using margin-inline: auto.

Article Structure

Every article follows this section order. Not all sections are required, but the order must be preserved.

The Problem — common mistakes or misunderstandings. State what goes wrong and why it matters.
The Solution — high-level approach. Keep it brief — details belong in code examples.
Code Examples — CSS (and HTML when needed) with inline commentary. Each technique gets its own sub-heading. Follow each code block with a CssPreview demo.
Live Previews — group CssPreview components here if not already inline above. Prefer inline placement.
Quick Reference — summary table: “Scenario” and “Technique” columns.
Common AI Mistakes — specific mistakes AI agents make. Bold the mistake, then explain.
When to Use — decision guidance by technique. Sub-headings, one or two sentences each.
Tailwind CSS — TailwindPreview equivalents. Optional — only when direct utility counterparts exist.
References — external links to MDN, web.dev, CSS-Tricks, etc.

CssPreview Demos

Every CSS concept must have a corresponding CssPreview demo. Demos are the most valuable part of each article. Prefer more demos over more prose.

CssPreview renders in an iframe with no JavaScript — all interactions must be CSS-only
Use hsl() colors, not hex
Use descriptive BEM-ish CSS class names (e.g., .card__title, .flex-center)
Keep demos minimal — show only the technique being explained
Every demo needs a descriptive title prop

OK/NG: Demo Colors

OK:

background: hsl(210, 50%, 95%);
color: hsl(210, 80%, 40%);

NG:

background: #f0f4f8;
color: #2563eb;

Writing Rules

Lead with Problems

Start articles with what goes wrong, not with what works. AI agents learn better from “do not do X because Y” than from “here is how to do X.”

One Concept Per Article

Each article covers one CSS technique or pattern. If the topic has enough depth, use the deep article pattern (folder with index.mdx + sub-pages).

No Subjective Judgment

Do not write “this is elegant” or “this is the best approach.” State what the technique does, when to use it, and the trade-offs.

OK (factual):

place-items: center is the most concise centering syntax — a single declaration replaces two.

NG (subjective):

place-items: center is an elegant and beautiful solution to the centering problem.

Do Not Repeat Generic CSS Knowledge

Assume the reader knows basic CSS. Focus on patterns, trade-offs, and common mistakes specific to the topic.

Use Tables for Comparisons

When comparing multiple approaches, use tables instead of prose. Tables are easier for AI agents to parse.

Code Before Prose

Show the code first, then explain it. Readers (especially AI agents) can often understand the code without explanation.

Deep Article Pattern

When a topic warrants multiple sub-pages, convert the flat .mdx file into a folder:

docs/layout/centering-techniques/
  index.mdx          # Overview + navigation
  margin-auto.mdx    # Sub-page
  flexbox.mdx        # Sub-page
  grid.mdx           # Sub-page

Markdown & MDX Formatting Rules

File Naming

Use kebab-case for all file names:

centering-techniques.mdx    OK
centeringTechniques.mdx     NG
Centering_Techniques.mdx    NG

Frontmatter

Every MDX file requires YAML frontmatter with at least sidebar_position:

---
sidebar_position: 3
---

Category index pages use sidebar_position: 0.

Import Patterns

Place imports immediately after frontmatter, before any content:

import CssPreview from '@/components/CssPreview';
import TailwindPreview from '@/components/TailwindPreview';

Headings

Article titles use h1 (the # Title at the top). All sections use h2 (##) or h3 (###).
Do not skip heading levels — go from h2 to h3, never h2 to h4.
Every heading must be followed by content before the next heading.

Lists

Do not mix ordered and unordered lists.
Do not put code blocks inside list items — place code blocks outside.

Bold

Bold is for inline emphasis only — not as section headings or list item headers.

Tables

Use tables for comparisons and quick-reference content. Keep tables simple with two or three columns.

Horizontal Rules

Do not use --- between sections. Headings provide sufficient visual separation. Use --- only for major topic shifts (e.g., separating appendix content).

Admonitions

Use sparingly. No imports needed.

:::note[Optional Title]
Supplementary information.
:::

Available types: note, tip, info, warning, danger. Use note and info for most cases.

CssPreview in MDX

<CssPreview client:load
  title="Flexbox Centering"
  html={`
<div class="flex-center">
  <div class="box">Centered</div>
</div>
  `}
  css={`
.flex-center {
  display: flex;
  justify-content: center;
  align-items: center;
  height: 200px;
  background: hsl(210, 50%, 97%);
}
.box {
  padding: 16px 24px;
  background: hsl(210, 80%, 55%);
  color: hsl(0, 0%, 100%);
  border-radius: 8px;
  font-family: system-ui, sans-serif;
}
  `}
/>

Rules:

Always provide a descriptive title prop
Use hsl() for all colors
Use descriptive BEM-ish class names
Keep HTML and CSS minimal
CSS-only interactions: :hover, :focus, :checked, :target, etc.
No JavaScript, no <script> tags

/css-wisdom — Before writing non-trivial CSS in demos or articles, invoke /css-wisdom <topic> to look up best practices. This ensures demos and article content align with the project’s CSS guidance.