An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): Section records its shipped contract as current (#8810)
Cindy Zhang3f4484887189
diff --git a/packages/core/src/Section/Section.spec.md b/packages/core/src/Section/Section.spec.mdindex a331608fcc..d7d9458f60 100644--- a/packages/core/src/Section/Section.spec.md+++ b/packages/core/src/Section/Section.spec.md@@ -1,17 +1,25 @@---schema_version: 3-template_version: 3+template_version: 7kind: componentid: component:Section-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-10-28owners: [cixzhang]-review_triggers: [theming]+review_triggers: [public-api, layout, theming, accessibility]verified_by:- [packages/core/src/Section/Section.test.tsx, scripts/check-knowledge.mjs]+ [+ packages/core/src/Layout/overlayPaddingReset.test.tsx,+ .github/visual-baseline/manifest.json,+ packages/core/src/serverSafeComponents.test.ts,+ packages/core/src/Section/Section.test.tsx,+ apps/storybook/stories/Section.stories.tsx,+ packages/core/src/theme/themingTargets.test.ts,+ scripts/check-knowledge.mjs,+ ]modules: []families: [family:layout-regions]design_specs: []@@ -27,74 +35,115 @@ system_specs: []# Section component contract+## Contract at a glance++| Area | Contract |+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | A generic page region with `variant`, selected `dividers`, `padding` with axis and edge overrides, and box sizing. |+| Behavior | An outer wrapper takes sizing and caller inputs and escapes a parent's inset; an inner container paints the variant and dividers and publishes its padding. |+| End-user impact | Readers see related content grouped in a region whose edges and spacing line up with the surrounding layout. |+| Builder impact | None; the record describes shipped behavior. |+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact. |+| Review checks | Reject physical left/right dividers or padding, edge padding that does not move its matching container variable, or a nested Section that loses its escape. |+| Governing rules | `family:layout-regions/FR2,FR4,FR5,FR7–FR9`; `architecture:container-padding`; `architecture:public-component-api/INV5,INV6,INV8`. |++This table is a review projection; the body below is authoritative.+## Intent-Section renders a painted container for a page region and places caller-provided-content inside it. This draft records current consumer anatomy and theming-ownership without changing layout, styling, targets, or public API.+Section is the generic painted region of the layout-regions family. It owns+its variant, selected divider edges, component padding, and how a nested+Section escapes its parent's inset.## Compatibility and migration- Released default preserved: `yes`-- Compatibility class: additive documentation only; runtime, DOM, styling,- targets, and public API remain unchanged+- Compatibility class: records shipped behavior; no public prop, default, DOM,+ styling, or target changes- Controlled/uncontrolled behavior: not applicable- Migration decision: noneConsumer migration instructions belong in consumer docs and release notes.+## Current-state impact++- **Painted region shorter than its minimum height (FR1).** With `minHeight`+ and no `height`, the wrapper reaches the minimum but the inner container,+ which carries the background, dividers, and padding, stays at its content+ height. A `muted` or `section` region then paints only its top part, and+ its bottom divider sits above the wrapper's bottom edge.+## Ownership boundary**Owns**-- The painted section container and its existing `section` theming target.+- The outer wrapper and the inner painted container with its `section` target.+- Variant paint, selected divider edges, component padding and its publication,+ and the nested escape.**Does not own / non-goals**-- The caller-provided content rendered inside the section.-- The outer layout wrapper as a consumer-facing anatomy part or theming target.+- Caller content inside the section.+- Slot arrangement — owned by `component:Layout` and its regions.+- Landmark semantics, scrolling, and responsive substitution — not provided by+ Section (`family:layout-regions` FR7–FR9).## Public concepts-No new public concept is introduced. Consumer props and usage remain documented-in `Section.doc.mjs`.+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |+| -------- | ---------------------------------------------------- | ---------------------------------------- | ----------------------------------------- | ---------------- | ------------------- | --------- | ------------------------------------------------------------------------------------------------------- |+| Variant | `section`, `transparent`, `muted`; theme additions | Region background. | Always | `section` | `component:Section` | Stable | A theme-added value with no matching theme rule renders no Section background and keeps `data-variant`. |+| Dividers | any of `top`, `bottom`, `start`, `end` | Which edges draw a 1px border. | Always | none | `component:Section` | Stable | TypeScript rejects other values. |+| Padding | Spacing steps uniform, per axis, or per logical edge | Inner padding, published to descendants. | Always | resolved per FR3 | `component:Section` | Stable | TypeScript rejects other values. |+| Sizing | `width`, `height`, `maxWidth`, `minHeight` | The wrapper's box size. | Always | unset | `component:Section` | Stable | Strings pass through as CSS. |## Behavioral and layout contract-| ID | Candidate invariant | Basis | Draft review state |-| --- | ----------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |-| FR1 | The current render places caller-provided content inside the inner container carrying the `section` target. | Current source, docs, and tests | Verified current behavior; no new behavior decided |+| ID | Invariant | Basis |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |+| FR1 | Section renders an outer `div` wrapper holding an inner `div` that carries the `section` target, reflects `variant`, and holds the children. The inner container fills the wrapper's height. Implementation gap: it fills only a set `height`; under `minHeight` alone the painted container stays at its content height inside a taller wrapper (Current-state impact). | Current source and tests |+| FR2 | `section` paints `--color-background-surface`, `transparent` paints nothing, and `muted` paints `--color-background-muted`; a theme-added variant with no matching theme rule paints no background and still reflects `data-variant` (`architecture:component-theming-surface` INV14). Each selected divider draws a 1px solid `--color-border` border on that edge; `start` and `end` are logical inline edges. | Current source and tests |+| FR3 | An omitted `padding` resolves per edge from the theme's per-edge and per-axis section padding, then the nearest ancestor Section's explicit `padding`, then the theme's single section padding, then spacing step 4. A step sets uniform padding and publishes it as the container-padding variables for descendants, and nested Sections without `padding` inherit it, except across an overlay boundary, where the inherited value stops (`architecture:container-padding` INV5). `paddingInline` and `paddingBlock` override one axis, and an edge prop overrides its edge alone; each override moves the matching container-padding variable. | Current source, tests, and family record |+| FR4 | The wrapper escapes its parent's published container padding: always on both inline edges, and on the block-start edge only as a first child and the block-end edge only as a last child. The inner container resets the inherited padding variables before publishing its own. | Current source and family record |+| FR5 | `ref`, `className`, `style`, `xstyle`, sizing, and DOM, data, ARIA, and event props reach the outer wrapper; numbers in sizing props are pixels. The inner painted container takes none of them; Toolbar relies on the wrapper routing. | Current source and tests |### Allowed variation-- Caller-provided content may vary without becoming Section-owned anatomy.+- **AV1 — Theme paint.** A theme may restyle `section` per `variant` and set+ the section padding.+- **AV2 — Content.** Any caller content fills the region.### Representative states-- The anatomy and target ownership are unchanged across the documented section- variants, sizes, dividers, and padding inputs.+| State | Required invariant | Allowed variation |+| ------------- | --------------------------------------------------------------------------- | ----------------- |+| Default | Surface paint; theme section padding; no dividers. | Content. |+| Divided | 1px borders on selected logical edges. | Edges. |+| Edge override | Only the named edge changes, with its container variable. | Step. |+| Nested | Inner Section escapes the outer inset inline and at first/last block edges. | Variant. |### Transformation and precedence order-- No new layout or style precedence rule is introduced.+- **ORD1 — Padding per edge.** Edge prop → axis prop → `padding` → theme+ per-edge and per-axis section padding → nearest ancestor Section's explicit+ `padding`, not across an overlay boundary → theme single section padding → spacing step 4.### Performance and resources-- No new performance or resource rule is introduced.+- **PR1 — Static render.** Section holds no state and uses no hooks.## Accessibility contract-This draft does not change or extend Section's existing accessibility behavior.+- **AR1 — No semantics added.** Section adds no role, name, landmark, or tab+ stop (`family:layout-regions` FR8); callers supply a role and label when the+ context needs one.## Design relationships-| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |-| ----------------- | ----------------------------------------------------------- | ------------------------------ | ----------------- | ------------------ |-| Section container | Presents the current painted page-region container. | Current source and public docs | Supporting | FR1 |-| Consumer content | Presents content supplied by the caller inside the section. | Caller-supplied content | Context-dependent | FR1 |--The outer layout wrapper remains implementation structure and is not listed as-consumer anatomy.+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ----------------- | ------------------------------------------------------ | ------------------------ | ----------------- | ------------------ |+| Section container | The painted region with optional dividers and padding. | Current source and docs | Supporting | FR1–FR4 |+| Consumer content | Caller content inside the region. | Caller-supplied content | Context-dependent | AR1 |### Theming anatomy@@ -105,29 +154,38 @@ consumer anatomy."Section container": {"target": "section"},"Consumer content": {"none": {- "reason": "unsettled: No Section theming target reaches caller-provided content."+ "reason": "intentional: caller content keeps its own theming ownership; Section applies no content target."}}}```+The outer wrapper is implementation structure and carries no target.+## Family and system relationships-This draft references the current shared owners without restating their rules:-`family:layout-regions`, `architecture:component-theming-surface`,-`architecture:container-padding`, and `architecture:public-component-api`.+- `family:layout-regions` names Section the generic region and a container+ publisher; FR2–FR4 apply its logical direction, padding, and boundary rules.+- `architecture:container-padding` owns the inset protocol Section publishes+ and escapes.+- `architecture:public-component-api` owns caller-input routing; FR5 names+ the outer wrapper as the element that receives caller inputs and `ref`+ under INV5 and INV8.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------------- | ------------------------------------------ | ------------------------------------ | --------------------------------------------------------------------------------------- | ----------------------- |-| FR1 | `Section.test.tsx` structure/target suites | Inner container and consumer content | Moving or removing the target or content fails existing structure and class assertions. | `audit:Section/anatomy` |-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:Section/theming` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |+| FR1, FR2 | `Section.test.tsx` structure and variant tests; stable visual baseline `core-section--default` | Variants; default section | A lost two-div structure, a lost `section` target on the inner `div`, or a lost variant reflection fails; a changed default surface comes back changed for review. Gap: the divider test asserts only that content renders, so divider borders and the `transparent` and `muted` paint have no automated check, and no check asserts the inner container fills the wrapper's height, including the `minHeight` gap. A theme-added variant with no matching rule also has no focused test. | `audit:Section/anatomy` |+| FR3, ORD1 | `Section.test.tsx` padding, propagation, and edge-override tests; `overlayPaddingReset.test.tsx`; `Section.stories.tsx` NestedPaddingInheritance | Uniform, axis, edge, nested | Axis-as-two-edges drift, edge over axis on the end edges, a lost propagated value for nested Sections, an ancestor Section's padding that crosses an overlay boundary, or a container variable (inline or block) that does not move with an edge override fails. Gap: edge over axis on the start edges, axis over uniform, the theme per-edge and per-axis padding ahead of the inherited value, and a variable that stops moving on both the axis and edge paths have no check. | `audit:Section/layout` |+| FR4 | `Section.stories.tsx` nested fixtures in a browser | Nested sections | Gap: no unit test asserts the escape margins; a lost escape is visible in the rendered fixture. | `audit:Section/layout` |+| FR5 | `Section.test.tsx` ref, className, style, and passthrough tests | Caller inputs | A `className` or `style` that misses the outer wrapper, or a dropped `data-testid`, fails. Gap: the ref test accepts either `div`, the passthrough test finds `data-testid` anywhere in the tree so the routing of DOM, data, ARIA, and event props has no check, and the sizing and `xstyle` tests assert only that content renders. | `audit:Section/api` |+| AR1, PR1 | `serverSafeComponents.test.ts`; source review | Every state | A client API (state, a hook) added without a client directive fails `serverSafeComponents.test.ts`. Gap: a client API added together with a client directive passes, and no automated check fails if Section adds a role, name, landmark, or tab stop. | `audit:Section/a11y` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Consumer anatomy and current target | Missing, extra, or stale mappings fail repository validation. | `audit:Section/theming` |## Decision log-None. This draft records current facts and introduces no component-local design-decision.+None recorded. The record describes shipped behavior.## Open questions@@ -135,5 +193,5 @@ None.## Content boundary-This file does not duplicate consumer prop tables, examples, implementation-steps, or system rules. It links to their owners.+This file does not duplicate consumer prop tables/examples, current audit+results, implementation steps, or family/system rules. It links to their owners.