@fairgarden/design 0.1.0-alpha.0

package/components/Form/Form.d.ts

@@ -0,0 +1,69 @@
+import * as React from 'react';
+import { Form as BaseForm } from '@base-ui/react/form';
+import { type VariantProps } from 'class-variance-authority';
+export declare const form: (props?: ({
+    primary?: "ruby" | "brown" | "crimson" | "gold" | "gray" | "indigo" | "olive" | "pink" | "plum" | "purple" | "red" | "tomato" | "violet" | "bronze" | "iris" | "mauve" | "sage" | "sand" | "slate" | null | undefined;
+    secondary?: "ruby" | "blue" | "brown" | "crimson" | "cyan" | "gold" | "gray" | "green" | "indigo" | "lime" | "olive" | "orange" | "pink" | "plum" | "purple" | "red" | "teal" | "tomato" | "violet" | "yellow" | "amber" | "bronze" | "grass" | "iris" | "jade" | "mauve" | "mint" | "sage" | "sand" | "sky" | "slate" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+type FormVariants = VariantProps<typeof form>;
+/** Props for Form: Base UI Form props plus `busy` and the color axes. */
+export type FormProps<Values extends Record<string, unknown> = Record<string, unknown>> = Omit<BaseForm.Props<Values>, 'className'> & {
+    /** Extra class names, added after the module's own. */
+    className?: string;
+    /**
+     * While the submission is pending: the form is `inert` and
+     * `aria-busy`. Give the solid submit its "-ing…" label ("Sending…").
+     */
+    busy?: boolean;
+    /** Primary Radix scale: structure and inherited control roles. Never defaulted [D133]. */
+    primary?: FormVariants['primary'];
+    /** Secondary Radix scale: accepted, unused. */
+    secondary?: FormVariants['secondary'];
+};
+/**
+ * A Base UI Form, one column at `--size-sm`. Base UI validates on submit,
+ * then re-validates failed fields as they change (§10.2 asks for blur;
+ * pass `validationMode="onBlur"` to a Field that should wait for it).
+ * Order: an optional `FormSummary`, fields and fieldsets, then
+ * `FormActions`.
+ */
+export declare function Form<Values extends Record<string, unknown> = Record<string, unknown>>(props: FormProps<Values>): React.JSX.Element;
+/** One failing field in the summary: the field's `id` and the message that links to it. */
+export interface FormSummaryError {
+    /** The `id` of the field's control; the link moves focus there. */
+    id: string;
+    /** The field's error message, as at the field. */
+    message: React.ReactNode;
+}
+/** Props for FormSummary. */
+export interface FormSummaryProps {
+    /** The heading, in `type-subhead`: "Fix 2 fields to continue". */
+    title: React.ReactNode;
+    /** The failing fields, each a link that moves focus to its control. */
+    errors: readonly FormSummaryError[];
+    /** Extra class names, added after the module's own. */
+    className?: string;
+}
+/**
+ * The error summary at the top of the form (§10.2): the danger Alert with
+ * a heading and a link to each failing field. Render it only while there
+ * are errors; it takes focus when it appears.
+ */
+export declare function FormSummary(props: FormSummaryProps): React.JSX.Element;
+/** Props for FormRow: `div` props. */
+export type FormRowProps = React.ComponentPropsWithRef<'div'>;
+/**
+ * A short pair, such as city and postcode: a 2:1 row that stacks when both
+ * fields do not fit, and always shares the row from 480 px of form width.
+ */
+export declare function FormRow(props: FormRowProps): React.JSX.Element;
+/** Props for FormActions: `div` props. */
+export type FormActionsProps = React.ComponentPropsWithRef<'div'>;
+/**
+ * The action row, `--size-px-5` below the last field. Author the solid
+ * submit (`size="lg"`) last: it shows first and full width at base, and
+ * last (rightmost) from `--md-n-above` [D106].
+ */
+export declare function FormActions(props: FormActionsProps): React.JSX.Element;
+export {};
+//# sourceMappingURL=Form.d.ts.map

package/components/Form/Form.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Form.d.ts","sourceRoot":"","sources":["../../src/components/Form/Form.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,EAAO,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAA;AA4BjE,eAAO,MAAM,IAAI;;;8EAMf,CAAA;AAEF,KAAK,YAAY,GAAG,YAAY,CAAC,OAAO,IAAI,CAAC,CAAA;AAE7C,yEAAyE;AACzE,MAAM,MAAM,SAAS,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,IAAI,CAC5F,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,EACtB,WAAW,CACZ,GAAG;IACF,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,0FAA0F;IAC1F,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAA;IACjC,+CAA+C;IAC/C,SAAS,CAAC,EAAE,YAAY,CAAC,WAAW,CAAC,CAAA;CACtC,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnF,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,qBAczB;AAED,2FAA2F;AAC3F,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,EAAE,EAAE,MAAM,CAAA;IACV,kDAAkD;IAClD,OAAO,EAAE,KAAK,CAAC,SAAS,CAAA;CACzB;AAED,6BAA6B;AAC7B,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,KAAK,EAAE,KAAK,CAAC,SAAS,CAAA;IACtB,uEAAuE;IACvE,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAA;IACnC,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,qBAmClD;AAED,sCAAsC;AACtC,MAAM,MAAM,YAAY,GAAG,KAAK,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAA;AAE7D;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,qBAG1C;AAED,0CAA0C;AAC1C,MAAM,MAAM,gBAAgB,GAAG,KAAK,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAA;AAEjE;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,qBAGlD"}

package/components/Form/Form.js

@@ -0,0 +1,90 @@
+'use client';
+import * as React from 'react';
+import { Form as BaseForm } from '@base-ui/react/form';
+import { cva } from 'class-variance-authority';
+import { Alert } from '../Alert';
+import { Link } from '../Link';
+import { cx } from '../../utils/className';
+import { primaryScaleVariants, secondaryScaleVariants } from '../../utils/scales';
+import { useScopeAttributes } from '../../utils/scope';
+import styles from './form.module.css';
+/*
+ * Form (§10.2): anything submitted. Instant-apply settings are switches.
+ *
+ * Implementation (CSS Modules + CVA)
+ * - Module: form.module.css; CVA function `form`.
+ * - Axes: `primary`, `secondary` → scales module classes (structure takes
+ *   `primary` only; `secondary` is accepted unused).
+ * - Compound variants: none. Defaults: color axes none.
+ * - Color fallback: inherits the scope. The summary is an Alert whose
+ *   secondary is the danger scale [D129].
+ * - States: `aria-busy` (set from `busy`) → the form is inert, the submit
+ *   reads "-ing…" at its rest width [D84].
+ * - Parts: base, summary (an Alert, status danger; `summaryTitle`,
+ *   `summaryList`), actions; `row` holds a short pair.
+ * - Scope: none.
+ * - Container: the root is the inline-size container `form`; short pairs
+ *   share a row from 480 px, fieldset padding and the butted submit's
+ *   stack guard read it below 360 px (§5.10.2) [D163].
+ */
+export const form = cva(styles.base, {
+    variants: {
+        // Color axes: never defaulted [D133].
+        primary: primaryScaleVariants,
+        secondary: secondaryScaleVariants,
+    },
+});
+/**
+ * A Base UI Form, one column at `--size-sm`. Base UI validates on submit,
+ * then re-validates failed fields as they change (§10.2 asks for blur;
+ * pass `validationMode="onBlur"` to a Field that should wait for it).
+ * Order: an optional `FormSummary`, fields and fieldsets, then
+ * `FormActions`.
+ */
+export function Form(props) {
+    const { busy, primary, secondary, className, ...rest } = props;
+    const scope = useScopeAttributes();
+    return (React.createElement(BaseForm, { ...rest, ...scope, "aria-busy": busy || undefined, inert: busy || undefined, className: form({ primary, secondary, className }) }));
+}
+/**
+ * The error summary at the top of the form (§10.2): the danger Alert with
+ * a heading and a link to each failing field. Render it only while there
+ * are errors; it takes focus when it appears.
+ */
+export function FormSummary(props) {
+    const { title, errors, className } = props;
+    const ref = React.useRef(null);
+    React.useEffect(() => {
+        ref.current?.focus();
+    }, []);
+    const focusField = (event, id) => {
+        const target = document.getElementById(id);
+        if (!target)
+            return;
+        event.preventDefault();
+        target.focus();
+        target.scrollIntoView({ block: 'center' });
+    };
+    return (React.createElement(Alert, { ref: ref, status: "danger", tabIndex: -1, className: cx(styles.summary, className) },
+        React.createElement("h2", { className: styles.summaryTitle }, title),
+        React.createElement("ul", { className: styles.summaryList }, errors.map((error) => (React.createElement("li", { key: error.id },
+            React.createElement(Link, { href: `#${error.id}`, onClick: (event) => focusField(event, error.id) }, error.message)))))));
+}
+/**
+ * A short pair, such as city and postcode: a 2:1 row that stacks when both
+ * fields do not fit, and always shares the row from 480 px of form width.
+ */
+export function FormRow(props) {
+    const { className, ...rest } = props;
+    return React.createElement("div", { ...rest, className: cx(styles.row, className) });
+}
+/**
+ * The action row, `--size-px-5` below the last field. Author the solid
+ * submit (`size="lg"`) last: it shows first and full width at base, and
+ * last (rightmost) from `--md-n-above` [D106].
+ */
+export function FormActions(props) {
+    const { className, ...rest } = props;
+    return React.createElement("div", { ...rest, className: cx(styles.actions, className) });
+}
+//# sourceMappingURL=Form.js.map

package/components/Form/Form.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Form.js","sourceRoot":"","sources":["../../src/components/Form/Form.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAA;AAEZ,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,EAAE,GAAG,EAAqB,MAAM,0BAA0B,CAAA;AAEjE,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAA;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AAC9B,OAAO,EAAE,EAAE,EAAE,MAAM,uBAAuB,CAAA;AAC1C,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,MAAM,MAAM,mBAAmB,CAAA;AAEtC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE;IACnC,QAAQ,EAAE;QACR,sCAAsC;QACtC,OAAO,EAAE,oBAAoB;QAC7B,SAAS,EAAE,sBAAsB;KAClC;CACF,CAAC,CAAA;AAsBF;;;;;;GAMG;AACH,MAAM,UAAU,IAAI,CAClB,KAAwB;IAExB,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAA;IAC9D,MAAM,KAAK,GAAG,kBAAkB,EAAE,CAAA;IAElC,OAAO,CACL,oBAAC,QAAQ,OACH,IAAI,KACJ,KAAK,eACE,IAAI,IAAI,SAAS,EAC5B,KAAK,EAAE,IAAI,IAAI,SAAS,EACxB,SAAS,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,GAClD,CACH,CAAA;AACH,CAAC;AAoBD;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAuB;IACjD,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,KAAK,CAAA;IAC1C,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAwB,IAAI,CAAC,CAAA;IAErD,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE;QACnB,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,CAAA;IACtB,CAAC,EAAE,EAAE,CAAC,CAAA;IAEN,MAAM,UAAU,GAAG,CAAC,KAA0C,EAAE,EAAU,EAAE,EAAE;QAC5E,MAAM,MAAM,GAAG,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,CAAA;QAC1C,IAAI,CAAC,MAAM;YAAE,OAAM;QACnB,KAAK,CAAC,cAAc,EAAE,CAAA;QACtB,MAAM,CAAC,KAAK,EAAE,CAAA;QACd,MAAM,CAAC,cAAc,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAA;IAC5C,CAAC,CAAA;IAED,OAAO,CACL,oBAAC,KAAK,IACJ,GAAG,EAAE,GAAG,EACR,MAAM,EAAC,QAAQ,EACf,QAAQ,EAAE,CAAC,CAAC,EACZ,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC;QAExC,4BAAI,SAAS,EAAE,MAAM,CAAC,YAAY,IAAG,KAAK,CAAM;QAChD,4BAAI,SAAS,EAAE,MAAM,CAAC,WAAW,IAC9B,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CACrB,4BAAI,GAAG,EAAE,KAAK,CAAC,EAAE;YACf,oBAAC,IAAI,IAAC,IAAI,EAAE,IAAI,KAAK,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC,IACxE,KAAK,CAAC,OAAO,CACT,CACJ,CACN,CAAC,CACC,CACC,CACT,CAAA;AACH,CAAC;AAKD;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,KAAmB;IACzC,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAA;IACpC,OAAO,gCAAS,IAAI,EAAE,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,GAAI,CAAA;AAChE,CAAC;AAKD;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAuB;IACjD,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,CAAA;IACpC,OAAO,gCAAS,IAAI,EAAE,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,GAAI,CAAA;AACpE,CAAC"}

package/components/Form/form.module.css

@@ -0,0 +1,123 @@
+/*
+ * Form (§10.2). CVA function `form`. Parts: `base` (the form and its
+ * inline-size container `form`), `summary` (the danger Alert at the top,
+ * with `summaryTitle` and `summaryList`), `row` (a short pair such as city
+ * and postcode) and `actions` (the action row). Structure takes role
+ * variables only; the summary's colors are the Alert's.
+ */
+
+/* Composition sits in top-level rules, outside the layers: Lightning CSS
+ * (Next.js with Turbopack) rejects `composes` inside @layer or any nesting.
+ * The composed classes keep their own layers. */
+.summaryTitle {
+  composes: typeSubhead from '../../utils/type.module.css';
+}
+
+@layer base {
+  /*
+   * One column at --size-sm, fields --size-px-5 apart (§10.2). The root is
+   * the inline-size container `form` that fieldsets, pairs and butted
+   * submits query (§5.10.2) [D163].
+   */
+  .base {
+    container: form / inline-size;
+    display: flex;
+    flex-direction: column;
+    gap: var(--size-px-5);
+    inline-size: 100%;
+    max-inline-size: var(--size-sm);
+    color: var(--primary12);
+  }
+
+  /* The summary takes focus when it appears; the Alert draws its own bar and glyph. */
+  .summary {
+    scroll-margin-block: var(--ds-space-margin);
+  }
+
+  .summaryTitle {
+    margin: 0;
+    color: var(--primary12);
+  }
+
+  .summaryList {
+    display: grid;
+    gap: var(--size-px-2);
+    margin: 0;
+    margin-block-start: var(--size-px-2);
+    padding: 0;
+    list-style: none;
+  }
+
+  /*
+   * A short pair shares one row in a 2:1 split and stacks when both do not
+   * fit (flex-wrap at each field's minimum); from 480 px of form width it
+   * always shares the row (§5.10.2).
+   */
+  .row {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--size-px-5);
+  }
+
+  .row > * {
+    flex: 2 1 var(--size-px-12);
+    min-inline-size: 0;
+  }
+
+  .row > :last-child:not(:first-child) {
+    flex: 1 1 var(--size-px-11);
+  }
+
+  @container form (width >= 480px) {
+    .row {
+      flex-wrap: nowrap;
+    }
+  }
+
+  /*
+   * The action row, --size-px-5 above the last field: stacked with the
+   * solid submit first at base; from --md-n-above one row with the submit
+   * last (rightmost) [D106]. Author the submit last.
+   */
+  .actions {
+    display: flex;
+    flex-direction: column-reverse;
+    align-items: stretch;
+    gap: var(--ds-space-12);
+  }
+
+  @media (min-width: 768px) {
+    .actions {
+      flex-direction: row;
+      flex-wrap: wrap;
+      align-items: center;
+      justify-content: flex-end;
+    }
+  }
+}
+
+@layer states {
+  /* The summary is focused by script; the ring shows for keyboard users only [D45]. */
+  .summary:focus {
+    outline: none;
+  }
+
+  .summary:focus-visible {
+    outline: var(--border-size-2) solid var(--primary12);
+    outline-offset: var(--border-size-2);
+  }
+
+  /* Busy: the form is inert until the response; the submit reads "Sending…" [D84]. */
+  .base[aria-busy='true'] {
+    cursor: progress;
+  }
+}
+
+@layer print {
+  @media print {
+    /* The summary prints if present; the action row is interaction only. */
+    .actions {
+      display: none;
+    }
+  }
+}

package/components/Form/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Form';
+//# sourceMappingURL=index.d.ts.map

package/components/Form/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/Form/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAA"}

package/components/Form/index.js

@@ -0,0 +1,2 @@
+export * from './Form';
+//# sourceMappingURL=index.js.map

package/components/Form/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/components/Form/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAA"}

package/components/Ground/Ground.d.ts

@@ -0,0 +1,105 @@
+import React from 'react';
+import { useRender } from '@base-ui/react/use-render';
+import { type PrimaryScale, type RadixScale } from '../../utils/scales';
+import { type BandPreset, type FieldPreset, type PageGroundPreset } from '../../utils/scope';
+export { companionField, companionFields, fieldPresets, pageGroundPresets, pastelPresets, presetDefaults, type BandPreset, type FieldPreset, type GroundKind, type GroundPreset, type PageGroundPreset, type PastelPreset, type PresetDefaults, } from '../../utils/scope';
+export declare const ground: (props?: ({
+    kind?: "field" | "band" | "face" | null | undefined;
+    framed?: boolean | null | undefined;
+    island?: boolean | null | undefined;
+    primary?: "ruby" | "brown" | "crimson" | "gold" | "gray" | "indigo" | "olive" | "pink" | "plum" | "purple" | "red" | "tomato" | "violet" | "bronze" | "iris" | "mauve" | "sage" | "sand" | "slate" | null | undefined;
+    secondary?: "ruby" | "blue" | "brown" | "crimson" | "cyan" | "gold" | "gray" | "green" | "indigo" | "lime" | "olive" | "orange" | "pink" | "plum" | "purple" | "red" | "teal" | "tomato" | "violet" | "yellow" | "amber" | "bronze" | "grass" | "iris" | "jade" | "mauve" | "mint" | "sage" | "sand" | "sky" | "slate" | null | undefined;
+    action?: "ruby" | "blue" | "brown" | "crimson" | "cyan" | "gold" | "gray" | "green" | "indigo" | "lime" | "olive" | "orange" | "pink" | "plum" | "purple" | "red" | "teal" | "tomato" | "violet" | "yellow" | "amber" | "bronze" | "grass" | "iris" | "jade" | "mauve" | "mint" | "sage" | "sand" | "sky" | "slate" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export type Density = 'compact' | 'default' | 'spacious';
+interface GroundCommonProps {
+    /**
+     * Override the preset's primary. Inside tinted or solid scopes, only a
+     * pairing that §2's matrix verifies [D128].
+     */
+    primary?: PrimaryScale;
+    /** Override the preset's secondary. */
+    secondary?: RadixScale;
+    /** Override the scope's action scale. */
+    action?: RadixScale;
+    /** Written as `data-density`; inherited by the scope, so never defaulted. */
+    density?: Density;
+}
+interface GroundBandProps {
+    /**
+     * `band` (default): a full-bleed section or the page root, drawing its
+     * `--role-seam` rule top and bottom (visible only on the night band in
+     * dark mode [D179]). `field`: an inset, fixed-mode surface with a radius
+     * and a `--primary12` edge. `face`: a nested card face, plate or panel.
+     */
+    kind?: 'band';
+    /**
+     * A page ground (`paper` default, `white`, or one pastel per page:
+     * `tide`, `meadow`, `pollen`, `apricot`, `rose`, `heather`), which follows
+     * the page mode; or `night`, always dark, for the footer and the media hero
+     * only [D176, D177].
+     */
+    preset?: BandPreset;
+    framed?: never;
+    onMedia?: never;
+}
+interface GroundFieldProps {
+    kind: 'field';
+    /**
+     * A field [D177]: `forest`, `royal`, `brick` (always dark) or `leaf`,
+     * `amber`, `clay`, `pink` (always light). Required.
+     */
+    preset: FieldPreset;
+    /**
+     * The one framed feature field per page: `--ds-radius-feature` and a
+     * `--border-size-2` `--primary12` edge [D95]. Default `false`.
+     */
+    framed?: boolean;
+    onMedia?: never;
+}
+interface GroundFaceProps {
+    kind: 'face';
+    /**
+     * A page ground as a card face, plate or panel (`paper` default). On a
+     * page ground it follows the mode; inside a field or the night band it is
+     * a light island [D149, D179].
+     */
+    preset?: PageGroundPreset;
+    framed?: never;
+    onMedia?: never;
+}
+interface GroundMediaFaceProps {
+    kind: 'face';
+    /** `night` as a face: only the `onMedia` Button's dark face (§1.11.10). */
+    preset: 'night';
+    /** Declares the face as the `onMedia` Button's; required with `night` [D178]. */
+    onMedia: true;
+    framed?: never;
+}
+/**
+ * Props for Ground: `section` props, `render`, the kind and its preset, the
+ * scale overrides and the density. A discriminated union on `kind` [D178]:
+ * a field preset outside `kind="field"`, `night` as a field, `night` as a
+ * face other than `onMedia`, and deferred or retired presets are type
+ * errors. Page grounds always follow the mode, so a pastel can never be a
+ * fixed-mode anchor.
+ */
+export type GroundProps = useRender.ComponentProps<'section'> & GroundCommonProps & (GroundBandProps | GroundFieldProps | GroundFaceProps | GroundMediaFaceProps);
+/**
+ * The ground scope component (§1.11.5). Writes data-ground, data-tone and
+ * data-scheme (and data-theme where the scope fixes its mode or is a light
+ * island [D149]), adds the scale classes for the preset's defaults or the
+ * overrides, paints `--role-ground`, publishes `--role-edge`, draws the
+ * seam on bands and the edge on fields, and provides the scope to
+ * descendants through React context [D148, D178].
+ */
+export declare const Ground: React.ForwardRefExoticComponent<(Omit<React.ClassAttributes<HTMLElement> & React.HTMLAttributes<HTMLElement> & {
+    render?: React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | import("@base-ui/react").ComponentRenderFn<import("@base-ui/react").HTMLProps, {}> | undefined;
+} & GroundCommonProps & GroundBandProps, "ref"> | Omit<React.ClassAttributes<HTMLElement> & React.HTMLAttributes<HTMLElement> & {
+    render?: React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | import("@base-ui/react").ComponentRenderFn<import("@base-ui/react").HTMLProps, {}> | undefined;
+} & GroundCommonProps & GroundFieldProps, "ref"> | Omit<React.ClassAttributes<HTMLElement> & React.HTMLAttributes<HTMLElement> & {
+    render?: React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | import("@base-ui/react").ComponentRenderFn<import("@base-ui/react").HTMLProps, {}> | undefined;
+} & GroundCommonProps & GroundFaceProps, "ref"> | Omit<React.ClassAttributes<HTMLElement> & React.HTMLAttributes<HTMLElement> & {
+    render?: React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | import("@base-ui/react").ComponentRenderFn<import("@base-ui/react").HTMLProps, {}> | undefined;
+} & GroundCommonProps & GroundMediaFaceProps, "ref">) & React.RefAttributes<HTMLElement>>;
+//# sourceMappingURL=Ground.d.ts.map

package/components/Ground/Ground.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Ground.d.ts","sourceRoot":"","sources":["../../src/components/Ground/Ground.tsx"],"names":[],"mappings":"AAEA,OAAO,KAA8B,MAAM,OAAO,CAAA;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAKrD,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,WAAW,EAGhB,KAAK,gBAAgB,EAEtB,MAAM,mBAAmB,CAAA;AAE1B,OAAO,EACL,cAAc,EACd,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,cAAc,GACpB,MAAM,mBAAmB,CAAA;AAa1B,eAAO,MAAM,MAAM;;;;;;;8EAsBjB,CAAA;AAEF,MAAM,MAAM,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAA;AAExD,UAAU,iBAAiB;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,uCAAuC;IACvC,SAAS,CAAC,EAAE,UAAU,CAAA;IACtB,yCAAyC;IACzC,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,UAAU,eAAe;IACvB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,MAAM,CAAC,EAAE,KAAK,CAAA;IACd,OAAO,CAAC,EAAE,KAAK,CAAA;CAChB;AAED,UAAU,gBAAgB;IACxB,IAAI,EAAE,OAAO,CAAA;IACb;;;OAGG;IACH,MAAM,EAAE,WAAW,CAAA;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,KAAK,CAAA;CAChB;AAED,UAAU,eAAe;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAA;IACzB,MAAM,CAAC,EAAE,KAAK,CAAA;IACd,OAAO,CAAC,EAAE,KAAK,CAAA;CAChB;AAED,UAAU,oBAAoB;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,2EAA2E;IAC3E,MAAM,EAAE,OAAO,CAAA;IACf,iFAAiF;IACjF,OAAO,EAAE,IAAI,CAAA;IACb,MAAM,CAAC,EAAE,KAAK,CAAA;CACf;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,CAAC,cAAc,CAAC,SAAS,CAAC,GAC3D,iBAAiB,GACjB,CAAC,eAAe,GAAG,gBAAgB,GAAG,eAAe,GAAG,oBAAoB,CAAC,CAAA;AAE/E;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM;;;;;;;;yFA4ElB,CAAA"}

package/components/Ground/Ground.js

@@ -0,0 +1,98 @@
+'use client';
+import React, { useContext, useMemo } from 'react';
+import { useRender } from '@base-ui/react/use-render';
+import { mergeProps } from '@base-ui/react/merge-props';
+import { cva } from 'class-variance-authority';
+import styles from './ground.module.css';
+import { actionScaleVariants, primaryScaleVariants, secondaryScaleVariants, } from '../../utils/scales';
+import { GroundContext, presetDefaults, presets, resolveScheme, } from '../../utils/scope';
+export { companionField, companionFields, fieldPresets, pageGroundPresets, pastelPresets, presetDefaults, } from '../../utils/scope';
+/*
+ * Ground (§1.11.5) [D178]. CVA function `ground`.
+ * - `kind` → band | field | face: geometry, and the container edge the
+ *   scope publishes as --role-edge (--role-rule on a band, --primary12 on a
+ *   field or a light island, --primary10 on a face on a page ground).
+ * - `framed` → the one framed feature field per page (fields only).
+ * - `island` is computed, never a prop: a page ground nested as a face
+ *   inside a field or the night band [D149, D179].
+ * - Color axes: computed from the preset or the overrides, never defaulted
+ *   [D133].
+ */
+export const ground = cva(styles.base, {
+    variants: {
+        kind: {
+            band: styles.band,
+            field: styles.field,
+            face: styles.face,
+        },
+        framed: {
+            true: styles.framed,
+        },
+        island: {
+            true: styles.island,
+        },
+        primary: primaryScaleVariants,
+        secondary: secondaryScaleVariants,
+        action: actionScaleVariants,
+    },
+    defaultVariants: {
+        kind: 'band',
+        framed: false,
+        island: false,
+    },
+});
+/**
+ * The ground scope component (§1.11.5). Writes data-ground, data-tone and
+ * data-scheme (and data-theme where the scope fixes its mode or is a light
+ * island [D149]), adds the scale classes for the preset's defaults or the
+ * overrides, paints `--role-ground`, publishes `--role-edge`, draws the
+ * seam on bands and the edge on fields, and provides the scope to
+ * descendants through React context [D148, D178].
+ */
+export const Ground = React.forwardRef(function Ground(props, forwardedRef) {
+    const { preset: presetProp, kind: kindProp, framed, 
+    // A type-level declaration only; never reaches the DOM.
+    onMedia: _onMedia, primary, secondary, action, density, render, className, children, ...rest } = props;
+    const preset = presetProp ?? 'paper';
+    const kind = kindProp ?? 'band';
+    const parent = useContext(GroundContext);
+    const { tone, mode } = presets[preset];
+    const scheme = resolveScheme(preset, parent);
+    // A follows-mode preset inside a fixed scope is a light island.
+    const island = mode === 'follows' && scheme === 'light';
+    const scope = useMemo(() => ({ ground: preset, tone, scheme, kind }), [preset, tone, scheme, kind]);
+    const defaults = presetDefaults[preset];
+    const resolvedPrimary = primary ?? defaults.primary;
+    const resolvedAction = action ?? (defaults.action === 'ink' ? resolvedPrimary : defaults.action);
+    // Fixed presets write their mode; a follows-mode preset writes nothing
+    // at page level and becomes a light island inside a fixed scope.
+    const theme = mode === 'always-dark'
+        ? 'dark'
+        : mode === 'always-light' || island
+            ? 'light'
+            : undefined;
+    const element = useRender({
+        defaultTagName: 'section',
+        render,
+        ref: forwardedRef,
+        props: mergeProps({
+            className: ground({
+                kind,
+                framed: kind === 'field' && framed === true,
+                island,
+                primary: resolvedPrimary,
+                secondary: secondary ?? defaults.secondary,
+                action: resolvedAction,
+                className,
+            }),
+            'data-ground': preset,
+            'data-tone': tone,
+            'data-scheme': scheme,
+            'data-theme': theme,
+            'data-density': density,
+            children,
+        }, rest),
+    });
+    return (React.createElement(GroundContext.Provider, { value: scope }, element));
+});
+//# sourceMappingURL=Ground.js.map

package/components/Ground/Ground.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Ground.js","sourceRoot":"","sources":["../../src/components/Ground/Ground.tsx"],"names":[],"mappings":"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"}

package/components/Ground/ground.module.css

@@ -0,0 +1,84 @@
+/*
+ * Ground: the preset scope (§1.11.5) [D178]. Paints the scope's ground, sets
+ * its one text ink, publishes the container edge as --role-edge, draws the
+ * seam on full-bleed bands and the edge on fields. Colors come from
+ * roles.css through the scope attributes the component writes; the module
+ * itself names role variables only and selects no scope or mode hook.
+ *
+ * The kind classes sit in the base layer, so a composing component's
+ * variant class (the Dialog's solid cover) can reset a field's geometry.
+ */
+@layer base {
+  .base {
+    display: block;
+    color: var(--primary12);
+    background-color: var(--role-ground);
+  }
+
+  /*
+   * Full-bleed band (a page ground, or the night band): a --border-size-1
+   * seam at top and bottom in --role-seam, invisible (the ground's own
+   * color) except on the night band in dark mode, where it is --primary12
+   * [D179]. A band has no container edge, so --role-edge is --role-rule.
+   * The hairline between two different page grounds is the §11.2 divider's.
+   */
+  .band {
+    --role-edge: var(--role-rule);
+
+    border-block: var(--border-size-1) solid var(--role-seam);
+  }
+
+  /*
+   * Field [D177]: inset inside the content container, never full-bleed, with
+   * a radius and its own --primary12 edge at --border-size-1 in both modes;
+   * no seam, because the edge does that job.
+   */
+  .field {
+    --role-edge: var(--primary12);
+    --ground-edge: var(--border-size-1);
+
+    padding: var(--ds-space-margin);
+    border: var(--ground-edge) solid var(--role-edge);
+    border-radius: var(--ds-radius-8);
+  }
+
+  /*
+   * Nested face (card face, plate, panel): no seam and no geometry of its
+   * own; the composing component sets size and radius and draws its edge in
+   * --role-edge: --primary10 on a page ground [D179].
+   */
+  .face {
+    --role-edge: var(--primary10);
+
+    border-block: none;
+  }
+}
+
+@layer variants {
+  /* A page ground inside a field or the night band: a light island with a --primary12 edge [D149, D179]. */
+  .island {
+    --role-edge: var(--primary12);
+  }
+
+  /* The one framed feature field per page: --ds-radius-feature and a --border-size-2 edge [D95, D177]. */
+  .framed {
+    --ground-edge: var(--border-size-2);
+
+    border-radius: var(--ds-radius-feature);
+  }
+}
+
+@layer print {
+  @media print {
+    /* The seam is the printed ground-change rule (§1.4.5); the ground prints white. */
+    .band {
+      border-block-width: var(--border-size-1);
+      break-inside: auto;
+    }
+
+    /* A field keeps its edge on paper; the framed feature field keeps --border-size-2 [D95]. */
+    .field {
+      break-inside: avoid;
+    }
+  }
+}

package/components/Ground/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Ground';
+//# sourceMappingURL=index.d.ts.map

package/components/Ground/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/Ground/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAA"}

package/components/Ground/index.js

@@ -0,0 +1,2 @@
+export * from './Ground';
+//# sourceMappingURL=index.js.map

package/components/Ground/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/components/Ground/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAA"}