registry:ui · layout
reference — the 引 primitive
A native <a href> that says what the target says: an equation Figure renders Eq (4.5), a numbered Section renders § 3.2.1, an unnumbered one renders its title. Change the target — kind, chapter, order — and every reference follows. Forward references prerender their ?? fallback carrying the edge claim and resolve on hydration.
$npx jixoai-ui add reference
https://ui.jixoai.com/r/reference.json
overview
Overview
A reference resolves itself from what the target says about itself — and paints nothing of its own.
The resolution grammar is the target's, never the reference's: a Figure renders its
kind's display word from the figure registry's single source plus the number string
the registrant owns — Eq (4.5); a numbered Section renders § 3.2.1; an unnumbered Section falls back to its bare title with no
connective word (connectives are author copy — the children escape
hatch exists for them, replacing the anchor's label while href + data-ref-to remain). The reference never formats
numbers and never copies display words; the registryDependency edge to the figure
family is the law.
The DOM is a TWO-STATE machine over one rule: "not yet registered" is not
"nonexistent". Before the settle criterion holds (hydration + two rAFs — which
means the whole SSR pass), an unresolved reference renders the FALLBACK ANCHOR: ??(to) text still carrying href + the data-ref-to edge claim, because the static harvester's two-pass
pre-scan needs the forward edge. Only when settle proves the target dead does it
degrade to the loud ??(to) span — not navigable, the edge released,
one console.warn per missing episode (not dev-gated: prerendered artifacts must
surface bad references). A live target that registers late resolves without ever
warning; a winner's eviction degrades the reference back and re-arms the warn.
The axes story is the fleet's other pole: the citation is a PURE INHERITANCE
surface. The family ships no atoms file and no css file — the anchor declares no
fontSize, no color, no corner, no shadow — so the preflight's a { color: inherit } law makes ink and size chain from the
context, and the §11 size stamp consumes exactly through that inheritance (the kbd contrast: that glyph pins
its own kernel voice; this one inherits everything). Density is the one stamp with
scope semantics — a rung re-scopes whatever the children escape hatch carries.
All eight lanes are no-own (the first-time W3-D2 contract). Per-axis below; the
shared grammar lives on the universal props page.
reference
The resolution matrix under one numbering domain: an equation, a numbered section, an unnumbered section, and a missing id.
1 Results
the momentum balance of ??(eq-r) holds
the procedure lives in ??(sec-methods)
for notation see ??(sec-unnumbered)
a broken one renders ??(eq-nope) loudly
p = m · v1.1 Methods
Notation
the join rule: an undeclared card INSIDE a domain joins it and numbers by structure — the bare-title fallback needs a domain-less target, which is why this one lives outside the provider (the route registry still resolves it).
see <Reference to="eq-1" /> and <Reference to="methods" />
<Reference to="eq-1">上式</Reference> — the children escape hatchlaw
The edge-emission state machine
Not yet registered is not nonexistent: the forward edge stays claimed until settle proves the target dead — then the marker goes loud, the edge is released, and the warn fires once per episode.
| Property | Type | Default | Description |
|---|---|---|---|
| resolved | the target is registered | a native <a href="#to"> reading the target's self-description | announces: Eq (4.5) · § 3.2.1 · the bare title |
| forward claim | the target is not registered YET (pre-settle, and all of SSR) | the FALLBACK ANCHOR — ??(to) text still carrying href + data-ref-to | announces: the edge claim survives for the static harvester's two-pass pre-scan |
| settled missing | hydration + two rAFs, target still absent | a loud <span>??(to)</span> — navigable status dropped, data-ref-to released | announces: one console.warn per missing episode (not dev-gated — prerendered artifacts must surface bad references) |
| provider escape | no registry in context | the missing-state render outright | announces: one dev-gated warn at init — never double-diagnosed with the settle warn |
| eviction | a live target is evicted | degrades back to missing and re-warns — a fresh episode (design §1.2's re-trigger law) | announces: the registry is the truth, reactively |
types
Postures
One anchor, four postures: equation, numbered section, unnumbered section, and the children escape hatch.
usage
Usage
Address by explicit id; the children snippet replaces the anchor's label text while href semantics remain.
see <Reference to="eq-1" /> and <Reference to="methods" />
<Reference to="eq-1">上式</Reference> — the children escape hatchapi
API
Two contract rows over the eight-lane surface (the first-time W3-D2 contract, all no-own): the target id and the label escape hatch. There is no rest spread and no paint surface — everything visual is inherited from the context.
Properties
| Property | Type | Default | Description |
|---|---|---|---|
| to * | string | — | The target's explicit id — resolved through the route-page target registry; referenceable targets are numbered Figures and Sections (numbered or not). |
| children | Snippet | — | Escape hatch: replaces the anchor's label text (author copy such as connectives); the href and data-ref-to semantics remain. |
Universal props
| Property | Type | Default | Description |
|---|---|---|---|
| size | 'small' | 'medium' | 'large' | 'auto' | number | 'auto' · ambient scope | the base scale — root font-size; parts size in em |
| shape | 'round' | 'scoop' | 'bevel' | 'notch' | 'square' | 'squircle' | 'auto' | 'auto' · ambient scope | corner geometry (CSS corner-shape; §14 degrade table) |
| radius | 'small' | 'medium' | 'large' | 'auto' | number | 'auto' · ambient scope | corner size; auto = the concentric broadcast (§3) |
| density | 'small' | 'medium' | 'large' | 'auto' | number | 'auto' · ambient scope | spacing/leading scale over the kernel channels (§4) |
| color | 'primary' | 'secondary' | 'error' | 'warn' | 'success' | 'info' | 'auto' | number | string | 'auto' · ambient scope | the hue axis of the fixed oklch primary system (§5) |
| theme | 'light' | 'dark' | 'system' | 'auto' | 'auto' · ambient scope | light/dark profile; system = the JS-mutable global (§6) |
| elevation | 'level-1' | 'level0' | 'level1' | 'level2' | 'level3' | 'level4' | 'level5' | 'auto' | number | 'auto' · ambient scope | official M3 levels over the surface ladder (§7) |
| motion | 'reduced' | 'subtle' | 'normal' | 'expressive' | 'auto' | number | 'auto' · ambient scope | intensity across the motion kernels (§8) |
axes
The eight axes on reference
The fleet's inheritance pole (the first-time W3-D2 contract, all no-own): the family ships no atoms and no css, the preflight's color: inherit anchor law makes ink and size chain from the context, and the §11 size stamp consumes exactly through that inheritance — the kbd contrast's other pole. Density is the one stamp with scope semantics (the children escape hatch's re-scoping); theme is a bridge to nothing (measured: a scoped dark island moves neither ink nor ground); everything else stamps-and-supplies.
| Property | Type | Default | Description |
|---|---|---|---|
| size | 'small' | 'medium' | 'large' | 'auto' | number | 'auto' | CONSUMED THROUGH INHERITANCE — the §11 stamp lands on the root and the label simply inherits it: the family declares no fontSize anywhere (no atoms, no css — grep receipt), so the anchor is the kbd contrast's other pole. Measured in two contexts: a 13.5px prose reference computes 13.5px, the size={18} demo computes 18px, and a 12.5px table instance would inherit 12.5px the same way. Number unit: px. |
| shape | 'round' | 'scoop' | 'bevel' | 'notch' | 'square' | 'squircle' | 'auto' | 'auto' | SUPPLY-ONLY — stamps the carriers; the family reads nothing (grep receipt: no css surface exists). An inline anchor paints no silhouette. Number unit: none. |
| radius | 'small' | 'medium' | 'large' | 'auto' | number | 'auto' | SUPPLY-ONLY — stamps --jx-radius-effective; zero readers (no corner is painted). The supply is for composed descendants through the children escape hatch. Number unit: px. |
| density | 'small' | 'medium' | 'large' | 'auto' | number (+ the five legacy spellings) | 'auto' | STAMP-ONLY, scope-carrier — the rung lands data-density on the root (measured), and the anchor itself reads no kernel channel: its ink and size are inherited from the context. The stamp matters for what the children escape hatch carries — a density-reading descendant re-bases inside the root's scope. No opinion stamps nothing. Number unit: coefficient. |
| color | 'primary' | 'secondary' | 'error' | 'warn' | 'success' | 'info' | 'auto' | number | string | 'auto' | SUPPLY-ONLY — stamps --jx-color-effective; zero readers. The anchor's ink is the preflight's `a { color: inherit }` law: the context's ink IS the reference's ink (measured: the served references compute their prose context's color). Number unit: hue degrees. |
| theme | 'light' | 'dark' | 'system' | 'auto' | 'auto' | BRIDGE-ONLY — the class:dark bridge lands on the root and NOTHING reads it: the family paints no color, and the preflight's color: inherit chains from OUTSIDE the scope, so a scoped dark island moves neither the ink nor the ground (measured: computed color unchanged inside an injected .dark). A citation is deliberately cascade-passive — whichever theme owns the surrounding prose owns the reference. No number lane. |
| elevation | 'level-1' | 'level0' | 'level1' | 'level2' | 'level3' | 'level4' | 'level5' | 'auto' | number | 'auto' | SUPPLY-ONLY — stamps --jx-elevation-effective; zero readers (no shadow anywhere in the family). An inline citation is flush with the plane. Number unit: dp. |
| motion | 'reduced' | 'subtle' | 'normal' | 'expressive' | 'auto' | number | 'auto' | SUPPLY-ONLY — stamps --jx-motion-effective; zero readers and zero transition declarations (grep receipt: the resolution is reactive registry flow, not choreography). Number unit: coefficient. |
| Token | Default | Source |
|---|---|---|
| a { color: inherit } | the preflight law | structural |
| kernel channels (--jx-text / --jx-hit / --jx-gap) | UNREAD by this family | density |
| data-ref-to | the edge claim | component |
| FIGURE_LABELS | the figure registry's single source | structural |
reference · the measured axes
ambient — the context's voice, inherited
1 Ambient
a = 1see Eq (1.1)
size=18 — consumed through inheritance
1 Size
a = 2see Eq (1.1)
density="small" — the scope stamp, voice unchanged
1 Density
a = 3see Eq (1.1)
settled missing — the loud span, edge released
1 Missing
the broken one: ??(eq-never)
<Reference to="eq-1" size={18}>the scaled citation</Reference>
<!-- density: the rung stamps the root — a scope for what the children
escape hatch carries, not a paint dial -->
<Reference to="eq-1" density="small">…</Reference><script lang="ts">
import Reference from '@ui/reference.svelte';
import { query } from '@lib/universal-props-query.svelte';
</script>
<!-- below 48rem the base (13.5px, the prose context) applies; at 48rem+
the md case (18px) wins through the root stamp + plain inheritance -->
<Reference to="eq-1" size={query({ md: 18 }, 13.5)} />reference · query()
1 Query
q = 4see Eq (1.1)
<script lang="ts">
import Reference from '@ui/reference.svelte';
import { query } from '@lib/universal-props-query.svelte';
</script>
<!-- below 48rem the base (13.5px, the prose context) applies; at 48rem+
the md case (18px) wins through the root stamp + plain inheritance -->
<Reference to="eq-1" size={query({ md: 18 }, 13.5)} />a11y
Accessibility
The platform owns everything: a native fragment anchor for the living edge, a plain span for the dead one — no synthetic tabindex, no role, no state.
Keyboard
| Key | Action |
|---|---|
| Enter | Activates the native fragment link — the platform scrolls to the target; no key handling exists in the family |
ARIA
| Attribute | Value | Description |
|---|---|---|
| a[href] | native anchor | Keyboard focus and activation ride the platform; no synthetic tabindex or role. |
| data-ref-to | the edge claim | Carried on every living anchor for the static harvester — released the moment settle proves the target dead. |
| span (missing) | not navigable | A dead target degrades to a visible ??(id) marker — no interaction affordance for a broken edge. |
| children | the label contract | A children override replaces the label text only — the href stays; announce-worthy copy is the author's to write. |