@astryxdesign/cli 0.1.0-canary.7847c5f → 0.1.0-canary.797f761

package/docs/getting-started.doc.mjs

@@ -88,7 +88,7 @@ import {VStack} from '@astryxdesign/core/Layout';
 export default function Page() {
   return (
     <VStack gap={2}>
-      <Button label="Hello Astryx" onClick={() => alert('Hi!')} />
+      <Button label="Hello XDS" onClick={() => alert('Hi!')} />
     </VStack>
   );
 }`,
@@ -96,11 +96,11 @@ export default function Page() {
       ],
     },
     {
-      title: 'Customize with StyleX',
+      title: 'Customize with xstyle',
       content: [
         {
           type: 'prose',
-          text: 'Astryx components support various styling solutions, from plain CSS and `className` to Tailwind and CSS-in-JS. See the [styling docs](/docs/styling) for the full guide. Astryx also has a deep integration with [StyleX](https://stylexjs.com/), an atomic CSS-in-JS library: create styles with `stylex.create()` and pass them to components with the `xstyle` prop.',
+          text: 'Every component accepts an `xstyle` prop for StyleX style overrides created via `stylex.create()`.',
         },
         {
           type: 'code',
@@ -127,19 +127,19 @@ const overrides = stylex.create({
           type: 'table',
           headers: ['Example', 'Stack', 'Path'],
           rows: [
-            ['Next.js', 'Next.js + theme CSS', '[apps/example-nextjs](https://github.com/facebook/astryx/tree/main/apps/example-nextjs)'],
-            ['Next.js + StyleX', 'Next.js + StyleX for custom styles', '[apps/example-nextjs-stylex](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-stylex)'],
-            ['Next.js + Tailwind', 'Next.js + Tailwind bridge', '[apps/example-nextjs-tailwind](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-tailwind)'],
-            ['Next.js Source', 'Next.js importing from source', '[apps/example-nextjs-source](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-source)'],
-            ['Vite', 'Vite', '[apps/example-vite](https://github.com/facebook/astryx/tree/main/apps/example-vite)'],
+            ['Next.js', 'Next.js + theme CSS', 'apps/example-nextjs'],
+            ['Next.js + StyleX', 'Next.js + StyleX for custom styles', 'apps/example-nextjs-stylex'],
+            ['Next.js + Tailwind', 'Next.js + Tailwind bridge', 'apps/example-nextjs-tailwind'],
+            ['Next.js Source', 'Next.js importing from source', 'apps/example-nextjs-source'],
+            ['Vite', 'Vite', 'apps/example-vite'],
           ],
         },
         {
           type: 'code',
           lang: 'bash',
           label: 'Clone and run an example',
-          code: `git clone https://github.com/facebook/astryx.git
-cd astryx/apps/example-nextjs
+          code: `git clone https://github.com/facebookexperimental/xds.git
+cd xds/apps/example-nextjs
 pnpm install
 pnpm dev`,
         },
