@astryxdesign/cli 0.1.1-canary.2b52cdc → 0.1.1-canary.36fb9fb

package/docs/working-with-ai.doc.mjs

@@ -34,11 +34,11 @@ export const docs = {
           type: 'code',
           lang: 'text',
           label: 'Paste this into your AI',
-          code: 'Install @astryxdesign/cli and run `npx astryx agent-docs` to set up your Astryx context. Read the generated file.',
+          code: 'Install @astryxdesign/cli and run `npx astryx init --features agents` to set up your Astryx context. Read the generated file.',
         },
         {
           type: 'prose',
-          text: 'That\'s it. The agent-docs command generates everything your AI needs (component index, behavioral rules, CLI reference) pulled from your installed version. After a version bump, run it again to update in place.',
+          text: 'That\'s it. The `init --features agents` command generates everything your AI needs (component index, behavioral rules, CLI reference) pulled from your installed version. After a version bump, run it again to update in place.',
         },
         {
           type: 'prose',
@@ -48,9 +48,9 @@ export const docs = {
           type: 'code',
           lang: 'bash',
           label: 'Manual options',
-          code: `npx astryx agent-docs --agent claude    # CLAUDE.md
-npx astryx agent-docs --agent cursor    # .cursorrules
-npx astryx agent-docs --agent codex     # AGENTS.md (Copilot, Codex, etc.)`,
+          code: `npx astryx init --features agents --agent claude    # CLAUDE.md
+npx astryx init --features agents --agent cursor    # .cursorrules
+npx astryx init --features agents --agent codex     # AGENTS.md (Copilot, Codex, etc.)`,
         },
       ],
     },
