Merge pull request #205 from maxnorm/feat/doc

Feat/doc

Author: mudgen

README.md

@@ -1,4 +1,5 @@
-# Compose
+# Compose 
+![Coverage](https://img.shields.io/badge/coverage-63%25-yellow) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Discord](https://img.shields.io/badge/Discord-Join%20Chat-blue.svg)](https://discord.gg/DCBD2UKbxc)
 
 > **⚠️ Early Stage**: Compose is currently in development and only available to contributors. It is **NOT production ready**.
 
@@ -14,14 +15,12 @@ Compose is a smart contract library that helps developers create smart contract
 
 The project actively evolves based on community input—[tell us](https://github.com/Perfect-Abstractions/Compose/discussions/108) what you'd like Compose to do for you.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Discord](https://img.shields.io/badge/Discord-Join%20Chat-blue.svg)](https://discord.gg/DCBD2UKbxc)
 
 ## Why Compose is Different
 
 **Forget traditional smart contract design patterns**—Compose takes a radically different approach.
 
-We build high-quality smart contracts by **intentionally restricting Solidity features** and following conventions designed specifically for smart contracts. This is **Smart Contract Oriented Programming (SCOP)**.
+We build high-quality smart contracts by <a href="https://compose.diamonds/docs/design/banned-solidity-features">**intentionally restricting Solidity features**</a> and following conventions designed specifically for smart contracts. This is **Smart Contract Oriented Programming (SCOP)**.
 
 ### Core Philosophy
 

lib/forge-std

@@ -6,7 +6,7 @@ description: How to design Compose facets and libraries for composition.
 
 Here are guidelines and rules to create composable facets.
 
-Compose replaces source-code inheritance with onchain composition. Facets are the building blocks; diamonds wire them together.
+Compose replaces source-code inheritance with on-chain composition. Facets are the building blocks; diamonds wire them together.
 
 We focus on building **small, independent, and easy-to-read facets**. Each facet is deployed once, then reused and combined with other facets to form complete, modular smart contract systems.
 
@@ -63,4 +63,4 @@ For example, `ERC721EnumerableFacet` does not extend `ERC721Facet` because enume
 
 *** 
 
-This level of composability strikes the right balance: it enables highly organized, modular, and understandable onchain smart contract systems.
+This level of composability strikes the right balance: it enables highly organized, modular, and understandable on-chain smart contract systems.

website/docs/_introOld.mdx

@@ -5,18 +5,53 @@ description: Overview for how Compose is designed
 sidebar_class_name: hidden
 ---
 
-This section contains the guidelines and rules for developing new facets and Solidity libraries in **Compose**.
-
-We focus on building small, independent, and easy-to-understand facets. Each facet is designed to be deployed once, then reused and composed seamlessly with others to form complete smart contract systems.
+import DocCard, { DocCardGrid } from '@site/src/components/docs/DocCard';
+import DocSubtitle from '@site/src/components/docs/DocSubtitle';
 
+<DocSubtitle>
+This section contains the guidelines and rules for developing new facets and Solidity libraries in **Compose**. We focus on building small, independent, and easy-to-understand facets. Each facet is designed to be deployed once, then reused and composed seamlessly with others to form complete smart contract systems.
+</DocSubtitle>
 ## Articles in this section
 
-- [Compose Is Written to Be Read](./written-to-be-read) — Emphasizes clarity first: keep facets and libraries self-contained, ordered top-to-bottom, and easy to read. Avoid clever abstractions that reduce readability.  
-
-- [Repeat Yourself](./repeat-yourself) — Prefer duplication over indirection when it improves clarity.
-  
-- [Banned Solidity Features](./banned-solidity-features) — Solidity Features we don't use in facets/libraries.
-
-- [Design for Composition](./design-for-composition) — Facets replace inheritance with onchain composition. Keep facets small and self-contained, pair each facet with a library, reuse storage layouts carefully, and extend behavior by adding new facets.
+<DocCardGrid columns={2}>
+  <DocCard
+    title="Compose Is Written to Be Read"
+    description="Emphasizes clarity first: keep facets and libraries self-contained, ordered top-to-bottom, and easy to read. Avoid clever abstractions that reduce readability."
+    href="./written-to-be-read"
+    icon={<Icon name="book" size={28} />}
+    size="medium"
+  />
+  <DocCard
+    title="Repeat Yourself"
+    description="Prefer duplication over indirection when it improves clarity."
+    href="./repeat-yourself"
+    icon={<Icon name="cycle" size={28} />}
+    size="medium"
+  />
+  <DocCard
+    title="Banned Solidity Features"
+    description="Solidity Features we don't use in facets/libraries."
+    href="./banned-solidity-features"
+    icon={<Icon name="no-entry" size={28} />}
+    size="medium"
+  />
+  <DocCard
+    title="Design for Composition"
+    description="Build your own facets that work seamlessly with existing Compose facets using shared storage layouts and internal logic through Solidity libraries."
+    href="./design-for-composition"
+    icon={<Icon name="composition" size={28} />}
+    size="medium"
+  />
+  <DocCard
+    title="Maintain Compatibility"
+    description="Learn how facets and libraries work together through shared storage to build composable systems."
+    href="./maintain-compatibility"
+    icon={<Icon name="puzzle" size={28} />}
+    size="medium"
+  />
+</DocCardGrid>
 
-- [Maintain Compatibility](./maintain-compatibility) — Build facets that work with existing standards, libraries, and systems and exhibit expected behavior.
+:::warning[Early Development]
+Compose is still in early development and currently available only to contributors.
+It is not **production-ready** — use it in test or development environments only.
+:::