style(docs): improve welcome page and visual styling

- Rewrite index.md with React Native-inspired welcoming layout - Add Diataxis section cards with descriptions - Remove sidebar separator, add spacing instead - Increase navbar padding with responsive breakpoints - Add rounded admonitions without left border bar - Use system font stack for better readability - Add lighter chevron styling in sidebar - Constrain max-width to 1600px for wide viewports 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-03 01:35:18 -05:00 · 2026-01-03 01:35:18 -05:00 · 34c65142be
parent e8cd1d0464
commit 34c65142be
2 changed files with 257 additions and 24 deletions
--- a/docs/index.md
+++ b/docs/index.md
@ -4,13 +4,31 @@ sidebar_position: 1
 title: Welcome to BMAD
 ---

-# BMAD Method Documentation
+# Welcome to BMAD

-> **Build More, Architect Dreams** — An AI-driven agile development framework with specialized agents, guided workflows, and scale-adaptive intelligence.
+BMAD (**B**uild **M**ore, **A**rchitect **D**reams) is an AI-driven development framework that helps you build software faster and smarter. It provides specialized AI agents, guided workflows, and intelligent planning that adapts to your project's complexity—whether you're fixing a bug or building an enterprise platform.
+
+If you're comfortable working with AI coding assistants like Claude, Cursor, or GitHub Copilot, you're ready to get started.

 ---

-## Choose Your Path
+## New Here? Start with the Quick Start
+
+The fastest way to understand BMAD is to try it. The Quick Start guide walks you through your first project in about 10 minutes.
+
+<a className="button button--primary button--lg" href="/docs/tutorials/getting-started/quick-start-bmm">Get Started with BMAD</a>
+
+<br/>
+
+:::tip Already familiar with AI-assisted development?
+Feel free to skip around. Use the sidebar to jump to any topic, or check out [What Are Agents?](/docs/explanation/core-concepts/what-are-agents) to understand how BMAD organizes its AI personas.
+:::
+
+---
+
+## How to Use These Docs
+
+These docs are organized into four sections based on what you're trying to do:

 <div className="row">
  <div className="col col--6 margin-bottom--lg">
@ -19,10 +37,10 @@ title: Welcome to BMAD
        <h3>Tutorials</h3>
      </div>
      <div className="card__body">
-        <p>Learn BMAD step by step. Start here if you're new.</p>
+        <p><strong>Learning-oriented.</strong> Step-by-step guides that walk you through building something. Start here if you're new to BMAD.</p>
      </div>
      <div className="card__footer">
-        <a className="button button--primary button--block" href="/docs/tutorials">Start Learning</a>
+        <a className="button button--secondary button--block" href="/docs/tutorials">Browse Tutorials</a>
      </div>
    </div>
  </div>
@ -32,10 +50,10 @@ title: Welcome to BMAD
        <h3>How-To Guides</h3>
      </div>
      <div className="card__body">
-        <p>Solve specific problems. Task-focused, practical guides.</p>
+        <p><strong>Task-oriented.</strong> Practical guides for solving specific problems. "How do I customize an agent?" lives here.</p>
      </div>
      <div className="card__footer">
-        <a className="button button--primary button--block" href="/docs/how-to">Find a Guide</a>
+        <a className="button button--secondary button--block" href="/docs/how-to">Find a Guide</a>
      </div>
    </div>
  </div>
@ -45,10 +63,10 @@ title: Welcome to BMAD
        <h3>Explanation</h3>
      </div>
      <div className="card__body">
-        <p>Understand the concepts. Why BMAD works the way it does.</p>
+        <p><strong>Understanding-oriented.</strong> Deep dives into concepts and architecture. Read these when you want to know <em>why</em> something works.</p>
      </div>
      <div className="card__footer">
-        <a className="button button--primary button--block" href="/docs/explanation">Explore Concepts</a>
+        <a className="button button--secondary button--block" href="/docs/explanation">Explore Concepts</a>
      </div>
    </div>
  </div>
@ -58,10 +76,10 @@ title: Welcome to BMAD
        <h3>Reference</h3>
      </div>
      <div className="card__body">
-        <p>Look up details. Agents, workflows, configuration options.</p>
+        <p><strong>Information-oriented.</strong> Technical specifications for agents, workflows, and configuration. Look things up here.</p>
      </div>
      <div className="card__footer">