@@ -88,7 +88,7 @@ npx astryx agent-docs --agent codex     # AGENTS.md (Copilot, Codex, etc.)`,
           lang: 'bash',
           label: 'Install as a Cursor user rule',
           code: `mkdir -p ~/.cursor/rules
-npx astryx agent-docs --agent-docs-path ~/.cursor/rules/xds.mdc`,
+npx astryx init --features agents --agent-docs-path ~/.cursor/rules/xds.mdc`,
         },
       ],
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.1-canary.2b52cdc",
+  "version": "0.1.1-canary.36fb9fb",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -63,9 +63,9 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.1.1-canary.2b52cdc",
-    "@astryxdesign/lab": "0.1.1-canary.2b52cdc",
-    "@astryxdesign/theme-neutral": "0.1.1-canary.2b52cdc",
+    "@astryxdesign/core": "0.1.1-canary.36fb9fb",
+    "@astryxdesign/lab": "0.1.1-canary.36fb9fb",
+    "@astryxdesign/theme-neutral": "0.1.1-canary.36fb9fb",
     "gpt-tokenizer": "^2.0.0"
   },
   "peerDependenciesMeta": {
@@ -80,9 +80,9 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/core": "0.1.1-canary.2b52cdc",
-    "@astryxdesign/lab": "0.1.1-canary.2b52cdc",
-    "@astryxdesign/theme-neutral": "0.1.1-canary.2b52cdc",
+    "@astryxdesign/core": "0.1.1-canary.36fb9fb",
+    "@astryxdesign/lab": "0.1.1-canary.36fb9fb",
+    "@astryxdesign/theme-neutral": "0.1.1-canary.36fb9fb",
     "gpt-tokenizer": "^2.0.0"
   },
   "scripts": {

package/src/codemods/__tests__/registry.test.mjs

@@ -17,6 +17,7 @@ describe('registry', () => {
         '0.0.14',
         '0.0.15',
         '0.1.0',
+        '0.1.2',
       ]);
     });
   });

package/src/codemods/registry.mjs

@@ -18,6 +18,7 @@ const registry = new Map([
   ['0.0.14', () => import('./transforms/v0.0.14/index.mjs')],
   ['0.0.15', () => import('./transforms/v0.0.15/index.mjs')],
   ['0.1.0', () => import('./transforms/v0.1.0/index.mjs')],
+  ['0.1.2', () => import('./transforms/v0.1.2/index.mjs')],
 ]);
 
 // Re-export from the shared utility so registry callers and other consumers

package/src/codemods/transforms/v0.1.2/__tests__/rename-text-color-active-to-accent.test.mjs

@@ -0,0 +1,120 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+async function applyTransform(source) {
+  const {default: transform} =
+    await import('../rename-text-color-active-to-accent.mjs');
+  const jscodeshift = (await import('jscodeshift')).default;
+  const j = jscodeshift.withParser('tsx');
+  const api = {jscodeshift: j, stats: () => {}, report: () => {}};
+  const file = {source, path: 'test.tsx'};
+  const result = transform(file, api);
+  return result ?? source;
+}
+
+describe('rename-text-color-active-to-accent', () => {
+  it('renames Text color="active" to color="accent"', async () => {
+    const input = `<Text color="active">Hi</Text>`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain('active');
+  });
+
+  it('renames Heading color="active" to color="accent"', async () => {
+    const input = `<Heading level={2} color="active">Title</Heading>`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain('active');
+  });
+
+  it('renames Link color="active" to color="accent"', async () => {
+    const input = `<Link href="/x" color="active">Go</Link>`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain('active');
+  });
+
+  it('renames Timestamp color="active" to color="accent"', async () => {
+    const input = `<Timestamp value={d} color="active" />`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain('active');
+  });
+
+  it("renames expression-container color={'active'}", async () => {
+    const input = `<Text color={'active'}>Hi</Text>`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain("'active'");
+  });
+
+  it('renames active inside a ternary color expression', async () => {
+    const input = `<Text color={isOn ? 'active' : 'secondary'}>Hi</Text>`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).toContain("'secondary'");
+    expect(output).not.toContain("'active'");
+  });
+
+  it('does not change other color values', async () => {
+    const input = `<Text color="secondary">Hi</Text>`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('does not touch color="active" on non-target components', async () => {
+    const input = `<StatusDot color="active" />`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('does not touch unrelated "active" string literals', async () => {
+    const input = `const node = {id: 'active', label: 'Active Users'};`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('does not touch a status enum value named active', async () => {
+    const input = `const filters = {status: 'active'};`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('renames object color prop in files importing a target component', async () => {
+    const input = `import {Text} from '@xds/core/Text';
+const cfg = {color: 'active'};`;
+    const output = await applyTransform(input);
+    expect(output).toContain("color: 'accent'");
+    expect(output).not.toContain("'active'");
+  });
+
+  it("renames color: 'active' as const in files importing a target component", async () => {
+    const input = `import {Text} from '@xds/core/Text';
+const COLORS = [{color: 'active' as const, description: 'Accent'}];`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent' as const");
+    expect(output).not.toContain("'active'");
+  });
+
+  it('does not rename object color prop when no target component is imported', async () => {
+    const input = `const cfg = {color: 'active'};`;
+    const output = await applyTransform(input);
+    expect(output).toBe(input);
+  });
+
+  it('renames active in Storybook color argTypes options', async () => {
+    const input = `import {Text} from '@xds/core/Text';
+const meta = {argTypes: {color: {control: 'select', options: ['primary', 'active', 'inherit']}}};`;
+    const output = await applyTransform(input);
+    expect(output).toContain("'accent'");
+    expect(output).not.toContain("'active'");
+  });
+
+  it('returns undefined (no change) when nothing matches', async () => {
+    const input = `<Text color="primary">Hi</Text>`;
+    const output = await applyTransform(input);
+    // applyTransform falls back to source when transform returns undefined
+    expect(output).toBe(input);
+  });
+});

package/src/codemods/transforms/v0.1.2/index.mjs

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file v0.1.2 transform manifest
+ *
+ * Lists all codemods for the v0.1.2 release in the order they should run.
+ */
+
+import renameTextColorActiveToAccent, {
+  meta as renameTextColorActiveToAccentMeta,
+} from './rename-text-color-active-to-accent.mjs';
+
+export default [
+  {
+    name: 'rename-text-color-active-to-accent',
+    transform: renameTextColorActiveToAccent,
+    meta: renameTextColorActiveToAccentMeta,
+  },
+];

package/src/codemods/transforms/v0.1.2/rename-text-color-active-to-accent.mjs

@@ -0,0 +1,136 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Codemod: Rename Text/Heading/Link/Timestamp color "active" to "accent"
+ * @see https://github.com/facebook/astryx/issues/2863
+ *
+ * The `active` text-color value is renamed to `accent` and now maps to the
+ * dedicated `--color-text-accent` token (legible accent ink) instead of
+ * `--color-accent` (the interactive/base accent surface). This gives a
+ * first-class, type-safe way to render accent-colored text and resolves the
+ * gap reported in #2863.
+ *
+ * Transforms (scoped to Text, Heading, Link, and Timestamp):
+ * - <Text color="active" />            → <Text color="accent" />
+ * - <Heading color={'active'} />       → <Heading color={'accent'} />
+ * - <Text color={cond ? 'active' : x}> → <Text color={cond ? 'accent' : x}>
+ * - Storybook argTypes: color: { options: [..., 'active', ...] }
+ *     → replaces 'active' with 'accent' (files importing a target component)
+ * - Object properties: { color: 'active' } / { color: 'active' as const }
+ *     → { color: 'accent' } (files importing a target component)
+ *
+ * The transform deliberately does NOT touch bare `'active'` strings that are
+ * not a `color` value (e.g. status enums, ids, filter values), so it is safe
+ * to run across an entire codebase.
+ */
+
+export const meta = {
+  title: 'Rename Text/Heading/Link/Timestamp color "active" to "accent"',
+  description:
+    'Renames the `color="active"` value to `color="accent"` on Text, Heading, ' +
+    'Link, and Timestamp. The `accent` value maps to `--color-text-accent` ' +
+    '(the dedicated accent text ink). Also updates Storybook color argTypes ' +
+    'options and object-literal `color` props in files that import a target component.',
+  pr: '#2863',
+};
+
+const OLD_VALUE = 'active';
+const NEW_VALUE = 'accent';
+
+/** Components whose `color` prop accepts a TextColor value. */
+const TARGET_COMPONENTS = new Set(['Text', 'Heading', 'Link', 'Timestamp']);
+
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let hasChanges = false;
+
+  /** Rewrite a string-literal node when it equals the old value. */
+  function renameStringLiteral(node) {
+    if (!node) return false;
+    if (
+      (node.type === 'StringLiteral' || node.type === 'Literal') &&
+      node.value === OLD_VALUE
+    ) {
+      node.value = NEW_VALUE;
+      if (node.raw) node.raw = `'${NEW_VALUE}'`;
+      return true;
+    }
+    return false;
+  }
+
+  /** Recursively rewrite the old value inside ternary/logical expressions. */
+  function renameInExpression(node) {
+    if (!node) return false;
+    let changed = false;
+    if (node.type === 'StringLiteral' || node.type === 'Literal') {
+      changed = renameStringLiteral(node) || changed;
+    } else if (node.type === 'ConditionalExpression') {
+      changed = renameInExpression(node.consequent) || changed;
+      changed = renameInExpression(node.alternate) || changed;
+    } else if (node.type === 'LogicalExpression') {
+      changed = renameInExpression(node.left) || changed;
+      changed = renameInExpression(node.right) || changed;
+    } else if (node.type === 'TSAsExpression') {
+      // `'active' as const` → rewrite the inner expression
+      changed = renameInExpression(node.expression) || changed;
+    }
+    return changed;
+  }
+
+  // --- 1. JSX attribute: color="active" / color={'active'} on target components ---
+  root.find(j.JSXOpeningElement).forEach(path => {
+    const name = path.node.name;
+    const componentName = name.type === 'JSXIdentifier' ? name.name : null;
+    if (!componentName || !TARGET_COMPONENTS.has(componentName)) return;
+
+    path.node.attributes.forEach(attr => {
+      if (attr.type !== 'JSXAttribute') return;
+      if (!attr.name || attr.name.name !== 'color') return;
+
+      const value = attr.value;
+      if (!value) return;
+
+      if (value.type === 'StringLiteral' || value.type === 'Literal') {
+        if (renameStringLiteral(value)) hasChanges = true;
+      } else if (value.type === 'JSXExpressionContainer') {
+        if (renameInExpression(value.expression)) hasChanges = true;
+      }
+    });
+  });
+
+  // Object-property / argTypes transforms only run in files that use a target
+  // component — keeps unrelated `{ color: 'active' }` / `'active'` strings safe.
+  const importsTarget =
+    root
+      .find(j.ImportSpecifier)
+      .filter(p => TARGET_COMPONENTS.has(p.node.imported?.name))
+      .size() > 0;
+
+  if (importsTarget) {
+    const PropertyType = j.ObjectProperty ?? j.Property;
+
+    // --- 2. Object property: { color: 'active' } / { color: 'active' as const } ---
+    root.find(PropertyType, {key: {name: 'color'}}).forEach(path => {
+      if (renameInExpression(path.node.value)) hasChanges = true;
+    });
+
+    // --- 3. Storybook argTypes: color: { options: [..., 'active', ...] } ---
+    root.find(PropertyType, {key: {name: 'color'}}).forEach(path => {
+      const value = path.node.value;
+      if (!value || value.type !== 'ObjectExpression') return;
+
+      const optionsProp = value.properties.find(
+        p => p.key && (p.key.name === 'options' || p.key.value === 'options'),
+      );
+      if (optionsProp && optionsProp.value.type === 'ArrayExpression') {
+        optionsProp.value.elements.forEach(el => {
+          if (renameStringLiteral(el)) hasChanges = true;
+        });
+      }
+    });
+  }
+
+  if (!hasChanges) return undefined;
+  return root.toSource({quote: 'single'});
+}

package/src/commands/upgrade.mjs

@@ -438,7 +438,7 @@ export function registerUpgrade(program) {
         } catch {
           if (!json) {
             p.log.warn(
-              `Could not update agent docs. Run \`${getRunPrefix()} astryx agent-docs\` to update manually.`,
+              `Could not update agent docs. Run \`${getRunPrefix()} astryx init --features agents\` to update manually.`,
             );
           }
         }

