@roadlittledawn/docs-design-system-react 0.7.0 → 0.8.0

package/dist/components/Grid.d.ts

@@ -0,0 +1,90 @@
+import { ReactNode } from 'react';
+/** Breakpoint at which columns stack vertically */
+type StackAt = 'sm' | 'md' | 'lg' | 'never';
+/** Vertical alignment of column content */
+type AlignItems = 'start' | 'center' | 'end' | 'stretch';
+/** Configuration for a border or divider line */
+export interface BorderConfig {
+    /**
+     * Line thickness in pixels
+     * @default 1
+     */
+    thickness?: number;
+    /** Line color (defaults to the `--dds-grid-divider-color` token) */
+    color?: string;
+}
+export interface GridProps {
+    /**
+     * Number of equal columns, or an array of fractional widths
+     * (e.g. `[1, 2]` for a 1/3 + 2/3 split).
+     * @default 2
+     */
+    columns?: number | number[];
+    /**
+     * Space between columns. Use `'sm'`, `'md'`, or `'lg'` for design-token sizes,
+     * or any valid CSS length string (e.g. `'16px'`, `'1.5rem'`, `'2em'`).
+     * @default 'md'
+     */
+    gap?: string;
+    /**
+     * Viewport breakpoint at which columns collapse to a single vertical stack.
+     * @default 'md'
+     */
+    stackAt?: StackAt;
+    /**
+     * Vertical dividing line drawn between columns.
+     * Converts to a horizontal rule when the layout stacks.
+     */
+    columnDivider?: BorderConfig;
+    /** Horizontal rule rendered above the grid. */
+    topBorder?: BorderConfig;
+    /** Horizontal rule rendered below the grid. */
+    bottomBorder?: BorderConfig;
+    /**
+     * Vertical alignment of content within each column.
+     * @default 'stretch'
+     */
+    align?: AlignItems;
+    /** Background color applied to the grid container. */
+    backgroundColor?: string;
+    /** Additional CSS classes applied to the grid wrapper. */
+    className?: string;
+    children: ReactNode;
+}
+export interface ColumnProps {
+    /**
+     * How many grid columns this item should span.
+     * @default 1
+     */
+    span?: number;
+    /**
+     * Makes the column content sticky (`position: sticky; top: …`) while adjacent columns scroll.
+     * Useful for tutorial-style layouts with a persistent code panel.
+     * Automatically disabled when the grid stacks on mobile.
+     * @default false
+     */
+    sticky?: boolean;
+    /** Background color applied to the column. */
+    backgroundColor?: string;
+    /** Additional CSS classes applied to the column wrapper. */
+    className?: string;
+    children: ReactNode;
+}
+/**
+ * Multi-column layout container for documentation pages.
+ * Supports equal and fractional column splits, configurable responsive stacking,
+ * optional column dividers, top/bottom borders, and background colours.
+ *
+ * Pair with `<Column>` children to control individual column behaviour.
+ */
+export declare function Grid({ columns, gap, stackAt, columnDivider, topBorder, bottomBorder, align, backgroundColor, className, children, }: GridProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * An individual column within a `<Grid>`.
+ *
+ * Use the `span` prop to make a column occupy more than one grid track, and
+ * `sticky` to keep the column content pinned while adjacent content scrolls.
+ * The column element itself always stretches to the full row height so that
+ * column dividers cover the entire row regardless of which column is taller.
+ */
+export declare function Column({ span, sticky, backgroundColor, className, children, }: ColumnProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Grid.js

@@ -0,0 +1,95 @@
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+import { jsx as _jsx } from "react/jsx-runtime";
+var GAP_TOKEN_MAP = {
+    sm: 'var(--dds-grid-gap-sm)',
+    md: 'var(--dds-grid-gap-md)',
+    lg: 'var(--dds-grid-gap-lg)',
+};
+var ALIGN_MAP = {
+    start: 'start',
+    center: 'center',
+    end: 'end',
+    stretch: 'stretch',
+};
+function resolveGap(gap) {
+    if (gap in GAP_TOKEN_MAP)
+        return GAP_TOKEN_MAP[gap];
+    return gap; // custom CSS length string, e.g. '16px', '1.5rem', '2em'
+}
+/**
+ * Multi-column layout container for documentation pages.
+ * Supports equal and fractional column splits, configurable responsive stacking,
+ * optional column dividers, top/bottom borders, and background colours.
+ *
+ * Pair with `<Column>` children to control individual column behaviour.
+ */
+export function Grid(_a) {
+    var _b, _c, _d, _e, _f, _g;
+    var _h = _a.columns, columns = _h === void 0 ? 2 : _h, _j = _a.gap, gap = _j === void 0 ? 'md' : _j, _k = _a.stackAt, stackAt = _k === void 0 ? 'md' : _k, columnDivider = _a.columnDivider, topBorder = _a.topBorder, bottomBorder = _a.bottomBorder, _l = _a.align, align = _l === void 0 ? 'stretch' : _l, backgroundColor = _a.backgroundColor, _m = _a.className, className = _m === void 0 ? '' : _m, children = _a.children;
+    var columnTemplate = Array.isArray(columns)
+        ? columns.map(function (n) { return "".concat(n, "fr"); }).join(' ')
+        : "repeat(".concat(columns, ", 1fr)");
+    var style = __assign(__assign(__assign(__assign({ '--dds-grid-template-columns': columnTemplate, '--dds-grid-gap': resolveGap(gap), '--dds-grid-align': ALIGN_MAP[align] }, (backgroundColor ? { backgroundColor: backgroundColor } : {})), (topBorder
+        ? {
+            '--dds-grid-top-border-thickness': "".concat((_b = topBorder.thickness) !== null && _b !== void 0 ? _b : 1, "px"),
+            '--dds-grid-top-border-color': (_c = topBorder.color) !== null && _c !== void 0 ? _c : 'var(--dds-grid-divider-color)',
+        }
+        : {})), (bottomBorder
+        ? {
+            '--dds-grid-bottom-border-thickness': "".concat((_d = bottomBorder.thickness) !== null && _d !== void 0 ? _d : 1, "px"),
+            '--dds-grid-bottom-border-color': (_e = bottomBorder.color) !== null && _e !== void 0 ? _e : 'var(--dds-grid-divider-color)',
+        }
+        : {})), (columnDivider
+        ? {
+            '--dds-grid-column-divider-thickness': "".concat((_f = columnDivider.thickness) !== null && _f !== void 0 ? _f : 1, "px"),
+            '--dds-grid-column-divider-color': (_g = columnDivider.color) !== null && _g !== void 0 ? _g : 'var(--dds-grid-divider-color)',
+        }
+        : {}));
+    var classNames = [
+        'dds-grid',
+        "dds-grid-stack-".concat(stackAt),
+        topBorder ? 'dds-grid-has-top-border' : '',
+        bottomBorder ? 'dds-grid-has-bottom-border' : '',
+        columnDivider ? 'dds-grid-has-column-divider' : '',
+        className,
+    ]
+        .filter(Boolean)
+        .join(' ');
+    return (_jsx("div", { className: classNames, style: style, children: children }));
+}
+/**
+ * An individual column within a `<Grid>`.
+ *
+ * Use the `span` prop to make a column occupy more than one grid track, and
+ * `sticky` to keep the column content pinned while adjacent content scrolls.
+ * The column element itself always stretches to the full row height so that
+ * column dividers cover the entire row regardless of which column is taller.
+ */
+export function Column(_a) {
+    var span = _a.span, _b = _a.sticky, sticky = _b === void 0 ? false : _b, backgroundColor = _a.backgroundColor, _c = _a.className, className = _c === void 0 ? '' : _c, children = _a.children;
+    var style = {};
+    if (span && span > 1) {
+        style.gridColumn = "span ".concat(span);
+    }
+    if (backgroundColor) {
+        style.backgroundColor = backgroundColor;
+    }
+    var classNames = [
+        'dds-grid-column',
+        sticky ? 'dds-grid-column-sticky' : '',
+        className,
+    ]
+        .filter(Boolean)
+        .join(' ');
+    return (_jsx("div", { className: classNames, style: style, children: sticky ? (_jsx("div", { className: "dds-grid-column-sticky-inner", children: children })) : (children) }));
+}

package/dist/components/Grid.stories.d.ts

@@ -0,0 +1,69 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Grid } from './Grid';
+/**
+ * `Grid` and `Column` provide a flexible multi-column layout for documentation pages.
+ * Common patterns include side-by-side comparisons, image + annotation, and
+ * tutorial-style instruction / code pairings.
+ */
+declare const meta: Meta<typeof Grid>;
+export default meta;
+type Story = StoryObj<typeof Grid>;
+/**
+ * Fully interactive default story — all controls in the prop table affect this
+ * live preview. Adjust `columns`, `gap`, `stackAt`, `align`, `columnDivider`,
+ * `topBorder`, `bottomBorder`, and `backgroundColor` via the Controls panel.
+ */
+export declare const Default: Story;
+/**
+ * Two equal columns — the default layout. Columns stack vertically at the `md`
+ * breakpoint (768 px) by default.
+ */
+export declare const TwoEqualColumns: Story;
+/**
+ * Three equal columns, with a top and bottom border to create a contained
+ * "feature grid" panel. Useful for listing icons with short descriptions.
+ */
+export declare const ThreeColumnFeatureGrid: Story;
+/**
+ * Asymmetric 1/3 + 2/3 split — pass an array of fractional weights.
+ * A common pattern for a narrow label / sidebar alongside wide content.
+ */
+export declare const AsymmetricSplit: Story;
+/**
+ * Image + annotation layout. `align="center"` vertically centres the shorter
+ * column when image and text have different heights.
+ */
+export declare const ImageAndText: Story;
+/**
+ * Tutorial layout — prose instructions on the left, sticky code panel on the
+ * right. The code panel stays in view while the user scrolls through the steps.
+ * The column divider runs the full height of the row regardless of which column
+ * is taller. The `sticky` prop is automatically disabled when the grid stacks.
+ */
+export declare const TutorialWithStickyCode: Story;
+/**
+ * Column dividers — a vertical line between columns that converts to a
+ * horizontal rule at the stacking breakpoint.
+ */
+export declare const WithColumnDivider: Story;
+/**
+ * Background colors — apply a background to the entire grid and / or to
+ * individual columns using the `backgroundColor` prop.
+ */
+export declare const BackgroundColors: Story;
+/**
+ * Large gap between columns — useful when columns contain rich content
+ * that needs extra breathing room.
+ */
+export declare const LargeGap: Story;
+/**
+ * Custom gap — pass any CSS length string such as `'1.5rem'` or `'40px'`
+ * for fine-grained control beyond the named size tokens.
+ */
+export declare const CustomGap: Story;
+/**
+ * Span — a column set to `span={2}` occupies two grid tracks.
+ * Useful for full-width content (e.g. a summary row) inside an otherwise
+ * multi-column grid.
+ */
+export declare const ColumnSpan: Story;

package/dist/components/Grid.stories.js

@@ -0,0 +1,259 @@
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Grid } from './Grid';
+import { Column } from './Grid';
+import { CodeBlock } from './CodeBlock';
+/**
+ * `Grid` and `Column` provide a flexible multi-column layout for documentation pages.
+ * Common patterns include side-by-side comparisons, image + annotation, and
+ * tutorial-style instruction / code pairings.
+ */
+var meta = {
+    title: 'Components/Grid',
+    component: Grid,
+    tags: ['autodocs'],
+    argTypes: {
+        columns: {
+            control: { type: 'object' },
+            description: 'Number of equal columns, or an array of fractional weights for asymmetric splits (e.g. `[1, 2]` → 1/3 + 2/3). Enter a number or a JSON array in the control.',
+            table: { defaultValue: { summary: '2' } },
+        },
+        gap: {
+            control: { type: 'select' },
+            options: ['sm', 'md', 'lg', '0.5rem', '1rem', '1.5rem', '2rem', '3rem', '8px', '16px', '24px', '32px'],
+            description: "Space between columns. Use `'sm'`, `'md'`, or `'lg'` for design-token sizes, or any CSS length string (e.g. `'16px'`, `'1.5rem'`).",
+            table: { defaultValue: { summary: "'md'" } },
+        },
+        stackAt: {
+            control: { type: 'select' },
+            options: ['sm', 'md', 'lg', 'never'],
+            description: 'Breakpoint at which columns collapse to a single vertical stack.',
+            table: { defaultValue: { summary: "'md'" } },
+        },
+        align: {
+            control: { type: 'select' },
+            options: ['start', 'center', 'end', 'stretch'],
+            description: 'Vertical alignment of content within each column.',
+            table: { defaultValue: { summary: "'stretch'" } },
+        },
+        columnDivider: {
+            control: { type: 'object' },
+            description: 'Vertical line between columns (`{ thickness?: number; color?: string }`). Converts to a horizontal rule when stacked.',
+        },
+        topBorder: {
+            control: { type: 'object' },
+            description: 'Horizontal rule above the grid (`{ thickness?: number; color?: string }`).',
+        },
+        bottomBorder: {
+            control: { type: 'object' },
+            description: 'Horizontal rule below the grid (`{ thickness?: number; color?: string }`).',
+        },
+        backgroundColor: {
+            control: 'color',
+            description: 'Background color for the entire grid container.',
+        },
+        className: {
+            control: 'text',
+            description: 'Additional CSS classes applied to the grid wrapper.',
+            table: { defaultValue: { summary: '""' } },
+        },
+        children: {
+            control: false,
+            description: 'Grid content — typically `Column` components.',
+        },
+    },
+    parameters: {
+        docs: {
+            description: {
+                component: "\nLayout primitive for multi-column documentation content.\n\n## When to Use\n\n- **Image + annotation** \u2014 screenshot or diagram on one side, feature callouts on the other\n- **Tutorial / live demo** \u2014 prose instructions on one side, sticky code panel on the other\n- **Side-by-side comparison** \u2014 before/after, two approaches, or option A vs option B\n- **Feature grid** \u2014 icon + short description repeated across columns\n\n## When Not to Use\n\n- For card-style repeating items of the same type \u2014 use `CardGrid` instead\n- For a single column of content \u2014 use standard block-level markup\n\n## Accessibility\n\n- Rendered as a semantic `<div>`; no implicit ARIA role (not a data table)\n- Source order should match reading order; avoid visual reordering via CSS `order`\n- Column dividers are decorative and carry no meaning for assistive technology\n        ",
+            },
+        },
+    },
+};
+export default meta;
+/* -------------------------------------------------------------------------- */
+/* Helpers                                                                     */
+/* -------------------------------------------------------------------------- */
+var textColor = { color: 'var(--dds-tabs-panel-text)' };
+var subtle = { color: 'var(--dds-tabs-panel-text)', fontFamily: 'sans-serif', margin: 0 };
+function Placeholder(_a) {
+    var label = _a.label, _b = _a.height, height = _b === void 0 ? 120 : _b, _c = _a.bg, bg = _c === void 0 ? 'rgba(99,102,241,0.1)' : _c;
+    return (_jsx("div", { style: __assign(__assign({ display: 'flex', alignItems: 'center', justifyContent: 'center', height: height, background: bg, borderRadius: 6 }, textColor), { fontFamily: 'sans-serif', fontWeight: 600, fontSize: '0.875rem' }), children: label }));
+}
+/* -------------------------------------------------------------------------- */
+/* Stories                                                                     */
+/* -------------------------------------------------------------------------- */
+/**
+ * Fully interactive default story — all controls in the prop table affect this
+ * live preview. Adjust `columns`, `gap`, `stackAt`, `align`, `columnDivider`,
+ * `topBorder`, `bottomBorder`, and `backgroundColor` via the Controls panel.
+ */
+export var Default = {
+    args: {
+        columns: 2,
+        gap: 'md',
+        stackAt: 'md',
+        align: 'stretch',
+    },
+    render: function (args) { return (_jsxs(Grid, __assign({}, args, { children: [_jsx(Column, { children: _jsx(Placeholder, { label: "Column 1" }) }), _jsx(Column, { children: _jsx(Placeholder, { label: "Column 2" }) })] }))); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid columns={2} gap=\"md\">\n  <Column>Column 1 content</Column>\n  <Column>Column 2 content</Column>\n</Grid>",
+            },
+        },
+    },
+};
+/**
+ * Two equal columns — the default layout. Columns stack vertically at the `md`
+ * breakpoint (768 px) by default.
+ */
+export var TwoEqualColumns = {
+    render: function () { return (_jsxs(Grid, { columns: 2, children: [_jsx(Column, { children: _jsx(Placeholder, { label: "Column 1" }) }), _jsx(Column, { children: _jsx(Placeholder, { label: "Column 2" }) })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid columns={2}>\n  <Column>Column 1 content</Column>\n  <Column>Column 2 content</Column>\n</Grid>",
+            },
+        },
+    },
+};
+/**
+ * Three equal columns, with a top and bottom border to create a contained
+ * "feature grid" panel. Useful for listing icons with short descriptions.
+ */
+export var ThreeColumnFeatureGrid = {
+    render: function () { return (_jsxs(Grid, { columns: 3, gap: "md", topBorder: { color: 'var(--dds-grid-divider-color)' }, bottomBorder: { color: 'var(--dds-grid-divider-color)' }, children: [_jsx(Column, { children: _jsxs("p", { style: subtle, children: [_jsx("strong", { children: "Feature A" }), _jsx("br", {}), "Short description of the feature."] }) }), _jsx(Column, { children: _jsxs("p", { style: subtle, children: [_jsx("strong", { children: "Feature B" }), _jsx("br", {}), "Short description of the feature."] }) }), _jsx(Column, { children: _jsxs("p", { style: subtle, children: [_jsx("strong", { children: "Feature C" }), _jsx("br", {}), "Short description of the feature."] }) })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid\n  columns={3}\n  gap=\"md\"\n  topBorder={{ color: '#ccc' }}\n  bottomBorder={{ color: '#ccc' }}\n>\n  <Column><strong>Feature A</strong> \u2014 Short description.</Column>\n  <Column><strong>Feature B</strong> \u2014 Short description.</Column>\n  <Column><strong>Feature C</strong> \u2014 Short description.</Column>\n</Grid>",
+            },
+        },
+    },
+};
+/**
+ * Asymmetric 1/3 + 2/3 split — pass an array of fractional weights.
+ * A common pattern for a narrow label / sidebar alongside wide content.
+ */
+export var AsymmetricSplit = {
+    render: function () { return (_jsxs(Grid, { columns: [1, 2], children: [_jsx(Column, { children: _jsx(Placeholder, { label: "1 / 3", height: 160, bg: "rgba(16,185,129,0.1)" }) }), _jsx(Column, { children: _jsx(Placeholder, { label: "2 / 3", height: 160, bg: "rgba(99,102,241,0.1)" }) })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid columns={[1, 2]}>\n  <Column>Narrow (1/3)</Column>\n  <Column>Wide (2/3)</Column>\n</Grid>",
+            },
+        },
+    },
+};
+/**
+ * Image + annotation layout. `align="center"` vertically centres the shorter
+ * column when image and text have different heights.
+ */
+export var ImageAndText = {
+    render: function () { return (_jsxs(Grid, { columns: [1, 2], align: "center", columnDivider: { color: 'var(--dds-grid-divider-color)' }, children: [_jsx(Column, { children: _jsx(Placeholder, { label: "Diagram / Screenshot", height: 200, bg: "rgba(234,179,8,0.1)" }) }), _jsxs(Column, { children: [_jsx("p", { style: __assign(__assign({}, subtle), { marginBottom: '0.5rem' }), children: _jsx("strong", { children: "What you're looking at" }) }), _jsxs("p", { style: subtle, children: ["This panel describes the key elements of the diagram on the left. Use ", _jsx("code", { children: "align=\"center\"" }), " so short text stays vertically centred next to a taller image."] })] })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid columns={[1, 2]} align=\"center\" columnDivider={{ color: '#ddd' }}>\n  <Column>\n    <img src=\"/diagram.png\" alt=\"Architecture diagram\" />\n  </Column>\n  <Column>\n    <h3>What you're looking at</h3>\n    <p>Description of the diagram elements...</p>\n  </Column>\n</Grid>",
+            },
+        },
+    },
+};
+/**
+ * Tutorial layout — prose instructions on the left, sticky code panel on the
+ * right. The code panel stays in view while the user scrolls through the steps.
+ * The column divider runs the full height of the row regardless of which column
+ * is taller. The `sticky` prop is automatically disabled when the grid stacks.
+ */
+export var TutorialWithStickyCode = {
+    render: function () { return (_jsxs(Grid, { columns: 2, stackAt: "lg", gap: "lg", columnDivider: { thickness: 2, color: 'var(--dds-grid-divider-color)' }, children: [_jsxs(Column, { children: [_jsx("p", { style: __assign(__assign({}, subtle), { marginBottom: '1rem' }), children: _jsx("strong", { children: "Step 1 \u2014 Install dependencies" }) }), _jsx("p", { style: __assign(__assign({}, subtle), { marginBottom: '1rem' }), children: "Run the installer and follow the prompts. This sets up the project scaffold and pulls in all required packages." }), _jsx("p", { style: __assign(__assign({}, subtle), { marginBottom: '1rem' }), children: _jsx("strong", { children: "Step 2 \u2014 Configure your project" }) }), _jsxs("p", { style: __assign(__assign({}, subtle), { marginBottom: '1rem' }), children: ["Open ", _jsx("code", { children: "config.ts" }), " and update the values for your environment. Refer to the code panel on the right for a complete example."] }), _jsx("p", { style: __assign(__assign({}, subtle), { marginBottom: '1rem' }), children: _jsx("strong", { children: "Step 3 \u2014 Start the dev server" }) }), _jsx("p", { style: subtle, children: "Run the dev command. The server watches for file changes and hot-reloads automatically." })] }), _jsx(Column, { sticky: true, children: _jsx(CodeBlock, { language: "bash", code: "npm install\n\nnpm run dev" }) })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid columns={2} stackAt=\"lg\" gap=\"lg\" columnDivider={{ thickness: 2 }}>\n  <Column>\n    {/* Step-by-step instructions */}\n    <p><strong>Step 1 \u2014 Install dependencies</strong></p>\n    <p>Run the installer and follow the prompts.</p>\n    {/* \u2026 more steps \u2026 */}\n  </Column>\n  <Column sticky>\n    <CodeBlock language=\"bash\" code=\"npm install\\n\\nnpm run dev\" />\n  </Column>\n</Grid>",
+            },
+        },
+    },
+};
+/**
+ * Column dividers — a vertical line between columns that converts to a
+ * horizontal rule at the stacking breakpoint.
+ */
+export var WithColumnDivider = {
+    render: function () { return (_jsxs(Grid, { columns: 3, columnDivider: { thickness: 1, color: 'var(--dds-grid-divider-color)' }, children: [_jsxs(Column, { children: [_jsx("p", { style: subtle, children: _jsx("strong", { children: "Option A" }) }), _jsx("p", { style: subtle, children: "Description of the first approach." })] }), _jsxs(Column, { children: [_jsx("p", { style: subtle, children: _jsx("strong", { children: "Option B" }) }), _jsx("p", { style: subtle, children: "Description of the second approach." })] }), _jsxs(Column, { children: [_jsx("p", { style: subtle, children: _jsx("strong", { children: "Option C" }) }), _jsx("p", { style: subtle, children: "Description of the third approach." })] })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid columns={3} columnDivider={{ thickness: 1, color: '#e0e0e0' }}>\n  <Column>\n    <strong>Option A</strong>\n    <p>Description of the first approach.</p>\n  </Column>\n  <Column>\n    <strong>Option B</strong>\n    <p>Description of the second approach.</p>\n  </Column>\n  <Column>\n    <strong>Option C</strong>\n    <p>Description of the third approach.</p>\n  </Column>\n</Grid>",
+            },
+        },
+    },
+};
+/**
+ * Background colors — apply a background to the entire grid and / or to
+ * individual columns using the `backgroundColor` prop.
+ */
+export var BackgroundColors = {
+    render: function () { return (_jsxs(Grid, { columns: 2, gap: "lg", backgroundColor: "rgba(99,102,241,0.04)", children: [_jsxs(Column, { backgroundColor: "rgba(16,185,129,0.08)", children: [_jsx("p", { style: subtle, children: _jsx("strong", { children: "Column with background" }) }), _jsx("p", { style: subtle, children: "Each column can have its own background color." })] }), _jsxs(Column, { backgroundColor: "rgba(234,179,8,0.08)", children: [_jsx("p", { style: subtle, children: _jsx("strong", { children: "Another column background" }) }), _jsxs("p", { style: subtle, children: ["The grid container also has a light background applied via", ' ', _jsx("code", { children: "backgroundColor" }), " on the ", _jsx("code", { children: "Grid" }), "."] })] })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid columns={2} gap=\"lg\" backgroundColor=\"rgba(99,102,241,0.04)\">\n  <Column backgroundColor=\"rgba(16,185,129,0.08)\">\n    <strong>Column with background</strong>\n    <p>Each column can have its own background color.</p>\n  </Column>\n  <Column backgroundColor=\"rgba(234,179,8,0.08)\">\n    <strong>Another column background</strong>\n    <p>Set on both the Grid container and individual Columns.</p>\n  </Column>\n</Grid>",
+            },
+        },
+    },
+};
+/**
+ * Large gap between columns — useful when columns contain rich content
+ * that needs extra breathing room.
+ */
+export var LargeGap = {
+    render: function () { return (_jsxs(Grid, { columns: 2, gap: "lg", children: [_jsx(Column, { children: _jsx(Placeholder, { label: "Column 1", height: 140 }) }), _jsx(Column, { children: _jsx(Placeholder, { label: "Column 2", height: 140 }) })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid columns={2} gap=\"lg\">\n  <Column>Column 1 content</Column>\n  <Column>Column 2 content</Column>\n</Grid>",
+            },
+        },
+    },
+};
+/**
+ * Custom gap — pass any CSS length string such as `'1.5rem'` or `'40px'`
+ * for fine-grained control beyond the named size tokens.
+ */
+export var CustomGap = {
+    render: function () { return (_jsxs(Grid, { columns: 2, gap: "3rem", children: [_jsx(Column, { children: _jsx(Placeholder, { label: "Column 1", height: 140 }) }), _jsx(Column, { children: _jsx(Placeholder, { label: "Column 2", height: 140 }) })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid columns={2} gap=\"3rem\">\n  <Column>Column 1 content</Column>\n  <Column>Column 2 content</Column>\n</Grid>",
+            },
+        },
+    },
+};
+/**
+ * Span — a column set to `span={2}` occupies two grid tracks.
+ * Useful for full-width content (e.g. a summary row) inside an otherwise
+ * multi-column grid.
+ */
+export var ColumnSpan = {
+    render: function () { return (_jsxs(Grid, { columns: 3, gap: "md", children: [_jsx(Column, { children: _jsx(Placeholder, { label: "Col 1" }) }), _jsx(Column, { children: _jsx(Placeholder, { label: "Col 2" }) }), _jsx(Column, { children: _jsx(Placeholder, { label: "Col 3" }) }), _jsx(Column, { span: 3, children: _jsx(Placeholder, { label: "Spans all 3 columns", height: 60, bg: "rgba(239,68,68,0.1)" }) })] })); },
+    parameters: {
+        docs: {
+            source: {
+                code: "<Grid columns={3} gap=\"md\">\n  <Column>Col 1</Column>\n  <Column>Col 2</Column>\n  <Column>Col 3</Column>\n  <Column span={3}>Spans all 3 columns</Column>\n</Grid>",
+            },
+        },
+    },
+};

package/dist/index.d.ts

@@ -11,4 +11,5 @@ export * from './components/Typography';
 export * from './components/Heading';
 export * from './components/Link';
 export * from './components/List';
+export * from './components/Grid';
 export * from './hooks/useKeyPress';

package/dist/index.js

@@ -12,5 +12,6 @@ export * from './components/Typography';
 export * from './components/Heading';
 export * from './components/Link';
 export * from './components/List';
+export * from './components/Grid';
 // Export hooks
 export * from './hooks/useKeyPress';

package/dist/styles.css

@@ -258,6 +258,13 @@
   --dds-list-badge-shadow: inset 0 0 0 1px #bfc2c7;
   --dds-list-connector-line: #eceef2; /* gray-200 */
   --dds-list-text: #374151; /* gray-700 */
+
+  /* Grid */
+  --dds-grid-gap-sm: 1rem; /* gap-4 */
+  --dds-grid-gap-md: 1.5rem; /* gap-6 */
+  --dds-grid-gap-lg: 2.5rem; /* gap-10 */
+  --dds-grid-divider-color: #e5e7eb; /* gray-200 */
+  --dds-grid-sticky-top: 1rem;
 }
 /* ==========================================================================
    Dark Mode Tokens
@@ -419,6 +426,9 @@
   --dds-list-badge-shadow: inset 0 0 0 1px #353a42;
   --dds-list-connector-line: #353a42; /* gray-600 */
   --dds-list-text: #e5e7eb; /* gray-200 */
+
+  /* Grid */
+  --dds-grid-divider-color: #4b5563; /* gray-600 */
 }
 /* Auto dark mode — follows OS preference, opt-out with .dds-light */
 @media (prefers-color-scheme: dark) {
@@ -575,6 +585,9 @@
     --dds-list-badge-shadow: inset 0 0 0 1px #353a42;
     --dds-list-connector-line: #353a42; /* gray-600 */
     --dds-list-text: #e5e7eb; /* gray-200 */
+
+    /* Grid */
+    --dds-grid-divider-color: #4b5563; /* gray-600 */
   }
 }
 /* Explicit dark mode via data attribute (overrides OS preference) */
@@ -1832,4 +1845,107 @@ a.no-text-decoration {
     }
   }
 }
+/* =============================================================================
+   Grid — multi-column layout component
+   ============================================================================= */
+/* Base grid container */
+.dds-grid {
+  display: grid;
+  grid-template-columns: var(--dds-grid-template-columns, repeat(2, 1fr));
+  gap: var(--dds-grid-gap, var(--dds-grid-gap-md));
+  align-items: var(--dds-grid-align, stretch);
+}
+/* Optional top border */
+.dds-grid-has-top-border {
+  border-top: var(--dds-grid-top-border-thickness, 1px) solid
+    var(--dds-grid-top-border-color, var(--dds-grid-divider-color));
+  padding-top: var(--dds-grid-gap, var(--dds-grid-gap-md));
+}
+/* Optional bottom border */
+.dds-grid-has-bottom-border {
+  border-bottom: var(--dds-grid-bottom-border-thickness, 1px) solid
+    var(--dds-grid-bottom-border-color, var(--dds-grid-divider-color));
+  padding-bottom: var(--dds-grid-gap, var(--dds-grid-gap-md));
+}
+/* Column divider — vertical line between columns */
+.dds-grid-has-column-divider .dds-grid-column + .dds-grid-column {
+  border-left: var(--dds-grid-column-divider-thickness, 1px) solid
+    var(--dds-grid-column-divider-color, var(--dds-grid-divider-color));
+  padding-left: var(--dds-grid-gap, var(--dds-grid-gap-md));
+}
+/* Individual column */
+.dds-grid-column {
+  /* Prevent grid cells from overflowing (e.g. wide code blocks) */
+  min-width: 0;
+}
+/* Sticky column — column div stretches to full row height so that border-left
+   covers the entire row. The CONTENT inside is what scrolls sticky, via the
+   inner wrapper. */
+.dds-grid-column-sticky {
+  /* No align-self override — stretches naturally to row height */
+}
+/* Inner wrapper that provides the actual sticky scroll behaviour */
+.dds-grid-column-sticky-inner {
+  position: sticky;
+  top: var(--dds-grid-sticky-top, 1rem);
+}
+/* =============================================================================
+   Responsive stacking — columns collapse to a single vertical track
+   ============================================================================= */
+/* Stack at sm breakpoint (≤ 640 px) */
+@media (max-width: 640px) {
+  .dds-grid-stack-sm {
+    grid-template-columns: 1fr;
+  }
+
+  /* Column divider becomes a horizontal rule when stacked */
+  .dds-grid-stack-sm.dds-grid-has-column-divider .dds-grid-column + .dds-grid-column {
+    border-left: none;
+    padding-left: 0;
+    border-top: var(--dds-grid-column-divider-thickness, 1px) solid
+      var(--dds-grid-column-divider-color, var(--dds-grid-divider-color));
+    padding-top: var(--dds-grid-gap, var(--dds-grid-gap-md));
+  }
+
+  /* Sticky inner wrapper no-ops when stacked */
+  .dds-grid-stack-sm .dds-grid-column-sticky-inner {
+    position: static;
+  }
+}
+/* Stack at md breakpoint (≤ 768 px) */
+@media (max-width: 768px) {
+  .dds-grid-stack-md {
+    grid-template-columns: 1fr;
+  }
+
+  .dds-grid-stack-md.dds-grid-has-column-divider .dds-grid-column + .dds-grid-column {
+    border-left: none;
+    padding-left: 0;
+    border-top: var(--dds-grid-column-divider-thickness, 1px) solid
+      var(--dds-grid-column-divider-color, var(--dds-grid-divider-color));
+    padding-top: var(--dds-grid-gap, var(--dds-grid-gap-md));
+  }
+
+  .dds-grid-stack-md .dds-grid-column-sticky-inner {
+    position: static;
+  }
+}
+/* Stack at lg breakpoint (≤ 1024 px) */
+@media (max-width: 1024px) {
+  .dds-grid-stack-lg {
+    grid-template-columns: 1fr;
+  }
+
+  .dds-grid-stack-lg.dds-grid-has-column-divider .dds-grid-column + .dds-grid-column {
+    border-left: none;
+    padding-left: 0;
+    border-top: var(--dds-grid-column-divider-thickness, 1px) solid
+      var(--dds-grid-column-divider-color, var(--dds-grid-divider-color));
+    padding-top: var(--dds-grid-gap, var(--dds-grid-gap-md));
+  }
+
+  .dds-grid-stack-lg .dds-grid-column-sticky-inner {
+    position: static;
+  }
+}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roadlittledawn/docs-design-system-react",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "license": "MIT",
   "description": "React components for documentation design system",
   "repository": {