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.tsxindex 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.tsxindex 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.tsxindex 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.tsxnew file mode 100644index 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.tsxdeleted file mode 100644index 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.mjsindex 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-nextjspnpm installpnpm 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.mjsindex 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)'"],],