package/src/lib/xle/browser.d.ts

@@ -79,8 +79,17 @@ export function hydrateRegistry(json: SerializedRegistry): object;
 export function serializeRegistry(registry: object): SerializedRegistry;
 export function parse(source: string, opts?: {form?: string}): unknown;
 export function detectForm(source: string): 'compact' | 'outline';
-export function validate(doc: unknown, registry: object, blocks?: XLEBlock[], opts?: {loose?: boolean}): {errors: XLEIssue[]; warnings: XLEIssue[]};
-export function expand(doc: unknown, registry: object, opts?: {componentName?: string}): {code: string; componentsUsed: string[]; states: number; todos: string[]};
+export function validate(
+  doc: unknown,
+  registry: object,
+  blocks?: XLEBlock[],
+  opts?: {loose?: boolean},
+): {errors: XLEIssue[]; warnings: XLEIssue[]};
+export function expand(
+  doc: unknown,
+  registry: object,
+  opts?: {componentName?: string},
+): {code: string; componentsUsed: string[]; states: number; todos: string[]};
 export function toCompact(doc: unknown): string;
 export function toOutline(doc: unknown): string;
 export const ALIAS_TABLE: Record<string, string>;

package/templates/blocks/components/Card/ClickableCardWithNestedButton.doc.mjs

