@tempoxyz/ds 0.3.10 → 0.3.13

package/README.md

@@ -22,10 +22,11 @@ npm i @tempoxyz/ds zyzz
 
 ### 2. Choose Surface
 
-| I am building...     | Surface | Import                |
-| -------------------- | ------- | --------------------- |
-| A web application    | Web     | `@tempoxyz/ds`        |
-| A mobile application | Mobile  | `@tempoxyz/ds/mobile` |
+| I am building...     | Surface   | Import                   |
+| -------------------- | --------- | ------------------------ |
+| A web application    | Web       | `@tempoxyz/ds`           |
+| A mobile application | Mobile    | `@tempoxyz/ds/mobile`    |
+| A marketing website  | Marketing | `@tempoxyz/ds/marketing` |
 
 Native Apple apps add the [tempoxyz/ds-swift](https://github.com/tempoxyz/ds-swift) Swift package, which each version mirrors from `swift/`, and import `TempoDesignSystem`. It holds the Web spacing, radius, ease, duration, opacity, scale, and shadow scales as Swift constants, such as `TDS.Spacing.s16` and `TDS.Ease.snappy.animation(TDS.Duration.ms200)`. Colors and typography stay with each app.
 
@@ -77,7 +78,7 @@ export function Card() {
 
 ### 6. (Optional) Lint
 
-`@tempoxyz/ds/oxlint` ships an Oxlint plugin that checks how your app uses the library. Spread the `web` or `mobile` configuration into the `lint` options of Vite Plus. It enables the TDS rules and the Zyzz rules together.
+`@tempoxyz/ds/oxlint` ships an Oxlint plugin that checks how your app uses the library. Spread the `web`, `mobile`, or `marketing` configuration into the `lint` options of Vite Plus. It enables the TDS rules and the Zyzz rules together.
 
 ```ts
 import { web } from '@tempoxyz/ds/oxlint'
@@ -102,7 +103,7 @@ With an `.oxlintrc.json`, register both plugins and enable the rules you need:
 }
 ```
 
-- **`tds/no-cross-surface`:** Reports an import from the other surface. Without `surface`, it reports a file that imports both.
+- **`tds/no-cross-surface`:** Reports an import from another surface. Without `surface`, it reports a file that imports more than one.
 - **`tds/no-internal-imports`:** Allows only the subpaths that the package `exports` map publishes.
 - **`tds/no-raw-values`:** Warns on raw colors, lengths, and font stacks in inline `style` props.
 - **`tds/prefer-component`:** Warns on native elements that a component replaces, such as `<button>` and `<select>`. `allow` accepts element names to skip.

package/dist/docs/AGENTS.md

@@ -0,0 +1,12 @@
+# Tempo Design System for Agents
+
+These files are the documentation of `@tempoxyz/ds` as Markdown, for the version installed beside them. They describe how to use the design system in an app, not how to build the library. Each page sits at the path of its page on ds.tehq.dev, and links between pages are relative. Read them here rather than on the site, so the guidance matches the version you import.
+
+Tempo has two design systems, and this package ships both. Choose one by what you build, and start from its Getting Started page:
+
+- **Product:** Interfaces people use, such as wallets, consoles, dashboards, explorers, and internal tools. Start from [product/introduction/getting-started.md](product/introduction/getting-started.md).
+- **Marketing:** Pages that present Tempo, such as the home page and launch, campaign, and event pages. Start from [marketing/introduction/getting-started.md](marketing/introduction/getting-started.md).
+
+An app uses one system. A marketing site does not import `@tempoxyz/ds`, and a product interface does not import `@tempoxyz/ds/marketing`.
+
+Each system's folder follows its sidebar on the site, with Introduction, Foundations, and Components sections. [index.md](index.md) lists every page with its description. Before you use a component, read its page in full. For Product, also read [Agents](product/foundations/agents.md), which states the rules that generated UI follows.

package/dist/docs/index.md

@@ -0,0 +1,145 @@
+# Tempo Design System
+
+> Foundations, guidelines, and components for Tempo products and websites.
+
+Each page is the Markdown of the documentation at ds.tehq.dev for this version of the package, at the path of its page on the site. [AGENTS.md](AGENTS.md) names the page to read first.
+
+## Product
+
+### Introduction
+
+- [FAQ](product/introduction/faq.md): Common questions about building with, and contributing to, Tempo Design System.
+- [Getting Started](product/introduction/getting-started.md): Install Tempo Design System and render your first component.
+
+### Foundations
+
+- [Accessibility](product/foundations/accessibility.md): The accessibility baseline for every Tempo component, and what you still own.
+- [Agents](product/foundations/agents.md): How coding agents read these docs and the source, and the rules they follow.
+- [Color](product/foundations/color.md): Color tokens for text, surfaces, borders, and status, with contrast rules.
+- [Tone](product/foundations/content/tone.md): How Tempo's voice adjusts to the reader, from a first visit to an error.
+- [Voice](product/foundations/content/voice.md): Tempo's personality in words, consistent across every product.
+- [Writing Style](product/foundations/content/writing-style.md): How Tempo writes interface text: sentence case, a verb first, and plain words.
+- [Iconography](product/foundations/iconography.md): Icons from the Tempo catalog, and how to size, color, and label them.
+- [Building From Intent](product/foundations/intent.md): Choose each component by the job of its content, not by the markup it replaces.
+- [Layout](product/foundations/layout.md): Page structure, grid, spacing, radius, and elevation.
+- [Linter](product/foundations/linter.md): Oxlint rules that check how your app uses Tempo Design System.
+- [Motion](product/foundations/motion.md): Easing curves, durations, and reduced-motion rules for state changes.
+- [Radius and Padding](product/foundations/radius-and-padding.md): How corner radius and padding pair, from fields to modals.
+- [Typography](product/foundations/typography.md): Type sets for titles, body text, values, and code.
+
+### Products
+
+- [Tempo Console](product/products/tempo-console.md): Tempo Console is the web app for Tempo API projects, keys, usage, and billing.
+- [Tempo Performance](product/products/tempo-performance.md): Tempo Performance is the public benchmark dashboard for the Tempo network.
+- [Tempo Wallet](product/products/tempo-wallet.md): Tempo Wallet is the first-party wallet for balances, transfers, and deposits.
+
+### Patterns
+
+- [Blockchain Values](product/patterns/blockchain-values.md): Formats addresses, hashes, amounts, and timestamps so people can verify them.
+- [Dashboards](product/patterns/dashboards.md): Summarizes system metrics, such as throughput, in tiles, filters, and charts.
+- [Destructive Actions](product/patterns/destructive-actions.md): Match the safeguard on a destructive action to its impact and its reversibility.
+- [Empty States](product/patterns/empty-states.md): Explain why a region has nothing to show, and offer the next step that fills it.
+- [Errors and Validation](product/patterns/errors-and-validation.md): Check values at the right moment, and state how to fix each problem.
+- [Feedback and Status](product/patterns/feedback-and-status.md): Name each system state once, and choose Toast, Alert, or Banner by urgency.
+- [Forms](product/patterns/forms.md): Order fields, labels, and actions so a person completes a form in one pass.
+- [Loading](product/patterns/loading.md): Show that content or an action is on its way, with an indicator to fit the wait.
+- [Navigation](product/patterns/navigation.md): Move between product areas, page views, and nested pages in one shared frame.
+- [Payments](product/patterns/payments.md): Build send, receive, and deposit flows, from the amount to the receipt.
+- [Responsive Layout](product/patterns/responsive-layout.md): Adapt layouts from a 320px phone to a wide desktop with shared breakpoints.
+- [Tables and Lists](product/patterns/tables-and-lists.md): Present records, such as payments and API keys, to scan, compare, and act on.
+
+### Components
+
+- [Overview](product/components.md): Components for building Tempo products, grouped by the job each one does.
+- [Accordion](product/components/accordion.md): Stacks collapsible sections that each reveal a labelled panel.
+- [AddressCard](product/components/address-card.md): Shows a wallet address to receive funds, with its QR code and networks.
+- [AgentLogo](product/components/agent-logo.md): Shows the logo of an AI agent that works with a wallet.
+- [AlertDialog](product/components/alert-dialog.md): Asks you to confirm a critical action before it happens.
+- [Alert](product/components/alert.md): Shows an inline message tied to nearby content.
+- [AmountInput](product/components/amount-input.md): Accepts a decimal amount, such as a payment or transfer value.
+- [Amount](product/components/amount.md): Formats a number as money or a token amount.
+- [AppShell](product/components/app-shell.md): Places a sticky sidebar beside the main content column.
+- [AssetChip](product/components/asset-chip.md): Labels a supported asset or network in a small chip, which can also pick one.
+- [Autocomplete](product/components/autocomplete.md): A text input that suggests values while people type.
+- [Avatar](product/components/avatar.md): Represents a person, contact, or wallet with an image, initials, or an icon.
+- [Badge](product/components/badge.md): Labels a status or category in a compact chip.
+- [BadgedLogo](product/components/badged-logo.md): Marks a token or an app with a small badge on the corner of its logo.
+- [Banner](product/components/banner.md): Shows a full-width message about the system or page.
+- [BarChart](product/components/bar-chart.md): Shows values over time as stacked bars, such as the daily spend of each agent.
+- [Breadcrumbs](product/components/breadcrumbs.md): Shows where the current page sits in the site hierarchy.
+- [ButtonGroup](product/components/button-group.md): Lays out the actions at the foot of a dialog or focused flow.
+- [Button](product/components/button.md): Triggers an action, such as submitting a form or sending a payment.
+- [Calendar](product/components/calendar.md): A month grid for picking one date or a date range.
+- [Callout](product/components/callout.md): Sets a short passage of body text apart in a subtle box.
+- [CheckboxGroup](product/components/checkbox-group.md): Shares one value array across a group of checkboxes.
+- [Checkbox](product/components/checkbox.md): Turns a single independent option on or off.
+- [ChoiceGroup](product/components/choice-group.md): A segmented control for a few mutually exclusive options.
+- [Choicebox](product/components/choicebox.md): A selectable tile with an optional icon, title, and description.
+- [Code](product/components/code.md): Sets a command, identifier, or value apart inside a sentence.
+- [Combobox](product/components/combobox.md): A text input that filters a list of fixed options while people type.
+- [Container](product/components/container.md): Centers content at a maximum width.
+- [CopyButton](product/components/copy-button.md): Copies a value to the clipboard and confirms the copy.
+- [DatePicker](product/components/date-picker.md): Shows the selected date and opens a calendar in a popup.
+- [Dialog](product/components/dialog.md): Opens a modal popup over the page.
+- [Drawer](product/components/drawer.md): Slides a modal panel in from an edge of the viewport.
+- [Empty](product/components/empty.md): Fills a region that has nothing to show yet.
+- [Field](product/components/field.md): Links a label, description, and error message to a control.
+- [Fieldset](product/components/fieldset.md): Groups related fields under a shared legend.
+- [Frame](product/components/frame.md): Lays out a header, body, and footer in a column.
+- [Gauge](product/components/gauge.md): Shows a measurement within a range as a ring.
+- [GetStartedVisual](product/components/get-started-visual.md): Illustrates one step of a get started flow at the top of its card.
+- [Grid](product/components/grid.md): Lays out children on a responsive grid.
+- [HeroVisual](product/components/hero-visual.md): Shows animated streaks and a title beside the steps of a setup flow.
+- [Hex](product/components/hex.md): Shows a hex string, such as an address, truncated to fit.
+- [IconTile](product/components/icon-tile.md): Anchors a centered modal with one icon in a rounded square.
+- [Identicon](product/components/identicon.md): Shows a unique gradient avatar derived from an address.
+- [Inline](product/components/inline.md): Lays out children in a horizontal row.
+- [Inset](product/components/inset.md): Pads content with spacing tokens.
+- [Kbd](product/components/kbd.md): Shows a keyboard key or shortcut.
+- [ListGroup](product/components/list-group.md): Stacks rows for details, pickers, checklists, and settings.
+- [LoadingDots](product/components/loading-dots.md): Shows three pulsing dots for inline loading.
+- [Menu](product/components/menu.md): Opens a list of actions from a button.
+- [NativeSelect](product/components/native-select.md): A native select styled as a field, which opens the browser's own picker.
+- [NetworkLogo](product/components/network-logo.md): Shows the logo of the network a token lives on.
+- [NumberField](product/components/number-field.md): A numeric input with increment and decrement buttons.
+- [OtpField](product/components/otp-field.md): Accepts a one-time passcode, one character per slot.
+- [Pagination](product/components/pagination.md): Moves between pages of a long list.
+- [Popover](product/components/popover.md): Opens a non-modal popup anchored to a trigger.
+- [Progress](product/components/progress.md): Shows how far a task has advanced.
+- [Qr](product/components/qr.md): Renders a value as a QR code.
+- [RadioGroup](product/components/radio-group.md): Lets you pick a single option from a short list.
+- [SecretValue](product/components/secret-value.md): Masks a secret and adds reveal and copy buttons.
+- [Select](product/components/select.md): Opens a list of options for choosing one value.
+- [Separator](product/components/separator.md): Draws a rule between groups of content.
+- [SidebarMenu](product/components/sidebar-menu.md): Vertical navigation for sidebars and drawers.
+- [Skeleton](product/components/skeleton.md): Holds the place of content while it loads.
+- [Slider](product/components/slider.md): Picks a single value or a range by dragging.
+- [Snippet](product/components/snippet.md): Shows a command or value with a copy button.
+- [Spinner](product/components/spinner.md): Shows that something is loading.
+- [SplitBar](product/components/split-bar.md): Splits one total between two parts, with a legend under the bar.
+- [SplitButton](product/components/split-button.md): Pairs a primary action with a menu of alternatives.
+- [Stack](product/components/stack.md): Lays out children in a vertical column.
+- [StatusChip](product/components/status-chip.md): Names the status of a payment, an authorization, or a network.
+- [StatusIndicator](product/components/status-indicator.md): Names the status of a system or a service with a dot and a label.
+- [StatusRow](product/components/status-row.md): Follows the status of one payment or task while it runs.
+- [Stepper](product/components/stepper.md): Shows progress through a fixed sequence of steps.
+- [SuccessHero](product/components/success-hero.md): Confirms that a setup flow finished, on a dark card of animated streaks.
+- [Surface](product/components/surface.md): A card container for grouping related content.
+- [Switch](product/components/switch.md): Toggles a setting that applies immediately.
+- [Table](product/components/table.md): Displays tabular data in rows and columns.
+- [Tabs](product/components/tabs.md): Switches between related views.
+- [TempoLogo](product/components/tempo-logo.md): Shows the Tempo brand logo.
+- [TextInput](product/components/text-input.md): A text field with optional prefix, suffix, and clear button.
+- [Textarea](product/components/textarea.md): A multi-line text field.
+- [Toast](product/components/toast.md): Shows a brief notification that dismisses itself.
+- [TokenLogo](product/components/token-logo.md): Shows a token logo by contract address or symbol.
+- [Token](product/components/token.md): Shows which token an amount is in, and opens a picker to change it.
+- [Tooltip](product/components/tooltip.md): Shows a short label for a control on hover or focus.
+- [VerificationCode](product/components/verification-code.md): Shows a code that a person compares with the one another app shows.
+- [Visual](product/components/visual.md): Illustrates the top of an onboarding or feature modal.
+
+## Marketing
+
+### Introduction
+
+- [Getting Started](marketing/introduction/getting-started.md): Install the Marketing system and style your first section.

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

@@ -0,0 +1,241 @@
+# Getting Started
+
+Install the Marketing system and style your first section.
+
+## Overview
+
+Marketing pages present Tempo to the public. They explain what Tempo is, who it is for, and why it matters, and lead the reader to a next step. `@tempoxyz/ds/marketing` ships the variables and authoring helpers for these pages.
+
+* **Home Page (tempo.xyz):** Introduces Tempo and routes each reader onward.
+* **Campaigns (Landing pages):** Carry one message to one audience at a time.
+* **Launches (Announcements):** Present a new feature, partner, or upgrade.
+* **Events (Event pages):** Show the agenda, the speakers, and registration.
+
+## Agent Prompt
+
+Paste this prompt into your coding agent:
+
+Read ds.tehq.dev/marketing/introduction/getting-started and help me build a Tempo marketing page
+with Tempo Design System.
+
+## Setup
+
+### Install the Library
+
+Install `@tempoxyz/ds` and its Zyzz peer. Marketing ships from the same package.
+
+```sh
+npm install @tempoxyz/ds zyzz
+```
+
+### Choose Framework
+
+Choose a compilation target and a variable mode:
+
+* **TDS Variables (Quick):** Uses the Marketing variables as they ship.
+* **Custom Variables (Advanced):** Extends the Marketing variables with site 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 Marketing variables, the Inter, Pilat, and JetBrains Mono fonts, and keyframes once, and each module 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)
+
+### Style a Section
+
+Import `style` from `@tempoxyz/ds/marketing`, and style your markup with Marketing tokens.
+
+```tsx title="Hero.tsx"
+import { style } from '@tempoxyz/ds/marketing'
+
+export function Hero() {
+  return (
+    <section {...styles.hero()}>
+      <h1 {...styles.title()}>Payments at internet speed</h1>
+      <p {...styles.lead()}>Move money anywhere in under a second.</p>
+    </section>
+  )
+}
+
+namespace styles {
+  export const hero = style({
+    backgroundColor: 'background.primary',
+    paddingBlock: '64',
+    paddingInline: '24',
+  })
+
+  export const lead = style({ color: 'content.secondary', typography: 'body.b1' })
+
+  export const title = style({ color: 'content.primary', typography: 'display.d1' })
+}
+```
+
+Tokens such as `content.primary`, `'64'`, and `display.d1` type-check against the Marketing variables. Light and dark values follow the inherited `color-scheme`.
+
+#### Custom Variables (Advanced)
+
+### Define Config
+
+Extend the Marketing variables with site tokens, and export the bound helpers.
+
+```ts title="zyzz.config.ts"
+import { variables } from '@tempoxyz/ds/marketing'
+import { Config, Vars } from 'zyzz'
+
+export const { style, vars } = Config.create({
+  id: 'site',
+  vars: Vars.extend(variables, { spacing: { section: '7.5rem' } }, { id: 'site/vars' }),
+})
+```
+
+Place `zyzz.config.ts` at the root of the site source, such as `src/zyzz.config.ts`. The Vite plugin scans its directory for global styles.
+
+### Style a Section
+
+Apply `vars()` to the site root. Style your markup with the bound `style` helper, which accepts Marketing and site tokens.
+
+```tsx title="Hero.tsx"
+import { style, vars } from './zyzz.config.js'
+
+export function Site() {
+  return (
+    <main {...vars()}>
+      <Hero />
+    </main>
+  )
+}
+
+function Hero() {
+  return (
+    <section {...styles.hero()}>
+      <h1 {...styles.title()}>Payments at internet speed</h1>
+    </section>
+  )
+}
+
+namespace styles {
+  export const hero = style({ paddingBlock: 'section', paddingInline: '24' })
+
+  export const title = style({ color: 'content.primary', typography: 'display.d1' })
+}
+```
+
+### 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)
+
+### Style a Section
+
+Import `style` from `@tempoxyz/ds/marketing`, and style your markup with Marketing tokens.
+
+```tsx title="Hero.tsx"
+import { style } from '@tempoxyz/ds/marketing'
+
+export function Hero() {
+  return (
+    <section {...styles.hero()}>
+      <h1 {...styles.title()}>Payments at internet speed</h1>
+      <p {...styles.lead()}>Move money anywhere in under a second.</p>
+    </section>
+  )
+}
+
+namespace styles {
+  export const hero = style({
+    backgroundColor: 'background.primary',
+    paddingBlock: '64',
+    paddingInline: '24',
+  })
+
+  export const lead = style({ color: 'content.secondary', typography: 'body.b1' })
+
+  export const title = style({ color: 'content.primary', typography: 'display.d1' })
+}
+```
+
+Tokens such as `content.primary`, `'64'`, and `display.d1` type-check against the Marketing variables. Light and dark values follow the inherited `color-scheme`.
+
+#### Custom Variables (Advanced)
+
+### Define Config
+
+Extend the Marketing variables with site tokens, and export the bound helpers.
+
+```ts title="zyzz.config.ts"
+import { variables } from '@tempoxyz/ds/marketing'
+import { Config, Vars } from 'zyzz'
+
+export const { style, vars } = Config.create({
+  id: 'site',
+  vars: Vars.extend(variables, { spacing: { section: '7.5rem' } }, { id: 'site/vars' }),
+})
+```
+
+### Style a Section
+
+Apply `vars()` to the site root. Style your markup with the bound `style` helper, which accepts Marketing and site tokens.
+
+```tsx title="Hero.tsx"
+import { style, vars } from './zyzz.config.js'
+
+export function Site() {
+  return (
+    <main {...vars()}>
+      <Hero />
+    </main>
+  )
+}
+
+function Hero() {
+  return (
+    <section {...styles.hero()}>
+      <h1 {...styles.title()}>Payments at internet speed</h1>
+    </section>
+  )
+}
+
+namespace styles {
+  export const hero = style({ paddingBlock: 'section', paddingInline: '24' })
+
+  export const title = style({ color: 'content.primary', typography: 'display.d1' })
+}
+```
+
+> [!NOTE]
+> The Marketing variables change as the Marketing designs define their own values. Marketing ships no components yet.