@astryxdesign/cli 0.0.15 → 0.1.0-canary.0b5b49f

package/src/commands/agent-docs.test.mjs

@@ -32,8 +32,8 @@ describe('generateCompressedIndex', () => {
   it('includes the version number', () => {
     const result = generateCompressedIndex('1.2.3');
     expect(result).toContain('Astryx v1.2.3');
-    expect(result).toContain('<!-- XDS:START -->');
-    expect(result).toContain('<!-- XDS:END -->');
+    expect(result).toContain('<!-- ASTRYX:START -->');
+    expect(result).toContain('<!-- ASTRYX:END -->');
   });
 
   it('includes theme nudge rule', () => {
@@ -82,19 +82,19 @@ describe('injectXdsBlock', () => {
     const filePath = path.join(tmpDir, 'test.md');
     fs.writeFileSync(filePath, '# Existing content\n');
 
-    const result = injectXdsBlock(filePath, '<!-- XDS:START -->\nnew\n<!-- XDS:END -->');
+    const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\nnew\n<!-- ASTRYX:END -->');
 
     expect(result).toBe(true);
     const content = fs.readFileSync(filePath, 'utf-8');
     expect(content).toContain('# Existing content');
-    expect(content).toContain('<!-- XDS:START -->');
+    expect(content).toContain('<!-- ASTRYX:START -->');
   });
 
   it('replaces existing markers', () => {
     const filePath = path.join(tmpDir, 'test.md');
     fs.writeFileSync(filePath, 'before\n<!-- XDS:START -->\nold\n<!-- XDS:END -->\nafter\n');
 
-    injectXdsBlock(filePath, '<!-- XDS:START -->\nnew\n<!-- XDS:END -->');
+    injectXdsBlock(filePath, '<!-- ASTRYX:START -->\nnew\n<!-- ASTRYX:END -->');
 
     const content = fs.readFileSync(filePath, 'utf-8');
     expect(content).toContain('new');
@@ -106,7 +106,7 @@ describe('injectXdsBlock', () => {
   it('returns false and does not create file when createIfMissing is false', () => {
     const filePath = path.join(tmpDir, 'nonexistent.md');
 
-    const result = injectXdsBlock(filePath, '<!-- XDS:START -->\ncontent\n<!-- XDS:END -->');
+    const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\ncontent\n<!-- ASTRYX:END -->');
 
     expect(result).toBe(false);
     expect(fs.existsSync(filePath)).toBe(false);
@@ -116,11 +116,11 @@ describe('injectXdsBlock', () => {
     const filePath = path.join(tmpDir, 'test.md');
     fs.writeFileSync(filePath, '# Existing content\n\nNo XDS markers here.\n');
 
-    const result = injectXdsBlock(filePath, '<!-- XDS:START -->\nnew\n<!-- XDS:END -->', {onlyReplace: true});
+    const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\nnew\n<!-- ASTRYX:END -->', {onlyReplace: true});
 
     expect(result).toBe(false);
     const content = fs.readFileSync(filePath, 'utf-8');
-    expect(content).not.toContain('<!-- XDS:START -->');
+    expect(content).not.toContain('<!-- ASTRYX:START -->');
     expect(content).toBe('# Existing content\n\nNo XDS markers here.\n');
   });
 
@@ -128,7 +128,7 @@ describe('injectXdsBlock', () => {
     const filePath = path.join(tmpDir, 'test.md');
     fs.writeFileSync(filePath, 'before\n<!-- XDS:START -->\nold\n<!-- XDS:END -->\nafter\n');
 
-    const result = injectXdsBlock(filePath, '<!-- XDS:START -->\nnew\n<!-- XDS:END -->', {onlyReplace: true});
+    const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\nnew\n<!-- ASTRYX:END -->', {onlyReplace: true});
 
     expect(result).toBe(true);
     const content = fs.readFileSync(filePath, 'utf-8');
@@ -139,7 +139,7 @@ describe('injectXdsBlock', () => {
   it('creates file when createIfMissing is true', () => {
     const filePath = path.join(tmpDir, 'new.md');
 
-    const result = injectXdsBlock(filePath, '<!-- XDS:START -->\ncontent\n<!-- XDS:END -->', {
+    const result = injectXdsBlock(filePath, '<!-- ASTRYX:START -->\ncontent\n<!-- ASTRYX:END -->', {
       createIfMissing: true,
       header: '# Header',
     });
@@ -147,7 +147,7 @@ describe('injectXdsBlock', () => {
     expect(result).toBe(true);
     const content = fs.readFileSync(filePath, 'utf-8');
     expect(content).toContain('# Header');
-    expect(content).toContain('<!-- XDS:START -->');
+    expect(content).toContain('<!-- ASTRYX:START -->');
   });
 });
 
@@ -157,9 +157,9 @@ describe('injectAgentsMd', () => {
 
     const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
     expect(content).toContain('# AGENTS.md');
-    expect(content).toContain('<!-- XDS:START -->');
+    expect(content).toContain('<!-- ASTRYX:START -->');
     expect(content).toContain('Astryx v1.0.0');
-    expect(content).toContain('<!-- XDS:END -->');
+    expect(content).toContain('<!-- ASTRYX:END -->');
   });
 
   it('updates existing AGENTS.md by replacing XDS markers', () => {
@@ -195,7 +195,7 @@ Existing agent docs.
 
     const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
     expect(content).toContain('Existing agent docs.');
-    expect(content).toContain('<!-- XDS:START -->');
+    expect(content).toContain('<!-- ASTRYX:START -->');
     expect(content).toContain('Astryx v1.0.0');
   });
 });
@@ -210,7 +210,7 @@ describe('injectClaudeMd', () => {
     const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
     expect(content).toContain('# Claude Config');
     expect(content).toContain('Existing rules.');
-    expect(content).toContain('<!-- XDS:START -->');
+    expect(content).toContain('<!-- ASTRYX:START -->');
     expect(content).toContain('Astryx v1.0.0');
   });
 
@@ -322,7 +322,7 @@ describe('installAgentDocs', () => {
     expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(true);
     expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
     const content = fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8');
-    expect(content).toContain('<!-- XDS:START -->');
+    expect(content).toContain('<!-- ASTRYX:START -->');
   });
 
   it('injects into CLAUDE.md at root when it exists', () => {
@@ -334,7 +334,7 @@ describe('installAgentDocs', () => {
     expect(written).toEqual(['CLAUDE.md']);
     expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
     const claudeContent = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
-    expect(claudeContent).toContain('<!-- XDS:START -->');
+    expect(claudeContent).toContain('<!-- ASTRYX:START -->');
     expect(claudeContent).toContain('Project rules.');
   });
 
@@ -349,8 +349,8 @@ describe('installAgentDocs', () => {
     expect(written).toContain('CLAUDE.md');
     const agentsContent = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
     const claudeContent = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
-    expect(agentsContent).toContain('<!-- XDS:START -->');
-    expect(claudeContent).toContain('<!-- XDS:START -->');
+    expect(agentsContent).toContain('<!-- ASTRYX:START -->');
+    expect(claudeContent).toContain('<!-- ASTRYX:START -->');
   });
 
   it('updates existing .claude/CLAUDE.md', () => {
@@ -363,7 +363,7 @@ describe('installAgentDocs', () => {
     expect(written).toEqual(['.claude/CLAUDE.md']);
     const content = fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8');
     expect(content).toContain('Existing content.');
-    expect(content).toContain('<!-- XDS:START -->');
+    expect(content).toContain('<!-- ASTRYX:START -->');
   });
 
   it('respects --agent claude preset: finds existing CLAUDE.md', () => {
@@ -410,7 +410,7 @@ describe('installAgentDocs', () => {
 
     expect(written).toEqual([]);
     const content = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
-    expect(content).not.toContain('<!-- XDS:START -->');
+    expect(content).not.toContain('<!-- ASTRYX:START -->');
     expect(content).toBe('# Claude\n\nProject rules only.\n');
   });
 

package/src/commands/doctor.test.mjs

@@ -106,14 +106,14 @@ describe('doctor — individual checks', () => {
   });
 
   it('themes: WARN when theme installed but not wired', () => {
-    installPkg('@astryxdesign/theme-default', '0.0.14');
+    installPkg('@astryxdesign/theme-neutral', '0.0.14');
     const res = checkThemes({cwd: tmpDir, configTheme: null});
     expect(res.status).toBe('warn');
-    expect(res.message).toContain('@astryxdesign/theme-default');
+    expect(res.message).toContain('@astryxdesign/theme-neutral');
   });
 
   it('themes: PASS when theme installed and wired via config', () => {
-    installPkg('@astryxdesign/theme-default', '0.0.14');
+    installPkg('@astryxdesign/theme-neutral', '0.0.14');
     const res = checkThemes({cwd: tmpDir, configTheme: 'default'});
     expect(res.status).toBe('pass');
   });

package/src/commands/init.mjs

@@ -246,9 +246,9 @@ export function registerInit(program) {
       humanLog('  Next steps:');
       humanLog("    1. Import components: import { Button } from '@astryxdesign/core'");
       humanLog('    2. Optionally add a theme:');
-      humanLog("       import { defaultTheme } from '@astryxdesign/theme-default'");
-      humanLog('       <Theme theme={defaultTheme}>...</Theme>');
-      humanLog(`    3. ${run} xds --help for all commands`);
+      humanLog("       import { neutralTheme } from '@astryxdesign/theme-neutral'");
+      humanLog('       <Theme theme={neutralTheme}>...</Theme>');
+      humanLog(`    3. ${run} astryx --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 xds', 'yarn xds', 'pnpm exec xds').
+ * (e.g. 'npx astryx', 'yarn astryx', 'pnpm exec astryx').
  */
 
 import * as fs from 'node:fs';

package/templates/pages/documentation/page.tsx

@@ -3,24 +3,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 {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',
+    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,
   },
 });
 
@@ -213,30 +212,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 +227,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 +237,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}
+                  xstyle={styles.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}
+                          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>
-                    </VStack>
+                    </ClickableCard>
                   ))}
                 </Grid>
               </VStack>

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

@@ -2,14 +2,8 @@
 
 'use client';
 
-import {useState, useMemo} from 'react';
+import {useCallback, 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';
@@ -20,8 +14,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,6 +25,7 @@ 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,
@@ -37,8 +34,25 @@ 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
 // ---------------------------------------------------------------------------
@@ -493,14 +507,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 +577,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"
+            xstyle={styles.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 +624,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 +659,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,7 +719,10 @@ function ComponentDetailView({
                         <TabList
                           value={activeTab}
                           onChange={value =>
-                            setExampleTabs(prev => ({...prev, [tabKey]: value}))
+                            setExampleTabs(prev => ({
+                              ...prev,
+                              [tabKey]: value,
+                            }))
                           }
                           size="sm"
                           xstyle={styles.tabListFlush}>
@@ -685,7 +732,11 @@ function ComponentDetailView({
                         {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 +756,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" />;
 }