@mithrl/design-system 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# Mithrl Design System
+
+The repository for Mithrl interface foundations, design references, and reusable React components, distributed under the `@mithrl` namespace.
+
+## Repository structure
+
+- `tokens/foundations.tokens.json` is the canonical token registry.
+- [`docs/`](docs/README.md) contains approved meaning, usage, rationale, and exceptions.
+- `figma/` contains parity metadata and future Code Connect mappings; the Figma library is the design reference.
+- `src/tokens/` contains the CSS implementation generated or synchronized from the registry.
+- `src/components/` contains the production React components.
+- `.storybook/` and `tests/` contain the review and verification layers.
+
+## Local review
+
+Install dependencies, then start the executable Foundations reference:
+
+```bash
+npm install
+npm run storybook
+```
+
+The first component implementation, Button, will follow in a separate pull
+request after the Foundations baseline is approved.
+
+## Hosted Storybook
+
+Pull requests validate the Storybook build without publishing it. After an
+approved change is merged into `main`, GitHub Actions publishes the current
+Storybook to GitHub Pages for the organization.
+
+Pull request branches publish review builds through Chromatic after the
+`CHROMATIC_PROJECT_TOKEN` repository secret is configured. See the
+[workflow setup](docs/governance/workflow-setup.md) for the required settings.
+
+## Package use
+
+The library build produces an installable package with React exports, types,
+tokens, and component styles.
+
+```bash
+npm run build
+npm run check:package
+```
+
+```tsx
+import "@mithrl/design-system/styles.css";
+import { ProjectLibrary } from "@mithrl/design-system";
+```
+
+Public package changes require a Changeset.
+
+```bash
+npm run changeset
+```
+
+## Validation
+
+```bash
+npm run test
+npm run build
+npm run build-storybook
+```

package/dist/components/account-menu/AccountMenu.d.ts

