Skip to content

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

TypeScript

docs(Collapsible): define chevron position contract (#6149)

Cindy Zhange074389e9b01
diff --git a/packages/core/src/Collapsible/Collapsible.spec.md b/packages/core/src/Collapsible/Collapsible.spec.md
new file mode 100644
index 0000000000..44b626e93a
--- /dev/null
+++ b/packages/core/src/Collapsible/Collapsible.spec.md
@@ -0,0 +1,210 @@
+---
+schema_version: 3
+template_version: 4
+kind: component
+id: component:Collapsible
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-09-07
+owners: [cixzhang, imdreamrunner]
+review_triggers: [public-api, behavior, layout, accessibility]
+verified_by:
+ [
+ packages/core/src/Collapsible/Collapsible.test.tsx,
+ packages/core/src/Collapsible/CollapsibleGroup.test.tsx,
+ ]
+modules: []
+families: []
+design_specs: []
+architecture:
+ [architecture:public-component-api, architecture:react-component-runtime]
+contributing: [contributing:api-conventions]
+system_specs: [spec:AST-002/DEC-1]
+---
+
+# Collapsible component contract
+
+## Intent
+
+Collapsible reveals and hides one content region from one disclosure trigger. Its
+chevron communicates the same open state in two intentional layout patterns: a
+trailing status indicator or a leading disclosure arrow aligned before a column of
+labels.
+
+The public axis is the chevron's logical position. Callers do not provide arbitrary
+cue content or replace Collapsible's disclosure rendering.
+
+## Compatibility and migration
+
+- Released default preserved: yes. Omitting the new position keeps the current
+ trailing chevron and current no-prop rendering.
+- Compatibility class: additive optional public axis with a stable default.
+- Controlled/uncontrolled behavior: unchanged.
+- Migration decision: `component:Collapsible/DEC-1`.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- the disclosure trigger, its `aria-expanded` / `aria-controls` relationship, and
+ the chevron that represents the open state;
+- the `start | end` logical chevron-position axis;
+- position-specific chevron direction in collapsed and expanded states;
+- group default, item override, and nested-item isolation for chevron position; and
+- trigger-label layout needed to preserve the position contract.
+
+**Does not own / non-goals**
+
+- caller-provided chevron, cue, icon, or render-function escape hatches;
+- TreeList, Table, or another component's disclosure indicator;
+- generic icon resolution or artwork customization;
+- a shared responsive or directional API; or
+- new content-reveal motion behavior. Existing behavior outside this decision stays
+ unchanged until its own current authority changes it.
+
+## Public concepts
+
+| Concept | Closed values or states | Meaning | Availability | Default | Owner | Stability | Invalid-value behavior |
+| ---------------------- | ----------------------- | ---------------------------------------------------------------------------- | -------------------------------- | ----------------------------------------- | -------------------------------------------- | --------- | ----------------------------------------- |
+| chevron position | `start`, `end` | logical side of the trigger label that owns Collapsible's disclosure chevron | Collapsible and CollapsibleGroup | `end` | `component:Collapsible` | stable | rejected by the public type |
+| disclosure state | collapsed, expanded | whether the controlled region is hidden or revealed | every Collapsible | existing state owner | `component:Collapsible` or group state owner | stable | existing controlled/uncontrolled behavior |
+| group position default | absent, `start`, `end` | common position supplied to direct group items | CollapsibleGroup | absent, so item default resolves to `end` | `component:Collapsible` | stable | rejected by the public type |
+
+The public prop is named `chevronPosition`. The exported value type is
+`CollapsibleChevronPosition`. `placement`, `side`, and rendering terminology are
+not parallel public names for this axis.
+
+## Behavioral and layout contract
+
+| ID | Invariant | Basis |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| FR1 | Collapsible MUST expose `chevronPosition?: 'start' \| 'end'`; omission resolves to `end`. | owner API decision; preserves released default |
+| FR2 | `end` MUST render Collapsible's chevron after the trigger label in logical order. Collapsed `end` points downward; expanded `end` points upward. | shipped trailing behavior plus approved position contract |
+| FR3 | `start` MUST render Collapsible's chevron before the trigger label in logical order. Collapsed `start` points inward toward the label/content, so its inline direction mirrors under RTL; expanded `start` points downward. | approved leading-disclosure behavior |
+| FR4 | Position changes the chevron glyph/direction as well as DOM order. Reusing a vertical down chevron and rotating it sideways MUST NOT make collapsed `start` point away from its content. | direction and representation decision |
+| FR5 | Collapsible owns and renders the chevron for both positions. The position axis MUST NOT accept `none`, arbitrary React content, a cue callback, a renderer, or another replacement escape hatch. | constrained public-axis decision |
+| FR6 | Trigger-label content MUST retain the usable row width needed by composed labels at either position. Moving the chevron to `start` MUST NOT strand the label at the opposite edge or prevent composed label content from using the remaining row. | approved layout rationale and existing grow behavior |
+| FR7 | CollapsibleGroup MAY provide one `chevronPosition` default to its direct Collapsible items. A direct item's explicit position MUST override the group default. | approved group-coherence behavior |
+| FR8 | A Collapsible nested inside another item's revealed content MUST begin a new presentation scope and use its own explicit position or the component default. The outer group's position MUST NOT leak into the nested disclosure. | approved nested isolation behavior |
+| FR9 | Chevron position MUST NOT change disclosure semantics. The same trigger remains a button, retains `aria-expanded`, identifies the controlled region with `aria-controls`, and follows the existing state owner. | existing accessibility and behavior contract |
+
+### Allowed variation
+
+- **AV1 — Artwork implementation.** The exact internal Icon names and transform
+ implementation may change if FR2–FR4 remain visually and directionally true.
+- **AV2 — Spacing mechanism.** Margin, gap, or equivalent internal layout may
+ separate a leading chevron from its label while preserving FR6.
+- **AV3 — Group consistency.** An item may explicitly override its group's
+ position. Mixed positions are supported by precedence but should remain an
+ intentional exception rather than an accidental row-to-row pattern.
+- **AV4 — Existing non-chevron behavior.** Open-state ownership, disabled behavior,
+ divider/density presentation, content layout, and reveal motion remain governed
+ by their existing authority and are not changed by this decision.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| ---------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------ |
+| omitted position, collapsed | chevron follows label and points down | internal icon implementation |
+| omitted position, expanded | chevron follows label and points up | internal rotation implementation |
+| `start`, collapsed LTR | chevron precedes label and points inline-end toward content | internal artwork |
+| `start`, collapsed RTL | chevron precedes label at logical start and points inline-end toward content | internal artwork/mirroring mechanism |
+| `start`, expanded | chevron precedes label and points down | internal transition mechanism |
+| group `start`, item omitted | direct item resolves to `start` | presentation-context implementation |
+| group `start`, item `end` | direct item resolves to `end` | presentation-context implementation |
+| group `start`, nested item omitted | nested item resolves to component default `end` | context-reset implementation |
+
+### Transformation and precedence order
+
+- **ORD1 — Position precedence.** Item `chevronPosition` → direct surrounding
+ CollapsibleGroup `chevronPosition` → component default `end`.
+- **ORD2 — Direction resolution.** Resolve position and open state first; apply
+ document direction to `start`'s inward inline direction. `end` remains a vertical
+ down/up indicator and does not mirror into a horizontal cue.
+
+## Accessibility contract
+
+- **AR1 — Disclosure semantics stay primary.** The trigger MUST expose its expanded
+ state and controlled-region relationship independently of the chevron artwork.
+- **AR2 — Position is visual order, not reading duplication.** Moving the decorative
+ chevron MUST NOT duplicate the accessible name or add a second focus target.
+- **AR3 — Direction remains understandable.** The collapsed leading cue MUST point
+ toward the content in both LTR and RTL; it MUST NOT retain an LTR physical
+ direction under RTL.
+
+## Design relationships
+
+The two positions express established disclosure patterns:
+
+- `end` is a trailing status indicator: down when collapsed, up when expanded;
+- `start` is a leading tree/file-browser disclosure arrow: inward when collapsed,
+ down when expanded.
+
+This contract chooses those relationships but does not expose arbitrary icon or cue
+selection. Themes may style the owning Collapsible target without changing the
+semantic direction or position states.
+
+## Family and system relationships
+
+- The public `useCollapsible` hook retains its existing state behavior and consumer
+ documentation. This component owns the rendered trigger, chevron, and aggregate
+ component/group protocol.
+- `architecture:public-component-api` owns reachability and compatibility of the
+ admitted position prop and exported type.
+- `architecture:react-component-runtime` owns context identity/lifecycle; this
+ record owns the presentation value and nested-scope outcome.
+- `spec:AST-002/DEC-1` admits this axis because otherwise-identical disclosure
+ layouts require caller-owned leading versus trailing patterns. It does not admit
+ custom cue rendering.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------ | ---------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| FR1–FR5 | Collapsible prop/type, DOM-order, glyph/direction, and no-extra-values tests | omitted/end/start; collapsed/expanded; LTR/RTL | default changes, `start` follows the label, collapsed leading cue points outward, or an unsupported cue value is admitted | audit:Collapsible/public-api |
+| FR6 | composed trigger layout and geometry tests | plain text; composed label with trailing content; start/end | label becomes shrink-wrapped/stranded or composed content cannot use remaining row | audit:Collapsible/layout |
+| FR7–FR8, ORD1 | group inheritance, item override, and nested reset tests | group start/end; item override; nested omission | group value is ignored, item cannot override, or position leaks into nested content | audit:Collapsible/behavior |
+| FR9, AR1–AR3, ORD2 | disclosure semantics plus real RTL rendering | collapsed/expanded; start/end; LTR/RTL | position changes state behavior, duplicates accessible output, or leading direction fails to mirror | audit:Collapsible/accessibility |
+
+## Decision log
+
+### DEC-1 — Chevron position is the public axis
+
+**Reference:** `component:Collapsible/DEC-1`
+**Decider:** `cixzhang`, `2026-09-07`
+
+Callers may choose the logical chevron position `start` or `end`. Collapsible owns
+the cue and derives its position-specific glyph and direction. `start` exists for
+leading disclosure patterns such as tree/file-browser rows; `end` preserves the
+released trailing indicator.
+
+Rejected: `chevronPlacement`, `none`, `hasChevron`, caller-provided cue content, and
+rendering callbacks. Those surfaces expose rendering machinery or permit the
+component's disclosure affordance to disappear rather than expressing the approved
+caller-owned layout distinction.
+
+### DEC-2 — Group defaults do not leak through content
+
+**Reference:** `component:Collapsible/DEC-2`
+**Decider:** `cixzhang`, `2026-09-07`
+
+A CollapsibleGroup may provide position to its direct items, and an item may
+override it. A Collapsible nested inside an item's body starts a new presentation
+scope so an outer list's visual convention does not silently alter an independent
+disclosure.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file owns Collapsible's durable semantic concepts, chevron-position behavior,
+precedence, and evidence. Consumer prop tables/examples remain in
+`Collapsible.doc.mjs` and `CollapsibleGroup.doc.mjs`. Exact Icon names, transforms,
+StyleX declarations, context fields, implementation plans, audit results, and pull-
+request verdicts do not belong here.