@astryxdesign/cli 0.1.0 → 0.1.1-canary.13763f6

package/templates/pages/documentation/page.tsx

@@ -2,27 +2,23 @@
 
 'use client';
 
-import * as stylex from '@stylexjs/stylex';
-import {
-  SideNav,
-  SideNavHeading,
-  SideNavItem,
-  SideNavSection,
-} from '@astryxdesign/core/SideNav';
-import {Text} from '@astryxdesign/core/Text';
+import type {CSSProperties} from 'react';
+import {Heading, 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, LayoutPanel} from '@astryxdesign/core/Layout';
+import {Layout, LayoutContent} 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-container'],
-    cursor: 'pointer',
-  },
-});
+const previewCard: CSSProperties = {
+  borderRadius: 'var(--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.
+const cardGrid: CSSProperties = {
+  margin: -8,
+};
 
 // ---------------------------------------------------------------------------
 // Data
@@ -213,30 +209,12 @@ const COMPONENT_CATEGORIES = [
 export default function DocumentationOverviewPage() {
   return (
     <Layout
-      height="fill"
+      height="auto"
       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="cyan" padding={10}>
+            <Card variant="gray" padding={10}>
               <HStack gap={8} vAlign="center">
                 <StackItem size="fill">
                   <VStack gap={4}>
@@ -246,11 +224,7 @@ 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>
@@ -260,25 +234,35 @@ export default function DocumentationOverviewPage() {
 
             {COMPONENT_CATEGORIES.map(category => (
               <VStack key={category.label} gap={4}>
-                <Text type="display-2">{category.label}</Text>
-                <Grid columns={{minWidth: 260}} gap={8}>
+                <Heading level={2}>{category.label}</Heading>
+                <Grid
+                  columns={{minWidth: 260}}
+                  gap={2}
+                  style={cardGrid}>
                   {category.items.map(item => (
-                    <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>
+                    <ClickableCard
+                      key={item.key}
+                      label={`Open ${item.name}`}
+                      onClick={() => {}}
+                      variant="transparent"
+                      padding={2}>
+                      <VStack gap={3}>
+                        <Card
+                          variant="muted"
+                          padding={0}
+                          minHeight={160}
+                          style={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>
-                    </VStack>
+                    </ClickableCard>
                   ))}
                 </Grid>
               </VStack>

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

@@ -2,14 +2,7 @@
 
 'use client';
 
-import {useState, useMemo} from 'react';
-import * as stylex from '@stylexjs/stylex';
-import {
-  SideNav,
-  SideNavHeading,
-  SideNavItem,
-  SideNavSection,
-} from '@astryxdesign/core/SideNav';
+import {useCallback, useState, useMemo, type CSSProperties} from 'react';
 import {Heading, Text} from '@astryxdesign/core/Text';
 import {Button} from '@astryxdesign/core/Button';
 import {IconButton} from '@astryxdesign/core/IconButton';
@@ -20,8 +13,10 @@ 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';
@@ -29,15 +24,31 @@ 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,
   PlusIcon,
 } from '@heroicons/react/24/outline';
 
-const styles = stylex.create({
-  tabListFlush: {marginInlineStart: '-12px'},
-});
+const tabListFlush: CSSProperties = {marginInlineStart: '-12px'};
+const outlinePanel: CSSProperties = {
+  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
@@ -493,14 +504,21 @@ function getComponentDocs(key: string) {
 // ComponentDetailView
 // ---------------------------------------------------------------------------
 
-function ComponentDetailView({
-  activeNav,
-  nav,
-}: {
-  activeNav: string;
-  nav: React.ReactNode;
-}) {
+function ComponentDetailView({activeNav}: {activeNav: string}) {
   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: [
@@ -556,25 +574,42 @@ function ComponentDetailView({
 
   return (
     <Layout
-      height="fill"
+      height="auto"
       contentWidth={960}
-      start={
-        <LayoutPanel hasDivider padding={0}>
-          {nav}
-        </LayoutPanel>
+      end={
+        isMobile ? undefined : (
+          <LayoutPanel
+            isScrollable={false}
+            label="On this page"
+            role="complementary"
+            style={outlinePanel}>
+            <Outline
+              items={COMPONENT_OUTLINE_ITEMS}
+              onActiveIdChange={setActiveId}
+            />
+          </LayoutPanel>
+        )
       }
       content={
-        <LayoutContent padding={8}>
+        <LayoutContent isScrollable={false} 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] ?? (
@@ -586,13 +621,18 @@ function ComponentDetailView({
             </Card>
 
             <VStack gap={4}>
-              <Heading level={2}>Usage</Heading>
+              <Heading id="usage" level={2}>
+                Usage
+              </Heading>
               <Text type="large" weight="normal">
                 {docs.usage}
               </Text>
-              <Heading level={3}>Best practices</Heading>
+              <Heading id="best-practices" level={3}>
+                Best practices
+              </Heading>
               <Table
                 data={docs.bestPractices as Record<string, unknown>[]}
+                dividers="none"
                 columns={[
                   {
                     key: 'type',
@@ -616,14 +656,15 @@ function ComponentDetailView({
                   },
                 ]}
                 density="spacious"
-                dividers="rows"
               />
             </VStack>
 
             <Divider />
 
             <VStack gap={4}>
-              <Heading level={2}>Examples</Heading>
+              <Heading id="examples" level={2}>
+                Examples
+              </Heading>
               <Text type="large" weight="normal">
                 Explore common configurations, variations, and states for this
                 component.
@@ -675,17 +716,24 @@ function ComponentDetailView({
                         <TabList
                           value={activeTab}
                           onChange={value =>
-                            setExampleTabs(prev => ({...prev, [tabKey]: value}))
+                            setExampleTabs(prev => ({
+                              ...prev,
+                              [tabKey]: value,
+                            }))
                           }
                           size="sm"
-                          xstyle={styles.tabListFlush}>
+                          style={tabListFlush}>
                           <Tab value="description" label="Description" />
                           <Tab value="code" label="Code" />
                         </TabList>
                         {activeTab === 'description' ? (
                           <Text type="body">{example.description}</Text>
                         ) : (
-                          <CodeBlock code={example.code} language="tsx" />
+                          <CodeBlock
+                            code={example.code}
+                            language="tsx"
+                            width="100%"
+                          />
                         )}
                       </VStack>
                     </Section>
@@ -705,31 +753,5 @@ function ComponentDetailView({
 // ---------------------------------------------------------------------------
 
 export default function DesignDocumentationPage() {
-  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>
-      }
-    />
-  );
+  return <ComponentDetailView activeNav="button" />;
 }

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

@@ -2,22 +2,20 @@
 
 'use client';
 
-import {
-  SideNav,
-  SideNavHeading,
-  SideNavItem,
-  SideNavSection,
-} from '@astryxdesign/core/SideNav';
+import {useCallback, useState, type CSSProperties} from 'react';
 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,
@@ -28,35 +26,73 @@ 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 outlinePanel: CSSProperties = {
+  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="fill"
+      height="auto"
       contentWidth={960}
-      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>
+      end={
+        isMobile ? undefined : (
+          <LayoutPanel
+            isScrollable={false}
+            label="On this page"
+            role="complementary"
+            style={outlinePanel}>
+            <Outline items={OUTLINE_ITEMS} onActiveIdChange={setActiveId} />
+          </LayoutPanel>
+        )
       }
       content={
-        <LayoutContent padding={8}>
+        <LayoutContent isScrollable={false} 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>
-              <Text type="body">
-                Install the package, configure your theme, and build your first
-                component in three steps.
-              </Text>
+              {isMobile && (
+                <Selector
+                  label="On this page"
+                  isLabelHidden
+                  options={OUTLINE_OPTIONS}
+                  value={activeId}
+                  onChange={scrollToId}
+                  width="100%"
+                />
+              )}
             </VStack>
 
             <Card>
@@ -64,11 +100,7 @@ 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>
@@ -103,15 +135,17 @@ export default function TechnicalDocumentationPage() {
                 </HStack>
                 <Text type="body" color="secondary">
                   Help me get set up with Product Name. Based on my project, do
-                  the following: 1. Install @astryxdesign/core and the StyleX compiler.
-                  2. Wrap my app in ThemeProvider. 3. Replace one existing
-                  component with an Astryx equivalent.
+                  the following: 1. Install @astryxdesign/core and the StyleX
+                  compiler. 2. Wrap my app in ThemeProvider. 3. Replace one
+                  existing component with an Astryx equivalent.
                 </Text>
               </VStack>
             </Card>
 
             <VStack gap={4}>
-              <Heading level={2}>Prerequisites</Heading>
+              <Heading id="prerequisites" level={2}>
+                Prerequisites
+              </Heading>
               <List density="compact" listStyle="disc">
                 <ListItem label="Node.js 18+" />
                 <ListItem label="React 18 or 19" />
@@ -122,7 +156,9 @@ export default function TechnicalDocumentationPage() {
             <Divider />
 
             <VStack gap={4}>
-              <Heading level={2}>Install the package</Heading>
+              <Heading id="install-package" 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.
@@ -131,54 +167,57 @@ export default function TechnicalDocumentationPage() {
                 <Text type="body" weight="bold">
                   Step 1: Install the core package
                 </Text>
-                <Card padding={0}>
-                  <CodeBlock code="npm install @astryxdesign/core" language="bash" />
-                </Card>
+                <CodeBlock
+                  code="npm install @astryxdesign/core"
+                  language="bash"
+                  width="100%"
+                />
               </VStack>
               <VStack gap={2}>
                 <Text type="body" weight="bold">
-                  Step 2: Add the StyleX compiler
+                  Step 2: Import the precompiled styles
                 </Text>
                 <Text type="body" color="secondary">
-                  Astryx uses StyleX for styling. Add the compiler plugin to your
-                  build configuration.
+                  Astryx ships precompiled CSS, so there is no build plugin to
+                  configure. Import the reset and component stylesheets once at
+                  your app entry point.
                 </Text>
-                <Card padding={0}>
-                  <CodeBlock
-                    code="npm install @stylexjs/babel-plugin"
-                    language="bash"
-                  />
-                </Card>
+                <CodeBlock
+                  code={`import '@astryxdesign/core/reset.css';
+import '@astryxdesign/core/astryx.css';`}
+                  language="tsx"
+                  width="100%"
+                />
               </VStack>
               <VStack gap={2}>
                 <Text type="body" weight="bold">
                   Step 3: Import your first component
                 </Text>
-                <Card padding={0}>
-                  <CodeBlock
-                    code={`import { Button } from '@astryxdesign/core/Button';
+                <CodeBlock
+                  code={`import { Button } from '@astryxdesign/core/Button';
 
 export default function App() {
   return <Button label="Hello Astryx" variant="primary" />;
 }`}
-                    language="tsx"
-                  />
-                </Card>
+                  language="tsx"
+                  width="100%"
+                />
               </VStack>
             </VStack>
 
             <Divider />
 
             <VStack gap={4}>
-              <Heading level={2}>Configure theming</Heading>
+              <Heading id="configure-theming" 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>
-              <Card padding={0}>
-                <CodeBlock
-                  code={`import { ThemeProvider } from '@astryxdesign/core/Theme';
+              <CodeBlock
+                code={`import { ThemeProvider } from '@astryxdesign/core/Theme';
 
 export default function App({ children }) {
   return (
@@ -187,9 +226,9 @@ export default function App({ children }) {
     </ThemeProvider>
   );
 }`}
-                  language="tsx"
-                />
-              </Card>
+                language="tsx"
+                width="100%"
+              />
               <Text type="body" color="secondary">
                 See the theming guide for the full list of customizable tokens.
               </Text>
@@ -198,7 +237,9 @@ export default function App({ children }) {
             <Divider />
 
             <VStack gap={4}>
-              <Heading level={2}>Next steps</Heading>
+              <Heading id="next-steps" 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" />