@@ -0,0 +1,27 @@
+import { type ReactNode } from "react";
+import { type DropdownMenuContentProps, type DropdownMenuItemProps } from "../dropdown-menu/DropdownMenu";
+
+export type AccountMenuAction = {
+    /** Native destination for a navigational item. Omit it to render a button. */
+    href?: string;
+    /** Invoked by command items. Navigation remains owned by the anchor. */
+    onSelect?: DropdownMenuItemProps["onClick"];
+    /** Disables the action without changing the menu's structure. */
+    disabled?: boolean;
+};
+export type AccountMenuProps = Omit<DropdownMenuContentProps, "aria-label" | "children" | "width"> & {
+    /** Signed-in display name. Long names truncate to one line. */
+    displayName: string;
+    /** Supporting identity copy from the approved product contract. */
+    message?: string;
+    account?: AccountMenuAction;
+    settings?: AccountMenuAction;
+    signOut?: Omit<AccountMenuAction, "href">;
+    /** Optional replacement for the default action labels. */
+    labels?: Partial<Record<"account" | "settings" | "signOut", ReactNode>>;
+};
+/**
+ * Product-specific account actions composed from Dropdown Menu. The external
+ * native Avatar button trigger and open state remain owned by Global App Bar.
+ */
+export declare function AccountMenu({ displayName, message, account, settings, signOut, labels, align, ...contentProps }: AccountMenuProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/avatar/Avatar.d.ts

@@ -0,0 +1,38 @@
+import { type VariantProps } from "class-variance-authority";
+import { type HTMLAttributes } from "react";
+
+export declare const avatarVariants: (props?: ({
+    size?: "default" | "large" | "small" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export type AvatarSize = NonNullable<VariantProps<typeof avatarVariants>["size"]>;
+type RestrictedAvatarAttribute = "aria-hidden" | "aria-label" | "aria-live" | "children" | "onClick" | "onDoubleClick" | "onKeyDown" | "onKeyUp" | "role" | "tabIndex";
+export type AvatarProps = Omit<HTMLAttributes<HTMLSpanElement>, RestrictedAvatarAttribute> & VariantProps<typeof avatarVariants> & {
+    /** Optional image source. The fallback stays visible until it loads. */
+    src?: string;
+    /** Consumer-supplied one- or two-grapheme fallback. */
+    initials?: string;
+    /**
+     * Accessible identity name. Without a label Avatar is decorative and
+     * hidden from assistive technology.
+     */
+    label?: string;
+};
+/**
+ * A compact, display-only identity primitive. Image content is revealed only
+ * after a successful load; otherwise Avatar shows supplied initials and then
+ * the official Lucide UserRound fallback through Icon.
+ */
+export declare const Avatar: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLSpanElement>, RestrictedAvatarAttribute> & VariantProps<(props?: ({
+    size?: "default" | "large" | "small" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string> & {
+    /** Optional image source. The fallback stays visible until it loads. */
+    src?: string;
+    /** Consumer-supplied one- or two-grapheme fallback. */
+    initials?: string;
+    /**
+     * Accessible identity name. Without a label Avatar is decorative and
+     * hidden from assistive technology.
+     */
+    label?: string;
+} & import("react").RefAttributes<HTMLSpanElement>>;
+export {};

package/dist/components/badge/Badge.d.ts

@@ -0,0 +1,28 @@
+import { type VariantProps } from "class-variance-authority";
+import { type HTMLAttributes, type ReactNode } from "react";
+import { type IconGlyphComponent } from "../icon/Icon";
+
+export declare const badgeVariants: (props?: ({
+    tone?: "destructive" | "information" | "neutral" | "success" | "warning" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export type MetadataTone = NonNullable<VariantProps<typeof badgeVariants>["tone"]>;
+type RestrictedBadgeAttribute = "aria-live" | "children" | "onClick" | "onDoubleClick" | "onKeyDown" | "onKeyUp" | "role" | "tabIndex";
+export type BadgeProps = Omit<HTMLAttributes<HTMLSpanElement>, RestrictedBadgeAttribute> & VariantProps<typeof badgeVariants> & {
+    /** Short visible count or compact version. */
+    children: ReactNode;
+    /** Optional approved Lucide glyph rendered through Icon/XSmall. */
+    icon?: IconGlyphComponent;
+};
+/**
+ * A static count or compact version. Badge is intentionally noninteractive;
+ * nearby visible text supplies context for bare numeric values.
+ */
+export declare const Badge: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLSpanElement>, RestrictedBadgeAttribute> & VariantProps<(props?: ({
+    tone?: "destructive" | "information" | "neutral" | "success" | "warning" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string> & {
+    /** Short visible count or compact version. */
+    children: ReactNode;
+    /** Optional approved Lucide glyph rendered through Icon/XSmall. */
+    icon?: IconGlyphComponent;
+} & import("react").RefAttributes<HTMLSpanElement>>;
+export {};

package/dist/components/button/Button.d.ts

@@ -0,0 +1,28 @@
+import { type VariantProps } from "class-variance-authority";
+import type { ButtonHTMLAttributes, ReactNode } from "react";
+
+export declare const buttonVariants: (props?: ({
+    variant?: "brand" | "destructive" | "ghost" | "outline" | "primary" | "secondary" | "text" | null | undefined;
+    size?: "comfortable" | "compact" | "default" | "large" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export type ButtonVariant = NonNullable<VariantProps<typeof buttonVariants>["variant"]>;
+export type ButtonSize = NonNullable<VariantProps<typeof buttonVariants>["size"]>;
+export type ButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children"> & VariantProps<typeof buttonVariants> & {
+    children: ReactNode;
+    loading?: boolean;
+    leadingIcon?: ReactNode;
+    trailingIcon?: ReactNode;
+};
+/**
+ * A labelled action control following the shadcn-style variant API and
+ * Mithrl's approved visual hierarchy. Icon-only actions use IconButton.
+ */
+export declare const Button: import("react").ForwardRefExoticComponent<Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children"> & VariantProps<(props?: ({
+    variant?: "brand" | "destructive" | "ghost" | "outline" | "primary" | "secondary" | "text" | null | undefined;
+    size?: "comfortable" | "compact" | "default" | "large" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string> & {
+    children: ReactNode;
+    loading?: boolean;
+    leadingIcon?: ReactNode;
+    trailingIcon?: ReactNode;
+} & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/components/checkbox/Checkbox.d.ts

@@ -0,0 +1,27 @@
+import { type InputHTMLAttributes } from "react";
+
+export type CheckboxPreviewState = "hover" | "pressed" | "focus";
+export type CheckboxProps = Omit<InputHTMLAttributes<HTMLInputElement>, "aria-checked" | "children" | "className" | "type"> & {
+    /** Mixed parent/child selection; assigned through the native DOM property. */
+    indeterminate?: boolean;
+    /** Class applied to the 28px visual root. */
+    className?: string;
+    /** Class applied directly to the native checkbox input. */
+    inputClassName?: string;
+    /** Storybook-only hook for reviewing non-persistent CSS states. */
+    "data-preview-state"?: CheckboxPreviewState;
+};
+/**
+ * Native form checkbox with the approved compact Mithrl visual. Visible labels,
+ * descriptions, validation, and group policy belong to the owning composition.
+ */
+export declare const Checkbox: import("react").ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "aria-checked" | "children" | "className" | "type"> & {
+    /** Mixed parent/child selection; assigned through the native DOM property. */
+    indeterminate?: boolean;
+    /** Class applied to the 28px visual root. */
+    className?: string;
+    /** Class applied directly to the native checkbox input. */
+    inputClassName?: string;
+    /** Storybook-only hook for reviewing non-persistent CSS states. */
+    "data-preview-state"?: CheckboxPreviewState;
+} & import("react").RefAttributes<HTMLInputElement>>;

package/dist/components/dialog/Dialog.d.ts

@@ -0,0 +1,94 @@
+import { Dialog as BaseDialog } from "@base-ui/react/dialog";
+import { type VariantProps } from "class-variance-authority";
+import { type ComponentPropsWithoutRef, type ReactNode } from "react";
+import { type IconButtonProps } from "../icon-button/IconButton";
+
+export declare const dialogPopupVariants: (props?: ({
+    size?: "default" | "large" | "small" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export type DialogSize = NonNullable<VariantProps<typeof dialogPopupVariants>["size"]>;
+export type DialogRootProps = Omit<ComponentPropsWithoutRef<typeof BaseDialog.Root>, "modal">;
+export type DialogTriggerProps = ComponentPropsWithoutRef<typeof BaseDialog.Trigger>;
+export type DialogPortalProps = ComponentPropsWithoutRef<typeof BaseDialog.Portal>;
+/**
+ * Modal state owner. Base UI provides focus trapping, outside-page inertness,
+ * Escape dismissal, scroll locking, and focus return.
+ */
+export declare function DialogRoot(props: DialogRootProps): import("react/jsx-runtime").JSX.Element;
+export declare const DialogTrigger: BaseDialog.Trigger;
+export declare const DialogPortal: import("react").ForwardRefExoticComponent<Omit<import("@base-ui/react").DialogPortalProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+export type DialogBackdropProps = Omit<ComponentPropsWithoutRef<typeof BaseDialog.Backdrop>, "className"> & {
+    className?: string;
+};
+export declare const DialogBackdrop: import("react").ForwardRefExoticComponent<Omit<Omit<Omit<import("@base-ui/react").DialogBackdropProps, "ref"> & import("react").RefAttributes<HTMLDivElement>, "ref">, "className"> & {
+    className?: string;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export type DialogViewportProps = Omit<ComponentPropsWithoutRef<typeof BaseDialog.Viewport>, "className"> & {
+    className?: string;
+};
+export declare const DialogViewport: import("react").ForwardRefExoticComponent<Omit<Omit<Omit<import("@base-ui/react").DialogViewportProps, "ref"> & import("react").RefAttributes<HTMLDivElement>, "ref">, "className"> & {
+    className?: string;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export type DialogPopupProps = Omit<ComponentPropsWithoutRef<typeof BaseDialog.Popup>, "className"> & VariantProps<typeof dialogPopupVariants> & {
+    className?: string;
+};
+export declare const DialogPopup: import("react").ForwardRefExoticComponent<Omit<Omit<Omit<import("@base-ui/react").DialogPopupProps, "ref"> & import("react").RefAttributes<HTMLDivElement>, "ref">, "className"> & VariantProps<(props?: ({
+    size?: "default" | "large" | "small" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string> & {
+    className?: string;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export type DialogHeaderProps = ComponentPropsWithoutRef<"header">;
+export declare const DialogHeader: import("react").ForwardRefExoticComponent<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLElement>, HTMLElement>, "ref"> & import("react").RefAttributes<HTMLElement>>;
+export type DialogTitleProps = Omit<ComponentPropsWithoutRef<typeof BaseDialog.Title>, "className"> & {
+    className?: string;
+};
+export declare const DialogTitle: import("react").ForwardRefExoticComponent<Omit<Omit<Omit<import("@base-ui/react").DialogTitleProps, "ref"> & import("react").RefAttributes<HTMLHeadingElement>, "ref">, "className"> & {
+    className?: string;
+} & import("react").RefAttributes<HTMLHeadingElement>>;
+export type DialogDescriptionProps = Omit<ComponentPropsWithoutRef<typeof BaseDialog.Description>, "className"> & {
+    className?: string;
+};
+export declare const DialogDescription: import("react").ForwardRefExoticComponent<Omit<Omit<Omit<import("@base-ui/react").DialogDescriptionProps, "ref"> & import("react").RefAttributes<HTMLParagraphElement>, "ref">, "className"> & {
+    className?: string;
+} & import("react").RefAttributes<HTMLParagraphElement>>;
+export type DialogBodyProps = ComponentPropsWithoutRef<"div">;
+/**
+ * The Dialog's only scroll owner. A top fade appears after content starts
+ * leaving the readable region; at rest, the first item keeps a clear inset.
+ */
+export declare const DialogBody: import("react").ForwardRefExoticComponent<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+export type DialogFooterProps = ComponentPropsWithoutRef<"footer">;
+export declare const DialogFooter: import("react").ForwardRefExoticComponent<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLElement>, HTMLElement>, "ref"> & import("react").RefAttributes<HTMLElement>>;
+export type DialogCloseProps = ComponentPropsWithoutRef<typeof BaseDialog.Close>;
+export declare const DialogClose: import("react").ForwardRefExoticComponent<Omit<import("@base-ui/react").DialogCloseProps, "ref"> & import("react").RefAttributes<HTMLButtonElement>>;
+export type DialogCloseButtonProps = Omit<IconButtonProps, "icon" | "variant" | "size" | "aria-label"> & {
+    label?: string;
+};
+/** Approved, accessible close action using the shared Icon Button primitive. */
+export declare const DialogCloseButton: import("react").ForwardRefExoticComponent<Omit<IconButtonProps, "aria-label" | "icon" | "size" | "variant"> & {
+    label?: string;
+} & import("react").RefAttributes<HTMLButtonElement>>;
+export type DialogContentProps = {
+    children: ReactNode;
+    /** Portal destination used to retain a local Light or Dark theme boundary. */
+    portalContainer?: DialogPortalProps["container"];
+    keepMounted?: DialogPortalProps["keepMounted"];
+    backdropProps?: DialogBackdropProps;
+    viewportProps?: DialogViewportProps;
+} & DialogPopupProps;
+/**
+ * Convenience layer for the approved Portal → Backdrop → Viewport → Popup
+ * structure. Header, Body, and Footer remain explicitly compositional.
+ */
+export declare const DialogContent: import("react").ForwardRefExoticComponent<{
+    children: ReactNode;
+    /** Portal destination used to retain a local Light or Dark theme boundary. */
+    portalContainer?: DialogPortalProps["container"];
+    keepMounted?: DialogPortalProps["keepMounted"];
+    backdropProps?: DialogBackdropProps;
+    viewportProps?: DialogViewportProps;
+} & Omit<Omit<Omit<import("@base-ui/react").DialogPopupProps, "ref"> & import("react").RefAttributes<HTMLDivElement>, "ref">, "className"> & VariantProps<(props?: ({
+    size?: "default" | "large" | "small" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string> & {
+    className?: string;
+} & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/dropdown-menu/DropdownMenu.d.ts

@@ -0,0 +1,102 @@
+import { Menu } from "@base-ui/react/menu";
+import { type VariantProps } from "class-variance-authority";
+import { type ComponentPropsWithoutRef, type ReactNode } from "react";
+
+export declare const dropdownMenuContentVariants: (props?: ({
+    width?: "compact" | "default" | "maximum" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export type DropdownMenuContentWidth = NonNullable<VariantProps<typeof dropdownMenuContentVariants>["width"]>;
+export type DropdownMenuItemTone = "neutral" | "destructive";
+export declare const DropdownMenuTrigger: Menu.Trigger;
+export type DropdownMenuProps = ComponentPropsWithoutRef<typeof Menu.Root>;
+export type DropdownMenuTriggerProps = ComponentPropsWithoutRef<typeof Menu.Trigger>;
+/**
+ * Menu state owner. Mithrl menus are non-modal by default so outside content
+ * remains available while the menu is open; consumers may opt into modal
+ * behavior explicitly when a documented composition requires it.
+ */
+export declare function DropdownMenu({ modal, ...props }: DropdownMenuProps): import("react/jsx-runtime").JSX.Element;
+export type DropdownMenuContentProps = Omit<ComponentPropsWithoutRef<typeof Menu.Positioner>, "children" | "className"> & {
+    children: ReactNode;
+    /** Approved preset width. Product compositions document wider exceptions. */
+    width?: DropdownMenuContentWidth;
+    /** Class applied to the positioned layer rather than the popup surface. */
+    positionerClassName?: string;
+    /** Class applied to the popup surface. */
+    className?: string;
+    /** Keeps the portal mounted while closed for controlled exit workflows. */
+    keepMounted?: boolean;
+    /** Optional portal owner, useful when a local theme boundary must be retained. */
+    portalContainer?: ComponentPropsWithoutRef<typeof Menu.Portal>["container"];
+    /** Focus destination after dismissal. Defaults to Base UI's trigger return. */
+    finalFocus?: ComponentPropsWithoutRef<typeof Menu.Popup>["finalFocus"];
+    /** Accessible name when no visible group label names the menu. */
+    "aria-label"?: string;
+};
+/**
+ * Portalled, collision-aware menu surface. Trigger styling remains external.
+ * The Base UI behavior layer owns dismissal, roving focus, typeahead, focus
+ * return, and positioning while Mithrl owns geometry, tokens, and motion.
+ */
+export declare const DropdownMenuContent: import("react").ForwardRefExoticComponent<Omit<Omit<Omit<import("@base-ui/react").MenuPositionerProps, "ref"> & import("react").RefAttributes<HTMLDivElement>, "ref">, "children" | "className"> & {
+    children: ReactNode;
+    /** Approved preset width. Product compositions document wider exceptions. */
+    width?: DropdownMenuContentWidth;
+    /** Class applied to the positioned layer rather than the popup surface. */
+    positionerClassName?: string;
+    /** Class applied to the popup surface. */
+    className?: string;
+    /** Keeps the portal mounted while closed for controlled exit workflows. */
+    keepMounted?: boolean;
+    /** Optional portal owner, useful when a local theme boundary must be retained. */
+    portalContainer?: ComponentPropsWithoutRef<typeof Menu.Portal>["container"];
+    /** Focus destination after dismissal. Defaults to Base UI's trigger return. */
+    finalFocus?: ComponentPropsWithoutRef<typeof Menu.Popup>["finalFocus"];
+    /** Accessible name when no visible group label names the menu. */
+    "aria-label"?: string;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export type DropdownMenuGroupProps = Omit<ComponentPropsWithoutRef<typeof Menu.Group>, "className"> & {
+    className?: string;
+};
+export declare const DropdownMenuGroup: import("react").ForwardRefExoticComponent<Omit<Omit<Omit<import("@base-ui/react").MenuGroupProps, "ref"> & import("react").RefAttributes<HTMLDivElement>, "ref">, "className"> & {
+    className?: string;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export type DropdownMenuLabelProps = Omit<ComponentPropsWithoutRef<typeof Menu.GroupLabel>, "className"> & {
+    className?: string;
+};
+export declare const DropdownMenuLabel: import("react").ForwardRefExoticComponent<Omit<Omit<Omit<import("@base-ui/react").MenuGroupLabelProps, "ref"> & import("react").RefAttributes<HTMLDivElement>, "ref">, "className"> & {
+    className?: string;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export type DropdownMenuItemProps = Omit<ComponentPropsWithoutRef<typeof Menu.Item>, "children" | "className" | "nativeButton" | "render"> & {
+    children: ReactNode;
+    leadingIcon?: ReactNode;
+    shortcut?: ReactNode;
+    tone?: DropdownMenuItemTone;
+    className?: string;
+};
+export declare const DropdownMenuItem: import("react").ForwardRefExoticComponent<Omit<Omit<Omit<import("@base-ui/react").MenuItemProps, "ref"> & import("react").RefAttributes<HTMLElement>, "ref">, "children" | "className" | "nativeButton" | "render"> & {
+    children: ReactNode;
+    leadingIcon?: ReactNode;
+    shortcut?: ReactNode;
+    tone?: DropdownMenuItemTone;
+    className?: string;
+} & import("react").RefAttributes<HTMLElement>>;
+export type DropdownMenuLinkItemProps = Omit<ComponentPropsWithoutRef<typeof Menu.LinkItem>, "children" | "className"> & {
+    children: ReactNode;
+    leadingIcon?: ReactNode;
+    shortcut?: ReactNode;
+    className?: string;
+};
+export declare const DropdownMenuLinkItem: import("react").ForwardRefExoticComponent<Omit<Omit<Omit<import("@base-ui/react").MenuLinkItemProps, "ref"> & import("react").RefAttributes<Element>, "ref">, "children" | "className"> & {
+    children: ReactNode;
+    leadingIcon?: ReactNode;
+    shortcut?: ReactNode;
+    className?: string;
+} & import("react").RefAttributes<Element>>;
+export type DropdownMenuSeparatorProps = Omit<ComponentPropsWithoutRef<typeof Menu.Separator>, "children" | "className" | "orientation"> & {
+    className?: string;
+};
+export declare const DropdownMenuSeparator: import("react").ForwardRefExoticComponent<Omit<Omit<Omit<import("@base-ui/react").SeparatorProps, "ref"> & import("react").RefAttributes<HTMLDivElement>, "ref">, "children" | "className" | "orientation"> & {
+    className?: string;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export declare function DropdownMenuShortcut({ className, ...props }: ComponentPropsWithoutRef<"span">): import("react/jsx-runtime").JSX.Element;

package/dist/components/field/Field.d.ts

@@ -0,0 +1,62 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+
+export type FieldSize = "standard" | "compact";
+export type FieldState = "default" | "warning" | "error";
+export type FieldControlStatus = "default" | "warning";
+export type FieldControlProps = {
+    id: string;
+    required?: boolean;
+    disabled?: boolean;
+    "aria-invalid"?: true;
+    "aria-describedby"?: string;
+    "aria-errormessage"?: string;
+};
+export type FieldRenderProps = {
+    /** Native and ARIA props that must be spread onto the labelable control. */
+    controlProps: FieldControlProps;
+    /** Advisory surface supported by Text Field and Textarea. */
+    status: FieldControlStatus;
+};
+type FieldRequirement = {
+    required: true;
+    optional?: never;
+} | {
+    optional: true;
+    required?: never;
+} | {
+    required?: false;
+    optional?: false;
+};
+type FieldFeedback = {
+    warning: ReactNode;
+    error?: never;
+    description?: never;
+} | {
+    error: ReactNode;
+    warning?: never;
+    description?: ReactNode;
+} | {
+    warning?: never;
+    error?: never;
+    description?: ReactNode;
+};
+export type FieldProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & FieldRequirement & FieldFeedback & {
+    /** Persistent visible name for the control. */
+    label: ReactNode;
+    /** Receives the resolved association props without cloning a child. */
+    children: (props: FieldRenderProps) => ReactNode;
+    /** Consumer-owned ID. A stable generated ID is used when omitted. */
+    controlId?: string;
+    /** Consumer-owned description IDs merged before Field-owned IDs. */
+    describedBy?: string;
+    size?: FieldSize;
+    /** Propagates the native disabled state and readable label treatment. */
+    disabled?: boolean;
+};
+/**
+ * Associates one persistent label and its feedback with one labelable control.
+ * Products own validation timing, live announcements, and control-specific
+ * behavior such as read-only state.
+ */
+export declare function Field({ label, children, controlId, describedBy, size, description, warning, error, required, optional, disabled, className, ...props }: FieldProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/field-label/FieldLabel.d.ts

@@ -0,0 +1,32 @@
+import { type LabelHTMLAttributes, type ReactNode } from "react";
+
+export declare const fieldLabelVariants: (props?: ({
+    size?: "compact" | "standard" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export type FieldLabelSize = "standard" | "compact";
+export type FieldLabelProps = Omit<LabelHTMLAttributes<HTMLLabelElement>, "className"> & {
+    /** Approved semantic typography size. */
+    size?: FieldLabelSize;
+    /** Shows the explicit optional-field cue approved for Field composition. */
+    optional?: boolean;
+    /** Applies readable lower emphasis when the associated control is disabled. */
+    disabled?: boolean;
+    /** Class applied to the native label element. */
+    className?: string;
+    children: ReactNode;
+};
+/**
+ * Persistent visible name for one native form control. Field layout, messages,
+ * generated IDs, and validation behavior belong to the containing composition.
+ */
+export declare const FieldLabel: import("react").ForwardRefExoticComponent<Omit<LabelHTMLAttributes<HTMLLabelElement>, "className"> & {
+    /** Approved semantic typography size. */
+    size?: FieldLabelSize;
+    /** Shows the explicit optional-field cue approved for Field composition. */
+    optional?: boolean;
+    /** Applies readable lower emphasis when the associated control is disabled. */
+    disabled?: boolean;
+    /** Class applied to the native label element. */
+    className?: string;
+    children: ReactNode;
+} & import("react").RefAttributes<HTMLLabelElement>>;

package/dist/components/field-message/FieldMessage.d.ts

@@ -0,0 +1,23 @@
+import { type VariantProps } from "class-variance-authority";
+import { type HTMLAttributes, type ReactNode } from "react";
+
+export declare const fieldMessageVariants: (props?: ({
+    tone?: "error" | "helper" | "warning" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export type FieldMessageTone = NonNullable<VariantProps<typeof fieldMessageVariants>["tone"]>;
+export type FieldMessageProps = Omit<HTMLAttributes<HTMLParagraphElement>, "children" | "className"> & VariantProps<typeof fieldMessageVariants> & {
+    /** Supporting or validation text for one form control. */
+    children: ReactNode;
+    className?: string;
+};
+/**
+ * Supporting or validation text for one form control. The consumer owns the
+ * ID, ARIA relationship, live-region policy, and validation behavior.
+ */
+export declare const FieldMessage: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLParagraphElement>, "children" | "className"> & VariantProps<(props?: ({
+    tone?: "error" | "helper" | "warning" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string> & {
+    /** Supporting or validation text for one form control. */
+    children: ReactNode;
+    className?: string;
+} & import("react").RefAttributes<HTMLParagraphElement>>;

package/dist/components/file-dropzone/FileDropzone.d.ts

@@ -0,0 +1,54 @@
+import { type HTMLAttributes } from "react";
+
+export type FileDropzoneSelectionSource = "browse" | "folder" | "drop";
+export type FileDropzoneSelection = {
+    files: File[];
+    source: FileDropzoneSelectionSource;
+};
+export type FileDropzoneRejectionReason = "count" | "size" | "type";
+export type FileDropzoneRejection = {
+    files: File[];
+    reason: FileDropzoneRejectionReason;
+    message: string;
+};
+export type FileDropzoneState = "default" | "drag-active" | "drag-rejected" | "disabled" | "selection-received";
+export type FileDropzoneHandle = {
+    browseFiles: () => void;
+    browseFolder: () => void;
+    focusBrowse: () => void;
+};
+export type FileDropzoneProps = Omit<HTMLAttributes<HTMLDivElement>, "children" | "onDrop" | "onDragEnter" | "onDragLeave" | "onDragOver"> & {
+    /** Persistent accessible name for the acquisition control. */
+    label: string;
+    /** Native accept policy, for example `.csv,application/pdf,image/*`. */
+    accept?: string;
+    multiple?: boolean;
+    enableFolderSelection?: boolean;
+    maxFiles?: number;
+    maxFileSize?: number;
+    disabled?: boolean;
+    onSelection?: (selection: FileDropzoneSelection) => void;
+    onReject?: (rejection: FileDropzoneRejection) => void;
+    /** Review-only state hook used by Storybook and visual regression tests. */
+    "data-preview-state"?: FileDropzoneState;
+};
+/**
+ * Generic file and folder acquisition surface. FileDropzone normalizes native
+ * picker and drop selections; upload lifecycle and product persistence remain
+ * with the owning workflow.
+ */
+export declare const FileDropzone: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children" | "onDragEnter" | "onDragLeave" | "onDragOver" | "onDrop"> & {
+    /** Persistent accessible name for the acquisition control. */
+    label: string;
+    /** Native accept policy, for example `.csv,application/pdf,image/*`. */
+    accept?: string;
+    multiple?: boolean;
+    enableFolderSelection?: boolean;
+    maxFiles?: number;
+    maxFileSize?: number;
+    disabled?: boolean;
+    onSelection?: (selection: FileDropzoneSelection) => void;
+    onReject?: (rejection: FileDropzoneRejection) => void;
+    /** Review-only state hook used by Storybook and visual regression tests. */
+    "data-preview-state"?: FileDropzoneState;
+} & import("react").RefAttributes<FileDropzoneHandle>>;