Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(spec): Divider records its shipped contract as current (#8743)

Cindy Zhang16443d084a23
diff --git a/packages/core/src/Divider/Divider.spec.md b/packages/core/src/Divider/Divider.spec.md
index 78fbd25a15..d3bcaa4ab5 100644
--- a/packages/core/src/Divider/Divider.spec.md
+++ b/packages/core/src/Divider/Divider.spec.md
@@ -3,15 +3,16 @@ schema_version: 3
template_version: 7
kind: component
id: component:Divider
-authority: draft
+authority: current
archive_reason: null
superseded_by: null
-approved_by: null
-approved_at: 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,
@@ -27,22 +28,22 @@ architecture:
architecture:component-test-sufficiency,
]
contributing: []
-system_specs: [spec:AST-020, spec:AST-029]
+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. The theme-extensible variant axis has no settled no-match line-paint fallback. |
-| End-user impact | People can perceive a named separator across horizontal, vertical, labelled, full-bleed, narrow, and RTL compositions. A custom theme variant can still lose its line paint; OQ2 records that retained gap. |
-| Builder impact | No new caller choice. Numeric zero remains a valid label; booleans and empty strings leave one continuous unnamed rule. |
-| Compatibility/readiness | Patch-compatible observational contract. Public props, defaults, target names, and built-in appearances remain unchanged; authority stays `draft` until exact-head owner approval. |
-| Review checks | Reject missing numeric labels, physical-edge bleed, dropped root inputs, or a target/axis that disagrees with the rendered separator. Keep the custom-variant paint gap unresolved until OQ2 is settled. |
-| 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`. |
+| 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.
@@ -59,7 +60,8 @@ Consumer syntax and examples belong in `Divider.doc.mjs`.
- Released default preserved: yes — horizontal, subtle, unlabelled, and not full
bleed.
-- Compatibility class: patch fix. ReactNode values that React renders, including
+- 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.
@@ -67,6 +69,19 @@ Consumer syntax and examples belong in `Divider.doc.mjs`.
Consumer migration instructions belong in consumer docs and release notes.
+## Current-state impact
+
+- **Theme-added variant without line paint (FR3).** `DividerVariantMap` admits
+ theme-added values, but an unmatched value leaves the inner rule unpainted, so
+ the line can disappear. `architecture:component-theming-surface` INV14
+ requires an extensible visual axis to have a safe theme-independent baseline;
+ OQ2 holds the remediation direction.
+- **Caller `role` and `aria-orientation` replaced (FR6).** Divider sets
+ `role="separator"` and `aria-orientation` after caller props, so a caller's
+ explicit values never reach the root, where
+ `architecture:public-component-api` INV5 lets a caller's explicit input reach
+ the element.
+
## Ownership boundary
**Owns**
@@ -76,8 +91,8 @@ Consumer migration instructions belong in consumer docs and release notes.
- Horizontal and vertical rule geometry.
- Optional label placement and the separator naming relationship.
- Built-in subtle and strong line weights.
-- The current reflected custom-variant state, including the missing deterministic
- line-paint fallback recorded by OQ2.
+- 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 `divider` target with reflected orientation and variant axes.
@@ -86,33 +101,30 @@ Consumer migration instructions belong in consumer docs and release notes.
- 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 — unresolved under OQ1.
+- 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 —
- unresolved under OQ2.
+ 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 has no deterministic line-paint baseline; see OQ2 |
-| 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; component-owned role and orientation remain authoritative |
+| 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
-Draft requirements identify their basis so observed code is not mistaken for an
-intentional decision.
-
-| ID | Candidate invariant | Basis | Draft review state |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------- |
-| FR1 | The divider MUST render one rule without a renderable label and two rules with the label between them. Numeric zero MUST remain a renderable label. | Released ReactNode API; current source/docs; `architecture:public-component-api/INV9` | verify |
-| FR2 | The root MUST expose `role="separator"` and the selected `aria-orientation`. A renderable label MUST name it through `aria-labelledby` unless an explicit caller `aria-label` or `aria-labelledby` wins. | WCAG 2.2 SC 1.3.1 and 4.1.2; current source/tests | verify |
-| FR3 | Built-in variants MUST paint subtle or strong lines. The exported map accepts theme-added values, but an unmatched value currently leaves the inner rule without line paint; the correct fallback/target ownership requires OQ2. | `architecture:component-theming-surface/INV4,INV6,INV14`; exported `DividerVariantMap` | human decision; open BLOCK |
-| FR4 | Full bleed MUST consume inherited logical inline inset for horizontal dividers and logical block inset for vertical dividers; absent inset MUST resolve to zero. | `architecture:container-padding/INV1,INV3,INV7–INV10` | verify |
-| FR5 | The root MUST carry the `divider` target and reflect orientation and requested variant. Rule and Label currently carry no public target. | `architecture:component-theming-surface/INV3–INV6`; current metadata | verify; part exposure unsettled |
-| FR6 | Accepted ref, DOM/data/ARIA, class, style, events, and `xstyle` MUST reach or compose on the separator root without replacing component-owned role or orientation. | `architecture:public-component-api/INV5–INV8` | verify |
+| 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
@@ -131,7 +143,7 @@ intentional decision.
| 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 (open BLOCK) | Custom variant name |
+| 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 |
@@ -144,7 +156,7 @@ intentional decision.
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 pending OQ2.
+ inner-rule paint (FR3).
### Performance and resources
@@ -153,8 +165,10 @@ intentional decision.
## Accessibility contract
-- **AR1 — Programmatic separator.** The root exposes separator role and the exact
- visual orientation.
+- **AR1 — Programmatic separator.** By default the root exposes separator role
+ and the exact visual orientation; a caller's explicit `role` or
+ `aria-orientation` wins (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,
@@ -164,11 +178,11 @@ intentional decision.
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
| ---------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | -------------- | ------------------ |
-| Divider group | Arrange rule segments and the optional label on one logical axis. | observed; container geometry settled by current architecture | supporting | FR1, FR4 |
-| Rule | Paint a visible subtle or strong separation line; theme-added values lack a settled fallback. | built-ins observed; custom fallback unsettled | supporting | FR3 |
-| Label | Present optional content between two rules using supporting text tokens. | observed; separate target exposure unsettled | prominent | FR1–FR2 |
+| 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 visual decision is settled by this draft.
+No component-local design decision is recorded.
### Theming anatomy
@@ -190,54 +204,49 @@ No component-local visual decision is settled by this draft.
}
```
-The two `none` dispositions record current reachability while target exposure
-remains unsettled. They do not decide that Rule or Label should remain without
-public targets.
+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-padding` owns the inherited internal inset protocol;
Divider consumes it only through `isFullBleed`.
-- `architecture:component-theming-surface` owns the aggregate target, reflected
- axes, anatomy qualification, and the requirement that an open visual axis have
- a deterministic fallback. Divider's current custom-value path does not satisfy
- that requirement; OQ2 keeps remediation out of this objective audit patch.
+- `architecture:component-theming-surface` sets 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-api` owns root composition, ref behavior, and
compatibility of the released ReactNode label surface.
- There is no current Divider family or design record.
-- `spec:AST-029` keeps this observational draft separate from the audit receipt.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ---------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------- |
-| FR1–FR2, AR1–AR3 | `Divider.test.tsx`; component-owned Storybook states; scoped axe | labelled/unlabelled, numeric zero, explicit names, both orientations | Truthiness renders zero outside wrappers or leaves the separator unnamed; role/orientation/name drift fails | `audit:Divider/§1,§4` |
-| FR3 | Source review; global extensible-axis structural guard | subtle, strong, unmatched theme-added value | The current unmatched path leaves the rule unpainted; no Divider-specific browser fallback proof exists | `audit:Divider/§2` |
-| FR4 | Source review; horizontal and vertical full-bleed stories | inline/block, LTR/RTL logical properties, absent inset | A physical property or wrong axis consumes unrelated container geometry | `audit:Divider/§5,§9,§10` |
-| FR5 | `themingTargets.test.ts`; component metadata; spec anatomy map | both orientations and variants | Target/axis/anatomy metadata disagrees with runtime reflection | `audit:Divider/§2` |
-| FR6 | `Divider.test.tsx`; lint, typecheck, and source review | ref, DOM/data/ARIA, class/style/xstyle/events | An accepted input is dropped or component-owned semantics are overwritten | `audit:Divider/§3` |
-| PR1 | Source review | every state | A lifecycle mechanism appears without a resource contract | `audit:Divider/§7` |
+| 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. This draft records current facts and introduces no component-local design
-or theming decision.
+None recorded. The record describes shipped behavior.
## Open questions
- **OQ1 — Should Rule or Label gain stable public theming targets?** (`human-api`)
- Their target exposure is unsettled; the current lack of reachability does not
- decide the answer.
+ No public target reaches them today; that absence does not decide the answer.
- **OQ2 — Should the open `variant` axis 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. Current authority requires a safe fallback but does not choose
- between closing the axis, moving target ownership, or routing paint through a
- reviewed public property.
+ 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 scores,
-screenshot matrices, implementation steps, or system rules. The audit pull request
-owns the closed run evidence required by `spec:AST-029/FR5`.
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.