# Grid

An equal-width column grid backed by CSS Grid, column-first with token-scale gaps and cell alignment.

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

## Guidance

{
  "summary": "An equal-width column grid backed by CSS Grid, column-first with token-scale gaps and cell alignment.",
  "guidance": [
    {
      "heading": "Overview",
      "body": "Equal-width column grid backed by CSS Grid (`repeat(columns, 1fr)`). Set the column count and\nrows fill implicitly as children flow in."
    },
    {
      "heading": "When to use",
      "body": "Reach for `Grid` when you want a **two-dimensional** layout of uniform tiles — metric cards, a\ndashboard's widget picker, a stat grid. Every column is `1fr`, so tiles share width evenly and\nwrap into new rows automatically.\n\n-   Only laying out **one axis** (a column or a row)? Use `VStack` or `HStack` — they are simpler\n    and don't force equal widths.\n-   Showing **one item per view with swiping**? Use `Carousel`.\n\nBecause tracks are `1fr` and fill the container, `align` (align-items) controls how uneven-height\ncells line up, while `justify` is usually a no-op."
    }
  ],
  "usage": [],
  "examples": [],
  "source": "packages/design-system/src/components/layout/Grid/Grid.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": "columns",
      "type": "number",
      "declared_type": "number",
      "required": true,
      "description": "Number of equal-width columns. Produces `repeat(N, 1fr)`.",
      "source": {
        "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
        "line": 35
      }
    },
    {
      "name": "gap",
      "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
      "declared_type": "GridGap",
      "required": false,
      "description": "Uniform gap between columns and rows, in `--cds-space-*` steps.",
      "source": {
        "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
        "line": 37
      },
      "values": [
        0,
        12,
        120,
        16,
        20,
        24,
        240,
        32,
        4,
        40,
        48,
        56,
        64,
        72,
        8,
        80,
        96
      ],
      "values_complete": true
    },
    {
      "name": "gapX",
      "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
      "declared_type": "GridGap",
      "required": false,
      "description": "Horizontal gap between columns, overrides `gap`.",
      "source": {
        "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
        "line": 39
      },
      "values": [
        0,
        12,
        120,
        16,
        20,
        24,
        240,
        32,
        4,
        40,
        48,
        56,
        64,
        72,
        8,
        80,
        96
      ],
      "values_complete": true
    },
    {
      "name": "gapY",
      "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
      "declared_type": "GridGap",
      "required": false,
      "description": "Vertical gap between rows, overrides `gap`.",
      "source": {
        "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
        "line": 41
      },
      "values": [
        0,
        12,
        120,
        16,
        20,
        24,
        240,
        32,
        4,
        40,
        48,
        56,
        64,
        72,
        8,
        80,
        96
      ],
      "values_complete": true
    },
    {
      "name": "align",
      "type": "StackAlign | undefined",
      "declared_type": "GridAlign",
      "required": false,
      "description": "Vertical alignment of items within their cells (`align-items`).",
      "source": {
        "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
        "line": 43
      },
      "values": [
        "baseline",
        "center",
        "end",
        "start",
        "stretch"
      ],
      "values_complete": true
    },
    {
      "name": "justify",
      "type": "StackJustify | undefined",
      "declared_type": "GridJustify",
      "required": false,
      "description": "Horizontal distribution of the grid tracks (`justify-content`).",
      "source": {
        "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
        "line": 45
      },
      "values": [
        "around",
        "between",
        "center",
        "end",
        "evenly",
        "start"
      ],
      "values_complete": true
    },
    {
      "name": "as",
      "type": "React.ElementType<any, keyof React.JSX.IntrinsicElements> | undefined",
      "declared_type": "React.ElementType",
      "required": false,
      "description": "Rendered element. Defaults to `div`.",
      "source": {
        "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
        "line": 47
      },
      "default": "'div'",
      "default_kind": "source-expression"
    },
    {
      "name": "className",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
        "line": 48
      }
    },
    {
      "name": "style",
      "type": "React.CSSProperties | undefined",
      "declared_type": "React.CSSProperties",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
        "line": 49
      }
    },
    {
      "name": "children",
      "type": "React.ReactNode",
      "declared_type": "React.ReactNode",
      "required": false,
      "description": "",
      "source": {
        "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
        "line": 50
      }
    },
    {
      "name": "testId",
      "type": "string | undefined",
      "declared_type": "string",
      "required": false,
      "description": "Optional test selector, placed on the `as` element.",
      "source": {
        "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
        "line": 52
      }
    },
    {
      "name": "padding",
      "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
      "declared_type": "CdsSpace",
      "required": false,
      "description": "Padding on all four sides.",
      "source": {
        "path": "packages/design-system/src/components/layout/resolvePadding.ts",
        "line": 10
      },
      "values": [
        0,
        12,
        120,
        16,
        20,
        24,
        240,
        32,
        4,
        40,
        48,
        56,
        64,
        72,
        8,
        80,
        96
      ],
      "values_complete": true
    },
    {
      "name": "paddingX",
      "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
      "declared_type": "CdsSpace",
      "required": false,
      "description": "Horizontal padding (left + right). Overrides `padding` on the X axis.",
      "source": {
        "path": "packages/design-system/src/components/layout/resolvePadding.ts",
        "line": 12
      },
      "values": [
        0,
        12,
        120,
        16,
        20,
        24,
        240,
        32,
        4,
        40,
        48,
        56,
        64,
        72,
        8,
        80,
        96
      ],
      "values_complete": true
    },
    {
      "name": "paddingY",
      "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
      "declared_type": "CdsSpace",
      "required": false,
      "description": "Vertical padding (top + bottom). Overrides `padding` on the Y axis.",
      "source": {
        "path": "packages/design-system/src/components/layout/resolvePadding.ts",
        "line": 14
      },
      "values": [
        0,
        12,
        120,
        16,
        20,
        24,
        240,
        32,
        4,
        40,
        48,
        56,
        64,
        72,
        8,
        80,
        96
      ],
      "values_complete": true
    },
    {
      "name": "paddingTop",
      "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
      "declared_type": "CdsSpace",
      "required": false,
      "description": "Top padding. Overrides `paddingY` and `padding`.",
      "source": {
        "path": "packages/design-system/src/components/layout/resolvePadding.ts",
        "line": 16
      },
      "values": [
        0,
        12,
        120,
        16,
        20,
        24,
        240,
        32,
        4,
        40,
        48,
        56,
        64,
        72,
        8,
        80,
        96
      ],
      "values_complete": true
    },
    {
      "name": "paddingRight",
      "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
      "declared_type": "CdsSpace",
      "required": false,
      "description": "Right padding. Overrides `paddingX` and `padding`.",
      "source": {
        "path": "packages/design-system/src/components/layout/resolvePadding.ts",
        "line": 18
      },
      "values": [
        0,
        12,
        120,
        16,
        20,
        24,
        240,
        32,
        4,
        40,
        48,
        56,
        64,
        72,
        8,
        80,
        96
      ],
      "values_complete": true
    },
    {
      "name": "paddingBottom",
      "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
      "declared_type": "CdsSpace",
      "required": false,
      "description": "Bottom padding. Overrides `paddingY` and `padding`.",
      "source": {
        "path": "packages/design-system/src/components/layout/resolvePadding.ts",
        "line": 20
      },
      "values": [
        0,
        12,
        120,
        16,
        20,
        24,
        240,
        32,
        4,
        40,
        48,
        56,
        64,
        72,
        8,
        80,
        96
      ],
      "values_complete": true
    },
    {
      "name": "paddingLeft",
      "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
      "declared_type": "CdsSpace",
      "required": false,
      "description": "Left padding. Overrides `paddingX` and `padding`.",
      "source": {
        "path": "packages/design-system/src/components/layout/resolvePadding.ts",
        "line": 22
      },
      "values": [
        0,
        12,
        120,
        16,
        20,
        24,
        240,
        32,
        4,
        40,
        48,
        56,
        64,
        72,
        8,
        80,
        96
      ],
      "values_complete": true
    }
  ],
  "prop_shapes": {},
  "api": {
    "method": "typescript-type-checker",
    "typescript_version": "5.9.3",
    "public_export": "Grid",
    "public_path": "Grid",
    "import_path": "@cloakedinc/design-system",
    "root_kind": "component",
    "entrypoints": [
      {
        "name": "Grid",
        "signature": 1,
        "visibility": "public",
        "source": {
          "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
          "line": 60
        },
        "props_type": "GridProps",
        "props": [
          {
            "name": "columns",
            "type": "number",
            "declared_type": "number",
            "required": true,
            "description": "Number of equal-width columns. Produces `repeat(N, 1fr)`.",
            "source": {
              "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
              "line": 35
            }
          },
          {
            "name": "gap",
            "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
            "declared_type": "GridGap",
            "required": false,
            "description": "Uniform gap between columns and rows, in `--cds-space-*` steps.",
            "source": {
              "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
              "line": 37
            },
            "values": [
              0,
              12,
              120,
              16,
              20,
              24,
              240,
              32,
              4,
              40,
              48,
              56,
              64,
              72,
              8,
              80,
              96
            ],
            "values_complete": true
          },
          {
            "name": "gapX",
            "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
            "declared_type": "GridGap",
            "required": false,
            "description": "Horizontal gap between columns, overrides `gap`.",
            "source": {
              "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
              "line": 39
            },
            "values": [
              0,
              12,
              120,
              16,
              20,
              24,
              240,
              32,
              4,
              40,
              48,
              56,
              64,
              72,
              8,
              80,
              96
            ],
            "values_complete": true
          },
          {
            "name": "gapY",
            "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
            "declared_type": "GridGap",
            "required": false,
            "description": "Vertical gap between rows, overrides `gap`.",
            "source": {
              "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
              "line": 41
            },
            "values": [
              0,
              12,
              120,
              16,
              20,
              24,
              240,
              32,
              4,
              40,
              48,
              56,
              64,
              72,
              8,
              80,
              96
            ],
            "values_complete": true
          },
          {
            "name": "align",
            "type": "StackAlign | undefined",
            "declared_type": "GridAlign",
            "required": false,
            "description": "Vertical alignment of items within their cells (`align-items`).",
            "source": {
              "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
              "line": 43
            },
            "values": [
              "baseline",
              "center",
              "end",
              "start",
              "stretch"
            ],
            "values_complete": true
          },
          {
            "name": "justify",
            "type": "StackJustify | undefined",
            "declared_type": "GridJustify",
            "required": false,
            "description": "Horizontal distribution of the grid tracks (`justify-content`).",
            "source": {
              "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
              "line": 45
            },
            "values": [
              "around",
              "between",
              "center",
              "end",
              "evenly",
              "start"
            ],
            "values_complete": true
          },
          {
            "name": "as",
            "type": "React.ElementType<any, keyof React.JSX.IntrinsicElements> | undefined",
            "declared_type": "React.ElementType",
            "required": false,
            "description": "Rendered element. Defaults to `div`.",
            "source": {
              "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
              "line": 47
            },
            "default": "'div'",
            "default_kind": "source-expression"
          },
          {
            "name": "className",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
              "line": 48
            }
          },
          {
            "name": "style",
            "type": "React.CSSProperties | undefined",
            "declared_type": "React.CSSProperties",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
              "line": 49
            }
          },
          {
            "name": "children",
            "type": "React.ReactNode",
            "declared_type": "React.ReactNode",
            "required": false,
            "description": "",
            "source": {
              "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
              "line": 50
            }
          },
          {
            "name": "testId",
            "type": "string | undefined",
            "declared_type": "string",
            "required": false,
            "description": "Optional test selector, placed on the `as` element.",
            "source": {
              "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
              "line": 52
            }
          },
          {
            "name": "padding",
            "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
            "declared_type": "CdsSpace",
            "required": false,
            "description": "Padding on all four sides.",
            "source": {
              "path": "packages/design-system/src/components/layout/resolvePadding.ts",
              "line": 10
            },
            "values": [
              0,
              12,
              120,
              16,
              20,
              24,
              240,
              32,
              4,
              40,
              48,
              56,
              64,
              72,
              8,
              80,
              96
            ],
            "values_complete": true
          },
          {
            "name": "paddingX",
            "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
            "declared_type": "CdsSpace",
            "required": false,
            "description": "Horizontal padding (left + right). Overrides `padding` on the X axis.",
            "source": {
              "path": "packages/design-system/src/components/layout/resolvePadding.ts",
              "line": 12
            },
            "values": [
              0,
              12,
              120,
              16,
              20,
              24,
              240,
              32,
              4,
              40,
              48,
              56,
              64,
              72,
              8,
              80,
              96
            ],
            "values_complete": true
          },
          {
            "name": "paddingY",
            "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
            "declared_type": "CdsSpace",
            "required": false,
            "description": "Vertical padding (top + bottom). Overrides `padding` on the Y axis.",
            "source": {
              "path": "packages/design-system/src/components/layout/resolvePadding.ts",
              "line": 14
            },
            "values": [
              0,
              12,
              120,
              16,
              20,
              24,
              240,
              32,
              4,
              40,
              48,
              56,
              64,
              72,
              8,
              80,
              96
            ],
            "values_complete": true
          },
          {
            "name": "paddingTop",
            "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
            "declared_type": "CdsSpace",
            "required": false,
            "description": "Top padding. Overrides `paddingY` and `padding`.",
            "source": {
              "path": "packages/design-system/src/components/layout/resolvePadding.ts",
              "line": 16
            },
            "values": [
              0,
              12,
              120,
              16,
              20,
              24,
              240,
              32,
              4,
              40,
              48,
              56,
              64,
              72,
              8,
              80,
              96
            ],
            "values_complete": true
          },
          {
            "name": "paddingRight",
            "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
            "declared_type": "CdsSpace",
            "required": false,
            "description": "Right padding. Overrides `paddingX` and `padding`.",
            "source": {
              "path": "packages/design-system/src/components/layout/resolvePadding.ts",
              "line": 18
            },
            "values": [
              0,
              12,
              120,
              16,
              20,
              24,
              240,
              32,
              4,
              40,
              48,
              56,
              64,
              72,
              8,
              80,
              96
            ],
            "values_complete": true
          },
          {
            "name": "paddingBottom",
            "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
            "declared_type": "CdsSpace",
            "required": false,
            "description": "Bottom padding. Overrides `paddingY` and `padding`.",
            "source": {
              "path": "packages/design-system/src/components/layout/resolvePadding.ts",
              "line": 20
            },
            "values": [
              0,
              12,
              120,
              16,
              20,
              24,
              240,
              32,
              4,
              40,
              48,
              56,
              64,
              72,
              8,
              80,
              96
            ],
            "values_complete": true
          },
          {
            "name": "paddingLeft",
            "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined",
            "declared_type": "CdsSpace",
            "required": false,
            "description": "Left padding. Overrides `paddingX` and `padding`.",
            "source": {
              "path": "packages/design-system/src/components/layout/resolvePadding.ts",
              "line": 22
            },
            "values": [
              0,
              12,
              120,
              16,
              20,
              24,
              240,
              32,
              4,
              40,
              48,
              56,
              64,
              72,
              8,
              80,
              96
            ],
            "values_complete": true
          }
        ],
        "branches": [],
        "constraints": [],
        "extraction_status": "extracted"
      }
    ],
    "type_sources": [
      {
        "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
        "line": 8,
        "name": "GridGap",
        "code": "export type GridGap = StackGap;"
      },
      {
        "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
        "line": 9,
        "name": "GridAlign",
        "code": "export type GridAlign = StackAlign;"
      },
      {
        "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
        "line": 10,
        "name": "GridJustify",
        "code": "export type GridJustify = StackJustify;"
      },
      {
        "path": "packages/design-system/src/components/layout/Grid/Grid.tsx",
        "line": 33,
        "name": "GridProps",
        "code": "export interface GridProps extends PaddingProps {\n    /** Number of equal-width columns. Produces `repeat(N, 1fr)`. */\n    columns: number;\n    /** Uniform gap between columns and rows, in `--cds-space-*` steps. */\n    gap?: GridGap;\n    /** Horizontal gap between columns, overrides `gap`. */\n    gapX?: GridGap;\n    /** Vertical gap between rows, overrides `gap`. */\n    gapY?: GridGap;\n    /** Vertical alignment of items within their cells (`align-items`). */\n    align?: GridAlign;\n    /** Horizontal distribution of the grid tracks (`justify-content`). */\n    justify?: GridJustify;\n    /** Rendered element. Defaults to `div`. */\n    as?: React.ElementType;\n    className?: string;\n    style?: React.CSSProperties;\n    children?: React.ReactNode;\n    /** Optional test selector, placed on the `as` element. */\n    testId?: string;\n}"
      },
      {
        "path": "packages/design-system/src/components/layout/resolvePadding.ts",
        "line": 8,
        "name": "PaddingProps",
        "code": "export interface PaddingProps {\n    /** Padding on all four sides. */\n    padding?: CdsSpace;\n    /** Horizontal padding (left + right). Overrides `padding` on the X axis. */\n    paddingX?: CdsSpace;\n    /** Vertical padding (top + bottom). Overrides `padding` on the Y axis. */\n    paddingY?: CdsSpace;\n    /** Top padding. Overrides `paddingY` and `padding`. */\n    paddingTop?: CdsSpace;\n    /** Right padding. Overrides `paddingX` and `padding`. */\n    paddingRight?: CdsSpace;\n    /** Bottom padding. Overrides `paddingY` and `padding`. */\n    paddingBottom?: CdsSpace;\n    /** Left padding. Overrides `paddingX` and `padding`. */\n    paddingLeft?: CdsSpace;\n}"
      },
      {
        "path": "packages/design-system/src/components/layout/Stack.tsx",
        "line": 8,
        "name": "StackGap",
        "code": "export type StackGap = CdsSpace;"
      },
      {
        "path": "packages/design-system/src/components/layout/Stack.tsx",
        "line": 9,
        "name": "StackAlign",
        "code": "export type StackAlign = 'start' | 'center' | 'end' | 'stretch' | 'baseline';"
      },
      {
        "path": "packages/design-system/src/components/layout/Stack.tsx",
        "line": 10,
        "name": "StackJustify",
        "code": "export type StackJustify = 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';"
      },
      {
        "path": "packages/design-system/src/tokens/CdsSpace.ts",
        "line": 8,
        "name": "PUI_SPACES",
        "code": "PUI_SPACES = [0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 56, 64, 72, 80, 96, 120, 240] as const"
      },
      {
        "path": "packages/design-system/src/tokens/CdsSpace.ts",
        "line": 13,
        "name": "CdsSpace",
        "code": "export type CdsSpace = (typeof PUI_SPACES)[number];"
      }
    ],
    "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": "Grid",
      "status": "preview",
      "version": "1.0.0",
      "summary": "An equal-width column grid backed by CSS Grid, column-first with token-scale gaps and cell alignment."
    },
    "parts": [
      {
        "id": "root",
        "label": "Root",
        "description": "CSS Grid container. Structural: it arranges children into equal-width columns and paints no surface.",
        "required": true
      }
    ],
    "allowedDesignChoices": {
      "variants": {
        "grid": {
          "label": "Grid",
          "description": "The single equal-width column grid."
        }
      },
      "sizes": {},
      "alignments": {
        "start": {
          "label": "Start"
        },
        "center": {
          "label": "Center"
        },
        "end": {
          "label": "End"
        },
        "stretch": {
          "label": "Stretch"
        },
        "baseline": {
          "label": "Baseline"
        }
      },
      "justifications": {
        "start": {
          "label": "Start"
        },
        "center": {
          "label": "Center"
        },
        "end": {
          "label": "End"
        },
        "between": {
          "label": "Between"
        },
        "around": {
          "label": "Around"
        },
        "evenly": {
          "label": "Evenly"
        }
      }
    },
    "variants": [
      {
        "id": "grid",
        "label": "Grid",
        "description": "Equal-width column grid.",
        "platforms": [
          "ios",
          "android",
          "web"
        ]
      }
    ],
    "sizes": [],
    "measurements": [
      {
        "id": "track-gap",
        "label": "Track gap",
        "kind": "example-only",
        "token": "--cds-space-12",
        "value": 12,
        "unit": "px",
        "appliesTo": [
          "root"
        ],
        "notes": "Representative value: gap, gapX, and gapY are author-configurable and accept any step on the spacing scale. 12 is the value rendered and verified by the Playground story."
      }
    ],
    "layout": {
      "alignment": "align sets align-items across rows; justify sets justify-content, usually a no-op while columns are 1fr.",
      "flow": "Column-first: set the column count and rows fill implicitly as children flow in.",
      "notes": [
        "Use VStack/HStack for a single-axis flow and Carousel for one-per-view swiping."
      ]
    },
    "typographyAndColor": {
      "typography": [
        {
          "label": "Inherited",
          "description": "Grid sets no type; children own their text. Ramp noted for parity.",
          "token": "--cds-type-body-size"
        }
      ],
      "colors": [
        {
          "label": "Transparent",
          "description": "Grid paints no background; the surface behind shows through.",
          "token": "--cds-bg-page"
        }
      ]
    },
    "states": [
      {
        "id": "default",
        "label": "Default",
        "description": "Equal-width tracks with a uniform gap."
      },
      {
        "id": "separate-axis-gaps",
        "label": "Separate axis gaps",
        "description": "gapX and gapY set column and row spacing independently."
      },
      {
        "id": "aligned",
        "label": "Aligned",
        "description": "align centers uneven cells within their row."
      }
    ],
    "behavior": [
      {
        "label": "Column-first",
        "description": "Specify columns; rows are created implicitly as children fill up."
      },
      {
        "label": "Token gaps",
        "description": "gap, gapX, and gapY map to the spacing scale."
      }
    ],
    "accessibility": [
      {
        "label": "Presentational",
        "description": "Grid is a layout container and adds no roles; order follows DOM order."
      },
      {
        "label": "Reading order",
        "description": "Children read in source order regardless of visual columns."
      }
    ],
    "contentAdaptation": [
      {
        "label": "Tile density",
        "description": "Change the column count to trade tile size for density."
      },
      {
        "label": "Uneven cells",
        "description": "Use align to line up cells of differing height."
      }
    ],
    "motionHaptics": {
      "motion": [
        {
          "label": "None",
          "description": "Grid does not animate layout changes on its own."
        }
      ],
      "haptics": [
        {
          "label": "None",
          "description": "A layout container requests no haptics."
        }
      ]
    },
    "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-space-12",
      "light": "12px",
      "dark": "12px"
    },
    {
      "name": "--cds-type-body-size",
      "light": "1rem",
      "dark": "1rem"
    },
    {
      "name": "--cds-bg-page",
      "light": "#f3f1ed",
      "dark": "#141410"
    }
  ],
  "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

