@tempoxyz/ds 0.3.10 → 0.3.13

package/dist/docs/product/foundations/radius-and-padding.md

@@ -0,0 +1,86 @@
+# Radius and Padding
+
+How corner radius and padding pair, from fields to modals.
+
+## Overview
+
+Corners in Tempo are squircles that ease into each edge. Each kind of element has its own radius, from fields and buttons up to modals, and the radius stays the same at every size of that element.
+
+Padding keeps content clear of the curve. Boxes and modals pad by their own radius, and corners step down the scale as layers nest.
+
+## Scale
+
+* **Fields, Buttons, and Alerts (xs):** A 12px corner at every size, padded by at least 16px.
+* **Boxes and Tiles (sm):** A 16px corner, padded by 16px, as in a list group.
+* **Small Modals (md):** A 24px corner, padded by 24px, for one decision.
+* **Medium and Large Modals (lg):** A 32px corner, padded by 32px, for longer tasks.
+* **Pills (full):** Icon buttons, avatars, and token chips.
+
+**Do:** Pad a corner by at least its radius, so content sits clear of the curve.
+
+```tsx
+<RadiusDemo kind="padded" />
+```
+
+**Don't:** Pad a container by less than its radius.
+
+```tsx
+<RadiusDemo kind="cramped" />
+```
+
+## Squircles
+
+Every corner is a squircle where the browser supports it, and a round corner of the same radius everywhere else.
+
+* **Squircle (corner-shape):** Supporting browsers draw each radius token as a squircle.
+* **Fallback (border-radius):** Other browsers draw the same token as a round corner.
+* **Circles and Pills (full):** Full radius stays round, so circles keep their shape.
+
+To keep your own circle or pill round, set the round corner shape beside the full radius.
+
+```tsx
+import { style } from '@tempoxyz/ds'
+
+namespace styles {
+  export const badge = style({ borderRadius: 'full', cornerShape: 'round' })
+}
+```
+
+## Nested Corners
+
+A layer inside another takes a smaller radius: a modal at 32px holds boxes at 16px, which hold fields at 12px.
+
+**Do:** Step the radius down at each layer, from modal to box to field.
+
+```tsx
+<RadiusDemo kind="nested" />
+```
+
+**Don't:** Repeat the outer radius on the layers inside it.
+
+```tsx
+<RadiusDemo kind="repeated" />
+```
+
+## Corner Controls
+
+* **Close and Back Buttons (First line):** Align with the title beside them, not with the corner.
+
+## Bleed
+
+* **Edge-Aligned Controls (Up to the padding):** Lines a text button's label up with the content edge.
+* **Full-Bleed Content (Exactly the padding):** Lets rows and tables reach both edges of the box.
+
+## Related
+
+[Layout](layout.md)
+
+Covers the radius, spacing, and shadow scales.
+
+[Surface](../components/surface.md)
+
+Use for padded boxes and cards.
+
+[Dialog](../components/dialog.md)
+
+Use for modals.

package/dist/docs/product/foundations/typography.md

