grove-ui-design

# Grove UI Design Skill ## When to Activate Activate this skill when: - Creating or enhancing pages for Grove sites - Adding decorative nature elements (trees, clouds, weather effects) - Implementing glassmorphism effects for readability - Working with the seasonal theme system - Building navigation patterns (navbar, mobile overflow menus) - Creating "story" pages that guide users through content - Ensuring mobile-friendly, accessible UI - Choosing icons or visual elements ## The Grove Aesthetic Grove is a **place**. It's nature-themed, warm, and inviting—like a midnight tea shop with good documentation. ### Core Principles ``` Warm, introspective, queer, unapologetically building something meaningful. Write with the warmth of a midnight tea shop and the clarity of good documentation. ``` **Every design choice should feel:** - **Welcoming** — like entering a cozy space - **Organic** — natural, not rigid or corporate - **Readable** — content-first, decorations enhance, never obstruct - **Alive** — subtle animations, seasonal changes, randomization ### User Identity Language Grove uses specific terms for community members in all UI: | Term | Who | Use For | |------|-----|---------| | **Wanderer** | Everyone | Greetings, welcome messages, all users | | **Rooted** | Subscribers | Subscription confirmations, thank-yous | | **Pathfinder** | Trusted guides | Community leaders (appointed) | | **Wayfinder** | Autumn | The grove keeper (singular) | **In UI text:** - "Welcome, Wanderer." (not "Welcome, user") - "Welcome back, Wanderer." (dashboard greeting) - "You've taken root." (subscription confirmation) - "Thanks for staying rooted." (payment received) See `docs/grove-user-identity.md` for full documentation. --- ## Glassmorphism Pattern Glass effects create readability while revealing hints of background decoration. ### The Layering Formula ``` Background (gradients, vines, nature) ↓ Decorative Elements (trees, clouds, particles) ↓ Glass Surface (translucent + blur) ↓ Content (text, cards, UI) ``` ### Glass Components ```svelte import { Glass, GlassCard, GlassButton, GlassOverlay } from '@groveengine/ui/ui'; <!-- Container with glass effect --> <Glass variant="tint" class="p-6 rounded-xl"> <p>Readable text over busy backgrounds</p> </Glass> <!-- Card with glass styling --> <GlassCard title="Settings" variant="default" hoverable> Content here </GlassCard> <!-- Glass button --> <GlassButton variant="accent">Subscribe</GlassButton> ``` ### Glass Variants | Variant | Use Case | Light Mode | Dark Mode | |---------|----------|------------|-----------| | `surface` | Headers, navbars | 95% white | 95% slate | | `tint` | Text over backgrounds | 60% white | 50% slate | | `card` | Content cards | 80% white | 70% slate | | `accent` | Callouts, highlights | 30% accent | 20% accent | | `overlay` | Modal backdrops | 50% black | 60% black | | `muted` | Subtle backgrounds | 40% white | 30% slate | ### CSS Utility Classes ```html <!-- Apply directly to any element --> <div class="glass rounded-xl p-4">Basic glass</div> <div class="glass-tint p-6">Text container</div> <div class="glass-accent p-4">Highlighted section</div> <nav class="glass-surface sticky top-0">Navbar</nav> ``` ### Key Pattern: Sticky Navigation ```svelte <nav class="sticky top-[73px] z-30 bg-white/80 dark:bg-slate-900/80 backdrop-blur-sm border-b border-divider"> <!-- Navigation content --> </nav> ``` --- ## Seasonal Theme System Grove uses four seasons, each with distinct colors, weather effects, and moods. ### Season Detection ```svelte import { season } from '$lib/stores/season'; const isSpring = $derived($season === 'spring'); const isAutumn = $derived($season === 'autumn'); const isWinter = $derived($season === 'winter'); // Summer is the default (no flag needed) ``` ### Color Palette System Import from: `@autumnsgrove/groveengine/ui/nature` or `$lib/components/nature/palette` #### Core Palettes (Year-Round) ```typescript import { greens, bark, earth, natural } from '@autumnsgrove/groveengine/ui/nature'; // Greens - organized dark-to-light for atmospheric depth greens.darkForest // #0d4a1c - Background trees greens.deepGreen // #166534 - Mid-distance greens.grove // #16a34a - Grove brand primary greens.meadow // #22c55e - Standard foliage greens.spring // #4ade80 - Bright accent greens.mint // #86efac - Light accent greens.pale // #bbf7d0 - Foreground highlights // Bark - warm wood tones bark.darkBark // #3d2817 - Oak, older trees bark.bark // #5d4037 - Standard trunk bark.warmBark // #6B4423 - Pine, cedar bark.lightBark // #8b6914 - Young trees // Earth - ground elements earth.soil, earth.mud, earth.clay, earth.sand, earth.stone, earth.pebble, earth.slate // Natural - cream and off-whites natural.cream, natural.aspenBark, natural.bone, natural.mushroom, natural.birchWhite ``` #### Spring Palettes ```typescript import { springFoliage, springSky, wildflowers, cherryBlossoms, cherryBlossomsPeak } from '@autumnsgrove/groveengine/ui/nature'; // Spring Foliage - yellow-green new growth springFoliage.sprout // #65a30d - Distant new growth springFoliage.newLeaf // #84cc16 - Classic spring lime springFoliage.freshGreen // #a3e635 - Bright foreground springFoliage.budding // #bef264 - Pale new leaf springFoliage.tender // #d9f99d - Very pale // Spring Sky springSky.clear // #7dd3fc - Clear morning springSky.soft // #bae6fd - Pale sky // Wildflowers - unified meadow flower colors wildflowers.buttercup // #facc15 - Yellow wildflowers.daffodil // #fde047 - Pale yellow wildflowers.crocus // #a78bfa - Purple crocus wildflowers.violet // #8b5cf6 - Wild violets wildflowers.purple // #a855f7 - Lupine, thistle wildflowers.lavender // #c4b5fd - Distant masses wildflowers.tulipPink // #f9a8d4 - Pink tulips wildflowers.tulipRed // #fb7185 - Red tulips wildflowers.white // #fefefe - Daisies, trillium // Cherry Blossoms - summer standard cherryBlossoms.deep // #db2777 - Dense centers cherryBlossoms.standard // #ec4899 - Standard blossom cherryBlossoms.light // #f472b6 - Light petals cherryBlossoms.pale // #f9a8d4 - Pale blossoms cherryBlossoms.falling // #fbcfe8 - Falling petals // Cherry Blossoms Peak - vibrant spring (one shade brighter!) cherryBlossomsPeak.deep // #ec4899 cherryBlossomsPeak.standard // #f472b6 cherryBlossomsPeak.light // #f9a8d4 cherryBlossomsPeak.pale // #fbcfe8 cherryBlossomsPeak.falling // #fce7f3 ``` #### Unified Flowers Palette (NEW!) The `flowers` namespace consolidates all flower colors into one organized structure: ```typescript import { flowers } from '@autumnsgrove/groveengine/ui/nature'; // Meadow wildflowers (yellows, purples, pinks, whites) flowers.wildflower.buttercup // #facc15 - Yellow flowers.wildflower.daffodil // #fde047 - Pale yellow flowers.wildflower.crocus // #a78bfa - Purple crocus flowers.wildflower.violet // #8b5cf6 - Wild violets flowers.wildflower.purple // #a855f7 - Lupine, thistle flowers.wildflower.lavender // #c4b5fd - Distant masses flowers.wildflower.tulipPink // #f9a8d4 - Pink tulips flowers.wildflower.tulipRed // #fb7185 - Red tulips flowers.wildflower.white // #fefefe - Daisies, trillium // Cherry blossoms - standard summer flowers.cherry.deep // #db2777 flowers.cherry.standard // #ec4899 flowers.cherry.light // #f472b6 flowers.cherry.pale // #f9a8d4 flowers.cherry.falling // #fbcfe8 // Cherry blossoms at peak bloom - vibrant spring flowers.cherryPeak.deep // #ec4899 flowers.cherryPeak.standard // #f472b6 flowers.cherryPeak.light // #f9a8d4 flowers.cherryPeak.pale // #fbcfe8 flowers.cherryPeak.falling // #fce7f3 ``` **Use `flowers.wildflower` instead of `accents.flower`** — the accents version is deprecated. #### Autumn & Winter Palettes ```typescript import { autumn, autumnReds, winter } from '@autumnsgrove/groveengine/ui/nature'; // Autumn - warm fall foliage (dark-to-light for depth) autumn.rust // #9a3412 - Deep background autumn.ember // #c2410c - Oak-like autumn.pumpkin // #ea580c - Maple mid-tones autumn.amber // #d97706 - Classic fall autumn.gold // #eab308 - Aspen/birch autumn.honey // #facc15 - Bright foreground autumn.straw // #fde047 - Pale dying leaves // Autumn Reds - cherry/maple fall foliage autumnReds.crimson // #be123c - Deep maple autumnReds.scarlet // #e11d48 - Bright cherry autumnReds.rose // #f43f5e - Light autumn autumnReds.coral // #fb7185 - Pale accent // Winter - frost, snow, ice + frosted evergreens winter.snow, winter.frost, winter.ice, winter.glacier winter.frostedPine, winter.winterGreen, winter.coldSpruce winter.winterSky, winter.twilight, winter.overcast winter.bareBranch, winter.frostedBark, winter.coldWood winter.hillDeep, winter.hillMid, winter.hillNear, winter.hillFront ``` #### Accent Palettes ```typescript import { accents, wildflowers } from '@autumnsgrove/groveengine/ui/nature'; // Mushrooms - fairy tale pops of color accents.mushroom.redCap, accents.mushroom.orangeCap, accents.mushroom.brownCap accents.mushroom.spots, accents.mushroom.gill // Firefly - bioluminescence accents.firefly.glow, accents.firefly.warmGlow, accents.firefly.body // Berry - rich saturated accents.berry.ripe, accents.berry.elderberry, accents.berry.red // Water - cool blue spectrum accents.water.surface, accents.water.deep, accents.water.shallow, accents.water.lily // Sky - time of day accents.sky.dayLight, accents.sky.dayMid, accents.sky.sunset, accents.sky.night, accents.sky.star // Birds - species-specific colors accents.bird.cardinalRed, accents.bird.cardinalMask, accents.bird.cardinalBeak accents.bird.chickadeeCap, accents.bird.chickadeeBody, accents.bird.chickadeeBelly accents.bird.robinBody, accents.bird.robinBreast, accents.bird.robinBeak accents.bird.bluebirdBody, accents.bird.bluebirdWing, accents.bird.bluebirdBreast // NOTE: accents.flower is deprecated - use flowers.wildflower instead ``` #### Seasonal Helper Functions ```typescript import { getSeasonalGreens, getCherryColors, isTreeBare, pickRandom, pickFrom } from '@autumnsgrove/groveengine/ui/nature'; // Get foliage colors mapped to season const foliage = getSeasonalGreens(season); // spring → springFoliage colors // summer → greens // autumn → autumn palette // winter → frosted evergreen colors // Get cherry tree colors by season const cherryColors = getCherryColors(season); // spring → cherryBlossomsPeak (vibrant!) // summer → cherryBlossoms (standard) // autumn → autumnReds // winter → null (bare tree) // Check if deciduous tree is bare if (isTreeBare('cherry', 'winter')) { /* no foliage */ } // Random color selection for natural variation const randomGreen = pickRandom(greens); const specificGreen = pickFrom(greens, ['grove', 'meadow']); ``` #### Deprecated Aliases (Still Work) ```typescript // These work but will be removed in v1.0: import { spring, pinks, springBlossoms } from '@autumnsgrove/groveengine/ui/nature'; // spring → use springFoliage, wildflowers, springSky instead // pinks → use cherryBlossoms instead // springBlossoms → use cherryBlossomsPeak instead // accents.flower → use flowers.wildflower instead ``` #### Season Mood Summary | Season | Primary Colors | Mood | |--------|---------------|------| | **Spring** | `springFoliage`, `cherryBlossomsPeak`, `wildflowers` | Renewal, hope | | **Summer** | `greens`, `cherryBlossoms` | Growth, warmth | | **Autumn** | `autumn`, `autumnReds` | Harvest, reflection | | **Winter** | `winter` (frost, snow, frosted pines) | Rest, stillness | ### Seasonal Weather Effects ```svelte <!-- Winter: Snowfall --> {#if isWinter} <SnowfallLayer count={40} zIndex={5} opacity={{ min: 0.4, max: 0.8 }} spawnDelay={8} /> {/if} <!-- Spring: Cherry blossom petals --> {#if isSpring} <FallingPetalsLayer count={80} zIndex={100} opacity={{ min: 0.5, max: 0.9 }} /> {/if} <!-- Autumn: Falling leaves (tied to trees) --> {#if isAutumn} <FallingLeavesLayer trees={forestTrees} season={$season} minLeavesPerTree={2} maxLeavesPerTree={4} /> {/if} ``` ### Seasonal Background Gradients