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 ### Grove Mode & Terminology (GroveTerm V2) Grove has a terminology system that automatically switches between Grove-themed terms and standard terms based on the user's **Grove Mode** setting. **Always use GroveTerm components instead of hardcoding Grove terminology in UI.** By default, Grove Mode is OFF for new visitors. They see familiar terms: "Posts" instead of "Blooms", "Dashboard" instead of "Arbor", "Support" instead of "Porch". When users opt in via the footer toggle, they see the full nature-themed vocabulary with interactive definitions. **The Component Suite:** ```svelte import {(GroveTerm, GroveSwap, GroveText, GroveSwapText, GroveIntro)} from '@autumnsgrove/lattice/ui'; import groveTermManifest from '$lib/data/grove-term-manifest.json'; ``` | Component | Use Case | Behavior | | --------------- | ---------------------------------------- | ------------------------------------------------------------------------- | | `GroveTerm` | Interactive terms with popup definitions | Colored underline when ON, click for popup. Shows standard term when OFF. | | `GroveSwap` | Silent text replacement | Reactively swaps text. No underline, no interaction. | | `GroveText` | Parse `[[term]]` syntax in data strings | Renders `[[bloom\|posts]]` as interactive GroveTerm components. | | `GroveSwapText` | Parse `[[term]]` syntax silently | Same parsing, silent swaps (no popups). | | `GroveIntro` | "We call it X" page banners | Standardized intro below page titles. | **Usage:** ```svelte <!-- Interactive term with popup --> <GroveTerm term="bloom" manifest={groveTermManifest} /> <!-- Custom display text --> <GroveTerm term="wanderer" manifest={groveTermManifest}>wanderers</GroveTerm> <!-- Silent swap (no popup, no underline) --> <GroveSwap term="arbor" manifest={groveTermManifest} /> <!-- Parse [[term]] syntax in data strings (ideal for FAQ items, pricing, etc.) --> <GroveText content="Your [[bloom|posts]] live in your [[garden|blog]]." manifest={groveTermManifest} /> <!-- Silent text swap (non-interactive, default behavior) --> <GroveTerm term="meadow" /> <!-- With leaf icon for Grove Mode hint --> <GroveTerm term="meadow" icon /> ``` **Key Rules:** - **Never hardcode Grove terms** in user-facing UI. Always use GroveTerm components. - **Default is OFF** for new visitors. Standard, familiar terminology first. - **URLs stay as Grove terms** (`/porch`, `/garden`) regardless of display mode. - **Brand terms** (Grove) and **subscription tiers** (Seedling/Sapling/Oak/Evergreen) always show as-is. - **Use `[[term]]` syntax** for data-driven content (FAQ items, pricing fineprint, feature lists). - **Grove Mode store**: `groveModeStore` from `@autumnsgrove/lattice/ui/stores`. Toggle lives in the footer. See `docs/grove-user-identity.md` for the full identity language documentation and `libs/engine/src/lib/ui/components/ui/groveterm/` for component source. --- ## 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 '@lattice/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/lattice/ui/nature` or `$lib/components/nature/palette` #### Core Palettes (Year-Round) > **Accent colors:** These palette hex values are for nature SVGs, illustrations, and brand use. For CSS accent-colored surfaces (buttons, links, highlights), use `var(--grove-accent-*)` tokens instead — the user's accent color may not be green. See the accent scale: `var(--grove-accent)` (solid), `var(--grove-accent-dark)` (hover), `var(--grove-accent-N)` (opacity tints, stops 5-80). Pre-commit hook enforces this. ```typescript import { greens, bark, earth, natural } from "@autumnsgrove/lattice/ui/nature"; // Greens - organized dark-to-light for atmospheric depth // NOTE: Use these for nature components and brand illustrations. // For accent-colored UI surfaces, use var(--grove-accent-*) instead. 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/lattice/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/lattice/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/lattice/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);