/**
 * Machine-readable component metadata.
 *
 * Every component ships a `<Name>.meta.ts` exporting a `ComponentMeta`. A build
 * script (`scripts/build-registry.ts`) aggregates these into the JSON files in
 * this folder, which power LLM / generative-UI tooling.
 */
export type AtomicLevel = 'token' | 'atom' | 'molecule' | 'organism' | 'template' | 'page';
/**
 * How a component relates to MUI:
 * - themed-mui:   pure MUI component, only themed (no wrapper code)
 * - mui-overrides: MUI component with custom style/prop overrides in the theme
 * - mui-wrapper:  thin wrapper adding standard product behavior around MUI
 * - custom:       fully custom component (no direct MUI base)
 * - third-party-wrapper: wraps a heavy third-party dependency declared as a peer
 */
export type Classification = 'themed-mui' | 'mui-overrides' | 'mui-wrapper' | 'custom' | 'third-party-wrapper';
export interface PropMeta {
    name: string;
    type: string;
    required?: boolean;
    description?: string;
    default?: string;
}
export interface ComponentMeta {
    /** PascalCase component name, e.g. "Button". */
    name: string;
    level: AtomicLevel;
    /** Functional category, e.g. "input", "feedback", "navigation". */
    category: string;
    classification: Classification;
    description: string;
    /** Base library, e.g. "@mui/material" or "custom". */
    baseLibrary: string;
    /** Name of the equivalent MUI component, if any. */
    muiEquivalent?: string;
    /** Official MUI docs URL, if applicable. */
    muiDocs?: string;
    /** Equivalent in A2UI / other generative UI systems, if known. */
    a2uiEquivalent?: string;
    /** Repo-internal source path, e.g. "@/atoms/Chip". Not for consumers. */
    importPath: string;
    /**
     * Bare-specifier import consumers must use, e.g. "@aistrike-dev/ui" or a
     * subpath like "@aistrike-dev/ui/charts". Defaults to the package root, so
     * only components shipped from a subpath need to set this.
     */
    packageImport?: string;
    props?: PropMeta[];
    requiredProps?: string[];
    optionalProps?: string[];
    /** Custom variants this component adds beyond MUI defaults. */
    customVariants?: string[];
    /** Interactive / visual states supported. */
    supportedStates?: string[];
    /** Design token groups this component consumes. */
    designTokens?: string[];
    accessibility?: string[];
    usageExamples?: string[];
    /**
     * Positive usage and selection guidance: which variant to reach for, how to
     * size it, when to ask. Short imperatives, one rule per entry. The negative
     * counterpart is `antiPatterns` - never state the same rule in both.
     */
    rules?: string[];
    antiPatterns?: string[];
    /**
     * How this component paints a surface rung of its own — either by rendering a
     * `Surface` or by setting its own background.
     *
     * Nesting surfaces is capped at three levels, and that cap can only be checked
     * statically if a tool knows which components count as a level: a `Card`
     * inside a `Card` is two levels even though neither mentions `Surface` in the
     * consumer's source. The build emits these into
     * `registry/surface-mounting.json`, which the ESLint rule and the
     * `check-surfaces` CLI both read.
     *
     * The two values are not a detail — they decide whether nesting in *source*
     * means nesting on *screen*:
     *
     * - `inline` stays in the DOM where it is written, so JSX nesting is real
     *   nesting and counts toward the cap.
     * - `portal` is reparented to `document.body`, so it escapes its author's
     *   nesting entirely. A `Dialog` written inside a `Card` is not two levels;
     *   the dialog renders over the whole page. Counting these would flag code
     *   that is perfectly fine, so a static check must not.
     */
    mountsSurface?: 'inline' | 'portal';
    /** Whether this component is safe to use in LLM-generated UI. */
    llmSafe: boolean;
    whenToUse?: string[];
    whenNotToUse?: string[];
    /** Link back to the Figma node, if this maps to a specific design. */
    figma?: string;
}
/** Identity helper for authoring metadata with full type-checking. */
export declare function defineMeta(meta: ComponentMeta): ComponentMeta;