@@ -5,7 +5,7 @@ export const doc = {
   type: 'block',
   exampleFor: 'ClickableCard',
   name: 'ClickableCardWithNestedButton',
-  displayName: 'Clickable Card With Nested Button',
+  displayName: 'Clickable Card — Nested Button',
   description:
     'A product card that navigates on click but has an independent "Add to cart" button inside.',
   isReady: true,

package/templates/blocks/components/Card/SelectableCardMulti.doc.mjs

@@ -5,7 +5,7 @@ export const doc = {
   type: 'block',
   exampleFor: 'SelectableCard',
   name: 'SelectableCardMulti',
-  displayName: 'Selectable Card Multi',
+  displayName: 'Selectable Card — Multi-select',
   description:
     'Multi-select tag picker using color variant selectable cards with color-matched selection borders.',
   isReady: true,

package/templates/blocks/components/ChatDictationButton/ChatDictationButtonShowcase.tsx

@@ -19,7 +19,7 @@ export default function ChatDictationButtonShowcase() {
   const dictation = useChatDictation({
     inputRef,
     hasSounds: true,
-    onResult: (text) => {
+    onResult: text => {
       console.log('Dictation result:', text);
     },
   });
@@ -31,7 +31,7 @@ export default function ChatDictationButtonShowcase() {
         input.
       </Text>
       <ChatComposer
-        onSubmit={(v) => console.log('Submit:', v)}
+        onSubmit={v => console.log('Submit:', v)}
         input={<ChatComposerInput handleRef={inputRef} />}
         sendActions={<ChatDictationButton dictation={dictation} />}
       />
@@ -63,7 +63,7 @@ export default function ChatDictationButtonShowcase() {
         </HStack>
       )}
       {!dictation.isSupported && (
-        <Text type="supporting" color="active">
+        <Text type="supporting" color="accent">
           SpeechRecognition is not supported in this browser.
         </Text>
       )}

package/templates/blocks/components/FileInput/FileInputShowcase.tsx

@@ -2,15 +2,17 @@
 
 'use client';
 
+import {useState} from 'react';
 import {FileInput} from '@astryxdesign/core/FileInput';
 
 export default function FileInputShowcase() {
+  const [value, setValue] = useState<File | File[] | null>(null);
   return (
     <div style={{width: 350}}>
       <FileInput
         label="Upload file"
-        value={null}
-        onChange={() => {}}
+        value={value}
+        onChange={setValue}
         placeholder="Drag files here or click to browse"
       />
     </div>

package/templates/blocks/components/LinkProvider/LinkProviderCustomLink.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'LinkProvider',
+  name: 'Link Provider — Custom Link Component',
+  displayName: 'Link Provider — Custom Link Component',
+  description:
+    'Routes every Astryx link through a custom component that intercepts the click — the hook frameworks like Next.js use for client-side navigation. Click the link to see the custom handler fire instead of a full-page load.',
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['LinkProvider', 'Link'],
+};

package/templates/blocks/components/LinkProvider/LinkProviderCustomLink.tsx

@@ -0,0 +1,43 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import type {AnchorHTMLAttributes} from 'react';
+import {Link, LinkProvider} from '@astryxdesign/core/Link';
+
+/**
+ * A stand-in for a framework router link (e.g. Next.js `Link` or React
+ * Router `Link`). Instead of letting the browser do a full-page navigation,
+ * it intercepts the click and hands the destination to a custom handler —
+ * the same hook real routers use for client-side navigation. Here it just
+ * announces the target so the behavior swap is observable in the preview.
+ */
+function RouterLink({
+  href,
+  onClick,
+  children,
+  ...props
+}: AnchorHTMLAttributes<HTMLAnchorElement>) {
+  return (
+    <a
+      href={href}
+      onClick={e => {
+        e.preventDefault();
+        onClick?.(e);
+        alert(`RouterLink intercepted navigation to: ${href}`);
+      }}
+      {...props}>
+      {children}
+    </a>
+  );
+}
+
+export default function LinkProviderCustomLink() {
+  return (
+    <LinkProvider component={RouterLink}>
+      <Link href="/dashboard" isStandalone>
+        Go to dashboard
+      </Link>
+    </LinkProvider>
+  );
+}

package/templates/blocks/components/MultiSelector/MultiSelectorShowcase.tsx

@@ -1,15 +1,19 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+'use client';
+
+import {useState} from 'react';
 import {MultiSelector} from '@astryxdesign/core/MultiSelector';
 
 export default function MultiSelectorShowcase() {
+  const [value, setValue] = useState<string[]>([]);
   return (
     <div style={{width: 300}}>
       <MultiSelector
         label="Columns"
         options={['Name', 'Email', 'Role', 'Status', 'Created']}
-        value={[]}
-        onChange={() => {}}
+        value={value}
+        onChange={setValue}
         placeholder="Select columns..."
       />
     </div>

package/templates/blocks/components/NumberInput/NumberInputShowcase.tsx

@@ -1,15 +1,19 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+'use client';
+
+import {useState} from 'react';
 import {NumberInput} from '@astryxdesign/core/NumberInput';
 
 export default function NumberInputShowcase() {
+  const [value, setValue] = useState<number | null>(0);
   return (
     <div style={{width: 300}}>
       <NumberInput
         label="Quantity"
         placeholder="Enter quantity"
-        value={0}
-        onChange={() => {}}
+        value={value}
+        onChange={setValue}
       />
     </div>
   );

package/templates/blocks/components/RadioList/RadioListShowcase.tsx

@@ -1,10 +1,17 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+'use client';
+
+import {useState} from 'react';
 import {RadioList, RadioListItem} from '@astryxdesign/core/RadioList';
 
 export default function RadioListShowcase() {
+  const [value, setValue] = useState('');
   return (
-    <RadioList label="Notification preference" value="" onChange={() => {}}>
+    <RadioList
+      label="Notification preference"
+      value={value}
+      onChange={setValue}>
       <RadioListItem label="Email" value="email" />
       <RadioListItem label="SMS" value="sms" />
       <RadioListItem label="Push notification" value="push" />

package/templates/blocks/components/SegmentedControl/SegmentedControlShowcase.tsx

@@ -2,14 +2,16 @@
 
 'use client';
 
+import {useState} from 'react';
 import {
   SegmentedControl,
   SegmentedControlItem,
 } from '@astryxdesign/core/SegmentedControl';
 
 export default function SegmentedControlShowcase() {
+  const [value, setValue] = useState('grid');
   return (
-    <SegmentedControl value="grid" onChange={() => {}} label="View mode">
+    <SegmentedControl value={value} onChange={setValue} label="View mode">
       <SegmentedControlItem value="grid" label="Grid" />
       <SegmentedControlItem value="list" label="List" />
       <SegmentedControlItem value="table" label="Table" />

package/templates/blocks/components/Selector/SelectorShowcase.tsx

@@ -2,16 +2,19 @@
 
 'use client';
 
+import {useState} from 'react';
 import {Selector} from '@astryxdesign/core/Selector';
 
 export default function SelectorShowcase() {
+  const [value, setValue] = useState<string | undefined>();
   return (
     <Selector
       style={{width: 300}}
       label="Fruit"
       options={['Apple', 'Banana', 'Orange', 'Mango', 'Pineapple']}
       placeholder="Select a fruit..."
-      onChange={() => {}}
+      value={value}
+      onChange={setValue}
     />
   );
 }

package/templates/blocks/components/Tab/TabShowcase.tsx

@@ -2,12 +2,14 @@
 
 'use client';
 
+import {useState} from 'react';
 import {TabList, Tab} from '@astryxdesign/core/TabList';
 import {Badge} from '@astryxdesign/core/Badge';
 
 export default function TabShowcase() {
+  const [value, setValue] = useState('inbox');
   return (
-    <TabList value="inbox" onChange={() => {}}>
+    <TabList value={value} onChange={setValue}>
       <Tab
         value="inbox"
         label="Inbox"

package/templates/blocks/components/TabList/TabListShowcase.tsx

@@ -2,11 +2,13 @@
 
 'use client';
 
+import {useState} from 'react';
 import {TabList, Tab} from '@astryxdesign/core/TabList';
 
 export default function TabListShowcase() {
+  const [value, setValue] = useState('home');
   return (
-    <TabList value="home" onChange={() => {}}>
+    <TabList value={value} onChange={setValue}>
       <Tab value="home" label="Home" />
       <Tab value="projects" label="Projects" />
       <Tab value="settings" label="Settings" />

package/templates/blocks/components/TabMenu/TabMenuShowcase.tsx

@@ -2,11 +2,13 @@
 
 'use client';
 
+import {useState} from 'react';
 import {TabList, Tab, TabMenu} from '@astryxdesign/core/TabList';
 
 export default function TabMenuShowcase() {
+  const [value, setValue] = useState('settings');
   return (
-    <TabList value="settings" onChange={() => {}}>
+    <TabList value={value} onChange={setValue}>
       <Tab value="overview" label="Overview" />
       <Tab value="activity" label="Activity" />
       <TabMenu

package/templates/blocks/components/Table/ColumnResizeHookUsage.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'useTableColumnResize',
+  name: 'useTableColumnResize — Draggable Columns',
+  displayName: 'useTableColumnResize — Draggable Columns',
+  description:
+    'A Table using useTableColumnResize. Drag the right edge of any column header to resize; widths are committed on release. The last proportional column flexes to fill remaining space.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Table'],
+};

package/templates/blocks/components/Table/ColumnResizeHookUsage.tsx

@@ -0,0 +1,59 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useState} from 'react';
+import {
+  Table,
+  useTableColumnResize,
+  proportional,
+  pixel,
+} from '@astryxdesign/core/Table';
+
+interface User extends Record<string, unknown> {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+}
+
+const users: User[] = [
+  {
+    id: '1',
+    name: 'Alice Johnson',
+    email: 'alice@example.com',
+    role: 'Engineer',
+  },
+  {id: '2', name: 'Bob Smith', email: 'bob@example.com', role: 'Designer'},
+  {id: '3', name: 'Charlie Brown', email: 'charlie@example.com', role: 'PM'},
+  {id: '4', name: 'Diana Prince', email: 'diana@example.com', role: 'Engineer'},
+  {id: '5', name: 'Eve Davis', email: 'eve@example.com', role: 'Analyst'},
+];
+
+const columns = [
+  {key: 'name', header: 'Name'},
+  {key: 'email', header: 'Email', width: proportional(2)},
+  {key: 'role', header: 'Role', width: pixel(120)},
+];
+
+export default function ColumnResizeHookUsage() {
+  const [columnWidths, setColumnWidths] = useState<Record<string, number>>({});
+
+  const columnResize = useTableColumnResize({
+    columnWidths,
+    columns,
+    onColumnResizeEnd: updates => {
+      setColumnWidths(prev => ({...prev, ...updates}));
+    },
+  });
+
+  return (
+    <Table
+      data={users}
+      columns={columns}
+      idKey="id"
+      hasHover
+      plugins={{columnResize}}
+    />
+  );
+}

package/templates/blocks/components/Table/StickyColumnsHookUsage.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'useTableStickyColumns',
+  name: 'useTableStickyColumns — Pinned Columns',
+  displayName: 'useTableStickyColumns — Pinned Columns',
+  description:
+    'A Table using useTableStickyColumns to pin the Name column to the start edge and Status to the end edge. Scroll horizontally — pinned columns stay in view with a soft shadow over the scrolling content.',
+  isReady: true,
+  aspectRatio: 16 / 9,
+  componentsUsed: ['Table'],
+};

package/templates/blocks/components/Table/StickyColumnsHookUsage.tsx

@@ -0,0 +1,104 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Table, useTableStickyColumns, pixel} from '@astryxdesign/core/Table';
+
+interface Employee extends Record<string, unknown> {
+  id: string;
+  name: string;
+  email: string;
+  team: string;
+  role: string;
+  location: string;
+  startDate: string;
+  status: string;
+}
+
+const employees: Employee[] = [
+  {
+    id: '1',
+    name: 'Alice Johnson',
+    email: 'alice@example.com',
+    team: 'Design Systems',
+    role: 'Staff Engineer',
+    location: 'San Francisco',
+    startDate: '2019-03-12',
+    status: 'Active',
+  },
+  {
+    id: '2',
+    name: 'Bob Smith',
+    email: 'bob@example.com',
+    team: 'Design Systems',
+    role: 'Senior Designer',
+    location: 'New York',
+    startDate: '2020-07-01',
+    status: 'Active',
+  },
+  {
+    id: '3',
+    name: 'Charlie Brown',
+    email: 'charlie@example.com',
+    team: 'Platform',
+    role: 'Engineering Manager',
+    location: 'London',
+    startDate: '2017-11-20',
+    status: 'On leave',
+  },
+  {
+    id: '4',
+    name: 'Diana Prince',
+    email: 'diana@example.com',
+    team: 'Platform',
+    role: 'Staff Engineer',
+    location: 'Remote',
+    startDate: '2021-01-15',
+    status: 'Active',
+  },
+  {
+    id: '5',
+    name: 'Eve Davis',
+    email: 'eve@example.com',
+    team: 'Growth',
+    role: 'Product Engineer',
+    location: 'Berlin',
+    startDate: '2022-05-30',
+    status: 'Active',
+  },
+];
+
+// Wide fixed-width columns so the table overflows and scrolls horizontally,
+// keeping the pinned Name (start) and Status (end) columns in view.
+const columns = [
+  {key: 'name', header: 'Name', width: pixel(180)},
+  {key: 'email', header: 'Email', width: pixel(220)},
+  {key: 'team', header: 'Team', width: pixel(180)},
+  {key: 'role', header: 'Role', width: pixel(200)},
+  {key: 'location', header: 'Location', width: pixel(160)},
+  {key: 'startDate', header: 'Start date', width: pixel(140)},
+  {key: 'status', header: 'Status', width: pixel(140)},
+];
+
+export default function StickyColumnsHookUsage() {
+  const stickyColumns = useTableStickyColumns<Employee>({
+    startKeys: ['name'],
+    endKeys: ['status'],
+  });
+
+  return (
+    // Constrain the width so the Table's own horizontal scroll container is
+    // narrower than its columns — that scroll container is what sticky columns
+    // pin against. Without a width cap the table renders full-width and never
+    // scrolls internally, so nothing sticks.
+    <div style={{width: 560, maxWidth: '100%'}}>
+      <Table
+        data={employees}
+        columns={columns}
+        idKey="id"
+        hasHover
+        plugins={{stickyColumns}}
+      />
+    </div>
+  );
+}

package/templates/blocks/components/Text/TextColors.tsx

@@ -6,11 +6,26 @@ import {Text} from '@astryxdesign/core/Text';
 import {Stack} from '@astryxdesign/core/Stack';
 
 const COLORS = [
-  {color: 'primary' as const, description: 'Primary — Default for headings and body text'},
-  {color: 'secondary' as const, description: 'Secondary — Supporting details and metadata'},
-  {color: 'active' as const, description: 'Active — Links, success states, and emphasis'},
-  {color: 'disabled' as const, description: 'Disabled — Unavailable or inactive content'},
-  {color: 'placeholder' as const, description: 'Placeholder — Empty field hints'},
+  {
+    color: 'primary' as const,
+    description: 'Primary — Default for headings and body text',
+  },
+  {
+    color: 'secondary' as const,
+    description: 'Secondary — Supporting details and metadata',
+  },
+  {
+    color: 'accent' as const,
+    description: 'Accent — Links, emphasis, and accent-colored text',
+  },
+  {
+    color: 'disabled' as const,
+    description: 'Disabled — Unavailable or inactive content',
+  },
+  {
+    color: 'placeholder' as const,
+    description: 'Placeholder — Empty field hints',
+  },
 ];
 
 export default function TextColors() {

package/templates/blocks/components/TextArea/TextAreaShowcase.tsx

@@ -2,15 +2,17 @@
 
 'use client';
 
+import {useState} from 'react';
 import {TextArea} from '@astryxdesign/core/TextArea';
 
 export default function TextAreaShowcase() {
+  const [value, setValue] = useState('');
   return (
     <div style={{width: 400}}>
       <TextArea
         label="Description"
-        value=""
-        onChange={() => {}}
+        value={value}
+        onChange={setValue}
         placeholder="Enter a description..."
       />
     </div>

package/templates/blocks/components/TextInput/TextInputShowcase.tsx

@@ -2,15 +2,17 @@
 
 'use client';
 
+import {useState} from 'react';
 import {TextInput} from '@astryxdesign/core/TextInput';
 
 export default function TextInputShowcase() {
+  const [value, setValue] = useState('');
   return (
     <div style={{width: 300}}>
       <TextInput
         label="Name"
-        value=""
-        onChange={() => {}}
+        value={value}
+        onChange={setValue}
         placeholder="Enter your name"
       />
     </div>

package/templates/blocks/components/Thumbnail/ThumbnailGallery.tsx

@@ -8,10 +8,30 @@ import {Stack} from '@astryxdesign/core/Layout';
 import {Text} from '@astryxdesign/core/Text';
 
 const ATTACHMENTS = [
-  {id: 1, src: 'https://lookaside.facebook.com/assets/astryx/illustrative-vertical-1.png', alt: 'River through a valley', label: 'valley.jpg'},
-  {id: 2, src: 'https://lookaside.facebook.com/assets/astryx/illustrative-vertical-2.png', alt: 'Foggy mountain peak', label: 'mountain.jpg'},
-  {id: 3, src: 'https://lookaside.facebook.com/assets/astryx/illustrative-vertical-3.png', alt: 'Golden retriever puppy', label: 'puppy.jpg'},
-  {id: 4, src: 'https://lookaside.facebook.com/assets/astryx/illustrative-vertical-4.png', alt: 'Bridge at sunset', label: 'bridge.jpg'},
+  {
+    id: 1,
+    src: 'https://lookaside.facebook.com/assets/astryx/illustrative-vertical-1.png',
+    alt: 'River through a valley',
+    label: 'valley.jpg',
+  },
+  {
+    id: 2,
+    src: 'https://lookaside.facebook.com/assets/astryx/illustrative-vertical-2.png',
+    alt: 'Foggy mountain peak',
+    label: 'mountain.jpg',
+  },
+  {
+    id: 3,
+    src: 'https://lookaside.facebook.com/assets/astryx/illustrative-vertical-3.png',
+    alt: 'Golden retriever puppy',
+    label: 'puppy.jpg',
+  },
+  {
+    id: 4,
+    src: 'https://lookaside.facebook.com/assets/astryx/illustrative-vertical-4.png',
+    alt: 'Bridge at sunset',
+    label: 'bridge.jpg',
+  },
 ];
 
 export default function ThumbnailGallery() {
@@ -38,7 +58,7 @@ export default function ThumbnailGallery() {
         ))}
       </Stack>
       {selected != null && (
-        <Text type="supporting" color="active">
+        <Text type="supporting" color="accent">
           Previewing: {selected}
         </Text>
       )}

package/templates/blocks/components/Timestamp/TimestampColors.tsx

@@ -31,9 +31,9 @@ export default function TimestampColors() {
       </Stack>
       <Stack direction="vertical" gap={1}>
         <Text type="supporting" color="secondary">
-          Active
+          Accent
         </Text>
-        <Timestamp value={DATE} format="date_time" color="active" />
+        <Timestamp value={DATE} format="date_time" color="accent" />
       </Stack>
     </Stack>
   );

package/templates/blocks/components/Tokenizer/TokenizerShowcase.tsx

@@ -2,8 +2,9 @@
 
 'use client';
 
+import {useState} from 'react';
 import {Tokenizer} from '@astryxdesign/core/Tokenizer';
-import type {SearchSource} from '@astryxdesign/core/Typeahead';
+import type {SearchableItem, SearchSource} from '@astryxdesign/core/Typeahead';
 
 const source: SearchSource = {
   search: () => [],
@@ -11,16 +12,17 @@ const source: SearchSource = {
 };
 
 export default function TokenizerShowcase() {
+  const [value, setValue] = useState<SearchableItem[]>([
+    {id: '1', label: 'Design'},
+    {id: '2', label: 'Engineering'},
+  ]);
   return (
     <Tokenizer
       label="Tags"
       placeholder="Search..."
       searchSource={source}
-      value={[
-        {id: '1', label: 'Design'},
-        {id: '2', label: 'Engineering'},
-      ]}
-      onChange={() => {}}
+      value={value}
+      onChange={setValue}
       style={{width: 400}}
     />
   );

package/templates/blocks/components/Typeahead/TypeaheadShowcase.tsx

@@ -1,5 +1,8 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+'use client';
+
+import {useState} from 'react';
 import {Typeahead} from '@astryxdesign/core/Typeahead';
 import type {SearchableItem, SearchSource} from '@astryxdesign/core/Typeahead';
 
@@ -21,14 +24,15 @@ const fruitSource: SearchSource = {
 };
 
 export default function TypeaheadShowcase() {
+  const [value, setValue] = useState<SearchableItem | null>(null);
   return (
     <div style={{width: 320}}>
       <Typeahead
         label="Fruit"
         placeholder="Search fruits..."
         searchSource={fruitSource}
-        value={null}
-        onChange={() => {}}
+        value={value}
+        onChange={setValue}
       />
     </div>
   );

package/templates/pages/theme-showcase/page.tsx

@@ -143,12 +143,6 @@ const styles: Record<string, CSSProperties> = {
     textAlign: 'center' as const,
     maxWidth: 560,
   },
-  // Hero headline painted with the theme's accent-text ink. Text has no
-  // 'accent' color value, so we set the dedicated --color-text-accent token
-  // directly (distinct from --color-accent / the 'active' color).
-  heroHeadline: {
-    color: 'var(--color-text-accent)',
-  },
   centerText: {
     textAlign: 'center',
   },
@@ -438,7 +432,7 @@ function StorePreview({
           <VStack gap={10} style={{...styles.content, ...styles.contentFluid}}>
             <Center>
               <VStack gap={4} hAlign="center" style={styles.heroText}>
-                <Text type="display-2" style={styles.heroHeadline}>
+                <Text type="display-2" color="accent">
                   Little joys,
                   <br />
                   everywhere you go
@@ -462,10 +456,7 @@ function StorePreview({
                       />
                     </AspectRatio>
                     <div style={inlineStyles.cardBody}>
-                      <VStack
-                        gap={2}
-                        hAlign="center"
-                        style={styles.cardStack}>
+                      <VStack gap={2} hAlign="center" style={styles.cardStack}>
                         <HStack>
                           <Badge label={p.badge} variant={p.badgeVariant} />
                         </HStack>
@@ -475,7 +466,10 @@ function StorePreview({
                         <Text
                           type="supporting"
                           color="secondary"
-                          style={{...styles.cardDescription, ...styles.centerText}}>
+                          style={{
+                            ...styles.cardDescription,
+                            ...styles.centerText,
+                          }}>
                           {p.description}
                         </Text>
                         <HStack gap={2} vAlign="center" hAlign="center">
@@ -746,9 +740,7 @@ function ChatCard() {
 
           <ChatMessage sender="assistant">
             <VStack gap={3}>
-              <Text type="body">
-                Here’s everything I have on order #1043:
-              </Text>
+              <Text type="body">Here’s everything I have on order #1043:</Text>
               <Card padding={3}>
                 <VStack gap={1}>
                   <Item
@@ -1107,10 +1099,7 @@ function InventoryCard({
   ).length;
   return (
     <Card padding={0} style={styles.inventoryCard}>
-      <HStack
-        hAlign="between"
-        vAlign="center"
-        style={styles.inventoryHeader}>
+      <HStack hAlign="between" vAlign="center" style={styles.inventoryHeader}>
         <Heading level={2}>Inventory</Heading>
         <Button
           label="Add item"