Component Status Taxonomy
Understand how AuraGlass classifies flagship, production, advanced, experimental, provider, primitive, listed, and internal component surfaces.
#Why Status Exists
AuraGlass has a broad public package surface. Status labels keep the website, docs, recipes, AI-agent guidance, and launch positioning honest about what each export is meant to do. A status label is not marketing decoration; it tells developers whether a component is a recommended flagship, a stable production control, an advanced feature with optional peers, a provider, a primitive, or an item that is catalogued without a standalone preview.
The website should avoid raw count-led positioning because counts are easy to misunderstand. A smaller set of excellent flagship components is more useful than a larger number of uneven demos. Status labels let the catalog show breadth while still steering new users toward the surfaces that can anchor real products.
#Launch Status Levels
Flagship components are the public face of the 3.1 launch. They should have polished demos, documented imports, examples, accessibility notes, performance notes, and credible usage in recipes or app surfaces. Examples include `GlassCard`, `GlassButton`, `OptimizedGlass`, `GlassCommandPalette`, `GlassDataGrid`, `GlassDataChart`, `GlassDashboard`, `GlassSidebar`, `LiquidGlassMaterial`, and `LiquidGlassMediaControls`.
Production components are stable, useful exports that may not be part of the curated launch set. They should still be valid package imports with a clear category and docs path. Advanced components are valid public exports that may need optional peers, providers, realtime services, media APIs, WebGL, or careful performance gates. Experimental components are public enough to mention only when the docs clearly explain the risk and avoid recommending them as defaults.
#Providers, Hooks, and Primitives
Providers and hooks are different from visual components. A provider such as `GlassEcommerceProvider`, `GlassMediaProvider`, or `LiquidGlassLayerProvider` may be essential for a feature family, but it should not be presented as a standalone visual card unless the demo explains what context it supplies. Hooks should be documented as APIs, not recommended as component imports.
Primitives such as `LiquidGlassMaterial`, `OptimizedGlass`, and lower-level layout helpers can be appropriate when a design engineer wants to compose a custom surface. They require stronger styling guidance than a finished component because the app owns more of the final structure, semantics, and responsive behavior.
#Agent and Docs Rules
AI-agent docs should recommend valid package exports only. Do not use future-facing aliases unless those names are actually exported by the package version in use. Use `GlassSidebar`, `GlassNavigation`, `LiquidGlassMediaControls`, and `GlassSmartShoppingCart` when those match the product job.
Component status in `docs-index.json` should be machine-readable and conservative. Each component entry needs an id, display name, import name, category, status, package path, peer dependency list, examples, and docs URL. This lets agents select components without inventing names or linking to missing pages.