@teacss/preset-articles

Purpose

@teacss/preset-articles is the official opt-in content preset for blogs, documentation, CMS output, and other pages whose semantic long-form HTML needs a readable baseline. It provides three fixed semantic-descendant utilities — article:base for mixed Latin and CJK, and article:hans and article:hant for simplified and traditional Chinese — all of which style supported descendants rather than the article scope.

This package does not implement TeaCSS parsing or generation; that remains the role of @teacss/core. It also does not replace @teacss/preset-standard, which supplies the ordinary layout, size, color, and condition utilities used to style the article scope, and it does not include the Iconify vocabulary from @teacss/preset-icons. There are no article-specific modifiers, theme, or merge plugin.

Usage

Select the preset explicitly in the TeaCSS CSS entry. The standard preset is optional, but it supplies the normal layout, size, color, condition, and important utilities used in this example.

@preset "standard";
@preset "articles";

@teacss;

<article
  class="article:base max-inline-size:65ch m-a:auto font-size:3x text-color:$color-foreground"
>
  <h1>Title</h1>
  <p>Readable long-form content.</p>
</article>

article:base adds declarations only to supported semantic descendants and sets nothing at all on the article scope: not its width, centering, font, color, line height, or breakpoint behavior. Compose those decisions with ordinary utilities:

<article
  class="article:base max-inline-size:65ch font-size:3x font-size:4x@md text-color:blue-900@_a"
>
  ...
</article>

The Chinese variants do declare on the scope, because a face and a glyph set are inherited and every descendant has to share them; what they set is described below. Autocomplete enumerates and prefix-suggests all three utilities when this preset is configured.

The utility's rules default to TeaCSS's built-in shortcuts layer (LAYER_SHORTCUTS). Under the default layer order, they are emitted before ordinary utilities in the utilities layer. Article selectors also have zero specificity, so a normal targeted utility can override the article utility's declarations. Conditions such as article:base@hover, article:base@dark, and article:base@md apply to the article scope before semantic descendants are selected. Pseudo-element conditions do not represent an article scope and generate no article CSS.

Exclude application UI embedded in an article with the presence attribute:

<section data-teacss-article-exclude>
  Application UI
</section>

The marked element and its descendants receive no direct declarations from this preset. The marker does not reset inherited CSS or block application selectors, and a nested article:base utility does not re-enable the excluded subtree.

Chinese variants

article:hans and article:hant select simplified or traditional Chinese. They are separate variants rather than one because the two scripts do not share a face. font-variant-east-asian: simplified | traditional is the mechanism CSS provides for the choice, but it only bites where a single font carries both glyph sets; in practice the two ship as separate families, so the font stack is what actually decides. This is the one place the preset names a font, and an ordinary font-family: utility overrides it, since utilities sort after this preset's shortcut layer.

Both start from everything article:base emits and add what Han text needs on top:

• text-autospace: normal inserts the gap Chinese typesetting expects between Han and adjacent Latin or digits; text-spacing-trim: space-first squeezes the fullwidth padding out of adjacent punctuation (标点挤压). Both are CSS Text 4 and degrade to today's spacing where a browser has not shipped them.
• line-break: strict keeps a line from opening with closing punctuation or ending with an opening one (避头尾), and word-break: normal leaves Latin words whole so the CJK breaker does the work.
• Leading rises to 1.8 for body text and 1.4 for headings, since Han lines carry more ink than Latin ones. Paragraphs are separated by the space between them and are not indented, which is how Chinese reads on the web.
• Body text is justified with text-justify: inter-character, which lands evenly across uniform-width Han glyphs.
• max-inline-size: 36em caps the measure: with uniform-width glyphs the comfortable measure is countable, roughly 36 characters a line.
• Link underlines gain text-underline-offset so they clear the Han glyphs they would otherwise cut through, and ruby annotations sit over the base text for pinyin and bopomofo.

Vertical Chinese

Direction is not a variant. writing-mode is an ordinary property, so the standard preset's utility composes with either script instead of doubling the vocabulary:

<article class="article:hant writing-mode:vertical-rl">...</article>

The shared table is written in logical properties throughout, so its block and inline axes turn with the flow rather than needing a second table — including the measure, since max-inline-size bounds the axis text runs along, which is line length horizontally and column height once turned.

pre is the one element that does not turn: the Chinese variants pin it to writing-mode: horizontal-tb, which restates the initial value until the article turns and then keeps code from losing every alignment it has. That pin makes the code block an orthogonal box, and margins resolve in the box's own writing mode — so a logical margin-block would land on the column's cross axis and stop separating the code from the text around it. The variants give pre a physical margin instead, which clears the text in either flow at the cost of a matching inset on the flat page.

Upright two-digit runs (縦中横) are not automatic. text-combine-upright: digits <n> has shipped in no engine — only the all value has, and all needs an inline wrapper around each number, which no scope-level rule can supply. Wrap those numbers in text-combine-upright:all where a turned article needs them.

Columns accumulate along the horizontal block axis, so that is where a turned article overflows; bound it with an ordinary overflow-x: utility on the container. Every scope declaration is a default an ordinary utility overrides, since utilities sort after this preset's shortcut layer.

JavaScript

The factory has no options. Its default and named exports are the same function:

import presetArticles, { presetArticles as namedPresetArticles } from "@teacss/preset-articles";

presetArticles === namedPresetArticles;

The same exports are available from teacss/preset-articles when using the application package. The root teacss entry does not re-export the factory, and the preset has no merge plugin.

Status

Pre-1.0. The fixed semantic-descendant utility has no article-specific size, width, color, theme-mode, or invert vocabulary.

License

MIT. See LICENSE.