docs: add crate organization sections to workspace (#1946)

Adds summary-level crate organization documentation to all crates
explaining the modular workspace structure and when to use each crate.
Links to ARCHITECTURE.md for detailed information.

ARCHITECTURE.md

@@ -0,0 +1,203 @@
+# Ratatui Architecture
+
+This document provides a comprehensive overview of Ratatui's architecture and crate
+organization, introduced in version 0.30.0.
+
+## Overview
+
+Starting with Ratatui 0.30.0, the project was reorganized from a single monolithic crate into
+a modular workspace consisting of multiple specialized crates. This architectural decision was
+made to improve modularity, reduce compilation times, enable more flexible dependency
+management, and provide better API stability for third-party widget libraries.
+
+## Crate Organization
+
+The Ratatui project is now organized as a Cargo workspace containing the following crates:
+
+### Core Crates
+
+#### `ratatui` (Main Crate)
+
+- **Purpose**: The main entry point that most applications should use
+- **Contents**: Re-exports everything from other crates for convenience, plus experimental features
+- **Target Users**: Application developers building terminal UIs
+- **Key Features**:
+  - Complete widget ecosystem
+  - Backend implementations
+  - Layout system
+  - Terminal management
+  - Experimental `WidgetRef` and `StatefulWidgetRef` traits
+
+#### `ratatui-core`
+
+- **Purpose**: Foundational types and traits for the Ratatui ecosystem
+- **Contents**: Core widget traits, text types, buffer, layout, style, and symbols
+- **Target Users**: Widget library authors, minimalist projects
+- **Key Features**:
+  - `Widget` and `StatefulWidget` traits
+  - Text rendering (`Text`, `Line`, `Span`)
+  - Buffer management
+  - Layout system
+  - Style and color definitions
+  - Symbol collections
+
+#### `ratatui-widgets`
+
+- **Purpose**: Built-in widget implementations
+- **Contents**: All standard widgets like `Block`, `Paragraph`, `List`, `Chart`, etc.
+- **Target Users**: Applications needing standard widgets, widget library authors
+- **Key Features**:
+  - Complete set of built-in widgets
+  - Optimized implementations
+  - Comprehensive documentation and examples
+
+### Backend Crates
+
+#### `ratatui-crossterm`
+
+- **Purpose**: Crossterm backend implementation
+- **Contents**: Cross-platform terminal backend using the `crossterm` crate
+- **Target Users**: Applications targeting multiple platforms
+
+#### `ratatui-termion`
+
+- **Purpose**: Termion backend implementation
+- **Contents**: Unix-specific terminal backend using the `termion` crate
+- **Target Users**: Unix-specific applications requiring low-level control
+
+#### `ratatui-termwiz`
+
+- **Purpose**: Termwiz backend implementation
+- **Contents**: Terminal backend using the `termwiz` crate
+- **Target Users**: Applications needing advanced terminal features
+
+### Utility Crates
+
+#### `ratatui-macros`
+
+- **Purpose**: Declarative macros for common patterns and boilerplate reduction
+- **Contents**: Macros for common patterns and boilerplate reduction
+- **Target Users**: Applications and libraries wanting macro support
+
+## Dependency Relationships
+
+```text
+ratatui
+├── ratatui-core
+├── ratatui-widgets → ratatui-core
+├── ratatui-crossterm → ratatui-core
+├── ratatui-termion → ratatui-core
+├── ratatui-termwiz → ratatui-core
+└── ratatui-macros
+```
+
+### Key Dependencies
+
+- **ratatui-core**: Foundation for all other crates
+- **ratatui-widgets**: Depends on `ratatui-core` for widget traits and types
+- **Backend crates**: Each depends on `ratatui-core` for backend traits and types
+- **ratatui**: Depends on all other crates and re-exports their public APIs
+
+## Design Principles
+
+### Stability and Compatibility
+
+The modular architecture provides different levels of API stability:
+
+- **ratatui-core**: Designed for maximum stability to minimize breaking changes for widget
+  libraries
+- **ratatui-widgets**: Focused on widget implementations with moderate stability requirements
+- **Backend crates**: Isolated from core changes, allowing backend-specific updates
+- **ratatui**: Main crate that can evolve more freely while maintaining backward compatibility
+  through re-exports
+
+### Compilation Performance
+
+The split architecture enables:
+
+- **Reduced compilation times**: Widget libraries only need to compile core types
+- **Parallel compilation**: Different crates can be compiled in parallel
+- **Selective compilation**: Applications can exclude unused backends or widgets
+
+### Ecosystem Benefits
+
+- **Widget Library Authors**: Can depend on stable `ratatui-core` without frequent updates
+- **Application Developers**: Can use the convenient `ratatui` crate with everything included
+- **Minimalist Projects**: Can use only `ratatui-core` for lightweight applications
+
+## Migration Guide
+
+### For Application Developers
+
+Most applications should continue using the main `ratatui` crate with minimal changes:
+
+```rust
+// No changes needed - everything is re-exported
+use ratatui::{
+    widgets::{Block, Paragraph},
+    layout::{Layout, Constraint},
+    Terminal,
+};
+```
+
+### For Widget Library Authors
+
+Consider migrating to `ratatui-core` for better stability:
+
+```rust
+// Before (0.29.x and earlier)
+use ratatui::{
+    widgets::{Widget, StatefulWidget},
+    buffer::Buffer,
+    layout::Rect,
+};
+
+// After (0.30.0+)
+use ratatui_core::{
+    widgets::{Widget, StatefulWidget},
+    buffer::Buffer,
+    layout::Rect,
+};
+```
+
+### Backwards Compatibility
+
+All existing code using the `ratatui` crate will continue to work unchanged, as the main crate
+re-exports all public APIs from the specialized crates.
+
+## Future Considerations
+
+### Potential Enhancements
+
+- **Widget-specific crates**: Further split widgets into individual crates for even more
+  granular dependencies
+- **Plugin system**: Enable dynamic widget loading and third-party widget ecosystems
+- **Feature flags**: More granular feature flags for compile-time customization
+
+### Version Synchronization
+
+Currently, all crates are versioned together for simplicity. Future versions may adopt
+independent versioning once the API stabilizes further.
+
+## Related Issues and PRs
+
+This architecture was developed through extensive discussion and implementation across multiple
+PRs:
+
+- [Issue #1388](https://github.com/ratatui/ratatui/issues/1388): Original RFC for modularization
+- [PR #1459](https://github.com/ratatui/ratatui/pull/1459): Move ratatui crate into workspace
+  folder
+- [PR #1460](https://github.com/ratatui/ratatui/pull/1460): Move core types to ratatui-core
+- [PR #1474](https://github.com/ratatui/ratatui/pull/1474): Move widgets into ratatui-widgets
+  crate
+
+## Contributing
+
+When contributing to the Ratatui project, please consider:
+
+- **Core changes**: Submit PRs against `ratatui-core` for fundamental improvements
+- **Widget changes**: Submit PRs against `ratatui-widgets` for widget-specific improvements
+- **Backend changes**: Submit PRs against the appropriate backend crate
+- **Integration changes**: Submit PRs against the main `ratatui` crate
+
+See the [CONTRIBUTING.md](CONTRIBUTING.md) guide for more details on the contribution process.

CONTRIBUTING.md

@@ -91,6 +91,14 @@ cd ratatui
 cargo xtask build
 ```
 
+### Architecture
+
+For an understanding of the crate organization and design decisions, see [ARCHITECTURE.md]. This
+document explains the modular workspace structure introduced in version 0.30.0 and provides
+guidance on which crate to use for different use cases.
+
+[ARCHITECTURE.md]: ./ARCHITECTURE.md
+
 ### Tests
 
 The [test coverage](https://app.codecov.io/gh/ratatui/ratatui) of the crate is reasonably

README.md

@@ -73,6 +73,7 @@ fn render(frame: &mut Frame) {
 - [Ratatui Forum] - a place to ask questions and discuss the library.
 - [Widget Examples] - a collection of examples that demonstrate how to use the library.
 - [App Examples] - a collection of more complex examples that demonstrate how to build apps.
+- [ARCHITECTURE.md] - explains the crate organization and modular workspace structure.
 - [Changelog] - generated by [git-cliff] utilizing [Conventional Commits].
 - [Breaking Changes] - a list of breaking changes in the library.
 
@@ -141,6 +142,7 @@ This project is licensed under the [MIT License][License].
 [Docs]: https://docs.rs/ratatui
 [Widget Examples]: https://github.com/ratatui/ratatui/tree/main/ratatui-widgets/examples
 [App Examples]: https://github.com/ratatui/ratatui/tree/main/examples
+[ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
 [Changelog]: https://github.com/ratatui/ratatui/blob/main/CHANGELOG.md
 [git-cliff]: https://git-cliff.org
 [Conventional Commits]: https://www.conventionalcommits.org

ratatui-core/README.md

@@ -29,6 +29,32 @@ Add `ratatui-core` to your `Cargo.toml`:
 cargo add ratatui-core
 ```
 
+## Crate Organization
+
+`ratatui-core` is part of the Ratatui workspace that was modularized in version 0.30.0 to
+improve compilation times, API stability, and dependency management. This crate provides the
+foundational types and traits that other crates in the workspace depend on.
+
+**When to use `ratatui-core`:**
+
+- Building widget libraries that implement [`Widget`] or [`StatefulWidget`]
+- Creating lightweight applications that don't need built-in widgets
+- You want minimal dependencies and faster compilation times
+- You need maximum API stability (core types change less frequently)
+
+**When to use the main [`ratatui`] crate:**
+
+- Building applications that use built-in widgets
+- You want convenience and don't mind slightly longer compilation times
+- You need backend implementations and terminal management utilities
+
+For detailed information about the workspace organization, see [ARCHITECTURE.md].
+
+[`ratatui`]: https://crates.io/crates/ratatui
+[`Widget`]: widgets::Widget
+[`StatefulWidget`]: widgets::StatefulWidget
+[ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
+
 ## Contributing
 
 We welcome contributions from the community! Please see our [CONTRIBUTING](../CONTRIBUTING.md)

ratatui-core/src/lib.rs

@@ -27,6 +27,32 @@
 //! ```shell
 //! cargo add ratatui-core
 //! ```
+//!
+//! # Crate Organization
+//!
+//! `ratatui-core` is part of the Ratatui workspace that was modularized in version 0.30.0 to
+//! improve compilation times, API stability, and dependency management. This crate provides the
+//! foundational types and traits that other crates in the workspace depend on.
+//!
+//! **When to use `ratatui-core`:**
+//!
+//! - Building widget libraries that implement [`Widget`] or [`StatefulWidget`]
+//! - Creating lightweight applications that don't need built-in widgets
+//! - You want minimal dependencies and faster compilation times
+//! - You need maximum API stability (core types change less frequently)
+//!
+//! **When to use the main [`ratatui`] crate:**
+//!
+//! - Building applications that use built-in widgets
+//! - You want convenience and don't mind slightly longer compilation times
+//! - You need backend implementations and terminal management utilities
+//!
+//! For detailed information about the workspace organization, see [ARCHITECTURE.md].
+//!
+//! [`ratatui`]: https://crates.io/crates/ratatui
+//! [`Widget`]: widgets::Widget
+//! [`StatefulWidget`]: widgets::StatefulWidget
+//! [ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
 #![cfg_attr(feature = "document-features", doc = "\n## Features")]
 #![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
 //!

ratatui-crossterm/README.md

@@ -7,4 +7,25 @@ the [Crossterm] crate to interact with the terminal.
 
 [Crossterm]: https://crates.io/crates/crossterm
 
+## Crate Organization
+
+`ratatui-crossterm` is part of the Ratatui workspace that was modularized in version 0.30.0.
+This crate provides the [Crossterm] backend implementation for Ratatui.
+
+**When to use `ratatui-crossterm`:**
+
+- You need fine-grained control over dependencies
+- Building a widget library that needs backend functionality
+- You want to use only the Crossterm backend without other backends
+
+**When to use the main [`ratatui`] crate:**
+
+- Building applications (recommended - includes crossterm backend by default)
+- You want the convenience of having everything available
+
+For detailed information about the workspace organization, see [ARCHITECTURE.md].
+
+[`ratatui`]: https://crates.io/crates/ratatui
+[ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
+
 <!-- cargo-rdme end -->

ratatui-crossterm/src/lib.rs

@@ -10,6 +10,27 @@
 //! the [Crossterm] crate to interact with the terminal.
 //!
 //! [Crossterm]: https://crates.io/crates/crossterm
+//!
+//! # Crate Organization
+//!
+//! `ratatui-crossterm` is part of the Ratatui workspace that was modularized in version 0.30.0.
+//! This crate provides the [Crossterm] backend implementation for Ratatui.
+//!
+//! **When to use `ratatui-crossterm`:**
+//!
+//! - You need fine-grained control over dependencies
+//! - Building a widget library that needs backend functionality
+//! - You want to use only the Crossterm backend without other backends
+//!
+//! **When to use the main [`ratatui`] crate:**
+//!
+//! - Building applications (recommended - includes crossterm backend by default)
+//! - You want the convenience of having everything available
+//!
+//! For detailed information about the workspace organization, see [ARCHITECTURE.md].
+//!
+//! [`ratatui`]: https://crates.io/crates/ratatui
+//! [ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
 #![cfg_attr(feature = "document-features", doc = "\n## Features")]
 #![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
 

ratatui-macros/README.md

@@ -115,6 +115,28 @@ let table = Table::new(rows, constraints![==20, *=1]);
 Contributions to `ratatui-macros` are welcome! Whether it's submitting a bug report, a feature
 request, or a pull request, all forms of contributions are valued and appreciated.
 
+## Crate Organization
+
+`ratatui-macros` is part of the Ratatui workspace that was modularized in version 0.30.0.
+This crate provides declarative macros to reduce boilerplate when working with
+Ratatui.
+
+**When to use `ratatui-macros`:**
+
+- You want to reduce boilerplate when creating styled text, layouts, or tables
+- You prefer macro-based syntax for creating UI elements
+- You need compile-time generation of repetitive UI code
+
+**When to use the main [`ratatui`] crate:**
+
+- Building applications (recommended - includes macros when the `macros` feature is enabled)
+- You want the convenience of having everything available
+
+For detailed information about the workspace organization, see [ARCHITECTURE.md].
+
+[`ratatui`]: https://crates.io/crates/ratatui
+[ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
+
 [Crates.io badge]: https://img.shields.io/crates/v/ratatui-macros?logo=rust&style=flat-square
 [License badge]: https://img.shields.io/crates/l/ratatui-macros
 [CI Badge]:

ratatui-macros/src/lib.rs

@@ -121,6 +121,28 @@
 //! Contributions to `ratatui-macros` are welcome! Whether it's submitting a bug report, a feature
 //! request, or a pull request, all forms of contributions are valued and appreciated.
 //!
+//! # Crate Organization
+//!
+//! `ratatui-macros` is part of the Ratatui workspace that was modularized in version 0.30.0.
+//! This crate provides declarative macros to reduce boilerplate when working with
+//! Ratatui.
+//!
+//! **When to use `ratatui-macros`:**
+//!
+//! - You want to reduce boilerplate when creating styled text, layouts, or tables
+//! - You prefer macro-based syntax for creating UI elements
+//! - You need compile-time generation of repetitive UI code
+//!
+//! **When to use the main [`ratatui`] crate:**
+//!
+//! - Building applications (recommended - includes macros when the `macros` feature is enabled)
+//! - You want the convenience of having everything available
+//!
+//! For detailed information about the workspace organization, see [ARCHITECTURE.md].
+//!
+//! [`ratatui`]: https://crates.io/crates/ratatui
+//! [ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
+//!
 //! [Crates.io badge]: https://img.shields.io/crates/v/ratatui-macros?logo=rust&style=flat-square
 //! [License badge]: https://img.shields.io/crates/l/ratatui-macros
 //! [CI Badge]:

ratatui-termion/README.md

@@ -8,4 +8,26 @@ the [Termion] crate to interact with the terminal.
 [`Backend`]: ratatui_core::backend::Backend
 [Termion]: https://docs.rs/termion
 
+## Crate Organization
+
+`ratatui-termion` is part of the Ratatui workspace that was modularized in version 0.30.0.
+This crate provides the [Termion] backend implementation for Ratatui.
+
+**When to use `ratatui-termion`:**
+
+- You need fine-grained control over dependencies
+- Building a widget library that needs backend functionality
+- You want to use only the Termion backend without other backends
+- You prefer Termion's Unix-focused approach
+
+**When to use the main [`ratatui`] crate:**
+
+- Building applications (recommended - includes termion backend when enabled)
+- You want the convenience of having everything available
+
+For detailed information about the workspace organization, see [ARCHITECTURE.md].
+
+[`ratatui`]: https://crates.io/crates/ratatui
+[ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
+
 <!-- cargo-rdme end -->

ratatui-termion/src/lib.rs

@@ -11,6 +11,28 @@
 //!
 //! [`Backend`]: ratatui_core::backend::Backend
 //! [Termion]: https://docs.rs/termion
+//!
+//! # Crate Organization
+//!
+//! `ratatui-termion` is part of the Ratatui workspace that was modularized in version 0.30.0.
+//! This crate provides the [Termion] backend implementation for Ratatui.
+//!
+//! **When to use `ratatui-termion`:**
+//!
+//! - You need fine-grained control over dependencies
+//! - Building a widget library that needs backend functionality
+//! - You want to use only the Termion backend without other backends
+//! - You prefer Termion's Unix-focused approach
+//!
+//! **When to use the main [`ratatui`] crate:**
+//!
+//! - Building applications (recommended - includes termion backend when enabled)
+//! - You want the convenience of having everything available
+//!
+//! For detailed information about the workspace organization, see [ARCHITECTURE.md].
+//!
+//! [`ratatui`]: https://crates.io/crates/ratatui
+//! [ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
 #![cfg_attr(feature = "document-features", doc = "\n## Features")]
 #![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
 

ratatui-termwiz/README.md

@@ -8,4 +8,26 @@ the [Termwiz] crate to interact with the terminal.
 [`Backend`]: trait.Backend.html
 [Termwiz]: https://crates.io/crates/termwiz
 
+## Crate Organization
+
+`ratatui-termwiz` is part of the Ratatui workspace that was modularized in version 0.30.0.
+This crate provides the [Termwiz] backend implementation for Ratatui.
+
+**When to use `ratatui-termwiz`:**
+
+- You need fine-grained control over dependencies
+- Building a widget library that needs backend functionality
+- You want to use only the Termwiz backend without other backends
+- You need Termwiz's advanced terminal capabilities
+
+**When to use the main [`ratatui`] crate:**
+
+- Building applications (recommended - includes termwiz backend when enabled)
+- You want the convenience of having everything available
+
+For detailed information about the workspace organization, see [ARCHITECTURE.md].
+
+[`ratatui`]: https://crates.io/crates/ratatui
+[ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
+
 <!-- cargo-rdme end -->

ratatui-termwiz/src/lib.rs

@@ -11,6 +11,28 @@
 //!
 //! [`Backend`]: trait.Backend.html
 //! [Termwiz]: https://crates.io/crates/termwiz
+//!
+//! # Crate Organization
+//!
+//! `ratatui-termwiz` is part of the Ratatui workspace that was modularized in version 0.30.0.
+//! This crate provides the [Termwiz] backend implementation for Ratatui.
+//!
+//! **When to use `ratatui-termwiz`:**
+//!
+//! - You need fine-grained control over dependencies
+//! - Building a widget library that needs backend functionality
+//! - You want to use only the Termwiz backend without other backends
+//! - You need Termwiz's advanced terminal capabilities
+//!
+//! **When to use the main [`ratatui`] crate:**
+//!
+//! - Building applications (recommended - includes termwiz backend when enabled)
+//! - You want the convenience of having everything available
+//!
+//! For detailed information about the workspace organization, see [ARCHITECTURE.md].
+//!
+//! [`ratatui`]: https://crates.io/crates/ratatui
+//! [ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
 #![cfg_attr(feature = "document-features", doc = "\n## Features")]
 #![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
 

ratatui-widgets/README.md

@@ -70,6 +70,28 @@ cargo add ratatui-widgets
 
 All these widgets are re-exported directly under `ratatui::widgets` in the `ratatui` crate.
 
+## Crate Organization
+
+`ratatui-widgets` is part of the Ratatui workspace that was modularized in version 0.30.0.
+This crate contains all the built-in widget implementations that were previously part of the
+main `ratatui` crate.
+
+**When to use `ratatui-widgets`:**
+
+- Building widget libraries that need to compose with built-in widgets
+- You want finer-grained dependencies and only need specific widgets
+- Creating custom widgets that extend or wrap the built-in ones
+
+**When to use the main [`ratatui`] crate:**
+
+- Building applications (recommended - includes everything you need)
+- You want the convenience of having all widgets available
+
+For detailed information about the workspace organization, see [ARCHITECTURE.md].
+
+[`ratatui`]: https://crates.io/crates/ratatui
+[ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
+
 ## Contributing
 
 Contributions are welcome! Please open an issue or submit a pull request on GitHub. For more

ratatui-widgets/src/lib.rs

@@ -69,6 +69,28 @@
 //! [`Tabs`]: crate::tabs::Tabs
 //!
 //! All these widgets are re-exported directly under `ratatui::widgets` in the `ratatui` crate.
+//!
+//! # Crate Organization
+//!
+//! `ratatui-widgets` is part of the Ratatui workspace that was modularized in version 0.30.0.
+//! This crate contains all the built-in widget implementations that were previously part of the
+//! main `ratatui` crate.
+//!
+//! **When to use `ratatui-widgets`:**
+//!
+//! - Building widget libraries that need to compose with built-in widgets
+//! - You want finer-grained dependencies and only need specific widgets
+//! - Creating custom widgets that extend or wrap the built-in ones
+//!
+//! **When to use the main [`ratatui`] crate:**
+//!
+//! - Building applications (recommended - includes everything you need)
+//! - You want the convenience of having all widgets available
+//!
+//! For detailed information about the workspace organization, see [ARCHITECTURE.md].
+//!
+//! [`ratatui`]: https://crates.io/crates/ratatui
+//! [ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
 #![cfg_attr(feature = "document-features", doc = "\n## Features")]
 #![cfg_attr(feature = "document-features", doc = document_features::document_features!())]
 //!

ratatui/src/lib.rs

@@ -21,8 +21,6 @@
 //!
 //! </div>
 //!
-//! # Ratatui
-//!
 //! [Ratatui][Ratatui Website] is a crate for cooking up terminal user interfaces in Rust. It is a
 //! lightweight library that provides a set of [widgets](`widgets`) and utilities to build complex
 //! Rust TUIs. Ratatui was forked from the [tui-rs] crate in 2023 in order to continue its
@@ -66,7 +64,7 @@
 //! various [Examples]. There are also several starter templates available in the [templates]
 //! repository.
 //!
-//! ## Other documentation
+//! # Other documentation
 //!
 //! - [Ratatui Website] - explains the library's concepts and provides step-by-step tutorials
 //! - [Ratatui Forum][Forum] - a place to ask questions and discuss the library
@@ -79,7 +77,27 @@
 //! You can also watch the [FOSDEM 2024 talk] about Ratatui which gives a brief introduction to
 //! terminal user interfaces and showcases the features of Ratatui, along with a hello world demo.
 //!
-//! ## Introduction
+//! # Crate Organization
+//!
+//! Starting with Ratatui 0.30.0, the project was reorganized into a modular workspace to improve
+//! compilation times, API stability, and dependency management. Most applications should continue
+//! using this main `ratatui` crate, which re-exports everything for convenience:
+//!
+//! - **[`ratatui`](crate)**: Main crate with complete functionality (recommended for apps)
+//! - **[`ratatui-core`]**: Core traits and types for widget libraries
+//! - **[`ratatui-widgets`]**: Built-in widget implementations
+//! - **Backend crates**: [`ratatui-crossterm`], [`ratatui-termion`], [`ratatui-termwiz`]
+//! - **[`ratatui-macros`]**: Macros for simplifying the boilerplate
+//!
+//! **For application developers**: No changes needed - continue using `ratatui` as before.
+//!
+//! **For widget library authors**: Consider depending on [`ratatui-core`] instead of the full
+//! `ratatui` crate for better API stability and reduced dependencies.
+//!
+//! See [ARCHITECTURE.md] for detailed information about the crate organization and design
+//! decisions.
+//!
+//! # Introduction
 //!
 //! Ratatui is based on the principle of immediate rendering with intermediate buffers. This means
 //! that for each frame, your app must render all [`widgets`] that are supposed to be part of the
@@ -99,7 +117,7 @@
 //!   - Handles input events
 //! - Restore the terminal state
 //!
-//! ### Initialize and restore the terminal
+//! ## Initialize and restore the terminal
 //!
 //! The [`Terminal`] type is the main entry point for any Ratatui application. It is generic over a
 //! a choice of [`Backend`] implementations that each provide functionality to draw frames, clear
@@ -126,7 +144,7 @@
 //! See the [`backend` module] and the [Backends] section of the [Ratatui Website] for more info on
 //! the alternate screen and raw mode.
 //!
-//! ### Drawing the UI
+//! ## Drawing the UI
 //!
 //! Drawing the UI is done by calling the [`Terminal::draw`] method on the terminal instance. This
 //! method takes a closure that is called with a [`Frame`] instance. The [`Frame`] provides the size
@@ -156,7 +174,7 @@
 //! # fn handle_events() -> std::io::Result<bool> { Ok(false) }
 //! ```
 //!
-//! ### Handling events
+//! ## Handling events
 //!
 //! Ratatui does not include any input handling. Instead event handling can be implemented by
 //! calling backend library methods directly. See the [Handling Events] section of the [Ratatui
@@ -180,7 +198,7 @@
 //! }
 //! ```
 //!
-//! ## Layout
+//! # Layout
 //!
 //! The library comes with a basic yet useful layout management object called [`Layout`] which
 //! allows you to split the available space into multiple areas and then render widgets in each
@@ -217,7 +235,7 @@
 //! Status Bar──────────────────────────────────
 //! ```
 //!
-//! ## Text and styling
+//! # Text and styling
 //!
 //! The [`Text`], [`Line`] and [`Span`] types are the building blocks of the library and are used in
 //! many places. [`Text`] is a list of [`Line`]s and a [`Line`] is a list of [`Span`]s. A [`Span`]
@@ -307,6 +325,13 @@
 //! [Termion]: https://crates.io/crates/termion
 //! [Termwiz]: https://crates.io/crates/termwiz
 //! [tui-rs]: https://crates.io/crates/tui
+//! [`ratatui-core`]: https://crates.io/crates/ratatui-core
+//! [`ratatui-widgets`]: https://crates.io/crates/ratatui-widgets
+//! [`ratatui-crossterm`]: https://crates.io/crates/ratatui-crossterm
+//! [`ratatui-termion`]: https://crates.io/crates/ratatui-termion
+//! [`ratatui-termwiz`]: https://crates.io/crates/ratatui-termwiz
+//! [`ratatui-macros`]: https://crates.io/crates/ratatui-macros
+//! [ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
 //! [GitHub Sponsors]: https://github.com/sponsors/ratatui
 //! [Crate Badge]: https://img.shields.io/crates/v/ratatui?logo=rust&style=flat-square&logoColor=E05D44&color=E05D44
 //! [License Badge]: https://img.shields.io/crates/l/ratatui?style=flat-square&color=1370D3
@@ -324,6 +349,13 @@
 //! [Forum Badge]: https://img.shields.io/discourse/likes?server=https%3A%2F%2Fforum.ratatui.rs&style=flat-square&logo=discourse&label=forum&color=C43AC3
 //! [Forum]: https://forum.ratatui.rs
 //! [Sponsors Badge]: https://img.shields.io/github/sponsors/ratatui?logo=github&style=flat-square&color=1370D3
+//! [`ratatui-core`]: https://crates.io/crates/ratatui-core
+//! [`ratatui-widgets`]: https://crates.io/crates/ratatui-widgets
+//! [`ratatui-crossterm`]: https://crates.io/crates/ratatui-crossterm
+//! [`ratatui-termion`]: https://crates.io/crates/ratatui-termion
+//! [`ratatui-termwiz`]: https://crates.io/crates/ratatui-termwiz
+//! [`ratatui-macros`]: https://crates.io/crates/ratatui-macros
+//! [ARCHITECTURE.md]: https://github.com/ratatui/ratatui/blob/main/ARCHITECTURE.md
 
 #![warn(clippy::std_instead_of_core)]
 #![warn(clippy::std_instead_of_alloc)]