Polish docs UI: layout, feedback aside, homepage code showcase, and footer

SECURITY.md

@@ -4,12 +4,19 @@ If you discover a security vulnerability, report it PRIVATELY with the maintaine
 
 ## Supported Versions
 
-Compose is currently under active development.</br>We actively support these versions:
+Compose is currently under active development. It is **NOT production ready.** and we may still make breaking changes to any part of the codebase.
+
+</br>**We actively support these versions:**
 
 | Version | Supported          |
 | ------- | ------------------ |
 | latest (main)   | :white_check_mark: |
 
+for both packages:
+
+- [`@perfect-abstractions/compose`](https://www.npmjs.com/package/@perfect-abstractions/compose)
+- [`@perfect-abstractions/compose-cli`](https://www.npmjs.com/package/@perfect-abstractions/compose-cli)
+
 ## Reporting a Vulnerability
 
 Emails: </br>

website/docs/contribution/documentation/all-components.mdx

@@ -1766,13 +1766,14 @@ Smooth counting animation for numbers.
 
 ### WasThisHelpful
 
-Feedback widget for collecting user feedback on documentation pages.
+Feedback widget for documentation pages. The **`aside`** variant is injected automatically at the bottom of the doc TOC column on desktop (and inline above the page pager on mobile) via the swizzled doc layout. Use the **`card`** variant when you want an embedded demo in MDX.
 
 <Badge variant="success">Feedback</Badge>
 
 #### Live Example
 
 <WasThisHelpful
+  variant="card"
   pageId="all-components-demo"
   onSubmit={(feedback) => console.log(feedback)}
 />
@@ -1782,36 +1783,37 @@ Feedback widget for collecting user feedback on documentation pages.
 <PropertyTable 
   showRequired={false}
   properties={[
-    { name: 'pageId', type: 'string', description: 'Unique page identifier' },
-    { name: 'onSubmit', type: 'Function', description: 'Callback when feedback submitted' }
+    { name: 'variant', type: "'card' | 'aside'", description: 'Layout: card (MDX demos) or aside (global doc rail; used by DocPageAside)' },
+    { name: 'pageId', type: 'string', description: 'Optional stable id for analytics' },
+    { name: 'permalink', type: 'string', description: 'Doc path (set automatically in global aside)' },
+    { name: 'title', type: 'string', description: 'Doc title for PostHog breakdowns' },
+    { name: 'onSubmit', type: 'Function', description: 'Optional callback when feedback is submitted (PostHog still captures)' }
   ]}
 />
 
 #### Usage
 
 ```jsx
 <WasThisHelpful
+  variant="card"
   pageId="unique-page-id"
   onSubmit={(feedback) => {
-    // Handle feedback
+    // Optional: PostHog events docs_helpful_vote / docs_helpful_submit still fire
     console.log(feedback);
   }}
 />
 ```
 
 #### Best Practices
 
-- Place at bottom of pages
-- Use unique pageId per page
-- Integrate with analytics
-- Respond to feedback
+- Prefer the built-in global aside on real docs; use `variant="card"` only for examples
+- Optional `pageId` helps PostHog filters; global aside uses permalink and title from the doc
+- Events: `docs_helpful_vote`, `docs_helpful_submit` (when PostHog is enabled)
 
 #### When to Use
 
-- End of documentation pages
-- After tutorials
-- Product documentation
-- Help articles
+- `variant="card"` in MDX examples or special pages without the global doc layout
+- Most real docs rely on the built-in aside (no manual component needed)
 
 ---
 
@@ -2209,6 +2211,4 @@ import Icon from '@site/src/components/ui/Icon';
 
 ---
 
-<WasThisHelpful pageId="all-components-reference" />
-
 <LastUpdated date={new Date().toISOString()} />

website/docs/design/index.mdx

@@ -18,35 +18,30 @@ This section contains the guidelines and rules for developing new facets and Sol
     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="/docs/design/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="/docs/design/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="/docs/design/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="/docs/design/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="/docs/design/maintain-compatibility"
-    icon={<Icon name="puzzle" size={28} />}
     size="medium"
   />
 </DocCardGrid>