@@ -0,0 +1,266 @@
+# Typography
+
+Type sets for titles, body text, values, and code.
+
+## Overview
+
+Type in Tempo is quiet and direct. Inter carries the interface, Pilat gives titles and large numbers their character, and JetBrains Mono keeps addresses and code legible.
+
+Each set bundles a family, size, weight, line height, and tracking into one token, so you choose a role instead of tuning properties. A set keeps one size at every screen width.
+
+```tsx
+import { style } from '@tempoxyz/ds'
+
+namespace styles {
+  export const title = style({ typography: 'heading.h2' })
+
+  export const body = style({ color: 'content.secondary', typography: 'body.b2' })
+}
+```
+
+## Typefaces
+
+Three bundled families cover every set.
+
+* **Inter (100 to 900):** Body text, labels, buttons, and table cells.
+* **Pilat (100 to 900):** Titles, display text, and large values.
+* **JetBrains Mono (400 to 700):** Addresses, hashes, keys, and code.
+
+## Type Sets
+
+Six sets cover the interface, from hero titles down to small labels.
+
+### Display
+
+Hero titles and large amounts, in light and regular weights that let size carry the emphasis. [Amount](../components/amount.md) uses display type at its largest size.
+
+* `display.d1`: 44px, weight 300, line height 41.8px
+* `display.d2`: 36px, weight 400, line height 34.2px
+
+### Value
+
+Large readings, such as balances and dashboard numbers, with tight tracking so the digits read as one figure.
+
+* `value.v1`: 80px, weight 400, line height normal
+* `value.v2`: 52px, weight 400, line height normal
+* `value.v3`: 40px, weight 400, line height normal
+
+### Heading
+
+Page, dialog, section, and card titles, in a medium weight. Tracking tightens as the size grows, so large titles stay compact.
+
+* `heading.h1`: 32px, weight 500, line height 36.8px
+* `heading.h2`: 24px, weight 500, line height 27.6px
+* `heading.h3`: 20px, weight 500, line height 23px
+* `heading.h4`: 18px, weight 500, line height 20.7px
+
+### Body
+
+Paragraphs, descriptions, labels, buttons, and table cells, in a regular and a strong weight at each size.
+
+* `body.b1`: 16px, weight 400, line height 22px
+* `body.b1Strong`: 16px, weight 500, line height 22px
+* `body.b2`: 14px, weight 400, line height 20px
+* `body.b2Strong`: 14px, weight 500, line height 20px
+* `body.b3`: 12px, weight 400, line height 16px
+* `body.b3Strong`: 12px, weight 500, line height 16px
+
+* **Weight (400 and 500):** Strong sets add emphasis without a larger size.
+* **Default (body.b1):** The page default, a size down on dense screens.
+* **Inputs (body.b1):** Large fields keep 16px, so iOS Safari won't zoom.
+* **Buttons (body.b2Strong):** Buttons set their own labels, one size per button.
+
+### Mono
+
+Addresses, hashes, keys, and code, in one size.
+
+* **Addresses and Hashes (mono.m1):** Hex values and monospace table cells.
+* **Commands and Keys (mono.m1):** Snippets and secret values.
+
+### Utility
+
+Short metadata labels in the mono family, with wide tracking. The design sets them in uppercase, which a component applies itself, since the sets keep the text's case.
+
+* `utility.m1`: 12px, weight 400, line height 16px
+* `utility.m2`: 10px, weight 400, line height 12px
+
+* **Label (utility.m1):** Metadata labels above or beside a value.
+* **Small Label (utility.m2):** The smaller size, for labels in tight spaces.
+
+## Guidelines
+
+### Build Hierarchy With Few Sizes
+
+Build hierarchy with size and weight, not color. Most screens need a page title, section titles, and body text.
+
+* **Page Title (heading.h2):** One per page, including app shell and dialog titles.
+* **Section and Card Title (heading.h3):** Section, surface, and popover titles.
+* **Small Title (body.b1Strong):** Compact titles, such as empty states and legends.
+* **Body and Secondary Text (body.b1):** Reading text, in the primary or secondary color.
+
+Keep headings in order. Choose the element by its place in the outline and the set by its look.
+
+**Do:** Let the component set the label and description sizes.
+
+```tsx
+<Field.Root>
+  <Field.Label>Amount</Field.Label>
+  <TextInput.Group>
+    <TextInput.Control defaultValue="25.00" />
+  </TextInput.Group>
+  <Field.Description>Available balance: 120.00 USDC.</Field.Description>
+</Field.Root>
+```
+
+**Don't:** Use all caps or bold every line to create hierarchy. Write in [sentence case](content/writing-style.md#capitalization).
+
+```tsx
+<p>
+  <strong>AMOUNT</strong>
+</p>
+<p>
+  <strong>Available balance: 120.00 USDC.</strong>
+</p>
+```
+
+### Match Sets to Their Role
+
+* **Wrapping Text (body):** Anything that can wrap.
+* **Labels (body.b2Strong):** Field labels and short lines beside controls.
+* **Titles (heading):** Page, dialog, section, and card titles.
+* **Hero Numbers (display and value):** Balances and dashboard readings.
+
+### Use Tabular Figures for Numbers
+
+Tabular figures align digits in columns and keep live values from shifting. [Amount](../components/amount.md), [NumberField](../components/number-field.md), [Slider](../components/slider.md), and numeric table cells already set them.
+
+**Do:** Align amounts with tabular figures, such as `Amount` with `align="right"`.
+
+```tsx
+/**
+ * Do example for "Use Tabular Figures for Numbers" on the Typography page.
+ * Align amounts with tabular figures, such as `Amount` with `align="right"`.
+ * @module
+ */
+import { Amount, style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.column()}>
+      <Amount align="right" symbol="PathUSD" value="1111.11" />
+      <Amount align="right" symbol="PathUSD" value="8808.80" />
+      <Amount align="right" symbol="PathUSD" value="4170.25" />
+    </div>
+  )
+}
+
+namespace styles {
+  export const column = style({ display: 'grid', gap: '8', width: '12rem !custom' })
+}
+```
+
+**Don't:** Stack amounts in proportional figures, where digits drift out of line.
+
+```tsx
+/**
+ * Don't example for "Use Tabular Figures for Numbers" on the Typography page.
+ * Don't stack amounts in proportional figures, where digits drift out of line.
+ * @module
+ */
+import { style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.column()}>
+      <span {...styles.amount()}>1,111.11 PathUSD</span>
+      <span {...styles.amount()}>8,808.80 PathUSD</span>
+      <span {...styles.amount()}>4,170.25 PathUSD</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const amount = style({
+    color: 'content.primary',
+    fontVariantNumeric: 'proportional-nums !custom',
+    textAlign: 'right',
+    typography: 'body.b2Strong',
+  })
+
+  export const column = style({ display: 'grid', gap: '8', width: '12rem !custom' })
+}
+```
+
+If you render a number yourself, such as a metric tile, set tabular figures in its style.
+
+```tsx
+style({ fontVariantNumeric: 'tabular-nums !custom' })
+```
+
+### Use Monospace for Hashes and Code
+
+Set addresses, hashes, keys, and code in monospace, so similar characters stay distinct and equal-length values align. [Hex](../components/hex.md), [Snippet](../components/snippet.md), and [SecretValue](../components/secret-value.md) apply it. Labels and prose stay out of it.
+
+**Do:** Set hashes in `mono.m1`, so they align and `I`, `l`, `0`, and `O` stay distinct.
+
+```tsx
+/**
+ * Do example for "Use Monospace for Hashes and Code" on the Typography page.
+ * Set hashes in a `.mono` set, so they align and `I`, `l`, `0`, and `O` stay distinct.
+ * @module
+ */
+import { style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.column()}>
+      <span {...styles.value()}>0x1f0a9c3e7b11d4e0</span>
+      <span {...styles.value()}>0x8d1Il0O4e2b7a96c</span>
+      <span {...styles.value()}>0x7777a1b2c3d4e5f6</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const column = style({ display: 'grid', gap: '8' })
+
+  export const value = style({ color: 'content.primary', typography: 'mono.m1' })
+}
+```
+
+**Don't:** Set hashes in a proportional set, where equal-length values drift apart.
+
+```tsx
+/**
+ * Don't example for "Use Monospace for Hashes and Code" on the Typography page.
+ * Don't set hashes in a proportional set, where equal-length values drift apart.
+ * @module
+ */
+import { style } from '@tempoxyz/ds'
+
+/** Renders the static preview, which the guideline card shows inert. */
+export function Demo() {
+  return (
+    <div {...styles.column()}>
+      <span {...styles.value()}>0x1f0a9c3e7b11d4e0</span>
+      <span {...styles.value()}>0x8d1Il0O4e2b7a96c</span>
+      <span {...styles.value()}>0x7777a1b2c3d4e5f6</span>
+    </div>
+  )
+}
+
+namespace styles {
+  export const column = style({ display: 'grid', gap: '8' })
+
+  export const value = style({ color: 'content.primary', typography: 'body.b3' })
+}
+```
+
+### Keep Lines Readable
+
+* **Line Length (45 to 75 characters):** Cap paragraphs with `maxWidth: '65ch !custom'`. Dialogs already cap their width.
+* **Alignment:** Left-align text. Center only short text, such as an empty state title.
+* **Minimum Size (12px):** Don't set interface text smaller. The smallest body set, `body.b3`, stops here.

