An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:Divider authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-27 owners: [cixzhang] review_triggers: [public-api, behavior, layout, theming, accessibility, testing] verified_by: [ .github/visual-baseline/manifest.json, packages/core/src/Divider/Divider.test.tsx, packages/core/src/theme/themingTargets.test.ts, apps/storybook/stories/Divider.stories.tsx, ] modules: [] families: [] design_specs: [] architecture: [ architecture:public-component-api, architecture:component-theming-surface, architecture:container-padding, architecture:component-test-sufficiency, ] contributing: []
system_specs: [spec:AST-009, spec:AST-020]
Divider component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | orientation, label, theme-extensible variant, isFullBleed, BaseProps<HTMLDivElement>, and a root ref. |
| Behavior | The separator renders one rule without a label and two rules around a renderable label; full bleed consumes inherited logical container inset. |
| End-user impact | People perceive a named separator across horizontal, vertical, labelled, full-bleed, narrow, and RTL compositions. |
| Builder impact | None; the record describes shipped behavior. Numeric zero is a valid label; booleans and empty strings leave one continuous unnamed rule. |
| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Two implementation gaps are listed under Current-state impact. |
| Review checks | Reject missing numeric labels, physical-edge bleed, dropped root inputs, or a target or axis that disagrees with the rendered separator. |
| Governing rules | architecture:public-component-api/INV1,INV5–INV9; architecture:component-theming-surface/INV3–INV7,INV14; architecture:container-padding/INV1,INV3,INV7–INV10; WCAG 2.2 SC 1.3.1 and 4.1.2 through spec:AST-020/FR1. |
This table is a review projection; the body below is authoritative.
Intent
Divider provides a programmatic and visual separator between caller-owned content
regions. It owns orientation, line weight, optional label placement and naming,
logical full-bleed geometry, and the aggregate divider theme target. The caller
owns the meaning of the surrounding regions.
Consumer syntax and examples belong in Divider.doc.mjs.
Compatibility and migration
- Released default preserved: yes — horizontal, subtle, unlabelled, and not full bleed.
- Compatibility class: records shipped behavior; no public prop, default, DOM, or styling output changes. ReactNode values that React renders, including numeric zero, stay inside the label wrapper; skipped scalar labels leave one continuous unnamed rule.
- Controlled/uncontrolled behavior: not applicable.
- Migration decision: none.
Consumer migration instructions belong in consumer docs and release notes.
Current-state impact
- Theme-added variant without line paint (FR3).
DividerVariantMapadmits theme-added values, but an unmatched value leaves the inner rule unpainted, so the line can disappear.architecture:component-theming-surfaceINV14 requires an extensible visual axis to have a safe theme-independent baseline; OQ2 holds the remediation direction. - Caller
roleandaria-orientationreplaced (FR6). Divider setsrole="separator"andaria-orientationafter caller props, so a caller's explicit values never reach the root, wherearchitecture:public-component-apiINV5 lets a caller's explicit input reach the element.
Ownership boundary
Owns
- One semantic separator root and its public ref, DOM, data, ARIA, class, style,
event, and
xstylecomposition. - Horizontal and vertical rule geometry.
- Optional label placement and the separator naming relationship.
- Built-in subtle and strong line weights.
- The reflected custom-variant state, including the missing line-paint fallback recorded under Current-state impact.
- Logical full-bleed consumption of inherited container inset.
- The aggregate
dividertarget with reflected orientation and variant axes.
Does not own / non-goals
- The meaning or heading structure of surrounding content regions — owned by the product callsite.
- Container inset publication — owned by
architecture:container-padding. - A separate public target for Rule or Label — none exists; OQ1 holds the question.
- Theme-authored custom variant paint and the public part that should own it — OQ2 holds the question.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Orientation | horizontal; vertical |
Selects the separator axis, rule geometry, and aria-orientation. |
Every divider | horizontal |
component | stable | Closed union; rejected by types |
| Label | renderable ReactNode; omitted/skipped scalar | Inserts one label between two rules and names the separator unless explicit ARIA naming wins. | Every orientation and variant | omitted | caller/component | stable | null, booleans, and empty strings render no label; numeric zero remains visible |
| Variant | subtle; strong; theme-added visual values |
Selects line paint and reflects the requested value on the target. | Every orientation and label state | subtle |
component/theme | stable built-ins; theme-extensible axis | An unmatched custom value leaves the rule unpainted (FR3) |
| Full bleed | false; true | Consumes inherited logical container inset on the divider axis. | Every orientation | false | component/container protocol | stable | Missing variables resolve to zero |
| Root surface | ref; DOM/data/ARIA; class/style/xstyle/events | Extends the semantic separator root. | Every divider | omitted | public component API | stable | Accepted inputs compose; a caller role or aria-orientation is replaced today (FR6 gap) |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | The divider renders one rule without a renderable label and two rules with the label between them. Numeric zero is a renderable label; null, booleans, and empty strings render no label. A horizontal divider is a full-width flex row and a vertical divider a full-height inline flex column; the label uses supporting type in secondary text with --spacing-3 padding on the divider's axis. |
Released ReactNode API; current source, docs, and tests |
| FR2 | By default the root exposes role="separator" and the selected aria-orientation; a caller's explicit role or aria-orientation wins and is used as given, even where it contradicts orientation (FR6). A renderable label names it through aria-labelledby unless a caller aria-label or aria-labelledby is supplied. |
WCAG 2.2 SC 1.3.1 and 4.1.2; current source and tests |
| FR3 | subtle paints the rule --color-border and strong paints it --color-border-emphasized, at --border-width. The exported map accepts theme-added values, which the root reflects, and an extensible visual axis has a safe theme-independent baseline (architecture:component-theming-surface INV14). Implementation gap: an unmatched value leaves the inner rule unpainted (Current-state impact). |
architecture:component-theming-surface/INV4,INV6,INV14; current source |
| FR4 | Full bleed consumes the inherited logical inline inset for horizontal dividers and the logical block inset for vertical dividers, extending the box by the same amounts; absent inset resolves to zero. | architecture:container-padding/INV1,INV3,INV7–INV10; current source |
| FR5 | The root carries the divider target and reflects orientation and the requested variant. Rule and Label carry no public target. The reflected data-orientation and data-variant are component-owned theming state and replace a caller's values. |
architecture:component-theming-surface/INV3–INV6; current source and docs |
| FR6 | ref, DOM, data, ARIA, class, style, event, and xstyle inputs reach or compose on the separator root, and a caller's explicit role or aria-orientation reaches it (architecture:public-component-api INV5). Implementation gap: the component sets role and aria-orientation after caller props, so a caller's values are replaced (Current-state impact). |
architecture:public-component-api/INV5–INV8; current source and tests |
Allowed variation
- AV1 — Label content. Any caller-owned ReactNode that React renders may fill the label wrapper.
- AV2 — Theme paint. An active theme may restyle the aggregate target and its variant axis. OQ2 owns the unresolved inner-rule paint and fallback boundary.
- AV3 — Container geometry. Full bleed follows the inherited per-edge inset, including asymmetric and zero values.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Unlabelled horizontal | One subtle or strong inline rule; horizontal separator semantics | Container width and theme paint |
| Labelled horizontal | Two rules around one visible, naming label | Any renderable label content |
| Numeric zero label | One visible 0 inside the label wrapper; separator name 0 |
Any orientation or variant |
| Vertical labelled/unlabelled | Block-axis rules and vertical separator semantics | Container height and label content |
| Theme-added variant without a match | Requested variant reflected; inner rule has no component-owned paint (FR3 gap) | Custom variant name |
| Full bleed | Logical-axis inset consumed without physical-direction assumptions | Uniform, asymmetric, zero, or absent inset |
| RTL | Horizontal geometry remains logical; full bleed consumes inline start/end independently | Surrounding content and label language |
Transformation and precedence order
- ORD1 — Label presence. Apply the shared renderable-value predicate; when a label remains, render and reference one wrapper between two rules.
- ORD2 — Accessible name. Explicit
aria-labelledbywins, then explicitaria-label, then the rendered label wrapper; an unlabelled separator stays unnamed. - ORD3 — Variant paint. Reflect the requested value on the root target. Built-in values select subtle or strong inner-rule paint; unmatched custom values select no inner-rule paint (FR3).
Performance and resources
- PR1 — No external lifecycle. Divider installs no listener, observer, timer, request, state machine, or Effect.
Accessibility contract
- AR1 — Programmatic separator. By default the root exposes separator role
and the exact visual orientation; a caller's explicit
roleoraria-orientationwins (FR6), and today the component's values replace it (FR6 gap). - AR2 — Label relationship. A rendered label names the separator unless the caller supplies an explicit accessible name relationship.
- AR3 — Decorative rule segments. Internal rule elements add no separate role, name, focus target, or interaction.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Divider group | Arrange rule segments and the optional label on one logical axis. | Current source; container geometry from current architecture | supporting | FR1, FR4 |
| Rule | Paint a visible subtle or strong separation line; theme-added values lack a settled fallback. | Current source; custom fallback is the FR3 gap | supporting | FR3 |
| Label | Present optional content between two rules using supporting text tokens. | Current source; no separate target (OQ1) | prominent | FR1–FR2 |
No component-local design decision is recorded.
Theming anatomy
{
"Divider group": {"target": "divider"},
"Rule": {
"none": {
"reason": "unsettled: No current public target reaches this part"
}
},
"Label": {
"none": {
"reason": "unsettled: No current public target reaches this part"
}
}
}
The two none dispositions record that no public target reaches Rule or Label;
OQ1 holds whether they should gain one.
Family and system relationships
architecture:container-paddingowns the inherited internal inset protocol; Divider consumes it only throughisFullBleed.architecture:component-theming-surfacesets the rules for the target, reflected axes, and anatomy qualification, and the requirement that an open visual axis have a deterministic fallback. Divider's custom-value path does not satisfy that requirement (FR3); OQ2 holds the remediation direction.architecture:public-component-apiowns root composition, ref behavior, and compatibility of the released ReactNode label surface.- There is no current Divider family or design record.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, FR2, AR1, AR2 | Divider.test.tsx orientation, label, naming, and numeric-zero tests |
Labelled and unlabelled, numeric zero, explicit names, both orientations | Rendering zero outside the wrapper, an unnamed labelled separator, or role, orientation, or name drift fails. Gap: only the unlabelled horizontal default is in the stable visual baseline (core-divider--default); the vertical layout and the label's type and padding have no automated check. |
audit:Divider/a11y |
| AR3 | Source review | Labelled and unlabelled | Gap: no automated check fails if a rule segment gains a role, name, or tab stop. | audit:Divider/a11y |
| FR3, FR5 | Divider.test.tsx variant and target tests; themingTargets.test.ts; stable visual baseline core-divider--default |
Subtle, strong, both orientations; default | A lost class or orientation/variant reflection fails; a changed default rule paint comes back changed for review. Gap: the strong paint and the unmatched theme-added path have no automated check. |
audit:Divider/theming |
| FR4 | @astryx/no-physical-properties lint rule; Divider.stories.tsx full-bleed fixtures |
Horizontal and vertical, LTR and RTL, absent inset | A physical left/right property in Divider's styles fails lint. Gap: the Divider.test.tsx full-bleed test only checks that the element renders, so no automated check fails when full bleed is not applied, on the wrong axis, or with a non-zero fallback, and no browser right-to-left check covers full bleed. |
audit:Divider/layout |
| FR6 | Divider.test.tsx ref and passthrough tests |
Ref, extra props | A dropped ref or caller prop fails. Gap: the ref test accepts any element, so a ref on a wrapper passes; no test covers the styling-input merge or a caller role or aria-orientation. |
audit:Divider/behavior |
| PR1 | Source review | Every state | Gap: no automated check fails if Divider adds a listener, observer, timer, or effect. | audit:Divider/behavior |
| AR1, AR2 | Accessibility-tree evidence (spec:AST-009 FR3) |
Labelled and unlabelled separators | Gap: no accessibility-tree check proves the separator role, orientation, or name; the unit tests query the DOM. | audit:Divider/a11y |
Decision log
None recorded. The record describes shipped behavior.
Open questions
- OQ1 — Should Rule or Label gain stable public theming targets? (
human-api) No public target reaches them today; that absence does not decide the answer. - OQ2 — Should the open
variantaxis close, or which painting part owns its deterministic custom-value fallback? (human-api) The root target can carry theme paint while the inner rule carries built-in paint. Applying a subtle inner fallback can cover an existing root background; keeping the current path can make the rule disappear. Options: close the axis, move target ownership, or route paint through a reviewed public property.
Content boundary
This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or family/system rules. It links to their owners.