//! moss component contract — Source 2 of the federated contract.
//!
//! Single source of truth for every `moss-*` class moss currently emits.
//! Each entry declares: the class name, its kind (container/instance/standalone/chrome),
//! accepted `data-*` attributes with value spaces, example HTML, example markdown.
//!
//! ## Adding a new emitter class
//!
//! 1. Emit the class from your renderer module (`build/markdown/*`, `build/components/*`).
//! 2. Add a `ComponentEntry` to [`COMPONENTS`] here.
//! 3. Run `cargo test --test components_sync_test` from src-tauri/ — the
//! scanner test will fail if you forget.
//! 4. Run `cargo run --bin generate-artifacts --features dev-tools -- contract-docs` to
//! refresh `docs/reference/contract.md`.
//!
//! ## Why a const table, not a derive macro?
//!
//! Mirrors the BUILTIN_FIELDS precedent in `schema_fields.rs`. The synchronization
//! is enforced by a sync test (`emitter_classes_match_components_table`) that
//! scans emitter Rust source for `class="moss-..."` literals. This is a
//! best-effort scanner (won't catch classes assembled via `format!()`), not a
//! type-checked guarantee like BUILTIN_FIELDS' compile-time mirror. The
//! limitation is documented in the spec § Source 2.
/// Status of a component entry.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Status {
/// In active use; theme authors can rely on it.
Confirmed,
/// Emerging convention; may evolve.
Emerging,
/// Scheduled for removal; theme authors should migrate.
Retired,
}
/// A declared `data-*` attribute on a component.
pub struct DataAttr {
/// Attribute name including `data-` prefix (e.g. `"data-layout"`).
pub name: &'static str,
/// Allowed values (e.g. `&["grid", "list", "minimal"]`). Empty means free-form.
pub values: &'static [&'static str],
/// Default value (first in `values`, or `""` for free-form).
pub default: &'static str,
/// Short description shown in reference.md.
pub description: &'static str,
}
/// A single component contract entry.
pub struct ComponentEntry {
/// Class name without leading `.` (e.g. `"moss-cards"`).
pub class: &'static str,
/// Container / Instance / Standalone / Chrome.
pub kind: &'static str,
/// For Instance kinds, the parent container's class (or `""`).
pub parent: &'static str,
/// Declared `data-*` attributes on the element with this class.
pub data_attrs: &'static [DataAttr],
/// Example HTML snippet showing the class in context. Multi-line allowed.
pub example_html: &'static str,
/// Example markdown that produces this HTML. Empty for HTML-only chrome.
pub example_markdown: &'static str,
/// Status: confirmed / emerging / retired.
pub status: Status,
/// Contract version this entry was introduced in.
pub since: &'static str,
/// Optional human-readable description.
pub description: &'static str,
}
/// Classes in [`COMPONENTS`] that deliberately carry no `moss-` prefix.
///
/// Every other entry must be `moss-`-prefixed; `every_component_has_a_class_name`
/// enforces that and consults this list for the exceptions. The list lives here,
/// beside the table, rather than in the test: an unprefixed class is a decision
/// made when the entry is *written*, and a reviewer reading the entry has to be
/// able to see that the decision was made. It was in the test file until
/// 2026-08-06, and the split cost a red build — declaring the masthead and nav
/// interior added 21 unprefixed entries whose exemption had to be recorded in a
/// file nobody editing the table had open.
///
/// Two families, both emitted for **theme parity** — themes written against
/// these names predate the `moss-` convention, so renaming them would break
/// styling moss does not own:
///
/// - Obsidian-style callouts (`callout`, `callout-<type>`), emitted alongside
/// their `moss-callout` equivalents.
/// - The nav interior and article masthead (`main-nav`, `date-line`, …).
///
/// Prefix matching is deliberate for the callout family only: `callout-<type>`
/// is an open set that grows with the callout vocabulary. The chrome names are
/// a closed set and are listed exactly, so a typo'd new one still fails.
pub const UNPREFIXED_LEGACY_CLASSES: &[&str] = &[
// Obsidian callout parity — `callout-*` is matched by prefix, see below.
"callout",
// Nav interior.
"main-nav",
"nav-left",
"nav-right",
"nav-links",
"nav-icons",
"nav-search-btn",
"nav-theme-btn",
"nav-lang-toggle",
"nav-lang-current",
"nav-lang-link",
"search-icon",
"theme-toggle-icon",
"mobile-menu-button",
"site-name",
"site-logo",
"breadcrumb-segment",
"breadcrumb-label",
"breadcrumb-separator",
// Article masthead.
"date-line",
"date",
// Default footer.
"footer-default",
"footer-link",
];
/// Whether `class` is exempt from the `moss-` prefix rule.
///
/// See [`UNPREFIXED_LEGACY_CLASSES`]. The `callout-` prefix arm covers the
/// open-ended Obsidian callout types (`callout-note`, `callout-warning`, …).
pub fn is_unprefixed_legacy(class: &str) -> bool {
class.starts_with("callout-") || UNPREFIXED_LEGACY_CLASSES.contains(&class)
}
/// The full contract surface — every `moss-*` class moss currently emits.
///
/// Phase 0b seeds this with the CURRENT emitted vocabulary (not the
/// v1-collapsed shape). Phase 1c rewrites to the collapsed form.
pub const COMPONENTS: &[ComponentEntry] = &[
ComponentEntry {
class: "moss-cards",
kind: "container",
parent: "",
data_attrs: &[
DataAttr {
name: "data-layout",
values: &["grid", "list", "minimal"],
default: "grid",
description: "Card layout density. Grid: 2-3 cols with covers. List: single column with side covers. Minimal: text-only with year groupings.",
},
DataAttr {
name: "data-density",
values: &["default", "compact"],
default: "default",
description: "Vertical spacing density.",
},
DataAttr {
name: "data-list-axis",
values: &["date", "weight", "title"],
default: "title",
description: "Sort axis for the listing (mirrors the folder's `sort:` frontmatter). Drives `--moss-card-min` density tuning and decides whether each `.moss-card-meta` slot is filled (date axis) or omitted (weight/title axes).",
},
DataAttr {
name: "data-list-has-covers",
values: &[""],
default: "",
description: "Boolean presence flag: emitted iff any child card has a cover. Combines with `data-list-axis` to widen `--moss-card-min` for cover-led layouts. Use `[data-list-has-covers]` in CSS to target it.",
},
],
example_html: r#"<div class="moss-cards-container">
<div class="moss-cards" data-layout="grid" data-list-axis="date" data-list-has-covers>
<a class="moss-card" href="...">...</a>
<a class="moss-card" href="...">...</a>
</div>
</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Auto-generated listing of child pages. The single canonical container; layout density on `data-layout` (`grid` for cover-led tiles, `list` for cover+excerpt rows, `minimal` for text-only year-grouped indexes). Wrapped in `.moss-cards-container` to scope CSS container queries.",
},
ComponentEntry {
class: "moss-cards-container",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-cards-container">
<div class="moss-cards" data-layout="grid">...</div>
</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Outer wrapper around `.moss-cards` that carries `container-type: inline-size` so the grid can use `@container` queries instead of viewport `@media` queries. Layout-agnostic — wraps any `data-layout` variant.",
},
ComponentEntry {
class: "moss-summary-layout",
kind: "container",
parent: "moss-cards",
data_attrs: &[],
example_html: r#"<div class="moss-cards" data-layout="list">...</div>"#,
example_markdown: "",
status: Status::Retired,
since: "1",
description: "Retired: the additional co-class on `.moss-cards[data-layout=\"list\"]` had no matching rules in the default CSS once `children_style: summary` collapsed into the list-layout block, and its lingering emission broke themes that hid the class (e.g. SoCiviC's `.moss/theme/style.css` keyed `display: none` on it, erasing folder-embed listings). Theme authors targeting summary listings should use `.moss-cards[data-layout=\"list\"]` directly.",
},
// -------------------------------------------------------------------
// Cards family — current emitted vocabulary (pre-Phase 1c collapsing).
// Three parallel layouts: grid, list, minimal. Each has its own
// container + instance + sub-classes.
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-cards-grid",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-cards-grid">
<a class="moss-card-grid" href="...">...</a>
</div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-cards[data-layout=grid]`.",
},
ComponentEntry {
class: "moss-cards-list",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-cards-list">
<a class="moss-card-list" href="...">...</a>
</div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-cards[data-layout=list]`.",
},
ComponentEntry {
class: "moss-cards-minimal-year-group",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r#"<section class="moss-cards-minimal-year-group">
<h3>2024</h3>
<div class="moss-card-minimal">...</div>
</section>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Year-grouped section in minimal card layout (e.g. blog index). Modifier `--summary` collapses past years.",
},
ComponentEntry {
class: "moss-cards-minimal-year-group--summary",
kind: "container",
parent: "moss-cards-minimal-year-group",
data_attrs: &[],
example_html: r#"<section class="moss-cards-minimal-year-group moss-cards-minimal-year-group--summary">...</section>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "BEM modifier on `.moss-cards-minimal-year-group`. Applied to year groups that should render in collapsed summary form (e.g. past years on a blog index).",
},
ComponentEntry {
class: "moss-card",
kind: "instance",
parent: "moss-cards",
data_attrs: &[
DataAttr {
name: "data-linkblog",
values: &[],
default: "",
description: "Presence flag: emitted IFF the card's source page has an `external_url:` frontmatter (linkblog pattern). When set, the element is a `<div>` rather than `<a>` so the kicker can host a nested `<a>★</a>` archive link; title, cover, and description carry their own inner anchors to the canonical URL. Absent on ordinary cards (single whole-card `<a>`).",
},
],
example_html: r#"<a class="moss-card" href="...">...</a>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "v1 collapsed shape — single canonical instance class inside `.moss-cards`. Layout-specific styling targets `.moss-cards[data-layout=X] .moss-card`. Tag is `<a>` for ordinary cards and `<div>` for linkblog cards (`[data-linkblog]`).",
},
ComponentEntry {
class: "moss-card-cover",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<div class="moss-card-cover"><img src="..." /></div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Cover media slot inside `.moss-card`. Gets `.moss-card-no-cover` modifier when no image is present.",
},
ComponentEntry {
class: "moss-card-no-cover",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<div class="moss-card-cover moss-card-no-cover"></div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Modifier applied to `.moss-card-cover` when no cover media is available.",
},
ComponentEntry {
class: "moss-card-content",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<div class="moss-card-content">...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Text content slot inside a grid-layout `.moss-card` (kicker + title + meta).",
},
ComponentEntry {
class: "moss-card-row",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<div class="moss-card-row">...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Row wrapper inside a list-layout `.moss-card` holding body + cover side-by-side.",
},
ComponentEntry {
class: "moss-card-body",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<div class="moss-card-body">...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Text body slot of a list-layout `.moss-card`.",
},
ComponentEntry {
class: "moss-card-head",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<div class="moss-card-head">...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Header row of a `.moss-card-body` (title + kicker + meta).",
},
ComponentEntry {
class: "moss-card-title",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<h3 class="moss-card-title">Page title</h3>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Title inside `.moss-card`.",
},
ComponentEntry {
class: "moss-card-meta",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<div class="moss-card-meta">2024-01-15</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Type-aware metadata slot (date for articles, count for folders, domain for links). Renders ABOVE the title in horizontal mode — filling the kicker position when the explicit `kicker` slot is unset, per `docs/reference/design/preview-cards.md:22-30`. To the right of the title in vertical CJK mode (the horizontal kicker position transposed). Meta IS the visual kicker, with the same uppercase overline treatment.",
},
ComponentEntry {
class: "moss-card-kicker",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<span class="moss-card-kicker">Category</span>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Eyebrow / overline above the title inside `.moss-card`.",
},
ComponentEntry {
class: "moss-card-permalink",
kind: "instance",
parent: "moss-card-kicker",
data_attrs: &[],
example_html: r#"<a class="moss-card-permalink" href="/posts/foo/" title="Permalink to 'Title'">★</a>"#,
example_markdown: "",
status: Status::Emerging,
since: "1",
description: "Author's-archive link mark (★, U+2605) emitted INSIDE `.moss-card-kicker` for linkblog cards (those whose child page has `external_url:`). The card title links to the external canonical (publisher); the `★` links to the local archival copy at the page's slug. Reads as part of the kicker line — \"Publisher · Year ★\". Semantically distinct from Daring-Fireball's linkblog ★ (which marks discussion permalink alongside commentary) — here the local copy is the same content preserved for resilience and stable bylines, not added commentary. Putting `<a>★</a>` inside the kicker is valid because linkblog cards emit `<div class=\"moss-card\" data-linkblog>` (not `<a>`) as the outer element — see the `data-linkblog` attribute described on `.moss-card`.",
},
ComponentEntry {
class: "moss-card-title-link",
kind: "instance",
parent: "moss-card-head",
data_attrs: &[],
example_html: r#"<a class="moss-card-title-link" href="https://outlet.example/article"><h3 class="moss-card-title">Article Title</h3></a>"#,
example_markdown: "",
status: Status::Emerging,
since: "1",
description: "Anchor wrapping the `.moss-card-title` `<h3>` on linkblog cards. Ordinary cards have the whole-card `<a class=\"moss-card\">` as the link target — but linkblog cards switch the outer to `<div>` so the kicker can host a nested `★` anchor, which means the title needs its own anchor to stay clickable. Same canonical-URL target as the other inner anchors (`moss-card-cover-link`, `moss-card-description-link`).",
},
ComponentEntry {
class: "moss-card-cover-link",
kind: "instance",
parent: "moss-card-row",
data_attrs: &[],
example_html: r#"<a class="moss-card-cover-link" href="https://outlet.example/article"><div class="moss-card-cover">...</div></a>"#,
example_markdown: "",
status: Status::Emerging,
since: "1",
description: "Anchor wrapping the `.moss-card-cover` on linkblog cards — same role as `.moss-card-title-link` but for the cover image / media. Targets the canonical (external) URL.",
},
ComponentEntry {
class: "moss-card-description-link",
kind: "instance",
parent: "moss-card-body",
data_attrs: &[],
example_html: r#"<a class="moss-card-description-link" href="https://outlet.example/article"><p class="moss-card-description">…</p></a>"#,
example_markdown: "",
status: Status::Emerging,
since: "1",
description: "Anchor wrapping the `.moss-card-description` on linkblog cards — same role as `.moss-card-title-link` but for the description excerpt. Targets the canonical (external) URL.",
},
ComponentEntry {
class: "moss-card-description",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<p class="moss-card-description">Excerpt...</p>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Excerpt / description paragraph inside a `.moss-card` — below the title in both grid- and list-layout cards.",
},
ComponentEntry {
class: "moss-card-count",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<div class="moss-card-count">4 articles</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Tertiary subtitle line showing `N articles` for a folder card. Renders only on non-date listings when the folder card has no `description` to display.",
},
ComponentEntry {
class: "moss-embed-more",
kind: "instance",
parent: "moss-cards-container",
data_attrs: &[],
example_html: r#"<p class="moss-embed-more"><a href="/news/">More →</a></p>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Trailing \"More →\" link on a truncated children listing (emitted when `children_limit` caps the embed); links to the folder's full index. Rendered as a sibling immediately after `.moss-cards-container`, so it sits outside the listing's flex `gap` and binds to the list via its own `margin-top` (see docs/reference/design/spacing.md).",
},
ComponentEntry {
class: "moss-card-grid",
kind: "instance",
parent: "moss-cards-grid",
data_attrs: &[],
example_html: r#"<a class="moss-card-grid" href="...">...</a>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card` (with parent `.moss-cards[data-layout=grid]`).",
},
ComponentEntry {
class: "moss-card-grid-cover",
kind: "instance",
parent: "moss-card-grid",
data_attrs: &[],
example_html: r#"<div class="moss-card-grid-cover"><img src="..." /></div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-cover`.",
},
ComponentEntry {
class: "moss-card-grid-no-cover",
kind: "instance",
parent: "moss-card-grid",
data_attrs: &[],
example_html: r#"<div class="moss-card-grid-cover moss-card-grid-no-cover"></div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-no-cover`.",
},
ComponentEntry {
class: "moss-card-grid-content",
kind: "instance",
parent: "moss-card-grid",
data_attrs: &[],
example_html: r#"<div class="moss-card-grid-content">...</div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-content`.",
},
ComponentEntry {
class: "moss-card-grid-kicker",
kind: "instance",
parent: "moss-card-grid",
data_attrs: &[],
example_html: r#"<span class="moss-card-grid-kicker">Category</span>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-kicker`.",
},
ComponentEntry {
class: "moss-card-grid-title",
kind: "instance",
parent: "moss-card-grid",
data_attrs: &[],
example_html: r#"<h3 class="moss-card-grid-title">Page title</h3>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-title`.",
},
ComponentEntry {
class: "moss-card-grid-meta",
kind: "instance",
parent: "moss-card-grid",
data_attrs: &[],
example_html: r#"<div class="moss-card-grid-meta">2024-01-15</div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-meta`.",
},
ComponentEntry {
class: "moss-card-list",
kind: "instance",
parent: "moss-cards-list",
data_attrs: &[],
example_html: r#"<a class="moss-card-list" href="...">...</a>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card` (with parent `.moss-cards[data-layout=list]`).",
},
ComponentEntry {
class: "moss-card-list-row",
kind: "instance",
parent: "moss-card-list",
data_attrs: &[],
example_html: r#"<div class="moss-card-list-row">...</div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-row`.",
},
ComponentEntry {
class: "moss-card-list-cover",
kind: "instance",
parent: "moss-card-list",
data_attrs: &[],
example_html: r#"<div class="moss-card-list-cover"><img src="..." /></div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-cover`.",
},
ComponentEntry {
class: "moss-card-list-body",
kind: "instance",
parent: "moss-card-list",
data_attrs: &[],
example_html: r#"<div class="moss-card-list-body">...</div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-body`.",
},
ComponentEntry {
class: "moss-card-list-head",
kind: "instance",
parent: "moss-card-list",
data_attrs: &[],
example_html: r#"<div class="moss-card-list-head">...</div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-head`.",
},
ComponentEntry {
class: "moss-card-list-kicker",
kind: "instance",
parent: "moss-card-list",
data_attrs: &[],
example_html: r#"<span class="moss-card-list-kicker">Category</span>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-kicker`.",
},
ComponentEntry {
class: "moss-card-list-title",
kind: "instance",
parent: "moss-card-list",
data_attrs: &[],
example_html: r#"<h3 class="moss-card-list-title">Page title</h3>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-title`.",
},
ComponentEntry {
class: "moss-card-list-meta",
kind: "instance",
parent: "moss-card-list",
data_attrs: &[],
example_html: r#"<div class="moss-card-list-meta">2024-01-15</div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-meta`.",
},
ComponentEntry {
class: "moss-card-list-description",
kind: "instance",
parent: "moss-card-list",
data_attrs: &[],
example_html: r#"<p class="moss-card-list-description">Excerpt...</p>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-description`.",
},
ComponentEntry {
class: "moss-card-minimal",
kind: "instance",
parent: "moss-cards-minimal-year-group",
data_attrs: &[],
example_html: r#"<div class="moss-card-minimal">
<a class="moss-prefix-link" href="...">...</a>
</div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card` (with parent `.moss-cards[data-layout=minimal]`).",
},
ComponentEntry {
class: "moss-folder-item",
kind: "instance",
parent: "moss-cards-minimal-year-group",
data_attrs: &[],
example_html: r#"<div class="moss-card-minimal moss-folder-item">
<a class="moss-prefix-link moss-folder-link" href="...">...</a>
<p class="moss-folder-description">...</p>
</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Modifier on `.moss-card-minimal` for folder-type entries in minimal listings.",
},
ComponentEntry {
class: "moss-folder-title",
kind: "instance",
parent: "moss-folder-item",
data_attrs: &[],
example_html: r#"<span class="moss-folder-title">Folder name</span>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Title text of a folder entry in minimal listings.",
},
ComponentEntry {
class: "moss-folder-description",
kind: "instance",
parent: "moss-folder-item",
data_attrs: &[],
example_html: r#"<p class="moss-folder-description">Description...</p>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Description paragraph of a folder entry in minimal listings.",
},
ComponentEntry {
class: "moss-folder-link",
kind: "instance",
parent: "moss-folder-item",
data_attrs: &[],
example_html: r#"<a class="moss-prefix-link moss-folder-link" href="...">...</a>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Modifier on `.moss-prefix-link` for folder-type links in minimal listings.",
},
// -------------------------------------------------------------------
// Prefix-link primitive — used by minimal cards and other listings.
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-prefix-link",
kind: "instance",
parent: "moss-card-minimal",
data_attrs: &[],
example_html: r#"<a class="moss-prefix-link" href="...">
<span class="moss-prefix-link-prefix">2024-01-15</span>
<span class="moss-prefix-link-title">Page title</span>
</a>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Link with a prefix span (date or icon) and a title span. Used inside minimal cards.",
},
ComponentEntry {
class: "moss-prefix-link-prefix",
kind: "instance",
parent: "moss-prefix-link",
data_attrs: &[],
example_html: r#"<span class="moss-prefix-link-prefix">2024-01-15</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Prefix slot of a prefix-link (typically a date).",
},
ComponentEntry {
class: "moss-prefix-link-title",
kind: "instance",
parent: "moss-prefix-link",
data_attrs: &[],
example_html: r#"<span class="moss-prefix-link-title">Page title</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Title slot of a prefix-link.",
},
ComponentEntry {
class: "moss-prefix-link-suffix",
kind: "instance",
parent: "moss-prefix-link",
data_attrs: &[],
example_html: r#"<span class="moss-prefix-link-suffix">→</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Optional trailing slot of a prefix-link.",
},
// -------------------------------------------------------------------
// Callouts — Obsidian-style admonitions. Type variant goes on the
// container as `.callout-<type>`. Phase 1c may collapse into
// `.moss-callout[data-type]`.
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-callout",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-callout callout" data-type="note">
<div class="callout-title">Note</div>
<div class="callout-content">Body...</div>
</div>"#,
example_markdown: "> [!note]\n> Body...",
status: Status::Confirmed,
since: "0",
description: "Obsidian-style callout. The Obsidian-compat `.callout` class is co-emitted; type lives on `data-type` (v1).",
},
ComponentEntry {
class: "callout",
kind: "standalone",
parent: "",
data_attrs: &[
DataAttr {
name: "data-type",
values: &["note", "info", "tip", "warning", "pending"],
default: "note",
description: "v1 callout type. Theme authors target `.callout[data-type=...]` to style by variant.",
},
],
example_html: r#"<div class="moss-callout callout" data-type="note">...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Obsidian-compat class co-emitted on every callout for theme parity. Type lives on `data-type` (v1).",
},
ComponentEntry {
class: "callout-title",
kind: "instance",
parent: "moss-callout",
data_attrs: &[],
example_html: r#"<div class="callout-title">Note</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Title row of a callout.",
},
ComponentEntry {
class: "callout-content",
kind: "instance",
parent: "moss-callout",
data_attrs: &[],
example_html: r#"<div class="callout-content">Body...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Body container of a callout.",
},
ComponentEntry {
class: "callout-note",
kind: "instance",
parent: "moss-callout",
data_attrs: &[],
example_html: r#"<div class="moss-callout callout callout-note">...</div>"#,
example_markdown: "> [!note]\n> Body",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — type lives on `.callout[data-type=note]`.",
},
ComponentEntry {
class: "callout-info",
kind: "instance",
parent: "moss-callout",
data_attrs: &[],
example_html: r#"<div class="moss-callout callout callout-info">...</div>"#,
example_markdown: "> [!info]\n> Body",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — type lives on `.callout[data-type=info]`.",
},
ComponentEntry {
class: "callout-tip",
kind: "instance",
parent: "moss-callout",
data_attrs: &[],
example_html: r#"<div class="moss-callout callout callout-tip">...</div>"#,
example_markdown: "> [!tip]\n> Body",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — type lives on `.callout[data-type=tip]`.",
},
ComponentEntry {
class: "callout-warning",
kind: "instance",
parent: "moss-callout",
data_attrs: &[],
example_html: r#"<div class="moss-callout callout callout-warning">...</div>"#,
example_markdown: "> [!warning]\n> Body",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — type lives on `.callout[data-type=warning]`.",
},
ComponentEntry {
class: "callout-pending",
kind: "instance",
parent: "moss-callout",
data_attrs: &[],
example_html: r#"<div class="moss-callout callout callout-pending">...</div>"#,
example_markdown: "> [!pending]\n> Body",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — type lives on `.callout[data-type=pending]`.",
},
// -------------------------------------------------------------------
// Embeds — `![[file.ext]]` shortcode renderers (audio, video, pdf,
// notebook, table, 3d, iframe).
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-embed",
kind: "standalone",
parent: "",
data_attrs: &[
DataAttr {
name: "data-type",
values: &["audio", "video", "pdf", "notebook", "table", "iframe", "3d"],
default: "",
description: "v1 embed kind. Set on the embed element. Theme authors target `.moss-embed[data-type=...]`.",
},
DataAttr {
name: "data-loop",
values: &[],
default: "",
description: "Ambient background video: autoplay + muted + loop + playsinline, controls off. Authored as `![[clip.mp4|loop]]`. Boolean presence flag (value is empty). JS reads it to apply the reduced-motion guard and mount the pause/play toggle.",
},
DataAttr {
name: "data-width",
values: &["body", "wide", "page", "screen"],
default: "body",
description: "Display width — text-column (body), wider than text (wide), page-width (page), or viewport-width (screen). See spec § P9.",
},
DataAttr {
name: "data-provider",
values: &["youtube", "vimeo", "codepen"],
default: "",
description: "Identifies the embed provider for external URL embeds. Absent for generic iframes and local HTML embeds.",
},
],
example_html: r#"<video class="moss-embed moss-embed-video" data-type="video" data-loop src="clip.mp4" autoplay muted loop playsinline preload="metadata"></video>"#,
example_markdown: "![[clip.mp4|loop]]",
status: Status::Confirmed,
since: "0",
description: "Base class on every typed embed. Kind on `data-type` (v1). Ambient video: add `data-loop` via `![[clip.mp4|loop]]`. `.moss-embed-audio` / `-video` / `-pdf` / `-notebook` / `-table` / `-iframe` / `-3d` retired in Phase 1c.",
},
ComponentEntry {
class: "moss-embed-audio",
kind: "instance",
parent: "moss-embed",
data_attrs: &[],
example_html: r#"<div class="moss-embed moss-embed-audio"><audio controls src="..."></audio></div>"#,
example_markdown: "![[track.mp3]]",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed to `.moss-embed[data-type=audio]`.",
},
ComponentEntry {
class: "moss-embed-video",
kind: "instance",
parent: "moss-embed",
data_attrs: &[],
example_html: r#"<div class="moss-embed moss-embed-video"><video controls src="..."></video></div>"#,
example_markdown: "![[clip.mp4]]",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed to `.moss-embed[data-type=video]`.",
},
ComponentEntry {
class: "moss-embed-pdf",
kind: "instance",
parent: "moss-embed",
data_attrs: &[],
example_html: r#"<div class="moss-embed moss-embed-pdf"><iframe src="..."></iframe></div>"#,
example_markdown: "![[paper.pdf]]",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed to `.moss-embed[data-type=pdf]`.",
},
ComponentEntry {
class: "moss-embed-iframe",
kind: "instance",
parent: "moss-embed",
data_attrs: &[],
example_html: r#"<div class="moss-embed moss-embed-iframe"><iframe src="..."></iframe></div>"#,
example_markdown: "![[page.html]]",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed to `.moss-embed[data-type=iframe]`.",
},
ComponentEntry {
class: "moss-embed-notebook",
kind: "instance",
parent: "moss-embed",
data_attrs: &[],
example_html: r#"<div class="moss-embed moss-embed-notebook">...</div>"#,
example_markdown: "![[analysis.ipynb]]",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed to `.moss-embed[data-type=notebook]`.",
},
ComponentEntry {
class: "moss-embed-ipynb",
kind: "instance",
parent: "moss-embed",
data_attrs: &[],
example_html: r#"<div class="moss-embed moss-embed-ipynb">...</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Alias of `.moss-embed-notebook`; consolidation pending.",
},
ComponentEntry {
class: "moss-embed-table",
kind: "instance",
parent: "moss-embed",
data_attrs: &[],
example_html: r#"<div class="moss-embed moss-embed-table"><table>...</table></div>"#,
example_markdown: "![[data.csv]]",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed to `.moss-embed[data-type=table]`.",
},
ComponentEntry {
class: "moss-embed-3d",
kind: "instance",
parent: "moss-embed",
data_attrs: &[],
example_html: r#"<div class="moss-embed moss-embed-3d">...</div>"#,
example_markdown: "![[model.glb]]",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed to `.moss-embed[data-type=3d]`.",
},
ComponentEntry {
class: "moss-embed-error",
kind: "instance",
parent: "moss-embed",
data_attrs: &[],
example_html: r#"<div class="moss-embed moss-embed-error">File not found: ...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Error state for embeds whose target cannot be resolved.",
},
ComponentEntry {
class: "moss-embed-missing",
kind: "instance",
parent: "moss-embed",
data_attrs: &[],
example_html: r#"<div class="moss-embed-missing">Folder not found: journal</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Fallback rendered when a folder-list embed (`![[journal/]]`) targets a folder that does not exist or cannot be resolved. Distinct from `.moss-embed-error` (file/wikilink resolution failure) — this one is specifically the folder-listing path.",
},
// -------------------------------------------------------------------
// Hero, image, visual primitives.
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-hero",
kind: "standalone",
parent: "",
data_attrs: &[
DataAttr {
name: "data-width",
values: &["body", "wide", "page", "screen"],
default: "body",
description: "Display width — text-column (body), wider than text (wide), page-width (page), or viewport-width (screen). See spec § P9. Emitted from the authoring shortcode (e.g. `:::hero {full}` -> `data-width=\"screen\"`); on article children, site.css sizes the band via the content-width escape (ADR-021 Corollary 2). The hero itself escapes by DOM position (outside `<main>`), not by these rules.",
},
DataAttr {
name: "data-slides",
values: &["2", "3", "4", "5", "6"],
default: "",
description: "Slide count of a multi-image hero (consecutive leading media lines). Present only when > 1; drives the ambient CSS crossfade — one slide visible at a time, no controls. Absent = single-image hero, today's exact markup.",
},
DataAttr {
name: "data-hero-tone",
values: &["light"],
default: "",
description: "Marks a hero whose image is pale enough (scan-cached dominant colour above 0.4 relative luminance) that the default legibility scrim leaves white overlay text under 4.5:1; site.css swaps in a stronger gradient. Emitted only when the hero also carries overlay text. Absent = mid-tone or dark image, no overlay, or an unparseable colour — all keep the default ramp.",
},
DataAttr {
name: "data-mobile",
values: &["overlay"],
default: "",
description: "Below **48rem** (moss's mobile threshold), `overlay` keeps the title on top of the image instead of stacking it underneath. Emitted **only** for `:::hero {mobile=overlay}` — an author must ask for it; a hero with overlay text does not get it by default. The selector to fight if you want the other behaviour is `.moss-hero[data-mobile=\"overlay\"]`.",
},
DataAttr {
name: "data-captioned",
values: &[""],
default: "",
description: "Present when the hero carries `caption=\"…\"`. Such a hero is a photograph on display rather than a backdrop for overlay text, and a caption that names a subject is a promise the subject is in frame — so site.css shows the whole image instead of the default crop-to-fill: the box takes the picture's own shape, centred, bounded by `--moss-hero-max-height` rather than filling the frame. Put the crop back on the image itself (`image=cover.jpg|cover top`), which lands as an inline style and wins.",
},
],
example_html: r#"<section class="moss-hero" data-width="page">
<div class="moss-hero-content">...</div>
</section>"#,
example_markdown: ":::hero {image=cover.jpg}\n:::\n\n:::hero {image=cover.jpg full mobile=overlay}\n# Title over the image\n:::\n",
status: Status::Confirmed,
since: "0",
description: "Hero banner section at the top of a page (cover image + title). v1 adds `data-width` for author-controlled sizing.",
},
ComponentEntry {
class: "moss-hero-content",
kind: "instance",
parent: "moss-hero",
data_attrs: &[],
example_html: r#"<div class="moss-hero-content">...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Text content slot inside `.moss-hero` — text laid ON the image. For text ABOUT the image, see `.moss-hero-caption`.",
},
ComponentEntry {
class: "moss-hero-caption",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<p class="moss-hero-caption">封面：基輔米迦勒修道院門口的陣亡將士紀念牆（拍攝：糜緒洋）</p>"#,
example_markdown: ":::hero {image=cover.jpg caption=\"Cover: the memorial wall (photo: A. Photographer)\"}\n:::\n",
status: Status::Confirmed,
since: "0",
description: "Caption or credit for a hero image, from `:::hero {caption=\"…\"}`. A SIBLING of `.moss-hero`, immediately after it — not a child: the section is a fixed-height cropping frame, and a photographer's credit has to survive as text below the picture rather than be printed across it. Rendered as inline markdown, so a credit can be a link, exactly like a `byline:` / `colophon:` row.",
},
ComponentEntry {
class: "moss-hero-slides",
kind: "instance",
parent: "moss-hero",
data_attrs: &[],
example_html: r#"<div class="moss-hero-slides"><div class="moss-hero-slide"><img src="portrait-1.jpg" alt="" /></div></div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Wrapper holding the `.moss-hero-slide` images of a multi-image hero; the CSS ambient crossfade cycles one slide visible at a time.",
},
ComponentEntry {
class: "moss-hero-slide",
kind: "instance",
parent: "moss-hero",
data_attrs: &[],
example_html: r#"<div class="moss-hero-slide"><img src="portrait-1.jpg" alt="" /></div>"#,
example_markdown: ":::hero
![[portrait-1.jpg]]
![[portrait-2.jpg]]
# Title
:::
",
status: Status::Confirmed,
since: "0",
description: "One background slide of a multi-image hero. Emitted only when the hero has 2+ images; slides crossfade ambiently via site.css keyed on the section's data-slides. First slide is the reduced-motion static fallback.",
},
ComponentEntry {
class: "moss-image",
kind: "standalone",
parent: "",
data_attrs: &[
DataAttr {
name: "data-aspect",
values: &["portrait", "square", "auto"],
default: "auto",
description: "v1 image aspect-ratio hint. Theme authors target `.moss-image[data-aspect=...]`. Emitter wiring lands in a follow-up.",
},
DataAttr {
name: "data-width",
values: &["body", "wide", "page", "screen"],
default: "body",
description: "Display width — text-column (body), wider than text (wide), page-width (page), or viewport-width (screen). See spec § P9.",
},
],
example_html: r#"<figure class="moss-image" style="width:55%"><img src="..." alt="..." /></figure>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Wrapper around an inline `<img>` for sizing and figure semantics. `data-width` carries a named width token (body|wide|page|screen); a content-relative width is instead emitted as inline `style=\"width:NN%\"` (set by the editor drag-resize), which also forces the inner image to fill that percent box. Images narrower than the content column center horizontally.",
},
ComponentEntry {
class: "moss-align-left",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<img src="..." alt="..." class="moss-align-left" />"#,
example_markdown: "![[photo.jpg|align-left]]",
status: Status::Confirmed,
since: "0",
description: "Floats an image to the left of body text (editorial runaround). Defaults max-width to 50% on desktop, collapses to full-width below 48rem. CSS `:has()` escalates the float to a wrapping `<figure class=\"moss-image\">` or `<picture>` when present. Mirrors WordPress's `alignleft` convention.",
},
ComponentEntry {
class: "moss-align-right",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<img src="..." alt="..." class="moss-align-right" />"#,
example_markdown: "![[photo.jpg|align-right]]",
status: Status::Confirmed,
since: "0",
description: "Floats an image to the right of body text (editorial runaround). Symmetric counterpart to `.moss-align-left`. Mirrors WordPress's `alignright` convention.",
},
ComponentEntry {
class: "moss-article-title",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<h1 class="moss-article-title">Title</h1>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Article-page H1 title emitted from frontmatter.",
},
ComponentEntry {
class: "moss-heading-anchor",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r##"<h2 id="setup">Setup<a class="moss-heading-anchor" href="#setup" aria-label="Permalink to this section"><span aria-hidden="true">#</span></a></h2>"##,
example_markdown: "## Setup",
status: Status::Emerging,
since: "1",
description: "Clickable permalink appended inside every author-written body heading that carries a slug id; links to the heading's `#`-fragment. The auto-injected `moss-article-title` H1 is emitted separately and gets no anchor.",
},
// -------------------------------------------------------------------
// Grid + gallery + buttons containers (free-form layouts).
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-grid",
kind: "container",
parent: "",
data_attrs: &[
DataAttr {
name: "data-width",
values: &["body", "wide", "page", "screen"],
default: "body",
description: "Display width — text-column (body), wider than text (wide), page-width (page), or viewport-width (screen). See spec § P9.",
},
DataAttr {
name: "data-columns",
values: &["1", "2", "3", "4"],
default: "",
description: "Column count, from `:::grid N`. Note the responsive default: below 768px moss collapses `[data-columns]` to a single column, which is right for a grid of cards and wrong for a grid of short text lines. Re-assert `grid-template-columns` inside your own media query if yours is the latter. A ratio (`:::grid 2 1:2`) arrives as the custom property `--moss-grid-ratio` on the element, so it stays overridable — the collapse applies to ratio grids too.",
},
],
example_html: r#"<div class="moss-grid" data-width="wide">
<div class="moss-grid-card">...</div>
</div>"#,
example_markdown: ":::grid {cols=2}\nLeft cell\n+++\nRight cell\n:::\n",
status: Status::Confirmed,
since: "0",
description: "Generic grid container (used by profiles, link previews, etc.). Modifier classes: `profiles`, `featured`, `no-cards`. v1 adds `data-width` (P9).",
},
ComponentEntry {
class: "moss-grid-card",
kind: "instance",
parent: "moss-grid",
data_attrs: &[
DataAttr {
name: "data-kind",
values: &["link", "friend", "card"],
default: "card",
description: "v1 grid-card variant. Today expressed via co-emitted classes (`.link-card`, `.friend-card`, `.no-cards`); Phase 1c collapses to this `data-kind` attribute.",
},
],
example_html: r#"<a class="moss-grid-card" data-kind="link" href="...">...</a>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Card instance inside `.moss-grid`. Today emits sibling classes `link-card` / `friend-card` / `no-cards`; v1 collapses to `data-kind`.",
},
ComponentEntry {
class: "moss-gallery",
kind: "container",
parent: "",
data_attrs: &[
DataAttr {
name: "data-width",
values: &["body", "wide", "page", "screen"],
default: "body",
description: "Display width — text-column (body), wider than text (wide), page-width (page), or viewport-width (screen). See spec § P9.",
},
DataAttr {
name: "data-columns",
values: &[],
default: "",
description: "Column count, from `:::gallery N` — the author names it rather than moss inferring it. The **opposite** of `.moss-grid[data-columns]` on mobile: below 48rem the grid collapses to one column, while the gallery uses `auto-fill` to keep as many tracks as clear 88px. N becomes a maximum rather than a mandate, and a gallery that already fits stays at its authored count. Collapsing a wall of thumbnails to one column is wrong; collapsing prose cells is right.",
},
],
example_html: r#"<div class="moss-gallery" data-width="page">
<div class="moss-gallery-item">...</div>
</div>"#,
example_markdown: ":::gallery\nphoto.jpg\n:::\n",
status: Status::Confirmed,
since: "0",
description: "Image gallery container. v1 adds `data-width` (P9).",
},
ComponentEntry {
class: "moss-gallery-item",
kind: "instance",
parent: "moss-gallery",
data_attrs: &[],
example_html: r#"<div class="moss-gallery-item"><img src="..." /></div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Single image entry inside `.moss-gallery`.",
},
ComponentEntry {
class: "moss-buttons",
kind: "container",
parent: "",
data_attrs: &[
DataAttr {
name: "data-style",
values: &["default", "inverted"],
default: "default",
description: "v1 button-row style. Theme authors target `.moss-buttons[data-style=...]`.",
},
],
example_html: r#"<div class="moss-buttons" data-style="inverted">
<a class="moss-btn" href="...">Click</a>
</div>"#,
example_markdown: ":::buttons\n[Get started](https://example.com)\n:::\n",
status: Status::Confirmed,
since: "0",
description: "Container for a row of `.moss-btn` buttons. v1: the inverted variant is on `data-style=\"inverted\"`.",
},
// -------------------------------------------------------------------
// Button primitive (used by subscribe + general CTAs).
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-btn",
kind: "standalone",
parent: "",
data_attrs: &[
DataAttr {
name: "data-role",
values: &["default", "primary", "secondary"],
default: "default",
description: "v1 button role. Theme authors target `.moss-btn[data-role=...]`.",
},
],
example_html: r#"<button class="moss-btn" data-role="primary">
<span class="moss-btn__label">Submit</span>
</button>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Generic button primitive. Role on `data-role` (v1).",
},
ComponentEntry {
class: "moss-btn__label",
kind: "instance",
parent: "moss-btn",
data_attrs: &[],
example_html: r#"<span class="moss-btn__label">Submit</span>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Label span inside `.moss-btn`.",
},
ComponentEntry {
class: "moss-btn__check",
kind: "instance",
parent: "moss-btn",
data_attrs: &[],
example_html: r#"<span class="moss-btn__check">✓</span>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Success checkmark slot inside `.moss-btn`.",
},
ComponentEntry {
class: "moss-btn__spinner",
kind: "instance",
parent: "moss-btn",
data_attrs: &[],
example_html: r#"<span class="moss-btn__spinner"></span>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Loading spinner slot inside `.moss-btn`.",
},
// -------------------------------------------------------------------
// Subscribe form (newsletter / Buttondown / seta).
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-subscribe",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-subscribe">
<form class="moss-subscribe-form">...</form>
</div>"#,
example_markdown: ":::subscribe\n:::\n",
status: Status::Confirmed,
since: "0",
description: "Newsletter subscribe block (auto-injected into footer when email channel configured).",
},
ComponentEntry {
class: "moss-subscribe-form",
kind: "instance",
parent: "moss-subscribe",
data_attrs: &[
DataAttr {
name: "data-position",
values: &["inline", "apply"],
default: "inline",
description: "Placement/behavior variant. All moss-hosted subscribe forms are `inline` (the auto-injected footer form and the `:::subscribe` shortcode emit identical HTML — footer vs in-page styling keys on the `footer` ancestor in CSS, not this attribute). `apply` marks the `:::apply` form (terminal success, FormData body).",
},
DataAttr {
name: "data-button-override",
values: &["true"],
default: "true",
description: "Emitted only when the author overrides the button label (`:::subscribe{button=\"...\"}`). Signals subscribe.ts to leave the button label AND placeholder as authored instead of overwriting them with the language-default copy.",
},
DataAttr {
name: "data-moss-hosted",
values: &["true"],
default: "true",
description: "Marks moss-hosted (seta) forms hydrated by subscribe.ts. Absent on 3rd-party provider forms.",
},
DataAttr {
name: "data-state",
values: &["idle", "loading", "success", "error"],
default: "idle",
description: "Runtime submit state machine, driven by subscribe.ts. Emitted as `idle`; theme authors target `.moss-subscribe-form[data-state=...]`.",
},
DataAttr {
name: "data-moss-pending-site",
values: &["true"],
default: "true",
description: "Pre-first-publish pending wiring (`action=\"#\"`, no site_id yet). Hidden on published pages (body without `data-moss-preview`) via the email.css defense rule so a pending form never faces real readers.",
},
],
example_html: r#"<form class="moss-subscribe-form">...</form>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Form element inside `.moss-subscribe`.",
},
ComponentEntry {
class: "moss-btn-slot",
kind: "instance",
parent: "moss-subscribe",
data_attrs: &[],
example_html: r#"<div class="moss-btn-slot"><button class="moss-btn">...</button></div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Fixed-width slot wrapping a form's submit button; used by both the subscribe and comment forms to prevent layout shift across idle/loading/success states.",
},
ComponentEntry {
class: "moss-subscribe-status",
kind: "instance",
parent: "moss-subscribe",
data_attrs: &[],
example_html: r#"<div class="moss-subscribe-status">
<span class="moss-subscribe-status__icon"></span>
Subscribed!
</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Status message shown after submit (success/error).",
},
ComponentEntry {
class: "moss-subscribe-status__icon",
kind: "instance",
parent: "moss-subscribe-status",
data_attrs: &[],
example_html: r#"<span class="moss-subscribe-status__icon"></span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Icon slot inside `.moss-subscribe-status`.",
},
ComponentEntry {
class: "moss-subscribe-landing",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<section class="moss-subscribe-landing">...</section>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Standalone subscribe landing page surface (larger variant).",
},
// -------------------------------------------------------------------
// Apply form (membership / contributor application).
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-apply",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-apply" data-state="idle">
<form class="moss-subscribe-form moss-apply-form">...</form>
</div>"#,
example_markdown: ":::apply\n:::\n",
status: Status::Emerging,
since: "0",
description: "Apply / membership-request form block (:::apply shortcode).",
},
ComponentEntry {
class: "moss-apply-form",
kind: "instance",
parent: "moss-apply",
data_attrs: &[
DataAttr {
name: "data-position",
values: &["apply"],
default: "apply",
description: "Position variant; always `apply` for this form. Drives CSS layout in email.css.",
},
DataAttr {
name: "data-revert",
values: &["false"],
default: "false",
description: "When `false`, success is terminal (no auto-revert). subscribe.ts reads this.",
},
],
example_html: r#"<form class="moss-subscribe-form moss-apply-form" data-position="apply" data-revert="false">...</form>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Form element inside `.moss-apply`. Also carries `.moss-subscribe-form` so subscribe.ts hydrates it.",
},
ComponentEntry {
class: "moss-apply-matters",
kind: "instance",
parent: "moss-apply",
data_attrs: &[],
example_html: r#"<input type="text" name="matters" class="moss-input moss-apply-matters">"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Second apply-form input inside `.moss-apply-form` — a Matters username OR a one-line pitch (placeholder-only, no visible label).",
},
ComponentEntry {
class: "moss-apply-hp",
kind: "instance",
parent: "moss-apply",
data_attrs: &[],
example_html: r#"<input type="text" name="website" class="moss-apply-hp" tabindex="-1" aria-hidden="true">"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Honeypot field (off-screen) inside `.moss-apply-form`. Bots fill it; humans don't.",
},
ComponentEntry {
class: "moss-apply-status",
kind: "instance",
parent: "moss-apply",
data_attrs: &[],
example_html: r#"<div class="moss-subscribe-status moss-apply-status" aria-live="polite">...</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Status region inside `.moss-apply-form` (also carries `.moss-subscribe-status`).",
},
ComponentEntry {
class: "moss-apply-helper",
kind: "instance",
parent: "moss-apply",
data_attrs: &[],
example_html: r#"<p class="moss-apply-helper" id="moss-apply-email-help">用于获取邀请及免费托管服务</p>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Helper text line beneath each field in `.moss-apply-form` (referenced by the field's aria-describedby). Internal — not part of the public component contract.",
},
// -------------------------------------------------------------------
// Series navigation (prev/next + collection links).
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-series-nav",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<nav class="moss-series-nav">
<div class="moss-series-nav-links">...</div>
</nav>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Series navigation bar (prev/next/collection) on series pages.",
},
ComponentEntry {
class: "moss-series-nav-links",
kind: "instance",
parent: "moss-series-nav",
data_attrs: &[],
example_html: r#"<div class="moss-series-nav-links">...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Row holding prev/next links in series nav.",
},
ComponentEntry {
class: "moss-series-nav-link",
kind: "instance",
parent: "moss-series-nav",
data_attrs: &[],
example_html: r#"<a class="moss-series-nav-link moss-series-nav-prev" href="...">...</a>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Individual link inside series nav. Modifiers: `moss-series-nav-prev`, `moss-series-nav-next`, `empty` (placeholder).",
},
ComponentEntry {
class: "moss-series-nav-prev",
kind: "instance",
parent: "moss-series-nav",
data_attrs: &[],
example_html: r#"<a class="moss-series-nav-link moss-series-nav-prev" href="...">...</a>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Previous-page modifier on a series nav link.",
},
ComponentEntry {
class: "moss-series-nav-next",
kind: "instance",
parent: "moss-series-nav",
data_attrs: &[],
example_html: r#"<a class="moss-series-nav-link moss-series-nav-next" href="...">...</a>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Next-page modifier on a series nav link.",
},
ComponentEntry {
class: "moss-series-nav-arrow",
kind: "instance",
parent: "moss-series-nav",
data_attrs: &[],
example_html: r#"<span class="moss-series-nav-arrow">→</span>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Arrow glyph inside a series-nav link.",
},
ComponentEntry {
class: "moss-series-nav-title",
kind: "instance",
parent: "moss-series-nav",
data_attrs: &[],
example_html: r#"<span class="moss-series-nav-title">Next page title</span>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Title text of the destination page in a series-nav link.",
},
ComponentEntry {
class: "moss-series-nav-collection",
kind: "instance",
parent: "moss-series-nav",
data_attrs: &[],
example_html: r#"<div class="moss-series-nav-collection">...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Collection-listing slot in series nav (sibling pages).",
},
ComponentEntry {
class: "moss-series-nav-collection-row",
kind: "instance",
parent: "moss-series-nav-collection",
data_attrs: &[],
example_html: r#"<div class="moss-series-nav-collection-row">...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Row inside the collection listing of series nav.",
},
ComponentEntry {
class: "moss-series-nav-position",
kind: "instance",
parent: "moss-series-nav-collection-row",
data_attrs: &[],
example_html: r#"<span class="moss-series-nav-position">2 of 3</span>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Where this page sits in its series — \"2 of 3\" / 「第 2 篇，共 3 篇」. Counts only the pages still in the reading order, so a page that stepped out with `series: false` is not in the total. Omitted when the folder holds a single page.",
},
// -------------------------------------------------------------------
// Collection cover (collection landing pages).
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-collection-cover",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<section class="moss-collection-cover">
<div class="moss-collection-cover-row">...</div>
</section>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Header surface on a collection landing page.",
},
ComponentEntry {
class: "moss-collection-cover-row",
kind: "instance",
parent: "moss-collection-cover",
data_attrs: &[],
example_html: r#"<div class="moss-collection-cover-row">...</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Row inside `.moss-collection-cover`.",
},
ComponentEntry {
class: "moss-collection-cover-body",
kind: "instance",
parent: "moss-collection-cover",
data_attrs: &[],
example_html: r#"<div class="moss-collection-cover-body">...</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Body content slot inside `.moss-collection-cover`.",
},
// -------------------------------------------------------------------
// Form primitives (input, label, field, link).
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-input",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<input class="moss-input" type="email" />"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Generic form input primitive.",
},
ComponentEntry {
class: "moss-field",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-field">
<label class="moss-label">Email</label>
<input class="moss-input" />
</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Form field group (label + input). Modifier `--inline` for horizontal layout.",
},
ComponentEntry {
class: "moss-label",
kind: "instance",
parent: "moss-field",
data_attrs: &[],
example_html: r#"<label class="moss-label">Email</label>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Label primitive for `.moss-field`. Modifier `--small` for compact form.",
},
ComponentEntry {
class: "moss-link",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<a class="moss-link" href="...">Click me</a>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Inline-link primitive (resets `<button>` chrome too). Use `--subtle` for muted variant.",
},
ComponentEntry {
class: "moss-field--inline",
kind: "instance",
parent: "moss-field",
data_attrs: &[],
example_html: r#"<div class="moss-field moss-field--inline">
<label class="moss-label">Email</label>
<input class="moss-input" />
</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "BEM modifier on `.moss-field` for horizontal label+input layout (used by settings UI primitives).",
},
ComponentEntry {
class: "moss-label--small",
kind: "instance",
parent: "moss-label",
data_attrs: &[],
example_html: r#"<label class="moss-label moss-label--small">Compact label</label>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "BEM modifier on `.moss-label` for compact form (used by services settings rows).",
},
ComponentEntry {
class: "moss-info-grid",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-info-grid">
<div class="moss-field moss-field--inline">...</div>
<div class="moss-field moss-field--inline">...</div>
</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Two-column aligned label+value rows (CSS grid with `display: contents` children). Used by the deployment settings panel; ships in the default theme so authors can reuse the layout.",
},
ComponentEntry {
class: "moss-row",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-row">
<div class="moss-field">...</div>
<div class="moss-field">...</div>
</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Horizontal flex row of equal-flex `.moss-field` children. Form-row layout helper shipped in the default theme.",
},
ComponentEntry {
class: "moss-input-feedback",
kind: "instance",
parent: "moss-field",
data_attrs: &[],
example_html: r#"<span class="moss-input-feedback">Saving…</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Auto-save status hint slot under `.moss-field`. Three state modifiers: `--success`, `--error`, `--fade-out`.",
},
ComponentEntry {
class: "moss-input-feedback--success",
kind: "instance",
parent: "moss-input-feedback",
data_attrs: &[],
example_html: r#"<span class="moss-input-feedback moss-input-feedback--success">Saved</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Success state modifier on `.moss-input-feedback`.",
},
ComponentEntry {
class: "moss-input-feedback--error",
kind: "instance",
parent: "moss-input-feedback",
data_attrs: &[],
example_html: r#"<span class="moss-input-feedback moss-input-feedback--error">Failed to save</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Error state modifier on `.moss-input-feedback`.",
},
ComponentEntry {
class: "moss-input-feedback--fade-out",
kind: "instance",
parent: "moss-input-feedback",
data_attrs: &[],
example_html: r#"<span class="moss-input-feedback moss-input-feedback--success moss-input-feedback--fade-out">Saved</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Transient fade-out modifier on `.moss-input-feedback` (applied after a success message to dismiss it).",
},
// -------------------------------------------------------------------
// Other emit surfaces (comments, colophon, shell frame, misc).
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-comments",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<section class="moss-comments">...</section>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Comments surface (per-site SQLite backend or Artalk legacy).",
},
ComponentEntry {
class: "moss-service-inactive",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<section class="moss-comments moss-service-inactive">...</section>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Co-class applied to `.moss-comments` and `.moss-subscribe-form` when the backing service is not configured. Hidden by default in published sites and revealed inside the preview chrome so authors can see the inactive surface during editing.",
},
// -------------------------------------------------------------------
// Preview link popover — emitted by `assets/js/preview.js` runtime.
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-preview-popup",
kind: "chrome",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-preview-popup" role="tooltip" aria-live="polite">
<strong class="moss-preview-title">...</strong>
<p class="moss-preview-desc">...</p>
<p class="moss-preview-text">...</p>
</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Floating link-preview popover injected at `document.body` level by the runtime `preview.js`. Fetches `/_moss/previews.json` and renders a hover card with title, description, and excerpt for internal links.",
},
ComponentEntry {
class: "moss-preview-title",
kind: "instance",
parent: "moss-preview-popup",
data_attrs: &[],
example_html: r#"<strong class="moss-preview-title">Article title</strong>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Title slot inside `.moss-preview-popup`.",
},
ComponentEntry {
class: "moss-preview-desc",
kind: "instance",
parent: "moss-preview-popup",
data_attrs: &[],
example_html: r#"<p class="moss-preview-desc">Short description</p>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Description slot inside `.moss-preview-popup` (from frontmatter `description`).",
},
ComponentEntry {
class: "moss-preview-text",
kind: "instance",
parent: "moss-preview-popup",
data_attrs: &[],
example_html: r#"<p class="moss-preview-text">Excerpt of the linked article…</p>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Excerpt slot inside `.moss-preview-popup` (auto-extracted from the linked article body).",
},
ComponentEntry {
class: "moss-colophon",
kind: "chrome",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-colophon">
<a href="https://mosspub.com">
<svg class="moss-colophon-icon"></svg>
<span class="moss-colophon-label">Published with moss</span>
</a>
</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Footer colophon credit appended by moss. Shows the moss mark alone at rest; the wording fades in beneath it on hover or keyboard focus, without moving the mark.",
},
ComponentEntry {
class: "moss-colophon-icon",
kind: "instance",
parent: "moss-colophon",
data_attrs: &[],
example_html: r#"<svg class="moss-colophon-icon"></svg>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "The moss mark inside `.moss-colophon`. Decorative (`aria-hidden`) — `.moss-colophon-label` carries the accessible name.",
},
ComponentEntry {
class: "moss-colophon-label",
kind: "instance",
parent: "moss-colophon",
data_attrs: &[],
example_html: r#"<span class="moss-colophon-label">Published with moss</span>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Localized attribution wording inside `.moss-colophon`. Transparent at rest and faded in on hover/focus, positioned out of flow beneath the mark so the reveal shifts nothing — it stays in the DOM because it is the link's accessible name.",
},
ComponentEntry {
class: "moss-shell-frame",
kind: "chrome",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-shell-frame">...</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "App-shell frame surface (preview chrome).",
},
ComponentEntry {
class: "moss-mobile-frame",
kind: "chrome",
parent: "moss-shell-frame",
data_attrs: &[],
example_html: r#"<html class="moss-shell-frame moss-mobile-frame">...</html>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Runtime marker the preview bridge adds to `<html>` when the shell is in mobile device-preview mode. Since ADR-039 the shell owns chrome clearance by insetting the preview iframe, so no CSS keys off this class and it currently has no effect; it is retained as a revert path and may be removed.",
},
ComponentEntry {
class: "main-nav",
kind: "chrome",
parent: "",
data_attrs: &[],
example_html: r#"<nav class="main-nav container">...</nav>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Top site navigation bar. Legacy non-`moss-` prefix kept for theme parity.",
},
// The article masthead and nav interior. Legacy non-`moss-` prefixes, kept
// for theme parity like `main-nav` above.
//
// These were emitted but undeclared until 2026-08-05, and the omission had
// a measured cost: an agent restyling a journalism site reaches for the
// byline row first, found nothing for it in `describe --json`, and had to
// recover the class by reading built HTML — which the shipped guidance
// sanctions only as a self-check, and which silently breaks on a rename.
// Declaring them is what makes "never hardcode a class from memory"
// followable for the masthead. `components_sync_test` cannot guard these:
// it only matches `class="moss-..."` literals.
ComponentEntry {
class: "date-line",
kind: "chrome",
parent: "",
data_attrs: &[],
example_html: r#"<div class="date-line"><span class="date">March 3, 2026</span><div class="font-anchor">...</div></div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Byline row under an article title: the publication date on the left, the reading-size control on the right. Emitted only when the page has a `date`.",
},
ComponentEntry {
class: "date",
kind: "instance",
parent: "date-line",
data_attrs: &[],
example_html: r#"<span class="date">March 3, 2026</span>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "The formatted publication date inside `.date-line`. Text is localized to the page's language.",
},
ComponentEntry {
class: "moss-byline",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-byline"><div class="moss-byline-row">作者 糜緒洋</div><div class="moss-byline-row">編輯 謝丁</div></div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Credit block under the page title, below `.date-line` when there is one. Emitted from the `byline` frontmatter field on every page kind — articles, folder indexes, the homepage and plain pages alike — one `.moss-byline-row` per authored line. On a page moss gives no title of its own (the homepage, a `home: true` folder page, a plain page) it sits under the author's own opening `<h1>`, or at the top of the page content when the body has none. Absent when the field is.",
},
ComponentEntry {
class: "moss-byline-row",
kind: "instance",
parent: "moss-byline",
data_attrs: &[],
example_html: r#"<div class="moss-byline-row">首發媒體 <a href="https://theinitium.com/a">端傳媒</a></div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "One credit line. Its content is the author's text rendered as inline markdown, so a row may contain links or emphasis. moss does not know which part is a role and which is a name — style the whole row.",
},
ComponentEntry {
class: "moss-article-colophon",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-article-colophon"><div class="moss-article-colophon-row">首發媒體 <a href="https://theinitium.com/a">端傳媒</a></div></div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Credit block at the FOOT of the page, emitted from the `colophon` frontmatter field — where the piece first ran, contributor biographies, production credits. Same rows as `.moss-byline`, different end of the page. Emitted on every page kind: inside `<article>` on an article page, and last in the page content everywhere else — after the children listing on a folder index or the homepage — where the enclosing element is not an `<article>` despite the class name. Unrelated to `.review-colophon`, which is the review feature's book card.",
},
ComponentEntry {
class: "moss-article-colophon-row",
kind: "instance",
parent: "moss-article-colophon",
data_attrs: &[],
example_html: r#"<div class="moss-article-colophon-row">封面 基輔米迦勒修道院門口的陣亡將士紀念牆（拍攝：糜緒洋）</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "One foot-credit line, rendered as inline markdown exactly like `.moss-byline-row`.",
},
ComponentEntry {
class: "site-name",
kind: "instance",
parent: "main-nav",
data_attrs: &[],
example_html: r#"<a href="/" class="site-name">在場</a>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "The site title link at the left of the nav bar. On a non-home page the same slot may instead carry `.breadcrumb-segment`.",
},
ComponentEntry {
class: "breadcrumb-segment",
kind: "instance",
parent: "main-nav",
data_attrs: &[],
example_html: r#"<a href="/awards/" class="breadcrumb-segment">獎項</a>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "One ancestor link in the nav-left breadcrumb trail, used in place of `.site-name` once the page is below the site root.",
},
ComponentEntry {
class: "nav-icons",
kind: "chrome",
parent: "main-nav",
data_attrs: &[],
example_html: r#"<div class="nav-icons">...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Right-hand icon cluster in the nav bar (search, theme toggle, and similar). Stationary chrome, present whether or not the site has nav links.",
},
// The rest of the nav interior and the default footer, on the same footing
// as the masthead block above: emitted since 0, styled in `site.css`, and
// undeclared until 2026-08-05.
//
// The 2026-08-05 trial found the concrete cost. An agent asked to restyle a
// site went looking in `describe --json` for the language switcher, found
// nothing, and recovered `.nav-lang-toggle` by grepping built HTML — the one
// move the shipped guidance tells agents not to make, because it breaks
// silently on a rename. `main-nav`, `.site-name` and `.nav-icons` were
// declared; everything they contain was not, which is the worst of both
// (the contract looks complete enough to trust).
ComponentEntry {
class: "nav-left",
kind: "chrome",
parent: "main-nav",
data_attrs: &[],
example_html: r#"<div class="nav-left"><a href="/" class="site-name">在場</a></div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Left group of the nav bar. Holds either `.site-name` or the breadcrumb trail, never both.",
},
ComponentEntry {
class: "nav-right",
kind: "chrome",
parent: "main-nav",
data_attrs: &[],
example_html: r#"<div class="nav-right">…hamburger, .nav-links, .nav-icons…</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Right group of the nav bar: the mobile menu button, the nav links, and the icon cluster, in that order.",
},
ComponentEntry {
class: "nav-links",
kind: "chrome",
parent: "nav-right",
data_attrs: &[],
example_html: r#"<div class="nav-links"><a href="/about/" class="active">關於</a>…</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "The nav link list. The link for the page currently being viewed additionally carries the bare class `active` — style `.nav-links .active`, not a `moss-` class.",
},
ComponentEntry {
class: "site-logo",
kind: "instance",
parent: "site-name",
data_attrs: &[],
example_html: r#"<img class="site-logo" src="…" alt="" aria-hidden="true">"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Optional logo image inside the site-name link. Decorative by construction (`alt=\"\"` + `aria-hidden`), because the adjacent text already names the site.",
},
ComponentEntry {
class: "breadcrumb-label",
kind: "instance",
parent: "nav-left",
data_attrs: &[],
example_html: r#"<span class="breadcrumb-label">獎項</span>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "The final, non-linked breadcrumb segment — the page you are on. `.breadcrumb-segment` is the linked form for ancestors.",
},
ComponentEntry {
class: "breadcrumb-separator",
kind: "instance",
parent: "nav-left",
data_attrs: &[],
example_html: r#"<span class="breadcrumb-separator">/</span>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "The `/` between breadcrumb segments. Restyle or hide this rather than trying to remove it from the markup.",
},
ComponentEntry {
class: "mobile-menu-button",
kind: "chrome",
parent: "nav-right",
data_attrs: &[],
example_html: r#"<button class="mobile-menu-button" aria-label="…"><svg>…</svg></button>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "The hamburger. Emitted on every page and hidden by media query above the mobile breakpoint — it is not conditionally rendered, so a rule that shows it always will.",
},
ComponentEntry {
class: "nav-search-btn",
kind: "instance",
parent: "nav-icons",
data_attrs: &[],
example_html: r#"<button class="nav-search-btn" type="button" aria-label="…"><svg class="search-icon">…</svg></button>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Search button in the nav icon cluster. Its glyph is `.search-icon`.",
},
ComponentEntry {
class: "search-icon",
kind: "instance",
parent: "nav-search-btn",
data_attrs: &[],
example_html: r#"<svg class="search-icon" aria-hidden="true" width="1em" height="1em">…</svg>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "The magnifier glyph. Sized in `em` and stroked with `currentColor`, so it follows the button's font-size and color rather than needing its own rule.",
},
ComponentEntry {
class: "nav-theme-btn",
kind: "instance",
parent: "nav-icons",
data_attrs: &[],
example_html: r#"<button class="nav-theme-btn" type="button" aria-label="…"><svg class="theme-toggle-icon">…</svg></button>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Light/dark toggle in the nav icon cluster. Its glyph is `.theme-toggle-icon`.",
},
ComponentEntry {
class: "theme-toggle-icon",
kind: "instance",
parent: "nav-theme-btn",
data_attrs: &[],
example_html: r#"<svg class="theme-toggle-icon" aria-hidden="true" width="1em" height="1em">…</svg>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "The sun/moon glyph. One SVG whose clip path animates between states — restyle it, but do not expect two separate icons to swap.",
},
ComponentEntry {
class: "nav-lang-toggle",
kind: "chrome",
parent: "nav-icons",
data_attrs: &[],
example_html: r#"<div class="nav-lang-toggle" aria-label="…"><span class="nav-lang-current">繁</span><a href="/en/" class="nav-lang-link" hreflang="en">EN</a></div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "The language switcher. Present only when the site has more than one edition among the three the switcher resolves (English, Simplified Chinese, Traditional Chinese) — a `ja/` or `fr/` tree publishes but adds no entry here.",
},
ComponentEntry {
class: "nav-lang-current",
kind: "instance",
parent: "nav-lang-toggle",
data_attrs: &[],
example_html: r#"<span class="nav-lang-current">繁</span>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "The edition being viewed, as inert text rather than a link — style the current-language affordance here.",
},
ComponentEntry {
class: "nav-lang-link",
kind: "instance",
parent: "nav-lang-toggle",
data_attrs: &[],
example_html: r#"<a href="/en/" class="nav-lang-link" hreflang="en">EN</a>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "A link to another edition of the same page. Carries `hreflang`, so `[hreflang=\"en\"]` is a stable hook for per-language styling.",
},
// The floating nav island (ADR-049) — the small bar that appears when the
// reader scrolls back up past the masthead on a long page. A SECOND object,
// not the masthead re-pinned, which is why it has its own `moss-`-prefixed
// vocabulary. Its trail is the one exception: it deliberately reuses
// `.site-name` / `.breadcrumb-segment` / `.breadcrumb-label` /
// `.breadcrumb-separator` from the masthead above, so a site that restyles
// its breadcrumb restyles both at once.
ComponentEntry {
class: "moss-nav-island",
kind: "chrome",
parent: "",
data_attrs: &[DataAttr {
name: "data-shown",
values: &["false", "true"],
default: "false",
description: "Whether the island is currently revealed. Written by the site runtime; ABSENT in the emitted HTML, which is what keeps the island invisible with JavaScript off.",
}],
example_html: r#"<div class="moss-nav-island" data-shown="true"><div class="moss-nav-island-bar">…</div></div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Floating navigation island: a one-line bar, aligned to the text column, revealed on scroll-up once the masthead has left the screen. Emitted on any page with a breadcrumb trail, but it only ever shows where it can take the reader somewhere — a trail of three or more crumbs (down the tree) or a page with headings (the sections panel). On a top-level page with neither, the markup stays dormant (ADR-049 §10). Turn it off site-wide with `[site].floating_nav = false` or `--moss-nav-island-display: none`.",
},
ComponentEntry {
class: "moss-nav-island-bar",
kind: "instance",
parent: "moss-nav-island",
data_attrs: &[],
example_html: r#"<div class="moss-nav-island-bar">…trail, actions, progress…</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "The visible rounded bar. Its width follows `--moss-nav-width`/`--moss-content-width`, so it lines up with the article text rather than with the window.",
},
ComponentEntry {
class: "moss-nav-island-trail",
kind: "instance",
parent: "moss-nav-island-bar",
data_attrs: &[],
example_html: r#"<nav class="moss-nav-island-trail" aria-label="Breadcrumb">…</nav>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "The breadcrumb inside the island. Same segment classes as the masthead's, plus the current page as a final crumb. It never wraps: ancestors fold into `.moss-nav-island-more` until the row fits.",
},
ComponentEntry {
class: "moss-nav-island-current",
kind: "instance",
parent: "moss-nav-island-trail",
data_attrs: &[],
example_html: r#"<span class="breadcrumb-segment moss-nav-island-current" aria-current="page">末代女礦工</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "The page you are on, as the trail's last crumb. The only crumb permitted to truncate — an ancestor either fits whole or folds away.",
},
ComponentEntry {
class: "moss-nav-island-more",
kind: "instance",
parent: "moss-nav-island-trail",
data_attrs: &[],
example_html: r#"<button class="moss-nav-island-more" aria-expanded="false">…</button>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Stands in for the ancestor levels the trail had to drop. Opens the levels menu on click; names them on hover via `data-tooltip`. Never opens on hover — a touch device has none, and that is the width where folding happens.",
},
ComponentEntry {
class: "moss-nav-island-actions",
kind: "instance",
parent: "moss-nav-island-bar",
data_attrs: &[],
example_html: r#"<span class="moss-nav-island-actions">…</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Button cluster at the island's end edge. Holds the sections button only — theme, language and search stay in the masthead.",
},
ComponentEntry {
class: "moss-nav-island-sections",
kind: "instance",
parent: "moss-nav-island-actions",
data_attrs: &[],
example_html: r#"<button class="moss-nav-island-sections" aria-expanded="false"><svg>…</svg></button>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Opens this page's section list. Ships `hidden` and is unhidden only once headings have been found, so a page with no headings shows no dead glyph.",
},
ComponentEntry {
class: "moss-nav-island-menu",
kind: "instance",
parent: "moss-nav-island",
data_attrs: &[DataAttr {
name: "data-island-menu",
values: &["levels", "sections"],
default: "levels",
description: "Which of the two menus this is: the folded ancestor levels, or the page's sections.",
}],
example_html: r#"<div class="moss-nav-island-menu" data-island-menu="sections">…</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Popover opened by `.moss-nav-island-more` or `.moss-nav-island-sections`. Every row reserves a leading gutter for the current-row rule, so the labels line up in one column whether or not a row is marked.",
},
ComponentEntry {
class: "moss-breadcrumb-more",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<button class="moss-breadcrumb-more" aria-expanded="false">…</button>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "The masthead trail's counterpart to `.moss-nav-island-more`: stands in for the ancestor levels the trail folded, opens the levels menu on click, names them on hover via `data-tooltip`. Emitted (hidden) only when the trail has a middle to fold — three or more crumbs.",
},
ComponentEntry {
class: "moss-breadcrumb-menu",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-breadcrumb-menu" hidden>…</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Popover listing the masthead trail's folded ancestor levels, opened by `.moss-breadcrumb-more`. A sibling of `.nav-left` (which clips its own overflow), positioned against `.nav-content`. Same shape as `.moss-nav-island-menu`.",
},
ComponentEntry {
class: "moss-nav-island-progress",
kind: "instance",
parent: "moss-nav-island-bar",
data_attrs: &[],
example_html: r#"<span class="moss-nav-island-progress"><span class="moss-nav-island-progress-fill"></span></span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Reading-progress track along the island's own bottom edge — not a separate bar across the window. Currently measures document scroll.",
},
ComponentEntry {
class: "moss-nav-island-progress-fill",
kind: "instance",
parent: "moss-nav-island-progress",
data_attrs: &[],
example_html: r#"<span class="moss-nav-island-progress-fill" style="width: 42%"></span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "The filled portion of the progress track. Its `width` is written inline by the site runtime; with JavaScript off it stays at 0 and the track reads as empty.",
},
ComponentEntry {
class: "footer-default",
kind: "chrome",
parent: "",
data_attrs: &[],
example_html: r#"<p class="footer-default"><a href="/rss.xml" class="footer-link" data-external>RSS</a>…</p>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "The generated footer link row, emitted only when the site has no authored `footer.md`. Authoring a footer replaces it, so a rule targeting this stops applying the moment the site gains one.",
},
ComponentEntry {
class: "footer-link",
kind: "instance",
parent: "footer-default",
data_attrs: &[],
example_html: r#"<a href="/rss.xml" class="footer-link" data-external>RSS</a>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "One link in the generated footer row (RSS and similar). Off-site ones also carry `data-external`.",
},
ComponentEntry {
class: "moss-child-section-divider",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<hr class="moss-child-section-divider" />"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Divider rule between auto-generated child sections.",
},
ComponentEntry {
// Source of truth: `crates/moss-core/src/ast/shortcode_extract.rs`
// (the unknown-name branch around line 1282). components_sync_test
// only greps emitter source for `class="moss-..."` literals — this
// class is assembled via `render_div_open`, so a regression here
// will NOT be caught by that test; keep this entry in sync by hand.
class: "moss-unknown-shortcode",
kind: "standalone",
parent: "",
data_attrs: &[DataAttr {
name: "data-name",
values: &[],
default: "",
description: "The unrecognised shortcode name, as written by the author.",
}],
example_html: r#"<div class="moss-unknown-shortcode" data-name="foo">
<p>body parsed as markdown</p>
</div>"#,
example_markdown: ":::foo\nbody parsed as markdown\n:::",
status: Status::Confirmed,
since: "0",
description: "Fallback wrapper emitted for any `:::name` fence whose name is not a registered shortcode. The body is still parsed as markdown and a build warning names the shortcode, so a misspelling degrades to a styled region rather than losing content.",
},
// -------------------------------------------------------------------
// Syntax highlight tokens (emitted by syntect inside <code>).
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-hl-keyword",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-keyword">if</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: keyword.",
},
ComponentEntry {
class: "moss-hl-string",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-string">"hi"</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: string literal.",
},
ComponentEntry {
class: "moss-hl-comment",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-comment">// note</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: comment.",
},
ComponentEntry {
class: "moss-hl-function",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-function">render</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: function name.",
},
ComponentEntry {
class: "moss-hl-type",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-type">String</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: type name.",
},
ComponentEntry {
class: "moss-hl-number",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-number">42</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: numeric literal.",
},
ComponentEntry {
class: "moss-hl-operator",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-operator">+</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: operator.",
},
ComponentEntry {
class: "moss-hl-builtin",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-builtin">print</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: builtin identifier.",
},
ComponentEntry {
class: "moss-hl-tag",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-tag">div</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: markup tag name.",
},
ComponentEntry {
class: "moss-hl-attr",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-attr">class</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: attribute name.",
},
ComponentEntry {
class: "moss-hl-meta",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-meta">@derive</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: meta/annotation.",
},
ComponentEntry {
class: "moss-hl-addition-bg",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-addition-bg">+ added line</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight diff token: added-line background.",
},
ComponentEntry {
class: "moss-hl-deletion",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-deletion">- removed line</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight diff token: removed-line text.",
},
ComponentEntry {
class: "moss-hl-deletion-bg",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-deletion-bg">- removed line</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight diff token: removed-line background.",
},
ComponentEntry {
class: "moss-recent",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r#"<ul class="moss-recent">
<li><a href="/posts/spring-notes/">Spring notes</a><div class="moss-recent__date">2026-04-12</div><div class="moss-recent__desc">A walk through the garden.</div></li>
</ul>"#,
example_markdown: ":::recent {count=5 since=\"2026-01-01\"}\n:::\n",
status: Status::Emerging,
since: "0",
description: "Auto-generated list of recent posts. Sorted newest-first; date and description slots are filled per child. No default CSS in the bundled theme — theme authors style it freely. IMPORTANT: emitted by the EMAIL/newsletter path only. On a web page, `:::recent` renders its fallback body as ordinary markdown and emits no list, because the per-page processor has no access to the build's aggregate document slice; a `:::recent` block with an empty body therefore produces nothing at all on a web page. To list posts on a page today, rely on the automatic child listing a folder home emits (`moss-cards`), and give any `:::recent` block a fallback body.",
},
ComponentEntry {
class: "moss-recent__date",
kind: "instance",
parent: "moss-recent",
data_attrs: &[],
example_html: r#"<div class="moss-recent__date">2026-04-12</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Per-entry date slot inside `.moss-recent` (BEM child). Format is `YYYY-MM-DD`, derived from frontmatter `date`. Empty string when the post lacks a parseable date.",
},
ComponentEntry {
class: "moss-recent__desc",
kind: "instance",
parent: "moss-recent",
data_attrs: &[],
example_html: r#"<div class="moss-recent__desc">A walk through the garden.</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Per-entry description slot inside `.moss-recent` (BEM child). Sourced from frontmatter `description`; empty when unset.",
},
// -------------------------------------------------------------------
// Ambient loop video — JS-injected wrapper + toggle (§3.5).
// The <video data-loop> synthesizer emits `data-loop` on the <video>;
// ambient-video.ts wraps it at init time.
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-ambient-video",
kind: "standalone",
parent: "",
data_attrs: &[
DataAttr {
name: "data-paused",
values: &[],
default: "",
description: "Boolean presence flag set by ambient-video.ts when the video is paused (user-initiated or reduced-motion guard). CSS uses `[data-paused]` to keep the toggle visible.",
},
],
example_html: r#"<div class="moss-ambient-video">
<video data-loop src="clip.mp4" autoplay muted loop playsinline preload="metadata"></video>
<button class="moss-ambient-toggle" type="button" aria-label="Pause video">⏸</button>
</div>"#,
example_markdown: "![[clip.mp4|loop]]",
status: Status::Emerging,
since: "1",
description: "JS-injected wrapper around a `video[data-loop]` element. Provides the positioning context for `.moss-ambient-toggle` and the `[data-paused]` state hook. Not emitted by the Rust synthesizer — ambient-video.ts creates it at init.",
},
ComponentEntry {
class: "moss-ambient-toggle",
kind: "instance",
parent: "moss-ambient-video",
data_attrs: &[],
example_html: r#"<button class="moss-ambient-toggle" type="button" aria-label="Pause video">⏸</button>"#,
example_markdown: "",
status: Status::Emerging,
since: "1",
description: "Chrome-free pause/play toggle button for ambient loop videos. Injected by ambient-video.ts. Keyboard-focusable; `aria-label` toggles between \"Pause video\" and \"Play video\". Visible on hover/focus of `.moss-ambient-video` and always visible when `[data-paused]`. Satisfies WCAG 2.2.2 Level A (Pause, Stop, Hide).",
},
// -------------------------------------------------------------------
// LaTeX math (ADR-030). P1 emits the escaped source in a marked
// `<code>`; P2 replaces the element's *contents* with a typeset
// `<svg>` while keeping the class and `data-moss-math` stable, so a
// theme selector written against P1 keeps working across the upgrade.
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-math",
kind: "standalone",
parent: "",
data_attrs: &[
DataAttr {
name: "data-moss-math",
values: &["inline", "display"],
default: "inline",
description: "Which delimiter produced the equation: `inline` for `$…$`, `display` for `$$…$$`. Carries the distinction to CSS and to the typesetter so neither has to re-derive it from context — a theme can select on it today to centre display math; moss ships no math stylesheet of its own yet, so both variants currently inherit plain `<code>` styling.",
},
],
example_html: r#"<code class="moss-math" data-moss-math="inline">$E = mc^2$</code>"#,
example_markdown: "Energy $E = mc^2$.",
status: Status::Emerging,
since: "1",
description: "A LaTeX equation. In P1 the element holds the author's own markdown source — `$` / `$$` delimiters included — HTML-escaped: an honest fallback that never shows a blank where an equation was written, and never deletes the delimiters of prose that merely looked like math. Requires `[site].math` (default on).",
},
ComponentEntry {
class: "moss-math-scroll",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-math-scroll"><svg class="moss-math" data-moss-math="display">…</svg></div>"#,
example_markdown: "$$E = mc^2$$",
status: Status::Emerging,
since: "1",
description: "Horizontal-scroll container the build path wraps around typeset display math (`svg.moss-math[data-moss-math=\"display\"]`). On a narrow viewport a wide equation scrolls inside this box at its natural size rather than shrinking to unreadability or pushing the page into horizontal overflow. Emitted only by P2's typeset path; the P1 `<code>` fallback is never wrapped. A display SVG left unwrapped still cannot overflow the page — it falls back to scaling down via `max-width: 100%`.",
},
ComponentEntry {
class: "moss-table-scroll",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-table-scroll" tabindex="0">
<table>…</table>
</div>"#,
example_markdown: "| Name | Subs |\n| --- | --- |\n| a | 1,200 |",
status: Status::Emerging,
since: "1",
description: "Horizontal-scroll wrapper the renderer emits around every Markdown table and every CSV/TSV embed (`.moss-embed[data-type=\"table\"]`). Keeps the `<table>` semantically intact (unlike a `display:block` table, which breaks column layout and assistive-tech table semantics) while letting a wide table scroll inside its own box instead of pushing the page into horizontal overflow. `tabindex=\"0\"` makes an overflowing table keyboard-scrollable.",
},
ComponentEntry {
class: "moss-col-right",
kind: "instance",
parent: "moss-table-scroll",
data_attrs: &[],
example_html: r#"<th class="moss-col-right">订阅数</th>
<td class="moss-col-right">1,457,776</td>"#,
example_markdown: "| Subs |\n| --: |\n| 1,457,776 |",
status: Status::Emerging,
since: "1",
description: "Right-aligned table cell (`<th>`/`<td>`). Applied to a whole column when the author right-aligned it in GFM (`|--:|`) or when the column auto-detects as numeric, so figures register on their trailing digits. Pairs with the table's `font-variant-numeric: tabular-nums`.",
},
ComponentEntry {
class: "moss-col-center",
kind: "instance",
parent: "moss-table-scroll",
data_attrs: &[],
example_html: r#"<th class="moss-col-center">Status</th>
<td class="moss-col-center">✓</td>"#,
example_markdown: "| Status |\n| :-: |\n| ✓ |",
status: Status::Emerging,
since: "1",
description: "Center-aligned table cell (`<th>`/`<td>`). Applied to a whole column the author center-aligned in GFM (`|:-:|`).",
},
ComponentEntry {
class: "moss-search",
kind: "chrome",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-search" id="moss-search" hidden>
<div class="moss-search__backdrop"></div>
<div class="moss-search__panel" role="dialog" aria-modal="true" aria-label="Search">
<div class="moss-search__field"><input class="moss-search__input" role="combobox"></div>
<div class="moss-search__progress" hidden></div>
<div class="moss-search__seam"></div>
<div class="moss-search__body">
<p class="moss-search__status" role="status" hidden></p>
<ul class="moss-search__results" role="listbox">
<li class="moss-search__row">
<a class="moss-search__link" role="option" href="/posts/foo/">
<span class="moss-search__title">Title</span>
<span class="moss-search__excerpt">…a <mark>match</mark>…</span>
</a>
</li>
</ul>
</div>
</div>
</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "1",
description: "Site-search overlay. Not emitted by the build — the client runtime (`_moss/js/search.<hash>.js`, shipped only when the build wrote a Pagefind index) constructs this subtree lazily on the first open, so a reader who never searches downloads no index and materializes no DOM. Opened by the nav's `.nav-search-btn`, by `/`, or by ⌘K/Ctrl+K. BEM children carry the interior: `__backdrop` (translucent page-coloured scrim, not an opaque modal takeover), `__panel` (top-anchored at 18vh, fixed 18px radius at any height), `__field`/`__input`, `__progress` (1px accent hairline, delayed 200ms so fast queries never flash it), `__seam` (hairline inset by the corner radius), `__status` (idle / no-matches line, sharing one vertical slot with the results so the panel never jumps), `__results`/`__row`/`__link`/`__title`/`__excerpt`. Selection is a 2px `--moss-color-ui-accent` left border plus a ~4% accent tint — never a solid fill block. `<mark>` inside `__excerpt` is Pagefind's own term highlighting, restyled to colour emphasis rather than a highlighter box.",
},
ComponentEntry {
class: "moss-footnotes",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r##"<section class="moss-footnotes" role="doc-endnotes">
<ol>
<li id="fn-1"><p>The note. <a class="moss-footnote-backref" href="#fnref-1" role="doc-backlink" aria-label="Back to reference 1">↩︎</a></p>
</li>
</ol>
</section>"##,
example_markdown: "Text[^1].\n\n[^1]: The note.",
status: Status::Emerging,
since: "1",
description: "The document's endnote section, appended after the body by the renderer. Holds one `<li id=\"fn-N\">` per footnote in first-reference order, whatever depth the author wrote the definition at — a definition inside a blockquote or a list item is hoisted here too. Present only on pages that define at least one footnote. `role=\"doc-endnotes\"` (DPUB-ARIA) names the region for assistive tech.",
},
ComponentEntry {
class: "moss-footnote-ref",
kind: "instance",
parent: "moss-footnotes",
data_attrs: &[],
example_html: r##"<sup class="moss-footnote-ref" id="fnref-1"><a href="#fn-1" role="doc-noteref">1</a></sup>"##,
example_markdown: "Text[^1].\n\n[^1]: The note.",
status: Status::Emerging,
since: "1",
description: "The in-body footnote marker: a superscript number linking down to its note. The number is first-reference order, not the author's label, so `[^method]` and `[^1]` both print as ordinals. A second marker for the same note takes id `fnref-N-2`, `fnref-N-3`, … so each has its own back-link.",
},
ComponentEntry {
class: "moss-footnote-backref",
kind: "instance",
parent: "moss-footnotes",
data_attrs: &[],
example_html: r##"<a class="moss-footnote-backref" href="#fnref-1" role="doc-backlink" aria-label="Back to reference 1">↩︎</a>"##,
example_markdown: "Text[^1].\n\n[^1]: The note.",
status: Status::Emerging,
since: "1",
description: "The return arrow at the end of a note, linking back to the marker that sent the reader there. One per marker, so a note referenced twice ends with two arrows. A note nobody referenced has none. The arrow carries VARIATION SELECTOR-15 (`︎`) so mobile Chrome renders it as plain text rather than a coloured emoji.",
},
];
/// Implementation classes that are emitted by moss for internal functionality
/// but must not appear in the public theme-facing contract (`moss describe` /
/// `docs/reference/contract.md`). These classes ARE present in `COMPONENTS` for
/// the sync-test to validate their HTML class literals, but `is_public()` hides
/// them from agents, themes, and `reference.md` generation.
const INTERNAL_CLASSES: &[&str] = &[
"moss-apply",
"moss-apply-form",
"moss-apply-matters",
"moss-apply-hp",
"moss-apply-status",
"moss-apply-helper",
];
impl ComponentEntry {
/// True for entries that belong in the public, agent/theme-facing surface.
/// v1 rule: not retired AND not an internal implementation class.
///
/// Internal classes (e.g. all `moss-apply*`) stay in COMPONENTS so the
/// sync-test can validate them, but they must not surface in `moss describe`
/// or `docs/reference/contract.md` — they are subject to change at any time.
pub fn is_public(&self) -> bool {
self.status != Status::Retired && !INTERNAL_CLASSES.contains(&self.class)
}
}
/// Iterator over class names with `Status::Retired`. Used by the build
/// pipeline's theme lint to warn users about pre-v1 vocabulary.
///
/// Exposed as an iterator over `&'static str` so callers don't need to
/// import the `Status` enum (keeps moss-core's surface narrow).
pub fn retired_class_names() -> impl Iterator<Item = &'static str> {
COMPONENTS.iter()
.filter(|e| e.status == Status::Retired)
.map(|e| e.class)
}
#[cfg(test)]
mod tests {
use super::*;
/// Orphan-gate: every class in `INTERNAL_CLASSES` must exist as a `class`
/// in `COMPONENTS`. If a class is renamed in the emitter *and* in
/// `INTERNAL_CLASSES` but forgotten in `COMPONENTS`, it would silently
/// re-enter the public contract surface (`is_public()` only hides known
/// internals). This test prevents that gap.
#[test]
fn every_internal_class_has_a_components_entry() {
let component_classes: std::collections::HashSet<&'static str> =
COMPONENTS.iter().map(|e| e.class).collect();
for &internal in INTERNAL_CLASSES {
assert!(
component_classes.contains(internal),
"INTERNAL_CLASSES entry '{}' has no matching entry in COMPONENTS — \
add a ComponentEntry for it or remove it from INTERNAL_CLASSES",
internal
);
}
}
}