Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs: update getting started styling guidance (#3069)

EJ Hammond907dbbd0552f
diff --git a/apps/docsite/src/components/docs/ListBlock.tsx b/apps/docsite/src/components/docs/ListBlock.tsx
index b2f2d799fc..6e148b7240 100644
--- a/apps/docsite/src/components/docs/ListBlock.tsx
+++ b/apps/docsite/src/components/docs/ListBlock.tsx
@@ -5,7 +5,7 @@
import {Badge} from '@astryxdesign/core/Badge';
import {Table} from '@astryxdesign/core/Table';
import {List, ListItem} from '@astryxdesign/core/List';
-import {renderInlineCode} from './renderInlineCode';
+import {renderInlineMarkdown} from './inlineMarkdown';
export function ListBlock({
items,
@@ -43,7 +43,7 @@ export function ListBlock({
key: 'text',
header: 'Practice',
renderCell: (item: Record<string, unknown>) =>
- renderInlineCode(item.text as string),
+ renderInlineMarkdown(item.text as string),
},
]}
density="spacious"
@@ -62,7 +62,7 @@ export function ListBlock({
return (
<List density="compact" listStyle={xdsListStyle}>
{items.map((item, i) => (
- <ListItem key={i} label={renderInlineCode(item)} />
+ <ListItem key={i} label={renderInlineMarkdown(item)} />
))}
</List>
);
diff --git a/apps/docsite/src/components/docs/ProseBlock.tsx b/apps/docsite/src/components/docs/ProseBlock.tsx
index 8048380744..f2afdab616 100644
--- a/apps/docsite/src/components/docs/ProseBlock.tsx
+++ b/apps/docsite/src/components/docs/ProseBlock.tsx
@@ -4,7 +4,7 @@
import * as stylex from '@stylexjs/stylex';
import {Text} from '@astryxdesign/core/Text';
-import {renderInlineCode} from './renderInlineCode';
+import {renderInlineMarkdown} from './inlineMarkdown';
import {layout} from '../../layout.stylex';
const styles = stylex.create({
@@ -12,5 +12,5 @@ const styles = stylex.create({
});
export function ProseBlock({text}: {text: string}) {
- return <Text xstyle={styles.prose}>{renderInlineCode(text)}</Text>;
+ return <Text xstyle={styles.prose}>{renderInlineMarkdown(text)}</Text>;
}
diff --git a/apps/docsite/src/components/docs/TableBlock.tsx b/apps/docsite/src/components/docs/TableBlock.tsx
index 2a58ba44f9..8d3971161b 100644
--- a/apps/docsite/src/components/docs/TableBlock.tsx
+++ b/apps/docsite/src/components/docs/TableBlock.tsx
@@ -5,7 +5,7 @@
import {Text} from '@astryxdesign/core/Text';
import {Table} from '@astryxdesign/core/Table';
import {Card} from '@astryxdesign/core/Card';
-import {renderInlineCode} from './renderInlineCode';
+import {renderInlineMarkdown} from './inlineMarkdown';
export function TableBlock({
headers,
@@ -26,7 +26,7 @@ export function TableBlock({
key: h,
header: h,
renderCell: (item: Record<string, unknown>) => (
- <Text>{renderInlineCode(item[h] as string)}</Text>
+ <Text>{renderInlineMarkdown(item[h] as string)}</Text>
),
}));
diff --git a/apps/docsite/src/components/docs/inlineMarkdown.tsx b/apps/docsite/src/components/docs/inlineMarkdown.tsx
new file mode 100644
index 0000000000..905f12ba81
--- /dev/null
+++ b/apps/docsite/src/components/docs/inlineMarkdown.tsx
@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {Fragment, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Code} from '@astryxdesign/core/CodeBlock';
+
+const TOKEN = /(`([^`]+)`|\[([^\]]+)\]\(([^)]+)\))/g;
+
+const styles = stylex.create({
+ link: {
+ color: 'var(--color-text-accent)',
+ textDecorationLine: 'underline',
+ textDecorationThickness: '1px',
+ textUnderlineOffset: '0.16em',
+ transition: 'color 120ms ease, text-decoration-color 120ms ease',
+ ':hover': {
+ '@media (hover: hover)': {
+ color: 'var(--color-accent)',
+ textDecorationThickness: '2px',
+ },
+ },
+ ':focus-visible': {
+ borderRadius: 'var(--radius-sm)',
+ outline: '2px solid var(--color-accent)',
+ outlineOffset: 2,
+ },
+ },
+});
+
+function renderLink(label: string, href: string, key: number): ReactNode {
+ const isExternal = /^https?:\/\//.test(href);
+ return (
+ <a
+ key={key}
+ href={href}
+ rel={isExternal ? 'noreferrer' : undefined}
+ target={isExternal ? '_blank' : undefined}
+ {...stylex.props(styles.link)}>
+ {label}
+ </a>
+ );
+}
+
+// Render a small inline markdown subset for authored docs: code spans and links.
+export function renderInlineMarkdown(text: string) {
+ const nodes: ReactNode[] = [];
+ let lastIndex = 0;
+ let match;
+ while ((match = TOKEN.exec(text)) !== null) {
+ if (match.index > lastIndex) {
+ nodes.push(text.slice(lastIndex, match.index));
+ }
+
+ const code = match[2];
+ const linkLabel = match[3];
+ const linkHref = match[4];
+ if (code != null) {
+ nodes.push(<Code key={match.index}>{code}</Code>);
+ } else if (linkLabel != null && linkHref != null) {
+ nodes.push(renderLink(linkLabel, linkHref, match.index));
+ }
+
+ lastIndex = match.index + match[0].length;
+ }
+ if (lastIndex < text.length) {
+ nodes.push(text.slice(lastIndex));
+ }
+ return nodes.map((node, i) => <Fragment key={i}>{node}</Fragment>);
+}
diff --git a/apps/docsite/src/components/docs/renderInlineCode.tsx b/apps/docsite/src/components/docs/renderInlineCode.tsx
deleted file mode 100644
index 605f339658..0000000000
--- a/apps/docsite/src/components/docs/renderInlineCode.tsx
+++ /dev/null
@@ -1,26 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-'use client';
-
-import {Fragment} from 'react';
-import {Code} from '@astryxdesign/core/CodeBlock';
-
-const INLINE_CODE = /`([^`]+)`/g;
-
-// Render backtick-delimited spans as inline code, leaving other text as-is.
-export function renderInlineCode(text: string) {
- const nodes = [];
- let lastIndex = 0;
- let match;
- while ((match = INLINE_CODE.exec(text)) !== null) {
- if (match.index > lastIndex) {
- nodes.push(text.slice(lastIndex, match.index));
- }
- nodes.push(<Code key={match.index}>{match[1]}</Code>);
- lastIndex = match.index + match[0].length;
- }
- if (lastIndex < text.length) {
- nodes.push(text.slice(lastIndex));
- }
- return nodes.map((node, i) => <Fragment key={i}>{node}</Fragment>);
-}
diff --git a/packages/cli/docs/getting-started.doc.mjs b/packages/cli/docs/getting-started.doc.mjs
index 4944cae0fa..289f8967cb 100644
--- a/packages/cli/docs/getting-started.doc.mjs
+++ b/packages/cli/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 XDS" onClick={() => alert('Hi!')} />
+ <Button label="Hello Astryx" onClick={() => alert('Hi!')} />
</VStack>
);
}`,
@@ -96,11 +96,11 @@ export default function Page() {
],
},
{
- title: 'Customize with xstyle',
+ title: 'Customize with StyleX',
content: [
{
type: 'prose',
- text: 'Every component accepts an `xstyle` prop for StyleX style overrides created via `stylex.create()`.',
+ 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.',
},
{
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'],
- ['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'],
+ ['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)'],
],
},
{
type: 'code',
lang: 'bash',
label: 'Clone and run an example',
- code: `git clone https://github.com/facebookexperimental/xds.git
-cd xds/apps/example-nextjs
+ code: `git clone https://github.com/facebook/astryx.git
+cd astryx/apps/example-nextjs
pnpm install
pnpm dev`,
},
@@ -157,7 +157,7 @@ pnpm dev`,
lang: 'json',
label: 'package.json',
code: `"scripts": {
- "xds": "node node_modules/@astryxdesign/cli/bin/astryx.mjs"
+ "astryx": "node node_modules/@astryxdesign/cli/bin/astryx.mjs"
}`,
},
{
diff --git a/packages/cli/docs/styling.doc.mjs b/packages/cli/docs/styling.doc.mjs
index 581c86025c..fe0a73641a 100644
--- a/packages/cli/docs/styling.doc.mjs
+++ b/packages/cli/docs/styling.doc.mjs
@@ -22,9 +22,8 @@ export const docs = {
type: 'table',
headers: ['Approach', 'Use for', 'Example'],
rows: [
- ['xstyle prop', 'Overriding a specific component', 'xstyle={styles.override}'],
+ ['StyleX', 'Component-specific overrides, reusable styles, pseudo-classes, and typed tokens', 'const styles = stylex.create(...); <Button xstyle={styles.save} />'],
['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)'"],
],