Migration from 3.0.x to 3.1
Move AuraGlass 3.0.x apps to the 3.1 launch docs, CSS import path, component status taxonomy, recipes, and current package exports.
#Migration Goal
AuraGlass 3.1 is a trust and adoption release. The migration is less about rewriting every component and more about making package usage explicit, docs links reliable, examples copy-safe, and visual claims defensible. Apps already using 3.0.x should verify imports, CSS loading, optional peers, reduced-motion behavior, and any local overrides that reached into internal package files.
Start with a small screen that imports the package stylesheet once and renders a core surface such as `GlassCard` and `GlassButton`. Then move through overlays, data components, media components, providers, and recipes. This order catches the most common integration issues before heavier optional peer families are involved.
#Imports and Styles
Keep named component imports from `aura-glass` unless a documented public subpath is required. Import `aura-glass/styles` once in the app shell. Remove imports from private build output, unpublished source paths, and website preview files. Those paths might have worked during local development, but they are not stable package contracts.
Audit examples for invented aliases. Use exported navigation surfaces such as `GlassSidebar`, `GlassNavigation`, or `GlassNavigationMenu` depending on the layout. Use `LiquidGlassMediaControls` for media controls and `GlassSmartShoppingCart` when ecommerce cart UI is needed.
import { GlassButton, GlassCard, LiquidGlassMediaControls } from 'aura-glass';
import 'aura-glass/styles';#Peer Dependencies
The 3.1 docs group optional peers by feature family. Simple cards, buttons, and many layout surfaces need React, React DOM, and the package stylesheet. Charts need chart peers. Form helpers can need form peers. 3D and spatial features need Three.js peers. AI or realtime collaboration surfaces may need service-specific configuration in the application.
Do not install every optional peer just because the package lists a broad public surface. Add peers when the selected component family needs them. This keeps simple apps lighter and makes dependency review easier for teams adopting AuraGlass incrementally.
#Docs, Recipes, and Status Labels
Update internal docs and AI-agent prompts to link to existing routes only. Use `/docs/getting-started`, `/docs/installation`, `/docs/styling`, `/docs/nextjs`, `/docs/theming`, `/docs/dark-mode`, `/docs/reduced-motion`, `/docs/component-status`, and `/docs/migration-3-1` for the launch adoption path. Use `/recipes` for concrete copyable app surfaces.
When documenting a component, include the id, name, import name, category, status, package path, peer dependency list, examples, and docs URL. This keeps humans and agents aligned. Status should be conservative: flagship for curated launch anchors, production for stable everyday exports, advanced for heavier public features, and listed when the catalog intentionally has no standalone live card.
#Verification Checklist
After the import and docs pass, run a focused typecheck and build where feasible. In the app, verify desktop and mobile layouts, dark mode, reduced motion, keyboard focus, overlay stacking, and contrast over realistic backdrops. Media, 3D, canvas, and realtime features should be checked in the actual browser environment because static type checks cannot prove rendering cost or permission behavior.
Treat the migration as complete when public examples use valid exports, no docs links point at missing routes, component detail pages have component-specific metadata, and Open Graph copy no longer depends on old count-led positioning. That combination is what makes the 3.1 launch feel credible to developers evaluating the package.