@marwes-ui/react 0.0.4 → 1.0.1

package/dist/index.d.ts

@@ -1,42 +1,28 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { Preset, ThemeOverrides, ThemeMode, System, Theme, ButtonOptions, InputOptions, iconRegistry, IconSize, IconStrokeWidth, CheckboxProps as CheckboxProps$1, DividerOptions, DividerSize, DividerOrientation, HeadingOptions, HeadingSize, ParagraphOptions, ParagraphSize } from '@marwes-ui/core';
-export { ButtonAction, ButtonSize, ButtonVariant, IconName, Preset, System, Theme, ThemeOverrides } from '@marwes-ui/core';
+import { ThemeInput, ThemeMode, FontLoadingConfig, ResolvedTheme, ButtonOptions, InputOptions, SelectOptions, SelectAppearance as SelectAppearance$1, SelectOption as SelectOption$1, TextareaOptions, RichTextOptions, InputOtpOptions, CurrencyCode, iconRegistry, IconSize, IconStrokeWidth, AvatarOptions, CheckboxProps as CheckboxProps$1, DividerOptions, DividerSize, DividerOrientation, SpinnerOptions, SpacingOptions, SpacingSize, HeadingOptions, HeadingSize, ParagraphOptions, ParagraphSize, ToastOptions, ToastVariant, ToastIntent, ToastPlacement, TooltipOptions, IconNameType, RadioOptions, BadgeOptions, SwitchOptions, SliderOptions, TabOptions, DialogOptions } from '@marwes-ui/core';
+export { AvatarSize, AvatarType, BadgeVariant, ButtonAction, ButtonSize, ButtonVariant, Density, FontLoadingConfig, FontLoadingMode, FontLoadingOptions, IconName, MwAvailableFont, MwFontFallback, MwGoogleFontFamily, MwStyledTheme, MwThemeVarName, MwThemeVarNames, MwThemeVarReference, MwThemeVars, ResolvedTheme, SpacingSize, Spacings, SwitchSize, Theme, ThemeInput, ThemeMode, ToneName, createFontStack, mwAvailableFonts, mwFontFallbacks, mwGoogleFontFamilies, mwStyledTheme, mwThemeVarNames, mwThemeVars, mwVar } from '@marwes-ui/core';
 import * as React from 'react';
 
 type MarwesProviderProps = {
-    preset?: Preset;
-    theme?: ThemeOverrides;
-    /**
-     * Current theme mode. Determines light or dark color palette.
-     * When changed, efficiently switches theme colors without recreating the entire system.
-     */
+    theme?: ThemeInput;
+    defaultMode?: ThemeMode;
     mode?: ThemeMode;
-    /**
-     * Callback fired when mode should change.
-     * Users are responsible for managing mode state and persistence (e.g., localStorage).
-     *
-     * Example with persistence:
-     * ```tsx
-     * const [mode, setMode] = useState<ThemeMode>(
-     *   () => (localStorage.getItem('theme-mode') as ThemeMode) ?? 'light'
-     * );
-     *
-     * const handleModeChange = (newMode: ThemeMode) => {
-     *   setMode(newMode);
-     *   localStorage.setItem('theme-mode', newMode);
-     * };
-     *
-     * <MarwesProvider mode={mode} onModeChange={handleModeChange}>
-     * ```
-     */
+    fontLoading?: FontLoadingConfig;
     onModeChange?: (mode: ThemeMode) => void;
     children: React.ReactNode;
 };
-declare function MarwesProvider({ preset, theme, mode, onModeChange, children, }: MarwesProviderProps): react_jsx_runtime.JSX.Element;
+declare function MarwesProvider({ theme, defaultMode, mode: controlledMode, fontLoading, onModeChange, children, }: MarwesProviderProps): react_jsx_runtime.JSX.Element;
 
-declare function useSystem(): System;
+declare function useTheme(): ResolvedTheme;
 