@@ -157,7 +157,7 @@ pnpm dev`,
           lang: 'json',
           label: 'package.json',
           code: `"scripts": {
-  "astryx": "node node_modules/@astryxdesign/cli/bin/astryx.mjs"
+  "xds": "node node_modules/@astryxdesign/cli/bin/astryx.mjs"
 }`,
         },
         {

package/docs/styling.doc.mjs

@@ -22,8 +22,9 @@ export const docs = {
           type: 'table',
           headers: ['Approach', 'Use for', 'Example'],
           rows: [
-            ['StyleX', 'Component-specific overrides, reusable styles, pseudo-classes, and typed tokens', 'const styles = stylex.create(...); <Button xstyle={styles.save} />'],
+            ['xstyle prop', 'Overriding a specific component', 'xstyle={styles.override}'],
             ['Tailwind utilities', 'Layout, wrappers, and utility styling', 'className="flex gap-3 p-4"'],
+            ['stylex.create', 'Reusable styles, pseudo-classes, typed tokens', 'stylex.create({ card: { ... } })'],
             ['className', 'Integrating with external CSS or Tailwind on components', 'className="my-card shadow-lg"'],
             ['Styling-library token aliases', 'Keeping Panda, Chakra, MUI, Emotion, styled-components, UnoCSS, CSS Modules, or Sass in sync with the system', "colors.surface = 'var(--color-background-surface)'"],
           ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.0-canary.7847c5f",
+  "version": "0.1.0-canary.797f761",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -54,9 +54,9 @@
     "jscodeshift": "^17.3.0"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.1.0-canary.7847c5f",
-    "@astryxdesign/lab": "0.1.0-canary.7847c5f",
-    "@astryxdesign/theme-neutral": "0.1.0-canary.7847c5f"
+    "@astryxdesign/core": "0.1.0-canary.797f761",
+    "@astryxdesign/lab": "0.1.0-canary.797f761",
+    "@astryxdesign/theme-neutral": "0.1.0-canary.797f761"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/core": {
@@ -70,9 +70,9 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/core": "0.1.0-canary.7847c5f",
-    "@astryxdesign/lab": "0.1.0-canary.7847c5f",
-    "@astryxdesign/theme-neutral": "0.1.0-canary.7847c5f"
+    "@astryxdesign/core": "0.1.0-canary.797f761",
+    "@astryxdesign/lab": "0.1.0-canary.797f761",
+    "@astryxdesign/theme-neutral": "0.1.0-canary.797f761"
   },
   "scripts": {
     "astryx": "node bin/astryx.mjs",

package/src/commands/init.mjs

@@ -248,7 +248,7 @@ export function registerInit(program) {
       humanLog('    2. Optionally add a theme:');
       humanLog("       import { neutralTheme } from '@astryxdesign/theme-neutral'");
       humanLog('       <Theme theme={neutralTheme}>...</Theme>');
-      humanLog(`    3. ${run} astryx --help for all commands`);
+      humanLog(`    3. ${run} xds --help for all commands`);
       humanLog('');
     });
 }

package/src/utils/package-manager.mjs

@@ -4,7 +4,7 @@
  * @file Detect the project's package manager from lockfiles.
  *
  * Returns the correct command prefix for running package binaries
- * (e.g. 'npx astryx', 'yarn astryx', 'pnpm exec astryx').
+ * (e.g. 'npx xds', 'yarn xds', 'pnpm exec xds').
  */
 
 import * as fs from 'node:fs';

package/templates/pages/documentation/page.tsx

@@ -3,23 +3,24 @@
 'use client';
 
 import * as stylex from '@stylexjs/stylex';
-import {Heading, Text} from '@astryxdesign/core/Text';
+import {
+  SideNav,
+  SideNavHeading,
+  SideNavItem,
+  SideNavSection,
+} from '@astryxdesign/core/SideNav';
+import {Text} from '@astryxdesign/core/Text';
 import {Button} from '@astryxdesign/core/Button';
 import {Card} from '@astryxdesign/core/Card';
-import {ClickableCard} from '@astryxdesign/core/ClickableCard';
 import {HStack, VStack, StackItem} from '@astryxdesign/core/Stack';
-import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
+import {Layout, LayoutContent, LayoutPanel} from '@astryxdesign/core/Layout';
 import {Grid} from '@astryxdesign/core/Grid';
 import {radiusVars} from '@astryxdesign/core/theme/tokens.stylex';
 
 const styles = stylex.create({
   previewCard: {
-    borderRadius: radiusVars['--radius-element'],
-  },
-  // Negative margin offsets each card's 8px padding so the grid content stays
-  // visually aligned while giving every card a padded hover/click target.
-  cardGrid: {
-    margin: -8,
+    borderRadius: radiusVars['--radius-container'],
+    cursor: 'pointer',
   },
 });
 
@@ -212,12 +213,30 @@ const COMPONENT_CATEGORIES = [
 export default function DocumentationOverviewPage() {
   return (
     <Layout
-      height="auto"
+      height="fill"
       contentWidth={1200}
+      start={
+        <LayoutPanel hasDivider padding={0}>
+          <SideNav header={<SideNavHeading heading="Product Name" />}>
+            <SideNavSection title="Navigation" isHeaderHidden>
+              <SideNavItem label="Home" isSelected />
+              <SideNavItem label="Getting started" />
+            </SideNavSection>
+
+            {COMPONENT_CATEGORIES.map(category => (
+              <SideNavSection key={category.label} title={category.label}>
+                {category.items.map(item => (
+                  <SideNavItem key={item.key} label={item.name} />
+                ))}
+              </SideNavSection>
+            ))}
+          </SideNav>
+        </LayoutPanel>
+      }
       content={
         <LayoutContent padding={8}>
           <VStack gap={10}>
-            <Card variant="gray" padding={10}>
+            <Card variant="cyan" padding={10}>
               <HStack gap={8} vAlign="center">
                 <StackItem size="fill">
                   <VStack gap={4}>
@@ -227,7 +246,11 @@ export default function DocumentationOverviewPage() {
                       beautiful, accessible products.
                     </Text>
                     <HStack>
-                      <Button label="Get started" variant="primary" size="lg" />
+                      <Button
+                        label="Get started"
+                        variant="primary"
+                        size="lg"
+                      />
                     </HStack>
                   </VStack>
                 </StackItem>
@@ -237,35 +260,25 @@ export default function DocumentationOverviewPage() {
 
             {COMPONENT_CATEGORIES.map(category => (
               <VStack key={category.label} gap={4}>
-                <Heading level={2}>{category.label}</Heading>
-                <Grid
-                  columns={{minWidth: 260}}
-                  gap={2}
-                  xstyle={styles.cardGrid}>
+                <Text type="display-2">{category.label}</Text>
+                <Grid columns={{minWidth: 260}} gap={8}>
                   {category.items.map(item => (
-                    <ClickableCard
-                      key={item.key}
-                      label={`Open ${item.name}`}
-                      onClick={() => {}}
-                      variant="transparent"
-                      padding={2}>
-                      <VStack gap={3}>
-                        <Card
-                          variant="muted"
-                          padding={0}
-                          minHeight={160}
-                          xstyle={styles.previewCard}
-                        />
-                        <VStack gap={0.5}>
-                          <Text type="body" weight="bold">
-                            {item.name}
-                          </Text>
-                          <Text type="body" color="secondary" maxLines={3}>
-                            {item.desc}
-                          </Text>
-                        </VStack>
+                    <VStack key={item.key} gap={3}>
+                      <Card
+                        variant="muted"
+                        padding={0}
+                        minHeight={160}
+                        xstyle={styles.previewCard}
+                      />
+                      <VStack gap={0.5}>
+                        <Text type="body" weight="bold">
+                          {item.name}
+                        </Text>
+                        <Text type="body" color="secondary">
+                          {item.desc}
+                        </Text>
                       </VStack>
-                    </ClickableCard>
+                    </VStack>
                   ))}
                 </Grid>
               </VStack>

package/templates/pages/documentation-design/page.tsx

@@ -2,8 +2,14 @@
 
 'use client';
 
-import {useCallback, useState, useMemo} from 'react';
+import {useState, useMemo} from 'react';
 import * as stylex from '@stylexjs/stylex';
+import {
+  SideNav,
+  SideNavHeading,
+  SideNavItem,
+  SideNavSection,
+} from '@astryxdesign/core/SideNav';
 import {Heading, Text} from '@astryxdesign/core/Text';
 import {Button} from '@astryxdesign/core/Button';
 import {IconButton} from '@astryxdesign/core/IconButton';
@@ -14,10 +20,8 @@ import {Token} from '@astryxdesign/core/Token';
 import {Banner} from '@astryxdesign/core/Banner';
 import {CodeBlock} from '@astryxdesign/core/CodeBlock';
 import {TabList, Tab} from '@astryxdesign/core/TabList';
-import {Selector} from '@astryxdesign/core/Selector';
 import {HStack, VStack, StackItem} from '@astryxdesign/core/Stack';
 import {Layout, LayoutContent, LayoutPanel} from '@astryxdesign/core/Layout';
-import {useMediaQuery} from '@astryxdesign/core/hooks';
 import {Dialog, DialogHeader} from '@astryxdesign/core/Dialog';
 import {Divider} from '@astryxdesign/core/Divider';
 import {Tooltip} from '@astryxdesign/core/Tooltip';
@@ -25,7 +29,6 @@ import {Table, pixel} from '@astryxdesign/core/Table';
 import {Icon} from '@astryxdesign/core/Icon';
 import {Section} from '@astryxdesign/core/Section';
 import {Center} from '@astryxdesign/core/Center';
-import {Outline, type OutlineItem} from '@astryxdesign/core/Outline';
 import {
   ArrowTopRightOnSquareIcon,
   ArrowsPointingOutIcon,
@@ -34,25 +37,8 @@ import {
 
 const styles = stylex.create({
   tabListFlush: {marginInlineStart: '-12px'},
-  outlinePanel: {
-    position: 'sticky',
-    top: 24,
-    alignSelf: 'start',
-    paddingBlockStart: 120,
-  },
 });
 
-const COMPONENT_OUTLINE_ITEMS: OutlineItem[] = [
-  {id: 'usage', label: 'Usage', level: 2},
-  {id: 'best-practices', label: 'Best practices', level: 3},
-  {id: 'examples', label: 'Examples', level: 2},
-];
-
-const COMPONENT_OUTLINE_OPTIONS = COMPONENT_OUTLINE_ITEMS.map(item => ({
-  value: item.id,
-  label: item.label,
-}));
-
 // ---------------------------------------------------------------------------
 // DialogPreview — stateful dialog preview for component previews
 // ---------------------------------------------------------------------------
@@ -507,21 +493,14 @@ function getComponentDocs(key: string) {
 // ComponentDetailView
 // ---------------------------------------------------------------------------
 
-function ComponentDetailView({activeNav}: {activeNav: string}) {
+function ComponentDetailView({
+  activeNav,
+  nav,
+}: {
+  activeNav: string;
+  nav: React.ReactNode;
+}) {
   const [exampleTabs, setExampleTabs] = useState<Record<string, string>>({});
-  const [activeId, setActiveId] = useState<string | undefined>(
-    COMPONENT_OUTLINE_ITEMS[0]?.id,
-  );
-  const isMobile = useMediaQuery('(max-width: 768px)');
-
-  const scrollToId = useCallback((id: string) => {
-    setActiveId(id);
-    const target = document.getElementById(id);
-    if (target != null) {
-      target.scrollIntoView({behavior: 'smooth', block: 'start'});
-      window.history.pushState(null, '', `#${id}`);
-    }
-  }, []);
 
   const EXAMPLE_PREVIEWS: Record<string, React.ReactNode[]> = {
     button: [
@@ -577,42 +556,25 @@ function ComponentDetailView({activeNav}: {activeNav: string}) {
 
   return (
     <Layout
-      height="auto"
+      height="fill"
       contentWidth={960}
-      end={
-        isMobile ? undefined : (
-          <LayoutPanel
-            isScrollable={false}
-            label="On this page"
-            role="complementary"
-            xstyle={styles.outlinePanel}>
-            <Outline
-              items={COMPONENT_OUTLINE_ITEMS}
-              onActiveIdChange={setActiveId}
-            />
-          </LayoutPanel>
-        )
+      start={
+        <LayoutPanel hasDivider padding={0}>
+          {nav}
+        </LayoutPanel>
       }
       content={
-        <LayoutContent isScrollable={false} padding={8}>
+        <LayoutContent padding={8}>
           <VStack gap={8}>
             <VStack gap={2}>
               <Text type="display-1">{getComponentName(activeNav)}</Text>
               <Text type="supporting" color="secondary">
                 March 30, 2026 · Updated 5:40 p.m. PST
               </Text>
-              {isMobile && (
-                <Selector
-                  label="On this page"
-                  isLabelHidden
-                  options={COMPONENT_OUTLINE_OPTIONS}
-                  value={activeId}
-                  onChange={scrollToId}
-                  width="100%"
-                />
-              )}
             </VStack>
 
+            <Divider />
+
             <Card variant="muted" padding={0}>
               <Center height={360}>
                 {COMPONENT_PREVIEWS[activeNav] ?? (
@@ -624,18 +586,13 @@ function ComponentDetailView({activeNav}: {activeNav: string}) {
             </Card>
 
             <VStack gap={4}>
-              <Heading id="usage" level={2}>
-                Usage
-              </Heading>
+              <Heading level={2}>Usage</Heading>
               <Text type="large" weight="normal">
                 {docs.usage}
               </Text>
-              <Heading id="best-practices" level={3}>
-                Best practices
-              </Heading>
+              <Heading level={3}>Best practices</Heading>
               <Table
                 data={docs.bestPractices as Record<string, unknown>[]}
-                dividers="none"
                 columns={[
                   {
                     key: 'type',
@@ -659,15 +616,14 @@ function ComponentDetailView({activeNav}: {activeNav: string}) {
                   },
                 ]}
                 density="spacious"
+                dividers="rows"
               />
             </VStack>
 
             <Divider />
 
             <VStack gap={4}>
-              <Heading id="examples" level={2}>
-                Examples
-              </Heading>
+              <Heading level={2}>Examples</Heading>
               <Text type="large" weight="normal">
                 Explore common configurations, variations, and states for this
                 component.
@@ -719,10 +675,7 @@ function ComponentDetailView({activeNav}: {activeNav: string}) {
                         <TabList
                           value={activeTab}
                           onChange={value =>
-                            setExampleTabs(prev => ({
-                              ...prev,
-                              [tabKey]: value,
-                            }))
+                            setExampleTabs(prev => ({...prev, [tabKey]: value}))
                           }
                           size="sm"
                           xstyle={styles.tabListFlush}>
@@ -732,11 +685,7 @@ function ComponentDetailView({activeNav}: {activeNav: string}) {
                         {activeTab === 'description' ? (
                           <Text type="body">{example.description}</Text>
                         ) : (
-                          <CodeBlock
-                            code={example.code}
-                            language="tsx"
-                            width="100%"
-                          />
+                          <CodeBlock code={example.code} language="tsx" />
                         )}
                       </VStack>
                     </Section>
@@ -756,5 +705,31 @@ function ComponentDetailView({activeNav}: {activeNav: string}) {
 // ---------------------------------------------------------------------------
 
 export default function DesignDocumentationPage() {
-  return <ComponentDetailView activeNav="button" />;
+  const [activePage, setActivePage] = useState<string>('button');
+
+  return (
+    <ComponentDetailView
+      activeNav={activePage}
+      nav={
+        <SideNav header={<SideNavHeading heading="Product Name" />}>
+          {COMPONENT_CATEGORIES.map(category => (
+            <SideNavSection key={category.label} title={category.label}>
+              {category.items.map(item => (
+                <SideNavItem
+                  key={item.key}
+                  label={item.name}
+                  isSelected={activePage === item.key}
+                  onClick={
+                    item.key === 'button'
+                      ? () => setActivePage(item.key)
+                      : undefined
+                  }
+                />
+              ))}
+            </SideNavSection>
+          ))}
+        </SideNav>
+      }
+    />
+  );
 }

package/templates/pages/documentation-technical/page.tsx

@@ -2,21 +2,22 @@
 
 'use client';
 
-import {useCallback, useState} from 'react';
-import * as stylex from '@stylexjs/stylex';
+import {
+  SideNav,
+  SideNavHeading,
+  SideNavItem,
+  SideNavSection,
+} from '@astryxdesign/core/SideNav';
 import {Heading, Text} from '@astryxdesign/core/Text';
 import {Button} from '@astryxdesign/core/Button';
 import {Card} from '@astryxdesign/core/Card';
 import {DropdownMenu} from '@astryxdesign/core/DropdownMenu';
 import {List, ListItem} from '@astryxdesign/core/List';
 import {CodeBlock} from '@astryxdesign/core/CodeBlock';
-import {Selector} from '@astryxdesign/core/Selector';
 import {HStack, VStack, StackItem} from '@astryxdesign/core/Stack';
 import {Layout, LayoutContent, LayoutPanel} from '@astryxdesign/core/Layout';
 import {Divider} from '@astryxdesign/core/Divider';
 import {Icon} from '@astryxdesign/core/Icon';
-import {Outline, type OutlineItem} from '@astryxdesign/core/Outline';
-import {useMediaQuery} from '@astryxdesign/core/hooks';
 import {
   SparklesIcon,
   ClipboardDocumentIcon,
@@ -27,75 +28,35 @@ import {
 // Main component
 // ---------------------------------------------------------------------------
 
-const OUTLINE_ITEMS: OutlineItem[] = [
-  {id: 'prerequisites', label: 'Prerequisites', level: 2},
-  {id: 'install-package', label: 'Install the package', level: 2},
-  {id: 'configure-theming', label: 'Configure theming', level: 2},
-  {id: 'next-steps', label: 'Next steps', level: 2},
-];
-
-const OUTLINE_OPTIONS = OUTLINE_ITEMS.map(item => ({
-  value: item.id,
-  label: item.label,
-}));
-
-const styles = stylex.create({
-  outlinePanel: {
-    position: 'sticky',
-    top: 24,
-    alignSelf: 'start',
-    paddingBlockStart: 120,
-  },
-});
-
 export default function TechnicalDocumentationPage() {
-  const [activeId, setActiveId] = useState<string | undefined>(
-    OUTLINE_ITEMS[0]?.id,
-  );
-  const isMobile = useMediaQuery('(max-width: 768px)');
-
-  const scrollToId = useCallback((id: string) => {
-    setActiveId(id);
-    const target = document.getElementById(id);
-    if (target != null) {
-      target.scrollIntoView({behavior: 'smooth', block: 'start'});
-      window.history.pushState(null, '', `#${id}`);
-    }
-  }, []);
-
   return (
     <Layout
-      height="auto"
+      height="fill"
       contentWidth={960}
-      end={
-        isMobile ? undefined : (
-          <LayoutPanel
-            isScrollable={false}
-            label="On this page"
-            role="complementary"
-            xstyle={styles.outlinePanel}>
-            <Outline items={OUTLINE_ITEMS} onActiveIdChange={setActiveId} />
-          </LayoutPanel>
-        )
+      start={
+        <LayoutPanel hasDivider padding={0}>
+          <SideNav header={<SideNavHeading heading="Product Name" />}>
+            <SideNavSection title="Navigation" isHeaderHidden>
+              <SideNavItem label="Home" />
+              <SideNavItem label="Getting started" isSelected />
+            </SideNavSection>
+          </SideNav>
+        </LayoutPanel>
       }
       content={
-        <LayoutContent isScrollable={false} padding={8}>
+        <LayoutContent padding={8}>
           <VStack gap={8}>
             <VStack gap={2}>
-              <Text type="display-1">Getting started with Product Name</Text>
+              <Text type="display-1">
+                Getting started with Product Name
+              </Text>
               <Text type="supporting" color="secondary">
                 Last updated March 30, 2026
               </Text>
-              {isMobile && (
-                <Selector
-                  label="On this page"
-                  isLabelHidden
-                  options={OUTLINE_OPTIONS}
-                  value={activeId}
-                  onChange={scrollToId}
-                  width="100%"
-                />
-              )}
+              <Text type="body">
+                Install the package, configure your theme, and build your first
+                component in three steps.
+              </Text>
             </VStack>
 
             <Card>
@@ -103,7 +64,11 @@ export default function TechnicalDocumentationPage() {
                 <HStack gap={2} vAlign="center">
                   <StackItem size="fill">
                     <HStack gap={2} vAlign="center">
-                      <Icon icon={SparklesIcon} size="sm" color="secondary" />
+                      <Icon
+                        icon={SparklesIcon}
+                        size="sm"
+                        color="secondary"
+                      />
                       <Text type="body" weight="semibold">
                         AI Assistance
                       </Text>
@@ -146,9 +111,7 @@ export default function TechnicalDocumentationPage() {
             </Card>
 
             <VStack gap={4}>
-              <Heading id="prerequisites" level={2}>
-                Prerequisites
-              </Heading>
+              <Heading level={2}>Prerequisites</Heading>
               <List density="compact" listStyle="disc">
                 <ListItem label="Node.js 18+" />
                 <ListItem label="React 18 or 19" />
@@ -159,9 +122,7 @@ export default function TechnicalDocumentationPage() {
             <Divider />
 
             <VStack gap={4}>
-              <Heading id="install-package" level={2}>
-                Install the package
-              </Heading>
+              <Heading level={2}>Install the package</Heading>
               <Text type="body">
                 Every project starts with installing the core package. This
                 gives you access to all components, tokens, and utilities.
@@ -170,11 +131,9 @@ export default function TechnicalDocumentationPage() {
                 <Text type="body" weight="bold">
                   Step 1: Install the core package
                 </Text>
-                <CodeBlock
-                  code="npm install @astryxdesign/core"
-                  language="bash"
-                  width="100%"
-                />
+                <Card padding={0}>
+                  <CodeBlock code="npm install @astryxdesign/core" language="bash" />
+                </Card>
               </VStack>
               <VStack gap={2}>
                 <Text type="body" weight="bold">
@@ -184,41 +143,42 @@ export default function TechnicalDocumentationPage() {
                   Astryx uses StyleX for styling. Add the compiler plugin to your
                   build configuration.
                 </Text>
-                <CodeBlock
-                  code="npm install @stylexjs/babel-plugin"
-                  language="bash"
-                  width="100%"
-                />
+                <Card padding={0}>
+                  <CodeBlock
+                    code="npm install @stylexjs/babel-plugin"
+                    language="bash"
+                  />
+                </Card>
               </VStack>
               <VStack gap={2}>
                 <Text type="body" weight="bold">
                   Step 3: Import your first component
                 </Text>
-                <CodeBlock
-                  code={`import { Button } from '@astryxdesign/core/Button';
+                <Card padding={0}>
+                  <CodeBlock
+                    code={`import { Button } from '@astryxdesign/core/Button';
 
 export default function App() {
   return <Button label="Hello Astryx" variant="primary" />;
 }`}
-                  language="tsx"
-                  width="100%"
-                />
+                    language="tsx"
+                  />
+                </Card>
               </VStack>
             </VStack>
 
             <Divider />
 
             <VStack gap={4}>
-              <Heading id="configure-theming" level={2}>
-                Configure theming
-              </Heading>
+              <Heading level={2}>Configure theming</Heading>
               <Text type="body">
                 Astryx ships with a default theme that works out of the box. To
                 customize colors, typography, and spacing, wrap your app in a
                 theme provider.
               </Text>
-              <CodeBlock
-                code={`import { ThemeProvider } from '@astryxdesign/core/Theme';
+              <Card padding={0}>
+                <CodeBlock
+                  code={`import { ThemeProvider } from '@astryxdesign/core/Theme';
 
 export default function App({ children }) {
   return (
@@ -227,9 +187,9 @@ export default function App({ children }) {
     </ThemeProvider>
   );
 }`}
-                language="tsx"
-                width="100%"
-              />
+                  language="tsx"
+                />
+              </Card>
               <Text type="body" color="secondary">
                 See the theming guide for the full list of customizable tokens.
               </Text>
@@ -238,9 +198,7 @@ export default function App({ children }) {
             <Divider />
 
             <VStack gap={4}>
-              <Heading id="next-steps" level={2}>
-                Next steps
-              </Heading>
+              <Heading level={2}>Next steps</Heading>
               <List density="compact" listStyle="disc">
                 <ListItem label="Fundamental concepts — How theming, layout, and composition work" />
                 <ListItem label="Component API reference — Props, variants, and examples for every component" />

package/templates/pages/ide/page.tsx

@@ -4,14 +4,14 @@
 
 import {useState, useMemo} from 'react';
 import * as stylex from '@stylexjs/stylex';
+import {SideNav, SideNavItem, SideNavSection} from '@astryxdesign/core/SideNav';
 
 import {Layout, LayoutContent, LayoutPanel} from '@astryxdesign/core/Layout';
 import {ResizeHandle, useResizable} from '@astryxdesign/core/Resizable';
 import {Text, Heading} from '@astryxdesign/core/Text';
 import {CodeBlock} from '@astryxdesign/core/CodeBlock';
 import {colorVars, spacingVars} from '@astryxdesign/core/theme/tokens.stylex';
-import {Stack, StackItem} from '@astryxdesign/core/Layout';
-import {useMediaQuery} from '@astryxdesign/core/hooks';
+import {Stack} from '@astryxdesign/core/Layout';
 import {TabList, Tab} from '@astryxdesign/core/TabList';
 import {
   SegmentedControl,
@@ -27,14 +27,29 @@ import type {TreeListItemData} from '@astryxdesign/core/TreeList';
 import {
   FolderIcon,
   DocumentTextIcon,
+  CodeBracketIcon,
   MagnifyingGlassIcon,
+  CommandLineIcon,
+  ExclamationTriangleIcon,
+  InformationCircleIcon,
+  BugAntIcon,
+  HomeIcon,
+  FolderOpenIcon,
+  PuzzlePieceIcon,
 } from '@heroicons/react/24/outline';
+import {
+  HomeIcon as HomeIconSolid,
+  FolderOpenIcon as FolderOpenSolid,
+  MagnifyingGlassIcon as MagnifyingGlassSolid,
+  PuzzlePieceIcon as PuzzlePieceSolid,
+} from '@heroicons/react/24/solid';
 
 const styles = stylex.create({
   contentFill: {
     height: '100%',
   },
   terminalWrapper: {
+    flex: 1,
     minHeight: 0,
     overflow: 'hidden',
     display: 'grid',
@@ -54,27 +69,28 @@ const styles = stylex.create({
     flexShrink: 0,
   },
   editorArea: {
+    flex: 1,
     overflow: 'auto',
-    minHeight: 0,
   },
   fileExplorer: {
     padding: 16,
-    minWidth: 0,
-  },
-  propertiesPanel: {
-    height: '100%',
-  },
-  propertiesContent: {
-    flex: 1,
-    minHeight: 0,
-  },
-  propertyActions: {
-    marginTop: 'auto',
   },
   terminalArea: {
     height: '100%',
     overflow: 'hidden',
   },
+  hideOnMobile: {
+    display: {
+      default: 'contents',
+      '@media (max-width: 768px)': 'none',
+    },
+  },
+  hideSideNav: {
+    display: {
+      default: 'flex',
+      '@media (max-width: 768px)': 'none',
+    },
+  },
 });
 
 const EDITOR_CODE = `import {useState, useCallback} from 'react';
@@ -135,23 +151,22 @@ $ `;
 function buildFileTree(
   onFileClick: (name: string) => void,
 ): TreeListItemData[] {
-  const label = (text: string) => <Text maxLines={1}>{text}</Text>;
   const file = (id: string): TreeListItemData => ({
     id,
-    label: label(id),
+    label: id,
     startContent: <Icon icon={DocumentTextIcon} size="xsm" />,
     onClick: () => onFileClick(id),
   });
   return [
     {
       id: 'src',
-      label: label('src'),
+      label: 'src',
       startContent: <Icon icon={FolderIcon} size="xsm" />,
       isExpanded: true,
       children: [
         {
           id: 'components',
-          label: label('components'),
+          label: 'components',
           startContent: <Icon icon={FolderIcon} size="xsm" />,
           isExpanded: true,
           children: [
@@ -162,14 +177,14 @@ function buildFileTree(
         },
         {
           id: 'pages',
-          label: label('pages'),
+          label: 'pages',
           startContent: <Icon icon={FolderIcon} size="xsm" />,
           isExpanded: true,
           children: [file('index.tsx'), file('about.tsx')],
         },
         {
           id: 'styles',
-          label: label('styles'),
+          label: 'styles',
           startContent: <Icon icon={FolderIcon} size="xsm" />,
           isExpanded: true,
           children: [file('tokens.stylex.ts'), file('theme.ts')],
@@ -201,6 +216,7 @@ const HISTORY_ITEMS = [
 
 export default function ResizableWorkspacePage() {
   const [activeFile, setActiveFile] = useState('Counter.tsx');
+  const [activeNavItem, setActiveNavItem] = useState('Explorer');
   const [activeTermTab, setActiveTermTab] = useState('terminal');
   const [activePropertiesTab, setActivePropertiesTab] = useState('properties');
   const fileTree = useMemo(() => buildFileTree(setActiveFile), []);
@@ -229,48 +245,89 @@ export default function ResizableWorkspacePage() {
     collapsedSize: 40,
   });
 
-  const isMobile = useMediaQuery('(max-width: 768px)');
-
   return (
     <Layout
       height="fill"
+      start={
+        <LayoutPanel hasDivider={false} padding={0}>
+          <SideNav
+            collapsible={{defaultIsCollapsed: true}}
+            resizable
+            xstyle={styles.hideSideNav}>
+            <SideNavSection title="Navigation" isHeaderHidden>
+              <SideNavItem
+                label="Home"
+                icon={HomeIcon}
+                selectedIcon={HomeIconSolid}
+                isSelected={activeNavItem === 'Home'}
+                onClick={() => setActiveNavItem('Home')}
+              />
+              <SideNavItem
+                label="Explorer"
+                icon={FolderOpenIcon}
+                selectedIcon={FolderOpenSolid}
+                isSelected={activeNavItem === 'Explorer'}
+                onClick={() => setActiveNavItem('Explorer')}
+              />
+              <SideNavItem
+                label="Search"
+                icon={MagnifyingGlassIcon}
+                selectedIcon={MagnifyingGlassSolid}
+                isSelected={activeNavItem === 'Search'}
+                onClick={() => setActiveNavItem('Search')}
+              />
+              <SideNavItem
+                label="Source Control"
+                icon={CodeBracketIcon}
+                isSelected={activeNavItem === 'Source Control'}
+                onClick={() => setActiveNavItem('Source Control')}
+              />
+              <SideNavItem
+                label="Extensions"
+                icon={PuzzlePieceIcon}
+                selectedIcon={PuzzlePieceSolid}
+                isSelected={activeNavItem === 'Extensions'}
+                onClick={() => setActiveNavItem('Extensions')}
+              />
+            </SideNavSection>
+          </SideNav>
+        </LayoutPanel>
+      }
       content={
         <LayoutContent padding={0}>
           <Layout
             height="fill"
             start={
-              isMobile ? undefined : (
-                <>
-                  {!startPanel.isCollapsed && (
-                    <LayoutPanel
-                      width={startPanel.size}
-                      hasDivider={false}
-                      padding={0}>
-                      <Stack
-                        direction="vertical"
-                        xstyle={styles.fileExplorer}
-                        gap={2}>
-                        <TextInput
-                          label="Search files"
-                          isLabelHidden
-                          value=""
-                          placeholder="Search"
-                          size="md"
-                          startIcon={MagnifyingGlassIcon}
-                        />
-                        <TreeList items={fileTree} density="compact" />
-                      </Stack>
-                    </LayoutPanel>
-                  )}
-                  <ResizeHandle
-                    direction="horizontal"
-                    hasDivider
-                    isAlwaysVisible={false}
-                    resizable={startPanel.props}
-                    label="Resize file explorer"
-                  />
-                </>
-              )
+              <div {...stylex.props(styles.hideOnMobile)}>
+                {!startPanel.isCollapsed && (
+                  <LayoutPanel
+                    width={startPanel.size}
+                    hasDivider={false}
+                    padding={0}>
+                    <Stack
+                      direction="vertical"
+                      xstyle={styles.fileExplorer}
+                      gap={2}>
+                      <TextInput
+                        label="Search files"
+                        isLabelHidden
+                        value=""
+                        placeholder="Search"
+                        size="md"
+                        startIcon={MagnifyingGlassIcon}
+                      />
+                      <TreeList items={fileTree} density="compact" />
+                    </Stack>
+                  </LayoutPanel>
+                )}
+                <ResizeHandle
+                  direction="horizontal"
+                  hasDivider
+                  isAlwaysVisible={false}
+                  resizable={startPanel.props}
+                  label="Resize file explorer"
+                />
+              </div>
             }
             content={
               <LayoutContent padding={0}>
@@ -278,13 +335,13 @@ export default function ResizableWorkspacePage() {
                   height="fill"
                   content={
                     <LayoutContent padding={0}>
-                      <Stack direction="vertical" xstyle={styles.contentFill}>
-                        <StackItem size="fill" xstyle={styles.editorArea}>
+                      <Stack
+                        direction="vertical"
+                        xstyle={styles.contentFill}>
+                        <div {...stylex.props(styles.editorArea)}>
                           <CodeBlock
                             code={EDITOR_CODE}
                             language="typescript"
-                            container="section"
-                            hasLanguageLabel={false}
                             hasLineNumbers
                             highlightLines={[21]}
                             hasCopyButton={false}
@@ -296,7 +353,7 @@ export default function ResizableWorkspacePage() {
                               borderRadius: 0,
                             }}
                           />
-                        </StackItem>
+                        </div>
                         <ResizeHandle
                           direction="vertical"
                           hasDivider
@@ -321,19 +378,43 @@ export default function ResizableWorkspacePage() {
                                 size="sm"
                                 hasDivider={false}
                                 xstyle={styles.tabListPadding}>
-                                <Tab label="Terminal" value="terminal" />
-                                <Tab label="Problems" value="problems" />
-                                <Tab label="Output" value="output" />
-                                <Tab label="Debug" value="debug" />
+                                <Tab
+                                  label="Terminal"
+                                  value="terminal"
+                                  icon={
+                                    <Icon icon={CommandLineIcon} size="sm" />
+                                  }
+                                />
+                                <Tab
+                                  label="Problems"
+                                  value="problems"
+                                  icon={
+                                    <Icon
+                                      icon={ExclamationTriangleIcon}
+                                      size="sm"
+                                    />
+                                  }
+                                />
+                                <Tab
+                                  label="Output"
+                                  value="output"
+                                  icon={
+                                    <Icon
+                                      icon={InformationCircleIcon}
+                                      size="sm"
+                                    />
+                                  }
+                                />
+                                <Tab
+                                  label="Debug"
+                                  value="debug"
+                                  icon={<Icon icon={BugAntIcon} size="sm" />}
+                                />
                               </TabList>
-                              <StackItem
-                                size="fill"
-                                xstyle={styles.terminalWrapper}>
+                              <div {...stylex.props(styles.terminalWrapper)}>
                                 <CodeBlock
                                   code={TERMINAL_OUTPUT}
                                   language="bash"
-                                  container="section"
-                                  hasLanguageLabel={false}
                                   hasCopyButton={false}
                                   size="sm"
                                   style={{
@@ -343,7 +424,7 @@ export default function ResizableWorkspacePage() {
                                     borderRadius: 0,
                                   }}
                                 />
-                              </StackItem>
+                              </div>
                             </Stack>
                           </div>
                         )}
@@ -351,118 +432,106 @@ export default function ResizableWorkspacePage() {
                     </LayoutContent>
                   }
                   end={
-                    isMobile ? undefined : (
-                      <>
-                        <ResizeHandle
-                          direction="horizontal"
-                          hasDivider
-                          isReversed
-                          isAlwaysVisible={false}
-                          resizable={endPanel.props}
-                          label="Resize properties panel"
-                        />
-                        {!endPanel.isCollapsed && (
-                          <LayoutPanel
-                            width={endPanel.size}
-                            hasDivider={false}
-                            padding={4}>
-                            <Stack
-                              direction="vertical"
-                              gap={3}
-                              xstyle={styles.propertiesPanel}>
-                              <SegmentedControl
-                                label="Properties panel sections"
-                                value={activePropertiesTab}
-                                onChange={setActivePropertiesTab}
-                                size="sm"
-                                layout="fill">
-                                <SegmentedControlItem
-                                  label="Properties"
-                                  value="properties"
-                                />
-                                <SegmentedControlItem
-                                  label="History"
-                                  value="history"
-                                />
-                              </SegmentedControl>
-                              {activePropertiesTab === 'properties' ? (
-                                <Stack
-                                  direction="vertical"
-                                  gap={3}
-                                  xstyle={styles.propertiesContent}>
-                                  <Stack direction="vertical" gap={1}>
-                                    <Heading level={3} maxLines={1}>
-                                      {activeFile}
-                                    </Heading>
-                                    <Text
-                                      color="secondary"
-                                      type="supporting"
-                                      maxLines={1}>
-                                      src/components/{activeFile}
-                                    </Text>
-                                  </Stack>
-                                  <MetadataList xstyle={styles.metadataCompact}>
-                                    {PROPERTIES.map(prop => (
-                                      <MetadataListItem
-                                        key={prop.label}
-                                        label={prop.label}>
-                                        {prop.value}
-                                      </MetadataListItem>
-                                    ))}
-                                  </MetadataList>
-                                  <Stack
-                                    direction="vertical"
-                                    gap={2}
-                                    xstyle={styles.propertyActions}>
+                    <div {...stylex.props(styles.hideOnMobile)}>
+                      <ResizeHandle
+                        direction="horizontal"
+                        hasDivider
+                        isReversed
+                        isAlwaysVisible={false}
+                        resizable={endPanel.props}
+                        label="Resize properties panel"
+                      />
+                      {!endPanel.isCollapsed && (
+                        <LayoutPanel
+                          width={endPanel.size}
+                          hasDivider={false}
+                          padding={4}>
+                          <Stack direction="vertical" gap={3}>
+                            <SegmentedControl
+                              label="Properties panel sections"
+                              value={activePropertiesTab}
+                              onChange={setActivePropertiesTab}
+                              size="sm"
+                              layout="fill">
+                              <SegmentedControlItem
+                                label="Properties"
+                                value="properties"
+                              />
+                              <SegmentedControlItem
+                                label="History"
+                                value="history"
+                              />
+                            </SegmentedControl>
+                            {activePropertiesTab === 'properties' ? (
+                              <>
+                                <Stack direction="vertical" gap={1}>
+                                  <Heading level={3}>
+                                    {activeFile}
+                                  </Heading>
+                                  <Text color="secondary" type="supporting">
+                                    src/components/{activeFile}
+                                  </Text>
+                                </Stack>
+                                <MetadataList
+                                  xstyle={styles.metadataCompact}>
+                                  {PROPERTIES.map(prop => (
+                                    <MetadataListItem
+                                      key={prop.label}
+                                      label={prop.label}>
+                                      {prop.value}
+                                    </MetadataListItem>
+                                  ))}
+                                </MetadataList>
+                                <Stack direction="vertical" gap={2}>
+                                  <Stack direction="vertical" gap={2}>
                                     <Button
                                       label="Format Document"
-                                      size="sm"
+                                      size="md"
                                       variant="secondary"
                                     />
                                     <Button
                                       label="Go to Definition"
-                                      size="sm"
+                                      size="md"
                                       variant="secondary"
                                     />
                                     <Button
                                       label="Find References"
-                                      size="sm"
+                                      size="md"
                                       variant="secondary"
                                     />
                                   </Stack>
                                 </Stack>
-                              ) : (
-                                <Stack direction="vertical" gap={1}>
-                                  <List>
-                                    {HISTORY_ITEMS.map(item => (
-                                      <ListItem
-                                        key={item.label}
-                                        label={item.label}
-                                        endContent={
-                                          <Text
-                                            type="supporting"
-                                            color="secondary"
-                                            maxLines={1}>
-                                            {item.time}
-                                          </Text>
-                                        }
-                                        startContent={
-                                          <span
-                                            {...stylex.props(
-                                              styles.historyTimelineDot,
-                                            )}
-                                          />
-                                        }
-                                      />
-                                    ))}
-                                  </List>
-                                </Stack>
-                              )}
-                            </Stack>
-                          </LayoutPanel>
-                        )}
-                      </>
-                    )
+                              </>
+                            ) : (
+                              <Stack direction="vertical" gap={1}>
+                                <List>
+                                  {HISTORY_ITEMS.map(item => (
+                                    <ListItem
+                                      key={item.label}
+                                      label={item.label}
+                                      endContent={
+                                        <Text
+                                          type="supporting"
+                                          color="secondary">
+                                          {item.time}
+                                        </Text>
+                                      }
+                                      startContent={
+                                        <span
+                                          {...stylex.props(
+                                            styles.historyTimelineDot,
+                                          )}
+                                        />
+                                      }
+                                    />
+                                  ))}
+                                </List>
+                              </Stack>
+                            )}
+                          </Stack>
+                        </LayoutPanel>
+                      )}
+                    </div>
                   }
                 />
               </LayoutContent>