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.mdindex 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: 3template_version: 7kind: componentid: component:Divider-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-10-27owners: [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 fullbleed.-- 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, includingnumeric zero, stay inside the label wrapper; skipped scalar labels leave onecontinuous 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 theproduct 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-invalues 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 thecaller 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, andcompatibility 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 itsdeterministic custom-value fallback?** (`human-api`) The root target can carrytheme paint while the inner rule carries built-in paint. Applying a subtle innerfallback 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.