-        <a className="button button--primary button--block" href="/docs/reference">Browse Reference</a>
+        <a className="button button--secondary button--block" href="/docs/reference">Browse Reference</a>
      </div>
    </div>
  </div>
@ -69,17 +87,31 @@ title: Welcome to BMAD

 ---

-## Quick Links
+## What You'll Need

- **New to BMAD?** → [Quick Start Tutorial](/docs/tutorials/getting-started/quick-start-bmm)
- **Installing?** → [Installation Guide](/docs/how-to/installation)
- **What are agents?** → [Understanding Agents](/docs/explanation/core-concepts/what-are-agents)
- **Looking for a workflow?** → [Workflow Reference](/docs/reference/workflows)
+BMAD works with any AI coding assistant that supports custom system prompts or project context. Popular options include:
+
+- **[Claude Code](https://claude.ai/claude-code)** — Anthropic's CLI tool (recommended)
+- **[Cursor](https://cursor.sh)** — AI-first code editor
+- **[Windsurf](https://codeium.com/windsurf)** — Codeium's AI IDE
+- **[Roo Code](https://roocode.com)** — VS Code extension
+
+You should be comfortable with basic software development concepts like version control, project structure, and agile workflows. No prior experience with BMAD-style agent systems is required—that's what these docs are for.

 ---

-## Community
+## Join the Community

- [Discord](https://discord.gg/gk8jAdXWmj) — Get help, share ideas
- [GitHub](https://github.com/bmad-code-org/BMAD-METHOD) — Source code, issues
- [YouTube](https://www.youtube.com/@BMadCode) — Video tutorials
+Get help, share what you're building, or contribute to BMAD:
+
+- **[Discord](https://discord.gg/gk8jAdXWmj)** — Chat with other BMAD users, ask questions, share ideas
+- **[GitHub](https://github.com/bmad-code-org/BMAD-METHOD)** — Source code, issues, and contributions
+- **[YouTube](https://www.youtube.com/@BMadCode)** — Video tutorials and walkthroughs
+
+---
+
+## Next Step
+
+Ready to dive in? Head to the Quick Start to build your first project with BMAD.
+
+<a className="button button--primary button--lg" href="/docs/tutorials/getting-started/quick-start-bmm">Start the Quick Start Tutorial</a>
--- a/website/css/custom.css
+++ b/website/css/custom.css
@ -39,9 +39,10 @@
 }

 /* ============================================
-   TYPOGRAPHY
+   TYPOGRAPHY - Clean, readable font stack
   ============================================ */
 :root {
+  --ifm-font-family-base: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
  --ifm-font-size-base: 100%;
  --ifm-line-height-base: 1.7;
  --ifm-heading-font-weight: 600;
@ -197,14 +198,99 @@
  color: var(--ifm-color-emphasis-200);
 }

+/* ============================================
+   LAYOUT - Spacing and structure
+   ============================================ */
+
+/* Max-width container for very wide viewports */
+.main-wrapper {
+  max-width: 1600px;
+  margin: 0 auto;
+}
+
+.navbar__inner {
+  max-width: 1600px;
+  margin: 0 auto;
+}
+
+.footer__container {
+  max-width: 1600px;
+  margin: 0 auto;
+}
+
+/* Remove sidebar border/separator, add spacing instead */
+.theme-doc-sidebar-container {
+  border-right: none !important;
+}
+
+/* Sidebar spacing on larger viewports */
+@media (min-width: 997px) {
+  .theme-doc-sidebar-container {
+    padding-left: 1rem;
+    padding-right: 1.5rem;
+  }
+
+  /* Add left margin to main content area */
+  .docMainContainer_node_modules-\@docusaurus-theme-classic-lib-theme-DocPage-Layout-Main-styles-module {
+    padding-left: 1rem;
+  }
+}
+
+@media (min-width: 1200px) {
+  .theme-doc-sidebar-container {
+    padding-left: 1.5rem;
+    padding-right: 2rem;
+  }
+}
+
+/* Ensure sidebar menu doesn't clip */
+.theme-doc-sidebar-menu {
+  padding-right: 1.5rem;
+}
+
+/* Lighter chevrons/carets */
+.menu__link--sublist-caret::after,
+.menu__caret::before {
+  opacity: 0.4;
+}
+
+.menu__link--sublist-caret:hover::after,
+.menu__caret:hover::before {
+  opacity: 0.6;
+}
+
+/* Add gap between sidebar and content */
+.col.docItemCol_node_modules-\@docusaurus-theme-classic-lib-theme-DocItem-Layout-styles-module {
+  padding-left: 2rem !important;
+}
+
 /* ============================================
   NAVBAR
   ============================================ */
 .navbar {
-  padding: 0.75rem 1rem;
+  padding: 1rem 1.5rem;
  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
 }

+/* Align logo with sidebar content */
+@media (min-width: 997px) {
+  .navbar {
+    padding-left: 2.5rem;
+    padding-right: 2.5rem;
+  }
+
+  .navbar__brand {
+    margin-right: 2rem;
+  }
+}
+
+@media (min-width: 1200px) {
+  .navbar {
+    padding-left: 3rem;
+    padding-right: 3rem;
+  }
+}
+
 .navbar__title {
  font-weight: 700;
 }
@ -412,7 +498,122 @@ blockquote {
  background-color: rgba(96, 165, 250, 0.05);
 }

-/* Admonition improvements */
-.admonition {
+/* ============================================
+   ADMONITIONS - Rounded, no left border bar
+   ============================================ */
+.admonition,
+.alert,
+[class*='admonition_'] {
  margin-bottom: 1.5rem;
+  padding: 1.25rem 1.5rem !important;
+  border-radius: 12px !important;
+  border: none !important;
+  border-left: 0 !important;
+  border-left-width: 0 !important;
+  box-shadow: 0 1px 4px rgba(0, 0, 0, 0.08);
+}
+
+.admonition::before,
+.alert::before {
+  display: none !important;
+}
+
+/* Force remove all left border variations */
+.admonition.alert,
+.alert.alert--secondary,
+.alert.alert--success,
+.alert.alert--info,
+.alert.alert--warning,
+.alert.alert--danger,
+[class*='admonition_'][class*='alert_'] {
+  border-left: 0 !important;
+  border-left-width: 0 !important;
+  border-left-style: none !important;
+}
+
+/* Tip admonition */
+.admonition.admonition-tip {
+  background-color: rgba(16, 185, 129, 0.08);
+}
+
+.admonition.admonition-tip .admonition-heading {
+  color: #059669;
+}
+
+[data-theme='dark'] .admonition.admonition-tip {
+  background-color: rgba(16, 185, 129, 0.12);
+}
+
+[data-theme='dark'] .admonition.admonition-tip .admonition-heading {
+  color: #34d399;
+}
+
+/* Info admonition */
+.admonition.admonition-info {
+  background-color: rgba(37, 99, 235, 0.08);
+}
+
+.admonition.admonition-info .admonition-heading {
+  color: #2563eb;
+}
+
+[data-theme='dark'] .admonition.admonition-info {
+  background-color: rgba(96, 165, 250, 0.12);
+}
+
+[data-theme='dark'] .admonition.admonition-info .admonition-heading {
+  color: #60a5fa;
+}
+
+/* Note admonition */
+.admonition.admonition-note {
+  background-color: rgba(107, 114, 128, 0.08);
+}
+
+[data-theme='dark'] .admonition.admonition-note {
+  background-color: rgba(156, 163, 175, 0.1);
+}
+
+/* Warning admonition */
+.admonition.admonition-warning,
+.admonition.admonition-caution {
+  background-color: rgba(245, 158, 11, 0.1);
+}
+
+.admonition.admonition-warning .admonition-heading,
+.admonition.admonition-caution .admonition-heading {
+  color: #d97706;
+}
+
+[data-theme='dark'] .admonition.admonition-warning,
+[data-theme='dark'] .admonition.admonition-caution {
+  background-color: rgba(245, 158, 11, 0.15);
+}
+
+[data-theme='dark'] .admonition.admonition-warning .admonition-heading,
+[data-theme='dark'] .admonition.admonition-caution .admonition-heading {
+  color: #fbbf24;
+}
+
+/* Danger admonition */
+.admonition.admonition-danger {
+  background-color: rgba(239, 68, 68, 0.1);
+}
+
+.admonition.admonition-danger .admonition-heading {
+  color: #dc2626;
+}
+
+[data-theme='dark'] .admonition.admonition-danger {
+  background-color: rgba(239, 68, 68, 0.15);
+}
+
+[data-theme='dark'] .admonition.admonition-danger .admonition-heading {
+  color: #f87171;
+}
+
+/* Admonition icon styling */
+.admonition-icon svg {
+  width: 1.25rem;
+  height: 1.25rem;
 }