- [Playground](/storybook/iframe.html?id=cloaked-design-system-layout-grid--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/layout/Grid/Grid.stories.tsx

- [Three Columns](/storybook/iframe.html?id=cloaked-design-system-layout-grid--three-columns&viewMode=story) | export: ThreeColumns | source: packages/design-system/src/components/layout/Grid/Grid.stories.tsx

- [Separate Axis Gaps](/storybook/iframe.html?id=cloaked-design-system-layout-grid--separate-axis-gaps&viewMode=story) | export: SeparateAxisGaps | source: packages/design-system/src/components/layout/Grid/Grid.stories.tsx

- [With Padding](/storybook/iframe.html?id=cloaked-design-system-layout-grid--with-padding&viewMode=story) | export: WithPadding | source: packages/design-system/src/components/layout/Grid/Grid.stories.tsx

- [Center Aligned](/storybook/iframe.html?id=cloaked-design-system-layout-grid--center-aligned&viewMode=story) | export: CenterAligned | source: packages/design-system/src/components/layout/Grid/Grid.stories.tsx

- [Justify](/storybook/iframe.html?id=cloaked-design-system-layout-grid--justify&viewMode=story) | export: Justify | source: packages/design-system/src/components/layout/Grid/Grid.stories.tsx

- [Column Matrix](/storybook/iframe.html?id=cloaked-design-system-layout-grid--column-matrix&viewMode=story) | export: ColumnMatrix | source: packages/design-system/src/components/layout/Grid/Grid.stories.tsx

- [Gap Matrix](/storybook/iframe.html?id=cloaked-design-system-layout-grid--gap-matrix&viewMode=story) | export: GapMatrix | source: packages/design-system/src/components/layout/Grid/Grid.stories.tsx

- [Responsive Mobile Width](/storybook/iframe.html?id=cloaked-design-system-layout-grid--responsive-mobile-width&viewMode=story) | export: ResponsiveMobileWidth | source: packages/design-system/src/components/layout/Grid/Grid.stories.tsx

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