@tempoxyz/ds 0.3.9 → 0.3.11

package/dist/docs/introduction/getting-started.md

@@ -0,0 +1,377 @@
+# Getting Started
+
+Install Tempo Design System and render your first component.
+
+## Overview
+
+Tempo Design System is the shared design language of Tempo products. `@tempoxyz/ds` ships it as components and variables for web and React Native.
+
+The APIs accept only design system values. Zyzz compiles the components and your styles ahead of time for each platform.
+
+## Agent Prompt
+
+Paste this prompt into your coding agent:
+
+Read ds.tehq.dev and help me build my project with Tempo Design System.
+
+## Setup
+
+### Install the Library
+
+Install `@tempoxyz/ds` and its Zyzz peer.
+
+```sh
+npm install @tempoxyz/ds zyzz
+```
+
+### Choose Framework
+
+Choose a compilation target and a variable mode:
+
+* **TDS Variables (Quick):** Uses the components and variables as they ship.
+* **Custom Variables (Advanced):** Extends the TDS variables with app tokens.
+
+### Vite
+
+### Configure Vite
+
+Add Zyzz beside the existing framework plugin.
+
+```ts title="vite.config.ts"
+import { defineConfig } from 'vite'
+import { zyzz } from 'zyzz/vite'
+
+export default defineConfig({
+  plugins: [zyzz()],
+  ssr: { noExternal: ['@tempoxyz/ds', 'zyzz'] },
+})
+```
+
+Run the existing dev or build command. The plugin emits the TDS variables, the Inter, Pilat, and JetBrains Mono fonts, and keyframes once, and each component emits its own rules. You import no stylesheet.
+
+With `ssr.noExternal`, the plugin reads the library's contracts in a server build.
+
+#### TDS Variables (Quick)
+
+### Use a Component
+
+Import components from `@tempoxyz/ds`. Style your own markup with TDS tokens through `style`.
+
+```tsx title="Checkout.tsx"
+import { Button, style } from '@tempoxyz/ds'
+
+export function Checkout() {
+  return (
+    <section {...styles.card()}>
+      <p>Ready to continue?</p>
+      <Button>Continue</Button>
+    </section>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    color: 'content.primary',
+    padding: '24',
+    typography: 'body.b2',
+  })
+}
+```
+
+Tokens such as `content.primary`, `'24'`, and `body.b2` type-check against the TDS variables. Light and dark values follow the inherited `color-scheme`.
+
+#### Custom Variables (Advanced)
+
+### Define Config
+
+Extend the TDS variables with app tokens, and export the bound helpers.
+
+```ts title="zyzz.config.ts"
+import { variables } from '@tempoxyz/ds'
+import { Config, Vars } from 'zyzz'
+
+export const { style, vars } = Config.create({
+  id: 'app',
+  vars: Vars.extend(variables, { spacing: { bleed: '-0.75rem' } }, { id: 'app/vars' }),
+})
+```
+
+Place `zyzz.config.ts` at the root of the application source, such as `src/zyzz.config.ts`. The Vite plugin scans its directory for global styles.
+
+### Use a Component
+
+Apply `vars()` to the app root. Style your markup with the bound `style` helper, which accepts TDS and app tokens.
+
+```tsx title="Checkout.tsx"
+import { Button } from '@tempoxyz/ds'
+import { style, vars } from './zyzz.config.js'
+
+export function App() {
+  return (
+    <main {...vars()}>
+      <Checkout />
+    </main>
+  )
+}
+
+function Checkout() {
+  return (
+    <section {...styles.card()}>
+      <p>Ready to continue?</p>
+      <Button>Continue</Button>
+    </section>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    backgroundColor: 'background.elevated',
+    color: 'content.primary',
+    marginInline: 'bleed',
+    padding: '24',
+  })
+}
+```
+
+### Other Bundlers
+
+### Configure the Bundler
+
+Add the matching unplugin adapter to the bundler configuration. Keep the existing TypeScript and JSX transforms.
+
+```ts title="rollup.config.ts"
+import { zyzz } from 'zyzz/unplugin'
+
+const plugins = [zyzz.rollup()]
+// Use zyzz.webpack() or zyzz.esbuild() for those bundlers.
+```
+
+Load the emitted stylesheet and script in the document. Adjust the paths to the deployment base.
+
+```html title="index.html"
+<link rel="stylesheet" href="/zyzz.css" />
+<script src="/zyzz.js"></script>
+```
+
+Run the existing build command. [Bundler Setup](https://zyzz.style/docs/api/unplugin) lists the configuration for each bundler.
+
+#### TDS Variables (Quick)
+
+### Use a Component
+
+Import components from `@tempoxyz/ds`. Style your own markup with TDS tokens through `style`.
+
+```tsx title="Checkout.tsx"
+import { Button, style } from '@tempoxyz/ds'
+
+export function Checkout() {
+  return (
+    <section {...styles.card()}>
+      <p>Ready to continue?</p>
+      <Button>Continue</Button>
+    </section>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    backgroundColor: 'background.elevated',
+    borderRadius: 'sm',
+    color: 'content.primary',
+    padding: '24',
+    typography: 'body.b2',
+  })
+}
+```
+
+Tokens such as `content.primary`, `'24'`, and `body.b2` type-check against the TDS variables. Light and dark values follow the inherited `color-scheme`.
+
+#### Custom Variables (Advanced)
+
+### Define Config
+
+Extend the TDS variables with app tokens, and export the bound helpers.
+
+```ts title="zyzz.config.ts"
+import { variables } from '@tempoxyz/ds'
+import { Config, Vars } from 'zyzz'
+
+export const { style, vars } = Config.create({
+  id: 'app',
+  vars: Vars.extend(variables, { spacing: { bleed: '-0.75rem' } }, { id: 'app/vars' }),
+})
+```
+
+### Use a Component
+
+Apply `vars()` to the app root. Style your markup with the bound `style` helper, which accepts TDS and app tokens.
+
+```tsx title="Checkout.tsx"
+import { Button } from '@tempoxyz/ds'
+import { style, vars } from './zyzz.config.js'
+
+export function App() {
+  return (
+    <main {...vars()}>
+      <Checkout />
+    </main>
+  )
+}
+
+function Checkout() {
+  return (
+    <section {...styles.card()}>
+      <p>Ready to continue?</p>
+      <Button>Continue</Button>
+    </section>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    backgroundColor: 'background.elevated',
+    color: 'content.primary',
+    marginInline: 'bleed',
+    padding: '24',
+  })
+}
+```
+
+### React Native
+
+### Configure Metro
+
+Install the React Native peers, then wrap the Expo Metro configuration with Zyzz. Keep the existing transformer and Expo settings.
+
+```sh
+npx expo install expo-haptics react-native-reanimated react-native-svg react-native-worklets
+```
+
+```ts title="metro.config.ts"
+import { getDefaultConfig } from 'expo/metro-config'
+import { zyzz } from 'zyzz/metro'
+
+export default zyzz(getDefaultConfig(import.meta.dirname), {
+  fonts: { 'HB Set v0.96': 'HBSet', Inter: 'Inter', 'JetBrains Mono': 'JetBrainsMono' },
+  units: { px: 1, rem: 16 },
+})
+```
+
+`fonts` maps each Figma family to a font that your app registers. The library bundles no font files. To preview with iOS system fonts, map a family to `System`.
+
+#### TDS Variables (Quick)
+
+### Use a Component
+
+Render components from `@tempoxyz/ds/mobile` below a `Provider` at the app root. Styles resolve against the nearest `Provider` above them.
+
+```tsx title="App.tsx"
+import { Button, Provider, style } from '@tempoxyz/ds/mobile'
+import { Text, View } from 'react-native'
+
+export function App() {
+  return (
+    <Provider colorScheme="system">
+      <Checkout />
+    </Provider>
+  )
+}
+
+function Checkout() {
+  return (
+    <View {...styles.card()}>
+      <Text {...styles.label()}>Ready to continue?</Text>
+      <Button onPress={() => {}}>Continue</Button>
+    </View>
+  )
+}
+
+namespace styles {
+  export const card = style({
+    backgroundColor: 'background.elevated',
+    gap: '12',
+    paddingHorizontal: '20',
+    paddingVertical: '16',
+  })
+
+  export const label = style({ color: 'content.primary', typography: 'body.b2' })
+}
+```
+
+`colorScheme="system"` follows the device setting. To override it, pass `light` or `dark`.
+
+#### Custom Variables (Advanced)
+
+### Define Config
+
+Define app tokens in sets named `base` and `inverse`. Every Zyzz config reads the set that `Provider` selects. Reference TDS values through `variables` and `inverse`.
+
+```ts title="zyzz.config.ts"
+import { inverse as tdsInverse, variables } from '@tempoxyz/ds/mobile'
+import { Vars } from 'zyzz'
+import { defineConfig } from 'zyzz/react-native'
+
+export const base = Vars.define({
+  color: {
+    caption: { light: variables.color.content.secondary, dark: variables.color.content.secondary },
+  },
+})
+
+export const inverse = Vars.extend(base, {
+  color: {
+    caption: {
+      light: tdsInverse.color.content.secondary,
+      dark: tdsInverse.color.content.secondary,
+    },
+  },
+})
+
+export const { style } = defineConfig({ defaultVars: 'base', id: 'app', vars: { base, inverse } })
+```
+
+Zyzz extensions only replace existing tokens. Put app tokens in your own sets, not in extensions of the TDS sets.
+
+### Use a Component
+
+Render TDS components below a `Provider`. Style your own elements with the bound `style` helper.
+
+```tsx title="App.tsx"
+import { Button, Provider } from '@tempoxyz/ds/mobile'
+import { Text, View } from 'react-native'
+import { style } from './zyzz.config.js'
+
+export function App() {
+  return (
+    <Provider colorScheme="system">
+      <View>
+        <Text {...styles.caption()}>Ready to continue?</Text>
+        <Button onPress={() => {}}>Continue</Button>
+      </View>
+    </Provider>
+  )
+}
+
+namespace styles {
+  export const caption = style({ color: 'caption' })
+}
+```
+
+## Next Steps
+
+[Build a Layout](/docs/components/app-shell)
+
+Place a sticky sidebar beside the main content column.
+
+[Trigger Actions](/docs/components/button)
+
+Submit forms, send payments, and run other actions.
+
+[Collect TextInput](/docs/components/field)
+
+Link labels, descriptions, and errors to form controls.
+
+[Show Feedback](/docs/components/toast)
+
+Confirm results with brief notifications.