-declare function useTheme(): Theme;
+type ThemeModeContextValue = {
+    mode: ThemeMode;
+    setMode: (mode: ThemeMode) => void;
+    toggleMode: () => void;
+    isDark: boolean;
+    isLight: boolean;
+};
+declare function useThemeMode(): ThemeModeContextValue;
 
 type ButtonProps = ButtonOptions & {
     children?: React.ReactNode;
@@ -46,162 +32,568 @@ type ButtonProps = ButtonOptions & {
 declare function Button(props: ButtonProps): react_jsx_runtime.JSX.Element;
 
 /**
- * Semantic Button Variants - AI-Friendly Components
+ * Purpose Components — Button
  *
- * These variants encode best practices and automatically set AI-friendly
- * metadata, making it easier for both developers and AI tools to understand
- * the purpose and behavior of each button.
+ * Pre-configured button compositions that encode a specific semantic purpose.
+ * Purpose buttons lock semantic intent and canonical visual treatment.
  */
-type DangerButtonProps = Omit<ButtonProps, "variant" | "action"> & {
+type DestructiveButtonProps = Omit<ButtonProps, "variant" | "action" | "as" | "href"> & {
     /**
      * Override automatic confirmation requirement.
      * Defaults to `true` for destructive actions.
      */
     confirmation?: boolean;
 };
+declare function DestructiveButton(props: DestructiveButtonProps): react_jsx_runtime.JSX.Element;
+type CreateButtonProps = Omit<ButtonProps, "variant" | "action">;
+declare function CreateButton(props: CreateButtonProps): react_jsx_runtime.JSX.Element;
+type SubmitButtonProps = Omit<ButtonProps, "variant" | "action" | "as" | "href">;
+declare function SubmitButton(props: SubmitButtonProps): react_jsx_runtime.JSX.Element;
+type CancelButtonProps = Omit<ButtonProps, "variant" | "action">;
+declare function CancelButton(props: CancelButtonProps): react_jsx_runtime.JSX.Element;
+type LinkButtonProps = Omit<ButtonProps, "variant" | "action" | "as"> & {
+    href: string;
+};
+declare function LinkButton(props: LinkButtonProps): react_jsx_runtime.JSX.Element;
+type SaveButtonProps = Omit<ButtonProps, "variant" | "action">;
+declare function SaveButton(props: SaveButtonProps): react_jsx_runtime.JSX.Element;
+type ConfirmButtonProps = Omit<ButtonProps, "variant" | "action" | "as" | "href">;
+declare function ConfirmButton(props: ConfirmButtonProps): react_jsx_runtime.JSX.Element;
+type VerifyButtonProps = Omit<ButtonProps, "variant" | "action" | "as" | "href">;
+declare function VerifyButton(props: VerifyButtonProps): react_jsx_runtime.JSX.Element;
+type EditButtonProps = Omit<ButtonProps, "variant" | "action">;
+declare function EditButton(props: EditButtonProps): react_jsx_runtime.JSX.Element;
+type CloseButtonProps = Omit<ButtonProps, "variant" | "action">;
+declare function CloseButton(props: CloseButtonProps): react_jsx_runtime.JSX.Element;
+type RefreshButtonProps = Omit<ButtonProps, "variant" | "action">;
+declare function RefreshButton(props: RefreshButtonProps): react_jsx_runtime.JSX.Element;
+type UploadButtonProps = Omit<ButtonProps, "variant" | "action">;
+declare function UploadButton(props: UploadButtonProps): react_jsx_runtime.JSX.Element;
+type DownloadButtonProps = Omit<ButtonProps, "variant" | "action">;
+declare function DownloadButton(props: DownloadButtonProps): react_jsx_runtime.JSX.Element;
+type CopyButtonProps = Omit<ButtonProps, "variant" | "action">;
+declare function CopyButton(props: CopyButtonProps): react_jsx_runtime.JSX.Element;
+type SearchButtonProps = Omit<ButtonProps, "variant" | "action">;
+declare function SearchButton(props: SearchButtonProps): react_jsx_runtime.JSX.Element;
+type FilterButtonProps = Omit<ButtonProps, "variant" | "action">;
+declare function FilterButton(props: FilterButtonProps): react_jsx_runtime.JSX.Element;
+type SortButtonProps = Omit<ButtonProps, "variant" | "action">;
+declare function SortButton(props: SortButtonProps): react_jsx_runtime.JSX.Element;
+type DropdownButtonProps = Omit<ButtonProps, "variant" | "action">;
+declare function DropdownButton(props: DropdownButtonProps): react_jsx_runtime.JSX.Element;
+type PrimaryButtonProps = Omit<ButtonProps, "variant" | "as"> & {};
+declare function PrimaryButton(props: PrimaryButtonProps): react_jsx_runtime.JSX.Element;
+type SecondaryButtonProps = Omit<ButtonProps, "variant" | "as"> & {};
+declare function SecondaryButton(props: SecondaryButtonProps): react_jsx_runtime.JSX.Element;
+type TextButtonProps = Omit<ButtonProps, "variant" | "as"> & {};
+declare function TextButton(props: TextButtonProps): react_jsx_runtime.JSX.Element;
+type SuccessButtonProps = Omit<ButtonProps, "variant" | "as"> & {};
+declare function SuccessButton(props: SuccessButtonProps): react_jsx_runtime.JSX.Element;
+
+type InputProps = InputOptions & {
+    onValueChange?: (value: string) => void;
+    className?: string;
+};
+declare function Input(props: InputProps): react_jsx_runtime.JSX.Element;
+
+type SelectAppearance = SelectAppearance$1;
+type SelectOption = SelectOption$1;
+type SelectProps = SelectOptions & {
+    onValueChange?: (value: string) => void;
+    className?: string;
+};
+declare function Select(props: SelectProps): react_jsx_runtime.JSX.Element;
+
+type TextareaProps = TextareaOptions & {
+    onValueChange?: (value: string) => void;
+    className?: string;
+};
+declare function Textarea(props: TextareaProps): react_jsx_runtime.JSX.Element;
+
+type RichTextProps = RichTextOptions & {
+    onValueChange?: (value: string) => void;
+    className?: string;
+};
+declare const RichText: React.ForwardRefExoticComponent<RichTextOptions & {
+    onValueChange?: (value: string) => void;
+    className?: string;
+} & React.RefAttributes<HTMLDivElement>>;
+
+type InputFieldProps = {
+    /** Optional: if omitted, we generate one via useId(). */
+    id?: string;
+    /** Field label (required for accessibility). */
+    label: string;
+    /** Optional helper text shown below the input. */
+    helperText?: string;
+    /** Optional error message. When present, input is marked invalid. */
+    error?: string;
+    /** Props forwarded to the Input atom. */
+    input: InputProps;
+    /** Additional aria-describedby IDs to merge with internal helper/error IDs. */
+    ariaDescribedBy?: string;
+    /** Optional leading text symbol displayed inside the input on the left (e.g. "$", "€", "kr"). */
+    leadingSymbol?: string;
+};
 /**
- * DangerButton - For destructive actions like delete, remove, or irreversible operations.
+ * InputField (Molecule) — Recommended
+ *
+ * A convenient, accessible wrapper around `Input` that provides:
+ * - a visible `<label>` wired via `htmlFor`/`id`
+ * - optional `helperText` and `error` regions
+ * - automatic `aria-describedby` wiring (helperText + error + any external ids)
+ * - automatic invalid state when `error` is present
+ *
+ * Use `InputField` for most forms. Use `Input` directly only when you need
+ * a highly custom layout or composite inputs.
+ *
+ * Accessibility
+ * - Generates a stable `id` via `useId()` when `id` is not provided.
+ * - Always renders a visible `<label>` element connected to the input control.
+ * - When `helperText` and/or `error` are present, it sets `aria-describedby`
+ *   on the input to reference their ids.
+ * - When `error` is present, the input is marked invalid (aria-invalid).
+ * - Error region has `aria-live="polite"` for screen reader announcements.
+ *
+ * @example Minimal (recommended)
+ * ```tsx
+ * <InputField
+ *   label="Email address"
+ *   input={{ type: "email", placeholder: "you@example.com" }}
+ * />
+ * ```
+ *
+ * @example With helper text
+ * ```tsx
+ * <InputField
+ *   label="Username"
+ *   helperText="Choose a unique username between 3-20 characters."
+ *   input={{ type: "text", placeholder: "johnsmith" }}
+ * />
+ * ```
+ *
+ * @example With error (invalid state)
+ * ```tsx
+ * <InputField
+ *   label="Password"
+ *   error="Password must be at least 8 characters."
+ *   input={{ type: "password", required: true }}
+ * />
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [email, setEmail] = React.useState("");
+ *
+ * <InputField
+ *   label="Email"
+ *   input={{
+ *     type: "email",
+ *     value: email,
+ *     onValueChange: setEmail,
+ *   }}
+ * />
+ * ```
+ *
+ * @example Disabled
+ * ```tsx
+ * <InputField
+ *   label="Account ID"
+ *   helperText="This value cannot be changed."
+ *   input={{ value: "ACC-12345", disabled: true }}
+ * />
+ * ```
+ *
+ * @example Read-only
+ * ```tsx
+ * <InputField
+ *   label="Account created"
+ *   input={{ value: "January 15, 2026", readOnly: true }}
+ * />
+ * ```
+ *
+ * @example Custom describedBy (merge with internal helper/error)
+ * ```tsx
+ * <InputField
+ *   ariaDescribedBy="my-extra-help"
+ *   label="API Key"
+ *   helperText="Your key is stored securely."
+ *   input={{ type: "password" }}
+ * />
+ *
+ * <div id="my-extra-help">This can be regenerated from your settings.</div>
+ * ```
+ */
+declare function InputField(props: InputFieldProps): React.ReactElement;
+
+type InputOtpProps = Omit<InputOtpOptions, "describedBy"> & {
+    label: string;
+    helperText?: string;
+    error?: string;
+    ariaDescribedBy?: string;
+    onValueChange?: (value: string) => void;
+    className?: string;
+};
+declare function InputOtp(props: InputOtpProps): React.ReactElement;
+
+type SelectFieldProps = {
+    id?: string;
+    label: string;
+    helperText?: string;
+    error?: string;
+    select: SelectProps;
+    ariaDescribedBy?: string;
+};
+declare function SelectField(props: SelectFieldProps): React.ReactElement;
+
+type TextareaFieldProps = {
+    id?: string;
+    label: string;
+    helperText?: string;
+    error?: string;
+    textarea: TextareaProps;
+    ariaDescribedBy?: string;
+};
+declare function TextareaField(props: TextareaFieldProps): React.ReactElement;
+
+type RichTextFieldProps = {
+    id?: string;
+    label: string;
+    helperText?: string;
+    error?: string;
+    editor: RichTextProps;
+    ariaDescribedBy?: string;
+};
+declare function RichTextField(props: RichTextFieldProps): React.ReactElement;
+
+/**
+ * Field Variants - AI-Friendly Components
+ *
+ * These variants encode best practices and automatically set AI-friendly
+ * metadata, making it easier for both developers and AI tools to understand
+ * the purpose and behavior of each field.
+ *
+ * Each variant manages its own purpose-specific logic (password toggle,
+ * search clear, etc.) and sets appropriate semantic attributes.
+ */
+type DropdownFieldProps = Omit<SelectFieldProps, "select"> & {
+    /**
+     * Select-specific props. Use `native` to opt back into the browser dropdown.
+     */
+    select: Omit<SelectProps, "appearance"> & {
+        native?: boolean;
+    };
+};
+/**
+ * DropdownField - For the Figma-aligned dropdown presentation.
  *
  * **AI Context:**
- * - Sets `variant="primary"` with error state for visual warning
- * - Sets `action="delete"` to indicate destructive behavior
- * - Enables confirmation by default
- * - Adds `data-destructive="true"` for AI parsing
+ * - Reuses `SelectField` accessibility and state wiring
+ * - Defaults to the Marwes dropdown presentation
+ * - Allows `native={true}` to fall back to the browser dropdown
+ * - Adds `data-purpose="dropdown"` for semantic parsing
+ *
+ * **Features:**
+ * - Same label/helper/error contract as `SelectField`
+ * - Controlled and uncontrolled modes supported
+ * - Prevents API drift between generic select and dropdown styling
  *
  * @example
  * ```tsx
- * import { DangerButton } from "@marwes-ui/react";
+ * <DropdownField
+ *   label="Country"
+ *   select={{
+ *     placeholder: "Choose a country",
+ *     options: [
+ *       { value: "se", label: "Sweden" },
+ *       { value: "us", label: "United States" },
+ *     ],
+ *   }}
+ * />
+ * ```
+ */
+declare function DropdownField(props: DropdownFieldProps): React.ReactElement;
+type SearchFieldProps = Omit<InputFieldProps, "input"> & {
+    /**
+     * Input-specific props (type is auto-set to "search")
+     */
+    input?: Omit<InputProps, "type">;
+};
+/**
+ * SearchField - For search inputs with an automatic search affordance and clear button.
+ *
+ * **AI Context:**
+ * - Sets `type="search"` automatically
+ * - Sets `inputMode="search"` for mobile keyboards
+ * - Shows a search icon by default and a clear button (X icon) when field has content
+ * - Adds `data-purpose="search"` for AI parsing
+ *
+ * **Features:**
+ * - Automatic clear button that appears when typing
+ * - Native search input behavior
+ * - Optimized mobile keyboard
+ * - Controlled and uncontrolled modes supported
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { SearchField } from "@marwes-ui/react";
  *
  * export function Example() {
- *   return <DangerButton onClick={deleteProject}>Delete Project</DangerButton>;
+ *   const [query, setQuery] = React.useState("");
+ *   return (
+ *     <SearchField
+ *       label="Search products"
+ *       input={{ value: query, onValueChange: setQuery }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+declare function SearchField(props: SearchFieldProps): React.ReactElement;
+type PasswordFieldProps = Omit<InputFieldProps, "input"> & {
+    /**
+     * Input-specific props (type is auto-set to "password")
+     */
+    input?: Omit<InputProps, "type">;
+    /**
+     * Autocomplete hint: "current-password" or "new-password"
+     * Defaults to "current-password"
+     */
+    autoComplete?: "current-password" | "new-password";
+};
+/**
+ * PasswordField - For password inputs with automatic show/hide toggle.
+ *
+ * **AI Context:**
+ * - Sets `type="password"` automatically (toggles to "text" when shown)
+ * - Shows eye/eyeOff icon toggle button
+ * - Sets appropriate `autoComplete` attribute
+ * - Adds `data-purpose="password"` for AI parsing
+ *
+ * **Features:**
+ * - Automatic show/hide toggle with eye icon
+ * - Proper autocomplete for password managers
+ * - Accessible toggle button with clear labels
+ * - Controlled and uncontrolled modes supported
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { PasswordField } from "@marwes-ui/react";
+ *
+ * export function Example() {
+ *   const [password, setPassword] = React.useState("");
+ *   return (
+ *     <PasswordField
+ *       label="Password"
+ *       input={{ value: password, onValueChange: setPassword }}
+ *     />
+ *   );
  * }
  * ```
+ *
+ * @example New password (signup/reset)
+ * ```tsx
+ * <PasswordField
+ *   label="New Password"
+ *   autoComplete="new-password"
+ *   helperText="Must be at least 8 characters"
+ * />
+ * ```
  */
-declare function DangerButton(props: DangerButtonProps): react_jsx_runtime.JSX.Element;
-type CreateButtonProps = Omit<ButtonProps, "action">;
+declare function PasswordField(props: PasswordFieldProps): React.ReactElement;
+type EmailFieldProps = Omit<InputFieldProps, "input"> & {
+    /**
+     * Input-specific props (type, inputMode, autoComplete auto-set)
+     */
+    input?: Omit<InputProps, "type" | "inputMode" | "autoComplete">;
+};
 /**
- * CreateButton - For creation actions like adding new items or entities.
+ * EmailField - For email address inputs with proper semantic attributes.
  *
  * **AI Context:**
- * - Sets `action="create"` to indicate creation behavior
- * - Uses primary tone by default
- * - Adds `data-creative="true"` for AI parsing
+ * - Sets `type="email"` for validation
+ * - Sets `inputMode="email"` for optimized mobile keyboard
+ * - Sets `autoComplete="email"` for autofill
+ * - Adds `data-purpose="email"` for AI parsing
+ *
+ * **Features:**
+ * - Browser email validation
+ * - Email-optimized mobile keyboard
+ * - Autofill support for email addresses
  *
  * @example
  * ```tsx
- * <CreateButton onClick={createProject}>
- *   New Project
- * </CreateButton>
+ * import { EmailField } from "@marwes-ui/react";
+ *
+ * <EmailField
+ *   label="Email address"
+ *   input={{ placeholder: "you@example.com" }}
+ * />
  * ```
  */
-declare function CreateButton(props: CreateButtonProps): react_jsx_runtime.JSX.Element;
-type SubmitButtonProps = Omit<ButtonProps, "action" | "as">;
+declare function EmailField(props: EmailFieldProps): React.ReactElement;
+type DateOfBirthFieldProps = Omit<InputFieldProps, "input"> & {
+    /**
+     * Input-specific props (type, inputMode, autoComplete auto-set)
+     */
+    input?: Omit<InputProps, "type" | "inputMode" | "autoComplete">;
+};
 /**
- * SubmitButton - For form submissions.
+ * DateOfBirthField - For birthday inputs with native date semantics.
  *
  * **AI Context:**
- * - Sets `action="submit"` and `type="submit"`
- * - Adds `data-context="form-submit"` for AI parsing
- * - Automatically uses button element (not anchor)
+ * - Sets `type="date"` for native browser date controls
+ * - Sets `autoComplete="bday"` for profile/password-manager autofill
+ * - Adds `data-purpose="date-of-birth"` for AI parsing
+ *
+ * **Features:**
+ * - Native date picker where the platform supports it
+ * - ISO value handling (`YYYY-MM-DD`) for predictable form state
+ * - Keeps the same label/helper/error contract as `InputField`
+ */
+declare function DateOfBirthField(props: DateOfBirthFieldProps): React.ReactElement;
+type ZipCodeFieldProps = Omit<InputFieldProps, "input"> & {
+    /**
+     * Input-specific props (type, inputMode, autoComplete auto-set)
+     */
+    input?: Omit<InputProps, "type" | "inputMode" | "autoComplete">;
+};
+/**
+ * ZipCodeField - For postal/ZIP code inputs that should keep text semantics.
+ *
+ * **AI Context:**
+ * - Sets `type="text"` to preserve leading zeros
+ * - Sets `inputMode="numeric"` for the mobile number keypad
+ * - Sets `autoComplete="postal-code"` for address autofill
+ * - Adds `data-purpose="zip-code"` for AI parsing
+ *
+ * **Features:**
+ * - Low-regret default for US ZIP and broader postal-code entry
+ * - Avoids number-input quirks like spinner UI and lost leading zeroes
+ * - Keeps the same label/helper/error contract as `InputField`
+ */
+declare function ZipCodeField(props: ZipCodeFieldProps): React.ReactElement;
+type PhoneFieldProps = Omit<InputFieldProps, "input"> & {
+    /**
+     * Input-specific props (type, inputMode, autoComplete auto-set)
+     */
+    input?: Omit<InputProps, "type" | "inputMode" | "autoComplete">;
+};
+/**
+ * PhoneField - For phone number inputs with proper semantic attributes.
+ *
+ * **AI Context:**
+ * - Sets `type="tel"` for telephone input
+ * - Sets `inputMode="tel"` for phone keyboard
+ * - Sets `autoComplete="tel"` for autofill
+ * - Adds `data-purpose="phone"` for AI parsing
+ *
+ * **Features:**
+ * - Phone-optimized mobile keyboard
+ * - Autofill support for phone numbers
+ * - Accepts any phone format (formatting should be done externally)
  *
  * @example
  * ```tsx
- * <SubmitButton>Submit</SubmitButton>
+ * import { PhoneField } from "@marwes-ui/react";
+ *
+ * <PhoneField
+ *   label="Phone number"
+ *   input={{ placeholder: "+1 (555) 000-0000" }}
+ * />
  * ```
  */
-declare function SubmitButton(props: SubmitButtonProps): react_jsx_runtime.JSX.Element;
-type CancelButtonProps = Omit<ButtonProps, "action">;
+declare function PhoneField(props: PhoneFieldProps): React.ReactElement;
+type URLFieldProps = Omit<InputFieldProps, "input"> & {
+    /**
+     * Input-specific props (type, inputMode, autoComplete auto-set)
+     */
+    input?: Omit<InputProps, "type" | "inputMode" | "autoComplete">;
+};
 /**
- * CancelButton - For cancel or reset actions.
+ * URLField - For URL inputs with proper semantic attributes.
  *
  * **AI Context:**
- * - Sets `action="cancel"` to indicate cancellation
- * - Uses secondary variant by default
- * - Adds `data-cancel="true"` for AI parsing
+ * - Sets `type="url"` for URL validation
+ * - Sets `inputMode="url"` for URL keyboard
+ * - Sets `autoComplete="url"` for autofill
+ * - Adds `data-purpose="url"` for AI parsing
+ *
+ * **Features:**
+ * - Browser URL validation
+ * - URL-optimized mobile keyboard
+ * - Autofill support for URLs
  *
  * @example
  * ```tsx
- * <CancelButton onClick={handleCancel}>
- *   Cancel
- * </CancelButton>
+ * import { URLField } from "@marwes-ui/react";
+ *
+ * <URLField
+ *   label="Website"
+ *   input={{ placeholder: "https://example.com" }}
+ * />
  * ```
  */
-declare function CancelButton(props: CancelButtonProps): react_jsx_runtime.JSX.Element;
-type LinkButtonProps = Omit<ButtonProps, "action" | "as"> & {
+declare function URLField(props: URLFieldProps): React.ReactElement;
+type CurrencyFieldProps = Omit<InputFieldProps, "input"> & {
     /**
-     * The URL to navigate to. Required for LinkButton.
+     * Input-specific props (type, inputMode auto-set)
      */
-    href: string;
+    input?: Omit<InputProps, "type" | "inputMode">;
+    /**
+     * Currency code (e.g., "USD", "EUR", "GBP").
+     * Prefer `CurrencyCode` for autocomplete and Storybook controls.
+     * Unknown strings are tolerated and simply render without a leading symbol.
+     */
+    currency?: CurrencyCode | string;
 };
 /**
- * LinkButton - For navigation actions that look like buttons.
+ * CurrencyField - For monetary amount inputs with currency context.
  *
  * **AI Context:**
- * - Sets `action="navigate"` to indicate navigation
- * - Uses anchor element with button styling
- * - Adds `data-navigation="true"` for AI parsing
+ * - Sets `type="text"` (better browser support than "number")
+ * - Sets `inputMode="decimal"` for numeric keyboard with decimal
+ * - Adds currency code to helper text if provided
+ * - Adds `data-purpose="currency"` and `data-currency` for AI parsing
  *
- * @example
- * ```tsx
- * <LinkButton href="/dashboard">
- *   Go to Dashboard
- * </LinkButton>
- * ```
- */
-declare function LinkButton(props: LinkButtonProps): react_jsx_runtime.JSX.Element;
-type PrimaryButtonProps = Omit<ButtonProps, "variant" | "as"> & {};
-/**
- * PrimaryButton - For general use when no specific semantic variant fits.
+ * **Features:**
+ * - Decimal keyboard on mobile
+ * - Currency code display in helper text
+ * - Better input control than type="number"
+ * - Sanitizes values passed through `input.onValueChange`
+ * - Note: Formatting should be handled by parent component
  *
- * @example
- * ```tsx
- * <PrimaryButton onClick={handlePrimaryAction}>
- *   Do something important
- * </PrimaryButton>
- * ```
- */
-declare function PrimaryButton(props: PrimaryButtonProps): react_jsx_runtime.JSX.Element;
-type SecondaryButtonProps = Omit<ButtonProps, "variant" | "as"> & {};
-/**
- * SecondaryButton - For general use when no specific semantic variant fits.
+ * **Controlled usage recommended:**
+ * - Use `input.value` + `input.onValueChange` when you need guaranteed sanitized state
+ * - In uncontrolled usage, the callback still receives sanitized values, but the DOM input may temporarily display unsanitized text
  *
  * @example
  * ```tsx
- * <SecondaryButton onClick={handleSecondaryAction}>
- *   Do something important
- * </SecondaryButton>
- * ```
- */
-declare function SecondaryButton(props: SecondaryButtonProps): react_jsx_runtime.JSX.Element;
-type TextButtonProps = Omit<ButtonProps, "variant" | "as"> & {};
-/**
- * TextButton - For general use when no specific semantic variant fits.
+ * import { CurrencyField } from "@marwes-ui/react";
  *
- * @example
- * ```tsx
- * <TextButton onClick={handleTextAction}>
- *   Do something important
- * </TextButton>
+ * <CurrencyField
+ *   label="Amount"
+ *   currency="USD"
+ *   input={{
+ *     value: amount,
+ *     onValueChange: setAmount,
+ *     placeholder: "0.00",
+ *   }}
+ * />
  * ```
  */
-declare function TextButton(props: TextButtonProps): react_jsx_runtime.JSX.Element;
-
-type InputProps = InputOptions & {
-    onValueChange?: (value: string) => void;
-    className?: string;
-};
-declare function Input(props: InputProps): react_jsx_runtime.JSX.Element;
+declare function CurrencyField(props: CurrencyFieldProps): React.ReactElement;
 
 type IconName = keyof typeof iconRegistry;
 type IconProps = {
     name: IconName;
     /**
-     * Token ("xs"|"sm"|"md"|"lg") or a raw px number.
+     * Icon scale token ("xs"|"sm"|"md"|"lg") or an explicit pixel size.
      * Defaults to system.theme.icon.size
      */
     size?: IconSize | number;
     /**
-     * Token ("xs"|"sm"|"md"|"lg") or a raw number.
+     * Stroke-width token ("xs"|"sm"|"md"|"lg") or an explicit numeric stroke width.
      * Defaults to system.theme.icon.strokeWidth
      */
     strokeWidth?: IconStrokeWidth | number;
@@ -214,7 +606,34 @@ type IconProps = {
 };
 declare function Icon({ name, size, strokeWidth, className, "aria-label": ariaLabel, decorative, }: IconProps): react_jsx_runtime.JSX.Element;
 
-declare function useRenderKitDebug(renderKit: unknown, componentName: string): void;
+interface AvatarProps extends AvatarOptions, Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> {
+    dataAttributes?: Record<string, string>;
+}
+declare function Avatar(props: AvatarProps): React.ReactElement;
+
+interface AvatarBadgeProps extends AvatarProps {
+    statusLabel?: string;
+}
+declare function AvatarBadge(props: AvatarBadgeProps): React.ReactElement;
+
+interface AvatarGroupItem extends Omit<AvatarProps, "size" | "className" | "style"> {
+    id?: string;
+}
+interface AvatarGroupProps extends Omit<React.HTMLAttributes<HTMLFieldSetElement>, "children"> {
+    items: AvatarGroupItem[];
+    overflowCount?: number;
+    overflowLabel?: string;
+    ariaLabel?: string;
+    dataAttributes?: Record<string, string>;
+}
+declare function AvatarGroup(props: AvatarGroupProps): React.ReactElement;
+
+type ProfileAvatarProps = AvatarProps;
+declare function ProfileAvatar(props: ProfileAvatarProps): React.ReactElement;
+type PresenceAvatarProps = AvatarBadgeProps;
+declare function PresenceAvatar(props: PresenceAvatarProps): React.ReactElement;
+type TeamAvatarGroupProps = AvatarGroupProps;
+declare function TeamAvatarGroup(props: TeamAvatarGroupProps): React.ReactElement;
 
 /**
  * React adapter for Marwes Checkbox.
@@ -299,12 +718,140 @@ type CheckboxProps = CheckboxProps$1 & {
  */
 declare function Checkbox(props: CheckboxProps): React.ReactElement;
 
+type CheckboxFieldProps = {
+    /** Optional: if omitted, we generate one via useId(). */
+    id?: string;
+    /** Field content (rendered by adapter). */
+    label: React.ReactNode;
+    description?: React.ReactNode;
+    error?: React.ReactNode;
+    /** Props forwarded to the Checkbox atom. */
+    checkbox: CheckboxProps;
+    /** Additional aria-describedby IDs to merge with internal description/error IDs. */
+    ariaDescribedBy?: string;
+};
+/**
+ * CheckboxField (Molecule) — Recommended
+ *
+ * A convenient, accessible wrapper around `Checkbox` that provides:
+ * - a clickable `<label>` wired via `htmlFor`/`id`
+ * - optional `description` and `error` regions
+ * - automatic `aria-describedby` wiring (description + error + any external ids)
+ * - automatic invalid state when `error` is present
+ *
+ * Use `CheckboxField` for most forms. Use `Checkbox` directly only when you need
+ * a highly custom layout (tables, list rows, compound list items, etc.).
+ *
+ * Accessibility
+ * - Generates a stable `id` via `useId()` when `id` is not provided.
+ * - Always renders a real `<label>` element connected to the checkbox control.
+ * - When `description` and/or `error` are present, it sets `aria-describedby`
+ *   on the checkbox to reference their ids.
+ * - When `error` is present, the checkbox is marked invalid (aria-invalid via core).
+ *
+ * @example Minimal (recommended)
+ * ```tsx
+ * <CheckboxField
+ *   label="Subscribe to updates"
+ *   checkbox={{ defaultChecked: true }}
+ * />
+ * ```
+ *
+ * @example With description
+ * ```tsx
+ * <CheckboxField
+ *   label="Subscribe to updates"
+ *   description="We'll only email you about important product changes."
+ *   checkbox={{}}
+ * />
+ * ```
+ *
+ * @example With error (invalid state)
+ * ```tsx
+ * <CheckboxField
+ *   label="Accept terms"
+ *   error="You must accept the terms to continue."
+ *   checkbox={{ required: true }}
+ * />
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [checked, setChecked] = React.useState(false);
+ *
+ * <CheckboxField
+ *   label="Accept terms"
+ *   checkbox={{
+ *     checked,
+ *     onCheckedChange: setChecked,
+ *   }}
+ * />
+ * ```
+ *
+ * @example Indeterminate (mixed)
+ * ```tsx
+ * const [checked, setChecked] = React.useState(false);
+ * const [mixed, setMixed] = React.useState(true);
+ *
+ * <CheckboxField
+ *   label="Select all"
+ *   description="Applies to all items in the current view."
+ *   checkbox={{
+ *     checked,
+ *     indeterminate: mixed,
+ *     onCheckedChange: (next) => {
+ *       setMixed(false);
+ *       setChecked(next);
+ *     },
+ *   }}
+ * />
+ * ```
+ *
+ * @example Custom describedBy (merge with internal description/error)
+ * ```tsx
+ * <CheckboxField
+ *   ariaDescribedBy="my-extra-help"
+ *   label="Enable telemetry"
+ *   description="Helps us improve the product."
+ *   checkbox={{}}
+ * />
+ *
+ * <div id="my-extra-help">This setting can be changed later.</div>
+ * ```
+ */
+declare function CheckboxField(props: CheckboxFieldProps): React.ReactElement;
+
+interface CheckboxGroupFieldOption {
+    value: string;
+    label: React.ReactNode;
+    disabled?: boolean;
+    indeterminate?: boolean;
+}
+type CheckboxGroupFieldCheckboxProps = Omit<CheckboxProps, "ariaDescribedBy" | "ariaLabel" | "ariaLabelledBy" | "checked" | "defaultChecked" | "disabled" | "id" | "indeterminate" | "invalid" | "name" | "onChange" | "onCheckedChange" | "required" | "value">;
+interface CheckboxGroupFieldProps {
+    label: React.ReactNode;
+    options: CheckboxGroupFieldOption[];
+    description?: React.ReactNode;
+    error?: React.ReactNode;
+    value?: string[];
+    onChange?: (value: string[]) => void;
+    defaultValue?: string[];
+    checkbox?: CheckboxGroupFieldCheckboxProps;
+    disabled?: boolean;
+    required?: boolean;
+    name?: string;
+    id?: string;
+    ariaDescribedBy?: string;
+    dataAttributes?: Record<string, string>;
+}
+declare function CheckboxGroupField(props: CheckboxGroupFieldProps): React.ReactElement;
+
 /**
  * React adapter for Marwes Divider component.
  * - Renders semantic <hr> using the core divider recipe.
  * - Supports 7 size variants: xxs/xs/sm/md/lg/xl/xxl.
  * - Supports horizontal and vertical orientation.
- * - Figma reference: node-id=1-932
+ * - Figma reference: component 1574:21053
  */
 
 type DividerProps = DividerOptions & Omit<React.HTMLAttributes<HTMLHRElement>, "children"> & {
@@ -355,23 +902,144 @@ type DividerProps = DividerOptions & Omit<React.HTMLAttributes<HTMLHRElement>, "
  * </div>
  * ```
  *
- * @example With custom ID
+ * @example With custom ID
+ * ```tsx
+ * <Divider id="section-break" />
+ * ```
+ */
+declare const Divider: React.ForwardRefExoticComponent<DividerOptions & Omit<React.HTMLAttributes<HTMLHRElement>, "children"> & {
+    /**
+     * Size variant for the divider.
+     * Maps to pixel values: xxs=1px, xs=8px, sm=16px, md=32px, lg=48px, xl=64px, xxl=80px
+     * @default "md"
+     */
+    size?: DividerSize;
+    /**
+     * Orientation of the divider.
+     * @default "horizontal"
+     */
+    orientation?: DividerOrientation;
+    /**
+     * Additional CSS class names.
+     */
+    className?: string;
+    /**
+     * Inline styles.
+     */
+    style?: React.CSSProperties;
+} & React.RefAttributes<HTMLHRElement>>;
+
+interface SpinnerProps extends SpinnerOptions, Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> {
+    dataAttributes?: Record<string, string>;
+}
+declare function Spinner(props: SpinnerProps): React.ReactElement;
+
+type ButtonSpinnerProps = SpinnerProps & {
+    inverted?: boolean;
+};
+declare function ButtonSpinner(props: ButtonSpinnerProps): React.ReactElement;
+type EmptyStateSpinnerProps = SpinnerProps;
+declare function EmptyStateSpinner(props: EmptyStateSpinnerProps): React.ReactElement;
+
+/**
+ * React adapter for Marwes Spacing component.
+ * - Renders a decorative, aria-hidden div using the core spacing recipe.
+ * - Inserts a fixed vertical gap driven by the --mw-spacing-* token scale.
+ */
+
+type SpacingProps = SpacingOptions & Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
+    /**
+     * Size variant for the spacing.
+     * Maps to token values: sp-0=0px, sp-2=2px, sp-4=4px, sp-8=8px,
+     * sp-16=16px, sp-24=24px, sp-32=32px, up to sp-120=120px.
+     * @default "sp-24"
+     */
+    size?: SpacingSize;
+    /**
+     * Ergonomic alias for `size`.
+     * Prefer this on `Spacer` for readable layout code.
+     */
+    spacing?: SpacingSize;
+    /**
+     * Additional CSS class names.
+     */
+    className?: string;
+    /**
+     * Inline styles.
+     */
+    style?: React.CSSProperties;
+};
+type SpacerProps = SpacingProps;
+/**
+ * Spacing
+ *
+ * Pure layout primitive that inserts a fixed vertical gap between elements.
+ * Driven by the design token scale — no magic numbers required.
+ *
+ * @example Basic usage (24px gap)
+ * ```tsx
+ * <Spacing />
+ * ```
+ *
+ * @example Semantic size
+ * ```tsx
+ * <H1>Hello</H1>
+ * <Spacing size={Spacings.sp24} />
+ * <Paragraph>World</Paragraph>
+ * ```
+ *
+ * @example All sizes
+ * ```tsx
+ * <Spacing size="sp-2" />  // 2px
+ * <Spacing size="sp-8" />  // 8px
+ * <Spacing size="sp-32" /> // 32px
+ * ```
+ */
+declare const Spacing: React.ForwardRefExoticComponent<SpacingOptions & Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
+    /**
+     * Size variant for the spacing.
+     * Maps to token values: sp-0=0px, sp-2=2px, sp-4=4px, sp-8=8px,
+     * sp-16=16px, sp-24=24px, sp-32=32px, up to sp-120=120px.
+     * @default "sp-24"
+     */
+    size?: SpacingSize;
+    /**
+     * Ergonomic alias for `size`.
+     * Prefer this on `Spacer` for readable layout code.
+     */
+    spacing?: SpacingSize;
+    /**
+     * Additional CSS class names.
+     */
+    className?: string;
+    /**
+     * Inline styles.
+     */
+    style?: React.CSSProperties;
+} & React.RefAttributes<HTMLDivElement>>;
+/**
+ * Spacer
+ *
+ * Alias for `Spacing` with a layout-oriented prop name.
+ *
+ * @example
  * ```tsx
- * <Divider id="section-break" />
+ * <Spacer spacing={Spacings.sp24} />
  * ```
  */
-declare const Divider: React.ForwardRefExoticComponent<DividerOptions & Omit<React.HTMLAttributes<HTMLHRElement>, "children"> & {
+declare const Spacer: React.ForwardRefExoticComponent<SpacingOptions & Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
     /**
-     * Size variant for the divider.
-     * Maps to pixel values: xxs=1px, xs=8px, sm=16px, md=32px, lg=48px, xl=64px, xxl=80px
-     * @default "md"
+     * Size variant for the spacing.
+     * Maps to token values: sp-0=0px, sp-2=2px, sp-4=4px, sp-8=8px,
+     * sp-16=16px, sp-24=24px, sp-32=32px, up to sp-120=120px.
+     * @default "sp-24"
      */
-    size?: DividerSize;
+    size?: SpacingSize;
     /**
-     * Orientation of the divider.
-     * @default "horizontal"
+     * Ergonomic alias for `size`.
+     * Prefer this on `Spacer` for readable layout code.
      */
-    orientation?: DividerOrientation;
+    spacing?: SpacingSize;
     /**
      * Additional CSS class names.
      */
@@ -380,7 +1048,7 @@ declare const Divider: React.ForwardRefExoticComponent<DividerOptions & Omit<Rea
      * Inline styles.
      */
     style?: React.CSSProperties;
-} & React.RefAttributes<HTMLHRElement>>;
+} & React.RefAttributes<HTMLDivElement>>;
 
 /**
  * React adapter for Marwes H1 component.
@@ -568,442 +1236,883 @@ type ParagraphProps = ParagraphOptions & {
  */
 declare function Paragraph(props: ParagraphProps): React.ReactElement;
 
-type CheckboxFieldProps = {
-    /** Optional: if omitted, we generate one via useId(). */
+interface CardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+    /** Optional title rendered above the body content */
+    title?: React.ReactNode;
+    /** Card body content */
+    children?: React.ReactNode;
+    /** Data attributes for AI-friendly metadata (used by purpose variants). */
+    dataAttributes?: Record<string, string>;
+}
+declare function Card(props: CardProps): React.ReactElement;
+
+type ProductCardProps = CardProps;
+declare function ProductCard(props: ProductCardProps): React.ReactElement;
+type ProfileCardProps = CardProps;
+declare function ProfileCard(props: ProfileCardProps): React.ReactElement;
+type StatCardProps = CardProps;
+declare function StatCard(props: StatCardProps): React.ReactElement;
+
+interface ToastProps extends ToastOptions {
+    /** Main notification message */
+    children: React.ReactNode;
+    /** Icon element shown on the left (e.g. an <Icon> component) */
+    icon?: React.ReactNode;
+    /** Action element shown inline after the message (e.g. a text action or <a>) */
+    action?: React.ReactNode;
+    /** When provided, renders a dismiss (×) button and calls this on click */
+    onDismiss?: () => void;
+    className?: string;
     id?: string;
-    /** Field content (rendered by adapter). */
-    label: React.ReactNode;
-    description?: React.ReactNode;
-    error?: React.ReactNode;
-    /** Props forwarded to the Checkbox atom. */
-    checkbox: CheckboxProps;
-    /** Additional aria-describedby IDs to merge with internal description/error IDs. */
-    ariaDescribedBy?: string;
-};
+    dataAttributes?: Record<string, string>;
+}
+declare function Toast(props: ToastProps): React.ReactElement;
+
+interface ManagedToast {
+    id: string;
+    children: React.ReactNode;
+    icon?: React.ReactNode;
+    action?: React.ReactNode;
+    onDismiss?: () => void;
+    className?: string;
+    variant?: ToastVariant;
+    ariaLive?: "polite" | "assertive";
+    intent?: ToastIntent;
+    duration?: number | null;
+    dataAttributes?: Record<string, string>;
+}
+type ShowToastOptions = Omit<ManagedToast, "id">;
+interface ToastContainerProps {
+    toasts: ManagedToast[];
+    placement?: ToastPlacement;
+    maxVisible?: number;
+    className?: string;
+    onDismiss?: (id: string) => void;
+}
+interface ToastProviderProps {
+    children: React.ReactNode;
+    placement?: ToastPlacement;
+    maxVisible?: number;
+    defaultDuration?: number | null;
+    className?: string;
+}
+interface ToastController {
+    show: (toast: ShowToastOptions) => string;
+    dismiss: (id: string) => void;
+    clear: () => void;
+}
+
+declare function ToastContainer(props: ToastContainerProps): React.ReactElement;
+
+declare function ToastProvider(props: ToastProviderProps): React.ReactElement;
+declare function useToast(): ToastController;
+
+type SuccessToastProps = ToastProps;
+declare function SuccessToast(props: SuccessToastProps): React.ReactElement;
+type ErrorToastProps = ToastProps;
+declare function ErrorToast(props: ErrorToastProps): React.ReactElement;
+type WarningToastProps = ToastProps;
+declare function WarningToast(props: WarningToastProps): React.ReactElement;
+type InfoToastProps = ToastProps;
+declare function InfoToast(props: InfoToastProps): React.ReactElement;
+
+interface TooltipProps extends TooltipOptions, Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> {
+    children: React.ReactNode;
+    dataAttributes?: Record<string, string>;
+}
+declare function Tooltip(props: TooltipProps): React.ReactElement;
+
+interface TooltipGroupProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "content"> {
+    content: React.ReactNode;
+    icon?: IconNameType;
+    triggerLabel?: string;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    tooltipId?: string;
+    tooltipClassName?: string;
+    triggerClassName?: string;
+    dataAttributes?: Record<string, string>;
+}
+declare function TooltipGroup(props: TooltipGroupProps): React.ReactElement;
+
 /**
- * CheckboxField (Molecule) — Recommended
+ * React adapter for Marwes Accordion.
+ * - Renders a compound structure: wrapper div > trigger button + panel div.
+ * - id is optional; falls back to React.useId() for aria wiring.
+ */
+
+interface AccordionProps {
+    /** Unique id for aria wiring. Defaults to React.useId() when omitted. */
+    id?: string;
+    open?: boolean;
+    disabled?: boolean;
+    /** Content of the trigger button header */
+    title: React.ReactNode;
+    /** Content shown in the collapsible panel */
+    children: React.ReactNode;
+    className?: string;
+    /** Called when the trigger is clicked */
+    onToggle?: () => void;
+}
+declare function Accordion(props: AccordionProps): React.ReactElement;
+
+/**
+ * AccordionField (Molecule) — Recommended
  *
- * A convenient, accessible wrapper around `Checkbox` that provides:
- * - a clickable `<label>` wired via `htmlFor`/`id`
- * - optional `description` and `error` regions
- * - automatic `aria-describedby` wiring (description + error + any external ids)
- * - automatic invalid state when `error` is present
+ * An accessible accordion group with field semantics: group label, optional
+ * description, optional error, and coordinated open-state management.
  *
- * Use `CheckboxField` for most forms. Use `Checkbox` directly only when you need
- * a highly custom layout (tables, list rows, compound list items, etc.).
+ * Composes `Accordion` atoms into a `role="group"` container with:
+ * - a visible label wired via `aria-labelledby`
+ * - optional `description` and `error` regions
+ * - automatic `aria-describedby` wiring (description + error + external IDs)
+ * - automatic `aria-invalid` when `error` is present
+ * - controlled (`openItems` + `onOpenItemsChange`) or uncontrolled (`defaultOpenItems`) state
+ * - single-open (`multiple=false`, default) or multi-open (`multiple=true`) behaviour
  *
- * Accessibility
- * - Generates a stable `id` via `useId()` when `id` is not provided.
- * - Always renders a real `<label>` element connected to the checkbox control.
- * - When `description` and/or `error` are present, it sets `aria-describedby`
- *   on the checkbox to reference their ids.
- * - When `error` is present, the checkbox is marked invalid (aria-invalid via core).
+ * Use `AccordionField` for most accordion groups. Use `Accordion` directly only
+ * when you need a standalone collapsible panel outside of group semantics.
  *
- * @example Minimal (recommended)
+ * @example Basic (uncontrolled, single-open)
  * ```tsx
- * <CheckboxField
- *   label="Subscribe to updates"
- *   checkbox={{ defaultChecked: true }}
+ * <AccordionField
+ *   label="FAQ"
+ *   items={[
+ *     { value: "q1", title: "What is Marwes?", content: <p>A design system.</p> },
+ *     { value: "q2", title: "Is it free?", content: <p>Yes.</p> },
+ *   ]}
+ *   defaultOpenItems={["q1"]}
  * />
  * ```
  *
- * @example With description
+ * @example Multi-open, controlled
  * ```tsx
- * <CheckboxField
- *   label="Subscribe to updates"
- *   description="We'll only email you about important product changes."
- *   checkbox={{}}
+ * const [open, setOpen] = React.useState<string[]>([]);
+ *
+ * <AccordionField
+ *   label="Settings"
+ *   items={settingsItems}
+ *   openItems={open}
+ *   onOpenItemsChange={setOpen}
+ *   multiple
  * />
  * ```
+ */
+
+interface AccordionFieldItem {
+    value: string;
+    title: React.ReactNode;
+    content?: React.ReactNode;
+    /** @deprecated Use `content` instead for cross-framework parity. */
+    children?: React.ReactNode;
+    disabled?: boolean;
+}
+interface AccordionFieldProps {
+    /** Visible label for the accordion group. */
+    label: React.ReactNode;
+    /** Optional description text below the label. */
+    description?: React.ReactNode;
+    /** Error message. When present, sets aria-invalid on the group. */
+    error?: React.ReactNode;
+    /** Accordion items to render. */
+    items: AccordionFieldItem[];
+    /** Allow multiple items open simultaneously. Defaults to `true`. */
+    multiple?: boolean;
+    /** Controlled: currently open item values. */
+    openItems?: string[];
+    /** Controlled: called with the new open-items array when state changes. */
+    onOpenItemsChange?: (openItems: string[]) => void;
+    /** Uncontrolled: initially open item values. */
+    defaultOpenItems?: string[];
+    /** Disables all accordion items. */
+    disabled?: boolean;
+    /** Explicit ID. If omitted, generated via useId(). */
+    id?: string;
+    /** Additional aria-describedby IDs to merge with internal description/error IDs. */
+    ariaDescribedBy?: string;
+    /** Data attributes for AI-friendly metadata (used by context variants). */
+    dataAttributes?: Record<string, string>;
+}
+declare function AccordionField(props: AccordionFieldProps): React.ReactElement;
+
+/**
+ * Purpose Components — Accordion
  *
- * @example With error (invalid state)
- * ```tsx
- * <CheckboxField
- *   label="Accept terms"
- *   error="You must accept the terms to continue."
- *   checkbox={{ required: true }}
- * />
- * ```
+ * Pre-configured accordion compositions that encode a specific semantic purpose.
+ * Each sets `data-purpose` for machine-readable intent while keeping the
+ * visual `variant` prop for presentation only.
+ */
+type FAQAccordionProps = Omit<AccordionFieldProps, "multiple">;
+/**
+ * FAQAccordion - For question-and-answer sections.
  *
- * @example Controlled
+ * **AI Context:**
+ * - Enforces single-open behaviour (opening one closes others)
+ * - Adds `data-purpose="faq"` for AI parsing
+ * - Ideal for FAQ pages, help sections, knowledge bases
+ *
+ * @example
  * ```tsx
- * const [checked, setChecked] = React.useState(false);
+ * import { FAQAccordion } from "@marwes-ui/react";
  *
- * <CheckboxField
- *   label="Accept terms"
- *   checkbox={{
- *     checked,
- *     onCheckedChange: setChecked,
- *   }}
- * />
+ * export function Example() {
+ *   return (
+ *     <FAQAccordion
+ *       label="Frequently Asked Questions"
+ *       items={[
+ *         { value: "q1", title: "What is Marwes?", content: <p>A design system.</p> },
+ *         { value: "q2", title: "Is it free?", content: <p>Yes.</p> },
+ *       ]}
+ *       defaultOpenItems={["q1"]}
+ *     />
+ *   );
+ * }
  * ```
+ */
+declare function FAQAccordion(props: FAQAccordionProps): React.ReactElement;
+type SettingsAccordionProps = Omit<AccordionFieldProps, "multiple">;
+/**
+ * SettingsAccordion - For configuration and settings panels.
  *
- * @example Indeterminate (mixed)
+ * **AI Context:**
+ * - Enforces multi-open behaviour (multiple sections open simultaneously)
+ * - Adds `data-purpose="settings"` for AI parsing
+ * - Ideal for preferences, admin panels, configuration forms
+ *
+ * @example
  * ```tsx
- * const [checked, setChecked] = React.useState(false);
- * const [mixed, setMixed] = React.useState(true);
+ * import { SettingsAccordion } from "@marwes-ui/react";
  *
- * <CheckboxField
- *   label="Select all"
- *   description="Applies to all items in the current view."
- *   checkbox={{
- *     checked,
- *     indeterminate: mixed,
- *     onCheckedChange: (next) => {
- *       setMixed(false);
- *       setChecked(next);
- *     },
- *   }}
- * />
+ * export function Example() {
+ *   return (
+ *     <SettingsAccordion
+ *       label="Account Settings"
+ *       items={[
+ *         { value: "profile", title: "Profile", content: <ProfileForm /> },
+ *         { value: "notifications", title: "Notifications", content: <NotificationsForm /> },
+ *         { value: "privacy", title: "Privacy", content: <PrivacyForm /> },
+ *       ]}
+ *     />
+ *   );
+ * }
  * ```
+ */
+declare function SettingsAccordion(props: SettingsAccordionProps): React.ReactElement;
+type SectionsAccordionProps = AccordionFieldProps;
+/**
+ * SectionsAccordion - For generic collapsible content sections.
  *
- * @example Custom describedBy (merge with internal description/error)
+ * **AI Context:**
+ * - Same API as `AccordionField` with `data-purpose="sections"` for AI parsing
+ * - Defaults to multi-open but can be overridden with `multiple={false}`
+ * - Use when no more specific purpose component fits
+ * - Documentation, product details, order breakdowns
+ *
+ * @example
  * ```tsx
- * <CheckboxField
- *   ariaDescribedBy="my-extra-help"
- *   label="Enable telemetry"
- *   description="Helps us improve the product."
- *   checkbox={{}}
- * />
+ * import { SectionsAccordion } from "@marwes-ui/react";
  *
- * <div id="my-extra-help">This setting can be changed later.</div>
+ * export function Example() {
+ *   return (
+ *     <SectionsAccordion
+ *       label="Product Details"
+ *       items={[
+ *         { value: "desc", title: "Description", content: <p>Full description.</p> },
+ *         { value: "specs", title: "Specifications", content: <SpecsTable /> },
+ *         { value: "reviews", title: "Reviews", content: <ReviewsList /> },
+ *       ]}
+ *     />
+ *   );
+ * }
  * ```
  */
-declare function CheckboxField(props: CheckboxFieldProps): React.ReactElement;
+declare function SectionsAccordion(props: SectionsAccordionProps): React.ReactElement;
 
-type InputFieldProps = {
-    /** Optional: if omitted, we generate one via useId(). */
-    id?: string;
-    /** Field label (required for accessibility). */
-    label: string;
-    /** Optional helper text shown below the input. */
-    helperText?: string;
-    /** Optional error message. When present, input is marked invalid. */
-    error?: string;
-    /** Props forwarded to the Input atom. */
-    input: InputProps;
-    /** Additional aria-describedby IDs to merge with internal helper/error IDs. */
-    ariaDescribedBy?: string;
+/**
+ * React adapter for Marwes Radio.
+ * - Renders a native <input type="radio"> using the core render kit.
+ * - Applies strict a11y fields and modifier classes.
+ */
+
+type RadioProps = RadioOptions & {
+    /**
+     * Called with the next checked value when the user selects this radio.
+     * In a group, only the newly selected radio fires `true`.
+     */
+    onCheckedChange?: (checked: boolean) => void;
+    /** Raw event access escape hatch. */
+    onChange?: React.ChangeEventHandler<HTMLInputElement>;
 };
 /**
- * InputField (Molecule) — Recommended
- *
- * A convenient, accessible wrapper around `Input` that provides:
- * - a visible `<label>` wired via `htmlFor`/`id`
- * - optional `helperText` and `error` regions
- * - automatic `aria-describedby` wiring (helperText + error + any external ids)
- * - automatic invalid state when `error` is present
+ * Radio (Atom)
  *
- * Use `InputField` for most forms. Use `Input` directly only when you need
- * a highly custom layout or composite inputs.
+ * Low-level radio control built on a native `<input type="radio">`.
+ * Use this when you need custom layout or when the label/grouping is handled
+ * elsewhere (e.g. inside a list item, table row, or custom field wrapper).
  *
- * Accessibility
- * - Generates a stable `id` via `useId()` when `id` is not provided.
- * - Always renders a visible `<label>` element connected to the input control.
- * - When `helperText` and/or `error` are present, it sets `aria-describedby`
- *   on the input to reference their ids.
- * - When `error` is present, the input is marked invalid (aria-invalid).
- * - Error region has `aria-live="polite"` for screen reader announcements.
+ * For most forms, prefer `RadioGroupField`, which composes `Radio` with
+ * group label/description/error wiring, selection state, and consistent spacing.
  *
- * @example Minimal (recommended)
- * ```tsx
- * <InputField
- *   label="Email address"
- *   input={{ type: "email", placeholder: "you@example.com" }}
- * />
- * ```
+ * **AI Context:**
+ * - Renders a native `<input type="radio">` using the core `radioRecipe`
+ * - Applies strict a11y attributes: `aria-label`, `aria-labelledby`, `aria-describedby`, `aria-invalid`
+ * - Supports controlled (`checked` + `onCheckedChange`) and uncontrolled (`defaultChecked`) modes
+ * - Modifier classes: `mw-radio`, `mw-radio--disabled`, `mw-radio--invalid`
+ *
+ * Accessibility:
+ * - Provide **either** `ariaLabel` **or** `ariaLabelledBy` (or wrap with a `<label htmlFor>`).
+ * - Use the same `name` attribute on all radios in a group for native keyboard navigation.
+ * - Use `ariaDescribedBy` to connect supporting text (help/error).
  *
- * @example With helper text
+ * @example Basic (uncontrolled)
  * ```tsx
- * <InputField
- *   label="Username"
- *   helperText="Choose a unique username between 3-20 characters."
- *   input={{ type: "text", placeholder: "johnsmith" }}
- * />
+ * <Radio ariaLabel="Option A" name="preference" defaultChecked />
  * ```
  *
- * @example With error (invalid state)
+ * @example Controlled
  * ```tsx
- * <InputField
- *   label="Password"
- *   error="Password must be at least 8 characters."
- *   input={{ type: "password", required: true }}
+ * const [selected, setSelected] = React.useState("a");
+ *
+ * <Radio
+ *   name="color"
+ *   value="a"
+ *   checked={selected === "a"}
+ *   onCheckedChange={(checked) => { if (checked) setSelected("a"); }}
+ *   ariaLabel="Red"
  * />
  * ```
  *
- * @example Controlled
+ * @example With external label
  * ```tsx
- * const [email, setEmail] = React.useState("");
+ * const id = "opt-1";
  *
- * <InputField
- *   label="Email"
- *   input={{
- *     type: "email",
- *     value: email,
- *     onValueChange: setEmail,
- *   }}
- * />
+ * <div style={{ display: "flex", alignItems: "center", gap: 8 }}>
+ *   <Radio id={id} name="group" value="a" />
+ *   <label htmlFor={id}>Option A</label>
+ * </div>
  * ```
  *
- * @example Disabled
+ * @example In a group (manual)
  * ```tsx
- * <InputField
- *   label="Account ID"
- *   helperText="This value cannot be changed."
- *   input={{ value: "ACC-12345", disabled: true }}
- * />
+ * const [selected, setSelected] = React.useState("a");
+ * const options = [
+ *   { value: "a", label: "Option A" },
+ *   { value: "b", label: "Option B" },
+ * ];
+ *
+ * <div role="radiogroup" aria-label="Preference">
+ *   {options.map(({ value, label }) => (
+ *     <label key={value}>
+ *       <Radio
+ *         name="preference"
+ *         value={value}
+ *         checked={selected === value}
+ *         onCheckedChange={(checked) => { if (checked) setSelected(value); }}
+ *       />
+ *       {label}
+ *     </label>
+ *   ))}
+ * </div>
  * ```
+ */
+declare function Radio(props: RadioProps): React.ReactElement;
+
+/**
+ * RadioGroupField (Molecule) — Recommended
  *
- * @example Read-only
+ * An accessible radio group with field semantics: group label, optional
+ * description, optional error, and selection state management.
+ *
+ * Composes `Radio` atoms into a `role="radiogroup"` container with:
+ * - a visible label wired via `aria-labelledby`
+ * - optional `description` and `error` regions
+ * - automatic `aria-describedby` wiring (description + error + external IDs)
+ * - automatic `aria-invalid` when `error` is present
+ * - controlled (`value` + `onChange`) or uncontrolled (`defaultValue`) state
+ *
+ * Use `RadioGroupField` for most forms. Use `Radio` directly only when you
+ * need a highly custom layout (tables, list rows, compound list items, etc.).
+ *
+ * **AI Context:**
+ * - Renders `role="radiogroup"` with proper ARIA wiring
+ * - Manages selection state for child Radio atoms
+ * - All child radios share the same `name` for native keyboard navigation
+ * - Supports both controlled and uncontrolled patterns
+ *
+ * @example Basic (uncontrolled)
  * ```tsx
- * <InputField
- *   label="Account created"
- *   input={{ value: "January 15, 2026", readOnly: true }}
+ * <RadioGroupField
+ *   name="color"
+ *   label="Favorite color"
+ *   options={[
+ *     { value: "red", label: "Red" },
+ *     { value: "blue", label: "Blue" },
+ *     { value: "green", label: "Green" },
+ *   ]}
+ *   defaultValue="red"
  * />
  * ```
- *
- * @example Custom describedBy (merge with internal helper/error)
- * ```tsx
- * <InputField
- *   ariaDescribedBy="my-extra-help"
- *   label="API Key"
- *   helperText="Your key is stored securely."
- *   input={{ type: "password" }}
+ *
+ * @example Controlled
+ * ```tsx
+ * const [color, setColor] = React.useState("red");
+ *
+ * <RadioGroupField
+ *   name="color"
+ *   label="Favorite color"
+ *   options={[
+ *     { value: "red", label: "Red" },
+ *     { value: "blue", label: "Blue" },
+ *   ]}
+ *   value={color}
+ *   onChange={setColor}
  * />
+ * ```
  *
- * <div id="my-extra-help">This can be regenerated from your settings.</div>
+ * @example With description and error
+ * ```tsx
+ * <RadioGroupField
+ *   name="plan"
+ *   label="Select a plan"
+ *   description="Choose the plan that best fits your needs."
+ *   error="Please select a plan to continue."
+ *   options={[
+ *     { value: "free", label: "Free" },
+ *     { value: "pro", label: "Pro" },
+ *   ]}
+ * />
  * ```
  */
-declare function InputField(props: InputFieldProps): React.ReactElement;
+
+interface RadioGroupFieldOption {
+    value: string;
+    label: React.ReactNode;
+    disabled?: boolean;
+}
+interface RadioGroupFieldProps {
+    /** Shared name for all radio inputs in the group. */
+    name: string;
+    /** Visible label for the radio group. */
+    label: React.ReactNode;
+    /** Optional description text below the label. */
+    description?: React.ReactNode;
+    /** Error message. When present, sets aria-invalid on the group. */
+    error?: React.ReactNode;
+    /** Controlled: current selected value. */
+    value?: string;
+    /** Controlled: called with the new value when selection changes. */
+    onChange?: (value: string) => void;
+    /** Uncontrolled: initial selected value. */
+    defaultValue?: string;
+    /** Radio options to render. */
+    options: RadioGroupFieldOption[];
+    /** Disables all radio inputs in the group. */
+    disabled?: boolean;
+    /** Marks the group as required. */
+    required?: boolean;
+    /** Explicit ID. If omitted, generated via useId(). */
+    id?: string;
+    /** Additional aria-describedby IDs to merge with internal description/error IDs. */
+    ariaDescribedBy?: string;
+    /** Data attributes for AI-friendly metadata (used by context variants). */
+    dataAttributes?: Record<string, string>;
+}
+declare function RadioGroupField(props: RadioGroupFieldProps): React.ReactElement;
 
 /**
- * Field Variants - AI-Friendly Components
- *
- * These variants encode best practices and automatically set AI-friendly
- * metadata, making it easier for both developers and AI tools to understand
- * the purpose and behavior of each field.
+ * Purpose Components — Radio Group
  *
- * Each variant manages its own purpose-specific logic (password toggle,
- * search clear, etc.) and sets appropriate semantic attributes.
+ * Pre-configured radio group compositions that encode a specific semantic purpose.
+ * Each sets `data-purpose` for machine-readable intent while keeping the
+ * visual `variant` prop for presentation only.
  */
-type SearchFieldProps = Omit<InputFieldProps, "input"> & {
-    /**
-     * Input-specific props (type is auto-set to "search")
-     */
-    input?: Omit<InputProps, "type">;
+type YesNoRadioGroupProps = Omit<RadioGroupFieldProps, "options"> & {
+    /** Label for the "Yes" option. Defaults to "Yes". */
+    yesLabel?: React.ReactNode;
+    /** Label for the "No" option. Defaults to "No". */
+    noLabel?: React.ReactNode;
 };
 /**
- * SearchField - For search inputs with automatic clear button functionality.
+ * YesNoRadioGroup - For binary yes/no choices.
  *
  * **AI Context:**
- * - Sets `type="search"` automatically
- * - Sets `inputMode="search"` for mobile keyboards
- * - Shows clear button (X icon) when field has content
- * - Adds `data-purpose="search"` for AI parsing
- *
- * **Features:**
- * - Automatic clear button that appears when typing
- * - Native search input behavior
- * - Optimized mobile keyboard
- * - Controlled and uncontrolled modes supported
+ * - Pre-built options with values `"yes"` and `"no"`
+ * - Adds `data-purpose="binary-choice"` for AI parsing
+ * - Labels customizable via `yesLabel` / `noLabel`
  *
- * @example Basic usage
+ * @example
  * ```tsx
- * import { SearchField } from "@marwes-ui/react";
+ * import { YesNoRadioGroup } from "@marwes-ui/react";
  *
  * export function Example() {
- *   const [query, setQuery] = React.useState("");
  *   return (
- *     <SearchField
- *       label="Search products"
- *       input={{ value: query, onValueChange: setQuery }}
+ *     <YesNoRadioGroup
+ *       name="accept-terms"
+ *       label="Do you accept the terms?"
+ *       defaultValue="no"
  *     />
  *   );
  * }
  * ```
+ *
+ * @example Custom labels
+ * ```tsx
+ * <YesNoRadioGroup
+ *   name="newsletter"
+ *   label="Subscribe to newsletter?"
+ *   yesLabel="Subscribe"
+ *   noLabel="No thanks"
+ * />
+ * ```
  */
-declare function SearchField(props: SearchFieldProps): React.ReactElement;
-type PasswordFieldProps = Omit<InputFieldProps, "input"> & {
-    /**
-     * Input-specific props (type is auto-set to "password")
-     */
-    input?: Omit<InputProps, "type">;
-    /**
-     * Autocomplete hint: "current-password" or "new-password"
-     * Defaults to "current-password"
-     */
-    autoComplete?: "current-password" | "new-password";
+declare function YesNoRadioGroup(props: YesNoRadioGroupProps): React.ReactElement;
+type RatingRadioGroupProps = Omit<RadioGroupFieldProps, "options"> & {
+    /** Minimum value (inclusive). Defaults to 1. */
+    min?: number;
+    /** Maximum value (inclusive). Defaults to 5. */
+    max?: number;
+    /** Custom label function. Receives the numeric value, returns a label. Defaults to `String(value)`. */
+    labelFn?: (value: number) => React.ReactNode;
 };
 /**
- * PasswordField - For password inputs with automatic show/hide toggle.
+ * RatingRadioGroup - For numeric scale selections.
  *
  * **AI Context:**
- * - Sets `type="password"` automatically (toggles to "text" when shown)
- * - Shows eye/eyeOff icon toggle button
- * - Sets appropriate `autoComplete` attribute
- * - Adds `data-purpose="password"` for AI parsing
+ * - Generates options from `min` to `max` (default 1–5)
+ * - Values are string representations of numbers ("1", "2", etc.)
+ * - Adds `data-purpose="rating"` for AI parsing
+ * - Custom labels via `labelFn`
  *
- * **Features:**
- * - Automatic show/hide toggle with eye icon
- * - Proper autocomplete for password managers
- * - Accessible toggle button with clear labels
- * - Controlled and uncontrolled modes supported
- *
- * @example Basic usage
+ * @example
  * ```tsx
- * import { PasswordField } from "@marwes-ui/react";
+ * import { RatingRadioGroup } from "@marwes-ui/react";
  *
  * export function Example() {
- *   const [password, setPassword] = React.useState("");
  *   return (
- *     <PasswordField
- *       label="Password"
- *       input={{ value: password, onValueChange: setPassword }}
+ *     <RatingRadioGroup
+ *       name="satisfaction"
+ *       label="How satisfied are you?"
+ *       defaultValue="3"
  *     />
  *   );
  * }
  * ```
  *
- * @example New password (signup/reset)
+ * @example Custom range and labels
  * ```tsx
- * <PasswordField
- *   label="New Password"
- *   autoComplete="new-password"
- *   helperText="Must be at least 8 characters"
+ * <RatingRadioGroup
+ *   name="priority"
+ *   label="Priority level"
+ *   min={1}
+ *   max={3}
+ *   labelFn={(v) => ["Low", "Medium", "High"][v - 1]}
  * />
  * ```
  */
-declare function PasswordField(props: PasswordFieldProps): React.ReactElement;
-type EmailFieldProps = Omit<InputFieldProps, "input"> & {
-    /**
-     * Input-specific props (type, inputMode, autoComplete auto-set)
-     */
-    input?: Omit<InputProps, "type" | "inputMode" | "autoComplete">;
-};
+declare function RatingRadioGroup(props: RatingRadioGroupProps): React.ReactElement;
+type OptionRadioGroupProps = RadioGroupFieldProps;
 /**
- * EmailField - For email address inputs with proper semantic attributes.
+ * OptionRadioGroup - For general labeled option selection.
  *
  * **AI Context:**
- * - Sets `type="email"` for validation
- * - Sets `inputMode="email"` for optimized mobile keyboard
- * - Sets `autoComplete="email"` for autofill
- * - Adds `data-purpose="email"` for AI parsing
- *
- * **Features:**
- * - Browser email validation
- * - Email-optimized mobile keyboard
- * - Autofill support for email addresses
+ * - Same API as `RadioGroupField` with `data-purpose="selection"` for AI parsing
+ * - Use when no more specific purpose component fits
+ * - Preferences, categories, modes, or any custom option list
  *
  * @example
  * ```tsx
- * import { EmailField } from "@marwes-ui/react";
+ * import { OptionRadioGroup } from "@marwes-ui/react";
  *
- * <EmailField
- *   label="Email address"
- *   input={{ placeholder: "you@example.com" }}
- * />
+ * export function Example() {
+ *   return (
+ *     <OptionRadioGroup
+ *       name="theme"
+ *       label="Select theme"
+ *       options={[
+ *         { value: "light", label: "Light" },
+ *         { value: "dark", label: "Dark" },
+ *         { value: "system", label: "System" },
+ *       ]}
+ *       defaultValue="system"
+ *     />
+ *   );
+ * }
  * ```
  */
-declare function EmailField(props: EmailFieldProps): React.ReactElement;
-type PhoneFieldProps = Omit<InputFieldProps, "input"> & {
-    /**
-     * Input-specific props (type, inputMode, autoComplete auto-set)
-     */
-    input?: Omit<InputProps, "type" | "inputMode" | "autoComplete">;
+declare function OptionRadioGroup(props: OptionRadioGroupProps): React.ReactElement;
+
+type BadgeProps = BadgeOptions & {
+    children?: React.ReactNode;
+    className?: string;
+    id?: string;
+    /** Data attributes for AI-friendly metadata (used by context variants). */
+    dataAttributes?: Record<string, string>;
 };
+declare function Badge(props: BadgeProps): React.ReactElement;
+
 /**
- * PhoneField - For phone number inputs with proper semantic attributes.
+ * BadgeGroup (Molecule) — Recommended
  *
- * **AI Context:**
- * - Sets `type="tel"` for telephone input
- * - Sets `inputMode="tel"` for phone keyboard
- * - Sets `autoComplete="tel"` for autofill
- * - Adds `data-purpose="phone"` for AI parsing
+ * An accessible badge group with a visible label. Groups related badges
+ * into a `role="group"` container with `aria-labelledby` wiring.
  *
- * **Features:**
- * - Phone-optimized mobile keyboard
- * - Autofill support for phone numbers
- * - Accepts any phone format (formatting should be done externally)
+ * Use `BadgeGroup` when displaying multiple related badges together
+ * (e.g. a list of tags, status indicators, or categories).
+ * Use `Badge` directly only when a single standalone badge is needed.
  *
  * @example
  * ```tsx
- * import { PhoneField } from "@marwes-ui/react";
+ * import { BadgeVariant } from "@marwes-ui/core";
  *
- * <PhoneField
- *   label="Phone number"
- *   input={{ placeholder: "+1 (555) 000-0000" }}
- * />
+ * <BadgeGroup label="Status">
+ *   <Badge variant={BadgeVariant.success}>Active</Badge>
+ *   <Badge variant={BadgeVariant.warning}>Pending review</Badge>
+ * </BadgeGroup>
  * ```
  */
-declare function PhoneField(props: PhoneFieldProps): React.ReactElement;
-type URLFieldProps = Omit<InputFieldProps, "input"> & {
-    /**
-     * Input-specific props (type, inputMode, autoComplete auto-set)
-     */
-    input?: Omit<InputProps, "type" | "inputMode" | "autoComplete">;
-};
+
+interface BadgeGroupProps {
+    /** Visible label for the badge group. */
+    label: React.ReactNode;
+    /** Badge children to render inside the group. */
+    children: React.ReactNode;
+    /** Additional CSS class names. */
+    className?: string;
+    /** Explicit ID. If omitted, generated via useId(). */
+    id?: string;
+    /** Data attributes for AI-friendly metadata (used by context variants). */
+    dataAttributes?: Record<string, string>;
+}
+declare function BadgeGroup(props: BadgeGroupProps): React.ReactElement;
+
 /**
- * URLField - For URL inputs with proper semantic attributes.
+ * Purpose Components — Badge
  *
- * **AI Context:**
- * - Sets `type="url"` for URL validation
- * - Sets `inputMode="url"` for URL keyboard
- * - Sets `autoComplete="url"` for autofill
- * - Adds `data-purpose="url"` for AI parsing
+ * Pre-configured badge compositions that encode a specific semantic purpose.
+ * Each sets `data-purpose` for machine-readable intent while keeping the
+ * visual `variant` prop for presentation only.
+ */
+
+type StatusBadgeProps = BadgeProps;
+/**
+ * StatusBadge - For operational or lifecycle status indicators.
  *
- * **Features:**
- * - Browser URL validation
- * - URL-optimized mobile keyboard
- * - Autofill support for URLs
+ * **AI Context:**
+ * - Adds `data-purpose="status"` for AI parsing
+ * - Ideal for active/inactive, online/offline, enabled/disabled states
  *
  * @example
  * ```tsx
- * import { URLField } from "@marwes-ui/react";
+ * import { BadgeVariant } from "@marwes-ui/core";
  *
- * <URLField
- *   label="Website"
- *   input={{ placeholder: "https://example.com" }}
- * />
+ * <StatusBadge variant={BadgeVariant.success}>Active</StatusBadge>
+ * <StatusBadge variant={BadgeVariant.error}>Offline</StatusBadge>
  * ```
  */
-declare function URLField(props: URLFieldProps): React.ReactElement;
-type CurrencyFieldProps = Omit<InputFieldProps, "input"> & {
-    /**
-     * Input-specific props (type, inputMode auto-set)
-     */
-    input?: Omit<InputProps, "type" | "inputMode">;
-    /**
-     * Currency code (e.g., "USD", "EUR", "GBP")
-     * Used for helper text and context
-     */
-    currency?: string;
-};
+declare function StatusBadge(props: StatusBadgeProps): React.ReactElement;
+type PriorityBadgeProps = BadgeProps;
 /**
- * CurrencyField - For monetary amount inputs with currency context.
+ * PriorityBadge - For urgency or importance indicators.
  *
  * **AI Context:**
- * - Sets `type="text"` (better browser support than "number")
- * - Sets `inputMode="decimal"` for numeric keyboard with decimal
- * - Adds currency code to helper text if provided
- * - Adds `data-purpose="currency"` and `data-currency` for AI parsing
+ * - Adds `data-purpose="priority"` for AI parsing
+ * - Ideal for critical/high/medium/low priority labels
  *
- * **Features:**
- * - Decimal keyboard on mobile
- * - Currency code display in helper text
- * - Better input control than type="number"
- * - Note: Formatting should be handled by parent component
+ * @example
+ * ```tsx
+ * import { BadgeVariant } from "@marwes-ui/core";
+ *
+ * <PriorityBadge variant={BadgeVariant.error}>Critical</PriorityBadge>
+ * <PriorityBadge variant={BadgeVariant.warning}>High</PriorityBadge>
+ * ```
+ */
+declare function PriorityBadge(props: PriorityBadgeProps): React.ReactElement;
+type NotificationBadgeProps = BadgeProps;
+/**
+ * NotificationBadge - For notification counts and alert indicators.
+ *
+ * **AI Context:**
+ * - Adds `data-purpose="notification"` for AI parsing
+ * - Ideal for unread counts, new items, alert badges
+ * - Always provide `ariaLabel` for numeric-only content
  *
  * @example
  * ```tsx
- * import { CurrencyField } from "@marwes-ui/react";
+ * import { BadgeVariant } from "@marwes-ui/core";
  *
- * <CurrencyField
- *   label="Amount"
- *   currency="USD"
- *   input={{ placeholder: "0.00" }}
- * />
+ * <NotificationBadge variant={BadgeVariant.info} ariaLabel="5 unread messages">5</NotificationBadge>
  * ```
  */
-declare function CurrencyField(props: CurrencyFieldProps): React.ReactElement;
+declare function NotificationBadge(props: NotificationBadgeProps): React.ReactElement;
+
+type SwitchProps = SwitchOptions & {
+    /** Label text rendered next to the toggle */
+    children?: React.ReactNode;
+    className?: string;
+    id?: string;
+    onCheckedChange?: (checked: boolean) => void;
+    onClick?: React.MouseEventHandler<HTMLButtonElement>;
+};
+declare function Switch(props: SwitchProps): React.ReactElement;
+
+type SwitchFieldProps = {
+    id?: string;
+    label: React.ReactNode;
+    description?: React.ReactNode;
+    error?: React.ReactNode;
+    switch: SwitchProps;
+    ariaDescribedBy?: string;
+    dataAttributes?: Record<string, string>;
+};
+declare function SwitchField(props: SwitchFieldProps): React.ReactElement;
+
+type FeatureToggleProps = SwitchFieldProps;
+declare function FeatureToggle(props: FeatureToggleProps): React.ReactElement;
+type PreferenceSwitchProps = SwitchFieldProps;
+declare function PreferenceSwitch(props: PreferenceSwitchProps): React.ReactElement;
+type PermissionSwitchProps = SwitchFieldProps;
+declare function PermissionSwitch(props: PermissionSwitchProps): React.ReactElement;
+
+type NativeSliderProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "className" | "defaultValue" | "max" | "min" | "onChange" | "step" | "style" | "type" | "value">;
+type SliderProps = SliderOptions & NativeSliderProps & {
+    className?: string;
+    style?: React.CSSProperties;
+    onValueChange?: (value: number) => void;
+    onChange?: React.ChangeEventHandler<HTMLInputElement>;
+};
+declare const Slider: React.ForwardRefExoticComponent<SliderOptions & NativeSliderProps & {
+    className?: string;
+    style?: React.CSSProperties;
+    onValueChange?: (value: number) => void;
+    onChange?: React.ChangeEventHandler<HTMLInputElement>;
+} & React.RefAttributes<HTMLInputElement>>;
+
+type SliderFieldLabelPosition = "top" | "inline";
+type SliderFieldProps = {
+    id?: string;
+    label: React.ReactNode;
+    description?: React.ReactNode;
+    error?: React.ReactNode;
+    slider: SliderProps;
+    ariaDescribedBy?: string;
+    minValueLabel?: React.ReactNode;
+    maxValueLabel?: React.ReactNode;
+    labelPosition?: SliderFieldLabelPosition;
+    showEdgeValues?: boolean;
+    dataAttributes?: Record<string, string>;
+};
+declare function SliderField(props: SliderFieldProps): React.ReactElement;
+
+type SliderFieldPurposeProps = Omit<SliderFieldProps, "label" | "slider" | "minValueLabel" | "maxValueLabel"> & {
+    label?: React.ReactNode;
+    slider?: SliderProps;
+    orientation?: SliderProps["orientation"];
+    minValueLabel?: React.ReactNode;
+    maxValueLabel?: React.ReactNode;
+};
+type VolumeSliderProps = SliderFieldPurposeProps;
+declare function VolumeSlider(props: VolumeSliderProps): React.ReactElement;
+type BrightnessSliderProps = SliderFieldPurposeProps;
+declare function BrightnessSlider(props: BrightnessSliderProps): React.ReactElement;
+type RadiusSliderProps = SliderFieldPurposeProps;
+declare function RadiusSlider(props: RadiusSliderProps): React.ReactElement;
+
+/**
+ * React adapter for Marwes Tab.
+ * - Renders a native <button> using the core render kit.
+ * - Applies strict a11y fields and modifier classes.
+ */
+
+type TabProps = TabOptions & {
+    children?: React.ReactNode;
+    className?: string;
+    onClick?: React.MouseEventHandler<HTMLButtonElement>;
+    id?: string;
+};
+declare function Tab(props: TabProps): React.ReactElement;
+
+interface TabGroupItem {
+    value: string;
+    label: React.ReactNode;
+    panel: React.ReactNode;
+    disabled?: boolean;
+    ariaLabel?: string;
+}
+interface TabGroupProps {
+    id?: string;
+    label?: React.ReactNode;
+    ariaLabel?: string;
+    tabs: TabGroupItem[];
+    activeTab?: string;
+    defaultActiveTab?: string;
+    onActiveTabChange?: (value: string) => void;
+    className?: string;
+    dataAttributes?: Record<string, string>;
+}
+interface TabPanelProps {
+    id: string;
+    tabId: string;
+    hidden?: boolean;
+    className?: string;
+    children?: React.ReactNode;
+}
+declare function TabPanel(props: TabPanelProps): React.ReactElement;
+declare function TabGroup(props: TabGroupProps): React.ReactElement;
+
+type NavigationTabsProps = TabGroupProps;
+declare function NavigationTabs(props: NavigationTabsProps): React.ReactElement;
+type ContentTabsProps = TabGroupProps;
+declare function ContentTabs(props: ContentTabsProps): React.ReactElement;
+type SettingsTabsProps = TabGroupProps;
+declare function SettingsTabs(props: SettingsTabsProps): React.ReactElement;
+
+interface DialogProps extends DialogOptions {
+    id?: string;
+    title?: React.ReactNode;
+    description?: React.ReactNode;
+    footer?: React.ReactNode;
+    children?: React.ReactNode;
+    onClose?: () => void;
+    className?: string;
+    dataAttributes?: Record<string, string>;
+}
+declare function Dialog(props: DialogProps): React.ReactElement;
+
+interface DialogFooterControls {
+    close: () => void;
+}
+interface DialogModalProps extends Omit<DialogProps, "footer" | "onClose"> {
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    closeOnEscape?: boolean;
+    closeOnScrimClick?: boolean;
+    restoreFocus?: boolean;
+    portalTarget?: HTMLElement | null;
+    overlayClassName?: string;
+    footer?: React.ReactNode | ((controls: DialogFooterControls) => React.ReactNode);
+}
+declare function DialogModal(props: DialogModalProps): React.ReactElement | null;
+
+type ConfirmDialogProps = Omit<DialogModalProps, "footer"> & {
+    confirmLabel?: React.ReactNode;
+    cancelLabel?: React.ReactNode;
+    onConfirm?: () => void;
+    onCancel?: () => void;
+};
+declare function ConfirmDialog(props: ConfirmDialogProps): React.ReactElement;
+type DestructiveDialogProps = Omit<DialogModalProps, "footer"> & {
+    confirmLabel?: React.ReactNode;
+    cancelLabel?: React.ReactNode;
+    onConfirm?: () => void;
+    onCancel?: () => void;
+};
+declare function DestructiveDialog(props: DestructiveDialogProps): React.ReactElement;
+type InfoDialogProps = Omit<DialogModalProps, "footer"> & {
+    acknowledgeLabel?: React.ReactNode;
+    onAcknowledge?: () => void;
+};
+declare function InfoDialog(props: InfoDialogProps): React.ReactElement;
 
-export { Button, type ButtonProps, CancelButton, type CancelButtonProps, Checkbox, CheckboxField, type CheckboxFieldProps, type CheckboxProps, CreateButton, type CreateButtonProps, CurrencyField, type CurrencyFieldProps, DangerButton, type DangerButtonProps, Divider, type DividerProps, EmailField, type EmailFieldProps, H1, type H1Props, H2, type H2Props, H3, type H3Props, Icon, type IconProps, Input, InputField, type InputFieldProps, type InputProps, LinkButton, type LinkButtonProps, MarwesProvider, type MarwesProviderProps, Paragraph, type ParagraphProps, PasswordField, type PasswordFieldProps, PhoneField, type PhoneFieldProps, PrimaryButton, type PrimaryButtonProps, SearchField, type SearchFieldProps, SecondaryButton, type SecondaryButtonProps, SubmitButton, type SubmitButtonProps, TextButton, type TextButtonProps, URLField, type URLFieldProps, useRenderKitDebug, useSystem, useTheme };
+export { Accordion, AccordionField, type AccordionFieldItem, type AccordionFieldProps, type AccordionProps, Avatar, AvatarBadge, type AvatarBadgeProps, AvatarGroup, type AvatarGroupItem, type AvatarGroupProps, type AvatarProps, Badge, BadgeGroup, type BadgeGroupProps, type BadgeProps, BrightnessSlider, type BrightnessSliderProps, Button, type ButtonProps, ButtonSpinner, type ButtonSpinnerProps, CancelButton, type CancelButtonProps, Card, type CardProps, Checkbox, CheckboxField, type CheckboxFieldProps, CheckboxGroupField, type CheckboxGroupFieldOption, type CheckboxGroupFieldProps, type CheckboxProps, CloseButton, type CloseButtonProps, ConfirmButton, type ConfirmButtonProps, ConfirmDialog, type ConfirmDialogProps, ContentTabs, type ContentTabsProps, CopyButton, type CopyButtonProps, CreateButton, type CreateButtonProps, CurrencyField, type CurrencyFieldProps, DateOfBirthField, type DateOfBirthFieldProps, DestructiveButton, type DestructiveButtonProps, DestructiveDialog, type DestructiveDialogProps, Dialog, type DialogFooterControls, DialogModal, type DialogModalProps, type DialogProps, Divider, type DividerProps, DownloadButton, type DownloadButtonProps, DropdownButton, type DropdownButtonProps, DropdownField, type DropdownFieldProps, EditButton, type EditButtonProps, EmailField, type EmailFieldProps, EmptyStateSpinner, type EmptyStateSpinnerProps, ErrorToast, type ErrorToastProps, FAQAccordion, type FAQAccordionProps, FeatureToggle, type FeatureToggleProps, FilterButton, type FilterButtonProps, H1, type H1Props, H2, type H2Props, H3, type H3Props, Icon, type IconProps, InfoDialog, type InfoDialogProps, InfoToast, type InfoToastProps, Input, InputField, type InputFieldProps, InputOtp, type InputOtpProps, type InputProps, LinkButton, type LinkButtonProps, type ManagedToast, MarwesProvider, type MarwesProviderProps, NavigationTabs, type NavigationTabsProps, NotificationBadge, type NotificationBadgeProps, OptionRadioGroup, type OptionRadioGroupProps, Paragraph, type ParagraphProps, PasswordField, type PasswordFieldProps, PermissionSwitch, type PermissionSwitchProps, PhoneField, type PhoneFieldProps, PreferenceSwitch, type PreferenceSwitchProps, PresenceAvatar, type PresenceAvatarProps, PrimaryButton, type PrimaryButtonProps, PriorityBadge, type PriorityBadgeProps, ProductCard, type ProductCardProps, ProfileAvatar, type ProfileAvatarProps, ProfileCard, type ProfileCardProps, Radio, RadioGroupField, type RadioGroupFieldOption, type RadioGroupFieldProps, type RadioProps, RadiusSlider, type RadiusSliderProps, RatingRadioGroup, type RatingRadioGroupProps, RefreshButton, type RefreshButtonProps, RichText, RichTextField, type RichTextFieldProps, type RichTextProps, SaveButton, type SaveButtonProps, SearchButton, type SearchButtonProps, SearchField, type SearchFieldProps, SecondaryButton, type SecondaryButtonProps, SectionsAccordion, type SectionsAccordionProps, Select, type SelectAppearance, SelectField, type SelectFieldProps, type SelectOption, type SelectProps, SettingsAccordion, type SettingsAccordionProps, SettingsTabs, type SettingsTabsProps, type ShowToastOptions, Slider, SliderField, type SliderFieldProps, type SliderProps, SortButton, type SortButtonProps, Spacer, type SpacerProps, Spacing, type SpacingProps, Spinner, type SpinnerProps, StatCard, type StatCardProps, StatusBadge, type StatusBadgeProps, SubmitButton, type SubmitButtonProps, SuccessButton, type SuccessButtonProps, SuccessToast, type SuccessToastProps, Switch, SwitchField, type SwitchFieldProps, type SwitchProps, Tab, TabGroup, type TabGroupItem, type TabGroupProps, TabPanel, type TabPanelProps, type TabProps, TeamAvatarGroup, type TeamAvatarGroupProps, TextButton, type TextButtonProps, Textarea, TextareaField, type TextareaFieldProps, type TextareaProps, type ThemeModeContextValue, Toast, ToastContainer, type ToastContainerProps, type ToastController, type ToastProps, ToastProvider, type ToastProviderProps, Tooltip, TooltipGroup, type TooltipGroupProps, type TooltipProps, URLField, type URLFieldProps, UploadButton, type UploadButtonProps, VerifyButton, type VerifyButtonProps, VolumeSlider, type VolumeSliderProps, WarningToast, type WarningToastProps, YesNoRadioGroup, type YesNoRadioGroupProps, ZipCodeField, type ZipCodeFieldProps, useTheme, useThemeMode, useToast };