# Divider

A full-width content separator that renders either a labeled section band or a plain hairline.

Version: 0.2.0-preview.1 (preview)
Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721
Contract kind: source-derived
Source: packages/design-system/src/components/primitives/Divider/Divider.tsx

## Guidance

{
  "summary": "A full-width content separator that renders either a labeled section band or a plain hairline.",
  "guidance": [
    {
      "heading": "Overview",
      "body": "A separator between content groups. Pass a `label` for a titled band, or leave it off for\na plain hairline."
    },
    {
      "heading": "Use when",
      "body": "Match `surface` to the container the divider sits in: `page` is the cream, borderless band\nfor the scroll-feed background; `surface` is white with a bottom hairline for grouping rows\ninside a Card."
    }
  ],
  "usage": [
    {
      "variant": "section",
      "use": "A labeled band that groups a scroll feed by time or category (Today, Yesterday). Defaults on when `label` is set.",
      "avoid": "A heading that needs a trailing action — use `SectionHeader`.",
      "axis": "Variant"
    },
    {
      "variant": "line",
      "use": "A plain hairline between rows or blocks when the group needs no title.",
      "avoid": "Grouping that reads better with a label — use section.",
      "axis": "Variant"
    }
  ],
  "examples": [],
  "source": "packages/design-system/src/components/primitives/Divider/Divider.mdx",
  "status": "local-preview",
  "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification."
}

## Contract and public API

