> ## Documentation Index > Fetch the complete documentation index at: https://boutiquedb.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 2026 08 05 boutiquedb docs redesign # BoutiqueDB Documentation Redesign Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Replace the current Maple-based docs-first presentation with a polished Aspen-based product landing page and a clearly separated, highly usable documentation experience in both light and dark mode. **Architecture:** Keep `/` as a hidden, `mode: custom` marketing landing page with only the product navbar visible. Route all onboarding CTAs into `/getting-started/quick-start`, where the full documentation sidebar begins. Use Aspen for the documentation shell and implement the BoutiqueDB visual system in `styles.css` so the custom landing and native Mintlify components share the same color, radius, depth, and interaction language. **Tech Stack:** Mintlify `docs.json`, MDX, custom CSS, Font Awesome icons, existing BoutiqueDB PNG assets, GitHub PR workflow. ## Global Constraints * English-only for this iteration; translation architecture remains deferred. * Do not add a new JavaScript framework, runtime dependency, or external asset CDN. * Preserve all existing documentation URLs. * Preserve the BoutiqueDB icon and GitHub/Swift Package Index destinations. * The landing page must not show the documentation sidebar or table of contents. * Documentation pages must retain searchable, navigable sidebar behavior. * Light mode must be intentionally designed, not a simple inversion of dark mode. * Cards must be compact, square-leaning, centered, and semantically colored. * Open a PR only after MDX/config validation, navigation inspection, responsive CSS review, and final diff review are complete. *** ## Theme decision ### Evaluated rendered implementations * **Maple — current BoutiqueDB site:** attractive centered hero in dark mode, but the shell produces broad rounded surfaces, oversized horizontal cards, large unused bands, and a weak light-mode identity. * **Almond — ComfyUI docs:** excellent information discovery and card-catalog density, but its visual hierarchy is portal-like and utility-heavy. It would compete with BoutiqueDB's custom feature-card system rather than supporting it. * **Aspen — CrewAI docs:** supports a product-oriented landing page, dense multi-level navigation, custom components, and a stronger separation between overview content and documentation. Its shell is structured without imposing a card-first homepage. * **Luma — Mintlify's Luma demo:** clear and readable, but intentionally airy and visually lightweight; it does not provide enough depth or product presence for BoutiqueDB. * **Mint, Willow, Palm, Linden, Sequoia:** rejected respectively for conventional docs styling, excessive minimalism, enterprise/fintech character, terminal gimmickry, or content-library emphasis over product presentation. **Selected theme: `aspen`.** It gives the best documentation shell for BoutiqueDB while leaving the custom landing page and card system under our control. *** ## File structure * Modify `docs/docs.json`: switch to Aspen, refine global colors/background/navbar/footer/search, and keep the documentation shell product-oriented. * Modify `docs/index.md`: replace the current docs overview with the complete custom landing page. * Modify `docs/styles.css`: define the full light/dark token system, landing layout, cards, architecture visual, code surface, shadows, native Mintlify component polish, navbar/sidebar states, and responsive behavior. * Modify navigation metadata through Mintlify Admin MCP: hide `/` from the sidebar, rename/reorder tabs and groups, and polish raw sidebar titles. * Create `docs/superpowers/plans/2026-08-05-boutiquedb-docs-redesign.md`: retain this implementation record. *** ### Task 1: Migrate the documentation shell to Aspen **Files:** * Modify: `docs/docs.json` **Produces:** Aspen theme shell, warm technical light mode, deep navy dark mode, grid decoration, product navbar, and consistent code block styling. * [ ] Set `theme` to `aspen`. * [ ] Set brand colors to coral primary (`#F25F3A`), lighter coral dark-mode accent (`#FF9B7A`), and deep rust interaction color (`#C9432B`). * [ ] Set background decoration to `grid` with light `#F7F6F2` and dark `#07101E`. * [ ] Keep system appearance switching enabled. * [ ] Set navbar links to GitHub and Swift Package Index, with `Get Started` as the primary action. * [ ] Use breadcrumb eyebrows on docs pages and keep separate light/dark Shiki themes. * [ ] Update footer copy destinations so the product, documentation, and contributor paths are coherent. * [ ] Validate the config through Mintlify's schema-backed `update_config` call. ### Task 2: Separate the landing page from the docs experience **Files:** * Modify: `docs/index.md` * Modify navigation metadata through Mintlify MCP **Produces:** `/` behaves as a product page; documentation chrome appears only after entering a docs route. * [ ] Keep `index` in `mode: custom`, hidden from sidebar navigation, indexed for search engines, and without footer pagination. * [ ] Rename the top tabs to `Docs` and `Architecture`. * [ ] Point the Docs tab at `/getting-started/quick-start` and Architecture at `/advanced/boutiquedb-architecture`. * [ ] Move `Getting Started` before conceptual/reference groups. * [ ] Rename the old Overview group to `Fundamentals`. * [ ] Polish sidebar labels for `stack`, `sync-overview`, and `open-options`. * [ ] Confirm that all existing paths remain unchanged. ### Task 3: Build the product landing page **Files:** * Modify: `docs/index.md` **Produces:** complete product page with clear hierarchy and conversion path. * [ ] Build a split hero with product copy on the left and a layered BoutiqueDB engine visual on the right. * [ ] Add the platform/status strip: Swift 6, iOS, macOS, SQLite-compatible, local-first. * [ ] Add primary `Get Started` and secondary `Explore Architecture` actions. * [ ] Add a centered 2x2 feature grid with distinct coral, blue, violet, and teal semantic treatments. * [ ] Add a visual architecture section showing SwiftUI → LiveQuery → BoutiqueDB Actor → Turso/CloudKit. * [ ] Add a Swift code window demonstrating `@Table` and `@LiveQuery`. * [ ] Add three compact product-principle cards and a final conversion CTA. * [ ] Keep copy technically accurate and avoid unsupported performance claims. * [ ] Validate the complete MDX through Mintlify `write_page`. ### Task 4: Implement the full visual system manually **Files:** * Modify: `docs/styles.css` **Produces:** intentionally designed light/dark modes, depth, responsive behavior, and shared component styling. * [ ] Define semantic CSS variables for backgrounds, surfaces, text, borders, coral, blue, violet, teal, and shadows in light mode. * [ ] Override the variables in `.dark` with independently tuned dark-mode values. * [ ] Style the landing container, split hero, subtle grid/noise layers, glow effects, logo pedestal, engine stack, and floating capability chips. * [ ] Implement compact feature cards with minimum height, balanced aspect, colored icon wells, top accent lines, layered shadows, and restrained hover lift. * [ ] Implement architecture, code, principle, and CTA surfaces with progressive depth rather than identical borders. * [ ] Polish native Mintlify cards, steps, code blocks, callouts, tables, selected sidebar links, navbar, search, and tabs so they match the new system. * [ ] Ensure focus-visible states remain obvious and motion respects `prefers-reduced-motion`. * [ ] Add breakpoints for large desktop, tablet, and mobile; collapse hero/architecture/code grids and make CTA buttons full-width where needed. ### Task 5: Validation and iteration gate **Files:** * Inspect: `docs/docs.json`, `docs/index.md`, `docs/styles.css`, navigation tree **Produces:** verified branch ready for review, with no premature PR. * [ ] Read back `index`, `styles.css`, and `docs.json` from the active Mintlify session. * [ ] Inspect the complete Mintlify diff and confirm only intentional files/navigation metadata changed. * [ ] Confirm every landing link points to an existing page. * [ ] Confirm `/` is hidden from sidebar but remains the logo destination. * [ ] Confirm Docs and Architecture tabs resolve to their intended entry pages. * [ ] Review CSS at desktop, tablet, and mobile breakpoints for overflow, oversized cards, unreadable contrast, and missing stacking rules. * [ ] Save to the branch with `mode: commit`, not PR. * [ ] Compare branch against `main` through GitHub and verify the final file list and diff size. * [ ] Check available commit/CI status and report any absent automated checks honestly. * [ ] Open a non-draft PR only after all previous steps pass. ### Task 6: PR evidence **Produces:** reviewable pull request that states exactly what changed and what was validated. * [ ] Use a PR title focused on the completed redesign rather than partial polish. * [ ] Include theme rationale, landing/docs split, card system, light/dark treatment, navigation changes, responsive coverage, and validation evidence in the PR body. * [ ] Explicitly state that translation was intentionally deferred. * [ ] Do not claim screenshot or browser validation unless actual visual evidence was obtained. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.