package/dist/docs/product/introduction/faq.md

@@ -0,0 +1,133 @@
+# FAQ
+
+Common questions about building with, and contributing to, Tempo Design System.
+
+## Getting Started
+
+### Which Surface Should I Use?
+
+Choose the surface by the platform you ship to. The surfaces share a design language but not code, so don't import one from the other.
+
+| I am building...          | Surface   | Import                   |
+| ------------------------- | --------- | ------------------------ |
+| A web application         | Web       | `@tempoxyz/ds`           |
+| A React Native mobile app | Mobile    | `@tempoxyz/ds/mobile`    |
+| A marketing website       | Marketing | `@tempoxyz/ds/marketing` |
+
+Web components render DOM elements and compile with a Zyzz bundler plugin. Mobile components render React Native views and compile with Metro. [Getting Started](getting-started.md) shows each setup.
+
+### Do I Need to Import a Stylesheet?
+
+No. The library publishes no stylesheet.
+
+* **Vite:** The [Vite plugin](getting-started.md#setup) emits the variables, the Inter, Pilat, and JetBrains Mono fonts, and keyframes once. Each component emits its own rules, so a build carries only the styles it uses.
+* **Rollup, Webpack, and esbuild:** The adapters emit a generated `/zyzz.css` that you load once.
+* **Mobile:** Metro compiles library and app styles during the bundle.
+
+The Zyzz plugin is the only supported web setup.
+
+### How Do I Style My Own Markup?
+
+Use `style` and `variants` from `@tempoxyz/ds` with TDS tokens, such as `content.primary`, `background.elevated`, `'24'`, and `body.b2`. Group the definitions in a `namespace styles` block.
+
+If your app needs its own tokens, extend `variables` in your own Zyzz config, as the Custom Variables setup in [Getting Started](getting-started.md#setup) shows.
+
+## Components
+
+### Can I Change How a Component Looks?
+
+Use the component's props first, such as `variant` and `size`.
+
+* **Web:** Components accept `className` and `style`, and keep your classes beside their own.
+* **Mobile:** Components accept React Native `style`. Import variables from `@tempoxyz/ds/mobile`.
+
+If you need a token the library does not have, extend `variables` as [How Do I Style My Own Markup?](#how-do-i-style-my-own-markup) shows.
+
+### What If the Library Doesn't Have the Component I Need?
+
+Build it in your app from library components and `style`, with TDS tokens. Keep that code in your app. If other products need it too, propose it for the library.
+
+### How Do I Request a Component, Variant, or Token?
+
+Open an issue in the Design System project in Linear. Include:
+
+* The use case.
+* The proposed contract, such as props, variants, or token names.
+* Links to the relevant Figma designs.
+* Consumer code or a pull request that shows the need.
+
+If an issue already covers the proposal, reuse it. A proposal joins `@tempoxyz/ds` after designer approval and an approved Figma definition.
+
+### Why Isn't a Figma Component in the Library?
+
+The library includes only components with a verified production family in Figma. Archived and experimental Figma components stay out until a production version exists.
+
+The [Components](../components.md) overview lists what ships today. Sidebar pages marked 🚧 are not written yet.
+
+### Which Components Exist on Mobile?
+
+`@tempoxyz/ds/mobile` has a smaller set, and some names differ from web.
+
+| Mobile       | Web counterpart                                                                   |
+| ------------ | --------------------------------------------------------------------------------- |
+| `Avatar`     | [Avatar](../components/avatar.md)                                                 |
+| `Badge`      | [Badge](../components/badge.md)                                                   |
+| `Button`     | [Button](../components/button.md)                                                 |
+| `CodeInput`  | [OtpField](../components/otp-field.md)                                            |
+| `IconButton` | [Button](../components/button.md) with `shape="icon"`                             |
+| `Skeleton`   | [Skeleton](../components/skeleton.md)                                             |
+| `Spinner`    | [Spinner](../components/spinner.md)                                               |
+| `TextButton` | [Button](../components/button.md) with `variant="tertiary"`                       |
+| `TextInput`  | [TextInput](../components/text-input.md) inside a [Field](../components/field.md) |
+| `Toast`      | [Toast](../components/toast.md)                                                   |
+| `Toggle`     | [Switch](../components/switch.md)                                                 |
+
+### Do Web Components Work in Mobile Browsers?
+
+Yes. [Responsive Layout](../patterns/responsive-layout.md) shows how to adapt a layout from a phone to a desktop.
+
+## Design
+
+### How Do Light and Dark Schemes Work?
+
+Every color has a light and a dark value, so you write each color once.
+
+* **Web:** Values follow the inherited CSS `color-scheme`. Set `color-scheme: light dark` on the root to follow the system, or apply `vars({ colorScheme: 'dark' })` to fix one region.
+* **Mobile:** `Provider colorScheme="system"` follows the device setting. To override it, pass `light` or `dark`. To render a subtree with inverse variables, pass `vars="inverse"`.
+
+The library does not store a scheme preference. If your app offers a theme setting, persist the choice yourself.
+
+### Which Is Right When Figma and Code Disagree?
+
+Figma is the design reference. Variables, icons, and components are maintained by hand, so the two can drift.
+
+If a component does not match its production Figma design, use Report issue on its page and include the Figma link. If you need the change before the library has it, keep the implementation in your app.
+
+### Where Are the Figma Files?
+
+The Figma files define every variable, icon, and component:
+
+* [TPDS 1.0 Platform](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs/TPDS-1.0-Platform) for Web variables and components
+* [TDS Platform](https://www.figma.com/design/pcO4NIuw8wx9U2nGJOcjzE) for Web icons
+* [TDS App](https://www.figma.com/design/8iu5856rBEI3pnZ6YaIBgw) for Mobile, whose families the mobile components implement
+
+## Docs
+
+### How Do I Report a Docs Issue?
+
+On wide screens, On this page includes two actions:
+
+* **Report issue:** Opens a GitHub issue titled with the page name and its path.
+* **Edit page:** Opens the MDX source of the page on GitHub.
+
+On narrower screens, use the GitHub link at the bottom of the sidebar.
+
+### How Should Coding Agents Use These Docs?
+
+Every page has a Markdown twin, `/llms.txt` indexes them all, and the library documents each export in its source. [Agents](../foundations/agents.md) lists the files and the rules an agent follows when it generates Tempo UI.
+
+## License
+
+### How Is the Library Licensed?
+
+The library is open source under the [MIT license](https://github.com/tempoxyz/ds/blob/main/LICENSE-MIT).