```json
{
  "props": [
    {
      "name": "variant",
      "type": "DividerVariant | undefined",
      "declared_type": "DividerVariant",
      "required": false,
      "description": "`section` renders a labeled band; `line` renders a hairline separator.",
      "source": {
        "path": "packages/design-system/src/components/primitives/Divider/Divider.tsx",
        "line": 18
      },
      "values": [
        "line",
        "section"
      ],
      "values_complete": true
    },
    {
      "name": "label",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Label shown inside a section divider.",
      "source": {
        "path": "packages/design-system/src/components/primitives/Divider/Divider.tsx",
        "line": 20
      }
    },
    {
      "name": "surface",
      "type": "DividerSurface | undefined",
      "declared_type": "DividerSurface",
      "required": false,
      "description": "Band treatment. `page` is the cream band (default); `surface` is the white\nband for in-card grouping. Both are borderless — spacing separates groups.",
      "source": {
        "path": "packages/design-system/src/components/primitives/Divider/Divider.tsx",
        "line": 25
      },
      "values": [
        "page",
        "surface"
      ],
      "values_complete": true,
      "default": "'page'",
      "default_kind": "source-expression"
    },
    {
      "name": "className",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/primitives/Divider/Divider.tsx",
        "line": 26
      }
    },
    {
      "name": "style",
      "type": "React.CSSProperties | undefined",
      "declared_type": "React.CSSProperties",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/primitives/Divider/Divider.tsx",
        "line": 27
      }
    },
    {
      "name": "testId",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Selector on the divider root; the section label renders inside it with none of its own.",
      "source": {
        "path": "packages/design-system/src/components/primitives/Divider/Divider.tsx",
        "line": 29
      }
    }
  ],
  "prop_shapes": {},
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "Divider",
    "public_path": "Divider",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "Divider",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/primitives/Divider/Divider.tsx",
          "line": 36
        },
        "props_type": "DividerProps",
        "props": [
          {
            "name": "variant",
            "type": "DividerVariant | undefined",
            "declared_type": "DividerVariant",
            "required": false,
            "description": "`section` renders a labeled band; `line` renders a hairline separator.",
            "source": {
              "path": "packages/design-system/src/components/primitives/Divider/Divider.tsx",
              "line": 18
            },
            "values": [
              "line",
              "section"
            ],
            "values_complete": true
          },
          {
            "name": "label",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Label shown inside a section divider.",
            "source": {
              "path": "packages/design-system/src/components/primitives/Divider/Divider.tsx",
              "line": 20
            }
          },
          {
            "name": "surface",
            "type": "DividerSurface | undefined",
            "declared_type": "DividerSurface",
            "required": false,
            "description": "Band treatment. `page` is the cream band (default); `surface` is the white\nband for in-card grouping. Both are borderless — spacing separates groups.",
            "source": {
              "path": "packages/design-system/src/components/primitives/Divider/Divider.tsx",
              "line": 25
            },
            "values": [
              "page",
              "surface"
            ],
            "values_complete": true,
            "default": "'page'",
            "default_kind": "source-expression"
          },
          {
            "name": "className",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/primitives/Divider/Divider.tsx",
              "line": 26
            }
          },
          {
            "name": "style",
            "type": "React.CSSProperties | undefined",
            "declared_type": "React.CSSProperties",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/primitives/Divider/Divider.tsx",
              "line": 27
            }
          },
          {
            "name": "testId",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Selector on the divider root; the section label renders inside it with none of its own.",
            "source": {
              "path": "packages/design-system/src/components/primitives/Divider/Divider.tsx",
              "line": 29
            }
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/primitives/Divider/Divider.tsx",
        "line": 6,
        "name": "DividerVariant",
        "code": "export type DividerVariant = 'section' | 'line';"
      },
      {
        "path": "packages/design-system/src/components/primitives/Divider/Divider.tsx",
        "line": 7,
        "name": "DividerSurface",
        "code": "export type DividerSurface = 'page' | 'surface';"
      },
      {
        "path": "packages/design-system/src/components/primitives/Divider/Divider.tsx",
        "line": 16,
        "name": "DividerProps",
        "code": "export interface DividerProps {\n    /** `section` renders a labeled band; `line` renders a hairline separator. */\n    variant?: DividerVariant;\n    /** Label shown inside a section divider. */\n    label?: string;\n    /**\n     * Band treatment. `page` is the cream band (default); `surface` is the white\n     * band for in-card grouping. Both are borderless — spacing separates groups.\n     */\n    surface?: DividerSurface;\n    className?: string;\n    style?: React.CSSProperties;\n    /** Selector on the divider root; the section label renders inside it with none of its own. */\n    testId?: string;\n}"
      }
    ],
    "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source."
  },
  "spec": {
    "$schema": "../../../specs/component-spec.schema.json",
    "identity": {
      "name": "Divider",
      "status": "preview",
      "version": "1.1.0",
      "summary": "A full-width content separator that renders either a labeled section band or a plain hairline."
    },
    "parts": [
      {
        "id": "separator",
        "label": "Separator",
        "description": "Owns full-width separator semantics and the selected treatment."
      },
      {
        "id": "section-band",
        "label": "Section band",
        "description": "Provides inset space and a surface behind a section label."
      },
      {
        "id": "label",
        "label": "Label",
        "description": "Names the following section when the section variant is used."
      },
      {
        "id": "line",
        "label": "Line",
        "description": "Draws the unlabeled hairline treatment."
      }
    ],
    "allowedDesignChoices": {
      "variants": {
        "section": {
          "label": "Section"
        },
        "line": {
          "label": "Line"
        }
      },
      "sizes": {},
      "surfaces": {
        "page": {
          "label": "Page",
          "description": "Uses the page background for a section band."
        },
        "surface": {
          "label": "Surface",
          "description": "Uses the raised surface background for a section band. Borderless — spacing separates groups."
        }
      }
    },
    "variants": [
      {
        "id": "section",
        "label": "Section",
        "description": "A labeled band for separating larger content groups.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      },
      {
        "id": "line",
        "label": "Line",
        "description": "An unlabeled hairline between adjacent content.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      }
    ],
    "sizes": [],
    "measurements": [
      {
        "id": "line-thickness",
        "label": "Line thickness",
        "kind": "exact",
        "token": "--cds-border-width-default",
        "value": 1,
        "unit": "px",
        "appliesTo": [
          "line"
        ]
      },
      {
        "id": "section-horizontal-inset",
        "label": "Section horizontal inset",
        "kind": "exact",
        "token": "--cds-space-20",
        "value": 20,
        "unit": "px",
        "appliesTo": [
          "section-band",
          "label"
        ]
      },
      {
        "id": "section-top-inset",
        "label": "Section top inset",
        "kind": "exact",
        "token": "--cds-space-32",
        "value": 32,
        "unit": "px",
        "appliesTo": [
          "section-band",
          "label"
        ]
      },
      {
        "id": "section-bottom-inset",
        "label": "Section bottom inset",
        "kind": "exact",
        "token": "--cds-space-12",
        "value": 12,
        "unit": "px",
        "appliesTo": [
          "section-band",
          "label"
        ]
      }
    ],
    "layout": {
      "alignment": "The separator spans its parent width; section labels align to the leading inset.",
      "flow": "A line consumes one stroke of height; a section band wraps one uppercase label.",
      "notes": [
        "A label automatically selects the section treatment unless a variant is explicit.",
        "The surface choice is page or raised surface and does not create another public variant."
      ]
    },
    "typographyAndColor": {
      "typography": [
        {
          "label": "Section label",
          "description": "Uses the compact link ramp and uppercase presentation.",
          "token": "--cds-type-link-size"
        }
      ],
      "colors": [
        {
          "label": "Hairline",
          "description": "Uses the theme-aware divider role.",
          "token": "--cds-divider"
        },
        {
          "label": "Page band",
          "description": "Uses the page background when separating feed sections.",
          "token": "--cds-bg-page"
        },
        {
          "label": "Surface band",
          "description": "Uses the raised surface background inside a card.",
          "token": "--cds-bg-surface"
        },
        {
          "label": "Section label",
          "description": "Uses primary text emphasis.",
          "token": "--cds-text-primary"
        }
      ]
    },
    "states": [
      {
        "id": "section-page",
        "label": "Section on page",
        "description": "Shows a borderless labeled band on the page canvas."
      },
      {
        "id": "section-surface",
        "label": "Section on surface",
        "description": "Shows a labeled raised band with a bottom hairline."
      },
      {
        "id": "line",
        "label": "Line",
        "description": "Shows only the theme-aware hairline."
      }
    ],
    "behavior": [
      {
        "label": "Variant inference",
        "description": "Resolve to section when a label exists and line when no label exists, unless the caller selects a variant."
      },
      {
        "label": "Separation only",
        "description": "Do not make the separator interactive or use it as a heading with an action."
      }
    ],
    "accessibility": [
      {
        "label": "Separator semantics",
        "description": "Expose separator role for both the line and section treatments."
      },
      {
        "label": "Section label",
        "description": "Keep the visible label concise; use a real heading component when document hierarchy is required."
      }
    ],
    "contentAdaptation": [
      {
        "label": "Labels",
        "description": "Use short section names that remain readable when transformed to uppercase."
      }
    ],
    "motionHaptics": {
      "motion": [
        {
          "label": "No motion",
          "description": "Divider has no animated state transition."
        }
      ],
      "haptics": [
        {
          "label": "No feedback",
          "description": "Divider is not interactive and does not request haptic feedback."
        }
      ]
    },
    "platformDifferences": []
  },
  "platforms": {
    "implemented": [
      "web"
    ],
    "native": "Imported design guidance only; no native implementation or parity verification in this preview.",
    "react": {
      "implementation": "local",
      "status": "preview",
      "parity": "web-reference"
    },
    "vue": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "swift": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    },
    "kotlin": {
      "implementation": "absent",
      "parity": "not-verified",
      "status": "reference-only"
    }
  },
  "tokens": [
    {
      "name": "--cds-border-width-default",
      "light": "1px",
      "dark": "1px"
    },
    {
      "name": "--cds-space-20",
      "light": "20px",
      "dark": "20px"
    },
    {
      "name": "--cds-space-32",
      "light": "32px",
      "dark": "32px"
    },
    {
      "name": "--cds-space-12",
      "light": "12px",
      "dark": "12px"
    },
    {
      "name": "--cds-type-link-size",
      "light": "0.75rem",
      "dark": "0.75rem"
    },
    {
      "name": "--cds-divider",
      "light": "#e0ddd6",
      "dark": "#ffffff1a"
    },
    {
      "name": "--cds-bg-page",
      "light": "#f3f1ed",
      "dark": "#141410"
    },
    {
      "name": "--cds-bg-surface",
      "light": "#ffffff",
      "dark": "#1b1b18"
    },
    {
      "name": "--cds-text-primary",
      "light": "#141410",
      "dark": "#f3f1ed"
    }
  ],
  "review": {
    "local_status": "not-reviewed",
    "source_approval": null,
    "imported_spec_status": "approved",
    "spec_origin": "imported-adapted",
    "local_spec_source_status": "approved",
    "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1",
    "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract."
  },
  "missing_facts": [
    {
      "code": "human-review-pending",
      "detail": "This local preview has no recorded human design or engineering sign-off."
    },
    {
      "code": "platform-parity-unverified",
      "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified."
    },
    {
      "code": "figma-mapping-unverified",
      "detail": "No current component-level Figma node and immutable revision have been verified for this contract."
    }
  ]
}
```

## Visual states

- [Section On Page](/storybook/iframe.html?id=cloaked-design-system-primitives-divider--section-on-page&viewMode=story) | export: SectionOnPage | source: packages/design-system/src/components/primitives/Divider/Divider.stories.tsx

- [Section On Surface](/storybook/iframe.html?id=cloaked-design-system-primitives-divider--section-on-surface&viewMode=story) | export: SectionOnSurface | source: packages/design-system/src/components/primitives/Divider/Divider.stories.tsx

- [Line](/storybook/iframe.html?id=cloaked-design-system-primitives-divider--line&viewMode=story) | export: Line | source: packages/design-system/src/components/primitives/Divider/Divider.stories.tsx

- [Line On Surface](/storybook/iframe.html?id=cloaked-design-system-primitives-divider--line-on-surface&viewMode=story) | export: LineOnSurface | source: packages/design-system/src/components/primitives/Divider/Divider.stories.tsx

- [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-primitives-divider--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/primitives/Divider/Divider.stories.tsx

Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.